phoebus_os/docs/OBJECTIVES.md
Phoebus 9ae86d5234
Some checks are pending
ci / test (push) Waiting to run
docs: ship no model; make the assistant model-optional
The AI assistant stays a defining, always-present subsystem, but Phoebus
ships no model. The user may download a local model or configure a remote
provider; with no model the assistant still explains, plans and applies
deterministic changes and the CLI remains available. Installation requires the
network; the installed system must boot, run and recover offline.
2026-09-20 14:29:59 -07:00

99 lines
4.4 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, built in.** The assistant and Nix are defining, always-present
subsystems, not optional add-ons. The assistant is **model-optional**: Phoebus
ships no model, but the user can download a local one or configure a remote
provider. With no model it still explains, plans and applies validated,
deterministic changes. A Phoebus system must boot, run and recover offline.
- **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.
Phoebus ships **no model**. The assistant is *model-optional*: the user may
download a local model or configure a remote provider (DeepSeek/OpenAI), and a
configured provider only ever receives approved, bounded system facts. With no
model, the assistant still offers offline explainers, planning and validated
deterministic actions, and the CLI is always available. 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`.