swarmvault compile

Compile all ingested sources into the wiki, knowledge graph, and search index.

Usage

swarmvault compile [--approve] [--commit] [--max-tokens <n>]

Options

  • --approve — Stage a review bundle in state/approvals/ without applying active wiki changes
  • --commit — Stage wiki/ and state/ changes and commit them when the vault root is inside a git worktree
  • --max-tokens <n> — Trim lower-priority generated pages from final wiki/ output to keep the compiled vault inside a token budget

What It Does

  1. Loads all source manifests
  2. Analyzes the source extracts with the configured compileProvider
  3. Reads swarmvault.schema.md and uses it as vault-specific guidance
  4. Layers project schemas when a source resolves to a configured project root
  5. Extracts concepts, entities, claims, questions, and local code structure for ingested code sources
  6. Stages new concept and entity pages in wiki/candidates/ on first sighting
  7. Promotes recurring candidates into active concept or entity pages on a later matching compile
  8. Builds state/graph.json
  9. Generates Markdown wiki pages in wiki/, including wiki/code/ module pages and wiki/projects/ rollups
  10. Writes wiki/graph/share-card.md, wiki/graph/share-card.svg, and wiki/graph/share-kit/ for post-ready, visual, and HTML-preview sharing
  11. Rebuilds the SQLite full-text search index
  12. Records compile metadata in state/compile-state.json
  13. Writes a canonical session artifact to state/sessions/
  14. Optionally stages a second approval bundle from orchestration-driven compile post-pass proposals when orchestration.compilePostPass is enabled
  15. When --max-tokens is set, estimates page token cost and removes the lowest-priority generated pages that exceed the budget

Large compile runs process source analysis in bounded batches and use a sparse graph co-occurrence projection so dense note sets do not create unbounded pairwise graph work.

Output

Reports the number of sources compiled, pages generated, and pages changed.

Compiled 5 source(s), 23 page(s). Changed: 8.

With --approve, compile stages the changed wiki files plus a graph preview in state/approvals/ instead of mutating active wiki paths.

Without --approve, compile still writes active pages directly, but an optional orchestration post-pass can stage additional proposed markdown changes through the same approval queue.

With --max-tokens, compile also reports the estimated corpus size plus how many pages were kept versus dropped after trimming.

With --commit, the command creates a git commit only when wiki/ or state/ changed and the current vault root is inside a git worktree. Outside git, it becomes a no-op.

After compile, swarmvault graph share --post prints the compact share text from wiki/graph/share-card.md; swarmvault graph share --svg [path] writes the 1200x630 visual card from wiki/graph/share-card.svg; swarmvault graph share --bundle [dir] writes markdown, post text, SVG, a self-contained HTML preview, and JSON metadata from the same artifact.

Notes

Generated pages include a schema_hash in frontmatter plus lifecycle metadata such as status, created_at, updated_at, compiled_from, managed_by, and project_ids.

Human-authored pages in wiki/insights/ are indexed into search during compile, but compile does not rewrite them.