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 (ENGINE_VERSION currently reads v1.0.106). 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:checkand 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
These five rules hold for every client. The rest of the pack elaborates them.
- 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_transactionis 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.