diff --git a/AGENTS.md b/AGENTS.md index 4b6c4c3..844c89f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,9 +10,12 @@ It is deliberately concrete: follow it rather than rediscovering the project. Phoebus OS is a **modern, stable, Gentoo-based workstation operating system**: systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast -dwl-style desktop, Flatpak, and an optional AI administration assistant. It is -**AI-first but never AI-dependent**: the system must be fully usable without an -LLM, and the LLM never holds privilege. +dwl-style desktop, Flatpak, and a built-in AI administration assistant. The AI +assistant and Nix are **defining, always-present subsystems**: the assistant +ships with a **local model** so it works offline and in recovery, 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. The +LLM never holds privilege (see §2.4). Fastest start: run `make context` (prints repository state, the roadmap's immediate next steps, the rolling handoff and open markers). diff --git a/docs/OBJECTIVES.md b/docs/OBJECTIVES.md index 906c1b0..381fa06 100644 --- a/docs/OBJECTIVES.md +++ b/docs/OBJECTIVES.md @@ -33,7 +33,15 @@ Modern architecture + mature implementations - **Friendly to proprietary software** (drivers, firmware, codecs, Steam, browsers) where legally distributable. No moralising warnings; respect licences. -- **AI-first, never AI-dependent.** The system is fully usable without an LLM. +- **AI-first, built in.** The assistant and Nix are defining, always-present + subsystems, not optional add-ons. The assistant ships with a **local model** + so it works offline; remote providers are an optional upgrade. A Phoebus + system must boot, run and recover without the network. +- **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 @@ -50,12 +58,34 @@ 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. +The default brain is a **local model**, so the assistant works without a network +and inside recovery. Remote providers (DeepSeek/OpenAI) are optional and only +ever receive approved, bounded system facts. 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 the LLM required for installation or normal operation. +- 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 diff --git a/docs/adr/0006-package-lanes.md b/docs/adr/0006-package-lanes.md new file mode 100644 index 0000000..601b8c2 --- /dev/null +++ b/docs/adr/0006-package-lanes.md @@ -0,0 +1,136 @@ +# ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in) + +- **Status:** Proposed +- **Date:** 2026-09-20 + +## Context + +Phoebus is built on Gentoo/Portage and must stay a thin layer over it. There is +a real need for **binary options for non-core software** (developer tooling, +alternate versions, packages awkward or slow to compile) without (a) +maintaining a private Gentoo binhost, or (b) letting a second package manager +claim ownership of the system. + +The decision here is that **Nix is part of the distro by default** — the same +way the AI assistant is: always present and ready, but never authoritative and +never required. A Phoebus system must remain completely usable with Portage +alone; a user who ignores Nix must not notice it. + +Options considered: a second distro via Distrobox/pacman, Nix, Homebrew, native +`-bin` ebuilds, a third-party Gentoo binhost, and Flatpak. + +Relevant facts established: + +- The official Gentoo binhost is a single non-systemd (hardened) baseline, so + systemd/desktop packages mostly compile from source. We will not maintain a + private binhost. +- `nix` is not in the Gentoo main tree, so Phoebus ships and manages it itself. +- Nix is strong for reproducible, multi-version developer environments and poor + for GPU/Wayland desktop apps on a non-NixOS host (`nixGL`, Electron sandbox). +- Flatpak is already designed into Phoebus and is the right fit for sandboxed + GUI apps. + +## Decision + +Adopt **three package lanes**, all present on a default install, with strict +ownership: + +| Lane | Owns | Availability | +| ---- | ---- | ------------ | +| **Portage** (authoritative) | kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot stack, system services, compilers/toolchain | always | +| **Flatpak** | graphical desktop apps (Chromium, Firefox, Spotify, Electron), sandboxed | always | +| **Nix** | developer tools, alternate versions, reproducible per-project environments, packages inconvenient in Portage | always, user-level use | + +Portage's native **`-bin` ebuilds** (`google-chrome`, `steam-launcher`, +`discord-bin`, ...) remain the vendor-blob lane; no new tool is introduced for +them. + +Nix is **baked in**, but "baked in" describes availability, not authority: + +- the Nix toolchain and daemon are shipped and configured by the installer; +- Portage still installs and updates Nix itself, so the daemon is system-managed + rather than a stray `curl | sh` artifact; +- no core component, service, library or application depends on Nix being used; +- ignoring Nix has no effect on the system. + +## How Nix is baked in without surrendering ownership + +1. **Ship it as a Portage package, not the upstream installer.** Provide a + Phoebus overlay ebuild for Nix (e.g. `sys-apps/nix`) that installs the + toolchain, creates the store and `nixbld` build users, and installs a + `nix-daemon.service` unit. The installer adds the overlay and emerges it as + part of the base/desktop package set. +2. **Multi-user, system-managed.** Because it is a real package, a root + `nix-daemon` is acceptable: it is enabled like any other service, updated + through `emerge`, and audited with the rest of the system. +3. **Pinned and verified.** The ebuild pins the Nix version and verifies the + upstream release tarball by SHA-256. The upstream `curl | sh` installer is + never used. nixpkgs itself is pinned per environment (flake lock / channel + revision), not "latest". +4. **No NixOS model.** No `configuration.nix`, no system profiles, no + Nix-managed services. Nix manages user environments only. + +## Rules + +1. **Portage is the only authority over the running system.** Nix and Flatpak + never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or + boot. +2. **Nix is user-level in effect.** It provides developer tools and project + environments, never system components. +3. **Never required.** The system is fully functional with Portage alone; the + base image and all services work if Nix is unused or removed. +4. **GUI apps go to Flatpak, not Nix.** +5. **No arbitrary remote evaluation by default.** Nix commands run by the + assistant are bounded (no arbitrary flakes or URLs), so eval-time fetching + is not an AI-reachable supply-chain surface. + +## AI integration + +The differentiated use is a typed, assistant-driven action: + +``` +CreateDevEnvironment { name, packages[], versions[] } +``` + +- executed unprivileged through `Exec` (no shell, no root for the user action); +- inputs validated against a bounded set; +- never mutates the base system; +- the deterministic broker reports which lane satisfied a request. + +A future `sys` chooser must prefer deterministically: system/compiler/Mesa/ +drivers → Portage only; GUI → Flatpak; per-project/dev → Nix. + +## Explicit non-goals + +- A universal `pkg install` meta-manager that silently picks a source (deferred; + provenance and support burden). +- NixOS-style system configuration. +- A second full distro (Distrobox, pacman) — rejected: a second rootfs to + maintain with weaker isolation than Flatpak. +- A third-party Gentoo binhost — rejected: trust, signature and availability. +- Homebrew — rejected: not packaged for Gentoo, FHS prefix shadowing, and it + adds nothing over Nix for the developer lane. + +## Consequences and risks + +- Every install now carries the Nix toolchain, a root daemon, and a growing + `/nix` store; image and disk usage increase. +- There are now two trust/update pipelines (`gentoo` + `nixpkgs`) on every + system, each with its own CVEs and update cadence. The daemon being + Portage-managed keeps ownership clear, but the risk is real and must be + documented to users. +- GUI/GPU stays Flatpak's job, consistent with this session's finding that Nix + is a poor fit there. +- The `nix-daemon` runs as root; it is a privileged component and must be + treated as one (service hardening, update tracking). + +## Next steps + +1. Finish Flatpak integration: `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends), + a documented app-install path, desktop integration. +2. Author the Phoebus overlay `sys-apps/nix` ebuild (+ `nix-daemon.service`), + install it from the installer, and verify in the disposable VM that a Nix + dev environment works and the base system still boots without using it. +3. Add the `CreateDevEnvironment` typed action with a bounded input set and + tests. +4. Only then consider a thin `sys`-level source chooser (not a general `pkg`).