Gessa Context for Codex

Operational guide for OpenAI Codex and CLI-style agents building in Gessa at engine version v1. Keep it tight: discover, build through canonical surfaces, prove before you claim done. For canonical tables, follow the links into the generated reference — do not rely on memory.

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

Operating loop

1. Discover first (read-only). Before any mutation, learn the live contract:
   • agent_get_project_context — handles/selectors for the current Project Graph (use this instead of dumping a full snapshot into context).
   • agent_get_semantic_operation_catalog — operations that lower into services.
   • engine_list_component_types, engine_get_component_schema — the ECS contract; read a component's fields before you set them.
   • engine_list_script_nodes, engine_list_script_patterns — the script surface.
   • The full tool list is in the MCP Tool Reference.
2. Prefer MCP + canonical actions. Build whole worlds with world.build.from_prompt / world.build.from_spatial_asset. Make targeted edits through cataloged project.* actions — for example project.world.create, project.entity.create, project.entity.component.set (see the Action Catalog). Generate assets with generation_quote_job then generation_create_job, polling generation_get_job.
3. Never hand-write full Script IR. Author behavior with Script Semantic Patch (project_apply_script_semantic_patch). project_create_script only yields an empty IR shell; the semantic compiler lowers operations into canonical IR. See Script Semantic Patch.
4. Require proof before claiming done. Renderability is not playability. Use qa_capture_observer_frame, qa_capture_renderer_viewport, and simulation_run. Accepting a playable world 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.

Hard rules

• Do not invent names. Components, actions, and MCP tools that are not in the generated reference or returned by a discovery tool do not exist at v1. There are 24 built-in ECS components; gameplay concepts such as health or damage are script patterns, not components.
• Do not mutate the raw Project Graph in normal paths. project_apply_transaction is a low-level escape hatch, not the authoring path.
• Do not write raw shader/pass fields. Reference cataloged renderer/material capability ids only; never send shaderSource, fragmentShader, wgsl, glsl, or customPassSource.
• Do not forward your MCP bearer token to any downstream tool or service.
• Do not synthesize proof receipts. If a capture is degraded, report it as degraded; missing proof is not_run, not pass.

When you are unsure

Ask the engine, not your memory. engine_get_engine_spec, engine_get_component_schema, engine_get_script_node, and agent_get_tool_contract return the live v1 contract. Cite the generated reference (Tier 2) for any fact you state, and prefer a discovery call over a guess.

See also: Claude Code guide, MCP tool use, Common failures and repairs.

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