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.

Source And Projection Map

Source of truth	Generated surface	Command
Hand-written wiki markdown	`wiki/_index.md`, `wiki/_backlinks.json`, root README stats	`npm run build-index`
Hand-written wiki markdown	qmd lexical and semantic search	`qmd update && qmd embed`
Public canonical Markdown + shared privacy policy + stable-object visibility	OKF v0.2 tree in `outputs/okf/` and production `.content/okf` served by `/api/okf`	`npm run okf:check` / `npm run okf:export`
`brain/*.json`, workflow manifests, registries, and wiki owners	`/system`, `/api/system/graph`, typed runtime queries	`npm run brain` and UI build
Skill source directories	Skill Registry, `wiki/skills/<category>/`, family pages, `skills/.runtime/all`	`npm run skill-registry`
Skills and package scripts	Slash Command Index	`npm run slash-command-index`
`wiki/meta/wiki-redirects.json`	Wiki Redirect Index	`npm run wiki-redirect-index`
Capability snapshots	Ecosystem Capability Coverage	`npm run ecosystem-coverage:audit`
X enriched records and manual decisions	`wiki/meta/x-bookmark-artifact-audit.json` and review queue	`npm run audit:x-bookmark-artifacts`
Doctor and audit scripts	doctor results, history, and audit ledgers	run the owning doctor or audit

Edit Rule

If a projection is wrong, fix the owning wiki page, brain object, workflow manifest, skill, redirect ledger, configuration, or generator. Then rerun the owning command. Directly editing a generated file is only valid while repairing its generator.

Stateful Ledgers

Ledger	Preserved state
`wiki/meta/x-bookmark-artifact-audit.json`	Review status, artifacts, decisions, promoted targets, visual notes.
`wiki/meta/page-consolidation-audit.json`	Merge, fold, and routing candidates.
`state.json`	Automation and synchronization timestamps.

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

Closeout Bundles

Change class	Minimum closeout
Wiki page	`npm run build-index`; qmd update/embed; `wiki/log.md`
Structural filing or redirect	Page closeout plus redirect index, wiki quality, and doctor
Brain graph or workflow	Runtime tests, routing doctor, UI build, page closeout
Skill source or routing	Skill registry, skills check, routing doctor, page closeout
Slash command or package script	Slash-command regenerate/check, page closeout
Public owner, privacy, or OKF projector	`npm run okf:check`; production build; page closeout
Capability ecosystem	Ecosystem audit, routing doctor, page closeout
Automation schema or schedule	Freshness check; update state only through the owning run
Agent configuration	Bootstrap, config-sync doctor, page closeout

Failure Modes

Rebuilding the markdown index but forgetting qmd.
Updating skills without refreshing the registry and runtime links.
Changing a source without interrogating its bound brain objects and workflows.
Hand-editing an OKF output instead of changing its canonical owner or projector.
Folding pages without redirects for old retrieval paths.
Treating an audit queue as completed work.
Resetting a stateful ledger and losing review history.

Timeline

2026-08-11 | Added the deterministic, privacy-filtered OKF v0.2 bundle as a generated interoperability surface. Canonical pages and registries remain write authority; /api/okf serves only the regenerated tree. Source: OKF v0.2 SPEC; local conformance replay
2026-08-10 | Aligned generated surfaces with the graph-backed brain, workflow registry, and executable skill system. Source: User request, 2026-08-10
2026-07-06 | Added the generated slash-command surface. Source: User request, 2026-07-06
2026-07-01 | Created the source/projection ownership contract. Source: User request, 2026-07-01

Source: OKF v0.2 SPEC; local conformance replay

Source: User request, 2026-08-10