Refresh project documentation

Red Bear OS Team
2026-04-16 12:46:07 +01:00
parent aeac5a6d92
commit 90fa45c545
32 changed files with 1659 additions and 167 deletions
@@ -133,7 +133,7 @@ redox-master/                  ← git pull updates mainline Redox
 │   │   ├── branding/          ← redbear-release (os-release, hostname, motd)
 │   │   ├── drivers/           ← redox-driver-sys, linux-kpi
 │   │   ├── gpu/               ← redox-drm (AMD + Intel display drivers), amdgpu (C port)
-│   │   ├── system/            ← cub, evdevd, udev-shim, firmware-loader, redbear-hwutils, redbear-info, redbear-netctl, redbear-meta
+│   │   ├── system/            ← cub, evdevd, udev-shim, redbear-firmware, firmware-loader, redbear-hwutils, redbear-info, redbear-netctl, redbear-meta
 │   │   ├── wayland/           ← Wayland compositor (Phase 4)
 │   │   └── kde/               ← KDE Plasma (Phase 6)
 │   ├── patches/
@@ -152,6 +152,17 @@ redox-master/                  ← git pull updates mainline Redox
 │   │   ├── 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
@@ -187,7 +198,8 @@ redox-master/                  ← git pull updates mainline Redox

 # 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 checks for the AMD IOMMU device plus guest boot reachability.
+# 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.

 # Phase 4 Wayland runtime validation
@@ -202,6 +214,21 @@ redox-master/                  ← git pull updates mainline Redox
 # 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
+
 # Phase 6 KDE session-surface validation
 ./local/scripts/build-redbear.sh redbear-kde
 ./local/scripts/test-phase6-kde-qemu.sh --check
@@ -247,6 +274,8 @@ When mainline updates affect our work:
  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.

@@ -20,15 +20,16 @@ P0 ACPI work is **complete**. Kernel patch is 574 lines, base/acpid patch is 558
 | DSDT (Differentiated System Description Table) | Parsed by `acpi` crate AML interpreter | Working | Platform-specific device config via AML bytecode |
 | SSDT (Secondary System Description Table) | Parsed by `acpi` crate AML interpreter | Working | Secondary AML tables (hotplug, etc.) |
 | FACP/FADT | ✅ Full parse in acpid | ✅ Done | PM registers, reset register, sleep states, `\_S5` |
-| IVRS (AMD-Vi IOMMU) | Removed (broken stub) | Deferred to P5+ | Needs real AMD IOMMU implementation |
+| IVRS (AMD-Vi IOMMU) | Removed from acpid stub path | Handled by `iommu` daemon path | ACPI-side broken stub removed; runtime AMD-Vi handling now lives in the separate daemon |
 | MCFG (PCI Express config space) | Removed (broken stub) | ✅ Handled by pcid | pcid /config endpoint provides direct PCI config space access |
 | DBG2 (Debug port) | Not implemented | Low | Serial debug port discovery |
 | BGRT (Boot graphics) | Not implemented | Low | Boot logo preservation |
 | FPDT (Firmware perf data) | Not implemented | Low | Boot performance metrics |

-IVRS was previously listed as "implemented" but the stub was broken. It has been removed
-from acpid. IVRS needs a real AMD IOMMU driver (P5+ scope). MCFG is now handled by
-pcid's /config endpoint (P1 complete) which provides direct PCI config space access.
+IVRS was previously listed as "implemented" but the acpid stub was broken, so it was removed from
+acpid. AMD-Vi runtime handling now lives in the separate `iommu` daemon path rather than in acpid.
+MCFG is now handled by pcid's /config endpoint (P1 complete) which provides direct PCI config space
+access.

 ## Implemented ACPI Tables

@@ -32,9 +32,9 @@ 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 | 🚧 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 |
+| 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 initializes both discovered units and drains events successfully in QEMU; 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 |
+| Wi-Fi/BT | 🚧 In progress | Repo now carries bounded wireless scaffolding: one experimental in-tree Bluetooth slice exists, and a bounded Intel Wi-Fi scaffold exists elsewhere, but validated wireless connectivity support is still incomplete |
 | USB | ⚠️ Variable | Some USB controllers work, others don't |

 ### Known AMD-Specific Issues
@@ -129,7 +129,9 @@ local/recipes/system/firmware-loader/
 | SMC | Power management | `smu_*_bin.bin` |
 | DMCUB | Display controller | `dcn_*_dmcub.bin` |

-**Storage**: `local/firmware/amdgpu/` (fetched via `local/scripts/fetch-firmware.sh`)
+**Storage**: staged into `/lib/firmware/amdgpu/` for runtime loading. The current local helper
+script still fetches AMD blobs from linux-firmware, but the runtime path should now be read as
+`/lib/firmware/amdgpu/`, not `/usr/firmware/amdgpu/`.

 ### P1-3: linux-kpi Compatibility Headers

@@ -2,13 +2,13 @@

 ## Purpose

-This document defines the current Bluetooth state in Red Bear OS and lays out a conservative,
-implementation-focused roadmap for adding Bluetooth support.
+This document defines the current Bluetooth state in Red Bear OS, assesses what the repo now proves
+through its bounded first slice, and lays out the conservative roadmap beyond that slice.

-The goal is not to imply that Bluetooth already exists in-tree. The goal is to describe what the
-repo currently proves, what it does not prove, and how Red Bear can grow from **no Bluetooth
-support** to a realistic, host-side Bluetooth stack that fits the existing Redox/Red Bear
-architecture.
+The goal is to describe what the repo currently proves, what it does not prove, what parts of the
+Bluetooth stack are credible versus not credible today, and how Red Bear can grow from **one
+bounded experimental Bluetooth slice** toward broader support without overstating current runtime
+validation.

 ## Validation States

@@ -24,10 +24,28 @@ This repo should not treat planned scope as equivalent to implemented support.

 ### Summary

-Bluetooth is currently **missing** in Red Bear OS.
+Broad Bluetooth support is still **missing** in Red Bear OS, but the repo now carries one bounded
+experimental first slice.

-The repo has no first-class Bluetooth daemon, no controller transport path, no host stack, no
-documented app-facing Bluetooth API, and no profile that can honestly claim Bluetooth support.
+That bounded slice is now **QEMU-validated for its claimed scope** through the packaged
+`redbear-bluetooth-battery-check` helper and the host-side
+`./local/scripts/test-bluetooth-qemu.sh --check` harness. That validation is still narrow and does
+not promote the repo to generic Bluetooth maturity.
+
+That first in-tree slice is deliberately narrow:
+
+- standalone profile: `config/redbear-bluetooth-experimental.toml`
+- transport daemon: `local/recipes/drivers/redbear-btusb/`
+- host/control daemon: `local/recipes/system/redbear-btctl/`
+- packaged in-guest checker: `redbear-bluetooth-battery-check`
+- host QEMU harness: `local/scripts/test-bluetooth-qemu.sh`
+- startup model: explicit startup only
+- transport model: USB-attached only
+- protocol scope: BLE-first only
+- autospawn model: **not** wired to USB-class autospawn yet
+
+This does **not** mean Red Bear has broad Bluetooth support. It means the repo now has one
+experimental, profile-scoped bring-up surface instead of zero in-tree Bluetooth components.

 What the repo *does* have is enough adjacent infrastructure to make a Bluetooth port plausible:

@@ -37,24 +55,41 @@ What the repo *does* have is enough adjacent infrastructure to make a Bluetooth
 - D-Bus plumbing for later desktop compatibility work
 - an evolving input and hotplug model that could later absorb Bluetooth HID devices

+### Feasibility Summary
+
+Implementing Bluetooth from scratch in Red Bear is **possible**, but only in a narrow, staged
+sense.
+
+The currently credible interpretation is:
+
+- **feasible**: one experimental USB-attached controller path, one native host daemon, one BLE-first
+  workload, one CLI/control surface, one hardware-specific validation slice
+- **not yet credible**: broad controller coverage, full classic-Bluetooth parity, Bluetooth audio,
+  or a desktop-equivalent BlueZ replacement in the first pass
+
+So the answer is not “Bluetooth from scratch is unrealistic,” but it is also not “Bluetooth is just
+one more driver.” The feasible first target is a deliberately small subsystem slice.
+
 ### Current Status Matrix

 | Area | State | Notes |
 |---|---|---|
-| Bluetooth controller support | **missing** | No HCI transport daemon in-tree |
-| Bluetooth host stack | **missing** | No L2CAP / ATT / SMP / GATT / RFCOMM stack evidence |
-| Pairing / bond database | **missing** | No Bluetooth-specific persistence path documented |
+| Bluetooth controller support | **experimental bounded slice** | `redbear-btusb` provides explicit-startup USB transport probing/status plus a daemon path that is now exercised repeatedly in QEMU for the bounded Battery Level slice |
+| Bluetooth host stack | **experimental bounded slice** | `redbear-btctl` provides a BLE-first CLI/scheme surface with stub-backed scan plus bounded connect/disconnect control for stored bond IDs; the packaged checker now reruns that slice repeatedly and covers daemon-restart honesty in QEMU |
+| Pairing / bond database | **experimental bounded slice** | `redbear-btctl` now persists conservative stub bond records under `/var/lib/bluetooth/<adapter>/bonds/`; connect/disconnect control targets those records, and the checker now verifies cleanup honesty, but this is still storage/control plumbing only, not real pairing or generic reconnect validation |
 | Desktop Bluetooth API | **missing** | D-Bus exists generally, but no Bluetooth API/service exists |
 | Bluetooth HID | **missing** | Could later build on input modernization work |
 | Bluetooth audio | **missing** | Also blocked by broader desktop audio compatibility work |
-| Runtime diagnostics | **partial prerequisite exists** | `redbear-info` model exists, but no Bluetooth integration exists |
+| Runtime diagnostics | **partial implemented** | `redbear-info` now reports the bounded Bluetooth transport/control surfaces conservatively |

 ## 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
+- `HARDWARE.md` says broad Wi-Fi and Bluetooth support is still incomplete even though bounded
+  in-tree scaffolding now exists
+- `local/docs/AMD-FIRST-INTEGRATION.md` treats `Wi-Fi/BT` as in progress with bounded wireless
+  scaffolding present but validated connectivity still incomplete

 ### Positive architectural prerequisites

@@ -64,6 +99,8 @@ What the repo *does* have is enough adjacent infrastructure to make a Bluetooth
  profile-scoped and evidence-backed
 - `local/docs/PROFILE-MATRIX.md` defines the validation-language model a future Bluetooth path must
  use
+- `local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md` now records the canonical QEMU operator path for the
+  current bounded Battery Level slice
 - `local/docs/INPUT-SCHEME-ENHANCEMENT.md` shows the direction of travel for per-device, hotplug,
  named input sources, which is relevant to later Bluetooth HID support
 - `config/redbear-kde.toml` and related profile wiring already show D-Bus and desktop-session
@@ -86,7 +123,22 @@ At minimum, Red Bear would need:

 This makes Bluetooth more like networking than like a single peripheral driver.

-### 1.1 Minimum Native Subsystem Shape
+### 1.1 From-Scratch Scope Reality
+
+Starting from zero, the minimum Red Bear-native Bluetooth stack is still several layers:
+
+- controller transport
+- HCI command/event handling
+- adapter management
+- LE scanning and connection lifecycle
+- pairing / bonding policy and persistence
+- ATT/GATT client work for the first useful BLE workload
+- some observable user control/reporting surface
+
+That means “from scratch” should be read as “new native subsystem assembly from several bounded
+components,” not as “write a single daemon and call Bluetooth done.”
+
+### 1.2 Minimum Native Subsystem Shape

 The smallest Red Bear-native Bluetooth subsystem should be split into these pieces:

@@ -109,7 +161,26 @@ The repo's existing system model strongly favors:
 That means Bluetooth should be implemented as a native Red Bear subsystem, not described as a
 wholesale Linux/BlueZ drop-in.

-### 2.1 Repo Placement Guidance
+### 2.1 BlueZ-equivalent replacement is not the first feasible target
+
+Red Bear should not frame the initial work as “reimplement BlueZ.”
+
+That would pull in a much larger surface:
+
+- broad controller/transport coverage
+- full classic + BLE host functionality
+- stable D-Bus compatibility shape
+- profile breadth beyond the first bounded use case
+- much more policy and persistence behavior than the repo currently needs for an initial milestone
+
+The first feasible target is instead:
+
+- native Red Bear controller transport daemon
+- native Red Bear host daemon
+- small native CLI/control path
+- later compatibility shim only if real desktop consumers require one
+
+### 2.2 Repo Placement Guidance

 Unless upstream Redox grows a first-class Bluetooth path first, the initial Red Bear work should
 live under `local/`:
@@ -133,7 +204,21 @@ The first realistic milestone is much smaller:
 - one limited workload
 - experimental support language only

-### 3.1 First-Milestone Dependency
+### 3.1 BLE-first is materially more feasible than classic-first
+
+The repo should treat **BLE-first** as the credible from-scratch path.
+
+Why:
+
+- it keeps the first useful workload smaller
+- it avoids early pressure for classic-audio and broader profile parity
+- it matches the repo's current “bounded experimental slice first” discipline
+- it reduces the amount of early compatibility behavior that must be correct before any user value
+  appears
+
+Classic Bluetooth should therefore be treated as a later expansion, not as the first milestone.
+
+### 3.2 First-Milestone Dependency

 If the first supported controller is USB-attached, then Bluetooth Phase B1 depends directly on the
 USB plan's controller and hotplug baseline work.
@@ -142,6 +227,18 @@ In practice that means Bluetooth should not claim a validated first controller p
 stack can already support that controller family with stable enumeration, attach/detach behavior,
 and honest runtime diagnostics.

+### 3.3 Most credible first controller family
+
+The most credible first controller family is:
+
+- one **USB-attached BLE-capable adapter family** with simple host-facing initialization behavior
+
+The least credible early targets are:
+
+- UART-attached laptop-integrated controllers that require new board-specific transport bring-up
+- broad “internal laptop Bluetooth” claims across mixed Intel/Realtek/MediaTek controller families
+- controller families that immediately force a large firmware and vendor-protocol surface
+
 ### 4. Bluetooth scope depends on adjacent subsystems

 Bluetooth HID depends on the modernized input path.
@@ -152,6 +249,60 @@ unfinished for desktop use.
 That means the Bluetooth roadmap must stay sequenced and should not over-promise audio or broad
 desktop integration early.

+### 4.1 Native host-side Bluetooth is still required even if transport uses compatibility glue
+
+The Wi-Fi plan already establishes an important repo rule: a compatibility layer can be useful below
+the subsystem boundary, but it does not remove the need for a native Red Bear control plane.
+
+Bluetooth should follow the same rule.
+
+That means:
+
+- transport-side glue or borrowed implementation ideas are acceptable
+- but adapter management, support language, diagnostics, persistence, and user-visible control
+  should still be modeled as native Red Bear runtime services
+
+### 4.2 Bluetooth is gated more by USB maturity than by D-Bus presence
+
+The repo already has D-Bus packages, but that does **not** make Bluetooth close to done.
+
+The more important blockers are still:
+
+- low-level controller/runtime trust
+- USB controller correctness and hotplug quality
+- a first real transport path
+- native host-daemon correctness
+
+So Bluetooth feasibility should be tied to controller/runtime credibility first, and only later to
+desktop compatibility.
+
+## Recommended From-Scratch Interpretation
+
+The currently recommended interpretation of “implement Bluetooth from scratch” in this repo is:
+
+1. do **not** start by chasing broad desktop Bluetooth parity
+2. do **not** start by promising internal laptop Bluetooth across all machines
+3. do start with one USB-attached adapter family
+4. do build one native controller transport daemon plus one native host daemon
+5. do target one BLE-first workflow
+6. do keep all support language experimental and hardware-specific until real runtime proof exists
+
+This is the narrowest version of “from scratch” that is still technically meaningful and worth
+shipping.
+
+## Recommended First Deliverable
+
+The first deliverable Red Bear should actually target is:
+
+- one standalone `redbear-bluetooth-experimental` profile slice
+- one USB Bluetooth transport daemon
+- one host/control daemon with bounded scan/status reporting
+- one CLI-oriented control path
+- one BLE-first workflow boundary
+- one validation helper script plus one named runtime surface contract
+
+That is small enough to be plausible and large enough to count as real Bluetooth work.
+
 ## Implementation Plan

 ### Repo-fit note
@@ -169,7 +320,7 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov

 **What to do**:

- declare Bluetooth support as absent today
+- declare broad Bluetooth support as incomplete today while one bounded experimental slice exists
 - define validation labels and support language for future Bluetooth work
 - freeze the first milestone as **host-side, experimental, one controller family, one limited use
  case**
@@ -193,7 +344,7 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov

 **Recommended first target**:

- one USB-attached Bluetooth controller family
+- one USB-attached Bluetooth controller family, BLE-first

 **Why**:

@@ -206,6 +357,8 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov
 - implement one controller transport daemon
 - expose adapter presence and basic control through a Red Bear-native runtime surface
 - ensure the daemon fits the userspace service/scheme model
+- keep the first daemon/controller contract narrow enough that the host daemon can be built around
+  one stable transport instead of a generic multi-transport abstraction from day one

 **Where**:

@@ -222,6 +375,8 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov
  once a Bluetooth USB class match is ready
 - before that exists, the first milestone may use explicit Red Bear service startup so the transport
  daemon can be validated without pretending that USB class autospawn is already solved
+- the first in-tree slice now follows exactly that bounded rule: explicit startup only, with no
+  claim that `xhcid` or another USB class matcher autospawns Bluetooth yet
 - if Red Bear adds that xHCI class match before it exists upstream, it should be carried as a Red
  Bear base patch rather than as an unqualified direct tree edit

@@ -241,6 +396,8 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov

 - one supported Bluetooth controller can be detected and initialized repeatedly
 - controller presence can be reported honestly at runtime
+- attach/detach behavior is good enough that controller disappearance does not require reboot to
+  recover the service path

 ---

@@ -254,6 +411,7 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov
 - support scanning and connect/disconnect for one limited workload
 - add persistent pairing/bond storage only once the storage path is explicitly defined
 - keep the control surface small and Red Bear-native
+- keep classic-Bluetooth scope and audio/profile breadth explicitly out of this phase

 **Where**:

@@ -270,9 +428,20 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov
 - bond database lifecycle rooted at `/var/lib/bluetooth/`
 - failure reporting suitable for later `redbear-info` integration

+**Current in-tree bounded slice**:
+
+- `redbear-btctl` now ships a minimal file-backed bond store rooted at `/var/lib/bluetooth/<adapter>/bonds/`
+- the CLI can add/list/remove **stub** bond records and reload them across process restarts
+- the btctl scheme now exposes bounded connect/disconnect control plus read surfaces for connection state and last connect/disconnect results
+- the bounded connect path only targets existing stub bond records and keeps connected bond IDs in daemon memory per adapter
+- `redbear-info` now reports the bond-store path/count plus bounded connection/result metadata conservatively
+- this is explicitly **not** real pairing, link-key exchange, trusted-device policy, validated reconnect behavior, real device traffic, or B3 BLE workload support
+
 **Exit criteria**:

 - the daemon can rediscover and reconnect to at least one target device class across repeated runs
+- the daemon's runtime state is observable enough that future `redbear-info` integration is
+  straightforward rather than guesswork

 ---

@@ -283,23 +452,39 @@ not a recommendation to edit upstream-managed trees outside Red Bear's normal ov
 **Recommended first workload**:

 - BLE-first rather than full classic Bluetooth parity
+- specifically, one experimental **battery-sensor Battery Level read** using Battery Service
+  `0000180f-0000-1000-8000-00805f9b34fb` and Battery Level characteristic
+  `00002a19-0000-1000-8000-00805f9b34fb`
+
+**Examples of acceptable first workloads**:
+
+- one BLE sensor/control workflow
+- one bounded BLE peripheral interaction that needs scan/connect/read/write/notify
+
+**Examples of bad first-workload choices**:
+
+- generic “all BLE works”
+- Bluetooth audio
+- broad HID support before the input plan matures

 **What to do**:

 - add scan/connect support for one BLE device type
- expose minimal read/write/notify behavior if the chosen workload needs it
+- expose only the minimal behavior the chosen workload needs
+- for the current B3 slice, that means **read only** for the experimental battery-sensor workload;
+  this slice does **not** claim write support or notify support
 - keep support language experimental and hardware-specific

 **Where**:

 - host-daemon implementation under `local/recipes/system/`
- package-group wiring in one explicitly experimental Red Bear package-group slice named
-  `bluetooth-experimental`
+- tracked profile wiring in one explicitly experimental Red Bear profile slice named
+  `redbear-bluetooth-experimental`
 - validation helper in `local/scripts/`

 **Recommended support slice**:

- start as one explicitly experimental package-group addition named `bluetooth-experimental`
+- start as one explicitly experimental tracked profile named `redbear-bluetooth-experimental`
  rather than claiming Bluetooth generically across all Red Bear images

 **Exit criteria**:
@@ -393,8 +578,8 @@ expects them instead of importing a whole foreign subsystem model blindly.

 **Recommended first support language**:

- one explicitly experimental Red Bear package-group slice named `bluetooth-experimental` for the
-  first supported controller + workload combination
+- one explicitly experimental Red Bear profile named `redbear-bluetooth-experimental` for the first
+  supported controller + workload combination

 **Where**:

@@ -408,13 +593,19 @@ expects them instead of importing a whole foreign subsystem model blindly.
 - at least one profile can honestly claim validated experimental Bluetooth support for named
  hardware and named workload scope

+**Current in-tree interpretation**:
+
+- the repo now satisfies the narrower QEMU-scoped version of this exit criterion for one packaged,
+  stub-backed Battery Level workload on `redbear-bluetooth-experimental`
+- it does **not** satisfy a broader real-hardware or generic BLE exit criterion yet
+
 ## Support-Language Guidance

 Until B1 through B3 exist, Red Bear should use language such as:

- “Bluetooth is not supported yet”
- “Bluetooth remains missing in-tree”
- “Bluetooth is a future implementation workstream”
+- “Bluetooth is not broadly supported yet”
+- “only the bounded experimental Bluetooth slice exists in-tree”
+- “Bluetooth remains a future implementation workstream beyond the documented first slice”

 Once B1 through B3 begin to land, prefer:

@@ -431,11 +622,26 @@ unless the repo has profile-scoped validation evidence to justify those claims.

 ## Summary

-Bluetooth in Red Bear today is not partial support — it is **missing**.
+Bluetooth in Red Bear today is still not broad support.
+
+What now exists is one bounded experimental first slice: explicit-startup, USB-attached,
+BLE-first, profile-scoped to `redbear-bluetooth-experimental`, with conservative stub bond-store
+persistence rooted at `/var/lib/bluetooth/<adapter>/bonds/` plus bounded connect/disconnect control
+that only targets those stored stub bond IDs, plus one experimental battery-sensor Battery Level
+read result for the exact Battery Service / Battery Level UUID pair above. That slice can now be
+built, booted in QEMU, exercised by the packaged `redbear-bluetooth-battery-check` helper, rerun in
+one boot, and rerun after a clean reboot without changing the bounded support claim.

 What makes it feasible is not any existing Bluetooth stack, but the surrounding Red Bear
 architecture: userspace daemons, runtime services, diagnostic discipline, profile-scoped support
-language, and an evolving per-device input model.
+language, firmware/runtime-service patterns, and an evolving per-device input model.
+
+The practical feasibility judgment is:
+
+- **yes**, Bluetooth from scratch is possible in Red Bear
+- **but only** as a bounded BLE-first, transport-constrained, experimental subsystem slice
+- **and no**, the current repo does not justify treating broad Bluetooth or desktop Bluetooth parity
+  as a near-term from-scratch target

 That means the right Bluetooth implementation plan is conservative and staged:

@@ -0,0 +1,96 @@
+# Red Bear OS Bluetooth Validation Runbook
+
+This runbook is the canonical operator path for exercising the current bounded Bluetooth Battery
+Level slice on Red Bear OS.
+
+It does **not** claim that Bluetooth is broadly solved. Its job is to make the current
+profile-scoped, QEMU-validated Battery Level workload reproducible and honest.
+
+## Goal
+
+Produce one or both of the following:
+
+- a successful bounded Bluetooth validation run via `redbear-bluetooth-battery-check`
+- a repeatable QEMU/UEFI validation log via `./local/scripts/test-bluetooth-qemu.sh --check`
+
+## Path A - Host-side QEMU validation
+
+Use this when the host supports the repo's normal x86_64 QEMU/UEFI flow.
+
+### On the host
+
+Build the tracked Bluetooth profile first:
+
+```bash
+./local/scripts/build-redbear.sh redbear-bluetooth-experimental
+```
+
+Then run the automated QEMU harness:
+
+```bash
+./local/scripts/test-bluetooth-qemu.sh --check
+```
+
+What that harness does today:
+
+1. boots `redbear-bluetooth-experimental` in QEMU with `qemu-xhci`
+2. logs in automatically on the serial console
+3. runs `redbear-bluetooth-battery-check` twice in one boot
+4. reboots the guest
+5. runs `redbear-bluetooth-battery-check` again after the clean reboot
+
+### Artifact to preserve
+
+- the full terminal log from `./local/scripts/test-bluetooth-qemu.sh --check`
+- any serial or CI log captured around the run
+
+## Path B - Interactive guest validation
+
+Use this when you want to inspect the runtime manually inside the guest.
+
+### On the host
+
+```bash
+./local/scripts/test-bluetooth-qemu.sh
+```
+
+### Inside the guest
+
+Run the packaged checker directly:
+
+```bash
+redbear-bluetooth-battery-check
+```
+
+The legacy guest helper remains as a compatibility wrapper:
+
+```bash
+test-bluetooth-runtime.sh
+```
+
+Useful supporting commands inside the guest:
+
+```bash
+redbear-btusb --status
+redbear-btctl --status
+redbear-info --verbose
+```
+
+## What success means today
+
+Current success is still **bounded** success:
+
+- the explicit-startup `redbear-btusb` and `redbear-btctl` path can be exercised in QEMU
+- the packaged checker can be rerun repeatedly in one boot
+- the checker covers daemon restart cleanup and disconnect stale-state cleanup within the current
+  Battery Level slice
+- the exact Battery Service / Battery Level UUID pair can be read through the bounded read-only
+  workload and reported conservatively by `redbear-info`
+
+This is **not yet** the same as:
+
+- real controller bring-up proof
+- generic BLE or generic GATT maturity
+- write support or notify support
+- real pairing or broad reconnect semantics
+- desktop Bluetooth parity, HID, audio, or passthrough-backed hardware claims
@@ -43,7 +43,7 @@ stack are runtime-trusted rather than just build-visible?”
 | Qt6 core stack | **builds** | `qtbase`, `qtdeclarative`, `qtsvg`, `qtwayland` are in-tree build surfaces |
 | KF6 frameworks | **mixed but strong build progress** | many frameworks build; some higher-level pieces still rely on bounded or reduced recipes |
 | KWin / Plasma session | **experimental / incomplete runtime** | recipe/config wiring exists, but runtime trust still trails build success |
-| Mesa / hardware graphics path | **partial** | software path exists; hardware-validated Wayland graphics path still lags |
+| Mesa / hardware graphics path | **partial** | software path exists; current QEMU validation still shows llvmpipe, and hardware-validated Wayland graphics path still lags |
 | Input stack | **build-visible and partly wired** | `evdevd`, `libevdev`, `libinput`, `seatd` are present, but runtime trust is still narrower than full desktop support |
 | D-Bus session/system plumbing | **builds / wired into profiles** | present in desktop-facing profiles, but not equal to full desktop integration completeness |

@@ -96,6 +96,23 @@ That gap is the main thing older docs sometimes blur.

 The software-rendered stack is much further along than the hardware-validated stack.

+Current QEMU truth:
+
+- the tracked `redbear-wayland` test harness still uses `-vga std`
+- the live compositor path currently reports `GL Renderer: "llvmpipe (LLVM 21.1.2, 256 bits)"`
+- therefore the current QEMU Wayland proof is still a software-rendered runtime slice, not a
+  hardware-accelerated desktop proof
+- QEMU should be treated as a bounded regression/test harness for Wayland/Qt bring-up, not as the
+  primary proof target for the final hardware-accelerated desktop claim
+
+The real hardware-accelerated acceptance target remains the bare-metal/runtime-driver path:
+
+- `redox-drm` detects and drives the target GPU family
+- Mesa GBM/EGL/GLES2 uses that runtime graphics path
+- the compositor and Qt Wayland clients run stably on top of it
+- runtime evidence shows the desktop path is using the real accelerated stack rather than a
+  software fallback
+
 The desktop stack therefore should not over-claim hardware-ready Wayland/KDE support yet.

 ### 3. KDE build progress is ahead of session maturity
@@ -0,0 +1,83 @@
+# External Redox Toolchain Export
+
+This repo already builds the Redox cross toolchain into:
+
+```text
+prefix/x86_64-unknown-redox/sysroot
+```
+
+That works for in-tree builds, but it is awkward for external consumers because:
+
+- the checkout path leaks into ad hoc scripts and CMake files,
+- `pkg-config` and `llvm-config` need host-side wrappers,
+- consumers usually want a single directory they can add to `PATH`.
+
+## Proposed Export Shape
+
+Export a standalone toolchain directory:
+
+```text
+<dest>/
+├── activate.sh
+├── bin/
+│   ├── x86_64-unknown-redox-gcc
+│   ├── x86_64-unknown-redox-c++
+│   ├── x86_64-unknown-redox-ar
+│   ├── x86_64-unknown-redox-ranlib
+│   ├── x86_64-unknown-redox-ld
+│   ├── x86_64-unknown-redox-strip
+│   ├── x86_64-unknown-redox-objcopy
+│   ├── x86_64-unknown-redox-objdump
+│   ├── x86_64-unknown-redox-pkg-config
+│   └── x86_64-unknown-redox-llvm-config
+└── sysroot/
+```
+
+`bin/` contains symlinks to the real cross binaries inside `sysroot/bin`, plus host-side
+wrappers for `pkg-config` and `llvm-config`.
+
+## Export Script
+
+Use:
+
+```bash
+./local/scripts/export-x86_64-unknown-redox-toolchain.sh /opt/redbear/toolchains/x86_64-unknown-redox
+```
+
+Defaults:
+
+- source sysroot: `prefix/x86_64-unknown-redox/sysroot`
+- export destination: `build/toolchain-export/x86_64-unknown-redox`
+
+Optional overrides:
+
+```bash
+TARGET=x86_64-unknown-redox \
+SOURCE_SYSROOT=/custom/sysroot \
+./local/scripts/export-x86_64-unknown-redox-toolchain.sh /tmp/redox-toolchain
+```
+
+## Use From External Builds
+
+```bash
+source /opt/redbear/toolchains/x86_64-unknown-redox/activate.sh
+x86_64-unknown-redox-gcc --version
+```
+
+`activate.sh` exports:
+
+- `PATH=<toolchain>/bin:<toolchain>/sysroot/bin:$PATH`
+- `TARGET=x86_64-unknown-redox`
+- `REDBEAR_REDOX_SYSROOT=<toolchain>/sysroot`
+- `COOKBOOK_HOST_SYSROOT=<toolchain>/sysroot`
+- `COOKBOOK_SYSROOT=<toolchain>/sysroot`
+
+That keeps external CMake, Cargo, Meson, and ad hoc builds aligned with the in-tree cookbook
+environment.
+
+## Why This Shape
+
+- It is relocatable after export.
+- It does not require the original repo checkout at runtime.
+- It reuses the already-built canonical sysroot from `mk/prefix.mk`.
+- It avoids teaching every external project Red Bear-specific path conventions.
@@ -124,7 +124,7 @@ Current runtime-proof entrypoint now present in-tree:

 ### 3. IOMMU and interrupt remapping

-IOMMU is the most important low-level controller area that is still incomplete in practice.
+IOMMU was the most important low-level controller area that was still incomplete in practice.

 - The implementation direction is correct.
 - The data structures and register model are already documented deeply.
@@ -132,15 +132,17 @@ IOMMU is the most important low-level controller area that is still incomplete i
  only partially integrated: the daemon now searches common IVRS table locations automatically, but
  full platform-native discovery and hardware validation are still open.
 - The current QEMU path now reaches AMD-Vi unit detection and `scheme:iommu` registration without
-  crashing at daemon startup, but unit initialization is still deferred and real hardware validation
-  remains open.
- The current guest-driven first-use proof now reaches AMD-Vi MMIO reads in QEMU (`control=0x0`,
-  `status=0x0`), but still dies during the completion path with a CPU-side page fault while touching
-  the completion-store region. That narrows the remaining blocker to DMA mapping/page-coverage
-  behavior rather than to missing discovery, missing scheme wiring, or unreadable MMIO registers.
+  crashing at daemon startup.
+- The current guest-driven first-use proof now completes successfully in QEMU: it reaches readable
+  and writable AMD-Vi MMIO, initializes both discovered units, and drains the event path without
+  faulting.
+- The critical blockers that previously stopped this path were fixed in the shared mapping layers,
+  not just in the userspace `iommu` daemon: physically contiguous DMA allocations now preserve
+  writable mappings, and MMIO mappings now use the explicit `fmap` path with the intended protection
+  bits.

-This makes IOMMU the highest-value long-term controller enhancement area after basic MSI-X runtime
-validation.
+This leaves IOMMU as a hardware-validation and deeper interrupt-remapping quality area, rather than
+as an immediate QEMU runtime blocker.

 ### 4. Input/controller path

@@ -241,7 +243,7 @@ Current runtime-validation surface now present in-tree:

 ### IOMMU / interrupt remapping

-**State**: the biggest completeness gap.
+**State**: QEMU runtime proof present; broader hardware validation still open.

 Concrete checked-in owner:

@@ -255,8 +257,6 @@ Open enhancement items:
 - interrupt remapping validation under device load
 - explicit distinction between “daemon builds” and “controller works”
 - replacement of `IOMMU_IVRS_PATH`-only discovery with real system discovery/integration
- diagnosis/fix for the remaining QEMU first-use blocker where completion-store CPU access faults
-  even after MMIO reads and multiple completion-store placement strategies succeed structurally

 Current implementation improvement:

@@ -265,8 +265,8 @@ Current implementation improvement:
 - daemon startup now defers AMD-Vi unit initialization until first scheme use, which keeps the
  QEMU validation path alive long enough to prove detection plus `scheme:iommu` registration
 - a guest-driven self-test path now exists (`/usr/bin/iommu --self-test-init` via
-  `redbear-phase-iommu-check` / `test-iommu-qemu.sh`) and proves that the remaining failure is in
-  runtime completion/DMA-page handling, not in daemon startup or bare MMIO readability
+  `redbear-phase-iommu-check` / `test-iommu-qemu.sh`) and now proves first-use unit initialization
+  and event-drain completion in QEMU

 ### Legacy IRQ ownership and dispatch map

@@ -450,25 +450,28 @@ Why fifth:

 Important, but less immediately blocking than MSI-X and IOMMU.

-## Priority 6 — xHCI interrupt restoration
+## Priority 6 — xHCI interrupt-path hardening

 This is Priority 6 **within the low-level controller plan itself**, not within the repository-wide
 subsystem order. At the repo-wide level, low-level controller quality remains ahead of USB/Wi-Fi/
 Bluetooth because these later subsystems depend on the controller/runtime proof work documented
 here.

-Goal: move USB host-controller operation from polling back to real interrupt-driven behavior.
+Goal: keep USB host-controller operation on the restored interrupt-driven path and harden the proof
+surface beyond the current narrow QEMU validation.

 Deliverables:

- restore the actual `get_int_method` path in `xhcid`
+- keep the actual `get_int_method` path in `xhcid` healthy
 - validate MSI/MSI-X or INTx behavior for xHCI on real hardware and/or QEMU
- update docs so USB controller quality is not overstated while polling remains active
+- update docs so USB controller quality is not overstated while broader runtime and hardware
+  validation remain open

 Why sixth:

-This is a real completeness gap in an important low-level controller, but it is narrower in scope
-than the cross-cutting MSI-X and IOMMU priorities above.
+This remains a real completeness gap in an important low-level controller, but it is now narrower in
+scope than the cross-cutting MSI-X and IOMMU priorities above because the interrupt path itself is
+already restored and QEMU-proven.

 ## Execution Plan

@@ -533,8 +536,7 @@ runtime-evidence surface:
 - `local/scripts/test-xhci-irq-qemu.sh --check` — xHCI interrupt-mode proof from QEMU boot logs
 - `local/scripts/test-msix-qemu.sh` — live MSI-X proof via `virtio-net`
 - `local/scripts/test-iommu-qemu.sh --check` — AMD IOMMU device visibility plus guest boot reachability
- `local/scripts/test-usb-storage-qemu.sh` — USB mass-storage autospawn probe (currently still an
-  active blocker path)
+- `local/scripts/test-usb-storage-qemu.sh` — USB mass-storage autospawn probe

 ## Bottom Line

@@ -46,6 +46,76 @@ Red Bear ships a Redox-native `netctl` compatibility command in `redbear-netctl`
 - `Gateway='a.b.c.d'`
 - `DNS=('a.b.c.d')`

+### Current Wi-Fi-facing extension
+
+`redbear-netctl` now also has a bounded Wi-Fi profile layer intended for future native wireless
+bring-up.
+
+Current Wi-Fi-facing fields:
+
+- `Interface=wlan0` (or another future wireless interface name)
+- `Connection=wifi`
+- `SSID='...'`
+- `Security=open|wpa2-psk`
+- `Key='...'` / `Passphrase='...'`
+
+Current boundary:
+
+- `redbear-netctl` can parse and start these profiles
+- it writes Wi-Fi intent and credentials into the in-tree `/scheme/wifictl` control surface
+- it reuses the native `netcfg`/`dhcpd` handoff only after association
+- it is **not** the supplicant and does not currently implement scan/auth/association itself
+
+Current orchestration order for Intel Wi‑Fi profiles:
+
+- `prepare`
+- `init-transport`
+- `activate-nic`
+- `connect`
+
+Current orchestration order for `netctl scan` on Intel Wi‑Fi profiles:
+
+- `prepare`
+- `init-transport`
+- `activate-nic`
+- `scan`
+
+The current Intel backend will not attempt `scan` or `connect` until transport initialization has
+been attempted.
+
+The current user-facing Wi‑Fi subcommands are:
+
+- `netctl scan <profile|iface>`
+- `netctl status <profile>` with Wi‑Fi status, link state, firmware status, transport status, transport-init status, activation status, and last error
+
+The current `redbear-wifictl` daemon provides:
+
+- a bounded stub backend for end-to-end profile/control validation
+- an Intel-oriented backend boundary that detects Intel wireless-class PCI devices
+- firmware-family and firmware-presence reporting for the Intel target boundary
+- a bounded `prepare` step before connect
+- transport-readiness reporting for the detected Intel device
+- a bounded `scan` action and per-interface `scan-results`
+- a bounded PCI transport-prep action before connect
+- a bounded `init-transport` state after preparation and before connect
+- a bounded `activate-nic` state after transport initialization and before connect/scan
+- per-interface Wi-Fi state files under `/scheme/wifictl/ifaces/<iface>/...`
+
+Below that control plane, the current repo also contains the first bounded Intel driver-side package:
+
+- `local/recipes/drivers/redbear-iwlwifi/`
+
+Current bounded driver-side actions:
+
+- `redbear-iwlwifi --probe`
+- `redbear-iwlwifi --status <device>`
+- `redbear-iwlwifi --prepare <device>`
+- `redbear-iwlwifi --transport-probe <device>`
+- `redbear-iwlwifi --init-transport <device>`
+- `redbear-iwlwifi --activate-nic <device>`
+- `redbear-iwlwifi --scan <device>`
+- `redbear-iwlwifi --retry <device>`
+
 ### Supported commands

 - `netctl list`
@@ -56,6 +126,7 @@ Red Bear ships a Redox-native `netctl` compatibility command in `redbear-netctl`
 - `netctl disable [profile]`
 - `netctl is-enabled [profile]`
 - `netctl --boot`
+- `netctl scan <profile|iface>`

 Profiles live in `/etc/netctl`. Shipped examples live in `/etc/netctl/examples/`.

@@ -74,6 +145,10 @@ base networking services have started.

 - `redbear-netctl` was type-checked and smoke-tested with a fake runtime root by exercising:
  `list`, `enable`, `status`, and `start`.
+- the Wi-Fi profile flow was also exercised with a fake runtime root by starting a
+  `Connection=wifi` / `Interface=wlan0` profile and verifying that `SSID`, `Security`, `Key`, and
+  `connect` were written to the fake `/scheme/wifictl` tree while `status` reported the Wi-Fi
+  profile correctly
 - `rtl8168d` type-checks with the RTL8125 autoload configuration in place.
 - relibc type-checks with the interface and header updates in place.
 - `./local/scripts/validate-vm-network-baseline.sh` verifies the repo-level VM boot chain for
@@ -188,7 +188,7 @@ real gap is **runtime and downstream-consumer validation**:
  login prompt over the serial console.
 - `pcid-spawner` successfully spawned `virtio-netd` during the guest boot sequence.
 - `firmware-loader` registered `scheme:firmware` without crashing, even with an empty
-  `/usr/firmware/` directory.
+`/lib/firmware/` directory.
 - `evdevd` registered `scheme:evdev` and `udev-shim` registered `scheme:udev` during the same
  guest boot.
 - `redbear-info --json` inside the guest reported `virtio_net_present: true`, a configured
@@ -23,8 +23,10 @@ USB plan uses:
 | Profile | Intent | Key Fragments | Current support language |
 |---|---|---|---|
 | `redbear-minimal` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline / DHCP boot profile enabled / input-runtime substrate wired |
+| `redbear-bluetooth-experimental` | First bounded Bluetooth validation profile | `redbear-bluetooth-experimental.toml`, `redbear-minimal.toml` | builds / boots in QEMU / validated bounded Battery Level slice via `redbear-bluetooth-battery-check` and `test-bluetooth-qemu.sh --check` / explicit-startup USB BLE-first only / repeated helper + restart cleanup covered / not generic GATT / not USB-class-autospawn |
+| `redbear-wifi-experimental` | First bounded Intel Wi-Fi validation profile | `redbear-wifi-experimental.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental bounded Intel Wi-Fi slice / driver + control/profile/reporting stack present / packaged in-target validation and capture commands available / real hardware connectivity still unproven |
 | `redbear-desktop` | Main Red Bear desktop integration profile without KDE-specific session wiring | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / input-runtime substrate wired / runtime reporting installed |
-| `redbear-wayland` | Phase 4 Wayland runtime validation profile | `wayland.toml` | builds / boots in QEMU / experimental graphics-runtime path |
+| `redbear-wayland` | Phase 4 Wayland runtime validation profile | `wayland.toml` | builds / boots in QEMU / experimental software-path graphics-runtime slice / not QEMU hardware-acceleration proof |
 | `redbear-full` | Phase 5 desktop/network plumbing profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / boots in QEMU / D-Bus system bus wired / experimental runtime path |
 | `redbear-kde` | Phase 6 KDE session-surface profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental desktop path / D-Bus+seatd+KWin session surface wired |
 | `redbear-live` | Live and recovery image layered on desktop | `redbear-desktop.toml` | builds |
@@ -38,6 +40,29 @@ USB plan uses:
 - Enables the shared `wired-dhcp` netctl profile by default for the Phase 2 VM/wired baseline.
 - Ships the shared firmware/input runtime service prerequisites so the early substrate can be tested on the smallest profile as well.

+### `redbear-bluetooth-experimental`
+
+- Standalone tracked profile for the first in-tree Bluetooth slice instead of a blanket claim about
+  all Red Bear images.
+- Extends `redbear-minimal` so the baseline runtime tooling is already present, then adds only the
+  bounded Bluetooth pieces on top.
+- Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-bluetooth-battery-check`, with repeated in-boot reruns, daemon-restart coverage, and one experimental battery-sensor Battery Level read-only workload.
+- Current support language is intentionally narrow: explicit-startup only, USB-attached transport,
+  BLE-first CLI/scheme surface, one experimental battery-sensor Battery Level read-only workload,
+  and no USB-class autospawn claim yet.
+
+### `redbear-wifi-experimental`
+
+- Standalone tracked profile for the current bounded Intel Wi-Fi slice instead of implying that the
+  wider desktop profiles already carry the full driver stack.
+- Extends `redbear-minimal` so the baseline firmware/input/reporting/profile-manager surface stays
+  inherited while the Intel Wi-Fi driver package and bounded validation role remain isolated here.
+- Includes the Intel driver package (`redbear-iwlwifi`) in addition to the shared firmware,
+  control-plane, reporting, and profile-manager pieces.
+- Current support language is intentionally narrow: bounded probe/prepare/init/activate/scan/
+  connect/disconnect lifecycle, packaged in-target validation and capture commands, and no claim yet
+  of validated real AP association or end-to-end Wi-Fi connectivity.
+
 ### `redbear-desktop`

 - Carries the standard Red Bear desktop-facing package additions.
@@ -50,6 +75,8 @@ USB plan uses:
 - Wraps the repo's existing `wayland.toml` into a first-class Red Bear build target.
 - Serves as the Phase 4 runtime-validation surface for `orbital-wayland` and `smallvil`.
 - Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-phase4-wayland-check`, with `smallvil` reaching xkbcommon initialization and EGL platform selection on Redox.
+- Current QEMU renderer evidence is still software-based (`llvmpipe` on the current `-vga std` harness), so this profile must not be described as a hardware-accelerated desktop proof yet.
+- Treat this profile as the bounded Phase 4 Wayland/Qt regression harness; the final hardware-desktop claim still belongs to the bare-metal accelerated graphics path.

 ### `redbear-full`

@@ -68,3 +95,13 @@ USB plan uses:

 - Intended for install, demo, and recovery workflows.
 - Should inherit only stable desktop-profile assumptions unless explicitly documented.
+
+## Bluetooth Note
+
+- `redbear-bluetooth-experimental` is now the tracked first Bluetooth-specific profile.
+- Its support language remains experimental and bounded; it should not be used to imply Bluetooth
+  support across the wider Red Bear profile set.
+- The current bounded BLE workload is one read-only battery-sensor Battery Level interaction; this
+  profile still does not claim generic GATT, write, or notify support.
+- The current validation claim is QEMU-scoped and packaged-checker-scoped, not a blanket claim
+  about real hardware Bluetooth maturity.
@@ -275,7 +275,7 @@ Graphics stack (PRIMARY DELIVERABLE):
 KWin recipe updated with 40 dependencies (all KF6 + Mesa + libdrm + libinput + qtwayland).
 plasma-workspace, plasma-desktop recipes created.

-### Phase 4 — Graphics Stack (✅ COMPLETE)
+### Phase 4 — Graphics Stack (✅ build-side complete, 🚧 runtime incomplete)

 Mesa EGL+GBM+GLES2 built:
 - libEGL.so (225KB) — platforms: redox, surfaceless, drm
@@ -295,12 +295,25 @@ Qt6 OpenGL enabled:
 - libQt6EglFSDeviceIntegration.so — EGLFS platform integration
 - EGLFS KMS plugin for direct DRM/KMS rendering

-### Phase 4b — Qt6 OpenGL Enablement (✅ COMPLETE)
+Current truth for Phase 4:
+
+- the graphics stack now builds end to end: Mesa EGL+GBM+GLES2, libdrm amdgpu, Qt6 OpenGL/EGL,
+  and qtwayland all stage successfully
+- the current `redbear-wayland` validation profile is still a bounded smallvil-first runtime path,
+  not proof of a hardware-accelerated desktop session
+- the current QEMU validation harness is still software-rendered (`llvmpipe`) and should be treated
+  as a bounded regression/test path, not as the final acceleration proof target
+- the in-repo Phase 4 runtime check currently still fails in `qt6-bootstrap-check` during early Qt
+  startup, so even the bounded software-path runtime proof remains incomplete
+- true hardware-accelerated desktop readiness still requires kernel DMA-BUF fd passing plus real
+  AMD/Intel hardware validation through the DRM → GBM/EGL → compositor → Qt client path
+
+### Phase 4b — Qt6 OpenGL Enablement (✅ build-side complete, 🚧 runtime incomplete)

 qtbase rebuilt with `-DFEATURE_opengl=ON -DINPUT_opengl=es2 -DFEATURE_egl=ON`
 Qt cmake summary: EGL=yes, OpenGL=yes, "OpenGL ES 2.0=yes, EGLFS GBM=yes"

-### Phase 5 — KDE Plasma (🔄 IN PROGRESS)
+### Phase 5 — KDE Plasma / desktop-session layer (🔄 IN PROGRESS)

 KDE Plasma packages built:
 - kf6-kwayland ✅ BUILT
@@ -327,7 +340,7 @@ Phase 1 ✅ (qtbase + qtdeclarative + qtsvg)
    └── Phase 2b ✅ (qtwayland built)
    └── Phase 2c ✅ (libevdev + libinput built)
    └── Phase 3 ✅ (KF6 — ALL 32 frameworks built)
-    └── Phase 4 ✅ (Mesa EGL+GBM+GLES2, Qt6 OpenGL+EGL, libdrm amdgpu)
+    └── Phase 4 ✅ build-side / 🚧 runtime (Mesa EGL+GBM+GLES2, Qt6 OpenGL+EGL, libdrm amdgpu)
    └── Phase 5 🔄 (kdecoration ✅, kf6-kwayland ✅, kirigami stub-only, KWin still blocked on shimmed/scaffolded deps)
 ```

@@ -34,13 +34,15 @@ are hardware-validated at runtime.

 - **Identity** — OS name, version, hostname
 - **Networking** — stack state, connected flag, interface, MAC, IP/CIDR, DNS, default route,
-  active `netctl` profile, visible `network.*` schemes
+  active `netctl` profile, visible `network.*` schemes, Wi-Fi control/firmware/transport surfaces,
+  and bounded Bluetooth transport/control visibility
 - **Hardware** — PCI device count, USB controller count, DRM card count, RTL8125 PCI visibility
 - **Hardware** — PCI device count, USB controller count, DRM card count, RTL8125 PCI visibility,
  VirtIO NIC visibility for VM baselines
 - **Integrations** — tools, daemons, and integration paths such as `lspci`, `lsusb`, `netctl`,
-  `pcid-spawner`, `smolnetd`, `firmware-loader`, `udev-shim`, `evdevd`, `redox-drm`, and the
-  native RTL8125 and VirtIO networking paths
+  `pcid-spawner`, `smolnetd`, `firmware-loader`, `udev-shim`, `evdevd`, `redox-drm`,
+  `redbear-wifictl`, `redbear-btusb`, `redbear-btctl`, and the native RTL8125 and VirtIO
+  networking paths

 For Phase 3 runtime validation, `udev-shim` is expected at `/usr/bin/udev-shim` and `evdevd` is
 expected at both `/usr/bin/evdevd` and `/usr/lib/drivers/evdevd` so service execution and runtime
@@ -66,5 +68,8 @@ That includes new:
 - hardware integration paths
 - configuration layers that users rely on to debug a running image

+Recent examples include the Wi-Fi control-plane surfaces and the bounded Bluetooth first-slice
+surfaces, both of which extend the runtime report without over-claiming hardware validation.
+
 The goal is for `redbear-info` to remain the first command users run when they need to understand
 the state of a Red Bear system.
@@ -16,6 +16,39 @@ The goal is to remove guesswork from the sync/fetch/apply/build workflow.
 | `local/scripts/build-redbear.sh` | Build Red Bear profiles from upstream base + local overlay | applies overlays, builds cookbook if needed, validates profile naming, launches the actual image build | does not guarantee every nested upstream source tree is fresh; does not replace explicit subsystem/runtime validation |
 | `scripts/fetch-all-sources.sh` | Fetch recipe source inputs for builds | downloads recipe sources for upstream and local recipes, reports status/preflight, supports config-scoped fetches | does not mean fetched upstream WIP source is the durable shipping source of truth |
 | `local/scripts/fetch-sources.sh` | Fetch local overlay source inputs | fetches local overlay recipe sources and keeps the local side ready for build work | does not decide whether upstream should replace the local overlay |
+| `local/scripts/build-redbear-wifictl-redox.sh` | Build `redbear-wifictl` for the Redox target with the repo toolchain | prepends `prefix/x86_64-unknown-redox/sysroot/bin` to `PATH` and runs `cargo build --target x86_64-unknown-redox` in the `redbear-wifictl` crate | does not prove runtime Wi-Fi behavior; only closes the target-build environment gap for this crate |
+| `local/scripts/test-iwlwifi-driver-runtime.sh` | Exercise the bounded Intel driver lifecycle inside a target runtime | validates bounded probe/prepare/init/activate/scan/connect/disconnect/retry surfaces for `redbear-iwlwifi` on a live target runtime | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end connectivity |
+| `local/scripts/test-wifi-control-runtime.sh` | Exercise the bounded Wi-Fi control/profile lifecycle inside a target runtime | validates `/scheme/wifictl` control nodes, bounded connect/disconnect behavior, and profile-manager/runtime reporting surfaces on a live target runtime | does not prove real AP association or end-to-end connectivity |
+| `local/scripts/test-wifi-baremetal-runtime.sh` | Exercise bounded Intel Wi-Fi runtime lifecycle on a target system | validates driver probe, control probe, bounded connect/disconnect, profile-manager start/stop via the `wifi-open-bounded` profile, Wi-Fi lifecycle reporting, and writes `/tmp/redbear-phase5-wifi-capture.json` on the target | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end hardware connectivity |
+| `local/scripts/test-wifi-passthrough-qemu.sh` | Launch Red Bear with VFIO-passed Intel Wi-Fi hardware | boots a Red Bear guest with a passed-through Intel Wi-Fi PCI function, auto-runs the in-guest bounded Wi-Fi validation command, and can copy the packaged capture bundle back to a host-side file during `--check` | depends on host VFIO setup and still does not by itself guarantee real AP association or end-to-end Wi-Fi connectivity |
+| `local/scripts/test-bluetooth-runtime.sh` | Compatibility guest entrypoint for the bounded Bluetooth Battery Level slice | runs the packaged `redbear-bluetooth-battery-check` helper inside a Redox guest or target runtime | does not run on the host and does not expand the Bluetooth support claim beyond the packaged checker’s bounded scope |
+| `local/scripts/test-bluetooth-qemu.sh` | Launch or validate the bounded Bluetooth Battery Level slice in QEMU | boots `redbear-bluetooth-experimental`, auto-runs the packaged checker during `--check`, reruns it in one boot, and reruns it again after a clean reboot | does not prove real controller bring-up, generic BLE/GATT maturity, write/notify support, or real hardware Bluetooth behavior |
+| `local/scripts/prepare-wifi-vfio.sh` | Prepare or restore an Intel Wi-Fi PCI function for passthrough | binds a chosen PCI function to `vfio-pci` or restores it to a specified host driver | does not verify guest Wi-Fi functionality and must be used carefully on a host with a safe detachable target device |
+| `local/scripts/validate-wifi-vfio-host.sh` | Check whether a host looks ready for Wi-Fi VFIO testing | validates PCI presence, current driver, UEFI firmware, Red Bear image presence, QEMU/expect availability, VFIO module state, and IOMMU group visibility; exits non-zero when blockers are found | does not bind devices or prove the guest Wi-Fi stack works |
+| `local/scripts/run-wifi-passthrough-validation.sh` | End-to-end host-side passthrough validation wrapper | prepares VFIO, runs the packaged in-guest Wi-Fi validation path, captures the guest JSON artifact to the host, writes a host-side metadata sidecar, and restores the host driver afterwards | still depends on real VFIO/hardware support and does not itself guarantee end-to-end Wi-Fi connectivity |
+| `local/scripts/package-wifi-validation-artifacts.sh` | Bundle Wi-Fi validation evidence into one archive | packages common capture/log artifacts from bare-metal or VFIO validation runs into a single tarball | does not create missing artifacts or validate their contents |
+| `local/scripts/summarize-wifi-validation-artifacts.sh` | Summarize Wi-Fi validation evidence quickly | extracts key runtime signals from a capture JSON or packaged tarball for fast triage | does not replace full artifact review or prove runtime correctness |
+| `local/scripts/finalize-wifi-validation-run.sh` | One-shot post-run Wi-Fi triage helper | runs the packaged analyzer on a capture JSON and then packages the chosen artifacts into a tarball | still depends on a real target run having produced the capture/artifacts first |
+
+The packaged companion command for those scripts is `redbear-phase5-wifi-check`, which performs the
+bounded in-target Wi-Fi lifecycle checks from inside the guest/runtime itself.
+
+The packaged Bluetooth companion command is `redbear-bluetooth-battery-check`, which performs the
+bounded Bluetooth Battery Level checks from inside the guest/runtime itself, including repeated
+helper runs, daemon-restart coverage, failure-path honesty checks, and stale-state cleanup checks
+within the current slice boundary.
+
+The packaged evidence companion is `redbear-phase5-wifi-capture`, which collects the bounded driver,
+control, profile-manager, reporting, interface-listing, and scheme-state surfaces — plus `lspci`
+and active-profile contents — into a single JSON artifact.
+
+The packaged link-oriented companion is `redbear-phase5-wifi-link-check`, which focuses on whether
+the target runtime is exposing interface/address/default-route signals in addition to the bounded
+Wi-Fi lifecycle state.
+
+For Redox-target Rust builds of Wi-Fi components such as `redbear-wifictl`, a missing
+`x86_64-unknown-redox-gcc` on `PATH` should first be treated as a host toolchain/path issue if the
+repo already contains `prefix/x86_64-unknown-redox/sysroot/bin/x86_64-unknown-redox-gcc`.

 ## Policy Mapping

@@ -40,8 +40,8 @@ The current limitations are material:
 - 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 and autospawn is now re-enabled for validation, but the current
-  blocker has moved to post-spawn runtime stability rather than driver matching.
+- USB mass storage exists in-tree and now autospawns successfully in the current QEMU validation
+  path, but broader runtime stability and wider class/topology validation are still open.
 - there is no evidence of validated support for broader USB classes or modern USB-C / dual-role
  scope

@@ -59,7 +59,7 @@ The current limitations are material:
 | libusb | **builds / experimental** | WIP, compiled but not tested |
 | usbutils | **broken / experimental** | WIP, compilation error |
 | EHCI/OHCI/UHCI | **absent / undocumented** | No evidence present in-tree |
-| USB networking/audio/video/Bluetooth classes | **absent / undocumented** | No evidence of working support |
+| USB networking/audio/video/Bluetooth classes | **partial / experimental** | Broad class support remains incomplete, but one bounded explicit-startup USB-attached Bluetooth slice now exists |
 | Device mode / OTG / dual-role / USB-C / PD / alt-modes / USB4 | **absent / undocumented** | No evidence present |

 ## Evidence Already In Tree
@@ -90,8 +90,8 @@ The current limitations are material:
 - `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
 - `recipes/core/base/source/drivers/usb/xhcid/drivers.toml` now re-enables USB SCSI autospawn with
  explicit protocol matching for BOT (`0x50`)
- `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
+- `recipes/core/base/source/drivers/COMMUNITY-HW.md` is a historical/community request ledger and
+  cannot be treated as a canonical current-state source for xHCI support

 ## Current Gaps and Limits

@@ -368,7 +368,8 @@ Prefer language such as:
 - “xHCI host support is present but experimental”
 - “USB enumeration and HID-adjacent host paths exist in-tree”
 - “USB support remains controller-variable”
- “USB storage support exists in-tree but is not currently enabled as a default working path”
+- “USB storage support exists in-tree and is QEMU-proven for the current validation path, but is
+  not yet a broad hardware support claim”

 ## Summary

@@ -5,10 +5,10 @@
 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
+The goal is not to imply that working Wi-Fi already exists. 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.
+from a **bounded experimental Intel Wi-Fi scaffold** to one experimental, validated Wi-Fi path that
+fits the existing Redox / Red Bear architecture.

 ## Validation States

@@ -25,10 +25,12 @@ This repo should not treat planned wireless scope as equivalent to implemented s

 ### Summary

-Wi-Fi is currently **missing** in Red Bear OS.
+Wi-Fi is currently **not supported as working connectivity** 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.
+There is still no complete in-tree cfg80211/mac80211/nl80211-compatible surface, no supplicant
+path, and no profile that can honestly claim working Wi-Fi support. What now exists in-tree is a
+bounded Intel bring-up slice: a driver-side package, a Wi-Fi control daemon/scheme, profile
+plumbing, and host-validated LinuxKPI/CLI scaffolding below the real association boundary.

 What the repo *does* have is a meaningful set of prerequisites:

@@ -43,20 +45,22 @@ What the repo *does* have is a meaningful set of prerequisites:

 | 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` |
+| Wi-Fi controller support | **experimental bounded slice exists** | `redbear-iwlwifi` provides an Intel-only bounded driver-side package, not validated Wi-Fi connectivity |
+| Linux wireless stack compatibility | **early compatibility scaffolding exists** | `linux-kpi` now carries initial `cfg80211` / `wiphy` / `mac80211` registration and station-mode compatibility scaffolding, but not a complete Linux wireless stack |
 | 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 |
+| Wireless control plane | **experimental bounded slice exists** | `redbear-wifictl` and `redbear-netctl` expose bounded prepare/init/activate/scan orchestration, not real association support |
 | 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 |
+| Runtime diagnostics | **experimental bounded slice exists** | `redbear-info` and runtime helpers expose Wi-Fi state surfaces, but not real Wi-Fi functionality proof |

 ## Evidence Already In Tree

-### Direct negative evidence
+### Direct current-state caution about supported connectivity

- `HARDWARE.md` says Wi-Fi and Bluetooth are not supported yet
- `local/docs/AMD-FIRST-INTEGRATION.md` marks `Wi-Fi/BT` as missing
+- `HARDWARE.md` says broad Wi-Fi and Bluetooth hardware support is still incomplete even though
+  bounded in-tree scaffolding now exists
+- `local/docs/AMD-FIRST-INTEGRATION.md` now treats `Wi-Fi/BT` as in progress with bounded wireless
+  scaffolding present but validated connectivity still incomplete

 ### Positive driver-side prerequisites

@@ -104,7 +108,8 @@ Current `linux-kpi` is suitable for low-level driver-enablement work such as:
 - 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:
+Current `linux-kpi` is **not** a complete Wi-Fi architecture because the repo still has no in-tree,
+complete:

 - cfg80211
 - mac80211
@@ -119,76 +124,326 @@ stack.

 The current native network stack is useful, but not yet Wi-Fi-ready.

-`redbear-netctl` only supports:
+`redbear-netctl` now has a first Wi-Fi-facing profile layer, but only at the profile/orchestration
+boundary.
+
+Current `redbear-netctl` support now includes:

 - `Connection=ethernet`
- `Interface=eth0`
- DHCP/static address, route, and DNS control
+- `Connection=wifi`
+- arbitrary `Interface=` values at the profile layer (for example `eth0`, `wlan0`)
+- DHCP/static address, route, and DNS control after association
+- Wi-Fi profile fields for `SSID`, `Security`, and `Key`/`Passphrase`
+- a bounded native handoff to a future `/scheme/wifictl` control surface

-`netcfg` is similarly hard-wired around the current `eth0` interface model.
+The repo now also contains the first bounded implementation of that control surface:
+
+- `local/recipes/system/redbear-wifictl/` provides a `redbear-wifictl` daemon and `/scheme/wifictl`
+  scheme
+- the current daemon supports a stub backend for end-to-end validation and an Intel-oriented backend
+  boundary that detects Intel wireless-class PCI devices
+- the current Intel backend is now firmware-aware: it reports candidate firmware families, selected
+  firmware blobs when present, and supports a bounded `prepare` step before connect
+- this is still not a full Intel association path, but it turns the control-plane contract into a
+  real in-tree interface rather than a placeholder
+
+This means `redbear-netctl` can now represent and start a Wi-Fi profile without pretending Wi-Fi is
+just an Ethernet profile, but it still does **not** own scan/auth/association itself.
+
+`netcfg` is no longer hard-wired to a single `eth0` node in the control scheme. The native control
+surface can now expose per-device interface nodes dynamically from the current device list, which is
+the first required step for post-association Wi-Fi handoff.

 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
+### 4. Intel target changes the first-driver strategy

-The first Wi-Fi target should minimize the amount of 802.11 MAC and Linux wireless subsystem logic
-that Red Bear has to recreate.
+The original version of this plan preferred a FullMAC-first path to avoid recreating Linux wireless
+subsystem boundaries.

-That makes **FullMAC** hardware the best first target class.
+That is still the simplest architecture in the abstract, but the project target has now changed:
+Red Bear must target **Intel Wi-Fi for Arrow Lake and older Intel client chips**.

-Red Bear should explicitly avoid starting with SoftMAC/mac80211-style Linux drivers such as:
+That means the first realistic driver family is now Intel `iwlwifi`-class hardware rather than an
+unspecified FullMAC family.

- Intel `iwlwifi`
- Realtek `rtw88` / `rtw89`
- MediaTek `mt76`
- other drivers that fundamentally assume cfg80211/mac80211 semantics
+This changes the implementation burden materially:
+
+- Intel `iwlwifi` is not a simple FullMAC path
+- current Linux support is tightly coupled to `mac80211` / `cfg80211`
+- firmware loading remains necessary but is not the hard part by itself
+- Red Bear must plan for a bounded compatibility layer below the user-facing control plane
+
+So the practical first target is now:
+
+- **Intel `iwlwifi`-class devices, Arrow Lake and older**, with the understanding that this is a
+  harder first driver family than a generic FullMAC-first strategy would have been

 ## Recommended Architecture

-The best Red Bear Wi-Fi architecture is:
+The best current Red Bear Wi-Fi architecture for the Intel target 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**
+1. **native Red Bear wireless control plane above the driver boundary**
+2. **Intel-first low-level driver work below that boundary**
+3. **reuse `firmware-loader` and `redox-driver-sys` wherever possible**
+4. **accept bounded `linux-kpi` growth where Intel transport/firmware glue requires it**
+
+### Build-note for the current Intel control-plane code
+
+The earlier Redox-target source-level compile failure in `redbear-wifictl`'s Intel backend is now
+fixed in-tree. If `cargo build --target x86_64-unknown-redox` still reports that
+`x86_64-unknown-redox-gcc` is missing, check whether the repo-provided cross toolchain under
+`prefix/x86_64-unknown-redox/sysroot/bin/` is on `PATH` before treating it as a fresh source-level
+regression.
+
+For repeatable local builds, use `local/scripts/build-redbear-wifictl-redox.sh`, which wires that
+repo-provided toolchain path into the build invocation explicitly.
 5. **reuse the existing native IP path only after association**

-This is a hybrid architecture, but it is **native-first**, not Linux-stack-first.
+This is still a native-first architecture at the control-plane level, but it is no longer a pure
+FullMAC-first plan.

 ### Subsystem boundary

 The Wi-Fi subsystem should be split into these pieces:

- one **device transport / driver daemon** for the chosen chipset family
+- one **device transport / driver daemon** for the Intel target 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.
+`redbear-netctl` should **not** become the supplicant. It can own profile orchestration and the
+post-association IP handoff, but scan/auth/association should still live in a dedicated Wi-Fi
+control daemon or scheme.
+
+The current implementation now matches that boundary more closely:
+
+- `redbear-netctl` can parse Wi-Fi profiles and hand credentials/intent to a native Wi-Fi control
+  surface (`/scheme/wifictl`)
+- `redbear-netctl` now also has a host-side CLI proof that starting a Wi-Fi profile drives the
+  bounded driver/control actions and preserves the surfaced bounded connect metadata in status
+  output; this is not yet proof of verified prepare/init/activate/connect execution order on a real
+  associated link
+- `redbear-netctl` stop now also drives the bounded disconnect path, so the current profile-manager
+  slice covers start and stop instead of start-only behavior
+- `redbear-wifictl` now exposes bounded connect and disconnect CLI flows, and the runtime checker
+  now exercises the bounded connect step through the scheme surface
+- the native IP path can address a non-`eth0` interface name after association
+- `redbear-netctl` now also performs interface-specific DHCP handoff for Wi-Fi profiles and waits
+  for the selected interface to receive an address in the bounded host/runtime validation path
+- `local/recipes/system/redbear-netctl-console/` now adds a terminal UI client on top of the same
+  `/scheme/wifictl` + `/etc/netctl` contract, so scan/select/edit/save/connect/disconnect workflows
+  can be exercised without introducing a new daemon or bypassing profile semantics
+- `local/scripts/test-wifi-baremetal-runtime.sh` now provides the strongest in-repo runtime
+  validation path for this Wi-Fi slice on a real Red Bear OS target: driver probe, control probe,
+  bounded connect/disconnect, profile start/stop, and `redbear-info --json` lifecycle reporting
+- `redbear-phase5-wifi-check` now packages that bounded in-target validation flow as a first-class
+  guest/runtime command, instead of leaving it only as a shell script
+- that packaged runtime proof currently defaults to the bounded open-profile path; WPA2-PSK remains
+  implemented and host/unit-verified elsewhere in-repo rather than equally packaged/runtime-validated
+- `redbear-phase5-wifi-capture` now packages the corresponding runtime evidence bundle, so target
+  runs can produce a single JSON artifact for debugging real hardware/passthrough failures;
+  that bundle now includes command outputs, Wi-Fi scheme state, `netctl` profile state, active
+  profile contents, interface listings, and `lspci` output
+- `test-wifi-baremetal-runtime.sh` now writes that capture bundle to `/tmp/redbear-phase5-wifi-capture.json`
+  as part of the target-side bounded validation flow
+- `local/scripts/test-wifi-passthrough-qemu.sh` now provides the corresponding VFIO/QEMU harness for
+  exercising the same bounded runtime path when an Intel Wi-Fi PCI function can be passed through to
+  a Red Bear guest, including optional host-side extraction of the packaged Wi-Fi capture bundle
+- `local/scripts/prepare-wifi-vfio.sh` now provides the matching host-side bind/unbind helper for
+  moving an Intel Wi-Fi PCI function onto `vfio-pci` before passthrough validation and restoring it
+  afterwards
+- `local/scripts/run-wifi-passthrough-validation.sh` now wraps the whole host-side passthrough flow:
+  bind to `vfio-pci`, run the packaged in-guest Wi-Fi validation path, collect the host-visible
+  capture bundle, and restore the original host driver afterwards
+- `local/scripts/validate-wifi-vfio-host.sh` now provides a read-only preflight for the same flow:
+  PCI presence, current binding, UEFI firmware, image availability, QEMU/expect presence, VFIO
+  module state, and visible IOMMU groups
+- `local/docs/WIFI-VALIDATION-RUNBOOK.md` now ties the bare-metal path, VFIO path, packaged
+  validators, and capture artifacts together into one operator runbook
+- the control daemon exists now, and the first bounded driver-side package now exists as
+  `local/recipes/drivers/redbear-iwlwifi/`
+- `redbear-iwlwifi` now supports bounded `--probe` and `--prepare` driver-side actions for the
+  current Intel family set
+- `redbear-iwlwifi` now also supports bounded `--init-transport` and `--activate-nic` actions for
+  the current Intel family set
+- `redbear-iwlwifi` now also supports bounded `--scan` and `--retry` actions for the current Intel
+  family set
+- `redbear-iwlwifi` now also carries a first bounded `--connect` path that runs through the new
+  LinuxKPI wireless compatibility scaffolding instead of stopping immediately at a hardcoded
+  transport/association error
+- `redbear-iwlwifi` now also carries a bounded `--disconnect` path so the current station-mode
+  lifecycle is not connect-only anymore
+- `redbear-iwlwifi --status` now reports the current bounded driver-side view directly
+- the bounded driver-side action set can be exercised through the dedicated helper script
+  `local/scripts/test-iwlwifi-driver-runtime.sh`
+- on Redox targets, `redbear-iwlwifi` now also begins to use a `linux-kpi` C shim for firmware
+  request and PCI/MMIO-facing prepare/transport actions instead of keeping those paths purely in
+  Rust fallback code
+
+### Port vs rewrite decision
+
+For Arrow Lake-and-lower Intel Wi‑Fi, the current repo direction is:
+
+- **do not** attempt a full Linux `mac80211` / `cfg80211` / `nl80211` port first,
+- **do** create a bounded Intel driver/transport package below the native Red Bear Wi‑Fi control
+  plane,
+- **do** accept limited `linux-kpi` growth only where it materially reduces transport/firmware glue
+  cost,
+- keep `redbear-netctl` and `redbear-wifictl` as the native control-plane/user-facing layers above
+  that driver boundary.
+
+That means the repo is now following a **bounded transport-layer port with native control-plane
+rewrite above it**, not a full Linux wireless stack port and not a pure greenfield driver rewrite.
+
+### What this means in practical porting terms
+
+The currently feasible interpretation of “use the real Linux Intel driver through `linux-kpi`” is:
+
+- port and reuse **transport-layer and firmware-facing logic** where that lowers cost materially,
+- keep the **native Red Bear control plane** above that boundary,
+- and avoid treating a full `cfg80211` / `mac80211` / `nl80211` / `wiphy` port as the immediate
+  first milestone.
+
+In other words, Red Bear should not try to import the whole Linux wireless stack in one step.
+Red Bear should instead pull over the **device-facing part** of the Intel stack in bounded layers.
+
+### Boundary where `linux-kpi` is helpful
+
+`linux-kpi` is most useful for:
+
+- PCI helper semantics
+- MMIO/IRQ/DMA glue
+- firmware request/load glue
+- workqueue-style deferred execution
+- timer, mutex, and IRQ-critical-section helpers that transport-facing Linux Wi-Fi code expects
+- low-level transport and reset sequences
+- early packet-buffer / `net_device` / `wiphy` / registration scaffolding when Red Bear begins the
+  first real Linux wireless-subsystem compatibility slice
+
+That is the boundary where “run Linux driver code on Red Bear” is currently realistic.
+
+The current tree now has the first explicit step in that direction as well:
+
+- `linux-kpi` now carries initial `sk_buff`, `net_device`, `cfg80211`/`wiphy`, and `mac80211`
+  registration scaffolding alongside the earlier firmware/timer/mutex/IRQ helpers
+- that scaffolding now also includes the first station-mode compatibility types and hooks used by
+  the bounded Intel scan/connect path: SSID/connect/station parameter structs plus basic
+  `cfg80211_connect_bss` / ready-on-channel and `mac80211` VIF/STA/BSS-conf surfaces
+- the bounded station-mode slice now also preserves real private-allocation sizes, exposes the
+  common `sk_buff` reserve/push/pull/headroom/tailroom helpers, tracks `net_device`
+  registration/setup, keeps carrier down until connect success, and routes
+  `ieee80211_queue_work()` through the bounded LinuxKPI workqueue instead of silently dropping
+  deferred work
+- this new scaffolding is compile- and host-test-validated inside the `linux-kpi` crate
+- this is still **not** a claim that Red Bear now has a working Linux wireless stack
+
+### Boundary where a full Linux port becomes too expensive
+
+A full Linux-style `iwlwifi` port becomes dramatically more expensive as soon as the code path
+depends on the Linux wireless subsystem proper:
+
+- `cfg80211`
+- `mac80211`
+- `nl80211`
+- `wiphy` model and callbacks
+- Linux regulatory integration
+- Linux station/BSS bookkeeping and userspace-facing wireless semantics
+
+The repo now has the earliest pieces of those subsystem layers, but still not anything close to a
+complete Linux wireless stack. Building them out far enough to host Intel Wi‑Fi as a true Linux-like
+solution still turns the effort from a bounded driver port into a much larger compatibility-stack
+port.
+
+### Chosen direction
+
+The chosen direction for Arrow Lake-and-lower Intel Wi‑Fi is therefore:
+
+1. keep the **native Red Bear control plane** (`redbear-netctl` + `redbear-wifictl`),
+2. keep pushing the **hardware-facing Intel path** down into `redbear-iwlwifi`,
+3. use `linux-kpi` for the low-level Linux-facing transport/runtime glue where that reduces effort,
+4. avoid promising or attempting a full Linux wireless-stack port as the first milestone.
+
+The current code now matches that decision more closely than before: `redbear-wifictl` remains the
+native control plane, while `redbear-iwlwifi` is the place where Linux-facing firmware/PCI/MMIO
+driver logic is starting to accumulate.
+
+The current tree also now pushes more of that bounded Intel path through the actual LinuxKPI
+surface instead of bespoke C declarations alone:
+
+- `linux-kpi` now exports direct and async firmware request helpers for firmware-family workflows
+- timer and IRQ save/restore bindings are exported through the Linux-facing headers instead of
+  remaining header-only stubs
+- `mutex_trylock()` is available to transport-facing code that needs bounded serialization without
+  pretending the full Linux scheduler model exists
+- the current `redbear-iwlwifi` C transport shim now includes the LinuxKPI headers directly and
+  uses Linux-style firmware, timer, mutex, and IRQ helper entry points for prepare/probe/init/
+  activate steps
+
+This remains a bounded transport-layer port. It does **not** change the rule that cfg80211/
+mac80211/nl80211 remain out of scope for the current milestone.
+
+### Current validation status for this bounded LinuxKPI slice
+
+The current validation story for this slice is intentionally narrow and should be described that
+way:
+
+- the `linux-kpi` host-side test suite now runs cleanly in this repo, including the Wi‑Fi-facing
+  helper changes in this slice: `request_firmware_direct`, `request_firmware_nowait`,
+  `mutex_trylock`, IRQ-depth tracking, variable private-allocation lifetime tracking, station-mode
+  scan/connect/disconnect lifecycle assertions, workqueue-backed `ieee80211_queue_work()`, the new
+  `sk_buff` headroom/tailroom helpers, and the existing memory tests
+- `redbear-iwlwifi` host-side tests now smoke-test the bounded firmware/transport/activation/scan/
+  retry actions used by the current Intel path
+- `redbear-iwlwifi` also now has a binary-level host-side CLI smoke test for the current bounded
+  Intel path against temporary PCI/firmware fixtures; this is not the same as a chained real-target
+  transport→activation→association proof
+- `redbear-wifictl` host-side tests pass for the bounded control-plane state propagation above that
+  Intel path
+- the packaged target-side Wi-Fi validators now also accept bounded `status=associating`/
+  pending-connect output, so the in-target/runtime checks stay aligned with the current honest
+  connect semantics instead of requiring a fake associated/connected result
+- the default packaged bounded runtime profile is now `wifi-open-bounded`, separating lifecycle
+  validation from the later DHCP-on-real-association gate
+
+This does **not** mean Red Bear has validated a full Linux Wi‑Fi driver stack. The validated claim
+is narrower: this repo now has tested, bounded LinuxKPI support for the current Intel transport-
+facing helper slice, plus host-tested bounded CLI/control flows above it. Current bounded connect
+results should still be read as pending/experimental lifecycle state, not proof of real AP
+association.
+
+In the current host environment used for this hardening pass, the Intel-specific VFIO runtime path
+also remains blocked by prerequisites outside the repo changes themselves: the host validator sees a
+MediaTek MT7921K (`14c3:0608`) instead of an Intel `iwlwifi` device on the available Wi‑Fi slot,
+and `vfio_pci` is not loaded. That means the repo-side bounded runtime harness is present and the
+Red Bear image/QEMU/OVMF/`expect` prerequisites are available, but a literal Intel passthrough run
+still requires compatible host hardware and VFIO binding before it can be executed.
+
+That is the current feasibility conclusion grounded in the codebase.

 ## Hardware Strategy

-### First decision gate
+### Target hardware scope

-Before implementation begins, Red Bear must choose **one** first Wi-Fi family from actual target
-machines or bring-up hardware.
+The target scope for this plan is now:

-The preferred target order is:
+- **Intel Wi-Fi chips used on Arrow Lake and older Intel client platforms**

-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
+That includes the practical `iwlwifi` family boundary, not an abstract FullMAC-first family chosen
+for architectural neatness.

-### What not to choose for phase 1
+### What this means for phase 1

-Do not start with:
+Phase 1 is no longer “pick any convenient Wi-Fi family.”

- Intel laptop Wi-Fi via `iwlwifi`
- mac80211/cfg80211-dependent Linux drivers
- any phase-1 scope that requires recreating a Linux wireless stack first
+Phase 1 is now:
+
+- prove one bounded Intel client Wi-Fi path,
+- keep the support language experimental,
+- and avoid promising the entire Linux wireless stack up front.

 ## Security Scope Freeze

@@ -212,38 +467,113 @@ This scope freeze is required to keep the first milestone honest and achievable.

 ## Comprehensive Full Plan

+## Current Implementation Progress
+
+### Already landed in-tree
+
+The current repo now contains a **bounded Phase W0/W2/W3 slice**:
+
+- the plan target is explicitly Intel Arrow Lake and older Intel Wi-Fi chips
+- `redbear-netctl` now supports Wi‑Fi profiles with `Connection=wifi`, `Interface=...`, `SSID`,
+  `Security`, and `Key` / `Passphrase`
+- `netctl` now performs a bounded `prepare` → `init-transport` → `connect` handoff into
+  `/scheme/wifictl`
+- that user-facing path now also includes a bounded `activate-nic` step before `connect`
+- `netctl scan <profile|iface>` now uses the same `prepare` → `init-transport` ordering before the
+  active `scan` action
+- `netcfg` no longer hard-codes a single `eth0` interface node and can expose interfaces from the
+  current device list dynamically
+- `redbear-wifictl` now exists as a real package/daemon/scheme with:
+  - a stub backend for end-to-end control-plane validation
+  - an Intel-oriented backend boundary for Arrow Lake-and-lower families
+  - firmware-family and firmware-presence reporting
+  - a bounded `prepare` step before `connect`
+  - transport-readiness reporting derived from PCI command/BAR/IRQ state
+  - a bounded PCI transport-prep action that enables memory-space and bus-master bits before connect
+- a bounded `scan` action with a working stub path and a bounded Intel scan/reporting path rather
+  than the older explicit `not implemented yet` result
+  - a bounded `init-transport` state boundary after preparation and before any future association path
+  - a bounded `activate-nic` state boundary after `init-transport`
+  - state-machine enforcement so Intel scan/connect refuse to proceed before `init-transport`
+- `redbear-info` and the runtime helper scripts now expose the Wi‑Fi control-plane surfaces
+- `redbear-info` now reports Wi‑Fi firmware status, transport status, activation status, and scan results from the
+  primary Wi‑Fi control interface
+- `redbear-info` and the runtime helper also now expose `transport-init-status`, which separates
+  simple transport probing from an actual transport-initialization attempt
+- on Redox runtime builds where `/usr/lib/drivers/redbear-iwlwifi` is present **and** at least one
+  Intel Wi-Fi candidate is actually detectable, `redbear-wifictl` now auto-selects the Intel backend
+  instead of silently falling back to the stub backend
+- if the Intel driver package is present but no Intel Wi-Fi candidate is detected, `redbear-wifictl`
+  now exposes a dedicated no-device fallback rather than a synthetic stub `wlan0`, so the runtime
+  does not pretend the Intel path is usable
+
+### What this means
+
+This does **not** mean Red Bear has working Intel Wi‑Fi connectivity yet.
+
+It means the repo now has:
+
+- a real Wi‑Fi profile model,
+- a real Wi‑Fi control-plane daemon and scheme,
+- a first dedicated Intel Wi‑Fi driver-side package (`redbear-iwlwifi`),
+- a runtime helper for the bounded Intel driver probe path (`local/scripts/test-iwlwifi-driver-runtime.sh`),
+- a runtime check that the Wi‑Fi control daemon selects the Intel backend only when Intel Wi‑Fi
+  candidates are actually present,
+- a native post-association IP handoff path that can address non-`eth0` interfaces,
+- and a firmware-aware, transport-aware Intel backend boundary.
+- and a bounded active scan surface.
+- and a bounded transport-initialization surface.
+
+The current bounded implementation is therefore no longer just static plumbing. It now has a real
+user-facing Wi‑Fi orchestration flow through `netctl`, a real control daemon state machine, and a
+real Intel-targeted firmware/transport preparation boundary.
+
+That is the first substantial Wi‑Fi bring-up slice, but not the final result.
+
+### Still missing after the current slice
+
+- real Intel transport initialization
+- actual firmware loading/prepare action on Redox target hardware
+- scan implementation against real hardware
+- authentication and association
+- WPA2 key negotiation on a real link
+- DHCP/static IP handoff on a real associated wireless interface
+- runtime validation on Intel hardware or a realistic guest path
+
 ### 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 the target scope to Intel Arrow Lake and older Intel Wi-Fi chips
 - freeze security scope to open + WPA2-PSK
- define `net-wifi-experimental` as the package-group slice for first Wi-Fi support
+- define `net-wifi-experimental` as the package/config slice for first Wi-Fi support
 - document unsupported wireless features explicitly

 **Exit criteria**:

- one hardware family is selected
+- Intel target scope is explicit
 - support language and non-goals are written down
+- the repo has a standalone tracked Wi-Fi experimental profile (`config/redbear-wifi-experimental.toml`) extending the minimal Red Bear baseline

 ---

-### Phase W1 — Driver Substrate Fit
+### Phase W1 — Intel Driver Substrate Fit

-**Goal**: Prove the chosen Wi-Fi family can fit Red Bear’s existing driver primitives.
+**Goal**: Prove the Intel target family can fit Red Bear’s existing driver primitives and identify
+the minimum additional compatibility surface required.

 **What to do**:

- map the chosen device family onto `redox-driver-sys`
+- map the Intel target 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
+- identify exactly which `linux-kpi` additions are mandatory for Intel transport/firmware bring-up
+- keep those additions below the wireless control-plane boundary

 **Exit criteria**:

- one chosen device can be discovered, initialized, and paired with its firmware-loading path
+- one Intel target device can be discovered, initialized, and paired with its firmware-loading path

 ---

@@ -341,12 +671,12 @@ This scope freeze is required to keep the first milestone honest and achievable.

 ### Phase W7 — Broader Hardware and `linux-kpi` Reassessment

-**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one FullMAC path works.
+**Goal**: Reassess whether Red Bear wants to widen Wi‑Fi support after one bounded Intel 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
+- only after one bounded Intel transport/association path is validated, decide whether a wider
+  multi-family or deeper `linux-kpi` path is worth the cost
 - do not assume this is automatically justified

 **Exit criteria**:
@@ -375,7 +705,7 @@ Until the validation gates above are passed, Red Bear should use language such a

 - “Wi-Fi is not supported yet”
 - “Wi-Fi remains experimental and hardware-specific”
- “The current wireless path is an experimental FullMAC-first bring-up”
+- “The current wireless path is an experimental Intel bounded-transport bring-up”

 Avoid language such as:

@@ -390,7 +720,7 @@ unless profile-scoped validation evidence exists.
 The best Red Bear Wi-Fi path is **native-first**:

 - native wireless control plane
- one experimental FullMAC family first
+- one experimental bounded Intel family path first
 - `firmware-loader` + `redox-driver-sys` underneath
 - optional narrow `linux-kpi` glue only where useful
 - native `smolnetd` / `netcfg` / `redbear-netctl` reused only after association
@@ -0,0 +1,78 @@
+# Wi‑Fi Validation Issue Template
+
+Use this template after the first real bare-metal or VFIO-backed Intel Wi‑Fi validation run.
+
+## Environment
+
+- Run type: bare metal / VFIO-backed guest
+- Host PCI BDF (if VFIO):
+- Expected host driver before VFIO (if applicable):
+- Red Bear profile: `wifi-open-bounded` / `wifi-dhcp` / other
+- Interface: `wlan0` / other
+- Intel device model:
+
+## Commands Used
+
+List the exact command(s) you ran, for example:
+
+```bash
+redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json
+```
+
+or
+
+```bash
+./local/scripts/run-wifi-passthrough-validation.sh --host-pci 0000:xx:yy.z --host-driver iwlwifi --artifact-dir ./wifi-validation-YYYYMMDD-HHMMSS
+```
+
+## Expected Outcome
+
+Describe what you expected to happen.
+
+## Actual Outcome
+
+Describe what actually happened.
+
+## Artifact Paths
+
+- Capture JSON:
+- Metadata JSON (if VFIO):
+- Packaged tarball (if created):
+- Serial log:
+- Console log:
+
+## Analyzer Output
+
+Paste the output of:
+
+```bash
+redbear-phase5-wifi-analyze <capture.json>
+```
+
+## Key Signals
+
+- `driver_probe` result:
+- `driver_status` result:
+- `wifictl_probe` result:
+- `wifictl_status` result:
+- `netctl_status` result:
+- `wifi_connect_result`:
+- `wifi_disconnect_result`:
+- `last_error`:
+
+## Suspected Blocker Class
+
+One or more of:
+
+- device-detection
+- firmware
+- association-control-path
+- disconnect-lifecycle
+- dhcp-or-addressing
+- reporting-surface
+- runtime-failure
+- bounded-lifecycle-pass-no-real-link-proof
+
+## Notes
+
+Anything else that seems relevant for reproducing or narrowing the issue.
@@ -0,0 +1,215 @@
+# Red Bear OS Wi‑Fi Validation Runbook
+
+This runbook is the canonical operator path for exercising the current bounded Intel Wi‑Fi stack on
+either a real Red Bear OS target or a VFIO-backed Red Bear guest.
+
+It does **not** claim that Wi‑Fi is fully solved. Its job is to make the remaining hardware/runtime
+validation step reproducible and evidence-oriented.
+
+## Goal
+
+Produce one or both of the following from a real target execution:
+
+- a successful bounded Wi‑Fi lifecycle run (`redbear-phase5-wifi-check`)
+- a structured evidence bundle (`redbear-phase5-wifi-capture`) for debugging real failures
+
+## Path A — Bare Metal Runtime Validation
+
+Use this when Red Bear OS is booted on a real machine with a supported Intel Wi‑Fi device.
+
+### In target runtime
+
+For an interactive operator path before or alongside the packaged checkers, the new console client is:
+
+```bash
+redbear-netctl-console
+```
+
+It is a Redox-native **ncurses** terminal client, and it uses the same bounded `/scheme/wifictl`
+and `/etc/netctl` surfaces as the scripted/operator flows.
+
+```bash
+redbear-phase5-wifi-run wifi-open-bounded wlan0 /tmp/redbear-phase5-wifi-capture.json
+test-wifi-baremetal-runtime.sh
+```
+
+### Artifacts to preserve
+
+- `/tmp/redbear-phase5-wifi-capture.json`
+- terminal output from `redbear-phase5-wifi-check`
+- terminal output from `test-wifi-baremetal-runtime.sh`
+- any serial console log captured during the run
+
+Recommended host-side naming after copying artifacts off the target:
+
+- `wifi-baremetal-capture.json`
+- `wifi-baremetal-serial.log`
+- `wifi-baremetal-console.log`
+
+Recommended staging pattern on the host:
+
+```bash
+run_dir=./wifi-baremetal-$(date +%Y%m%d-%H%M%S)
+mkdir -p "$run_dir"
+# copy the capture/log files into that directory
+./local/scripts/package-wifi-validation-artifacts.sh \
+  "${run_dir}.tar.gz" \
+  "$run_dir"
+```
+
+Optional packaging step on the host:
+
+```bash
+./local/scripts/package-wifi-validation-artifacts.sh
+```
+
+The resulting tarball now includes a small manifest file with the packaged paths and file checksums
+for regular files when `sha256sum` is available on the host.
+
+Optional summary step on the host:
+
+```bash
+./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-baremetal-capture.json
+# or
+./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-validation-artifacts.tar.gz
+# or use the packaged analyzer directly on the captured JSON
+redbear-phase5-wifi-analyze ./wifi-baremetal-capture.json
+```
+
+Optional one-shot post-run step on the host:
+
+```bash
+./local/scripts/finalize-wifi-validation-run.sh \
+  ./wifi-baremetal-capture.json \
+  ./wifi-validation-artifacts.tar.gz \
+  ./wifi-baremetal-serial.log \
+  ./wifi-baremetal-console.log
+```
+
+## Path B — VFIO/QEMU Validation
+
+Use this when a host can safely detach an Intel Wi‑Fi PCI function and pass it through to a Red Bear
+guest.
+
+### On the host
+
+First, validate the host prerequisites:
+
+```bash
+sudo ./local/scripts/validate-wifi-vfio-host.sh \
+  --host-pci 0000:xx:yy.z \
+  --expect-driver iwlwifi
+```
+
+This preflight now exits non-zero when blockers are found, so it is safe to use as an automation
+gate before attempting VFIO passthrough validation.
+
+Then run the full passthrough validation wrapper:
+
+```bash
+sudo ./local/scripts/run-wifi-passthrough-validation.sh \
+  --host-pci 0000:xx:yy.z \
+  --host-driver iwlwifi \
+  --artifact-dir ./wifi-validation-$(date +%Y%m%d-%H%M%S)
+```
+
+Default output artifacts from that wrapper:
+
+- `./wifi-passthrough-capture.json`
+- `./wifi-passthrough-capture.json.meta.json`
+
+If `--artifact-dir` is provided, those files are written into that directory instead.
+
+Recommended packaging step afterwards:
+
+```bash
+./local/scripts/package-wifi-validation-artifacts.sh \
+  ./wifi-passthrough-artifacts.tar.gz \
+  ./wifi-validation-YYYYMMDD-HHMMSS
+```
+
+That tarball also includes the manifest/checksum file described above.
+
+Optional summary step afterwards:
+
+```bash
+./local/scripts/summarize-wifi-validation-artifacts.sh ./wifi-passthrough-artifacts.tar.gz
+# or
+redbear-phase5-wifi-analyze ./wifi-passthrough-capture.json
+```
+
+Optional one-shot post-run step afterwards:
+
+```bash
+./local/scripts/finalize-wifi-validation-run.sh \
+  ./wifi-passthrough-capture.json \
+  ./wifi-passthrough-artifacts.tar.gz \
+  ./wifi-passthrough-capture.json.meta.json
+```
+
+For structured follow-up after a failed run, use:
+
+- `local/docs/WIFI-VALIDATION-ISSUE-TEMPLATE.md`
+
+You can override those paths explicitly if needed:
+
+```bash
+sudo ./local/scripts/run-wifi-passthrough-validation.sh \
+  --host-pci 0000:xx:yy.z \
+  --host-driver iwlwifi \
+  --capture-output ./wifi-passthrough-capture.json \
+  --metadata-output ./wifi-passthrough-capture.meta.json
+```
+
+The wrapper handles:
+
+1. binding the selected device to `vfio-pci`
+2. launching the Red Bear guest passthrough harness
+3. running `redbear-phase5-network-check` and `redbear-phase5-wifi-run` inside the guest
+4. collecting the packaged Wi‑Fi capture bundle back to the host
+5. writing a host-side metadata sidecar for the run
+6. restoring the host driver afterwards
+
+### Artifact to preserve
+
+- `./wifi-passthrough-capture.json`
+- `./wifi-passthrough-capture.meta.json`
+- full terminal log from the wrapper invocation
+
+Optional packaging step on the host:
+
+```bash
+./local/scripts/package-wifi-validation-artifacts.sh
+```
+
+## Minimum Evidence for a Real Runtime Attempt
+
+At minimum, keep all of the following together:
+
+- the capture JSON bundle
+- the console output of the checker/wrapper
+- the exact PCI BDF used for the Intel Wi‑Fi device
+- whether the run was bare metal or VFIO/QEMU
+
+## What Success Means Today
+
+Current success is still **bounded** success:
+
+- the Intel driver/runtime lifecycle can be exercised on a real target
+- the Wi‑Fi control/profile/reporting stack can observe that lifecycle, including honest bounded
+  pending/associating connect state when real association is not yet proven
+- the default bounded validation profile is `wifi-open-bounded`, which intentionally avoids turning
+  DHCP handoff into a false requirement for lifecycle-only validation
+- the packaged runtime checker currently proves that bounded open-profile path by default; WPA2-PSK
+  is implemented and covered by host/unit-level regressions, but is not yet the default packaged
+  runtime validation path
+- a structured evidence bundle is captured for debugging
+
+This is **not yet** the same as:
+
+- real AP scan/association proof
+- real packet/data-path proof
+- DHCP success over a true wireless link
+- validated end-to-end Wi‑Fi connectivity
+
+Those remain the next debugging targets after the first real target execution.
@@ -0,0 +1,77 @@
+# `wifictl:` Scheme Reference
+
+This document describes the current bounded `/scheme/wifictl` surface exposed by
+`redbear-wifictl`.
+
+It is a reference for validation and debugging of the current Intel Wi‑Fi slice. It does **not**
+imply that Wi‑Fi connectivity is fully supported.
+
+## Root Layout
+
+Top-level entries:
+
+- `wifictl:/ifaces`
+- `wifictl:/capabilities`
+
+## Per-interface entries
+
+For each interface under `wifictl:/ifaces/<iface>/`, the scheme currently exposes:
+
+### Read-only status/state nodes
+
+- `status`
+- `link-state`
+- `firmware-status`
+- `transport-status`
+- `transport-init-status`
+- `activation-status`
+- `connect-result`
+- `disconnect-result`
+- `scan-results`
+- `last-error`
+
+### Read/write profile/config nodes
+
+- `ssid`
+- `security`
+- `key`
+
+### Write-triggered control nodes
+
+- `scan`
+- `prepare`
+- `transport-probe`
+- `init-transport`
+- `activate-nic`
+- `connect`
+- `disconnect`
+- `retry`
+
+## Current bounded lifecycle
+
+The bounded Intel path currently treats the Wi‑Fi lifecycle as:
+
+1. `prepare`
+2. `transport-probe`
+3. `init-transport`
+4. `activate-nic`
+5. `connect`
+6. `disconnect`
+7. `retry`
+
+The scheme records the last reported bounded connect/disconnect metadata in `connect-result` and
+`disconnect-result`.
+
+## Interpretation guidance
+
+- Presence of the scheme means the control surface exists, not that a real Wi‑Fi link is proven.
+- `connect-result` and `disconnect-result` are lifecycle evidence surfaces, not proof of real AP
+  authentication or real packet flow.
+- `scan-results` may reflect bounded or synthetic runtime outcomes unless and until hardware-backed
+  scan evidence is captured on a real target.
+
+## Related documents
+
+- `local/docs/WIFI-IMPLEMENTATION-PLAN.md`
+- `local/docs/WIFI-VALIDATION-RUNBOOK.md`
+- `local/docs/SCRIPT-BEHAVIOR-MATRIX.md`
@@ -33,6 +33,7 @@ This is a repo-governance document, not a subsystem deep dive.
 | `seatd` runtime path | **mixed-transition** | recipe-level decision still local | It builds and is integrated into KDE-facing configs, but runtime trust still trails the packaging story. |
 | `redox-driver-sys` | **local-overlay-owner** | local overlay | Red Bear-owned driver substrate. |
 | `linux-kpi` | **local-overlay-owner** | local overlay | Red Bear-owned compatibility layer. |
+| `redbear-iwlwifi` | **local-overlay-owner** | local overlay | Bounded Intel Wi-Fi driver-side package below the native Red Bear Wi-Fi control plane; current scope is probe, status, firmware prepare, transport probe/init, NIC activation, bounded scan/connect/disconnect lifecycle, and retry. |
 | `redox-drm` / `amdgpu` | **local-overlay-owner** | local overlay | Red Bear-owned graphics/driver work. |
 | `firmware-loader` | **local-overlay-owner** | local overlay | Red Bear-owned runtime infrastructure. |
 | relibc compatibility overlays | **mixed-transition** | upstream + local overlay | Prefer upstream where available; keep only the overlays that still prove necessary after fresh-source reapply and downstream rebuild. |
@@ -19,8 +19,10 @@ reproducible, reviewable, and upstream-friendly.
 Tracked Red Bear profiles are:

 - `redbear-minimal`
+- `redbear-bluetooth-experimental`
 - `redbear-desktop`
 - `redbear-full`
+- `redbear-wayland`
 - `redbear-kde`
 - `redbear-live`

@@ -54,6 +56,11 @@ why it is intentionally excluded.

 Primary validation baseline: console, storage, package flow, and wired networking.

+### `redbear-bluetooth-experimental`
+
+First bounded Bluetooth validation profile: explicit-startup, USB-attached, BLE-first, and
+experimental only.
+
 ### `redbear-desktop`

 Main integration profile for desktop-oriented Red Bear services without making KDE the default.
@@ -62,6 +69,10 @@ Main integration profile for desktop-oriented Red Bear services without making K

 Expanded desktop/integration target that includes more runtime pieces and graphics-path bring-up.

+### `redbear-wayland`
+
+Dedicated Wayland runtime validation profile layered above the current Red Bear service baseline.
+
 ### `redbear-kde`

 Dedicated KDE/Plasma bring-up profile.