# Concepts

`llm-wiki-kit` follows the LLM Wiki pattern:

```text
raw sources -> wiki -> schema/rules
```

- `raw/` is evidence. It is immutable unless a hook appends a redacted event envelope.
- `wiki/` is the living Markdown knowledge layer maintained by the agent.
- `wiki/memory.md` is the compact hot index that keeps the most reusable current facts close to the context window.
- `AGENTS.md`, `CLAUDE.md`, and `.kit/procedures/` are the schema/rules layer; `procedures/` holds user-authored runbooks (`type: procedure`, first-class wiki pages).
- `.kit-state.json` records which managed rules/templates were applied by which runtime version.

The important behavior is a loop:

1. A Claude Code or Codex session starts.
2. `memory.md`, `index.md`, and relevant wiki context are injected automatically with an answer-first instruction.
3. The user works normally; no extra command loop is required.
4. Hooks gather redacted prompt/tool/result summaries.
5. At stop/session end, hooks append redacted chunked live Q&A only for handoff-worthy durable checkpoints: explicit durable requests, structured durable conclusions, or durable wiki/procedure updates.
6. When possible, generated candidates carry safe `evidence_refs` such as changed files, verification commands, raw source IDs, or external URLs.
7. Simple answers, status checks, and keyword-only responses stay out of live Q&A and durable wiki by default.
8. Durable wiki promotion is selective: explicit record/document requests and structured durable conclusions enter the queue, but the active agent should batch-review and merge only explicit, repeated, or clearly reusable facts into existing wiki pages.
9. At the next start/prompt after an abrupt shutdown, hooks retry the same generation-scoped delivery. Archive-worthy buffered turns are written idempotently to chunked live Q&A; a maintenance item is added only when policy requires review and is deduplicated against normal Stop delivery. State is marked complete only after required side effects succeed.
10. At session start, hooks may report maintenance pressure but do not mutate the queue or layout. Explicit `maintenance --apply-lifecycle` keeps candidates pending for batch review, may skip old low-signal items, and archives old reviewed items without generating wiki pages automatically.
11. When reusable knowledge appears repeatedly or explicitly, the active Claude Code/Codex agent folds it into existing durable wiki pages instead of creating one page per candidate.
12. Export and eval reuse the same durable visibility policy so handoff manifests, retrieval fixtures, and context selection describe the same wiki surface.
13. Future sessions start from the improved wiki instead of relying on long chat history.

The kit is a template/runtime repository. It must not centralize project wiki contents.

Runtime updates and project knowledge are separate:

- npm updates replace the runtime package and hook targets.
- project patching updates only managed policy blocks and generated procedure files.
- old generated `llm-wiki/AGENTS.md` and procedure files are refreshed only by explicit `install`, `update`, or `post-update` commands when they are clearly kit-generated, even if old project state is missing.
- user-edited files are preserved and surfaced to the agent as cleanup work.
- `memory.md` is created when missing, then treated as project-owned content.
- curated wiki pages remain project-owned content and are not overwritten by runtime updates.

The maintenance loop is intentionally layered:

- `memory.md`: short hot index for current durable facts.
- `index.md`: broad navigation map.
- `memory`: read-only review of the active wiki root, current focus, durable entry points, retrieval hits, queue state, and lint/eval health.
- MiniSearch + wikilinks: retrieval over durable `wiki/**/*.md`, including frontmatter `aliases`, `description`, `globs`, and low-boost scalar values under `extensions`. Pages with `memory_type: episodic` and episodic query/context/session roles are hidden by default unless promoted or `--include-episodic` is requested; archived/superseded pages stay preserved but hidden unless `--include-archived` is requested. Verbose context explains `why selected`, hidden-page reasons, and snippet budgets; hook context stays compact.
- `activation` and `visibility`: optional frontmatter for ranking and export policy. `activation: always` slightly boosts retrieval, `activation: manual` downranks it, and `visibility: private` or `no-export` excludes a page from generated exports.
- `evidence_refs`: optional frontmatter that ties durable claims to `file:`, `cmd:`, `raw:`, or `url:` evidence without embedding secrets or raw transcripts.
- Fixed core + extensions: curated pages carry `title`, `type`, `status`, `memory_type`, and `last_updated` (missing core fields are lint warnings; invalid values are errors). Optional standard fields use stable defaults; project-specific typed metadata belongs under `extensions` with lowercase snake_case keys.
- `outputs/maintenance/queue.md`: selective reminders for explicit durable requests, structured durable conclusions, and stale turn recovery that need batch review. Queue state is `pending`, `approved`, `done`, or `skipped`; reviewed history can move to `outputs/maintenance/archive/`.
- `lint`: finds broken links, stale pages, duplicates, metadata gaps, invalid evidence refs, secret-like content, outdated managed rules, memory/page-count budget pressure, hidden episodic growth, and stale/archived discoverability gaps.
- `maintenance`: reports `reviewDue` only when periodic thresholds are met; hook reminders are soft and limited to session start/instructions loaded or compact prompt-time reminders for maintenance prompts, approved items, explicit durable requests, recovered items, or batch-threshold pressure. `--apply-lifecycle` previews or applies bounded queue hygiene and deprecated scaffold migration; it does not merge, auto-approve, or create durable wiki pages.
- `consolidate`: agent helper that refreshes bounded generated blocks in `memory.md` and `index.md` while preserving handwritten notes, balancing memory entries across page types, reporting omissions, keeping episodic pages out of durable maps, and skipping stale/archived/superseded pages.
- `eval`: checks retrieval fixtures in `llm-wiki/evals/retrieval.json` and reports recall, MRR, stale-hit rate, citation coverage, missed expected paths, unexpected hits, hidden unexpected hits, and top hits.
- `export`: writes redacted `llms.txt`, `llms-full.txt`, and `llm-wiki.json` manifests for agent onboarding, handoff, retrieval eval, and external consumption using the same durable visibility policy. `llms.txt` is not treated as a passive SEO artifact.