RedBear-OS/local/AGENTS.md

# RED BEAR OS — DERIVATIVE OF REDOX OS

This directory contains ALL custom work on top of mainline Redox. When mainline Redox
updates (`git pull` on the build system repo), this directory is untouched.

## DESIGN PRINCIPLE

Red Bear OS relates to Redox OS in the same way Ubuntu relates to Debian:
  - We track Redox OS as upstream, merging changes regularly
  - We add custom packages, drivers, configs, and branding on top
  - The `local/` directory is our overlay — untouched by upstream updates
  - First-class configs use `redbear-*` naming (not `my-*`, which is gitignored)

Build flow:
```
make all CONFIG_NAME=redbear-desktop
  → mk/config.mk resolves to config/redbear-desktop.toml
  → Config includes desktop.toml (mainline) + Red Bear packages
  → repo cook builds all packages including our custom ones
  → mk/disk.mk creates harddrive.img with Red Bear branding
```

Update flow:
```
./local/scripts/sync-upstream.sh          # Rebase onto upstream Redox + verify symlinks
make all CONFIG_NAME=redbear-full          # Rebuild with latest
```

## TRACKING UPSTREAM (SYNC WITH REDOX OS)

Red Bear OS tracks the Redox OS build system as upstream. The `local/` directory
survives upstream updates untouched.

## SOURCE-OF-TRUTH RULE (VERY IMPORTANT)

Treat the repository as two different layers with different durability guarantees:

### 1. Upstream-owned layer — disposable, refreshable every day

These paths are expected to be replaced, refetched, or regenerated when upstream changes:

- `recipes/*/source/`
- most of `recipes/` outside our symlinked `local/recipes/*` overlays
- `config/desktop.toml`, `config/minimal.toml`, and other mainline configs
- generated build outputs under `target/`, `build/`, `repo/`, and recipe-local `target/*`

For relibc specifically, **`recipes/core/relibc/source/` is upstream-owned working source**, not
Red Bear’s durable storage location. We may build and validate there, but we must not rely on that
tree alone to preserve Red Bear work.

### 2. Red Bear-owned layer — durable, must survive upstream refresh

These paths are our actual long-term source of truth:

- `local/patches/` — all durable changes to upstream-owned source trees
- `local/recipes/` — Red Bear recipe overlays and new packages
- `local/docs/` — Red Bear planning, validation, and integration documentation
- tracked Red Bear configs such as `config/redbear-*.toml`

If we can fetch fresh upstream sources tomorrow, reapply `local/patches/*`, relink
`local/recipes/*`, and rebuild successfully, then the work is in the right place.

If a change exists only inside an upstream-owned `recipes/*/source/` tree, then it is **not yet
preserved**, even if the current build happens to pass.

### Upstream-first rule for fast-moving components

Some components, especially relibc, are actively evolving upstream. For those areas, Red Bear must
prefer the upstream solution whenever upstream already solves the same problem.

That means:

- if our local patch solves a gap that upstream still has, keep the patch carrier
- if upstream lands an equivalent or better solution, prefer upstream and shrink or drop our local patch
- do not keep a Red Bear patch just because it existed first; keep it only while it still provides unique value

For relibc specifically, patch carriers should be treated as **temporary compatibility overlays**,
not a permanent fork strategy.

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.

### Daily-upstream-safe workflow

For any change to upstream-owned source:

1. make the minimal working change in the live source tree if needed for validation
2. prove it builds/tests against the real recipe
3. mirror that delta into `local/patches/<component>/...`
4. update `local/docs/...` so the rebuild/reapply story is explicit
5. assume the live upstream source tree may be thrown away and recreated at any time

The success criterion is therefore:

> We can pull renewed upstream sources every day, reapply Red Bear’s local overlays, and still
> build the project successfully.

```bash
# Automated sync (preferred):
./local/scripts/sync-upstream.sh              # Fetch + rebase + check patches
./local/scripts/sync-upstream.sh --dry-run    # Preview conflicts before rebasing
./local/scripts/sync-upstream.sh --no-merge   # Only check for patch conflicts

# Manual sync:
git remote add upstream-redox https://github.com/redox-os/redox.git  # First time only
git fetch upstream-redox master
git rebase upstream-redox/master

# If rebase fails (nuclear option):
git rebase --abort
git reset --hard upstream-redox/master
./local/scripts/apply-patches.sh --force     # Rebuild Red Bear OS changes from patch files

# After sync:
cargo build --release                         # Rebuild cookbook
make all CONFIG_NAME=redbear-full             # Rebuild OS
```

## STRUCTURE

```
redox-master/                  ← git pull updates mainline Redox
├── config/
│   ├── desktop.toml           ← mainline configs (untouched)
│   ├── minimal.toml
│   ├── redbear-desktop.toml   ← RED BEAR OS configs (first-class, tracked)
│   ├── redbear-minimal.toml
│   └── redbear-live.toml
├── recipes/                   ← mainline package recipes (untouched)
├── mk/                        ← mainline build system (untouched)
├── local/                     ← RED BEAR OS custom work
│   ├── AGENTS.md              ← This file
│   ├── config/                ← Legacy configs (my-*, gitignored)
│   ├── recipes/
│   │   ├── core/              ← ext4d (ext4 filesystem scheme daemon + mkfs tool), grub (GRUB 2.12 UEFI bootloader)
│   │   ├── branding/          ← redbear-release (os-release, hostname, motd)
│   │   ├── drivers/           ← redox-driver-sys, linux-kpi (GPU/Wi-Fi compat only — NOT USB)
│   │   ├── gpu/               ← redox-drm (AMD + Intel display drivers), amdgpu (C port)
│   │   ├── system/            ← cub, evdevd, udev-shim, redbear-firmware, firmware-loader, redbear-hwutils, redbear-info, redbear-netctl, redbear-quirks, redbear-meta
│   │   │   ├── redbear-sessiond    ← org.freedesktop.login1 D-Bus session broker (zbus-based Rust daemon)
│   │   │   ├── redbear-dbus-services ← D-Bus .service activation files + XML policies
│   │   ├── wayland/           ← Wayland compositor (v2.0 Phase 2)
│   │   └── kde/               ← KDE Plasma (v2.0 Phases 3–4)
│   ├── patches/
│   │   ├── kernel/            ← Kernel patches (ACPI, x2APIC)
│   │   ├── base/              ← Base patches (acpid fixes, power methods, pcid /config endpoint)
│   │   ├── relibc/            ← relibc compatibility overlays still needed beyond upstream (eventfd, signalfd, timerfd, waitid, SysV IPC)
│   │   ├── bootloader/        ← Bootloader patches
│   │   └── installer/         ← Installer patches (ext4 filesystem support + GRUB bootloader)
│   ├── Assets/                ← Branding assets (icon, loading background)
│   │   └── images/            ← Red Bear OS icon (1254x1254) + loading bg (1536x1024)
│   ├── firmware/              ← GPU firmware blobs (gitignored, fetched)
│   ├── scripts/
│   │   ├── sync-upstream.sh   ← Sync with upstream Redox OS
│   │   ├── build-redbear.sh   ← Unified Red Bear OS build script
│   │   ├── fetch-firmware.sh  ← Download AMD firmware
│   │   ├── build-amd.sh       ← Legacy AMD-specific build (use build-redbear.sh)
│   │   ├── test-amd-gpu.sh    ← AMD GPU test script
│   │   ├── test-baremetal.sh  ← Bare metal test script
│   │   ├── build-redbear-wifictl-redox.sh ← Build redbear-wifictl for the Redox target with the repo toolchain
│   │   ├── test-iwlwifi-driver-runtime.sh ← Bounded Intel driver lifecycle check inside a target runtime
│   │   ├── test-wifi-control-runtime.sh ← Bounded Wi-Fi control/profile runtime check inside a target runtime
│   │   ├── test-wifi-baremetal-runtime.sh ← Strongest in-repo Wi-Fi runtime check on a real Red Bear target
│   │   ├── validate-wifi-vfio-host.sh ← Host-side VFIO passthrough readiness check for Intel Wi-Fi validation
│   │   ├── prepare-wifi-vfio.sh ← Bind/unbind Intel Wi-Fi PCI function for VFIO validation
│   │   ├── test-wifi-passthrough-qemu.sh ← QEMU/VFIO Wi-Fi validation harness with in-guest checks
│   │   ├── run-wifi-passthrough-validation.sh ← One-shot host wrapper for the full Wi-Fi passthrough validation flow
│   │   ├── package-wifi-validation-artifacts.sh ← Package Wi-Fi validation artifacts into one host-side tarball
│   │   ├── summarize-wifi-validation-artifacts.sh ← Summarize captured Wi-Fi validation artifacts for quick triage
│   │   ├── finalize-wifi-validation-run.sh ← Analyze a Wi-Fi capture bundle and package the final evidence set
│   │   ├── validate-vm-network-baseline.sh ← Static repo-level VM networking baseline check
│   │   ├── test-vm-network-qemu.sh ← QEMU launcher for the VirtIO VM networking baseline
│   │   └── test-vm-network-runtime.sh ← In-guest runtime check for the VM networking baseline
│   └── docs/                  ← Integration docs
```

## HOW TO BUILD RED BEAR OS

```bash
# Full desktop with GPU drivers + branding
./local/scripts/build-redbear.sh redbear-desktop

# Minimal server variant
./local/scripts/build-redbear.sh redbear-minimal

# Live ISO
./local/scripts/build-redbear.sh redbear-live && make live CONFIG_NAME=redbear-live

# VM-network baseline validation helpers
./local/scripts/validate-vm-network-baseline.sh
./local/scripts/test-vm-network-qemu.sh redbear-minimal
# Then run inside the guest:
#   ./local/scripts/test-vm-network-runtime.sh

# Phase 1 desktop-substrate validation (v2.0 plan: relibc headers, evdevd, udev-shim,
# firmware-loader, DRM/KMS, health-check — covers 6 acceptance areas)
./local/scripts/test-phase1-desktop-substrate.sh --qemu redbear-wayland

# Legacy Phase 3 runtime-substrate validation (historical P0-P6 numbering; script still works)
./local/scripts/test-phase3-runtime-substrate.sh --qemu redbear-desktop

# Low-level controller validation
./local/scripts/test-xhci-irq-qemu.sh --check
./local/scripts/test-msix-qemu.sh
./local/scripts/test-iommu-qemu.sh
./local/scripts/test-usb-storage-qemu.sh
./local/scripts/test-usb-qemu.sh --check

# The current xHCI proof checks for an interrupt-driven mode in boot logs.
# The current MSI-X proof uses the live virtio-net path in QEMU.
# The current IOMMU proof runs a guest-driven first-use self-test and checks that discovered
# AMD-Vi units initialize and drain events successfully in QEMU.
# The USB storage proof currently verifies whether usbscsid autospawns without hitting crash-class errors.

# Legacy Phase 4 Wayland runtime validation (historical P0-P6 numbering; script still works)
./local/scripts/build-redbear.sh redbear-wayland
./local/scripts/test-phase4-wayland-qemu.sh
# Then run inside the guest:
#   redbear-phase4-wayland-check

# Legacy Phase 5 desktop/network plumbing validation (historical P0-P6 numbering; script still works)
./local/scripts/build-redbear.sh redbear-full
./local/scripts/test-phase5-network-qemu.sh --check
# Then run inside the guest:
#   redbear-phase5-network-check

# Bounded Intel Wi-Fi runtime validation (real target or passthrough guest)
# Host preparation for VFIO-backed guests:
#   sudo ./local/scripts/validate-wifi-vfio-host.sh --host-pci 0000:xx:yy.z --expect-driver iwlwifi
#   sudo ./local/scripts/prepare-wifi-vfio.sh bind 0000:xx:yy.z
# Guest/target packaged checks:
#   redbear-phase5-wifi-check
#   redbear-phase5-wifi-link-check
#   redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json
#   redbear-phase5-wifi-capture wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json
#   redbear-phase5-wifi-analyze /tmp/redbear-phase5-wifi-capture.json
# Helper scripts:
#   ./local/scripts/test-wifi-baremetal-runtime.sh
#   ./local/scripts/test-wifi-passthrough-qemu.sh --host-pci 0000:xx:yy.z --check --capture-output ./wifi-passthrough-capture.json
#   ./local/scripts/finalize-wifi-validation-run.sh ./wifi-passthrough-capture.json ./wifi-passthrough-artifacts.tar.gz

# Legacy Phase 6 KDE session-surface validation (historical P0-P6 numbering; script still works)
./local/scripts/build-redbear.sh redbear-kde
./local/scripts/test-phase6-kde-qemu.sh --check
# Then run inside the guest:
#   redbear-phase6-kde-check

# redbear-netctl user-facing alias
redbear-netctl --help

# Or manually:
make all CONFIG_NAME=redbear-desktop

# Single custom recipe:
./target/release/repo cook local/recipes/branding/redbear-release
./target/release/repo cook local/recipes/system/redbear-meta
./target/release/repo cook local/recipes/core/ext4d
./target/release/repo cook local/recipes/core/grub  # GRUB bootloader (host build, produces EFI binary)

# GRUB boot manager (installer-native, Phase 2):
make r.grub                                                   # Build GRUB recipe
make all CONFIG_NAME=redbear-full-grub                        # Build with GRUB chainload
# Linux-compatible CLI (add local/scripts to PATH):
grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img
grub-mkconfig -o local/recipes/core/grub/grub.cfg
# Or legacy post-build script:
./local/scripts/install-grub.sh build/x86_64/harddrive.img    # Modify existing image
```

## TRACKING MAINLINE CHANGES

When mainline updates affect our work:

| Component | What to check | Where |
|-----------|---------------|-------|
| Kernel | ACPI, scheme, memory API changes | `recipes/core/kernel/source/src/` |
| relibc | New POSIX functions added upstream | `recipes/core/relibc/source/src/header/` |
| Base drivers | Driver API changes | `recipes/core/base/source/drivers/` |
| libdrm | DRM API updates | `recipes/wip/x11/libdrm/` or `recipes/libs/` |
| Mesa | OpenGL/Vulkan backend changes | `recipes/libs/mesa/` |
| Build system | Makefile/config changes | `mk/`, `src/` |
| rsext4 | ext4 crate API changes | `local/recipes/core/ext4d/source/` Cargo.toml |
| Installer | ext4 dispatch, filesystem selection, GRUB bootloader | `local/patches/installer/redox.patch` |
| Quirks | New Linux quirk entries to port | `local/recipes/drivers/redox-driver-sys/source/src/quirks/` |

## PLANNING NOTES

- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` is the canonical public execution plan.
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0) is the canonical desktop path plan from console to
  hardware-accelerated KDE Plasma on Wayland, using a three-track Phase 1–5 model.
- `local/docs/AMD-FIRST-INTEGRATION.md` remains the deeper AMD-specific technical roadmap, but AMD
  and Intel machines are now equal-priority Red Bear OS targets.
- `local/docs/PHASE-0-3-REASSESSMENT.md` is deprecated — its reconciliation role is now covered by the
  updated CONSOLE-TO-KDE-DESKTOP-PLAN.md and docs/07.
- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` is the current Wi-Fi architecture and rollout plan,
  including the bounded role of `linux-kpi` and the native wireless control-plane direction.
- `local/docs/USB-IMPLEMENTATION-PLAN.md` and `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` should
  also be treated as first-class subsystem plans, not as side notes.
- `local/docs/WIFI-VALIDATION-RUNBOOK.md` is the canonical operator runbook for bare-metal and
  VFIO-backed Intel Wi-Fi validation, packaged checkers, and capture artifacts.
- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` is the current umbrella plan for
  IRQ delivery, MSI/MSI-X quality, IOMMU validation, and other low-level controller completeness work.
- `local/docs/QUIRKS-SYSTEM.md` documents the hardware quirks infrastructure: compiled-in tables,
  TOML runtime files, DMI matching, driver integration, and the linux-kpi C FFI bridge.
- `local/docs/QUIRKS-IMPROVEMENT-PLAN.md` is the current follow-up plan for removing quirks drift,
  integrating quirks into real drivers, and converging on one source of truth.
- `local/docs/DBUS-INTEGRATION-PLAN.md` is the canonical D-Bus architecture and implementation plan for KDE Plasma 6 on Wayland. It defines the phased approach to D-Bus service integration, the `redbear-sessiond` login1-compatible session broker, and the gap analysis for desktop-facing D-Bus services.

The current execution order for these subsystem plans is:

1. IRQ / low-level controller quality
2. USB maturity
3. Wi-Fi native control plane and first driver family
4. Bluetooth controller + host path
5. desktop/session compatibility on top of those runtime services

Do not present USB, Wi-Fi, Bluetooth, or low-level controller work as optional or secondary.

## FILESYSTEMS

Red Bear OS supports three filesystems:

| Filesystem | Implementation | Package | Status |
|------------|---------------|---------|--------|
| RedoxFS | Mainline Redox (default) | `recipes/core/redoxfs` | ✅ Stable |
| ext4 | rsext4 0.3 crate + ext4d scheme daemon | `local/recipes/core/ext4d` | ✅ Compiles + Installer wired |
| FAT (VFAT) | fatfs 0.3.6 crate + fatd scheme daemon | `local/recipes/core/fatd` | ✅ Compiles + Tools tested + label write verified |

### ext4 Workspace (`local/recipes/core/ext4d/source/`)

```
ext4d/source/
├── Cargo.toml              ← Workspace: ext4-blockdev, ext4d, ext4-mkfs
├── ext4-blockdev/           ← BlockDevice trait impls for rsext4
│   ├── Cargo.toml           ← Features: default=["redox"], redox=[libredox,syscall]
│   └── src/
│       ├── lib.rs           ← Re-exports: FileDisk, RedoxDisk, Ext4Error, Ext4Result
│       ├── file_disk.rs     ← FileDisk: std::fs backed, builds on host Linux + Redox
│       └── redox_disk.rs    ← RedoxDisk: syscall/libredox backed, Redox-only (feature-gated)
├── ext4d/                   ← ext4 filesystem scheme daemon (Redox userspace)
│   ├── Cargo.toml           ← Features: default=["redox"], redox deps
│   └── src/
│       ├── main.rs          ← Daemon: fork, SIGTERM, scheme registration
│       ├── mount.rs         ← Scheme event loop (redox_scheme::SchemeSync)
│       ├── scheme.rs        ← Full ext4 FSScheme: open, read, write, mkdir, unlink, stat...
│       └── handle.rs        ← FileHandle, DirectoryHandle, Handle types
└── ext4-mkfs/               ← ext4 mkfs tool (host-side utility)
    ├── Cargo.toml
    └── src/main.rs          ← Creates ext4 images via FileDisk + rsext4::mkfs
```

**Architecture**:
- `ext4d` is a Redox scheme daemon — it serves ext4 filesystems via `scheme:ext4d`
- Uses `rsext4` crate (pure Rust ext4 implementation) for all filesystem operations
- `FileDisk` allows building/testing on the Linux host machine
- `RedoxDisk` uses `libredox` + `redox_syscall` for actual Redox bare-metal I/O
- Both impls are behind the `redox` feature flag — `--no-default-features` gives Linux-only

**Recipe**: Symlinked into mainline search path:
```
recipes/core/ext4d → local/recipes/core/ext4d
```

**Config**: ext4d is included in `config/desktop.toml` (mainline), which `redbear-desktop.toml` inherits.

**Dependencies** (from workspace Cargo.toml):
- `rsext4 = "0.3"` — Pure Rust ext4 filesystem implementation
- `redox_syscall = "0.7.3"` — Redox syscall wrappers (scheme, data types, flags)
- `redox-scheme = "0.11.0"` — Scheme server framework
- `libredox = "0.1.13"` — High-level Redox syscalls (open, read, write, fstat)
- `redox-path = "0.3.0"` — Redox path utilities

### Installer ext4 + GRUB Integration (`local/patches/installer/redox.patch`)

The mainline installer is patched to support ext4 as an install target filesystem and
GRUB as an alternative boot manager:
- `GeneralConfig.filesystem: Option<String>` — TOML field, accepts `"redoxfs"` (default) or `"ext4"`
- `GeneralConfig.bootloader: Option<String>` — TOML field, accepts `"redox"` (default) or `"grub"`
- `FilesystemType` enum — dispatch tag used by `install_inner`
- `with_whole_disk_ext4()` — GPT partition layout + ext4 mkfs + file sync (mirrors `with_whole_disk`)
- `Ext4SliceDisk<T>` — adapts `DiskWrapper` to rsext4's `BlockDevice` trait
- `sync_host_dir_to_ext4()` — copies staged sysroot files into ext4 filesystem
- GRUB chainload: when `bootloader = "grub"`, writes GRUB EFI + grub.cfg to ESP alongside Redox bootloader
- CLI flags: `--filesystem ext4` / `--bootloader grub`

Usage in config TOML:
```toml
[general]
filesystem = "ext4"        # "redoxfs" is default
bootloader = "grub"        # "redox" is default
efi_partition_size = 16    # Required for GRUB (default 1 MiB is too small)
filesystem_size = 10240    # MB
```

See `local/docs/GRUB-INTEGRATION-PLAN.md` for the full GRUB architecture and usage guide.

### FAT (VFAT) Workspace (`local/recipes/core/fatd/source/`)

```
fatd/source/
├── Cargo.toml              ← Workspace: fat-blockdev, fatd, fat-mkfs, fat-label, fat-check
├── fat-blockdev/            ← Block device adapter for fatfs crate
│   ├── src/lib.rs           ← Re-exports: FileDisk (always), RedoxDisk (feature-gated)
│   ├── src/file_disk.rs     ← FileDisk: std::fs::File → Read+Write+Seek
│   └── src/redox_disk.rs    ← RedoxDisk: libredox → Read+Write+Seek (redox feature)
├── fatd/                    ← FAT filesystem scheme daemon (Redox userspace)
│   ├── src/main.rs          ← Daemon: fork, SIGTERM, dispatch to FileDisk/RedoxDisk
│   ├── src/mount.rs         ← Scheme event loop (redox_scheme::SchemeSync)
│   ├── src/scheme.rs        ← FatScheme: full FSScheme (open/read/write/mkdir/unlink/stat...)
│   └── src/handle.rs        ← FileHandle, DirectoryHandle, Handle types
├── fat-mkfs/                ← mkfs.fat equivalent (create FAT12/16/32 filesystems)
│   └── src/main.rs
├── fat-label/               ← fatlabel equivalent (read + write volume labels via BPB)
│   └── src/main.rs          ← `-s "LABEL"` writes label at BPB offset 43/71; verifies round-trip
└── fat-check/               ← fsck.fat equivalent (verify BPB, FAT chains, directory tree + safe repair)
    └── src/main.rs          ← `--repair` clears dirty flag, fixes FSInfo, reclaims lost clusters
```

**Architecture**: `fatd` is a Redox scheme daemon using `fatfs` v0.3.6 (MIT, no_std capable).
FAT is for data volumes and ESP only — NOT for root filesystem.
`fscommon::BufStream` wraps block device for mandatory caching.

**Recipe**: Symlinked into mainline search path:
```
recipes/core/fatd → ../../local/recipes/core/fatd
```

**Config**: Packages included via `config/redbear-device-services.toml` (inherited by
`redbear-desktop.toml` and `redbear-full.toml`). Init service at
`/usr/lib/init.d/15_fatd.service`.

**Dependencies**: fatfs 0.3.6, fscommon 0.1.1, redox_syscall, redox-scheme, libredox, libc

**Tool verification status** (2026-04-17):
- `fat-mkfs`: ✅ Creates FAT12/16/32, labels, auto-detection, cluster size option (`-c`), tested up to 1GB
- `fat-label`: ✅ Reads labels; writes BPB + creates/updates root-directory volume-label entry; verifies round-trip on all FAT types (including previously unlabeled volumes)
- `fat-check`: ✅ BPB validation, boot signature check, directory tree walk, cluster stats; ✅ safe repair (dirty flag including FAT12, FSInfo, lost clusters, orphaned LFN). Handles 0xFFFFFFFF FSInfo sentinel on fresh images.
- `fatd`: ✅ Compiles (links on Redox target only — expected). ✅ `frename` + rmdir non-empty check implemented. NOT runtime-tested (requires QEMU/bare metal).
- Phase 4 (runtime auto-mount): Deferred to runtime validation. Static init service exists.
- Known limitation: fatfs v0.3.6 strictly requires `total_sectors_16 == 0` for FAT32, rejecting some Linux `mkfs.fat` images
- `cargo test`: 60 unit tests (25 scheme + 7 label + 28 check) + 13+ integration edge cases

## BRANDING ASSETS

Red Bear OS visual identity files live in `local/Assets/`.

```
local/Assets/
└── images/
    ├── Red Bear OS icon.png              ← App icon / logo (1254x1254px)
    │                                        Red bear head, dark background, red border
    │                                        Use: desktop icon, bootloader logo, about dialog
    └── Red Bear OS loading background.png ← Boot / loading screen (1536x1024px)
                                             Cinematic red bear with forest silhouette
                                             Use: bootloader splash, login screen background
```

**Integration points** (future):
| Asset | Target | How |
|-------|--------|-----|
| icon.png | Bootloader logo | Convert to BMP, embed via bootloader config |
| icon.png | Desktop icon | Install to `/usr/share/icons/hicolor/` via redbear-release recipe |
| icon.png | About dialog | COSMIC desktop reads from icon theme |
| loading background.png | Boot splash | Convert to framebuffer-compatible format, display before orbital starts |
| loading background.png | Login screen | Set as orblogin/orbital background |

**Current status**: Assets are committed to git. Not yet integrated into the build — requires bootloader and display server integration (P2 hardware validation).

## ANTI-PATTERNS

- **DO NOT** edit files under mainline `recipes/` directly — put patches in `local/patches/`
- **DO NOT** commit firmware blobs to git — use `local/scripts/fetch-firmware.sh`
- **DO NOT** modify `mk/` or `src/` directly — extend via `local/scripts/`
- **DO NOT** assume mainline recipe names won't conflict — prefix custom ones (e.g., `redox-`)
- **DO NOT** use `my-*` naming for configs that should be tracked in git — use `redbear-*` instead
- **DO NOT** edit config/base.toml directly — our configs include it and override via TOML merge
- **DO NOT** forget to run sync-upstream.sh before major builds — stale upstream causes build failures

## RED BEAR OS CONFIG HIERARCHY

```
redbear-live.toml
  └── redbear-desktop.toml
        ├── redbear-legacy-base.toml   ← Neutralize broken base legacy init scripts
        ├── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
        ├── redbear-netctl.toml        ← Shared Red Bear network profile files + netctl boot service
        ├── desktop.toml (mainline)
        │     ├── desktop-minimal.toml
        │     │     └── minimal.toml
        │     │           └── base.toml
        │     └── server.toml
        │           └── minimal.toml
        │                 └── base.toml
        └── [packages] redbear-release, redbear-hwutils, redbear-netctl,
                       firmware-loader, evdevd, udev-shim, redbear-info,
                       mc, cub
        NOTE: ext4d is inherited from desktop.toml (mainline package)
        NOTE: cub is treated as an essential Red Bear utility and is included through the tracked
              flavor configs; it still depends on the custom recipe symlink
              (recipes/system/cub → local/recipes/system/cub) being created by
              integrate-redbear.sh or apply-patches.sh before building.
        NOTE: redbear-netctl provides a Redox-native `netctl` command with profiles
              in /etc/netctl and a boot-time `netctl --boot` service.
        NOTE: redbear-info is the canonical runtime integration report. Keep it updated when
              Red Bear adds new tools, schemes, services, or hardware integration paths.
        NOTE: redbear-live inherits cub through redbear-desktop.toml.
        NOTE: redbear-meta is explicitly included in redbear-full.toml. Keep any broader inclusion
              deliberate because its dependency surface is much heavier than the core utility layer.

redbear-full.toml
  └── desktop.toml (mainline)
  └── redbear-legacy-base.toml     ← Neutralize broken base legacy init scripts
  └── redbear-legacy-desktop.toml  ← Neutralize broken desktop legacy init scripts
  └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
  └── redbear-netctl.toml          ← Shared Red Bear network profile files + netctl boot service

redbear-wayland.toml
  └── wayland.toml (mainline-derived Wayland profile)
  └── runtime surface: orbital-wayland → smallvil
  └── validation entrypoints: test-phase4-wayland-qemu.sh + redbear-phase4-wayland-check

redbear-kde.toml
  └── desktop.toml (mainline)
  └── redbear-legacy-base.toml     ← Neutralize broken base legacy init scripts
  └── redbear-legacy-desktop.toml  ← Neutralize broken desktop legacy init scripts
  └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
  └── redbear-netctl.toml          ← Shared Red Bear network profile files + netctl boot service

redbear-minimal.toml
  └── minimal.toml (mainline)
        └── base.toml
  └── redbear-legacy-base.toml     ← Neutralize broken base legacy init scripts
  └── redbear-device-services.toml ← Shared firmware-loader / evdevd / udev service wiring
  └── redbear-netctl.toml          ← Shared Red Bear network profile files + netctl boot service
  └── [packages] redbear-release, redbear-hwutils, redbear-netctl,
                 firmware-loader, evdevd, udev-shim, redbear-info
```

Config comparison:
| Config | GPU Stack | Desktop | Branding | ext4d | filesystem_size |
|--------|-----------|---------|----------|-------|-----------------|
| redbear-desktop | Full | COSMIC | Yes | ✅ (via desktop.toml) | 10240 MiB |
| redbear-minimal | None | None | Yes | ❌ | 512 MiB |
| redbear-live | Full | COSMIC | Yes | ✅ (via desktop.toml) | 12288 MiB |