You are improving CLI/build logs for a NWN asset toolchain.

## Status Snapshot

Current state as of 2026-05-13:

- This work is largely implemented for the current `build-haks` path.
- The app layer now exposes `--quiet`, `--verbose`, and `--debug`, and normal
  mode prints compact music summaries instead of raw per-file mappings.
- Detailed mapping output is available behind verbose logging, and app tests
  cover the compact versus detailed presentation split.

Remaining work:

- continue applying the same presentation discipline to other command families
  where raw pipeline output still leaks through
- keep summary wording and phase naming aligned as new generated-asset stages
  are added

## Active Scope

Logging remains an active priority, but no longer for `build-haks` alone.

The next logging phase should target:

- `build-topdata`
- `validate-topdata`
- `compare-topdata`
- `build-wiki`
- `deploy-wiki`
- release wrapper flows that currently interleave raw shell/tool output

## Current Findings

The asset-side log refactor proved the presentation model. The remaining gap is
uneven command coverage:

- topdata and wiki commands do not yet have the same polished phase/summarized
  output contract as `build-haks`
- release scripts still emit long shell-oriented logs that are useful for CI
  diagnosis but not shaped into the same structured presentation model
- wrapper-side status lines and toolkit-side progress lines are not yet fully
  harmonized

## Deferred Scope

Defer cosmetic-only logging work that does not improve operator clarity.

For now, prioritize:

- structured summaries
- deterministic phase labels
- stderr/stdout hygiene
- parity between topdata/wiki flows and the existing build-haks presentation

## Immediate Plan

1. Reuse the existing verbosity model for topdata and wiki command families.
2. Define concise normal-mode summaries for topdata build/validate/compare.
3. Add deploy/build wiki progress summaries that surface:
   - local pages scanned
   - create/update/skip/drift counts
   - manifest path
4. Keep debug mode capable of exposing raw internal progress when diagnosis is
   required.
5. Extend app-layer tests to cover topdata/wiki presentation once those
   commands adopt the structured output contract.

Goal: Make the logs cleaner, prettier, less repetitive, and easier to understand, without hiding important diagnostics.

Current issues:

- The same credits refresh output appears twice.
- Long file-by-file mappings overwhelm the main log.
- Some messages are noisy or too implementation-focused.
- The final build summary is useful but visually cramped.
- Paths are too long for normal human reading unless needed for debugging.
- Status prefixes are inconsistent: [credits], [build-haks], run-nwn-tool.sh, [|].

Desired behavior:

1. Use clear phase headers.
2. Collapse repetitive file listings by default.
3. Show counts and summaries in normal mode.
4. Keep detailed mappings available behind a verbose/debug flag.
5. Avoid printing the same credits scan twice unless something changed.
6. Use consistent prefixes and indentation.
7. Prefer relative paths when possible.
8. Group related output together.
9. End with a compact, readable summary.
10. Preserve warnings, errors, and actionable diagnostics prominently.

Suggested output style:

Build HAKs ────────── • Refreshing credits cache

- Scanned: envi/music/westgate
- Tracks: 38
- Output: .cache/credits/envi/music/westgate/credits.json
- Aggregate cache updated

• Validating project • Collecting asset resources • Writing autogen manifests

- sow-parts-manifest.json
- sow-head-vfx-manifest.json

• Planning HAK chunks • Resolving module HAK order • Reusing unchanged HAKs

- 12 / 12 reused
- 65,320 assets total

• Cleaning stale generated HAKs • Writing HAK manifest

Summary ─────── Project: Shadows Over Westgate HAK archives: 12 HAK assets: 65,320 Manifest: assets/build/haks.json Credits artifacts: 2 Autogen manifests: 2 Status: complete

Rules:

- In normal mode, do not print every `mp3 -> bmu` mapping.
- Instead print something like: `Mapped 38 music files. Use --verbose to list mappings.`
- In verbose mode, print mappings under an indented section.
- If the credits cache is refreshed before and after the build for normalization, make the second refresh terse: `Restored normalized credits cache: unchanged.`
- If files changed, say how many changed and where.
- Do not remove any warnings or errors.
- Do not make failure logs terse; failures should include enough context to debug.
- Keep output deterministic so CI diffs remain readable.
- Use plain ASCII unless the toolchain already supports Unicode reliably.
- Do not introduce color unless color can be disabled with NO_COLOR or --no-color.

Implementation guidance:

- Add logging helpers for phases, steps, summaries, verbose details, warnings, and errors.
- Add a verbosity level, for example: quiet, normal, verbose, debug.
- Route repeated detailed output through verbose/debug logging.
- Track counts while scanning instead of printing every scanned item.
- Detect unchanged cache writes and report them as unchanged rather than rewriting noisy output.
- Normalize absolute paths to project-relative paths in normal output.
- Keep machine-readable artifacts unchanged.

Concrete implementation plan:

1. CLI presentation layer

- Keep the pipeline responsible for state and artifact generation.
- Move `build-haks` presentation rules into `internal/app/app.go`.
- Introduce `--quiet`, `--verbose`, and `--debug` for `build-haks`.
- In normal mode, print grouped sections and a compact summary.
- In verbose mode, include detailed mapping and per-archive action lines.
- In debug mode, preserve raw pipeline progress messages for diagnosis.

2. Spinner behavior

- Reuse the existing spinner infrastructure instead of adding a second animation system.
- Make the spinner phase-aware so it shows the current high-level step, for example:
  - `Build HAKs: refreshing credits cache`
  - `Build HAKs: collecting asset resources`
  - `Build HAKs: planning HAK chunks`
- Only animate on interactive TTY stderr.
- Disable spinner animation automatically in CI and non-interactive output.
- Always keep stable human-readable logs on stdout.

3. Pipeline data surfaced to the CLI

- Extend `pipeline.BuildResult` with log-summary metadata instead of forcing the CLI to parse raw strings.
- Return credits refresh summary data:
  - scanned music directories
  - converted track count
  - generated credits artifact paths
  - per-file source/output mappings
  - changed-versus-unchanged artifact count
- Return HAK archive summary data:
  - total archive count
  - reused archive count
  - written archive count
  - per-archive actions for verbose mode

4. Credits artifact handling

- Stop blindly deleting and rewriting `.cache/credits` on every run.
- Render the desired credits outputs in memory first.
- Compare desired artifacts against the current on-disk artifacts.
- Rewrite only changed files.
- Remove stale artifacts that are no longer desired.
- Report `unchanged` when the second pass produces identical output.

5. Output rules

- Normal mode:
  - show phase blocks
  - show counts
  - show relative paths
  - hide file-by-file mappings
- Verbose mode:
  - show music mappings under an indented `mappings:` section
  - show per-archive `reused` or `wrote` details
- Quiet mode:
  - keep only the final summary
- Debug mode:
  - allow raw internal progress lines in addition to the formatted summary

6. Tests

- Add app-layer tests for:
  - compact normal-mode output
  - verbose mapping output
- Add pipeline regression coverage proving:
  - music conversion still writes the expected credits artifacts
  - a second identical credits refresh reports zero changed files

Acceptance checks:

- `build-haks` emits the new grouped summary format.
- `build-haks --verbose` includes per-track mappings and per-archive details.
- The spinner reflects phase changes without polluting stdout logs.
- Re-running the same build keeps credits refresh output deterministic and reports `unchanged` when applicable.
- Existing machine-readable artifacts remain unchanged in schema and location.
