Gessa Context for Claude Code

Operational guide for Claude Code and Claude agents building in Gessa at engine version v1 — whether working directly in this repo or driving the engine through MCP. It mirrors the Codex guide and adds the repo-aware workflows (generated-docs and contract gates) that apply when you have the source tree.

Read llms-full.md once for the full model. This page is the short operational checklist plus the repo gates.

Operating loop

1. Discover first (read-only). Learn the live contract before mutating:
   • agent_get_project_context, agent_get_semantic_operation_catalog.
   • engine_list_component_types / engine_get_component_schema — read fields before you set them.
   • engine_list_script_nodes / engine_list_script_patterns.
   • Full list: the MCP Tool Reference.
2. Prefer MCP + canonical actions. Build worlds with world.build.from_prompt / world.build.from_spatial_asset; edit through cataloged project.* actions — project.world.create, project.entity.create, project.entity.component.set (see the Action Catalog); generate assets via generation_quote_job then generation_create_job.
3. Never hand-write full Script IR. Author behavior with Script Semantic Patch (project_apply_script_semantic_patch); project_create_script yields only an empty IR shell. See Script Semantic Patch.
4. Require proof before claiming done. Use qa_capture_observer_frame, qa_capture_renderer_viewport, simulation_run. Playable acceptance needs a collision proxy, a nav/query proxy, a semantic anchor, and playability.accepted receipts (see the World Build Contract). Missing proof is not_run, not pass — never synthesize a receipt.

Repo-aware workflows (when you have the source tree)

• Generated reference is Tier 2 — never hand-edit it. Files under docs/spec/generated/ and docs/creator/mcp/ carry the header GENERATED FILE: do not edit by hand. To change them, change the Tier-1 source and regenerate with npm run gen-docs; verify with npm run gen-docs:check (which is part of the global npm run check).
• Respect the gates. Documentation is guarded like code. The docs guards run via npm run check:docs — check:docs-contract-scaffold (structure), check:docs-links (every relative link resolves), check:docs-markdoc (every prose Markdoc tag is well-formed and resolves to its generated reference), check:docs-examples (every ts/tsx/js/json example carries a conceptual or verbatim marker), and check:docs-claims (no page asserts an unaccepted capability). Engine contracts are guarded by npm run check:contract-freeze (with contracts:bump), npm run check:version-coordinates, and the forbidden vocabulary gate npm run check:no-2d-references. Run the relevant check:* gates before relying on a contract claim or considering a change complete.
• Edit hand-authored prose in place at v1. Tier-3 pages (this folder and docs/product/v1/) link to Tier-2 generated tables and must not restate them.
• Cross-reference, do not duplicate. When a page needs a canonical table, link to the generated file rather than copying it. Copying a generated table creates a second, un-versioned source of truth that silently rots.

Hard rules

• Do not invent component, action, or MCP tool names — if it is not in the generated reference or a discovery tool's output, it does not exist at v1. There are 24 built-in ECS components; gameplay concepts are script patterns, not components.
• Do not mutate the raw Project Graph in normal paths; project_apply_transaction is a low-level escape hatch.
• Do not write raw shader/pass fields; reference cataloged capability ids.
• Do not forward your MCP bearer token to downstream tools or services.
• Do not synthesize proof; report degraded captures as degraded.

See also: Codex guide, MCP tool use, Common failures and repairs, Documentation Contract Architecture.

Status: stable — v1 Claude Code operating guide, pinned to engine v1.