The AI assistant stays a defining, always-present subsystem, but Phoebus ships no model. The user may download a local model or configure a remote provider; with no model the assistant still explains, plans and applies deterministic changes and the CLI remains available. Installation requires the network; the installed system must boot, run and recover offline.
7.6 KiB
AGENTS.md — operating instructions for AI sessions
This file is the entry point for any AI/LLM session (or human) working on Phoebus OS. Read this file first, then follow the reading order below. It is deliberately concrete: follow it rather than rediscovering the project.
1. What Phoebus is
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 a built-in AI administration assistant. The AI assistant and Nix are defining, always-present subsystems: the assistant is built in and model-optional (the user may download a local model or configure a remote provider; no model is shipped), 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).
Then read, in order:
docs/OBJECTIVES.md— vision, philosophy, non-goals.docs/ROADMAP.md— priorities and what is done/next/later.docs/HANDOFF.md— where the last session stopped and the next actions.docs/STATUS.md— what is implemented vs unit-tested vs VM-verified.docs/ARCHITECTURE.md— components and how they fit together.docs/adr/— why significant decisions were made (BLS, profile, ...).docs/DEVELOPMENT.md— host setup, build, test, VM workflow.docs/CONTRIBUTING.md— code standards and definition of done.docs/GIT-WORKFLOW.md— how changes are committed and published.git log --oneline -30and the top ofdocs/CHANGELOG.md— recent history.
2. Non-negotiable rules
These are not preferences. Do not violate them, even to make a test pass.
- Never touch a physical host disk. All destructive testing happens on a disposable qcow2 image. If a test needs a real disk, stop and say so.
- Never send secrets to an LLM. No passwords, passphrases, API keys or tokens in prompts, logs, config files, command lines or commits.
- Never log secrets. Register every secret with the redactor; pass passphrases only over stdin.
- Never give the LLM a shell or root. AI can only emit typed, validated actions; a privileged, human-approved broker executes them.
- Never globally enable Gentoo
~amd64. Scopedaccept_keywordsfor hardware/desktop enablement are allowed and must be explicit. - Never disable package signature verification to make an install pass.
- Never weaken LUKS2, Btrfs, systemd, UEFI or disk protection for convenience. Fix the real problem.
- Stability beats novelty. No release-candidate kernels, no experimental filesystem defaults, no unstable snapshots. Prefer stable/LTS and mature implementations.
- Do not regress the proven boot path. See
docs/STATUS.mdfor the exact configuration that is known to boot. - Do not commit the ISO, build output, session transcripts or secrets.
.gitignorehandles this; do not override it.
3. Repository map
AGENTS.md this file (read first)
README.md short project overview
docs/ objectives, roadmap, status, architecture, process
installer/tests/vm/ disposable UEFI VM harness (static Rust binary)
installer-rs/ production Rust installer
crates/phoebus-core types, validation, plan, policy, target-root safety
crates/phoebus-executor command layer, storage, Portage, boot, snapshots, ...
crates/phoebus-ai typed proposals + enforced privacy boundary
crates/phoebus-tui ratatui TUI
crates/phoebus-installer CLI, `sys`, `phoebus-release`, orchestration
scripts/ git/dev tooling (hooks, publish, agent-commit)
.githooks/ committed git hooks
Authoritative design records:
docs/FINDINGS.md— what the reference live environment contains.docs/VM-BOOT-VERIFICATION.md— the proven VM install/boot path.docs/BASH-MIGRATION.md— the evidence-gated retirement of the Bash installer.installer-rs/README.md— Rust workspace details.
4. How to work (loop)
- Read this file and the reading order in §1; run
make context. - Run
make doctorbefore VM work, and inspectdocs/ROADMAP.mdfor the highest-priority unfinished item. - Inspect
git log --oneline -20,docs/CHANGELOG.mdanddocs/HANDOFF.md. - Inspect the relevant code and existing tests before editing.
- Implement the smallest correct change. Prefer upstream tools over new code.
- Run the quality gates and relevant tests (§5).
- If you did destructive work, run it in the disposable VM (§6) and record the evidence.
- Update
docs/CHANGELOG.md,docs/STATUS.mdanddocs/HANDOFF.mdif behavior/verification changed. - Commit with a conventional commit message (see
docs/GIT-WORKFLOW.md) and push (scripts/publish.shormake publish).
Do the actual work; do not stop at a design document. Do not ask for guidance when the next engineering step is clear.
5. Build and test gates
Rust installer (production):
cd installer-rs
cargo fmt --all -- --check
cargo clippy --workspace --all-targets
cargo test --workspace
cargo build --release -p phoebus-installer
Static binary for the live installer environment:
cd installer-rs
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
The Rust suite must pass before a commit. The pre-commit hook runs a secret scan
and an optional Rust suite; see docs/GIT-WORKFLOW.md.
6. Disposable VM testing
installer/tests/vm/ contains a repeatable harness:
serial-driver.py— host-side pexpect driver (installandbootmodes).install.sh— guest-side non-interactive install.test.conf.example— configuration.run-vm.sh— interactive QEMU launcher.
Never point DISK at a /dev/* device. See docs/DEVELOPMENT.md for the full
procedure and required host packages.
7. Code conventions (short form)
Rust: no unsafe (if truly needed, keep it tiny, document invariants, test
it); no unwrap/expect in privileged paths; structured thiserror errors;
never sh -c; every command goes through phoebus-executor::Exec; every
target write goes through TargetRoot; destructive functions require a
DestructiveAuthorization token.
Bash (developer tooling only): shellcheck clean; no local a="$1" b="$a"
(dynamic scoping bug class); no writes to host paths without the target root;
quote everything.
Use just-style readability, not cleverness. Fewer lines is not the goal;
correctness, testability and observability are.
8. Where history lives
git log— the authoritative change history.docs/CHANGELOG.md— curated, human-readable milestones.docs/VM-BOOT-VERIFICATION.md— boot evidence per iteration.docs/STATUS.md— current implementation/verification matrix.
When you finish work, update the changelog and status, then commit. A future session should be able to reconstruct what happened from these alone.
9. Known limitations (keep this current)
See docs/STATUS.md for the full list. Highlights: UKI is deferred (BLS is
used); Btrfs rollback is not implemented; the AI OS sandbox is designed but not
enforced; Full Disk Encryption boot, desktop and Flatpak are verified only in
a disposable VM (graphical session via the headless wlroots backend, no
physical seat); NVIDIA is not verified.