phoebus_os/README.md
Phoebus fc64793aec docs: update references after retiring the Bash installer
Point AGENTS.md, README.md and the docs at the Rust-only toolchain and the
moved VM-BOOT-VERIFICATION.md, and drop the Bash installer from DEVELOPMENT.md.
2026-09-20 04:00:19 -07:00

70 lines
2.5 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/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.
- `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`.