---
title: "Gessa AI Context (Full, v1)"
description: "The expanded single-file orientation an AI agent loads wholesale before building in Gessa, three-tier model, canonical world-build path, semantic scripting, safe MCP, and the proof requirement, pinned to engine v1."
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/llms-full/
---

# Gessa AI Context (Full, v1)

This is the expanded, single-file orientation an AI agent can load wholesale
before building in Gessa. It pins **engine version v1**. It is concise and
operational, it tells you what to call, what not to call, and what proof you owe
before claiming a result. For canonical tables, follow the links into the
generated reference; this page never restates them.

If you only read one thing: **build through canonical actions and MCP tools, author
behavior through Script Semantic Patch, and never claim a world is playable
without proof receipts.**

## What Gessa is

Gessa builds **worlds**, persistent, stateful spatial-and-operational
environments, not throwaway renderable scenes. The product surfaces are **Spawn**
(describe what you want; the AI proposes a reviewable scene-graph diff), **Build**
(edit the world directly), **Play** (run it in an ephemeral preview session), and
**Generate** (produce assets). The frontend is a **non-authoritative projection**
over backend authority: backend acceptance and proof receipts are the truth, not
local UI state.

The engine has never launched. Everything here is `v1`, aligned to
[`packages/engine-version`](../../../packages/engine-version) (its `ENGINE_VERSION`
constant carries the exact pin). The [v1 readiness ledger](../../cycles/v1-engine-readiness-loop/)
has zero accepted rows, so this page describes the **canonical flow** whose
end-to-end runnable status tracks that ledger, it does not promise the flow runs
unattended today.

## The three-tier source-of-truth model

1. **Tier 1: Code / registry (truth).** Canonical contracts live in code:
   - [`packages/ecs`](../../../packages/ecs): ECS components.
   - [`packages/action-catalog`](../../../packages/action-catalog): verbs.
   - [`packages/capability-catalog`](../../../packages/capability-catalog) +
     runtime packs, capabilities.
   - [`server/src/modules/mcp/server.ts`](../../../server/src/modules/mcp/server.ts)
: MCP tools.
   - [`packages/script-semantic-patch`](../../../packages/script-semantic-patch): 
     semantic authoring.
   - [`packages/script-nodes`](../../../packages/script-nodes) +
     [`packages/script-codegen`](../../../packages/script-codegen): Script IR.
   - [`packages/script-sdk`](../../../packages/script-sdk): the script SDK.
   - [`packages/world-build-contract`](../../../packages/world-build-contract): 
     the World Build Contract.
   - [`packages/platform-catalog`](../../../packages/platform-catalog): the
     Platform Catalog.
   - [`packages/engine-version`](../../../packages/engine-version): the version
     manifest.
2. **Tier 2: Generated reference (derived projection).** Machine-citeable,
   header-marked `GENERATED FILE: do not edit by hand.`, produced by
   `scripts/gen-*-docs.ts` via `npm run gen-docs` and verified by
   `npm run gen-docs:check`. It lives under [`docs/spec/generated/`](../../spec/generated/)
   and [`docs/creator/mcp/`](../../creator/mcp/), and carries catalog versions and
   `sha256` hashes. **Cite this for any contract fact.**
3. **Tier 3: Hand-authored prose (this folder + product docs).** Orientation and
   instruction that links to Tier 2 and never duplicates it.

When you need a contract fact, prefer the live tool (`engine_list_*`,
`engine_get_*`) or the generated reference over your own memory. Nothing edits a
higher tier from a lower one.

## How to build a world (the canonical path)

{% recipe id="build-a-world" goal="Go from discovery to a proven world through canonical surfaces" audience="agent" %}
Discover the live contract, build through cataloged surfaces, author behavior
semantically, then capture proof before reporting the result.
{% /recipe %}

1. **Discover, don't guess.** Start with read-only discovery to learn the real
   contract surface:
   - `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 reach for
     `project_get_graph_snapshot` only for broad planning).
   - `world_build_get_operation_catalog`: the intent-level world-build operation
     algebra that lowers into Gessa services.
   - `engine_list_component_types` / `engine_get_component_schema`: the ECS
     contract.
   - `engine_list_script_nodes` / `engine_list_script_patterns`: the script
     surface.
   - `engine_get_engine_spec` / `engine_get_capability_graph`: the engine and
     capability surface.

   See the [MCP Tool Reference](../../creator/mcp/tool-reference.md) for the full
   list; it is grouped by surface prefix.
2. **Prefer prompt-to-world build for whole worlds.** `world.build.from_prompt`
   is the canonical action for prompt-to-world execution, and
   `world.build.from_spatial_asset` turns imported or generated spatial assets
   into executable worlds. MCP exposes `world_build_compile_semantic_operations`,
   `world_build_from_spatial_asset`, and `world_build_get_operation_catalog`. See
   the [World Build Contract](../../spec/generated/world-build-contract.md).
3. **Make targeted edits through canonical actions.** Create and modify Project
   Graph resources via the cataloged verbs, for example `project.world.create`,
   `project.entity.create`, and `project.entity.component.set`, surfaced as MCP
   `project_*` tools. See the [Action Catalog](../../spec/generated/action-catalog.md).
4. **Author behavior through Script Semantic Patch.** Apply
   `project.script.patch.apply` (MCP `project_apply_script_semantic_patch`). The
   backend compiler projects semantic operations into canonical Script IR and
   persists through the normal script update path. `project_create_script` only
   yields an empty IR shell; behavior comes from the patch, never from
   hand-written IR. See [Script Semantic Patch](../../spec/generated/script-semantic-patch.md).
   For source syntax and language-view editing rules, use the generated
   [Script source and language views](../../spec/generated/script-node-catalog.md#script-source-and-language-views).
5. **Generate assets through the generation actions.** `generation.job.quote`
   then `generation.job.create` (MCP `generation_quote_job`,
   `generation_create_job`); poll `generation_get_job` and cancel with
   `generation_cancel_job`. Import or generate spatial captures through the
   `spatial_*` tools, then feed them to `world_build_from_spatial_asset`.
6. **Prove it.** Capture observer/renderer frames and run the simulation before
   claiming the world is done (see [The proof requirement](#the-proof-requirement)).

## Discovering ECS components

The v1 engine ships a fixed set of **built-in atomic ECS components**; the current count, the canonical inventory, and the
field contract live in the generated
[Component Types](../../spec/generated/component-types.md) reference (catalog
contract hash and field-contract version are pinned there). Representative
built-ins include `TransformComponent`, `RigidBodyComponent`, `ColliderComponent`,
`CameraComponent`, `RenderableComponent`, `LightComponent`, and `ScriptComponent`.

Two rules keep you grounded:

- **Atomic only.** Under ADR 0020, gameplay patterns such as health, damage, spawn
  pools, collectors, and motion helpers are **script patterns**, not ECS atomics.
  If a name is not in the built-in inventory, it is not a built-in component: 
  treat it as a script pattern or project-defined data, or it does not exist.
- **Read the schema before you set it.** Use `engine_get_component_schema` (or the
  generated reference) to learn a component's fields before `project.entity.component.set`.
  Do not invent fields.

## Authoring behavior semantically

Script behavior is canonical **Script IR**, but IR is generated output, not a
hand-authoring surface. You author by applying **semantic operations** that the
backend compiler lowers into IR:

- The semantic operation alphabet is the generated [Script Semantic Patch](../../spec/generated/script-semantic-patch.md)
  reference, with the effect and typed-state contracts from
  `engine_get_script_effect_contract_catalog`; that is the algebra you express edits in.
- Apply edits with `project_apply_script_semantic_patch`; it checks the intent-level
  operations against your latest read (pass the current `irFingerprint`) and rejects a
  stale or invalid patch with a diagnostic. Typecheck the result with `script_typecheck`
  after applying.
- The [Script Node Catalog](../../spec/generated/script-node-catalog.md) and
  [Script SDK Surface](../../spec/generated/script-sdk.md) document the IR nodes
  and the TypeScript `ScriptContext` your script runs against, read them to
  understand the target, not to write IR by hand.

A semantic patch is a small, intent-level request, name the operation and its
parameters, not raw IR:

<!-- example:conceptual -->
```json
{
  "operations": [
    { "op": "<operation-id from the semantic patch catalog>", "params": { } }
  ]
}
```

The real operation ids and parameters come from the catalog; the shape above is
illustrative only.

## Do / Don't

**Do**

- Discover the live contract with read-only tools before mutating.
- Build worlds with `world.build.from_prompt` / `world.build.from_spatial_asset`.
- Make graph edits through cataloged `project.*` actions.
- Author behavior through Script Semantic Patch.
- Treat backend acceptance and proof receipts as the source of truth.
- Cite the generated reference (Tier 2) for any contract claim.

**Don't**

{% warning severity="critical" title="Do not mutate the Project Graph directly" %}
`project.transaction.apply` (`project_apply_transaction`) is a low-level,
workflow-exposure escape hatch, not the normal authoring path. Normal edits route
through cataloged `project.*` actions so they pass authority and validation.
{% /warning %}

- Don't hand-write full Script IR. `project_create_script` only yields an empty IR
  shell; behavior must come from Script Semantic Patch.
- Don't invent component, action, or MCP tool names. If it isn't in the generated
  reference or returned by a discovery tool, it doesn't exist at v1.
- Don't write raw shader/pass fields (`shaderSource`, `fragmentShader`, `wgsl`,
  `glsl`, `customPassSource`, …). Renderer/material choices must reference
  cataloged capability ids.
- Don't claim "playable" from a render alone: renderability is not playability.
- Don't forward your MCP bearer token to any downstream tool or service.

## The proof requirement

Renderability is **not** playability. Per the
[World Build Contract](../../spec/generated/world-build-contract.md) acceptance
policy:

- **Playable spatial-world acceptance** requires a collision proxy, a nav/query
  proxy, a semantic anchor, and `playability.accepted` receipts. Renderability
  alone is not playable proof.
- **Accepted build proof** additionally requires semantic-contract proof, Project
  Graph validation, visible unsupported requirements, passing QA receipts, and a
  timeline receipt.
- **Generated assets** may iterate through placeholders, but accepted final proof
  only permits `terminal_success`, `substituted`, or `degraded` asset receipts.
- **Missing proof is `not_run`, not pass.** Never synthesize a receipt.

{% proof class="playability" registry="docs/cycles/v1-engine-readiness-loop/PROOF_REGISTRY.json" status="unaccepted" %}
A playable world requires collision proxy, nav/query proxy, semantic anchor, and a
`playability.accepted` receipt. Every v1 readiness-ledger row is currently
unaccepted, so capture and report real receipts, do not assert playability.
{% /proof %}

Proof tooling you can call: `qa_capture_observer_frame`,
`qa_capture_renderer_viewport`, and `simulation_run`. If a capture is degraded,
report it as degraded, do not fabricate a passing receipt. The authoritative
readiness registries live under
[`docs/cycles/v1-engine-readiness-loop/`](../../cycles/v1-engine-readiness-loop/)
(`FEATURE_LEDGER.json`, `PROOF_REGISTRY.json`, `GUARDRAIL_REGISTRY.json`,
`MUTATION_AUTHORITY_REGISTRY.json`, `VERSION_REGISTRY.json`).

## Handling renderer and runtime failures

Failures are expected mid-build; the rule is to repair through a canonical surface,
never to paper over backend authority.

- **Degraded or failed capture.** `qa_capture_*` may return a degraded frame.
  Report it as degraded, re-run, or escalate, do not synthesize a passing
  receipt.
- **Accepted locally but not by the backend.** The frontend is a non-authoritative
  projection. Confirm acceptance and receipts from the backend before reporting
  success.
- **Raw-graph or raw-shader rejection.** Route the change through the matching
  `project.*` action or a cataloged renderer/material capability id.
- **Unknown name rejected.** Re-discover with `engine_list_component_types`,
  `engine_get_component_schema`, or the [MCP Tool Reference](../../creator/mcp/tool-reference.md)
  and use only names that appear there.

The [Common failures and repairs](./common-failures-and-repairs.md) runbook
expands each class with its canonical repair.

## Versioning

Docs version == engine version; today there is exactly **v1**, aligned to
[`packages/engine-version`](../../../packages/engine-version). A page pins the
contract snapshot it documents (catalog versions + `sha256` hashes), Stripe-style.
The engine has never launched; everything is version 1. Never write second-attempt
version spellings.

## Where to go next

- [AI Context README](./README.md): folder index and the five ground rules.
- [Codex guide](./codex.md) and [Claude Code guide](./claude-code.md): per-client
  operating loops.
- [MCP tool use](./mcp-tool-use.md): safe MCP usage and token rules.
- [Common failures and repairs](./common-failures-and-repairs.md): the runbook.
- [Documentation Contract Architecture](../../docs-system/DOCUMENTATION_CONTRACT_ARCHITECTURE.md)
 , the full model.

Status: stable, single-file v1 orientation, pinned to engine v1.