# Red Bear OS Documentation Index

**Last updated:** 2026-06-10 · **Red Bear OS version:** 0.2.3 (branch `0.2.3`)

This index is the entry point for the Red Bear OS documentation set. Red Bear OS is a **full fork
of Redox OS**: the build system, source archive layout, recipe/source ownership, and patch model
are all in-tree in this repository. Upstream Redox is a reference, not a live dependency — sources
are never auto-pulled.

For the canonical current-state implementation plan, see
[`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`](local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md). It
supersedes every other plan in the tree for execution order, claim language, and current state.

## Top-level policy and current state

| File | Role |
|---|---|
| `README.md` | Project introduction, build commands, status matrix |
| `AGENTS.md` | Repository-level agent knowledge base (rules, structure, conventions) |
| `local/AGENTS.md` | Red Bear OS local-area agent knowledge base (in-tree vs upstream ownership, Rule 1/2 model, build durability) |
| `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` | Canonical public implementation plan (repository-level execution order) |
| `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Canonical comprehensive implementation plan (all current state, supersedes individual subsystem docs) |
| `docs/README.md` (this file) | Documentation index |

## Canonical subsystem plans (`local/docs/`)

Each plan covers a single subsystem. The desktop path plan is the single authority for
desktop/session execution order; subsystem plans are deep-dive references for their area.

| Plan | Subsystem |
|---|---|
| `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | **Canonical comprehensive plan** — kernel → DRM → Mesa → Wayland → KDE |
| `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` | DRM/AMD + Intel execution (subsystem detail) |
| `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` | Wayland compositor (subsystem detail) |
| `local/docs/ACPI-IMPROVEMENT-PLAN.md` | ACPI ownership, robustness, validation |
| `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` | PCI/IRQ quality, MSI/MSI-X, IOMMU |
| `local/docs/USB-IMPLEMENTATION-PLAN.md` | USB controller, hub, storage, HID |
| `local/docs/WIFI-IMPLEMENTATION-PLAN.md` | Wi-Fi native control plane + driver family |
| `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` | Bluetooth host/controller path |
| `local/docs/QUIRKS-SYSTEM.md` | Hardware quirks infrastructure (compiled-in + TOML + DMI) |
| `local/docs/DBUS-INTEGRATION-PLAN.md` | D-Bus architecture for KDE Plasma 6 |
| `local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md` | Red Bear-native greeter/login design |
| `local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md` | Kernel credential syscalls + IPC (implemented) |
| `local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` | relibc IPC surface |
| `local/docs/GRUB-INTEGRATION-PLAN.md` | GRUB boot manager integration |
| `local/docs/BUILD-SYSTEM-HARDENING-PLAN.md` | Build system hardening (collision detection, validation) |
| `local/docs/BUILD-SYSTEM-INVARIANTS.md` | Build system invariants I1–I3 |
| `local/docs/SCRIPT-BEHAVIOR-MATRIX.md` | Script guarantees and non-guarantees |
| `local/docs/STUBS-FIX-PROGRESS.md` | v6.0 stubs → real code rewrite progress (tracking document) |

## Reading rule

When a current-state local document conflicts with an older reference, **prefer the console-to-KDE
plan and the canonical subsystem plan for that area.** Older assessments and roadmap drafts that
refer to historical P0–P6 numbering, "0.1.0" status, or AMD-first platform priority are obsolete;
the project is now on `0.2.3` with AMD and Intel as equal-priority targets.

## Build commands

```bash
# Build the desktop target (full)
./local/scripts/build-redbear.sh redbear-full

# Build the text-only recovery target
./local/scripts/build-redbear.sh redbear-mini

# Build the text-only target with GRUB
./local/scripts/build-redbear.sh redbear-grub

# Run a single package through the build system
./target/release/repo cook <recipe-path>

# Cascade rebuild after a low-level change
./local/scripts/rebuild-cascade.sh relibc
```

## Repository hosting

The canonical Red Bear OS Git server is **Gitea** at
`https://gitea.redbearos.org/vasilito/RedBear-OS.git`. Do not use GitHub for Red Bear OS pushes,
issues, releases, or project coordination. Historical/upstream references may still point to their
original hosts when documenting third-party projects.