# DOCS — ARCHITECTURE & INTEGRATION DOCUMENTATION

Public `docs/` files now mix three roles:

- canonical repository-level policy/current-state docs,
- architecture/reference docs,
- and older roadmap/design docs that are still useful but partly historical.

Do not assume everything under `docs/` is equally current.

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/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — **canonical comprehensive implementation plan** — all current state
- `local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md` — canonical 3D-desktop plan (consolidates the former DRM-modernization, Wayland, 3D-driver, and SDDM-bringup docs, all deleted 2026-07-27)
- `local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — current script guarantees and non-guarantees

## STRUCTURE

```
docs/
├── 01-REDOX-ARCHITECTURE.md   # Architecture reference: microkernel, scheme system, driver model, display architecture
├── 04-LINUX-DRIVER-COMPAT.md  # Driver-compat architecture reference + historical porting path
├── 06-BUILD-SYSTEM-SETUP.md   # Build/setup mechanics guide (not canonical policy)
├── 07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md # Canonical public implementation plan
└── README.md                  # Canonical docs index + status matrix

Note: 05-KDE-PLASMA-ON-REDOX.md was deleted on 2026-07-27 during the doc
consolidation (see `local/docs/SUPERSEDED-DOC-LOG.md`). Its content was
superseded by `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` and
`local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md`.
```

## WHERE TO LOOK

| Question | Document | Key Section |
|----------|----------|-------------|
| How does the kernel work? | 01 | §1 Microkernel, §2 Scheme System |
| How do drivers access hardware? | 01 | §3 Driver Model, §6 Build System |
| What is the canonical current implementation plan? | 07 | Entire document |
| Which docs are current vs historical? | README | Document Status Matrix |
| What is the current WIP ownership policy? | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Current state and blocker map |
| What do the main sync/fetch/apply/build scripts actually guarantee? | local/docs/SCRIPT-BEHAVIOR-MATRIX.md | Entire document |
| What is the current desktop-stack truth? | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Entire document |
| What is the current Wi-Fi architecture and validation path? | local/docs/WIFI-IMPLEMENTATION-PLAN.md | Entire document |
| What's missing for Wayland? | `local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md` | Wayland compositor section (formerly `WAYLAND-IMPLEMENTATION-PLAN.md`, deleted 2026-07-27) |
| What is the current Wayland plan? | `local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md` | Wayland compositor section (formerly `WAYLAND-IMPLEMENTATION-PLAN.md`, deleted 2026-07-27) |
| How to run Linux GPU drivers? | 04 | Architecture diagram, i915 porting example |
| What is redox-driver-sys? | 04 | Crate 1: memory, IRQ, PCI, DMA wrappers |
| What is linux-kpi? | 04 | Crate 2: C headers translating Linux→Redox APIs |
| How to port Qt? | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` + `local/docs/3D-DESKTOP-COMPREHENSIVE-PLAN.md` | Canonical plans (historical `05-KDE-PLASMA-ON-REDOX.md` was deleted 2026-07-27) |
| How to port KDE Frameworks? | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Canonical desktop path plan (historical `05-KDE-PLASMA-ON-REDOX.md` was deleted 2026-07-27) |
| How to port KDE Plasma? | `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Canonical desktop path plan (historical `05-KDE-PLASMA-ON-REDOX.md` was deleted 2026-07-27) |
| How to set up the build? | 06 | Prerequisites per distro, build commands |
| What is the current work ordering? | 07 | Workstream Order + Blocker chain |
| How to fix POSIX gaps in relibc? | `local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md` | Implemented credential syscalls |

## READING RULE

When a current-state local document conflicts with an older public roadmap/design file, prefer the
current local subsystem plan or the canonical public implementation plan.