docs: agent-facing documentation pass

Add guidance map, purpose, and usage sections to AGENTS.md; replace
sibling-repository paths with repo name + Gitea URL. Includes pending
working-tree changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

AGENTS.md

@@ -9,6 +9,47 @@ This repo owns the **builder logic:** one Go module
 (`git.westgate.pw/ShadowsOverWestgate/sow-tools`) producing the `crucible`
 dispatcher and the `crucible-<name>` binaries.
 
+## What it is / part it serves
+
+Shadows Over Westgate (SoW) is a Neverwinter Nights: Enhanced Edition
+persistent world, split into single-purpose repos. This repo is Crucible, the
+Go build toolkit. The content repos hold game source (module areas, rules
+data, binary assets) and call Crucible to turn that source into artifacts:
+the `.mod` file, 2DA/TLK tables, HAKs, wiki pages. Crucible is the only place
+builder logic lives; content repos only run it through thin wrapper scripts.
+
+## Guidance map
+
+| Where | What |
+|-------|------|
+| `cmd/crucible/`, `cmd/crucible-<name>/` | dispatcher + per-builder shims (thin `main.go` files) |
+| `internal/dispatch/` | the command registry — single source of truth for the command surface |
+| `internal/` (app, pipeline, project, erf, gff, topdata, changelog, validator, depot, menu, buildinfo) | the actual builder logic |
+| `wrappers/` | canonical bootstrap wrappers (`crucible`, `crucible.ps1`) synced to consumer repos; `wrappers/consumers.txt` lists targets |
+| `docs/command-surface.md` | every command, old `nwn-tool` name → new home |
+| `docs/consumer-contract.md` | how consumer repos resolve/pin a Crucible binary |
+| `docs/migration-from-nwn-tool.md` | migration status, what remains |
+| `tests/`, `Makefile`, `flake.nix` | checks, targets, dev shell |
+
+Task routing: adding/changing a command → read `docs/command-surface.md`
+first, then `internal/dispatch`. Changing how consumers get binaries →
+`docs/consumer-contract.md` + `wrappers/`. Release/CI questions → README "CI"
+section and `.gitea/workflows/`.
+
+## How it is used
+
+- Dev loop: `nix develop`, then `make check` / `make build` / `make smoke`
+  (see Commands below).
+- Release: push a `v*` tag. CI uploads cross-built binaries + wrappers to the
+  Gitea release and publishes the `crucible` container image.
+- Consumers (they download released binaries via the wrapper; they never
+  vendor a toolkit):
+  - sow-module — https://git.westgate.pw/ShadowsOverWestgate/sow-module
+  - sow-topdata — https://git.westgate.pw/ShadowsOverWestgate/sow-topdata
+  - sow-assets-manifest — https://git.westgate.pw/ShadowsOverWestgate/sow-assets-manifest
+  - sow-platform (deploys the released image/pins) —
+    https://git.westgate.pw/ShadowsOverWestgate/sow-platform
+
 ## What this repo owns / does not own
 
 Owns: build/extract/validate/compare pipeline, ERF/HAK packing, topdata 2da/tlk