Documentation Contract Architecture

This document defines how Gessa's documentation is produced, versioned, and validated. It is the spine of the documentation contract system: every other docs-system page, every generated reference, and every hand-authored product page derives its rules from here.

This is the first version of the documentation contract system. It establishes structure, source-of-truth rules, and the scaffolding for authoring and validation. It is architecture, not a finished documentation set. Pages that are stubs say so explicitly.

Docs as Contract

A Gessa documentation page is a product contract: it states what the engine guarantees at a pinned engine version. Documentation is not aspirational marketing copy and it is not a changelog of intentions — it is a promise about observable engine behavior, scoped to a specific contract snapshot.

Three consequences follow from treating docs as contracts:

1. The engine repo owns the authoritative source. Canonical contracts live in the repository identified by GESSA_ENGINE_REPO. Documentation is downstream of code, never the reverse.
2. A page must not claim a capability the engine has not accepted. The v1 engine-readiness ledger (docs/cycles/v1-engine-readiness-loop/FEATURE_LEDGER.json) is the acceptance authority. A page that asserts a capability whose ledger row is not in an accepting status is making a false contract. See Docs Validation Plan.
3. Every contract page pins a version. A page declares which engine contract snapshot it documents, so a reader (human or generative engine) can cite an immutable coordinate rather than a moving target.

The engine has never launched. Everything described today is v1, and the docs system is built so that the very first published contract is already version-pinned and drift-guarded.

Source-of-Truth Rules

Documentation follows a strict three-tier source-of-truth model. Each tier has one job, and content never flows upward.

Tier 1 — CODE/REGISTRY is the source of truth. Canonical contracts live in code:

• ECS components: packages/ecs
• Action Catalog verbs: packages/action-catalog
• Capability Registry: packages/capability-catalog + runtime capability packs
• MCP tools: server/src/modules/mcp/server.ts
• SDK: the script SDK source (packages/script-sdk)
• Script IR / GessaScript: packages/script-nodes + packages/script-codegen + the Script IR
• Semantic authoring: packages/script-semantic-patch
• World Build Contract: packages/world-build-contract
• Platform Catalog: packages/platform-catalog
• Runtime: server runtime modules (server/src/modules/runtime)
• Renderer: renderer modules + renderer visual profile (packages/renderer-visual-profiles)
• Version manifest / catalog hashes: packages/engine-version

Tier 2 — GENERATED REFERENCE is a derived projection of Tier 1, never hand-edited. It carries the header comment GENERATED FILE: do not edit by hand. and lives under docs/spec/generated/ and docs/creator/mcp/. It is produced by scripts/gen-*-docs.ts via npm run gen-docs and verified by npm run gen-docs:check.

Tier 3 — HAND-AUTHORED PROSE is reviewed instructional and explanatory content under docs/product/v<n>/ and docs/ai-context/v<n>/. It must link to Tier 2 for canonical tables and must not restate or duplicate generated content. Reference pages are thin pointers plus orientation, not copies of the generated tables.

The cardinal rule: Tier 3 links down to Tier 2; Tier 2 is regenerated from Tier 1; nothing edits a higher tier from a lower one.

Generated vs Hand-Authored Content Rules

The boundary between Tier 2 and Tier 3 is enforced, not advisory.

• Generated (Tier 2) files are machine-owned. They begin with <!-- GENERATED FILE: do not edit by hand. --> and <!-- Regenerate with \npm run gen-docs`. -->. Each names its Sources:(the exact Tier-1 code paths) and carries catalog versions andsha256hashes. Do not hand-edit them; change the code, then regenerate.npm run gen-docs:check` fails CI if a generated file drifts from its source.
• Hand-authored (Tier 3) files are human-owned prose. They teach, explain, and orient. When a Tier-3 page needs a canonical fact — the list of ECS components, the Action Catalog verbs, the MCP tool inventory — it links to the Tier-2 file rather than copying the table. Copying a generated table into prose creates a second, un-versioned source of truth that silently rots.
• One fact, one home. If a fact is in a generated table, the prose page references it. If a fact is genuinely editorial (a tutorial's narrative, an explanation of why a contract exists), it lives only in prose and is never generated.

Versioning Model

Docs version == engine version. Today there is exactly one: v1, aligned to packages/engine-version (ENGINE_VERSION currently reads v1.0.106; ENGINE_VERSION_MAJOR is 1). The engine has never launched.

The model is folder-per-version, in the style of Docusaurus versioning:

• docs/product/v1/ — hand-authored product documentation for engine v1.
• docs/ai-context/v1/ — AI-agent context for engine v1.

A future engine major opens v2/. Do not pre-create it.

A docs version pins engine manifest coordinates — catalog versions plus sha256 hashes from packages/engine-version and the generated reference headers — so a page declares which contract snapshot it documents. This is Stripe-style version pinning: a page is anchored to immutable coordinates, not to "latest."

Pre-launch, v1 content is edited in place. Post-launch, an accepted behavior change goes through the contract-freeze gate (npm run check:contract-freeze, with npm run contracts:bump to advance coordinates) and may open a new docs version. Never silently rewrite a pinned version to describe new behavior — that breaks the contract promise for anyone who cited the old coordinate.

Note on spelling: the engine has launched zero times, so every coordinate reads version 1. Documentation never uses second-attempt spellings for engine majors; check:version-coordinates guards this.

Markdoc Strategy

Authoring and rendering use Markdoc. Markdoc is a superset of Markdown, so every page is valid Markdown today, before any renderer exists. We define a small set of custom tags as scaffolding — schema, attributes, and intended render — not a working renderer in this cycle.

The eleven planned custom tags are exactly: contract, version, generated-reference, proof, warning, ai-context, mcp-tool, component, action, capability, recipe. Block tags use {% tag attr="value" %} ... {% /tag %}; self-closing tags use {% tag /%}.

Some tags are pure prose annotations; others point at Tier-2 generated data (for example component, action, capability, mcp-tool, and generated-reference resolve to entries in generated files). Full schema, attribute tables, intended render, and the map of which tags bind to generated data are defined in the Markdoc Schema Plan.

rune_web Consumption Model

The marketing/web repository ~/rune_web (sibling to this engine repo) is a consumer, never a source of truth for engine contracts.

• ~/rune_web consumes a published, version-pinned docs artifact: the generated Tier-2 bundle plus curated Tier-3 pages, exported through a future one-way export build step.
• The export boundary is one-directional. ~/rune_web renders and presents; it never edits and never owns engine contracts. It treats the engine repo's published version as immutable input.
• No engine contract source ever moves to ~/rune_web. The engine repo owns content and version pinning; ~/rune_web owns the eventual public sitemap and canonical tags for the rendered site.

If a future need arises to change a contract fact, the change happens in Tier 1 in this repo, regenerates Tier 2, republishes the pinned artifact, and only then does ~/rune_web see it.

AI-Context Strategy

Alongside human product docs, Gessa publishes a dedicated AI-agent context axis so that coding agents and MCP clients can build worlds correctly without dumping the whole engine into a model's context window.

The AI-context surface provides: an llms.txt index (per the llmstxt.org standard), an expanded llms-full.md, per-client operational guides (Codex, Claude Code, and MCP clients), a common-failures-and-repairs runbook, and a machine-readable ai-context-manifest.json that pins the engine version and lists the context files. SDK-user and internal-agent guidance is currently folded into the shared context files; dedicated per-client pages for them are candidate future additions.

AI docs are concise and operational: what to call for world building, what not to call, how to discover ECS components, how to use semantic script authoring, how to use MCP safely, how to avoid raw Project Graph mutations, what proof is required before claiming a world is playable, and how to handle renderer/runtime failures. The full layout lives in Gessa AI Context (v1); its validation rules are in the Docs Validation Plan.

SEO / GEO / Parsability Strategy

Documentation is built to be citeable by humans, search engines, and generative engines (GEO = Generative Engine Optimization).

• Stable per-version URLs. docs/product/v1/... and docs/ai-context/v1/... give every fact a durable address that does not move when v2 opens.
• Semantic heading hierarchy. One H1 per page, descending H2/H3 that mirror the contract's structure.
• Front-matter metadata. Each page carries title, description, engineVersion, and canonical.
• llms.txt for AI discovery. The AI-context index follows the llmstxt.org standard so agents can find the right context file quickly.
• Generated reference as machine-citeable ground truth. Tier-2 files carry catalog versions and sha256 hashes, giving generative engines immutable coordinates to cite.
• Hash-pinned facts. Because Tier-2 facts are hash-pinned to packages/engine-version, a citation can name an exact contract snapshot rather than a moving "current" claim.

~/rune_web owns the eventual public sitemap and canonical tags for the rendered site; the engine repo owns the content and the version pinning that those tags point at.

Docs Validation and Drift-Guard Model

Documentation is guarded the same way code is: deterministic, file-walking checks that exit non-zero with findings.

Today, exactly two guards are wired:

• Generated-docs drift via npm run gen-docs:check — regenerates each Tier-2 file and fails if the committed output differs from its Tier-1 source.
• Scaffold existence via npm run check:docs-contract-scaffold — a structural stub guard that verifies the docs-system scaffolding (these files and the expected v1 folders and H1 titles) exists. It is deliberately not in the global npm run check yet, because it guards structure rather than behavior.

Future guards — MCP docs vs executable tools, action docs vs the Action Catalog, ECS docs vs the component contract, SDK docs vs generated SDK, AI-context manifest hashes, example-compilation, and a public-claims gate tied to the v1 readiness ledger acceptance states — are specified in the Docs Validation Plan.

Subsystem Mapping

Each subsystem has exactly one Tier-1 canonical owner in code, one generator script, one Tier-2 generated reference, and a planned Tier-3 product page that links down to the generated reference. This table is the authoritative generator-to-file map.

The Tier-3 column lists the product pages that exist in the current v1 scaffold (mapped in the Information Architecture); rows marked (planned) have no scaffold page yet and are candidates for systematic authoring. Every Tier-3 page links down to the Tier-2 file in the same row and never restates its tables.

Status

This is the first version of the Gessa documentation contract system: scaffolding and architecture, not a finished docs set. The three-tier model, the versioning model, and the generator-to-file map are real and enforced by gen-docs:check. The Markdoc tag set and most validation guards are specified here and in the sibling docs-system pages as scaffolds for future agents to implement systematically. When in doubt, describe the contract rule, not a capability guarantee.

See also: Information Architecture, Markdoc Schema Plan, Docs Validation Plan.