Refresh subsystem planning docs

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

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

local/docs/AMD-FIRST-INTEGRATION.md

@@ -1,7 +1,12 @@
 # AMD-FIRST REDOX OS — MASTER INTEGRATION PLAN
 
-**Target**: Modern AMD64 bare metal machine with AMD GPU (RDNA2/RDNA3)
+> **Status note (2026-04-14):** This document remains the detailed AMD-focused hardware roadmap,
-**Secondary**: Intel GPU machines
+> but it is no longer the repository-wide platform-priority policy. Red Bear OS should now treat
+> AMD and Intel machines as equal-priority targets. Read this file as the deeper AMD-specific plan,
+> not as a statement that Intel is secondary going forward.
+
+**Target**: AMD64 bare metal machine with AMD GPU (RDNA2/RDNA3), within an overall Red Bear OS
+hardware policy that treats AMD and Intel machines as equal-priority targets.
 **Date**: 2026-04-11
 
 ## CRITICAL FINDINGS
@@ -14,8 +19,9 @@
 | i915 (Intel) | ~341,000 | Well-documented, simpler |
 | nouveau (NVIDIA) | ~400,000 | Community driver |
 
-**Implication**: AMD-first is HARDER but has larger market impact. We MUST use
+**Implication**: The AMD path is HARDER but still important. For AMD-class Linux GPU and related
-the LinuxKPI compatibility approach — a clean Rust rewrite would take 5+ years.
+device enablement, we MUST use the LinuxKPI compatibility approach — a clean Rust rewrite would
+take 5+ years.
 
 ### AMD Bare Metal Status on Redox
 
@@ -26,7 +32,7 @@ the LinuxKPI compatibility approach — a clean Rust rewrite would take 5+ years
 | ACPI | ✅ Complete | RSDP/SDT checksums, MADT types 0x4/0x5/0x9/0xA, LVT NMI, FADT shutdown/reboot |
 | x2APIC | ✅ Works | Auto-detected via CPUID, APIC/SMP functional |
 | HPET | ✅ Works | Timer initialized from ACPI |
-| IOMMU | 🚧 Buildable, unvalidated | `iommu` daemon now builds, but no VT-d/AMD-Vi hardware validation yet |
+| IOMMU | 🚧 In progress | `iommu` daemon now builds, auto-discovers common IVRS table paths, reaches unit detection plus `scheme:iommu` registration in the QEMU/AMD-IOMMU validation path, and now has a guest-driven first-use self-test that reaches MMIO reads; the remaining blocker is a CPU-side completion/DMA-page fault during init, and real hardware validation is still missing |
 | AMD GPU | 🚧 In progress | MMIO mapped, DC port compiles, MSI-X wired, no hardware validation yet |
 | Wi-Fi/BT | ❌ Missing | No wireless support |
 | USB | ⚠️ Variable | Some USB controllers work, others don't |
@@ -327,6 +333,10 @@ Currently libdrm has `-Damdgpu=disabled`. Enable it once redox-drm exists.
 
 ## PHASE 5: AMD GPU ACCELERATION (16-24 weeks, parallel with P4)
 
+> Note: this AMD-first Phase 5 is a hardware-driver track. It is **not** the same thing as the
+> canonical public `docs/07` Phase 5, which is about wired networking and desktop/session
+> integration.
+
 ### P5-1: Full amdgpu Port via LinuxKPI
 
 This is the big one. Port the full amdgpu driver using linux-kpi headers.
@@ -403,7 +413,7 @@ P0 (ACPI boot)
 
 | Document | Change |
 |----------|--------|
-| `AGENTS.md` (root) | Add AMD-first strategy, local/ overlay refs |
+| `AGENTS.md` (root) | Keep equal-priority AMD/Intel hardware policy visible; keep local/ overlay refs |
 | `recipes/core/AGENTS.md` | Add AMD boot requirements, IOMMU note |
 | `recipes/wip/AGENTS.md` | Add AMD GPU driver WIP section |
 | `docs/AGENTS.md` | Add reference to local/docs/ |

local/docs/NETWORKING-RTL8125-NETCTL.md

@@ -80,10 +80,21 @@ base networking services have started.
   `redbear-minimal`: `pcid-spawner` → `smolnetd` → `dhcpd` → `netctl --boot` → `wired-dhcp`.
 - `./local/scripts/test-vm-network-qemu.sh` launches a VirtIO-backed QEMU run for the same Phase 2
   baseline and prints the in-guest validation commands to run.
+  On x86_64 hosts it now fails fast unless usable OVMF/edk2 UEFI firmware is installed, because
+  otherwise the helper can fall through a misleading BIOS/iPXE boot path before Red Bear OS ever
+  starts.
 - `./local/scripts/test-vm-network-runtime.sh` is the in-guest check for the same baseline: it
   verifies `/scheme/pci`, `/scheme/netcfg`, the active netctl profile, visible `network.*`
   schemes, and the current `eth0` address.
 
+During reassessment, the QEMU/UEFI VM baseline reached a real guest login prompt and
+`redbear-info --json` reported:
+
+- `virtio_net_present: true`
+- configured `eth0` address `10.0.2.15/24`
+- default route via `10.0.2.2`
+- visible `network.pci-0000-00-03.0_virtio_net` scheme
+
 ## Remaining hardware validation
 
 This repo change set wires RTL8125 through the native path, but real hardware validation is still

local/docs/USB-IMPLEMENTATION-PLAN.md

@@ -34,11 +34,14 @@ and a low-level userspace client API through `xhcid_interface`.
 
 The current limitations are material:
 
-- xHCI still runs in polling mode because interrupt support is disabled
+- xHCI no longer hard-forces polling; it uses the existing interrupt-mode selection path again, but
+  interrupt-driven behavior is still only lightly validated under runtime load
+- checked-in event-ring growth support now exists, but it still needs stronger runtime validation
 - USB support varies by machine, including known `xhcid` panic cases
 - hub/topology handling is partial
 - HID is still wired through the legacy mixed-stream `inputd` path
-- USB mass storage exists in-tree, but default autospawn is disabled because it causes xHCI errors
+- USB mass storage exists in-tree and autospawn is now re-enabled for validation, but the current
+  blocker has moved to post-spawn runtime stability rather than driver matching.
 - there is no evidence of validated support for broader USB classes or modern USB-C / dual-role
   scope
 
@@ -47,10 +50,10 @@ The current limitations are material:
 | Area | State | Notes |
 |---|---|---|
 | Host mode | **usable / experimental** | Real host-side stack exists, but not broadly validated |
-| xHCI controller | **builds / enumerates / usable on some hardware** | Polling mode, hardware-variable, not fully corrected |
+| xHCI controller | **builds / enumerates / usable on some hardware** | Interrupt-mode selection restored, hardware-variable, event-ring growth exists in-tree but still needs stronger runtime validation |
 | Hub handling | **builds / partial usable** | `usbhubd` exists, USB 3 hub limitations remain |
 | HID | **builds / usable in narrow path** | `usbhidd` handles keyboard/mouse/button/scroll via legacy input path |
-| Mass storage | **builds** | `usbscsid` exists, but default autospawn is disabled |
+| Mass storage | **builds / autospawns in QEMU** | `usbscsid` now spawns from the xHCI class-driver table, but runtime stability past spawn still needs work |
 | Native tooling | **builds / enumerates** | `lsusb`, `usbctl`, `redbear-info` provide partial observability |
 | Low-level userspace API | **builds** | `xhcid_interface` exists, but not a mature general userspace USB story |
 | libusb | **builds / experimental** | WIP, compiled but not tested |
@@ -84,10 +87,9 @@ The current limitations are material:
 - `HARDWARE.md` says USB support varies by machine and records systems where USB input or USB more
   broadly does not work, plus known `xhcid` panic cases
 - `local/docs/AMD-FIRST-INTEGRATION.md` marks USB as **variable**
-- `recipes/core/base/source/drivers/usb/xhcid/src/main.rs` forces polling mode and leaves
+- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/irq_reactor.rs` now contains event-ring growth logic, but the restored interrupt path still needs stronger validation under sustained runtime load
-  interrupt setup disabled with `TODO: Fix interrupts.`
+- `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` now re-enables USB SCSI autospawn with
-- `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` comments out USB SCSI autospawn with
+  explicit protocol matching for BOT (`0x50`)
-  `#TODO: causes XHCI errors`
 - `recipes/core/base/source/drivers/COMMUNITY-HW.md` still claims there is no Redox xHCI driver,
   which means inherited USB docs cannot be treated as uniformly current
 
@@ -99,7 +101,7 @@ The current limitations are material:
 
 Current repo-visible issues include:
 
-- polling-mode operation instead of interrupt-driven behavior
+- partially restored interrupt-driven behavior without complete event-ring growth support
 - incorrect or incomplete speed handling for child devices
 - TODOs around configuration choice and alternate settings
 - TODOs around endpoint selection across interfaces
@@ -126,8 +128,9 @@ per-device streams, and explicit hotplug events.
 
 ### 4. Storage is present in-tree but not a current support claim
 
-`usbscsid` is a real driver, but the current xHCI class-driver table disables the SCSI-over-USB
+`usbscsid` is a real driver and the xHCI class-driver table now spawns it again during QEMU USB
-autospawn path because it causes XHCI errors.
+storage validation. The current blocker is not matching or spawn, but transport/runtime stability
+after spawn.
 
 That means Red Bear should document USB storage as **implemented in-tree but not currently enabled
 as a default working class path**.
@@ -276,7 +279,7 @@ family.
 
 **What to do**:
 
-- repair and re-enable USB mass-storage autospawn
+- stabilize USB mass-storage after autospawn (BOT transport / SCSI runtime path)
 - decide whether BOT-only is sufficient short-term or whether UAS is part of the next step
 - bring `libusb` to a runtime-tested state or explicitly replace it with a Red Bear-native API
   strategy

local/docs/WIFI-IMPLEMENTATION-PLAN.md

@@ -0,0 +1,402 @@
+# Red Bear OS Wi-Fi Implementation Plan
+
+## Purpose
+
+This document defines the current Wi-Fi state in Red Bear OS and lays out the recommended path for
+integrating Wi-Fi drivers and a usable wireless control plane.
+
+The goal is not to imply that Wi-Fi already exists in-tree. The goal is to describe what the repo
+currently proves, what `linux-kpi` can and cannot realistically provide, and how Red Bear can grow
+from **no Wi-Fi support** to one experimental, validated Wi-Fi path that fits the existing Redox /
+Red Bear architecture.
+
+## Validation States
+
+- **builds** — code exists in-tree and is expected to compile
+- **boots** — image or service path reaches a usable runtime state
+- **reports** — runtime surfaces can honestly report current wireless state
+- **validated** — behavior has been exercised with real evidence for the claimed scope
+- **experimental** — available for bring-up, but not support-promised
+- **missing** — no in-tree implementation path is currently present
+
+This repo should not treat planned wireless scope as equivalent to implemented support.
+
+## Current Repo State
+
+### Summary
+
+Wi-Fi is currently **missing** in Red Bear OS.
+
+There is no in-tree Wi-Fi driver, no wireless daemon, no cfg80211/mac80211/nl80211-compatible
+surface, no supplicant path, and no profile that can honestly claim Wi-Fi support.
+
+What the repo *does* have is a meaningful set of prerequisites:
+
+- userspace drivers and schemes as the standard architectural model
+- `redox-driver-sys` for PCI/MMIO/IRQ/DMA primitives
+- `linux-kpi` as a limited low-level C-driver compatibility layer
+- `firmware-loader` for blob-backed devices
+- a working native wired network path through `network.*`, `smolnetd`, `dhcpd`, and `netcfg`
+- profile/package-group discipline, including the reserved `net-wifi-experimental` slice
+
+### Current Status Matrix
+
+| Area | State | Notes |
+|---|---|---|
+| Wi-Fi controller support | **missing** | No PCIe/USB/SDIO Wi-Fi driver recipes in-tree |
+| Linux wireless stack compatibility | **missing** | No cfg80211/mac80211/nl80211/wiphy support in `linux-kpi` |
+| Firmware loading | **partial prerequisite exists** | `firmware-loader` can serve firmware blobs generically |
+| Wireless control plane | **missing** | No scan/auth/association/link-state daemon or CLI |
+| Post-association IP path | **present** | Native `smolnetd` / `netcfg` / `dhcpd` / `redbear-netctl` path exists |
+| Desktop Wi-Fi API | **missing** | No NetworkManager-like or D-Bus Wi-Fi surface |
+| Runtime diagnostics | **partial prerequisite exists** | `redbear-info` model exists, but no Wi-Fi integration exists |
+
+## Evidence Already In Tree
+
+### Direct negative evidence
+
+- `HARDWARE.md` says Wi-Fi and Bluetooth are not supported yet
+- `local/docs/AMD-FIRST-INTEGRATION.md` marks `Wi-Fi/BT` as missing
+
+### Positive driver-side prerequisites
+
+- `docs/04-LINUX-DRIVER-COMPAT.md` documents `redox-driver-sys`, `linux-kpi`, and
+  `firmware-loader`
+- `local/recipes/drivers/redox-driver-sys/` provides userspace PCI/MMIO/IRQ/DMA primitives
+- `local/recipes/drivers/linux-kpi/` provides a limited Linux-style compatibility subset
+- `local/recipes/system/firmware-loader/` provides `scheme:firmware`
+
+### Positive network/control-plane prerequisites
+
+- `local/docs/NETWORKING-RTL8125-NETCTL.md` documents the native wired path:
+  `pcid-spawner` → NIC daemon → `network.*` → `smolnetd` → `dhcpd` / `netcfg`
+- `recipes/core/base/source/netstack/src/scheme/netcfg/mod.rs` shows route/address/resolver state
+  is already exposed through a native control scheme
+- `local/recipes/system/redbear-netctl/source/src/main.rs` shows Red Bear already uses a native
+  network profile tool, even though it is currently wired-only
+- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` reserves `net-wifi-experimental` as a package-group
+  slot for future wireless work
+
+## Feasibility Constraints
+
+### 1. Wi-Fi is not just a driver
+
+Wi-Fi in Red Bear cannot be treated as a single hardware daemon.
+
+At minimum, a working Wi-Fi path needs:
+
+- hardware transport and firmware bring-up
+- scan/discovery
+- authentication and association state
+- link-state and disconnect handling
+- credential storage
+- post-association handoff into the native IP stack
+- later desktop/user-facing integration if the repo wants it
+
+This makes Wi-Fi more like a complete subsystem than a simple wired NIC driver.
+
+### 2. `linux-kpi` is feasible only below the wireless control-plane boundary
+
+Current `linux-kpi` is suitable for low-level driver-enablement work such as:
+
+- PCI / IRQ / DMA / MMIO access
+- firmware request glue
+- workqueue-style helper logic
+- C-driver compatibility for narrow hardware bring-up
+
+Current `linux-kpi` is **not** a complete Wi-Fi architecture because the repo has no in-tree:
+
+- cfg80211
+- mac80211
+- nl80211
+- wiphy model
+- supplicant/control-plane compatibility layer
+
+So `linux-kpi` is feasible only as a **partial low-level aid**, not as the primary Red Bear Wi-Fi
+stack.
+
+### 3. The current Red Bear control plane is Ethernet-specific
+
+The current native network stack is useful, but not yet Wi-Fi-ready.
+
+`redbear-netctl` only supports:
+
+- `Connection=ethernet`
+- `Interface=eth0`
+- DHCP/static address, route, and DNS control
+
+`netcfg` is similarly hard-wired around the current `eth0` interface model.
+
+That means Red Bear can reuse its native IP plumbing **after association**, but not as the radio
+control plane itself.
+
+### 4. FullMAC is a better first target than SoftMAC
+
+The first Wi-Fi target should minimize the amount of 802.11 MAC and Linux wireless subsystem logic
+that Red Bear has to recreate.
+
+That makes **FullMAC** hardware the best first target class.
+
+Red Bear should explicitly avoid starting with SoftMAC/mac80211-style Linux drivers such as:
+
+- Intel `iwlwifi`
+- Realtek `rtw88` / `rtw89`
+- MediaTek `mt76`
+- other drivers that fundamentally assume cfg80211/mac80211 semantics
+
+## Recommended Architecture
+
+The best Red Bear Wi-Fi architecture is:
+
+1. **native Red Bear wireless control plane**
+2. **one experimental FullMAC driver family first**
+3. **reuse `redox-driver-sys` + `firmware-loader` directly**
+4. **use `linux-kpi` only where it reduces low-level glue cost**
+5. **reuse the existing native IP path only after association**
+
+This is a hybrid architecture, but it is **native-first**, not Linux-stack-first.
+
+### Subsystem boundary
+
+The Wi-Fi subsystem should be split into these pieces:
+
+- one **device transport / driver daemon** for the chosen chipset family
+- one **firmware loading path** via `firmware-loader`
+- one **Wi-Fi control daemon** for scan/auth/association/link state
+- one **user-facing control tool** (`wifictl` or equivalent)
+- one **post-association handoff** into `smolnetd` / `netcfg` / `dhcpd`
+- one **later desktop shim** only if KDE/user-facing workflows require it
+
+`redbear-netctl` should **not** become the supplicant. It can remain the post-association IP
+profile tool, or be generalized later, but it should not own scan/auth/association itself.
+
+## Hardware Strategy
+
+### First decision gate
+
+Before implementation begins, Red Bear must choose **one** first Wi-Fi family from actual target
+machines or bring-up hardware.
+
+The preferred target order is:
+
+1. **PCIe FullMAC** — if a real Red Bear target machine in the hardware matrix has one
+2. **USB FullMAC** — if PCIe FullMAC hardware is not available, use this as the first prototype path
+
+### What not to choose for phase 1
+
+Do not start with:
+
+- Intel laptop Wi-Fi via `iwlwifi`
+- mac80211/cfg80211-dependent Linux drivers
+- any phase-1 scope that requires recreating a Linux wireless stack first
+
+## Security Scope Freeze
+
+### Phase-1 supported security
+
+- open networks
+- WPA2-PSK
+
+### Explicitly out of initial scope
+
+- WPA3
+- 802.1X / enterprise Wi-Fi
+- AP mode
+- roaming
+- monitor mode
+- suspend/resume guarantees
+- multi-BSS support
+- sophisticated regulatory-domain handling
+
+This scope freeze is required to keep the first milestone honest and achievable.
+
+## Comprehensive Full Plan
+
+### Phase W0 — Scope Freeze and Package-Group Definition
+
+**Goal**: Define the first Wi-Fi milestone precisely before implementation starts.
+
+**What to do**:
+
+- choose one target FullMAC family from actual hardware
+- freeze security scope to open + WPA2-PSK
+- define `net-wifi-experimental` as the package-group slice for first Wi-Fi support
+- document unsupported wireless features explicitly
+
+**Exit criteria**:
+
+- one hardware family is selected
+- support language and non-goals are written down
+
+---
+
+### Phase W1 — Driver Substrate Fit
+
+**Goal**: Prove the chosen Wi-Fi family can fit Red Bear’s existing driver primitives.
+
+**What to do**:
+
+- map the chosen device family onto `redox-driver-sys`
+- verify firmware naming and fetch path through `firmware-loader`
+- decide whether any narrow `linux-kpi` glue is useful for that family
+- keep `linux-kpi` below the wireless control-plane boundary
+
+**Exit criteria**:
+
+- one chosen device can be discovered, initialized, and paired with its firmware-loading path
+
+---
+
+### Phase W2 — Native Wireless Control Plane
+
+**Goal**: Add a Red Bear-native wireless daemon and control interface.
+
+**What to do**:
+
+- implement a Wi-Fi daemon that owns:
+  - scan state
+  - auth/association state
+  - link state
+  - disconnect/retry behavior
+  - credential ownership
+- add a user-facing `wifictl`-style control surface
+
+**What not to do**:
+
+- do not push supplicant logic into `redbear-netctl`
+- do not model Wi-Fi as “just another Ethernet profile” at this phase
+
+**Exit criteria**:
+
+- the daemon can report scan results and current link state honestly
+
+---
+
+### Phase W3 — Network Stack Refactor for Post-Association Handoff
+
+**Goal**: Make the native IP stack accept Wi-Fi as a first-class post-association interface.
+
+**What to do**:
+
+- generalize current `eth0` / Ethernet assumptions where needed
+- allow the native stack to consume a post-association Wi-Fi interface state
+- keep route/address/DNS handling in native `netcfg` / `smolnetd` plumbing after association
+
+**Exit criteria**:
+
+- a connected Wi-Fi link can be handed off to the existing IP path without pretending it is merely a
+  raw Ethernet control-plane object
+
+---
+
+### Phase W4 — First Association Milestone
+
+**Goal**: Achieve one real Wi-Fi connection under the frozen phase-1 scope.
+
+**What to do**:
+
+- scan for one real SSID
+- join one test network
+- complete open or WPA2-PSK association
+- hand off to DHCP or static IP configuration
+
+**Exit criteria**:
+
+- one chosen device family reaches usable network connectivity on a real network
+
+---
+
+### Phase W5 — Runtime Reporting and Recovery
+
+**Goal**: Make Wi-Fi support diagnosable and honest.
+
+**What to do**:
+
+- extend `redbear-info` with Wi-Fi-specific runtime reporting
+- add reconnect and failure-state reporting
+- keep all support labels experimental
+
+**Exit criteria**:
+
+- users can see whether hardware is present, firmware is loaded, scans succeed, and association has
+  succeeded or failed
+
+---
+
+### Phase W6 — Desktop Compatibility (Later)
+
+**Goal**: Add desktop-oriented control only after native Wi-Fi works.
+
+**What to do**:
+
+- if KDE or desktop workflows require it, add a small compatibility shim over the native Wi-Fi
+  service
+- keep that shim above the native control plane, not in place of it
+
+**Exit criteria**:
+
+- desktop Wi-Fi workflows become possible without changing the native subsystem boundaries
+
+---
+
+### Phase W7 — Broader Hardware and `linux-kpi` Reassessment
+
+**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one FullMAC path works.
+
+**What to do**:
+
+- only after one FullMAC family is validated, decide whether a wider SoftMAC / deeper `linux-kpi`
+  path is worth the cost
+- do not assume this is automatically justified
+
+**Exit criteria**:
+
+- Red Bear either keeps the narrow native-first architecture, or consciously chooses a larger Linux
+  wireless-compat effort with full awareness of the cost
+
+## Validation Gates
+
+Wi-Fi should not be described as supported until these gates are passed in order:
+
+1. hardware is detected
+2. firmware loads successfully
+3. the driver/daemon initializes and reports link state
+4. scan sees a real SSID
+5. association succeeds for one supported network type
+6. DHCP or static IP handoff succeeds through the native network stack
+7. reconnect works after disconnect or reboot
+8. `redbear-info` and profile docs report supported and unsupported states honestly
+
+Until then, support language should remain under `net-wifi-experimental` only.
+
+## Support-Language Guidance
+
+Until the validation gates above are passed, Red Bear should use language such as:
+
+- “Wi-Fi is not supported yet”
+- “Wi-Fi remains experimental and hardware-specific”
+- “The current wireless path is an experimental FullMAC-first bring-up”
+
+Avoid language such as:
+
+- “Linux Wi‑Fi drivers are supported”
+- “wireless support works”
+- “Wi-Fi is generally available”
+
+unless profile-scoped validation evidence exists.
+
+## Summary
+
+The best Red Bear Wi-Fi path is **native-first**:
+
+- native wireless control plane
+- one experimental FullMAC family first
+- `firmware-loader` + `redox-driver-sys` underneath
+- optional narrow `linux-kpi` glue only where useful
+- native `smolnetd` / `netcfg` / `redbear-netctl` reused only after association
+
+`linux-kpi` is therefore **feasible only in a narrow sense**. It is useful as a low-level helper
+for driver bring-up, but it is not currently a viable full Wi‑Fi architecture for Red Bear OS.
+
+That is the most realistic way to integrate Wi‑Fi into Red Bear while keeping the design aligned
+with the repo’s current userspace-driver and profile-based architecture.