diff --git a/setup/preflight.test.md b/setup/preflight.test.md
new file mode 100644
index 0000000..556f3d1
--- /dev/null
+++ b/setup/preflight.test.md
@@ -0,0 +1,52 @@
+# preflight.test.ts — test suite summary
+
+Smoke tests for the preflight orchestrator (`setup/preflight.ts`), which runs
+the 12 setup steps before installation.
+
+## Setup / mocks
+
+- `spawnSync` is stubbed so no real subprocesses run — every call returns exit 0 by default
+- `fs.writeFileSync` / `mkdirSync` are stubbed to capture what gets written without touching disk
+- `process.exit` is spied on so a failing preflight does not kill the test runner
+- Two helpers extract the outputs: `getSummaryJson()` and `getSummaryEnv()` parse what was written to `summary.json` / `summary.env`
+
+## 5 describe blocks, 17 tests
+
+### basic run (no flags)
+
+All 12 steps run in the correct order:
+
+```
+environment → pi-config → jails → db → git → cms →
+hosts → mounts → telegram-auth → service → verify → doctor
+```
+
+- `summary.json` has `overallStatus: success`
+- `summary.env` has `OVERALL_STATUS=success`, `WITH_ONBOARDING=false`, `CAPTURE_PASSWORD_STEP=false`
+- `process.exit` is not called
+
+### failure handling
+
+- A single failing step does not abort the run — all 12 still execute
+- `overallStatus` becomes `failed`
+- `process.exit(1)` is called
+- `--fail-fast` stops after the first failure (only 1 npm call, then exit 1)
+
+### --with-onboarding
+
+- The interactive onboarding step skips gracefully in a non-TTY environment (test runner has no TTY)
+- All 12 non-interactive steps still run
+- `overallStatus` is `failed` because onboarding itself fails without a TTY
+- `WITH_ONBOARDING=true` appears in `summary.env`
+
+### --capture-password-step
+
+- Implies `--with-onboarding` (verified via `summary.json` args)
+- The Python screenshot capture does NOT run when onboarding failed (no TTY)
+- `CAPTURE_PASSWORD_STEP=true` appears in `summary.env`
+
+### summary output structure
+
+- Every step result in `summary.json` has all required fields: `id`, `label`, `commandLine`, `exitCode`, `status`, `startedAt`, `finishedAt`, `logFile`
+- Log file paths are bare filenames with no path separator (e.g. `environment.log`)
+- `summary.env` contains a `*_STATUS=` and `*_EXIT_CODE=` line for every step