RedBear-OS/AGENTS.md

# RED BEAR OS BUILD SYSTEM — PROJECT KNOWLEDGE BASE

**Generated:** 2026-04-12 (P1/P2 complete)
**Toolchain:** Rust nightly-2025-10-03 (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

## OVERVIEW

Red Bear OS build system orchestrator — fetches, builds, and packages ~100+ Git repositories
into a bootable Redox image. Uses a Makefile + Rust "cookbook" tool + TOML configs.
Languages: Rust (core), C (ported packages), TOML (config), Make (build orchestration).

RedBearOS is a **full fork** of Redox OS — based on frozen, archived source snapshots.
Sources are immutable and never auto-immutable archived from upstream. All changes are explicit,
human-initiated operations. Durable Red Bear state belongs in `local/patches/`,
`local/recipes/`, `local/docs/`, and tracked Red Bear configs.

## ABSOLUTE RULE — NEVER DELETE, NEVER IGNORE, NEVER COMMENT OUT

**If an agent decides something is "not necessary", "not required for boot", "too heavy",
or "not needed" — that decision is WRONG. Always keep and fix.**

- **NEVER delete** a package, config, service, patch, or file because it seems unnecessary.
- **NEVER ignore** a package by setting it to `"ignore"` because it seems unneeded.
- **NEVER comment out** a package, service, or config entry to "clean up" or "trim".
- **NEVER remove** build tools, desktop services, or any other package to reduce image size.
- **ALWAYS fix** the root cause if something breaks — do not work around it by removal.

The ONLY acceptable time to remove or ignore a package is when the **user explicitly
and directly** requests it. No agent-initiated removals. No "I think this isn't needed".
No "this seems too heavy for mini". **When in doubt: KEEP IT AND FIX IT.**

This rule exists because agents have repeatedly destroyed months of work by deciding
packages were "unnecessary" and silently removing them during syncs and config changes.

The current baseline is **Red Bear OS 0.1.0** (Redox snapshot at build-system commit `f55acba68`).
All recipe sources are pinned and archived in `sources/redbear-0.1.0/`.

## STRUCTURE

```
redox-master/
├── config/          # Build configs (TOML): tracked redbear-* targets plus mainline references
├── mk/              # Makefile fragments: config.mk, repo.mk, prefix.mk, disk.mk, qemu.mk
├── recipes/         # Package recipes (TOML + source). 26 categories. See recipes/AGENTS.md
│   ├── core/        # kernel, bootloader, relibc, base drivers — See recipes/core/AGENTS.md
│   ├── wip/         # Wayland, KDE, driver WIP ports — See recipes/wip/AGENTS.md
│   ├── libs/        # Libraries: mesa, cairo, SDL, zlib, openssl, etc.
│   ├── gui/         # Legacy GUI stack packages
│   └── ...          # 21 other categories (net, dev, games, shells, etc.)
├── src/             # Cookbook Rust tooling (repo binary, cook logic)
├── docs/            # Architecture docs (6 detailed integration guides) — See docs/AGENTS.md
├── local/           # OUR CUSTOM WORK — survives mainline updates — See local/AGENTS.md
│   ├── config/      # Custom configs (my-amd-desktop.toml)
│   ├── recipes/     # Custom recipes (AMD drivers, GPU stack, Wayland)
│   ├── patches/     # Patches against mainline sources (kernel, relibc, base)
│   ├── Assets/      # Branding assets (icon, loading background)
│   ├── firmware/    # AMD GPU firmware blobs (fetched, not committed)
│   ├── scripts/     # Build/deploy scripts (fetch-firmware.sh, build-redbear.sh)
│   ├── docs/        # Red Bear integration docs (AMD roadmap, Wi-Fi/Bluetooth plans, status notes)
│   └── reference/   # External reference sources (gitignored, never deleted, always kept)
├── prefix/          # Cross-compiler toolchain (Clang/LLVM for x86_64-unknown-redox)
├── build/           # Build outputs, logs, fstools, per-arch directories
├── repo/            # Package manifests and PKGAR artifacts per architecture
├── bin/             # Cross-tool wrappers (pkg-config, llvm-config per target)
├── scripts/         # Helper scripts (backtrace, category, changelog, etc.)
├── podman/          # Podman container build support
├── .cargo/          # Cargo config: linker per target (aarch64, x86_64, i586, i686, riscv64gc)
├── Makefile         # Root orchestrator (all, live, image, rebuild, clean, qemu, gdb)
├── Cargo.toml       # Cookbook crate: binaries (repo, repo_builder), lib (cookbook)
├── rust-toolchain.toml  # nightly-2025-10-03 + rust-src + rustfmt + clippy
└── .config          # PODMAN_BUILD=0 (set to 1 for container builds)
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| Add a package | `recipes/<category>/<name>/recipe.toml` | Use `template = "cargo\|cmake\|meson\|custom"` |
| Change build config | `config/<name>.toml` | Include chain: wayland→desktop→desktop-minimal→minimal→base |
| Fix kernel | `recipes/core/kernel/source/` | Kernel is a recipe, not top-level |
| Fix a driver | `recipes/core/base/source/drivers/` | All drivers are userspace daemons |
| Fix relibc (POSIX) | `recipes/core/relibc/source/` | C library written in Rust |
| Wayland integration | `recipes/wip/wayland/` + `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` | 21 WIP recipes + local validation/ownership plan |
| KDE Plasma path | `recipes/wip/kde/` + `docs/05-KDE-PLASMA-ON-REDOX.md` | 9 WIP KDE app recipes |
| **Desktop path plan** | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | **Canonical plan: console → HW-accelerated KDE** |
| Linux driver compat | `docs/04-LINUX-DRIVER-COMPAT.md` | linux-kpi + redox-driver-sys architecture (**GPU and Wi-Fi only — not USB**) |
| Build system internals | `src/bin/repo.rs`, `src/lib.rs`, `mk/repo.mk` | Cookbook tool in Rust |
| Cross-toolchain setup | `mk/prefix.mk`, `prefix/x86_64-unknown-redox/` | Downloads Clang/LLVM toolchain |
| Display/session surface | `config/redbear-full.toml` | Active desktop/graphics compile surface |
| GPU/graphics stack | `recipes/libs/mesa/` | OSMesa + LLVMpipe (software only) |
| GPU hardware drivers | `local/recipes/gpu/redox-drm/source/` | AMD + Intel DRM/KMS via redox-driver-sys |
| D-Bus integration | `local/docs/DBUS-INTEGRATION-PLAN.md` | Architecture, gap analysis, phased implementation for KDE Plasma D-Bus |
| Boot config | `config/*.toml` | TOML hierarchy, include-based |
| **Hardware quirks** | `local/recipes/drivers/redox-driver-sys/source/src/quirks/` | Data-driven quirk tables: compiled-in + TOML + DMI; see `local/docs/QUIRKS-SYSTEM.md` |
| **Package build quirks** | `local/docs/PACKAGE-BUILD-QUIRKS.md` | Cross-compilation issues (DYNAMIC_INIT, m4, ninja-build), fixes, and general patterns |

## BUILD COMMANDS

```bash
# Prerequisites (Linux x86_64 host)
#   rustup + nightly-2025-10-03, cargo install just cbedgen, nasm, qemu-system-x86
#   See docs/06-BUILD-SYSTEM-SETUP.md for distro-specific packages

# Configuration
echo 'PODMAN_BUILD?=0' > .config          # Native build (no container)
echo 'PODMAN_BUILD?=1' > .config          # Podman container build

# CRITICAL: .config MUST NOT contain REDBEAR_RELEASE=... in development mode.
# If it does, the build system re-extracts sources from the immutable release
# archive and ignores the local forks. Remove it if present:
grep -v REDBEAR_RELEASE .config > .config.tmp && mv .config.tmp .config

# Build Red Bear OS
# Supported compile targets:
#   redbear-full         desktop/graphics target (harddrive.img or live ISO)
#   redbear-mini         text-only console/recovery target (harddrive.img or live ISO)
#   redbear-grub         text-only with GRUB boot manager (live ISO)
# Desktop/graphics target: redbear-full
# Text-only targets: redbear-mini, redbear-grub
./local/scripts/build-redbear.sh redbear-mini         # Recommended (dev mode, local forks)
./local/scripts/build-redbear.sh --upstream redbear-mini  # With online fetch (fast iteration)
make all CONFIG_NAME=redbear-mini         # Text-only target → harddrive.img
make all CONFIG_NAME=redbear-full         # Desktop/graphics target → harddrive.img
make live CONFIG_NAME=redbear-full        # Full desktop live ISO
make live CONFIG_NAME=redbear-mini        # Text-only mini live ISO
make live CONFIG_NAME=redbear-grub        # Text-only mini live ISO with GRUB
CI=1 make all CONFIG_NAME=redbear-mini    # CI mode (disables TUI, for non-interactive)

# IMPORTANT: For local fork development, use:
#   export REDBEAR_ALLOW_PROTECTED_FETCH=1  # base/kernel/relibc are protected recipes
#   ./local/scripts/build-redbear.sh --upstream redbear-mini
# Without --upstream, the build is in offline mode and re-extracts from
# the immutable release archive instead of using the local forks.

# Run
make qemu                                 # Boot in QEMU
make qemu QEMUFLAGS="-m 4G"              # With more RAM
make live                                 # Build live ISO for real bare metal

# QEMU with network access (required for testing):
qemu-system-x86_64 -cdrom build/x86_64/redbear-mini.iso \
  -m 1024 -netdev user,id=n0 -device e1000,netdev=n0

# Rebuild prefix (after relibc/kernel/base fork changes):
#   touch relibc && make prefix        # Rebuild relibc in the cross-toolchain
#   touch kernel && make prefix        # Rebuild kernel-related toolchain parts
# The prefix provides libc.a and system headers used by ALL recipes.
# 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
./target/release/repo fetch recipes/core/kernel   # Fetch source only
make r.mesa                                      # Make shorthand for cook
make cr.mesa                                     # Clean + rebuild

# Clean
make clean                                # Remove build artifacts
make distclean                            # Remove sources + artifacts

# Safe cleanup (NEVER deletes tracked source files — checks git ls-files first):
./local/scripts/cleanup-build.sh           # Remove only build/ and repo/ (safest)
./local/scripts/cleanup-build.sh --all     # Also remove recipe target/ dirs (forces rebuild)
# DO NOT run ad-hoc `rm -rf` or unvetted cleanup scripts — they have wiped
# tracked local/recipes/*/source/ and local/sources/*/source/ trees in the past.
# The safe cleanup script above uses `git ls-files` to skip every tracked path.
```

### Local forks vs overlay patches

As of 2026-06, the following core components use **local forks** (in
`local/sources/<component>/`) instead of `upstream + overlay patches`:

- `relibc`, `kernel`, `bootloader`, `installer`, `redoxfs`, `userutils`
- **`base`** — uses `path = "..."` in `recipes/core/base/recipe.toml` to point
  at the local fork

The local fork approach was chosen because:

1. The overlay patch chain accumulated drift from upstream, causing
   repeated build failures (broken patches, version mismatches, etc).
2. The local forks are the durable source of truth, with version pins and
   fixes already applied.
3. Iterating on a local fork is faster than maintaining dozens of patches.

For details on how to import upstream commits into a local fork, see
`local/AGENTS.md` § "LOCAL FORK MODEL".

## BUILD FLOW

```
make all
  → mk/config.mk (ARCH, CONFIG_NAME, FILESYSTEM_CONFIG)
  → mk/depends.mk (check host tools: rustup, cbedgen, nasm, just)
  → mk/prefix.mk (download/setup cross-toolchain if needed)
  → mk/fstools.mk (build cookbook repo binary + fstools)
  → mk/repo.mk (repo cook --filesystem=config/*.toml)
    → For each recipe: fetch source → apply patches → build → stage into sysroot
  → mk/disk.mk (create filesystem.img, harddrive.img, redbear-live.iso or harddrive.img)
    → redoxfs-mkfs → redox_installer → bootloader embedding
```

## CONVENTIONS

- **Rust edition 2024**, nightly channel
- **rustfmt.toml**: max_width=100, brace_style=SameLineWhere
- **clippy.toml**: cognitive-complexity-threshold=100, type-complexity-threshold=1000
- **Recipe format**: TOML with `[source]` + `[build]` + optional `[package]`
- **Build templates**: `cargo`, `meson`, `cmake`, `make`, `configure`, `custom`
- **WIP recipes**: Must start with `#TODO` comment explaining what's missing
- **Custom configs**: Name with `redbear-*` prefix (tracked in git). The legacy `my-*` prefix is deprecated and git-ignored.
- **DYNAMIC_INIT**: Cookbook function that overwrites `CFLAGS`, `LDFLAGS`, `CXXFLAGS` entirely. Custom flags MUST be set AFTER `DYNAMIC_INIT`. See `local/docs/PACKAGE-BUILD-QUIRKS.md` for details.
- **Cross-compilation tests**: Disable test suites (`BUILD_TESTING=OFF`, `--disable-tests`) when cross-compiling. Tests require host frameworks (gtest) that conflict with Redox sysroot headers. See `local/docs/PACKAGE-BUILD-QUIRKS.md` § General Patterns.
- **CI**: GitLab CI (`.gitlab-ci.yml`) at root + per-recipe; some have GitHub Actions
- **Syscall ABI**: Unstable intentionally. Stability via `libredox` and `relibc`
- **Drivers**: ALL userspace daemons via scheme system. No kernel-space drivers (except serio)
- **In-house crate versioning**: All Red Bear original crates (`local/recipes/*/source/`) MUST
  use the current Red Bear OS version (derived from the git branch name, e.g. `0.2.4` on branch
  `0.2.4`). Upstream Redox forks (`local/sources/`) keep their upstream versioning. Established
  projects with independent release cycles (`tlc`, `zbus`) are exempt. Use
  `./local/scripts/sync-versions.sh` to sync all in-house crate versions when creating a new
  branch, and `./local/scripts/sync-versions.sh --check` to verify compliance.

## INSTALLER FILE LAYERING

The installer creates filesystem images in four layers. Understanding this ordering is critical
to avoid silent file overwrites.

### Layer Ordering During `install_dir()`

```
Layer 1: Config pre-install [[files]]    (postinstall = false)
Layer 2: Package staging                  (install_packages())
Layer 3: Config post-install [[files]]    (postinstall = true)
Layer 4: User/group creation              (passwd, shadow, group)
```

### Collision Implications

- **Layer 2 overwrites Layer 1** silently (same path → last writer wins). This is the bug class
  that caused the D-Bus regression: config overrides at `/usr/lib/init.d/` were overwritten by
  the `base` package staging the same paths.
- **Layer 3 overwrites Layer 2** (intentional — postinstall overrides).
- For init services, config overrides **MUST** use `/etc/init.d/` so they survive Layer 2.

### Init Service File Ownership

- **Packages own `/usr/lib/init.d/`** — default service files installed by recipe staging
- **Config overrides own `/etc/init.d/`** — override files created by `[[files]]` entries
- The init system's `config_for_dirs()` gives `/etc/init.d/` priority via BTreeMap dedup
- **Config `[[files]]` entries MUST NOT use `/usr/lib/init.d/` paths for init services**
- Run `make lint-config` to detect violations

### Collision Detection

The installer now includes a `CollisionTracker` (in `collision.rs`) that detects when package
staging overwrites config pre-install files. Init service collisions always error. Other
collisions warn by default, error in strict mode (`REDBEAR_STRICT_COLLISION=1`).

### Validation Gates

After building an image, run `make validate` to verify:
- Init service path violations (via `lint-config`)
- Override effectiveness and scheme binary existence (via `validate-init-services.sh`)
- File ownership conflicts (via `validate-file-ownership.sh`)

See `local/docs/BUILD-SYSTEM-HARDENING-PLAN.md` for the full plan.

## ANTI-PATTERNS (THIS PROJECT)

- **DO NOT** suppress errors with `as any` / `@ts-ignore` — use proper `Result` handling
- **DO NOT** use `unwrap()` / `expect()` in library/driver code — pervasive anti-pattern (~14k instances)
- **DO NOT** modify kernel syscall ABI directly — use `libredox` or `relibc`
- **DO NOT** put drivers in kernel space — all drivers are userspace daemons
- **DO NOT** hardcode `/dev/` paths — use scheme paths (`/scheme/drm/card0`)
- **DO NOT** skip patches in WIP recipes — document what's missing with `#TODO`
- **DO NOT** skip warnings — investigate, diagnose, and fix the root cause; suppressing or ignoring warnings is not acceptable when a fix is feasible
- **DO NOT** remove patches from `recipe.toml` to fix build failures — rebase the patch instead (see `local/docs/PATCH-GOVERNANCE.md`)
- **DO NOT** remove BINS entries to fix build failures — fix the source or use EXISTING_BINS filtering

## LINUX REFERENCE SOURCE POLICY

`local/reference/linux-7.0/` (or later) contains a full Linux kernel source tree for
cross-referencing driver behavior, hardware initialization sequences, register definitions,
and error handling patterns.

**Rules:**
- **NEVER delete** the reference tree.
- **ALWAYS consult** the Linux source when building or fixing drivers, daemons, or any subsystem
  that has a Linux counterpart (audio/HDA, GPU/DRM, networking, USB, PCI, ACPI, input, storage,
  filesystems, scheduler, memory management).
- **Update** the reference tree when a new stable Linux version is needed:
  `git -C local/reference/linux-7.0 fetch --depth=1 origin tag:v7.x --force`
- The reference tree is read-only for consultation purposes. No modifications.
- Location: `local/reference/` survives `make clean` and `make distclean`.

**Tracking policy:** The Linux reference tree is currently gitignored (2.1GB).
Per our **NEVER GITIGNORE CRITICAL INFRASTRUCTURE** policy, it should eventually
be migrated to either:
- A sparse git submodule reference (only top-level + needed subdirs), or
- A periodic mirror on the gitea server that CI re-clones when needed.

This is a follow-up refactor — the tree is permanent, just currently gitignored
by size. The `local/reference/` directory is **NOT** optional.

## DURABILITY POLICY

Every change to an upstream-owned source tree (anything under `recipes/*/source/`) **must** be
mirrored into a durable location **in the same work session** it was made. A change that exists
only inside a fetched source tree is not preserved.

**Required actions after any source-tree edit:**

1. **Generate a patch** from the source git diff and save it under `local/patches/<component>/`.
2. **Wire the patch** into the recipe's `recipe.toml` `patches = [...]` list.
3. **Commit** the patch file and recipe change before the session ends.

**Why:** `make distclean`, `make clean`, and source immutable archivedes all
discard or replace `recipes/*/source/` trees. Only `local/patches/`, `local/recipes/`,
tracked configs, `local/docs/`, and `sources/redbear-0.1.0/` survive.

**Examples of changes that require immediate patching:**

| What you edited | Durable location |
|---|---|
| `recipes/core/relibc/source/src/header/sys_select/mod.rs` | `local/patches/relibc/P3-select-not-epoll-timeout.patch` + `recipe.toml` |
| `recipes/core/relibc/source/src/header/signal/cbindgen.toml` | same patch as above |
| `recipes/core/userutils/source/res/issue` | `local/patches/userutils/redox.patch` + `recipe.toml` |
| `recipes/core/kernel/source/...` | `local/patches/kernel/redox.patch` (symlinked from recipe) |

**What does NOT need patching:** Files that already live in `local/`, tracked `config/redbear-*.toml`,
or any path that is already git-tracked and not inside a fetched source tree.

## BUILD SYSTEM POLICIES

### Atomic Patch Application

The cookbook tool (`src/cook/fetch.rs`) applies patches **atomically**:
patches are applied to a staging directory (created via `cp -al` hard links),
and only promoted into the live source tree if **all** patches succeed. If any
patch fails, the staging directory is discarded and the source tree remains
untouched.

**The source tree is NEVER left in a partially-patched state.**

When a patch fails, the error message includes the `[ATOMIC]` tag and the
failed patch name. Recovery: fix the patch file, then re-run `repo fetch`.

### Patch Format

Patches may use either format:
- Unified diff (`---`/`+++` lines, preferred — most portable)
- `diff --git` format (auto-normalized by `normalize_patch()`)
- `diff -ruN` format (also auto-normalized — `diff -ruN` headers stripped like `diff --git`)

Git-specific headers (`diff --git`, `diff -ruN`, `index`, `new file mode`, `rename from/to`,
`similarity index`, `dissimilarity index`) are automatically stripped before
`patch` is invoked. The build system uses `--fuzz=0` for strict context matching.

**Timestamps in `---`/`+++` lines** (common in `diff -ruN` output) should be removed.
Use `--- a/path` and `+++ b/path` without timestamps. The `normalize_patch` function
does NOT strip timestamps — they should be removed from the patch file directly.

### Protected Recipes

Core recipes (`base`, `kernel`, `relibc`, `bootloader`, etc.) and any recipe carrying
Red Bear patches are **protected** and cannot be re-fetched online.

As of 2026-06, most protected recipes use **local forks** in
`local/sources/<component>/` rather than archives. The cookbook falls back to
the immutable release archive (`sources/redbear-<release>/tarballs/`) only when
the local fork is missing.

For the protected recipes, the build needs the source to exist. In development
mode with local forks, the cookbook copies the fork to `recipes/<component>/source/`.
In release mode, the source is extracted from the archive.

**For development builds with local forks, use:**

```bash
export REDBEAR_ALLOW_PROTECTED_FETCH=1
./local/scripts/build-redbear.sh --upstream redbear-mini
```

Or, equivalently:

```bash
REDBEAR_ALLOW_PROTECTED_FETCH=1 ./local/scripts/build-redbear.sh --upstream redbear-mini
```

Without `REDBEAR_ALLOW_PROTECTED_FETCH=1`, the cookbook refuses to fetch the
protected recipe's source and the build fails.

Without `--upstream`, the build defaults to offline mode and tries to extract
from the release archive (which may be stale or missing patches).

The full protected recipe list (in `src/cook/fetch.rs:redbear_protected_recipe()`)
includes: all core system recipes, all Red Bear custom recipes, all patched Qt/Wayland/
KDE recipes, and all recipes carrying Red Bear patches (Qt, DRM, Mesa, Wayland, D-Bus,
glib, etc.). Any recipe with a `redox.patch` or local patches is a candidate for
protection — add it when adding patches.

### Offline-First By Default

Red Bear OS is a **fork with frozen sources**. The cookbook tool defaults to
`COOKBOOK_OFFLINE=true` (changed from upstream Redox's `false`). Builds use archived
sources from `sources/redbear-0.1.0/` — no network access during compilation.

To allow online fetching for non-protected development recipes:
```bash
COOKBOOK_OFFLINE=false make all CONFIG_NAME=redbear-full
```

Or use the `--upstream` flag of `build-redbear.sh`:
```bash
./local/scripts/build-redbear.sh --upstream redbear-mini
```

In release mode (`REDBEAR_RELEASE=0.1.0`), online fetching is **completely disabled**
even with `COOKBOOK_OFFLINE=false`. Sources are immutable in release mode.

**For development with local forks** (see "LOCAL FORK MODEL" in `local/AGENTS.md`),
the recommended invocation is:
```bash
unset REDBEAR_RELEASE  # CRITICAL: must not be set in dev
export REDBEAR_ALLOW_PROTECTED_FETCH=1
./local/scripts/build-redbear.sh --upstream redbear-mini
```

### Workspace Pollution Prevention

Before every fetch and build, the cookbook tool removes orphaned `Cargo.toml`
and `Cargo.lock` files from `recipes/` root. These files can appear as side
effects of relibc workspace builds and cause "current package believes it's in
a workspace" errors.

### Patch Chain Ordering

Patches in `recipe.toml` are applied in listed order. Dependencies between
patches must be respected:
- Patches that **define** types (e.g., `InputProducer`) must come BEFORE
  patches that **use** those types
- Patches that **create** files must come BEFORE patches that **modify** them
- Cumulative patches (P0 → P2 → P3) must maintain correct line number context

When reordering patches: remove the source tree, re-fetch, and rebuild to verify.

### Large Patch Files

**POLICY: Never gitignore critical build infrastructure, regardless of file size.**

The Gitea server is our own — we have unlimited space. Do not put `local/patches/*`,
`local/recipes/*`, `local/sources/*`, or any other durable Red Bear code in
`.gitignore` because of file size.

**Historical context (resolved):** The original `local/patches/base/redox.patch` was a 100MB+
consolidated mega-patch that was placed in `.gitignore`. After it was lost, base
recipe could not be built from a clean checkout. The mega-patch approach was
abandoned in favor of ~100 individual `P*.patch` files (totaling 2.4MB) that are
all committed to git.

**Current state (2026-06):**
- All `local/patches/base/P*.patch` files are tracked in git.
- The dangling `recipes/core/base/redox.patch` symlink (the old mega-patch
  shortcut) has been removed.
- For components that need extensive changes (base, relibc, kernel), we now
  use **local forks** in `local/sources/<component>/` instead of accumulating
  many patches. See "LOCAL FORK MODEL" in `local/AGENTS.md`.

**Future policy:** If a single patch ever grows beyond what Git LFS would
comfortably handle, split it into multiple smaller patches. Do not put it in
`.gitignore`. Do not store it in chunks that need reassembly.

**For local forks:** The full source tree of a fork can be large (e.g.,
Redox kernel is ~30MB, relibc is ~10MB). Local forks in `local/sources/` are
git-tracked and pushed to gitea. The `.gitignore` MUST NOT exclude them.

### Patch Governance

See `local/docs/PATCH-GOVERNANCE.md` for the full patch governance rules.
Critical rules:
- **Never remove patches** to fix build failures — rebase them
- **Never remove BINS entries** — fix the source or use `EXISTING_BINS`
- **Recipe.toml is git-tracked** — changes to it are durable
- **Source trees are disposable** — `repo clean`/`distclean` destroy them
- **All source changes must be patches** in `local/patches/`
- **Commit patch files and recipe.toml changes** before session end

### Build Validation

After ANY change to patches or `recipe.toml`:
1. Validate patches: `./target/release/repo validate-patches <recipe>`
2. Remove source: `rm -rf recipes/core/<recipe>/source`
3. Fetch: `repo --allow-protected fetch <recipe>`
4. Build: `repo cook <recipe>`
5. Verify no `FAILED`, `[ATOMIC] patch application rolled back`, or `.rej` files
6. Full image: `make all CONFIG_NAME=<target>`

The `repo validate-patches` command (added 2026-05) performs a dry-run patch
application against clean upstream source in a temporary staging directory.
It reports per-patch `[PASS]`/`[FAIL]` status without modifying the live source
tree. Always run it before attempting a full build when patches have changed.

## PATCH MANAGEMENT

All Red Bear OS modifications to upstream files are kept separately in `local/patches/`.

### GOLDEN RULE — Red Bear adapts to upstream, never the reverse

**When upstream Redox changes a dependency version, API, or ABI, Red Bear adapts.**
Red Bear NEVER pins, downgrades, or holds back an upstream package to avoid
adaptation work. If `libredox` moves to `redox_syscall 0.8`, every Red Bear crate
that touches `redox_syscall` moves to `0.8` — we fix our code, not theirs.

This applies to:
- Crate dependency version bumps (`redox_syscall`, `libredox`, `redox-scheme`, etc.)
- API changes in upstream crates (module reorganization, renamed types, trait changes)
- ABI changes in relibc, kernel, or syscall layer
- Any upstream evolution that requires Red Bear source changes

**The only acceptable response to an upstream version bump is: update, adapt, commit.**

This is not just a convenience rule; it is a long-term maintenance rule. For fast-moving upstream
areas like relibc, prefer the upstream solution whenever upstream already solves the same problem.
Keep Red Bear patch carriers only for gaps or compatibility work that upstream still does not solve
adequately.

When upstream Redox already provides a package, crate, or subsystem for functionality that also
exists in Red Bear local code, prefer the upstream Redox version by default unless the Red Bear
implementation is materially better. Do not grow lower-quality in-house duplicates as a steady
state.

For quirks and driver support specifically:

- prefer improving and using the canonical `redox-driver-sys` path,
- avoid maintaining separate lower-quality quirk engines when the same functionality belongs in
  `redox-driver-sys`,
- if duplication is temporarily unavoidable, treat it as convergence work to remove, not as a
  permanent design.

### Structure

```
local/patches/
├── kernel/redox.patch              # Applied to kernel source during build (symlinked from recipe)
├── kernel/P0-*.patch               # Individual logical patches (for reference/merge)
├── base/redox.patch                # Applied to base source during build (symlinked from recipe)
├── base/P0-*.patch                 # Individual logical patches
├── relibc/P3-*.patch               # POSIX gap patches (eventfd, signalfd, timerfd, etc.)
├── installer/redox.patch           # Installer ext4 + GRUB bootloader support
└── build-system/
    ├── 001-rebrand-and-build.patch # Makefile, mk/*, scripts, build.sh rebranding
    ├── 002-cookbook-fixes.patch    # src/ Rust fixes (fetch.rs, staged_pkg.rs, repo.rs, html.rs)
    ├── 003-config.patch            # config/*.toml changes (os-release, hostname, redbear-full)
    └── 004-docs-and-cleanup.patch  # README, CONTRIBUTING, LICENSE, deleted upstream files
```

### Protection Mechanism

1. **Recipe patches** (`kernel/redox.patch`, `base/redox.patch`): Canonical copy lives in
   `local/patches/`. The recipe directory contains a **symlink** to it:
   ```
   recipes/core/kernel/redox.patch → ../../../local/patches/kernel/redox.patch
   recipes/core/base/redox.patch   → ../../../local/patches/base/redox.patch
   ```
   The build system follows symlinks transparently. Patches are never touched by `make clean`
   or `make distclean`. Only `local/` modifications affect them.

2. **Build-system patches**: Generated via `git diff` against the upstream base commit.
   These serve as a backup — the working tree already has patches applied (via git commits).
   If upstream update via rebase fails, these can be applied from scratch.

3. **Custom recipes**: Live entirely in `local/recipes/` with symlinks into `recipes/`:
   ```
   recipes/drivers/linux-kpi       → ../../local/recipes/drivers/linux-kpi
   recipes/gpu/amdgpu              → ../../local/recipes/gpu/amdgpu
   recipes/system/firmware-loader  → ../../local/recipes/system/firmware-loader
   ... etc
   ```

### Scripts

| Script | Purpose |
|--------|---------|
| `local/scripts/apply-patches.sh` | Apply all build-system patches + create recipe symlinks |
| `local/scripts/provision-release.sh` | Provision new release from Redox ref + archive sources |
| `local/scripts/check-upstream-releases.sh` | Check for new Redox snapshots (read-only) |

### Release Model (Fork)

Red Bear OS is a full fork based on frozen Redox snapshots. Sources are immutable
and never auto-immutable archived. The current baseline is 0.1.0.

```bash
# Check for newer Redox snapshots (read-only, zero side effects):
./local/scripts/check-upstream-releases.sh

# Provision a new release (explicit, human-initiated only):
./local/scripts/provision-release.sh --ref=<redox-tag> --release=0.2.0 --dry-run
```

## AMD-FIRST INTEGRATION PATH

See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path plan.

**Target**: AMD64 bare metal, with AMD and Intel machines treated as equal-priority hardware targets.

**amdgpu is 6M+ lines — 18x larger than Intel i915. LinuxKPI compat approach mandatory.**

### Bare Metal Boot Status

| Component | Status | Detail |
|-----------|--------|--------|
| UEFI boot | ✅ | x86_64 bootloader functional |
| AMD CPUs | ✅ | Ryzen Threadripper 128-thread verified |
| ACPI | ✅ Boot-baseline complete | RSDP/SDT checksums, MADT types 0x4/0x5/0x9/0xA, LVT NMI, FADT shutdown/reboot, explicit `RSDP_ADDR` forwarding into `acpid`, x86 BIOS-search AML fallback, and bounded AML-backed power enumeration are present; the explicit AML bootstrap producer contract and broader robustness still remain open — see `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| ACPI shutdown | 🚧 | PM1a/PM1b S5 via `\_S5` AML exists, but shutdown robustness and bounded validation are still open |
| ACPI reboot | 🚧 | Reset register + keyboard controller fallback exist, but broader reboot correctness and bounded validation are still open |
| ACPI power | 🚧 | `\_PS0`/`\_PS3`/`\_PPC` AML methods are available and the runtime power surface performs bounded AML-backed enumeration, but bootstrap preconditions and validation are still too weak for stronger support claims; see `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| x2APIC/SMP | ✅ | Multi-core works |
| IOMMU | 🚧 | QEMU first-use proof now passes; real hardware validation still open |
| AMD GPU | 🚧 | MMIO mapped, bounded Red Bear display glue path builds, MSI-X wired; imported Linux AMD DC/TTM/core remain builds and included in redbear-full (2026-04-29); no hardware validation yet |

### Phased Roadmap (historical P0–P6)

> **Note:** The P0–P6 numbering below is the historical hardware-enablement sequence.
> The canonical current desktop path plan uses a new Phase 1–5 structure documented in
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0, 2026-04-16).

| Phase | Duration | Delivers |
|-------|----------|----------|
| ~~P0: Fix ACPI for AMD~~ | ~~4-6 weeks~~ | ✅ Materially complete — boots on modern AMD bare metal; see `local/docs/ACPI-IMPROVEMENT-PLAN.md` for forward work |
| ~~P1: Driver infrastructure~~ | ~~8-12 weeks~~ | ✅ Complete — redox-driver-sys + linux-kpi + firmware-loader + pcid /config + MSI-X (compiles) |
| ~~P2: AMD GPU display~~ | ~~12-16 weeks~~ | 🚧 Partial — redox-drm + bounded Red Bear AMD display glue build; imported Linux AMD DC/TTM/core remain builds and included in redbear-full (2026-04-29); Intel driver compiles, no HW validation |
| ~~P3: POSIX + input~~ | ~~4-8 weeks~~ | 🚧 Build-side work substantially complete — the active relibc recipe patch chain now carries the bounded fd-event, semaphore, and waitid compatibility surface needed by current downstreams, while broader runtime validation and input-stack maturity remain open |
| P4: Wayland compositor | 4-6 weeks | 🚧 Partial — libwayland/Qt6 Wayland/Mesa EGL+GBM+GLES2/Qt6 OpenGL now build, but compositor/runtime validation is still incomplete |
| ~~P5: DML2 enablement~~ | ~~partial~~ | 🚧 Historical DML2 config work landed, but the current retained AMDGPU build no longer treats imported DML2/TTM as part of the default bounded compile path; libdrm amdgpu ✅, `iommu` daemon now builds; hardware validation still open |
| P6: KDE Plasma | 12-16 weeks | 🚧 In progress — Qt6 ✅, KF6 32/32 ✅, Mesa EGL/GBM/GLES2 ✅, kf6-kcmutils ✅, kf6-kwayland ✅, kdecoration ✅, KWin 🔄 building |

### Canonical Desktop Path (current plan)

The current execution plan uses a three-track model with new Phase 1–5 numbering:
- **Phase 1:** Runtime Substrate Validation (4–6 weeks)
- **Phase 2:** Wayland Compositor Proof (4–6 weeks)
- **Phase 3:** KWin Desktop Session (6–10 weeks)
- **Phase 4:** KDE Plasma Session (8–12 weeks)
- **Phase 5:** Hardware GPU Enablement (12–20 weeks, parallel with 3–4)

See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for full detail.

**Total to software-rendered KDE Plasma**: 22–34 weeks (~6–8 months) with 2 developers.
**Total to hardware-accelerated KDE Plasma**: 34–54 weeks (~8–13 months) with 2 developers.

### Critical Path
```
Phase 1 (runtime substrate) → Phase 2 (software compositor) → Phase 3 (KWin session) → Phase 4 (KDE Plasma)
                               Phase 5 (hardware GPU, parallel with Phases 3–4)
```

### Custom Crates (P1/P2)
1. `redox-driver-sys` — `local/recipes/drivers/redox-driver-sys/source/` — Safe Rust wrappers for scheme:memory, scheme:irq, scheme:pci + hardware quirks system (`src/quirks/`)
2. `linux-kpi` — `local/recipes/drivers/linux-kpi/source/` — C headers translating Linux kernel APIs → redox-driver-sys; includes `pci_get_quirk_flags()` C FFI for quirk queries. **GPU and Wi-Fi drivers only — linux-kpi does NOT cover USB.** It provides PCI, DMA, IRQ, DRM, networking (ieee80211/nl80211/mac80211), firmware, and related kernel infrastructure headers, but contains zero USB headers, USB device ID tables, or USB driver implementations.
3. `redox-drm` — `local/recipes/gpu/redox-drm/source/` — DRM scheme daemon (AMD + Intel drivers); consumes quirk flags for MSI/MSI-X fallback and DISABLE_ACCEL
4. `firmware-loader` — `local/recipes/system/firmware-loader/source/` — scheme:firmware for GPU blobs
5. `amdgpu` — `local/recipes/gpu/amdgpu/source/` — AMD DC C port with linux-kpi compat; can query quirks via `pci_has_quirk()` FFI
6. `redbear-sessiond` — `local/recipes/system/redbear-sessiond/source/` — Rust D-Bus session broker exposing `org.freedesktop.login1` subset for KWin (uses `zbus`)
7. `redbear-dbus-services` — `local/recipes/system/redbear-dbus-services/` — D-Bus activation `.service` files and XML policy files for system and session buses
8. `redbear-power` — `local/recipes/system/redbear-power/source/` — ratatui-based interactive TUI for live CPU/governor/thermal monitoring and on-the-fly P-state / governor / throttle control (Intel MSR-based)

All custom work goes in `local/` — see `local/AGENTS.md` for fork model usage.

## NOTES

- Build requires Linux x86_64 host, 8GB+ RAM, 20GB+ disk
- QEMU used for testing (make qemu). VirtualBox also supported
- The `repo` binary (cookbook CLI) may crash with TUI in non-interactive environments — use `CI=1`
- No git submodules — external repos managed via recipe source URLs and repo manifests
- Historical integration report removed (2026-04-16); see `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for current state

### Stale Prefix Detection

The prefix toolchain (`prefix/x86_64-unknown-redox/`) provides the cross-compiler and relibc
sysroot (`libc.a`, system headers) used by ALL recipe builds. When a local fork (relibc, kernel,
base) gains new commits, the prefix must be rebuilt:

```bash
touch relibc && make prefix    # Rebuild relibc in the cross-toolchain
```

`build-redbear.sh` includes a preflight check that warns when fork commits are newer than
prefix artifacts. **A stale prefix is the #1 cause of "undefined reference" link errors**
after fork changes (e.g., adding `__freadahead` to relibc's `ext.rs` without rebuilding the
prefix).

### relibc Header Circular Includes (Fixed)

relibc's generated headers had a circular include chain that broke gnulib-based packages
(m4, bison, flex, etc.):
```
wchar.h → stdio.h → stdint.h → gnulib inttypes.h → inttypes.h → wchar.h (circular!)
```

**Root cause**: `wchar.h` included `<stdio.h>` before defining `wint_t`/`mbstate_t`, and
`inttypes.h` included `<wchar.h>` instead of `<stdint.h>`+`<stddef.h>` per POSIX spec.

**Fix** (commits `d28963d`, `a2e4cd2`, `826a984f`, `4eabdf20` in `local/sources/relibc/`):
1. `wchar/cbindgen.toml`: Types defined in `after_includes` before `#include <stdio.h>`
2. `inttypes/cbindgen.toml`: `sys_includes = ["stdint.h", "stddef.h"]` (POSIX compliant)
3. **stddef → cbindgen** (`826a984f`, integrates upstream `3be84f4b`):
   - Eliminated hand-written `include/stddef.h` (was missing `wchar_t`)
   - `stddef.h` now generated by cbindgen from `src/header/stddef/cbindgen.toml`
   - Split into modular `bits_*` sub-headers (each can be included independently):
     - `bits/wchar-t.h` — `wchar_t` with `_WCHAR_T` guard + `__WCHAR_TYPE__`
     - `bits/size-t.h` — `size_t` from Rust `usize` via cbindgen `[export]`
     - `bits/null.h` — `NULL`: `nullptr` (C++11), `0L` (C++), `(void *)0` (C)
4. **wchar.h include ordering** (`4eabdf20`):
   - `wint_t` defined BEFORE `#include <stddef.h>` (avoid GCC `__need_wint_t` conflict)
   - Removed redundant `wchar_t` redefinition (now provided by `bits/wchar-t.h`)
5. **stdbool.h POSIX fix** (`4eabdf20`): `#define bool _Bool` replaces non-standard `typedef _Bool bool`

See `local/docs/PACKAGE-BUILD-QUIRKS.md` § relibc Quirk 3 for details.

## WARNING POLICY

When presented with a compiler warning, linker warning, runtime warning, or test warning, the
project treats it as a signal requiring action — not as noise to be silenced or deferred.

- **Investigate** every warning. Understand what causes it and whether it indicates a real defect.
- **Fix the root cause** when feasible. Prefer comprehensive fixes over workarounds.
- **Suppress only as last resort**, with a comment explaining why the warning is known-safe and
  why suppression is the correct choice for that specific case.
- **Never ignore warnings silently.** An unexplained warning in the build is a defect in
  discipline, not just in code.

This applies to all subsystems: kernel, relibc, drivers, userspace daemons, and build tooling.

## SUBSYSTEM PRIORITY AND ORDER

Red Bear OS should treat low-level controllers, USB, Wi-Fi, and Bluetooth as first-class subsystem
targets.

For PCI interrupt plumbing, IRQ delivery quality, MSI/MSI-X follow-up, low-level controller
runtime-proof sequencing, and IOMMU/interrupt-remapping quality, the canonical current plan is:

- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`

Use that file as the execution authority and current robustness judgment for PCI/IRQ work. Higher-
level summaries in `README.md`, `docs/README.md`, and this file should stay aligned with its
validation language rather than acting as competing rollout plans.

Current execution order:

1. low-level controllers / IRQ quality / runtime-proof
2. USB controller and topology maturity
3. Wi-Fi native control-plane and one bounded driver path
4. Bluetooth host/controller path
5. desktop/session compatibility layers on top of those runtime services

Current blocker emphasis:

- low-level controller quality blocks reliable USB and Wi-Fi validation
- USB maturity blocks the realistic first Bluetooth transport path
- Wi-Fi and Bluetooth should not be treated as optional polish; both remain missing subsystem work
  that must be implemented fully, but in the right order