Information Architecture

This page defines how Gessa documentation is organized. It applies the Diataxis framework to human product docs and adds a separate axis for AI-agent documentation. Every page mapped here is a Tier-3 hand-authored page that links down to Tier-2 generated reference; see the Documentation Contract Architecture for the three-tier model.

This is a scaffold-stage IA. The structure and page paths below describe the files that exist in the current v1 scaffold; the content of most pages is still a stub awaiting systematic authoring. Where a subsystem has no page yet, it is marked (planned).

Navigational Philosophy

Two audiences, two surfaces, one ground truth:

• Product docs teach humans. They live under docs/product/v1/ and follow Diataxis: a reader knows whether they want to learn, do a task, look something up, or understand a concept, and the IA routes them accordingly.
• AI-context docs orient agents. They live under docs/ai-context/v1/ and are concise and operational: what to call, what not to call, and what proof is required before claiming a world is playable.
• Both link down to Tier-2 generated reference. Neither surface restates a generated table. When a page needs the canonical ECS component list, Action Catalog verbs, or MCP tool inventory, it links to the relevant file under docs/spec/generated/ or docs/creator/mcp/.

The load-bearing product verbs — Spawn, Build, Play, Generate — anchor task-oriented pages. A "world" is a persistent stateful environment, not merely a renderable scene, and the frontend is a non-authoritative projection over backend authority; the IA keeps these framings consistent across every mode.

Diataxis: Product Documentation

The product landing page is docs/product/v1/index.md (H1: "Gessa Product Documentation (v1)"), and the shortest path from zero to a running world is docs/product/v1/start/quickstart.md. The four Diataxis modes map to subfolders of docs/product/v1/.

Tutorials (learning-oriented)

Guided, end-to-end lessons for a newcomer.

• docs/product/v1/tutorials/create-a-world.md — Spawn, Build, and Play a first world end to end.
• docs/product/v1/tutorials/create-a-playable-game.md — extend a world into a playable game that ends in a Play proof.

How-to (task-oriented)

Recipes for a reader who already knows the basics and has a specific goal.

• docs/product/v1/how-to/use-mcp-tools.md — drive Gessa from an MCP client; links to docs/creator/mcp/tool-reference.md.
• docs/product/v1/how-to/edit-components.md — edit ECS components through canonical authoring, not raw graph writes.
• docs/product/v1/how-to/write-gessascript.md — author behavior via Script Semantic Patch; links to docs/spec/generated/script-semantic-patch.md.
• docs/product/v1/how-to/publish-and-play.md — publish a world, then Play, reconnect, and reload.

Reference (information-oriented)

Thin orientation pages that point at Tier-2 generated reference. These never duplicate generated tables.

• docs/product/v1/reference/ecs-components.md -> docs/spec/generated/component-types.md
• docs/product/v1/reference/action-catalog.md -> docs/spec/generated/action-catalog.md
• docs/product/v1/reference/mcp-tools.md -> docs/creator/mcp/tool-reference.md
• docs/product/v1/reference/script-nodes.md -> docs/spec/generated/script-node-catalog.md, docs/spec/generated/script-sdk.md
• docs/product/v1/reference/runtime-playability.md -> runtime modules and the v1 readiness registries under docs/cycles/v1-engine-readiness-loop/

Dedicated reference pages for capabilities, the SDK surface, the World Build Contract, the renderer, and the Platform Catalog are (planned); until they exist, link directly to the Tier-2 generated files for those subsystems.

Explanation (understanding-oriented)

Conceptual pages that explain why the contracts are shaped the way they are.

• docs/product/v1/explanation/backend-authority.md — the frontend as a non-authoritative projection; one mutation authority.
• docs/product/v1/explanation/project-graph.md — the Project Graph as the authoritative world/resource model.
• docs/product/v1/explanation/script-ir-and-gessascript.md — Script IR as canonical behavior; source and visual graph as projections.
• docs/product/v1/explanation/playability-proofs.md — why proof gates exist and what playability proof means.

AI-Agent Documentation

A separate axis serves agents, not human learners. It lives under docs/ai-context/v1/ and is concise and operational. The index is docs/ai-context/v1/README.md (H1: "Gessa AI Context (v1)"), and the machine discovery entry point is docs/ai-context/v1/llms.txt (first line: "# Gessa").

The shared, client-agnostic context files:

• docs/ai-context/v1/llms.txt — llmstxt.org index: H1 title, blockquote summary, H2 link sections.
• docs/ai-context/v1/llms-full.md — expanded single-file context.
• docs/ai-context/v1/common-failures-and-repairs.md — runbook for renderer/runtime/MCP failures and their repairs.
• docs/ai-context/v1/ai-context-manifest.json — machine-readable manifest pinning the engine version and listing the context files.

Per-client orientation. The five intended agent audiences map onto the current files as follows:

Codex

• docs/ai-context/v1/codex.md — how OpenAI Codex-style agents should discover ECS components, author scripts semantically, and avoid raw Project Graph mutations.

Claude Code

• docs/ai-context/v1/claude-code.md — Claude Code operational guide; complements the generated MCP client guide docs/creator/mcp/claude-code.md.

MCP clients

• docs/ai-context/v1/mcp-tool-use.md — generic MCP-client orientation: what to call for world building, what not to call, safe MCP usage; links to docs/creator/mcp/tool-reference.md and docs/creator/mcp/security.md.

SDK users

• Currently folded into docs/ai-context/v1/mcp-tool-use.md and docs/ai-context/v1/llms-full.md, which point at docs/spec/generated/script-sdk.md. A dedicated sdk-users.md page is (planned).

Internal Gessa agents

• Currently folded into docs/ai-context/v1/common-failures-and-repairs.md and docs/ai-context/v1/llms-full.md: proof obligations before a playability claim, the readiness-ledger acceptance states, and the World Build Contract acceptance policy. A dedicated internal-agents.md page is (planned).

Directory Trees

Current docs/product/v1/:

docs/product/v1/
  index.md                      # H1: Gessa Product Documentation (v1)
  start/
    quickstart.md
  tutorials/
    create-a-world.md
    create-a-playable-game.md
  how-to/
    use-mcp-tools.md
    edit-components.md
    write-gessascript.md
    publish-and-play.md
  reference/
    ecs-components.md
    mcp-tools.md
    action-catalog.md
    script-nodes.md
    runtime-playability.md
  explanation/
    backend-authority.md
    project-graph.md
    script-ir-and-gessascript.md
    playability-proofs.md

Current docs/ai-context/v1/:

docs/ai-context/v1/
  README.md                     # H1: Gessa AI Context (v1)
  llms.txt                      # first line: # Gessa
  llms-full.md
  codex.md
  claude-code.md
  mcp-tool-use.md
  common-failures-and-repairs.md
  ai-context-manifest.json

Versioned Folders

The IA is versioned by engine version. Today only v1 exists, aligned to packages/engine-version (see the versioning model). Both axes follow folder-per-version: docs/product/v1/ and docs/ai-context/v1/. A future engine major opens docs/product/v2/ and docs/ai-context/v2/; do not pre-create them. Per-version URLs stay stable so a citation never breaks when the next major opens.

Status

This is a scaffold-stage Information Architecture. The folder structure, Diataxis mapping, AI-agent axis, and page paths are real and consistent with the Documentation Contract Architecture Subsystem Mapping. Most listed pages are stubs to be authored systematically by future agents; each must link down to its Tier-2 generated reference rather than restate it. Rows and pages marked (planned) do not exist yet and are candidates for the next authoring pass.