Mark Wayland and driver-compat docs as historical references

docs/03-WAYLAND-ON-REDOX.md

@@ -11,12 +11,11 @@ porting notes.
 
 ## Current State
 
-- `config/wayland.toml` exists — now uses the Red Bear runtime-service fragments and launches the
+- `config/wayland.toml` exists — it remains the bounded validation path that launches the
-  `smallvil` path by default via `orbital-wayland`
+  `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) is still the recommended first runtime target because it is the smallest
+- `smallvil` (Smithay) remains the bounded validation compositor path, not the production desktop goal
-  compositor path already present in-tree
 - `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
 - `libdrm` builds with amdgpu and Intel enabled
 - Mesa builds with EGL+GBM+GLES2 (software via LLVMpipe; hardware acceleration still requires kernel DMA-BUF)
@@ -52,7 +51,8 @@ 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 smallvil-first Wayland validation target.
+That path is the current bounded smallvil validation target. The production desktop path is
+`config/redbear-kde.toml` with `kwin_wayland`.
 
 Current runtime evidence for that target:
 
@@ -63,17 +63,18 @@ Current runtime evidence for that target:
 - 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 first runtime-validation pass, keep the **runtime target** intentionally small: `smallvil`
+For the runtime-validation pass, keep the **validation target** intentionally small: `smallvil`
- as the compositor and no heavier secondary Wayland stack as the primary goal. The current
+as the compositor harness and not as the production desktop goal. The current `redbear-wayland`
- `redbear-wayland` profile still inherits the broader desktop package set from `desktop.toml`, but
+profile still inherits the broader desktop package set from `desktop.toml`, but this repo's
- Phase 4 validation in this repo is specifically about the `orbital-wayland` → `smallvil` path,
+Wayland validation is specifically about the `orbital-wayland` → `smallvil` path. It is a bounded
- not about treating every inherited desktop package as part of the Wayland validation surface.
+regression harness subordinate to the `redbear-kde` / `kwin_wayland` production path, not a peer
+desktop direction.
 
 ---
 
-## Step 1: Fix relibc POSIX Gaps (1-2 weeks)
+## Historical Step 1: Fix relibc POSIX Gaps (1-2 weeks)
 
-### What to implement
+### Historical implementation sketch
 
 Historically these were the 7 APIs that `libwayland/redox.patch` worked around. They now exist
 in-tree in relibc, and this repo pass restored the full build-side path for `signalfd`, `timerfd`,
@@ -215,7 +216,7 @@ After implementing all 7 APIs:
 
 ---
 
-## Step 2: evdev Input Daemon (4-6 weeks)
+## Historical Step 2: evdev Input Daemon (4-6 weeks)
 
 ### Architecture
 
@@ -332,7 +333,7 @@ mesonflags = [
 
 ---
 
-## Step 3: DRM/KMS Scheme (8-12 weeks)
+## Historical Step 3: DRM/KMS Scheme (8-12 weeks)
 
 ### Architecture
 
@@ -457,15 +458,18 @@ impl IntelDriver {
 
 ---
 
-## Step 4: Working Wayland Compositor (4-6 weeks after Steps 1-3)
+## Historical Step 4: Working Wayland Compositor (4-6 weeks after Steps 1-3)
 
-### Recommended: Smithay/smallvil first, then KWin
+### Historical staging note: smallvil before KWin
 
-**Why Smithay first:**
+This section is historical context only. It explains why `smallvil` 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:**
 - 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
-- Gets us a working compositor months before KWin is ported
+- Provided an earlier bounded compositor proof before the KWin session path was viable
 
 **What to modify in Smithay:**
 
@@ -545,7 +549,7 @@ cargopackages = ["smallvil"]
 
 ---
 
-## Step 5: Enable cosmic-comp and Other Compositors
+## Historical Step 5: Enable cosmic-comp and Other Compositors
 
 Once Steps 1-4 are done:
 

docs/04-LINUX-DRIVER-COMPAT.md

@@ -5,6 +5,9 @@
 > `local/recipes/system/firmware-loader/`, `local/recipes/gpu/redox-drm/`, and
 > `local/recipes/gpu/amdgpu/`. Treat the sections below as architecture rationale and porting notes,
 > not as an accurate statement that those components are still "not started".
+>
+> Treat the step-by-step recipe examples and timelines below as historical architecture notes, not
+> as the current execution plan or current package-status truth.
 
 ## Current State Snapshot
 
@@ -351,7 +354,7 @@ pub trait GpuDriver: Send + Sync {
 
 ## Concrete Porting Example: Intel i915 Driver
 
-### Step 1: Extract i915 from Linux kernel
+### Historical Step 1: Extract i915 from Linux kernel
 
 ```bash
 # Clone Linux kernel
@@ -363,7 +366,7 @@ tar cf intel-driver.tar linux/drivers/gpu/drm/i915/ \
     linux/arch/x86/include/
 ```
 
-### Step 2: Create recipe
+### Historical Step 2: Create recipe
 
 > **Historical recipe note:** the `recipes/wip/drivers/...` example below is part of the original
 > upstream-oriented porting path. Under the Red Bear overlay policy, upstream WIP driver recipes are
@@ -405,7 +408,7 @@ cp i915_redox.so ${COOKBOOK_STAGE}/usr/lib/redox/drivers/
 """
 ```
 
-### Step 3: Minimal patches needed
+### Historical Step 3: Minimal patches needed
 
 For i915 on Redox, these are the typical `#ifdef __redox__` changes:
 
@@ -446,7 +449,7 @@ void __iomem *regs = ioremap(pci_resource_start(pdev, 0), pci_resource_len(pdev,
 #endif
 ```
 
-### Step 4: Run as daemon
+### Historical Step 4: Run as daemon
 
 ```bash
 # In Redox init:
@@ -461,8 +464,9 @@ AMD's driver is larger and more complex than Intel's. The LinuxKPI approach is e
 
 ### Key challenges for amdgpu:
 
-1. **Firmware loading**: amdgpu needs proprietary firmware blobs. Redox has no firmware
+1. **Firmware loading**: amdgpu needs proprietary firmware blobs. Historically Redox lacked the
-   loading infrastructure yet. Need to implement:
+   needed firmware-loading path; the current repo now ships `firmware-loader`, and the remaining
+   work is validation of the GPU-facing runtime path rather than inventing the scheme from scratch:
    ```
    scheme:firmware/amdgpu/  — firmware blob storage
    request_firmware()       — compat function that reads from scheme
@@ -523,7 +527,7 @@ The daemon reads from Redox input schemes and exposes `/dev/input/eventX` nodes.
 
 ---
 
-## Implementation Priority and Timeline
+## Historical Implementation Priority and Timeline
 
 | Phase | Component | Effort | Delivers |
 |-------|-----------|--------|----------|