# Stage Anatomy

ChillcraftOS is built in stages. Each stage builds on the previous one.

## Stages

### Stage 0 — Bootstrap

Bootstraps a minimal Debian Trixie filesystem using `debootstrap`. Configures apt sources (including the ChillcraftOS apt repo), installs firmware packages, and sets up the base package state. Does not produce a bootable system.

- RPi: installs `raspi-firmware`, `linux-image-rpi-v8`, `linux-image-rpi-2712`
- amd64: installs `grub2`, `linux-image-amd64`

### Stage 1 — Minimal Bootable System

Makes the system bootable. Installs `/etc/fstab` (arch-specific), configures the hostname, locale, and basic networking. At this stage the system can boot to a console.

- RPi fstab: `/boot/firmware` (vfat) + btrfs root with subvolumes
- amd64 fstab: `/boot` (vfat) + `/boot/efi` + btrfs root with subvolumes

Both use btrfs subvolumes: `@`, `@home`, `@var`, `@snapshots`.

### Stage 2 — System Layer

Installs the core system utilities, tools, and services. This is the "lite" layer.

Key additions:
- `zsh` as the system-wide default shell
- `btrfs-progs` + `snapper` for filesystem snapshots
- `cloud-init` + `netplan` for first-boot configuration
- Bluetooth, Wi-Fi, avahi, SSH, cups, and other system services
- Python 3, Lua, build tools

### Stage 3 — Desktop

Installs the full GNOME desktop environment and user-facing applications.

Key additions:
- GNOME Shell and core apps
- Firefox ESR
- amd64: `live-boot`, `live-config`, `live-config-systemd`, `grub-efi-amd64`

This stage triggers the export pipeline via `EXPORT_ISO` and/or `EXPORT_SQUASHFS` for amd64, and `EXPORT_IMAGE` for RPi.

## Export Outputs

| Stage | Arch | Marker | Output |
|-------|------|--------|--------|
| stage3 | amd64 | `EXPORT_ISO` | Bootable live ISO |
| stage3 | amd64 | `EXPORT_SQUASHFS` | Raw squashfs archive |
| stage3 | arm64/armhf | `EXPORT_IMAGE` | Flashable `.img` |

## Skipping Stages for Development

Place a `SKIP` file in any stage directory to skip it. Use `SKIP_IMAGES` to prevent an export from running without skipping the stage itself.

```bash
# Only rebuild stage3 (assumes stage0-2 already built)
touch stage0/SKIP stage1/SKIP stage2/SKIP
sudo CLEAN=1 ./build.sh -c config
```