phoebus_os/AGENTS.md
Phoebus 83368f774c
Some checks are pending
ci / test (push) Waiting to run
feat(git): add session context, host doctor, ADRs and git hygiene
Adds scripts/context.sh + 'make context' (one-screen session briefing),
scripts/doctor.sh + 'make doctor' (host prerequisites), docs/HANDOFF.md
(rolling cross-session note), docs/adr/ (BLS, desktop profile, keyring, Rust),
.githooks/commit-msg (Conventional Commits), .gitattributes, scripts/backup-git.sh
+ 'make backup', and a Forgejo Actions CI workflow. Updates AGENTS.md reading
order/work loop and DEVELOPMENT.md.
2026-09-20 02:36:32 -07:00

195 lines
7.8 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 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.
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/ 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; 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
Bash installer (reference):
```sh
installer/tests/run_tests.sh # unit/regression assertions
shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh
```
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
```
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.