phoebus_os/README.md
Phoebus 38214ea9e7 chore: import Phoebus OS installer and Rust migration
Initial public import of the proven Bash installer (installer/) and the production Rust workspace (installer-rs/). The reference ISO, build output and local agent transcripts are gitignored.

Verified: installer/tests/run_tests.sh and cargo test --workspace both pass.
2026-09-20 02:07:33 -07:00

69 lines
2.4 KiB
Markdown

# Phoebus OS
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. AI-first, never
AI-dependent.
Stability first: modern architecture + mature implementations + conservative
updates + recovery.
## Status
A complete encrypted UEFI install has been built and **booted in a disposable
VM** (ISO detached): GPT + LUKS2 + Btrfs, systemd PID 1, login, networking, and
a verified Wayland desktop stack with Flatpak. See `docs/STATUS.md` for the
exact implementation/verification matrix and known limitations.
## Repository layout
```
AGENTS.md entry point for AI/human contributors (read first)
docs/ objectives, roadmap, status, architecture, process
installer/ proven Bash installer (reference / fallback) + VM harness
installer-rs/ production Rust installer (crates/ workspace)
scripts/ git/dev tooling (hooks, publish, agent-commit)
.githooks/ committed git hooks
```
The Gentoo LiveGUI ISO is a reference artifact and is **not** tracked by git.
## Build and test
```sh
# Bash reference
installer/tests/run_tests.sh
# Rust production installer
cd installer-rs
cargo fmt --all -- --check
cargo clippy --workspace --all-targets
cargo test --workspace
cargo build --release -p phoebus-installer
```
Installer quick start (Rust):
```sh
phoebus-installer --config FILE --plan # installation plan
phoebus-installer --config FILE --dry-run # no system changes
phoebus-installer --config FILE --install # run the backend
phoebus-installer --config FILE --install --yes \
--luks-passphrase-file /secure/luks.pw \
--user-password-file /secure/user.pw
```
The normal installation path is entirely deterministic and does not require an
LLM. AI is an optional assistant that proposes typed, validated changes which
the user approves; it never holds root or a shell.
## Documentation
- `docs/OBJECTIVES.md` — vision, philosophy, non-goals.
- `docs/ROADMAP.md` — priorities and current status.
- `docs/STATUS.md` — implemented / unit-tested / VM-verified.
- `docs/ARCHITECTURE.md` — components and safety model.
- `docs/DEVELOPMENT.md` — host setup, build, VM testing.
- `docs/CONTRIBUTING.md` — standards and definition of done.
- `docs/GIT-WORKFLOW.md` — how to commit, push and release.
- `installer/doc/VM-BOOT-VERIFICATION.md` — boot evidence.