Add firstboot onboarding and prep/check tooling

docs/workflow.md

@@ -0,0 +1,70 @@
+# Pi-Kit Image Workflow
+
+This documents the *current* workflow and the *target* workflow once profiles + first‑boot automation are implemented. It is meant to be a practical, repeatable checklist.
+
+## 0) Keep a golden base image (do this first)
+1) Boot the known‑good base Pi.
+2) Verify core services:
+   - Nginx + Pi‑Kit dashboard
+   - DietPi dashboard
+3) Update the system if needed.
+4) Run the prep scrub:
+   - `sudo ./pikit-prep.sh`
+   - (optional) `sudo ./check-pikit-clean.sh`
+5) Image the SD card with DietPi Imager.
+6) Store it as the golden base (e.g., `images/base/pikit-base-YYYYMMDD.img.xz`).
+
+## 1) Build a profile image (current/manual workflow)
+1) Identify the SD card:
+   - `lsblk`
+2) Flash the golden base image to SD:
+   - `sudo ./flash_sd.sh qemu-dietpi/shared/base.img.xz /dev/sdX`
+3) Boot the Pi and install/configure services manually.
+   - Avoid port 80/443 (Pi‑Kit already uses those).
+4) Add dashboard services using the UI (Add Service modal).
+5) Open any needed ports in ufw (done as part of testing/config):
+   - `sudo ufw allow from <LAN subnet> to any port <port>`
+6) Run the prep scrub:
+   - `sudo ./pikit-prep.sh`
+   - (optional) `sudo ./check-pikit-clean.sh`
+7) Image the SD card via the QEMU DietPi VM:
+   - Insert the SD card into your desktop.
+   - Identify it with `lsblk`.
+   - Start QEMU with passthrough:
+     - `./qemu-dietpi/run-dietpi.sh /dev/sdX`
+   - SSH in:
+     - `ssh -i qemu-dietpi/ssh/id_ed25519 -p 2222 root@localhost`
+   - In the VM, go to the shared mount and run DietPi Imager:
+     - `cd /mnt/images`
+     - `dietpi-imager`
+   - After imaging, shut down the VM:
+     - `shutdown`
+8) Store the image as the profile name (e.g., `images/profiles/dns-stack.img.xz`).
+
+## 2) Build a profile image (target workflow with profiles + first‑boot)
+1) Flash the golden base image to SD.
+2) Boot the Pi and install/configure services manually.
+3) Create or export the profile file locally: `profiles/<name>/profile.json`.
+   - Includes *additional* services and firewall ports only.
+   - Planned: export a profile from the running Pi (services + ufw) to avoid manual edits.
+4) Apply the profile to the Pi (planned script, optional if already configured):
+   - Writes `/etc/pikit/profile.json` (for first‑boot).
+   - Merges services into `/etc/pikit/services.json` (idempotent).
+5) Run the drift check (planned script):
+   - Confirms services + ports match the profile + base.
+6) Run the prep scrub:
+   - `sudo ./pikit-prep.sh`
+7) Image the SD card with DietPi Imager.
+
+First boot on the end‑user device will:
+- Regenerate unique identity + TLS certs.
+- Ensure the profile’s firewall ports are open (LAN‑only).
+- Show a progress overlay until complete.
+
+## 3) Flashing an image to SD
+Use the helper:
+- `sudo ./flash_sd.sh <image.img.xz> /dev/sdX`
+
+## Notes
+- Profiles are additive to the base image defaults; do not include Pi‑Kit or DietPi dashboard entries in profiles.
+- Keep `RESCUE.md` in `/root` and `/home/dietpi` only (not in `/var/www`).