Document overlay-aware script behavior

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

local/scripts/apply-patches.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# apply-patches.sh — Apply all Red Bear OS patches on top of upstream Redox build system.
+# apply-patches.sh — Apply all Red Bear OS overlays on top of upstream Redox build system.
 #
 # Usage: ./local/scripts/apply-patches.sh [--force]
 #
@@ -8,6 +8,10 @@
 #   2. Ensures recipe patches are symlinked from local/patches/
 #   3. Ensures custom recipe symlinks exist in recipes/
 #
+# WIP policy note:
+#   If upstream work is still under recipes/wip/, Red Bear may still ship from local/recipes/
+#   instead. This script therefore treats the local overlay as the durable source of truth.
+#
 # With --force: reapplies even if patches appear already applied.
 #
 # SAFE: does not touch local/ directory. Only modifies upstream files.

local/scripts/build-redbear.sh

@@ -1,13 +1,19 @@
 #!/usr/bin/env bash
-# build-redbear.sh — Build Red Bear OS
+# build-redbear.sh — Build Red Bear OS from upstream base + Red Bear overlay
 #
 # Usage:
 #   ./local/scripts/build-redbear.sh                     # Default: redbear-desktop
 #   ./local/scripts/build-redbear.sh redbear-minimal     # Minimal validation baseline
 #   ./local/scripts/build-redbear.sh redbear-full        # Full Red Bear integration target
+#   ./local/scripts/build-redbear.sh redbear-wayland     # Wayland runtime validation profile
 #   ./local/scripts/build-redbear.sh redbear-kde         # KDE Plasma bring-up target
 #   ./local/scripts/build-redbear.sh redbear-live        # Live ISO variant
 #   APPLY_PATCHES=0 ./local/scripts/build-redbear.sh     # Skip patch application
+#
+# This script assumes the Red Bear overlay model:
+# - upstream-owned sources are refreshable working trees
+# - Red Bear-owned shipping deltas live in local/patches/ and local/recipes/
+# - upstream WIP recipes are not trusted as stable shipping inputs until upstream promotes them
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -18,11 +24,11 @@ JOBS="${JOBS:-$(nproc)}"
 APPLY_PATCHES="${APPLY_PATCHES:-1}"
 
 case "$CONFIG" in
-    redbear-desktop|redbear-minimal|redbear-full|redbear-kde|redbear-live)
+    redbear-desktop|redbear-minimal|redbear-full|redbear-wayland|redbear-kde|redbear-live)
         ;;
     *)
         echo "ERROR: Unknown config '$CONFIG'"
-        echo "Supported: redbear-desktop, redbear-minimal, redbear-full, redbear-kde, redbear-live"
+        echo "Supported: redbear-desktop, redbear-minimal, redbear-full, redbear-wayland, redbear-kde, redbear-live"
         exit 1
         ;;
 esac
@@ -39,6 +45,20 @@ echo ""
 
 cd "$PROJECT_ROOT"
 
+stash_nested_repo_if_dirty() {
+    local target_dir="$1"
+    local label="$2"
+    if [ -d "$target_dir/.git" ]; then
+        if ! git -C "$target_dir" diff --quiet || ! git -C "$target_dir" diff --cached --quiet || [ -n "$(git -C "$target_dir" ls-files --others --exclude-standard)" ]; then
+            echo ">>> Stashing dirty nested $label checkout before build..."
+            rm -f "$target_dir/.git/index.lock"
+            git -C "$target_dir" stash push --all -m "build-redbear-auto-stash" > /dev/null 2>&1 || true
+        fi
+    fi
+}
+
+stash_nested_repo_if_dirty "$PROJECT_ROOT/recipes/core/relibc/source" "relibc"
+
 # Step 0: Apply local patches
 if [ "$APPLY_PATCHES" = "1" ]; then
     echo ">>> Applying local patches..."
@@ -48,6 +68,14 @@ if [ "$APPLY_PATCHES" = "1" ]; then
         local target_dir="$2"
         local label="$3"
 
+        if [ "$label" = "relibc" ] && [ -d "$target_dir/.git" ]; then
+            if ! git -C "$target_dir" diff --quiet || ! git -C "$target_dir" diff --cached --quiet || [ -n "$(git -C "$target_dir" ls-files --others --exclude-standard)" ]; then
+                echo "    STASH relibc source (dirty nested checkout)"
+                rm -f "$target_dir/.git/index.lock"
+                git -C "$target_dir" stash push --all -m "build-redbear-auto-stash" > /dev/null 2>&1 || true
+            fi
+        fi
+
         if [ ! -d "$patch_dir" ]; then
             return 0
         fi
@@ -55,6 +83,15 @@ if [ "$APPLY_PATCHES" = "1" ]; then
         for patch_file in "$patch_dir"/*.patch; do
             [ -f "$patch_file" ] || continue
             patch_name=$(basename "$patch_file")
+
+            if [ "$label" = "base" ] && [ "$patch_name" = "P0-acpid-power-methods.patch" ]; then
+                acpid_file="$target_dir/drivers/acpid/src/acpi.rs"
+                if [ -f "$acpid_file" ] && grep -q "pub fn evaluate_acpi_method(" "$acpid_file"; then
+                    echo "    SKIP $patch_name (ACPI power helper methods already present)"
+                    continue
+                fi
+            fi
+
             if [ ! -d "$target_dir" ]; then
                 echo "    SKIP $patch_name ($label source not fetched yet)"
                 continue
@@ -73,6 +110,9 @@ if [ "$APPLY_PATCHES" = "1" ]; then
     apply_patch_dir "$PROJECT_ROOT/local/patches/relibc"     "$PROJECT_ROOT/recipes/core/relibc/source"      "relibc"
     apply_patch_dir "$PROJECT_ROOT/local/patches/bootloader" "$PROJECT_ROOT/recipes/core/bootloader/source"  "bootloader"
     apply_patch_dir "$PROJECT_ROOT/local/patches/installer"  "$PROJECT_ROOT/recipes/core/installer/source"   "installer"
+
+    # repo cook refetches nested sources before building; keep relibc clean after patch application
+    stash_nested_repo_if_dirty "$PROJECT_ROOT/recipes/core/relibc/source" "relibc"
     echo ""
 fi
 
@@ -117,6 +157,11 @@ if [ "$CONFIG" = "redbear-minimal" ] || [ "$CONFIG" = "redbear-desktop" ]; then
     echo "  ./local/scripts/validate-vm-network-baseline.sh"
     echo "  ./local/scripts/test-vm-network-qemu.sh $CONFIG"
 fi
+if [ "$CONFIG" = "redbear-wayland" ]; then
+    echo ""
+    echo "To validate the Phase 4 Wayland runtime path:"
+    echo "  ./local/scripts/test-phase4-wayland-qemu.sh"
+fi
 echo ""
 echo "To build live ISO:"
 echo "  make live CONFIG_NAME=$CONFIG"

local/scripts/integrate-redbear.sh

@@ -141,6 +141,7 @@ symlink "../../local/recipes/gpu/amdgpu" "recipes/gpu/amdgpu"
 symlink "../../local/recipes/gpu/redox-drm" "recipes/gpu/redox-drm"
 symlink "../../local/recipes/system/evdevd" "recipes/system/evdevd"
 symlink "../../local/recipes/system/firmware-loader" "recipes/system/firmware-loader"
+symlink "../../local/recipes/system/iommu" "recipes/system/iommu"
 symlink "../../local/recipes/system/redbear-info" "recipes/system/redbear-info"
 symlink "../../local/recipes/system/redbear-hwutils" "recipes/system/redbear-hwutils"
 symlink "../../local/recipes/system/redbear-netstat" "recipes/system/redbear-netstat"

local/scripts/sync-upstream.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# sync-upstream.sh — Update from upstream Redox and reapply Red Bear OS patches.
+# sync-upstream.sh — Update from upstream Redox and reapply Red Bear OS overlays.
 #
 # Usage:
 #   ./local/scripts/sync-upstream.sh              # Rebase onto upstream master
@@ -9,6 +9,10 @@
 # Strategy: git rebase (preserves Red Bear OS commits, replays on new upstream).
 # Fallback: if rebase fails, patches in local/patches/build-system/ can be
 #           applied from scratch via: ./local/scripts/apply-patches.sh --force
+#
+# IMPORTANT: upstream WIP recipes are not treated as durable shipping inputs by Red Bear.
+# After upstream sync, Red Bear-owned WIP work still needs to come from local/recipes/ and
+# local/patches/, not from trust in recipes/wip/ alone.
 
 set -euo pipefail
 

scripts/fetch-all-sources.sh

@@ -19,6 +19,11 @@
 #
 # Sources are placed in recipes/<category>/<name>/source/ for git/tar recipes,
 # and are left in-place for local/recipes/ (path-based sources).
+#
+# WIP policy note:
+# upstream WIP recipes are still useful fetch inputs, but Red Bear may ship the maintained version
+# from local/recipes/ instead. Fetching upstream WIP source does not by itself make that upstream
+# tree the durable shipping source of truth.
 
 set -euo pipefail