Gessa AI Context (v1)

This folder is the operational context pack for AI agents: Codex, Claude Code, MCP clients, SDK callers, and internal Gessa agents, working against the Gessa engine at engine version v1. Everything here is pinned to v1: the contracts, tool names, and proof rules described match the packages/engine-version manifest for v1 (its ENGINE_VERSION constant carries the exact pin). When a future engine major opens, a sibling v2/ folder is created; this folder is never silently rewritten to describe new behavior.

These are Tier-3 hand-authored pages in the Documentation Contract Architecture: they orient and instruct, and they link to the Tier-2 generated reference for canonical tables, they never restate it. The canonical source of truth is always the code/registry (Tier 1), projected into the generated reference (Tier 2) under docs/spec/generated/ and docs/creator/mcp/.

How to use this pack

• Loading one file? Load llms-full.md: it is the single expanded orientation and links down to every catalog you need.
• Discovering the doc surface programmatically? Start from llms.txt, the llmstxt.org index.
• Driving the engine through a specific client? Read the matching per-client guide (codex.md, claude-code.md, mcp-tool-use.md), each is a short operating checklist on top of the shared model.
• Something failed? Go straight to common-failures-and-repairs.md.

What each file is for

• llms.txt: the llmstxt.org discovery index. Start here to find the product docs, this context pack, and the generated reference. Tight, link-only.
• llms-full.md: the expanded single-file orientation an agent loads wholesale: the three-tier model, the canonical world-build path, the do/don't list, the proof requirement, and where to recover from failures.
• codex.md: operational guide tuned for OpenAI Codex / CLI agents: the discover → build → prove loop and the hard rules.
• claude-code.md: operational guide for Claude Code / Claude agents, including the repo-aware gen-docs:check and contract gates that apply when you have the source tree.
• mcp-tool-use.md: how to use Gessa MCP safely: read-only discovery first, then mutate; token-handling and scope rules.
• common-failures-and-repairs.md: a runbook of known failure classes and their canonical repairs.
• ai-context-manifest.json: machine-readable manifest pinning engine v1 and listing the context files and the engine contracts they reference. This file is generated; do not hand-edit it.

Ground rules for every agent

• The frontend is a non-authoritative projection over backend authority. Treat backend acceptance and proof receipts as truth, not local UI state.
• A world is a persistent stateful environment, not merely a renderable scene. Renderability is not playability.
• Prefer MCP tools and canonical actions over raw Project Graph mutation. project_apply_transaction is a low-level escape hatch, not the authoring path.
• Author script behavior through Script Semantic Patch, never by hand-writing full Script IR.
• Never claim a world is playable without the required proof receipts. The v1 readiness ledger has zero accepted rows; describe the canonical flow, not a guarantee.

The three tiers, in one paragraph

Tier 1 is code (the engine packages and server modules). Tier 2 is the generated reference projected from Tier 1, machine-owned, hash-pinned, marked GENERATED FILE: do not edit by hand. Tier 3 is this prose, which links down to Tier 2 and never restates it. When you need a contract fact, prefer a live discovery tool (engine_list_*, engine_get_*) or the Tier-2 file over your own memory.

For the full architecture, see Documentation Contract Architecture, the Information Architecture, and the Gessa Product Documentation (v1) index.

Status: stable, index for the v1 AI-context pack, pinned to engine v1.