{
"id": "page:00-wiki-architecture",
"_kind": "Page",
"_file": "wiki/00-wiki-architecture.md",
"_cluster": "wiki",
"attributes": {
"title": "Wiki Architecture",
"displayName": "Wiki Architecture",
"slug": "00-wiki-architecture",
"articlePath": "wiki/00-wiki-architecture.md",
"article": "# Wiki Architecture\r\n\r\n> Phase-4 deliverable. The wiki is the user-facing projection of the graph — full encyclopedia, navigable, searchable, deeply cross-linked. **Every page is generated from a graph query, never authored.**\r\n\r\n## Site shape\r\n\r\nThe site is a static, file-based build. Output lands under `wiki/generated/`. Top-level navigation:\r\n\r\n```\r\n/\r\n├── overview/ (auto-derived: introduction, glossary, stack diagram)\r\n├── stack/ (one page per top-level Layer)\r\n├── products/ (one page per AgentProduct, with version subpages)\r\n├── capabilities/ (one page per Capability, with support matrix)\r\n├── hooks/ (one page per HookSurface, grouped by HookFamily)\r\n├── channels/ (one page per Channel + ChannelKind index)\r\n├── extensions/ (Plugin / NativeExtension / PortableExtension / Skill / Subagent / ToolServer / ToolDescriptor / Blueprint / ExtensionInterface)\r\n├── lifecycle/ (Run / Invocation / Session / Phase + state-machine diagrams)\r\n├── domain/ (Domain / Specialization / Topic / Language / Framework / StackProfile / ExpertiseLevel)\r\n├── roles/ (Role / Responsibility / OrgUnit)\r\n├── benchmarks/ (Benchmark / TestSet / EvalRun / EvalResult)\r\n├── trust/ (Authority / Attestation / TrustLevel)\r\n├── glossary/ (every Term, sorted; alias index)\r\n├── meta/ (CatalogVersion history, Generator catalog, evidence dashboard, gap dashboard)\r\n└── search/ (full-text search index endpoint)\r\n```\r\n\r\nThe full mapping of page type → query lives in [`01-derivation-mapping.md`](./01-derivation-mapping.md).\r\n\r\n## Navigation taxonomy\r\n\r\nNavigation is generated, never authored. Three layers:\r\n\r\n1. **Cluster sidebar** — the NodeKind clusters from `graph/schema/node-kinds/README.md`. Mirrors the schema's editorial frame.\n2. **Breadcrumbs** — derived from edge traversal. A `ModelVersion` page's breadcrumb is `Stack → Compute Path → ModelFamily(claude) → ModelVersion(claude-opus-4-7)`.\r\n3. **In-page TOC** — derived from the page's section list, which is itself derived from the page-type's query template.\r\n\r\nEvery link target is a node `id`; broken links are impossible because the link generator only emits links for ids that resolved during graph load.\r\n\r\n## Search\r\n\r\nFull-text search index built at generation time:\r\n\r\n- One document per page; `id`, `displayName`, `aliases` (from `Synonym` + `Acronym`), and the rendered prose body are indexed.\r\n- Lunr.js client-side search by default; pluggable to a hosted index (Algolia/Meili) via the same generator manifest.\r\n- Cross-reference highlights: when a query matches a `Term`, the result preview shows up to three nodes that `reference` it.\r\n\r\n## Cross-references\r\n\r\nCross-refs are first-class. Every NodeKind page renders:\r\n\r\n- **Outgoing**: edges this node has, grouped by `EdgeKind`, each with target link.\r\n- **Incoming**: reverse adjacency (e.g., a `Capability` page lists every `CapabilitySupport` and through it every `AgentVersion` that supports the capability).\r\n- **Mentioned in**: `Term` references back to nodes that name them.\r\n- **Evidence trail**: every claim on the page links to its `EvidenceSource`(s) and shows freshness state.\r\n\r\nA \"Why this page?\" disclosure on every page lists the exact graph query that produced it (and the manifest hash) — opening it shows which `Generator` is responsible, satisfying the audit requirement in Phase 5.\r\n\r\n## Authoring vs generation\r\n\r\nAuthoring touches **only**:\r\n\r\n- `assets/` (logos, hand-drawn diagrams, screenshots).\r\n- Page templates inside `graph/wiki/generators/templates/wiki/`.\n- Navigation configuration (which clusters appear, ordering).\r\n\r\nAuthoring **never** touches `generated/`. CI rejects any PR that hand-edits a file under `generated/` without a corresponding template/data change.\r\n\r\n## Asset handling\r\n\r\n- Hand-drawn diagrams in `assets/diagrams/` are referenced by node id (`asset:diagram-stack-overview`) and tracked as `EvidenceSource` records of `kindLabel = file` so freshness checks apply uniformly.\r\n- Auto-rendered diagrams (mermaid) live under `generated/assets/` and are produced by the stack-diagram generator.\r\n\r\n## Generation cadence\r\n\r\n| Trigger | Action |\r\n|---|---|\r\n| Per PR | Re-run generators that consume any node touched by the PR. CI fails if the resulting tree diff exceeds the PR's claimed scope (Level-2 / Level-4 gate). |\r\n| On merge to main | Full regeneration; static site published to the docs host. |\r\n| Weekly | Full regeneration without code changes — surfaces stale evidence (Level-1 freshness gate). Any new diff means an external truth has shifted; opens a Level-1 `Gap`. |\r\n| On schema bump | Full regeneration tagged with the new `CatalogVersion`; previous version archived under `/wiki/<version>/`. |\r\n\r\n## Versioning\r\n\r\nThe published site has a version selector keyed to `CatalogVersion`. Pinning a wiki page URL to `/<semver>/...` returns the exact prose generated against that schema version, supporting Phase 5's downstream-pinning contract.\r\n",
"documents": []
},
"outgoingEdges": [],
"incomingEdges": []
}