RedBear-OS/local/docs/REDBEAR-FIRST-CLASS-CITIZEN-POLICY.md

Red Bear First-Class Citizen Policy (added 2026-07-28; corrected 2026-07-28)

Rule

Every redbear-* recipe under local/recipes/*/redbear-*/ is a first-class citizen of Red Bear OS. No redbear-* recipe may be left orphaned by the build.

There are exactly 48 redbear-* recipes as of 2026-07-28 (verified by enumeration against local/recipes/). Every redbear-* recipe MUST be reachable from at least one active Red Bear OS build config. Library-only recipes (zero [[bin]], produces only a .rlib) are first-class citizens too — they are wired into a config so the cookbook builds and stages the .rlib. Data-only recipes (firmware subsets, D-Bus .service files, TOML policy files) are also first-class citizens — they ship files into the stage and are consumed by other components.

Wiring target by purpose (corrected 2026-07-28)

Red Bear OS has TWO compile targets that differ by intended use:

Target	Purpose	Build surface
redbear-mini	Text-only console / recovery / install	Networking, USB, CPU/memory, console utilities, TUI daemons — no graphics, no GUI, no compositor
redbear-full	Desktop / graphics / KDE Plasma	Everything in mini + Wayland compositor + Qt6 + KF6 + Mesa + DRM drivers + firmware + greeter

Wiring rule (per program classification)

• Text-only binary (CPU/memory daemons, USB class drivers, networking tools, console utilities, TUI daemons): wire into config/redbear-mini.toml [packages]. Examples: redbear-wifictl, redbear-btctl, redbear-power (ratatui TUI), redbear-info, redbear-hwutils, redbear-acmd, redbear-ecmd, redbear-ftdi, redbear-usbaudiod, redbear-usb-hotplugd.

• Graphics / desktop binary (Wayland compositor, graphical login, desktop session launcher, D-Bus desktop services, KDE daemons, full firmware bundle): wire into config/redbear-full.toml [packages]. Examples: redbear-compositor (Wayland), redbear-greeter (SDDM/Qt login), redbear-authd (PAM for SDDM), redbear-session-launch, redbear-statusnotifierwatcher (KDE tray), redbear-accessibility (desktop input filter), redbear-ime, redbear-keymapd, redbear-meta (desktop meta), redbear-firmware (2 GB firmware bundle), redbear-firmware-{amdgpu,bluetooth,intel,iwlwifi} (subsets).

• Library-only (no [[bin]], consumed via Cargo path dep): wire into the same target as its primary consumer(s). If consumers are in mini, the library is in mini. If consumers are in full, the library is in full. Examples: redbear-tui-theme (consumed by redbear-power, cub, tlc — all in mini → wire into mini); redbear-hid-core, redbear-login-protocol, redbear-passwd (consumed by desktop daemons — wire into full).

• Hardware peripheral driver (Wi-Fi, Bluetooth): wire into the experimental config that enables the peripheral. NOT in mini (peripheral not part of text console baseline). Examples: redbear-iwlwifi → redbear-wifi-experimental.toml; redbear-btusb, redbear-btctl → redbear-bluetooth-experimental.toml. Note: full inherits these via the experimental config's parent chain.

The config/redbear-full.toml includes ["redbear-mini.toml"] and additionally includes ["redbear-bluetooth-experimental.toml"] and ["redbear-wifi-experimental.toml"], so the full ISO transitively builds every redbear-* program.

Rationale

The operator explicitly created each redbear-* recipe for a documented purpose. Per the local/AGENTS.md § ABSOLUTE RULE — NEVER DELETE:

"If an agent decides something is 'not necessary', 'not required for boot', 'too heavy', or 'not needed' — that decision is WRONG. Always keep and fix."

The corollary: leaving a redbear-* recipe unreachable from the build is structurally equivalent to ignoring it — its source still lives in the tree, but its code, config files, firmware, or services never ship to a Red Bear OS image. The next operator who runs a build sees nothing from that recipe and reasonably concludes it is dead. This is exactly the failure mode AGENTS.md warns against.

Therefore: every redbear-* recipe MUST be reachable from at least one active Red Bear OS build config (redbear-mini.toml, redbear-full.toml, or an experimental *-experimental.toml that full inherits).

Authoritative source of truth

local/AGENTS.md is the canonical home for this rule. This doc is the change-log entry for the rule's introduction. Any future addition of a new redbear-* recipe MUST be accompanied by a config/redbear-*.toml edit that wires the new recipe into the appropriate [packages] section in the same commit (or in a tightly coupled follow-up commit). Code review MUST verify this wiring — a recipe without wiring is a CI failure under the new policy.

Recipes that are NOT first-class citizens

This policy applies only to redbear-* recipes under local/recipes/*/. The following non-redbear-* artifacts are out of scope:

• Upstream Redox recipes under recipes/*/source/ (managed by upstream)
• Cat 2 fork subprojects under local/sources/<component>/ (kernel, relibc, base, …)
• Cat 1 internal projects without a redbear- prefix:
  • local/recipes/system/cub/
  • local/recipes/system/evdevd/
  • local/recipes/system/udev-shim/
  • local/recipes/system/driver-manager/
  • local/recipes/system/driver-params/
  • local/recipes/system/iommu/
  • local/recipes/system/firmware-loader/
  • local/recipes/system/cpufreqd/
  • local/recipes/system/thermald/
  • local/recipes/system/hwrngd/
  • local/recipes/system/seatd/
  • local/recipes/gpu/redox-drm/
  • local/recipes/gpu/amdgpu/
  • local/recipes/gpu/linux-kpi/
  • local/recipes/drivers/redox-driver-sys/
  • local/recipes/drivers/redox-driver-core/
  • local/recipes/drivers/redox-driver-acpi/
  • local/recipes/drivers/redox-driver-pci/
  • local/recipes/drivers/linux-kpi/
  • local/recipes/tui/tlc/
  • local/recipes/tui/mc/
  • local/recipes/libs/pam-redbear/
  • local/recipes/libs/zbus/

These are governed by their own wiring rules (some are Cat 2 forks, some are build deps of redbear-* programs). Adding a redbear- prefix is the canonical way to express "first-class citizen of the OS image".

Worked example (corrected 2026-07-28)

The original architecture had a clean split:

• mini = text-only (24 redbear-* programs)
• full = mini + 11 graphics-only programs

A 2026-07-28 first-class-citizen pass initially added all 48 redbear-* programs to mini without regard to whether they were graphics-related. The operator correction was: "MINI target includes just packages which are not related to graphics. FULL must contain all text+graphial packages." The correction restored the original split with all 48 programs reachable from full (via inheritance + explicit full-only entries).

Complete inventory (48 recipes, verified 2026-07-28)

All 48 redbear-* recipes are reachable from config/redbear-full.toml (directly + via inheritance from mini + via experimental config inclusions):

redbear-accessibility       redbear-ecmd                  redbear-input-headers
redbear-acmd                redbear-firmware              redbear-iwlwifi
redbear-authd               redbear-firmware-amdgpu       redbear-keymapd
redbear-btctl               redbear-firmware-bluetooth    redbear-login-protocol
redbear-btusb               redbear-firmware-intel        redbear-meta
redbear-compositor          redbear-firmware-iwlwifi      redbear-mtr
redbear-dbus-services       redbear-ftdi                  redbear-netctl
redbear-dnsd                redbear-greeter               redbear-netctl-console
redbear-driver-policy       redbear-hid-core              redbear-netstat
redbear-nmap                redbear-sessiond              redbear-traceroute
redbear-notifications       redbear-session-launch        redbear-tui-theme
redbear-passwd              redbear-statusnotifierwatcher redbear-udisks
redbear-polkit              redbear-release               redbear-ufw
redbear-power               redbear-hwutils               redbear-upower
redbear-quirks              redbear-ime                   redbear-usbaudiod
redbear-info                redbear-usb-hotplugd          redbear-wifictl

Verification

The policy is verifiable by:

# Every redbear-* recipe directory under local/recipes/ must be reachable from
# at least one config (full transitively includes mini + experimental).
for r in $(find local/recipes -maxdepth 3 -type d -name "redbear-*" | sort -u); do
  prog=$(basename "$r")
  if ! grep -rq "$prog" config/redbear-full.toml 2>/dev/null && \
     ! grep -rq "$prog" config/redbear-mini.toml 2>/dev/null && \
     ! grep -rq "$prog" config/redbear-*-experimental.toml 2>/dev/null; then
    echo "ORPHAN: $prog"
  fi
done

Zero ORPHAN: lines should print. Any operator running this script immediately sees policy violations. The policy is enforced by the local/scripts/sync-versions.sh preflight gate plus operator review.

Cross-references

• local/AGENTS.md § ABSOLUTE RULE — NEVER DELETE — preservation rule
• local/AGENTS.md § STUB AND WORKAROUND POLICY — ZERO TOLERANCE — implementation quality
• local/AGENTS.md § BRANCH AND SUBMODULE POLICY — git workflow
• local/docs/REDBEAR-ULW-ASSESSMENT-PLAN.md — the systematic plan that produced this rule
• local/docs/REDBEAR-UFW-STATUS.md — the redbear-ufw status (text-only prototype, wired into mini)
• local/docs/ORPHAN-STATUS.md — library-only crate classification
• local/docs/FIRMWARE-SUBSETS-DECISION.md — firmware subset recipes (graphics-only, in full)