sow-tools/docs/command-surface.md

Crucible command surface

internal/dispatch.Registry is the single source of truth for Crucible's builders, visible commands, descriptions, help, and hidden compatibility aliases.

Visible commands

Builder	Command	Purpose
hak	build	Build configured HAK archives and their manifest.
hak	manifest	Apply a generated HAK list to module source.
module	build	Build the module and configured project outputs.
module	extract	Extract built archives into configured source trees.
module	validate	Validate project layout, config, and source inventory.
module	compare	Compare source content with built archives.
module	manifest	Apply a generated HAK list to module source.
topdata	validate	Validate topdata source and canonical JSON compatibility.
topdata	build	Compile topdata and refresh the configured package.
topdata	package	Package cached outputs into HAK and TLK files.
topdata	compare	Compare current output with a fresh native build.
topdata	convert	Convert between 2DA and native JSON/module formats.
wiki	build	Render wiki page drafts from compiled topdata.
wiki	deploy	Deploy generated wiki pages to NodeBB.
assets	compile	Compile ASCII .mdl models to binary in place.
assets	convert	Convert textures to/from NWN DDS (flips vertically).
assets	upscale	Upscale textures through an installed backend.
assets	check-mdl	Report uncompiled ASCII .mdl and model-name mismatches.
assets	fix-mdl	Lowercase .mdl names and rewrite model identity to match.
assets	check-dupes	Report runtime-name (basename) collisions across dirs.
assets	clean-dupes	Delete clean-tree files whose basename collides with primary.

crucible-depot remains registered but unwired. It fails closed with exit 70 and never emits placeholder artifacts.

Hidden compatibility aliases

Existing scripts may continue using these names indefinitely. They are accepted but omitted from routine help and the interactive menu:

Builder	Hidden alias	Implementation
hak	build-haks	build-haks
hak	apply-hak-manifest	apply-hak-manifest
module	build-module	module-only build-module
module	apply-hak-manifest	apply-hak-manifest
topdata	validate-topdata	validate-topdata
topdata	build-topdata	build-topdata
topdata	build-top-package	build-top-package
topdata	compare-topdata	compare-topdata
topdata	convert-topdata	convert-topdata
wiki	build-wiki	build-wiki
wiki	deploy-wiki	deploy-wiki

module build-module deliberately retains its narrower module-only behavior; it is not redirected to the broader module build.

Global commands

crucible help | -h          usage + builder list
crucible version | -V       build version
crucible list               name<TAB>binary<TAB>summary
crucible config [args]      inspect and validate effective configuration
crucible changelog [args]   generate a release changelog

HAK build options

crucible hak build
  [--hak <hak-name> ...]
  [--archive <archive-name> ...]
  [--source-manifest <path>]
  [--content-addressed-root <path>]
  [--plan-only]
  [--quiet|--verbose|--debug]

When a source manifest contains asset_sources, pass --content-addressed-root <directory>. Crucible resolves each declared SHA-256 under sha256/<first-two>/<next-two>/<full-sha256> and verifies streamed bytes while writing selected HAK archives. Authored .bmu files are ordinary assets and require no conversion pipeline.