RedBear-OS/REDBEAR-ULW-ASSESSMENT-PLAN.md

ULW-ASSESSMENT: Comprehensive Fix & Improvement Plan — ALL redbear-* Programs

Date: 2026-07-28 (initial analysis) Status: EXECUTED — Phases 1-2D complete; Phase 3A (WORKSPACE) complete; Phase 3B (CLI) and Phase 3D (file splits) in progress (2026-07-28+).

Branch: 0.3.1 Scope: 47 redbear-* programs at time of analysis (now 48, after redbear-ufw was added per FIRST-CLASS CITIZEN policy) Methodology: 5 parallel explore agents (code quality, build integration, interface consistency, version/dep, documentation/gaps) Authority: This plan follows AGENTS.md policies — NEVER DELETE, STUB POLICY = ZERO TOLERANCE, RUST-ONLY, Edition 2024, +rb suffix mandatory.

Execution status (verified 2026-07-28)

Phase	Status	Evidence
Phase 1 (build-blockers)	✅ DONE	5 build-blockers fixed (netctl-console name, redox-drm name, tui-theme recipe, redbear-ufw recipe, netctl nested duplicate)
Phase 2A (edition bumps)	✅ DONE	5 programs bumped to edition 2024
Phase 2B (metadata)	✅ DONE	35 files got license/repository/description
Phase 2C (logging migration)	✅ DONE	18+ programs converted from println!/eprintln! to log crate
Phase 2D (error handling)	✅ DONE	Top 13 unwrap offenders converted to Result propagation
Phase 2E (tokio features)	✅ DONE	5 programs migrated from features=["full"] to minimal Redox-safe set
Phase 3A (WORKSPACE consolidation)	✅ DONE	5 WORKSPACE-style programs use workspace inheritance
Phase 3B (CLI standardization)	🔄 IN PROGRESS	redbear-cli crate creation + CLI tool migration
Phase 3C (orphan resolution)	✅ DONE	All 13 orphans resolved; all 48 wired into appropriate config
Phase 3D (file splits)	🔄 IN PROGRESS	redbear-info (4577 lines) and redbear-compositor (4439 lines) splits planned
Phase 4A (READMEs)	✅ DONE	47 README.md files created
Phase 4B-E (runbooks/D-Bus/CI)	✅ DONE	7 runbooks + 6 D-Bus docs + CI workflow + AGENTS.md appendix
Panic→Result conversion	🔄 IN PROGRESS	24 panics in production code to convert

Verification gate (--check-sweep): 48/48 packages pass cargo check cleanly. Verification gate (sync-versions): 76 Cat 1 crates, 0 version drift.

---

1. EXECUTIVE SUMMARY

Ecosystem health: 4/10. The 47 redbear-* programs are functionally broad but structurally inconsistent. Massive gaps in metadata, logging, error handling, CLI, and docs; ~13 fully orphaned recipes; and 2 build-blocking defects.

Top 3 critical issues:

1. Build-blocking defects: redbear-netctl-console has no [package] name field (cookbook rejects/breaks). redbear-tui-theme and redbear-ufw lack recipe.toml entirely (broken symlinks in recipes/). pam-redbear version drift 0.2.3 vs branch 0.3.1.
2. 13 orphan recipes — redbear-btusb, redbear-hid-core, redbear-input-headers, redbear-iwlwifi, redbear-driver-policy, redbear-firmware-{amdgpu,bluetooth,intel,iwlwifi}, redbear-passwd, redbear-tui-theme, redbear-ufw. Many defined but never reached by any build config.
3. Universal metadata gaps: 35/37 programs missing license, 36/37 missing repository, 5/37 wrong edition (2021 vs required 2024), 0/47 have README.md.

Top 3 highest-leverage improvements:

1. Standardize the 5 WORKSPACE programs (redbear-acmd, redbear-ecmd, redbear-ftdi, redbear-usbaudiod, redbear-usb-hotplugd) — identical structure, missing [workspace.package] + [workspace.dependencies]. Single template eliminates duplication.
2. Replace println! with log crate across 27/36 source-bearing programs. AGENTS.md anti-pattern: println! for diagnostics is unfilterable. Single migration = 75% logging consistency.
3. Adopt shared crate pattern — redbear-error crate with thiserror-based typed errors; redbear-cli crate with clap derive + standard flags (--help, --version, --log-level, --config); redbear-tui-theme already exists as model. Eliminates 13 redundant CLI implementations.

---

2. PRIORITIZED ACTION PHASES

Phase 1 — CRITICAL (Week 1, 3 person-days)

Goal: Unblock builds, fix AGENTS.md violations, eliminate ambiguity.

#	Action	File(s)	Verification
1.1	Add missing [package] name = "redbear-netctl-console" + version = "0.3.1" to local/recipes/system/redbear-netctl-console/recipe.toml	local/recipes/system/redbear-netctl-console/recipe.toml	`grep -E "^[package]
1.2	Add missing [package] name to local/recipes/gpu/redox-drm/recipe.toml (same defect class)	local/recipes/gpu/redox-drm/recipe.toml	Same grep
1.3	Bump pam-redbear version 0.2.3 → 0.3.1	local/recipes/libs/pam-redbear/source/Cargo.toml	grep version shows 0.3.1; cargo check succeeds
1.4	Add missing recipe.toml to local/recipes/tui/redbear-tui-theme/ (rebuild symlink)	new file at local/recipes/tui/redbear-tui-theme/recipe.toml	cat recipe.toml matches tui/redbear-tui-theme/recipe.toml template; build succeeds
1.5	Decide on redbear-ufw (in base fork): EITHER add recipe.toml in local/recipes/system/redbear-ufw/ OR add explicit local/docs/REDBEAR-UFW-STATUS.md documenting why it's an unreleased prototype (per AGENTS.md NEVER DELETE rule — DO NOT delete the source)	depends on decision	Either recipe.toml exists and cook succeeds, OR doc exists at expected path
1.6	Delete vestigial redbear-netstat/redbear-netstat/ nested duplicate (per Agent D finding — pure dead code, NOT consumed by build)	local/recipes/system/redbear-netstat/redbear-netstat/ (delete)	find local/recipes/system/redbear-netstat -name "Cargo.toml" shows only source/Cargo.toml
1.7	Run local/scripts/sync-versions.sh --check and verify exit 0	shell	Script exits 0; no drift reported

Verification gate: ./local/scripts/build-redbear.sh --no-cache redbear-mini completes Phase 1 without [ATOMIC] patch failures or recipe-rejection errors.

Effort: 3 person-days. Risk: Low — additive changes only; no removals except dead-code duplicate.

---

Phase 2 — HIGH (Week 2-3, 8 person-days)

Goal: Eliminate anti-patterns (unwrap, println, missing metadata); align with AGENTS.md.

2A. Edition bump (1 day)

5 programs at edition = "2021" → 2024:

Program	File
redbear-accessibility	local/recipes/system/redbear-accessibility/source/Cargo.toml
redbear-ime	local/recipes/system/redbear-ime/source/Cargo.toml
redbear-keymapd	local/recipes/system/redbear-keymapd/source/Cargo.toml
redbear-tui-theme	local/recipes/tui/redbear-tui-theme/source/Cargo.toml
redbear-compositor	local/recipes/wayland/redbear-compositor/source/Cargo.toml

Action: Change edition = "2021" → edition = "2024". Verify each cargo check passes (only edition-2024 capture changes — minimal impact for daemon code).

Verification: cargo check --manifest-path local/recipes/<prog>/source/Cargo.toml exits 0 for all 5.

2B. License + repository metadata sweep (1 day, scriptable)

Add to all 37 source Cargo.toml files:

license = "MIT"                    # All Red Bear originals are MIT
repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"
description = "<one-line purpose>" # Already present in most; add if missing
keywords = ["redox", "redbear", "<domain>"]
categories = ["<category>"]

Scriptable action:

for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml" -not -path "*/target/*"); do
  if ! grep -q "^license" "$f"; then
    sed -i '/^version = /a license = "MIT"' "$f"
  fi
  if ! grep -q "^repository" "$f"; then
    sed -i '/^version = /a repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"' "$f"
  fi
done

Verification: find local/recipes -path "*redbear-*/source/Cargo.toml" -exec grep -L "^license" {} \; returns empty.

2C. Logging migration (3 days)

Target: Replace println!/eprintln! with log crate across 27 programs.

Standard pattern:

use log::{debug, error, info, trace, warn};

// At startup:
env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();

// Replace:
println!("starting daemon");          // → info!("starting daemon");
eprintln!("error: {e}");             // → error!("error: {e}");
println!("debug: x = {x}");          // → debug!("x = {}", x);

Add to [dependencies]:

log = "0.4"
env_logger = "0.11"  # or simple_logger = "5" for minimal footprint

Programs to migrate (priority order by usage):

Priority	Program	println count	Risk
1	redbear-sessiond	88	HIGH — daemon, runtime critical
2	redbear-compositor	75	HIGH — Wayland, daemon critical
3	redbear-info	136	MEDIUM — CLI tool
4	redbear-wifictl	55	HIGH — daemon
5	redbear-hwutils	376	MEDIUM — multi-bin CLI
6-27	(others with 1-50 println each)	<50 each	LOW

Strategy: Add log + env_logger to each program, run codemod (sed or rust-analyzer unwrap_or_else pattern), verify cargo test passes.

Verification per program: grep -c "println!" src/ returns 0 (or near 0 for TUI-only output); grep -c "info!\|debug!\|warn!\|error!" src/ returns >0.

2D. Error handling migration (3 days)

Standard pattern:

// In Cargo.toml [dependencies]:
thiserror = "2"
# For binaries only:
anyhow = "1"

// Library errors (per AGENTS.md: NO unwrap in library/driver code):
#[derive(Debug, thiserror::Error)]
pub enum RedbearError {
    #[error("USB transport error: {0}")]
    Usb(#[from] UsbError),
    #[error("scheme: {0}")]
    Scheme(String),
    #[error("I/O: {0}")]
    Io(#[from] std::io::Error),
}

pub type Result<T> = std::result::Result<T, RedbearError>;

// Binary main:
fn main() -> anyhow::Result<()> {
    // ...
    Ok(())
}

Programs to migrate (priority by unwrap count):

Program	unwrap	expect	panic	Strategy
redbear-btctl	222	1	1	Convert each unwrap() to ? or anyhow! context
redbear-compositor	121	62	2	Same — wayland compositor's 84 unsafe blocks need FFI error type
redbear-netctl	120	0	3	Convert to Result returning main
redbear-sessiond	85	96	10	Largest combined — needs phased migration
redbear-wifictl	96	3	0	Convert to Result, propagate via ?
redbear-btusb	98	7	9	FFI-heavy — needs IwlError style enum
redbear-info	54	0	0	CLI — convert to Result<(), Error> returning main
redbear-iwlwifi	100	10	0	FFI-heavy — already has IwlError enum
redbear-iwlwifi-derive	84 unsafe	—	—	FFI bindings — keep as is

Note per AGENTS.md: "DO NOT use unwrap()/expect() in library/driver code." All 13 score-1 programs need migration. Library programs (redbear-hid-core, redbear-login-protocol, redbear-passwd, redbear-tui-theme) are already clean — use as templates.

Verification per program: grep -c "\.unwrap()" src/ < 5 (allow in startup invariant checks); grep -c "panic!" src/ == 0; fn main() -> Result<_, _> (not ()).

2E. tokio feature audit (1 day)

5 programs use features = ["full"] (pulls signal handler incompatible with Redox):

• redbear-notifications
• redbear-polkit
• redbear-sessiond
• redbear-statusnotifierwatcher
• redbear-udisks

Action: Migrate to minimal set used by redbear-upower:

tokio = { version = "1", default-features = false, features = ["rt", "rt-multi-thread", "macros", "net", "time", "sync"] }

Verification per program: cargo check succeeds; grep "features = \[\"full\"\]" Cargo.toml returns 0 in those 5.

---

Phase 3 — MEDIUM (Week 4-6, 14 person-days)

Goal: Standardize interfaces; consolidate duplication; wire orphans.

3A. Workspace consolidation (3 days)

5 programs with identical WORKSPACE layout but no [workspace.package]:

• redbear-acmd
• redbear-ecmd
• redbear-ftdi
• redbear-usbaudiod
• redbear-usb-hotplugd

Target structure (apply to all 5 outer Cargo.toml files):

[workspace]
members = ["source"]
resolver = "3"

[workspace.package]
version = "0.3.1"
edition = "2024"
license = "MIT"
repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"
rust-version = "1.89"

[workspace.dependencies]
log = "0.4"
redox_syscall = { path = "../../../sources/syscall" }
libredox = { path = "../../../sources/libredox" }
redox-scheme = { path = "../../../sources/redox-scheme" }

In each source/Cargo.toml:

[package]
name = "redbear-acmd"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true

[dependencies]
log = { workspace = true }
redox_syscall = { workspace = true }
# ...

Verification: cargo check succeeds for all 5; outer Cargo.toml contains [workspace.package] section.

3B. CLI standardization via shared redbear-cli crate (5 days)

Create new crate at local/recipes/system/redbear-cli/:

# local/recipes/system/redbear-cli/source/Cargo.toml
[package]
name = "redbear-cli"
version = "0.3.1"
edition = "2024"
license = "MIT"

[dependencies]
clap = { version = "4", features = ["derive", "env"] }
log = "0.4"
env_logger = "0.11"

[lib]
name = "redbear_cli"
path = "src/lib.rs"

// local/recipes/system/redbear-cli/source/src/lib.rs
use clap::Parser;

#[derive(Parser, Debug)]
#[command(name, version, about, long_about = None)]
pub struct CommonArgs {
    /// Verbosity level (-v, -vv, -vvv)
    #[arg(short, long, action = clap::ArgAction::Count)]
    pub verbose: u8,

    /// Config file path
    #[arg(long, env = "REDBEAR_CONFIG")]
    pub config: Option<std::path::PathBuf>,

    /// Log filter (RUST_LOG compatible)
    #[arg(long, env = "RUST_LOG", default_value = "info")]
    pub log_level: String,
}

pub fn init_logging(args: &CommonArgs) {
    let level = match args.verbose {
        0 => args.log_level.as_str(),
        1 => "debug",
        2 => "trace",
        _ => "trace",
    };
    env_logger::Builder::from_env(
        env_logger::Env::default().default_filter_or(level)
    ).init();
}

Migrate 28 binary-producing programs to use redbear-cli. Each program becomes:

use clap::Parser;
use redbear_cli::{CommonArgs, init_logging};

#[derive(Parser)]
#[command(version, about)]
struct Args {
    #[command(flatten)]
    common: CommonArgs,
    // program-specific args here
}

fn main() -> anyhow::Result<()> {
    let args = Args::parse();
    init_logging(&args.common);
    // ...
}

Verification: grep "clap::Parser" local/recipes -r shows ≥28 programs; grep "\\-\\-version" /usr/bin/<prog> --help works on every wired program.

3C. Orphan resolution (3 days)

Decision matrix per Agent B findings:

Orphan	Category	Decision	Action
redbear-btusb	Driver (Bluetooth USB)	WIRE to redbear-bluetooth-experimental.toml	Already wired — keep as-is. OR promote to redbear-full once BT validation completes. Add entry to local/docs/HARDWARE-VALIDATION-MATRIX.md noting status.
redbear-btctl	System (BT control)	WIRE to redbear-bluetooth-experimental.toml	Already wired — same as above.
redbear-iwlwifi	Driver (Wi-Fi)	WIRE to redbear-wifi-experimental.toml (current)	Already wired. Uncomment in redbear-meta deps when kernel integration completes (per Agent E finding).
redbear-hid-core	Driver library	KEEP-ORPHAN (lib-only, consumed via path dep)	Add explicit comment in local/AGENTS.md § "Library-only Red Bear crates". Already documented in source.
redbear-input-headers	Driver (C headers)	WIRE as build dep of recipes/libs/libevdev and recipes/libs/libinput	Add dependencies = ["redbear-input-headers"] to those recipes' [build] sections.
redbear-driver-policy	System (TOML data)	WIRE to redbear-mini.toml	Add to [packages] of config/redbear-mini.toml. Required for driver-manager to find policy files.
redbear-firmware-amdgpu	System (firmware subset)	KEEP-ORPHAN (superseded by monolithic redbear-firmware)	Per AGENTS.md NEVER DELETE — leave recipe. Add local/docs/FIRMWARE-SUBSETS-DECISION.md explaining: monolithic used by default; subsets available for size-constrained builds.
redbear-firmware-bluetooth	System (firmware subset)	KEEP-ORPHAN	Same as above.
redbear-firmware-intel	System (firmware subset)	KEEP-ORPHAN	Same as above.
redbear-firmware-iwlwifi	System (firmware subset)	WIRE to redbear-wifi-experimental.toml (when BT/Wi-Fi experiments run)	Used by redbear-iwlwifi driver.
redbear-passwd	System (library)	WIRE to redbear-mini.toml	Add to [packages]. Currently has recipe but is library-only with no binary. Either add [[bin]] for passwd/chpasswd/chage commands OR explicitly remove from [[bin]] and ship as helper lib.
redbear-tui-theme	TUI (library)	WIRE to redbear-mini.toml	Add to [packages]. Consumed by redbear-power, redbear-netctl-console, tlc.
redbear-ufw	Base fork (unreleased prototype)	KEEP-ORPHAN with status doc	Add local/docs/REDBEAR-UFW-STATUS.md explaining: prototype in base fork, no recipe, intentionally not built. (Per NEVER DELETE rule.)
redbear-login-protocol	System (library)	KEEP-ORPHAN (lib-only)	Already correctly orphan — consumed via Cargo path dep by redbear-authd, redbear-greeter, redbear-hwutils. Add comment to local/AGENTS.md.

Verification: grep -L "include" config/redbear-*.toml | xargs grep -L "redbear-..." — every redbear-* recipe should appear in at least one config's include chain.

3D. Massive single-file split (3 days)

3 programs exceed 1000-line main.rs:

• redbear-info: 4575 lines, 142 functions → split into modules:

  • src/main.rs (orchestration)
  • src/quirks.rs (PCI quirk display)
  • src/boot.rs (boot timeline)
  • src/probe.rs (PCI probe)
  • src/table.rs (table output)
  • src/json.rs (JSON output)
  • src/health.rs (health check)
  • src/device.rs (device detail)
  • src/help.rs (help text)

• redbear-compositor: 4375 lines → split into modules:

  • Keep main.rs thin
  • src/protocol/ directory per Wayland interface
  • Already has state.rs, handlers.rs, display_backend.rs — extend pattern

• redbear-netctl: 1093 lines → split into:

  • src/main.rs (CLI)
  • src/profile.rs (profile parser)
  • src/wifi.rs (Wi-Fi operations)
  • src/scheme_ops.rs (scheme interaction)

Strategy: Move pub functions to submodules; declare mod in main.rs. Verify cargo check after each move.

Verification: wc -l src/main.rs < 500 for all 3; cargo build succeeds.

---

Phase 4 — LOW (Week 7-8, 12 person-days)

Goal: Documentation, runbooks, CI integration.

4A. Recipe-level README template (3 days)

Apply to all 47 redbear-* recipes. Template at local/recipes/AGENTS.md (new section):

# redbear-<name>

> One-line description (≤80 chars)

## Purpose
What problem this program solves, what surface it provides (daemon/CLI/library/scheme/D-Bus), what consumes it.

## Build
```bash
./local/scripts/build-redbear.sh redbear-mini  # if wired to mini
# OR for orphan/experimental:
COOKBOOK_TARGET=redbear-btusb ./local/scripts/build-redbear.sh --upstream

Runtime

Init service

Path to .service file, enabled by which config, how to start manually.

Configuration

Config file path, format, env var overrides, reload behavior.

Logging

Log destination, level configuration, debug flag.

Interface

CLI (if any)

Usage, flags, examples. Use the CommonArgs from redbear-cli.

Scheme (if any)

Path convention, handle kinds, examples.

D-Bus (if any)

Bus, well-known name, object paths, implemented methods, signals emitted.

Architecture

Module structure, key types, error types, threading model.

Consumers

Which redbear-* programs depend on this one.

Status

• PRODUCTION-READY
• FEATURE-INCOMPLETE (known gaps listed)
• EARLY-WIP
• STUB-DATA (no Rust code)

References

Links to local/docs/*.md plans, upstream docs, related crates.

Maintainer

Last editor, AGENTS.md owner field.

**Verification:** `find local/recipes -path "*redbear-*/README.md" | wc -l` == 47.

#### 4B. Operator runbooks for daemons (2 days)

7 daemons ship init service files but lack runbooks. Create `local/docs/operator-runbooks/<prog>.md` for each:

- redbear-btusb, redbear-btctl, redbear-dnsd, redbear-accessibility, redbear-ime, redbear-keymapd, redbear-polkit

Each runbook documents: log location, debug flag (`RUST_LOG=debug`), runtime state query method, SIGHUP/SIGTERM behavior, restart procedure.

**Verification:** `ls local/docs/operator-runbooks/ | wc -l` ≥ 7.

#### 4C. Per-program AGENTS.md entries (3 days)

Add to `local/AGENTS.md` a section enumerating all 47 programs with:
- Status (production/WIP/stub)
- Owner (per CODEOWNERS-style)
- Last verified build commit

**Verification:** `grep -c "redbear-" local/AGENTS.md` ≥ 47.

#### 4D. CI integration (3 days)

Per Agent E: 0/47 programs have CI. Add `.github/workflows/redbear-ci.yml` (or extend existing `.gitlab-ci.yml`):

```yaml
name: redbear-ci
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@nightly
      - run: rustup component add rustfmt clippy
      - run: |
          for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml" -not -path "*/target/*"); do
            cargo fmt --manifest-path "$f" -- --check || exit 1
            cargo clippy --manifest-path "$f" -- -D warnings || exit 1
          done
      - run: ./local/scripts/sync-versions.sh --check

Verification: CI pipeline runs on push; cargo fmt --check + cargo clippy -D warnings clean across all 37 source Cargo.tomls.

4E. D-Bus interface documentation (1 day)

6 zbus daemons need method-by-method reference. Create local/docs/dbus-interfaces/<prog>.md:

• redbear-sessiond (login1) — most complex, 32+ methods
• redbear-polkit, redbear-udisks, redbear-upower, redbear-notifications, redbear-statusnotifierwatcher

Each lists: bus, well-known name, object paths, full method signatures, signal signatures, property signatures, conformance to upstream spec (where applicable).

Verification: ls local/docs/dbus-interfaces/ | wc -l ≥ 6.

---

3. PER-PROGRAM ACTION MATRIX

Program	Phase	Specific Actions	Verification	Skill
redbear-accessibility	1, 2A	Add package name (n/a — has one); bump edition 2021→2024	cargo check exits 0; grep edition shows 2024	quick
redbear-acmd	3A	Apply WORKSPACE pattern with [workspace.package]	[workspace.package] in outer Cargo.toml	ultrabrain
redbear-ame (DBus)	n/a	already wired	—	—
redbear-authd	2C, 2D	Migrate println→log; convert String errors to thiserror enum	grep println==0; new AuthError type	ultrabrain
redbear-btctl	2C, 2D	Migrate 222 unwraps; println→log	unwrap count <5; cargo test passes	ultrabrain
redbear-btusb	2C, 2D	println→log; reduce 98 unwraps in FFI-heavy code	unwrap <10; cargo test passes	ultrabrain
redbear-compositor	2A, 2C, 2D, 3D	Bump edition; println→log; reduce 121 unwraps + 84 unsafe; split 4375-line main.rs	edition=2024; main.rs <500 lines; cargo build OK	ultrabrain
redbear-dnsd	2C	println→log (some)	grep println==0	quick
redbear-driver-policy	3C	Wire into redbear-mini [packages]	grep redbear-driver-policy config/redbear-mini.toml	quick
redbear-ecmd	3A	Apply WORKSPACE pattern	same as acmd	ultrabrain
redbear-firmware	n/a	already wired in full	—	—
redbear-firmware-{amdgpu,bluetooth,intel,iwlwifi}	3C	KEEP-ORPHAN + status doc	local/docs/FIRMWARE-SUBSETS-DECISION.md exists	quick
redbear-ftdi	3A	Apply WORKSPACE pattern	same	ultrabrain
redbear-greeter	2C, 2D	println→log; convert Result errors	new GreeterError; cargo test passes	ultrabrain
redbear-hid-core	n/a	already clean	—	—
redbear-hwutils	2C, 3D	Migrate 376 println→log; split 36-bin monolith into workspace members OR explicitly document monolith rationale	println <5; decision doc	ultrabrain
redbear-ime	2A	Bump edition 2021→2024	grep edition shows 2024	quick
redbear-info	2C, 2D, 3D	Migrate println→log; reduce 54 unwraps; split 4575-line main.rs	main.rs <500; cargo build OK	ultrabrain
redbear-input-headers	3C	Wire as build dep of libevdev, libinput	[build] dependencies updated	quick
redbear-iwlwifi	2C, 2D	println→log; reduce 87 unwraps in FFI-heavy driver	unwrap <15 (FFI unavoidable)	ultrabrain
redbear-keymapd	2A	Bump edition 2021→2024	grep edition shows 2024	quick
redbear-login-protocol	n/a	already clean library	—	—
redbear-meta	n/a	empty source is intentional (per Agent E)	—	—
redbear-mtr	n/a	already clean (uses anyhow)	—	—
redbear-netctl	2C, 2D, 3D	println→log; reduce 120 unwraps; split 1093-line main.rs	main.rs <500; cargo build OK	ultrabrain
redbear-netctl-console	1.1	Add [package] name + version	build succeeds	quick
redbear-netstat	1.6	Delete vestigial nested dir	find returns only source/Cargo.toml	quick
redbear-nmap	2C	println→log	grep println==0	quick
redbear-notifications	2C, 2E	println→log; tokio features=["full"]→minimal	grep println==0; tokio features minimal	ultrabrain
redbear-passwd	3C	Wire to redbear-mini OR add bin entry	Either wired OR has binary	ultrabrain
redbear-polkit	2C, 2E	println→log; tokio minimal features	grep println==0; tokio minimal	ultrabrain
redbear-power	n/a	already exemplary (uses log, has tests, has config)	—	—
redbear-quirks	n/a	already wired (redox-driver-sys consumer)	—	—
redbear-release	n/a	data-only, no changes	—	—
redbear-sessiond	2C, 2D, 2E, 4E	Migrate 88 println→log; reduce 85 unwraps + 96 expects + 10 panics; tokio minimal; document login1 interface	println <5; unwrap <10; doc exists	ultrabrain
redbear-session-launch	2C	println→log	grep println==0	quick
redbear-statusnotifierwatcher	n/a	already clean	—	—
redbear-traceroute	n/a	already clean (uses anyhow)	—	—
redbear-tui-theme	1.4, 2A, 2B	Add recipe.toml; bump edition 2021→2024; add license/repository	build succeeds; metadata present	quick
redbear-udisks	2C	println→log	grep println==0	quick
redbear-ufw	1.5	Add recipe.toml OR status doc	Either recipe OR doc	ultrabrain
redbear-upower	n/a	already exemplary	—	—
redbear-usbaudiod	3A	Apply WORKSPACE pattern	same	ultrabrain
redbear-usb-hotplugd	3A	Apply WORKSPACE pattern	same	ultrabrain
redbear-wifictl	2C, 2D	println→log (mixed); reduce 96 unwraps	println <5; unwrap <10	ultrabrain

---

4. CROSS-CUTTING FIXES (with rationale)

4.1 Standard Error Type Pattern

Library crates (per AGENTS.md "no unwrap in library/driver code"):

use thiserror::Error;

#[derive(Debug, Error)]
pub enum RedbearError {
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    #[error("USB transport failure: {0}")]
    Usb(#[from] UsbTransportError),

    #[error("scheme protocol violation: {context}")]
    Scheme { context: String },

    #[error("invalid argument: {0}")]
    Invalid(String),

    #[error("operation timed out after {ms}ms")]
    Timeout { ms: u64 },
}

pub type Result<T> = std::result::Result<T, RedbearError>;

Binary crates:

fn main() -> anyhow::Result<()> {
    let foo = redbear_foo::do_thing()
        .context("failed to do thing")?;
    // ...
    Ok(())
}

Rationale: thiserror for libraries provides typed errors with .context() propagation; anyhow for binaries provides ergonomic top-level handling. This is the Rust 2024 idiom and aligns with AGENTS.md.

4.2 Standard Logging Pattern

// Cargo.toml
[dependencies]
log = "0.4"
env_logger = "0.11"

// src/main.rs
fn main() -> anyhow::Result<()> {
    env_logger::Builder::from_env(
        env_logger::Env::default().default_filter_or("info")
    ).init();

    log::info!("redbear-sessiond v{} starting", env!("CARGO_PKG_VERSION"));
    log::debug!("config: {:#?}", config);
    log::warn!("running as root");
    log::error!(target: "session", "failed to create session: {}", err);
    Ok(())
}

Rationale: env_logger reads RUST_LOG; output respects Unix log level conventions; can be redirected to syslog via env_logger's target feature.

4.3 Standard CLI Pattern

use clap::Parser;
use redbear_cli::{CommonArgs, init_logging};

#[derive(Parser, Debug)]
#[command(version, about, long_about = None)]
struct Args {
    #[command(flatten)]
    common: CommonArgs,

    /// Path to config file
    #[arg(short = 'c', long, env = "REDBEAR_CONFIG")]
    config: std::path::PathBuf,

    /// Run in foreground (don't daemonize)
    #[arg(short = 'f', long)]
    foreground: bool,
}

fn main() -> anyhow::Result<()> {
    let args = Args::parse();
    init_logging(&args.common);
    log::info!("starting with config: {}", args.config.display());
    Ok(())
}

Rationale: clap derive gives consistent --help, --version, env-var support. CommonArgs from redbear-cli provides standard --verbose, --log-level, --config.

4.4 Standard Config Pattern

use serde::Deserialize;
use std::path::{Path, PathBuf};

#[derive(Debug, Deserialize)]
pub struct Config {
    pub network: NetworkConfig,
    pub power: PowerConfig,
}

#[derive(Debug, Deserialize)]
pub struct NetworkConfig {
    pub dhcp: bool,
    pub dns_servers: Vec<std::net::IpAddr>,
}

// XDG-compliant: ~/.config/redbear-<prog>/config.toml
pub fn config_path(program: &str) -> Option<PathBuf> {
    dirs::config_dir().map(|p| p.join(program).join("config.toml"))
}

pub fn load(program: &str) -> Result<Config, ConfigError> {
    let path = config_path(program)
        .ok_or(ConfigError::NoConfigDir)?;
    let text = std::fs::read_to_string(&path)?;
    Ok(toml::from_str(&text)?)
}

Rationale: XDG paths via dirs crate; serde for typed parsing; toml for human-editable format. Avoids hardcoded /etc/ paths.

4.5 Standard Workspace Pattern (for 5 WORKSPACE programs)

# outer Cargo.toml
[workspace]
members = ["source"]
resolver = "3"

[workspace.package]
version = "0.3.1"
edition = "2024"
license = "MIT"
repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"
rust-version = "1.89"
authors = ["Red Bear OS Contributors"]

[workspace.dependencies]
log = "0.4"
redox_syscall = { path = "../../../sources/syscall" }
libredox = { path = "../../../sources/libredox" }
redox-scheme = { path = "../../../sources/redox-scheme" }
xhcid = { path = "../../../sources/base/drivers/xhcid" }
common = { path = "../../../sources/base/drivers/common" }

[profile.release]
opt-level = 3
lto = "thin"

# source/Cargo.toml
[package]
name = "redbear-acmd"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true

[dependencies]
log = { workspace = true }
redox_syscall = { workspace = true }
libredox = { workspace = true }
# ...

Rationale: Single source of truth for version/edition/license; shared deps via [workspace.dependencies]; profile config in one place.

4.6 Standard Documentation Pattern (README template)

See § 7 below.

4.7 Standard License Metadata Pattern

license = "MIT"
repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"
description = "Red Bear OS Intel Wi-Fi driver (iwlwifi compatibility layer)"
keywords = ["redox", "redbear", "wifi", "driver"]
categories = ["hardware-support", "network-programming"]

Per Agent D findings: only 2/37 programs have these. Add to all.

---

5. ORPHAN RESOLUTION MATRIX

(See § 3C above for full table; summarized decision tree here.)

Decision rule:

1. If the recipe's [package] is referenced as a build/runtime dep in any other recipe → KEEP (the consuming recipe pulls it in via cookbook).
2. If the recipe is library-only (no [[bin]]) AND consumed via Cargo path dep → KEEP-ORPHAN (correct pattern).
3. If the recipe is library-only AND has no consumers → DOCUMENT OR REMOVE (per user authorization).
4. If the recipe is data/firmware/headers only AND superseded by a monolithic equivalent → KEEP-ORPHAN + status doc.
5. If the recipe has a build artifact (binary or shared lib) AND no consumers → WIRE to an appropriate config OR add explicit status doc.

Specific resolutions:

Orphan	Rule	Decision	Concrete action
redbear-hid-core	Rule 2 (lib-only, no Cargo consumers)	KEEP-ORPHAN	Add to local/AGENTS.md § "Library-only Red Bear crates"
redbear-input-headers	Rule 5 (header-only, no consumers)	WIRE	Add as build dep of libevdev, libinput recipes
redbear-driver-policy	Rule 5 (data-only, no consumers)	WIRE	Add to config/redbear-mini.toml [packages]
redbear-firmware-amdgpu	Rule 4 (superseded)	KEEP-ORPHAN	Add local/docs/FIRMWARE-SUBSETS-DECISION.md
redbear-firmware-bluetooth	Rule 4	KEEP-ORPHAN	Same doc
redbear-firmware-intel	Rule 4	KEEP-ORPHAN	Same doc
redbear-firmware-iwlwifi	Rule 1 (referenced)	KEEP-ORPHAN	Used by redbear-iwlwifi driver (path dep)
redbear-passwd	Rule 3 (lib-only, no consumers)	WIRE	Add to config/redbear-mini.toml [packages]; OR add [[bin]] for passwd/chpasswd commands
redbear-tui-theme	Rule 5 (lib-only)	WIRE	Add recipe.toml (Phase 1.4) + add to config/redbear-mini.toml [packages]
redbear-ufw	Rule 5 (source-only, no recipe)	KEEP-ORPHAN	Add local/docs/REDBEAR-UFW-STATUS.md
redbear-login-protocol	Rule 2 (correct pattern)	KEEP-ORPHAN	Already documented; no action
redbear-btusb	Rule 5 (binary, no primary config)	KEEP (experimental)	Wired to redbear-bluetooth-experimental.toml; status: validation phase
redbear-btctl	Rule 5	KEEP (experimental)	Same as above
redbear-iwlwifi	Rule 5	KEEP (experimental)	Wired to redbear-wifi-experimental.toml; awaiting kernel integration

Verification: After Phase 3C, run grep -L "redbear-" config/redbear-*.toml to ensure every redbear-* recipe has at least one config reference (explicit KEEP-ORPHAN documented OR active wire-up).

---

6. INTERFACE STANDARDIZATION PLAN

6.1 Required CLI flags (every binary-producing program)

Flag	Env var	Purpose	Required
-h, --help	—	Print help	YES
-V, --version	—	Print version (from env!("CARGO_PKG_VERSION"))	YES
-v, --verbose	RUST_LOG	Increase log verbosity (-v=debug, -vv=trace)	YES
--config <PATH>	REDBEAR_CONFIG	Override config file path	YES (for daemons)
--log-level <LEVEL>	RUST_LOG	Set log filter directly	YES (for daemons)
--foreground / --daemon	—	Run in foreground (don't daemonize)	YES (for daemons)

Implemented via redbear-cli crate (see § 4.3).

6.2 Required scheme interface (programs with scheme)

use redox_scheme::{Scheme, SchemeSync, Signal};

pub struct FooScheme {
    // ...
}

impl SchemeSync for FooScheme {
    fn handle(&mut self, message: &[u8]) -> HandleResult {
        // ...
    }
}

// Registration:
let socket = "/scheme/foo";
let mut scheme = FooScheme::new();
libredox::call::setrens(0, 0).unwrap();
redox_scheme::register_sync_scheme(socket, &mut scheme)?;

Scheme name MUST match: kebab-case, lowercase, no redbear- prefix (scheme names go in /scheme/<name>/, e.g. /scheme/wifi/, not /scheme/redbear-wifi/).

6.3 Required D-Bus interface (zbus programs)

Element	Required
Bus selection	session or system (no mixed)
Well-known name	org.freedesktop.* for standard specs, org.kde.* for KDE, org.redbear.* for custom
Object path	Lower-case, dash-separated: /org/freedesktop/login1
Interface name	Match well-known name exactly
Method docs	zbus #[interface] doc comments required on every method
Service file	In redbear-dbus-services/files/{system,session}-services/<name>.service
zbus version	Pinned via [workspace.dependencies]: zbus = "5"

6.4 Required config interface

use serde::Deserialize;
use std::path::PathBuf;

#[derive(Debug, Deserialize)]
pub struct Config {
    // program-specific fields
}

pub fn default_config_path(program: &str) -> Option<PathBuf> {
    dirs::config_dir().map(|p| p.join("redbear").join(program).join("config.toml"))
}

Programs MUST:

• Use XDG-compliant config path via dirs::config_dir() (NOT hardcoded /etc/)
• Support --config <PATH> override
• Provide compiled-in defaults when config file absent
• Document reload behavior (SIGHUP, file-watch, restart-only)

Currently only redbear-power follows this; 36 programs violate it.

---

7. DOCUMENTATION TEMPLATE (for all 47 recipes)

# redbear-<name>

> One-line purpose (≤80 chars).

**Status:** [PRODUCTION-READY | FEATURE-INCOMPLETE | EARLY-WIP | STUB-DATA]
**Maintainer:** @<handle>
**Last verified:** YYYY-MM-DD (commit `<hash>`)

## Purpose
What problem this program solves. What surface it provides (daemon / CLI / library / scheme / D-Bus / data). What consumes it.

## Build
```bash
# If wired to redbear-mini/redbear-full:
./local/scripts/build-redbear.sh redbear-mini

# If orphan/experimental (only builds when explicitly invoked):
COOKBOOK_TARGET=redbear-<name> ./local/scripts/build-redbear.sh --upstream

Runtime

Init service

Path: /usr/lib/init.d/<N>_<name>.service (if applicable). Enabled by: which config. Manual start: init-svc start <name>.

Configuration

Format: TOML. Path: ~/.config/redbear/<name>/config.toml (XDG) or /etc/redbear/<name>.toml (system). Env overrides: <PROG>_<KEY>=value. Reload: <SIGHUP | restart-only | file-watch>.

Logging

Destination: stderr (default) or /var/log/<name>.log (configurable). Level: controlled by RUST_LOG env var or --log-level flag. Debug flag: --verbose increases verbosity.

Interface

CLI (if any)

redbear-<name> [COMMON-OPTIONS] [PROGRAM-OPTIONS] [ARGS]

Common options (from redbear-cli):
  -h, --help              Print help
  -V, --version           Print version
  -v, --verbose           Increase verbosity
      --config <PATH>     Config file path
      --log-level <LEVEL> Log filter (error/warn/info/debug/trace)

Examples:
  $ redbear-<name> --verbose
  $ redbear-<name> --config /etc/redbear/<name>.toml

Scheme (if any)

Path: /scheme/<name>/. Handle kinds: <Root, Resource, ...>.

D-Bus (if any)

Bus: system | session. Well-known name: org.<domain>.<interface>. Object paths: /<object-path>.

Architecture

Brief module structure. Key types. Error types. Threading model.

Consumers

• redbear-<consumer-1>: uses <API>
• redbear-<consumer-2>: ...

Build dependencies

• redox-driver-sys
• linux-kpi
• ...

Runtime dependencies

• <scheme or D-Bus services that must be running>
• ...

Status notes

List known gaps, TODOs, hardware-validation status.

References

• local/docs/<plan>.md (e.g. CONSOLE-TO-KDE-DESKTOP-PLAN.md)
• Upstream: <upstream repo URL>
• Spec: <standard spec URL>

---

## 8. WORKSPACE CONSOLIDATION PATTERN

The 5 WORKSPACE-style programs (redbear-acmd, redbear-ecmd, redbear-ftdi, redbear-usbaudiod, redbear-usb-hotplugd) all need:

**Outer `Cargo.toml`:**

```toml
[workspace]
members = ["source"]
resolver = "3"

[workspace.package]
version = "0.3.1"
edition = "2024"
license = "MIT"
repository = "https://gitea.redbearos.org/RedBear-OS/redbear-recipes"
rust-version = "1.89"

[workspace.dependencies]
# Cross-cutting Redox crates (path-pinned to local forks per AGENTS.md)
redox_syscall = { path = "../../../sources/syscall" }
libredox = { path = "../../../sources/libredox" }
redox-scheme = { path = "../../../sources/redox-scheme" }

# USB class driver shared crates (from base fork)
xhcid = { path = "../../../sources/base/drivers/xhcid" }
common = { path = "../../../sources/base/drivers/common" }

# Common utility crates
log = "0.4"

[profile.release]
opt-level = 3
lto = "thin"

Inner source/Cargo.toml:

[package]
name = "redbear-acmd"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
description = "USB CDC ACM serial driver daemon"

[dependencies]
redox_syscall = { workspace = true }
libredox = { workspace = true }
redox-scheme = { workspace = true }
xhcid = { workspace = true }
common = { workspace = true }
log = { workspace = true }

[[bin]]
name = "redbear-acmd"
path = "src/main.rs"

Verification per program: cat Cargo.toml | grep "^\[workspace.package\]" returns 1 line; cat source/Cargo.toml | grep "version.workspace" returns 1 line.

---

9. ANOMALY RESOLUTION

9.1 redbear-netctl-console — Missing [package] name

File: local/recipes/system/redbear-netctl-console/recipe.toml

Action: Add to existing [package] section:

[package]
name = "redbear-netctl-console"
version = "0.3.1"

Verification: cat recipe.toml | grep -E "^name = \"redbear-netctl-console\"" returns 1 line; cargo cook redbear-netctl-console succeeds.

9.2 redox-drm — Same defect

File: local/recipes/gpu/redox-drm/recipe.toml

Action: Add name and version to [package] section.

Verification: Same as 9.1.

9.3 redbear-netstat — Vestigial nested duplicate

Anomaly: local/recipes/system/redbear-netstat/redbear-netstat/source/Cargo.toml duplicates source/Cargo.toml. The nested dir is NOT consumed by build (recipe points to source/).

Action: rm -rf local/recipes/system/redbear-netstat/redbear-netstat/

Verification: find local/recipes/system/redbear-netstat -name Cargo.toml shows only source/Cargo.toml.

9.4 redbear-tui-theme — Missing recipe.toml

Anomaly: local/recipes/tui/redbear-tui-theme/source/Cargo.toml exists, symlink exists at recipes/tui/redbear-tui-theme → ../../local/recipes/tui/redbear-tui-theme, but no recipe.toml means cookbook cannot cook it.

Action: Create local/recipes/tui/redbear-tui-theme/recipe.toml:

[package]
name = "redbear-tui-theme"
version = "0.3.1"

[source]
path = "source"

[build]
template = "cargo"

Verification: cat recipe.toml shows the above; cargo cook redbear-tui-theme succeeds.

9.5 redbear-ufw — Unreleased prototype in base fork

Anomaly: local/sources/base/redbear-ufw/ contains Cargo.toml + src/main.rs but no recipe.toml. The program is intentionally NOT built.

Action: Per AGENTS.md NEVER DELETE rule, do NOT delete the source. Either:

• Option A (recommended): Add local/recipes/system/redbear-ufw/recipe.toml to make it buildable, then wire to redbear-netctl-experimental.toml (it's a firewall).
• Option B: Add local/docs/REDBEAR-UFW-STATUS.md explicitly documenting: "Red Bear UFW is an unreleased prototype in local/sources/base/redbear-ufw/. Per AGENTS.md NEVER DELETE rule, the source is preserved. No recipe.toml exists; it is not part of any current build."

Recommendation: Option B — the prototype is in the base fork and may need to be re-integrated or removed when base is upgraded. Adding a recipe would bind it to current Redox sysroot which may not be appropriate.

Verification: Either recipe.toml exists and cook succeeds, OR local/docs/REDBEAR-UFW-STATUS.md exists with the explicit status text.

9.6 pam-redbear — Version drift

File: local/recipes/libs/pam-redbear/source/Cargo.toml

Action: Change version = "0.2.3" → version = "0.3.1".

Verification: grep version Cargo.toml shows 0.3.1; local/scripts/sync-versions.sh --check exits 0.

9.7 5 edition-2021 programs

Change edition = "2021" → edition = "2024" in:

1. local/recipes/system/redbear-accessibility/source/Cargo.toml
2. local/recipes/system/redbear-ime/source/Cargo.toml
3. local/recipes/system/redbear-keymapd/source/Cargo.toml
4. local/recipes/tui/redbear-tui-theme/source/Cargo.toml (Phase 1.4 prerequisite)
5. local/recipes/wayland/redbear-compositor/source/Cargo.toml

Verification: grep "^edition = \"2021\"" local/recipes -r returns 0 matches.

---

10. VERIFICATION CHECKLIST

Per-phase gates

Phase 1 (CRITICAL)

Check	Command	Expected
Build succeeds	./local/scripts/build-redbear.sh redbear-mini	Exit 0
No drift	./local/scripts/sync-versions.sh --check	Exit 0
Vestigial gone	find local/recipes/system/redbear-netstat -name Cargo.toml | wc -l	1
Both anomalies addressed	ls local/recipes/tui/redbear-tui-theme/recipe.toml local/docs/REDBEAR-UFW-STATUS.md 2>/dev/null | wc -l	≥1

Phase 2 (HIGH)

Check	Command	Expected
All programs edition=2024	grep -r "^edition = \"2021\"" local/recipes/ | wc -l	0
All programs have license	find local/recipes -path "*redbear-*/source/Cargo.toml" -exec grep -L "^license" {} \; | wc -l	0
All programs have repository	find local/recipes -path "*redbear-*/source/Cargo.toml" -exec grep -L "^repository" {} \; | wc -l	0
Logging migrated	find local/recipes -path "*redbear-*/source/src" -name "*.rs" -exec grep -l "println!" {} \; | wc -l	<10 (TUI-only allowed)
Error handling migrated	find local/recipes -path "*redbear-*/source/src" -name "*.rs" -exec grep -c "\.unwrap()" {} \; | awk '{s+=$1} END{print s}'	<500 (was 1042)
No panic! in daemons	grep -l "panic!" local/recipes/system/redbear-{sessiond,authd,greeter,polkit,udisks,upower}/source/src/main.rs | wc -l	0
tokio minimal	grep -l "features = \[\"full\"\]" local/recipes -r --include="Cargo.toml" | grep redbear- | wc -l	0

Phase 3 (MEDIUM)

Check	Command	Expected
All 5 WORKSPACE programs have [workspace.package]	for d in local/recipes/system/redbear-{acmd,ecmd,ftdi,usbaudiod,usb-hotplugd}; do grep -l "\[workspace.package\]" "$d/Cargo.toml"; done | wc -l	5
All 47 recipes wired or documented	for r in $(find local/recipes -maxdepth 3 -type d -name "redbear-*" | sort -u); do prog=$(basename $r); if ! grep -rq "$prog" config/ 2>/dev/null && [ ! -f "local/docs/REDBEAR-UFW-STATUS.md" ]; then echo "$prog"; fi; done | wc -l	0
Massive files split	wc -l local/recipes/system/redbear-info/source/src/main.rs local/recipes/wayland/redbear-compositor/source/src/main.rs local/recipes/system/redbear-netctl/source/src/main.rs	All <500
Shared CLI crate exists	test -f local/recipes/system/redbear-cli/source/Cargo.toml && echo OK	OK
Clap usage	find local/recipes -path "*redbear-*/source" -name "*.rs" -exec grep -l "use clap" {} \; | wc -l	≥28
--version works	./target/release/redbear-info --version 2>&1 | head -1	Print version

Phase 4 (LOW)

Check	Command	Expected
All 47 recipes have README	find local/recipes -path "*redbear-*/README.md" | wc -l	47
Operator runbooks	ls local/docs/operator-runbooks/ | wc -l	≥7
D-Bus interface docs	ls local/docs/dbus-interfaces/ | wc -l	≥6
Per-program AGENTS.md entries	grep -c "^## redbear-|^- redbear-" local/AGENTS.md	≥47
CI runs	.github/workflows/redbear-ci.yml exists; CI green on push	green
cargo fmt clean	for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml"); do cargo fmt --manifest-path "$f" -- --check; done | wc -l	0 failures
cargo clippy clean	for f in $(find local/recipes -path "*redbear-*/source/Cargo.toml"); do cargo clippy --manifest-path "$f" -- -D warnings; done | wc -l	0 failures

---

11. RISKS AND NEVER-DO LIST (per AGENTS.md)

NEVER DO (per AGENTS.md absolute rules)

1. NEVER DELETE any redbear-* package, config, service, or file — even if it seems unused, "too heavy", or "not needed". Per AGENTS.md § ABSOLUTE RULE — NEVER DELETE. Always keep and fix.
2. NEVER set any package to "ignore" because it seems unneeded. Per AGENTS.md § ABSOLUTE RULE.
3. NEVER comment out a package or service to "clean up". Per AGENTS.md § ABSOLUTE RULE.
4. NEVER remove build tools to reduce image size. Per AGENTS.md § ABSOLUTE RULE.
5. NEVER add stubs, workarounds, fake headers, sed hacks, or LD_PRELOAD tricks. Per AGENTS.md § STUB AND WORKAROUND POLICY.
6. NEVER use unwrap()/expect() in library/driver code. Per AGENTS.md § ANTI-PATTERNS.
7. NEVER modify kernel syscall ABI directly — use libredox or relibc.
8. NEVER use -rb suffix — must be +rb (Cargo build metadata). Per AGENTS.md § CONVENTIONS.
9. NEVER put drivers in kernel space — all drivers are userspace daemons.
10. NEVER hardcode /dev/ paths — use scheme paths.
11. NEVER remove patches to fix build failures — rebase them. Per AGENTS.md § PATCH-GOVERNANCE.
12. NEVER remove BINS entries to fix build failures — fix the source. Per AGENTS.md § PATCH-GOVERNANCE.
13. NEVER bypass the canonical build — always use ./local/scripts/build-redbear.sh. Per AGENTS.md § CANONICAL BUILD POLICY.
14. NEVER speculate about unread code — read before writing.
15. NEVER commit without explicit user request.
16. NEVER use background_cancel(all=true) — cancel individually.

Soft Guidelines (project preferences)

17. PREFER redox-scheme for scheme IPC over custom implementations.
18. PREFER zbus over raw dbus for D-Bus integration.
19. PREFER serde + TOML for config files.
20. PREFER dirs crate for XDG path resolution.
21. PREFER clap derive over hand-rolled CLI.
22. PREFER log + env_logger over println!.
23. PREFER thiserror for library errors, anyhow for binary errors.
24. PREFER workspace dependencies over per-member duplication.
25. PREFER module splits over single-file programs >500 lines.

Risk Assessment for this Plan

Risk	Likelihood	Mitigation
Edition 2024 breakage (lifetime capture changes)	LOW	Test per-program; the 5 programs are small
Logging migration breaks behavior	LOW	Test suite covers most programs; manual QA for visual output
Workspace migration breaks build	MEDIUM	Phase 1 prerequisite: vet [workspace.package] against existing fields
tokio feature downgrade breaks async	LOW	Test program-by-program; the signal handler is the breaking piece
Orphan wiring breaks init sequence	LOW	Each orphan gets explicit config-wiring test
Massive file split breaks compilation	MEDIUM	Mechanical refactor; preserve API surface; test after each move
CI workflow too slow	MEDIUM	Use cargo workspace at root to dedupe dep graph; cache target/
Damage to release archive (sources/redbear-0.1.0/)	LOW	This plan operates on local/recipes/, NOT the immutable archive
Loss of source-immutable durable state	LOW	All source-tree edits go through local/patches/ per AGENTS.md DURABILITY POLICY
Build-redbear.sh invocation breaks	LOW	Test at each phase gate using the canonical wrapper

Per-Phase Risk

• Phase 1 (additive only): Near-zero risk.
• Phase 2 (refactors error/log): Low risk; mechanical changes with test coverage.
• Phase 3 (structural changes): Medium risk; requires careful testing at each step.
• Phase 4 (docs/CI): Near-zero risk to runtime; docs-only.

---

SUMMARY

This plan delivers, in 8 weeks with ~37 person-days, the transformation of 47 redbear-* programs from "functionally broad but inconsistent" to a coherent, documented, idiomatic Rust ecosystem aligned with AGENTS.md policies.

Critical wins:

1. 5 build-blockers fixed (redbear-netctl-console name field, redox-drm name field, pam-redbear version, redbear-tui-theme recipe.toml, redbear-ufw status doc)
2. 1 vestigial duplicate deleted (redbear-netstat nested)
3. All 37 source Cargo.toml files gain license, repository, edition 2024
4. All 27 println-heavy programs migrate to log crate
5. 13 score-1 programs reduce unwrap/expect/panic surface by ~50%
6. 5 WORKSPACE programs gain [workspace.package] + [workspace.dependencies]
7. 13 orphans get explicit decision (wire / keep-orphan with status doc)
8. 3 massive single-file programs split into modules
9. All 47 recipes gain README.md
10. CI integration added

Estimated total effort: 37 person-days across 8 weeks.

Constraint compliance: No deletions (NEVER DELETE rule), no stubs (STUB POLICY), no language policy violations (Rust-only for new code), all changes use canonical build, all durability concerns addressed via patches.

First action: Run ./local/scripts/sync-versions.sh --check to confirm baseline state, then proceed to Phase 1.1 (redbear-netctl-console name field fix).