Some checks are pending
ci / test (push) Waiting to run
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.
187 lines
7.6 KiB
Markdown
187 lines
7.6 KiB
Markdown
# 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:
|
|
|
|
1. `docs/OBJECTIVES.md` — vision, philosophy, non-goals.
|
|
2. `docs/ROADMAP.md` — priorities and what is done/next/later.
|
|
3. `docs/HANDOFF.md` — where the last session stopped and the next actions.
|
|
4. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified.
|
|
5. `docs/ARCHITECTURE.md` — components and how they fit together.
|
|
6. `docs/adr/` — why significant decisions were made (BLS, profile, ...).
|
|
7. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow.
|
|
8. `docs/CONTRIBUTING.md` — code standards and definition of done.
|
|
9. `docs/GIT-WORKFLOW.md` — how changes are committed and published.
|
|
10. `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/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)
|
|
|
|
1. Read this file and the reading order in §1; run `make context`.
|
|
2. Run `make doctor` before VM work, and inspect `docs/ROADMAP.md` for the
|
|
highest-priority unfinished item.
|
|
3. Inspect `git log --oneline -20`, `docs/CHANGELOG.md` and `docs/HANDOFF.md`.
|
|
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`, `docs/STATUS.md` and `docs/HANDOFF.md` if
|
|
behavior/verification changed.
|
|
9. Commit with a conventional commit message (see `docs/GIT-WORKFLOW.md`) and
|
|
push (`scripts/publish.sh` or `make 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):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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 (`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 (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.
|