docs: require an AI at install; AI-first system, legacy fallback
Some checks are pending
ci / test (push) Waiting to run

Installing Phoebus now requires a connected model (remote provider or a
user-downloaded local model; none is shipped). The installed system is AI-first
and uses a connected model proactively. It is never required to boot, run or
recover: the deterministic CLI (sys, emerge, nix, flatpak) remains as a
break-glass fallback, and no model ever holds privilege.
This commit is contained in:
Phoebus 2026-09-20 14:33:19 -07:00
parent 9ae86d5234
commit 0c2a6bb9d6
2 changed files with 22 additions and 16 deletions

View file

@ -11,11 +11,12 @@ It is deliberately concrete: follow it rather than rediscovering the project.
Phoebus OS is a **modern, stable, Gentoo-based workstation operating system**: Phoebus OS is a **modern, stable, Gentoo-based workstation operating system**:
systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast
dwl-style desktop, Flatpak, and a built-in AI administration assistant. The AI dwl-style desktop, Flatpak, and a built-in AI administration assistant. The AI
assistant and Nix are **defining, always-present subsystems**: the assistant is assistant and Nix are **defining, always-present subsystems**: installing
built in and *model-optional* (the user may download a local model or configure Phoebus **requires a connected model** (a remote provider or a downloaded local
a remote provider; no model is shipped), and Nix is a second package lane model; none is shipped), the installed system is AI-first and uses a connected
shipped and updated through Portage. Installation requires the network; the model proactively, and Nix is a second package lane shipped and updated through
installed system must boot, run and recover without it. The Portage. Installation requires the network; the installed system must boot, run
and recover without it, with legacy commands as the fallback. The
LLM never holds privilege (see §2.4). LLM never holds privilege (see §2.4).
Fastest start: run `make context` (prints repository state, the roadmap's Fastest start: run `make context` (prints repository state, the roadmap's

View file

@ -33,11 +33,14 @@ Modern architecture + mature implementations
- **Friendly to proprietary software** (drivers, firmware, codecs, Steam, - **Friendly to proprietary software** (drivers, firmware, codecs, Steam,
browsers) where legally distributable. No moralising warnings; respect browsers) where legally distributable. No moralising warnings; respect
licences. licences.
- **AI-first, built in.** The assistant and Nix are defining, always-present - **AI-first, by design.** The assistant and Nix are defining, always-present
subsystems, not optional add-ons. The assistant is **model-optional**: Phoebus subsystems, not optional add-ons. **Installing Phoebus requires an AI**: the
ships no model, but the user can download a local one or configure a remote installer will not complete without a connected model (a remote provider, or a
provider. With no model it still explains, plans and applies validated, local model the user downloads; Phoebus ships none). The installed system is
deterministic changes. A Phoebus system must boot, run and recover offline. AI-first — the assistant is the primary interface, and while a model is
connected the system uses it proactively. Legacy commands (`sys`, `emerge`,
`nix`, `flatpak`) always remain so the system can be operated and repaired by
hand if the AI is unavailable; nothing bricks.
- **Nix as a second, built-in package lane.** Portage stays authoritative for - **Nix as a second, built-in package lane.** Portage stays authoritative for
the system (kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot, the system (kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot,
services); Nix provides developer tools, alternate versions and reproducible services); Nix provides developer tools, alternate versions and reproducible
@ -59,12 +62,14 @@ 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 through sudo/polkit/PAM outside model context), and it has no code path to
read private files: system access is not home-directory access. read private files: system access is not home-directory access.
Phoebus ships **no model**. The assistant is *model-optional*: the user may Phoebus ships **no model**: the user connects a remote provider
download a local model or configure a remote provider (DeepSeek/OpenAI), and a (DeepSeek/OpenAI) or downloads a local model, and a configured provider only
configured provider only ever receives approved, bounded system facts. With no ever receives approved, bounded system facts. **A connected model is required
model, the assistant still offers offline explainers, planning and validated to install**, and it is the primary way to operate the system: when one is
deterministic actions, and the CLI is always available. Installation requires present, the assistant is used proactively. It is never required to boot, run
the network (stage3, Portage, packages); the installed system must not. or recover — the deterministic command line (`sys`, `emerge`, `nix`, `flatpak`)
is always available as a break-glass fallback. Installation requires the network
(stage3, Portage, packages); the installed system must not.
The assistant is the **preferred front-end, never a gate**. The deterministic 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 command line is always available with no model, and a user who wants the