docs/consumer-contract.md

@@ -22,19 +22,37 @@ If none resolve, the wrapper exits non-zero with a Phase 5 message. The
 wrappers prefer the single-token `crucible-<name>` shim so `"$builder" args`
 quoting stays correct.
 
-## In CI (preferred)
+## Parity contract — wrappers are not authoritative for build inputs
 
-**OPERATOR NOTE: Stop. Do not do it this way.**
-**Use the pinned `prod.yml` version. That's what it's there for.**
+A consumer build wrapper may only:
 
-~~Run the consumer job inside the pinned image and the binaries are on `PATH`:~~
+1. **validate** — a pre-build gate that does not change output;
+2. **publish** — a post-build step on a separate artifact;
+3. **resolve the crucible binary** — the bootstrap above.
 
-```yaml
-container:
-  image: registry.westgate.pw/deployment/crucible:<sha> # pinned, immutable
-```
+A wrapper MUST NOT fetch, resolve, generate, or stage any input Crucible reads to
+produce the artifact. If Crucible needs an input, Crucible acquires it. This makes
+the "no local-machine assumptions" + "same inputs → identical output" rules
+explicit: local `crucible <build>` and CI `crucible <build>` against the same
+committed config must produce identical bytes, with no CI-only pre-steps.
 
-~~No host install, no `$HOME` layout, no developer machine assumptions.~~
+Builders read every input from the project tree. No NWN install is required. A
+builder that one day needs NWN game data auto-detects the install (the NWN home
+and Steam path are reliably discoverable), with an optional explicit override for
+non-standard layouts — never a required hand-set env.
+
+## In CI
+
+Builds run the Crucible **binary** — from the `crucible.sh` / `crucible.ps1`
+bootstrap (anonymous download) or, for Nix users, from the flake devshell pinned
+by `flake.lock`. CI runs the _same_ `crucible <build>` as local dev, inside the
+nix devshell (binary-cache fast). No build container, no token, no CI-only
+pre-steps.
+
+The `registry.westgate.pw/deployment/crucible:<sha>` image is **deployment-only**:
+`prod.yml` pins it so tools travel with the runtime host (`nwn.enable`), a
+disabled placeholder until the NWN stack lands. It is **not** a build tool and no
+build/CI job consumes it.
 
 ## Determinism