Projects and shared knowledge

A project is the shared scope for your resources, tables, documents, and apps. A local workspace attaches a directory to that server-side project and records where its source lives.

Create or attach a workspaceCopy Anchor Link

vortexify init --name operations --description 'Operations project'

Without --project-id, init creates a project; its name defaults to the current directory's name. To attach an existing project instead:

vortexify init --project-id PROJECT_ID

Init writes vortexify.project.yaml, initializes shared document collections, and adds coding-agent guidance. It refuses an existing configuration and nested projects. Attaching identity is separate from retrieving all resource source.

To initialize a directory and download registered resource source in one workflow:

vortexify pull --project-id PROJECT_ID

Once attached, use ordinary vortexify pull. An explicit project ID must match the workspace configuration; use another directory for a different project.

Workspace source pathsCopy Anchor Link

vortexify.project.yaml contains the project ID and resource path mapping. Resource commands use those configured paths, so an API does not have to live in the default apis/ directory. Sync source belongs under its connector's nested syncs/ directory in the default layout.

Creating a local folder is not the same as registering a resource. Use create and commit to give source a project identity and saved version.

Project context and business knowledgeCopy Anchor Link

These collections give people and coding agents a persistent understanding they can use to plan, design, build and improve the project.

Context records what you are building, why, how it should work and how you plan to implement it. Knowledge Base records your evolving understanding of the business, its concepts and entities.

Structure and useful artifactsCopy Anchor Link

.vortexify/
  context/
    index.md
    requirements/
    applications/
    architecture/
  knowledge-base/
    index.md
    concepts/
    entities/

Both root index.md files and the five category folders are required. Empty folders are valid. Documents and nested subfolders are flexible; there are no mandatory filenames, templates, sections or documents per resource. Organize proportionally to the project: entities/manufacturing/production-order.md may help a large project, while a small project's entity files can sit directly under entities/.

Use .md for documents and .html for application designs. HTML designs are visual artifacts agents can create and use during planning and implementation, not merely written descriptions. Keep them under context/applications/, alongside the app specification or in nested folders. Prefer names such as inventory-planner-overview.html; multiple designs per app are supported. These examples guide organization rather than prescribe a layout.

Maintain Context as development progressesCopy Anchor Link

Capture requirements when users explain what they want. As applications are planned, create or update useful specifications, workflows and HTML designs. As technical resources are designed and implemented, maintain the relevant pipeline plans and decisions. Revise existing artifacts when requirements or approaches change, rather than accumulating contradictory plans or deferring documentation until the end.

Business concepts belong in Knowledge Base; requested app functionality belongs in application specifications; implementation approaches belong in architecture. Link shared definitions instead of repeating them. Plans may describe future work; committed code and registered resources remain authoritative for actual behavior.

Maintain Knowledge Base as business understanding growsCopy Anchor Link

Preserve useful business explanations from conversations and answers to business questions, even when the user did not explicitly ask for documentation. For example, when the user explains how reserved inventory affects availability, update the relevant concept so future agents can reuse that knowledge.

Data exploration and primary-key/relationship discoveries can help explain business entities and their connections. Synthesize that understanding rather than copying schemas, table catalogs or graph reports. Inspect technical information directly through the CLI and knowledge graph; include relevant data references only when they help explain the business meaning.

Distinguish confirmed facts from unresolved interpretations. If orders connect to material rolls but it is unclear whether the connection represents planned usage or actual consumption, preserve the question and clarify it when relevant. Update the existing explanation once answered. Discovery refreshes should preserve useful business knowledge already supplied by users.

Knowledge Base is not a transcript or activity log. Implementing an API or changing a component alone does not warrant an entry unless it changes business understanding.

Navigation, references and cleanupCopy Anchor Link

Read the root indexes first. Keep each concise, with an overview and links to useful documents; additional indexes in subfolders are optional. Prefer updating existing documents, split distinct topics when useful, merge overlap and remove obsolete plans and superseded designs. Maintain the smallest useful collection of accurate knowledge and development artifacts.

Use ordinary relative Markdown links to documents, HTML designs and source. For example, from context/applications/inventory-planner.md:

- [Inventory definition](../../knowledge-base/concepts/available-inventory.md)
- [Overview design](inventory-planner-overview.html)

Resolve links from the actual document location, including .vortexify/, and consult vortexify.project.yaml for configured source paths. Linking a source file does not establish a registered resource identity or automatically synchronize the target into a collection. Update links and indexes when files move or disappear.

Synchronize the collectionsCopy Anchor Link

vortexify context init
vortexify context status
vortexify context pull
vortexify context push
vortexify context read knowledge-base index.md
vortexify context versions context

init initializes and retrieves collections. status compares local and server state; pull retrieves changes; push saves changes through the collection version/hash contract. read COLLECTION PATH reads a server file and versions COLLECTION lists saved history. Full project pull, commit and status also include the collections; resource-filtered operations affect source only. Pull and reconcile concurrent changes before saving again. If local and server edits conflict, vortexify context pull --backup-local saves each conflicting local collection in .vortexify/backups/*.tar.gz before pulling the server version. Extract the backup into a separate directory, reconcile your edits into the pulled files, then run vortexify context push. Ordinary pull leaves conflicting local files unchanged. Knowledge-graph writes can update Business knowledge while you edit it.

Collections are versioned separately from resource source and are separate from files attached to connectors or runtime assistants. Attached blueprints are references, distinct from your authored project designs. In the platform, the knowledge panel presents these collections as Project context and Business knowledge, with a file tree and saved collection version.

Access and organization contextCopy Anchor Link

Project creation requires builder and organization-admin access. Existing project access comes from active project membership; organization membership alone does not grant it. Select authentication and organization context as described in configuration.