fix: xorriso append_partition for real USB boot + grub-mkstandalone

Root cause of USB boot failure: our xorriso used -e boot/grub/efi.img to embed the EFI image inside the ISO. This works for CD-ROM and QEMU but NOT for USB on real UEFI hardware. Fix: use the Will Haley / Debian live-build approach: - -append_partition 2 (GPT type EFI) appends efi.img AFTER ISO data - -e --interval:appended_partition_2:all:: references the appended partition - --mbr-force-bootable forces MBR active flag - grub-mkstandalone with embedded bootstrap config (searches for grub.cfg) - grub.cfg placed in both /boot/grub/ AND /EFI/BOOT/ on ISO - grub.cfg uses search --label ARCHIPELAGO to find the ISO root This is the exact approach used by StartOS, TAILS, and every production custom Debian live ISO that boots from USB. Also: iso-debug, iso-branding skills + reference docs, dev-start.sh option 0 for branding dev, improved dev-branding.sh and test-iso-qemu.sh. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 11:34:29 +00:00
parent 013b724e02
commit 34a476d0a1
6 changed files with 1006 additions and 217 deletions
@@ -0,0 +1,146 @@
+---
+name: iso-branding
+description: Design and implement Archipelago boot visuals — GRUB theme, Plymouth splash, ISOLINUX menu, console banners. Handles pixel-art cyberpunk aesthetic with Bitcoin orange accents. Use when working on boot screen design, splash animations, GRUB backgrounds, or installer UI appearance.
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Agent
+---
+
+# ISO Boot Branding — Archipelago
+
+Design and build the visual boot experience from USB power-on to web UI.
+
+## Brand Identity
+
+**Archipelago** = self-sovereign Bitcoin node OS. Floating islands in the sky.
+
+| Element | Value |
+|---------|-------|
+| Primary accent | `#fb923c` (Bitcoin orange) |
+| Secondary accent | `#f7931a` (deeper orange) |
+| Success | `#4ade80` (green) |
+| Background | `#0a0a0a` → `#050505` (near-black) |
+| Text | `#ffffff` (white), `#aaaaaa` (dim), `#555555` (subtle) |
+| Glass | `rgba(255,255,255,0.06)` frost overlay |
+| Style | Pixel art cyberpunk, dark glass morphism, CRT scanlines |
+| Logo | Pixel-art lowercase "a" (from SVG favicon) |
+
+## Boot Stages & What's Customizable
+
+### 1. GRUB Menu (UEFI boot)
+- **Background**: `branding/grub-theme/background.png` — any PNG, GRUB scales it
+- **Theme**: `branding/grub-theme/theme.txt` — colors, layout, labels
+- **Fonts**: Generated with `grub-mkfont` during build, .pf2 format
+- **Config**: Written by build script in Step 5 (`grub.cfg` heredoc)
+
+GRUB theme.txt properties that work:
+```
+desktop-color: "#rrggbb"       # Fallback if no background
+desktop-image: "background.png" # Background image
+title-text: ""                  # Empty = no title
+
+ boot_menu {
+    left/top/width/height = N%
+    item_color = "#rrggbb"
+    selected_item_color = "#rrggbb"
+    item_height = N
+    item_spacing = N
+    scrollbar = false
+}
+
+ label {
+    left/top/width = N%
+    text = "string"
+    color = "#rrggbb"
+    align = "center"
+}
+```
+
+**IMPORTANT**: Do NOT reference font names in theme.txt unless you know the exact internal name from grub-mkfont output. GRUB falls back to default if a font reference fails, which causes the ENTIRE theme to not load.
+
+### 2. ISOLINUX Menu (BIOS boot)
+- **Config**: Written by build script in Step 5 (`isolinux.cfg` heredoc)
+- **Colors**: ANSI-style color codes in `MENU COLOR` directives
+- **Title**: `MENU TITLE` string
+- Text-only — no background image (use `vesamenu.c32` for graphical, but `menu.c32` is more compatible)
+
+### 3. Plymouth Splash (kernel boot → login)
+- **Theme**: `branding/plymouth-theme/archipelago.script`
+- **Logo**: `branding/plymouth-theme/logo.png` (PNG with transparency)
+- **Config**: `branding/plymouth-theme/archipelago.plymouth`
+- Supports: animated progress bar, logo sprites, LUKS password prompt
+- Kernel param `splash` must be present (added to GRUB_CMDLINE_LINUX_DEFAULT)
+
+Plymouth script language:
+```javascript
+Window.SetBackgroundTopColor(r, g, b);  // 0.0-1.0
+logo = Image("logo.png");
+sprite = Sprite(logo);
+sprite.SetX(x); sprite.SetY(y);
+Plymouth.SetRefreshFunction(callback);
+Plymouth.SetBootProgressFunction(callback);
+Plymouth.SetDisplayPasswordFunction(callback);
+```
+
+### 4. Console Banner (TTY login)
+- ASCII art + system info in `/etc/profile.d/archipelago.sh`
+- Generated in auto-install.sh (Step 4, the INSTALLER_SCRIPT heredoc)
+- Uses ANSI escape codes for color
+
+### 5. Installer Prompt
+- "ARCHIPELAGO BITCOIN NODE OS / Automatic Installer"
+- In the systemd service wrapper: `/usr/local/bin/archipelago-start-installer`
+- Built inside the debootstrap container in Step 2
+
+## Dev Workflow
+
+### Quick preview (no ISO needed)
+```bash
+# Edit background, see it instantly:
+open image-recipe/branding/grub-theme/background.png
+
+# Generate procedural background:
+python3 image-recipe/branding/generate-grub-background.py /tmp/bg.png && open /tmp/bg.png
+
+# Generate Plymouth logo:
+python3 image-recipe/branding/generate-plymouth-logo.py /tmp/logo.png && open /tmp/logo.png
+```
+
+### Full boot test (needs base ISO)
+```bash
+./image-recipe/dev-branding.sh [path-to-iso]
+# Or via dev-start.sh option 0
+```
+Extracts ISO → patches branding → repackages → boots QEMU. ~30 seconds.
+
+### What to edit
+| File | Affects |
+|------|---------|
+| `branding/grub-theme/background.png` | GRUB boot screen image |
+| `branding/grub-theme/theme.txt` | GRUB menu colors, layout |
+| `branding/plymouth-theme/logo.png` | Plymouth boot logo |
+| `branding/plymouth-theme/archipelago.script` | Plymouth animation/progress |
+| `branding/generate-grub-background.py` | Procedural background generator |
+| `branding/generate-plymouth-logo.py` | Procedural logo generator |
+
+## Image Specs
+
+| Asset | Format | Size | Notes |
+|-------|--------|------|-------|
+| GRUB background | PNG | 1024x768 recommended | GRUB scales any size, but large images slow boot |
+| Plymouth logo | PNG (RGBA) | 256x256 recommended | Transparent background |
+| GRUB fonts | .pf2 | Generated | `grub-mkfont -s SIZE -o out.pf2 input.ttf` |
+
+## Build Integration
+
+GRUB theme is installed in Step 2 (after artifacts placed):
+- Static `background.png` copied from `branding/grub-theme/`
+- Falls back to Python generator if static file missing
+- Fonts generated in debootstrap container with `grub-mkfont`
+
+Plymouth theme installed in Step 3 (component copy) + Step 4 (auto-install.sh):
+- Files copied to `$ARCH_DIR/plymouth-theme/` in ISO
+- Auto-install.sh copies to target at `/usr/share/plymouth/themes/archipelago/`
+- Sets as default via `plymouth-set-default-theme`
+
+GRUB theme also installed on TARGET system (not just installer):
+- Auto-install.sh copies theme to `/mnt/target/boot/grub/themes/archipelago/`
+- Adds `GRUB_THEME=` to `/mnt/target/etc/default/grub`