Wiki Brain Operating Model
The wiki should behave like a compiled brain: coherent articles, stable retrieval, generated inventories, explicit provenance, and routing that makes the next edit obvious.
This is the shape spec for broad wiki changes. Read it before consolidation, recategorization, page creation, or any rewrite that could change the graph. Then use Filing Decision Tree for directory placement.
The durable unit is not a captured thought, source, skill, or folder path. The durable unit is a coherent mental object: a page, section, ledger row, generated view, or redirect that future agents can retrieve and update without reconstructing the original chat.
Current Brain State
The current wiki is no longer just flat article pages. It has canonical synthesis pages, operational protocols, generated skill/source views, portable agent-doc packs, identity/cadence extractions, and redirect ledgers. The filing model has to account for all of them. Source: User request, 2026-07-01
| Surface | Role |
|---|---|
wiki/RESOLVER.md |
Directory-level page filing. |
wiki/meta/ |
Operating model, protocols, quality gates, sync, automation, generated-index docs. |
wiki/resolver/ |
Compact retrieval companions for filing rules. |
wiki/skill-resolver/ |
Compact retrieval companions for task/tool/skill dispatch. |
wiki/soul/, wiki/user/, wiki/heartbeat/ |
Extracted identity, Kevin model, and cadence expansions. |
wiki/agent-docs/ |
Generated or pack-oriented agent context surfaces. |
wiki/skills/<category>/ |
Generated source views for executable skills. |
wiki/concepts/*-skills.md and Skill Registry |
Readable skill-family synthesis and generated inventory. |
wiki/meta/wiki-redirects.json and Wiki Redirect Index |
Retired slug retrieval. |
| Generated Surface Contract | Source/projection ownership for indexes, packs, registries, redirects, qmd, and stateful ledgers. |
Thesis
Flatten meaning. Use folders to clarify ownership, not to manufacture ontology.
A good wiki page should be useful to a human reader and to an agent. It should explain what is true now, preserve why we believe it, and make the next action obvious. If a page only exists because a source was captured once, it is probably the wrong shape.
Design Targets
| Target | Rule |
|---|---|
| Readability | A human should understand the article without knowing the ingestion history. |
| Retrieval | Old names, aliases, and redirects must still resolve after merging. |
| Compression | Merge low-signal pages into stronger parent articles, ledgers, timelines, or tables. |
| Evidence | Preserve source trails in timelines, citations, source pages, raw captures, or generated ledgers. |
| Agent usability | Every article should answer "when do I use this knowledge?" |
| Maintenance | Generated inventories stay generated; hand-written pages own synthesis. |
Brain Architecture
Page Layers
| Layer | Purpose | Authoring rule |
|---|---|---|
| Canonical synthesis article | Readable mental object. | Hand-written, source-backed, revised in place. |
| Directory hub or README | Local ownership and navigation. | Hand-written and short. |
| Tool/ecosystem page | Facts, setup, tradeoffs, interfaces, alternatives. | Hand-written, current enough, source-backed. |
| Workflow page | Human/team process or operational runbook. | Hand-written checklist plus failure modes. |
| Executable skill | Actual agent procedure. | Lives in skills/{engineering,productivity,personal,misc,in-progress,deprecated}/<slug>/SKILL.md. |
| Generated skill source page | Browseable view of executable skill source. | Generated under wiki/skills/<category>/; do not hand-edit generated bodies. |
| Skill registry/family page | Inventory plus readable capability synthesis. | Registry is generated; family pages are synthesis-backed. |
| Source/evidence entry | Provenance, raw extraction, or timeline material. | Preserve evidence; do not pretend it is synthesis. |
| Ledger | Compact store for low-signal entities. | Table/list with aliases and promotion criteria. |
| Generated pack | Portable agent context bundle. | Never hand-edit; regenerate from source pages. |
| Redirect | Retired slug that should still resolve. | Store in wiki/meta/wiki-redirects.json; regenerate Wiki Redirect Index. |
Category Shape
Use Filing Decision Tree for final placement. This model describes why the placement exists.
| Category family | Owns |
|---|---|
| Article categories | architecture/, career/, concepts/, decisions/, design/, interview-prep/, people/, philosophies/, postmortems/, projects/, research/, stories/, style/, tools/, workflows/. |
| Operational categories | meta/, resolver/, skill-resolver/, soul/, user/, heartbeat/, inbox/. |
| Generated or asset categories | agent-docs/, skills/, assets/. |
| Dormant schema categories | places/, patterns/, tensions/, eras/, transitions/ when a real cluster justifies them. |
Everything else should justify itself. If a category mostly contains stubs, fold those stubs into a stronger article, ledger, timeline, or generated view.
Flattening Rule
Prefer a strong article with sections and decision tables over a deep tree of thin pages. Use subfolders only when they improve browsing, enforce generation boundaries, or preserve a mature domain.
Good reasons for subfolders:
- Generated namespaces such as
wiki/skills/<category>/andwiki/agent-docs/. - Resolver companion pages that provide retrieval handles but point back to canonical authority.
- Identity/cadence expansions that keep boot files readable.
- Asset provenance and media groupings.
- Mature domains with multiple real standalone articles.
Folders are navigation. Identity lives in canonical slugs, titles, aliases, redirects, and qmd retrieval.
Article Standard
Every canonical article should include the subset of these sections that helps the topic:
| Section | Purpose |
|---|---|
| One-line thesis | What the page lets the reader understand or decide. |
| Routing summary | When humans or agents should open it. |
| Core model | The actual explanation. |
| Decision matrix | Tradeoffs, routes, comparisons, ownership boundaries. |
| Tool/skill routing | What to load or use when the page changes behavior. |
| Failure modes | Common mistakes and confusions. |
| Evidence/timeline | Source trail without turning the article into a diary. |
| Related pages | Neighboring mental objects. |
Small pages do not need every section. Long pages need enough structure to be scanned.
Combining Rule
When merging pages, preserve ideas by changing their form:
| Old page shape | New form |
|---|---|
| One-off thought | Section in a canonical article. |
| Skill mirror | Generated source page plus row in Skill Registry. |
| Similar tools | Comparison table in an ecosystem/tool article. |
| Minor person/entity | Row in a ledger with aliases and promotion criteria. |
| Source summary | Timeline entry, raw source reference, or provenance note. |
| Duplicate concept | Alias, redirect, and merged section. |
| Narrow procedure | Executable skill or workflow subsection. |
| Resolver micro-rule | Companion page under wiki/resolver/ that points back to Filing Decision Tree. |
No idea gets deleted because it is small. It gets promoted, folded, generated, or redirected.
Rewrite Procedure
- Pick a cluster, not a pair of pages.
- List pages, aliases, source files, skills, tools, generated packs, and redirects in the cluster.
- Choose the canonical article owner.
- Move useful claims into the owner as sections, rows, matrices, or timeline entries.
- Preserve source trails, citations, dates, and embeds.
- Add aliases for old titles.
- Add redirects for retired slugs.
- Update wikilinks when the old link should no longer resolve through redirects.
- Regenerate indexes, qmd, packs, and audits.
- Log the rewrite.
Promotion And Demotion
| Action | Trigger |
|---|---|
| Promote to standalone page | Durable retrieval value, multiple sources, decisions, active use, or future agent trigger. |
| Keep as section | The idea only makes sense inside a broader topic. |
| Keep as ledger row | The entity matters but does not justify narrative context. |
| Keep as generated page | It is inventory, executable source, or derived context. |
| Keep as evidence | Provenance matters more than synthesis. |
| Keep as redirect | Old slug/title still matters for retrieval. |
| Keep as session-only | No durable retrieval value. |
Validation Loop
After any structural rewrite:
npm run build-index
npm run wiki-quality
npm run routing-doctor
npm run agent-packs:refresh
npm run agent-packs:check
npx tsx scripts/doctor.ts --quiet
qmd update && qmd embed
Use npm run wiki:resolve -- <old-slug> to verify retired names still land on the intended article.
Timeline
- 2026-07-01 | Updated the operating model for the current wiki shape: resolver companions, skill-resolver extracts, identity/cadence subtrees, generated agent-doc packs, generated skill source views, and dormant schema categories. Source: User request, 2026-07-01
- 2026-07-01 | Added Generated Surface Contract as the explicit source/projection layer for generated pages, packs, registries, qmd, redirects, and stateful ledgers. Source: User request, 2026-07-01
- 2026-06-27 | Established the wiki brain operating model after the skill-source folder work revealed the larger need: flatten meaning, combine weak articles, keep generated inventories generated, and make the brain readable to humans and agents. Source: User request, 2026-06-27