Documentation Surfaces

STAGE separates interfaces for humans and agents without duplicating project truth.

Decision

Use one versioned source chain and three views:

View	Consumer	Responsibility
Canonical source	Humans, agents, Git, validation	Markdown, YAML, schemas, and code owning the actual decision or contract
Agent interface	Codex	AGENTS.md, packaged skills, and deterministic helpers that route to canonical sources
Human reading interface	Owner and readers	A generated documentation site with navigation, search-ready structure, and readable presentation

Changing prose in the site must mean changing its canonical Markdown source. The site build is a consumer, not an authoring database.

Canonical Source

The authority order remains:

1. SPEC.md for normative method requirements;
2. docs/glossary.md for vocabulary;
3. docs/adr/ for current and superseded decisions;
4. packaged skills for executable agent procedure;
5. practitioner and maintainer guides for explanation; and
6. studies and release records for bounded historical evidence.

Keep one owner for each fact. Prefer links and curated reading paths over copied paragraphs.

Agent Interface

Agent-facing material should optimize for routing and safe execution:

• AGENTS.md stays short and mandatory;
• skill frontmatter states when a workflow should trigger;
• SKILL.md carries concise procedure and stopping rules;
• deterministic scripts gather repository facts that should not depend on model memory; and
• longer rationale stays in canonical guides or skill references loaded only when relevant.

Agent instructions are not the best human handbook. They prioritize compact, unambiguous control flow over narrative teaching.

Human Reading Interface

The site is built with Docusaurus from selected canonical repository documents. It provides:

• a task-oriented start page;
• workflow selection and quick invocation examples;
• concept and safety explanations;
• practitioner and maintainer reading paths; and
• links back to exact source files.

The first site does not use documentation versioning. Git tags and release records already preserve history, and frozen site versions would multiply maintenance before a named consumer requires them.

The site build may generate temporary content under its own ignored directory. Generated pages are never edited directly or treated as canonical.

The public reading interface is https://stage.zoshachi.com. After the private canonical repository's main quality workflow passes, its publication workflow checks out that exact revision, builds the static site, runs a bounded public-artifact safety screen, and replaces the dedicated public documentation repository's gh-pages branch with only generated output. Cloudflare Pages watches that public branch and serves it without access to canonical private source. See ADR 0062.

Public visibility applies to the generated reading interface. It does not change the source repository's visibility or transfer authority away from the canonical Git sources.

Trackers And External Knowledge Bases

Linear, Notion, or another service may later provide an attention view for Ready work, but it must not own architecture, vocabulary, source state, verification evidence, or human acceptance. Synchronization is justified only after repeated manual coordination cost is observed.

For the current solo-owner workflow:

• Git owns implementation and checkpoints;
• canonical repository documents own durable knowledge;
• Codex tasks own transient execution;
• Task Handoffs bridge unfinished task boundaries; and
• the Stage Director's Flow may own lightweight prioritization without a mandatory tracker.