# AGENTS.md

Guidance for AI coding agents working in this repository.

## Documentation layout

- `building_guide/` is for **human world builders only**: how to author the
  game's YAML content (rooms, objects, mobs, items, drops, triggers, quests,
  casino tables, and so on). See its README for the index.
- `dev_guide/` is for **engine internals**: architecture, concurrency,
  durability contracts, presentation internals, and per-game implementation
  notes. Code comments that cite documentation must point here.
- `README.md` is the project front page; keep it short and player/operator
  oriented.

When writing documentation, pick the right directory by audience, not by
topic:

1. A builder placing a Pai Gow table reads `building_guide/pai_gow.md`.
2. Someone changing hand evaluation reads `dev_guide/pai_gow.md`.
3. If an article mixes both, split it across the two guides and cross-link.

**Do not** use `building_guide/` as a scratch space: no TODOs, roadmaps,
progress logs, implementation assessments, or "future work" sections. If
you find yourself writing one, put it in `dev_guide/`, a code comment, or
delete it. Conversely, don't bury builder-relevant configuration examples
in `dev_guide/` — builders read only `building_guide/`.

## House rules

- Go: keep tests deterministic (seeded RNG); money flows through
  `internal/casino/credits.go` helpers; run `go test ./...` before handing
  work back.
- YAML data files are validated at startup; run the server or the validate
  tests after editing anything under `data/`.
- If a test or code comment names a documentation file, that file must
  exist at the cited path; update both together.