RedBear-OS/README.md

<p align="center">
  <img alt="Red Bear OS" width="200" src="assets/redbear-icon.png">
</p>

<h1 align="center">Red Bear OS</h1>

<p align="center">
  <strong>A microkernel operating system written in Rust — derived from <a href="https://www.redox-os.org">Redox OS</a>, built for bare metal.</strong>
</p>

<p align="center">
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
  <img src="https://img.shields.io/badge/arch-x86__64-red" alt="x86_64">
  <img src="https://img.shields.io/badge/status-active%20development-orange" alt="Status">
</p>

---

## What is Red Bear OS?

Red Bear OS is a general-purpose, Unix-like operating system with a **microkernel architecture**,
written entirely in **Rust**. It is a full fork of Redox OS (baseline 0.3.1), actively developed
on branch `0.3.1` with hardware enablement, multiple filesystems, a native greeter and login
system, and a KDE Plasma desktop path.

We aim to stay close to upstream Redox — diverging only where necessary to add missing
functionality, fix bugs, or support new hardware. The build system itself is under constant
active development alongside the OS.

It ships with several **first-in-class Rust-native tools** found nowhere else in the OS world:

- **cub** — an AUR-inspired package manager with pacman-style CLI (`-S`/`-Q`/`-R`) and a ratatui
  TUI that converts Arch Linux PKGBUILDs into Red Bear recipes on the fly
- **tlc** (Twilight Commander) — a pure-Rust reimplementation of Midnight Commander; dual-panel
  file manager, built-in editor and viewer, 8 color themes, 1204 unit tests, zero unsafe code
- **redbear-power** — interactive ratatui TUI for live CPU frequency, governor, and thermal
  monitoring with on-the-fly P-state control

These are joined by dozens of `redbear-*` system utilities — `redbear-netctl` (network control),
`redbear-info` (hardware diagnostics), `redbear-acmd` (admin CLI), `redbear-mtr`,
`redbear-nmap`, `redbear-btctl`, and many more — all written in Rust, all built from source
alongside the OS.

**Goals**:
- **AMD & Intel parity** — equal-priority bare-metal support for both platforms
- **KDE Plasma desktop** — Wayland-based desktop environment via the KWin compositor
- **Hardware GPU acceleration** — AMD (amdgpu) and Intel GPU drivers via `redox-drm`
- **cub package ecosystem** — AUR → recipe.toml pipeline giving access to thousands of packages
- **First-class subsystems** — USB, Wi‑Fi, Bluetooth, ext4, FAT, GRUB, D-Bus (none optional)
- **Power management** — CPU frequency scaling, thermal monitoring, RAPL, sleep states
- **Offline-first, reproducible builds** — BLAKE3-verified source archives with content-hash caching

---

## Our Git Server

Red Bear OS lives on a self-hosted Gitea instance at **https://gitea.redbearos.org**.
This is the canonical home — no GitHub, GitLab, or Codeberg mirror is authoritative.
There is exactly **one repository**: all component sources (kernel, relibc, drivers,
system utilities) live here as submodule branches or tracked trees in `local/sources/`.

| Field    | Value                                                |
|----------|------------------------------------------------------|
| Host     | `https://gitea.redbearos.org`                        |
| User     | `vasilito`                                           |
| Web UI   | `https://gitea.redbearos.org/vasilito`               |
| Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS`    |

> Authentication tokens are per-session credentials — never stored in the repo.
> See [`local/AGENTS.md` § Our Git Server](./local/AGENTS.md) for the full operator runbook.

---

## Quick Start

### Prerequisites

Linux x86_64 host with Rust nightly, QEMU, nasm, and standard build tools.
See the [Redox Build Guide](https://doc.redox-os.org/book/podman-build.html) for full setup.

### Build & Run

```bash
# Clone (read-only)
git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git
cd RedBear-OS

# Authenticated clone — supply token via env var
git clone https://vasilito:${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git

# Canonical build entry point
./local/scripts/build-redbear.sh redbear-mini     # Text-only target
./local/scripts/build-redbear.sh redbear-full     # Desktop-capable target

# Boot in QEMU
make qemu
```

> `local/scripts/build-redbear.sh` is the **only supported build entry point**. It handles
> `.config` parsing, prefix staleness detection, protected-recipe authorization, pre-cooking
> critical packages, and source fingerprint tracking. Direct `make` invocations bypass these
> gates. See [`AGENTS.md` § Build Commands](./AGENTS.md) for details.

### Config Targets

| Target | Type | Description |
|--------|------|-------------|
| `redbear-full` | Desktop-capable | GPU drivers + Wayland compositor + Qt 6.11.1 + KF6 6.27.0 + KWin + SDDM + greeter + D-Bus |
| `redbear-mini` | Console | Text-only recovery / install target with tlc, cub, and redbear-* utilities |
| `redbear-grub` | Console | Text-only with GRUB boot manager |

---

## Current Status

Red Bear OS **boots to a login prompt** in QEMU with working wired networking, D-Bus system bus,
hardware detection daemons, and three filesystem backends (RedoxFS, ext4, FAT). The ISO builds
successfully on branch `0.3.1`. Graphics packages are frozen at latest upstream stable
(Qt 6.11.1, KF6 6.27.0, Plasma 6.7.2, SDDM 0.21.0, Mesa 24.0.8).

| Area | Status |
|------|--------|
| Boot (ACPI, x2APIC, SMP) | ✅ Bare-metal proven — Ryzen Threadripper 128-thread verified |
| Userspace drivers (PCI, storage, net) | ✅ Working in QEMU |
| Filesystems — RedoxFS, ext4, FAT | ✅ Scheme daemons + mkfs/fsck tools |
| D-Bus system bus + services | ✅ Working — login1, PolicyKit, UDisks, UPower |
| **cub** package manager | 🟡 17-module Rust workspace; AUR → recipe pipeline; 70+ tests |
| **tlc** file manager | 🟡 113 .rs files, 46k+ lines; 986 tests; 8 skins; VFS archives |
| IRQ / PCI / MSI-X / IOMMU | 🟡 QEMU-proven; hardware validation open |
| POSIX gaps (relibc) | 🟡 ~85% coverage; ~38 active patches |
| DRM/KMS display drivers | 🟡 AMD + Intel + virtio-gpu compile; HW validation open |
| Mesa — llvmpipe + virgl | 🟡 Builds (`virtio_gpu_dri.so`, 17.4 MB); virgl EGL runtime probe open |
| SDDM display manager + Greeter/Login | 🟡 Wired in `redbear-full`; graphical login blocked by Qt6 Wayland crash |
| Qt 6.11.1 (Core, Gui, DBus, Wayland) | 🟡 Builds successfully; Wayland `null+8` crash blocks runtime |
| KF6 Frameworks — 40/40 | 🟡 All frameworks build; KWin cooks successfully |
| Wayland compositor | 🟡 Bounded proof; blocked by Qt6 Wayland protocol crash |
| KDE Plasma / KWin | 🔴 Blocked by Qt6 Wayland crash in `wl_proxy_add_listener` |
| Wi‑Fi (Intel iwlwifi) | 🟡 VFIO/passthrough bounded runtime validation framework exists |
| USB / Bluetooth | 🔴 USB maturity work in progress; Bluetooth controller path planned |

**Where help is most wanted:**
Qt6 Wayland protocol crash — the #1 blocker for graphical desktop · AMD/Intel GPU hardware validation on bare metal · USB controller maturity · Wi‑Fi native control plane · cub AUR pipeline hardening · package maintainers for the growing recipe catalog · tlc VFS remote backends and archive support

---

## How It Works

Red Bear OS uses a **userspace driver model** — all drivers run as unprivileged daemons
communicating through the kernel's scheme-based IPC.

```
┌─────────────────────────────────────────────────────────────────┐
│                         KERNEL (microkernel)                     │
│          schemes: memory  ·  irq  ·  event  ·  pipe  ·  debug   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
     ┌─────────────────────┼─────────────────────────┐
     ▼                     ▼                         ▼
┌──────────┐   ┌──────────────────┐   ┌──────────────────────┐
│  pcid    │   │  e1000d  xhcid   │   │  vesad  redox-drm    │
│ PCI enum │   │  Intel   USB 3.0 │   │  fbdev  GPU manager  │
└──────────┘   └──────────────────┘   └──────────────────────┘
┌──────────┐   ┌──────────────────┐   ┌──────────────────────┐
│  ext4d   │   │  ps2d   evdevd   │   │  thermald  cpufreqd  │
│  fatd    │   │  KB+mouse input  │   │  thermal   CPU freq  │
└──────────┘   └──────────────────┘   └──────────────────────┘
┌──────────┐   ┌──────────────────┐   ┌──────────────────────┐
│  iommu   │   │  acpid           │   │  dbus-daemon         │
│  DMA map │   │  power mgmt      │   │  system + session    │
└──────────┘   └──────────────────┘   └──────────────────────┘
```

The kernel provides minimal services: memory, interrupts, and IPC. Everything else —
filesystems, networking, graphics, input, power management, D-Bus — runs in userspace.
Hardware quirks are handled by a data-driven system in `redox-driver-sys` with compiled-in
tables, TOML runtime configuration, and DMI matching.

---

## Engineering Standards

Red Bear OS operates under strict discipline. Full policies: [`local/AGENTS.md`](./local/AGENTS.md).

| Rule | |
|------|---|
| **Never delete to "fix" a build** | If a package breaks, fix the root cause. Never remove, ignore, or comment out a package, service, or config to make a build pass. |
| **Zero stubs** | No fake headers, `#ifdef` no-ops, or "make it compile" shortcuts. Missing functionality must be implemented properly in the right component. |
| **Single repository** | All component sources live here — no per-component repos. 9 `submodule/<component>` branches. |
| **Local fork model** | Core components (kernel, relibc, base, etc.) maintained as local forks in `local/sources/` with immutability guarantees. |
| **Adapt to upstream** | Red Bear adapts to upstream API/ABI changes — never pins, downgrades, or holds back a dependency. |
| **Free/libre only** | No proprietary, source-unavailable, or redistributability-restricted dependencies. MIT licensed. |

---

## Documentation

- [Desktop Path Plan](local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — Canonical plan v6.0: kernel → DRM → Mesa → Wayland → KDE
- [Implementation Plan](docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) — Roadmap and execution model
- [cub Package Manager](local/docs/CUB-PACKAGE-MANAGER.md) — AUR → recipe pipeline, CLI reference, architecture
- [tlc File Manager](local/recipes/tui/tlc/README.md) — Pure-Rust Midnight Commander replacement
- [D-Bus Integration](local/docs/DBUS-INTEGRATION-PLAN.md) — Session bus architecture
- [IRQ & Low-Level Controllers](local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md) — IRQ delivery, MSI/MSI-X, IOMMU
- [Greeter & Login](local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md) — Native greeter, auth daemon, session launch
- [DRM Modernization](local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md) — DRM/KMS display and render maturity
- [USB Plan](local/docs/USB-IMPLEMENTATION-PLAN.md) — USB stack design and implementation
- [Wi‑Fi Plan](local/docs/WIFI-IMPLEMENTATION-PLAN.md) — Wireless architecture and driver plan
- [Bluetooth Plan](local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md) — Bluetooth stack design
- [Build Cache](local/docs/BUILD-CACHE-PLAN.md) — Content-hash (BLAKE3) build cache system
- [Build System Hardening](local/docs/BUILD-SYSTEM-HARDENING-PLAN.md) — Collision detection, init service validation
- [Quirks System](local/docs/QUIRKS-SYSTEM.md) — Hardware quirks infrastructure
- [Documentation Index](docs/README.md) — Full doc map

---

## Contributing

Red Bear OS is a **full fork** of Redox OS. Upstream sources are frozen and archived; all
custom work lives in `local/` and survives every build operation.

```
local/
├── sources/    # Local forks of core components (kernel, relibc, base, bootloader, …)
├── recipes/    # Custom packages — drivers, GPU stack, system daemons, branding
├── patches/    # Durable changes to upstream source trees
├── docs/       # Integration and planning documentation
└── scripts/    # Build, test, validation, and release tooling
```

### We're Looking For

| Role | What you'd work on |
|------|--------------------|
| **Package maintainers** | Port and maintain AUR packages through cub's pipeline; write and test recipe.toml files for Red Bear OS; improve the PKGBUILD → recipe conversion |
| **Driver developers** | AMD/Intel GPU drivers, USB controller maturity, Wi‑Fi native control plane, Bluetooth |
| **Graphics stack engineers** | Qt6 Wayland crash fix (the #1 desktop blocker), Mesa virgl runtime, KWin Wayland compositor |
| **Systems/Rust engineers** | Kernel syscalls, relibc POSIX gaps, filesystem daemons, D-Bus services, hardware quirks |
| **TUI/app developers** | tlc feature completion, cub TUI polish, redbear-power enhancements, new redbear-* utilities |

Contributions are welcome with or without AI assistance — we care about **quality**, not how
the code was produced. Pick an area from the status table above, check the relevant plan doc,
and dive in.

---

## License

[MIT](./LICENSE) — same as upstream Redox OS.