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

66 lines
2.7 KiB
Markdown

# 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`.