# Crucible Command Surface Cleanup Design

**Date:** 2026-06-25  
**Status:** Approved  
**Scope:** `sow-tools`, with the two active `sow-assets-manifest` call sites
updated in lockstep

## Problem

Crucible exposes migrated `nwn-tool` implementation names directly. Several
public commands repeat their builder name (`topdata build-topdata`,
`wiki build-wiki`), the interactive menu repeats builder-level descriptions
instead of explaining each action, and selected commands only prompt for
unexplained "extra args".

The registry also exposes a migrated music-conversion subsystem that is not part
of the current project workflow. Live HAK builds explicitly bypass it with
`--skip-music`; authored `.bmu` files are already packed as ordinary assets.

## Decisions

### Canonical command names

The visible command surface is:

| Builder | Visible commands |
| --- | --- |
| `hak` | `build`, `manifest` |
| `module` | `build`, `extract`, `validate`, `compare`, `manifest` |
| `topdata` | `validate`, `build`, `package`, `compare`, `convert` |
| `wiki` | `build`, `deploy` |

The dispatcher translates these names to the existing `internal/app`
implementation commands. The app implementation names do not need to be
renamed.

### Hidden compatibility aliases

Existing long names remain callable indefinitely but are omitted from the
interactive menu and routine builder help:

- `hak build-haks`
- `hak apply-hak-manifest`
- `module build-module`
- `module apply-hak-manifest`
- `topdata validate-topdata`
- `topdata build-topdata`
- `topdata build-top-package`
- `topdata compare-topdata`
- `topdata convert-topdata`
- `wiki build-wiki`
- `wiki deploy-wiki`

Aliases preserve their existing implementation target. In particular,
`module build-module` continues to run the module-only implementation; it must
not silently become the broader `module build`.

### Registry model

`internal/dispatch.Registry` remains the single source of truth. Each wired
builder owns command records containing:

- visible command name;
- action-oriented summary;
- underlying `internal/app` command;
- command usage and option guidance;
- hidden compatibility aliases, where applicable.

Execution, menu items, and builder help are generated from these records.
Unknown commands continue to fail with exit `64`.

### Interactive behavior

The main menu:

- lists only visible commands;
- aligns the description column from the longest visible label;
- shows a distinct description for every command.

After selection, it prints the selected command's usage and available options,
then prompts:

```text
arguments (press Enter to use defaults):
```

Arguments continue to use shell-like whitespace splitting, matching current
behavior. Quoted argument parsing is out of scope.

`crucible <builder> <command> --help` prints the same command-specific guidance,
returns success, and performs no project loading or build work.

### Remove the unused music pipeline

The music conversion subsystem is deleted rather than hidden:

- remove the `music` app and dispatcher commands;
- remove `internal/music` and `internal/pipeline/music.go`;
- remove music config, effective config, validation, environment overrides, and
  project accessors;
- remove HAK music preparation, conversion, credits, generated-manifest result
  fields, `--skip-music`, and `--music-dataset`;
- remove ffmpeg/ffprobe runtime and development dependencies;
- remove music-pipeline documentation and wrapper wording.

`.bmu` remains a supported ordinary asset extension and continues through the
same content-addressed HAK packing path as other authored files. Actual game
content, category names, or prose that happens to use the word "music" is not
part of this deletion.

The default asset-extension list drops conversion-only `.mp3` and `.ogg`.
`.wav` remains because it is an NWN resource type independent of the deleted
conversion pipeline.

Because `sow-assets-manifest` currently passes `--skip-music`, its
`scripts/pack-haks.sh` and `scripts/build-local-haks.sh` call sites are updated
in the same change before verification.

## Error handling

- Canonical and hidden alias lookup is deterministic within one builder.
- Registry tests reject duplicate visible names or aliases.
- Command help never delegates to `internal/app`.
- Removed music commands and flags fail as unknown usage.
- Existing project files containing a top-level `music:` configuration become
  invalid under strict YAML decoding. No active consumer configuration contains
  that field.

## Testing

Tests assert public contracts rather than exact incidental formatting:

- visible command names and hidden alias translation;
- preservation of the distinct `module build-module` target;
- hidden aliases absent from menu and normal help;
- command-specific help exits successfully without project setup;
- menu columns align and selected-command guidance is displayed;
- `.bmu` remains accepted as an asset;
- `.mp3`/`.ogg` are no longer default packable assets;
- HAK builds no longer expose or execute music preparation;
- ffmpeg is absent from package/image definitions;
- both consumer scripts no longer pass `--skip-music`.

Final verification is `nix develop --command make check`, `make build`,
`make smoke`, focused consumer tests, and repository-wide searches for deleted
pipeline identifiers.