# Plan: ISO Polish — Fix Everything for Beta Release

## Context
Fresh ISO install on .198 revealed 11 issues ranging from critical (app installs, Tor broken) to UX (GRUB scaling, boot splash, kiosk reliability). Goal: next ISO build produces a flawless out-of-box experience.

## Issues & Fixes (priority order)

### 1. CRITICAL: Tor services.json not written (escaping bug)
**Symptom:** `setup-tor.sh: line 12: $ARCHY_TOR_DIR/services.json: No such file or directory`
**Root cause:** In `build-auto-installer-iso.sh`, the setup-tor heredoc escapes `$ARCHY_TOR_DIR` as `\$ARCHY_TOR_DIR`, producing a literal `$` in the output script. The variable never expands at runtime.
**Fix:** In the heredoc that generates setup-tor.sh (~line 1200), use unescaped `$ARCHY_TOR_DIR` so it expands at runtime. The heredoc itself uses `<<TORSCRIPT` (unquoted) so we need to check the quoting carefully.
**File:** `image-recipe/build-auto-installer-iso.sh` (setup-tor heredoc section)

### 2. CRITICAL: App installs failing ("Operation failed")
**Symptom:** Screenshot shows "Failed: Error: Operation failed. Check server logs" + "Downloading..." stuck
**Root cause:** This is the OLD build (pre-CSRF fix). The new build has the fix. However, `sanitize_error_message()` in `middleware.rs` masks ALL real errors. Need to verify the new build works.
**Fix:** Already fixed (auth.ts, rpc-client.ts, mod.rs). Verify on next ISO.
**Also:** Consider allowing "Failed to pull" errors through the sanitizer so users see meaningful install errors.
**File:** `core/archipelago/src/api/rpc/middleware.rs`

### 3. HIGH: Kiosk white screen / never loads on first boot
**Symptom:** First boot: black screen → white screen → kiosk never loads. Second boot works fine.
**Root cause:** The kiosk `ExecStartPre` health check polls 15x with 2s delay (30s max), but on first boot the backend may not be ready within 30s (first-boot-containers, Tor setup, etc. all running). Chromium opens `http://localhost/kiosk` before nginx/backend is fully up → white page. No retry logic in the launcher.
**Fix:** Increase health check to 30 attempts (60s). Add a loading page that Chromium shows while waiting (a simple HTML file served by nginx even when backend is down). Add `--disable-gpu` flag to Chromium (fixes some white screen issues on low-end GPUs).
**File:** `image-recipe/build-auto-installer-iso.sh` (kiosk launcher + ExecStartPre)

### 4. HIGH: GRUB theme text not scaling / cut off on 4:3 monitors
**Symptom:** Screenshot shows "Install (var" cut off, menu items barely readable on 1280x1024 Dell
**Root cause:** GRUB theme uses percentage-based layout but no font size control. GRUB defaults to a small bitmap font. The `item_height = 40` is fixed pixels, too small at some resolutions. No explicit font loaded in theme.txt.
**Fix:** In `grub.cfg`, load a larger font (24px DejaVu or similar). Adjust theme.txt: increase `item_height`, move menu position up, ensure text fits. Add `loadfont` to grub.cfg.
**Files:** `image-recipe/branding/grub-theme/theme.txt`, `image-recipe/build-auto-installer-iso.sh` (grub.cfg generation)

### 5. HIGH: LUKS partition not showing in disk stats
**Symptom:** Server view doesn't show LUKS encryption status or the encrypted partition
**Root cause:** Backend `system.disk-status` uses `df /` or `df /var/lib/archipelago` but doesn't report LUKS status. No `cryptsetup status` call. Frontend only shows used/total/free/percent.
**Fix:** Add LUKS detection to the disk status RPC: check if `/dev/mapper/archipelago*` exists, read `cryptsetup status`. Return `encrypted: true/false` and `encryption_cipher` fields. Frontend: show a lock icon + "LUKS2 Encrypted" badge in disk stats.
**Files:** `core/archipelago/src/api/rpc/system/handlers.rs`, `neode-ui/src/views/Server.vue`

### 6. MEDIUM: No Plymouth boot splash showing
**Symptom:** No animation between GRUB and login — just black screen with blinking cursor
**Root cause:** Plymouth theme files exist in `image-recipe/branding/plymouth-theme/` but the ISO build doesn't copy the logo.png or install the theme properly. Also kernel cmdline needs `splash quiet` and `plymouth-set-default-theme` must be run.
**Fix:** Verify the ISO build copies plymouth theme + logo.png to rootfs, runs `plymouth-set-default-theme archipelago`, and kernel cmdline includes `splash quiet`.
**File:** `image-recipe/build-auto-installer-iso.sh` (plymouth setup section)

### 7. MEDIUM: No custom MOTD
**Symptom:** Default Debian MOTD on VT1 login
**Fix:** Add custom MOTD to ISO build that shows Archipelago ASCII logo, version, IP address, and useful commands (kiosk toggle, SSH info).
**File:** `image-recipe/build-auto-installer-iso.sh` (add MOTD generation)

### 8. MEDIUM: Onboarding intro needs double press
**Symptom:** Pressing the intro circle/button once resets, need to press twice
**Root cause:** `SplashScreen.vue` has a 48-segment ring animation triggered on hover. The splash → intro transition may have a race condition with animation completion. `OnboardingIntro.vue` auto-focuses CTA after 2100ms delay — if user clicks before that, focus may steal the event.
**Fix:** Investigate SplashScreen.vue transition timing. Add click debounce or ensure single-click always proceeds.
**Files:** `neode-ui/src/components/SplashScreen.vue`, `neode-ui/src/views/OnboardingIntro.vue`

### 9. MEDIUM: No TUI animations in actual installer
**Symptom:** Installer is functional but plain — no bouncing Bitcoin, no glitch effects from demo
**Root cause:** `scripts/install-tui-demo.sh` has elaborate animations but the actual installer in the ISO build script is minimal (basic spinner + typewriter only).
**Fix:** Port key animations from install-tui-demo.sh into the actual installer: logo decrypt reveal, progress bars with percentage, phase transitions. Keep it lightweight but visually distinctive.
**File:** `image-recipe/build-auto-installer-iso.sh` (auto-install.sh section)

### 10. LOW: Container tests CI failing
**Symptom:** `cargo: command not found` in container-tests workflow
**Fix:** Add `source $HOME/.cargo/env` to test steps. Already staged locally.
**File:** `.gitea/workflows/container-tests.yml`

### 11. LOW: Kiosk enable/disable command lacks visual feedback
**Symptom:** User runs command, MOTD changes but no immediate visual confirmation
**Root cause:** The `archipelago-kiosk` script DOES print feedback messages. The issue may be that VT auto-switches and the user doesn't see the output.
**Fix:** Add a brief sleep before VT switch so user sees the confirmation message. Consider adding a `--quiet` flag for scripted use.
**File:** `image-recipe/build-auto-installer-iso.sh` (kiosk toggle script)

## Execution Order
1. Tor fix (#1) — 5 min, critical
2. Kiosk reliability (#3) — 15 min, high impact
3. GRUB text scaling (#4) — 15 min, visible
4. LUKS disk stats (#5) — 20 min, backend + frontend
5. App install error messages (#2) — 10 min, verify + improve
6. Plymouth boot splash (#6) — 15 min
7. Custom MOTD (#7) — 10 min
8. Intro double-press (#8) — 10 min
9. TUI animations (#9) — 30 min (port from demo)
10. CI fix (#10) — 2 min
11. Kiosk feedback (#11) — 5 min

## Verification
- Build new ISO on .228 via CI (push to main)
- Flash to USB, install on .198
- Check: GRUB readable → Plymouth splash → TUI installer animations → MOTD shows → Kiosk loads first time → Tor onion addresses visible → App installs work → Disk shows LUKS → Intro single-click works