sow-tools/AGENTS.md

description, alwaysApply

description	alwaysApply
sow-tools / Crucible — the build/conversion/sync toolchain repo.	true

sow-tools / Crucible Agent Guide

This repo owns the builder logic for the migration: one Go module (gitea.westgate.pw/ShadowsOverWestgate/sow-tools) producing the crucible dispatcher and the crucible-<name> binaries (D11). Read ../AGENTS.md (migration hub) and ../../KICKOFF_PROMPT.md first.

What this repo owns / does not own

Owns: build/extract/validate/compare pipeline, ERF/HAK packing, topdata 2da/tlk compilation, wiki rendering/deploy, depot blob verify, music conversion, changelog. Does not own authored game content (that is sow-module / sow-topdata / sow-assets-manifest) or any production deploy authority (that is sow-platform).

Scaffold rules (Phase 5)

1. Source is not transplanted. The migration hard rules forbid copying the internal/ packages from gitea/sow-tools automatically. The operator migrates them at cutover; see docs/migration-from-nwn-tool.md.
2. Fail closed, never fake. Unwired builders exit 70. Do not stub a builder to emit a placeholder artifact.
3. Binaries are not committed. They are CI artifacts / image layers (D19). /bin/, *.exe, nwn-tool, sow-toolkit are gitignored.
4. No home-dir / NWN_ROOT guessing. Builders take roots explicitly via flag or env. See docs/consumer-contract.md.
5. The registry is the command surface. internal/dispatch.Registry is the single source of truth; keep it in sync with cmd/ and docs/command-surface.md. Adding a builder = a cmd/crucible-<name>/main.go shim + a Registry entry + a doc row.

Wiring a builder (operator cutover)

1. Migrate the relevant internal/ package(s) from gitea/sow-tools.
2. Register a handler and flip the builder off the unwired path in internal/dispatch.
3. Add tests; keep outputs deterministic (same input → same bytes).
4. make check must stay green; make smoke is updated to expect a wired exit.

Commands

nix develop && make check   # vet + test + shellcheck + yamllint
make build                  # cmd/* -> ./bin
make smoke                  # assert fail-closed contract
make image                  # crucible:<sha>

Git

Never commit, branch, or push. Suggest a commit message; let the operator do it.