Add CONTRIBUTING.md + review doc

- Created CONTRIBUTING.md with repo-specific build/test/contribute guidance
- (constraint-theory-core: existing CONTRIBUTING.md verified, review doc only)
- Added review document explaining what was missing and why

Author: Cocapn Fleet

CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to MUD Arena
+
+> *"The game plays itself. The agent coaches from the sidelines. The GPU runs the plays."*
+
+## Quick Start
+
+MUD Arena uses multiple build targets depending on your hardware:
+
+### GPU Build (CUDA, recommended)
+```bash
+make gpu
+```
+
+### CPU Build
+```bash
+make cpu
+```
+
+### Zig Build (ARM64 / x86_64)
+```bash
+# x86_64 dev machine
+zig build -Doptimize=ReleaseSmall
+
+# ARM64 (Jetson, Pi)
+zig build -Dtarget=aarch64-linux -Doptimize=ReleaseSmall
+
+# WASM (browser)
+emcc -O3 -s WASM=1 src/wasm_mud.c
+```
+
+### Run Evolution
+```bash
+python3 src/evolve.py --generations 100 --population 200 --scenarios 20
+```
+
+### Docker
+```bash
+docker build -t mud-arena .
+docker run --gpus all mud-arena
+```
+
+## Making Changes
+
+1. **Read the Charter** — Start with `CHARTER.md` and `BOARDING-MANIFESTO.md` to understand the vision
+2. **Fork the repo**
+3. **Create a feature branch** (`git checkout -b feature/my-feature`)
+4. **Make your changes** — CUDA kernels go in `src/mud_arena.cu`, Zig in `src/mud_arena.zig`, Python scripts in `src/`
+5. **Test your changes** (see Testing section below)
+6. **Commit** (`git commit -m "feat: add my feature"`)
+7. **Push** (`git push origin feature/my-feature`)
+8. **Open a PR**
+
+## Code Style
+
+### CUDA
+- Follow standard CUDA best practices (coalesced memory access, bank conflict avoidance)
+- Thread = agent, block = room — maintain this abstraction
+- Use `__shared__` memory for room-level state
+- Document kernel launch parameters (grid, block dims)
+
+### Zig
+- Run `zig fmt` before committing
+- Follow Zig standard naming conventions
+- Binary must be <100KB target size
+
+### Python
+- Use `make lint` or `ruff check src/`
+- Type hints required for all public functions
+- Document in Google-style docstrings
+
+## Testing
+
+### CUDA Kernels
+- Tests are in `src/tests/` — run via `make test`
+- Verify correctness vs CPU reference implementation
+- Benchmark performance across hardware targets
+
+### Python
+```bash
+# Run Python tests
+make test-py
+# or
+python3 -m pytest tests/
+```
+
+### Evolution
+Test a short evolution run before committing:
+```bash
+python3 src/evolve.py --generations 10 --population 20 --scenarios 5
+```
+
+## Boarding Manifesto
+
+Before contributing architecture decisions, read `BOARDING-MANIFESTO.md`. It describes the vision:
+- MUD runs on any device (Pi, Jetson, ESP32)
+- Humans board via SSH, brief agents, then beam off
+- Agents execute autonomously with battery awareness
+- Comm resolution drops with distance — agents must work disconnected
+
+This isn't just a codebase. It's a holodeck running at GPU speed.
+
+## Hardware Targets
+
+| Hardware | Threads | Scenarios/sec | Build Target |
+|----------|---------|--------------|-------------|
+| Jetson Orin Nano | 1,024 | ~10,000 | `zig build -Dtarget=aarch64-linux` |
+| RTX 4090 | 16,384 | ~100,000 | `make gpu` |
+| A100 | 69,120 | ~500,000 | `make gpu` |
+| Pi 5 (CPU) | 4 | ~100 | `zig build` or `make cpu` |
+
+Contributions that optimize for specific hardware targets are welcome.
+
+## Reporting Issues
+
+Open an [Issue](https://github.com/SuperInstance/mud-arena/issues) with:
+- Hardware specs (GPU model, RAM, OS)
+- Build target being used
+- Reproduction steps
+
+## Questions?
+
+- Open a [Discussion](https://github.com/SuperInstance/mud-arena/discussions)
+- Read the [Charter](CHARTER.md)
+- Read the [Boarding Manifesto](BOARDING-MANIFESTO.md)
+- Check existing [Issues](https://github.com/SuperInstance/mud-arena/issues)

reviews/2026-05-17-contributing-added.md

@@ -0,0 +1,31 @@
+# CONTRIBUTING.md Added — MUD Arena
+
+**Date:** 2026-05-17
+**Action:** Created `CONTRIBUTING.md`
+
+## Why This Repo Needed It
+
+MUD Arena is the gold-standard README in the SuperInstance org, but it had zero contribution guidance. Despite having an excellent README, BUILD.md, BOARDING-MANIFESTO.md, and CHARTER.md, there was no single place telling a new developer:
+
+- How to set up a dev environment
+- What build targets are available (Zig, CUDA, CPU, WASM, Docker)
+- What coding standards to follow
+- How to write tests
+- How to propose changes
+
+New contributors had to piece together guidance from multiple files. The CONTRIBUTING.md now serves as the single entry point for development workflow.
+
+## What the Contribution Workflow Looks Like
+
+1. Read `CHARTER.md` and `BOARDING-MANIFESTO.md` first (vision context)
+2. Fork and create a feature branch
+3. Build for target platform (`make gpu`, `zig build`, etc.)
+4. Write tests for CUDA kernels, Python scripts, or Zig code
+5. Run `make test` / `make test-py` / `zig test`
+6. Open PR with clear description of changes and hardware tested
+
+## Special Notes
+
+- **Boarding Manifesto**: This repo isn't just code — it's a holodeck vision. Contributors should read `BOARDING-MANIFESTO.md` before making architecture decisions. The MUD is designed to run on edge devices (Pi, Jetson, ESP32) with battery awareness and disconnected operation.
+- **Multiple Build Targets**: Unlike typical repos, MUD Arena has four build paths (CUDA GPU, CPU fallback, Zig native, WASM). The CONTRIBUTING.md documents all of them.
+- **Multi-Language**: Code lives in CUDA (`src/mud_arena.cu`), Zig (`src/mud_arena.zig`), C (`src/wasm_mud.c`), and Python (`src/evolve.py`). Each has its own conventions.