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).

Rules

1. Migrated logic, not a fresh rewrite. The internal/ packages (app, pipeline, project, erf, gff, topdata, music, changelog, validator) were folded in from gitea/sow-tools at cutover; wired builders delegate to internal/app's command surface. Keep them in step with upstream fixes rather than diverging silently.
2. Fail closed, never fake. A builder with no migrated logic yet (depot) exits 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 (project resolution is CWD-based, never $HOME). 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

1. Ensure the relevant internal/ package(s) cover the work.
2. Add the legacy command(s) to the builder's Legacy/Extra set and set Wired: true in internal/dispatch; the dispatcher delegates to app.Run. depot is the remaining unwired builder.
3. Add tests; keep outputs deterministic (same input → same bytes).
4. make check must stay green; update make smoke to expect the 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.