phoebus_os/docs/OBJECTIVES.md
Phoebus 20bfd82079 docs: add objectives, roadmap, status, architecture and agent guide
Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md.

STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
2026-09-20 02:07:44 -07:00

2.7 KiB

Objectives

Vision

Phoebus OS is a modern, stable, Gentoo-based workstation operating system that provides Gentoo-level flexibility, performance and control without requiring the user to act as a full-time Gentoo administrator.

It combines a mature modern architecture with a conservative update policy and real recovery:

Modern architecture + mature implementations
+ conservative updates + snapshots/rollback

Pillars

  • Gentoo + Portage remain the package foundation. Phoebus is an integration layer, not a parallel Linux ecosystem.
  • systemd is the init and service architecture; OpenRC is out of scope.
  • Wayland-first, with XWayland only for compatibility.
  • PipeWire + WirePlumber are the audio stack. PulseAudio is not the target.
  • UEFI/GPT-first. Legacy BIOS is not a v0.1 priority.
  • LUKS2 whole-root encryption with a passphrase (TPM2 later, never mandatory).
  • Btrfs with subvolumes, snapshots and (eventually) rollback.
  • Stability over novelty. Stable/LTS kernels, mature filesystems, no release candidates, no globally unmasked testing tree.
  • Pragmatic builds. Compile when it is cheap or genuinely beneficial; use signed Gentoo binaries when compilation is expensive and the benefit is negligible.
  • Friendly to proprietary software (drivers, firmware, codecs, Steam, browsers) where legally distributable. No moralising warnings; respect licences.
  • AI-first, never AI-dependent. The system is fully usable without an LLM.

The AI contract

The LLM is an interface, explainer, planner and reasoning assistant. It is not the source of truth, the root shell, or the privilege boundary.

user request -> LLM -> typed structured action -> policy engine
-> human-readable preview -> explicit approval -> authentication
-> privileged deterministic broker -> verification -> history

The model never receives the user's sudo password (authentication happens through sudo/polkit/PAM outside model context), and it has no code path to read private files: system access is not home-directory access.

Non-goals

  • A custom init system, package manager, audio stack or compositor.
  • A giant kernel fork or a large downstream patch set.
  • Bleeding-edge/experimental defaults.
  • Making the LLM required for installation or normal operation.
  • Rebuilding the world on a small release VPS.

Definition of a successful distribution

Phoebus installs a bootable, encrypted, systemd system in a disposable UEFI VM, boots with the installer media removed, unlocks LUKS, reaches a login and a functional Wayland desktop, and can be maintained without the user becoming a Gentoo expert. This is verified per docs/STATUS.md.