sow-tools/docs/command-surface.md

Crucible command surface

Crucible re-homes the single nwn-tool (a.k.a. sow-toolkit) command surface into five builders plus a dispatcher (D11). This table maps every legacy command to its Crucible home. It is the migration contract — keep it in sync with internal/dispatch.Registry.

Builders

Builder	Legacy nwn-tool commands subsumed
crucible-module	build, build-module, extract, validate, compare, apply-hak-manifest†
crucible-topdata	validate-topdata, build-topdata, build-top-package, compare-topdata, convert-topdata
crucible-hak	build-haks, apply-hak-manifest
crucible-wiki	build-wiki, deploy-wiki
crucible-depot	(new) depot blob verify/move — was shell mc/S3 in sow-assets-manifest

† apply-hak-manifest is HAK-list maintenance on a module; it is reachable from both crucible-module and crucible-hak. Canonical home is crucible-hak.

Folded / global commands

These legacy commands are not top-level builders:

• music * (list-datasets, scan, build, credits, validate, manifest, normalize) → folds into the module/hak build pipeline (music BMUs are packed into HAKs at build time). Exposed as crucible-module music ... / crucible-hak music .... Needs ffmpeg at runtime (in the image).
• config * (validate, effective, inspect, explain, sources) → a global concern shared by every builder; exposed as the global crucible config ..., not its own binary.
• build-changelog → release tooling; exposed as the global crucible changelog rather than a content builder.

Global commands (implemented)

crucible help | -h          usage + builder list
crucible version | -V       build version (git sha via -ldflags)
crucible list               builders, one per line: name<TAB>bin<TAB>summary
crucible config [args]      -> legacy `config` command group
crucible changelog [args]   -> legacy `build-changelog`

crucible list is machine-readable so CI can enumerate builders without parsing help text.

Global flags (planned, at wiring time)

--quiet, --verbose, --debug (the legacy verbosity model), passed after the builder name, e.g. crucible topdata build-topdata --verbose.