From e9e0e33c15d2bc76ffafb7f0ca86dd3913185f89 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 2 Jun 2026 04:48:35 +0000
Subject: [PATCH] docs: add AGENTS.md with Cursor Cloud development
 instructions

Co-authored-by: Kevan <kevan.burns@fthtrading.com>
---
 AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0666d35
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,53 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Product overview
+
+Genesis Protocol is a **Rust Cargo workspace** (13 crates). The primary runnable service is the **OaaS HTTP gateway** (`genesis-protocol` binary): background simulation ticks plus REST/SSE on port **3000**. Persistence is a JSON snapshot (`world_state.json`) in the process working directory.
+
+See `README.md` for experiment reproduction (`cargo run --release --bin run_experiments`) and `scripts/validate.sh` for deployment smoke checks.
+
+### Toolchain (non-obvious)
+
+- **Rust stable ≥ 1.96** is required: `Cargo.lock` pulls `getrandom` 0.4.x, which needs a recent toolchain. The image may ship an older default (e.g. 1.83); run `rustup default stable` and `source /usr/local/cargo/env` before building.
+- **System packages** (one-time on a fresh VM, not in the update script): `pkg-config`, `libssl-dev`, `build-essential` — needed for `openssl-sys` / `reqwest` native TLS.
+
+### Running the gateway locally
+
+After `cargo build --release`:
+
+```bash
+./target/release/genesis-protocol
+# or: cargo run --release --bin genesis-protocol
+```
+
+Binds `0.0.0.0:3000`. Optional `.env` from `.env.example` (Moltbook adapter only if `MOLTBOOK_API_KEY` is set).
+
+### Lint / test / build
+
+| Task | Command |
+|------|---------|
+| Build | `cargo build --release` |
+| Tests | `cargo test --workspace` (7 long-run tests in `tests/long_run_validation.rs` are `#[ignore]`) |
+| Lint | `cargo clippy --workspace --all-targets` (warnings only; no CI config in-repo) |
+
+### Smoke validation
+
+With the server listening on `localhost:3000`:
+
+```bash
+bash scripts/validate.sh hour0
+```
+
+`hour1`–`hour5` assume Docker container name `genesis-protocol` and optional Moltbook logs — skip those in pure local `cargo run` setups.
+
+### Optional components (out of scope for default dev)
+
+- **Docker**: `docker compose up` per `docker-compose.yml` (not required for local dev).
+- **papers/**: `cd papers && npm install && npm run build-pdf` (Puppeteer PDF).
+- **tts/**: `python tts/server.py` on port 8770 (FastAPI + Piper; separate Python deps).
+
+### Background processes in Cloud Agent VMs
+
+If `tmux` is unavailable, start the gateway with the release binary in the background and log to `/tmp/genesis-server.log`. Always pass `--bin genesis-protocol` when using `cargo run` (multiple binaries in the root package).