# 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"
desktop-image: "background.png"
title-text: ""

+ boot_menu { left/top/width/height = N%; item_color/selected_item_color = "#rrggbb" }
+ 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.

### 2. ISOLINUX Menu (BIOS boot)
- Text-only ANSI-style `MENU COLOR` directives
- Use `vesamenu.c32` for graphical, `menu.c32` for compatibility

### 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`
- Kernel param `splash` must be present

### 4. Console Banner (TTY login)
- ASCII art in `/etc/profile.d/archipelago.sh`
- Uses ANSI escape codes for color

### 5. Installer Prompt
- In systemd service wrapper: `/usr/local/bin/archipelago-start-installer`

## Image Specs

| Asset | Format | Size | Notes |
|-------|--------|------|-------|
| GRUB background | PNG | 1024x768 recommended | 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: Step 2 (copied from `branding/grub-theme/`, fonts generated with `grub-mkfont`)
Plymouth theme: Step 3 (component copy) + Step 4 (auto-install.sh copies to target)
GRUB on target: auto-install.sh copies to `/mnt/target/boot/grub/themes/archipelago/`

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