archy/.claude/plans/toasty-inventing-cascade.md

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