Gessa

Gessa is an AI-native engine for building persistent, stateful spatial-and-operational worlds. Agents build by calling canonical actions and MCP tools — never by mutating the raw Project Graph or hand-writing script code. This index pins engine version v1.

Gessa worlds are authored through a layered contract: ECS components, the Action Catalog, MCP tools, and Script Semantic Patch. The frontend is a non-authoritative projection over backend authority; a world is playable only when the backend accepts the required proof receipts. Read the AI-context files below before building, treat the generated reference as ground truth, and verify any tool, action, or component name against it before you call it. The v1 readiness ledger has zero accepted rows, so describe the canonical flow rather than guaranteeing a capability.

AI Context

• AI Context README: index of this folder; what each file is for; the three-tier model; pins engine v1.
• Full AI context: single-file orientation — three-tier model, canonical world-build path, do/don't list, proof rule, failure recovery.
• Codex guide: operating loop and hard rules for OpenAI Codex / CLI agents.
• Claude Code guide: operating loop plus repo-aware gates (gen-docs:check, contract-freeze) for Claude Code / Claude agents.
• MCP tool use: safe MCP usage — read-only discovery first, then mutate; token and scope rules.
• Common failures and repairs: runbook of known failure classes and canonical repairs.
• AI context manifest: machine-readable manifest pinning v1 and listing context + contract files (generated; do not edit).

Docs

• Gessa Product Documentation (v1): hand-authored product docs index for engine v1 (Spawn, Build, Play, Generate).
• Quickstart: shortest path from zero to a running world.
• Documentation Contract Architecture: the three-tier source-of-truth model and contract rules.
• Information Architecture: how product and AI-context docs are organized.

Reference

• MCP Tool Reference: generated catalog of every MCP tool (185 entries) — the source of truth for tool names.
• Component Types: generated ECS component contract (24 built-in atomics; Tier 2, do not hand-edit).
• Action Catalog: generated canonical verb registry (64 actions) for mutating surfaces.
• Script Semantic Patch: generated catalog of semantic edit operations — the canonical way to author behavior.
• World Build Contract: generated prompt-to-world build contract and its proof/acceptance policy.
• Script Node Catalog: generated Script IR node catalog (generated output, not a hand-authoring surface).
• Script SDK Surface: generated TypeScript script SDK shape and ScriptContext surfaces.

Optional

• Capability Catalog: generated registry of versioned job/workflow powers.
• Capability Packs: generated runtime capability pack ids (for example physics.v1, rendering.v1).
• Platform Catalog: generated composite catalog of platform surfaces and coordinates.
• MCP Quickstart: how to connect an MCP client to Gessa.
• MCP Security: MCP auth and token-handling guidance.