diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7cf9ecd..1200826 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,27 @@ Everything below is opt-in. Notes for existing consumers:
 - `StepError` messages are richer (multi-line, with artifact paths). If you parsed them, prefer the new structured `error.artifacts` field.
 - The timing manifest gained optional fields (`lang`, `capture`). Old kept work dirs still post-process fine.
 
+## 0.10.0 — teardown safety & authoring state
+
+A second dogfooding pass (umami again, on 0.9.0) surfaced a cluster of setup/teardown lifecycle gaps and the ergonomic hole the new per-tutorial setup opened. Additive for normal use — existing tutorials and adapters render unchanged. One type-only caveat: `StepContext` gained a required `state` field, so if you construct a `StepContext` object literal yourself (e.g. a test harness) it now needs that field; code that merely *receives* `ctx` in a callback is unaffected.
+
+Bug fixes (teardown coverage):
+
+- **Setup-phase failures no longer leak.** A throw in `adapter.setup` or `tutorial.setup` now runs the full teardown chain (step `onTeardown` thunks → `tutorial.teardown` → `adapter.teardown`) before rethrowing, instead of only `browser.close()`. `ctx.onTeardown` registered inside a `setup()` now means what it looks like it means, on the path most likely to seed-then-throw (a flaky sign-in, a warm-up `goto` timeout) (#15).
+- **`preview` no longer leaks the adapter seed.** It now runs the *full* teardown chain on every exit path, not just the step thunks. `preview` is the run-repeatedly iterate tool, so the previous behavior (clean up step data, leak the adapter seed) quietly filled a shared test DB. Teardown hooks should tolerate the partial, mid-tutorial state `preview` reaches (#16).
+- **Partial contact sheet on failure.** A failed render with `--contact-sheet`/`contactSheet` now emits a partial sheet of the steps that completed plus the failure frame as the last cell, instead of nothing — the at-a-glance view you most want for a failing run (#20).
+- The `ctx.onTeardown` callback return type is widened to `() => unknown | Promise<unknown>` (the result is awaited and discarded), so value-returning cleanups like `() => Promise.all(...)` typecheck without a wrapper (#21).
+
+New (additive API):
+
+- **`ctx.state` — a typed, per-render state channel.** `adapter.setup`'s return value lands on `ctx.state`, which `tutorial.setup` and steps read — replacing the module-global + `!`-assertion handoff with something scoped to one render (parallel-safe). Steps can also stash a live-created id on it for their own `onTeardown`. Typed end-to-end via `TutorialAdapter<S>` / `tutorial<S>` / `step<S>` (#17).
+- **`tutorial-forge doctor --setup`** actually runs `adapter.setup` once and tears it down, catching the "reachable but pointed at the wrong database" class of failure — a green reachability check followed by a guaranteed sign-in failure — before you wait out a whole render. Exposed programmatically as `probeAdapterSetup(adapter)`. Off by default (it seeds + signs in for real) (#19).
+
+Docs:
+
+- The "Settling" section now warns that `settleUntil: 'networkidle'` races React `startTransition`-deferred Server Actions (the standard Next.js App Router mutation) and steers those to `waitFor` on the committed UI (#18).
+- Adapters docs gain a `ctx.state` section and a teardown-coverage matrix spelling out which hooks run on each path — clean finish, step failure, setup failure, `preview`, `doctor --setup` (#23).
+
 ## 0.9.0 — authoring loop
 
 Ergonomics from a real-world dogfooding pass (authoring tutorials for the umami app). Additive for normal use — existing tutorials and adapters render unchanged. One type-only caveat: `StepContext` gained a required `onTeardown` method, so if you construct a `StepContext` object literal yourself (e.g. in a test harness) it now needs that field; code that merely *receives* `ctx` in a callback is unaffected.
diff --git a/ISSUE-ACTION-REPORT.md b/ISSUE-ACTION-REPORT.md
index fa35779..b5d406e 100644
--- a/ISSUE-ACTION-REPORT.md
+++ b/ISSUE-ACTION-REPORT.md
@@ -1,210 +1,77 @@
 # tutorial-forge — Issue Action Report
 
-_Prepared 2026-06-13 against `main` (v0.8.0). Author: maintainer review._
+_Prepared 2026-06-13 against `main` (v0.9.0 → v0.10.0). Author: maintainer review._
 
-All eight open issues except #1 came out of a single real-world authoring session:
-building the umami "steward how-to" tutorials (`run-an-event`, `send-a-broadcast`) on
-v0.8.0. They are field notes from someone actually authoring a non-trivial tutorial, which
-makes them unusually high-signal. #1 predates that session and is a feature proposal.
+Issues #15–#21 came out of a second real-world dogfooding session: authoring the umami
+"steward how-to" tutorials (`run-an-event`, `send-a-broadcast`) on **v0.9.0**, the release
+that added per-tutorial setup/teardown (#8). #22–#23 are gaps filed during this review.
+(The prior round — #8–#14, the authoring inner loop — shipped in 0.9.0; this report
+supersedes that one.)
 
 ---
 
 ## Executive summary
 
-The umami session exposed one dominant theme: **the authoring inner loop is slow and
-blind.** An author writes steps, runs a full render, and then cannot easily tell whether
-the result is correct without scrubbing video or hand-extracting frames with ffmpeg.
-Concretely, the pain clusters into three groups:
+The dominant theme: **the setup/teardown lifecycle #8 introduced has a correctness hole
+and an ergonomic hole.** Six of seven issues cluster there.
 
-1. **Slow, blind iteration (the core pain).** Re-recording all steps to tune step 11 of 13
-   (#11), no way to see per-step output without ffmpeg (#9), and no feedback that a feature
-   (idleSpeedup) even did anything (#13). These are about closing the edit→verify loop.
+- **Correctness:** teardown didn't run on the setup-failure path (#15) or fully on the
+  `preview` path (#16), so a shared test DB silently accumulated leaked rows.
+- **Ergonomics:** there was no first-class channel for `tutorial.setup`/steps to read what
+  `adapter.setup` established, forcing a module-global + `!` handoff (#17).
+- Plus a settling foot-gun in the standard Next.js mutation pattern (#18), a doctor blind
+  spot (#19), a missing failure-time diagnostic (#20), and a type papercut (#21).
 
-2. **Choreography gaps on non-click interactions (the most visible output-quality bug).**
-   `selectOption` / `fill` / `check` on off-screen or native controls produce "visually
-   dead frames" — narration talking about a control the camera never moves to or scrolls
-   into view (#10). This directly degrades the rendered video, which is the product.
-
-3. **Setup/teardown and readiness ergonomics (workarounds the author had to invent).**
-   A single global adapter forced state hacks and data leaks across tutorials (#8); fixed
-   `settleMs` magic numbers stood in for a real "wait until settled" signal (#14); and
-   `doctor` didn't catch the single most common failure — the app not running (#12).
-
-`forge publish` (#1) is a separate, forward-looking distribution feature, not session
-friction.
-
-A notable finding from reading the code: **#10 and #13 are already partly built**, which
-changes their effort and framing (details below). #13 is essentially a one-line fix.
-
----
-
-## Per-issue assessment
-
-Importance: Critical / High / Medium / Low. Effort: S (hours) / M (a day or two) / L (multi-day).
-
-| # | Title (restated) | Importance | Effort | Notes / dependencies |
-|---|---|---|---|---|
-| 13 | Log idleSpeedup even when it compresses nothing | Medium | **S** | One-line fix; already 90% there. Quick win. |
-| 12 | `doctor` probes adapter `baseURL` reachability | High | S–M | Needs doctor to load config (it currently doesn't). Big friction-per-effort. |
-| 9 | Keep per-step screenshots on success + contact sheet | High | M | Reuses existing `--debug` screenshot path. Core to the verify loop. |
-| 10 | Cursor/callout/auto-scroll for fill/select/check | High | M | **Partly done already** — see below. Real gap is auto-scroll. Output quality. |
-| 11 | Render a step range / single-step preview | High | M–L | Hardest of the loop trio (state deps). Biggest time saver if solved. |
-| 14 | Docs: settleMs vs waitFor + a network-idle settle | Medium | S (docs) / M (helper) | Split: docs are S; `settleUntil` helper is M. |
-| 8 | Per-tutorial setup/teardown hooks + step teardown | High | M | Type + pipeline change; backward-compatible. Removes real workarounds. |
-| 1 | `forge publish` to hosting (Vimeo first) | Low (now) | L | Net-new surface, external API auth, well-specced but premature. |
-
-### #13 — idleSpeedup logs nothing on a no-op  · Medium · S
-**Verified in code.** `packages/core/src/pipeline/post.ts` lines 85–98 only log inside
-`if (segments.length > 0)`. When idleSpeedup runs but finds no span over the threshold, it
-emits nothing — exactly the reported symptom. By contrast zoom always logs (line 132). Fix
-is to add an `else` branch (`idle: no spans over <maxIdleMs>ms`) and, ideally, normalize the
-existing line to the issue's suggested phrasing. Trivial, high-confidence, no risk. **Best
-first quick win.**
-
-### #12 — `doctor` doesn't check the app is up  · High · S–M
-**Verified.** `packages/cli/src/doctor.ts` checks node/ffmpeg/ffprobe/chromium/TTS env vars
-but never loads the config or touches `adapter.baseURL`. "Forgot to start the dev server" is
-the single most common real failure and currently surfaces as a Playwright navigation
-timeout deep inside a render. Effort is S–M only because `doctor` must now load
-`forge.config.ts` (the render path already does this via `cli/src/load.ts`, so it's
-reusable). Keep it best-effort: skip cleanly if no config is resolvable, so `doctor` stays
-useful outside a project. The issue's pnpm aside (`pnpm exec ... doctor` fails on an
-ignored-builds pre-check) is a real, separate docs nit worth a one-liner.
-
-### #9 — Keep success screenshots + contact sheet  · High · M
-**Verified gap.** Screenshots are written only on failure (`captureFailure`) or in
-`--debug` (`debugScreenshot`, `packages/core/src/pipeline/record.ts`). The infrastructure
-already exists — the work is (a) optionally keep an end-of-step screenshot on success, and
-(b) assemble a labeled contact-sheet PNG (ffmpeg `tile` or montage of the per-step shots).
-This is the cheapest direct answer to "a passing render doesn't prove the right thing
-rendered," which the author called their *entire verification loop*. Recommend `--contact-
-sheet` opt-in (default-on risks slowing every render). Pairs naturally with #11.
-
-### #10 — Choreography for non-click interactions  · High · M (reduced)
-**Partially implemented already — re-scope before building.** In
-`packages/core/src/browser/instrument.ts`: `ACTION_METHODS` already includes `fill`,
-`check`, `uncheck`, `selectOption`, so the **cursor already travels** to those targets; and
-`CLICK_METHODS` already includes `selectOption`/`check`/`uncheck`, so they **already get the
-ring + pulse**. So the issue is partly stale. The genuine remaining gaps:
-  - **No auto-scroll-into-view anywhere.** `presentAction` reads `boundingBox()` but never
-    scrolls the element into frame — this is the actual umami `<select>` "off-screen,
-    visually dead" complaint and the reason the author hand-wrote `scrollIntoView`. This is
-    the highest-value part.
-  - **`fill` gets a cursor move but no ring** (it's in `ACTION_METHODS`, not
-    `CLICK_METHODS`) — arguably correct (typing isn't a click), but worth a deliberate
-    decision.
-  - **Optional `step(..., { focus: locator })`** as an explicit anchor for narration about a
-    control not directly acted on.
-
-Reframe the issue around auto-scroll + the explicit `focus` anchor; the cursor/ring part is
-mostly done. This is the most visible *output-quality* win.
-
-### #11 — Step-range / single-step preview  · High · M–L
-**Verified gap.** No `--steps` flag in `cli/src/main.ts`; `runRecordPhase` always loops all
-steps. The biggest time saver in the loop-pain cluster, and the hardest because of inter-step
-state dependencies. The issue's own framing is the right one: don't promise arbitrary ranges
-first. Ship the **single-step preview** (run `adapter.setup()` + prior steps' `run()` to
-reach state, then execute just the target step and dump a screenshot — no encode) before any
-true range render. Depends on #9's screenshot machinery; build #9 first, then #11 reuses it.
-
-### #14 — settleMs vs waitFor docs + network-idle settle  · Medium · S (docs) / M (helper)
-**Verified.** `docs/writing-tutorials.md` mentions `settleMs` and `waitFor` (lines ~32–44)
-but has no "which tool when / avoid magic numbers" mental-model section. The author tuned
-600/800/1200/1500 by trial-and-render because there's no DOM signal after a `router.refresh()`
-repaint. **Split this:** the docs section is an S quick win and should ship immediately; the
-`settleUntil: 'networkidle'` helper is a separate M enhancement (real product surface — a new
-step option) that can wait.
-
-### #8 — Per-tutorial setup/teardown hooks  · High · M
-**Verified.** The `Tutorial` type (`packages/core/src/types.ts`) exposes only
-`id/title/description/steps/translations`; `runRecordPhase` only ever calls
-`adapter.setup`/`adapter.teardown`. Two tutorials needing different starting states is
-unsolvable today, which forced the author into a "(demo)" naming convention + a purge helper
-and caused data to leak between renders. The proposal is clean and backward-compatible:
-optional `setup?`/`teardown?` on the tutorial spec composing with the adapter, plus
-`ctx.onTeardown(fn)` so a step can register deterministic cleanup for data it creates. This
-removes a genuine workaround and unblocks multi-tutorial repos (umami being exactly that).
-
-### #1 — `forge publish` to Vimeo  · Low now · L
-**Verified net-new.** No `publish` command in `cli/src/main.ts`; no `PublishTarget` in
-`core/src/index.ts`. The design is thorough (provider interface, `published.json` mapping,
-content-hash idempotency, Vimeo replace-in-place). But it's a large surface with external API
-auth/review, and it doesn't address any session friction — you can't publish a video you're
-struggling to author correctly. **Defer until the authoring loop is solid.** Keep the issue
-open as the agreed design; don't start it this cycle.
-
----
-
-## What's most important to fix
-
-Ranked by author value per unit effort, grounded in "this is what made the umami session
-painful":
-
-1. **#13 (S)** — one-line observability fix; do it immediately.
-2. **#12 (S–M)** — kills the most common confusing failure at the front door.
-3. **#9 (M)** — gives authors a way to *verify* output without ffmpeg; foundational for #11.
-4. **#10 auto-scroll (M)** — the most visible defect in the rendered video itself; partly
-   done, so cheaper than it looks.
-5. **#11 single-step preview (M–L)** — the biggest raw time-saver; build on #9.
-6. **#8 (M)** — unblocks real multi-tutorial repos and removes a data-leak workaround.
-
-#9 → #11 is the one hard dependency to respect (preview reuses the per-step screenshot
-machinery). #14-docs and the #10-rescope are essentially free clarifying wins to fold in.
+All shipped together as **0.10.0** (a minor: it includes additive API — `ctx.state`,
+`probeAdapterSetup`, `doctor --setup`). Bug fixes + additive API in one release was simpler
+than the originally-proposed 0.9.1/0.10.0 split and matches how the work actually landed.
 
 ---
 
-## Plan of action (phased)
-
-**Phase 0 — Quick wins (ship as a 0.8.x patch, ~1 day total).**
-- #13 idleSpeedup no-op log line (one-line change in `post.ts`).
-- #14 *docs only*: add the settleMs-vs-waitFor mental-model section to
-  `writing-tutorials.md`; add the pnpm `doctor` note from #12's aside.
-- #10 *triage*: edit the issue to reflect that cursor+ring already cover select/check and
-  rescope it to auto-scroll + `focus` anchor (do this before estimating the build).
-
-**Phase 1 — Close the authoring loop (a 0.9.0 "authoring DX" release).**
-- #12 doctor reachability probe (load config, probe `baseURL`).
-- #9 success screenshots + `--contact-sheet`.
-- #11 single-step preview (reuses #9 screenshot path). Defer arbitrary `--steps` ranges.
-
-**Phase 2 — Output quality + state model (0.10.0).**
-- #10 auto-scroll-into-view in `presentAction`; optional `step({ focus })`.
-- #8 per-tutorial `setup`/`teardown` + `ctx.onTeardown`.
-- #14 *helper*: `settleUntil: 'networkidle'` step option.
-
-**Phase 3 — Distribution (later, own release).**
-- #1 `forge publish` (Vimeo first), only once authoring is solid.
-
-Quick wins: #13, #14-docs, #12. Larger efforts: #11, #8, #1.
-
----
-
-## Can be disregarded / deferred
-
-- **#1 `forge publish` — defer (not disregard).** Well-designed but premature: it's a large
-  external-API surface that solves distribution, while every other open issue says authoring
-  itself is still rough. Revisit after Phase 1–2. Keep the issue as the design of record.
-- **#10 cursor/ring portion — already shipped.** Don't rebuild cursor travel or the
-  click ring for select/check; only auto-scroll and the `focus` anchor remain. Rescope, don't
-  re-implement.
-- **#14 network-idle helper — split out and defer** behind the (free) docs section. The docs
-  resolve most of the friction; the helper is a nice-to-have new surface.
-- **#11 arbitrary `--steps from..to` ranges — defer within the issue.** State dependencies
-  make true ranges unreliable; ship single-step preview only and don't over-promise ranges.
-
----
-
-## Recommended issue housekeeping (no edits made)
-
-- **#10**: add a comment/relabel noting cursor + ring already cover `selectOption`/`check`
-  (`instrument.ts` `ACTION_METHODS`/`CLICK_METHODS`) and rescoping to auto-scroll + `focus`.
-- **#14**: consider splitting into a `documentation` issue (mental model, ready now) and an
-  `enhancement` issue (`settleUntil` helper).
-- **#12**: capture the pnpm `doctor` ignored-builds docs note as its own `good first issue`.
-
-## Possible gap not yet tracked (noted, not filed)
-
-No open issue covers **multi-tutorial UX more broadly** — the render summary, `list`, and
-output naming are all single-tutorial-shaped, and the umami session was inherently
-multi-tutorial (it surfaced via #8's shared-adapter problem). Worth watching as #8 lands; not
-yet worth its own issue.
+## Per-issue disposition
+
+| # | Title | Disposition | Where |
+|---|---|---|---|
+| #15 | Setup-phase failures skip teardown | **Fixed** — setup wrapped; full chain runs then rethrows | `record.ts` |
+| #16 | preview leaks the adapter seed | **Fixed** — preview runs full teardown chain on every exit | `preview.ts` |
+| #17 | adapter→tutorial state channel | **Implemented** — typed `ctx.state`; adapter return lands on it | `types.ts`, `step-hooks.ts` |
+| #18 | networkidle races startTransition | **Docs done (18a)**; React-idle settle **deferred (18b)** | `writing-tutorials.md`, `types.ts` |
+| #19 | doctor validates adapter.setup | **Implemented** — `doctor --setup` / `probeAdapterSetup` | `preflight.ts`, `doctor.ts` |
+| #20 | partial contact sheet on failure | **Fixed** — emitted from the failure path | `render.ts` |
+| #21 | widen onTeardown return type | **Fixed** — `() => unknown \| Promise<unknown>` | `types.ts`, `step-hooks.ts` |
+| #22 | e2e assert teardown coverage | **Done** — new e2e + unit coverage | `e2e.ts`, `step-hooks.test.ts` |
+| #23 | document teardown matrix | **Done** — matrix + ctx.state section | `adapters.md` |
+
+## Decisions taken (PM recommendations, all adopted)
+
+- **D1 (#15):** On a setup throw, run the **full** teardown chain. Safe because every hook
+  is guarded (`safeTeardown`), so teardown against half-built state logs rather than masks.
+  Contract documented: teardown hooks must tolerate partial setup.
+- **D2 (#16):** `preview` runs **full teardown by default** (a `--keep` opt-out can come
+  later if it proves slow). A quick-iterate tool must not dirty a shared DB.
+- **D3 (#17):** Typed, returned **`ctx.state`** via `TutorialAdapter<S>` → `StepContext<S>`
+  (parallel-safe; cleanest to type end-to-end). Defaults to `{}` so steps can always stash.
+- **D4 (#18):** **Docs only** for now; the React-aware settle (18b) is deferred — the
+  principled answer is `waitFor` on committed UI, and a generic settle can't observe
+  React's transition queue without a heuristic that may trade one race for another.
+- **D5 (#20):** Partial sheet emitted **next to the intended output** (survives like the
+  success path) with the failure frame appended as the last cell.
+
+## Shared design note
+
+#15, #16, and #19 all needed "run the teardown chain safely," so that logic was extracted
+once into `runTeardownChain()` in `pipeline/step-hooks.ts` and is now the single entry point
+for record, preview, and the doctor probe.
+
+## Follow-ups / deferred
+
+- **#18b** (filed) — a React-idle `settleUntil` variant. Design-gated; revisit only if the
+  `waitFor` guidance proves insufficient in practice.
+- **`preview --keep`** — opt-out of preview teardown, only if full teardown proves too slow.
+
+## Verification
+
+`pnpm typecheck` (core, cli, example-app) clean · `pnpm test` (97 unit tests) green ·
+`pnpm e2e` green, including new assertions for setup-failure teardown, preview teardown,
+`ctx.state` handoff, `probeAdapterSetup` (success + failure-still-tears-down), and the
+partial failure contact sheet.
diff --git a/docs/adapters.md b/docs/adapters.md
index 022ce70..67d6bf3 100644
--- a/docs/adapters.md
+++ b/docs/adapters.md
@@ -46,7 +46,59 @@ export default tutorial('Create your first event', steps, {
 });
 ```
 
-Run order is **adapter.setup → tutorial.setup** going in, and **step `onTeardown` thunks (LIFO) → tutorial.teardown → adapter.teardown** coming out. Teardown runs even when a step fails mid-render, so data created before the failure is still cleaned up. Tutorials without hooks keep working through the adapter alone.
+Run order is **adapter.setup → tutorial.setup** going in, and **step `onTeardown` thunks (LIFO) → tutorial.teardown → adapter.teardown** coming out. Tutorials without hooks keep working through the adapter alone.
+
+The teardown chain runs on **every** exit path of a render — clean finish, a step failure, *and* a failure inside `adapter.setup`/`tutorial.setup` — so data created (and any `ctx.onTeardown` registered) before a throw is always cleaned up, never leaked into a shared test DB. Each hook is guarded: a teardown that runs against half-built state (e.g. after a setup failure) logs a warning instead of masking the original error. Because of this, **write teardown hooks to tolerate partial setup** (null-check what you delete).
+
+### Sharing state between the adapter and a tutorial
+
+`tutorial.setup` and steps usually need what `adapter.setup` established — the signed-in identity, a seeded id. Return it from `adapter.setup` and it lands on **`ctx.state`**, a per-render bag (scoped to one render, so it's parallel-safe). No module-global handoff, no `!` assertions:
+
+```ts
+interface Seed { steward: Person }
+
+export const adapter: TutorialAdapter<Seed> = {
+  baseURL: 'http://localhost:3000',
+  async setup(page) {
+    const steward = await seedSteward();
+    await signIn(page, steward);
+    return { steward }; // → ctx.state
+  },
+  async teardown(page, ctx) {
+    await deletePerson(ctx.state.steward.id);
+  },
+};
+
+// Read it in the tutorial — typed via tutorial<Seed>/step<Seed>:
+export default tutorial<Seed>('Send a broadcast', [
+  step<Seed>('Create an event.', async (page, ctx) => {
+    await createEvent(page, ctx.state.steward);
+    const id = new URL(page.url()).pathname.split('/').pop()!;
+    ctx.state.eventId = id;               // steps can stash live-created ids…
+    ctx.onTeardown(() => deleteEvent(id)); // …for their own cleanup
+  }),
+], {
+  async setup(page, ctx) {
+    await seedEventFor(ctx.state.steward); // reads what the adapter established
+  },
+});
+```
+
+A teardown thunk's return value is awaited and discarded, so value-returning one-liners work directly: `ctx.onTeardown(() => Promise.all(people.map((p) => deletePerson(p.id))))`.
+
+### Teardown coverage matrix
+
+Which hooks run on each path:
+
+| Path | step `onTeardown` | `tutorial.teardown` | `adapter.teardown` |
+|---|---|---|---|
+| Render — clean finish | ✓ | ✓ | ✓ |
+| Render — a step fails | ✓ (for completed steps) | ✓ | ✓ |
+| Render — `adapter.setup`/`tutorial.setup` throws | ✓ (registered before the throw) | ✓ | ✓ |
+| `preview <step>` (any outcome) | ✓ | ✓ | ✓ |
+| `doctor --setup` | ✓ | n/a (no tutorial) | ✓ |
+
+`preview` reaches partial, mid-tutorial state yet still runs the full chain — it's run repeatedly while tuning a step, so leaving the adapter seed behind would quietly fill the DB. (This is why teardown hooks must tolerate partial setup.)
 
 For data a *step* creates mid-tutorial, register cleanup inline with `ctx.onTeardown()` instead of tracking it in the adapter:
 
@@ -67,4 +119,5 @@ Thunks run in reverse registration order, so the last thing created is the first
 - **Seed deterministic state.** Same inputs should produce the same video. Create fixture data with fixed names/dates; avoid "3 minutes ago"-style relative content where you can.
 - **Run your app yourself.** The pipeline does not start your dev server; do that before `tutorial-forge render` (or in your CI job before the render step).
 - **Keep secrets in env vars.** The adapter is plain code in your repo; read credentials from the environment, as in any e2e test.
-- **Teardown failures are non-fatal.** They log a warning and the render still succeeds — teardown runs after the manifest is final.
+- **Teardown failures are non-fatal, and must tolerate partial setup.** They log a warning and the render still succeeds — teardown runs after the manifest is final, and also after a *failed* setup, so null-check what you delete.
+- **Verify setup before a full render.** `tutorial-forge doctor` checks the app is reachable; add `--setup` to actually run `adapter.setup` once and tear it down. It catches the "reachable but pointed at the wrong database" case — a green reachability check followed by a guaranteed sign-in failure — before you wait out a whole render.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index fca774a..1d163a5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -13,7 +13,7 @@ You also need `ffmpeg` and `ffprobe` (≥ 6) on PATH. Verify everything with:
 pnpm exec tutorial-forge doctor
 ```
 
-Run this from your project directory so `doctor` can read `forge.config.ts` and probe that the app at your adapter's `baseURL` is up — the most common render failure is simply forgetting to start the dev server.
+Run this from your project directory so `doctor` can read `forge.config.ts` and probe that the app at your adapter's `baseURL` is up — the most common render failure is simply forgetting to start the dev server. Add `--setup` (`tutorial-forge doctor --setup`) to go one step further and actually run `adapter.setup` once, tearing it down afterward — this catches a reachable-but-mispointed server (e.g. the dev server on the wrong database) that would otherwise pass reachability and then fail every render at sign-in.
 
 > **pnpm note:** if `pnpm exec tutorial-forge …` trips pnpm's ignored-builds pre-check, invoke the bin directly (`./node_modules/.bin/tutorial-forge …`) or approve the build with `pnpm approve-builds`.
 
diff --git a/docs/writing-tutorials.md b/docs/writing-tutorials.md
index e87fd5d..fbf0341 100644
--- a/docs/writing-tutorials.md
+++ b/docs/writing-tutorials.md
@@ -67,7 +67,7 @@ After a step's action, the recording needs to wait until the app has visually ca
 | | What it waits on | Use when |
 |---|---|---|
 | **`waitFor`** | A DOM signal you choose (a locator appears, text changes, a spinner detaches) | There's a specific element/state that marks "done". This is the principled default — it waits exactly as long as needed, no more. |
-| **`settleUntil`** | A page load-state signal (`networkidle` / `load` / `domcontentloaded`) | There's *no* clean DOM signal — e.g. a `router.refresh()` that just repaints, or a navigation whose result you don't want to assert on. `'networkidle'` waits for in-flight requests to quiesce. |
+| **`settleUntil`** | A page load-state signal (`networkidle` / `load` / `domcontentloaded`) | There's *no* clean DOM signal — e.g. a `router.refresh()` that just repaints, or a navigation whose result you don't want to assert on. `'networkidle'` waits for in-flight requests to quiesce. **Not** for `startTransition`-deferred Server Actions — see the warning below. |
 | **`settleMs`** | A fixed number of milliseconds | A last resort, or a deliberate on-screen beat *after* readiness (e.g. let an animation finish, or hold the final frame a touch longer). |
 
 Rule of thumb: **if you can name the thing you're waiting for, use `waitFor`.** If the only signal is "the network went quiet," use `settleUntil: 'networkidle'`. Only fall back to `settleMs` for a deliberate pause or when nothing else applies — and keep it small.
@@ -86,6 +86,22 @@ step('The list refreshes with your new row.', async (page) => {
 
 `settleUntil` is **best-effort and bounded** (~5s): a page that never goes idle — websockets, polling, server-sent events — logs and proceeds rather than failing the render, so it's safe to use even when you're not sure the app quiesces. `settleUntil` and `settleMs` compose: the signal-based wait happens first, then `settleMs` adds its on-screen hold.
 
+> **`networkidle` races React `startTransition` — prefer `waitFor` for deferred mutations.** The standard Next.js App Router mutation — a controlled input whose `onChange` runs `startTransition(async () => { await someServerAction(); router.refresh() })` — does **not** dispatch its request synchronously. At the instant your `selectOption`/`click` returns, React hasn't fired the action's fetch yet, so the page is *momentarily* network-idle and `settleUntil: 'networkidle'` can resolve against the **pre-mutation** UI (the screenshot shows the old value). It often lands correctly by luck (the request is usually in flight by the time Playwright polls), but it's timing-dependent. Don't reach for `networkidle` here — wait on the committed result instead:
+>
+> ```ts
+> // ❌ races the transition — can settle before the server action even dispatches
+> step('Switch the status to Tickets open.', async (page) => {
+>   await page.getByLabel('Status').selectOption('open');
+> }, { settleUntil: 'networkidle' })
+>
+> // ✅ wait on the committed UI — exactly as long as the repaint takes, no race
+> step('Switch the status to Tickets open.', async (page) => {
+>   await page.getByLabel('Status').selectOption('open');
+> }, { waitFor: (page) => page.getByText('Tickets open').waitFor() })
+> ```
+>
+> Reserve `settleUntil: 'networkidle'` for cases with no committed-state signal to name — a `router.refresh()`/reload that only repaints existing data, or a navigation whose result you don't assert on.
+
 ## Iterating on a step
 
 A passing render only proves your selectors *resolved* — not that the right thing was on screen. A step that locates a wrong-but-valid element (or one scrolled off-screen) succeeds silently. Two helpers close that gap without re-recording the whole tutorial every cycle:
@@ -99,7 +115,7 @@ tutorial-forge preview set-status --only my-tutorial
 
 > Prior-step state is reached by replaying earlier `run()`/`waitFor()` callbacks in order — exactly what a real render does — so anything those steps set up (navigation, form state, seeded data) is present. Only the target step's `settleMs` hold is honored; intermediate pacing is skipped for speed.
 
-**`tutorial-forge render --contact-sheet`** keeps a settled screenshot per step and emits a labeled grid PNG next to the video (`<name>-contact-sheet.png`), one thumbnail per step tagged with its id and narration. Scan it to confirm every step framed the right thing at a glance, instead of scrubbing the video. Enable it persistently with `contactSheet: true` in `forge.config.ts`.
+**`tutorial-forge render --contact-sheet`** keeps a settled screenshot per step and emits a labeled grid PNG next to the video (`<name>-contact-sheet.png`), one thumbnail per step tagged with its id and narration. Scan it to confirm every step framed the right thing at a glance, instead of scrubbing the video. Enable it persistently with `contactSheet: true` in `forge.config.ts`. If a step fails mid-render, you still get a **partial** sheet of the steps that completed plus the failure frame as the last cell — the at-a-glance view of how the run got to the failure.
 
 ## Timing manifest
 
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 87e83e2..cbeec3e 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "tutorial-forge-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "CLI for tutorial-forge: render scripted Playwright walkthroughs into narrated tutorial videos",
   "type": "module",
   "license": "MIT",
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index e723066..ad310c3 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { ffmpegVersion } from 'tutorial-forge';
+import { ffmpegVersion, probeAdapterSetup, type ForgeConfig } from 'tutorial-forge';
 import { loadConfig } from './load.js';
 
 interface Check {
@@ -36,7 +36,7 @@ async function probeReachable(baseURL: string, timeoutMs = 3000): Promise<Check>
   }
 }
 
-export async function doctorCommand(opts: { config?: string } = {}): Promise<void> {
+export async function doctorCommand(opts: { config?: string; setup?: boolean } = {}): Promise<void> {
   const checks: Check[] = [];
 
   const nodeMajor = parseInt(process.versions.node.split('.')[0]!, 10);
@@ -81,10 +81,15 @@ export async function doctorCommand(opts: { config?: string } = {}): Promise<voi
   // App reachability: only when we can resolve a baseURL from the config.
   // A missing/broken config is the render command's problem to report, not
   // doctor's — here it just means we skip the probe rather than fail.
+  let config: ForgeConfig | null = null;
   try {
-    const config = await loadConfig(process.cwd(), opts.config);
-    checks.push(await probeReachable(config.adapter.baseURL));
+    config = await loadConfig(process.cwd(), opts.config);
   } catch {
+    /* no config — handled below */
+  }
+  if (config) {
+    checks.push(await probeReachable(config.adapter.baseURL));
+  } else {
     checks.push({
       name: 'app reachable',
       ok: true,
@@ -92,6 +97,27 @@ export async function doctorCommand(opts: { config?: string } = {}): Promise<voi
     });
   }
 
+  // Opt-in (--setup): actually run adapter.setup and tear it down, catching the
+  // wrong-database / unseedable-target class of failure that a reachable but
+  // mispointed dev server hides behind a green check. Off by default because it
+  // seeds + signs in for real (#19).
+  if (opts.setup) {
+    if (config) {
+      try {
+        await probeAdapterSetup(config.adapter);
+        checks.push({ name: 'adapter.setup', ok: true, detail: 'ran and tore down cleanly' });
+      } catch (err) {
+        checks.push({
+          name: 'adapter.setup',
+          ok: false,
+          detail: `${err instanceof Error ? err.message : String(err)} — is the dev server pointed at the right database?`,
+        });
+      }
+    } else {
+      checks.push({ name: 'adapter.setup', ok: true, detail: 'skipped (no forge.config found)' });
+    }
+  }
+
   let failed = false;
   for (const c of checks) {
     console.log(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(22)} ${c.detail}`);
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index e5479a0..5b40836 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -74,6 +74,7 @@ program
   .command('doctor')
   .description('check the environment (node, ffmpeg, playwright, TTS env vars, app reachability)')
   .option('--config <path>', 'path to forge.config.ts')
+  .option('--setup', "also run the adapter's setup() and tear it down, to catch a wrong-database/unseedable target")
   .action(doctorCommand);
 
 program
diff --git a/packages/core/package.json b/packages/core/package.json
index 193e7ff..6d3ead4 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "tutorial-forge",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Turn scripted Playwright walkthroughs into narrated tutorial videos (MP4). Tutorials are source code: re-render instead of re-recording when your UI changes.",
   "type": "module",
   "license": "MIT",
diff --git a/packages/core/src/i18n.ts b/packages/core/src/i18n.ts
index 626a4c2..d816f4c 100644
--- a/packages/core/src/i18n.ts
+++ b/packages/core/src/i18n.ts
@@ -12,7 +12,7 @@ import { logger } from './util/logger.js';
  * - A language with no table at all throws: rendering a wholly untranslated
  *   tutorial under a language suffix would silently produce a mislabeled video.
  */
-export function localizeTutorial(tutorial: Tutorial, lang: string, defaultLang = 'en'): Tutorial {
+export function localizeTutorial<S = unknown>(tutorial: Tutorial<S>, lang: string, defaultLang = 'en'): Tutorial<S> {
   if (lang === defaultLang) return tutorial;
 
   const table = tutorial.translations?.[lang];
@@ -53,6 +53,6 @@ export function localizeTutorial(tutorial: Tutorial, lang: string, defaultLang =
 }
 
 /** Languages a tutorial can render in: the default language plus every translation table. */
-export function availableLanguages(tutorial: Tutorial, defaultLang = 'en'): string[] {
+export function availableLanguages(tutorial: Pick<Tutorial, 'translations'>, defaultLang = 'en'): string[] {
   return [defaultLang, ...Object.keys(tutorial.translations ?? {}).filter((l) => l !== defaultLang)];
 }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 5ae7d43..231a2f2 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -39,6 +39,7 @@ export {
   type ContactSheetStyle,
 } from './pipeline/contact-sheet.js';
 export { previewStep, type PreviewOptions, type PreviewResult } from './pipeline/preview.js';
+export { probeAdapterSetup } from './pipeline/preflight.js';
 
 export { SilentProvider } from './tts/silent.js';
 export { Piper, type PiperOptions } from './tts/piper.js';
diff --git a/packages/core/src/pipeline/preflight.ts b/packages/core/src/pipeline/preflight.ts
new file mode 100644
index 0000000..4525d88
--- /dev/null
+++ b/packages/core/src/pipeline/preflight.ts
@@ -0,0 +1,53 @@
+import { chromium, type Browser } from 'playwright';
+import type { TutorialAdapter } from '../types.js';
+import { createStepContext, runTeardownChain } from './step-hooks.js';
+
+/**
+ * Exercise `adapter.setup` against the live app once, then tear down whatever it
+ * created. "Reachable" (a 2xx/3xx from baseURL) is necessary but not sufficient:
+ * a dev server pointed at the wrong database answers fine yet fails every render
+ * at sign-in, because the identity the adapter seeds into DB-A doesn't exist in
+ * the DB-B the server reads. Running setup turns that 20-minute detour into one
+ * clear up-front error. Used by `doctor --setup` (#19).
+ *
+ * Throws the setup error (so the caller can report it); always runs teardown
+ * first — even when setup half-completed — so the probe itself never leaks.
+ */
+export async function probeAdapterSetup(
+  adapter: TutorialAdapter,
+  opts: { headless?: boolean } = {},
+): Promise<void> {
+  const browser = await launchChromium(opts.headless ?? true);
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const { ctx, teardownThunks } = createStepContext();
+    try {
+      const state = await adapter.setup(page, ctx);
+      if (state != null) ctx.state = state;
+    } finally {
+      // No tutorial in a doctor probe — just the adapter's own teardown (plus
+      // any onTeardown the setup registered). Guarded, so it can't mask the
+      // setup error we're about to rethrow.
+      await runTeardownChain(page, ctx, {}, adapter, teardownThunks);
+    }
+  } finally {
+    await safeClose(browser.close());
+  }
+}
+
+async function launchChromium(headless: boolean): Promise<Browser> {
+  try {
+    return await chromium.launch({ headless, channel: 'chromium' });
+  } catch {
+    return chromium.launch({ headless });
+  }
+}
+
+async function safeClose(p: Promise<unknown>): Promise<void> {
+  try {
+    await p;
+  } catch {
+    /* already closed */
+  }
+}
diff --git a/packages/core/src/pipeline/preview.ts b/packages/core/src/pipeline/preview.ts
index b2b1ad7..fa24f83 100644
--- a/packages/core/src/pipeline/preview.ts
+++ b/packages/core/src/pipeline/preview.ts
@@ -6,7 +6,7 @@ import { localizeTutorial } from '../i18n.js';
 import { CURSOR_INIT_SCRIPT } from '../browser/cursor.js';
 import { CALLOUT_INIT_SCRIPT } from '../browser/callout.js';
 import { instrumentPage } from '../browser/instrument.js';
-import { anchorFocus, createStepContext, runStepTeardowns, waitForSettle } from './step-hooks.js';
+import { anchorFocus, createStepContext, runTeardownChain, waitForSettle } from './step-hooks.js';
 import { ensureDir } from '../util/fs.js';
 import { logger } from '../util/logger.js';
 
@@ -49,7 +49,7 @@ export interface PreviewResult {
 }
 
 /** Resolve a "step" argument (1-based index or id) to a 0-based index. */
-export function resolveStepIndex(tutorial: Tutorial, step: string): number {
+export function resolveStepIndex<S = unknown>(tutorial: Tutorial<S>, step: string): number {
   const asNum = /^\d+$/.test(step.trim()) ? parseInt(step.trim(), 10) : null;
   if (asNum !== null) {
     if (asNum < 1 || asNum > tutorial.steps.length) {
@@ -65,9 +65,9 @@ export function resolveStepIndex(tutorial: Tutorial, step: string): number {
   return idx;
 }
 
-export async function previewStep(
-  tutorial: Tutorial,
-  adapter: TutorialAdapter,
+export async function previewStep<S = unknown>(
+  tutorial: Tutorial<S>,
+  adapter: TutorialAdapter<S>,
   opts: PreviewOptions,
 ): Promise<PreviewResult> {
   validateTutorial(tutorial);
@@ -89,41 +89,46 @@ export async function previewStep(
     if (callouts || cursor) await context.addInitScript(CALLOUT_INIT_SCRIPT);
 
     const page = await context.newPage();
-    const { ctx, teardownThunks } = createStepContext(opts.lang);
-    logger.info(`preview: setup (${adapter.baseURL})${opts.lang ? ` [${opts.lang}]` : ''}`);
-    await adapter.setup(page, ctx);
-    if (tutorial.setup) await tutorial.setup(page, ctx);
+    const { ctx, teardownThunks } = createStepContext<S>(opts.lang);
+    // Full teardown chain (step thunks → tutorial → adapter), run on every exit
+    // path. preview is the fast iterate-on-one-step tool, run repeatedly by
+    // design, so leaving the adapter seed behind each run quietly fills the
+    // shared test DB — exactly what a quick-iteration tool must not do (#16).
+    // Hooks must tolerate the partial, mid-tutorial state preview reaches; each
+    // is guarded, so a teardown that can't run logs rather than failing.
+    try {
+      logger.info(`preview: setup (${adapter.baseURL})${opts.lang ? ` [${opts.lang}]` : ''}`);
+      const setupState = await adapter.setup(page, ctx);
+      if (setupState != null) ctx.state = setupState as S;
+      if (tutorial.setup) await tutorial.setup(page, ctx);
 
-    // Replay prior steps on the RAW page (no cursor/scroll animation) — we only
-    // need their state, not their framing, so replay stays fast (#11).
-    for (let i = 0; i < target; i++) {
-      const step = tutorial.steps[i]!;
-      logger.info(`preview: replay ${i + 1}/${target} "${stepId(step, i)}"`);
-      await step.run(page, ctx);
-      await step.waitFor?.(page, ctx);
-    }
-
-    // The target step runs instrumented (cursor/callouts/focus), to match a
-    // real render's framing — that's what the screenshot is verifying.
-    const instrumented = instrumentPage(page, { cursor, callouts, nowMs: () => 0, onCallout: () => {} });
-    const step = tutorial.steps[target]!;
-    logger.info(`preview: step ${target + 1}/${tutorial.steps.length} "${id}"`);
-    await anchorFocus(step, instrumented as Page, ctx, id);
-    await step.run(instrumented as Page, ctx);
-    await step.waitFor?.(instrumented as Page, ctx);
-    await waitForSettle(step, page, id);
-    await page.waitForTimeout(opts.settleMs ?? step.settleMs ?? 400);
+      // Replay prior steps on the RAW page (no cursor/scroll animation) — we only
+      // need their state, not their framing, so replay stays fast (#11).
+      for (let i = 0; i < target; i++) {
+        const step = tutorial.steps[i]!;
+        logger.info(`preview: replay ${i + 1}/${target} "${stepId(step, i)}"`);
+        await step.run(page, ctx);
+        await step.waitFor?.(page, ctx);
+      }
 
-    await page.screenshot({ path: output });
-    logger.info(`preview: wrote ${output}`);
+      // The target step runs instrumented (cursor/callouts/focus), to match a
+      // real render's framing — that's what the screenshot is verifying.
+      const instrumented = instrumentPage(page, { cursor, callouts, nowMs: () => 0, onCallout: () => {} });
+      const step = tutorial.steps[target]!;
+      logger.info(`preview: step ${target + 1}/${tutorial.steps.length} "${id}"`);
+      await anchorFocus(step, instrumented as Page, ctx, id);
+      await step.run(instrumented as Page, ctx);
+      await step.waitFor?.(instrumented as Page, ctx);
+      await waitForSettle(step, page, id);
+      await page.waitForTimeout(opts.settleMs ?? step.settleMs ?? 400);
 
-    // Clean up only what the previewed steps registered. Unlike a full render
-    // we do NOT run tutorial/adapter teardown: previewing a mid-tutorial step
-    // reaches partial state, and those hooks assume a complete run (they could
-    // throw or destructively delete shared fixtures a later render needs).
-    await runStepTeardowns(teardownThunks);
+      await page.screenshot({ path: output });
+      logger.info(`preview: wrote ${output}`);
 
-    return { stepId: id, index: target, screenshot: output };
+      return { stepId: id, index: target, screenshot: output };
+    } finally {
+      await runTeardownChain(page, ctx, tutorial, adapter, teardownThunks);
+    }
   } finally {
     await safeClose(browser.close());
   }
diff --git a/packages/core/src/pipeline/record.ts b/packages/core/src/pipeline/record.ts
index 300b2d0..293a1bb 100644
--- a/packages/core/src/pipeline/record.ts
+++ b/packages/core/src/pipeline/record.ts
@@ -6,7 +6,7 @@ import type { CalloutRecord, FailureArtifacts, TimingManifest, Tutorial, Tutoria
 import { StepError } from '../types.js';
 import { ConsoleCapture } from '../browser/console.js';
 import { stepId } from '../spec.js';
-import { anchorFocus, createStepContext, runStepTeardowns, safeTeardown, waitForSettle } from './step-hooks.js';
+import { anchorFocus, createStepContext, runTeardownChain, waitForSettle } from './step-hooks.js';
 import type { TTSPhaseResult } from './tts.js';
 import { CURSOR_INIT_SCRIPT } from '../browser/cursor.js';
 import { CALLOUT_INIT_SCRIPT } from '../browser/callout.js';
@@ -48,9 +48,9 @@ export interface RecordPhaseOptions {
  * video, pacing each step to its narration budget. Writes raw.webm and
  * manifest.json into workDir.
  */
-export async function runRecordPhase(
-  tutorial: Tutorial,
-  adapter: TutorialAdapter,
+export async function runRecordPhase<S = unknown>(
+  tutorial: Tutorial<S>,
+  adapter: TutorialAdapter<S>,
   tts: TTSPhaseResult,
   opts: RecordPhaseOptions,
 ): Promise<TimingManifest> {
@@ -108,20 +108,28 @@ export async function runRecordPhase(
     }
 
     // Step-registered cleanup thunks (ctx.onTeardown), run LIFO at teardown.
-    const { ctx, teardownThunks } = createStepContext(opts.lang);
+    const { ctx, teardownThunks } = createStepContext<S>(opts.lang);
     // Teardown, innermost-first: step thunks (LIFO) → tutorial → adapter. Runs
-    // on both the success and failure paths so data created before a failing
-    // step is still cleaned up (the orphan-leak #8 set out to fix).
-    const runTeardown = async () => {
-      await runStepTeardowns(teardownThunks);
-      if (tutorial.teardown) await safeTeardown('tutorial teardown', () => tutorial.teardown!(page, ctx));
-      if (adapter.teardown) await safeTeardown('teardown', () => adapter.teardown!(page, ctx));
-    };
+    // on the success, step-failure, AND setup-failure paths so data created
+    // before any throw is still cleaned up (the orphan-leak #8 set out to fix).
+    const runTeardown = () => runTeardownChain(page, ctx, tutorial, adapter, teardownThunks);
     logger.info(`record: setup (${adapter.baseURL})${opts.lang ? ` [${opts.lang}]` : ''}`);
-    await adapter.setup(page, ctx);
-    if (tutorial.setup) {
-      logger.info('record: tutorial setup');
-      await tutorial.setup(page, ctx);
+    try {
+      // adapter.setup's return value (if any) is the per-render state bag that
+      // tutorial.setup and steps read via ctx.state (#17).
+      const setupState = await adapter.setup(page, ctx);
+      if (setupState != null) ctx.state = setupState as S;
+      if (tutorial.setup) {
+        logger.info('record: tutorial setup');
+        await tutorial.setup(page, ctx);
+      }
+    } catch (cause) {
+      // A throw in setup (flaky signIn, warm-up goto timeout) must still tear
+      // down anything seeded/registered before it — otherwise ctx.onTeardown in
+      // setup is a no-op on the most leak-prone path (#15).
+      await runTeardown();
+      await safeClose(context.close());
+      throw cause;
     }
     // The final video begins leadInMs before step 1. Hold past that window
     // now so it shows the settled app, not the tail end of setup.
@@ -226,7 +234,7 @@ async function launchChromium(headless: boolean): Promise<Browser> {
 }
 
 async function saveManifest(
-  tutorial: Tutorial,
+  tutorial: Pick<Tutorial, 'id'>,
   clock: RecordingClock,
   steps: TimingManifest['steps'],
   workDir: string,
diff --git a/packages/core/src/pipeline/render.ts b/packages/core/src/pipeline/render.ts
index b1119a2..4689e44 100644
--- a/packages/core/src/pipeline/render.ts
+++ b/packages/core/src/pipeline/render.ts
@@ -1,5 +1,6 @@
 import { resolve, join } from 'node:path';
 import type { RenderOptions, TimingManifest, Tutorial, TutorialAdapter } from '../types.js';
+import { StepError } from '../types.js';
 import { validateTutorial } from '../spec.js';
 import { localizeTutorial } from '../i18n.js';
 import { runTTSPhase, loadTTSResult } from './tts.js';
@@ -22,9 +23,9 @@ export interface RenderResult extends PostPhaseResult {
  * Phases: tts → record → post. The work directory is kept on failure
  * (and on success with keepWorkDir: true) so every stage is inspectable.
  */
-export async function render(
-  tutorial: Tutorial,
-  adapter: TutorialAdapter,
+export async function render<S = unknown>(
+  tutorial: Tutorial<S>,
+  adapter: TutorialAdapter<S>,
   options: RenderOptions,
 ): Promise<RenderResult> {
   validateTutorial(tutorial);
@@ -54,7 +55,7 @@ export async function render(
           })
         : await loadTTSResult(workDir);
     if (phase === 'tts') {
-      return partialResult(workDir, output, await safeLoadManifest(workDir, tutorial));
+      return partialResult(workDir, output, await safeLoadManifest(workDir, tutorial.id));
     }
 
     const manifest =
@@ -106,16 +107,48 @@ export async function render(
     return { ...post, manifest, workDir, contactSheetPath: sheetPath };
   } catch (err) {
     logger.error(`render failed — work dir kept at ${workDir}`);
+    // On a step failure, the steps that completed already have settled
+    // screenshots on disk; emit a partial contact sheet (completed steps + the
+    // failure frame as the last cell) so the at-a-glance "what did each step
+    // frame" view exists for exactly the run you most want it for (#20).
+    if (wantContactSheet && err instanceof StepError) {
+      await emitFailureContactSheet(err, workDir, output, viewport);
+    }
     throw err;
   }
 }
 
-async function safeLoadManifest(workDir: string, tutorial: Tutorial): Promise<TimingManifest> {
+/** Best-effort partial contact sheet for a failed render. Never throws — diagnostics must not mask the StepError. */
+async function emitFailureContactSheet(
+  err: StepError,
+  workDir: string,
+  output: string,
+  viewport: { width: number; height: number },
+): Promise<void> {
+  try {
+    const manifest = await loadManifest(workDir); // completed steps only (the failing one isn't recorded)
+    const entries = contactSheetEntries(manifest, workDir);
+    if (err.artifacts?.screenshot) {
+      entries.push({
+        index: entries.length + 1,
+        id: `${err.stepId} (failed)`,
+        narration: err.cause instanceof Error ? err.cause.message : String(err.cause),
+        file: err.artifacts.screenshot,
+      });
+    }
+    const sheet = await renderContactSheet(entries, contactSheetPath(output), viewport);
+    if (sheet) logger.info(`contact sheet (partial, through failure): ${sheet}`);
+  } catch (sheetErr) {
+    logger.warn(`partial contact sheet skipped: ${sheetErr instanceof Error ? sheetErr.message : sheetErr}`);
+  }
+}
+
+async function safeLoadManifest(workDir: string, tutorialId: string): Promise<TimingManifest> {
   try {
     return await loadManifest(workDir);
   } catch {
     return {
-      tutorialId: tutorial.id,
+      tutorialId,
       fps: 25,
       recordingStartEpochMs: 0,
       steps: [],
diff --git a/packages/core/src/pipeline/step-hooks.ts b/packages/core/src/pipeline/step-hooks.ts
index 2586775..562aa99 100644
--- a/packages/core/src/pipeline/step-hooks.ts
+++ b/packages/core/src/pipeline/step-hooks.ts
@@ -1,5 +1,5 @@
 import type { Page } from 'playwright';
-import type { Step, StepContext } from '../types.js';
+import type { Step, StepContext, Tutorial, TutorialAdapter } from '../types.js';
 import { logger } from '../util/logger.js';
 
 /**
@@ -8,8 +8,8 @@ import { logger } from '../util/logger.js';
  * "cleanup must never throw" rule live in one place.
  */
 
-/** A cleanup callback registered via ctx.onTeardown(). */
-export type TeardownThunk = () => void | Promise<void>;
+/** A cleanup callback registered via ctx.onTeardown(). Its result is awaited and discarded. */
+export type TeardownThunk = () => unknown | Promise<unknown>;
 
 /** Cap on a step's settleUntil wait — bounded so a never-idle page (websockets, polling) can't stall the render. */
 export const SETTLE_TIMEOUT_MS = 5000;
@@ -21,7 +21,7 @@ export const SETTLE_TIMEOUT_MS = 5000;
  * reaches the state (persistent connections) logs and proceeds rather than
  * failing the render.
  */
-export async function waitForSettle(step: Step, page: Page, id: string): Promise<void> {
+export async function waitForSettle(step: Pick<Step, 'settleUntil'>, page: Page, id: string): Promise<void> {
   if (!step.settleUntil) return;
   try {
     await page.waitForLoadState(step.settleUntil, { timeout: SETTLE_TIMEOUT_MS });
@@ -33,9 +33,11 @@ export async function waitForSettle(step: Step, page: Page, id: string): Promise
 }
 
 /** Build a StepContext and the array its onTeardown() pushes into. */
-export function createStepContext(lang?: string): { ctx: StepContext; teardownThunks: TeardownThunk[] } {
+export function createStepContext<S = unknown>(lang?: string): { ctx: StepContext<S>; teardownThunks: TeardownThunk[] } {
   const teardownThunks: TeardownThunk[] = [];
-  const ctx: StepContext = { lang, onTeardown: (fn) => teardownThunks.push(fn) };
+  // state starts as an empty bag so steps can stash live-created ids even when
+  // the adapter returns nothing; adapter.setup's return value replaces it.
+  const ctx: StepContext<S> = { lang, state: {} as S, onTeardown: (fn) => teardownThunks.push(fn) };
   return { ctx, teardownThunks };
 }
 
@@ -53,13 +55,33 @@ export async function runStepTeardowns(thunks: TeardownThunk[]): Promise<void> {
   for (const fn of [...thunks].reverse()) await safeTeardown('step teardown', fn);
 }
 
+/**
+ * The single teardown entry point, innermost-first: step onTeardown thunks
+ * (LIFO) → tutorial.teardown → adapter.teardown. Every hook is guarded, so a
+ * teardown that runs against half-built state (e.g. after a setup failure)
+ * degrades to a logged warning instead of masking the original error or
+ * leaking. Shared by record, preview, and the doctor setup probe so all three
+ * clean up identically (#15/#16/#19).
+ */
+export async function runTeardownChain<S>(
+  page: Page,
+  ctx: StepContext<S>,
+  tutorial: Pick<Tutorial<S>, 'teardown'>,
+  adapter: Pick<TutorialAdapter<S>, 'teardown'>,
+  teardownThunks: TeardownThunk[],
+): Promise<void> {
+  await runStepTeardowns(teardownThunks);
+  if (tutorial.teardown) await safeTeardown('tutorial teardown', () => tutorial.teardown!(page, ctx));
+  if (adapter.teardown) await safeTeardown('teardown', () => adapter.teardown!(page, ctx));
+}
+
 /**
  * Anchor the cursor on a step's focus control (decorative #10): smooth-scroll
  * the control into frame + move the fake cursor there via the instrumented
  * hover. The focus callback may be sync or async. Never throws — a failure
  * here is logged and skipped, so the render is unaffected.
  */
-export async function anchorFocus(step: Step, page: Page, ctx: StepContext, id: string): Promise<void> {
+export async function anchorFocus<S>(step: Step<S>, page: Page, ctx: StepContext<S>, id: string): Promise<void> {
   if (!step.focus) return;
   try {
     const locator = await step.focus(page, ctx);
diff --git a/packages/core/src/pipeline/tts.ts b/packages/core/src/pipeline/tts.ts
index 6b1783b..9cd26d8 100644
--- a/packages/core/src/pipeline/tts.ts
+++ b/packages/core/src/pipeline/tts.ts
@@ -19,8 +19,8 @@ const TTS_RESULT_FILE = 'tts.json';
  * bounded concurrency. Result is persisted to workDir/tts.json so the record
  * phase can re-run without re-synthesizing.
  */
-export async function runTTSPhase(
-  tutorial: Tutorial,
+export async function runTTSPhase<S = unknown>(
+  tutorial: Tutorial<S>,
   opts: { provider: TTSProvider; workDir: string; cacheDir: string; concurrency: number },
 ): Promise<TTSPhaseResult> {
   const audioDir = join(opts.workDir, 'audio');
diff --git a/packages/core/src/spec.ts b/packages/core/src/spec.ts
index ca308cd..bef2db6 100644
--- a/packages/core/src/spec.ts
+++ b/packages/core/src/spec.ts
@@ -6,19 +6,19 @@ const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 // another TTS system; providers read them literally, so warn at load time.
 const SUSPICIOUS_NARRATION_RE = /<[a-z][^>]*>|[\x00-\x08\x0b\x0c\x0e-\x1f]/i;
 
-export function step(narration: string, run: Step['run'], opts?: Partial<Step>): Step {
+export function step<S = unknown>(narration: string, run: Step<S>['run'], opts?: Partial<Step<S>>): Step<S> {
   return { narration, run, ...opts };
 }
 
-export function tutorial(idOrTitle: string, steps: Step[], meta?: Partial<Tutorial>): Tutorial {
+export function tutorial<S = unknown>(idOrTitle: string, steps: Step<S>[], meta?: Partial<Tutorial<S>>): Tutorial<S> {
   const id = meta?.id ?? slugify(idOrTitle);
   const title = meta?.title ?? idOrTitle;
-  const t: Tutorial = { ...meta, id, title, steps };
+  const t: Tutorial<S> = { ...meta, id, title, steps };
   validateTutorial(t);
   return t;
 }
 
-export function validateTutorial(t: Tutorial): void {
+export function validateTutorial<S = unknown>(t: Tutorial<S>): void {
   if (!t.id || !SLUG_RE.test(t.id)) {
     throw new Error(`Tutorial id "${t.id}" must be a lowercase slug (a-z, 0-9, hyphens)`);
   }
@@ -60,7 +60,7 @@ export function validateTutorial(t: Tutorial): void {
 }
 
 /** Resolve a step's stable id: explicit id, or its zero-padded index. */
-export function stepId(s: Step, index: number): string {
+export function stepId(s: Pick<Step, 'id'>, index: number): string {
   return s.id ?? `step-${String(index + 1).padStart(2, '0')}`;
 }
 
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 91f377f..3dedf56 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -1,37 +1,56 @@
 import type { Locator, Page } from 'playwright';
 
-/** Passed to adapter and step callbacks; lets app code react to the render language. */
-export interface StepContext {
+/**
+ * Passed to adapter and step callbacks; lets app code react to the render
+ * language and share per-render state. Generic in the shape of `state` (S),
+ * which `adapter.setup`'s return value populates — see {@link TutorialAdapter}.
+ */
+export interface StepContext<S = unknown> {
   /** The language being rendered (from RenderOptions.lang / --lang), if any. */
   lang?: string;
+  /**
+   * Per-render state bag, scoped to one render (never shared across renders, so
+   * it's safe even if renders run in parallel). The value `adapter.setup`
+   * returns lands here, so `tutorial.setup` and steps can read what the adapter
+   * established (the signed-in identity, seeded ids) without a module-global
+   * handoff — and steps can stash a live-created id on it for their own
+   * `onTeardown`. Defaults to `{}` when the adapter returns nothing.
+   */
+  state: S;
   /**
    * Register a cleanup callback for data this step creates. Thunks run after
    * recording in reverse (LIFO) order — before the tutorial's and adapter's
    * teardown — so mid-tutorial state is cleaned up deterministically without
-   * the adapter needing to know about it. Failures are logged, not fatal.
+   * the adapter needing to know about it. The return value is awaited and
+   * discarded, so `() => Promise.all([...])` works directly. Failures are
+   * logged, not fatal.
    */
-  onTeardown(fn: () => void | Promise<void>): void;
+  onTeardown(fn: () => unknown | Promise<unknown>): void;
 }
 
 /** Gets the target app into a known, recordable state. The only app-specific code. */
-export interface TutorialAdapter {
+export interface TutorialAdapter<S = unknown> {
   /** Base URL of the running app, e.g. http://localhost:3000 */
   baseURL: string;
-  /** Auth, seeding, navigation to a starting screen. Runs after page creation, before step 1. Excluded from the final video by default. */
-  setup(page: Page, ctx: StepContext): Promise<void>;
+  /**
+   * Auth, seeding, navigation to a starting screen. Runs after page creation,
+   * before step 1. Excluded from the final video by default. Anything it
+   * returns lands on `ctx.state` for `tutorial.setup` and steps to read.
+   */
+  setup(page: Page, ctx: StepContext<S>): Promise<S | void>;
   /** Optional cleanup after recording (delete seeded data, logout). Never recorded. */
-  teardown?(page: Page, ctx: StepContext): Promise<void>;
+  teardown?(page: Page, ctx: StepContext<S>): Promise<void>;
 }
 
-export interface Step {
+export interface Step<S = unknown> {
   /** Stable id, auto-derived from index if omitted. Used in manifest, cache keys, logs, translation tables. */
   id?: string;
   /** The narration line spoken over this step, in the source language. Plain text; may be ''. */
   narration: string;
   /** The action. Receives the raw Playwright Page. May be a no-op for pure-narration steps. */
-  run: (page: Page, ctx: StepContext) => Promise<void>;
+  run: (page: Page, ctx: StepContext<S>) => Promise<void>;
   /** Optional readiness hook awaited after run(); use when auto-waiting isn't enough. */
-  waitFor?: (page: Page, ctx: StepContext) => Promise<void>;
+  waitFor?: (page: Page, ctx: StepContext<S>) => Promise<void>;
   /**
    * Anchor the cursor on a control at the start of the step — smooth-scrolls it
    * into frame and moves the fake cursor there — so narration about "this
@@ -39,25 +58,31 @@ export interface Step {
    * is pure narration. Return the locator to anchor on (may be async).
    * Decorative: a failure here is logged and skipped, never failing the render.
    */
-  focus?: (page: Page, ctx: StepContext) => Locator | Promise<Locator>;
+  focus?: (page: Page, ctx: StepContext<S>) => Locator | Promise<Locator>;
   /**
    * Wait for a real page load-state signal after run()/waitFor() instead of
    * guessing a settleMs — e.g. 'networkidle' to let a router.refresh()'s
    * fetches quiesce. Best-effort and bounded (~5s): a page that never reaches
    * the state (websockets, polling) logs and proceeds rather than failing.
    * Composes with settleMs (which still adds its on-screen hold afterward).
+   *
+   * Caveat: 'networkidle' can resolve in the gap *before* a React
+   * `startTransition`-deferred Server Action dispatches its request, settling on
+   * the pre-mutation UI. For the standard `startTransition` + Server Action +
+   * `router.refresh()` pattern, prefer `waitFor` on the committed UI (the value
+   * flipping, a toast appearing) — see docs/writing-tutorials.md "Settling".
    */
   settleUntil?: 'load' | 'domcontentloaded' | 'networkidle';
   /** Extra hold time (ms) after both narration and action complete. Default 400. */
   settleMs?: number;
 }
 
-export interface Tutorial {
+export interface Tutorial<S = unknown> {
   /** Slug, used for output filenames. */
   id: string;
   title: string;
   description?: string;
-  steps: Step[];
+  steps: Step<S>[];
   /**
    * Per-language narration overrides: lang → (step id → translated line).
    * Usually loaded from sidecar files (<tutorial-file>.<lang>.json) by the CLI.
@@ -67,15 +92,16 @@ export interface Tutorial {
    * Per-tutorial setup, run after the adapter's setup() and before step 1 (not
    * recorded). The adapter is the shared auth/seed baseline; this is per-video
    * state — e.g. seed an event for this tutorial only. Optional; tutorials
-   * without it keep working through the adapter alone.
+   * without it keep working through the adapter alone. Reads what the adapter
+   * established via `ctx.state`.
    */
-  setup?(page: Page, ctx: StepContext): Promise<void>;
+  setup?(page: Page, ctx: StepContext<S>): Promise<void>;
   /**
    * Per-tutorial cleanup, run after recording (not recorded) — after any
    * step-registered onTeardown thunks and before the adapter's teardown().
    * Failures are logged, not fatal.
    */
-  teardown?(page: Page, ctx: StepContext): Promise<void>;
+  teardown?(page: Page, ctx: StepContext<S>): Promise<void>;
 }
 
 export interface TTSProvider {
diff --git a/packages/core/test/step-hooks.test.ts b/packages/core/test/step-hooks.test.ts
new file mode 100644
index 0000000..be6cf0c
--- /dev/null
+++ b/packages/core/test/step-hooks.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Page } from 'playwright';
+import {
+  createStepContext,
+  runTeardownChain,
+  runStepTeardowns,
+  waitForSettle,
+} from '../src/pipeline/step-hooks.js';
+import type { StepContext, Tutorial, TutorialAdapter } from '../src/types.js';
+
+// The teardown chain and ctx are browser-agnostic, so they unit-test without
+// Playwright — pass a stub page the hooks never actually touch.
+const fakePage = {} as Page;
+
+describe('createStepContext', () => {
+  it('defaults state to an empty bag steps can stash on', () => {
+    const { ctx } = createStepContext();
+    expect(ctx.state).toEqual({});
+    (ctx.state as Record<string, unknown>).createdId = 'evt_1';
+    expect((ctx.state as Record<string, unknown>).createdId).toBe('evt_1');
+  });
+
+  it('carries the render language', () => {
+    const { ctx } = createStepContext('es');
+    expect(ctx.lang).toBe('es');
+  });
+});
+
+describe('runTeardownChain', () => {
+  it('runs innermost-first: step thunks (LIFO) → tutorial → adapter', async () => {
+    const order: string[] = [];
+    const { ctx, teardownThunks } = createStepContext();
+    ctx.onTeardown(() => void order.push('step.a'));
+    ctx.onTeardown(() => void order.push('step.b'));
+    const tutorial: Pick<Tutorial, 'teardown'> = { teardown: async () => void order.push('tutorial') };
+    const adapter: Pick<TutorialAdapter, 'teardown'> = { teardown: async () => void order.push('adapter') };
+
+    await runTeardownChain(fakePage, ctx, tutorial, adapter, teardownThunks);
+
+    expect(order).toEqual(['step.b', 'step.a', 'tutorial', 'adapter']);
+  });
+
+  it('keeps going (and never throws) when a hook fails — a half-built teardown must not leak the rest', async () => {
+    const order: string[] = [];
+    const { ctx, teardownThunks } = createStepContext();
+    ctx.onTeardown(() => {
+      throw new Error('thunk boom');
+    });
+    const tutorial: Pick<Tutorial, 'teardown'> = {
+      teardown: async () => {
+        throw new Error('tutorial boom');
+      },
+    };
+    const adapter: Pick<TutorialAdapter, 'teardown'> = { teardown: async () => void order.push('adapter ran') };
+
+    await expect(runTeardownChain(fakePage, ctx, tutorial, adapter, teardownThunks)).resolves.toBeUndefined();
+    expect(order).toEqual(['adapter ran']); // adapter teardown still ran despite earlier failures
+  });
+
+  it('awaits value-returning thunks (widened onTeardown type, #21)', async () => {
+    const seen: number[] = [];
+    const { ctx, teardownThunks } = createStepContext();
+    // Returns a Promise<number[]> — would not typecheck under the old void-only signature.
+    ctx.onTeardown(() => Promise.all([1, 2, 3].map(async (n) => void seen.push(n))));
+    await runStepTeardowns(teardownThunks);
+    expect(seen.sort()).toEqual([1, 2, 3]);
+  });
+});
+
+describe('waitForSettle', () => {
+  it('is a no-op when no settleUntil is set', async () => {
+    const page = { waitForLoadState: vi.fn() } as unknown as Page;
+    await waitForSettle({}, page, 'id');
+    expect(page.waitForLoadState).not.toHaveBeenCalled();
+  });
+
+  it('never throws when the load-state never arrives', async () => {
+    const page = {
+      waitForLoadState: vi.fn().mockRejectedValue(new Error('timeout')),
+    } as unknown as Page;
+    await expect(waitForSettle({ settleUntil: 'networkidle' }, page, 'id')).resolves.toBeUndefined();
+  });
+});
+
+// Keep the StepContext generic honest: the typed-state handoff must compile.
+describe('typed state handoff (#17)', () => {
+  it('threads an adapter state type through to ctx.state', () => {
+    interface Seed {
+      steward: { id: string };
+    }
+    const ctx: StepContext<Seed> = { state: { steward: { id: 'p1' } }, onTeardown: () => {} };
+    // No `!` assertion, no module global — the field is typed.
+    expect(ctx.state.steward.id).toBe('p1');
+  });
+});
diff --git a/packages/example-app/test/e2e.ts b/packages/example-app/test/e2e.ts
index 60567c5..40e8ea2 100644
--- a/packages/example-app/test/e2e.ts
+++ b/packages/example-app/test/e2e.ts
@@ -10,7 +10,7 @@ import { fileURLToPath } from 'node:url';
 import { mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { chromium } from 'playwright';
-import { render, previewStep, probeDurationMs, detectFlashOffsetMs, SilentProvider, StepError, tutorial, step, type TutorialAdapter } from 'tutorial-forge';
+import { render, previewStep, probeAdapterSetup, probeDurationMs, detectFlashOffsetMs, contactSheetPath, SilentProvider, StepError, tutorial, step, type TutorialAdapter } from 'tutorial-forge';
 // Internal (not public API) — exercised from source under tsx for #10 coverage.
 import { instrumentPage } from '../../core/src/browser/instrument.ts';
 import { CURSOR_INIT_SCRIPT } from '../../core/src/browser/cursor.ts';
@@ -350,6 +350,167 @@ try {
     'onTeardown thunks + tutorial.teardown run even when a later step fails',
   );
   console.log(`e2e OK [failure]: StepError + teardown ran (${cleanedUpOnFailure.join(', ')})`);
+
+  // #17 — ctx.state: adapter.setup's return lands on ctx.state, typed end-to-end
+  // (TutorialAdapter<S> → tutorial<S> → step<S>), so tutorial.setup and steps
+  // read what the adapter established without a module-global + `!` handoff, and
+  // a step can stash a live-created id on it for its own onTeardown.
+  {
+    interface Seed { token: string }
+    const seen: Record<string, unknown> = {};
+    const stateAdapter: TutorialAdapter<Seed> = {
+      baseURL,
+      async setup(page) {
+        await page.goto(baseURL);
+        await page.getByRole('heading', { name: 'Dashboard' }).waitFor();
+        return { token: 'seed-123' }; // becomes ctx.state
+      },
+    };
+    const stateTut = tutorial<Seed>('State', [
+      step<Seed>('Read adapter state; stash a live id.', async (_page, ctx) => {
+        seen.stepSaw = ctx.state.token; // typed: ctx.state is Seed, no assertion
+        ctx.state.token = 'mutated-by-step';
+        ctx.onTeardown(() => { seen.teardownSaw = ctx.state.token; });
+      }, { id: 'use-state' }),
+    ], {
+      id: 'state-demo',
+      async setup(_page, ctx) { seen.tutorialSetupSaw = ctx.state.token; },
+    });
+    await render(stateTut, stateAdapter, {
+      tts: SilentProvider(),
+      output: join(outDir, 'state.mp4'),
+      workDir: join(outDir, 'work-state'),
+      ttsCacheDir: join(outDir, 'tts-cache'),
+    });
+    assert.equal(seen.tutorialSetupSaw, 'seed-123', 'tutorial.setup reads adapter state via ctx.state');
+    assert.equal(seen.stepSaw, 'seed-123', 'step reads adapter state via ctx.state');
+    assert.equal(seen.teardownSaw, 'mutated-by-step', 'onTeardown sees step mutations to ctx.state');
+    console.log('e2e OK [ctx.state]: adapter → tutorial.setup → step → onTeardown handoff');
+  }
+
+  // #15 — a throw in tutorial.setup must still run the FULL teardown chain, so
+  // data seeded (and any ctx.onTeardown registered) before the throw is cleaned
+  // up. Previously teardown ran only on a step failure or a clean finish, so a
+  // setup-phase throw silently leaked everything seeded so far.
+  {
+    const cleaned: string[] = [];
+    const failAdapter: TutorialAdapter = {
+      baseURL,
+      async setup(page, ctx) {
+        await page.goto(baseURL);
+        await page.getByRole('heading', { name: 'Dashboard' }).waitFor();
+        ctx.onTeardown(() => { cleaned.push('adapter.onTeardown'); }); // seeded-in-setup cleanup
+      },
+      async teardown() { cleaned.push('adapter.teardown'); },
+    };
+    const failTut = tutorial('SetupFail', [step('never runs', async () => {}, { id: 'noop' })], {
+      id: 'setup-fail',
+      async setup() { throw new Error('seed warm-up timed out'); },
+      async teardown() { cleaned.push('tutorial.teardown'); },
+    });
+    let setupErr: Error | null = null;
+    try {
+      await render(failTut, failAdapter, {
+        tts: SilentProvider(),
+        output: join(outDir, 'setup-fail.mp4'),
+        workDir: join(outDir, 'work-setup-fail'),
+        ttsCacheDir: join(outDir, 'tts-cache'),
+      });
+    } catch (err) {
+      setupErr = err as Error;
+    }
+    assert.ok(setupErr && /seed warm-up timed out/.test(setupErr.message), 'setup failure propagates');
+    assert.deepEqual(
+      cleaned,
+      ['adapter.onTeardown', 'tutorial.teardown', 'adapter.teardown'],
+      'setup-phase failure runs the full teardown chain — no seeded-data leak (#15)',
+    );
+    console.log(`e2e OK [setup-fail]: teardown ran on setup failure (${cleaned.join(', ')})`);
+  }
+
+  // #16 — preview must run the FULL teardown chain (incl. adapter.teardown), not
+  // just step thunks. preview is the run-repeatedly iterate tool, so leaking the
+  // adapter seed each run quietly fills the shared test DB.
+  {
+    const cleaned: string[] = [];
+    const previewAdapter: TutorialAdapter = {
+      baseURL,
+      async setup(page) {
+        await page.goto(baseURL);
+        await page.getByRole('heading', { name: 'Dashboard' }).waitFor();
+      },
+      async teardown() { cleaned.push('adapter.teardown'); },
+    };
+    const previewTut = tutorial('PreviewTeardown', [
+      step('Seed a row.', async (_p, ctx) => { ctx.onTeardown(() => { cleaned.push('step.teardown'); }); }, { id: 'seed' }),
+      step('Target.', async () => {}, { id: 'target' }),
+    ], { id: 'preview-teardown', async teardown() { cleaned.push('tutorial.teardown'); } });
+    await previewStep(previewTut, previewAdapter, {
+      step: 'target',
+      workDir: join(outDir, 'preview-td'),
+      output: join(outDir, 'preview-td.png'),
+    });
+    assert.deepEqual(
+      cleaned,
+      ['step.teardown', 'tutorial.teardown', 'adapter.teardown'],
+      'preview runs the full teardown chain — no adapter-seed leak (#16)',
+    );
+    console.log(`e2e OK [preview-teardown]: ${cleaned.join(', ')}`);
+  }
+
+  // #19 — probeAdapterSetup actually runs adapter.setup (and tears it down),
+  // surfacing the wrong-database class of failure that a reachable-but-mispointed
+  // server hides behind a green check. It must tear down even when setup throws.
+  {
+    await probeAdapterSetup(adapter); // the working adapter resolves cleanly
+    const cleaned: string[] = [];
+    const badAdapter: TutorialAdapter = {
+      baseURL,
+      async setup(_page, ctx) {
+        ctx.onTeardown(() => { cleaned.push('cleaned'); });
+        throw new Error('sign-in failed: steward not found (wrong database?)');
+      },
+      async teardown() { cleaned.push('adapter.teardown'); },
+    };
+    let probeErr: Error | null = null;
+    try {
+      await probeAdapterSetup(badAdapter);
+    } catch (err) {
+      probeErr = err as Error;
+    }
+    assert.ok(probeErr && /wrong database/.test(probeErr.message), 'probeAdapterSetup surfaces a setup failure (#19)');
+    assert.deepEqual(cleaned, ['cleaned', 'adapter.teardown'], 'probe tears down even when setup throws');
+    console.log('e2e OK [probe-setup]: success resolves; failure surfaces + tears down');
+  }
+
+  // #20 — a failed render with contactSheet on still emits a PARTIAL contact
+  // sheet (completed steps + the failure frame), the at-a-glance view you most
+  // want for a failing run — the post phase that normally builds it never runs.
+  {
+    const partialBroken = tutorial('PartialBroken', [
+      step('First step succeeds.', async () => {}, { id: 'ok-1' }),
+      step('Second step succeeds.', async () => {}, { id: 'ok-2' }),
+      step('Third step fails.', async (page) => {
+        await page.getByRole('button', { name: 'No Such Button' }).click({ timeout: 1000 });
+      }, { id: 'boom' }),
+    ], { id: 'partial-broken' });
+    const partialOutput = join(outDir, 'partial-broken.mp4');
+    let perr: StepError | null = null;
+    try {
+      await render(partialBroken, adapter, {
+        tts: SilentProvider(),
+        output: partialOutput,
+        workDir: join(outDir, 'work-partial'),
+        ttsCacheDir: join(outDir, 'tts-cache'),
+        contactSheet: true,
+      });
+    } catch (err) {
+      perr = err as StepError;
+    }
+    assert.ok(perr instanceof StepError && perr.stepId === 'boom', 'partial render failed at the bad step');
+    assert.ok(existsSync(contactSheetPath(partialOutput)), 'partial contact sheet emitted on step failure (#20)');
+    console.log(`e2e OK [partial-sheet]: ${contactSheetPath(partialOutput)}`);
+  }
 } finally {
   await close();
 }