Outcome

The documentation bundle helps a curious evaluator understand Superbee, a new user succeed without already knowing the product vocabulary, an active user complete recurring work, and a maintainer verify product behavior. It is readable public documentation and source-grounded knowledge that agents can evolve through reviewable changes.

This document governs documentation structure and maintenance. Product behavior remains governed by the product sources linked from each page.

Audiences and success conditions

Documentation should start from the reader's goal. Superbee vocabulary is introduced only when it helps the reader make or execute a decision.

House style

Write concise technical prose for a human reader:

• Name the subject, behavior, and result directly.

• Use a period, comma, colon, semicolon, or parentheses in place of an em dash.

• Replace rhetorical denial-then-correction patterns with a direct statement of the behavior that matters.

• Reserve terms such as exact, authority, boundary, and durable for cases where they name a verified identity, security rule, ownership rule, or persistence guarantee. Prefer the concrete component, scope, or behavior elsewhere.

• Keep commands, identifiers, schema terms, source citations, and compatibility constraints verbatim. Editorial simplification must preserve their technical meaning.

• Prefer one clear claim per sentence. Explain necessary safety distinctions without dramatizing them or narrating the review process.

The repository prose check enforces only objective signals: em dashes, a short banned-phrase list, and common rhetorical contrast templates. Human review remains responsible for clarity, tone, and technical fidelity in both rendered documentation outputs.

Content model and navigation

Internally, every reader-facing page has one primary mode:

• Tutorial: a safe, guided learning experience that produces a real result.

• How-to: a task-oriented procedure for a reader who already knows the desired outcome.

• Explanation: a mental model, boundary, or rationale that makes later decisions easier.

• Reference: exact facts organized for lookup.

These modes follow the distinct user needs described by Diataxis. They are an authoring classification, not the required names of the site's primary navigation. Releases and migrations are a navigation and product-lifecycle area: release facts are Reference, migration procedures are How-to, and design rationale is Explanation. Landing and map pages are structural navigation and do not need a content mode.

The public navigation uses conventional goal-oriented labels:

1. Get started: orientation, installation, setup, first bundle, and first persisted result.

2. Core concepts: bundles, documents, Kinds, recipes, relationships, Views, and trust.

3. Guides: preserve context, model a domain, coordinate work, present knowledge, share, and recover.

4. Integrations: supported agent hosts and installation or lifecycle differences.

5. Examples: complete, inspectable bundles and patterns grounded in real needs.

6. Reference: CLI, configuration, schemas, compatibility, security constraints, and errors.

7. Troubleshooting: symptom-first diagnosis and recovery.

8. Releases and migrations: verified versions, changes, actions, and compatibility windows.

9. Contributing and architecture: documentation maintenance and source-grounded system design.

Launch with a shallow subset that has real content: Get started, Core concepts, Guides, Reference, Releases and migrations, and Architecture and contributing. Promote Integrations and Examples to top-level navigation only when each has enough verified material to justify the space.

The first page offers two or three likely next actions. Section pages orient and route; they do not become long catalogs. Article pages expose related prerequisites, next actions, sources, and relevant visuals without making the raw bundle tree the primary interface.

Priority user journeys

The initial documentation is complete enough to launch only when a reader can perform these journeys without private knowledge:

1. Decide whether Superbee fits the work.

2. Install Superbee and complete host setup.

3. Create a greenfield bundle or safely join an existing one.

4. Preserve important context and retrieve it in a later session.

5. Recognize when an ordinary document, Kind, recipe, relationship, or View is warranted.

6. Present a document or View to a human.

7. Share and synchronize a bundle without confusing another bundle for the active project.

8. Diagnose common setup, resolution, validation, and View failures.

9. Upgrade or migrate using verified release guidance.

These are the task corpus for documentation review. Navigation labels and page counts are secondary to whether the journeys succeed.

Page contract

Every reader-facing page states, either explicitly or through its placement and introduction:

• the intended audience and outcome;

• one primary content mode;

• prerequisites and supported scope;

• the exact product or release evidence that governs material behavior claims;

• the tested package version or source commit when the behavior is version-sensitive;

• expected result and recovery guidance for procedures;

• related concepts, next actions, and relevant registered Views.

Additional expectations depend on the mode:

Examples must be runnable or clearly marked illustrative. Commands are copied from current help or verified installed-package behavior, not reconstructed from memory. Claims such as supported, secure, deterministic, compatible, or complete require corresponding evidence.

Sources and authority

Each maintained page names its authoritative source class:

• source and tests for product semantics;

• generated CLI help and packed-package probes for command behavior;

• schemas for accepted structure;

• installed-host probes for host compatibility;

• npm and GitHub release receipts for released state;

• reviewed product decisions for declared policy.

Evidence links and version pins live visibly in the page or a linked Source document. Operational Documentation Trigger records relate maintained pages to source paths and named product events. They are ordinary public bundle documents, so agents and public inspection tools can query them without forcing maintenance instructions into reader prose. Private material may inform a separately reviewed public explanation but is never copied into this bundle.

Generated reference is authoritative only for the exact facts its generator can prove, such as command syntax, options, defaults, output fields, or schemas. Authored pages own task framing, explanation, examples, limitations, and recovery. Generated text must not overwrite authored prose, and authored prose must not duplicate generated facts where a stable link or projection will do.

Page freshness

Page freshness is computed by the publication workflow, not typed into prose or frontmatter for display. Last updated means the document's OKF meaningful-change clock (generated.at, with the legacy timestamp fallback) when present. Otherwise it is the commit time of the exact clean, tracked document source in the repository's full Git history. The fact is bound to that document's source version before entering the shared documentation projection, so unchanged inputs rebuild to the same output. Dirty files, untracked files, shallow history, and other unknown sources emit no date.

Last verified is a different claim. It may be published only when an independent immutable verification input exists; an evidence-only verification must not change Last updated. Product release applicability remains the configured version label and is not inferred from either date. Portal and MkDocs render the same available facts with native, accessible <time> elements and omit missing facts.

Lifecycle

The persisted lifecycle is deliberately small:

1. Current: the page passed its evidence, link, task, and publication checks for its stated version or scope.

2. Needs review: a declared trigger changed or evidence is no longer sufficient; the limitation is visible until the page is re-verified.

3. Retired: the page no longer earns maintenance and identifies its replacement or historical scope.

Planned belongs in the coverage plan. A branch or pull request is the draft and review state; the bundle does not need duplicate workflow records. After several real pages prove which fields and transitions recur, the bundle may promote the stable shape into Kinds. Until then, the coverage plan is the one planning projection and Git history is the audit trail.

Operational documentation records

Documentation Trigger records live under maintenance/documentation-triggers/. Each record names its affected page, exact source-path patterns or product events, the required review action, and the governing evidence. They remain generic OKF documents until repeated authoring demonstrates that a Kind would reduce real maintenance effort.

The documentation profile declares Documentation Trigger in operationalTypes. The complete Portal publication therefore retains every trigger under its raw bundle route, while the shared documentation projection rejects any attempt to select one as navigation or supporting content. This is a presentation rule, not an authorization or privacy boundary.

Run npm run docs:impact:check to validate the records and their affected-page links. For a product change, run npm run docs:impact -- --changed <source-path> and add repeatable --changed or --event arguments as needed. Review every returned page and either update it or record why the verified behavior did not change.

Operational moments

Stable current-release identities

Reader navigation and maintained pages link to releases/current and sources/current-release, not to a package-version path. Each verified release also creates immutable releases/<version> and sources/superbee-release-<version> records. The stable documents are semantic copies of those immutable records, so history remains inspectable while ordinary pages avoid mechanical version churn.

The release process passes an ephemeral, validated JSON handoff to:

npm run docs:release -- --manifest <release.json>

The input is transport, not a persisted documentation authority. The command normalizes and writes the four bundle documents through Superbee, refuses to replace immutable history, and is idempotent when retried. npm run docs:release:check verifies stable-to-immutable agreement, stable Portal navigation, and the absence of hardcoded Superbee package versions outside release, evidence, or migration records. Authored behavioral claims still require the declared release verification; automation never promotes an unverified version merely by changing a number.

An agent run ends with a durable update to the relevant page or plan, the evidence examined, checks run, and unresolved questions. Private chat is not the handoff mechanism.

Multi-agent coordination

• One agent owns one bounded page or tightly coupled page set at a time.

• The coverage plan is the shared queue; an active branch or pull request is the observable claim on a page brief during the pilot.

• Research agents return source identities and claim-level findings, not ungrounded prose for direct publication.

• Authors integrate evidence and maintain narrative coherence.

• Reviewers audit the exact page against its sources and journey; site reviewers test the rendered experience using the settled product semantics.

• Navigation and synthesis pages are reduced only after their contributing pages stabilize.

Site and bundle boundary

The bundle owns documents, relationships, evidence links, registered Views, and the information architecture. One captured Superbee publication snapshot and one explicit, owned documentation projection bind the selected documents, navigation, relationships, brand asset, and admitted static diagrams before any output adapter runs. Portal owns its deterministic publication artifact, integrity and View-admission boundaries, browser primitives, and deployment adapters. The Portal documentation client owns routing, layout, navigation rendering, search presentation, and responsive behavior. The separate MkDocs adapter owns only its conventional static-site materialization. Both consume the same closed projection and generated bytes remain projections, never competing content authorities.

The entire public bundle remains inspectable. The primary UI may emphasize a curated subset and human navigation without hiding the underlying documents.

Stopping rule

Do not introduce a Kind, generated index, claim registry, content metric, or maintenance job unless it removes observed authoring, review, release, or reader effort. The next milestone is a verified representative vertical slice, not a comprehensive documentation bureaucracy.