diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 612fba2c..645f740a 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,20 +1,36 @@ # DOCS — ARCHITECTURE & INTEGRATION DOCUMENTATION -7 technical documents covering Redox architecture, gap analysis, and integration paths. -Some are now historical roadmap documents; check each file's top-level status note before treating it as current state. -For current Red Bear OS status, also read `local/docs/AMD-FIRST-INTEGRATION.md` and `local/docs/QT6-PORT-STATUS.md`. +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/DESKTOP-STACK-CURRENT-STATUS.md` — current desktop stack build/runtime truth +- `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/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 # Microkernel design, scheme system, driver model, Orbital -├── 02-GAP-ANALYSIS.md # Dependency chain, gap matrix, milestone roadmap -├── 03-WAYLAND-ON-REDOX.md # Wayland implementation path (5 steps, ~26 weeks) -├── 04-LINUX-DRIVER-COMPAT.md # LinuxKPI-style driver compat layer (3 crates) -├── 05-KDE-PLASMA-ON-REDOX.md # KDE Plasma port (3 phases, ~38 weeks) -├── 06-BUILD-SYSTEM-SETUP.md # Build prerequisites, config, commands, troubleshooting -└── README.md # Index of all docs +├── 01-REDOX-ARCHITECTURE.md # Architecture reference: microkernel, scheme system, driver model, Orbital +├── 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 +├── 05-KDE-PLASMA-ON-REDOX.md # Historical KDE implementation path + deeper rationale +├── 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 ``` ## WHERE TO LOOK @@ -23,8 +39,14 @@ docs/ |----------|----------|-------------| | 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/WIP-MIGRATION-LEDGER.md | Entire document | +| 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/DESKTOP-STACK-CURRENT-STATUS.md | Entire document | +| What is the current Qt/KF6 status? | local/docs/QT6-PORT-STATUS.md | Entire document | | What's missing for Wayland? | 02 | Status correction + ordered remaining gaps | -| How to fix POSIX gaps? | 03 | Status correction + historical §1 notes | +| How to fix POSIX gaps? | local/docs/RELIBC-COMPLETENESS-AND-ENHANCEMENT-PLAN.md | Current relibc completeness work | | How to build evdevd? | 03 | §2 (evdev input daemon architecture) | | How to build DRM/KMS? | 03 | §3 (drmd daemon, Intel driver) | | How to port a Wayland compositor? | 03 | §4 (Smithay Redox backends) | @@ -35,13 +57,9 @@ docs/ | How to port KDE Frameworks? | 05 | Phase KDE-B (25 frameworks, tiered approach) | | How to port KDE Plasma? | 05 | Phase KDE-C (KWin, Plasma Shell, session config) | | How to set up the build? | 06 | Prerequisites per distro, build commands | -| What's the milestone timeline? | 02 | M1-M8 roadmap, parallel execution plan | +| What is the current work ordering? | 07 | Workstream Order + Blocker chain | -## KEY NUMBERS +## READING RULE -- **POSIX gap story**: APIs now largely exist in-tree, but downstream Wayland consumers still carry compatibility patches -- **Wayland recipes**: 21 in `recipes/wip/wayland/` -- **KDE apps**: 9 WIP recipes in `recipes/wip/kde/` -- **To Wayland compositor**: ~26 weeks (2 developers) -- **To KDE Plasma**: ~38 weeks (2 developers) -- **To Linux driver compat**: ~24 weeks (parallel track) +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. diff --git a/docs/README.md b/docs/README.md index 920675b3..ccb99ea8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,26 +1,79 @@ -# Redox OS Fork — Wayland, KDE & Linux Driver Compatibility +# Red Bear OS Documentation Index -Technical documentation for forking Redox OS to include Wayland protocol support, -KDE Plasma desktop environment, and a Linux driver compatibility layer. +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-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` | 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) | Redox OS internals: microkernel, scheme system, driver model, display stack | -| 02 | [Gap Analysis & Roadmap](02-GAP-ANALYSIS.md) | What's missing between current Redox and our Wayland/KDE/driver-compat goals | -| 03 | [Wayland on Redox](03-WAYLAND-ON-REDOX.md) | Deep-dive into Wayland protocol requirements and current porting status | -| 04 | [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md) | Design for a FreeBSD LinuxKPI-style driver compatibility shim | -| 05 | [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) | Feasibility study and implementation plan for KDE Plasma | +| 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 | -## Current State Summary (as of 2026-04-14) +## Related Red Bear-local 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/BLUETOOTH-IMPLEMENTATION-PLAN.md` — current Bluetooth architecture and rollout plan +- `../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/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/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. + +## 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/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.