diff --git a/local/docs/CUB-PACKAGE-MANAGER.md b/local/docs/CUB-PACKAGE-MANAGER.md
new file mode 100644
index 000000000..4887622d9
--- /dev/null
+++ b/local/docs/CUB-PACKAGE-MANAGER.md
@@ -0,0 +1,366 @@
+# Cub — Red Bear OS Package Manager
+
+**Status:** Active (redesign complete 2026-05)
+**Location:** `local/recipes/system/cub/`
+**Type:** Runtime package manager (runs inside Red Bear OS)
+**Dependencies:** `pkgutils` (redox-pkg), `pkgar`
+
+## Overview
+
+Cub is the Red Bear OS package manager — an AUR-inspired tool for searching, fetching,
+building, installing, and managing packages. It serves as the bridge between Red Bear OS
+and the Arch Linux AUR ecosystem, converting PKGBUILD recipes into Red Bear OS recipe.toml
+files and producing pkgar packages.
+
+Cub runs as a regular user inside Red Bear OS, managing packages in `~/.cub/` and
+installing them via the `pkgar` system.
+
+## Architecture
+
+```
+cub (workspace)
+├── cub-lib/          ← Core library (13 modules)
+│   ├── aur.rs        ← AUR RPC v5 client (search, info)
+│   ├── storage.rs    ← ~/.cub/ user-local storage manager
+│   ├── cook.rs       ← recipe cooking (shells out to repo cook)
+│   ├── pkgbuild.rs   ← Enhanced AUR PKGBUILD parser
+│   ├── recipe.rs     ← Unified recipe.toml generation
+│   ├── converter.rs  ← Legacy PKGBUILD converter (preserved)
+│   ├── cookbook.rs   ← recipe.toml generation from RBPKGBUILD
+│   ├── rbpkgbuild.rs ← RBPKGBUILD TOML type definitions
+│   ├── package.rs    ← pkgar archive creation
+│   ├── sandbox.rs    ← Build sandbox environment
+│   ├── deps.rs       ← Arch Linux → Redox dependency name mapping
+│   ├── rbsrcinfo.rs  ← .RBSRCINFO metadata format
+│   └── error.rs      ← CubError enum (11 variants)
+├── cub-tui/          ← Terminal UI (ratatui 0.30 + termion)
+│   ├── app.rs        ← TUI app struct and event loop
+│   ├── theme.rs      ← Red Bear color theme
+│   ├── views/        ← search, info, install, build, query
+│   └── widgets/      ← Reusable TUI components
+└── cub-cli/          ← CLI binary entry point
+    └── main.rs       ← 14 Arch-style switches + TUI launcher
+```
+
+## CLI Reference
+
+### Operation Modes
+
+Cub supports three operation modes mirroring pacman:
+
+| Mode | Flag | Description |
+|------|------|-------------|
+| Sync | `-S` | Install, search, refresh, upgrade packages |
+| Query | `-Q` | Manage locally installed packages |
+| Remove | `-R` | Uninstall packages |
+
+### Sync Operations (`-S`)
+
+```bash
+cub -S <pkg>         # Install from official repo or BUR/AUR
+cub -Ss <query>      # Search official repo + cached BUR + AUR
+cub -Si <pkg>        # Show AUR package info (description, deps, votes)
+cub -Sy              # Refresh BUR cache + verify AUR connectivity
+cub -Syu             # Full system upgrade (sync + update all)
+cub -Sua             # Update AUR packages only
+cub -Sc              # Clean package caches
+```
+
+### Build Operations (`-B`, `-G`)
+
+```bash
+cub -B <dir>         # Build local RBPKGBUILD directory → pkgar + install
+cub -G <pkg>         # Fetch AUR PKGBUILD, convert to recipe, save to ~/.cub/
+```
+
+### Query Operations (`-Q`)
+
+```bash
+cub -Q               # List all installed packages
+cub -Qi <pkg>        # Show installed package details (version, deps, size)
+cub -Ql <pkg>        # List files installed by a package
+```
+
+### Remove Operations (`-R`)
+
+```bash
+cub -R <pkg>         # Uninstall a package
+```
+
+### Other Commands
+
+```bash
+cub -Pi <target>     # Inspect installed package or local RBPKGBUILD
+cub --import-aur <target>  # Import AUR package (clone + convert PKGBUILD)
+cub -T, --no-tui     # Disable TUI mode (use CLI directly)
+cub                  # No subcommand: launch TUI
+```
+
+## User Storage (`~/.cub/`)
+
+Cub maintains all user-local data in `~/.cub/` with four subdirectories:
+
+```
+~/.cub/
+├── recipes/          # Converted recipe.toml + RBPKGBUILD + patches
+│   └── <pkgname>/
+│       ├── recipe.toml    ← Generated cookbook recipe
+│       ├── RBPKGBUILD     ← Red Bear PKGBUILD (TOML format)
+│       ├── .RBSRCINFO     ← Metadata for dependency resolution
+│       └── patches/       ← Local patches
+├── sources/          # Cached source tarballs and git clones
+├── repo/             # Built pkgar packages organized by target
+│   └── x86_64-unknown-redox/
+│       ├── <pkg>.pkgar    ← Signed package archive
+│       └── <pkg>.toml     ← Package metadata
+└── config/           # Cub configuration and keyring
+```
+
+## AUR Integration
+
+Cub accesses the Arch User Repository via the AUR RPC v5 API:
+
+| Endpoint | Method | Cub Function |
+|----------|--------|-------------|
+| `/rpc?v=5&type=search&arg=<q>` | GET | `AurClient::search(query)` |
+| `/rpc?v=5&type=info&arg[]=<pkg>` | GET | `AurClient::info(pkgs)` |
+| `https://aur.archlinux.org/<pkg>.git` | git clone | `-G <pkg>` (import) |
+
+### PKGBUILD Conversion
+
+When importing from AUR (`-G` or `--import-aur`):
+
+1. Clone the AUR git repository
+2. Parse `PKGBUILD` bash script — extracts `pkgname`, `pkgver`, `pkgrel`,
+   `depends`, `makedepends`, `source`, `sha256sums`, `optdepends`
+3. Detect build template (cargo, cmake, meson, configure, custom)
+4. Map Arch dependencies to Redox equivalents (glibc→relibc, openssl→openssl3,
+   systemd→removed, etc.)
+5. Generate `RBPKGBUILD` (TOML format) and `.RBSRCINFO`
+6. Generate `recipe.toml` compatible with the Red Bear cookbook
+7. Save all files to `~/.cub/recipes/<pkgname>/`
+
+### Dependency Mapping
+
+Cub maintains a 44-entry mapping table (`deps.rs`) translating Arch Linux
+package names to their Redox/Red Bear equivalents:
+
+| Arch Package | Redox Mapping | Notes |
+|---|---|---|
+| `glibc` | `relibc` | Redox uses relibc instead of glibc |
+| `openssl` | `openssl3` | Version-specific mapping |
+| `gcc`, `make` | `build-base` | Meta-package for build tools |
+| `systemd` | *(removed)* | Unavailable on Redox — warning issued |
+| `libx11`, `libxcb` | *(mapped)* | X11 unavailable — manual port needed |
+| `linux-api-headers` | *(removed)* | Linux-specific — not applicable |
+| `wayland` | `wayland` | Direct 1:1 mapping when available |
+| `qt6-base` | `qtbase` | Qt 6 base libraries |
+| `dbus` | `dbus` | Direct 1:1 mapping |
+
+Unknown dependencies are passed through unchanged with a warning.
+
+## Build Flow
+
+```
+cub -B <dir>                    # Build local RBPKGBUILD
+  │
+  ├─ 1. Parse RBPKGBUILD        ← Validate TOML format
+  ├─ 2. Create sandbox          ← .cub-sandbox/{build,stage,sysroot}
+  ├─ 3. Generate recipe.toml    ← cookbook::generate_recipe()
+  ├─ 4. repo cook <recipe_dir>  ← Shell out to cookbook (cook.rs)
+  ├─ 5. Locate stage directory  ← Find populated stage dir
+  ├─ 6. Create pkgar archive    ← pkgar::create_with_flags()
+  ├─ 7. Generate .toml metadata ← Package name, version, deps
+  └─ 8. Install via pkgutils    ← library.install() + apply()
+```
+
+### Sandbox Environment
+
+The build sandbox sets these environment variables for `repo cook`:
+
+| Variable | Value |
+|----------|-------|
+| `COOKBOOK_SOURCE` | Source directory path |
+| `COOKBOOK_STAGE` | Stage (install) directory |
+| `COOKBOOK_SYSROOT` | Sysroot with built dependencies |
+| `COOKBOOK_TARGET` | `x86_64-unknown-redox` |
+| `COOKBOOK_HOST_TARGET` | `x86_64-unknown-linux-gnu` |
+| `COOKBOOK_MAKE_JOBS` | CPU core count |
+| `DESTDIR` | Alias for COOKBOOK_STAGE |
+| `TARGET` | `x86_64-unknown-redox` |
+| `GNU_TARGET` | `x86_64-redox` |
+
+## TUI (Terminal UI)
+
+Cub launches a ratatui-based TUI by default when run without a subcommand.
+Use `--no-tui` / `-T` for direct CLI operation.
+
+### Views
+
+| View | Description | Key Bindings |
+|------|-------------|-------------|
+| **Search** | Search AUR by name/description | Type query, Enter to search |
+| **Info** | Detailed package view | Shows deps, version, votes, description |
+| **Install** | Install progress with log output | Shows command output in real-time |
+| **Build** | Build progress for local recipes | Shows stage/progress indicators |
+| **Query** | Browse locally installed packages | Arrows to navigate, Enter for details |
+
+### Global Keys
+
+| Key | Action |
+|-----|--------|
+| `q` / `Esc` | Quit TUI |
+| `/` | Focus search bar |
+| `Tab` | Cycle between views |
+| `↑` `↓` | Navigate lists |
+| `Enter` | Select / confirm |
+
+### Theme
+
+Red Bear color theme:
+- Background: dark (terminal default)
+- Accent: red (#CC0000)
+- Text: white
+- Selected: red highlight on white text
+- Borders: gray
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CUB_BUR_REPO_URL` | `https://gitlab.redox-os.org/redox-os/bur.git` | BUR repository URL |
+| `CUB_PKGAR_SECRET_KEY` | *(auto-detected)* | Path to pkgar secret key |
+| `CUB_PKGAR_PUBKEY_DIR` | *(auto-detected)* | Directory containing public key |
+
+### Key Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.pkg/id_ed25519.toml` | Secret key (pkgar signing) |
+| `/etc/pkg/id_ed25519.toml` | System secret key fallback |
+| `/pkg/id_ed25519.toml` | System secret key fallback 2 |
+| `~/.cub/config/` | Cub-specific configuration |
+
+## Recipe Format
+
+Cub generates standard Red Bear OS recipe.toml files compatible with the
+`repo cook` command:
+
+```toml
+[source]
+git = "https://github.com/user/repo.git"
+branch = "main"
+rev = "abc123"
+
+[build]
+template = "cargo"
+dependencies = ["cargo", "pkg-config"]
+
+[package]
+dependencies = ["relibc", "openssl3"]
+version = "1.0.0-1"
+description = "Example package converted from AUR"
+```
+
+### Template Detection
+
+Cub auto-detects the correct build template from PKGBUILD `build()` contents:
+
+| PKGBUILD pattern | recipe.toml template |
+|---|---|
+| `cargo build`, `cargo install` | `cargo` |
+| `cmake` | `cmake` |
+| `meson setup`, ` meson ` | `meson` |
+| `./configure`, ` configure ` | `configure` |
+| Other | `custom` |
+
+## Linuxism Detection
+
+During PKGBUILD conversion, cub detects Linux-specific patterns and issues
+warnings for manual intervention:
+
+| Pattern | Warning |
+|---------|---------|
+| `systemctl` | systemctl not available on Redox |
+| `/usr/lib/systemd` | Linux-specific paths |
+| `systemd` as dependency | Dependency removed (unavailable) |
+| `/proc` references | May require Redox-specific adaptation |
+
+## Build Recipe
+
+Cub is built as a standard Cargo workspace:
+
+```toml
+# local/recipes/system/cub/recipe.toml
+[source]
+path = "source"
+
+[build]
+template = "cargo"
+cargopath = "cub-cli"
+
+[package]
+dependencies = ["pkgutils"]
+```
+
+The recipe builds `cub-cli` which depends on `cub-lib` and optionally `cub-tui`.
+The `default-members` of the workspace is `cub-cli` (the binary).
+
+## Protected Recipe
+
+Cub is listed as a **protected recipe** in `src/cook/fetch.rs` — it cannot be
+re-fetched online. Sources are archived in `sources/redbear-0.1.0/`.
+
+## Error Handling
+
+Cub uses an 11-variant `CubError` enum via `thiserror`:
+
+| Variant | Description |
+|---------|-------------|
+| `Io` | Filesystem errors |
+| `TomlParse` | recipe.toml parse failures |
+| `TomlSerialize` | recipe.toml serialization failures |
+| `InvalidPkgbuild` | Malformed RBPKGBUILD |
+| `BuildFailed` | `repo cook` or build failures |
+| `PackageNotFound` | Missing package in repo/BUR |
+| `Conversion` | PKGBUILD conversion errors |
+| `Dependency` | Dependency resolution failures |
+| `Aur` | AUR RPC errors (HTTP, parse, rate limit) |
+| `Storage` | `~/.cub/` storage errors |
+| `Network` | General network failures |
+| `Sandbox` | Build sandbox errors |
+
+## Limitations
+
+1. **Build tools required**: `repo cook` requires the build toolchain
+   (cross-compiler, host tools) which is not yet available inside Red Bear OS.
+   Until build tools are ported, `cub build` (cooking) only works on build
+   hosts. Runtime-only operations (search, install, query, remove) work inside
+   Red Bear OS.
+
+2. **Single source support**: recipe.toml generation currently supports only one
+   primary source per recipe (AUR packages with multiple sources need manual
+   adjustment).
+
+3. **No binary repository**: cub currently fetches from AUR (source-based) and
+   BUR (Red Bear package recipes). There is no binary package repository — all
+   packages must be built from source.
+
+4. **AUR JSON parsing**: The AUR module uses a hand-written JSON parser to avoid
+   adding `serde_json` as a dependency. This works for the AUR RPC response
+   format but is less robust than `serde_json`.
+
+5. **TUI test coverage**: The `cub-tui` crate has no unit tests. Views are
+   rendering-only and verified via `cargo build`.
+
+## Future Work
+
+- Port build tools inside Red Bear OS to enable full cooking at runtime
+- Add binary package repository support for pre-built packages
+- Implement `serde_json` dependency for robust AUR JSON parsing
+- Add TUI unit tests for view rendering
+- Support multi-source PKGBUILDs in recipe.toml generation
+- Add package signing verification on install
+- Implement delta updates for large packages