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.
This commit is contained in:
Phoebus 2026-09-20 02:07:44 -07:00
parent 38214ea9e7
commit 20bfd82079
9 changed files with 889 additions and 0 deletions

189
AGENTS.md Normal file
View file

@ -0,0 +1,189 @@
# 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):
```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.

121
docs/ARCHITECTURE.md Normal file
View file

@ -0,0 +1,121 @@
# Architecture
Phoebus currently ships two installer implementations:
1. **Bash** (`installer/`) — the proven prototype and executable reference.
2. **Rust** (`installer-rs/`) — the production installer. It reproduces the
proven VM boot path and is the intended long-term backend.
The Bash implementation stays until hardware-level desktop verification exists.
## Layering
```
TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer)
|
v
Orchestration + plan staged execution, single source of truth
|
v
Executor commands, storage, Portage, boot, services
|
v
Core typed config, models, policy, validation
```
### phoebus-core
Pure, non-privileged logic with no external commands except reading `/proc`,
`/sys` and small system files:
- `config` — `InstallConfig` (nested sections, enums for closed sets); TOML and
legacy flat-format loading (format is detected structurally).
- `validate` — hostname/username/locale/timezone/keymap/password checks.
- `disk` / `hardware` — models and protection classification (pure).
- `plan` — `InstallPlan` with the canonical step order and human rendering.
- `policy` — deterministic source/binary decisions + policy context.
- `emergelog` — parses Portage `emerge.log` into measured compile times.
- `target` — `TargetRoot`, which rejects absolute paths and `..` traversal.
- `secret` — `SecretString` (redacted `Debug`, zeroized on drop) + `Redactor`.
- `snapshot` — deterministic snapshot names + TOML transaction history.
- `action` — closed `SystemAction` schema and a small deterministic parser.
- `update` — preparation policy and real Portage argument builders.
### phoebus-executor
The only crate that runs privileged commands.
- `command` — `CommandSpec`, `ProcessRunner` (real / recording / never) with
arguments always separate; there is no `sh -c`.
- `exec` — `Exec` centralises logging, redaction, dry-run, chroot mounts and
target writes.
- `log` — file + optional stderr logging; every line is redacted.
- `auth` — `DestructiveAuthorization`, issued only after ERASE + final
confirmation.
- `storage`, `encryption`, `portage`, `kernel`, `boot`, `users`, `services`,
`desktop` — the install backend, mirroring the proven order.
- `probe` — read-only hardware and disk discovery.
- `snapshot`, `update`, `admin`, `actions` — post-install foundations.
### phoebus-ai
- Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell).
- `privacy` — `PrivacyPolicy` + `ContextBundle`; forbidden-path checks. The
collector in `phoebus-executor::admin` only reads system sources.
### phoebus-installer
- `orchestrate` — `Installer` runs the plan stages and stops on first failure.
- `release` — `ReleaseManifest` create/verify, assemble command.
- Binaries: `phoebus-installer`, `sys`, `phoebus-release`.
## Safety model
- Every command goes through `Exec`, which logs a redacted command line, exit
status and duration, and honours dry-run centrally.
- Destructive functions take `&DestructiveAuthorization`; the token is created
only after the destructive preview and confirmations.
- All target writes go through `TargetRoot`; host-versus-target mistakes are
caught by construction and covered by tests.
- Secrets travel over stdin only and are registered with the redactor before
any logging. They never enter the config.
- The AI cannot execute; it can only propose typed changes that the backend
validates and the user approves.
## Installation order (do not regress)
```
storage_prepare -> stage_install -> fstab_generate -> portage_configure
-> packages_base -> kernel_install -> boot_install -> users_configure
-> services_configure -> desktop_install -> finalize
```
Storage order: partition GPT, create ESP, LUKS format/open, `mkfs.btrfs`, mount
top-level, create subvolumes, unmount, mount the subvolume layout. `fstab` and
`crypttab` are generated **after** stage3 extraction (stage3 ships its own
`/etc/fstab`).
## Configuration and plan
`InstallConfig` is canonical data; the plan and all rendering derive from it.
The same plan drives the review screen, the destructive preview, dry-run and
the actual execution, so the UI cannot diverge from the backend.
## Post-install foundations
- **Snapshots**: read-only Btrfs snapshots under `/.snapshots`, recorded in a
TOML history. `/home` is intentionally not snapshotted by default.
- **Background updates**: `emerge --fetchonly` then `--buildpkgonly` stage
distfiles and reusable local binary packages without installing; activation
stays explicit.
- **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel`
(optimized), dracut initramfs, systemd-boot BLS entries, plus a recovery
entry booting `rescue.target`.
## Extension points
- `ProcessRunner` — swap the real runner for a recording/never runner in tests,
or for a different execution backend.
- `InstallStep` — add stages in `plan.rs` and handle them in `orchestrate.rs`.
- `SystemAction` — add closed verbs; the policy engine classifies and previews
them, and the broker executes them after approval.

79
docs/CHANGELOG.md Normal file
View file

@ -0,0 +1,79 @@
# Changelog
All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary.
Format: Keep a Changelog. Dates are UTC.
## Unreleased
### Added
- Git workflow: committed hooks (`.githooks/`), `scripts/check-secrets.sh`,
`scripts/agent-commit.sh`, `scripts/publish.sh`, `scripts/setup-hooks.sh`.
- Documentation set: `docs/OBJECTIVES.md`, `ROADMAP.md`, `STATUS.md`,
`ARCHITECTURE.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`, `GIT-WORKFLOW.md`,
`CHANGELOG.md`, and the top-level `AGENTS.md`.
- `.gitignore` covering the ISO, build output, transcripts and secrets.
## 2026-09-20 — Rust installer parity, desktop, and foundations
### Added
- Rust workspace (`installer-rs/`): `phoebus-core`, `phoebus-executor`,
`phoebus-ai`, `phoebus-tui`, `phoebus-installer` (~9.4k LOC, 45 files).
- Typed `InstallConfig` supporting TOML and the legacy flat format.
- `TargetRoot` (host/target path safety), `SecretString`/`Redactor`,
`DestructiveAuthorization`, central `Exec` command layer with dry-run.
- Storage backend: GPT, ESP, LUKS2, Btrfs layout, fstab/crypttab, swapfile.
- Stage3 fetch with pinned SHA-256 (or signed DIGESTS), Portage configuration,
signed binary use, source builds, kernel, dracut, systemd-boot BLS.
- Desktop/Flatpak: selects `default/linux/amd64/23.0/desktop/systemd`, writes
`/usr/local/bin/phoebus-session`; flathub remote configured.
- Package policy instrumentation: measured compile times parsed from
`emerge.log` (326 entries recorded in the desktop run), persisted to
`/var/lib/phoebus/compile-times.tsv`.
- Snapshots: read-only Btrfs snapshots + TOML transaction history.
- Background update preparation (`--fetchonly` + `--buildpkgonly`).
- Typed `SystemAction` schema, privileged broker, and the `sys` command.
- AI privacy boundary (`PrivacyPolicy`, `ContextBundle`, forbidden paths).
- Release tooling: `phoebus-release` manifest/verify/sha256/assemble.
- ratatui TUI with plan review and ERASE confirmation.
- Recovery BLS entry booting `rescue.target`.
### Fixed
- Subvolumes mounted before creation.
- fstab/crypttab overwritten by stage3 extraction (moved to `fstab_generate`).
- Missing `/var/tmp` breaking `kernel-install`.
- `installkernel` requiring `uki_generator` even for BLS.
- dracut `crypt` module and `systemd-cryptsetup` missing.
- LUKS cmdline using `rd.luks.uuid` instead of `rd.luks.name`.
- dracut UKI missing the kernel command line (BLS adopted).
- `@swap` not mounted, breaking swap activation.
- Portage GPG verify user unable to read the getuto keyring.
- Transient rsync mirror quarantine (sync retries).
- Pillow/HarfBuzz documentation circular dependency.
- Legacy config silently parsed as TOML with defaults.
### Verified
- Full encrypted UEFI install and boot with the ISO detached: `systemd` PID 1,
`is-system-running = running`, 0 failed units, 10.73 s boot.
- Desktop stack headless: dwl, waybar, mako, swaybg, `grim` screenshot,
`wl-copy`/`wl-paste`, `wpctl`, `flatpak 1.18.1` + flathub.
- No secret leakage in the installer log.
## 2026-09-19 — Bash installer prototype and first VM boot
### Added
- Bash + `dialog` installer (`installer/`) with deterministic backend, TUI,
plan/review, dry-run, logging, and destructive confirmation.
- Read-only hardware/disk discovery with live-medium protection.
- GPT/LUKS2/Btrfs backend, systemd stage3, Portage, kernel, systemd-boot,
users/services/desktop modules.
- Unit/regression suite and a disposable VM harness.
### Verified
- First complete encrypted UEFI VM install and boot with the Bash installer.
### Fixed
- The subvolume-ordering, fstab-timing, `/var/tmp`, `rd.luks.name`,
`uki_generator`, cryptsetup, `@swap`, and `local root="$1" dir=...` bugs
(these are the class of bug the Rust port is designed to prevent).

84
docs/CONTRIBUTING.md Normal file
View file

@ -0,0 +1,84 @@
# Contributing
## Golden rules
1. Read `AGENTS.md` and the reading order in it before changing anything.
2. Prefer upstream tools and Gentoo conventions over new code.
3. Keep the proven boot path working. If a change could regress it, verify in
the disposable VM before committing.
4. Never commit secrets, the ISO, build output or session transcripts.
5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior or
verification changes.
## Rust standards
- No `unsafe`. If it is genuinely required, keep it tiny, document the
invariants, and test it. (The TUI uses `std::io::IsTerminal` rather than a
foreign `isatty`.)
- No `unwrap`/`expect` in privileged paths. Return structured `thiserror`
errors that carry stage, operation and exit status.
- Never `sh -c`. Every command goes through `phoebus-executor::Exec` with
separate arguments; secrets go over stdin.
- Every target write goes through `TargetRoot`.
- Destructive functions require `&DestructiveAuthorization`.
- Keep unit-testable logic pure and in `phoebus-core`; keep privileged effects
in `phoebus-executor` behind `ProcessRunner`.
## Bash standards (while it remains)
- `shellcheck -S warning` clean.
- Never `local a="$1" b="$a"` (the dynamic-scoping bug class). Use two `local`
statements.
- Never write to a host path without the target root.
- Quote all expansions.
## Tests
- Add a regression test for every meaningful bug (see the tests in
`installer/tests/` and `installer-rs/crates/*/src`).
- Prefer a fake `ProcessRunner` + `TempDir` over root or real disks.
- Destructive/integration testing only in a disposable qcow2 VM.
- Both suites must pass before a commit.
## Commit messages
Conventional Commits, imperative mood:
```
<type>(<scope>): <summary>
<body: what changed and why, and how it was verified>
```
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `chore`.
Scopes: `installer`, `rust`, `core`, `executor`, `ai`, `tui`, `vm`, `docs`,
`git`, `release`.
Examples:
```
feat(rust): add typed SystemAction broker for sys
fix(executor): make getuto keyring readable by the verify user
docs(git): add migration plan and agent workflow
```
## Definition of done
- [ ] The change is implemented, not merely described.
- [ ] Tests added or updated; both suites pass.
- [ ] `cargo fmt`/`clippy` clean (when the components are installed).
- [ ] `docs/CHANGELOG.md` updated; `docs/STATUS.md` updated if verification
changed.
- [ ] No secrets, ISO, build output or transcripts staged.
- [ ] Committed with a conventional message and pushed when a remote exists.
## Review checklist
- Does it weaken encryption, signing, boot protection or disk safety? If so,
stop.
- Does it globally enable `~amd64` or disable signature verification? If so,
stop.
- Does it give the LLM a shell, root, secrets or home-directory access? If so,
stop.
- Does it preserve the proven boot path and the fstab/subvolume ordering?
- Is the change observable in the log and covered by a test?

117
docs/DEVELOPMENT.md Normal file
View file

@ -0,0 +1,117 @@
# Development
## Host requirements
Ubuntu/Debian host names (the development machine is Ubuntu 26.04):
```sh
sudo apt install qemu-system-x86 qemu-utils ovmf-generic seabios ipxe-qemu \
dialog xorriso mtools dosfstools squashfs-tools cpio zstd \
shellcheck python3-pexpect
# Rust quality gates (names may be versioned; check `apt search rustfmt`)
sudo apt install rust-clippy rustfmt
# or, if cargo is rustup-managed:
# rustup component add rustfmt clippy
```
Optional: `expect`, `cryptsetup`, `btrfs-progs`, `parted`, `kpartx` for offline
inspection of VM images. `7z`/`p7zip` is useful for reading the reference ISO.
## Reference media
The Gentoo LiveGUI ISO is a **reference artifact**, not source. It is ignored by
`.gitignore`. Keep it outside git; point the VM harness at it by path.
## Bash installer
```sh
installer/tests/run_tests.sh
shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh
# Non-interactive, non-destructive:
installer/bin/ai-installer --config installer/config/example.conf --plan
installer/bin/ai-installer --dry-run --config installer/config/example.conf
```
## Rust installer
```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 environment:
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
```
Useful CLI invocations:
```sh
target/release/phoebus-installer --config FILE --plan
target/release/phoebus-installer --config FILE --dry-run --install
target/release/phoebus-installer --config FILE --install --yes \
--luks-passphrase-file /secure/luks.pw --user-password-file /secure/user.pw
```
## Disposable VM testing
Never point the harness at a physical disk. The target is always a qcow2 file.
`installer/tests/vm/serial-driver.py` drives QEMU over the serial console:
```sh
cd /path/to/serve
tar czf installer.tar.gz -C /path/to/phoebus_os installer # or the Rust binary
python3 -m http.server 8000 --bind 127.0.0.1
QEMU_BIN=qemu-system-x86_64 \
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \
DISK=/tmp/phoebus/target.qcow2 \
ISO=/path/to/livegui-*.iso \
KERNEL=/tmp/live/boot/gentoo INITRD=/tmp/live/boot/gentoo.igz \
INSTALL_URL=http://10.0.2.2:8000/install.sh \
python3 installer/tests/vm/serial-driver.py install
# Then boot the disk alone (ISO detached):
DISK=/tmp/phoebus/target.qcow2 OVMF_CODE=... OVMF_VARS=... \
python3 installer/tests/vm/serial-driver.py boot
```
`installer/tests/vm/run-vm.sh` launches an interactive VM instead.
### Verifying the graphical stack
The serial-only VM has no logind seat, so wlroots' DRM backend cannot start
there. For headless verification use:
```sh
export WLR_BACKENDS=headless WLR_RENDERER=pixman WLR_RENDERER_ALLOW_SOFTWARE=1
dwl & # creates wayland-0
grim /tmp/shot.png # proves the compositor renders
```
On a real machine the installer writes `/usr/local/bin/phoebus-session`
(waybar + mako + swaybg + dwl).
## Inspecting the reference ISO without booting
```sh
7z l livegui-*.iso
7z x livegui-*.iso image.squashfs boot/gentoo boot/gentoo.igz
unsquashfs -l image.squashfs # file listing
unsquashfs -d /tmp/root image.squashfs etc/portage/make.conf
```
## Quality gates before commit
1. `installer/tests/run_tests.sh`
2. `cd installer-rs && cargo test --workspace`
3. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets`
4. `shellcheck` on the Bash tree (while it exists)
5. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes.
6. Commit (see `docs/GIT-WORKFLOW.md`).

101
docs/GIT-WORKFLOW.md Normal file
View file

@ -0,0 +1,101 @@
# Git workflow and public-repository migration
## What is tracked
Tracked: source (`installer/`, `installer-rs/crates/`, `scripts/`, `.githooks/`),
`Cargo.toml`/`Cargo.lock`, documentation (`docs/`, `AGENTS.md`, `README.md`,
`installer/doc/`, `installer-rs/README.md`), installer configs and tests.
Ignored (see `.gitignore`): the reference ISO and other images, `installer-rs/target/`,
`__pycache__`, `.agent-shell/` transcripts, and any secret material
(`*.pw`, `*.key`, `*.pem`, `credentials`).
## One-time migration (already performed)
```sh
cd /path/to/phoebus_os
git init -b main
git add -A
git commit -m "chore: import Phoebus OS installer and Rust migration"
# ... further commits for docs and tooling ...
git config core.hooksPath .githooks # enable the committed hooks
```
Then connect the public remote and push:
```sh
git remote add origin <PUBLIC_REPO_URL>
git push -u origin main
```
`scripts/publish.sh` performs the push after re-running the checks. It takes the
remote and branch as arguments:
```sh
scripts/publish.sh origin main
```
> The remote URL is intentionally not hard-coded. Add it once with
> `git remote add origin <URL>` and every later `scripts/publish.sh` uses it.
## Ongoing loop for a work session
```
read AGENTS.md
-> inspect docs/ROADMAP.md and git log
-> implement the smallest correct change
-> run the quality gates
-> update docs/CHANGELOG.md and docs/STATUS.md
-> commit (conventional message)
-> push
```
An AI session **must commit the work it does**. The one-line helper:
```sh
scripts/agent-commit.sh "feat(rust): add typed SystemAction broker
Adds a closed action schema and a privileged broker. Verified with
cargo test --workspace."
```
`agent-commit.sh` refuses to commit if the secret scan finds a credential or if
a staged file is too large, then runs the fast tests.
## Hooks
`.githooks/pre-commit` (enabled with `git config core.hooksPath .githooks`):
1. scans staged files for secrets (`scripts/check-secrets.sh`);
2. blocks staged `*.iso`, `*.qcow2` and files larger than 5 MiB;
3. runs the fast Bash test suite.
Bypass for a genuine emergency with `git commit --no-verify`, or set
`SKIP_PHOEBUS_HOOKS=1`. Set `PHOEBUS_PRECOMMIT_RUST=1` to also run
`cargo test --workspace` in the hook.
## Branching and releases
- Trunk-based: `main` is always green. Short-lived branches are fine for risky
work; merge with a conventional merge/squash.
- Releases are annotated tags `vX.Y.Z` with the manifest produced by
`phoebus-release`. Never replace `latest.iso` until `phoebus-release verify`
passes.
- Never rewrite published history (`push --force` to `main` is forbidden). Fix
mistakes with a new `fix:` commit.
## Secret policy
- Never commit passwords, LUKS passphrases, API keys or tokens.
- Secrets are supplied at runtime through 0600 files or stdin and registered
with the redactor.
- The pre-commit scan is a safety net, not a licence to be careless.
## What a future session should do
1. `git log --oneline -20` and `head docs/CHANGELOG.md` for context.
2. Work as described in `AGENTS.md`.
3. Before committing: `scripts/check-secrets.sh` and the test gates.
4. Commit with `scripts/agent-commit.sh` (or `git commit`), then
`scripts/publish.sh`.
5. Confirm `git status` is clean and the push succeeded.

66
docs/OBJECTIVES.md Normal file
View file

@ -0,0 +1,66 @@
# Objectives
## Vision
Phoebus OS is a modern, stable, Gentoo-based workstation operating system that
provides Gentoo-level flexibility, performance and control **without requiring
the user to act as a full-time Gentoo administrator**.
It combines a mature modern architecture with a conservative update policy and
real recovery:
```
Modern architecture + mature implementations
+ conservative updates + snapshots/rollback
```
## Pillars
- **Gentoo + Portage** remain the package foundation. Phoebus is an integration
layer, not a parallel Linux ecosystem.
- **systemd** is the init and service architecture; OpenRC is out of scope.
- **Wayland-first**, with XWayland only for compatibility.
- **PipeWire + WirePlumber** are the audio stack. PulseAudio is not the target.
- **UEFI/GPT-first.** Legacy BIOS is not a v0.1 priority.
- **LUKS2** whole-root encryption with a passphrase (TPM2 later, never
mandatory).
- **Btrfs** with subvolumes, snapshots and (eventually) rollback.
- **Stability over novelty.** Stable/LTS kernels, mature filesystems, no
release candidates, no globally unmasked testing tree.
- **Pragmatic builds.** Compile when it is cheap or genuinely beneficial; use
signed Gentoo binaries when compilation is expensive and the benefit is
negligible.
- **Friendly to proprietary software** (drivers, firmware, codecs, Steam,
browsers) where legally distributable. No moralising warnings; respect
licences.
- **AI-first, never AI-dependent.** The system is fully usable without an LLM.
## The AI contract
The LLM is an interface, explainer, planner and reasoning assistant. It is
**not** the source of truth, the root shell, or the privilege boundary.
```
user request -> LLM -> typed structured action -> policy engine
-> human-readable preview -> explicit approval -> authentication
-> privileged deterministic broker -> verification -> history
```
The model never receives the user's sudo password (authentication happens
through sudo/polkit/PAM outside model context), and it has no code path to
read private files: system access is not home-directory access.
## Non-goals
- A custom init system, package manager, audio stack or compositor.
- A giant kernel fork or a large downstream patch set.
- Bleeding-edge/experimental defaults.
- Making the LLM required for installation or normal operation.
- Rebuilding the world on a small release VPS.
## Definition of a successful distribution
Phoebus installs a **bootable, encrypted, systemd** system in a disposable UEFI
VM, boots with the installer media removed, unlocks LUKS, reaches a login and
a functional Wayland desktop, and can be maintained without the user becoming
a Gentoo expert. This is verified per `docs/STATUS.md`.

44
docs/ROADMAP.md Normal file
View file

@ -0,0 +1,44 @@
# Roadmap
Priority order is deliberate. Do not skip a higher item because a later one is
more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| # | Item | Status | Evidence / notes |
|---|------|--------|------------------|
| 1 | Verify the Bash baseline | Done | `installer/tests/run_tests.sh`, `installer/doc/VM-BOOT-VERIFICATION.md` |
| 2 | Build the Rust architecture | Done | `installer-rs/` workspace, 5 crates |
| 3 | Port the deterministic core | Done | `phoebus-core` (config, plan, policy, validation, models) |
| 4 | Port the destructive backend | Done | `phoebus-executor` (storage, LUKS2, Btrfs, Portage, boot, users, services) |
| 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s |
| 6 | Finish the desktop | Partial | dwl/waybar/mako/swaybg/pipewire verified headless; physical seat + interactive login pending |
| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; no app installed yet |
| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries) |
| 9 | Background update preparation | Partial | `--fetchonly` + `--buildpkgonly` implemented and unit-tested; not VM-tested |
| 10 | Snapshots / rollback | Partial | snapshot create + history done; rollback not implemented |
| 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary; OS sandbox not implemented |
| 12 | `sys` operations | Partial | history, enable/disable service, inspect, install, prepare-updates |
| 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists |
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; no scheduling/publish/smoke test |
| 15 | Recovery environment | Later | recovery BLS entry generated; full recovery image not built |
| — | Rust TUI | Partial | ratatui UI with plan/ERASE; not yet the default on all paths |
| — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` |
## Immediate next steps
1. **Physical-seat desktop**: run `phoebus-session`/dwl on a real VT (or a
`seatd`-backed session) and verify kitty, wofi, XWayland, the polkit agent,
logout and reboot interactively.
2. **Desktop binary strategy**: match the desktop USE set to a signed binhost
(or publish one) so desktop installs stop compiling ~26 minutes of packages.
3. **Snapshots and safe updates end-to-end**: prove `sys` snapshot +
`prepare-updates` on an installed system, then implement and test rollback
before wiring `sys undo`.
## Later
- Full recovery environment (network, LUKS, Btrfs, Portage/kernel repair).
- Automated biweekly ISO candidate build with tiered tests and atomic publish.
- AI OS sandbox (systemd sandboxing / namespaces / bubblewrap / Landlock).
- Local model support; richer provider onboarding.
- Optimised kernel profiles with real hardware detection.
- Risk-class update policy (CORE / PROVEN / EDGE) and update preflight.

88
docs/STATUS.md Normal file
View file

@ -0,0 +1,88 @@
# Status
Truthful implementation/verification matrix. Vocabulary:
- **Implemented** — code exists.
- **Unit tested** — covered by automated tests that run on any host.
- **VM verified** — exercised in the disposable QEMU/OVMF VM.
- **Hardware verified** — exercised on real hardware.
- **Not verified** — do not claim it works.
## Proven baseline (do not regress)
A complete installation in a disposable UEFI VM, booted with the ISO detached:
```
QEMU + OVMF (UEFI)
30 GiB qcow2, virtio-blk (/dev/vda); live ISO at /dev/sr0
GPT: 1 GiB FAT32 ESP + LUKS2 remainder
Btrfs: @ @home @var @snapshots @swap
Gentoo systemd stage3 (default/linux/amd64/23.0/systemd)
systemd-boot + BLS entry + dracut initramfs
LUKS2 passphrase unlock at boot
systemd PID 1, login, networking
systemctl is-system-running = running; 0 failed units
```
Boot timing (Rust installer): 1.378 s kernel + 5.238 s initrd + 4.114 s
userspace = 10.730 s.
## Matrix
| Area | Implemented | Unit tested | VM verified | Hardware verified |
|------|-------------|-------------|-------------|-------------------|
| Config (TOML + legacy), validation | yes | yes | yes | n/a |
| Hardware/disk discovery, protection | yes | yes | yes | no |
| Install plan + destructive preview | yes | yes | yes | n/a |
| Destructive authorization (ERASE) | yes | yes | yes | n/a |
| GPT partitioning + ESP | yes | yes | yes | no |
| LUKS2 format/open/close | yes | yes | yes | no |
| Btrfs subvolumes + swapfile | yes | yes | yes | no |
| fstab / crypttab generation | yes | yes | yes | no |
| stage3 fetch + SHA-256 verify + extract | yes | yes | yes | n/a |
| Portage config + sync + getuto | yes | yes | yes | n/a |
| Signed Gentoo binary install | yes | yes | yes | n/a |
| Source package compilation | yes | yes | yes | n/a |
| Kernel install + dracut initramfs | yes | yes | yes | no |
| systemd-boot + BLS | yes | yes | yes | no |
| Recovery BLS entry (rescue.target) | yes | yes | no | no |
| Users, passwords, sudo | yes | yes | yes | n/a |
| Locale/timezone/keymap/services | yes | yes | yes | n/a |
| Rust VM boot parity | yes | yes | yes | no |
| Rust TUI | yes | yes | smoke test | no |
| Desktop profile (dwl/waybar/mako/swaybg) | yes | partial | headless only | no |
| PipeWire/WirePlumber | yes | no | headless (`wpctl`) | no |
| Flatpak + flathub | yes | no | installed + remote | no |
| XWayland / polkit agent / kitty / wofi | yes | no | installed, not launched | no |
| Package policy + measured history | yes | yes | yes (326 entries) | no |
| Background update preparation | yes | yes | no | no |
| Btrfs snapshots + history | yes | yes | no | no |
| Btrfs rollback | no | no | no | no |
| AI typed proposals | yes | yes | no | n/a |
| AI privacy boundary | yes | yes | no | n/a |
| AI OS sandbox | no | no | no | no |
| `sys` verbs | yes | yes | no | no |
| OpenCode pinned bootstrap | yes | yes | no | n/a |
| Release manifest/verify | yes | yes | no | n/a |
| NVIDIA proprietary | architecture only | no | no | no |
| UKI | no (deferred) | no | no | no |
## Known limitations
- **Desktop graphical session** was verified with the *headless* wlroots
backend because the serial-only VM has no logind seat. The DRM path and a
real VT login are not yet exercised. `phoebus-session` is written by the
installer for that purpose.
- **Flatpak apps** were not installed from the remote; only the runtime and
the flathub remote were verified.
- **NVIDIA** is architecturally allowed but not verified on hardware.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **Rollback** is not implemented; snapshots and history are.
- **AI sandbox** is not enforced; only typed actions and the privacy boundary.
- **Release automation** stops at manifest/verify; no scheduler, smoke test,
signing or atomic publish.
- The desktop transaction compiles heavily because desktop USE does not match
the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM).
- The installer rebuilds `sys-apps/systemd` from source because
boot/policykit/cryptsetup USE differ from the binhost.