---
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`