# AI Companion

> One file that briefs an AI model on writing Apogee guest programs. Download it, put it in front of your model, and it starts from the same rules this manual teaches.

Much of the code written against Apogee will be drafted by a model. A model that has never seen Apogee will write a plausible guest that uses `std`, allocates in every loop, reaches for an atomic counter, trusts its advice and commits a `usize`. The **AI Companion** is a single Markdown file that front-loads everything that prevents those mistakes: what a guest is, the hard rules, the SDK's complete public surface with exact signatures, patterns to copy, the errors and their fixes, and a review checklist.

[Download the companion](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md)
Copy to clipboard
[Open as text](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md)

## How to use it

- **In a chat:** attach the file, or paste it as the first message, before you describe what you want built.
- **In a coding agent:** save it at the root of your project under the name your tool reads by convention, such as `AGENTS.md` or `CLAUDE.md`, or add it to the tool's project rules. The agent then reads it at the start of every session.
- **For review:** ask the model to check a guest against section 8 of the file, the review checklist, line by line.

The file states its rules as **MUST** and **MUST NOT**, with the reason beside each, because models follow constraints that are explicit and explained more reliably than conventions they are expected to infer.

## What it contains

| Section | Contents |
| --- | --- |
| 0. Instructions to the model | Treat the rules as hard constraints; never call an API that is not listed; proofs are not zero-knowledge |
| 1. What a guest is | The target, the single hart, what a proof states, the program identity, the three memory regions |
| 2. Hard rules | 23 rules: program shape, 32-bit `usize` and pointers, the bump allocator, the stack, alignment, atomics, the absent outside world, advice, public-value limits, the instruction set, floats, overflow checks, cost |
| 3. Layout and build | The crate templates, the guest workspace, the build command, the host-first library split |
| 4. The guest SDK | Every public function with its exact signature, the runtime facts and memory map, the delegated operations and the vendored crates |
| 5. Patterns | Advice checked against a hash; a Merkle query and state transition; buffer reuse; structured advice; digests for growing outputs |
| 6. Host side | Running in the emulator, profiling, exporting the image, proving and verifying, heights and shards in flight |
| 7. Errors and fixes | Every exit status, fatal error and refusal a guest meets, with its cause and fix |
| 8. Review checklist | Eleven checks to run before proposing guest code |
| 9. Facts | The ISA, the proof system, the security level, the limits and the measured results |

## The rules it insists on

The companion repeats this manual's rules, and three of them deserve to be called out because models get them wrong most often:

- **Pointers and `usize` are 32 bits.** A model trained mostly on 64-bit code serializes `usize` without a second thought. The guest and the host then disagree on the bytes.
- **The heap never frees.** Idiomatic Rust allocates freely because a real allocator gives memory back. Here every allocation is permanent for the rest of the run, so the companion asks for reuse and `with_capacity` everywhere.
- **Atomics compile, and do not belong in new guest code.** They are supported for compatibility with existing libraries. On a single hart they synchronize nothing, and they add a circuit family to the proof.

## For agents reading these docs directly

- [`/llms.txt`](/llms.txt) indexes every page of this site in Markdown, for models that read the web.
- [`/docs/llms-full.txt`](https://apogee.gweb3networks.com/docs/llms-full.txt) is the whole English documentation, specification included, in one file.
- Every page has a **View as Markdown** link and a **Copy as Markdown** button, under its title and in the right-hand column.

English is the canonical language of the documentation, and the companion is published in English for every locale: it is the language models follow most reliably, and the one the specification is written in.