--- title: "Information Architecture" description: "The Diataxis content structure for Gessa product docs plus the parallel AI-agent documentation axis, mapped to the real v1 page paths." engineVersion: v1.0.234 date: 2026-09-28 license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/." canonical: https://gessa.ai/docs/docs-system/IA/ --- # Information Architecture This page defines how Gessa documentation is organized. It applies the [Diataxis](https://diataxis.fr) 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](./DOCUMENTATION_CONTRACT_ARCHITECTURE.md) for the three-tier model. The folder structure, the Diataxis mapping, and the page paths below are real and present in the `v1` tree today; the depth of individual pages varies, and a subsystem with no page yet is marked _(planned)_. Every listed page links down to its Tier-2 generated reference rather than restating it. ## 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`](../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`](../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`](../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`](../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`](../product/v1/how-to/use-mcp-tools.md): drive Gessa from an MCP client; links to [`docs/creator/mcp/tool-reference.md`](../creator/mcp/tool-reference.md). - [`docs/product/v1/how-to/edit-components.md`](../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`](../product/v1/how-to/write-gessascript.md): author behavior via Script Semantic Patch; links to [`docs/spec/generated/script-semantic-patch.md`](../spec/generated/script-semantic-patch.md). - [`docs/product/v1/how-to/publish-and-play.md`](../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`](../product/v1/reference/ecs-components.md) points at [`docs/spec/generated/component-types.md`](../spec/generated/component-types.md) - [`docs/product/v1/reference/action-catalog.md`](../product/v1/reference/action-catalog.md) points at [`docs/spec/generated/action-catalog.md`](../spec/generated/action-catalog.md) - [`docs/product/v1/reference/mcp-tools.md`](../product/v1/reference/mcp-tools.md) points at [`docs/creator/mcp/tool-reference.md`](../creator/mcp/tool-reference.md) - [`docs/product/v1/reference/script-nodes.md`](../product/v1/reference/script-nodes.md) points at [`docs/spec/generated/script-node-catalog.md`](../spec/generated/script-node-catalog.md) and [`docs/spec/generated/script-sdk.md`](../spec/generated/script-sdk.md) - [`docs/product/v1/reference/runtime-playability.md`](../product/v1/reference/runtime-playability.md) points at 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`](../product/v1/explanation/backend-authority.md): the frontend as a non-authoritative projection; one mutation authority. - [`docs/product/v1/explanation/project-graph.md`](../product/v1/explanation/project-graph.md): the Project Graph as the authoritative world and resource model. - [`docs/product/v1/explanation/script-ir-and-gessascript.md`](../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`](../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`](../ai-context/v1/README.md) (H1: "Gessa AI Context (v1)"), and the machine discovery entry point is [`docs/ai-context/v1/llms.txt`](../ai-context/v1/llms.txt) (first line: "# Gessa"). The shared, client-agnostic context files: - [`docs/ai-context/v1/llms.txt`](../ai-context/v1/llms.txt): llmstxt.org index with an H1 title, a blockquote summary, and H2 link sections. - [`docs/ai-context/v1/llms-full.md`](../ai-context/v1/llms-full.md): expanded single-file context. - [`docs/ai-context/v1/common-failures-and-repairs.md`](../ai-context/v1/common-failures-and-repairs.md): runbook for renderer, runtime, and MCP failures and their repairs. - [`docs/ai-context/v1/ai-context-manifest.json`](../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`](../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`](../ai-context/v1/claude-code.md): Claude Code operational guide; complements the generated MCP client guide [`docs/creator/mcp/claude-code.md`](../creator/mcp/claude-code.md). ### MCP clients - [`docs/ai-context/v1/mcp-tool-use.md`](../ai-context/v1/mcp-tool-use.md): generic MCP-client orientation covering what to call for world building, what not to call, and safe MCP usage; links to [`docs/creator/mcp/tool-reference.md`](../creator/mcp/tool-reference.md) and [`docs/creator/mcp/security.md`](../creator/mcp/security.md). ### SDK users - Currently folded into [`docs/ai-context/v1/mcp-tool-use.md`](../ai-context/v1/mcp-tool-use.md) and [`docs/ai-context/v1/llms-full.md`](../ai-context/v1/llms-full.md), which point at [`docs/spec/generated/script-sdk.md`](../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`](../ai-context/v1/common-failures-and-repairs.md) and [`docs/ai-context/v1/llms-full.md`](../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](./DOCUMENTATION_CONTRACT_ARCHITECTURE.md#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 The folder structure, the Diataxis mapping, the AI-agent axis, and the page paths are real and consistent with the [Documentation Contract Architecture](./DOCUMENTATION_CONTRACT_ARCHITECTURE.md) Subsystem Mapping. Individual page depth varies and grows through systematic authoring; each page links down to its Tier-2 generated reference rather than restating it. Rows and pages marked _(planned)_ do not exist yet and are candidates for the next authoring pass.