# LLM Wiki Overlay — Methodology

## Purpose

Document the methodology for building a **derived LLM wiki** on top of
canonical SSOT docs. The overlay is a non-canonical, human-and-agent-friendly
layer of compiled pages (concepts, syntheses, dashboards, reading guides) that
makes retrieval cheaper and reasoning more stable, **without ever becoming
source-of-truth**.

This module describes the contract, file layout, and lifecycle of the overlay.
The agent that maintains it is `wiki-curator`. The skill that captures synthesis
pages from live conversations is `/capture`.

## Layered Knowledge Stack

The wiki overlay sits on top of an existing retrieval stack. A typical layout:

| Layer | Role | Authority |
|-------|------|-----------|
| Canonical SSOT (`${paths.references_dir}/**`, `${paths.adrs_dir}/**`, code itself) | Source of truth | **Canonical** — never override from below |
| External human knowledge (Obsidian vault, Notion, Confluence) | Human-readable narrative; optional | Mirrors canonical with extra context |
| **Wiki overlay** (`${paths.wiki_dir}/**`) | Compiled, navigable, stable | **Derived** — always cites canonical refs |

Rules:

1. The wiki never creates canonical truth.
2. SSOT changes propagate down; wiki pages must be recompiled when canonicals
   change.
3. If a wiki page conflicts with SSOT, SSOT wins and the wiki page is rewritten.

## Page Types

A complete overlay typically contains five page types:

| Type | Folder | Purpose |
|------|--------|---------|
| **Concept** | `${paths.wiki_dir}/concepts/` | Explanatory pages that define a term, pattern, or system component |
| **Synthesis** | `${paths.wiki_dir}/syntheses/` | Multi-source distillation of cross-document reasoning (often captured via `/capture`) |
| **Dashboard** | `${paths.wiki_dir}/dashboards/` | Current-state snapshots (status of an epic, freshness of a SSOT, validator output) |
| **Reading Guide** | `${paths.wiki_dir}/reading-guides/` | Ordered paths into the corpus for specific tasks (onboarding, incident response) |
| **Index** | `${paths.wiki_dir}/index.md` | Single navigation entry point listing the other pages |

The `${paths.wiki_dir}/log.md` file is an **append-only event log** recording
synthesis candidates and captures (see § Maintenance & Capture).

## Frontmatter Discipline (MANDATORY)

Every wiki page MUST carry frontmatter so agents and validators can route and
trust the page:

```yaml
---
doc_type: synthesis | concept | dashboard | reading-guide | log | index
domain: <e.g. platform | booking | payments | …>
canonicality: derived          # NEVER `canonical` — that's the SSOT layer's contract
owner: <agent or team>
status: active | draft | deprecated
freshness_status: fresh | stale | needs-rebuild
confidence: high | medium | low
source_refs:                   # explicit canonical doc paths the page synthesizes
  - ${paths.adrs_dir}/<ADR>.md
  - ${paths.references_dir}/<ref>.md
last_verified_from_code: YYYY-MM-DD
canonical_refs:                # broader canonicals this page is consistent with
  - ${paths.references_dir}/ssot-registry.md
  - ${paths.references_dir}/project-status.md
---
```

Run a frontmatter validator (typically `npm run validate:frontmatter` or
equivalent) before committing wiki edits.

## Anchor & Cross-Reference Discipline

- Markdown slugification: lowercase, spaces → dashes, strip punctuation except
  dashes (GitHub-flavored).
- For every `[text](#some-anchor)` link, the corresponding heading must exist
  with the slugified form `some-anchor`.
- For every `[text](../foo.md#anchor)` link, the heading must exist in
  `foo.md`.
- The `wiki-curator` agent flags `WIKI_ANCHOR_BROKEN` on mismatch and fixes
  it in the same invocation when possible.

## Maintenance & Capture

The overlay is maintained on two paths — a scheduled structural sweep and an
on-demand capture from live conversations.

### Synthesis candidates (nightly review)

The `wiki-curator` agent, running on a schedule (typically nightly), scans:

- ADRs and PRDs from the last 14 days with significant architectural impact
  (touches >3 modules, provider swap, schema change, auth change, API
  contract) → propose a synthesis page.
- PRD-led multi-card epics (≥4 cards in same parent epic) → propose an
  overview synthesis.
- **(when `features.has_code_graph: true`)** Graphify's native
  `${graph.output_dir}/GRAPH_REPORT.md` — **god nodes** (highest-degree core
  abstractions), **communities** (Leiden clusters), and the auto-generated
  **suggested questions** — cross-checked against existing synthesis pages.
  A god node or community with no corresponding wiki page → propose a synthesis
  (this is the auto-learning signal, replacing the removed RAG verdicts).

Candidates are appended to `${paths.wiki_dir}/log.md` with
`entry_type: synthesis_candidate` and a small payload (title, source refs,
expected scope, triggering agent).

### `/capture` skill (manual + proactive)

The `/capture` skill turns a recent multi-turn synthesis (cross-document
reasoning done in a conversation) into a durable synthesis page under
`${paths.wiki_dir}/syntheses/<slug>.md`. Two modes:

| Mode | When | How |
|------|------|-----|
| **Manual** | User runs `/capture` explicitly | Skill reads pending queue + recent turns, proposes a synthesis |
| **Proactive** | A `Stop`-event hook detected a synthesis-worthy turn and queued a candidate | Next `/capture` invocation surfaces the candidate first |

Manual mode always works. Proactive mode is a convenience layer the user can
disable with a kill-switch file (`touch .claude/capture-queue/.disabled`).

The skill requires explicit user approval before writing. Acceptance and
rejection are both logged.

### Auto-learning loop (Graphify-fed, when `has_code_graph: true`)

The original RAG-fed loop (weak/empty search verdicts → gap → synthesis) was
removed in v4.20.0. It is now **re-activated on the code graph** (v4.21.0): the
gap signal is structural, not retrieval-telemetry, and entirely **offline**
(no API cost).

```
graphify update .  (native, on commit via `graphify hook install`)
        │
        ▼
graphify-out/GRAPH_REPORT.md  (god nodes · Leiden communities · suggested questions)
        │   (cross-check vs ${paths.wiki_dir}/syntheses/*)
        ▼
wiki-curator / doc-graph-align  → propose synthesis for uncovered god nodes/communities
        │
        ▼
/capture writes the page  → next graph review finds it covered
```

The graph never becomes canonical — synthesis pages still cite repo SSOT and the
`canonicality: derived` contract holds. When `has_code_graph: false` or Graphify
is absent, the loop is simply inactive and the overlay runs on the manual +
ADR/PRD-scheduled paths above (no regression). Engine details:
`docs/archive/rag-layer/rebind-to-graphify.md` and
`framework/agents/code-graph-protocol.md`.

## Roles & Responsibilities

| Role | Owns | Edits |
|------|------|-------|
| `wiki-curator` agent | Overlay quality, drift detection, candidate proposal | `${paths.wiki_dir}/**` |
| `/capture` skill | Synthesis page creation from live conversations | `${paths.wiki_dir}/syntheses/**` |
| `doc-reviewer` agent | Canonical SSOT integrity (downstream of the overlay) | `${paths.references_dir}/**`, `${paths.adrs_dir}/**` |
| Project-specific knowledge-sync agent (optional) | Mirror to external corpus (Obsidian/Notion/Confluence) | External corpus only |

## Adoption Checklist (for a new project)

To install the LLM wiki overlay in a new project:

1. Create `${paths.wiki_dir}/` with the five page-type folders and an `index.md`.
2. Add the frontmatter validator (or adapt your existing one) to check
   wiki frontmatter compliance.
3. Schedule the `wiki-curator` agent to run on a nightly cadence
   (cron / Claude Code remote agent / GitHub Action).
4. Enable the `/capture` skill for users and (optionally) the proactive hook.
5. Document the overlay in your repo README so contributors know it exists
   and is non-canonical.

## Related

- Agent: [`.claude/agents/wiki-curator.md`](../.claude/agents/wiki-curator.md)
- Skill: [`.claude/skills/capture/SKILL.md`](../.claude/skills/capture/SKILL.md)
- Doc-writer agent: [`.claude/agents/doc-reviewer.md`](../.claude/agents/doc-reviewer.md)
