---
title: "Gessa Context for Codex"
description: "Operational guide for OpenAI Codex / CLI agents building in Gessa at engine v1, the discover, build, prove loop and the hard rules."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/ai/codex/
---

# 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](./llms-full.md) once for the full model. This page is the
short operational checklist.

## Operating loop

{% ai-context audience="codex" priority="must" %}
Run this loop in order on every task: discover read-only, build through canonical
surfaces, author behavior semantically, then capture proof. Skipping discovery is
the most common cause of invented names and rejected mutations.
{% /ai-context %}

1. **Discover first (read-only).** Before any mutation, learn the live contract:
   - `project_get_entity`, `project_get_component_definition`, `project_get_script`:
     read one Project Graph resource by handle (there is no compact-packet tool; pull
     narrowly instead of dumping a full snapshot into context, and use
     `project_get_graph_snapshot` only for broad planning).
   - `world_build_get_operation_catalog`: the intent-level world-build 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](../../creator/mcp/tool-reference.md).
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](../../spec/generated/action-catalog.md)). 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](../../spec/generated/script-semantic-patch.md).
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](../../spec/generated/world-build-contract.md)). 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. The
  built-in ECS components are enumerated in the generated component reference;
  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`, and `engine_get_script_node` return the live v1
contract; the [MCP Tool Reference](../../creator/mcp/tool-reference.md) (Tier 2)
carries each tool's canonical input schema. Cite the generated reference for any
fact you state, and prefer a discovery call over a guess.

See also: [Claude Code guide](./claude-code.md),
[MCP tool use](./mcp-tool-use.md),
[Common failures and repairs](./common-failures-and-repairs.md).

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