docs: one control plane — sys typed actions, not raw Portage
Some checks are pending
ci / test (push) Waiting to run

The no-model fallback is the Phoebus deterministic CLI (sys) running the same
typed actions the assistant emits, exposed as an explicit non-AI (legacy) mode.
Raw emerge/nix/flatpak remain a last resort rather than the intended front-end.
This commit is contained in:
Phoebus 2026-09-20 14:35:05 -07:00
parent 0c2a6bb9d6
commit d36b2fe5fe
2 changed files with 12 additions and 7 deletions

View file

@ -16,7 +16,8 @@ Phoebus **requires a connected model** (a remote provider or a downloaded local
model; none is shipped), the installed system is AI-first and uses a connected model; none is shipped), the installed system is AI-first and uses a connected
model proactively, and Nix is a second package lane shipped and updated through model proactively, and Nix is a second package lane shipped and updated through
Portage. Installation requires the network; the installed system must boot, run Portage. Installation requires the network; the installed system must boot, run
and recover without it, with legacy commands as the fallback. The and recover without it, with the Phoebus deterministic CLI (`sys`) — the same
typed actions the assistant uses — as the no-model 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

@ -38,9 +38,11 @@ Modern architecture + mature implementations
installer will not complete without a connected model (a remote provider, or a installer will not complete without a connected model (a remote provider, or a
local model the user downloads; Phoebus ships none). The installed system is local model the user downloads; Phoebus ships none). The installed system is
AI-first — the assistant is the primary interface, and while a model is AI-first — the assistant is the primary interface, and while a model is
connected the system uses it proactively. Legacy commands (`sys`, `emerge`, connected the system uses it proactively. There is **one control plane**: the
`nix`, `flatpak`) always remain so the system can be operated and repaired by typed actions the assistant emits are the same ones the Phoebus CLI (`sys`)
hand if the AI is unavailable; nothing bricks. executes. That CLI — not raw Portage — always works without a model, 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
@ -67,9 +69,11 @@ Phoebus ships **no model**: the user connects a remote provider
ever receives approved, bounded system facts. **A connected model is required ever receives approved, bounded system facts. **A connected model is required
to install**, and it is the primary way to operate the system: when one is to install**, and it is the primary way to operate the system: when one is
present, the assistant is used proactively. It is never required to boot, run present, the assistant is used proactively. It is never required to boot, run
or recover — the deterministic command line (`sys`, `emerge`, `nix`, `flatpak`) or recover — the **Phoebus deterministic CLI** (`sys`) runs the same typed
is always available as a break-glass fallback. Installation requires the network actions the assistant emits, with no model, as an explicit non-AI ("legacy")
(stage3, Portage, packages); the installed system must not. mode. Raw `emerge`, `nix` and `flatpak` remain but are a last resort, not the
intended front-end. 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