Refresh architecture and integration docs

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-04-18 17:58:32 +01:00
parent ca32adf6ba
commit 8c3fac8e84
8 changed files with 98 additions and 102 deletions
@@ -231,8 +231,9 @@ Configs are TOML files that include each other:
 wayland.toml → desktop.toml → desktop-minimal.toml → minimal.toml → base.toml
 ```
-Each config selects packages and overrides init scripts. For example, `wayland.toml`
+Each config selects packages and overrides init scripts. The tracked Red Bear desktop direction now
-overrides the orbital init to launch `cosmic-comp` instead of `orblogin`.
+centers on the KWin Wayland target, while bounded validation configs remain separate from that
 forward desktop path.
 ### Build Flow
@@ -249,25 +250,11 @@ make all
 ## 7. Existing Wayland/X11 Support
-### X11 (Working)
+### Compatibility and Validation Surfaces
-Config: `config/x11.toml`
+- legacy compatibility configs remain in-tree as references
- X.org with dummy video driver inside Orbital
+- the tracked Red Bear desktop direction is KWin Wayland
- GTK3, MATE desktop, Mesa EGL
+- bounded validation configs remain separate from the forward desktop target
 - DRI3 enabled
 - Software rendering only
 ### Wayland (Experimental, WIP)
 Config: `config/wayland.toml`
 - **21 Wayland recipes** in `recipes/wip/wayland/`
 - **cosmic-comp**: partially working, performance issues, no keyboard input
 - **smallvil** (Smithay): ported, basic compositor running
 - **wlroots**: not compiled or tested
 - **sway**: not compiled or tested
 - **hyprland**: not compiled or tested
 - **niri**: needs Smithay port
 - **xwayland**: partially patched, needs wayland-client fixes
 ### Key Blockers for Wayland
@@ -275,4 +262,4 @@ Config: `config/wayland.toml`
 2. **No GPU acceleration** (only software rendering)
 3. **Input/runtime integration remains incomplete** (`evdevd`, `udev-shim`, and libinput exist, but compositor input is not fully validated)
 4. **DRM/KMS runtime validation remains incomplete** (`redox-drm` exists in-tree, but full Wayland/driver runtime integration is still open)
-5. **cosmic-comp**: keyboard/input integration and performance issues remain
+5. **runtime compositor/session proof** remains incomplete
@@ -19,7 +19,7 @@ Use the matrix below as the authoritative phase summary before reading the older
 | Layer / Phase | Current repo state | Evidence |
 |---|---|---|
-| P0 ACPI / bare-metal boot | Complete in-tree | `local/docs/ACPI-FIXES.md`, `local/patches/kernel/redox.patch`, `local/patches/base/redox.patch` |
+| P0 ACPI / bare-metal boot | **Materially complete for boot baseline.** Implemented: kernel RSDP/RSDT/XSDT/MADT/FADT parsing, typed `StartupError` in `acpid`, AML mutex real state (`aml_physmem.rs`), EC widened accesses via byte transactions (`ec.rs`), kstop-based shutdown eventing (kernel registers `/scheme/kernel.acpi/kstop`, `acpid` subscribes, `redbear-sessiond` emits D-Bus `PrepareForShutdown`). Sleep state transitions (`\_Sx` beyond `\_S5`) and sleep eventing are **known gaps**. DMAR module present in `acpid` but not wired; effectively owned by `iommu` daemon. | `local/docs/ACPI-FIXES.md`, `local/docs/ACPI-IMPROVEMENT-PLAN.md`, `local/patches/kernel/redox.patch`, `local/patches/base/redox.patch`, `recipes/core/base/source/drivers/acpid/src/main.rs`, `recipes/core/base/source/drivers/acpid/src/aml_physmem.rs`, `recipes/core/base/source/drivers/acpid/src/ec.rs`, `local/recipes/system/redbear-sessiond/source/src/acpi_watcher.rs` |
 | P1 driver infrastructure | Complete in-tree, compile-oriented | `local/recipes/drivers/redox-driver-sys/`, `local/recipes/drivers/linux-kpi/`, `local/recipes/system/firmware-loader/` |
 | P2 DRM / AMD+Intel display | Complete in-tree, hardware validation pending | `local/docs/P2-AMD-GPU-DISPLAY.md`, `local/recipes/gpu/redox-drm/`, `local/recipes/gpu/amdgpu/` |
 | P3 POSIX + input | Implemented in-tree; consumer-visible `signalfd`/`timerfd`/`eventfd`/`open_memstream` header-export path fixed in this repo pass; runtime validation still pending | `recipes/core/relibc/source/src/header/`, `recipes/core/relibc/source/include/sys/signalfd.h`, `local/patches/relibc/`, `local/recipes/system/evdevd/`, `local/recipes/system/udev-shim/` |
@@ -116,9 +116,8 @@ implemented phase with its own config/recipe/doc boundary.
 | Component | Status | Recipe | Blocker |
 |-----------|--------|--------|---------|
 | libwayland | Patched, downstream compatibility workarounds remain | `recipes/wip/wayland/libwayland/` | Reduce/remove `redox.patch` and verify runtime behavior |
-| cosmic-comp | No keyboard input | `recipes/wip/wayland/cosmic-comp/` | Layer 3 libinput |
+| bounded validation compositor | Incomplete session | `recipes/wip/wayland/*` historical references | Layer 2+3 for DRM+input validation |
-| smallvil (Smithay) | Basic, slow | `recipes/wip/wayland/smallvil/` | Layer 2+3 for DRM+input |
+| additional historical compositor references | Not active | `recipes/wip/wayland/*` historical references | Not part of the forward desktop path |
 | wlroots/sway/hyprland | Not tested | `recipes/wip/wayland/wlroots/` | Layer 2+3 |
 ### Layer 5: KDE Plasma
@@ -128,7 +127,7 @@ implemented phase with its own config/recipe/doc boundary.
 | KDE Frameworks | Partially ported in-tree | [05 Phase KDE-B](05-KDE-PLASMA-ON-REDOX.md) |
 | KWin | Recipe exists, still incomplete | [05 Phase KDE-C](05-KDE-PLASMA-ON-REDOX.md) |
 | Plasma Shell | Recipe exists, still incomplete | [05 Phase KDE-C](05-KDE-PLASMA-ON-REDOX.md) |
-| D-Bus | **Ported** | `config/x11.toml` has it working |
+| D-Bus | **Ported** | Runtime evidence now belongs to Red Bear desktop/KDE profiles rather than any alternate windowing path being a peer direction |
 ### Layer 6: Linux Driver Compatibility
@@ -163,11 +162,11 @@ implemented phase with its own config/recipe/doc boundary.
 - **Test**: `modetest -M intel` shows display modes
 - **Delivers**: KMS modesetting, hardware display control
-### Milestone M4: "Wayland compositor with input + display" (2-4 weeks after M2+M3)
+### Milestone M4: "Wayland compositor validation with input + display" (2-4 weeks after M2+M3)
- Add Redox backends to Smithay (input + DRM + EGL)
+- Add Redox backends to the bounded validation compositor stack (input + DRM + EGL)
- Build `smallvil` with Redox backends
+- Build the bounded validation compositor path with Redox backends
- **Test**: Compositor takes over display, keyboard/mouse work
+- **Test**: Validation compositor takes over display, keyboard/mouse work
- **Delivers**: First fully functional Wayland compositor on Redox
+- **Delivers**: Bounded Wayland compositor proof on Redox, not the final production desktop path
 ### Milestone M5: "Qt application runs" (6-8 weeks after M4)
 - Port `qtbase` with Wayland QPA
@@ -11,12 +11,11 @@ porting notes.
 ## Current State
- `config/wayland.toml` exists — it remains the bounded validation path that launches the
+- `config/wayland.toml` exists — it remains the bounded validation path, not the production desktop path
  `smallvil` harness via `orbital-wayland`, not the production desktop path
 - 21 Wayland recipes in `recipes/wip/wayland/` — most untested
 - `libwayland` 1.24.0 now rebuilds with a much smaller `redox.patch`; the P3 POSIX path (`signalfd`, `timerfd`, `eventfd`, `open_memstream`, `MSG_CMSG_CLOEXEC`, `MSG_NOSIGNAL`) is back on the native path, and the remaining patch is down to Redox-specific build quirks
- `smallvil` (Smithay) remains the bounded validation compositor path, not the production desktop goal
+- the bounded validation compositor path remains separate from the production desktop goal
- `cosmic-comp` builds but still has no working keyboard input; the remaining issue is runtime/input integration, not simply the absence of a libinput recipe
+- the remaining compositor/runtime issue is still input integration, not simply the absence of a libinput recipe
 - `libdrm` builds with amdgpu and Intel enabled
 - Mesa builds with EGL+GBM+GLES2 (software via LLVMpipe; hardware acceleration still requires kernel DMA-BUF)
 - **evdevd** (`scheme:evdev`) provides Linux-compatible `/dev/input/eventX` interface
@@ -51,7 +50,7 @@ For the current Wayland runtime entrypoint in this repo, use:
 > (`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`), Wayland compositor work falls under Phase 2.
 > The scripts still work under their original names.
-That path is the current bounded smallvil validation target. The production desktop path is
+That path is the current bounded validation target. The production desktop path is
 `config/redbear-kde.toml` with `kwin_wayland`.
 Current runtime evidence for that target:
@@ -59,16 +58,15 @@ Current runtime evidence for that target:
 - `redbear-wayland` builds to a bootable image
 - the image boots to a real login prompt in QEMU/UEFI
 - `redbear-phase4-wayland-check` runs in-guest and confirms the Wayland launch surface is present
- `smallvil` reaches xkbcommon initialization and selects the Redox EGL platform in the live guest
+- the compositor reaches xkbcommon initialization and selects the Redox EGL platform in the live guest
 - the direct launcher `local/scripts/test-phase4-wayland-qemu.sh` now boots the built
  `redbear-wayland` disk image instead of re-entering the build pipeline
-For the runtime-validation pass, keep the **validation target** intentionally small: `smallvil`
+For the runtime-validation pass, keep the **validation target** intentionally small as a bounded
-as the compositor harness and not as the production desktop goal. The current `redbear-wayland`
+compositor harness and not as the production desktop goal. The current `redbear-wayland`
 profile still inherits the broader desktop package set from `desktop.toml`, but this repo's
-Wayland validation is specifically about the `orbital-wayland` → `smallvil` path. It is a bounded
+Wayland validation remains a bounded regression harness subordinate to the `redbear-kde` /
-regression harness subordinate to the `redbear-kde` / `kwin_wayland` production path, not a peer
+`kwin_wayland` production path, not a peer desktop direction.
 desktop direction.
 ---
@@ -460,12 +458,12 @@ impl IntelDriver {
 ## Historical Step 4: Working Wayland Compositor (4-6 weeks after Steps 1-3)
-### Historical staging note: smallvil before KWin
+### Historical staging note: bounded compositor validation before KWin
-This section is historical context only. It explains why `smallvil` was used earlier as a bounded
+This section is historical context only. It explains why a smaller compositor was used earlier as a bounded
 validation compositor before the KWin-first production path became the repo's architecture.
-**Why smallvil was used first as a validation compositor:**
+**Why a smaller compositor was used first as a validation compositor:**
 - Pure Rust — no C++ toolchain issues
 - Already has a Redox branch (`https://github.com/jackpot51/smithay`, branch `redox`)
 - Smithay's input backend is pluggable — write a Redox-specific one
@@ -521,7 +519,7 @@ impl DrmBackend for RedoxDrmBackend {
 ### Recipe to add/modify
 ```toml
-# recipes/wip/wayland/smallvil/recipe.toml (modify existing)
+# recipes/wip/wayland/<validation-compositor>/recipe.toml (modify existing)
 [source]
 git = "https://github.com/jackpot51/smithay"
 branch = "redox"
@@ -537,26 +535,26 @@ dependencies = [
    "evdevd",      # for input
    "seatd",       # for session management
 ]
-cargopackages = ["smallvil"]
+cargopackages = ["<validation-compositor>"]
 ```
 ### Verification
-1. `smallvil` launches with DRM backend — takes over display
+1. the validation compositor launches with DRM backend — takes over display
 2. Keyboard and mouse work via evdevd
 3. `libcosmic-wayland_application` renders a window on the compositor
 4. Screenshot shows the window
 ---
-## Historical Step 5: Enable cosmic-comp and Other Compositors
+## Historical Step 5: Additional compositor experiments
 Once Steps 1-4 are done:
-1. **cosmic-comp**: Uncomment libinput dependency in recipe, rebuild
+1. Re-enable additional historical compositor experiments only if they serve bounded validation needs
-2. **wlroots**: Build with libdrm + libinput + GBM
+2. Keep DRM + libinput + GBM experimentation explicitly subordinate to the canonical KWin path
-3. **sway**: Should work once wlroots builds
+3. Treat any extra compositor work as historical/reference exploration rather than a forward desktop path
-4. **KWin**: See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path; `05-KDE-PLASMA-ON-REDOX.md` for historical rationale
+4. For the canonical desktop path, see `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`; for historical rationale, see `05-KDE-PLASMA-ON-REDOX.md`
 ---
@@ -449,17 +449,17 @@ seatd = {}
 evdevd = {}
 drmd = {}
-# Override init to launch KDE session
+# Historical example: launch KDE session
 [[files]]
-path = "/usr/lib/init.d/20_orbital"
+path = "/usr/lib/init.d/20_display"
 data = """
 requires_weak 10_net
 notify audiod
-nowait VT=3 orbital orbital-kde
+nowait VT=3 redbear-kde-session
 """
 [[files]]
-path = "/usr/bin/orbital-kde"
+path = "/usr/bin/redbear-kde-session"
 mode = 0o755
 data = """
 #!/usr/bin/env bash
@@ -518,7 +518,7 @@ Once Qt + KDE Frameworks are ported, these apps should compile with minimal patc
 ### D-Bus (Already Ported)
 D-Bus is ported, and current KDE-facing runtime wiring belongs to the Red Bear desktop/KDE profiles.
-It should not be framed as an X11-only or X11-primary integration surface.
+It should not be framed as an alternate-windowing-primary integration surface.
 ### Audio: PulseAudio PipeWire Shim Needed
 KDE expects PulseAudio or PipeWire for audio. Redox has its own `scheme:audio`.
@@ -556,4 +556,4 @@ KDE uses NetworkManager for network configuration. Redox has `smolnetd`.
 **Critical insight**: The Qt Foundation phase is the highest-risk phase.
 If Qt compilation hits unexpected relibc gaps, the entire KDE timeline shifts.
 Mitigation: start Qt porting early, even before DRM/input is complete,
-using software rendering and Orbital backend as a test environment.
+using software rendering and a bounded test environment.
@@ -99,19 +99,17 @@ echo 'PODMAN_BUILD?=0' > .config
 ### Select Build Configuration
 Mainline configs still exist, but tracked Red Bear work should normally be built and validated
-through the first-class `redbear-*` profiles.
+through the tracked `redbear-*` profiles. For the desktop direction specifically, `redbear-kde`
 is the tracked default target.
 Available configs (in `config/`):
 | Config | Description |
 |---|---|
-| `minimal` | Bare minimum bootable system |
+| `redbear-minimal` | Minimal tracked Red Bear image |
-| `server` | Server-oriented (no GUI) |
+| `redbear-full` | Broader tracked integration image |
-| `desktop-minimal` | Orbital + basic GUI apps |
+| `redbear-kde` | Tracked default KWin Wayland image |
-| `desktop` | COSMIC apps + installer |
+| `redbear-live` | Live image following the tracked desktop target |
 | `wayland` | Wayland compositor (experimental) |
 | `x11` | X.org + MATE desktop |
 | `demo` | Demo apps |
 ## Building
@@ -121,7 +119,7 @@ Available configs (in `config/`):
 make all
 ```
-This produces `build/x86_64/desktop/harddrive.img`.
+This produces `build/x86_64/redbear-kde/harddrive.img`.
 ### Export External Toolchain
@@ -147,16 +145,13 @@ For the full layout and rationale, see `local/docs/EXTERNAL-TOOLCHAIN.md`.
 ```bash
 # Preferred Red Bear wrapper:
 ./local/scripts/build-redbear.sh redbear-desktop
 ./local/scripts/build-redbear.sh redbear-minimal
 ./local/scripts/build-redbear.sh redbear-wayland
 ./local/scripts/build-redbear.sh redbear-full
 ./local/scripts/build-redbear.sh redbear-kde
 ./local/scripts/build-redbear.sh redbear-live
 # Direct make is still valid when needed:
-make all CONFIG_NAME=redbear-desktop
+make all CONFIG_NAME=redbear-kde
 make all CONFIG_NAME=redbear-wayland
 ```
 For tracked Red Bear work, prefer the `redbear-*` profiles over older mainline profile names.
@@ -164,8 +159,8 @@ For tracked Red Bear work, prefer the `redbear-*` profiles over older mainline p
 ### Build a Live ISO
 ```bash
-make live
+make live CONFIG_NAME=redbear-live
-# Produces: build/x86_64/desktop/redox-live.iso
+# Produces: build/x86_64/redbear-live/redox-live.iso
 ```
 ### Rebuild After Changes
@@ -179,9 +174,12 @@ make rebuild    # Clean rebuild of filesystem image
 ### QEMU (Recommended)
 ```bash
-# Desktop with Orbital GUI:
+# Default tracked KWin Wayland desktop target:
 make qemu
 # Explicit KWin Wayland desktop target:
 make qemu CONFIG_NAME=redbear-kde
 # With more RAM:
 make qemu QEMUFLAGS="-m 4G"
@@ -202,7 +200,7 @@ make virtualbox
 ```bash
 # Write image to USB device (replace sdX with your device):
-sudo dd if=build/x86_64/desktop/harddrive.img of=/dev/sdX bs=4M status=progress
+sudo dd if=build/x86_64/redbear-kde/harddrive.img of=/dev/sdX bs=4M status=progress
 ```
 ## Building Specific Packages (Recipes)
@@ -212,7 +210,7 @@ sudo dd if=build/x86_64/desktop/harddrive.img of=/dev/sdX bs=4M status=progress
 ```bash
 # Using the repo tool:
 ./target/release/repo cook recipes/libs/mesa
-./target/release/repo cook recipes/gui/orbital
+./target/release/repo cook recipes/wip/kde/kwin
 ```
 Under the Red Bear overlay model, remember:
@@ -264,7 +262,7 @@ cp target/release/myapp ${COOKBOOK_STAGE}/usr/bin/
 | Variable | Default | Description |
 |---|---|---|
 | `ARCH` | Host arch | Target architecture (x86_64, aarch64, i586, riscv64gc) |
-| `CONFIG_NAME` | `desktop` | Build config name |
+| `CONFIG_NAME` | `redbear-kde` | Build config name |
 | `PODMAN_BUILD` | `1` | Use Podman container |
 | `PREFIX_BINARY` | `1` | Use prebuilt toolchain (faster) |
 | `REPO_BINARY` | `0` | Use prebuilt packages (faster, no compilation) |
@@ -326,7 +324,7 @@ make distclean
 redox-master/
 ├── build/
 │   └── x86_64/
-│       └── desktop/
+│       └── redbear-kde/
 │           ├── harddrive.img      # Bootable disk image
 │           ├── redox-live.iso     # Live CD ISO
 │           ├── filesystem/        # Mounted filesystem (during build)
@@ -90,7 +90,7 @@ That means:
 ## Product Surfaces
-The first-class Red Bear profiles are:
+The tracked Red Bear profiles are:
 - `redbear-minimal`
 - `redbear-desktop`
@@ -99,7 +99,7 @@ The first-class Red Bear profiles are:
 - `redbear-kde`
 - `redbear-live`
-Each profile is a product surface, not just a build convenience.
+Each profile is a tracked build surface, but only `redbear-kde` is the forward desktop target.
 ### `redbear-minimal`
@@ -115,24 +115,28 @@ Scope:
 ### `redbear-desktop`
-Main integration profile for base desktop/runtime work.
+Supplementary integration profile for shared runtime work beneath the tracked desktop target.
 Scope:
 - Orbital desktop path,
 - runtime services,
 - diagnostics,
- base user-facing system bring-up.
+- shared bring-up support.
 Current role:
 - subordinate integration/support slice.
 ### `redbear-wayland`
-Dedicated Wayland runtime validation profile.
+Dedicated runtime validation profile.
 Scope:
 - narrow compositor/runtime path,
 - explicit validation target for Wayland stack correctness,
- not a claim of full desktop completeness.
+- not a claim of full desktop completeness,
 - subordinate to the KDE session goal.
 ### `redbear-full`
@@ -147,14 +151,20 @@ Scope:
 ### `redbear-kde`
-Dedicated KDE/Plasma bring-up profile.
+Dedicated KWin Wayland target desktop profile.
 Scope:
 - KWin,
 - Plasma session surfaces,
 - session packaging and dependencies,
- explicit documentation of limitations while still incomplete.
+- explicit documentation of limitations while still incomplete,
 - the tracked default compositor/session direction.
 ### Desktop policy
 - The intended primary desktop direction is KWin Wayland.
 - Validation work is subordinate to the KWin Wayland desktop goal.
 ### `redbear-live`
@@ -267,7 +277,7 @@ Current state:
 Acceptance:
- each first-class profile has a documented role,
+- each tracked profile has a documented role,
 - profile behavior is reproducible,
 - support labels are tied to profile-specific evidence.
@@ -13,17 +13,17 @@ For current Red Bear OS status, also read:
 - `docs/README.md` — canonical docs index + status matrix
 - `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` — canonical public implementation plan
 - `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` — current desktop stack build/runtime truth
 - `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` — current DRM-focused execution plan beneath the canonical desktop path
 - `local/docs/QT6-PORT-STATUS.md` — current Qt/KF6 package-level status
- `local/docs/AMD-FIRST-INTEGRATION.md` — deeper AMD/graphics technical roadmap
+- `local/docs/AMD-FIRST-INTEGRATION.md` — deeper AMD/graphics technical roadmap, useful detail but not the canonical desktop plan
 - `local/docs/WIP-MIGRATION-LEDGER.md` — current WIP ownership status
 - `local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — current script guarantees and non-guarantees
 - `local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md` — current assessment of the documentation corpus
 ## STRUCTURE
 ```
 docs/
-├── 01-REDOX-ARCHITECTURE.md   # Architecture reference: microkernel, scheme system, driver model, Orbital
+├── 01-REDOX-ARCHITECTURE.md   # Architecture reference: microkernel, scheme system, driver model, display architecture
 ├── 02-GAP-ANALYSIS.md         # Historical gap matrix with corrected current-state notes
 ├── 03-WAYLAND-ON-REDOX.md     # Historical Wayland implementation path + deeper rationale
 ├── 04-LINUX-DRIVER-COMPAT.md  # Driver-compat architecture reference + historical porting path
@@ -18,8 +18,9 @@ current/canonical versus historical/reference split obvious.
 > **Red Bear note:** newer subsystem plans can also live under `local/docs/` when they are Red Bear-
 > specific rather than general Redox architecture material. In particular, see
-> `local/docs/WIFI-IMPLEMENTATION-PLAN.md` for the current Wi-Fi direction and
+> `local/docs/WIFI-IMPLEMENTATION-PLAN.md` for the current Wi-Fi direction,
-> `local/docs/AMD-FIRST-INTEGRATION.md` for the AMD-focused hardware roadmap.
+> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path,
 > and `local/docs/AMD-FIRST-INTEGRATION.md` for AMD-specific technical detail only.
 > **Repository model:** RedBearOS relates to Redox in the same way Ubuntu relates to Debian.
 > Upstream Redox remains the base platform; Red Bear carries packaging, patch, validation, and
@@ -37,7 +38,7 @@ current/canonical versus historical/reference split obvious.
 | Document set | Role |
 |---|---|
 | `README.md`, `AGENTS.md`, `docs/README.md`, `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` | canonical repository-level policy and current execution model |
-| `local/docs/*IMPLEMENTATION-PLAN*.md`, `local/docs/*STATUS*.md`, `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | canonical current Red Bear subsystem plans and status |
+| `local/docs/*IMPLEMENTATION-PLAN*.md`, `local/docs/*STATUS*.md`, `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`, `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` | canonical current Red Bear subsystem plans and status |
 | `docs/01-REDOX-ARCHITECTURE.md` | architecture reference |
 | `docs/02-GAP-ANALYSIS.md`, `docs/03-WAYLAND-ON-REDOX.md`, `docs/04-LINUX-DRIVER-COMPAT.md`, `docs/05-KDE-PLASMA-ON-REDOX.md` | valuable but partly historical roadmap/design material |
@@ -67,9 +68,12 @@ current local subsystem plan.
 - `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — guarantees and non-guarantees for the main Wi-Fi and Bluetooth validation helpers plus core repo scripts
 - `../local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` — current Bluetooth architecture and rollout plan
 - `../local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md` — canonical operator path for the bounded Bluetooth Battery Level QEMU validation slice
 - `../local/docs/ACPI-IMPROVEMENT-PLAN.md` — current ACPI ownership, robustness, and validation plan
 - `../local/docs/ACPI-FIXES.md` — historical P0 ACPI bring-up ledger and status record
 - `../local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — current low-level controller and IRQ blocker plan
- `../local/docs/AMD-FIRST-INTEGRATION.md` — AMD-focused technical roadmap; historical AMD-first sequencing, not current platform-priority policy
+- `../local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` — current DRM-focused execution plan beneath the canonical desktop path, with equal Intel/AMD evidence bars
- `../local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md` — current assessment of documentation quality, canon, and remaining cleanup priorities
+- PCI vendor/device names in Red Bear runtime tools now come from the shipped `pciids` database; PCI quirk policy still lives in `../local/docs/QUIRKS-SYSTEM.md`
 - `../local/docs/AMD-FIRST-INTEGRATION.md` — AMD-focused technical roadmap and hardware detail only, not the canonical desktop plan
 - `../local/docs/DESKTOP-STACK-CURRENT-STATUS.md` — canonical current build/runtime truth summary for the desktop stack
 These local Red Bear plans should be treated as first-class subsystem references for USB, Wi-Fi,
@@ -82,7 +86,7 @@ at a higher level.
 - `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee
 - `../local/docs/EXTERNAL-TOOLCHAIN.md` — how to export a relocatable external `x86_64-unknown-redox-gcc` toolchain from the built prefix
-## Current State Summary (as of 2026-04-15)
+## Current State Summary (as of 2026-04-18)
 This summary is only a quick orientation layer. For canonical current-state detail, prefer:
@@ -92,8 +96,8 @@ This summary is only a quick orientation layer. For canonical current-state deta
 - `local/docs/PROFILE-MATRIX.md` for support-language by tracked profile,
 - and the active subsystem plans under `local/docs/` for detailed current workstreams.
- **Display server**: Orbital (custom, scheme-based) — works
+- **Desktop target**: the tracked default build now resolves to `CONFIG_NAME?=redbear-kde`
- **Wayland**: libwayland + wayland-protocols built. Smallvil/cosmic-comp remain partial runtime experiments.
+- **Wayland**: libwayland + wayland-protocols built. Runtime compositor proof remains incomplete.
 - **Qt6**: qtbase 6.11.0 (Core+Gui+Widgets+DBus+Wayland), qtdeclarative, qtsvg, qtwayland ALL BUILT
 - **D-Bus**: 1.16.2 built for Redox. Qt6DBus enabled.
 - **KF6 Frameworks**: all 32/32 built. Some packages remain shimmed or stubbed (kirigami stub-only, kf6-kio heavy shim).
@@ -103,7 +107,8 @@ This summary is only a quick orientation layer. For canonical current-state deta
 - **Networking**: native wired stack present (`pcid-spawner` → NIC daemon → `smolnetd`/`dhcpd`/`netcfg`), Red Bear ships a native `netctl` command, RTL8125 is wired into the existing Realtek autoload path, and the bounded Intel Wi‑Fi path now has host-tested profile start/stop plus interface-specific DHCP handoff without claiming real wireless connectivity.
 - **Wi-Fi profile target**: `config/redbear-wifi-experimental.toml` is the first explicit tracked image slice for bounded Intel Wi‑Fi validation, instead of spreading that claim across the generic desktop profiles.
 - **Bluetooth**: one bounded in-tree BLE-first experimental slice exists, and the Battery Level read-only workload now has a packaged in-guest checker plus a host QEMU harness; QEMU validation is still in progress, so broad desktop Bluetooth parity is still incomplete
- **KDE**: `redbear-kde.toml` exists and the recipe tree is populated, but the runtime stack is still incomplete.
+- **KDE direction**: `redbear-kde.toml` is the tracked KWin Wayland desktop direction, and the runtime stack is still incomplete.
 - **ACPI**: boot-baseline materially complete; implemented: typed startup errors in `acpid`, AML mutex real state, EC widened accesses via byte transactions, kstop-based shutdown eventing; **known gaps**: sleep state transitions and sleep eventing; DMAR present in `acpid` but not wired; bare-metal validation still outstanding. See `local/docs/ACPI-IMPROVEMENT-PLAN.md`.
 - **Linux driver compat**: linux-kpi now includes early wireless-subsystem compatibility scaffolding in addition to the earlier helper layer, redox-driver-sys and firmware-loader compile, and the bounded Intel Wi-Fi path now has host-tested scan/connect/disconnect/profile/reporting flows without claiming real hardware Wi-Fi connectivity.
 - **Wi-Fi validation tooling**: `redbear-phase5-wifi-check` and `redbear-phase5-wifi-capture` are now packaged in-guest helpers for bounded Intel Wi-Fi runtime validation and evidence capture on bare metal or VFIO-backed guests.
 - **Phase 5 naming note**: the bounded `redbear-phase5-network-check` / `test-phase5-network-qemu.sh` path proves desktop/network plumbing on `redbear-full` in QEMU; it does **not** mean the Wi-Fi implementation plan's later Phase W5 real-hardware reporting/recovery milestone is complete.
@@ -138,7 +143,6 @@ make qemu
 | Kernel | Microkernel | https://gitlab.redox-os.org/redox-os/kernel |
 | Base | Drivers + system components | https://gitlab.redox-os.org/redox-os/base |
 | relibc | C library (Rust) | https://gitlab.redox-os.org/redox-os/relibc |
 | Orbital | Display server + WM | https://gitlab.redox-os.org/redox-os/orbital |
 | RedoxFS | Default filesystem | https://gitlab.redox-os.org/redox-os/redoxfs |
 | libredox | System library | https://gitlab.redox-os.org/redox-os/libredox |
 | This repo | Build system | https://gitlab.redox-os.org/redox-os/redox |