# Environment findings This document records what was actually found in the reference environment before any installer code was written. Nothing here is assumed just because "Gentoo usually has it". ## Reference media - Repository: `/home/dominic/Source/phoebus_os` - Reference image: `livegui-amd64-20260913T163055Z.iso` - Volume label: `gentoo-amd64-livegui` - 4.3 GiB ISO 9660 (El Torito, UEFI + BIOS bootable) - Root filesystem: `image.squashfs` (4.1 GiB) inside the ISO - Base system: `Gentoo Base System release 2.18` - Reference profile: `default/linux/amd64/23.0/desktop/plasma` (i.e. the LiveGUI is a **KDE Plasma / OpenRC** image) Inspection was done by extracting `image.squashfs` with `7z` and listing it with `unsquashfs -l` (365,567 entries); individual config files were extracted read-only. The host used for development is Ubuntu 26.04; the reference is used strictly as read-only data. ## Init system mismatch (important) The LiveGUI reference boots **OpenRC/sysvinit** (`/etc/inittab` present, no `systemctl`, `/usr/lib/systemd/systemd-sysctl`/`systemd-udevd` come from `sys-apps/systemd-utils`). Phoebus OS itself is **systemd-based**. Consequence: the installer runs on an OpenRC live medium but installs a systemd target. Inside the target chroot, `systemctl` is available after the stage3, and service enablement is performed there. The installer must not assume the live environment can `systemctl`. ## Tools found in the live environment Present (`usr/bin`, `usr/sbin`, `bin`, `sbin`): - Shell: `bash`, coreutils, `sed`, `awk`, `grep` - TUI: **`dialog`** (and `whiptail`), `libdialog`, `libncurses`, `tput` - Portage: `emerge`, `portageq`, `eselect`, `locale-gen` - Disk: `lsblk`, `blkid`, `findmnt`, `parted`, `sgdisk`, `gdisk`, `fdisk`, `sfdisk`, `wipefs`, `partprobe`, `udevadm`, `losetup`, `dmsetup` - Filesystems: `mkfs.btrfs`, `btrfs`, `btrfsck`, `mkfs.fat`, `mkfs.ext4`, `mkswap`, `swapon` - Encryption: `cryptsetup`, `gocryptfs` - Network: `NetworkManager`/`nmcli`/`nmtui`, `iw`, `wpa_supplicant`, `dhcpcd`, `ip`, `ping`, `rfkill` - Boot: `efibootmgr`, `grub-install`, `dracut`; `arch-chroot` - Compiler/toolchain: `gcc`, `make`, `git`, `rsync`, `curl`, `wget`, `openssl`, `gpg`, `sha256sum` - Misc: `lspci`, `lsusb`, `lscpu`, `dmidecode`, `smartctl`, `tmux`, `vim` Absent / not available in the live environment: - `systemctl`, `bootctl`, `kernel-install`, `ukify`, `localectl`, `timedatectl`, `hostnamectl`, `systemd-cryptenroll` - `genkernel`, `jq` (so all parsing is done in pure bash) - `opencode`, `node`, `npm`, `flatpak` ## Portage configuration found - `/etc/portage/make.conf`: catalyst stage defaults, `COMMON_FLAGS="-O2 -pipe"`, `LC_MESSAGES=C.UTF-8` - `/etc/portage/make.profile` -> `.../desktop/plasma` - `/etc/portage/binrepos.conf/gentoo.conf`: `https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64`, `verify-signature = true` - confirms Gentoo binary packages are usable and signed, which the package policy relies on - `/etc/portage/package.license/package.license`: `*/* @BINARY-REDISTRIBUTABLE` - Kernel package `sys-kernel/gentoo-kernel` with `experimental` USE flag in the live image; `sys-fs/lvm2 thin` - **No Portage tree is present** (`/var/db/repos` exists but is empty) Consequence: the installer must sync Portage and/or fetch a stage3 itself; it cannot rely on a pre-populated tree in the live image. ## Goop / prior installer scripts The reference image contains no Gentoo installer script that overlaps with what we are building (only unrelated `*installer` binaries from KDE/rust). There was nothing to reuse or avoid duplicating in-tree. ## OpenCode OpenCode is **not** present in the live image. It is downloaded by the installer from a pinned GitHub release (`anomalyco/opencode`, currently `v1.18.31`) and verified by SHA-256 against `config/opencode.manifest` before use. The vendor `curl | sh` installer is deliberately not used. (During development OpenCode `v1.18.31` was fetched and hashed; the live image provides no Node.js, so the standalone `opencode-linux-x64.tar.gz` binary is used.) ## Design decisions driven by these findings 1. **Bash + dialog**, not a heavier stack: both are present in the live image and `dialog` gives a clean Void-style TUI with no extra dependencies. 2. **No `jq`**: all JSON-ish parsing (AI proposals) is implemented in pure bash. 3. **systemd target**: services are enabled inside the target chroot, not in the live environment. 4. **Binhost enabled by default**: Gentoo signed binary packages are already configured in the reference, so the balanced package policy can use them. 5. **Installer fetches its own stage3**: the live image has no Portage tree. 6. **systemd-boot + UKI are target-side operations** (`bootctl`, `kernel-install`), performed after the stage3 is installed.