From d36b2fe5fe0df2433ad0b3d34fa66056f563146e Mon Sep 17 00:00:00 2001 From: Phoebus Date: Sun, 20 Sep 2026 14:35:05 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20one=20control=20plane=20=E2=80=94=20sys?= =?UTF-8?q?=20typed=20actions,=20not=20raw=20Portage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- AGENTS.md | 3 ++- docs/OBJECTIVES.md | 16 ++++++++++------ 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 45541e4..3d061e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/docs/OBJECTIVES.md b/docs/OBJECTIVES.md index ba0d801..46e5efa 100644 --- a/docs/OBJECTIVES.md +++ b/docs/OBJECTIVES.md @@ -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