# Projects and shared knowledge Source: /docs/reference/cli/projects.md 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 workspace [#create-or-attach-a-workspace] ```sh 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: ```sh 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: ```sh 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 paths [#workspace-source-paths] `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](/docs/reference/cli/resources) to give source a project identity and saved version. ## Project context and business knowledge [#project-context-and-business-knowledge] 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 artifacts [#structure-and-useful-artifacts] ```text .vortexify/ context/ index.md requirements/ applications/ architecture/ knowledge-base/ index.md concepts/ entities/ ``` | Folder | Useful files and their purpose | | --- | --- | | `context/requirements/` | Markdown project objectives, user needs, constraints, expected behavior and acceptance criteria. One `project-requirements.md` is often sufficient. | | `context/applications/` | Markdown specifications for app users, pages, navigation, workflows, functionality and visualizations; actual HTML designs for page layouts, components and interactions. | | `context/architecture/` | Markdown implementation plans for pipelines, calculations, APIs, responsibilities, data flows and technical decisions. A plan can describe several resources working together. | | `knowledge-base/concepts/` | Markdown business concepts: definitions, processes, calculations, policies and rules, such as available inventory or waste classification. | | `knowledge-base/entities/` | Markdown business entities, such as production orders, machines or doctors: what they represent and how they relate. An entity may span several datasets. | 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 progresses [#maintain-context-as-development-progresses] 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 grows [#maintain-knowledge-base-as-business-understanding-grows] 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 cleanup [#navigation-references-and-cleanup] 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`: ```markdown - [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 collections [#synchronize-the-collections] ```sh 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 context [#access-and-organization-context] 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](/docs/reference/cli/configuration).