# 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, built in.** The assistant and Nix are defining, always-present subsystems, not optional add-ons. The assistant ships with a **local model** so it works offline; remote providers are an optional upgrade. A Phoebus system must boot, run and recover without the network. - **Nix as a second, built-in package lane.** Portage stays authoritative for the system (kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot, services); Nix provides developer tools, alternate versions and reproducible per-project environments. Nix is shipped and updated **through Portage**, never as a `curl | sh` artifact. ## 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. The default brain is a **local model**, so the assistant works without a network and inside recovery. Remote providers (DeepSeek/OpenAI) are optional and only ever receive approved, bounded system facts. Installation requires the network (stage3, Portage, packages); the installed system must not. The assistant is the **preferred front-end, never a gate**. The deterministic command line is always available with no model, and a user who wants the old-fashioned way can always use it directly: ``` sys install vim # typed broker, offline parser, no LLM sys enable sshd sys history emerge www-client/firefox # Portage (the Gentoo `apt install` equivalent) nix shell nixpkgs#nodejs # Nix development environments flatpak install flathub org.chromium.Chromium ``` Whatever the assistant can do, a human can do without it; the assistant only makes it easier. ## 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 a **remote** LLM/provider required to boot, run or recover. The local assistant must work offline, and deterministic tools remain available. - 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`.