Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

Imager: docs/IMAGER.md, screenshots, build scripts and a CI workflow

Federico Pereira14ad5b672871
diff --git a/.github/workflows/imager-desktop.yml b/.github/workflows/imager-desktop.yml
new file mode 100644
index 0000000..23bc248
--- /dev/null
+++ b/.github/workflows/imager-desktop.yml
@@ -0,0 +1,51 @@
+# LordOS Imager desktop downloads (docs/IMAGER.md, "Building the desktop downloads"). Builds the Mac,
+# Windows and Linux downloads on hosted runners and keeps them as workflow artifacts. Runs only by
+# hand: nothing is published or signed here.
+name: Imager desktop downloads
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - os: macos-14
+ bundles: app,dmg
+ label: mac
+ - os: windows-2022
+ bundles: nsis
+ label: windows
+ - os: ubuntu-24.04
+ bundles: deb
+ label: linux
+ runs-on: ${{ matrix.os }}
+ defaults:
+ run:
+ working-directory: desktop/imager
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ - uses: dtolnay/rust-toolchain@stable
+ - name: Linux build packages
+ if: matrix.label == 'linux'
+ run: sudo apt-get update && sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev libsoup-3.0-dev
+ - run: npm ci --no-audit --no-fund
+ - run: node build-web.mjs
+ - name: Core tests
+ run: cargo test -p lordos-imager-core
+ - run: npx tauri build --bundles ${{ matrix.bundles }}
+ - uses: actions/upload-artifact@v4
+ with:
+ name: lordos-imager-${{ matrix.label }}
+ path: |
+ desktop/imager/target/release/bundle/dmg/*.dmg
+ desktop/imager/target/release/bundle/nsis/*.exe
+ desktop/imager/target/release/bundle/deb/*.deb
+ if-no-files-found: ignore
diff --git a/apps/imager/ui/Options.jsx b/apps/imager/ui/Options.jsx
index f280253..807759d 100644
--- a/apps/imager/ui/Options.jsx
+++ b/apps/imager/ui/Options.jsx
@@ -24,7 +24,9 @@ export function OptionsDialog({ s }) {
<SwitchRow id="o-sound" label={tr('imager.options.sound')} on={o.sound} onChange={(sound) => setOptions({ sound })} />
<SwitchRow id="o-eject" label={tr('imager.options.eject')} detail={tr('imager.options.ejectHint')} on={o.eject} onChange={(eject) => setOptions({ eject })} />
{platform.appUpdates ? (
- <SwitchRow id="o-upd" label={tr('imager.options.updates')} detail={tr('imager.options.updatesHint')} on={o.appUpdates} onChange={(appUpdates) => setOptions({ appUpdates })} />
+ <SwitchRow id="o-upd" label={tr('imager.options.updates')}
+ detail={o.appUpdates && platform.appUpdate ? tr('imager.options.updateFound', { v: platform.appUpdate.version }) : tr('imager.options.updatesHint')}
+ on={o.appUpdates} onChange={(appUpdates) => setOptions({ appUpdates })} />
) : (
<View style={{ paddingVertical: 9 }}><Text style={{ fontSize: typeScale.caption, color: t.textDim, lineHeight: 1.4 }}>{tr('imager.options.updatesSystem')}</Text></View>
)}
diff --git a/assets/locales/en/imager.json b/assets/locales/en/imager.json
index 9763c27..8d66d30 100644
--- a/assets/locales/en/imager.json
+++ b/assets/locales/en/imager.json
@@ -194,8 +194,9 @@
"options.sound": "Play a sound when finished",
"options.theme": "Appearance",
"options.title": "App options",
+ "options.updateFound": "LordOS Imager {v} is on the LordOS releases page.",
"options.updates": "Check for app updates",
- "options.updatesHint": "Looks for a newer LordOS Imager on the LordOS releases page when it starts.",
+ "options.updatesHint": "Looks for a newer LordOS Imager in the LordOS release list it already reads. Nothing else is sent.",
"options.updatesSystem": "The imager is part of LordOS: it's updated with the system.",
"phase.check": "Checking the image",
"phase.done": "Done",
diff --git a/assets/locales/es/imager.json b/assets/locales/es/imager.json
index b6f822a..020428b 100644
--- a/assets/locales/es/imager.json
+++ b/assets/locales/es/imager.json
@@ -194,8 +194,9 @@
"options.sound": "Sonar al terminar",
"options.theme": "Apariencia",
"options.title": "Opciones de la app",
+ "options.updateFound": "LordOS Imager {v} está en la página de versiones de LordOS.",
"options.updates": "Buscar actualizaciones de la app",
- "options.updatesHint": "Al abrirse, busca un LordOS Imager más nuevo en la página de versiones de LordOS.",
+ "options.updatesHint": "Busca un LordOS Imager más nuevo en la lista de versiones de LordOS que ya lee. No se envía nada más.",
"options.updatesSystem": "El grabador es parte de LordOS: se actualiza con el sistema.",
"phase.check": "Verificando la imagen",
"phase.done": "Listo",
diff --git a/assets/locales/pt/imager.json b/assets/locales/pt/imager.json
index 2df7232..9879140 100644
--- a/assets/locales/pt/imager.json
+++ b/assets/locales/pt/imager.json
@@ -194,8 +194,9 @@
"options.sound": "Tocar um som ao terminar",
"options.theme": "Aparência",
"options.title": "Opções do app",
+ "options.updateFound": "O LordOS Imager {v} está na página de versões do LordOS.",
"options.updates": "Procurar atualizações do app",
- "options.updatesHint": "Ao abrir, procura um LordOS Imager mais novo na página de versões do LordOS.",
+ "options.updatesHint": "Procura um LordOS Imager mais novo na lista de versões do LordOS que ele já lê. Nada mais é enviado.",
"options.updatesSystem": "O gravador faz parte do LordOS: ele é atualizado com o sistema.",
"phase.check": "Conferindo a imagem",
"phase.done": "Pronto",
diff --git a/desktop/imager/core/src/drives.rs b/desktop/imager/core/src/drives.rs
index 72011cc..2b3976a 100644
--- a/desktop/imager/core/src/drives.rs
+++ b/desktop/imager/core/src/drives.rs
@@ -286,7 +286,8 @@ mod linux {
for line in parts.lines() {
let mut it = line.split_whitespace();
let (Some(p), Some(_m)) = (it.next(), it.next()) else { continue };
- let proxy = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", udisks_path(p).as_str(), "org.freedesktop.UDisks2.Filesystem").map_err(|e| Error::new("disk.busy", e.to_string()))?;
+ let op = udisks_path(p);
+ let proxy = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", op.as_str(), "org.freedesktop.UDisks2.Filesystem").map_err(|e| Error::new("disk.busy", e.to_string()))?;
proxy.call_method("Unmount", &(opts(),)).map_err(|e| Error::new("disk.busy", e.to_string()))?;
}
Ok(())
@@ -296,7 +297,8 @@ mod linux {
use std::os::fd::{FromRawFd, IntoRawFd};
if let Ok(f) = std::fs::OpenOptions::new().read(true).write(true).open(&d.path) { return Ok(f); } // root, or a test loop device
let c = conn()?;
- let proxy = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", udisks_path(&d.path).as_str(), "org.freedesktop.UDisks2.Block").map_err(|e| Error::new("disk.openFailed", e.to_string()))?;
+ let op = udisks_path(&d.path);
+ let proxy = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", op.as_str(), "org.freedesktop.UDisks2.Block").map_err(|e| Error::new("disk.openFailed", e.to_string()))?;
let mut o = opts();
o.insert("flags", zbus::zvariant::Value::I32(libc::O_EXCL));
let reply = proxy.call_method("OpenDevice", &("rw", o)).map_err(|e| Error::new("imager.notAuthorized", e.to_string()))?;
@@ -308,7 +310,8 @@ mod linux {
pub fn eject(d: &Drive) -> Result<()> {
let c = conn()?;
// the drive object behind the block device, then PowerOff (like "Safely remove")
- let block = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", udisks_path(&d.path).as_str(), "org.freedesktop.UDisks2.Block").map_err(|e| Error::new("imager.ejectFailed", e.to_string()))?;
+ let op = udisks_path(&d.path);
+ let block = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", op.as_str(), "org.freedesktop.UDisks2.Block").map_err(|e| Error::new("imager.ejectFailed", e.to_string()))?;
let drive: zbus::zvariant::OwnedObjectPath = block.get_property("Drive").map_err(|e| Error::new("imager.ejectFailed", e.to_string()))?;
let dp = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", drive.as_str(), "org.freedesktop.UDisks2.Drive").map_err(|e| Error::new("imager.ejectFailed", e.to_string()))?;
let _ = dp.call_method("Eject", &(opts(),));
@@ -322,7 +325,8 @@ mod linux {
let c = conn()?;
for _ in 0..30 {
if std::path::Path::new(&p).exists() {
- let fs = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", udisks_path(&p).as_str(), "org.freedesktop.UDisks2.Filesystem").map_err(|e| Error::new("imager.bootNotFound", e.to_string()))?;
+ let op = udisks_path(&p);
+ let fs = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", op.as_str(), "org.freedesktop.UDisks2.Filesystem").map_err(|e| Error::new("imager.bootNotFound", e.to_string()))?;
if let Ok(r) = fs.call_method("Mount", &(opts(),)) {
let mp: String = r.body().deserialize().map_err(|e| Error::new("imager.bootNotFound", e.to_string()))?;
return Ok(mp.into());
@@ -334,9 +338,9 @@ mod linux {
}
pub fn unmount_boot(d: &Drive) {
if let Ok(c) = conn() {
- if let Ok(fs) = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", udisks_path(&part1(d)).as_str(), "org.freedesktop.UDisks2.Filesystem") {
- let _ = fs.call_method("Unmount", &(opts(),));
- }
+ let op = udisks_path(&part1(d));
+ let fs = zbus::blocking::Proxy::new(&c, "org.freedesktop.UDisks2", op.as_str(), "org.freedesktop.UDisks2.Filesystem");
+ if let Ok(fs) = fs { let _ = fs.call_method("Unmount", &(opts(),)); }
}
}
}
diff --git a/desktop/imager/scripts/Dockerfile.build b/desktop/imager/scripts/Dockerfile.build
new file mode 100644
index 0000000..573f9f9
--- /dev/null
+++ b/desktop/imager/scripts/Dockerfile.build
@@ -0,0 +1,16 @@
+# The LordOS Imager's Linux and Windows builds, from a Debian 13 container (docs/IMAGER.md,
+# "Building the desktop downloads"). Linux: Tauri's WebKitGTK stack. Windows: cargo-xwin (the MSVC
+# runtime and SDK headers, downloaded by xwin under their license) with clang and lld, and NSIS for
+# the installer.
+FROM debian:trixie
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ ca-certificates curl build-essential pkg-config file xz-utils git \
+ libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev libsoup-3.0-dev libjavascriptcoregtk-4.1-dev libssl-dev \
+ clang lld llvm nsis nodejs npm \
+ && rm -rf /var/lib/apt/lists/*
+ENV RUSTUP_HOME=/opt/rustup CARGO_HOME=/opt/cargo PATH=/opt/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --no-modify-path \
+ && rustup target add x86_64-pc-windows-msvc \
+ && cargo install --locked cargo-xwin
+WORKDIR /src
diff --git a/desktop/imager/scripts/build-linux.sh b/desktop/imager/scripts/build-linux.sh
new file mode 100755
index 0000000..406a1e2
--- /dev/null
+++ b/desktop/imager/scripts/build-linux.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+# build-linux.sh — the Linux download (.deb and the bare binary) in a Debian 13 container.
+# desktop/imager/scripts/build-linux.sh → desktop/imager/target/linux/
+# The container keeps its own node_modules and cargo target folder (named volumes), so the host's
+# (another platform's) are never mixed in; the results are copied out at the end.
+set -eu
+here=$(cd "$(dirname "$0")" && pwd)
+repo=$(cd "$here/../../.." && pwd)
+docker build -t lordos-imager-build -f "$here/Dockerfile.build" "$here"
+docker run --rm -v "$repo:/src" -v lordos-imager-cargo:/opt/cargo/registry \
+ -v lordos-imager-nm-linux:/src/desktop/imager/node_modules -v lordos-imager-target-linux:/build \
+ -e CARGO_TARGET_DIR=/build -w /src/desktop/imager lordos-imager-build sh -c '
+ set -e
+ npm ci --no-audit --no-fund && node build-web.mjs
+ npx tauri build --bundles deb
+ mkdir -p target/linux && cp /build/release/lordos-imager target/linux/ && cp /build/release/bundle/deb/*.deb target/linux/
+ ls -la target/linux/'
diff --git a/desktop/imager/scripts/build-mac.sh b/desktop/imager/scripts/build-mac.sh
new file mode 100755
index 0000000..16bafdc
--- /dev/null
+++ b/desktop/imager/scripts/build-mac.sh
@@ -0,0 +1,11 @@
+#!/bin/sh
+# build-mac.sh — the Mac download (.app and .dmg) on a Mac with Rust and Node.
+# desktop/imager/scripts/build-mac.sh → desktop/imager/target/release/bundle/
+# Unsigned by default. With a signing identity in the keychain, set APPLE_SIGNING_IDENTITY (and the
+# notarization variables Tauri documents) before running it; see docs/IMAGER.md, "Signing".
+set -eu
+cd "$(dirname "$0")/.."
+npm ci --no-audit --no-fund
+node build-web.mjs
+npx tauri build --bundles app,dmg
+ls -la target/release/bundle/macos target/release/bundle/dmg
diff --git a/desktop/imager/scripts/build-windows.sh b/desktop/imager/scripts/build-windows.sh
new file mode 100755
index 0000000..3fe4938
--- /dev/null
+++ b/desktop/imager/scripts/build-windows.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+# build-windows.sh — the Windows download (an NSIS installer and the .exe), cross-built with
+# cargo-xwin in a Debian 13 container. The .exe carries the administrator manifest
+# (src-tauri/windows-app.manifest).
+# desktop/imager/scripts/build-windows.sh → desktop/imager/target/windows/
+set -eu
+here=$(cd "$(dirname "$0")" && pwd)
+repo=$(cd "$here/../../.." && pwd)
+docker build -t lordos-imager-build -f "$here/Dockerfile.build" "$here"
+docker run --rm -v "$repo:/src" -v lordos-imager-cargo:/opt/cargo/registry -v lordos-imager-xwin:/root/.cache/cargo-xwin \
+ -v lordos-imager-nm-linux:/src/desktop/imager/node_modules -v lordos-imager-target-windows:/build \
+ -e CARGO_TARGET_DIR=/build -w /src/desktop/imager lordos-imager-build sh -c '
+ set -e
+ npm ci --no-audit --no-fund && node build-web.mjs
+ npx tauri build --runner cargo-xwin --target x86_64-pc-windows-msvc --bundles nsis
+ mkdir -p target/windows && cp /build/x86_64-pc-windows-msvc/release/lordos-imager.exe target/windows/ && cp /build/x86_64-pc-windows-msvc/release/bundle/nsis/*.exe target/windows/
+ ls -la target/windows/'
diff --git a/desktop/imager/src-tauri/build.rs b/desktop/imager/src-tauri/build.rs
index 709efcc..1a7794b 100644
--- a/desktop/imager/src-tauri/build.rs
+++ b/desktop/imager/src-tauri/build.rs
@@ -1,10 +1,9 @@
fn main() {
// `windows`: writing a whole disk needs an administrator, so the app asks for it when it starts
- // (src-tauri/windows-app.manifest). Mac and Linux ask only when the drive is opened.
- #[allow(unused_mut)]
+ // (src-tauri/windows-app.manifest). `macos` and `linux` ask only when the drive is opened.
+ // The target, not the host, decides (the Windows build is cross-compiled).
let mut attrs = tauri_build::Attributes::new();
- #[cfg(windows)]
- {
+ if std::env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("windows") {
attrs = attrs.windows_attributes(tauri_build::WindowsAttributes::new().app_manifest(include_str!("windows-app.manifest")));
}
tauri_build::try_build(attrs).expect("tauri-build");
diff --git a/desktop/imager/web/platform.js b/desktop/imager/web/platform.js
index 265e416..6cee761 100644
--- a/desktop/imager/web/platform.js
+++ b/desktop/imager/web/platform.js
@@ -84,8 +84,10 @@ export const platform = {
async releases() {
const text = await call('fetch_releases');
await cacheStates(text);
+ if (options.appUpdates !== false) findUpdate(text);
return text;
},
+ appUpdate: null,
async cachedReleases() {
const text = await invoke('cached_releases');
if (text) await cacheStates(text);
@@ -158,6 +160,17 @@ export const platform = {
let profilesCache = [];
let cacheSizeNow = 0;
+// "Check for app updates": a newer LordOS Imager among the release files GitHub lists (no other request)
+const newer = (a, b) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0); return false; };
+function findUpdate(text) {
+ try {
+ for (const r of JSON.parse(text)) for (const a of r.assets || []) {
+ const m = /^(?:lordos-imager|LordOS[ ._-]Imager)[_-]v?(\d+\.\d+\.\d+)/i.exec(a.name || '');
+ if (m && newer(m[1], info_.version) && (!platform.appUpdate || newer(m[1], platform.appUpdate.version))) platform.appUpdate = { version: m[1], tag: r.tag_name };
+ }
+ } catch { /* not a list */ }
+}
+
export async function warm() {
profilesCache = (await invoke('load_profiles')) || [];
cacheSizeNow = await invoke('cache_size');
diff --git a/docs/IMAGER.md b/docs/IMAGER.md
new file mode 100644
index 0000000..d433d20
--- /dev/null
+++ b/docs/IMAGER.md
@@ -0,0 +1,347 @@
+# LordOS Imager
+
+Our own SD card and USB stick writer, with a first-run experience for LordOS on the Raspberry Pi 5:
+choose the device, the system image and the drive, customise the first boot (computer name,
+language, user, Wi-Fi, remote access, appearance, cooling), and write. Lumo gives a tip at every
+step and celebrates at the end.
+
+It comes in two forms that share the same interface and the same rules:
+
+- **in LordOS**, as a native app (`apps/imager`), shipped with the distribution;
+- **for other computers**, as a small desktop app built with Tauri (`desktop/imager`, about 6 MB):
+ a Mac download, a Windows download and a Linux download.
+
+It is not a web page: a browser can't write a whole disk.
+
+| In LordOS | On another computer |
+|---|---|
+| ![Device](imager/native-01-device.png) | ![Device](imager/desktop-01-device.png) |
+| ![Customise: cooling](imager/native-10-tab-cooling.png) | ![Customise: cooling](imager/desktop-07-cooling.png) |
+| ![Writing](imager/native-15-writing.png) | ![Writing](imager/desktop-11-writing-dark.png) |
+| ![Done](imager/native-18-done.png) | ![Done](imager/desktop-12-done-dark.png) |
+
+## The steps
+
+| Step | What it does |
+|---|---|
+| **Device** | Raspberry Pi 5 (the only supported board; Pi 500/CM5 and Pi 4/400 are listed as "not supported yet", Pi 3 and Zero 2 as "not planned") or **PC (USB stick)**, which writes the amd64 live ISO. For the Pi, the memory advice: 4 GB minimum, 8 GB comfortable, 16 GB for the best performance. |
+| **System image** | The latest LordOS release (version, date, download size, "Signed by LordOS"), older releases on request, or **an image file of your own** (`.img`, `.img.xz`, `.iso`) with a clear warning that nobody vouches for it. Downloads are cached and resume after an interruption. |
+| **Storage** | Only removable drives (USB, SD cards): model, size, kind, labels, what is mounted. Internal disks and the disk the computer runs from are never listed, and "show all drives" doesn't exist. Too small, write-protected and over-2-TiB drives are shown disabled with the reason; a very large removable drive gets a warning. Erasing is spelled out before anything happens. |
+| **Customise** (Pi only) | A switch, then seven tabs: **General** (computer name, language, time zone, keyboard layout, Wi-Fi country), **User** (full name, user name, password with confirmation and a strength hint, automatic login), **Wi-Fi** (network name, password or open network, hidden network, a scan on LordOS), **Remote access** (SSH off / keys only / password and keys, keys pasted or from a `.pub` file; LordOS remote desktop on or off), **Appearance** (Lord Default or Classic, light or dark, accent, wallpaper), **Cooling** (case with a fan, active cooler, passive case, nothing; a profile; a mild overclock only with a fan), **More** (Bluetooth, automatic update checks, and the statement that LordOS collects nothing). Profiles save and load everything except secrets. |
+| **Write** | A summary, then "Erase and write" asks once more. Download (if needed) → release signature → image check → write → read back and compare → first-run file → eject. Progress, speed and time left; Cancel at any time (the drive is wiped so it never looks half-written). |
+| **Done** | Lumo celebrates; next steps: put the card in the Pi 5, the first boot takes about a minute, then it is `hostname.local` on the network (`ssh [email protected]`, `https://hostname.local:5673`). A sound and a notification when it finishes. |
+
+**App options:** sound when finished, eject when finished, check for app updates (the desktop app;
+in LordOS the imager updates with the system), language and appearance (the desktop app; in
+LordOS they follow Settings), the download cache (where, how big, clear; the desktop app can move
+it). No telemetry: the imager only contacts the LordOS releases on GitHub.
+
+More screenshots: the native app in [`imager/native-*.png`](imager/) (every step and tab, the
+custom image warning, the confirmation, cancelling, the options), the desktop app in
+[`imager/desktop-*.png`](imager/) (light and dark).
+
+## One interface, two platforms
+
+```
+apps/imager/
+ index.jsx, ui/*.jsx the interface: steps, Lumo's tips, dialogs (React)
+ state.js the wizard state and the write pipeline
+ core/ validators, the first-run file writer, profiles, the release list (plain JS)
+ data/ time zones and keyboard layouts (Debian 13's tzdata and xkb-data)
+ platform.js LordOS: lord.disks, lord.imager, the admin actions, lord.fs
+desktop/imager/
+ web/sdk.jsx DOM versions of the few @lordos/sdk primitives the UI uses
+ web/platform.js the same functions as apps/imager/platform.js, over Tauri commands
+ build-web.mjs builds apps/imager against those two files (esbuild)
+ core/ lordos-imager-core (Rust): signature, .xz index, write and verify, drives, secrets
+ src-tauri/ the Tauri shell and its commands
+```
+
+The interface imports only View, Text, Image, ScrollView, TextInput, Button, Lumo, useTheme,
+useKeyboard, t, typeScale, spacing and a store from `@lordos/sdk`; in the desktop build those come
+from `web/sdk.jsx`, which draws them with HTML and Lord Default's colors (light, dark or automatic).
+The texts are the same catalogs (`assets/locales/<lang>/imager.json`, plus errors, status, mascot
+and countries), so both apps speak English, Spanish and Portuguese identically.
+
+The writing rules exist twice, in C for LordOS (`server/src/imager/`) and in Rust for the desktop
+(`desktop/imager/core/`), and are tested against the same fixtures (a real signed `SHA256SUMS`, the
+same `.xz` files, the same password and Wi-Fi vectors).
+
+## Security model
+
+### In LordOS
+
+`lord-server` runs as the user and never executes anything. Everything that needs root is one of
+four closed admin actions in `server/src/imager/imager_admin.c` (table `IMAGER_ADMIN_ACTIONS`):
+
+| Action | Argument | What it does |
+|---|---|---|
+| `imager-fetch` | `meta`, or `file\n<tag>\n<name>\n<size>` | `/usr/bin/curl` **as the user** (setresuid, no new privileges, no curlrc, https only also after redirects) fetches `https://api.github.com/repos/lordbasex/LordOS/releases?per_page=10` or `https://github.com/lordbasex/LordOS/releases/download/<tag>/<name>` into `~/.cache/lordos/imager` (resumable `.part`; the tag and name are validated; only images and the two signature files). Root never parses what arrives. |
+| `imager-fetch-cancel` | none | stops this user's download |
+| `imager-cache-clear` | none | deletes the imager's cache, as the user, one level of release folders |
+| `imager-write` | `<disk>\n<size>\n<model>\n<serial>\nofficial\|custom\n<image>[\n<SHA256SUMS>\n<SHA256SUMS.sig>]` | writes the image to a whole disk (below) |
+
+`imager-write`, all checked on the root side:
+
+1. **The drive:** a whole disk (the `disk-*` rules: a real block device whose `/dev` node matches
+ sysfs), never the system disk, **only removable** (USB or a card; refused even for an
+ administrator), not read-only, at most 2 TiB, and its size, model and serial are the ones the
+ user picked.
+2. **The image:** opened with the user's permissions, only from their home or their mounts, never
+ from the disk being written; `.img`, `.img.xz` or `.iso`; the `.xz` index gives its uncompressed
+ size, which must fit.
+3. **Official images:** `SHA256SUMS.sig` must verify with the release key compiled into LordOS
+ (`codesig_release_key`, fingerprint `c7155b8e…53ea108e`, docs/SIGNING.md) and the file's SHA-256
+ must be the listed one — **before anything is erased**.
+4. **Right before opening:** the identity is checked again, mounts under `/media` are unmounted
+ (anything mounted elsewhere is refused), the device is opened `O_EXCL | O_DIRECT`, and the
+ opened descriptor must be that very device (major:minor, `BLKGETSIZE64`).
+5. **Writing:** a raw image is copied; an `.img.xz` is decompressed by `/usr/bin/xz` running **as
+ the user** with no privileges, fed through pipes, so root never decodes compressed data. The
+ file's bytes are hashed again while writing; if they no longer match the signed hash, the write
+ fails.
+6. **Verifying:** the drive is read back with `O_DIRECT` and its SHA-256 compared with what was
+ written.
+7. **Failing safely:** on any error or a cancel after the first write, the first and last MiB are
+ zeroed, so a half-written card never looks bootable. Cancelling is `disk-cancel <disk>`.
+
+The first-run file then goes onto the card's boot partition the way any file goes onto a USB stick:
+`disk-mount` mounts it for the user under `/media/<user>`, `lord.fs.write` writes the file, and
+`disk-unmount` and `disk-eject` finish. The board validates the file again (below).
+
+`lord.imager` (`server/src/ui/js_imager.c`) only computes: `hashPassword` (yescrypt with libcrypt,
+Debian's default), `wifiPsk` (PBKDF2-HMAC-SHA1, 4096 rounds), `checkSums` (the signature check, so
+the UI can show it before writing) and `imageInfo` (size and uncompressed size of a file in the
+user's folders). It writes nothing and runs nothing.
+
+### On other computers
+
+- **Downloads** go only to the LordOS releases on GitHub over HTTPS (Rust, `reqwest` with rustls),
+ into the platform's cache folder, resumable. What is trusted is decided by the signature, never by
+ the transport.
+- **Drives:** only removable, non-system drives are listed and accepted; the identity is checked
+ again right before opening; nothing of the drive stays mounted.
+ - Mac download: `diskutil` (external, physical disks; the boot disk and internal ones are left
+ out). The raw device is opened by the system's authorized-open helper (`/usr/libexec/authopen`),
+ which asks for an administrator's approval in the system's own dialog and hands back only that
+ one open device; the app itself never runs as root.
+ - Linux download: `lsblk` for the list; the device is opened through udisks2 (`OpenDevice`, which
+ polkit approves like a desktop's "Format disk"); the boot partition is mounted and the drive
+ powered off through udisks2 too. The `.deb` depends on `udisks2`.
+ - Windows download: `Get-Disk` (USB, SD and MMC bus types; never a boot or system disk); the
+ `.exe` carries an administrator manifest (`requireAdministrator`); every volume on the disk is
+ locked and dismounted before writing.
+- **The same pipeline** as in LordOS: signature and hash before erasing, decompression while
+ writing with the file hashed again, read back and compare, wipe on failure or cancel.
+- **Secrets** are derived in Rust: the password as SHA-512 crypt with 200 000 rounds (`$6$`, accepted
+ by every Linux PAM and by `lordos-firstrun`), the Wi-Fi key as the WPA2 PSK.
+- **Test devices:** `LORDOS_IMAGER_TEST_DEVICES=<folder>` also lists disk images (Mac download) or loop
+ devices (Linux) whose backing file is inside that folder, and nothing else; disk images attached
+ for any other purpose are never listed. `LORDOS_IMAGER_TEST_STATE=<file.json>` opens the window at
+ a given step with given choices, for tests and documentation screenshots; it can start a write only
+ to such a test device. Neither is ever set by the app.
+
+## The first-run file
+
+`lordos-firstrun.txt` on the boot partition (FAT, `bootfs`), written by both imagers
+(`apps/imager/core/firstrun.js`) and read once by the Pi on its first boot.
+
+- UTF-8 text, LF or CRLF, a BOM allowed, at most 64 KiB, no NUL or control characters.
+- Lines are empty, comments (`# …`) or `key=value`. The first setting must be `version=1`.
+- **Strict:** an unknown key, a repeated key (except `ssh_key`), a value out of range, a space
+ around a value, or a broken rule between keys makes the whole file invalid, and **nothing** of it
+ is applied (the board starts in setup mode, as without a file).
+- **No secrets in clear:** the password is a crypt(3) hash, the Wi-Fi password is replaced by its
+ derived key.
+- Only what was chosen is written; everything else keeps the image's defaults.
+
+| Key | Value | Rule |
+|---|---|---|
+| `version` | `1` | first |
+| `hostname` | RFC 1123 label | `[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?`, not only digits, not `localhost` |
+| `lang` | `en` \| `es` \| `pt` | the languages LordOS ships |
+| `timezone` | `Area/City` | `[A-Za-z0-9_+-/]`, starts with a capital, no `..`; must exist in the image's zoneinfo |
+| `keyboard`, `keyboard_variant` | xkb layout and variant | `[a-z]{2,10}`; variant `[A-Za-z0-9_-]{0,32}`; the layout must exist in the image |
+| `wifi_country` | two capital letters | `cfg80211.ieee80211_regdom=` in `cmdline.txt` |
+| `user` | user name | `^[a-z_][a-z0-9_-]{0,31}$`, not a reserved system name |
+| `fullname` | UTF-8 | up to 128 bytes, no control or bidi-override characters, no `: , = \` |
+| `password_hash` | `$6$[rounds=N$]salt$…` or `$y$…` | required with `user` |
+| `autologin` | `0` \| `1` | needs `user` |
+| `wifi_ssid_hex` | the network name's bytes in lower-case hex | 1–32 bytes, no NUL |
+| `wifi_psk` | 64 lower-case hex digits | the WPA2 key; without it the network is open |
+| `wifi_hidden` | `0` \| `1` | needs `wifi_ssid_hex` |
+| `ssh` | `off` \| `password` \| `keys` | `keys` needs at least one `ssh_key`; on needs `user` |
+| `ssh_key` | an OpenSSH public key line | up to 16; ed25519, ECDSA, security keys or RSA ≥ 2048 bits; the blob's type must match; no `command=` or other options |
+| `remote_desktop` | `0` \| `1` | needs `user` |
+| `bluetooth` | `0` \| `1` | |
+| `theme` | `default` \| `classic` | |
+| `mode` | `light` \| `dark` | |
+| `accent` | a LordOS accent name | `azul`, `violeta`, `rosa`, `naranja`, `verde`, `grafito`, … |
+| `wallpaper` | a wallpaper id | `[a-z0-9-]{1,48}` |
+| `cooler` | `case-fan` \| `active-cooler` \| `passive` \| `none` | |
+| `performance` | `balanced` \| `performance` \| `quiet` \| `conservative` | needs `cooler`; `performance` and `quiet` need a fan |
+| `overclock` | `0` \| `1` | `1` needs a fan |
+| `auto_updates` | `0` \| `1` | |
+
+Example (what the imager writes):
+
+```
+version=1
+hostname=pi-living
+lang=en
+timezone=America/Argentina/Buenos_Aires
+keyboard=us
+keyboard_variant=
+wifi_country=AR
+user=ana
+fullname=Ana Perez
+password_hash=$y$j9T$szwfNUJQrRIXau020U3AQ.$JWQYK9BLxED/3ePLXhQZSPEoVcZhisZzAZ.B5GpXuk3
+autologin=0
+wifi_ssid_hex=43617361204c6f7264
+wifi_psk=d98e0bb94693bd28702424c1dfe34e440968a185eee961785e000f7b50c2b825
+wifi_hidden=0
+ssh=keys
+ssh_key=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIF8zdvpQ/Ic++n9TOGaDGEe9/+IRgtRBf1H86da41yJ8 ana@laptop
+remote_desktop=1
+bluetooth=1
+theme=default
+mode=dark
+accent=azul
+wallpaper=lumo-celestial
+cooler=active-cooler
+performance=performance
+overclock=1
+auto_updates=1
+```
+
+### On the board
+
+`lordos-rpi-firstboot.service` (`/usr/lib/lordos/rpi/firstboot`, docs/RASPBERRY.md, "First boot")
+runs `/usr/lib/lordos/bin/lordos-firstrun apply /boot/firmware/lordos-firstrun.txt` on the first
+boot, before the user section. `lordos-firstrun` (`server/src/firstrun/`) parses the file with the
+strict parser above (`fr_parse`, pure), and only if it is valid applies it, as root:
+
+| Part | How |
+|---|---|
+| Computer name | `/etc/hostname`, the `127.0.1.1` line of `/etc/hosts` |
+| Time zone, language, keyboard | `/etc/localtime` → zoneinfo, `/etc/timezone`, `/etc/locale.conf` (Debian 13's `/etc/default/locale` points there), `/etc/default/keyboard` |
+| Wi-Fi country | `cfg80211.ieee80211_regdom=` in `cmdline.txt` (one line kept) |
+| Wi-Fi | `/etc/lordos/net/wifi/<ssid hex>.json` and `.key` (0600, `psk=<hex>`), the format Settings → Network uses; lord-netd now accepts a derived key there (WPA2; a WPA3-only network needs the password itself) |
+| User | `useradd` and `usermod -p <hash>` (fixed paths, the values as arguments, never a shell), groups `sudo audio video input render` (and `pipewire plugdev lpadmin bluetooth netdev` when they exist), linger, the home folders in the chosen language, `~/.config/lordos/settings.json` (language, keyboard, theme, mode, accent, wallpaper, `updates.autoCheck`) and `~/.config/locale.conf`; the setup account is then removed by `firstboot` |
+| Automatic login | `AUTOLOGIN=<user>` (or empty) in `/etc/lordos/session.conf` |
+| SSH | `systemctl enable` + `start --no-block ssh.service`; with keys only, `~/.ssh/authorized_keys` (0600 in a 0700 folder) and `/etc/ssh/sshd_config.d/05-lordos-keys-only.conf` (`PasswordAuthentication no`, `KbdInteractiveAuthentication no`); root never logs in (10-lordos.conf) |
+| Remote desktop | `/etc/lordos/remote/config` with `enabled=1`, `port=5673`, `allow=all`, `net=lan` (local network only) — the same file Settings → Sharing writes, with the 0.8.3 defaults (TLS, the lockout after 3 failed sign-ins) |
+| Bluetooth off | a soft block of every Bluetooth radio through `/dev/rfkill` (`RFKILL_OP_CHANGE_ALL`), kept across boots by systemd-rfkill; Settings → Bluetooth turns it back on |
+| Cooling | `/etc/lordos/fan.json` with the profile (and `PROFILE` to `lord-fand` if it is already running); performance: `/etc/tmpfiles.d/lordos-cpu-governor.conf` sets the `performance` governor at boot; a block of our own in `config.txt` between `# >>> lordos-firstrun` and `# <<< lordos-firstrun`: `arm_freq=2600` for the mild overclock (fan only), `arm_freq=2000` for the conservative profile without cooling |
+
+The file is then **shredded** (overwritten with random bytes, then zeros, `fsync`, deleted) whatever
+the outcome; `firstboot` deletes it too if anything is left. On an SD card the flash controller may
+keep old copies of blocks, which is why the file never holds a secret in clear in the first place.
+
+Exit status: 0 applied with a user (the board goes to the login screen, or logs in automatically),
+2 applied without a user (setup mode), 1 invalid file (nothing applied), 3 the user could not be
+created. `--root DIR --boot DIR` apply into a mounted image for tests (`useradd`/`usermod`/`systemctl
+--root`; nothing is started).
+
+### Cooling profiles
+
+| Cooler | Profiles | What they set |
+|---|---|---|
+| Case with a fan, active cooler | **Balanced** (default), Performance, Quiet; optional mild overclock | lord-fand's curve (docs/FANS.md): Balanced 55 °C → 30 %, Performance 45 °C → 40 % plus the `performance` CPU governor, Quiet 60 °C → 30 %; overclock 2.6 GHz instead of 2.4 GHz with no extra voltage |
+| Passive case | Balanced (default), Conservative | no fan to drive; Conservative caps the clock at 2.0 GHz |
+| Nothing | **Conservative** (default), Balanced | 2.0 GHz so a bare board doesn't reach the 85 °C throttle within minutes |
+
+The overclock warns that not every board is stable and how to undo it (delete our block in
+`config.txt` from another computer). It is refused by the parser without a fan.
+
+## Accessibility
+
+- **Keyboard:** Tab and Shift+Tab move a visible focus ring (2 px in the accent color) through
+ every button, card, switch, tab and field of the step; Enter or Space activates; Escape goes back.
+ In the desktop app the browser's own focus does the same and every control has a screen-reader
+ label, role and state (`aria-label`, `aria-checked`, `aria-selected`, `role="progressbar"`…).
+ LordOS itself has no screen reader yet; the labels are in place for when it does.
+- **Texts:** every string is in English, Spanish and Portuguese (`node tools/i18n-check.mjs`).
+- **Never color alone:** problems carry text, the steps carry numbers and checkmarks.
+
+## Building the desktop downloads
+
+Everything is built from `desktop/imager`. The interface is built first (`node build-web.mjs` →
+`dist/`), then the Rust shell bundles it.
+
+### Mac download
+
+On the development machine (the Mac download is built on one), with Rust (rustup) and Node:
+
+```sh
+desktop/imager/scripts/build-mac.sh
+# → desktop/imager/target/release/bundle/macos/LordOS Imager.app (6.3 MB)
+# desktop/imager/target/release/bundle/dmg/LordOS Imager_0.8.4_x64.dmg (3.7 MB)
+```
+
+**Signing:** the build is **unsigned**. The repository documents no signing identity for apps, and
+the LordOS release key (Ed25519, `~/.config/lordos-release/`) signs release files, not apps, so it
+was not used. A code-signing identity can be passed to Tauri (`APPLE_SIGNING_IDENTITY`, plus its
+notarization variables) once the maintainer decides which one to use. Unsigned, the first launch
+needs a right click → Open.
+
+### Linux download
+
+In a Debian 13 container (Docker), so the host needs nothing but Docker:
+
+```sh
+desktop/imager/scripts/build-linux.sh
+# → desktop/imager/target/linux/LordOS Imager_0.8.4_amd64.deb (4.1 MB, depends on udisks2 and WebKitGTK 4.1)
+# desktop/imager/target/linux/lordos-imager (7.6 MB)
+```
+
+### Windows download
+
+Cross-built in the same container with `cargo-xwin` (clang, lld and the MSVC runtime headers that
+xwin downloads), NSIS for the installer:
+
+```sh
+desktop/imager/scripts/build-windows.sh
+# → desktop/imager/target/windows/LordOS Imager_0.8.4_x64-setup.exe (3.3 MB)
+# desktop/imager/target/windows/lordos-imager.exe (6.2 MB, requireAdministrator)
+```
+
+The installer is unsigned (Tauri signs only when it builds on that platform itself, or with a custom sign command).
+`.github/workflows/imager-desktop.yml` builds all three on hosted runners; it is in the tree but
+was never pushed or run.
+
+The containers keep their own `node_modules` and cargo target folders in named volumes
+(`lordos-imager-*`), so the host's are never mixed in; `docker volume rm` them to start clean.
+
+## Tests
+
+| Test | What | Result |
+|---|---|---|
+| `build/firstrun-test` (`make -C server test`) | validators, a full file, 55 broken files, cross-key rules, 16/17 keys, a 64 KiB+1 file, 30 000 mutations | 166 checks |
+| `build/firstrun-fuzz` | the same with 300 000 mutations under ASan and UBSan | 0 errors |
+| `build/imager-test` (ASan/UBSan) | the real 0.8.1 `SHA256SUMS` signature: good, without the newline, tampered list, truncated list, tampered signature, missing, short, not base64, other key; the key's fingerprint; `SHA256SUMS` lookups; names and tags; the `.xz` index on one stream, many blocks, two streams and stream padding, every byte of the last 64 flipped, 40 truncations, 8 000 random edits | 461 checks |
+| `tests/imager_core_test.mjs` | the shared JS: validators, the first-run writer (and every file it writes parsed by the C parser), profiles without secrets, the release list (with hostile names and tags) | 79 checks |
+| `desktop/imager/core` (`cargo test`) | the Rust core: the same signature fixtures and the 0.8.0 signature over the 0.8.1 list, the key fingerprint, the `.xz` index, the IEEE 802.11i PSK vector, glibc's SHA-512 crypt vectors, write + verify of raw and two-stream `.xz` images to a file standing in for a device, refusals (too large, a changed file wipes the device), cancel in the middle wipes the device | 7 tests, on the development machine and on Linux |
+| `server/tests/imager_write_test.sh` (root, VM 116) | `imager-write` against a virtual USB stick (the kernel's USB gadget over a file): 17 refusals (internal disk even for an administrator, system disk, partition, wrong size/model/serial, tampered list, another release's signature, missing signature, unlisted image, too large, broken `.xz`, a link to `/etc/shadow`, a file outside the home, not an image, missing signature lines, a control character), a custom image and the official 0.8.1 image written and read back independently, cancel in the middle (first MiB wiped), another user can't cancel | 24/24 |
+| `server/tests/firstrun_image_test.sh` (root, VM 116) | the real 0.8.3 Raspberry Pi image written by `imager-write`, the first-run file put on its boot partition as the user, then `lordos-firstrun --root --boot`: every file it should write, owners and modes, nothing else changed in `cmdline.txt`/`config.txt`, no Wi-Fi password anywhere, the file shredded, and a broken file applies nothing | 25/25 |
+| Native app on VM 116 | the whole flow with the 0.8.3 image to the virtual stick: written and verified; the first-run file it wrote parses, its yescrypt hash verifies with `crypt(3)` and its PSK matches `pbkdf2_hmac` | ✓ |
+| Desktop app (Mac download, on the development machine) | the whole flow through the app's own commands (`LORDOS_IMAGER_TEST_STATE`, no simulated input) to a 16 GB disk image: download of 0.8.3 from GitHub, signature, image check, write, read back (the same SHA-256 as the native write, `b623f7a8…`), the first-run file on the boot partition (it parses, glibc accepts its SHA-512 hash, the PSK matches) | ✓ |
+| Downloads on VM 116 | `imager-fetch meta`, the two signature files, the 558 MB image cancelled at 335 MB and resumed from the `.part` | ✓ |
+
+## Not done or not verified yet
+
+- **Not booted on a real Raspberry Pi:** the first-run file was applied with `--root` to the real
+ 0.8.3 image (arm64) from an amd64 build, and the image's own `firstboot` script runs `lordos-firstrun`
+ but wasn't executed (no board was reflashed, as asked). The next Pi image build ships
+ `lordos-firstrun`; images up to 0.8.3 ignore the file and start in setup mode.
+- **Not tested with real drives:** only virtual ones (the USB gadget on VM 116, a disk image on the
+ development machine). The authorized-open prompt of the Mac download, udisks2's `OpenDevice` with
+ polkit and the Windows download were not run against a real stick (the test opened its own disk
+ image directly; the Linux and Windows downloads were built and the core tested on Linux, not run
+ with a window).
+- **Wi-Fi scan** only on LordOS (the desktop app types the name).
+- **App updates** on the desktop: the option looks for a newer LordOS Imager among the files of the
+ LordOS releases it already reads; no release carries one yet, so it has never found one.
+- **WPA3-only networks** need the password on the board (only the WPA2 key is stored).
+- **Secrets in the host keychain:** profiles never keep secrets at all; storing them in the
+ keychain was left out.
diff --git a/docs/imager/desktop-01-device.png b/docs/imager/desktop-01-device.png
new file mode 100644
index 0000000..76135aa
Binary files /dev/null and b/docs/imager/desktop-01-device.png differ
diff --git a/docs/imager/desktop-02-image.png b/docs/imager/desktop-02-image.png
new file mode 100644
index 0000000..4af24c5
Binary files /dev/null and b/docs/imager/desktop-02-image.png differ
diff --git a/docs/imager/desktop-03-storage.png b/docs/imager/desktop-03-storage.png
new file mode 100644
index 0000000..add5050
Binary files /dev/null and b/docs/imager/desktop-03-storage.png differ
diff --git a/docs/imager/desktop-04-user.png b/docs/imager/desktop-04-user.png
new file mode 100644
index 0000000..4c89920
Binary files /dev/null and b/docs/imager/desktop-04-user.png differ
diff --git a/docs/imager/desktop-05-wifi.png b/docs/imager/desktop-05-wifi.png
new file mode 100644
index 0000000..eb562f6
Binary files /dev/null and b/docs/imager/desktop-05-wifi.png differ
diff --git a/docs/imager/desktop-06-look.png b/docs/imager/desktop-06-look.png
new file mode 100644
index 0000000..6099839
Binary files /dev/null and b/docs/imager/desktop-06-look.png differ
diff --git a/docs/imager/desktop-07-cooling.png b/docs/imager/desktop-07-cooling.png
new file mode 100644
index 0000000..d567c23
Binary files /dev/null and b/docs/imager/desktop-07-cooling.png differ
diff --git a/docs/imager/desktop-08-review.png b/docs/imager/desktop-08-review.png
new file mode 100644
index 0000000..c460a3e
Binary files /dev/null and b/docs/imager/desktop-08-review.png differ
diff --git a/docs/imager/desktop-09-options.png b/docs/imager/desktop-09-options.png
new file mode 100644
index 0000000..4549ec6
Binary files /dev/null and b/docs/imager/desktop-09-options.png differ
diff --git a/docs/imager/desktop-10-device-dark.png b/docs/imager/desktop-10-device-dark.png
new file mode 100644
index 0000000..1a72316
Binary files /dev/null and b/docs/imager/desktop-10-device-dark.png differ
diff --git a/docs/imager/desktop-11-writing-dark.png b/docs/imager/desktop-11-writing-dark.png
new file mode 100644
index 0000000..d272488
Binary files /dev/null and b/docs/imager/desktop-11-writing-dark.png differ
diff --git a/docs/imager/desktop-12-done-dark.png b/docs/imager/desktop-12-done-dark.png
new file mode 100644
index 0000000..0d8d44c
Binary files /dev/null and b/docs/imager/desktop-12-done-dark.png differ
diff --git a/docs/imager/native-01-device.png b/docs/imager/native-01-device.png
new file mode 100644
index 0000000..7e202f6
Binary files /dev/null and b/docs/imager/native-01-device.png differ
diff --git a/docs/imager/native-02-image.png b/docs/imager/native-02-image.png
new file mode 100644
index 0000000..af418d9
Binary files /dev/null and b/docs/imager/native-02-image.png differ
diff --git a/docs/imager/native-03-custom.png b/docs/imager/native-03-custom.png
new file mode 100644
index 0000000..fcbc719
Binary files /dev/null and b/docs/imager/native-03-custom.png differ
diff --git a/docs/imager/native-04-storage.png b/docs/imager/native-04-storage.png
new file mode 100644
index 0000000..59aac4c
Binary files /dev/null and b/docs/imager/native-04-storage.png differ
diff --git a/docs/imager/native-05-tab-general.png b/docs/imager/native-05-tab-general.png
new file mode 100644
index 0000000..a3199e4
Binary files /dev/null and b/docs/imager/native-05-tab-general.png differ
diff --git a/docs/imager/native-06-tab-user.png b/docs/imager/native-06-tab-user.png
new file mode 100644
index 0000000..8851601
Binary files /dev/null and b/docs/imager/native-06-tab-user.png differ
diff --git a/docs/imager/native-07-tab-wifi.png b/docs/imager/native-07-tab-wifi.png
new file mode 100644
index 0000000..19e3f07
Binary files /dev/null and b/docs/imager/native-07-tab-wifi.png differ
diff --git a/docs/imager/native-08-tab-remote.png b/docs/imager/native-08-tab-remote.png
new file mode 100644
index 0000000..e90bb86
Binary files /dev/null and b/docs/imager/native-08-tab-remote.png differ
diff --git a/docs/imager/native-09-tab-look.png b/docs/imager/native-09-tab-look.png
new file mode 100644
index 0000000..812c381
Binary files /dev/null and b/docs/imager/native-09-tab-look.png differ
diff --git a/docs/imager/native-10-tab-cooling.png b/docs/imager/native-10-tab-cooling.png
new file mode 100644
index 0000000..61154ff
Binary files /dev/null and b/docs/imager/native-10-tab-cooling.png differ
diff --git a/docs/imager/native-11-tab-more.png b/docs/imager/native-11-tab-more.png
new file mode 100644
index 0000000..699d68b
Binary files /dev/null and b/docs/imager/native-11-tab-more.png differ
diff --git a/docs/imager/native-12-skip.png b/docs/imager/native-12-skip.png
new file mode 100644
index 0000000..fb69abc
Binary files /dev/null and b/docs/imager/native-12-skip.png differ
diff --git a/docs/imager/native-13-review.png b/docs/imager/native-13-review.png
new file mode 100644
index 0000000..9c40f31
Binary files /dev/null and b/docs/imager/native-13-review.png differ
diff --git a/docs/imager/native-14-confirm.png b/docs/imager/native-14-confirm.png
new file mode 100644
index 0000000..0133dc5
Binary files /dev/null and b/docs/imager/native-14-confirm.png differ
diff --git a/docs/imager/native-15-writing.png b/docs/imager/native-15-writing.png
new file mode 100644
index 0000000..36313bb
Binary files /dev/null and b/docs/imager/native-15-writing.png differ
diff --git a/docs/imager/native-16-cancel-ask.png b/docs/imager/native-16-cancel-ask.png
new file mode 100644
index 0000000..458f348
Binary files /dev/null and b/docs/imager/native-16-cancel-ask.png differ
diff --git a/docs/imager/native-17-cancelled.png b/docs/imager/native-17-cancelled.png
new file mode 100644
index 0000000..90fb0b2
Binary files /dev/null and b/docs/imager/native-17-cancelled.png differ
diff --git a/docs/imager/native-18-done.png b/docs/imager/native-18-done.png
new file mode 100644
index 0000000..a4ea073
Binary files /dev/null and b/docs/imager/native-18-done.png differ
diff --git a/docs/imager/native-19-options.png b/docs/imager/native-19-options.png
new file mode 100644
index 0000000..07ce910
Binary files /dev/null and b/docs/imager/native-19-options.png differ