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:
   • project_get_entity, project_get_component_definition, project_get_script for a targeted read (project_get_graph_snapshot reads the whole graph, not for targeted lookup); world_build_get_operation_catalog for the intent-level world-build operations.
   • 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. The built-in ECS components are enumerated in the generated component reference; 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.