From 4a912db671b6cb9b9a7f0e25adde06b54277a138 Mon Sep 17 00:00:00 2001
From: Admin Pupkin <adminpupkin@gmail.com>
Date: Tue, 2 Jun 2026 22:56:11 +0300
Subject: [PATCH] AGENTS.md: document build workflow with build-redbear.sh,
 cascade rebuild rule

- Recommended workflow: use build-redbear.sh (enforces policies)
- Cascade rebuild rule: rebuild-cascade.sh after low-level changes
- Toolchain updated to nightly (latest)
- Local-over-WIP policy enforcement documented
---
 AGENTS.md | 38 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 37 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0af885fb7a..42b33498cc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
 # RED BEAR OS BUILD SYSTEM — PROJECT KNOWLEDGE BASE
 
 **Generated:** 2026-04-12 (P1/P2 complete) · Updated: 2026-06 (source ownership migration)
-**Toolchain:** Rust nightly-2025-10-03 (edition 2024)
+**Toolchain:** Rust nightly (edition 2024)
 **Architecture:** Microkernel OS in Rust, ~38k files, ~294k LoC Rust
 **Target Hardware**: AMD64 bare metal, with AMD and Intel machines treated as equal-priority Red Bear OS targets
 
@@ -286,6 +286,42 @@ redox-master/
 
 ## BUILD COMMANDS
 
+### Recommended Workflow (use the build script)
+
+The canonical way to build Red Bear OS ISOs is through `local/scripts/build-redbear.sh`.
+It enforces all project policies automatically:
+
+```bash
+# Build redbear-mini (text-only, recovery) — ~30 min
+./local/scripts/build-redbear.sh redbear-mini
+
+# Build redbear-full (3D desktop + SDDM + KDE) — ~90 min first build
+./local/scripts/build-redbear.sh redbear-full
+
+# Clean rebuild (discard caches, force recompile)
+./local/scripts/build-redbear.sh redbear-full --no-cache
+```
+
+**What `build-redbear.sh` does automatically:**
+1. **Enforces local-over-WIP**: Any `recipes/wip/` package shadowing a `local/recipes/` package is replaced with a symlink to the local version (per local/recipes/ priority policy)
+2. **Verifies overlay integrity**: Checks that all recipe symlinks resolve correctly
+3. **Stashes dirty submodules**: Prevents accidental commits from contaminating the build
+4. **Checks firmware**: Warns if AMD GPU firmware is missing for redbear-full
+
+**When to use `--no-cache`:**
+- After changing `local/sources/{relibc,kernel,base}` (low-level packages)
+- After `make clean` or `make distclean`
+- When stale cached packages cause build failures
+
+**Cascade rebuild rule:** When a low-level package changes (relibc, kernel, base),
+ALL packages that transitively depend on it must be rebuilt. Use:
+```bash
+./local/scripts/rebuild-cascade.sh relibc    # Rebuild relibc + all dependents
+./local/scripts/rebuild-cascade.sh --dry-run relibc  # Preview without rebuilding
+```
+
+### Legacy Manual Build Commands
+
 ```bash
 # Prerequisites (Linux x86_64 host)
 #   rustup + nightly-2025-10-03, cargo install just cbedgen, nasm, qemu-system-x86