---
title: "Gessa AI Context (v1)"
description: "Index of the AI-agent context pack for engine v1, what each file is for, the three-tier source-of-truth model, and the ground rules every agent follows."
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/
---

# Gessa AI Context (v1)

This folder is the operational context pack for AI agents: Codex, Claude Code,
MCP clients, SDK callers, and internal Gessa agents, working against the Gessa
engine at **engine version v1**. Everything here is pinned to v1: the contracts,
tool names, and proof rules described match the [`packages/engine-version`](../../../packages/engine-version)
manifest for v1 (its `ENGINE_VERSION` constant carries the exact pin). When a future
engine major opens, a sibling `v2/` folder is created; this folder is never
silently rewritten to describe new behavior.

These are Tier-3 hand-authored pages in the
[Documentation Contract Architecture](../../docs-system/DOCUMENTATION_CONTRACT_ARCHITECTURE.md):
they orient and instruct, and they **link** to the Tier-2 generated reference for
canonical tables, they never restate it. The canonical source of truth is always
the code/registry (Tier 1), projected into the generated reference (Tier 2) under
[`docs/spec/generated/`](../../spec/generated/) and
[`docs/creator/mcp/`](../../creator/mcp/).

## How to use this pack

- **Loading one file?** Load [llms-full.md](./llms-full.md): it is the single
  expanded orientation and links down to every catalog you need.
- **Discovering the doc surface programmatically?** Start from
  [llms.txt](./llms.txt), the [llmstxt.org](https://llmstxt.org) index.
- **Driving the engine through a specific client?** Read the matching per-client
  guide ([codex.md](./codex.md), [claude-code.md](./claude-code.md),
  [mcp-tool-use.md](./mcp-tool-use.md)), each is a short operating checklist on
  top of the shared model.
- **Something failed?** Go straight to
  [common-failures-and-repairs.md](./common-failures-and-repairs.md).

## What each file is for

- **[llms.txt](./llms.txt)**: the [llmstxt.org](https://llmstxt.org) discovery
  index. Start here to find the product docs, this context pack, and the generated
  reference. Tight, link-only.
- **[llms-full.md](./llms-full.md)**: the expanded single-file orientation an
  agent loads wholesale: the three-tier model, the canonical world-build path, the
  do/don't list, the proof requirement, and where to recover from failures.
- **[codex.md](./codex.md)**: operational guide tuned for OpenAI Codex / CLI
  agents: the discover → build → prove loop and the hard rules.
- **[claude-code.md](./claude-code.md)**: operational guide for Claude Code /
  Claude agents, including the repo-aware `gen-docs:check` and contract gates that
  apply when you have the source tree.
- **[mcp-tool-use.md](./mcp-tool-use.md)**: how to use Gessa MCP safely:
  read-only discovery first, then mutate; token-handling and scope rules.
- **[common-failures-and-repairs.md](./common-failures-and-repairs.md)**: a
  runbook of known failure classes and their canonical repairs.
- **[ai-context-manifest.json](./ai-context-manifest.json)**: machine-readable
  manifest pinning engine v1 and listing the context files and the engine
  contracts they reference. This file is **generated**; do not hand-edit it.

## Ground rules for every agent

{% ai-context audience="any" priority="must" %}
These five rules hold for every client. The rest of the pack elaborates them.
{% /ai-context %}

- The frontend is a **non-authoritative projection** over backend authority.
  Treat backend acceptance and proof receipts as truth, not local UI state.
- A **world** is a persistent stateful environment, not merely a renderable scene.
  Renderability is not playability.
- Prefer **MCP tools and canonical actions** over raw Project Graph mutation.
  `project_apply_transaction` is a low-level escape hatch, not the authoring path.
- Author script behavior through **Script Semantic Patch**, never by hand-writing
  full Script IR.
- Never claim a world is playable without the required proof receipts. The v1
  readiness ledger has zero accepted rows; describe the canonical flow, not a
  guarantee.

## The three tiers, in one paragraph

**Tier 1 is code** (the engine packages and server modules). **Tier 2 is the
generated reference** projected from Tier 1, machine-owned, hash-pinned, marked
`GENERATED FILE: do not edit by hand.` **Tier 3 is this prose**, which links down
to Tier 2 and never restates it. When you need a contract fact, prefer a live
discovery tool (`engine_list_*`, `engine_get_*`) or the Tier-2 file over your own
memory.

For the full architecture, see
[Documentation Contract Architecture](../../docs-system/DOCUMENTATION_CONTRACT_ARCHITECTURE.md),
the [Information Architecture](../../docs-system/IA.md), and the
[Gessa Product Documentation (v1)](../../product/v1/index.md) index.

Status: stable, index for the v1 AI-context pack, pinned to engine v1.