docs: canonical build policy — build-redbear.sh is the ONLY build tool

Document once and for all that ./local/scripts/build-redbear.sh is the
sole sanctioned way to build Red Bear OS, any package, or any target
artifact. Forbid cargo check/build/clippy in source trees, cargo test
--target in source trees, and repo cook / make r.* / make all / make live
as build substitutes (they skip prefix-staleness detection, fingerprint
tracking, the concurrency lock, branch gates, and stash-and-restore).
Host unit tests (cargo test, no --target) for pure-logic crates are the
single sanctioned test alternative. Explain WHY the script is the build
(concurrency lock, prefix rebuild, stash-and-restore, branch gate,
fingerprints, config parsing). Mark repo cook/make r.* as DIAGNOSTIC
ONLY. Give the correct per-component verification flow.

AGENTS.md

@@ -99,6 +99,59 @@ redox-master/
 
 ## BUILD COMMANDS
 
+### ⛔ CANONICAL BUILD POLICY (ABSOLUTE — READ FIRST)
+
+**The ONLY way to build Red Bear OS is `./local/scripts/build-redbear.sh`.**
+
+There is **no other build tool.** Agents and operators **MUST NOT** build Red Bear OS,
+any package, or any target artifact with anything else. This is absolute:
+
+| Forbidden for building Red Bear OS | Why |
+|---|---|
+| `cargo check` / `cargo build` / `cargo clippy` in any source tree | Bypasses the cross-compile target, sysroot, feature flags, and workspace orchestration. Produces wrong-target or mis-configured output and misleading "it compiles" claims. |
+| `cargo test --target x86_64-unknown-redox` (or any target) in a source tree | Same problem — compiles outside the cookbook's sysroot/prefix. |
+| `./target/release/repo cook <pkg>` **as a substitute for a build** | Diagnostic/diagnostic-only. Outside build-redbear.sh it runs without prefix-staleness detection, source-fingerprint tracking, the concurrency lock, branch gates, or the stash-and-restore guard. The cookbook itself warns: *"repo invoked outside build-redbear.sh"*. |
+| `make r.<pkg>` / `make cr.<pkg>` **as a substitute for a build** | Same — a thin wrapper over `repo cook`, with the same missing guarantees. |
+| `make all` / `make live` directly | build-redbear.sh wraps these with the required preflight (prefix rebuild, version sync, config parsing, protected-fetch policy). Calling them directly skips that preflight. |
+
+**What "build" means here:** producing any Red Bear OS artifact — a cooked package
+(`.pkgar`), a cross-compiled binary for `x86_64-unknown-redox`, a bootable ISO, or the
+prefix toolchain. All of these go through build-redbear.sh, and only build-redbear.sh.
+
+**The single sanctioned alternative — host unit tests.** Running `cargo test`
+(without `--target`, on the host) for crates whose tests are pure host-runnable logic
+(protocol parsers, quirk tables, format decoders) is a **test** action, not a build
+action, and is allowed. This is how `redox-driver-sys`, `firmware-loader`,
+`redbear-iwlwifi`, `redbear-wifictl`, `redbear-btusb` host tests are run. It never
+produces a Red Bear target artifact.
+
+**Why build-redbear.sh is the only path (it is not a wrapper — it is the build):**
+- **Concurrency lock** (`flock`) — two builds at once corrupt cookbook caches and the prefix.
+- **Prefix staleness detection + rebuild** — the #1 cause of "undefined reference" link
+  errors after relibc/kernel/base fork changes is a stale prefix; only build-redbear.sh
+  detects and rebuilds it before any recipe compiles.
+- **Stash-and-restore** — dirty fork sources (`local/sources/*`) are stashed before the
+  build and popped on EXIT, so fingerprints reflect committed HEAD. **Uncommitted fork
+  changes are NOT built** — commit to the `submodule/<name>` branch first.
+- **Branch topology gate** — every fork worktree must be on its canonical
+  `submodule/<name>` branch; the build refuses otherwise.
+- **Source-fingerprint tracking + content-hash cache** — correct incremental rebuilds.
+- **`.config` parsing + protected-fetch policy + version sync + pre-cooking.**
+- Sets `REDBEAR_CANONICAL_BUILD=1` so the cookbook knows it is inside the pipeline.
+
+**Correct per-component verification flow (the ONLY flow):**
+1. Make your edits.
+2. Commit to the right branch: fork code → `submodule/<name>` in `local/sources/<name>`;
+   original recipe code → the release branch in `local/recipes/...`. Push.
+3. Bump the parent's submodule pointers if a fork moved; commit + push.
+4. Run `./local/scripts/build-redbear.sh redbear-mini` (or `redbear-full`). That is the
+   build. That is also the compile verification.
+5. Run host unit tests (`cargo test`) for pure-logic crates as the test pass.
+
+If a recipe is not yet included in any `config/redbear-*.toml` target, build-redbear.sh
+will not build it — wiring it into a config is a separate integration step, and until
+then its verification is host unit tests only.
+
 ```bash
 # Prerequisites (Linux x86_64 host)
 #   rustup + nightly-2026-05-24, cargo install just cbedgen, nasm, qemu-system-x86
@@ -152,12 +205,16 @@ qemu-system-x86_64 -cdrom build/x86_64/redbear-mini.iso \
 # Stale prefix artifacts are the #1 cause of "undefined reference" link errors
 # after fork changes. build-redbear.sh now warns when prefix is stale.
 
-# Single recipe
-./target/release/repo cook recipes/libs/mesa     # Build one recipe (uses content-hash cache)
-./target/release/repo cook mesa --force-rebuild  # Bypass cache, force rebuild
-./target/release/repo fetch recipes/core/kernel   # Fetch source only
-make r.mesa                                      # Make shorthand for cook
-make cr.mesa                                     # Clean + rebuild
+# Single recipe — DIAGNOSTIC ONLY, NOT A BUILD SUBSTITUTE (see policy above).
+# `repo cook` / `make r.*` skip prefix-staleness detection, fingerprint tracking,
+# the concurrency lock, and branch gates. Use ONLY for quick diagnostics while a
+# canonical build-redbear.sh run is the actual build. When in doubt, use
+# build-redbear.sh instead.
+./target/release/repo cook recipes/libs/mesa     # DIAGNOSTIC: cook one recipe
+./target/release/repo cook mesa --force-rebuild  # DIAGNOSTIC: bypass cache
+./target/release/repo fetch recipes/core/kernel   # DIAGNOSTIC: fetch source only
+make r.mesa                                      # DIAGNOSTIC: shorthand for cook
+make cr.mesa                                     # DIAGNOSTIC: clean + rebuild
 
 # Clean
 make clean                                # Remove build artifacts