Status	Last updated	Parent	Read before this
complete	2026-04-30	Design - Architecture Overview	Design - Architecture Overview

Wiki Layer

Current state

The wiki holds post-deployment, reader-oriented documentation of the consuming project. Issues hold transactional work-in-progress; the wiki holds stable system knowledge.

What the wiki owns:

• Living component/module pages (continuously updated as features land)
• Cross-feature architecture and ADRs
• Synthesized learnings
• Release notes

The wiki is organised by reader's mental model, not by developer's unit of work. Roughly twelve component or module pages, not fifty feature pages. Pages reflect how someone reasons about the system ("how does auth work?") rather than how work was chunked for delivery.

The wiki is updated by Role - The Documentation Agent — a separate agent population from coding harness agents. Its job is maintenance, not summarization: it reads from the queue of issues in pending-docs state and updates relevant existing pages. New pages get created only when a feature introduces a genuinely new component or module — not per feature.

There's no SLA. The queue gets processed; if processing falls behind, the queue grows but nothing breaks.

Rationale

The split between issues and wiki tracks the lifecycle of the content. Issues are append-only chronological logs of work that happened. The wiki is current-state documentation that supersedes itself — see the supersede-don't-append discipline in Wiki Conventions. Mixing the two in one substrate would either pollute the issue tracker with reference docs or pollute the wiki with work history.

The "twelve pages, not fifty" sizing comes from observing what readers actually look for. Nobody asks "how was feature 42 built?" — they ask "how does the auth system work?" Per-feature pages duplicate effort, fragment knowledge, and rot in place because no one reads them once the feature is shipped. Component pages get continuously edited by every feature that touches that component.

A separate agent population exists because coding harness agents and the doc agent need different mental models. Coding harness agents think in feature work; the doc agent thinks in component knowledge. If one agent held both at once — for example, if /closeout could write to the wiki — the predictable failure mode is wiki pages that read like feature changelogs, which is exactly what "twelve pages, not fifty" is designed to avoid.

Open questions

The doc agent's exact integration point is undecided — see Role - The Documentation Agent for specifics.