Wrapper tool hardening and cleanup

SCRIPT_WRAPPER_CONTRACT.md

@@ -1,5 +1,75 @@
 Refactor and harden all shell wrapper scripts across the module and assets repositories.
 
+## Status Snapshot
+
+Current state as of 2026-05-13:
+
+- Argument passthrough is largely solved for the active root wrappers.
+- `module/` and `assets/` now use repo-root launchers plus
+  `scripts/run-nwn-tool.*` passthrough shims.
+- Wrapper regression coverage already exists in `module/tests/` and
+  `assets/tests/`.
+- The previously stale JSON-config assumption shown in this contract is no
+  longer current; active repos use `nwn-tool.yaml`.
+
+## Active Scope
+
+This contract is still active, but the priority has changed.
+
+The old priority was:
+
+- make `$@` / `@args` forwarding work
+
+The current priority is:
+
+- remove wrapper-side business logic that still duplicates toolkit behavior
+- keep wrappers thin across shell, PowerShell, and release-entrypoint paths
+- align wrapper logs and error handling with the current logging contract
+- finish wrapper/tooling parity before moving deeper into wiki deployment
+
+## Current Findings
+
+The main active wrapper gap is no longer argument forwarding. The bigger gaps are
+wrapper thickness and duplicated orchestration:
+
+- `module/build-module.sh` still shells out to `config effective --json`, parses
+  config locally, probes script sources, resolves manifest paths, and performs
+  pre-build manifest refresh.
+- `module/build-module.ps1` mirrors the same logic in a second implementation.
+- `module/scripts/release-all.sh` and `assets/scripts/release-haks.sh` both
+  parse effective config themselves and still own substantial orchestration that
+  is not just "launch the toolkit".
+
+That means the wrapper contract should now optimize for:
+
+- a single source of truth for preflight behavior
+- thinner root wrappers
+- shared repo plumbing only where toolkit ownership is not appropriate
+- no duplicated config decoding logic between `.sh` and `.ps1`
+
+## Deferred Scope
+
+Defer unrelated wrapper-adjacent work for now:
+
+- model-compilation wrapper concerns
+- release-announcement publication scripting
+- broader asset-processing script consolidation outside wrapper ownership
+
+## Immediate Plan
+
+1. Audit every wrapper that does more than `cd` plus `exec`.
+2. Classify wrapper logic into:
+   - toolkit-owned behavior
+   - shared repo plumbing
+   - release-only orchestration
+3. Move duplicated config reads and command decisions out of paired `.sh` and
+   `.ps1` wrappers where possible.
+4. Keep root wrappers as thin launchers with transparent argument forwarding.
+5. Expand regression coverage from passthrough correctness into:
+   - wrapper-side preflight behavior
+   - stderr/stdout separation for JSON-producing subcommands
+   - shell/PowerShell parity for any remaining unavoidable wrapper logic
+
 # Problem
 
 The current `.sh` and `.ps1` wrapper scripts do not properly forward arbitrary CLI arguments to the underlying toolkit commands.