docs: document the repository graph and project memory

[RomanEmreis]

Documentation for the 0.4 repository graph release.

New pages

Repository graph (/docs/repository-graph) — the flagship page:

• enablement (opt-in; the [repository_graph] namespace is not scaffolded by ferrus init)
• incremental indexing, --full, and where the sidecar lives
• the three built-in extractors with their actual node and edge kinds, plus semantic key formats
• the full ferrus graph status|search|show|context|neighbors surface with real command output
• why availability, build state, and freshness are three orthogonal axes rather than one flag
• task worktree views: pinned baseline + changed-file overlay, frozen submitted views, and the no-silent-fallback rule
• the read-only MCP tools, verified snippets, and the "absence is not proof" contract
• privacy invariants, query budgets, and the recorded benchmark and evaluation results — including the honest context-byte caveat from the RG2 evaluation

Project memory (/docs/project-memory):

• the default source allowlist and, explicitly, what is never indexed
• ferrus graph memory index|status
• --domain repository|memory|all and what federation does not do
• repository link resolution states (resolved / stale / unresolved)
• archive-driven refresh and independent freshness

Updates to existing pages

Page	Change
Configuration	[repository_graph] reference with a per-namespace "affects snapshot identity" column; source, index_limits, query_limits, retention, telemetry defaults; the two new sidecars in the runtime file table
Quickstart	optional step 5, "Index your repository"
Supported agents	the six read-only retrieval tools exposed to every role
State machine	pinned per-task repository views, and that indexing is never a correctness dependency
Specs & Milestones	how an approved ## Outcome feeds project memory

Plus a Repository intelligence sidebar category, navbar and footer entries, a homepage section, two new feature cards, and the version bump to 0.4.0-alpha.1.

Verification

npm run build passes clean — no broken links (onBrokenLinks: 'throw') and no broken anchors.

Command output, node/edge vocabulary, semantic key formats, config defaults, MCP tool names, and input schemas in the examples were all read from the source or captured from ferrus 0.4.0-alpha.1 running against the ferrus repository, rather than paraphrased from the design docs.

Note

ferrus/docs/milestones.md still lists the repository graph and project memory as "not started". That is a separate repository and is already planned.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	ferrus	203e9b9	Commit Preview URL Branch Preview URL	Aug 31 2026, 03:06 PM