Remove obsolete audio and buzzer control documentation files, including detailed guides and HTML interfaces, to streamline the repository and eliminate redundancy. This cleanup enhances maintainability and focuses on essential resources for the reTerminal DM4 audio and buzzer functionalities.

2026-02-20 15:39:39 +02:00
parent 9656771d5a
commit 58d9144752
101 changed files with 80 additions and 193 deletions
--- a/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md
+++ b/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md
@@ -0,0 +1,256 @@
+# eMMC provisioning for reTerminal DM4 (CM4)
+
+This guide covers:
+
+1. **USB boot mode**: When the reTerminal is in boot mode (eMMC disable jumper) and connected via USB, the host runs **rpiboot** to expose the eMMC, then the **dashboard** shows "Device connected (USB)". You choose **Backup** or **Deploy** in the portal — there is no auto-flash; the action runs only after your choice.
+2. **Network boot**: If the device boots over the network and runs the **provisioning client** (see `network-client/`), it registers with the dashboard and appears as "Device (Network)"; you then choose Backup or Deploy. Deploy streams the golden image to the device; Backup uploads the device eMMC to the server.
+3. **Cloud-init**: The golden image can include cloud-init so each device configures itself on first boot (hostname, network, packages, kiosk setup).
+
+---
+
+## Part 1: USB boot mode — detect device, choose Backup or Deploy in portal
+
+### How it works
+
+- reTerminal has an **eMMC disable** jumper (see reTerminal docs; often “J2” or “nRPIBOOT”). When the jumper is fitted, the CM4 boots in **USB device mode** and waits for `rpiboot` from the host.
+- You connect the reTerminal’s **USB slave** port to a **provisioning PC** (Linux).
+- **udev** detects the Raspberry Pi Foundation USB device (vendor `2b8e`) and runs a trigger script.
+- The trigger starts the **provisioning script** that:
+  1. Runs **rpiboot** (from the `usbboot` project). The CM4 then exposes its eMMC as a USB mass-storage device.
+  2. Finds the new block device (eMMC) and writes status so the **dashboard** shows "Device connected (USB boot mode). Choose Backup or Deploy in the dashboard."
+  3. **Waits for your choice in the portal** — no automatic flash. When you click **Backup** or **Deploy** in the dashboard, the script runs that action (dd backup or dd deploy).
+- You remove the jumper and power cycle; the reTerminal boots from eMMC and can run **cloud-init** on first boot.
+
+### Provisioning host setup (Linux)
+
+#### 1. Build and install usbboot (rpiboot)
+
+```bash
+sudo apt-get install -y libusb-1.0-0-dev
+git clone --depth=1 https://github.com/raspberrypi/usbboot
+cd usbboot
+make
+sudo mkdir -p /opt/usbboot
+sudo cp rpiboot /opt/usbboot/
+```
+
+#### 2. Create golden image and config directory
+
+- Build your golden image (see Part 2) and place it where the script will find it, e.g.:
+
+  ```bash
+  sudo mkdir -p /var/lib/cm4-provisioning
+  sudo cp /path/to/your/golden-reterminal.img /var/lib/cm4-provisioning/golden.img
+  ```
+
+- Or use a different path and set `GOLDEN_IMAGE` when installing the script (see below). On Proxmox with LXC, you can store backup images on a host directory by setting `CM4_BACKUPS_HOST_PATH` at deploy so that folder is bind-mounted into the LXC — see **PROXMOX-LXC-DEPLOYMENT.md** § Store backup images on a host directory.
+
+#### 3. Install the provisioning script and trigger
+
+```bash
+# From this repo (emmc-provisioning/host/)
+cd emmc-provisioning/host
+
+sudo mkdir -p /opt/cm4-provisioning
+sudo cp flash-emmc-on-connect.sh /opt/cm4-provisioning/
+sudo chmod +x /opt/cm4-provisioning/flash-emmc-on-connect.sh
+
+# Optional: override paths via environment (create env file)
+echo 'GOLDEN_IMAGE=/var/lib/cm4-provisioning/golden.img' | sudo tee /opt/cm4-provisioning/env
+echo 'RPIBOOT_DIR=/opt/usbboot' | sudo tee -a /opt/cm4-provisioning/env
+echo 'EMMC_SIZE_BYTES=8589934592' | sudo tee -a /opt/cm4-provisioning/env   # 8GB; use 17179869184 for 16GB
+# Optional: shrink backups after dd (requires PiShrink; see "Shrinking backup and golden images" below)
+# echo 'SHRINK_BACKUP=1' | sudo tee -a /opt/cm4-provisioning/env
+# echo 'PISHRINK_COMPRESS=gz' | sudo tee -a /opt/cm4-provisioning/env   # or xz
+
+sudo cp cm4-flash-trigger.sh /usr/local/bin/
+sudo chmod +x /usr/local/bin/cm4-flash-trigger.sh
+```
+
+If your golden image path or rpiboot path is different, set `GOLDEN_IMAGE`, `RPIBOOT_DIR`, and optionally `EMMC_SIZE_BYTES` in `/opt/cm4-provisioning/env` and source it from the script, or pass them into the systemd-run call in the trigger (e.g. by making the trigger source the env file and export variables before `systemd-run`).
+
+#### 4. Install udev rule
+
+```bash
+# From emmc-provisioning/host/
+sudo cp 90-cm4-boot-mode.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+#### 5. Enable provisioning (safety)
+
+Provisioning runs only if the “enabled” file exists:
+
+```bash
+sudo mkdir -p /etc/cm4-provisioning
+sudo touch /etc/cm4-provisioning/enabled
+```
+
+To disable provisioning (no device detection), remove that file: `sudo rm /etc/cm4-provisioning/enabled`.
+
+#### 6. Optional: pass environment into the provisioning job
+
+If you use `/opt/cm4-provisioning/env`, update the trigger so the flash script sees those variables. For example change `/usr/local/bin/cm4-flash-trigger.sh` to:
+
+```bash
+#!/usr/bin/env bash
+set -a
+[[ -f /opt/cm4-provisioning/env ]] && source /opt/cm4-provisioning/env
+set +a
+export GOLDEN_IMAGE RPIBOOT_DIR EMMC_SIZE_BYTES
+FLASH_SCRIPT="${CM4_FLASH_SCRIPT:-/opt/cm4-provisioning/flash-emmc-on-connect.sh}"
+exec systemd-run --no-block --unit=cm4-flash-once --property=Environment="GOLDEN_IMAGE=$GOLDEN_IMAGE" ...
+```
+
+Or keep it simple and edit the defaults inside `flash-emmc-on-connect.sh` (e.g. `GOLDEN_IMAGE`, `RPIBOOT_DIR`, `EMMC_SIZE_BYTES`).
+
+### Usage
+
+1. Fit the **eMMC disable** jumper on the reTerminal.
+2. Connect the reTerminal **USB slave** port to the provisioning PC.
+3. Power the reTerminal (or apply power after USB).
+4. On the host, `rpiboot` will run automatically; when it exits, the script will `dd` the golden image to the eMMC. Watch logs: `journalctl -u cm4-flash-once -f` or `journalctl -t cm4-flash -f`.
+5. When done, remove the jumper and power cycle the reTerminal. It will boot from eMMC; cloud-init will run on first boot.
+
+---
+
+## Part 2: Golden image with cloud-init
+
+Raspberry Pi OS (recent versions) supports **cloud-init** using the **NoCloud** datasource: it reads `user-data`, `meta-data`, and optionally `network-config` from the **boot** (FAT32) partition.
+
+### Steps to prepare a cloud-init image for Raspberry Pi OS
+
+1. **Obtain Raspberry Pi OS**
+   - Download from [raspberrypi.com/software](https://www.raspberrypi.com/software/) (desktop or Lite), or use **Raspberry Pi Imager** with "Edit settings" for locale/SSH. Recent Raspberry Pi OS has cloud-init built in.
+
+2. **Flash the image**
+   - Flash to a spare SD card, or to a loop file for building without physical media: `cp raspios.img golden-work.img`
+
+3. **Mount the boot partition**
+   - **From an image file**: `sudo losetup -fP golden-work.img` then e.g. `sudo mount /dev/loop0p1 /mnt/boot`
+   - **From SD**: mount the first (FAT32) partition at `/mnt/boot`. On a running Pi, boot is often `/boot/firmware`.
+
+4. **Add NoCloud files on the boot partition** (root of FAT32, same level as `config.txt`):
+   - `user-data`, `meta-data`, `network-config`
+   - From this repo: `cp emmc-provisioning/cloud-init/{user-data,meta-data,network-config} /mnt/boot/`
+
+5. **Customise** `user-data` and `network-config`. Use the **remote bootstrap script** pattern (below) to avoid rebuilding the image when you change first-boot commands.
+
+6. **Unmount and create golden image**: `sudo umount /mnt/boot`, then copy the image to your `GOLDEN_IMAGE` path (e.g. `/var/lib/cm4-provisioning/golden.img`).
+
+### Remote bootstrap script (no image rebuild for script changes)
+
+You can keep the golden image **fixed** and have cloud-init **download a script from a file server** and run it on first boot. When you change the script on the server, the next device gets the new commands without rebuilding the image.
+
+1. **Host the script** on an HTTP/HTTPS file server (e.g. nginx, or `python3 -m http.server`) at a URL the Pi can reach, e.g. `http://192.168.1.10/provisioning/bootstrap.sh`.
+
+2. **In `user-data`, use `runcmd` to download and run it** (runcmd runs after packages and network are up):
+
+   ```yaml
+   #cloud-config
+   package_update: true
+   package_upgrade: false
+   packages:
+     - curl   # or wget
+
+   runcmd:
+     - curl -fsSL "http://YOUR_FILE_SERVER/provisioning/bootstrap.sh" -o /tmp/bootstrap.sh
+     - chmod +x /tmp/bootstrap.sh
+     - /tmp/bootstrap.sh
+   ```
+
+   With **wget**: `wget -q -O /tmp/bootstrap.sh "http://.../bootstrap.sh"` then `chmod +x /tmp/bootstrap.sh` and `/tmp/bootstrap.sh`.
+
+3. **Bootstrap script**: use a normal shell script (e.g. `#!/bin/bash` and `set -e`). It can install packages, configure kiosk, set hostname, register with a dashboard, etc.
+
+4. **Notes**: Ensure `network-config` (or DHCP) gives the Pi an IP before runcmd. For HTTPS, add `ca-certificates` to `packages` if needed. You can use one script for all devices or have the script call your server with serial/MAC for device-specific config.
+
+### Creating the golden image
+
+1. **Flash Raspberry Pi OS** (or your base image) to a spare SD card or a loop file.
+2. **Mount the boot partition** (first partition, FAT32). On the image file it might be at an offset; use `losetup -P` or mount the SD’s partition.
+3. **Add cloud-init NoCloud files** on the boot partition (same level as `config.txt`, not in a subfolder for default NoCloud):
+   - `user-data` – main config (packages, runcmd, etc.)
+   - `meta-data` – optional (instance-id, local-hostname)
+   - `network-config` – optional (network config in netplan format)
+
+You can use the examples in this repo:
+
+```bash
+# After mounting boot partition at e.g. /mnt/boot
+# (On Raspberry Pi OS, boot is often /boot/firmware on the running system, or the first FAT partition of the image)
+cp emmc-provisioning/cloud-init/user-data /mnt/boot/
+cp emmc-provisioning/cloud-init/meta-data /mnt/boot/
+cp emmc-provisioning/cloud-init/network-config /mnt/boot/
+```
+
+4. **Customise** `user-data` and `network-config` (hostname, WiFi, packages, Chromium kiosk, or a single runcmd that downloads and runs a remote script—see "Remote bootstrap script" above).
+5. **Copy your kiosk/Chromium scripts** into the image rootfs only if you are not using a remote script; otherwise the remote script can pull what it needs.
+6. **Unmount**, then create a **golden image** from the SD or loop device (e.g. `dd` or copy of the whole block device). Use that as `golden.img` on the provisioning host. Optionally shrink it with PiShrink (see below) to save space and speed up deploy.
+
+### Shrinking backup and golden images (PiShrink)
+
+Raw full-disk backups and golden images are the full size of the eMMC (e.g. 32 GB). [PiShrink](https://github.com/Drewsif/PiShrink) shrinks the **last partition** (must be ext2/3/4) to its minimum size and truncates the image file; on first boot the rootfs can expand back to fill the device. This reduces backup/golden image size (often to a few GB) and improves transfer times.
+
+**On the provisioning host:**
+
+1. **Install PiShrink and dependencies** (run as root on the host, or via `ssh root@HOST 'bash -s' < scripts/install-pishrink-on-host.sh`):
+
+   ```bash
+   # From this repo (on the host or via ssh)
+   bash emmc-provisioning/scripts/install-pishrink-on-host.sh
+   ```
+
+   This installs `parted`, `e2fsprogs`, `gzip`, `pigz`, `xz-utils` and downloads `pishrink.sh` to `/usr/local/bin/pishrink.sh`.
+
+2. **Shrink backups automatically** after each Backup in the dashboard: add to `/opt/cm4-provisioning/env` and ensure the trigger sources it:
+
+   ```bash
+   echo 'SHRINK_BACKUP=1' | sudo tee -a /opt/cm4-provisioning/env
+   # Optional: compress after shrinking (smaller file; must decompress before using as golden image)
+   # echo 'PISHRINK_COMPRESS=gz' | sudo tee -a /opt/cm4-provisioning/env   # good balance
+   echo 'PISHRINK_COMPRESS=xz' | sudo tee -a /opt/cm4-provisioning/env   # minimum size (slower)
+   ```
+
+   With `SHRINK_BACKUP=1`, once a backup finishes, the script runs PiShrink on the `.img` file. Use **`PISHRINK_COMPRESS=xz`** for **minimum size** (smallest file, slower); or **`gz`** for a good balance. The file becomes `.img.xz` or `.img.gz` and must be decompressed before deploy (e.g. `xz -dk backup.img.xz` then copy to `golden.img`).
+
+3. **Shrink a golden image manually** (e.g. after building from Raspberry Pi OS):
+
+   ```bash
+   sudo pishrink.sh -n /path/to/large.img /var/lib/cm4-provisioning/golden.img
+   ```
+
+   `-n` disables update check. Omit the second argument to shrink in place. The shrunk image will expand the rootfs on first boot when deployed to eMMC.
+
+**Notes:**
+
+- PiShrink only shrinks the **last** partition; it must be ext2/3/4 (standard Raspberry Pi OS root is ext4).
+- Compressed backups (`.img.gz` / `.img.xz`) are for archival; to use as golden image, decompress first (e.g. `gunzip -k backup.img.gz` then copy to `golden.img`).
+- **Dashboard "Shrink" / "Compress"** buttons run PiShrink **on the host** (not in the LXC). The dashboard writes a request file; the host runs `run-shrink-on-host.sh` when `cm4-shrink.path` sees it. Ensure PiShrink is installed on the host (see above) and that deploy has installed `run-shrink-on-host.sh` and enabled `cm4-shrink.path`.
+
+### Cloud-init file locations on the Pi
+
+- **NoCloud**: Boot partition root – `user-data`, `meta-data`, `network-config`.
+- Some images expect them in a subfolder `cloud-init/` or on a separate vfat partition labeled `cidata`; check your OS docs. Standard Raspberry Pi OS NoCloud uses the boot partition root.
+
+### Per-device config (optional)
+
+NoCloud can also use a **seed** partition or **config drive**. For per-device hostname/settings you can:
+
+- Use **meta-data** `instance-id` and `local-hostname` and generate different `meta-data` per device when imaging (e.g. script that writes `meta-data` before flashing), or
+- Use a first-boot script that calls a provisioning server (e.g. by serial number) and applies device-specific config; cloud-init can launch that script from `runcmd`.
+
+---
+
+## Summary
+
+| Step | Action |
+|------|--------|
+| 1 | Build `usbboot`, install `rpiboot` on provisioning host. |
+| 2 | Create golden image with cloud-init `user-data`, `meta-data`, `network-config` on boot partition. |
+| 3 | Install `flash-emmc-on-connect.sh`, `cm4-flash-trigger.sh`, and udev rule; set `GOLDEN_IMAGE` and enable file. |
+| 4 | Put reTerminal in boot mode (jumper), connect USB to host; image is written automatically. |
+| 5 | Remove jumper, power cycle; device boots from eMMC and cloud-init runs on first boot. |
+
+This gives you automatic deployment of the golden image to eMMC when the reTerminal is in boot mode, plus first-boot configuration via cloud-init.
--- a/emmc-provisioning/docs/NETWORK-BOOT-LXC.md
+++ b/emmc-provisioning/docs/NETWORK-BOOT-LXC.md
@@ -0,0 +1,97 @@
+# Network boot on the provisioning LXC (eth1 = LAN, eth0 = WAN)
+
+The provisioning LXC can provide **network boot** (PXE-style) and **internet access** to devices connected on **eth1**, while **eth0** is used as WAN for the LXC itself.
+
+## Roles
+
+| Interface | Role | Typical config |
+|-----------|------|-----------------|
+| **eth0** | WAN | DHCP or static; default route; internet for the LXC |
+| **eth1** | LAN (provisioning) | Static e.g. `10.20.50.1/24`; DHCP server + TFTP server; NAT so clients get internet via eth0 |
+
+Devices plugged into the same network as **eth1** (e.g. reTerminals with network boot enabled) will:
+
+1. Get an IP via **DHCP** (from the LXC on eth1).
+2. Get **TFTP** boot files (Raspberry Pi firmware: `start4.elf`, `fixup4.dat`, kernel, etc.) for network boot.
+3. Have **internet** via NAT through the LXC (eth0).
+
+## What you need on the LXC
+
+1. **DHCP server** on eth1 only (e.g. **dnsmasq**), handing out addresses in e.g. `10.20.50.100`–`10.20.50.200` and advertising the TFTP server (next-server = LXC’s eth1 IP).
+2. **TFTP server** (dnsmasq can provide this) with **TFTP root** containing Raspberry Pi 4 / CM4 boot files.
+3. **IP forwarding** and **NAT** (nftables or iptables) so traffic from `10.20.50.0/24` is masqueraded out **eth0**.
+
+## One-time setup (inside the LXC)
+
+From your machine, run the setup script **on the LXC** (replace with your LXC IP if different):
+
+```bash
+# From the repo (script runs inside the LXC)
+./emmc-provisioning/scripts/setup-network-boot-on-lxc.sh root@10.130.60.141
+```
+
+Or SSH into the LXC and run the script there:
+
+```bash
+ssh root@10.130.60.141
+# Copy or rsync the emmc-provisioning tree into the container, then:
+bash /path/to/setup-network-boot-on-lxc.sh
+```
+
+The script will:
+
+- Install **dnsmasq** (DHCP + TFTP).
+- Configure dnsmasq to listen only on **eth1**, with a DHCP range and TFTP root.
+- Create `/srv/tftpboot` and **fetch Raspberry Pi 4 boot files from GitHub** (raspberrypi/firmware, `boot/` folder) if not already present.
+- Enable **IPv4 forwarding** and **NAT** (nftables) so clients on eth1 use eth0 for internet.
+- Enable and start the **dnsmasq** service.
+
+## Proxmox: adding eth1 to the LXC
+
+If you create the container by hand or want a second interface:
+
+1. On the **Proxmox host**, add a second network device to the container, e.g.:
+   ```bash
+   pct set <CTID> --net1 name=eth1,bridge=vmbr1,ip=10.20.50.1/24
+   ```
+   Use the bridge that corresponds to the physical LAN where reTerminals are connected (e.g. `vmbr1` or a dedicated provisioning bridge).
+
+2. Inside the LXC, ensure **eth1** has a static address (e.g. in `/etc/network/interfaces`):
+   ```
+   auto eth1
+   iface eth1 inet static
+       address 10.20.50.1/24
+   ```
+
+Your current LXC already has eth0 (10.130.60.141) and eth1 (10.20.50.1); the setup script only adds DHCP, TFTP, and NAT.
+
+## After setup: reTerminal network boot
+
+1. Set the reTerminal **boot order** to try network first (e.g. `BOOT_ORDER=0x21`; see cloud-init/first-boot).
+2. Connect the reTerminal to the **same network as the LXC’s eth1** (e.g. 10.20.50.0/24).
+3. Power on; it will get an IP via DHCP and load boot files via TFTP from the LXC.
+4. For **provisioning** (Backup/Deploy), the netboot environment must run **network-client/provisioning-client.sh** with `PROVISIONING_SERVER=http://10.20.50.1:5000` so it talks to the dashboard on the LXC.
+
+## TFTP boot files (Raspberry Pi 4 / CM4)
+
+The setup script **automatically downloads** the official Raspberry Pi firmware `boot/` folder from GitHub (https://github.com/raspberrypi/firmware) into `/srv/tftpboot` when `start4cd.elf` is missing. No manual copy is needed.
+
+To refresh or populate TFTP without re-running the full setup:
+
+```bash
+./emmc-provisioning/scripts/populate-tftpboot-from-git.sh root@<LXC-IP>
+```
+
+(Remove `/srv/tftpboot/start4cd.elf` on the LXC first if you want a full re-fetch.)
+
+The TFTP root contains e.g. `start4cd.elf`, `fixup4cd.dat`, `config.txt`, `cmdline.txt`, `kernel8.img`, and other boot files. For a custom kernel or initramfs (e.g. for provisioning), add or replace files in `/srv/tftpboot` and adjust `config.txt` / `cmdline.txt` as needed.
+
+## Summary
+
+| Component    | Where  | Purpose |
+|-------------|--------|--------|
+| eth0        | LXC    | WAN; LXC’s internet |
+| eth1        | LXC    | LAN; 10.20.50.1/24; DHCP + TFTP |
+| dnsmasq     | LXC    | DHCP (on eth1) + TFTP |
+| TFTP root   | LXC    | e.g. `/srv/tftpboot` with RPi boot files |
+| NAT         | LXC    | 10.20.50.0/24 → eth0 so LAN has internet |
--- a/emmc-provisioning/docs/PORTAL_STYLING_GUIDE.md
+++ b/emmc-provisioning/docs/PORTAL_STYLING_GUIDE.md
@@ -0,0 +1,292 @@
+# Portal Styling Guide (Template)
+
+Use this document when building new portals so they match the visual and UX style of the reference portal (e.g. FreePBX / TM VOIP Extensions Portal). Replace placeholders like `[Portal Name]` with your portal’s name where relevant.
+
+---
+
+## 1. Design philosophy
+
+- **Dark theme:** Dark backgrounds with light text; no light-mode variant in this guide.
+- **Accent:** Single accent (teal/cyan gradient) for primary actions, links, and highlights.
+- **Clarity:** Clear hierarchy (cards, sections, labels), consistent spacing, readable typography.
+- **Consistency:** Same tokens, components, and patterns across all pages (login, app, modals).
+
+---
+
+## 2. Design tokens (CSS variables)
+
+Define these in `:root` (or in a shared CSS file) and use them everywhere instead of hard-coded colors.
+
+### Colors
+
+| Token | Value | Usage |
+|-------|--------|--------|
+| `--bg-primary` | `#0a0e14` | Page background |
+| `--bg-secondary` | `#11151c` | Header, secondary surfaces |
+| `--bg-tertiary` | `#1a1f2b` | Inputs, table header, hover states |
+| `--bg-card` | `#151a24` | Cards, modals |
+| `--accent-primary` | `#00d4aa` | Primary accent (teal) |
+| `--accent-secondary` | `#00b894` | Accent variant, secondary accent |
+| `--accent-glow` | `rgba(0, 212, 170, 0.15)` | Focus rings, subtle highlights |
+| `--text-primary` | `#e6e8eb` | Main text |
+| `--text-secondary` | `#8b949e` | Labels, secondary text |
+| `--text-muted` | `#5c6370` | Placeholders, disabled, hints |
+| `--border-color` | `#2d333b` | Borders (cards, inputs, tables) |
+| `--danger` | `#ff6b6b` | Errors, delete, destructive actions |
+| `--danger-glow` | `rgba(255, 107, 107, 0.15)` | Danger focus/hover background |
+| `--warning` | `#ffd93d` | Warnings |
+| `--success` | `#00d4aa` | Success (can match accent) |
+| `--gradient-accent` | `linear-gradient(135deg, #00d4aa 0%, #00b894 50%, #00cec9 100%)` | Primary buttons, logo text |
+
+### Example `:root` block
+
+```css
+:root {
+    --bg-primary: #0a0e14;
+    --bg-secondary: #11151c;
+    --bg-tertiary: #1a1f2b;
+    --bg-card: #151a24;
+    --accent-primary: #00d4aa;
+    --accent-secondary: #00b894;
+    --accent-glow: rgba(0, 212, 170, 0.15);
+    --text-primary: #e6e8eb;
+    --text-secondary: #8b949e;
+    --text-muted: #5c6370;
+    --border-color: #2d333b;
+    --danger: #ff6b6b;
+    --danger-glow: rgba(255, 107, 107, 0.15);
+    --warning: #ffd93d;
+    --success: #00d4aa;
+    --gradient-accent: linear-gradient(135deg, #00d4aa 0%, #00b894 50%, #00cec9 100%);
+}
+```
+
+---
+
+## 3. Typography
+
+- **Body / UI font:** `'Outfit', -apple-system, BlinkMacSystemFont, sans-serif`
+- **Monospace (data, code, IDs):** `'JetBrains Mono', monospace`
+
+Load from Google Fonts:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+```
+
+- **Body:** `color: var(--text-primary);` `line-height: 1.6;`
+- **Labels:** `font-size: 0.85rem;` `font-weight: 500;` `color: var(--text-secondary);` optional `text-transform: uppercase;` `letter-spacing: 0.5px;`
+- **Card/section titles:** `font-size: 1.1rem;` `font-weight: 600;`
+- **Table header:** `font-size: 0.75rem–0.8rem;` `font-weight: 600;` `text-transform: uppercase;` `letter-spacing: 0.5px;` `color: var(--text-secondary);`
+- **Table body:** `font-size: 0.9rem;` monospace for IDs/codes
+
+---
+
+## 4. Page layout
+
+### Global
+
+- **Reset:** `* { margin: 0; padding: 0; box-sizing: border-box; }`
+- **Body:** `background: var(--bg-primary);` `color: var(--text-primary);` `min-height: 100vh;` `font-family: 'Outfit', ...`
+
+### Background treatment (optional)
+
+Subtle gradient overlay for depth:
+
+```css
+body::before {
+    content: '';
+    position: fixed;
+    inset: 0;
+    background:
+        radial-gradient(circle at 20% 20%, rgba(0, 212, 170, 0.03) 0%, transparent 50%),
+        radial-gradient(circle at 80% 80%, rgba(0, 184, 148, 0.03) 0%, transparent 50%),
+        linear-gradient(180deg, var(--bg-primary) 0%, var(--bg-secondary) 100%);
+    pointer-events: none;
+    z-index: -1;
+}
+```
+
+### Header (fixed)
+
+- **Container:** `background: var(--bg-secondary);` `border-bottom: 1px solid var(--border-color);` `position: fixed; top: 0; left: 0; right: 0; z-index: 1000;` optional `backdrop-filter: blur(10px);`
+- **Top row:** Logo left; status/user/actions right; `padding: 1rem 2rem;` `display: flex; align-items: center; justify-content: space-between;`
+- **Tabs row:** Under the top row; `background: var(--bg-tertiary);` `padding: 0.5rem 2rem;` `border-top: 1px solid var(--border-color);` horizontal flex, gap, overflow-x auto for small screens
+
+### Main content
+
+- **Container:** `max-width: 1400px;` `margin: 0 auto;` `padding: 2rem;` `padding-top: calc(2rem + 140px);` (offset for fixed header + tabs). On mobile reduce padding and increase top offset if header stacks.
+
+---
+
+## 5. Logo
+
+- **Wrapper:** flex, `align-items: center;` `gap: 0.75rem;`
+- **Icon:** Square (e.g. 40×40px), `background: var(--gradient-accent);` `border-radius: 10px;` optional `box-shadow: 0 4px 20px var(--accent-glow);` emoji or icon inside.
+- **Title (h1):** `font-size: 1.5rem;` `font-weight: 600;` `background: var(--gradient-accent);` `-webkit-background-clip: text;` `background-clip: text;` `-webkit-text-fill-color: transparent;`
+
+---
+
+## 6. Tabs (main navigation)
+
+- **Tab button (default):** `padding: 0.75rem 1.5rem;` `background: transparent;` `border: none;` `color: var(--text-secondary);` `font-size: 0.95rem;` `font-weight: 500;` `border-radius: 8px;` flex with icon + label, `gap: 0.5rem;`
+- **Hover:** `color: var(--text-primary);` `background: var(--bg-tertiary);`
+- **Active:** `background: var(--gradient-accent);` `color: var(--bg-primary);`
+- **Tab content:** `display: none;` by default; `.tab-content.active { display: block; }` optional fade-in animation.
+
+---
+
+## 7. Cards
+
+- **Base:** `background: var(--bg-card);` `border: 1px solid var(--border-color);` `border-radius: 16px;` `padding: 1.5rem;` `margin-bottom: 1.5rem;`
+- **Card header:** flex, `justify-content: space-between;` `align-items: center;` `margin-bottom: 1.5rem;` `padding-bottom: 1rem;` `border-bottom: 1px solid var(--border-color);`
+- **Card title:** `font-size: 1.1rem;` `font-weight: 600;` flex with icon + text, `gap: 0.5rem;`
+
+---
+
+## 8. Buttons
+
+- **Base:** `padding: 0.75rem 1.5rem;` `border-radius: 8px;` `font-size: 0.9rem;` `font-weight: 500;` inline-flex, `align-items: center;` `gap: 0.5rem;` `transition: all 0.2s ease;`
+- **Primary:** `background: var(--gradient-accent);` `color: var(--bg-primary);` `border: none;` hover: slight `translateY(-2px);` `box-shadow: 0 4px 20px var(--accent-glow);`
+- **Secondary:** `background: var(--bg-tertiary);` `border: 1px solid var(--border-color);` `color: var(--text-primary);` hover: `border-color: var(--accent-primary);`
+- **Danger:** `background: transparent;` `border: 1px solid var(--danger);` `color: var(--danger);` hover: `background: var(--danger);` `color: white;`
+- **Disabled:** `opacity: 0.5;` `cursor: not-allowed;`
+- **Icon-only (small):** e.g. 28×28px, `border-radius: 6px;` same semantic colors (e.g. `.btn-remove` with `--danger`).
+
+---
+
+## 9. Forms
+
+- **Grid:** `display: grid;` `grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));` `gap: 1rem;`
+- **Form group:** flex column, `gap: 0.5rem;`
+- **Label:** `font-size: 0.85rem;` `font-weight: 500;` `color: var(--text-secondary);` optional uppercase + letter-spacing
+- **Input / select:** `padding: 0.75rem 1rem;` `background: var(--bg-tertiary);` `border: 1px solid var(--border-color);` `border-radius: 8px;` `color: var(--text-primary);` `font-size: 0.9rem;` monospace for IDs/codes
+- **Focus:** `outline: none;` `border-color: var(--accent-primary);` `box-shadow: 0 0 0 3px var(--accent-glow);`
+- **Placeholder:** `color: var(--text-muted);`
+- **Read-only:** `background: var(--bg-secondary);` `cursor: default;`
+- **Checkbox:** `accent-color: var(--accent-primary);` (or custom size e.g. 18×18px)
+- **Password field:** wrapper with toggle button; input `padding-right: 3rem;` so toggle doesn’t overlap text.
+
+---
+
+## 10. Tables
+
+- **Container:** `overflow-x: auto;` `border-radius: 12px;` `border: 1px solid var(--border-color);`
+- **Table:** `width: 100%;` `border-collapse: collapse;`
+- **th / td:** `padding: 0.6rem 0.75rem;` `text-align: left;` `border-bottom: 1px solid var(--border-color);` `color: var(--text-primary);`
+- **th:** `background: var(--bg-tertiary);` `font-size: 0.75rem;` `font-weight: 600;` `text-transform: uppercase;` `letter-spacing: 0.5px;`
+- **tbody tr hover:** `background-color: var(--bg-tertiary);`
+- **Last row:** `tr:last-child td { border-bottom: none; }`
+- **Data cells:** `font-family: 'JetBrains Mono', monospace;` `font-size: 0.9rem;`
+- **Actions column:** right-aligned; min-width for action buttons; `.table-actions { display: flex; gap: 1rem; flex-wrap: wrap; }`
+- **Data table variant:** `.data-table` with alternating row background (e.g. `nth-child(even)` subtle `rgba(255,255,255,0.02)`) and same hover.
+
+---
+
+## 11. Badges and status
+
+- **Status badge (e.g. connection):** flex, `align-items: center;` `gap: 0.5rem;` `padding: 0.5rem 1rem;` `background: var(--bg-tertiary);` `border-radius: 20px;` `font-size: 0.85rem;` `border: 1px solid var(--border-color);`
+- **Status dot:** 8×8px circle; `.connected { background: var(--success); }` `.error { background: var(--danger); }` optional pulse animation
+- **Pill badge (e.g. extension ID):** `padding: 0.25rem 0.75rem;` `background: var(--accent-glow);` `color: var(--accent-primary);` `border-radius: 20px;` `font-weight: 500;`
+- **Tech badge (e.g. PJSIP/SIP):** small, `border-radius: 4px;` `font-size: 0.75rem;` `font-weight: 600;` `text-transform: uppercase;` distinct colors per type (e.g. PJSIP blue, SIP purple)
+
+---
+
+## 12. Search and filters
+
+- **Search box:** wrapper relative; input `padding: 0.6rem 1rem 0.6rem 2.5rem;` `width: 250px;` same colors as form inputs; optional `::before` search icon (e.g. 🔍) `left: 0.75rem;`
+- **Filter checkbox:** inline-flex, `align-items: center;` `gap: 0.4rem;` `color: var(--text-secondary);` `accent-color: var(--accent-primary);`
+
+---
+
+## 13. Empty and loading states
+
+- **Empty state:** `text-align: center;` `padding: 3rem;` `color: var(--text-muted);`
+- **No results:** same idea, `padding: 2rem;`
+- **Loading:** flex center, `padding: 2rem;` spinner (e.g. 32×32px border, `border-top-color: var(--accent-primary);` `animation: spin 1s linear infinite;`)
+
+---
+
+## 14. Modals
+
+- **Overlay:** `position: fixed;` `inset: 0;` `background: rgba(0,0,0,0.7);` `z-index: 1000;` flex center; `display: none;` `.active { display: flex; }`
+- **Dialog:** `background: var(--bg-card);` `border: 1px solid var(--border-color);` `border-radius: 16px;` `padding: 2rem;` `max-width: 500px;` `width: 90%;` optional scale-in animation
+- **Modal header:** flex, `align-items: center;` `gap: 1rem;` `margin-bottom: 1.5rem;`
+- **Modal icon:** e.g. 48×48px, `background: var(--accent-glow);` `border-radius: 12px;` centered content
+- **Modal title:** `font-size: 1.25rem;` `font-weight: 600;`
+- **Detail sections:** `margin-bottom: 2rem;` section title `font-size: 1.1rem;` `color: var(--accent-primary);` `border-bottom: 1px solid var(--border-color);` `padding-bottom: 0.5rem;`
+- **Details grid:** `grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));` `gap: 1rem;` each item: label (small, secondary) + value (primary)
+
+---
+
+## 15. Toasts (notifications)
+
+- **Container:** `position: fixed;` `top: 1rem;` `right: 1rem;` `z-index: 1100;` flex column, `gap: 0.5rem;`
+- **Toast:** `padding: 1rem 1.5rem;` `background: var(--bg-card);` `border: 1px solid var(--border-color);` `border-radius: 8px;` flex, `align-items: center;` `gap: 0.75rem;` `max-width: 400px;` slide-in animation
+- **Success:** `border-left: 3px solid var(--success);`
+- **Error:** `border-left: 3px solid var(--danger);`
+
+---
+
+## 16. Pagination
+
+- **Wrapper:** flex, `justify-content: center;` `align-items: center;` `gap: 0.5rem;` `padding: 1rem;` `border-top: 1px solid var(--border-color);`
+- **Button:** `padding: 0.5rem 0.75rem;` `background: var(--bg-tertiary);` `border: 1px solid var(--border-color);` `border-radius: 6px;` `color: var(--text-primary);` `font-size: 0.85rem;` `min-width: 36px;`
+- **Hover:** `background: var(--accent-glow);` `border-color: var(--accent-primary);` `color: var(--accent-primary);`
+- **Active page:** `background: var(--accent-primary);` `color: var(--bg-primary);`
+- **Disabled:** `opacity: 0.4;` `cursor: not-allowed;`
+- **Info text:** `color: var(--text-secondary);` `font-size: 0.85rem;` between prev/next
+
+---
+
+## 17. Login page
+
+- **Layout:** full viewport, flex center; `padding: 2rem;`
+- **Card:** same tokens as app cards; `max-width: 400px;` `padding: 2.5rem;` `border-radius: 16px;` `box-shadow: 0 8px 32px rgba(0,0,0,0.3);`
+- **Logo:** centered; icon (e.g. 64×64px) with gradient + glow; title with gradient text
+- **Form:** same form-group and input styles as app; full-width primary submit button
+- **Error message:** `color: var(--danger);` `font-size: 0.9rem;` above or below form
+- Use the same `:root` variables and body background so login and app feel like one product.
+
+---
+
+## 18. Responsive
+
+- **Breakpoint:** e.g. `@media (max-width: 768px)`
+- **Header top:** `flex-direction: column;` `gap: 1rem;` `text-align: center;` reduce padding
+- **Tabs:** reduce horizontal padding; allow horizontal scroll if needed
+- **Container:** reduce padding; increase `padding-top` if header height grows (e.g. `calc(1rem + 180px)`)
+- **Form grid:** `grid-template-columns: 1fr;` for single column on small screens
+
+---
+
+## 19. Checklist for a new portal
+
+- [ ] Copy or recreate the `:root` design tokens.
+- [ ] Load **Outfit** and **JetBrains Mono** (or same weights).
+- [ ] Use the same header structure: logo + status/user + actions, then tabs.
+- [ ] Use `.card`, `.card-header`, `.card-title` for sections.
+- [ ] Use `.btn`, `.btn-primary`, `.btn-secondary`, `.btn-danger` for actions.
+- [ ] Use `.form-grid`, `.form-group`, and input/select styles for forms.
+- [ ] Use `.table-container`, table, `.data-table` and th/td styles for lists.
+- [ ] Use same modal overlay/dialog and toast styles.
+- [ ] Use same empty, loading, and error states.
+- [ ] Apply same login page layout and token usage.
+- [ ] Test at 768px width for basic responsive behavior.
+- [ ] Replace [Portal Name] and any product-specific labels in this guide for your portal.
+
+---
+
+## 20. Reference files (this repo)
+
+| File | Purpose |
+|------|--------|
+| `static/css/main.css` | Full implementation of tokens, layout, components |
+| `app/templates/base.html` | App shell: fonts, header, tabs, container, toasts |
+| `app/templates/login.html` | Login layout and inline tokens (can be moved to main.css) |
+| `app/templates/tabs/_dashboard.html` | Example: cards, stats, table container |
+| `app/templates/tabs/_users.html` | Example: card, form-grid, form-group, buttons, table |
+
+For a new portal, you can copy `main.css` and adapt it (e.g. change `:root` if you need a different accent), then build your base template and pages to use the same class names and structure described above.
--- a/emmc-provisioning/docs/PROXMOX-LXC-DEPLOYMENT.md
+++ b/emmc-provisioning/docs/PROXMOX-LXC-DEPLOYMENT.md
@@ -0,0 +1,248 @@
+# CM4 eMMC provisioning on Proxmox (LXC + host)
+
+The auto-flash **runs on the Proxmox host** (where the USB device appears). The **LXC** holds the dashboard and shares the **golden image** directory with the host.
+
+## One-command deploy
+
+From your repo, a single run deploys **all** host and LXC files (scripts, systemd units, udev, dashboard):
+
+```bash
+./emmc-provisioning/scripts/deploy-to-proxmox.sh root@YOUR_PROXMOX_HOST
+```
+
+Optional env: `CM4_BACKUPS_HOST_PATH=/path`, `DEPLOY_ROOTFS_STORAGE=local-lvm`, `DEPLOY_LXC_ROOT_PASSWORD=secret` (set root password in LXC and enable SSH), `DEPLOY_LXC_SSH_KEY=/path/to/pub` (default: `~/.ssh/id_ed25519.pub` or `id_rsa.pub` — copied to LXC root so you can `ssh root@<LXC-IP>`).
+
+The script **finds the container by hostname `cm4-provisioning`** (any existing ID). If none exists, it **creates a new LXC with the next available ID**. So you can redeploy repeatedly without assuming a fixed ID like 201.
+
+## What is deployed
+
+| Where | What |
+|-------|-----|
+| **Proxmox host** | udev rule, trigger script, flash script, build-cloudinit and run-shrink scripts, systemd path units (build + shrink), `/var/lib/cm4-provisioning/`, `/etc/cm4-provisioning/enabled` |
+| **LXC (hostname cm4-provisioning)** | Dashboard (Flask) in `/opt/cm4-provisioning/dashboard/`; `/var/lib/cm4-provisioning/` is a **bind mount** from the host (shared storage for golden image and backups) |
+
+When you plug the reTerminal in boot mode into the **host**, udev on the host runs the flash (rpiboot + dd). The golden image is read from `/var/lib/cm4-provisioning/golden.img` on the host (same path visible in the LXC).
+
+---
+
+## Deployment layout (after running the deploy script)
+
+1. **LXC** (hostname `cm4-provisioning`, ID = found by hostname or next free):
+   - Debian 12, 1 GB RAM, 8 GB rootfs
+   - Bind mount: host `/var/lib/cm4-provisioning` → container `/var/lib/cm4-provisioning`
+   - Optional second mount: `CM4_BACKUPS_HOST_PATH` → container `/var/lib/cm4-provisioning/backups`
+
+2. **On the host**:
+   - `/opt/cm4-provisioning/flash-emmc-on-connect.sh` – flash script
+   - `/opt/cm4-provisioning/build-cloudinit-image.sh` – build cloud-init image (triggered by path unit)
+   - `/opt/cm4-provisioning/run-shrink-on-host.sh` – PiShrink for dashboard Shrink/Compress
+   - `/usr/local/bin/cm4-flash-trigger.sh` – started by udev
+   - `/etc/udev/rules.d/90-cm4-boot-mode.rules` – run trigger when USB vendor `2b8e` is added
+   - `/opt/cm4-provisioning/env` – `GOLDEN_IMAGE`, `RPIBOOT_DIR`, `EMMC_SIZE_BYTES` (and `BACKUPS_DIR` if `CM4_BACKUPS_HOST_PATH` set)
+   - `/etc/cm4-provisioning/enabled` – safety switch (remove to disable auto-flash)
+   - systemd: `cm4-build-cloudinit.path` + `.service`, `cm4-shrink.path` + `.service`
+   - `/opt/cm4-provisioning/fix-gadget-bootcode-on-host.sh` – used by `install-usbboot-on-host.sh` after building usbboot (fixes "rpiboot gadget empty" when gadget has broken symlinks)
+
+3. **Inside the LXC** (use `pct exec <CTID> -- ...` where `<CTID>` is the ID of the container with hostname `cm4-provisioning`; get it with `pct list`):
+   - Dashboard: Flask app in `/opt/cm4-provisioning/dashboard/` (monitor deployment, backup list, build cloud-init, set golden).
+   - Golden image path: `/var/lib/cm4-provisioning/golden.img` (bind-mounted from host).
+
+4. **usbboot (rpiboot)** is **not** installed by the deploy script. Install it when the host has internet (see below).
+
+---
+
+## What you need to do
+
+### 1. Build and install rpiboot on the Proxmox host (when it has internet)
+
+On your machine (repo already synced to the host):
+
+```bash
+# From your repo
+scp emmc-provisioning/scripts/install-usbboot-on-host.sh root@10.130.60.224:/tmp/
+ssh root@10.130.60.224 "bash /tmp/install-usbboot-on-host.sh"
+```
+
+Or on the host (if the deploy folder is still there):
+
+```bash
+ssh root@10.130.60.224
+bash /tmp/emmc-provisioning-deploy/scripts/install-usbboot-on-host.sh
+```
+
+This installs dependencies, clones usbboot, builds it, and copies `rpiboot` to `/opt/usbboot/`. It then runs **fix-gadget-bootcode-on-host.sh** if present (from deploy), so the gadget has valid boot files and rpiboot does not fail with "No bootcode files found".
+
+### 2. Enable root SSH and add your SSH key to the LXC
+
+If you deployed with **`DEPLOY_LXC_ROOT_PASSWORD`** and/or a default SSH key (**`~/.ssh/id_ed25519.pub`** or **`id_rsa.pub`**), the LXC already has SSH enabled, root password set, and your key in `/root/.ssh/authorized_keys` — you can **skip** to `ssh root@<LXC-IP>` (get IP from deploy output or `pct exec <CTID> -- hostname -I`).
+
+Otherwise, to enable root SSH and add a key:
+
+- **Option A – Use the setup script (recommended):** From your machine (with SSH key and optional password):
+
+  ```bash
+  # Add your default SSH key (~/.ssh/id_ed25519.pub or id_rsa.pub) and enable root SSH
+  ./emmc-provisioning/scripts/setup-lxc-ssh.sh root@10.130.60.224
+
+  # Or specify key file and set root password
+  ROOT_PASSWORD='YourPassword' ./emmc-provisioning/scripts/setup-lxc-ssh.sh root@10.130.60.224 ~/.ssh/id_ed25519.pub
+  ```
+
+  Then connect with `ssh root@<LXC-IP>` (script prints the IP). To get the LXC IP:  
+  `ssh root@HOST "CID=\$(pct list -no-header -output vmid,name | awk '\''\$2==\"cm4-provisioning\"{print \$1}'\''); pct exec \$CID -- hostname -I"`
+
+- **Option B – Manual:**  
+  `ssh root@HOST`, then `pct exec <CTID> -- bash` (use the container ID from `pct list` for hostname cm4-provisioning). Install openssh-server, set `PermitRootLogin yes`, set root password, add your key, restart ssh.
+
+### 3. (Optional) Store backup images on a host directory
+
+To keep backup images on a specific host path (e.g. a large disk or NFS mount) instead of under `/var/lib/cm4-provisioning/backups`, deploy with **`CM4_BACKUPS_HOST_PATH`** set. That directory is created on the host, bind-mounted into the LXC at `/var/lib/cm4-provisioning/backups`, and the host flash script is configured to write backups there. The dashboard in the LXC then lists and serves those same files.
+
+**Deploy with a host backup path:**
+
+```bash
+CM4_BACKUPS_HOST_PATH=/mnt/storage/cm4-backups ./emmc-provisioning/scripts/deploy-to-proxmox.sh root@10.130.60.224
+```
+
+Create `/mnt/storage/cm4-backups` (or your path) on the host first if it doesn’t exist; the deploy script will create it if possible. To add or change the backup mount, set `CM4_BACKUPS_HOST_PATH` and run the deploy script again (it reuses the container by hostname and updates the bind mount).
+
+### 4. Put the golden image on the host (or in the LXC)
+
+The image must be at **`/var/lib/cm4-provisioning/golden.img`** on the **host**. Because that directory is bind-mounted into the LXC, you can use either:
+
+- **From the host:**
+  ```bash
+  scp your-golden.img root@10.130.60.224:/var/lib/cm4-provisioning/golden.img
+  ```
+
+- **From the LXC** (e.g. after copying the image into the container elsewhere first):
+  ```bash
+  pct exec <CTID> -- ls -la /var/lib/cm4-provisioning/
+  # Replace <CTID> with the ID of the cm4-provisioning container (pct list).
+  ```
+
+### 5. Run the provisioning dashboard (optional)
+
+The dashboard shows **connection steps** and **live deployment status** (idle / connecting / flashing / done / error) and a recent flash log. It reads the same `status.json` and `flash.log` that the host’s flash script writes (via the bind-mounted `/var/lib/cm4-provisioning`).
+
+**Inside the LXC (pct exec <CTID> -- bash):**
+
+```bash
+# Copy dashboard into the container (from host, if you have the repo there)
+# Or from your workstation:
+#   rsync -a emmc-provisioning/dashboard/ root@10.130.60.224:/tmp/dashboard/
+#   Or re-run deploy-to-proxmox.sh to push the latest dashboard files.
+
+# Inside the LXC (pct exec <CTID> -- bash):
+apt-get update && apt-get install -y python3-flask
+mkdir -p /opt/cm4-provisioning/dashboard/templates
+# Copy app.py, templates/index.html, cm4-dashboard.service into the container (see dashboard/README.md)
+
+cp /opt/cm4-provisioning/dashboard/cm4-dashboard.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now cm4-dashboard
+```
+
+Then open **http://&lt;LXC-IP&gt;:5000** (get the IP with `pct exec <CTID> -- hostname -I`). If the LXC is on a private network, set up port forwarding on the Proxmox host or use a reverse proxy.
+
+### 6. Optional: disable or enable auto-flash
+
+- **Disable:**  
+  `ssh root@10.130.60.224 "rm /etc/cm4-provisioning/enabled"`
+
+- **Enable again:**  
+  `ssh root@10.130.60.224 "touch /etc/cm4-provisioning/enabled"`
+
+---
+
+## Usage
+
+1. Place the reTerminal in **boot mode** (eMMC disable jumper).
+2. Connect its **USB slave** port to the **Proxmox host** (not to the LXC).
+3. Power the reTerminal (or connect after power).
+4. On the host, udev will run the trigger and then the flash script (rpiboot, then dd). Watch logs:
+   ```bash
+   ssh root@10.130.60.224 "journalctl -u cm4-flash-once -f"
+   # or
+   ssh root@10.130.60.224 "journalctl -t cm4-flash -f"
+   ```
+5. When flashing finishes, remove the jumper and power cycle the reTerminal so it boots from eMMC.
+
+---
+
+## Monitoring from the host
+
+From the **Proxmox host** you can monitor:
+
+| What | How |
+|------|-----|
+| **USB device** | `lsusb` — CM4 in boot mode shows as **2b8e** (RPi) or **0a5c:2711** (Broadcom BCM2711) |
+| **Live status** | `cat /var/lib/cm4-provisioning/status.json` — same JSON the dashboard shows (phase, message, error) |
+| **Flash log** | `tail -f /var/lib/cm4-provisioning/flash.log` — script log (rpiboot, dd, errors) |
+| **Flash job** | `systemctl status cm4-flash-once` — whether the udev-triggered job is running/failed |
+| **Journal** | `journalctl -u cm4-flash-once -f` or `journalctl -t cm4-flash -f` — systemd/log output |
+| **Block devices** | `lsblk` — after rpiboot, the eMMC appears as a new disk (e.g. `/dev/sdb`) |
+| **Backups** | `ls /var/lib/cm4-provisioning/backups/` — backup images (on host; if you used `CM4_BACKUPS_HOST_PATH` they are under that path on the host, bind-mounted into the LXC). To shrink automatically, set `SHRINK_BACKUP=1` in `/opt/cm4-provisioning/env` — see **EMMC-PROVISIONING-GUIDE.md** § Shrinking backup and golden images. |
+| **Config** | `cat /opt/cm4-provisioning/env` — GOLDEN_IMAGE, RPIBOOT_DIR, EMMC_SIZE_BYTES |
+
+**One-command snapshot:**
+
+```bash
+# From your machine (stream script to host):
+ssh root@10.130.60.224 'bash -s' < emmc-provisioning/scripts/monitor-from-host.sh
+```
+
+Or copy `scripts/monitor-from-host.sh` to the host and run `./monitor-from-host.sh` for a full status dump (USB, status.json, flash unit, last log lines, block devices, config).
+
+---
+
+## Troubleshooting: device connected but not shown in portal
+
+1. **Host has old flash script** – The script must *not* exit when the golden image is missing (so you can use Backup first). Update the host:
+   ```bash
+   scp emmc-provisioning/host/flash-emmc-on-connect.sh root@10.130.60.224:/opt/cm4-provisioning/
+   ssh root@10.130.60.224 "chmod +x /opt/cm4-provisioning/flash-emmc-on-connect.sh"
+   ```
+
+2. **Unplug and replug the USB** – udev runs the trigger only when the device is *added*. Unplug the reTerminal USB (keep it in boot mode), then plug it back in. The trigger will run the script and rpiboot; when the eMMC is exposed, the portal shows "Device connected" with Backup/Deploy.
+
+3. **If rpiboot fails** – Check on the host: `ssh root@10.130.60.224 'tail -30 /var/lib/cm4-provisioning/flash.log'` (rpiboot stderr is appended there). Try unplug/replug again. To see the exact rpiboot error: `ssh root@10.130.60.224 '/opt/usbboot/rpiboot -d /opt/usbboot/mass-storage-gadget64'` (device connected; Ctrl+C to stop). Run `scripts/monitor-from-host.sh` for a full snapshot.
+
+4. **"No 'bootcode' files found in mass-storage-gadget64"** – Usually because `bootfiles.bin` is a **broken symlink** (e.g. `-> ../firmware/bootfiles.bin`) and that target doesn’t exist. **Fix on host:** run `scripts/fix-gadget-bootcode-on-host.sh` on the host (it removes the symlink and extracts `bootcode4.bin` from the installed rpiboot binary). From your machine: `ssh root@10.130.60.224 'bash -s' < scripts/fix-gadget-bootcode-on-host.sh`. **Alternative:** repopulate the gadget dir with `./scripts/populate-gadget-on-host.sh root@10.130.60.224`, or full reinstall with `./scripts/build-and-deploy-usbboot-to-host.sh root@10.130.60.224`. Then verify: `ls -la /opt/usbboot/mass-storage-gadget64/` (should list a real `bootcode4.bin` or `bootfiles.bin`, plus `boot.img`, `config.txt`).
+
+4. **Clear stuck error in portal** – If the portal shows an old error (e.g. "Golden image not found" or "rpiboot failed"), click **Clear message** in the dashboard, or: `ssh root@10.130.60.224 "echo '{\"phase\":\"idle\",\"message\":\"Waiting for reTerminal in boot mode or network.\",\"progress\":null}' > /var/lib/cm4-provisioning/status.json"`. Then unplug/replug the device.
+
+5. **"PiShrink not installed" when clicking Shrink/Compress** – Shrink and Compress run **on the host**, not in the LXC. Install PiShrink on the host: `ssh root@HOST 'bash -s' < emmc-provisioning/scripts/install-pishrink-on-host.sh`. Ensure deploy has been run so the host has `run-shrink-on-host.sh` and `cm4-shrink.path` enabled (`systemctl status cm4-shrink.path`).
+
+6. **"Download failed" when building cloud-init image** – The download runs on the **host** (not the LXC). Check: (1) Host can reach the internet: `ssh root@HOST 'curl -sI https://downloads.raspberrypi.com/'`. (2) Build status now shows curl’s error (e.g. "Could not resolve host", "Connection timed out"); check the dashboard error text. (3) If you use a proxy or custom CA, set in `/opt/cm4-provisioning/env`: `CURL_INSECURE=1` to skip SSL verify (only if you understand the risk), then rerun the build.
+
+7. **Backup stops before finishing** – If backup or shrink appears to stop partway (e.g. dashboard stuck on "Creating backup…" or "Shrinking…"), the service may have been killed by systemd. The `cm4-flash.service` unit uses `TimeoutStartSec=7200` (2 hours); if you deployed an older version with 15 minutes, redeploy so the host gets the updated unit, then on the host run `systemctl daemon-reload` so the next backup has enough time to complete.
+
+8. **Trigger now runs the flash script in the background** (not via systemd-run) so it can access the USB device; a 2s delay gives the device time to enumerate before rpiboot runs.
+
+---
+
+## Redeploy / update scripts
+
+From your repo (e.g. after changing scripts):
+
+```bash
+./emmc-provisioning/scripts/deploy-to-proxmox.sh root@10.130.60.224
+```
+
+That script syncs the repo to the host and reinstalls scripts on both the host and LXC 201. It does **not** overwrite `/opt/cm4-provisioning/env` or `/etc/cm4-provisioning/enabled` if you’ve changed them; adjust the script if you want that. It also does **not** build usbboot; run `install-usbboot-on-host.sh` on the host when needed.
+
+---
+
+## Summary
+
+| Item | Location |
+|------|----------|
+| LXC | Hostname `cm4-provisioning` (ID from `pct list`), on your Proxmox host |
+| Golden image | `/var/lib/cm4-provisioning/golden.img` (host and LXC see the same file) |
+| Flash runs on | Proxmox **host** (udev + rpiboot + dd) |
+| Build rpiboot on host | Run `scripts/install-usbboot-on-host.sh` on the host when it has internet |
+| Dashboard | Flask app in LXC at `http://<LXC-IP>:5000`; switch Flash/Backup mode, list and download backups; see **dashboard/README.md** and section 3 above |
+| Backups | Saved under `/var/lib/cm4-provisioning/backups/` (optionally a host path bind-mounted into the LXC — set `CM4_BACKUPS_HOST_PATH` at deploy). When a device is detected, choose **Backup** or **Deploy** in the dashboard. |
+| Network deploy/backup | Network-booted devices run **network-client/provisioning-client.sh** and register with the dashboard; they then appear under "Device detected (Network)" and you choose Backup or Deploy. See **network-client/README.md**. |
+| Network boot (DHCP + TFTP on eth1) | If the LXC has a second interface **eth1** as provisioning LAN (e.g. 10.20.50.1/24), run **scripts/setup-network-boot-on-lxc.sh root@&lt;LXC-IP&gt;** to install dnsmasq (DHCP+TFTP) on eth1 and NAT so LAN clients get internet via eth0. See **docs/NETWORK-BOOT-LXC.md**. |