phoebus_os/README.md
Phoebus fe8de3904b
Some checks are pending
ci / test (push) Waiting to run
refactor(desktop): unify desktop stack on Mango + DarkMaterial and excise standalone dwl
- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock
- Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop
- Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations
- PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback
- Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango
- Live ISO emitted assets reduced from 24 to 17 and verified clean
2026-09-24 15:49:15 -07:00

71 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
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.
- `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`.