# Phoebus OS A modern, stable, **Gentoo-based** workstation operating system: systemd, Wayland-first, PipeWire, UEFI/GPT, LUKS2, Btrfs with snapshots, a fast Mango + DarkMaterial 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/live/ Debian-Live installer appliance ISO recipe installer/tests/vm/ disposable UEFI VM harness (static Rust binary) 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 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. - [User-level agents](docs/USER-AGENTS.md) — workspace capabilities, desktop tools and personal-state recovery. - `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. - `docs/VM-BOOT-VERIFICATION.md` — boot evidence. ## License Phoebus OS is licensed under the GNU General Public License, version 2 or later (GPL-2.0-or-later). See `LICENSE`.