phoebus_os/docs/adr/README.md
Phoebus f9e39925b4 feat(install): AI-first sys install workflow
Implement the shared installation workflow (ADR 0013). sys install, sys ask
install and the explicit backend flags all use one path: identify -> evidence
-> AI investigation -> deterministic validation/effects -> review -> approval
-> execute -> verify -> history.

- phoebus-ai::install: bounded, multi-turn investigation. The model may request
  typed read-only evidence (discover_candidates, inspect_candidate,
  check_backend, inspect_installation), ask one bounded question about intent,
  and must return a structured InstallProposal. Turn/request/size limits and
  repeated-request detection bound it; a rejected proposal is revised.
- phoebus-core: add the four read-only investigation actions and strict
  validators; add a transaction id; backend/kind wire names now match as_str.
- phoebus-executor::install: resolve_explicit (no model, no fallback),
  resolve_deterministic and resolve_with_ai; validate_proposal re-resolves the
  candidate against real metadata, rejects fabrication/ambiguity/staleness/
  duplicates, maps it to the existing broker action, and binds approval to a
  digest; revalidate + verify_installed. chooser gains per-lane friendly-name
  resolution and structured evidence.
- transaction::begin/finish record an in-progress transaction before mutation.
- sys: --portage/--flatpak/--nix/--snap/--appimage/--ebuild (mutually
  exclusive) bypass the model; an unqualified install consults the model and,
  with none, prints the deterministic selection and installs nothing.
- The installer persists /etc/phoebus/install.toml; sys loads it and adds free
  space, Wayland, usable lanes, saved preferences and recovery capability to
  the bounded facts.
- Docs: ADR 0013, docs/SYS.md install sections and cases 23-31, CHANGELOG,
  STATUS, HANDOFF, ROADMAP. New live-VM workflow check script.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test.
VM: verified the workflow CLI and read-only investigation on the reference
LiveGUI ISO; a full target install journey is running (see HANDOFF).
2026-09-23 20:30:13 -07:00

23 lines
1.6 KiB
Markdown

# Architecture Decision Records
Short records of significant decisions, so a new session understands *why*
rather than only *what*. Add a new numbered file for each meaningful decision
and link it here.
| ADR | Title | Status |
|-----|-------|--------|
| [0001](0001-rust-installer.md) | Rust installer as production; Bash retained as reference | Accepted |
| [0002](0002-bls-over-uki.md) | BLS entries instead of UKI for the boot path | Accepted |
| [0003](0003-desktop-systemd-profile.md) | Desktop installs inherit the Gentoo desktop/systemd profile | Accepted |
| [0004](0004-portage-verify-keyring.md) | Relax the getuto keyring for the dropped-privilege verifier | Accepted |
| [0005](0005-debian-live-appliance.md) | Debian-Live appliance ISO with a Gentoo target | Accepted |
| [0006](0006-package-lanes.md) | Package lanes and hardware-aware software selection | Accepted (revised 2026-09-24) |
| [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted |
| [0008](0008-nix-isolation-lifecycle.md) | Nix lifecycle, build isolation, and packaging | Accepted |
| [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted |
| [0010](0010-graphical-installer-frontend.md) | Graphical installer frontend and typed bridge | Accepted |
| [0011](0011-opencode-connection-boundary.md) | OpenCode connection boundary | Accepted |
| [0012](0012-nvidia-driver-policy.md) | NVIDIA accelerated-driver policy and payload | Accepted |
| [0013](0013-ai-first-installation.md) | AI-first package installation workflow | Accepted |
Format: Context / Decision / Consequences / Status.