Generated Surface Contract

Generated surfaces are projections of source truth. Update the source or generator, then regenerate; do not make the projection the new authority.

This page owns the distinction between durable source pages, generated inventories, generated packs, runtime indexes, and review ledgers. It exists so broad wiki work can refresh the brain without hand-editing derived files into drift.

Routing

Open this page when work touches:

wiki/_index.md, wiki/_backlinks.json, qmd search, or root README stats
agent-docs/packs/*.md, agent-docs/capsules.json, Brain Capsules, or Agent Doc Pack Index
Skill Registry, Slash Command Index, wiki/skills/<category>/, or skills/.runtime/all
Wiki Redirect Index or wiki/meta/wiki-redirects.json
audit ledgers such as agent-pack-corpus-audit.json, page-consolidation-audit.json, or x-bookmark-artifact-audit.json
generator scripts under scripts/

Source And Projection Map

Source of truth	Generated surface	Command
Hand-written wiki markdown	`wiki/_index.md`, `wiki/_backlinks.json`, root README stats block	`npx tsx scripts/build-index.ts`
Hand-written wiki markdown and qmd database	qmd lexical/semantic search	`qmd update && qmd embed`
`skills/{engineering,productivity,personal,misc,in-progress,deprecated}/`	Skill Registry, `wiki/skills/<category>/`, skill family pages, `skills/.runtime/all`	`npm run skill-registry`
`skills/{engineering,productivity,personal,misc,in-progress,deprecated}/` and `package.json` scripts	Slash Command Index	`npm run slash-command-index`
Wiki pages, capsule definitions, pack definitions, pack audits, and Agent Docs System Map	`agent-docs/packs/*.md`, `agent-docs/capsules.json`, Brain Capsules, Agent Doc Pack Index	`npm run agent-packs:refresh`
`wiki/meta/wiki-redirects.json`	Wiki Redirect Index	`npm run wiki-redirect-index`
Capability harvest snapshots and coverage script	Ecosystem Capability Coverage	`npm run ecosystem-coverage:audit`
X bookmark enriched records and manual review fields	`wiki/meta/x-bookmark-artifact-audit.json` and output queue	`npm run audit:x-bookmark-artifacts`
Doctor and audit scripts	`wiki/meta/doctor-results.json`, `wiki/meta/doctor-history.json`, audit output files	run the specific doctor or audit

Edit Rule

If a generated page is wrong, fix one of these instead:

The source page, skill, redirect JSON, capsule definition, or audit ledger row.
The generator script.
The seed/config file used by the generator.

Then rerun the command. Only edit a generated file directly when the generator is broken and the direct edit is part of repairing or bootstrapping the generator. Log that exception.

Ledgers Are Different

Some tracked JSON files are both generated and stateful. They may preserve manual review fields across reruns:

Ledger	Preserved state
`wiki/meta/x-bookmark-artifact-audit.json`	Review status, reviewed artifacts, decisions, promoted pages, visual notes.
`wiki/meta/agent-pack-corpus-audit.json`	Current pack/capsule decisions and review queues.
`wiki/meta/page-consolidation-audit.json`	Current merge/fold/router review candidates.
`state.json`	Automation and sync timestamps.

Do not delete these to "refresh" them unless the owning script explicitly supports a reset and Kevin approved losing the review state.

Closeout Bundles

Change class	Minimum closeout
Page-only wiki edit	`npx tsx scripts/build-index.ts`; `qmd update && qmd embed`; `wiki/log.md`
Structural filing, merge, redirect, or category change	Page-only closeout plus `npm run wiki-redirect-index` if redirects changed, `npm run wiki-quality`, `npx tsx scripts/doctor.ts --quiet`
Skill source, skill routing, or skill family change	`npm run skill-registry`; `npm run routing-doctor`; page-only closeout
Slash-command surface or package-script change	`npm run slash-command-index`; `npm run slash-command-index:check`; page-only closeout
Capsule or pack-source change	`npm run agent-packs:refresh`; `npm run agent-packs:check`; page-only closeout
Capability ecosystem change	`npm run ecosystem-coverage:audit`; `npm run routing-doctor`; page-only closeout
Automation schedule/schema change	`npx tsx scripts/check-freshness.ts`; update `state.json` only through the run or owning script; page-only closeout
Agent config change	`npm run bootstrap`; `npx tsx scripts/doctor.ts --only config-sync`; page-only closeout

Failure Modes

Hand-editing Brain Capsules or generated packs instead of updating source pages.
Rebuilding _index.md but forgetting qmd, so semantic search misses new pages.
Updating skills/ without regenerating Skill Registry and runtime links.
Folding pages without adding redirects for old retrieval paths.
Treating audit queues as completed work instead of promotion candidates.
Resetting stateful ledgers and losing review history.

Timeline

2026-07-06 | Added Slash Command Index as the generated command surface for local skills, package scripts, and upstream alias routes so root agent docs can stay pointer-sized. Source: User request, 2026-07-06
2026-07-01 | Added the AGENT DOCS system map and generated pack index to the explicit source/projection contract. Source: User request, 2026-07-01
2026-07-01 | Created as the canonical contract for source/projection ownership, generated-surface commands, stateful ledger handling, and closeout bundles. Source: User request, 2026-07-01

Source: User request, 2026-07-06