phoebus_os/README.md
Phoebus b6b9630148
Some checks are pending
ci / test (push) Waiting to run
feat(git): add license, opencode project config and branch protection
- LICENSE (GPL-2.0-or-later, matching the crate manifests) plus a README note.
- .opencode/opencode.json encodes the safety rules as tool permissions (deny
  disk/format tools and secret stores) and pulls OBJECTIVES/ROADMAP/HANDOFF
  into context; .opencode/command/{verify,handoff}.md add session commands.
- scripts/forgejo.sh protect/unprotect and 'make protect'; main is protected
  (owner push allowed, force-push blocked).
2026-09-20 02:41:35 -07:00

74 lines
2.6 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.
## License
Phoebus OS is licensed under the GNU General Public License, version 2 or
later (GPL-2.0-or-later). See `LICENSE`.