# Phoebus OS installer A deterministic, text-mode installer for Phoebus OS, inspired by `void-installer`. It is usable entirely without an LLM; AI only augments it. ## Goals - Simple keyboard-driven TUI. - Logical, revisitable configuration stages. - A complete installation plan and explicit confirmation before anything destructive happens. - Logs for every backend operation. - No magical hidden disk modifications. ## Two layers ``` tui/ front-end: menus, dialogs, screens menu.sh main loop, review and install flow screens.sh one function per configuration stage ui.sh dialog/whiptail abstraction lib/ deterministic backend (usable without the TUI) state.sh structured configuration state logging.sh logging + run_cmd + dry-run confirm.sh destructive-operation authorization gates hardware.sh read-only hardware probing disks.sh read-only disk discovery and protection rules partitions.sh GPT partitioning filesystem.sh mkfs, mount, fstab/crypttab generation encryption.sh LUKS2 btrfs.sh subvolume layout network.sh live networking + target hostname portage.sh Portage configuration and stage3 pkgpolicy.sh compile-vs-binary policy kernel.sh kernel profile and installation boot.sh systemd-boot (BLS entries) + dracut initramfs users.sh accounts, passwords, sudo desktop.sh desktop profiles ai.sh assistant and structured proposals opencode.sh pinned, checksum-verified OpenCode plan.sh installation plan generation validation.sh configuration validation install.sh staged orchestration config/ defaults.conf all defaults opencode.manifest pinned OpenCode release + SHA-256 tests/ unit tests, no root or disks required ``` ## Running in a Gentoo Live environment The LiveGUI reference (or any Gentoo live medium with `dialog`, Portage and the disk tools listed in `doc/FINDINGS.md`) can run the installer directly: ```sh sudo /path/to/installer/bin/ai-installer ``` Useful non-interactive modes (the backend works without the TUI): ```sh # Print the generated installation plan and validate the configuration ai-installer --plan # Load a saved configuration ai-installer --config /root/phoebus-install.conf # Dry run: every command is logged, nothing is executed ai-installer --dry-run # Run the backend without a TUI (still requires explicit ERASE confirmation) ai-installer --config /root/phoebus-install.conf --install # Fetch and verify the pinned OpenCode release ai-installer --bootstrap-opencode ``` ### Typical flow 1. Network (connect Wi-Fi if needed). 2. Keyboard, hostname, locale, timezone, user. 3. Disk: pick a target (protected devices are never offered). 4. Filesystem / encryption: LUKS2 is the default; set a passphrase. 5. Boot / kernel / packages / desktop as desired. 6. Review configuration -> inspect the plan. 7. Install -> read the destructive summary, type `ERASE`, confirm again. ## Safety model - Detection never modifies a disk. - The target disk must be explicitly selected from candidates. - Disks that are mounted, read-only, optical/loop, or back the live medium are marked **PROTECTED** and cannot be selected. - All destructive commands go through `run_destructive`, which refuses to run unless `PHOEBUS_DESTRUCTIVE_AUTHORIZED=yes`. Only `install.sh` grants this, only after the plan is approved. - Whole-disk erase additionally requires typing `ERASE`. - Dry-run mode redirects all file writes to a temporary sandbox and runs no commands. - Passwords, passphrases and API keys are never written to the config or logs. ## Package policy `lib/pkgpolicy.sh` implements the rule "compile when cheap or beneficial, use a binary when expensive and the benefit is negligible". It is deterministic and uses a curated table plus optional historical compile times (`$STATE_DIR/compile-times.tsv`). No model is consulted to guess performance. ## AI policy - The normal install path is fully deterministic and LLM-free. - The AI assistant explains hardware, disks, filesystems, kernel and package choices, and can translate a natural-language request into a **structured proposal** (flat JSON with a fixed key whitelist). - Every proposed field is validated by `lib/validation.sh`. The LLM never receives secrets, never touches a disk and never runs a command. - Proposal flow: request -> proposal -> validation -> preview -> confirmation -> backend. See `doc/FINDINGS.md` for environment findings and `doc/TESTING.md` for safe testing instructions.