Wrapper tool hardening and cleanup

CONFIGURATION_REFACTOR_CONTRACT.md

@@ -1,5 +1,82 @@
 Refactor toolkit configuration from JSON to YAML only.
 
+## Status Snapshot
+
+Current state as of 2026-05-13:
+
+- This refactor is largely implemented.
+- Root config discovery now prefers `nwn-tool.yaml`, then `nwn-tool.yml`, then
+  legacy `nwn-tool.json`.
+- YAML is canonical in the consumer repos, and the toolkit exposes
+  `config validate|effective|inspect|explain|sources`.
+- Legacy JSON compatibility still exists by design and is still used heavily in
+  test fixtures.
+
+Remaining work:
+
+- continue migrating representative tests from `nwn-tool.json` fixtures to YAML
+  while keeping only targeted legacy coverage
+- decide when to deprecate or remove legacy shorthand such as `music.prefixes`
+  after consumer configs are fully dataset-based
+- keep documentation/examples synchronized with the normalized YAML schema as it
+  expands
+
+## Active Scope
+
+This contract remains active and is one of the current priorities.
+
+The implementation gap is no longer "load YAML at all". The real gap is
+configuration authority drift:
+
+- some repository behavior is still encoded as toolkit defaults when it should
+  become explicit schema
+- some tests still model old JSON-era expectations
+- some topdata behavior is still driven by explicit namespace/path checks rather
+  than generic dataset rules
+
+## Current Findings
+
+The most important remaining configuration work is topdata-related:
+
+- topdata dataset discovery already derives default output names when `output` is
+  absent, but validation still hard-fails for
+  `topdata/data/masterfeats/base.json` when `output` is missing
+- `internal/topdata/topdata.go` dispatches validation through explicit path
+  checks for `masterfeats`, `feat`, parts overrides, and racialtypes registry
+- topdata defaults in `internal/project` still mix generic toolkit defaults with
+  behavior that may need clearer schema ownership
+
+This means the config-refactor track now overlaps directly with topdata
+hardening. The core question is no longer file format migration; it is whether a
+behavior belongs in:
+
+- root YAML
+- dataset-authored JSON
+- or a documented intrinsic toolkit invariant
+
+## Deferred Scope
+
+Defer unrelated schema expansion for now:
+
+- model compilation config
+- broader asset-maintenance policy schema
+- release-announcement config
+
+## Immediate Plan
+
+1. Continue shrinking legacy `nwn-tool.json` coverage down to deliberate
+   compatibility tests.
+2. Audit hardcoded topdata behaviors and classify each as:
+   - root YAML concern
+   - dataset JSON concern
+   - toolkit invariant
+3. Remove outdated namespace-specific validation assumptions where generic
+   dataset logic already exists.
+4. Keep generated artifacts in JSON, but stop using explicit path-based logic
+   when the same rule can be inferred from generic dataset shape.
+5. Document every remaining intentional toolkit default in `config effective`
+   terms.
+
 # Context
 
 Repositories currently use `config.json` for human-authored toolkit configuration.