vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refresh public docs navigation

Browse Source 
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
Vasilito
2026-04-15 12:57:07 +01:00
parent 620a98aa9b
commit 5cd9442a7c
2 changed files with 99 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS.md
+37 -19
View File
@@ -1,20 +1,36 @@
# DOCS — ARCHITECTURE & INTEGRATION DOCUMENTATION # DOCS — ARCHITECTURE & INTEGRATION DOCUMENTATION
7 technical documents covering Redox architecture, gap analysis, and integration paths. Public `docs/` files now mix three roles:
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`. - 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 ## STRUCTURE
``` ```
docs/ docs/
├── 01-REDOX-ARCHITECTURE.md # Microkernel design, scheme system, driver model, Orbital ├── 01-REDOX-ARCHITECTURE.md # Architecture reference: microkernel, scheme system, driver model, Orbital
├── 02-GAP-ANALYSIS.md # Dependency chain, gap matrix, milestone roadmap ├── 02-GAP-ANALYSIS.md # Historical gap matrix with corrected current-state notes
├── 03-WAYLAND-ON-REDOX.md # Wayland implementation path (5 steps, ~26 weeks) ├── 03-WAYLAND-ON-REDOX.md # Historical Wayland implementation path + deeper rationale
├── 04-LINUX-DRIVER-COMPAT.md # LinuxKPI-style driver compat layer (3 crates) ├── 04-LINUX-DRIVER-COMPAT.md # Driver-compat architecture reference + historical porting path
├── 05-KDE-PLASMA-ON-REDOX.md # KDE Plasma port (3 phases, ~38 weeks) ├── 05-KDE-PLASMA-ON-REDOX.md # Historical KDE implementation path + deeper rationale
├── 06-BUILD-SYSTEM-SETUP.md # Build prerequisites, config, commands, troubleshooting ├── 06-BUILD-SYSTEM-SETUP.md # Build/setup mechanics guide (not canonical policy)
└── README.md # Index of all docs ├── 07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md # Canonical public implementation plan
└── README.md # Canonical docs index + status matrix
``` ```
## WHERE TO LOOK ## WHERE TO LOOK
@@ -23,8 +39,14 @@ docs/
|----------|----------|-------------| |----------|----------|-------------|
| How does the kernel work? | 01 | §1 Microkernel, §2 Scheme System | | How does the kernel work? | 01 | §1 Microkernel, §2 Scheme System |
| How do drivers access hardware? | 01 | §3 Driver Model, §6 Build 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 | | 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 evdevd? | 03 | §2 (evdev input daemon architecture) |
| How to build DRM/KMS? | 03 | §3 (drmd daemon, Intel driver) | | How to build DRM/KMS? | 03 | §3 (drmd daemon, Intel driver) |
| How to port a Wayland compositor? | 03 | §4 (Smithay Redox backends) | | 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 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 port KDE Plasma? | 05 | Phase KDE-C (KWin, Plasma Shell, session config) |
| How to set up the build? | 06 | Prerequisites per distro, build commands | | 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 When a current-state local document conflicts with an older public roadmap/design file, prefer the
- **Wayland recipes**: 21 in `recipes/wip/wayland/` current local subsystem plan or the canonical public implementation plan.
- **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)
docs/README.md
+62 -9
View File
@@ -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, Technical documentation for Red Bear OS as an overlay distribution on top of Redox OS.
KDE Plasma desktop environment, and a Linux driver compatibility layer.
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 > **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 > 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 > 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. > `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 ## Documents
| # | Document | Description | | # | Document | Description |
|---|----------|-------------| |---|----------|-------------|
| 01 | [Architecture Overview](01-REDOX-ARCHITECTURE.md) | Redox OS internals: microkernel, scheme system, driver model, display stack | | 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) | What's missing between current Redox and our Wayland/KDE/driver-compat goals | | 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) | Deep-dive into Wayland protocol requirements and current porting status | | 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) | Design for a FreeBSD LinuxKPI-style driver compatibility shim | | 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) | Feasibility study and implementation plan for KDE Plasma | | 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 | | 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 | | 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 - **Display server**: Orbital (custom, scheme-based) — works
- **Wayland**: libwayland + wayland-protocols built. Smallvil/cosmic-comp remain partial runtime experiments. - **Wayland**: libwayland + wayland-protocols built. Smallvil/cosmic-comp remain partial runtime experiments.