1 files changed, 40 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bfc7ad9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,40 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `ocaml/` hosts the OCaml port; runtime modules live in `ocaml/lib/` (`noun.ml`, `nock.ml`, `serial.ml`, `state.ml`, `boot.ml`), tests in `ocaml/test/`, utility scripts in `ocaml/scripts/`.  
+- `vere/` is the production C runtime; reference `vere/pkg/noun` and related subsystems when matching behaviour or layout.  
+- `sword/` holds the Rust experiments (`sword/rust/`); use them for parity checks and implementation ideas when OCaml semantics feel unclear.
+
+## Build, Test, and Development Commands
+- `cd ocaml && dune build` — compile the OCaml port and dependencies.  
+- `cd ocaml && dune exec ./test_nock.exe` — run the focused opcode suite.  
+- `cd ocaml && dune runtest` — execute the full `ocaml/test/` matrix.  
+- `cd ocaml && dune exec ./bench_nock.exe` or `make bench` — benchmark against Vere baselines; prefer after changes that touch evaluator hot paths.  
+- `cd ocaml && make bench-c` — opt-in comparison against the C runtime (requires `vere/build` artifacts).
+
+## Coding Style & Naming Conventions
+- Keep the current OCaml style: two-space indentation, `snake_case` values, `CamelCase` modules, and doc-comments (`(** ... *)`) where APIs surface.  
+- Maintain feature parity with the C headers (e.g., `_n_nock_on` → `nock.ml`) and reuse existing aliases and record layouts.  
+- Avoid broad `open` statements; prefer explicit module references until a formatter (likely `dune fmt`) is agreed upon.
+
+## Testing Guidelines
+- Add targeted test executables under `ocaml/test/` when porting new behaviour; name them after the Vere feature being exercised (`test_hashcons.ml`, `test_parallel_clean.ml`).  
+- Compare outputs with the Vere runtime, log temporary deviations in `ocaml/STATUS.md`, and use `make bench` plus `ocaml/compare*.sh` to show performance parity when changing evaluator paths.
+
+## Commit & Pull Request Guidelines
+- Use short, imperative commit subjects that describe the observable change (`add`, `fix`, `align`).  
+- Reference affected subsystems (`nock`, `jets`, `runtime`) in either the subject or first line of the body.  
+- PRs should link the relevant Vere and Sword files, note parity considerations, list test commands run, and include artefacts (bench numbers, logs) when behaviour or performance shifts.
+
+## Current Progress & Next Steps
+
+- ✅ **Interpreters**: Rebuilt `noun` and `nock` modules from scratch; opcode test suite mirrors Sword’s expectations.  
+- ✅ **Serialization**: Bitstream utilities plus fresh jam/cue implementation; exhaustive tests ported from Sword (`test_jam_cue_*`, invalid encodings, random round-trips).  
+- ✅ **State & bootstrap scaffolding**: `state.ml` manages the Arvo core/event counter; `boot.ml` cues pills, runs the lifecycle formula `[2 [0 3] [0 2]]`, and stashes the ivory kernel.  
+- ✅ **Pill sanity**: Smoke tests confirm `cue ∘ jam` succeeds for `baby.pill` and `ivory.pill`.  
+
+- ⏳ **Up next**:
+  1. Finalise `%solid` replay: extract bot/mod/use events and feed them through `State.poke` using the real gate formula.  
+  2. Compare the ivory boot result (core digest, event counter) against Vere/Sword to confirm lifecycle parity.  
+  3. Introduce the event log (append/replay jammed events) so pill replay and runtime events share one pipeline.  
+  4. Once parity is verified, wire a minimal runtime loop and drivers around `State`.