Markdoc Schema Plan

Gessa documentation is authored and rendered with Markdoc. Markdoc is a superset of Markdown, so every page is valid Markdown today, before any renderer exists. This page defines a small set of custom tags as scaffolding — schema, attributes, and intended render — for future agents to implement. We do not build a working renderer in this cycle.

There are exactly eleven planned custom tags: 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 /%}.

These tags exist to keep Tier-3 prose consistent with the three-tier source-of-truth model in the Documentation Contract Architecture: annotation tags carry contract semantics, and reference tags resolve to Tier-2 generated data instead of copying it.

Tag Schemas

contract

• Purpose: marks a block as a versioned product contract — a promise about engine behavior at a pinned version.

• Form: block.

• Attributes:

  Attribute	Type	Required	Description
  id	string	yes	Stable contract identifier (for cross-reference and citation).
  engineVersion	string	yes	Pinned engine version this contract describes (e.g. v1).
  status	string	no	Readiness status; should mirror a v1 readiness-ledger acceptance state.

• Intended render: a bordered contract callout with a version badge and an anchor on id, signaling "this is a guarantee, not a suggestion."

• Example:

  Contract · world.build.from_prompt · unaccepted
  Prompt-to-world build accepts a world spec and returns an executable world.
  

version

• Purpose: pins and displays the engine version coordinate a page or section documents.

• Form: self-closing.

• Attributes:

  Attribute	Type	Required	Description
  engineVersion	string	yes	The docs/engine version (e.g. v1).
  coordinate	string	no	A specific catalog coordinate from packages/engine-version.
  hash	string	no	The sha256 hash that immutably pins the coordinate.

• Intended render: an inline version pill, optionally linking to the pinned coordinate's generated source.

• Example:

  v1 · action-catalog.v1.ecs-contract-surface-closure
  

generated-reference

• Purpose: embeds a thin pointer to a Tier-2 generated file instead of restating its tables.

• Form: self-closing.

• Attributes:

  Attribute	Type	Required	Description
  file	string	yes	Repo-relative path to the Tier-2 generated file.
  anchor	string	no	Heading anchor within the generated file.
  label	string	no	Display label for the link.

• Intended render: a "Canonical reference" link card pointing at the generated file, with a note that the table is generated and must not be copied.

• Example:

  Canonical reference: ECS component inventory
  

proof

• Purpose: records the proof obligation or evidence backing a capability claim, tied to the v1 readiness registries.

• Form: block.

• Attributes:

  Attribute	Type	Required	Description
  class	string	yes	Proof class (e.g. playability, renderability).
  registry	string	no	Source registry, e.g. docs/cycles/v1-engine-readiness-loop/PROOF_REGISTRY.json.
  status	string	no	Whether the evidence is present, pending, or absent — or the readiness-row progress it mirrors (in_progress, unaccepted, planned).

• Intended render: an evidence callout listing the required proof and its current state.

• Example:

  Proof · playability · pending
  Requires collision proxy, nav/query proxy, semantic anchor, and a `playability.accepted` receipt.
  

warning

• Purpose: flags a caution, limitation, or footgun for the reader.

• Form: block.

• Attributes:

  Attribute	Type	Required	Description
  severity	string	no	info, caution, or critical.
  title	string	no	Short heading for the warning.

• Intended render: a colored admonition block keyed by severity.

• Example:

  Do not mutate the Project Graph directly
  Use the Action Catalog or semantic authoring; raw graph mutations bypass authority and validation.
  

ai-context

• Purpose: marks a block as agent-facing operational guidance (what to call, what to avoid).

• Form: block.

• Attributes:

  Attribute	Type	Required	Description
  audience	string	no	Target client, e.g. codex, claude-code, mcp, sdk, internal.
  priority	string	no	must, should, or avoid.

• Intended render: an agent-oriented callout, visually distinct from human prose, optionally filtered by audience.

• Example:

  AI · mcp · avoid
  Do not paste full project snapshots into context; call `agent_get_project_context` for a compact packet.
  

mcp-tool

• Purpose: references a single MCP tool from the generated MCP reference.

• Form: self-closing.

• Attributes:

  Attribute	Type	Required	Description
  name	string	yes	The MCP tool name (e.g. agent_get_project_context).
  file	string	no	Generated MCP reference path; defaults to docs/creator/mcp/tool-reference.md.

• Intended render: an inline tool chip linking to the tool's entry in the generated MCP reference.

• Example:

  agent_get_project_context
  

component

• Purpose: references a single ECS component from the generated component inventory.

• Form: self-closing.

• Attributes:

  Attribute	Type	Required	Description
  name	string	yes	The component type name (e.g. RigidBodyComponent).
  file	string	no	Generated reference path; defaults to docs/spec/generated/component-types.md.

• Intended render: an inline component chip linking to the component's row in the generated inventory.

• Example:

  RigidBodyComponent
  

action

• Purpose: references a single Action Catalog verb from the generated action reference.

• Form: self-closing.

• Attributes:

  Attribute	Type	Required	Description
  name	string	yes	The action id (e.g. project.world.create).
  file	string	no	Generated reference path; defaults to docs/spec/generated/action-catalog.md.

• Intended render: an inline action chip linking to the verb's row in the generated Action Catalog.

• Example:

  project.world.create
  

capability

• Purpose: references a single capability or capability pack from the generated capability reference.

• Form: self-closing.

• Attributes:

  Attribute	Type	Required	Description
  id	string	yes	The capability or pack id (e.g. physics.v1).
  file	string	no	Generated reference path; defaults to docs/spec/generated/capability-catalog.md.

• Intended render: an inline capability chip linking to the capability's entry in the generated capability reference or pack list.

• Example:

  physics.v1
  

recipe

• Purpose: marks a reusable, ordered task recipe (a how-to sequence) for humans or agents.

• Form: block.

• Attributes:

  Attribute	Type	Required	Description
  id	string	yes	Stable recipe identifier.
  goal	string	no	One-line statement of what the recipe accomplishes.
  audience	string	no	human, agent, or both.

• Intended render: a numbered recipe card with a goal header; pairs naturally with how-to pages.

• Example:

  Recipe · Turn a prompt into an executable world
  1. Submit the world spec via the World Build Contract.
  2. Validate against the Project Graph.
  3. Collect playability proof receipts before claiming the world is playable.
  

Tag Data Bindings

The eleven tags split into two groups by where their truth lives.

Tags that bind to Tier-2 generated data (these resolve identifiers against generated files and must point at the canonical reference rather than restate it):

• generated-reference -> any file under docs/spec/generated/ or docs/creator/mcp/.
• mcp-tool -> docs/creator/mcp/tool-reference.md.
• component -> docs/spec/generated/component-types.md.
• action -> docs/spec/generated/action-catalog.md.
• capability -> docs/spec/generated/capability-catalog.md and docs/spec/generated/capability-packs.md.

A future validation check can verify that every name/id referenced by these tags actually exists in the named generated file; see the Docs Validation Plan.

Tags that are pure prose annotations (no binding to generated data; they carry editorial/contract semantics only):

• contract, version, proof, warning, ai-context, recipe.

version and proof may reference pinned coordinates and registries by string, but they do not resolve a row in a generated catalog the way the binding tags do.

Implementation Plan

This cycle delivers schema scaffolding only. The plan:

• Define the ten tags as Markdoc tag schema objects (attribute types, required flags, allowed children) in a planned Markdoc config — a candidate home is a new packages/markdoc-schema or scripts/markdoc/ location that exports the tag definitions plus the attributes and render metadata above.
• Keep every page valid Markdown without a renderer. Because Markdoc is a Markdown superset, an unrendered {% ... %} tag degrades gracefully and a plain Markdown viewer still shows readable content.
• Do not build a full renderer in this cycle. The render descriptions above are intended behavior for a future renderer (likely in ~/rune_web or a docs export build step), not a deliverable now.
• When the renderer lands, the binding tags resolve against Tier-2 generated files at build time, so a stale component/action/capability/mcp-tool reference fails the build rather than silently misleading a reader.

Status

This is a scaffold. The eleven tags, their attributes, intended render, and data bindings are specified here for future implementation. No Markdoc renderer is built in this cycle, and pages remain valid Markdown. See the Documentation Contract Architecture for the three-tier model these tags enforce and the Docs Validation Plan for how tag references will eventually be checked against generated data.