phoebus_os/AGENTS.md
Phoebus 20bfd82079 docs: add objectives, roadmap, status, architecture and agent guide
Adds the documentation a new session needs: AGENTS.md (read-first contract), docs/OBJECTIVES.md, ROADMAP.md, STATUS.md, ARCHITECTURE.md, DEVELOPMENT.md, CONTRIBUTING.md, GIT-WORKFLOW.md and CHANGELOG.md.

STATUS.md records an honest implemented/unit-tested/VM-verified matrix and known limitations.
2026-09-20 02:07:44 -07:00

7.4 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 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.

Read next, in order:

  1. docs/OBJECTIVES.md — vision, philosophy, non-goals.
  2. docs/ROADMAP.md — priorities and what is done/next/later.
  3. docs/STATUS.md — what is implemented vs unit-tested vs VM-verified.
  4. docs/ARCHITECTURE.md — components and how they fit together.
  5. docs/DEVELOPMENT.md — host setup, build, test, VM workflow.
  6. docs/CONTRIBUTING.md — code standards and definition of done.
  7. docs/GIT-WORKFLOW.md — how changes are committed and published.
  8. git log --oneline -30 and the top of docs/CHANGELOG.md — recent history.

2. Non-negotiable rules

These are not preferences. Do not violate them, even to make a test pass.

  1. 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.
  2. Never send secrets to an LLM. No passwords, passphrases, API keys or tokens in prompts, logs, config files, command lines or commits.
  3. Never log secrets. Register every secret with the redactor; pass passphrases only over stdin.
  4. Never give the LLM a shell or root. AI can only emit typed, validated actions; a privileged, human-approved broker executes them.
  5. Never globally enable Gentoo ~amd64. Scoped accept_keywords for hardware/desktop enablement are allowed and must be explicit.
  6. Never disable package signature verification to make an install pass.
  7. Never weaken LUKS2, Btrfs, systemd, UEFI or disk protection for convenience. Fix the real problem.
  8. Stability beats novelty. No release-candidate kernels, no experimental filesystem defaults, no unstable snapshots. Prefer stable/LTS and mature implementations.
  9. Do not regress the proven boot path. See docs/STATUS.md for the exact configuration that is known to boot.
  10. Do not commit the ISO, build output, session transcripts or secrets. .gitignore handles 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/                proven Bash installer (reference / fallback)
  bin/ai-installer        entry point
  lib/                    deterministic backend modules
  tui/                    dialog/whiptail UI
  config/                 defaults, example config, OpenCode manifest
  tests/                  unit suite + tests/vm/ disposable-VM harness
  doc/                    environment findings and VM boot verification
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:

  • installer/doc/FINDINGS.md — what the reference live environment contains.
  • installer/doc/VM-BOOT-VERIFICATION.md — the proven VM install/boot path.
  • installer-rs/README.md — Rust workspace details.

4. How to work (loop)

  1. Read this file and the reading order in §1.
  2. Inspect docs/ROADMAP.md for the highest-priority unfinished item.
  3. Inspect git log --oneline -20 and docs/CHANGELOG.md for context.
  4. Inspect the relevant code and existing tests before editing.
  5. Implement the smallest correct change. Prefer upstream tools over new code.
  6. Run the quality gates and relevant tests (§5).
  7. If you did destructive work, run it in the disposable VM (§6) and record the evidence.
  8. Update docs/CHANGELOG.md and docs/STATUS.md if behavior/verification changed.
  9. Commit with a conventional commit message (see docs/GIT-WORKFLOW.md) and push when the user's remote is configured.

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

Bash installer (reference):

installer/tests/run_tests.sh          # unit/regression assertions
shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh

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

Both test suites must pass before a commit. The pre-commit hook runs the fast Bash suite and a secret scan; see docs/GIT-WORKFLOW.md.


6. Disposable VM testing

installer/tests/vm/ contains a repeatable harness:

  • serial-driver.py — host-side pexpect driver (install and boot modes).
  • 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 (while it exists): 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.
  • installer/doc/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.