Projects

Use the projects block in swarmvault.config.json when one vault covers multiple codebases, initiatives, or workstreams.

Example

{
  "projects": {
    "site": {
      "roots": ["apps/site", "packages/docs"],
      "schemaPath": "schemas/site.schema.md"
    },
    "engine": {
      "roots": ["packages/engine"]
    }
  }
}

Fields

Resolution Rules

• SwarmVault normalizes roots and source paths before matching.
• The longest matching root wins.
• If two matches have the same length, the lexicographically smaller project id wins.
• Unmatched sources remain global.

What Becomes Project-Scoped

• Source pages and code module pages inherit the source project directly.
• Concept, entity, candidate, and output pages become project-scoped only when all contributing project-backed sources agree on the same project.
• Mixed-project aggregate pages stay global and keep project_ids: [].

Layered Schemas

The root schema always applies. If a page belongs to a project with schemaPath, SwarmVault appends the project schema after the root schema and treats the combined content as the effective schema for that page.

That affects:

• compile prompts
• query prompts when retrieved context includes project-scoped pages
• generated schema_hash values
• incremental invalidation in state/compile-state.json

Generated Artifacts

Project-aware vaults add:

• wiki/projects/index.md
• wiki/projects/<project-id>/index.md
• project_ids frontmatter on generated pages
• project/<project-id> tags on project-scoped pages
• project color groups in .obsidian/graph.json when you use swarmvault init --obsidian

Project indexes link to canonical pages. SwarmVault does not duplicate the underlying page trees under wiki/projects/.

Current Release Limits

• Each source resolves to at most one primary project.
• External package dependencies from code ingestion do not become project pages.
• Insight pages stay global and human-managed in this release.