YAML Configuration Refactor

README.md

@@ -31,6 +31,45 @@ internal/validator/validation and diagnostics
 tools/             built development binary output
 ```
 
+## Repository Configuration
+
+Human-authored consumer repository configuration is YAML. The toolkit discovers
+configuration in this order:
+
+1. `nwn-tool.yaml`
+2. `nwn-tool.yml`
+3. legacy `nwn-tool.json`
+
+YAML is canonical. If both YAML and legacy JSON files are present, the YAML file
+wins. Legacy `nwn-tool.json` still loads for migration, but commands print a
+warning and should be updated to `nwn-tool.yaml`.
+
+Example:
+
+```yaml
+module:
+  name: Shadows Over Westgate
+  resref: sow_module
+  description: Shadows Over Westgate asset pipeline.
+  hak_order:
+    - sow_top
+    - group:sow_over
+    - group:sow_core
+
+paths:
+  assets: content
+  build: build
+
+music:
+  prefixes:
+    envi/music/westgate: mus_wg_
+```
+
+Generated and machine-readable artifacts remain JSON, including HAK manifests,
+topdata datasets, caches, credits inventories, build reports, and canonical GFF
+documents. Nested metadata such as `topdata/templates/config.json` is not root
+repository configuration and is intentionally unchanged.
+
 ## Intended Consumers
 
 - `sow-module` uses `sow-toolkit` for `build-module`, `extract`, `validate`, `compare`, and `apply-hak-manifest`