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
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.
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,
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.