RedBear-OS/docs/README.md

# Red Bear OS Documentation Index

Technical documentation for Red Bear OS as an overlay distribution on top of Redox OS.

This index is the entry point for the documentation set. Its main job is to make the
current/canonical versus historical/reference split obvious.

> **Status note (2026-04-16):** The canonical desktop path document is now
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v2.0, three-track Phase 1–5 model). It consolidates
> the Wayland, KDE, and GPU roadmap into one honest implementation plan with testable exit criteria.
> The historical docs below (01–05) remain useful for architecture reference and implementation
> rationale, but they should be read together with the new plan and the current local subsystem docs.

> **Status note (2026-04-14):** several documents below are historical implementation plans whose
> original "missing / not started" language is now stale. The repo already contains substantial
> Red Bear OS work under `local/`; use each document's top-level status notes together with
> `local/docs/AMD-FIRST-INTEGRATION.md` and `local/docs/QT6-PORT-STATUS.md` for current state.

> **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/AMD-FIRST-INTEGRATION.md` for the AMD-focused hardware roadmap.

> **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
> subsystem overlays on top. For long-term stability, upstream-owned source trees should be treated
> as refreshable working copies, while durable Red Bear state belongs in `local/patches/`,
> `local/recipes/`, `local/docs/`, and tracked Red Bear configs.
>
> **WIP policy:** if an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a
> local project until upstream promotes it to first-class status. We may refresh from upstream WIP,
> but we should fix and ship from the Red Bear overlay until upstream support is real enough to
> replace the local copy.

## Document Status Matrix

| 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 |
| `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 |

When a current-state local document conflicts with an older historical public roadmap, prefer the
current local subsystem plan.

## Documents

| # | Document | Description |
|---|----------|-------------|
| 01 | [Architecture Overview](01-REDOX-ARCHITECTURE.md) | Architecture reference for Redox internals: microkernel, scheme system, driver model, display stack |
| 02 | [Gap Analysis & Roadmap](02-GAP-ANALYSIS.md) | Historical gap matrix plus corrected current phase summary |
| 03 | [Wayland on Redox](03-WAYLAND-ON-REDOX.md) | Historical Wayland implementation path plus deeper Wayland-specific rationale |
| 04 | [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md) | Historical/current hybrid design reference for the LinuxKPI-style driver compatibility model |
| 05 | [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) | Historical KDE implementation path plus deeper KDE-specific rationale |
| 06 | [Build System Setup](06-BUILD-SYSTEM-SETUP.md) | How to build Redox from this repository |
| 07 | [Red Bear OS Implementation Plan](07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) | Canonical public implementation plan focused on profiles, packaging, validation, and staged hardware enablement |
| 08 | [Firmware in Red Bear OS](firmware.md) | Canonical firmware packaging, licensing, and runtime-loading policy |

## Related Red Bear-local current-state plans

- `../local/docs/USB-IMPLEMENTATION-PLAN.md` — current USB completeness and rollout plan
- `../local/docs/WIFI-IMPLEMENTATION-PLAN.md` — current Wi-Fi architecture and rollout plan
- `../local/docs/WIFI-VALIDATION-RUNBOOK.md` — canonical operator path for bare-metal/VFIO Wi-Fi validation and evidence capture
- `../local/docs/WIFICTL-SCHEME-REFERENCE.md` — bounded `/scheme/wifictl` interface reference for the current Wi-Fi control surface
- `../local/recipes/system/redbear-netctl-console/source/` — Redox-native ncurses terminal client for the bounded Wi-Fi profile flow
- `../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/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/PROJECT-DOCUMENTATION-ASSESSMENT.md` — current assessment of documentation quality, canon, and remaining cleanup priorities
- `../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,
Bluetooth, and low-level controller work. They carry blocker detail that the public docs summarize
at a higher level.

## Related Red Bear-local governance docs

- `../local/docs/WIP-MIGRATION-LEDGER.md` — current WIP ownership and upstream-vs-local migration ledger
- `../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)

This summary is only a quick orientation layer. For canonical current-state detail, prefer:

- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` for repository-wide execution order,
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path from console to KDE Plasma on Wayland,
- `local/docs/DESKTOP-STACK-CURRENT-STATUS.md` for desktop build/runtime truth,
- `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
- **Wayland**: libwayland + wayland-protocols built. Smallvil/cosmic-comp remain partial runtime experiments.
- **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).
- **Mesa**: software-rendered path is present; full GBM / hardware-validated Wayland path is still incomplete.
- **GPU drivers**: redox-drm scheme daemon and AMD+Intel compile-oriented paths exist; hardware validation is still pending.
- **Input**: evdevd compiled, libevdev built, libinput 1.30.2 built
- **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 is now QEMU-validated through a packaged in-guest checker plus a host harness; 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.
- **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.

## Quick Start

```bash
# 1. Install dependencies (Arch/Manjaro)
sudo pacman -S --needed --noconfirm gdb meson nasm patchelf python-mako \
  doxygen expat file fuse3 gmp libjpeg-turbo libpng po4a scons \
  sdl12-compat syslinux texinfo xdg-utils zstd

# 2. Install Rust + tools
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
cargo install just cbindgen

# 3. Configure for native build (no Podman)
echo 'PODMAN_BUILD?=0' > .config

# 4. Build (downloads cross-toolchain, then compiles)
make all

# 5. Run in QEMU
make qemu
```

## Key Repositories

| Repo | Purpose | URL |
|------|---------|-----|
| 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 |