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 proactively, and Nix is a second package lane shipped and updated through
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).
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
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
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.
connected the system uses it proactively. There is **one control plane**: the
typed actions the assistant emits are the same ones the Phoebus CLI (`sys`)
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
the system (kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot,
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
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
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.
or recover — the **Phoebus deterministic CLI** (`sys`) runs the same typed
actions the assistant emits, with no model, as an explicit non-AI ("legacy")
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
command line is always available with no model, and a user who wants the