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

```text
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`.