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

# sow-tools / Crucible Agent Guide

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 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. **Fail closed, never fake.** A builder with no migrated logic yet (`depot`)
   exits `70`. Do not stub a builder to emit a placeholder artifact.
2. **Binaries are not committed.** They are CI artifacts / image layers.
   `/bin/`, `*.exe`, `nwn-tool`, `sow-toolkit` are gitignored.
3. **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`](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 tests; keep outputs deterministic (same input → same bytes).
3. `make check` must stay green; update `make smoke` to expect the wired exit.

## Commands

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