diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..3a7d857
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,44 @@
+name: Bug report
+description: Something in dittosh doesn't work as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a problem. The fastest way to help us is a diagnostic report:
+
+        ```bash
+        dittosh doctor --report
+        ```
+
+        It writes `dittosh-report-<time>.tar.gz` in the current folder, with versions, OS details,
+        health checks, the last failed command, a store summary (no document contents), and Ditto's
+        SDK support bundle (SDK debug logs). The license token is never included. The SDK bundle is
+        Ditto's own file and holds the database ID, full file paths, and peer keys. Extract it and
+        read it before attaching it. Leave parts out with `--no-store` or `--no-sdk-bundle`.
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you run, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command and output
+      description: The exact command and what it printed. Add `--debug` to see SDK logs.
+      render: shell
+  - type: textarea
+    id: report
+    attributes:
+      label: Diagnostic report
+      description: Drag the `dittosh-report-….tar.gz` file here. If you can't attach files, paste the contents of `report.md` instead.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: dittosh version
+      description: Output of `dittosh --version`
+      placeholder: "0.2.0"
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..0086358
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1 @@
+blank_issues_enabled: true
diff --git a/AGENTS.md b/AGENTS.md
index bff7072..17691dc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,10 +15,14 @@ The Ditto CLI: an npm/Homebrew-installable TypeScript CLI (binary `dittosh` —
 
 ## Layout
 
-- `src/cli/` — commander entry (`index.ts`), injected version (`version.ts`, tsup `define`), `groups/` per command group (`dql`, `skills`, `system`)
+- `src/cli/` — commander entry (`index.ts`), injected version (`version.ts`, tsup `define`), `groups/` per command group (`dql`, `skills`, `system`, `tutorial`)
 - `src/config/` — data-dir resolution (`--data-dir` > `DITTOSH_DATA_DIR` > OS default), config dir (`DITTOSH_CONFIG_DIR` > OS default; env-paths caches homedir at module load, so tests must use this override, not `$HOME`), persisted state (one-time warnings, update cache)
 - `src/identity/` — token loading (dev env / release reassembly), expiry
-- `src/ditto/session.ts` — the only SDK touchpoint: init/open/close, log taming, lock mapping
+- `src/ditto/session.ts` — the only SDK touchpoint: init/open/close, log taming, lock mapping; enables the startup-gated `system:metrics` exporter (`systemParameters`)
+- `src/tutorial/` — `dittosh tutorial`: Markdown walkthrough as structured blocks (`content.ts`, runnable blocks executed by `tests/e2e/tutorial.test.ts`) and interactive DQL lessons (`lessons.ts` by level, `runner.ts`, `lesson-eval.ts`; every sample answer verified in `tests/integration/lessons.test.ts`). The full-screen lesson view is Ink + React in `src/tutorial/ui/` (`app.tsx` screen, `components.tsx`, `context.tsx` provider for the runner/store, pure `editor.ts`/`layout.ts`/`store.ts`/`help.ts` (right drawer: help, or the data view from `src/tutorial/schema.ts`)/`outline.ts` (left lesson sidebar); tests in `tests/unit/tutorial-ui.test.ts` with a fake TTY). It is lazy-loaded (`await import`) so Ink/React never load for other commands; `--plain` or a <60×20 window uses the node:repl shell. Wiring: `src/cli/groups/tutorial.ts`, `tutorial-repl.ts`
+- `src/bench/` — `dittosh dql bench` (wiring: `src/cli/groups/dql/bench.ts`; also `dataset run --runs/--warmup`): benchmark file parsing (`spec.ts`, the dql-metrics-benchmark `benchmarks.json` format), the timed runner (`runner.ts`: pre → warmup → reset+timed runs → post), stats matching the benchmark runners (`stats.ts`: floor-indexed p95/p99, adaptive ~250 ms warmup), and `--example` sample files from the dataset catalogs (`example.ts`). User docs: `docs/benchmarking.md`
+- `src/support/` — diagnostics for bug reports: `dittosh doctor --report` (wiring: `src/cli/groups/doctor.ts`, shared by `dittosh doctor` and `dittosh dql doctor`) gathers a redacted report (`report.ts`, `redact.ts`) and archives it as .tar.gz (`archive.ts`); `sdk-bundle.ts` requests the SDK 5.2 support bundle (`EXECUTE FUNCTION system_request_support_bundle()` → attachment token → `DittoSession.saveAttachment`; rate limit 3/10 min per store → falls back to the newest in `system:support_bundles`; also `dittosh dql support-bundle`); `last-error.ts` tails stderr and saves the last failed command to `<config dir>/last-error.json` (written from `src/cli/index.ts`). `--debug`/`DITTOSH_DEBUG` enables SDK logs (native logger writes to stderr). Never put the token or document contents in a report. User docs: `docs/troubleshooting.md`
+- `src/metrics/` — `system:metrics` row parsing and section grouping (REPL `.metrics`, rendered by `src/render/metrics.ts`)
 - `src/query/` — statement classifier, splitter, param binding, result extraction, row cap
 - `src/render/` — table (terminal-width fitting)/JSON/CSV/markdown/HTML/vertical, pager (`$PAGER`/`less`, `--no-pager`/`DITTOSH_NO_PAGER`), `-o/--out`, (M4: explain/profile/advise renderers)
 - `datasets/` — vendored benchmark suite definitions (movies, retail, retail-joins, pos); **no generated data ever committed**
@@ -66,7 +70,7 @@ scripts/install-release.sh # stamp token → RELEASE=true build → npm i -g . (
 
 ## Known platform facts
 
-- SDK `@dittolive/ditto@5.1.0` native matrix: macOS arm64, Linux x64/arm64, Windows x64 (no darwin-x64).
+- SDK `@dittolive/ditto@5.2.0` native matrix: macOS arm64, Linux x64/arm64, Windows x64 (no darwin-x64).
 - `DittoConfig(appId, { mode: "smallPeersOnly" }, dir)` + `Ditto.open` + `setOfflineOnlyLicenseToken` — verified (Spike A). EXPLAIN → first item `plan`; PROFILE → trailing `~request_profile` item.
 - The native tracing bootstrap writes ~7 WARN/INFO lines to **stderr** at `sdk.init()` (fd-level, not suppressible from JS). Cosmetic only; stdout is clean.
 - Two processes on one data dir → "File already locked" → mapped to `LockError` (exit 4).
diff --git a/README.md b/README.md
index 864559a..fc85a5d 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ npm i -g @dittolive/cli          # npm (primary)
 brew install getditto/tap/dittosh # Homebrew (macOS/Linux)
 ```
 
-The binary is `dittosh`. Requires Node.js ≥ 22 for npm installs; Homebrew manages Node.js 24. Supported platforms (matching the Ditto Node SDK): **macOS arm64, Linux x64/arm64, Windows x64**. Intel Macs (darwin-x64) are not supported by SDK 5.1.0.
+The binary is `dittosh`. Requires Node.js ≥ 22 for npm installs; Homebrew manages Node.js 24. Supported platforms (matching the Ditto Node SDK): **macOS arm64, Linux x64/arm64, Windows x64**. Intel Macs (darwin-x64) are not supported by SDK 5.2.0.
 
 Update using the package manager you installed with:
 
@@ -41,7 +41,7 @@ The CLI ships with a built-in offline license and runs entirely locally — no a
 
 ```bash
 # check your install
-dittosh dql doctor
+dittosh doctor
 
 # load a sample dataset
 dittosh dql dataset load movies
@@ -84,7 +84,7 @@ dittosh dql                                            # interactive REPL
 | `--continue-on-error` | keep running after a failure (batch mode) |
 | `--time` | timing footer (host wall-clock + server parse/plan/elapsed when profiling) |
 | `--explain` | print the query plan (EXPLAIN side-trip, SELECTs only) |
-| `--profile` | print the execution profile with per-operator timings and hotspot flags (SELECTs only) |
+| `--profile` | print the execution profile with per-operator timings (exec/recv/send/stor), document counts, scheduler yields, join subplans, and hotspot flags (SELECTs only) |
 | `--advise` | print index advice (ADVISE, SELECTs only) |
 | `--apply` | apply ADVISE's suggested `CREATE INDEX` statements (prompts; `-y` skips) |
 | `-y, --yes` | skip confirmation prompts |
@@ -98,10 +98,17 @@ dittosh dql "SELECT _id FROM movies WHERE _id.year = '2001' LIMIT 1" \
   | dittosh dql "SELECT * FROM movies WHERE _id = :id" --args -
 ```
 
-### `dittosh dql doctor`
+### `dittosh doctor` (also `dittosh dql doctor`)
 
 Platform/arch, Node version, data-directory writability, token validity + expiry, SDK load, and store-lock probe — with an exit code that says what's wrong.
 
+**Reporting a bug?** `dittosh doctor --report` writes `dittosh-report-<time>.tar.gz` to attach to a [GitHub issue](https://github.com/getditto/ditto-cli/issues/new?template=bug_report.yml): versions, OS and terminal details, the checks, paths and free space, dittosh settings (credentials only as set/not set), a store summary (collection names, counts, indexes; no document contents), the last failed command and its error output, and the Ditto SDK support bundle with the SDK's debug logs. `--no-store` and `--no-sdk-bundle` leave parts out.
+
+- `dittosh dql support-bundle [-o file.tar]` saves only the Ditto SDK support bundle (`--list` shows the ones kept in the store).
+- `--debug` (or `DITTOSH_DEBUG=1`) on any command shows the SDK's debug logs and stack traces on stderr; stdout is unchanged.
+
+See [Troubleshooting](docs/troubleshooting.md).
+
 ### `dittosh dql collections` / `dittosh dql indexes [collection]`
 
 List collections (`system:collections`) and indexes (`system:indexes`).
@@ -146,6 +153,27 @@ dittosh dql dataset reset retail --yes            # evict the dataset's collecti
 
 `dataset run` prints the resolved statement (on stderr, so stdout stays clean), then executes it. Query names resolve across datasets; ambiguous names list the matches. `--setup` applies the entry's index DDL first; write-category catalog queries require `--yes` and clean up after themselves. `--seed <n>` reproduces a dataset exactly; changing seeds adds new documents (reset first for a clean slate).
 
+### `dittosh dql bench` — benchmark statements
+
+Time a statement over many runs and get mean, p50, p95, p99, min, max, and standard deviation:
+
+```bash
+dittosh dql bench "SELECT * FROM movies WHERE rated = 'PG'" --runs 100 --warmup
+dittosh dql bench "SELECT * FROM movies WHERE rated = 'PG'" \
+  --pre "CREATE INDEX IF NOT EXISTS movies_rated ON movies (rated)" \
+  --post "DROP INDEX IF EXISTS movies_rated ON movies"
+dittosh dql bench --example movies -o movies-bench.json   # sample benchmark file
+dittosh dql bench -f movies-bench.json --runs 50 --warmup
+dittosh dql dataset run filtered_query_with_index --runs 50 --warmup   # a catalog query
+```
+
+- `--runs <n>`: timed runs (default 50). `--warmup`: untimed runs first, enough to fill about 250 ms; `--warmup <n>` for an exact count.
+- `--pre` runs once before timing, `--before-each` (or `--reset`) before every run (untimed, e.g. re-insert the document an `EVICT` removes), and `--post` once at the end, even after a failure. Each is repeatable.
+- `-f <file>`: benchmarks from a JSON file, in the same format as Ditto's DQL benchmark suites: `{"name": {"query": "…", "preQueries": […], "resetQueries": […], "postQueries": […]}}`. `--only a,b` picks entries. `--example <dataset>` writes a sample file for `movies`, `retail`, `retail-joins`, or `pos`.
+- Results go to stdout (a table in a terminal, JSON when piped, or `-o`/`--format`); progress goes to stderr. Exit code 1 if any benchmark fails.
+
+The full file format, the order of steps, and how to build a benchmark file are in [docs/benchmarking.md](docs/benchmarking.md).
+
 ### Global flags
 
 `--no-color`, `--quiet` (suppress informational notes), `--no-update-check` (planned; update flow lands in a later milestone).
@@ -171,6 +199,21 @@ Semantics: `add` never upgrades an existing install (it skips; `--force` overwri
 
 Agent targets: Claude Code (`~/.claude/skills` or `.claude/skills`), OpenCode (`~/.agents/skills` or `.agents/skills`), Codex (`~/.codex/skills`), Gemini (`~/.gemini/skills`), Antigravity (`~/.gemini/config/skills` or `.agents/skills`), Cursor (`.cursor/rules`, project-only), Copilot + Windsurf (project instruction files). While `getditto/agent-skills` is private, set `GITHUB_TOKEN` (e.g. `GITHUB_TOKEN=$(gh auth token)`).
 
+### `dittosh tutorial` — learn the CLI and DQL
+
+```bash
+dittosh tutorial                       # write ./dittosh-tutorial.md, a hands-on walkthrough of the CLI
+dittosh tutorial -o ~/t.md --force     # choose the file / overwrite
+dittosh tutorial --stdout              # print the Markdown instead
+dittosh tutorial --interactive         # guided DQL lessons, full screen
+dittosh tutorial --interactive --plain # the same lessons in a line-by-line shell
+dittosh tutorial --interactive --level advanced   # start at beginner | intermediate | advanced
+```
+
+The Markdown tutorial is tailored to this install (CLI and SDK version, Homebrew or npm upgrade commands, platform) and covers importing, querying, exporting, the interactive shell and `.metrics`, sample datasets, `--explain`/`--profile`/`--advise`, benchmarking with `dql bench` (including benchmark files), joins, diagnostics with system collections and more advanced DQL, and agent skills. Every runnable command in it is exercised by the e2e suite.
+
+The interactive lessons teach DQL concepts — documents and collections, projection, predicates, boolean logic, sorting, writes, expressions and functions, `CASE`, MISSING vs NULL, aggregation and grouping, joins, `ANY … SATISFIES`, indexes, `EXPLAIN`, `PROFILE`, and system collections — in 27 lessons across beginner, intermediate, and advanced levels. Each lesson explains the idea (with an "if you know SQL" note), shows the syntax, sets a task, and checks your answer. They run in a separate practice store (`<config dir>/tutorial-store`) and save your progress. The lessons open full screen: the lesson stays in a panel at the top, results scroll below it, the latest ✓/✗ verdict sits above the prompt, a sidebar on the left outlines the lessons and your progress (Ctrl+B toggles it), Ctrl+T (or `.schema`) shows the fields of the collections each lesson uses, and `?` slides a help panel in from the right. Press Enter to run a statement (`;` is optional); Tab hints, Ctrl+N/Ctrl+P move between lessons, Ctrl+L picks a lesson from a list, PgUp/PgDn scroll, and Ctrl+D quits. The dot-commands (`.hint`, `.answer`, `.next`/`.back`, `.lessons`, `.level <name>`, `.goto <n>`, `.reset`, `.exit`) work too. `--plain`, or a window smaller than 60×20, uses a simple line-by-line shell instead.
+
 ### Planned for later milestones
 
 `dittosh version`, `dittosh update` (self-update banner + channel-aware upgrade).
@@ -208,7 +251,9 @@ dittosh dql --advise --apply -y "SELECT …"  # apply them
 
 ## REPL
 
-Bare `dittosh dql` starts an interactive session: multi-line statements terminated with `;`, history, per-statement timing, dot-commands (`.help`, `.collections`, `.indexes [name]`, `.break`, `.exit`).
+Bare `dittosh dql` starts an interactive session: multi-line statements terminated with `;`, history, per-statement timing, dot-commands (`.help`, `.collections`, `.indexes [name]`, `.metrics [section]`, `.break`, `.exit`).
+
+`.metrics` shows the SDK's live system metrics for the session as formatted tables — store (SQLite transactions, fsync, WAL size, commit/lock timings) and query/DQL (requests, selects, failures, parse/plan/execution time) by default. Totals run since the session opened; the Change, p50/p90/p99 and Max columns cover the time since the previous `.metrics`. `.metrics query` or `.metrics store` narrows the view; `.metrics all` adds network, sync, transport, and the other sections.
 
 ## Development
 
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
new file mode 100644
index 0000000..7bbea32
--- /dev/null
+++ b/docs/benchmarking.md
@@ -0,0 +1,174 @@
+# Benchmarking DQL with `dittosh dql bench`
+
+`dittosh dql bench` times DQL statements against your local store. It runs each
+statement many times, optionally after an untimed warmup, and reports mean, p50,
+p95, p99, min, max, and standard deviation. Statements that run before, between,
+and after the timed runs create indexes and put data back, so every run starts
+from the same state.
+
+It follows the method of Ditto's DQL benchmark suites (`dql-metrics-benchmark`):
+the same file format, the same order of steps, the same warmup sizing, and the
+same percentile formulas. A suite's `benchmarks.json` runs here unchanged.
+
+## Quick start
+
+```bash
+dittosh dql dataset load movies                      # some data to measure
+dittosh dql bench "SELECT * FROM movies WHERE rated = 'PG'" --runs 100 --warmup
+
+dittosh dql bench --example movies -o movies-bench.json   # a sample file to copy from
+dittosh dql bench -f movies-bench.json --runs 50 --warmup
+```
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `[statement]` | The statement to time. Use this or `-f`. |
+| `-f, --file <path>` | A JSON benchmark file (format below). |
+| `--only <a,b>` | With `-f`: run only these benchmarks, in file order. |
+| `--runs <n>` | Timed runs per benchmark, 1–10,000. Default 50. |
+| `--warmup [n]` | Untimed runs before timing. With no number (or `auto`), enough runs to fill about 250 ms (at least 1, at most 1,000). `--warmup 0`, or leaving the flag out, means no warmup. |
+| `--pre <stmt>` | Run once before warmup and timing. Repeatable. |
+| `--before-each <stmt>` | Run before every warmup and timed run, untimed. Repeatable. The file version is `resetQueries`. |
+| `--reset <stmt>` | Same as `--before-each`. |
+| `--post <stmt>` | Run once at the end, even after a failure. Repeatable. |
+| `--example <dataset>` | Write a sample benchmark file for `movies`, `retail`, `retail-joins`, or `pos`: to stdout, or to the `-o` path. |
+| `-o, --out <path>` | Write the results to a file; the extension picks the format (`.json`, `.csv`, `.md`, `.html`). |
+| `--format <fmt>` | `table`, `json`, `csv`, `markdown`, `html`, or `vertical`. Defaults to a table in a terminal and JSON when piped. |
+| `-d, --data-dir <path>` | The store to use. |
+
+With `-f`, `--pre` and `--before-each` statements run before each benchmark's own, and
+`--post` statements run after its own.
+
+`dittosh dql dataset run <query> --runs <n> [--warmup [n]]` benchmarks one query from
+a sample dataset's catalog with the same runner. It keeps `dataset run`'s setup rules:
+write queries always run their fixtures and cleanup (and need `--yes`); read queries
+create their index only with `--setup`, and keep it afterwards. Without `--runs`
+it runs the query once (one timing).
+
+`--pre` runs **once**, not before every run. To time a write against data that must
+be there each time, such as evicting a test document, insert it with `--before-each`:
+
+```bash
+dittosh dql bench "EVICT FROM movies WHERE _id = 'bench-doc'" --runs 50 \
+  --before-each "INSERT INTO movies VALUES ({'_id': 'bench-doc', 'rated': 'TEST'})"
+```
+
+With the insert in `--pre` instead, only the first run would evict anything.
+
+## What happens, in order
+
+For each benchmark:
+
+1. **`preQueries`** run once. Typical use: `CREATE INDEX`, or inserting a test document.
+2. **Warmup** (if asked for): the query runs untimed, `resetQueries` before each run.
+   The first run of a query pays for cold caches and query planning; warmup keeps
+   that out of the numbers. With auto warmup, the first warmup run is timed to decide
+   how many more fit in 250 ms.
+3. **Timed runs**: `resetQueries` run (untimed), then the query runs and its time is
+   recorded. This repeats `--runs` times.
+4. **`postQueries`** run once, **even if an earlier step failed**. Typical use:
+   `DROP INDEX`, removing test documents.
+
+If a step fails, the benchmark stops, the failure and statement are printed on
+stderr, the post statements still run, and the result row is marked failed. Other
+benchmarks in the file still run. The command exits 1 if any benchmark (or any
+post statement) failed, and 2 for usage errors such as a bad file.
+
+An `INSERT`, `EVICT`, or `DELETE` benchmark that runs more than once with no
+`resetQueries` gets a warning: after the first run, an `EVICT` or `DELETE` usually
+finds nothing to remove, and an `INSERT` of a fixed `_id` fails or does nothing.
+An `UPDATE` does the same work on every run, so it needs no reset.
+
+## The benchmark file format
+
+A benchmark file is a JSON object. Each key names a benchmark, and each value
+describes it:
+
+```json
+{
+  "movies_by_rating": {
+    "description": "Optional: a note for people reading the file.",
+    "preQueries": [
+      "DROP INDEX IF EXISTS movies_rated ON movies",
+      "CREATE INDEX movies_rated ON movies (rated)"
+    ],
+    "query": "SELECT * FROM movies WHERE rated = 'PG'",
+    "postQueries": ["DROP INDEX IF EXISTS movies_rated ON movies"]
+  },
+  "evict_one": {
+    "resetQueries": ["INSERT INTO movies VALUES ({'_id': 'bench-doc', 'rated': 'TEST'})"],
+    "query": "EVICT FROM movies WHERE _id = 'bench-doc'"
+  }
+}
+```
+
+| Key | Required | Meaning |
+|---|---|---|
+| `query` | yes | The statement that is timed. |
+| `preQueries` | no | Statements run once, before warmup and timing. |
+| `resetQueries` | no | Statements run before every warmup and timed run, untimed (`--before-each` on the command line). |
+| `postQueries` | no | Statements run once at the end, even after a failure. |
+| `description` | no | Free text; not used by the runner. |
+
+- Each list holds strings, one DQL statement each. A single string also works.
+- A trailing `;` on a statement is optional.
+- Key order doesn't matter. The sample files list them in the order they run.
+- Keys the DQL benchmark suites use for their own tools (`category`, `qb`,
+  `sql_equivalent`, `expected_count`, `expected_first_rows_hash`, `negative`,
+  `expected_error_substring`) are accepted and ignored. Any other key is an error,
+  with a suggestion when it looks like a typo (`prequeries` → `preQueries`). This
+  stops a misspelled key from silently skipping an index.
+
+Two other shapes are accepted:
+
+- **A list** of benchmarks, each with an optional `"name"` (unnamed ones become
+  `benchmark_1`, `benchmark_2`, …):
+  `[{"name": "pg", "query": "SELECT * FROM movies WHERE rated = 'PG'"}]`
+- **A single benchmark**, with `query` at the top level:
+  `{"query": "SELECT count(*) FROM movies"}`
+
+## Creating a benchmark file
+
+1. **Start from a sample.** `dittosh dql bench --example <dataset> -o my-bench.json`
+   writes a few entries from that dataset's query catalog: a plain read, an indexed
+   read, an aggregate (and a join, for `retail-joins`), and a write that restores its
+   own data. Each has a `description` that explains its parts. Load the dataset
+   (`dittosh dql dataset load <dataset>`) to run it as is.
+2. **Write the statement you want to time** as `query`. Run it once with
+   `dittosh dql "<query>"` first to check it returns what you expect.
+3. **Decide what state it needs.**
+   - A read that should use an index: create the index in `preQueries` and drop it in
+     `postQueries`. Start `preQueries` with `DROP INDEX IF EXISTS …` so a leftover
+     index from an interrupted run doesn't fail the `CREATE INDEX`.
+   - A write: make every run do the same work. Use `resetQueries` to put the data
+     back before each run. For example, re-insert the document an `EVICT` removes,
+     or evict the document an `INSERT` adds. Use `postQueries` to remove test
+     documents at the end.
+   - Use `_id`s that can't collide with real data, such as `bench-…`.
+4. **Check that the store ends as it started.** Compare
+   `dittosh dql "SELECT count(*) FROM <collection>"` and `dittosh dql indexes` before
+   and after a run.
+5. **Run it:** `dittosh dql bench -f my-bench.json --runs 50 --warmup`.
+
+## Reading the results
+
+```
+benchmark         runs  warmup  rows  mean_ms  p50_ms  p95_ms  p99_ms  min_ms  max_ms  stddev_ms
+movies_by_rating    50      84   312    2.941   2.902   3.214   3.390   2.811   3.390      0.112
+```
+
+- `rows`: rows returned by the last timed run (0 for writes).
+- `p50_ms` is the median. `p95_ms` and `p99_ms` take the sorted sample at
+  index ⌊n × 0.95⌋ and ⌊n × 0.99⌋, as the benchmark suites do. With fewer than 100
+  runs, p99 is the slowest run; use more runs for a meaningful tail.
+- `stddev_ms` is the population standard deviation.
+- With `--runs 1`, the table shows just `rows` and `time_ms`.
+- Times are wall-clock time for `execute` from the CLI, including moving results
+  from the SDK into JavaScript. Compare runs made on the same machine with the same
+  data. Load a larger dataset (`dataset load <name> --docs <n>`) to see how a query
+  scales.
+
+To compare a change, save results with `-o before.json`, make the change (such as
+an index), and run again with `-o after.json`.
diff --git a/docs/testing-dql-diagnostics.md b/docs/testing-dql-diagnostics.md
index 309bd8f..e1b850f 100644
--- a/docs/testing-dql-diagnostics.md
+++ b/docs/testing-dql-diagnostics.md
@@ -76,7 +76,19 @@ Two things that are **not** bugs:
   dittosh dql "SELECT _id.title FROM movies WHERE rated = 'PG'" --profile
   ```
   Expect: per-operator timings with the hotspot flagged (`▲`), a results
-  summary line.
+  summary line (with `Stor`/`Yields` totals when the SDK reports them), a dim
+  `db … · request … · flags … · directives #profile` header line, and under
+  each operator dim detail lines: `recv … · send … · stor …`, `yields: budget
+  N · receiver N …` (largest first), and the operator's remaining attributes
+  (long values end in `…`).
+
+- [ ] **Join subplan**
+  ```bash
+  dittosh dql "SELECT m._id, y.label FROM movies m JOIN years y ON m.year = y.year LIMIT 50" --profile
+  ```
+  (needs a `years` collection with an index on `year`.) Expect: the `nlJoin`
+  operator is followed by a nested `inner: sequence` subtree with its own
+  timings, rather than a raw JSON `inner=` attribute.
 
 - [ ] **Server breakdown with `--time`**
   ```bash
diff --git a/docs/testing-dql-doctor.md b/docs/testing-dql-doctor.md
index e739483..5f31f2a 100644
--- a/docs/testing-dql-doctor.md
+++ b/docs/testing-dql-doctor.md
@@ -51,9 +51,56 @@ Prereq: the release build is installed (`scripts/install-release.sh`).
   ```
   Expect: the data-directory (or lock) check fails, `exit: 3`.
 
-## 3. Cleanup
+## 3. Report bundle (`--report`)
+
+- [ ] **Top-level alias**
+  ```bash
+  dittosh doctor ; echo "exit: $?"
+  ```
+  Expect: the same checks as `dittosh dql doctor`.
+
+- [ ] **Write a report after a failure**
+  ```bash
+  dittosh dql dataset load movies -d /tmp/mt-doctor --docs 100
+  dittosh dql "SELEC oops FROM movies" -d /tmp/mt-doctor   # fails, exit 1
+  cd /tmp && dittosh doctor -d /tmp/mt-doctor --report /tmp/mt-report.tar.gz
+  mkdir -p /tmp/mt-report && tar -xzf /tmp/mt-report.tar.gz -C /tmp/mt-report
+  ls /tmp/mt-report/mt-report
+  ```
+  Expect: stderr lists the contents and the issue link; the folder holds
+  `report.md`, `report.json`, `ditto-support-bundle.tar`. `report.md` shows the
+  `movies` collection with 100 documents, the failed `SELEC` command and its
+  error under "Last error", credentials as "set (value hidden)", and `~` for
+  your home folder.
+
+- [ ] **Leave parts out**
+  ```bash
+  dittosh doctor -d /tmp/mt-doctor --report /tmp/mt-report2.tar.gz --no-store --no-sdk-bundle
+  tar -tzf /tmp/mt-report2.tar.gz
+  ```
+  Expect: only `report.md` and `report.json`; the report says both parts were left out.
+
+- [ ] **SDK bundle only, and the rate limit**
+  ```bash
+  for i in 1 2 3 4; do dittosh dql support-bundle -d /tmp/mt-doctor -o /tmp/mt-sb$i.tar; done
+  dittosh dql support-bundle -d /tmp/mt-doctor --list
+  tar -tf /tmp/mt-sb1.tar
+  ```
+  Expect: each run saves a `.tar` (`ditto-logs.log.gz`, `device_logs_METADATA.json`,
+  `config_snapshot.json`). Once the store has made 3 bundles in 10 minutes
+  (the report above counts), a yellow note says a new one wasn't allowed and the
+  newest existing bundle was saved. `--list` shows the bundles.
+
+- [ ] **`--debug`**
+  ```bash
+  dittosh --debug dql "SELECT count(*) FROM movies" -d /tmp/mt-doctor 2>/tmp/mt-debug.log | jq .
+  grep -c DEBUG /tmp/mt-debug.log
+  ```
+  Expect: `jq` prints the count (stdout clean); the log has DEBUG lines.
+
+## 4. Cleanup
 
 - [ ] **Remove scratch dirs**
   ```bash
-  rm -rf /tmp/mt-doctor /tmp/mt-doctor-ro
+  rm -rf /tmp/mt-doctor /tmp/mt-doctor-ro /tmp/mt-report* /tmp/mt-sb*.tar /tmp/mt-debug.log
   ```
diff --git a/docs/testing-dql-repl.md b/docs/testing-dql-repl.md
index 516115c..c999494 100644
--- a/docs/testing-dql-repl.md
+++ b/docs/testing-dql-repl.md
@@ -85,7 +85,8 @@ tracing bootstrap on **stderr**; results still render normally.
 ## 5. Dot-commands
 
 - [ ] **`.help`** — lists the dot-commands:
-  `.collections`, `.indexes [name]`, `.break` / `.clear`, `.exit`.
+  `.collections`, `.indexes [name]`, `.metrics [section]`, `.break` /
+  `.clear`, `.exit`.
 
 - [ ] **`.collections`** — lists the `movies` collection (plus the
   `__feature_flags` system collection).
@@ -93,6 +94,23 @@ tracing bootstrap on **stderr**; results still render normally.
 - [ ] **`.indexes`** — lists all indexes (`[]`-style empty on a fresh
   store); **`.indexes movies`** scopes to one collection.
 
+- [ ] **`.metrics`** — after a few statements, prints `System metrics ·
+  Store, Query (DQL)` with a "first read this session" note, then boxed
+  tables: `Store · counters`, `Store · timings & distributions`, and the
+  same pair for `Query (DQL)`. Each table has a two-level header
+  (`since session opened` over Total/Count/Avg/Peak, `since last .metrics`
+  over Change/New/p50/p90/p99/Max); names are grouped under namespace rows
+  (`backend.sqlite3`, `query`) with labelled breakdowns as `└ db=main`.
+  Times read as `ns`/`µs`/`ms`/`s`, sizes as `B`/`KB`/`MB`.
+- [ ] **`.metrics` again** — no "first read" note; `query · requests`
+  Change is small (the previous `.metrics` read counts as one query).
+- [ ] **`.metrics query`** shows only the Query tables; **`.metrics all`**
+  adds every other section the SDK reports (e.g. Network, Transport);
+  **`.metrics bogus`** prints `unknown metrics section: bogus` plus usage
+  on stderr and the shell stays up.
+- [ ] **Narrow terminal** — resize to ~100 columns and run `.metrics`:
+  tables still fit, long names end in `…`.
+
 - [ ] **Unsupported node:repl commands are refused politely** — `.editor`,
   `.load`, `.save`. Expect: `not supported in the DQL REPL (use -f to run
   files)` on stderr, shell stays up.
diff --git a/docs/testing-dql-retail-joins.md b/docs/testing-dql-retail-joins.md
index 7f036fe..5e13d86 100644
--- a/docs/testing-dql-retail-joins.md
+++ b/docs/testing-dql-retail-joins.md
@@ -240,7 +240,7 @@ hard error — and the error itself tells you what to do next.
   dittosh version
   dittosh version --format json | jq '.ditto_sdk'
   ```
-  Expect: aligned key/value list; the JSON form reports `"5.1.0"`.
+  Expect: aligned key/value list; the JSON form reports `"5.2.0"`.
 
 - [ ] **Collections**
   ```bash
diff --git a/docs/testing-dql-retail.md b/docs/testing-dql-retail.md
index e1aec12..309de1b 100644
--- a/docs/testing-dql-retail.md
+++ b/docs/testing-dql-retail.md
@@ -68,7 +68,7 @@ Two things that are **not** bugs:
   dittosh version --format json | jq '.ditto_sdk'
   ```
   Expect: aligned key/value list (version, SDK, channel, token expiry,
-  paths); the JSON form parses and reports `"5.1.0"`.
+  paths); the JSON form parses and reports `"5.2.0"`.
 
 - [ ] **Collections**
   ```bash
diff --git a/docs/testing-tutorial.md b/docs/testing-tutorial.md
new file mode 100644
index 0000000..8a171a3
--- /dev/null
+++ b/docs/testing-tutorial.md
@@ -0,0 +1,161 @@
+# Manual testing — `dittosh tutorial`
+
+Checklist for the tutorial command: the generated Markdown walkthrough and
+the interactive DQL lessons (`--interactive`). Run top to bottom; check off
+what passes. Note anything off as a comment under the failing test.
+
+Prereq: the release build is installed (`scripts/install-release.sh`).
+
+The automated suites already run every runnable command block of the
+generated tutorial (`tests/e2e/tutorial.test.ts`) and every lesson's sample
+answer against a real store (`tests/integration/lessons.test.ts`). This
+checklist covers what they can't: reading it as a person, and the terminal UI.
+
+Not a bug: the ~7 `warning:`/`INFO` lines at startup are the SDK's native
+tracing bootstrap on **stderr**.
+
+## 1. Markdown tutorial
+
+- [ ] **Generate it**
+  ```bash
+  cd "$(mktemp -d)" && dittosh tutorial
+  ```
+  Expect: stderr `Wrote the tutorial to …/dittosh-tutorial.md` plus a pointer
+  to `--interactive`; nothing on stdout; exit 0.
+
+- [ ] **Tailored header and footer** — open the file. The `**Release:**` line
+  shows this CLI's version and Ditto SDK 5.2.0; section 1 names your install
+  channel (Homebrew or npm); the last line reads `Generated by dittosh tutorial
+  on <today> for <platform>`; the "Update the CLI" section shows the matching
+  manual upgrade command.
+
+- [ ] **Overwrite protection** — run `dittosh tutorial` again. Expect: exit 2,
+  `already exists — pass --force`. `dittosh tutorial --force` succeeds.
+
+- [ ] **Other targets** — `dittosh tutorial -o ~/Desktop/t.md` writes there;
+  `dittosh tutorial --stdout | head` prints the Markdown;
+  `dittosh tutorial --stdout -o x.md` exits 2.
+
+- [ ] **Follow it** — work through the file in a fresh terminal. Every
+  **Check:** line should hold. Pay attention to section 13, "Diagnostics and
+  advanced DQL": `degraded` is 0, a support bundle is created
+  (`USER_INITIATED`), `ANY … SATISFIES` returns only `o1`, the `USE IDS` evict
+  brings the count to 2, and `6 < price` returns Green tea and Coffee beans.
+
+- [ ] **Renders well** — preview the file in a Markdown viewer (VS Code,
+  GitHub). Headings, numbered list, tables, and code fences look right.
+
+## 2. Interactive lessons (full screen)
+
+Uses its own store (`<config dir>/tutorial-store`) — your default data
+directory is untouched. Use a window of at least 60×20; 80×24 and larger is
+the normal case.
+
+- [ ] **Start** — `dittosh tutorial --interactive`. Expect: the terminal
+  switches to a full-screen view (like `less`): a ` Learn DQL ` header with
+  `Lesson 1/27 · Beginner 1/8 · <title>` and a progress bar, a cyan lesson
+  panel (concept, "If you know SQL", syntax, **Task:**), a grey output panel,
+  the `learn>` prompt, and a key bar at the bottom.
+
+- [ ] **Pass a lesson** — type `SELECT * FROM products` and press Enter.
+  Expect: your statement and the products table in the output panel,
+  `✓ Correct! …` on the status line above the prompt, and the header and
+  lesson panel move to Lesson 2. The progress bar counts 1/27.
+
+- [ ] **Wrong answer** — in lesson 2 type `SELECT name FROM products;` (a
+  trailing `;` also works). Expect: `✗ Not quite.` with a specific reason on
+  the status line; still lesson 2.
+
+- [ ] **Query error** — type `SELEKT 1`. Expect: `Query error: …` on the status
+  line; the next statement clears it.
+
+- [ ] **Multi-line** — type `SELECT name,` (Enter) then `price FROM products`
+  (Enter). Expect: the second line gets a `|` prompt (the first ended on a
+  comma), then a pass. Backspace at the start of a `|` line joins it back;
+  Esc clears the input.
+
+- [ ] **Line editing** — ←/→, Home/End (Ctrl+A/Ctrl+E), Ctrl+W, Ctrl+U, and
+  ↑/↓ for earlier statements all work. Pasting a multi-line statement puts it
+  on one line.
+
+- [ ] **Help drawer** — `?` on an empty line (or `.help`) slides a Help panel
+  in from the **right** (Keys, Commands, How it works); the lesson and results
+  stay visible beside it. PgDn/PgUp scroll it (`PgDn more` in its title);
+  typing still goes to the prompt. `?` or Esc closes it (Esc closes the drawer
+  before it clears the input). Below ~88 columns it takes the full width.
+
+- [ ] **Data view** — every lesson card ends with `Collections: … · Ctrl+T
+  shows their fields`. Ctrl+T (or `.schema`) slides a Data panel in from the
+  right listing each collection's fields with type, `n of m` when only some
+  documents have it, and an example value; nested fields as `details.origin`,
+  arrays of objects as `lines[].sku`. Lesson 19 shows `products` and
+  `suppliers`. Insert a document with a new field and it appears. `?` switches
+  to Help; Ctrl+T or Esc closes. The plain shell has `.schema`.
+
+- [ ] **Case sensitivity** — lesson 1 explains that collection and field names
+  are case-sensitive. `SELECT * FROM Products` gets "✗ Not quite. Collection
+  names are case-sensitive: `Products` is a different (empty) collection from
+  `products`." `SELECT Name FROM products` gets the field version.
+
+- [ ] **Outline sidebar** — in a window 90+ columns wide, a Lessons panel on
+  the **left** shows `n/27`, each level with its progress, and the current
+  level's lessons (✓ done, ▸ current). It follows you between levels.
+  Ctrl+B hides/shows it (also in a narrower window, when there's room).
+
+- [ ] **Hints and answers** — Tab (or `.hint`) shows a hint; `.answer` shows a
+  statement.
+
+- [ ] **Scrolling** — run `SELECT * FROM products` in a short window: the
+  table opens at its top, the key bar shows `↓n PgUp/Dn`, PgDn/PgUp scroll.
+
+- [ ] **One action at a time** — after `.answer`, run any statement. Expect:
+  the answer is gone; the output panel shows only that statement and its
+  result. Tab replaces it with the hint but keeps the ✓/✗ line; Ctrl+N clears
+  both.
+
+- [ ] **Lesson picker** — Ctrl+L (or `.lessons`) shows every lesson under
+  Beginner / Intermediate / Advanced, ✓ on completed ones, and the current lesson highlighted. ↑/↓, PgUp/PgDn,
+  Home/End move; Enter opens a lesson; Esc closes without moving.
+
+- [ ] **Navigation** — Ctrl+N / Ctrl+P (or `.next` / `.back`), `.goto 10`,
+  `.level advanced` (lesson 19), `.level expert` and `.goto 99` (usage
+  messages in the output panel).
+
+- [ ] **Short window** — at 80×24, lesson 23's panel shows
+  `… ^O shows the whole lesson` with the **Task:** line still visible below it.
+  Ctrl+O shows the whole lesson; Ctrl+O again restores the output panel.
+
+- [ ] **Wide tables** — at 80 columns, lesson 1's 9-column table is cut off at
+  the panel edge with `…` rather than wrapping.
+
+- [ ] **Resize** — resize the window while a lesson is open. The layout
+  redraws to fit.
+
+- [ ] **EXPLAIN / PROFILE rendering** — `.goto 24`, then `.answer` and type it.
+  Expect: the query-plan tree (with `indexScan`), then a pass. Lesson 25
+  (PROFILE) shows the Execution Profile view.
+
+- [ ] **Reset** — `.goto 7`, run `UPDATE products SET stock = 999 WHERE
+  _id = 'p1'`, then `.reset`. Expect: "Practice data restored.";
+  `SELECT stock FROM products WHERE _id = 'p1'` shows 20.
+
+- [ ] **Exit and resume** — Ctrl+D on an empty line (also `.exit`, or Ctrl+C on
+  an empty line). Expect: the terminal returns to what it showed before, then
+  `Progress saved (n/27 lessons)`. Start again: it opens at the saved lesson.
+  `--level beginner` starts at lesson 1.
+
+## 3. Plain shell
+
+- [ ] **`--plain`** — `dittosh tutorial --interactive --plain`. Expect: the
+  line-by-line shell: "Learn DQL — interactive lessons", lesson cards printed
+  in the scrollback, the `learn>` prompt, Enter runs, `.help` explains.
+
+- [ ] **Small window** — in a window smaller than 60×20, `dittosh tutorial
+  --interactive` prints "The window is small, so the lessons use the simple
+  shell …" and starts the plain shell.
+
+- [ ] **Not a terminal** — `echo | dittosh tutorial --interactive`. Expect:
+  exit 2, "Interactive lessons need a terminal".
+
+- [ ] **Flags only with --interactive** — `dittosh tutorial --level advanced`
+  and `dittosh tutorial --plain` exit 2 with "only apply with --interactive".
diff --git a/docs/testing-version.md b/docs/testing-version.md
index b1fd36a..fbe687b 100644
--- a/docs/testing-version.md
+++ b/docs/testing-version.md
@@ -35,7 +35,7 @@ Prereq: the release build is installed (`scripts/install-release.sh`).
   ```bash
   dittosh version --format json | jq -r .ditto_sdk
   ```
-  Expect: `5.1.0`.
+  Expect: `5.2.0`.
 
 - [ ] **Data dir is absolute and expandable**
   ```bash
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..a7fd86d
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,144 @@
+# Troubleshooting and reporting problems
+
+## Check your install
+
+```bash
+dittosh doctor            # same as: dittosh dql doctor
+```
+
+`doctor` checks the platform, Node version, data directory, license token, that
+the Ditto SDK loads and opens a store, and whether another process holds the
+store's lock. Each line is `✓` or `✗` with the reason. The exit code says what
+failed: `0` all good, `3` a platform, SDK, token, or data-directory problem, `4`
+the store is locked by another process.
+
+## Report a problem: `dittosh doctor --report`
+
+```bash
+dittosh doctor --report                         # ./dittosh-report-<time>.tar.gz
+dittosh doctor --report ~/Desktop/report.tar.gz # choose the file name
+dittosh doctor --report -d /path/to/store       # report on a specific store
+```
+
+This runs the checks, then writes one `.tar.gz` file to attach to a
+[GitHub issue](https://github.com/getditto/ditto-cli/issues/new?template=bug_report.yml).
+It extracts into a single folder:
+
+| File | What's in it |
+|---|---|
+| `report.md` | Readable summary: the sections below. |
+| `report.json` | The same data, for tools. |
+| `ditto-support-bundle.tar` | Ditto's SDK support bundle (see below). |
+
+`report.md` has these sections:
+
+- **Environment:** dittosh and Ditto SDK versions, release or dev build, how it
+  was installed (Homebrew, npm), update status, license expiry, OS version, CPU,
+  memory, Node, whether stdout/stderr are terminals and their size, locale and
+  time zone.
+- **Checks:** every `doctor` check.
+- **Paths and disk:** the data directory, store size, free disk space, the config
+  directory and the files in it, and the executable path.
+- **Settings:** every `DITTOSH_*` variable, plus `NO_COLOR`, `FORCE_COLOR`, `CI`,
+  `PAGER`, `LESS`, `TERM`, `TERM_PROGRAM`, `COLORTERM`, `LANG`, `LC_ALL`, and
+  `SHELL`. Credential variables (`OFFLINE_TOKEN`, `DATABASE_ID`,
+  `DITTOSH_GITHUB_TOKEN`, and any variable whose name contains `TOKEN`, `SECRET`,
+  `PASSWORD`, `API_KEY`, `PRIVATE_KEY`, `LICENSE`, `CREDENTIAL`, or `AUTH`) appear only as "set" or "not set", and
+  their values are removed from everything else in the report, including the
+  saved last error.
+- **Store:** collection names with document counts, and index definitions. No
+  document contents.
+- **Ditto SDK support bundle:** its size and when it was made, or why there isn't
+  one.
+- **Last error:** the most recent command that failed, with its exit code, the
+  last 60 lines it printed to stderr, and a stack trace for unexpected errors.
+
+Options:
+
+| Option | Effect |
+|---|---|
+| `--report [file]` | Write the bundle (default `./dittosh-report-<time>.tar.gz`). |
+| `--no-store` | Leave out the store summary (collection names, counts, indexes). |
+| `--no-sdk-bundle` | Leave out the Ditto SDK support bundle. |
+| `-d, --data-dir <path>` | The store to check and summarize. |
+
+The report never includes the license token or document contents. In
+`report.md` and `report.json` your home folder is written as `~`. The command
+line in "Last error" is saved as typed, so a DQL statement with literal values
+shows those values.
+
+`ditto-support-bundle.tar` is Ditto's own file, included as is: its config and
+logs hold the database ID (which `report.md` shows only as "set"), full file
+paths including your home folder, peer keys, and sometimes values from
+queries the SDK planned with an index. Leave it out with `--no-sdk-bundle` if
+that matters for a public issue.
+
+`--report` never overwrites a file; given a directory, it writes the default
+name inside it. Extract the file (`tar -xzf dittosh-report-….tar.gz`) and read
+it before you share it.
+
+If the store doesn't exist yet, is locked, or won't open, the report says why
+and still includes everything else.
+
+### The last failed command
+
+Whenever a command exits with an error (exit code `1`, `3`, or `4`; not usage
+errors), dittosh saves the command, its exit code, and the end of its error
+output to `last-error.json` in the config directory. `doctor --report`
+includes it, so you can make the report after the fact. Running `doctor` or
+`support-bundle` doesn't replace it.
+
+## The Ditto SDK support bundle
+
+Ditto SDK 5.2 can build a support bundle on the device, offline. dittosh asks
+for one with `EXECUTE FUNCTION system_request_support_bundle()` and copies it
+out. It's a plain `.tar`:
+
+| File | What's in it |
+|---|---|
+| `ditto-logs.log.gz` | The SDK's debug logs (JSON lines, gzipped). The SDK keeps up to 15 MB / 15 days of logs in the store folder, even when logging is off. |
+| `device_logs_METADATA.json` | The time range the logs cover. |
+| `config_snapshot.json` | The store configuration with secrets removed, all system parameters, transport settings, and the SDK version. |
+| `dial9/dial9.bin.gz` | Runtime telemetry, when available. |
+| `bundle_errors.txt` | Present only if part of the bundle failed. |
+
+The SDK bundle isn't redacted by dittosh: the logs and config include the
+database ID, full file paths, and peer keys.
+
+To save only this bundle, for example when Ditto support asks for it:
+
+```bash
+dittosh dql support-bundle                     # ./ditto-support-bundle-<time>.tar
+dittosh dql support-bundle -o bundle.tar
+dittosh dql support-bundle --list              # bundles kept in the store
+```
+
+Ditto allows **3 new bundles per 10 minutes per store** and keeps the newest 10.
+Past the limit, dittosh saves the newest bundle already in the store and says
+so. Bundles are stored inside the store, so `--list` shows bundles from earlier
+reports too.
+
+## See SDK logs live: `--debug`
+
+```bash
+dittosh --debug dql "SELECT * FROM movies LIMIT 1"
+DITTOSH_DEBUG=1 dittosh dql "SELECT * FROM movies LIMIT 1"
+DITTOSH_DEBUG=verbose dittosh dql …            # even more detail
+```
+
+`--debug` (or `DITTOSH_DEBUG=1`) turns on the Ditto SDK's logs at Debug level and
+prints a stack trace when a command fails unexpectedly. Everything goes to
+stderr, so results on stdout and pipes like `| jq` are unchanged. Save the logs
+with `2> debug.log`.
+
+## Common problems
+
+| What you see | What to do |
+|---|---|
+| `dittosh: command not found` | Follow your package manager's shell setup and open a new terminal. |
+| Store locked / exit 4 | Close the other dittosh process or shell using the same data directory, or pass `-d` to use another. |
+| Expired license | Run `dittosh update`. |
+| `platform ✗` | The Ditto SDK supports macOS arm64, Linux x64/arm64, and Windows x64. Intel Macs aren't supported. |
+| `node ✗` | Install Node.js 22 or newer. |
+| `data directory ✗` | The directory isn't writable or a file is in the way; fix permissions or pass `-d`. |
+| WARN/INFO lines when a command starts | The native SDK prints these to stderr at startup; they're harmless and don't affect stdout. |
diff --git a/package-lock.json b/package-lock.json
index be7c42d..d766b23 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@dittolive/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@dittolive/cli",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "cpu": [
         "arm64",
         "x64"
@@ -18,13 +18,16 @@
         "win32"
       ],
       "dependencies": {
-        "@dittolive/ditto": "^5.1.0",
+        "@dittolive/ditto": "^5.2.0",
         "@inquirer/prompts": "^8.7.0",
         "chalk": "^5.6.2",
         "commander": "^14.0.2",
         "env-paths": "^3.0.0",
+        "ink": "^8.0.0",
+        "react": "^19.3.1",
         "string-width": "^8.2.2",
-        "tar": "^7.5.22"
+        "tar": "^7.5.22",
+        "wrap-ansi": "^10.0.2"
       },
       "bin": {
         "dittosh": "dist/cli.js"
@@ -32,19 +35,45 @@
       "devDependencies": {
         "@biomejs/biome": "^2.5.11",
         "@types/node": "^26.4.0",
+        "@types/react": "^19.3.0",
         "@types/semver": "7.8.0",
-        "@vitest/coverage-v8": "^4.1.11",
+        "@vitest/coverage-v8": "^4.1.12",
         "execa": "^10.0.1",
         "semver": "7.8.6",
         "tsup": "^8.5.1",
         "tsx": "^4.23.12",
         "typescript": "^7.0.2",
-        "vitest": "^4.1.11"
+        "vitest": "^4.1.12"
       },
       "engines": {
         "node": ">=22"
       }
     },
+    "node_modules/@alcalzone/ansi-tokenize": {
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/@alcalzone/ansi-tokenize/-/ansi-tokenize-0.3.1.tgz",
+      "integrity": "sha512-cUD0PT0YX+rImRhfn7BfMRduP/tX/Zqt/N0dHlAyn2RlcJssCb5KsCJkhln61eh9vuJDkH8wKn3L8zJzzWXPFg==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "is-fullwidth-code-point": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@alcalzone/ansi-tokenize/node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/@babel/helper-string-parser": {
       "version": "7.29.7",
       "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
@@ -281,9 +310,9 @@
       }
     },
     "node_modules/@dittolive/ditto": {
-      "version": "5.1.0",
-      "resolved": "https://registry.npmjs.org/@dittolive/ditto/-/ditto-5.1.0.tgz",
-      "integrity": "sha512-6K7sCzhZs/CwdZ5UbiplDnd0Ex4hLEH/yWnu70UdpKoS7fhOKKrO2PeuGTtlBs2cTyjyl55RBAAMQnr4exMkuA==",
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@dittolive/ditto/-/ditto-5.2.0.tgz",
+      "integrity": "sha512-NUl4xVe5WT/QmAHmNhAxaJ3E4d/66oFGg9y7TFLlaBa9mMasvpoz6Ncz/w85WIkTShzQScgk5XYlsXMbiFy7yA==",
       "license": "SEE LICENSE IN LICENSE.md",
       "engines": {
         "node": ">=14"
@@ -1143,19 +1172,19 @@
       }
     },
     "node_modules/@oxc-project/types": {
-      "version": "0.147.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.147.0.tgz",
-      "integrity": "sha512-IJ3s6ltHLp45S0bh7phkX+gJO7A1Wuz2EaqpAhb8WjqDwbzMiWKHhyyT42tskaWjEYXtHtVCPpnBJVT9+dcRLg==",
+      "version": "0.156.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.156.0.tgz",
+      "integrity": "sha512-1Duyg48TdJNdyhEB8Xn1L36bT9Pv6GUtlKjHxOys8xkaF/rQq3XJE+bAurSK/AgIz5mGFsb77cn9Pb20+WCScw==",
       "dev": true,
       "license": "MIT",
       "funding": {
-        "url": "https://github.com/sponsors/Boshen"
+        "url": "https://github.com/sponsors/oxc-project"
       }
     },
     "node_modules/@rolldown/binding-android-arm-eabi": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.6.tgz",
-      "integrity": "sha512-b+jTcARdTiFLI6jB4a5XjTm0RWd6KcRfQj/I2356fxUZemiho9zQLxo0RtCuMDAyKcLo6cEltkgbQp6d1+sjjQ==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.16.tgz",
+      "integrity": "sha512-ia3DwAs0OsMGS7+IConptSiyk9pEXkOx/AbJ2n/lAGxH3QkWQus1t8d7gnAT38FCU2sQu8lUbeR6AiZFv4JxaA==",
       "cpu": [
         "arm"
       ],
@@ -1170,9 +1199,9 @@
       }
     },
     "node_modules/@rolldown/binding-android-arm64": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.6.tgz",
-      "integrity": "sha512-lkWU8ZJaRk9q3CIEY1Tc7vIFALp3Xw5NfGJo2hQg5oIqNgxWi1zI+IiDEK3r70BF5Dzol1tcXsnzsRc8NLhG+Q==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.16.tgz",
+      "integrity": "sha512-kx5wBiMB6E7TEvpl2B9gjLU004BkvEm2Dr941BFjx/SontPwSzNuQUIoVKxHHoSjpFIfHMmcguyLOtyn0hObRg==",
       "cpu": [
         "arm64"
       ],
@@ -1187,9 +1216,9 @@
       }
     },
     "node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.6.tgz",
-      "integrity": "sha512-dgR56NYnvAszm7Ob1B2/Vn0e8bUQYZH2UjVaMMtMVOCKFSfjhfLmuA/9+O+F+ajUdG6B/bSssrKW6JJYASa8jA==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.16.tgz",
+      "integrity": "sha512-qslZrXnKJU4cUpjoAmtAo/KQM9e2IRMlmpig6Zpwj+8KWxW8v+nkAf9216Bsek9lOC1jvg2yCjygCFo2f83msQ==",
       "cpu": [
         "arm64"
       ],
@@ -1204,9 +1233,9 @@
       }
     },
     "node_modules/@rolldown/binding-darwin-x64": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.6.tgz",
-      "integrity": "sha512-vpVxFvUCFioJqug7OTvqptkc4yb8UX0AwfDmJpaR/0sWz+BUmqSVAf7c8JkUgnN8YLspb4a/N6NhTyMAmdyQ7Q==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.16.tgz",
+      "integrity": "sha512-FdF+y48ND13eAyM2mQn+85kvAqNlvRWROy2rhgA463X/0Gv4vGtazZtfaF1mRBLscYvtOlh4QnLjOWiFzX69OQ==",
       "cpu": [
         "x64"
       ],
@@ -1221,9 +1250,9 @@
       }
     },
     "node_modules/@rolldown/binding-freebsd-x64": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.6.tgz",
-      "integrity": "sha512-h1wG6Y6K3JlRswxsI64qQJqBAy4vrLuHgRbc8CZMGSWTOFRY6ghMApM1NKzB2I0n5xV1fjkE18SuVl2QpLeNpA==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.16.tgz",
+      "integrity": "sha512-ddjqFM5e95AgLbUPtKIS7V1KTVlA0RUgCVr5mn+/IEhsdy3pr+Vuj/HZ7nlMN2FyxIwUktOH1LEPIQXO1v9y1Q==",
       "cpu": [
         "x64"
       ],
@@ -1238,9 +1267,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.6.tgz",
-      "integrity": "sha512-tbCiqub0q2MVWJKgF5PoAlNWCtQydiOYSLIkd8sByqK/6MMYLJRcSXSYodqYtd0O+Fw7QaVmKKlS4oL94YRZ0w==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.16.tgz",
+      "integrity": "sha512-tHdKWbFkFBI687iim3LIyIvyL7j66VvQYkDPss5Stn/qyE2tWkR1YD0dXmXPFKKqT/o5ZEJVsaRsWS2meQwGOA==",
       "cpu": [
         "arm"
       ],
@@ -1255,9 +1284,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm64-gnu": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.6.tgz",
-      "integrity": "sha512-oxK9+baEBPhZG5HB4URY+uU04zJWeZlH6Tb9rB5DK4DF9XR1uXNLXt5Q5ZsugTKayNCNLhkcwz/ye74hRI98dg==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.16.tgz",
+      "integrity": "sha512-FJiLGAblPBMlBEdbOqw6kW6QcXDWAf/oJu7gYs9ZJZwmg+K+/zjFLxPTIY9izJUzxzc24FHvmseyA0IvJSl17w==",
       "cpu": [
         "arm64"
       ],
@@ -1275,9 +1304,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm64-musl": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.6.tgz",
-      "integrity": "sha512-muWCk27FVBEZtv0MsK8gnfSmgczA8KQ0uRVJbTABKhkRfQc38aUrcb7fhi3BNiyseFmgcRsoMfQsSNJ+DbZdSw==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.16.tgz",
+      "integrity": "sha512-hrJpblMsrQ58U9veWpbXzkhV5zStunds6HWLprqq1qauvgBr1E6P+24kLj6lSLI9vjRn/RYpjprhkHQPKGWpNg==",
       "cpu": [
         "arm64"
       ],
@@ -1295,9 +1324,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.6.tgz",
-      "integrity": "sha512-eWDoSfU7Co2qj3vgB3Dt4lj1mG6CoWbcJQkRMP3XJplyCMtuaq3LHvPFjS9QIPvMGWVadJC04Xiy0IdcVPtnwQ==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.16.tgz",
+      "integrity": "sha512-qJd/dC6j6CwLG9/s/RP2nb1RZ0GIgj7Ioj7x/SYa3RzjVrlzrmH0fhIOpfvqQDeIsdP0loi+kHaMhJzY1PBIaA==",
       "cpu": [
         "ppc64"
       ],
@@ -1315,9 +1344,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-s390x-gnu": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.6.tgz",
-      "integrity": "sha512-2bWNjRSIayvupRKxXUY2tWG9fYdoUlTqWywHRvE8Eq3GvuQ+f2HeIkve697fIt+IQs/PV8yFsdWuhp1aJ1PdnA==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.16.tgz",
+      "integrity": "sha512-Vx7Xg5uUJuNcujJjI70OICaH0EYj80BtOLZTSN7uOYg8QOLlyKnaG0IW7Fn/J0IpJsaKzmDKMhOQv1JBM9m9vg==",
       "cpu": [
         "s390x"
       ],
@@ -1335,9 +1364,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-x64-gnu": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.6.tgz",
-      "integrity": "sha512-KekI0gS0wLxe1UBSQSjenBVwou/JkcQPDzBPICGZjxUv9k3RteHDPBQaiOicZUFKRIH2wKEimGwVpnJsbPzu7w==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.16.tgz",
+      "integrity": "sha512-TNKhgE3uJTsTzatUSSYt0Kgo+Oa2uSlSjz4r1aEIea7HX6ULBym4fAlYUhG1i6pjNf2njfCUAfKwr6C3E9Xg1w==",
       "cpu": [
         "x64"
       ],
@@ -1355,9 +1384,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-x64-musl": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.6.tgz",
-      "integrity": "sha512-TvtPnfVr+HtyGiDmPK4VWmlNm7QhNNAcK5Q9A7aOXsI8545yCyaoMaicXrFZ72JzeYjaUVk7yT243zT0jzjFKQ==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.16.tgz",
+      "integrity": "sha512-7chXdpjXZ8qG0+mIxECN3cT9kvhZ3/oZhMX6Pp876P7CDrIy8nJswva6Mq357JR7eYXfuskwZxMeV1SzoZdHrA==",
       "cpu": [
         "x64"
       ],
@@ -1375,9 +1404,9 @@
       }
     },
     "node_modules/@rolldown/binding-openharmony-arm64": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.6.tgz",
-      "integrity": "sha512-iOo0VEay2XFhaCcH0sps5XIimkSuOnNaZrf6+ZkoSOQBJPKNU48RkmJv0/lSpipexu5P+ouFgafe5IGr/DiQfg==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.16.tgz",
+      "integrity": "sha512-Kwjt+7uNTJK5/MDkGWGVO2KQPnj8yAV75dMpfwyHZrJSXWHrniOB0aUEWlVYf3H1hOqFLIStLdM5QXq6bnKmOQ==",
       "cpu": [
         "arm64"
       ],
@@ -1392,9 +1421,9 @@
       }
     },
     "node_modules/@rolldown/binding-win32-arm64-msvc": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.6.tgz",
-      "integrity": "sha512-y5NTmmasMS455JlOCO4ZM9krIchv3Mvm1crL1iUPGOPgEzSkves9n0SdC5Sjz6+qWDFhd8/JpfWMH8NSWNHe+A==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.16.tgz",
+      "integrity": "sha512-/LH6WfjDRXXJz/p5xl4TmU+jpcnwcxbKEQBW/GZE0JHfN0lGIyTtsUEGaQ/q/GikkGJ2yLKe6pwm7AnEWO8pdw==",
       "cpu": [
         "arm64"
       ],
@@ -1409,9 +1438,9 @@
       }
     },
     "node_modules/@rolldown/binding-win32-x64-msvc": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.6.tgz",
-      "integrity": "sha512-np8iZSLfXlAD4kWhiyq/u0Yt8oZDtRQ8lGhQaCXo2rl37KNjeU0GjJuwr4P3oeZ++ROfofsKNBqR5LTO8aXyWQ==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.16.tgz",
+      "integrity": "sha512-1lv1KvX0Z871zfk7vw+dnXMMnHNyDwMzWG8Kv3HxDXMOhzCX4SHc7HK319fInP0i+0p9D8brkfzL7pJOaGl+tw==",
       "cpu": [
         "x64"
       ],
@@ -1883,6 +1912,16 @@
         "undici-types": "~8.3.0"
       }
     },
+    "node_modules/@types/react": {
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
+      "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "csstype": "^3.2.2"
+      }
+    },
     "node_modules/@types/semver": {
       "version": "7.8.0",
       "resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.8.0.tgz",
@@ -2231,14 +2270,14 @@
       }
     },
     "node_modules/@vitest/coverage-v8": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.11.tgz",
-      "integrity": "sha512-8MVGEFnJIcdGjcbfKmeq8z0pZHH0JlVtoVZH9Q/qwUp6wyFnEJUBMrw9DCaj+ra3vShGmhavjalMIhPNxZAUcw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.12.tgz",
+      "integrity": "sha512-6S7/iVknKglLAxMFxQGNppBI0iqJS2NgM6FBxavitj7KaDq/vywOWGf6dGu7F2L1Qy0G6S3uTp7aGshHrzK8JA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@bcoe/v8-coverage": "^1.0.2",
-        "@vitest/utils": "4.1.11",
+        "@vitest/utils": "4.1.12",
         "ast-v8-to-istanbul": "^1.0.0",
         "istanbul-lib-coverage": "^3.2.2",
         "istanbul-lib-report": "^3.0.1",
@@ -2252,8 +2291,8 @@
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
-        "@vitest/browser": "4.1.11",
-        "vitest": "4.1.11"
+        "@vitest/browser": "4.1.12",
+        "vitest": "4.1.12"
       },
       "peerDependenciesMeta": {
         "@vitest/browser": {
@@ -2262,16 +2301,16 @@
       }
     },
     "node_modules/@vitest/expect": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz",
-      "integrity": "sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.12.tgz",
+      "integrity": "sha512-vFlTt+YEu9WBpNjdGayNmlMVzrWPi1+sv853/7t2FU7hpO5gAFBKHzQmkCq5Xjpr+evegF2994LQT3hF3mRlqQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@standard-schema/spec": "^1.1.0",
         "@types/chai": "^5.2.2",
-        "@vitest/spy": "4.1.11",
-        "@vitest/utils": "4.1.11",
+        "@vitest/spy": "4.1.12",
+        "@vitest/utils": "4.1.12",
         "chai": "^6.2.2",
         "tinyrainbow": "^3.1.0"
       },
@@ -2280,13 +2319,13 @@
       }
     },
     "node_modules/@vitest/mocker": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.11.tgz",
-      "integrity": "sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.12.tgz",
+      "integrity": "sha512-fKShNpKZzupWZuY0z7egydvL0sqW4INEZBEExMBMAa6izlENEVHwoXgdaTCaBZ5fwlr4xf2o1wXC83n9RpO+NA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/spy": "4.1.11",
+        "@vitest/spy": "4.1.12",
         "estree-walker": "^3.0.3",
         "magic-string": "^0.30.21"
       },
@@ -2307,9 +2346,9 @@
       }
     },
     "node_modules/@vitest/pretty-format": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz",
-      "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.12.tgz",
+      "integrity": "sha512-XW9O8+Mxx4VpCtkYdMJLZQQwsVryP9wk7cPKDxtXFfwSak6yRh5+2fep/Y0XF/ElBvJHq8bcYdi6aeuai0opZA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2320,13 +2359,13 @@
       }
     },
     "node_modules/@vitest/runner": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz",
-      "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.12.tgz",
+      "integrity": "sha512-NKlVKCr5QnCe8jijdMnmkpHHU+WTqiLFR6G0pHji9uRjXK9xJl1k1nTw6F3pOOj2PDcsDt2GKQMI7wIsaT491w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "4.1.11",
+        "@vitest/utils": "4.1.12",
         "pathe": "^2.0.3"
       },
       "funding": {
@@ -2334,14 +2373,14 @@
       }
     },
     "node_modules/@vitest/snapshot": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz",
-      "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.12.tgz",
+      "integrity": "sha512-ko1y1Qgb/slzQ9mr+b89Cuqud8WG1TKtsPD8r7ZUBdvVOGt85Af2HwCqHujrhwJq95hs/9RM7fcAPg57o1vlzw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.11",
-        "@vitest/utils": "4.1.11",
+        "@vitest/pretty-format": "4.1.12",
+        "@vitest/utils": "4.1.12",
         "magic-string": "^0.30.21",
         "pathe": "^2.0.3"
       },
@@ -2350,9 +2389,9 @@
       }
     },
     "node_modules/@vitest/spy": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.11.tgz",
-      "integrity": "sha512-apNa/prQy2qCeywhnixOHPRCgGNhvg7T4Dapfl1GahLp/R+uhBm5cPyFoNVyqsNd2h1nJxL6BqqdIjiABL60YA==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.12.tgz",
+      "integrity": "sha512-RGq9x4JNGNTZHEJxvN0oSiJjeSCExm0n2gZKKJZHY9cX5AVA6M7VJILBT3ZJ/tJ/0J9uWT7fETV9/btoi//vSg==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -2360,13 +2399,13 @@
       }
     },
     "node_modules/@vitest/utils": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz",
-      "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.12.tgz",
+      "integrity": "sha512-Q3awXrwOfEV+qc3WmO5ONyE0yO7Q1gQ9/oyHxGLZ/pl7N3NO/ZztqQwKLuwMkV+CA1JYSIeO3gkHnRDIo4AVaA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.11",
+        "@vitest/pretty-format": "4.1.12",
         "convert-source-map": "^2.0.0",
         "tinyrainbow": "^3.1.0"
       },
@@ -2387,6 +2426,21 @@
         "node": ">=0.4.0"
       }
     },
+    "node_modules/ansi-escapes": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-7.3.0.tgz",
+      "integrity": "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==",
+      "license": "MIT",
+      "dependencies": {
+        "environment": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/ansi-regex": {
       "version": "6.3.0",
       "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.3.0.tgz",
@@ -2399,6 +2453,18 @@
         "url": "https://github.com/chalk/ansi-regex?sponsor=1"
       }
     },
+    "node_modules/ansi-styles": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-7.0.0.tgz",
+      "integrity": "sha512-kKvt3m4uwzqL0wlkPd09CmljPJGOZZ4D0fP65sqFSvPkMRKhNi+74MgIJ5QxE6SxqB4t4KyUFGg8+n5zjo6hew==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=22"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/any-promise": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz",
@@ -2428,6 +2494,18 @@
         "js-tokens": "^10.0.0"
       }
     },
+    "node_modules/auto-bind": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/auto-bind/-/auto-bind-5.0.1.tgz",
+      "integrity": "sha512-ooviqdwwgfIfNmDwo94wlshcdzfO64XV0Cg6oDsDYBJfITDz1EngD2z7DkbvCWn+XIMsIqW27sEVF6qcpJrRcg==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/bundle-require": {
       "version": "5.1.0",
       "resolved": "https://registry.npmjs.org/bundle-require/-/bundle-require-5.1.0.tgz",
@@ -2455,9 +2533,9 @@
       }
     },
     "node_modules/chai": {
-      "version": "6.2.2",
-      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
-      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.3.0.tgz",
+      "integrity": "sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -2507,6 +2585,49 @@
         "node": ">=18"
       }
     },
+    "node_modules/cli-boxes": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/cli-boxes/-/cli-boxes-4.0.1.tgz",
+      "integrity": "sha512-5IOn+jcCEHEraYolBPs/sT4BxYCe2nHg374OPiItB1O96KZFseS2gthU4twyYzeDcFew4DaUM/xwc5BQf08JJw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.20 <19 || >=20.10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-cursor": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-4.0.0.tgz",
+      "integrity": "sha512-VGtlMu3x/4DOtIUwEkRezxUZ2lBacNJCHash0N0WeZDBS+7Ux1dm3XWAgWYxLJFMMdOeXMHXorshEFhbMSGelg==",
+      "license": "MIT",
+      "dependencies": {
+        "restore-cursor": "^4.0.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-truncate": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-6.2.0.tgz",
+      "integrity": "sha512-5uyZew3nYoDgyltqSI8OER6DuyecorYOSVDAXl9wQ9Y8Re/HaQ/5qP0HmTUOUQqmvtpB+mlsf1gG/FUS3U1gLQ==",
+      "license": "MIT",
+      "dependencies": {
+        "slice-ansi": "^10.0.0",
+        "string-width": "^8.3.0"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/cli-width": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/cli-width/-/cli-width-4.1.0.tgz",
@@ -2516,6 +2637,18 @@
         "node": ">= 12"
       }
     },
+    "node_modules/code-excerpt": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/code-excerpt/-/code-excerpt-4.0.0.tgz",
+      "integrity": "sha512-xxodCmBen3iy2i0WtAK8FlFNrRzjUqjRsMfho58xT/wvZU1YTM3fCnRjcy1gJPMepaRlgm/0e6w8SpWHpn3/cA==",
+      "license": "MIT",
+      "dependencies": {
+        "convert-to-spaces": "^2.0.1"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
     "node_modules/commander": {
       "version": "14.0.3",
       "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
@@ -2549,6 +2682,22 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/convert-to-spaces": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/convert-to-spaces/-/convert-to-spaces-2.0.1.tgz",
+      "integrity": "sha512-rcQ1bsQO9799wq24uE5AM2tAILy4gXGIK/njFWcVQkGNZ96edlpY+A7bjwvzjYvLDyzmG1MmMLZhpcsb+klNMQ==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "devOptional": true,
+      "license": "MIT"
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -2589,6 +2738,18 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/environment": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz",
+      "integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/es-module-lexer": {
       "version": "2.3.2",
       "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
@@ -2596,6 +2757,18 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/es-toolkit": {
+      "version": "1.53.2",
+      "resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.53.2.tgz",
+      "integrity": "sha512-iUqZ+NlwH4jUgRmXZUxFBsV/9762TQEa1O4IXLFBmDEjVHScBytKuseX23I0+v9ShZ5MYxEx6WKNzm6IPnex8g==",
+      "license": "MIT",
+      "workspaces": [
+        "docs",
+        "benchmarks",
+        "tests/types",
+        "tests/browser-compat"
+      ]
+    },
     "node_modules/esbuild": {
       "version": "0.28.2",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
@@ -2638,6 +2811,15 @@
         "@esbuild/win32-x64": "0.28.2"
       }
     },
+    "node_modules/escape-string-regexp": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz",
+      "integrity": "sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/estree-walker": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
@@ -2842,6 +3024,113 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/indent-string": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-5.0.0.tgz",
+      "integrity": "sha512-m6FAo/spmsW2Ab2fU35JTYwtOKa2yAwXSwgjSv1TJzh4Mh7mC3lzAOVLBprb72XsTrgkEIsl7YrFNAiDiRhIGg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ink": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/ink/-/ink-8.0.0.tgz",
+      "integrity": "sha512-M2aFwZOqmkFxCwedy6xrP4E+DGoK57iahAFnfTqNyOyJ54O7DZzu027z/NI8EGy44Sw9O9BcbTF4QEUS2GHAtg==",
+      "license": "MIT",
+      "dependencies": {
+        "@alcalzone/ansi-tokenize": "^0.3.1",
+        "ansi-escapes": "^7.3.0",
+        "ansi-styles": "^7.0.0",
+        "auto-bind": "^5.0.1",
+        "chalk": "^6.0.1",
+        "cli-boxes": "^4.0.1",
+        "cli-cursor": "^4.0.0",
+        "cli-truncate": "^6.0.0",
+        "code-excerpt": "^4.0.0",
+        "es-toolkit": "^1.52.0",
+        "indent-string": "^5.0.0",
+        "is-in-ci": "^2.0.0",
+        "patch-console": "^2.0.0",
+        "quick-lru": "^7.3.0",
+        "react-reconciler": "^0.34.0",
+        "signal-exit": "^3.0.7",
+        "stack-utils": "^2.0.6",
+        "string-width": "^8.3.0",
+        "terminal-size": "^4.0.1",
+        "type-fest": "^5.10.0",
+        "widest-line": "^6.0.0",
+        "wrap-ansi": "^10.0.2",
+        "yoga-layout": "~3.2.1"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "@types/react": ">=19.3.0",
+        "react": ">=19.3.0",
+        "react-devtools-core": ">=6.1.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "react-devtools-core": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ink/node_modules/chalk": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-6.0.1.tgz",
+      "integrity": "sha512-/Ce6KNm3vIbWdMlNna6RVIZ/ICQxnJxCicet5LBKK9ZffBkqzDw0xh9EiKSljdRtiIQ1S1z4YgcscUUGzNCWrA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=22"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/ink/node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "license": "ISC"
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-5.1.0.tgz",
+      "integrity": "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==",
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.3.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-in-ci": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/is-in-ci/-/is-in-ci-2.0.0.tgz",
+      "integrity": "sha512-cFeerHriAnhrQSbpAxL37W1wcJKUUX07HyLWZCW1URJT/ra3GyUTzBgUnh24TMVfNTV2Hij2HLxkPHFZfOZy5w==",
+      "license": "MIT",
+      "bin": {
+        "is-in-ci": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/is-plain-obj": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz",
@@ -3278,6 +3567,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/mimic-fn": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
+      "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/minipass": {
       "version": "7.1.3",
       "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
@@ -3341,9 +3639,9 @@
       }
     },
     "node_modules/nanoid": {
-      "version": "3.3.18",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
-      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
+      "version": "3.3.20",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.20.tgz",
+      "integrity": "sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==",
       "dev": true,
       "funding": [
         {
@@ -3387,9 +3685,9 @@
       }
     },
     "node_modules/obug": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.4.tgz",
-      "integrity": "sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==",
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.2.1.tgz",
+      "integrity": "sha512-XrsrhT5sybtKI6wakr2SPOlGZWWYbUXZ7a0jT8/QOeAPau+1X/bSegNe5YR75oJmEZQbKningirmGOEJCIk61Q==",
       "dev": true,
       "funding": [
         "https://github.com/sponsors/sxzz",
@@ -3400,6 +3698,21 @@
         "node": ">=12.20.0"
       }
     },
+    "node_modules/onetime": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
+      "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
+      "license": "MIT",
+      "dependencies": {
+        "mimic-fn": "^2.1.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/parse-ms": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/parse-ms/-/parse-ms-4.0.0.tgz",
@@ -3413,6 +3726,15 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/patch-console": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/patch-console/-/patch-console-2.0.0.tgz",
+      "integrity": "sha512-0YNdUceMdaQwoKce1gatDScmMo5pu/tfABfnzEqeG0gtTmd7mh/WcwgUjtAeOU7N8nFFlbQBnFK2gXW5fGvmMA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      }
+    },
     "node_modules/path-key": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz",
@@ -3476,9 +3798,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.26",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
-      "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
+      "version": "8.5.32",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.32.tgz",
+      "integrity": "sha512-LJlKCCAUFKOuZxipUdYw1NzIITEsPcgyOG9LkvRJvuKj/bRzbuRY0ARXvL0pWGpsZvn8jku+LMep2eU0seHp8g==",
       "dev": true,
       "funding": [
         {
@@ -3496,9 +3818,9 @@
       ],
       "license": "MIT",
       "dependencies": {
-        "nanoid": "^3.3.17",
+        "nanoid": "^3.3.20",
         "picocolors": "^1.1.1",
-        "source-map-js": "^1.2.1"
+        "source-map-js": "^1.2.2"
       },
       "engines": {
         "node": "^10 || ^12 || >=14"
@@ -3563,6 +3885,42 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/quick-lru": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-7.3.0.tgz",
+      "integrity": "sha512-k9lSsjl36EJdK7I06v7APZCbyGT2vMTsYSRX1Q2nbYmnkBqgUhRkAuzH08Ciotteu/PLJmIF2+tti7o3C/ts2g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz",
+      "integrity": "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-reconciler": {
+      "version": "0.34.0",
+      "resolved": "https://registry.npmjs.org/react-reconciler/-/react-reconciler-0.34.0.tgz",
+      "integrity": "sha512-eVibvB1fc9j5Qf1KRkiM3GzRPBdjg2P6G6QV2f3P6Eb3OGMxRBhdg2rrUwjbV5JrQaJj8nOa8uajmmJA5tJWjQ==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.28.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "peerDependencies": {
+        "react": "^19.3.0"
+      }
+    },
     "node_modules/readdirp": {
       "version": "4.1.2",
       "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
@@ -3587,14 +3945,36 @@
         "node": ">=8"
       }
     },
+    "node_modules/restore-cursor": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-4.0.0.tgz",
+      "integrity": "sha512-I9fPXU9geO9bHOt9pHHOhOkYerIMsmVaWB0rA2AI9ERh/+x/i7MV5HKBNrg+ljO5eoPVgCcnFuRjJ9uH6I/3eg==",
+      "license": "MIT",
+      "dependencies": {
+        "onetime": "^5.1.0",
+        "signal-exit": "^3.0.2"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/restore-cursor/node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "license": "ISC"
+    },
     "node_modules/rolldown": {
-      "version": "1.2.6",
-      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.6.tgz",
-      "integrity": "sha512-vMM4q3aixf46GiF1Kok8jDPFsEpXgFWGjUHXNkNHNm+Y2adXAG2dbX91jkti3i0ZRsOlcmbuzAz1poObSHCmUA==",
+      "version": "1.2.16",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.16.tgz",
+      "integrity": "sha512-bWvlMpFKiTfDKfnK7FC2MPgPeWCf/Kpwsq49ApdW+FQaBZb6O6dZ4MAPbPUjp7hYQrw/RobqCzn64BRrQecGHw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@oxc-project/types": "=0.147.0",
+        "@oxc-project/types": "=0.156.0",
         "@rolldown/pluginutils": "^1.0.0"
       },
       "bin": {
@@ -3604,21 +3984,21 @@
         "node": "^20.19.0 || >=22.12.0"
       },
       "optionalDependencies": {
-        "@rolldown/binding-android-arm-eabi": "1.2.6",
-        "@rolldown/binding-android-arm64": "1.2.6",
-        "@rolldown/binding-darwin-arm64": "1.2.6",
-        "@rolldown/binding-darwin-x64": "1.2.6",
-        "@rolldown/binding-freebsd-x64": "1.2.6",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.2.6",
-        "@rolldown/binding-linux-arm64-gnu": "1.2.6",
-        "@rolldown/binding-linux-arm64-musl": "1.2.6",
-        "@rolldown/binding-linux-ppc64-gnu": "1.2.6",
-        "@rolldown/binding-linux-s390x-gnu": "1.2.6",
-        "@rolldown/binding-linux-x64-gnu": "1.2.6",
-        "@rolldown/binding-linux-x64-musl": "1.2.6",
-        "@rolldown/binding-openharmony-arm64": "1.2.6",
-        "@rolldown/binding-win32-arm64-msvc": "1.2.6",
-        "@rolldown/binding-win32-x64-msvc": "1.2.6"
+        "@rolldown/binding-android-arm-eabi": "1.2.16",
+        "@rolldown/binding-android-arm64": "1.2.16",
+        "@rolldown/binding-darwin-arm64": "1.2.16",
+        "@rolldown/binding-darwin-x64": "1.2.16",
+        "@rolldown/binding-freebsd-x64": "1.2.16",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.2.16",
+        "@rolldown/binding-linux-arm64-gnu": "1.2.16",
+        "@rolldown/binding-linux-arm64-musl": "1.2.16",
+        "@rolldown/binding-linux-ppc64-gnu": "1.2.16",
+        "@rolldown/binding-linux-s390x-gnu": "1.2.16",
+        "@rolldown/binding-linux-x64-gnu": "1.2.16",
+        "@rolldown/binding-linux-x64-musl": "1.2.16",
+        "@rolldown/binding-openharmony-arm64": "1.2.16",
+        "@rolldown/binding-win32-arm64-msvc": "1.2.16",
+        "@rolldown/binding-win32-x64-msvc": "1.2.16"
       }
     },
     "node_modules/rollup": {
@@ -3673,6 +4053,12 @@
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/scheduler": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+      "license": "MIT"
+    },
     "node_modules/semver": {
       "version": "7.8.6",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz",
@@ -3705,6 +4091,22 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/slice-ansi": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-10.0.0.tgz",
+      "integrity": "sha512-2rOYDG420YH3p2PbRAu6LdYnGuMZldshqZS2qqFh/WEzAytVo7b8n1HhubLtRunvqjao74MmGfW4sY4ex0YvpQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^7.0.0",
+        "string-width": "^8.3.0"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/slice-ansi?sponsor=1"
+      }
+    },
     "node_modules/source-map": {
       "version": "0.7.6",
       "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz",
@@ -3716,15 +4118,27 @@
       }
     },
     "node_modules/source-map-js": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
-      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
+      "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
       "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=0.10.0"
       }
     },
+    "node_modules/stack-utils": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.6.tgz",
+      "integrity": "sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==",
+      "license": "MIT",
+      "dependencies": {
+        "escape-string-regexp": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/stackback": {
       "version": "0.0.2",
       "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
@@ -3733,16 +4147,16 @@
       "license": "MIT"
     },
     "node_modules/std-env": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.2.0.tgz",
-      "integrity": "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==",
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.3.0.tgz",
+      "integrity": "sha512-OtU/EgQ1kIm5KwqQpBC6ZEMXrZRui11w8zgfTWp8cdO9B8OaPsbA8bTHO2P+HNo1VlUTGMVBwPhydu6poeXiag==",
       "dev": true,
       "license": "MIT"
     },
     "node_modules/string-width": {
-      "version": "8.2.2",
-      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.2.tgz",
-      "integrity": "sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==",
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.3.0.tgz",
+      "integrity": "sha512-ZbmZM0JCihQN91dWnxoipT2KOEyHqEyfRXUyjuRhW8b/xnqPDoq4gWEVApTVa9db2wN8mmoikgFBbjh71+cGeQ==",
       "license": "MIT",
       "dependencies": {
         "get-east-asian-width": "^1.5.0",
@@ -3829,6 +4243,18 @@
         "node": ">=8"
       }
     },
+    "node_modules/tagged-tag": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
+      "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/tar": {
       "version": "7.5.22",
       "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz",
@@ -3845,6 +4271,18 @@
         "node": ">=18"
       }
     },
+    "node_modules/terminal-size": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/terminal-size/-/terminal-size-4.0.1.tgz",
+      "integrity": "sha512-avMLDQpUI9I5XFrklECw1ZEUPJhqzcwSWsyyI8blhRLT+8N1jLJWLWWYQpB2q2xthq8xDvjZPISVh53T/+CLYQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/thenify": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz",
@@ -3876,9 +4314,9 @@
       "license": "MIT"
     },
     "node_modules/tinyexec": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.0.tgz",
-      "integrity": "sha512-QKAl9m8gWWGHV8jZcPeym6j+XULi6tOf1mT83WYJ4Lk2ytW/uwAWkrP0uFsdoYMdueVJ0qs26wZ+23xeB4ibNQ==",
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz",
+      "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -3903,9 +4341,9 @@
       }
     },
     "node_modules/tinyrainbow": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
-      "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.2.0.tgz",
+      "integrity": "sha512-LgO3D9yZJjApUiuUfl9iFAwrtaX4+lok3wJIqttGoKCHlWUqHqbQpnxCf82L8FjgKsh4iGo78hqJwgL8F6To2A==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -3983,9 +4421,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/aix-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
-      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.2.tgz",
+      "integrity": "sha512-GZMB+a0mOMZs4MpDbj8RJp4cw+w1WV5NYD6xzgvzUJ5Ek2jerwfO2eADyI6ExDSUED+1X8aMbegahsJi+8mgpw==",
       "cpu": [
         "ppc64"
       ],
@@ -4000,9 +4438,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/android-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
-      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.2.tgz",
+      "integrity": "sha512-DVNI8jlPa7Ujbr1yjU2PfUSRtAUZPG9I1RwW4F4xFB1Imiu2on0ADiI/c3td+KmDtVKNbi+nffGDQMfcIMkwIA==",
       "cpu": [
         "arm"
       ],
@@ -4017,9 +4455,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/android-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
-      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.2.tgz",
+      "integrity": "sha512-pvz8ZZ7ot/RBphf8fv60ljmaoydPU12VuXHImtAs0XhLLw+EXBi2BLe3OYSBslR4rryHvweW5gmkKFwTiFy6KA==",
       "cpu": [
         "arm64"
       ],
@@ -4034,9 +4472,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/android-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
-      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.2.tgz",
+      "integrity": "sha512-z8Ank4Byh4TJJOh4wpz8g2vDy75zFL0TlZlkUkEwYXuPSgX8yzep596n6mT7905kA9uHZsf/o2OJZubl2l3M7A==",
       "cpu": [
         "x64"
       ],
@@ -4051,9 +4489,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/darwin-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
-      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.2.tgz",
+      "integrity": "sha512-davCD2Zc80nzDVRwXTcQP/28fiJbcOwvdolL0sOiOsbwBa72kegmVU0Wrh1MYrbuCL98Omp5dVhQFWRKR2ZAlg==",
       "cpu": [
         "arm64"
       ],
@@ -4068,9 +4506,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/darwin-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
-      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.2.tgz",
+      "integrity": "sha512-ZxtijOmlQCBWGwbVmwOF/UCzuGIbUkqB1faQRf5akQmxRJ1ujusWsb3CVfk/9iZKr2L5SMU5wPBi1UWbvL+VQA==",
       "cpu": [
         "x64"
       ],
@@ -4085,9 +4523,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.2.tgz",
+      "integrity": "sha512-lS/9CN+rgqQ9czogxlMcBMGd+l8Q3Nj1MFQwBZJyoEKI50XGxwuzznYdwcav6lpOGv5BqaZXqvBSiB/kJ5op+g==",
       "cpu": [
         "arm64"
       ],
@@ -4102,9 +4540,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/freebsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
-      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.2.tgz",
+      "integrity": "sha512-tAfqtNYb4YgPnJlEFu4c212HYjQWSO/w/h/lQaBK7RbwGIkBOuNKQI9tqWzx7Wtp7bTPaGC6MJvWI608P3wXYA==",
       "cpu": [
         "x64"
       ],
@@ -4119,9 +4557,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-arm": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
-      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.2.tgz",
+      "integrity": "sha512-vWfq4GaIMP9AIe4yj1ZUW18RDhx6EPQKjwe7n8BbIecFtCQG4CfHGaHuh7fdfq+y3LIA2vGS/o9ZBGVxIDi9hw==",
       "cpu": [
         "arm"
       ],
@@ -4136,9 +4574,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
-      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.2.tgz",
+      "integrity": "sha512-hYxN8pr66NsCCiRFkHUAsxylNOcAQaxSSkHMMjcpx0si13t1LHFphxJZUiGwojB1a/Hd5OiPIqDdXONia6bhTw==",
       "cpu": [
         "arm64"
       ],
@@ -4153,9 +4591,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
-      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.2.tgz",
+      "integrity": "sha512-MJt5BRRSScPDwG2hLelYhAAKh9imjHK5+NE/tvnRLbIqUWa+0E9N4WNMjmp/kXXPHZGqPLxggwVhz7QP8CTR8w==",
       "cpu": [
         "ia32"
       ],
@@ -4170,9 +4608,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-loong64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
-      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.2.tgz",
+      "integrity": "sha512-lugyF1atnAT463aO6KPshVCJK5NgRnU4yb3FUumyVz+cGvZbontBgzeGFO1nF+dPueHD367a2ZXe1NtUkAjOtg==",
       "cpu": [
         "loong64"
       ],
@@ -4187,9 +4625,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-mips64el": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
-      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.2.tgz",
+      "integrity": "sha512-nlP2I6ArEBewvJ2gjrrkESEZkB5mIoaTswuqNFRv/WYd+ATtUpe9Y09RnJvgvdag7he0OWgEZWhviS1OTOKixw==",
       "cpu": [
         "mips64el"
       ],
@@ -4204,9 +4642,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-ppc64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
-      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.2.tgz",
+      "integrity": "sha512-C92gnpey7tUQONqg1n6dKVbx3vphKtTHJaNG2Ok9lGwbZil6DrfyecMsp9CrmXGQJmZ7iiVXvvZH6Ml5hL6XdQ==",
       "cpu": [
         "ppc64"
       ],
@@ -4221,9 +4659,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-riscv64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
-      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.2.tgz",
+      "integrity": "sha512-B5BOmojNtUyN8AXlK0QJyvjEZkWwy/FKvakkTDCziX95AowLZKR6aCDhG7LeF7uMCXEJqwa8Bejz5LTPYm8AvA==",
       "cpu": [
         "riscv64"
       ],
@@ -4238,9 +4676,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-s390x": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
-      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.2.tgz",
+      "integrity": "sha512-p4bm9+wsPwup5Z8f4EpfN63qNagQ47Ua2znaqGH6bqLlmJ4bx97Y9JdqxgGZ6Y8xVTixUnEkoKSHcpRlDnNr5w==",
       "cpu": [
         "s390x"
       ],
@@ -4255,9 +4693,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/linux-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
-      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.2.tgz",
+      "integrity": "sha512-uwp2Tip5aPmH+NRUwTcfLb+W32WXjpFejTIOWZFw/v7/KnpCDKG66u4DLcurQpiYTiYwQ9B7KOeMJvLCu/OvbA==",
       "cpu": [
         "x64"
       ],
@@ -4272,9 +4710,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.2.tgz",
+      "integrity": "sha512-Kj6DiBlwXrPsCRDeRvGAUb/LNrBASrfqAIok+xB0LxK8CHqxZ037viF13ugfsIpePH93mX7xfJp97cyDuTZ3cw==",
       "cpu": [
         "arm64"
       ],
@@ -4289,9 +4727,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/netbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.2.tgz",
+      "integrity": "sha512-HwGDZ0VLVBY3Y+Nw0JexZy9o/nUAWq9MlV7cahpaXKW6TOzfVno3y3/M8Ga8u8Yr7GldLOov27xiCnqRZf0tCA==",
       "cpu": [
         "x64"
       ],
@@ -4306,9 +4744,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
-      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.2.tgz",
+      "integrity": "sha512-DNIHH2BPQ5551A7oSHD0CKbwIA/Ox7+78/AWkbS5QoRzaqlev2uFayfSxq68EkonB+IKjiuxBFoV8ESJy8bOHA==",
       "cpu": [
         "arm64"
       ],
@@ -4323,9 +4761,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/openbsd-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
-      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.2.tgz",
+      "integrity": "sha512-/it7w9Nb7+0KFIzjalNJVR5bOzA9Vay+yIPLVHfIQYG/j+j9VTH84aNB8ExGKPU4AzfaEvN9/V4HV+F+vo8OEg==",
       "cpu": [
         "x64"
       ],
@@ -4340,9 +4778,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
-      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.2.tgz",
+      "integrity": "sha512-LRBbCmiU51IXfeXk59csuX/aSaToeG7w48nMwA6049Y4J4+VbWALAuXcs+qcD04rHDuSCSRKdmY63sruDS5qag==",
       "cpu": [
         "arm64"
       ],
@@ -4357,9 +4795,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/sunos-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
-      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.2.tgz",
+      "integrity": "sha512-kMtx1yqJHTmqaqHPAzKCAkDaKsffmXkPHThSfRwZGyuqyIeBvf08KSsYXl+abf5HDAPMJIPnbBfXvP2ZC2TfHg==",
       "cpu": [
         "x64"
       ],
@@ -4374,9 +4812,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/win32-arm64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
-      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.2.tgz",
+      "integrity": "sha512-Yaf78O/B3Kkh+nKABUF++bvJv5Ijoy9AN1ww904rOXZFLWVc5OLOfL56W+C8F9xn5JQZa3UX6m+IktJnIb1Jjg==",
       "cpu": [
         "arm64"
       ],
@@ -4391,9 +4829,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/win32-ia32": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
-      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.2.tgz",
+      "integrity": "sha512-Iuws0kxo4yusk7sw70Xa2E2imZU5HoixzxfGCdxwBdhiDgt9vX9VUCBhqcwY7/uh//78A1hMkkROMJq9l27oLQ==",
       "cpu": [
         "ia32"
       ],
@@ -4408,9 +4846,9 @@
       }
     },
     "node_modules/tsup/node_modules/@esbuild/win32-x64": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
-      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.2.tgz",
+      "integrity": "sha512-sRdU18mcKf7F+YgheI/zGf5alZatMUTKj/jNS6l744f9u3WFu4v7twcUI9vu4mknF4Y9aDlblIie0IM+5xxaqQ==",
       "cpu": [
         "x64"
       ],
@@ -4425,9 +4863,9 @@
       }
     },
     "node_modules/tsup/node_modules/esbuild": {
-      "version": "0.27.7",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
-      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "version": "0.27.2",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.2.tgz",
+      "integrity": "sha512-HyNQImnsOC7X9PMNaCIeAm4ISCQXs5a5YasTXVliKv4uuBo1dKrG0A+uQS8M5eXjVMnLg3WgXaKvprHlFJQffw==",
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
@@ -4438,32 +4876,32 @@
         "node": ">=18"
       },
       "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.27.7",
-        "@esbuild/android-arm": "0.27.7",
-        "@esbuild/android-arm64": "0.27.7",
-        "@esbuild/android-x64": "0.27.7",
-        "@esbuild/darwin-arm64": "0.27.7",
-        "@esbuild/darwin-x64": "0.27.7",
-        "@esbuild/freebsd-arm64": "0.27.7",
-        "@esbuild/freebsd-x64": "0.27.7",
-        "@esbuild/linux-arm": "0.27.7",
-        "@esbuild/linux-arm64": "0.27.7",
-        "@esbuild/linux-ia32": "0.27.7",
-        "@esbuild/linux-loong64": "0.27.7",
-        "@esbuild/linux-mips64el": "0.27.7",
-        "@esbuild/linux-ppc64": "0.27.7",
-        "@esbuild/linux-riscv64": "0.27.7",
-        "@esbuild/linux-s390x": "0.27.7",
-        "@esbuild/linux-x64": "0.27.7",
-        "@esbuild/netbsd-arm64": "0.27.7",
-        "@esbuild/netbsd-x64": "0.27.7",
-        "@esbuild/openbsd-arm64": "0.27.7",
-        "@esbuild/openbsd-x64": "0.27.7",
-        "@esbuild/openharmony-arm64": "0.27.7",
-        "@esbuild/sunos-x64": "0.27.7",
-        "@esbuild/win32-arm64": "0.27.7",
-        "@esbuild/win32-ia32": "0.27.7",
-        "@esbuild/win32-x64": "0.27.7"
+        "@esbuild/aix-ppc64": "0.27.2",
+        "@esbuild/android-arm": "0.27.2",
+        "@esbuild/android-arm64": "0.27.2",
+        "@esbuild/android-x64": "0.27.2",
+        "@esbuild/darwin-arm64": "0.27.2",
+        "@esbuild/darwin-x64": "0.27.2",
+        "@esbuild/freebsd-arm64": "0.27.2",
+        "@esbuild/freebsd-x64": "0.27.2",
+        "@esbuild/linux-arm": "0.27.2",
+        "@esbuild/linux-arm64": "0.27.2",
+        "@esbuild/linux-ia32": "0.27.2",
+        "@esbuild/linux-loong64": "0.27.2",
+        "@esbuild/linux-mips64el": "0.27.2",
+        "@esbuild/linux-ppc64": "0.27.2",
+        "@esbuild/linux-riscv64": "0.27.2",
+        "@esbuild/linux-s390x": "0.27.2",
+        "@esbuild/linux-x64": "0.27.2",
+        "@esbuild/netbsd-arm64": "0.27.2",
+        "@esbuild/netbsd-x64": "0.27.2",
+        "@esbuild/openbsd-arm64": "0.27.2",
+        "@esbuild/openbsd-x64": "0.27.2",
+        "@esbuild/openharmony-arm64": "0.27.2",
+        "@esbuild/sunos-x64": "0.27.2",
+        "@esbuild/win32-arm64": "0.27.2",
+        "@esbuild/win32-ia32": "0.27.2",
+        "@esbuild/win32-x64": "0.27.2"
       }
     },
     "node_modules/tsup/node_modules/tinyexec": {
@@ -4492,6 +4930,21 @@
         "fsevents": "~2.3.3"
       }
     },
+    "node_modules/type-fest": {
+      "version": "5.10.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.10.0.tgz",
+      "integrity": "sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==",
+      "license": "(MIT OR CC0-1.0)",
+      "dependencies": {
+        "tagged-tag": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/typescript": {
       "version": "7.0.2",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
@@ -4555,16 +5008,16 @@
       }
     },
     "node_modules/vite": {
-      "version": "8.2.2",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.2.2.tgz",
-      "integrity": "sha512-cFKLV/PRgAUlIRm5WjMjJ86jrftzpqcgH+Us+DS8mI3CDNiH30Whrz8uHL3+MOLPAgqbMBAqWdAHAphOAM+z/Q==",
+      "version": "8.3.6",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.3.6.tgz",
+      "integrity": "sha512-UI7dK29NnS54Fk+mmo7o+jI6U8Fp7hDl+X5Q1k45WH+d4dSlbLVUETGQ+hfkNgvLQGyoElPj837nZyv4MBc0VA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "lightningcss": "^1.33.0",
-        "picomatch": "^4.0.5",
-        "postcss": "^8.5.26",
-        "rolldown": "~1.2.4",
+        "picomatch": "^4.0.7",
+        "postcss": "^8.5.32",
+        "rolldown": "~1.2.16",
         "tinyglobby": "^0.2.17"
       },
       "bin": {
@@ -4581,7 +5034,7 @@
       },
       "peerDependencies": {
         "@types/node": "^20.19.0 || >=22.12.0",
-        "@vitejs/devtools": "^0.4.0 || ^0.5.0",
+        "@vitejs/devtools": "^0.7.1 || ^0.8.0",
         "esbuild": "^0.27.0 || ^0.28.0",
         "jiti": ">=1.21.0",
         "less": "^4.0.0",
@@ -4633,19 +5086,19 @@
       }
     },
     "node_modules/vitest": {
-      "version": "4.1.11",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz",
-      "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.12.tgz",
+      "integrity": "sha512-5eWdz2yb3ajxWF3C8C4TjkXl7FGm3n2E/VlazALrQHzK7nYMSGFnCZto0bbPNl77AwkOZVLk0YnBAejUu0NiWA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/expect": "4.1.11",
-        "@vitest/mocker": "4.1.11",
-        "@vitest/pretty-format": "4.1.11",
-        "@vitest/runner": "4.1.11",
-        "@vitest/snapshot": "4.1.11",
-        "@vitest/spy": "4.1.11",
-        "@vitest/utils": "4.1.11",
+        "@vitest/expect": "4.1.12",
+        "@vitest/mocker": "4.1.12",
+        "@vitest/pretty-format": "4.1.12",
+        "@vitest/runner": "4.1.12",
+        "@vitest/snapshot": "4.1.12",
+        "@vitest/spy": "4.1.12",
+        "@vitest/utils": "4.1.12",
         "es-module-lexer": "^2.0.0",
         "expect-type": "^1.3.0",
         "magic-string": "^0.30.21",
@@ -4673,12 +5126,12 @@
         "@edge-runtime/vm": "*",
         "@opentelemetry/api": "^1.9.0",
         "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
-        "@vitest/browser-playwright": "4.1.11",
-        "@vitest/browser-preview": "4.1.11",
-        "@vitest/browser-webdriverio": "4.1.11",
-        "@vitest/coverage-istanbul": "4.1.11",
-        "@vitest/coverage-v8": "4.1.11",
-        "@vitest/ui": "4.1.11",
+        "@vitest/browser-playwright": "4.1.12",
+        "@vitest/browser-preview": "4.1.12",
+        "@vitest/browser-webdriverio": "^4.1.11",
+        "@vitest/coverage-istanbul": "4.1.12",
+        "@vitest/coverage-v8": "4.1.12",
+        "@vitest/ui": "4.1.12",
         "happy-dom": "*",
         "jsdom": "*",
         "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
@@ -4755,6 +5208,49 @@
         "node": ">=8"
       }
     },
+    "node_modules/widest-line": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/widest-line/-/widest-line-6.0.0.tgz",
+      "integrity": "sha512-U89AsyEeAsyoF0zVJBkG9zBgekjgjK7yk9sje3F4IQpXBJ10TF6ByLlIfjMhcmHMJgHZI4KHt4rdNfktzxIAMA==",
+      "license": "MIT",
+      "dependencies": {
+        "string-width": "^8.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/wrap-ansi": {
+      "version": "10.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-10.0.2.tgz",
+      "integrity": "sha512-6OLRNZqRntVGBm26ghZ5eZhCuWWyOkRCSn8XsOIuq5stpCE/tjLbdozd93naILZig0lmD8ANfRwnhn0DLeXGlg==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.3",
+        "string-width": "^8.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/yallist": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz",
@@ -4776,6 +5272,12 @@
       "funding": {
         "url": "https://github.com/sponsors/sindresorhus"
       }
+    },
+    "node_modules/yoga-layout": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/yoga-layout/-/yoga-layout-3.2.1.tgz",
+      "integrity": "sha512-0LPOt3AxKqMdFBZA3HBAt/t/8vIKq7VaQYbuA8WxCgung+p9TVyKRYdpvCb80HcdTN2NkbIKbhNwKUfm3tQywQ==",
+      "license": "MIT"
     }
   }
 }
diff --git a/package.json b/package.json
index 0b06733..ddee870 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@dittolive/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "dittosh — the Ditto CLI: run DQL against a local Ditto store, load sample datasets, and install DQL skills for AI agents",
   "license": "MIT",
   "repository": {
@@ -48,24 +48,28 @@
     "spike:c": "node --env-file=.env scripts/spike-c.mjs"
   },
   "dependencies": {
-    "@dittolive/ditto": "^5.1.0",
+    "@dittolive/ditto": "^5.2.0",
     "@inquirer/prompts": "^8.7.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "env-paths": "^3.0.0",
+    "ink": "^8.0.0",
+    "react": "^19.3.1",
     "string-width": "^8.2.2",
-    "tar": "^7.5.22"
+    "tar": "^7.5.22",
+    "wrap-ansi": "^10.0.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.11",
     "@types/node": "^26.4.0",
+    "@types/react": "^19.3.0",
     "@types/semver": "7.8.0",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.12",
     "execa": "^10.0.1",
     "semver": "7.8.6",
     "tsup": "^8.5.1",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.12"
   }
 }
diff --git a/releases/v0.2.0.md b/releases/v0.2.0.md
new file mode 100644
index 0000000..b8a988d
--- /dev/null
+++ b/releases/v0.2.0.md
@@ -0,0 +1,108 @@
+# dittosh v0.2.0
+
+This release updates the bundled Ditto SDK to 5.2.0, adds a tutorial command
+with interactive DQL lessons, adds a benchmark command, adds `dittosh doctor --report` for bug reports, adds live system
+metrics to the interactive shell, shows the full execution profile the SDK reports, and refreshes
+development dependencies to resolve security advisories.
+
+## New
+
+`dittosh tutorial` writes a hands-on Markdown walkthrough of the CLI, tailored to
+your installation (version, Homebrew or npm upgrade commands, platform), from
+importing and querying to diagnostics and advanced DQL.
+
+`dittosh tutorial --interactive` teaches DQL in 27 guided lessons across
+beginner, intermediate, and advanced levels, in a full-screen view: the lesson
+stays in view at the top, results scroll below it, the ✓/✗ verdict stays
+above the prompt, a sidebar outlines the lessons and your progress, Ctrl+T shows
+the fields of the collections each lesson uses, and `?` slides in a help panel.
+
+- Each lesson explains a concept (projection, predicates, functions,
+  aggregation, joins, indexes, query plans, and more), shows the syntax, sets a
+  task, and checks your answer.
+- Lessons run in a separate practice store, so your data is never touched.
+- Press Enter to run a statement (`;` is optional). Tab gives a hint, Ctrl+L
+  picks a lesson from a list, Ctrl+N/Ctrl+P move between lessons, and `?`
+  explains everything; progress is saved between sessions.
+- `--plain` (or a window smaller than 60×20) uses a simple line-by-line shell
+  instead.
+- Advanced lessons cover joins, `ANY … SATISFIES`, indexes (including
+  mixed-direction composite indexes), query plans, `USE IDS`, and the system
+  collections.
+
+`dittosh dql bench` benchmarks DQL statements: it runs each one many times and
+reports mean, p50, p95, p99, min, max, and standard deviation.
+
+- `--runs <n>` sets the number of timed runs (default 50). `--warmup` runs the
+  statement untimed first, enough to fill about 250 ms, or `--warmup <n>` times.
+- `--pre`, `--before-each` (also `--reset`), and `--post` run statements once before timing, before
+  every run (untimed), and once afterwards (even after a failure). Use them to
+  create and drop indexes, or to put data back so every run of a write does the
+  same work.
+- `-f <file>` runs benchmarks from a JSON file, in the same format as Ditto's DQL
+  benchmark suites (`query`, `preQueries`, `resetQueries`, `postQueries`).
+  `--example <dataset>` writes a sample file to start from. See
+  `docs/benchmarking.md`.
+- `dittosh dql dataset run <query> --runs <n> --warmup` benchmarks a query from
+  a sample dataset's catalog.
+
+`dittosh doctor --report` writes one `.tar.gz` file to attach to a GitHub issue.
+
+- It holds versions, OS and terminal details, the health checks, paths and free
+  disk space, dittosh settings (credentials only as set/not set), a store summary
+  (collection names, document counts, indexes; no document contents), and the
+  last failed command with its error output.
+- It includes the Ditto SDK 5.2 support bundle: the SDK's debug logs and the
+  store configuration with secrets removed. `dittosh dql support-bundle` saves
+  just that bundle.
+- `--no-store` and `--no-sdk-bundle` leave parts out. The license token is never
+  included, and `report.md`/`report.json` show your home folder as `~`. The SDK
+  bundle is included as is: it holds the database ID, file paths, and peer keys.
+- `dittosh doctor` now works without `dql` (`dittosh dql doctor` still works).
+- `--debug` (or `DITTOSH_DEBUG=1`) on any command shows the SDK's debug logs and
+  stack traces on stderr; stdout is unchanged.
+- A bug-report issue template asks for the file. See `docs/troubleshooting.md`.
+
+The interactive `dittosh dql` shell has a new `.metrics` command that shows
+the SDK's live system metrics as formatted tables.
+
+- Store metrics: SQLite transactions, fsync, WAL size, commit and lock timings.
+- Query (DQL) metrics: requests, selects, failures, and parse, plan, and
+  execution times.
+- Totals run since the session opened; Change, p50/p90/p99, and Max cover the
+  time since the previous `.metrics`.
+- `.metrics store` or `.metrics query` narrows the view; `.metrics all` adds
+  network, sync, transport, and the other sections.
+
+## Improved
+
+`dittosh dql --profile` now shows everything in the SDK's profile:
+
+- per-operator `recv`, `send`, and `stor` (time blocked on storage) timings
+- scheduler yield counts by reason (`budget`, `sender`, `receiver`,
+  `heartbeat`), plus total storage time and total yields in the summary
+- skipped document counts
+- join subplans (`nlJoin` → `inner`) as nested trees
+- each operator's remaining attributes
+- the database ID, request type, feature flags, and directives
+
+## Changed
+
+- Updated the bundled Ditto Node SDK from 5.1.0 to 5.2.0. `dittosh version`
+  reports the new SDK version.
+- Updated vite, source-map-js, and vitest to patched versions. These are
+  build and test tools only; they are not part of the installed CLI.
+
+## Installation and updates
+
+```bash
+npm install -g @dittolive/cli@latest
+
+brew update && brew upgrade dittosh
+```
+
+Or run `dittosh update` to update through the detected package manager.
+
+Supported systems are unchanged: Apple Silicon macOS, Linux x64/arm64, and
+Windows x64 (npm). Intel Macs are not supported by the bundled Ditto SDK.
+npm installation requires Node.js 22 or newer; Homebrew manages Node.js 24.
diff --git a/scripts/spike-c.mjs b/scripts/spike-c.mjs
index 8baca9c..ccf7cb1 100644
--- a/scripts/spike-c.mjs
+++ b/scripts/spike-c.mjs
@@ -21,8 +21,9 @@ const ditto = await sdk.Ditto.open(
 );
 await ditto.setOfflineOnlyLicenseToken(token);
 
-// Seed some movies so the plan has real scans
-const docs = Array.from({ length: 200 }, (_, i) => ({
+// Seed enough movies that operators yield (SDK 5.1+ `#stats.yields`), plus a
+// small indexed `years` collection so a JOIN produces an `nlJoin.inner` subplan.
+const docs = Array.from({ length: 2000 }, (_, i) => ({
   _id: `m${i}`,
   title: i % 7 === 0 ? `Star Movie ${i}` : `Movie ${i}`,
   year: String(1950 + (i % 75)),
@@ -35,9 +36,17 @@ for (const d of docs) {
   });
 }
 
+for (let i = 0; i < 75; i++) {
+  await ditto.store.execute("INSERT INTO years DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE", {
+    doc: { _id: `y${i}`, year: String(1950 + i), label: `Year ${1950 + i}` },
+  });
+}
+await ditto.store.execute("CREATE INDEX IF NOT EXISTS years_year ON years (year)");
+
 const queries = [
   "PROFILE SELECT * FROM movies WHERE rated = 'PG'",
   "PROFILE SELECT * FROM movies WHERE year > '2000' AND rated = 'R' ORDER BY year DESC LIMIT 10",
+  "PROFILE SELECT m._id, y.label FROM movies m JOIN years y ON m.year = y.year WHERE m.rated = 'G' LIMIT 50",
 ];
 const out = [];
 for (const q of queries) {
@@ -60,7 +69,7 @@ fs.rmSync(storeDir, { recursive: true, force: true });
 
 const fixture = {
   capturedAt: new Date().toISOString(),
-  sdkVersion: "5.1.0",
+  sdkVersion: sdk.Ditto.VERSION,
   profiles: out,
   explain: explainItems[0] ?? null,
 };
diff --git a/src/bench/example.ts b/src/bench/example.ts
new file mode 100644
index 0000000..b761c20
--- /dev/null
+++ b/src/bench/example.ts
@@ -0,0 +1,89 @@
+import type { CatalogQuery, DatasetSuite } from "../datasets/types.js";
+
+/** One entry of a sample benchmark file, keys in the order they run. */
+export interface ExampleEntry {
+  description: string;
+  preQueries?: string[];
+  resetQueries?: string[];
+  query: string;
+  postQueries?: string[];
+}
+
+const WRITES = new Set(["INSERT", "UPSERT", "UPDATE", "DELETE", "EVICT"]);
+
+const DESCRIBE = {
+  read: 'A plain read. Only "query" is required: it is the statement that is timed.',
+  index:
+    "preQueries run once, before warmup and timing: here they create an index. postQueries run once at the end, even if something failed: here they drop the index so later benchmarks start from the same state.",
+  aggregate: "An aggregate over a whole collection: usually the slowest kind of read.",
+  join: "A join across two collections, with an index on the join field created in preQueries and dropped in postQueries.",
+  resetWrite:
+    "A write. resetQueries run before every warmup and timed run, untimed, to put the data back, so each run makes the same change. postQueries remove the test document at the end.",
+  repeatWrite:
+    "A write that is safe to repeat: preQueries add a test document once, every run updates it, and postQueries remove it at the end.",
+};
+
+/** The VALUES keyword reads better than DOCUMENTS (same meaning in DQL). */
+function preferValues(statement: string): string {
+  return statement.replace(/\b(INSERT\s+INTO\s+\S+\s+)DOCUMENTS(\s*\()/gi, "$1VALUES$2");
+}
+
+function entry(description: string, q: CatalogQuery): ExampleEntry {
+  const list = (xs?: string[]) => (xs && xs.length > 0 ? xs.map(preferValues) : undefined);
+  // Spread in run order so the JSON reads top to bottom as it executes.
+  const pre = list(q.preQueries);
+  const reset = list(q.resetQueries);
+  const post = list(q.postQueries);
+  return {
+    description,
+    ...(pre && { preQueries: pre }),
+    ...(reset && { resetQueries: reset }),
+    query: preferValues(q.query),
+    ...(post && { postQueries: post }),
+  };
+}
+
+/**
+ * A small sample benchmark file drawn from a dataset's query catalog: a
+ * plain read, an indexed read, an aggregate, a join (when the dataset has
+ * one), and a write that restores its own state, each with a description of
+ * what its parts do.
+ */
+export function exampleBenchFile(suite: DatasetSuite): Record<string, ExampleEntry> {
+  const candidates = Object.entries(suite.catalog).filter(
+    ([name, q]) => !q.negative && !suite.knownIssues?.[name],
+  );
+  const first = (test: (q: CatalogQuery) => boolean) => candidates.find(([, q]) => test(q));
+
+  const picks: [string, CatalogQuery, string][] = [];
+  const add = (found: [string, CatalogQuery] | undefined, description: string) => {
+    if (found && !picks.some(([n]) => n === found[0])) picks.push([...found, description]);
+  };
+
+  add(
+    first((q) => q.category === "SELECT"),
+    DESCRIBE.read,
+  );
+  add(
+    first((q) => /INDEX_SELECT$/.test(q.category) && (q.preQueries?.length ?? 0) > 0),
+    DESCRIBE.index,
+  );
+  add(
+    first((q) => q.category === "AGGREGATION"),
+    DESCRIBE.aggregate,
+  );
+  add(
+    first((q) => q.category === "JOIN_INNER"),
+    DESCRIBE.join,
+  );
+  const resetWrite = first((q) => WRITES.has(q.category) && (q.resetQueries?.length ?? 0) > 0);
+  if (resetWrite) add(resetWrite, DESCRIBE.resetWrite);
+  else {
+    add(
+      first((q) => q.category === "UPDATE" && (q.postQueries?.length ?? 0) > 0),
+      DESCRIBE.repeatWrite,
+    );
+  }
+
+  return Object.fromEntries(picks.map(([name, q, d]) => [name, entry(d, q)]));
+}
diff --git a/src/bench/runner.ts b/src/bench/runner.ts
new file mode 100644
index 0000000..ebdc103
--- /dev/null
+++ b/src/bench/runner.ts
@@ -0,0 +1,187 @@
+import type { QueryExecutor } from "../ditto/session.js";
+import { classify, firstKeyword } from "../query/execute.js";
+import type { BenchSpec } from "./spec.js";
+import { computeStats, decideWarmup, type Stats } from "./stats.js";
+
+/** Warmup iterations: a fixed count (0 = none), or "auto" to fill ~250 ms. */
+export type WarmupSetting = number | "auto";
+
+export interface BenchOptions {
+  runs: number;
+  warmup: WarmupSetting;
+  /** Progress notes (stderr, quiet-able). */
+  note?: (message: string) => void;
+  /** Warnings that change how to read the numbers (stderr, always shown). */
+  warn?: (message: string) => void;
+  /** Clock in ms (injectable for tests). */
+  now?: () => number;
+}
+
+export type BenchStage = "pre" | "warmup" | "reset" | "query" | "post";
+
+export interface BenchResult {
+  name: string;
+  ok: boolean;
+  /** Where it failed, and the statement and error that stopped it. */
+  failure?: { stage: BenchStage; statement: string; error: string };
+  /** postQueries that failed (the store may not be back to its starting state). */
+  cleanupFailures: { statement: string; error: string }[];
+  /** Completed timed runs and warmup iterations. */
+  runs: number;
+  warmup: number;
+  /** Rows returned by the last timed run. */
+  rows: number;
+  /** Timed run durations, in ms. */
+  samples: number[];
+  stats?: Stats;
+}
+
+class StageError extends Error {
+  constructor(
+    readonly stage: BenchStage,
+    readonly statement: string,
+    cause: unknown,
+  ) {
+    const e = cause as { message?: string; code?: string };
+    super(`${e.code ? `[${e.code}] ` : ""}${e.message ?? String(cause)}`);
+  }
+}
+
+async function exec(session: QueryExecutor, stage: BenchStage, statement: string) {
+  try {
+    return await session.execute(statement);
+  } catch (err) {
+    throw new StageError(stage, statement, err);
+  }
+}
+
+/**
+ * Time one benchmark, following the dql-metrics-benchmark runner:
+ *   preQueries once → warmup (untimed) → `runs` timed executions → postQueries.
+ * resetQueries run untimed before every warmup and timed execution, so a
+ * write measures a real mutation each time. postQueries always run, even
+ * after a failure, so indexes and fixtures don't leak into the next run.
+ */
+export async function runBenchmark(
+  session: QueryExecutor,
+  spec: BenchSpec,
+  opts: BenchOptions,
+): Promise<BenchResult> {
+  const now = opts.now ?? (() => performance.now());
+  const result: BenchResult = {
+    name: spec.name,
+    ok: false,
+    cleanupFailures: [],
+    runs: 0,
+    warmup: 0,
+    rows: 0,
+    samples: [],
+  };
+
+  // An UPDATE does the same work on every run; an INSERT, EVICT, or DELETE
+  // usually fails or finds nothing after the first unless the data is put back.
+  const executions = opts.runs + (opts.warmup === "auto" ? 1 : opts.warmup);
+  if (
+    classify(spec.query) === "mutation" &&
+    firstKeyword(spec.query) !== "UPDATE" &&
+    spec.resetQueries.length === 0 &&
+    executions > 1
+  ) {
+    opts.warn?.(
+      `${spec.name}: this write has no resetQueries, so runs after the first may change nothing (or fail). Put the data back before each run with resetQueries (--before-each on the command line).`,
+    );
+  }
+
+  const reset = async () => {
+    for (const s of spec.resetQueries) await exec(session, "reset", s);
+  };
+  const timed = async (stage: BenchStage) => {
+    await reset();
+    const started = now();
+    const r = await exec(session, stage, spec.query);
+    return { ms: now() - started, rows: r.items.length };
+  };
+
+  try {
+    for (const s of spec.preQueries) await exec(session, "pre", s);
+
+    if (opts.warmup === "auto") {
+      const pilot = await timed("warmup");
+      result.warmup = 1;
+      const target = decideWarmup(pilot.ms);
+      while (result.warmup < target) {
+        await timed("warmup");
+        result.warmup++;
+      }
+    } else {
+      while (result.warmup < opts.warmup) {
+        await timed("warmup");
+        result.warmup++;
+      }
+    }
+    if (result.warmup > 0) opts.note?.(`  ${spec.name}: ${result.warmup} warmup runs`);
+
+    for (let i = 0; i < opts.runs; i++) {
+      const r = await timed("query");
+      result.samples.push(r.ms);
+      result.rows = r.rows;
+      result.runs++;
+    }
+    result.ok = true;
+  } catch (err) {
+    if (!(err instanceof StageError)) throw err;
+    result.failure = { stage: err.stage, statement: err.statement, error: err.message };
+  } finally {
+    for (const s of spec.postQueries) {
+      try {
+        await session.execute(s);
+      } catch (err) {
+        result.cleanupFailures.push({ statement: s, error: (err as Error).message ?? String(err) });
+      }
+    }
+  }
+  if (result.cleanupFailures.length > 0) result.ok = false;
+  if (result.samples.length > 0) result.stats = computeStats(result.samples);
+  return result;
+}
+
+const ms = (n: number) => Number(n.toFixed(3));
+
+/**
+ * Result rows for rendering (table, JSON, CSV…). One requested run shows just
+ * its time; more show the distribution. The columns follow the requested
+ * `runs`, not the completed ones, so a failure doesn't change the shape.
+ */
+export function resultRows(results: BenchResult[], runs: number): Record<string, unknown>[] {
+  const anyFailed = results.some((r) => !r.ok);
+  const distribution = runs > 1;
+  return results.map((r) => {
+    const row: Record<string, unknown> = { benchmark: r.name };
+    if (anyFailed) {
+      row.status = r.failure
+        ? `failed (${r.failure.stage})`
+        : r.cleanupFailures.length > 0
+          ? "cleanup failed"
+          : "ok";
+    }
+    const s = r.stats;
+    if (!distribution) {
+      row.rows = r.rows;
+      row.time_ms = s ? ms(s.mean) : null;
+      return row;
+    }
+    Object.assign(row, {
+      runs: r.runs,
+      warmup: r.warmup,
+      rows: r.rows,
+      mean_ms: s ? ms(s.mean) : null,
+      p50_ms: s ? ms(s.p50) : null,
+      p95_ms: s ? ms(s.p95) : null,
+      p99_ms: s ? ms(s.p99) : null,
+      min_ms: s ? ms(s.min) : null,
+      max_ms: s ? ms(s.max) : null,
+      stddev_ms: s ? ms(s.stdDev) : null,
+    });
+    return row;
+  });
+}
diff --git a/src/bench/spec.ts b/src/bench/spec.ts
new file mode 100644
index 0000000..8f6cea4
--- /dev/null
+++ b/src/bench/spec.ts
@@ -0,0 +1,151 @@
+/**
+ * Benchmark definitions: what `dittosh dql bench` times, and the statements
+ * that set up and restore the store around it. The JSON file format is the
+ * one dql-metrics-benchmark uses for its suites (`benchmarks.json`), so a
+ * suite file from that repo runs here unchanged.
+ */
+export interface BenchSpec {
+  name: string;
+  /** The statement that is timed. */
+  query: string;
+  /** Run once, before warmup and the timed runs (e.g. CREATE INDEX). */
+  preQueries: string[];
+  /** Run before every warmup and timed run, untimed (restores state for writes). */
+  resetQueries: string[];
+  /** Run once at the end, even after a failure (e.g. DROP INDEX, EVICT fixtures). */
+  postQueries: string[];
+  description?: string;
+}
+
+export class BenchSpecError extends Error {
+  readonly exitCode = 2;
+  constructor(message: string) {
+    super(message);
+    this.name = "BenchSpecError";
+  }
+}
+
+const STATEMENT_LISTS = ["preQueries", "resetQueries", "postQueries"] as const;
+
+/** Keys the benchmark repo uses for its own tooling (oracles, labels); accepted and ignored. */
+const IGNORED_KEYS = new Set([
+  "category",
+  "qb",
+  "sql_equivalent",
+  "expected_count",
+  "expected_first_rows_hash",
+  "negative",
+  "expected_error_substring",
+]);
+
+const KNOWN_KEYS = ["name", "query", ...STATEMENT_LISTS, "description"];
+
+/** Trim, and drop one trailing `;` (each statement runs on its own). */
+export function cleanStatement(statement: string): string {
+  return statement.trim().replace(/;\s*$/, "").trim();
+}
+
+function suggestKey(key: string): string | undefined {
+  const flat = key.toLowerCase().replace(/[_-]/g, "");
+  return KNOWN_KEYS.find((k) => k.toLowerCase() === flat);
+}
+
+function statementList(value: unknown, where: string): string[] {
+  if (value === undefined) return [];
+  if (typeof value === "string") value = [value];
+  if (!Array.isArray(value)) throw new BenchSpecError(`${where} must be a list of statements`);
+  return value.map((s, i) => {
+    if (typeof s !== "string" || cleanStatement(s) === "") {
+      throw new BenchSpecError(`${where}[${i}] must be a non-empty statement string`);
+    }
+    return cleanStatement(s);
+  });
+}
+
+function parseEntry(raw: unknown, name: string, where: string, allowName: boolean): BenchSpec {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new BenchSpecError(`${where} must be an object with a "query"`);
+  }
+  const entry = raw as Record<string, unknown>;
+  for (const key of Object.keys(entry)) {
+    if (KNOWN_KEYS.includes(key) || IGNORED_KEYS.has(key)) continue;
+    const hint = suggestKey(key);
+    throw new BenchSpecError(
+      `${where} has an unknown key "${key}"${hint ? ` (did you mean "${hint}"?)` : ""}. Known keys: ${KNOWN_KEYS.join(", ")}`,
+    );
+  }
+  if (typeof entry.query !== "string" || cleanStatement(entry.query) === "") {
+    throw new BenchSpecError(`${where} needs a "query" string (the statement to time)`);
+  }
+  let finalName = name;
+  if (entry.name !== undefined) {
+    if (!allowName) {
+      throw new BenchSpecError(`${where}: "name" goes in the key of the entry, not inside it`);
+    }
+    if (typeof entry.name !== "string" || entry.name.trim() === "") {
+      throw new BenchSpecError(`${where}.name must be a non-empty string`);
+    }
+    finalName = entry.name.trim();
+  }
+  if (entry.description !== undefined && typeof entry.description !== "string") {
+    throw new BenchSpecError(`${where}.description must be a string`);
+  }
+  return {
+    name: finalName,
+    query: cleanStatement(entry.query),
+    preQueries: statementList(entry.preQueries, `${where}.preQueries`),
+    resetQueries: statementList(entry.resetQueries, `${where}.resetQueries`),
+    postQueries: statementList(entry.postQueries, `${where}.postQueries`),
+    description: entry.description as string | undefined,
+  };
+}
+
+/**
+ * Parse a benchmark file. Three shapes are accepted:
+ *  - a map of name → benchmark (the dql-metrics-benchmark `benchmarks.json` shape)
+ *  - a list of benchmarks, each with an optional "name"
+ *  - a single benchmark object (it has a top-level "query")
+ */
+export function parseBenchFile(text: string, label: string): BenchSpec[] {
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch (err) {
+    throw new BenchSpecError(`${label} isn't valid JSON: ${(err as Error).message}`);
+  }
+  let specs: BenchSpec[];
+  if (Array.isArray(data)) {
+    specs = data.map((entry, i) => parseEntry(entry, `benchmark_${i + 1}`, `${label}[${i}]`, true));
+  } else if (typeof data === "object" && data !== null) {
+    const obj = data as Record<string, unknown>;
+    if ("query" in obj) {
+      specs = [parseEntry(obj, "benchmark", label, true)];
+    } else {
+      specs = Object.entries(obj).map(([name, entry]) =>
+        parseEntry(entry, name, `${label}: "${name}"`, false),
+      );
+    }
+  } else {
+    throw new BenchSpecError(`${label} must hold a JSON object or list of benchmarks`);
+  }
+  if (specs.length === 0) throw new BenchSpecError(`${label} has no benchmarks`);
+  const seen = new Set<string>();
+  for (const s of specs) {
+    if (seen.has(s.name))
+      throw new BenchSpecError(`${label}: two benchmarks are named "${s.name}"`);
+    seen.add(s.name);
+  }
+  return specs;
+}
+
+/** Keep only the named benchmarks (in file order); unknown names are a usage error. */
+export function selectBenchmarks(specs: BenchSpec[], names: string[]): BenchSpec[] {
+  if (names.length === 0) return specs;
+  const missing = names.filter((n) => !specs.some((s) => s.name === n));
+  if (missing.length > 0) {
+    throw new BenchSpecError(
+      `No benchmark named ${missing.map((m) => `"${m}"`).join(", ")}. In this file: ${specs.map((s) => s.name).join(", ")}`,
+    );
+  }
+  return specs.filter((s) => names.includes(s.name));
+}
diff --git a/src/bench/stats.ts b/src/bench/stats.ts
new file mode 100644
index 0000000..ee78f33
--- /dev/null
+++ b/src/bench/stats.ts
@@ -0,0 +1,49 @@
+/**
+ * Timing statistics, computed the same way as the dql-metrics-benchmark
+ * runners (Kotlin `Stats.kt`, Rust `stats.rs`): population standard
+ * deviation, a true median for p50, and floor-indexed p95/p99. Matching them
+ * keeps numbers from `dittosh dql bench` comparable with benchmark sweeps.
+ */
+export interface Stats {
+  mean: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  min: number;
+  max: number;
+  stdDev: number;
+}
+
+export function computeStats(samples: readonly number[]): Stats {
+  if (samples.length === 0) throw new Error("computeStats needs at least one sample");
+  const sorted = [...samples].sort((a, b) => a - b);
+  const n = sorted.length;
+  const mean = sorted.reduce((sum, x) => sum + x, 0) / n;
+  const p50 = n % 2 === 0 ? (sorted[n / 2 - 1]! + sorted[n / 2]!) / 2 : sorted[(n - 1) / 2]!;
+  const variance = sorted.reduce((sum, x) => sum + (x - mean) ** 2, 0) / n;
+  return {
+    mean,
+    p50,
+    p95: sorted[Math.floor(n * 0.95)]!,
+    p99: sorted[Math.floor(n * 0.99)]!,
+    min: sorted[0]!,
+    max: sorted[n - 1]!,
+    stdDev: Math.sqrt(variance),
+  };
+}
+
+/** Adaptive warmup budget, as in the benchmark runners (and androidx.benchmark). */
+export const WARMUP_TARGET_MS = 250;
+export const WARMUP_MIN = 1;
+export const WARMUP_MAX = 1000;
+
+/**
+ * How many warmup iterations fill the budget, given one pilot run's time.
+ * A pilot that rounds to 0 ms counts as "very fast" (the cap); a negative
+ * time is treated as garbage (the floor).
+ */
+export function decideWarmup(pilotMs: number, targetMs = WARMUP_TARGET_MS): number {
+  if (pilotMs === 0) return WARMUP_MAX;
+  if (pilotMs < 0) return WARMUP_MIN;
+  return Math.min(WARMUP_MAX, Math.max(WARMUP_MIN, Math.ceil(targetMs / pilotMs)));
+}
diff --git a/src/cli/default-command.ts b/src/cli/default-command.ts
index 3f1c9ec..de0e48f 100644
--- a/src/cli/default-command.ts
+++ b/src/cli/default-command.ts
@@ -33,6 +33,8 @@ const DEFAULT_SUBCOMMANDS: Record<string, { exec: string; known: Set<string> }>
       "collections",
       "indexes",
       "dataset",
+      "bench",
+      "support-bundle",
       "delete-store",
       "import",
       "help",
@@ -44,7 +46,7 @@ const DEFAULT_SUBCOMMANDS: Record<string, { exec: string; known: Set<string> }>
 const DATASET_LEAVES = new Set(["list", "show", "load", "run", "reset"]);
 
 /** Global flags that may precede or follow the group token (boolean, no values). */
-const GLOBAL_FLAGS = new Set(["--no-color", "--quiet", "--no-update-check"]);
+const GLOBAL_FLAGS = new Set(["--no-color", "--quiet", "--no-update-check", "--debug"]);
 
 /** exec's value-taking flags (consume the next token); everything else is boolean or --flag=value. */
 const EXEC_VALUE_FLAGS = new Set([
diff --git a/src/cli/groups/doctor.ts b/src/cli/groups/doctor.ts
new file mode 100644
index 0000000..e805e9a
--- /dev/null
+++ b/src/cli/groups/doctor.ts
@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { configDir, expandTilde, resolveDataDir } from "../../config/paths.js";
+import type { Identity } from "../../identity/token.js";
+import { daysUntilExpiry, loadIdentity } from "../../identity/token.js";
+import { writeArchive } from "../../support/archive.js";
+import { readLastError } from "../../support/last-error.js";
+import { makeRedactor, secretEnvValues } from "../../support/redact.js";
+import {
+  collectReport,
+  describeContents,
+  formatBytes,
+  renderReport,
+  renderReportJson,
+  type StoreSession,
+} from "../../support/report.js";
+import { saveSupportBundle } from "../../support/sdk-bundle.js";
+import { detectChannel } from "../../update/channel.js";
+import { isNewer, readCachedUpdate } from "../../update/check.js";
+import { CLI_VERSION, DITTO_SDK_VERSION } from "../version.js";
+import { collectDoctorChecks, type DoctorCheck } from "./dql/doctor.js";
+
+export const ISSUE_URL = "https://github.com/getditto/ditto-cli/issues/new?template=bug_report.yml";
+
+/** Injectable pieces (tests replace the SDK-touching ones). */
+export interface DoctorDeps {
+  collectChecks: (opts: { dataDir?: string }) => Promise<DoctorCheck[]>;
+  openStore: (identity: Identity, dataDir: string) => Promise<StoreSession>;
+  channelDetail: () => string;
+  now: () => Date;
+}
+
+export const realDoctorDeps: DoctorDeps = {
+  collectChecks: (opts) => collectDoctorChecks(opts),
+  openStore: async (identity, dataDir) => {
+    const { DittoSession } = await import("../../ditto/session.js");
+    return DittoSession.open(identity, dataDir);
+  },
+  channelDetail: () => detectChannel().detail,
+  now: () => new Date(),
+};
+
+/** `dittosh-report-20261107-153012.tar.gz` (local time). */
+export function defaultReportName(d: Date): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `dittosh-report-${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}.tar.gz`;
+}
+
+interface DoctorOpts {
+  dataDir?: string;
+  report?: string | boolean;
+  store: boolean;
+  sdkBundle: boolean;
+}
+
+function versionFacts(deps: DoctorDeps): { facts: Record<string, string>; identity?: Identity } {
+  const facts: Record<string, string> = {
+    dittosh: CLI_VERSION,
+    "ditto sdk": DITTO_SDK_VERSION,
+  };
+  let identity: Identity | undefined;
+  try {
+    identity = loadIdentity();
+    facts.build = identity.source === "embedded" ? "release" : "dev (.env credentials)";
+    const days = daysUntilExpiry(identity.expiresOn);
+    facts["token expires"] = identity.expiresOn
+      ? `${identity.expiresOn}${days !== null ? ` (${days < 0 ? "expired" : `${days}d`})` : ""}`
+      : "unknown";
+  } catch (err) {
+    facts.build = "unknown";
+    facts["token expires"] = `unavailable: ${(err as Error).message.split("\n")[0]}`;
+  }
+  try {
+    facts.installed = deps.channelDetail();
+  } catch {
+    facts.installed = "unknown";
+  }
+  const cached = readCachedUpdate();
+  facts.update = cached
+    ? isNewer(CLI_VERSION, cached.latest)
+      ? `${cached.latest} available`
+      : "up to date"
+    : "never checked";
+  return { facts, ...(identity ? { identity } : {}) };
+}
+
+/** Write the report bundle; returns its path. Status lines go to stderr. */
+/** A bad `--report` path: a usage error (exit 2). */
+export class ReportPathError extends Error {
+  readonly exitCode = 2;
+}
+
+/**
+ * Where `--report` writes: the given file, the default name inside a given
+ * directory, or the default name in the current directory. Never overwrites.
+ */
+export function resolveReportPath(report: string | boolean | undefined, now: Date): string {
+  const given = typeof report === "string" && report.trim() ? report : undefined;
+  let out = path.resolve(expandTilde(given ?? defaultReportName(now)));
+  if (given && fs.existsSync(out) && fs.statSync(out).isDirectory()) {
+    out = path.join(out, defaultReportName(now));
+  }
+  if (fs.existsSync(out)) {
+    throw new ReportPathError(`${out} already exists; choose another name with --report <file>`);
+  }
+  return out;
+}
+
+export async function writeReport(
+  opts: DoctorOpts,
+  checks: DoctorCheck[],
+  deps: DoctorDeps,
+  out: string = resolveReportPath(opts.report, deps.now()),
+): Promise<string> {
+  const now = deps.now();
+  const dataDir = resolveDataDir(opts.dataDir);
+  const { facts, identity } = versionFacts(deps);
+  const redact = makeRedactor({
+    secrets: [identity?.token, ...secretEnvValues()],
+  });
+
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "dittosh-report-"));
+  try {
+    if (opts.store || opts.sdkBundle) {
+      console.error(chalk.dim("Collecting diagnostics (this can take a few seconds)…"));
+    }
+    const report = await collectReport({
+      dataDir,
+      configDir: configDir(),
+      includeStore: opts.store,
+      includeSdkBundle: opts.sdkBundle,
+      workDir: work,
+      checks,
+      environment: facts,
+      lastError: readLastError(),
+      openStore: () => {
+        if (!identity) throw new Error("no license token loaded");
+        return deps.openStore(identity, dataDir);
+      },
+      saveBundle: (session, file) =>
+        saveSupportBundle(session, file, {
+          source: "dittosh doctor --report",
+          dittosh: CLI_VERSION,
+        }),
+      now: () => now,
+    });
+    fs.writeFileSync(path.join(work, "report.md"), redact(renderReport(report)), "utf8");
+    fs.writeFileSync(path.join(work, "report.json"), renderReportJson(report, redact), "utf8");
+    const files = ["report.md", "report.json"];
+    if (report.sdkBundle.file) files.push(report.sdkBundle.file);
+    const folder = path.basename(out).replace(/\.tar\.gz$|\.tgz$/, "") || "dittosh-report";
+    const size = await writeArchive(out, work, folder, files);
+
+    const shown = redact(out);
+    console.error(chalk.green(`Wrote ${shown} (${formatBytes(size)})`));
+    console.error("It contains:");
+    for (const item of describeContents(report)) console.error(`  - ${item}`);
+    if (!report.sdkBundle.file)
+      console.error(chalk.dim(`  (no SDK support bundle: ${report.sdkBundle.detail})`));
+    console.error(`Look inside before sharing: tar -xzf ${JSON.stringify(shown)}`);
+    console.error(`Attach it to an issue: ${ISSUE_URL}`);
+    return out;
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Add doctor's options and action to `cmd` (used for `dittosh doctor` and `dittosh dql doctor`). */
+export function configureDoctorCommand(cmd: Command, deps: DoctorDeps = realDoctorDeps): Command {
+  return cmd
+    .description(
+      "Check platform, SDK, token, and data directory health; --report writes a file for bug reports",
+    )
+    .option("-d, --data-dir <path>", "override the data directory")
+    .option(
+      "--report [file]",
+      "also write a diagnostic bundle (.tar.gz) to attach to a GitHub issue (default: ./dittosh-report-<time>.tar.gz)",
+    )
+    .option("--no-store", "with --report: leave out collection names, counts, and indexes")
+    .option("--no-sdk-bundle", "with --report: leave out the Ditto SDK support bundle (SDK logs)")
+    .addHelpText(
+      "after",
+      `
+The report bundle holds versions, OS and terminal details, these checks, paths
+and free space, dittosh settings (credentials only as set/not set), a store
+summary (no document contents), the last failed command, and a Ditto SDK
+support bundle. In report.md and report.json your home folder is shown as ~.
+The SDK bundle is Ditto's own file, included as is: its logs and config hold
+the database ID, full file paths, and peer keys (--no-sdk-bundle leaves it out).
+The license token is never included.
+
+Examples:
+  dittosh doctor
+  dittosh doctor --report
+  dittosh doctor --report ~/Desktop/report.tar.gz --no-store
+  dittosh dql support-bundle          # only the Ditto SDK support bundle`,
+    )
+    .action(async (opts: DoctorOpts) => {
+      // A bad --report path is a usage error: report it before doing any work.
+      let out: string | undefined;
+      if (opts.report !== undefined) {
+        try {
+          out = resolveReportPath(opts.report, deps.now());
+        } catch (err) {
+          if (!(err instanceof ReportPathError)) throw err;
+          console.error(chalk.red(err.message));
+          process.exitCode = 2;
+          return;
+        }
+      }
+      const checks = await deps.collectChecks({ dataDir: opts.dataDir });
+      for (const c of checks) {
+        console.log(`${c.ok ? chalk.green("✓") : chalk.red("✗")} ${c.label} — ${c.detail}`);
+      }
+      const failures = checks.filter((c) => !c.ok).length;
+      // Spec: lock failures are their own exit code (4), everything else 3.
+      const lockFailed = checks.some((c) => c.label === "lock" && !c.ok);
+      process.exitCode = failures === 0 ? 0 : lockFailed ? 4 : 3;
+
+      if (out !== undefined) {
+        try {
+          await writeReport(opts, checks, deps, out);
+        } catch (err) {
+          console.error(chalk.red(`Could not write the report: ${(err as Error).message}`));
+          process.exitCode = 1;
+        }
+      }
+    });
+}
diff --git a/src/cli/groups/dql/bench.ts b/src/cli/groups/dql/bench.ts
new file mode 100644
index 0000000..c75c369
--- /dev/null
+++ b/src/cli/groups/dql/bench.ts
@@ -0,0 +1,315 @@
+import fs from "node:fs";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { exampleBenchFile } from "../../../bench/example.js";
+import {
+  type BenchResult,
+  resultRows,
+  runBenchmark,
+  type WarmupSetting,
+} from "../../../bench/runner.js";
+import {
+  type BenchSpec,
+  BenchSpecError,
+  cleanStatement,
+  parseBenchFile,
+  selectBenchmarks,
+} from "../../../bench/spec.js";
+import { expandTilde } from "../../../config/paths.js";
+import { DATASETS, getDataset } from "../../../datasets/registry.js";
+import type { DittoSession, QueryExecutor } from "../../../ditto/session.js";
+import { ParamError, parsePositiveInt } from "../../../query/params.js";
+import {
+  FormatError,
+  formatForOutFile,
+  type OutputFormat,
+  renderRows,
+  resolveFormat,
+} from "../../../render/output.js";
+import { note, validateOutPath } from "./run.js";
+
+export const MAX_RUNS = 10_000;
+
+export interface BenchDeps {
+  openSession: (opts: { dataDir?: string }) => Promise<DittoSession | null>;
+}
+
+/** `--runs <n>`: 1..10,000. */
+export function parseRuns(raw: string | undefined, fallback: number): number {
+  return parsePositiveInt(raw?.replace(/^=/, ""), "--runs", fallback, { max: MAX_RUNS });
+}
+
+/**
+ * `--warmup [n]`: bare (or `auto`) fills ~250 ms like the benchmark runners;
+ * a number is an exact count (0 = none). Undefined when the flag is absent.
+ */
+export function parseWarmup(raw: string | boolean | undefined): WarmupSetting | undefined {
+  if (raw === undefined || raw === false) return undefined;
+  if (raw === true) return "auto";
+  const v = raw.replace(/^=/, "").trim();
+  if (v === "auto") return "auto";
+  if (!/^\d+$/.test(v)) {
+    throw new ParamError(
+      `--warmup takes a number of runs or "auto", got "${raw}". (If that's your statement, put it before --warmup.)`,
+    );
+  }
+  return parsePositiveInt(v, "--warmup", 0, { min: 0, max: MAX_RUNS });
+}
+
+export interface BenchOutput {
+  format?: string;
+  out?: string;
+}
+
+/** Validate --format / -o before the store opens (usage beats lock). */
+export function resolveBenchOutput(o: BenchOutput): OutputFormat {
+  if (o.out) {
+    const err = validateOutPath(o.out);
+    if (err) throw new ParamError(err);
+    return formatForOutFile(o.out, o.format);
+  }
+  return resolveFormat(o.format);
+}
+
+function describeWarmup(w: WarmupSetting): string {
+  if (w === "auto") return "warmup to ~250 ms";
+  return w === 0 ? "no warmup" : `${w} warmup run${w === 1 ? "" : "s"}`;
+}
+
+/** Run benchmarks, print progress (stderr) and the results table (stdout or -o). */
+export async function runBenchmarks(
+  session: QueryExecutor,
+  specs: BenchSpec[],
+  opts: { runs: number; warmup: WarmupSetting; format: OutputFormat; out?: string },
+): Promise<{ ok: boolean; results: BenchResult[] }> {
+  const count = specs.length === 1 ? "1 benchmark" : `${specs.length} benchmarks`;
+  note(
+    `Benchmarking ${count}: ${opts.runs} timed run${opts.runs === 1 ? "" : "s"} each, ${describeWarmup(opts.warmup)}.`,
+  );
+  const results: BenchResult[] = [];
+  for (const spec of specs) {
+    note(`▸ ${spec.name}`);
+    const r = await runBenchmark(session, spec, {
+      runs: opts.runs,
+      warmup: opts.warmup,
+      note,
+      warn: (m) => console.error(chalk.yellow(`  ⚠ ${m}`)),
+    });
+    if (r.failure) {
+      console.error(chalk.red(`  ${spec.name} failed in ${r.failure.stage}: ${r.failure.error}`));
+      console.error(chalk.dim(`    in: ${r.failure.statement}`));
+    }
+    for (const c of r.cleanupFailures) {
+      console.error(chalk.red(`  cleanup failed: ${c.error}`));
+      console.error(chalk.dim(`    in: ${c.statement}`));
+    }
+    results.push(r);
+  }
+
+  const rows = resultRows(results, opts.runs);
+  if (opts.format === "json") process.env.DITTOSH_JSON_OUT = "1";
+  if (opts.out) {
+    const prev = chalk.level;
+    chalk.level = 0;
+    try {
+      fs.writeFileSync(expandTilde(opts.out), `${renderRows(rows, opts.format)}\n`, "utf8");
+    } catch (err) {
+      console.error(chalk.red(`Cannot write ${opts.out}: ${(err as Error).message}`));
+      return { ok: false, results };
+    } finally {
+      chalk.level = prev;
+    }
+    console.log(
+      `Wrote ${rows.length} benchmark result${rows.length === 1 ? "" : "s"} to ${opts.out} (${opts.format})`,
+    );
+  } else {
+    console.log(renderRows(rows, opts.format, { maxWidth: process.stdout.columns }));
+  }
+  if (opts.runs === 1 && results.some((r) => r.ok)) {
+    note("Use --runs <n> to time several runs and see p50/p95/p99.");
+  }
+  return { ok: results.every((r) => r.ok), results };
+}
+
+function collect(value: string, previous: string[] | undefined): string[] {
+  return [...(previous ?? []), value];
+}
+
+interface BenchCliOptions {
+  file?: string;
+  only?: string;
+  runs?: string;
+  warmup?: string | boolean;
+  pre?: string[];
+  reset?: string[];
+  post?: string[];
+  example?: string;
+  dataDir?: string;
+  out?: string;
+  format?: string;
+}
+
+function usage(message: string): void {
+  console.error(chalk.red(message));
+  process.exitCode = 2;
+}
+
+/** `--example <dataset>`: print or save a sample benchmark file. */
+function writeExample(name: string, opts: BenchCliOptions): void {
+  const suite = getDataset(name.replace(/^=/, ""));
+  if (!suite) {
+    usage(`Unknown dataset: ${name}. Available: ${DATASETS.map((d) => d.name).join(", ")}`);
+    return;
+  }
+  const text = `${JSON.stringify(exampleBenchFile(suite), null, 2)}\n`;
+  const out = opts.out?.replace(/^=/, "");
+  if (!out) {
+    process.stdout.write(text);
+    return;
+  }
+  const err = validateOutPath(out);
+  if (err) {
+    usage(err);
+    return;
+  }
+  fs.writeFileSync(expandTilde(out), text, "utf8");
+  console.log(`Wrote a sample benchmark file for ${suite.name} to ${out}`);
+  note(`Load the data:   dittosh dql dataset load ${suite.name}`);
+  note(`Run it:          dittosh dql bench -f ${out} --runs 50 --warmup`);
+}
+
+export function registerBenchCommand(dql: ReturnType<Command["command"]>, deps: BenchDeps): void {
+  dql
+    .command("bench")
+    .description("Time DQL statements: warmup, repeated runs, p50/p95/p99")
+    .argument("[statement]", "the statement to time (or use -f for a benchmark file)")
+    .option("-f, --file <path>", "JSON benchmark file (see --example for a sample)")
+    .option("--only <names>", "with -f: run only these benchmarks (comma-separated)")
+    .option("--runs <n>", "timed runs per benchmark (default 50)")
+    .option("--warmup [n]", "untimed runs before timing; with no number, enough to fill ~250 ms")
+    .option("--pre <statement>", "run once before timing, e.g. CREATE INDEX (repeatable)", collect)
+    .option(
+      "--before-each <statement>",
+      "run untimed before every run, e.g. re-insert what a write removes (repeatable)",
+    )
+    .option("--reset <statement>", "same as --before-each (resetQueries in a file)", collect)
+    .option("--post <statement>", "run once at the end, even after a failure (repeatable)", collect)
+    .option(
+      "--example <dataset>",
+      "print a sample benchmark file for a sample dataset (save it with -o)",
+    )
+    .option("-d, --data-dir <path>", "override the data directory")
+    .option("-o, --out <path>", "write the results to a file (format from extension or --format)")
+    .option("--format <format>", "table | json | csv | markdown | html | vertical")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  dittosh dql bench "SELECT * FROM movies WHERE rated = 'PG'" --runs 100 --warmup
+  dittosh dql bench "SELECT * FROM movies WHERE rated = 'PG'" \\
+    --pre "CREATE INDEX IF NOT EXISTS movies_rated ON movies (rated)" \\
+    --post "DROP INDEX IF EXISTS movies_rated ON movies"
+  dittosh dql bench "EVICT FROM movies WHERE _id = 'bench-doc'" \\
+    --before-each "INSERT INTO movies VALUES ({'_id': 'bench-doc'})"
+  dittosh dql bench --example retail -o retail-bench.json
+  dittosh dql bench -f retail-bench.json --runs 50 --warmup`,
+    )
+    .on("option:before-each", function (this: Command, value: string) {
+      this.setOptionValue("reset", collect(value, this.getOptionValue("reset")));
+    })
+    .action(async (statement: string | undefined, opts: BenchCliOptions) => {
+      if (opts.example !== undefined) {
+        if (statement || opts.file || opts.pre || opts.reset || opts.post) {
+          usage(
+            "--example only writes a sample file; leave out the statement, -f, and --pre/--before-each/--post.",
+          );
+          return;
+        }
+        writeExample(opts.example, opts);
+        return;
+      }
+
+      // `--warmup "SELECT …"`: the optional value swallowed the statement.
+      if (
+        !statement &&
+        typeof opts.warmup === "string" &&
+        !/^=?\s*(\d+|auto)\s*$/.test(opts.warmup)
+      ) {
+        statement = opts.warmup;
+        opts.warmup = true;
+      }
+      const file = opts.file?.replace(/^=/, "");
+      if (!statement && !file) {
+        usage(
+          "Give a statement to time, or -f <file>. For a sample file: dittosh dql bench --example <dataset>",
+        );
+        return;
+      }
+      if (statement && file) {
+        usage("Give either a statement or -f <file>, not both.");
+        return;
+      }
+      if (opts.only && !file) {
+        usage("--only picks benchmarks from a file; use it with -f.");
+        return;
+      }
+
+      let specs: BenchSpec[];
+      let runs: number;
+      let warmup: WarmupSetting;
+      let format: OutputFormat;
+      const out = opts.out?.replace(/^=/, "");
+      try {
+        runs = parseRuns(opts.runs, 50);
+        warmup = parseWarmup(opts.warmup) ?? 0;
+        format = resolveBenchOutput({ format: opts.format?.replace(/^=/, ""), out });
+        const pre = (opts.pre ?? []).map(cleanStatement).filter(Boolean);
+        const reset = (opts.reset ?? []).map(cleanStatement).filter(Boolean);
+        const post = (opts.post ?? []).map(cleanStatement).filter(Boolean);
+        if (file) {
+          let text: string;
+          try {
+            text = fs.readFileSync(expandTilde(file), "utf8");
+          } catch (err) {
+            throw new BenchSpecError(
+              `Cannot read ${file}: ${(err as NodeJS.ErrnoException).message}`,
+            );
+          }
+          const names = (opts.only ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+          specs = selectBenchmarks(parseBenchFile(text, file), names).map((s) => ({
+            ...s,
+            preQueries: [...pre, ...s.preQueries],
+            resetQueries: [...reset, ...s.resetQueries],
+            postQueries: [...s.postQueries, ...post],
+          }));
+        } else {
+          const query = cleanStatement(statement!);
+          if (!query) throw new BenchSpecError("The statement is empty.");
+          const name = query.length > 60 ? `${query.slice(0, 59)}…` : query;
+          specs = [{ name, query, preQueries: pre, resetQueries: reset, postQueries: post }];
+        }
+      } catch (err) {
+        if (
+          err instanceof ParamError ||
+          err instanceof FormatError ||
+          err instanceof BenchSpecError
+        ) {
+          usage(err.message);
+          return;
+        }
+        throw err;
+      }
+
+      const session = await deps.openSession({ dataDir: opts.dataDir });
+      if (!session) return;
+      try {
+        const { ok } = await runBenchmarks(session, specs, { runs, warmup, format, out });
+        if (!ok) process.exitCode = 1;
+      } finally {
+        await session.close();
+      }
+    });
+}
diff --git a/src/cli/groups/dql/dataset.ts b/src/cli/groups/dql/dataset.ts
index 8499cc4..4fac6a4 100644
--- a/src/cli/groups/dql/dataset.ts
+++ b/src/cli/groups/dql/dataset.ts
@@ -1,12 +1,19 @@
 import chalk from "chalk";
 import type { Command } from "commander";
+import type { WarmupSetting } from "../../../bench/runner.js";
 import { loadDataset } from "../../../datasets/loader.js";
 import { DATASETS, getDataset, resolveQuery } from "../../../datasets/registry.js";
-import type { DatasetSuite } from "../../../datasets/types.js";
+import type { CatalogQuery, DatasetSuite } from "../../../datasets/types.js";
 import type { DittoSession } from "../../../ditto/session.js";
 import { ParamError, parsePositiveInt } from "../../../query/params.js";
-import { FormatError, renderRows, resolveFormat } from "../../../render/output.js";
+import {
+  FormatError,
+  type OutputFormat,
+  renderRows,
+  resolveFormat,
+} from "../../../render/output.js";
 import { renderTable } from "../../../render/table.js";
+import { parseRuns, parseWarmup, resolveBenchOutput, runBenchmarks } from "./bench.js";
 import { note, runStatement, validateOutPath } from "./run.js";
 
 const WRITE_CATEGORIES = new Set(["INSERT", "UPDATE", "DELETE", "EVICT", "UPSERT"]);
@@ -28,6 +35,84 @@ function printQueryCatalog(suite: DatasetSuite): void {
   }
 }
 
+/**
+ * `dataset run --runs/--warmup`: benchmark a catalog query. Setup follows the
+ * plain `dataset run` rules: write queries always run their fixtures
+ * (preQueries/resetQueries) and cleanup (postQueries); read queries run their
+ * index DDL only with --setup and keep the index afterwards.
+ */
+async function benchCatalogQuery(
+  queryName: string,
+  suite: DatasetSuite,
+  entry: CatalogQuery,
+  opts: {
+    setup: boolean;
+    dataDir?: string;
+    out?: string;
+    format?: string;
+    time?: boolean;
+    explain?: boolean;
+    profile?: boolean;
+    runs?: string;
+    warmup?: string | boolean;
+  },
+  command: Command,
+  deps: DatasetDeps,
+): Promise<void> {
+  let runs: number;
+  let warmup: WarmupSetting;
+  let format: OutputFormat;
+  try {
+    if (opts.explain || opts.profile || opts.time) {
+      throw new ParamError(
+        "--explain, --profile, and --time don't combine with --runs/--warmup (the benchmark reports its own timings)",
+      );
+    }
+    if (command.getOptionValueSource("maxRows") === "cli") {
+      throw new ParamError(
+        "--max-rows doesn't apply with --runs/--warmup (benchmarks don't print rows)",
+      );
+    }
+    runs = parseRuns(opts.runs, 1);
+    warmup = parseWarmup(opts.warmup) ?? 0;
+    format = resolveBenchOutput({ format: opts.format, out: opts.out });
+  } catch (err) {
+    if (err instanceof ParamError || err instanceof FormatError) {
+      console.error(chalk.red(err.message));
+      process.exitCode = err.exitCode;
+      return;
+    }
+    throw err;
+  }
+
+  const isWrite = WRITE_CATEGORIES.has(entry.category);
+  note(`Running ${chalk.bold(queryName)} (${suite.name}):`);
+  note(chalk.cyan(`  ${entry.query}`));
+  const knownIssue = suite.knownIssues?.[queryName];
+  if (knownIssue) console.error(chalk.yellow(`  ⚠ known issue: ${knownIssue}`));
+
+  const session = await deps.openSession({ dataDir: opts.dataDir });
+  if (!session) return;
+  try {
+    const { ok } = await runBenchmarks(
+      session,
+      [
+        {
+          name: queryName,
+          query: entry.query,
+          preQueries: isWrite || opts.setup ? (entry.preQueries ?? []) : [],
+          resetQueries: entry.resetQueries ?? [],
+          postQueries: isWrite ? (entry.postQueries ?? []) : [],
+        },
+      ],
+      { runs, warmup, format, out: opts.out },
+    );
+    if (!ok) process.exitCode = 1;
+  } finally {
+    await session.close();
+  }
+}
+
 export function registerDatasetCommands(
   dql: ReturnType<Command["command"]>,
   deps: DatasetDeps,
@@ -183,6 +268,11 @@ export function registerDatasetCommands(
     .option("--time", "print timing after the results", false)
     .option("--explain", "run EXPLAIN on the query and print the plan", false)
     .option("--profile", "run PROFILE on the query and print the execution profile", false)
+    .option("--runs <n>", "benchmark it: time this many runs and show p50/p95/p99")
+    .option(
+      "--warmup [n]",
+      "benchmark it: untimed runs first; with no number, enough to fill ~250 ms",
+    )
     .action(
       async (
         queryName: string,
@@ -197,6 +287,8 @@ export function registerDatasetCommands(
           time?: boolean;
           explain?: boolean;
           profile?: boolean;
+          runs?: string;
+          warmup?: string | boolean;
         },
         command: Command,
       ) => {
@@ -237,6 +329,11 @@ export function registerDatasetCommands(
           return;
         }
 
+        if (opts.runs !== undefined || opts.warmup !== undefined) {
+          await benchCatalogQuery(queryName, suite, entry, opts, command, deps);
+          return;
+        }
+
         // Validate usage flags before the banner or the store (usage beats lock).
         let base: import("./run.js").RunOptions;
         try {
diff --git a/src/cli/groups/dql/doctor.ts b/src/cli/groups/dql/doctor.ts
index 3ac541b..8578637 100644
--- a/src/cli/groups/dql/doctor.ts
+++ b/src/cli/groups/dql/doctor.ts
@@ -11,7 +11,7 @@ export interface DoctorCheck {
   detail: string;
 }
 
-/** Native matrix of @dittolive/ditto@5.1.0 (verified from the npm tarball). */
+/** Native matrix of @dittolive/ditto@5.2.0 (verified from the npm tarball). */
 const SUPPORTED: Record<string, string[]> = {
   darwin: ["arm64"],
   linux: ["x64", "arm64"],
@@ -55,7 +55,7 @@ export async function collectDoctorChecks(opts: DoctorOptions = {}): Promise<Doc
     label: "platform",
     detail: platformOk
       ? `${platform}/${arch} supported`
-      : `${platform}/${arch} is not supported by the Ditto Node SDK 5.1.0 (supported: macOS arm64, Linux x64/arm64, Windows x64)`,
+      : `${platform}/${arch} is not supported by the Ditto Node SDK 5.2.0 (supported: macOS arm64, Linux x64/arm64, Windows x64)`,
   });
 
   const nodeMajor = Number(nodeVersion.split(".")[0]);
diff --git a/src/cli/groups/dql/index.ts b/src/cli/groups/dql/index.ts
index 7ed5167..27b3b2e 100644
--- a/src/cli/groups/dql/index.ts
+++ b/src/cli/groups/dql/index.ts
@@ -19,13 +19,15 @@ import {
 } from "../../../query/params.js";
 import { isBlankOrComments, splitComplete, splitStatements } from "../../../query/split.js";
 import { FormatError, resolveFormat } from "../../../render/output.js";
+import { configureDoctorCommand } from "../doctor.js";
 import { runBatch, stripDotCommandLines } from "./batch.js";
+import { registerBenchCommand } from "./bench.js";
 import { registerDatasetCommands } from "./dataset.js";
 import { deleteStore } from "./delete-store.js";
-import { collectDoctorChecks } from "./doctor.js";
 import { ImportError, importDocuments, isValidCollectionName, parseImportFile } from "./import.js";
 import { startRepl } from "./repl.js";
 import { note, runStatement, validateOutPath } from "./run.js";
+import { registerSupportBundleCommand } from "./support-bundle.js";
 
 interface ExecOpts {
   dataDir?: string;
@@ -49,7 +51,7 @@ interface ExecOpts {
 /** days until expiry at which the user gets a heads-up on every run. */
 const EXPIRY_NAG_DAYS = 14;
 
-async function openSession(opts: ExecOpts): Promise<DittoSession | null> {
+export async function openSession(opts: ExecOpts): Promise<DittoSession | null> {
   // Bogus data-dir values (commander artifacts like `-d --`) fail fast for
   // EVERY store-opening command. Mirror resolveDataDir's fallthrough: an
   // empty/whitespace flag means the env var wins — check the EFFECTIVE value.
@@ -149,21 +151,10 @@ export function registerDqlGroup(dql: ReturnType<Command["command"]>): void {
   dql.description("Run DQL statements against a local Ditto store");
 
   registerDatasetCommands(dql, { openSession });
+  registerBenchCommand(dql, { openSession });
 
-  dql
-    .command("doctor")
-    .description("Check platform, SDK, token, and data directory health")
-    .option("-d, --data-dir <path>", "override the data directory")
-    .action(async (opts: { dataDir?: string }) => {
-      const checks = await collectDoctorChecks(opts);
-      for (const c of checks) {
-        console.log(`${c.ok ? chalk.green("✓") : chalk.red("✗")} ${c.label} — ${c.detail}`);
-      }
-      const failures = checks.filter((c) => !c.ok).length;
-      // Spec: lock failures are their own exit code (4), everything else 3.
-      const lockFailed = checks.some((c) => c.label === "lock" && !c.ok);
-      process.exitCode = failures === 0 ? 0 : lockFailed ? 4 : 3;
-    });
+  configureDoctorCommand(dql.command("doctor"));
+  registerSupportBundleCommand(dql, { openSession });
 
   dql
     .command("collections")
diff --git a/src/cli/groups/dql/metrics.ts b/src/cli/groups/dql/metrics.ts
new file mode 100644
index 0000000..5f6dc07
--- /dev/null
+++ b/src/cli/groups/dql/metrics.ts
@@ -0,0 +1,79 @@
+import chalk from "chalk";
+import type { QueryExecutor } from "../../../ditto/session.js";
+import {
+  buildSections,
+  isExporterDisabled,
+  SECTION_IDS,
+  type SectionId,
+} from "../../../metrics/system-metrics.js";
+import { extractRows } from "../../../query/execute.js";
+import { renderMetrics } from "../../../render/metrics.js";
+
+export const METRICS_USAGE = `.metrics [store|query|all|${SECTION_IDS.filter((id) => id !== "store" && id !== "query").join("|")}]`;
+
+const DEFAULT_SECTIONS: readonly SectionId[] = ["store", "query"];
+
+/** Parse `.metrics` arguments into sections; undefined on an unknown word. */
+export function parseMetricsArgs(arg: string | undefined): readonly SectionId[] | undefined {
+  const words = (arg ?? "")
+    .trim()
+    .toLowerCase()
+    .split(/[\s,]+/)
+    .filter(Boolean);
+  if (words.length === 0) return DEFAULT_SECTIONS;
+  if (words.includes("all")) return SECTION_IDS;
+  const known = new Set<string>(SECTION_IDS);
+  if (!words.every((w) => known.has(w))) return undefined;
+  return SECTION_IDS.filter((id) => words.includes(id));
+}
+
+export interface MetricsCommandOptions {
+  /** Terminal width to fit (default: stdout columns on a TTY). */
+  maxWidth?: () => number | undefined;
+  now?: () => Date;
+}
+
+/**
+ * The REPL's `.metrics` command: reads `system:metrics` and renders the
+ * selected sections. Stateful only to know the first read of the session
+ * (each read flushes the SDK's deltas, so "Change" is since the last read).
+ */
+export function makeMetricsCommand(session: QueryExecutor, opts: MetricsCommandOptions = {}) {
+  let reads = 0;
+  const maxWidth =
+    opts.maxWidth ?? (() => (process.stdout.isTTY ? process.stdout.columns : undefined));
+
+  return async (arg?: string): Promise<{ ok: boolean; text: string }> => {
+    const sections = parseMetricsArgs(arg);
+    if (!sections) {
+      return {
+        ok: false,
+        text: chalk.red(`unknown metrics section: ${arg?.trim()}\nusage: ${METRICS_USAGE}`),
+      };
+    }
+    let rows: Record<string, unknown>[];
+    try {
+      rows = extractRows(await session.execute("SELECT * FROM system:metrics"));
+    } catch (err) {
+      return {
+        ok: false,
+        text: chalk.red(`Cannot read system metrics: ${(err as Error).message}`),
+      };
+    }
+    if (isExporterDisabled(rows)) {
+      return {
+        ok: false,
+        text: chalk.yellow(
+          "System metrics are disabled for this session (the SDK's metrics exporter was not enabled at startup).",
+        ),
+      };
+    }
+    const firstRead = reads === 0;
+    reads++;
+    const selected = buildSections(rows).filter((s) => sections.includes(s.id));
+    return {
+      ok: true,
+      text: renderMetrics(selected, { maxWidth: maxWidth(), firstRead, readAt: opts.now?.() }),
+    };
+  };
+}
diff --git a/src/cli/groups/dql/repl-core.ts b/src/cli/groups/dql/repl-core.ts
index 9b74d39..fc308b0 100644
--- a/src/cli/groups/dql/repl-core.ts
+++ b/src/cli/groups/dql/repl-core.ts
@@ -32,6 +32,8 @@ const DOT_HELP = `Available commands:
   .help                 show this help
   .collections          list collections (system:collections)
   .indexes [name]       list indexes (system:indexes), optionally for one collection
+  .metrics [section]    store + query (DQL) system metrics; sections: store, query,
+                        network, sync, transport, discovery, peer, other, or all
   .break / .clear       discard the current multi-line statement
   .exit                 quit (also: Ctrl-D, Ctrl-C)
 
diff --git a/src/cli/groups/dql/repl.ts b/src/cli/groups/dql/repl.ts
index 622fe75..d3be43e 100644
--- a/src/cli/groups/dql/repl.ts
+++ b/src/cli/groups/dql/repl.ts
@@ -4,6 +4,7 @@ import { start } from "node:repl";
 import chalk from "chalk";
 import { configDir } from "../../../config/paths.js";
 import type { QueryExecutor } from "../../../ditto/session.js";
+import { METRICS_USAGE, makeMetricsCommand } from "./metrics.js";
 import { dotHelp, makeReplEval } from "./repl-core.js";
 import { type RunOptions, runStatement } from "./run.js";
 
@@ -60,6 +61,17 @@ export async function startRepl(
     },
   });
 
+  const metrics = makeMetricsCommand(session);
+  server.defineCommand("metrics", {
+    help: `Show store and query (DQL) system metrics: ${METRICS_USAGE}`,
+    async action(arg?: string) {
+      const { ok, text } = await metrics(arg);
+      if (ok) console.log(text);
+      else console.error(text);
+      if (!isClosed()) server.displayPrompt();
+    },
+  });
+
   server.defineCommand("help", {
     help: "Show help",
     action() {
diff --git a/src/cli/groups/dql/support-bundle.ts b/src/cli/groups/dql/support-bundle.ts
new file mode 100644
index 0000000..a8293f1
--- /dev/null
+++ b/src/cli/groups/dql/support-bundle.ts
@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { expandTilde } from "../../../config/paths.js";
+import type { DittoSession } from "../../../ditto/session.js";
+import { FormatError, renderRows, resolveFormat } from "../../../render/output.js";
+import { formatBytes } from "../../../support/report.js";
+import {
+  bundleErrorMessage,
+  listSupportBundles,
+  saveSupportBundle,
+} from "../../../support/sdk-bundle.js";
+import { CLI_VERSION } from "../../version.js";
+import { note } from "./run.js";
+
+/** `ditto-support-bundle-20261107-153012.tar` (local time). */
+export function defaultBundleName(d: Date): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `ditto-support-bundle-${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}.tar`;
+}
+
+interface SupportBundleOpts {
+  dataDir?: string;
+  out?: string;
+  list?: boolean;
+  format?: string;
+}
+
+export function registerSupportBundleCommand(
+  dql: Command,
+  deps: {
+    openSession: (opts: { dataDir?: string }) => Promise<DittoSession | null>;
+    now?: () => Date;
+  },
+): void {
+  dql
+    .command("support-bundle")
+    .description("Save a Ditto SDK support bundle (SDK debug logs and config) for Ditto support")
+    .option("-d, --data-dir <path>", "override the data directory")
+    .option(
+      "-o, --out <file>",
+      "where to save the .tar (default: ./ditto-support-bundle-<time>.tar)",
+    )
+    .option("--list", "list the bundles kept in the store instead of making one")
+    .option("--format <fmt>", "with --list: table, json, csv, markdown, html, vertical")
+    .addHelpText(
+      "after",
+      `
+Ditto builds the bundle on this machine, offline: a .tar with the SDK's debug
+logs (ditto-logs.log.gz), their time range, and the store configuration with
+secrets removed. The logs include file paths and peer keys; look inside before
+sharing. Ditto allows 3 new bundles per 10 minutes per store; past that, the
+newest existing bundle is saved instead.
+
+For a GitHub issue, prefer: dittosh doctor --report (includes this bundle).`,
+    )
+    .action(async (opts: SupportBundleOpts) => {
+      let format: ReturnType<typeof resolveFormat> | undefined;
+      if (opts.list) {
+        try {
+          format = resolveFormat(opts.format?.replace(/^=/, ""));
+        } catch (err) {
+          if (!(err instanceof FormatError)) throw err;
+          console.error(chalk.red(err.message));
+          process.exitCode = 2;
+          return;
+        }
+      } else if (opts.format !== undefined) {
+        console.error(chalk.red("--format only applies with --list"));
+        process.exitCode = 2;
+        return;
+      }
+
+      const session = await deps.openSession(opts);
+      if (!session) return;
+      try {
+        if (opts.list) {
+          const rows = await listSupportBundles(session);
+          if (rows.length === 0) note("No support bundles in this store yet.");
+          else console.log(renderRows(rows, format!, { maxWidth: process.stdout.columns }));
+          return;
+        }
+        const now = (deps.now ?? (() => new Date()))();
+        const out = path.resolve(expandTilde(opts.out ?? defaultBundleName(now)));
+        if (fs.existsSync(out)) {
+          console.error(chalk.red(`${out} already exists; choose another name with -o`));
+          process.exitCode = 2;
+          return;
+        }
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        const saved = await saveSupportBundle(session, out, {
+          source: "dittosh dql support-bundle",
+          dittosh: CLI_VERSION,
+        });
+        if (saved.reusedBecause) {
+          console.error(
+            chalk.yellow(
+              `A new bundle wasn't allowed (${saved.reusedBecause}); saved the newest existing one.`,
+            ),
+          );
+        }
+        console.error(
+          chalk.green(`Saved ${out} (${formatBytes(saved.bytes)}, created ${saved.createdAt})`),
+        );
+        note(`Look inside: tar -tf ${JSON.stringify(out)}`);
+      } catch (err) {
+        console.error(chalk.red(`Could not save a support bundle: ${bundleErrorMessage(err)}`));
+        process.exitCode = 1;
+      } finally {
+        await session.close();
+      }
+    });
+}
diff --git a/src/cli/groups/tutorial-repl.ts b/src/cli/groups/tutorial-repl.ts
new file mode 100644
index 0000000..3098c60
--- /dev/null
+++ b/src/cli/groups/tutorial-repl.ts
@@ -0,0 +1,168 @@
+import path from "node:path";
+import { start } from "node:repl";
+import chalk from "chalk";
+import { configDir } from "../../config/paths.js";
+import { readState, writeState } from "../../config/state.js";
+import type { DittoSession } from "../../ditto/session.js";
+import { makeLessonEval } from "../../tutorial/lesson-eval.js";
+import { LEVELS, type Level } from "../../tutorial/lessons.js";
+import {
+  checkPracticeStore,
+  markPracticeStore,
+  practiceStoreDir,
+} from "../../tutorial/practice-store.js";
+import {
+  LessonRunner,
+  type LessonRunnerOptions,
+  lessonHelp,
+  type Progress,
+} from "../../tutorial/runner.js";
+import { MIN_COLUMNS, MIN_ROWS } from "../../tutorial/ui/limits.js";
+
+/** The lessons' own store, separate from the user's default data directory. */
+export function tutorialDataDir(): string {
+  return path.join(configDir(), "tutorial-store");
+}
+
+function readProgress(): Progress | undefined {
+  const p = readState().tutorialProgress as Progress | undefined;
+  return p && typeof p.lesson === "number" && Array.isArray(p.completed) ? p : undefined;
+}
+
+/**
+ * `dittosh tutorial --interactive`: the full-screen lessons (Ink, lazy-loaded),
+ * or the plain node:repl shell with --plain / in a small window. Logic lives in
+ * LessonRunner, lesson-eval, and tutorial/ui (unit-tested); this is wiring.
+ */
+export async function startTutorialShell(
+  openSession: (opts: { dataDir?: string }) => Promise<DittoSession | null>,
+  opts: { dataDir?: string; level?: string; plain?: boolean },
+): Promise<void> {
+  if (!process.stdin.isTTY) {
+    console.error(chalk.red("Interactive lessons need a terminal (stdin is not a TTY)."));
+    process.exitCode = 2;
+    return;
+  }
+  let level: Level | undefined;
+  if (opts.level !== undefined) {
+    const l = opts.level.toLowerCase() as Level;
+    if (!LEVELS.includes(l)) {
+      console.error(chalk.red(`--level must be one of ${LEVELS.join(", ")} — got "${opts.level}"`));
+      process.exitCode = 2;
+      return;
+    }
+    level = l;
+  }
+
+  const fullScreen = !opts.plain && canDrawFullScreen();
+  if (!opts.plain && !fullScreen) {
+    console.error(
+      chalk.dim(
+        `The window is small, so the lessons use the simple shell. At ${MIN_COLUMNS}×${MIN_ROWS} or larger you get the full-screen view.`,
+      ),
+    );
+  }
+
+  // The lessons reset their store's data; never let -d aim that at real data.
+  const dataDir = practiceStoreDir(opts.dataDir, tutorialDataDir());
+  const check = checkPracticeStore(dataDir, tutorialDataDir());
+  if (!check.ok) {
+    console.error(chalk.red(check.reason));
+    process.exitCode = 2;
+    return;
+  }
+
+  const session = await openSession({ dataDir });
+  if (!session) return;
+  markPracticeStore(dataDir);
+  try {
+    const saved = {
+      progress: readProgress(),
+      saveProgress: (p: Progress) => writeState({ tutorialProgress: p }),
+    };
+    let runner: LessonRunner;
+    if (fullScreen) {
+      // Loaded only here, so Ink and React cost nothing for every other command.
+      const { runLessonScreen } = await import("../../tutorial/ui/app.js");
+      runner = await runLessonScreen((io) => new LessonRunner(session, { io, ...saved }), {
+        level,
+      });
+    } else {
+      runner = await runPlainShell(session, saved, level);
+    }
+    console.error(
+      chalk.dim(
+        `Progress saved (${runner.completedCount}/${runner.lessons.length} lessons). Run dittosh tutorial --interactive to continue.`,
+      ),
+    );
+  } finally {
+    await session.close();
+  }
+}
+
+function canDrawFullScreen(): boolean {
+  const { columns = 0, rows = 0, isTTY } = process.stdout;
+  return (
+    Boolean(isTTY) && process.env.TERM !== "dumb" && columns >= MIN_COLUMNS && rows >= MIN_ROWS
+  );
+}
+
+/** The line-by-line lesson shell (node:repl): `--plain`, or a window too small for the full screen. */
+async function runPlainShell(
+  session: DittoSession,
+  saved: Pick<LessonRunnerOptions, "progress" | "saveProgress">,
+  level: Level | undefined,
+): Promise<LessonRunner> {
+  const runner = new LessonRunner(session, {
+    io: { print: (t) => console.log(t), width: () => process.stdout.columns },
+    ...saved,
+  });
+  await runner.start({ level });
+
+  const evaluator = makeLessonEval(runner);
+  const server = start({
+    prompt: chalk.cyan("learn> "),
+    ignoreUndefined: true,
+    eval: evaluator.eval,
+  });
+  const isClosed = () => (server as unknown as { closed: boolean }).closed === true;
+  const prompt = () => {
+    if (!isClosed()) server.displayPrompt();
+  };
+  // Actions queue behind any statement still running (see lesson-eval), and
+  // drain() below waits for them before the session closes.
+  const command = (name: string, help: string, action: (arg?: string) => unknown) => {
+    server.defineCommand(name, {
+      help,
+      async action(arg?: string) {
+        await evaluator.enqueue(() => action(arg));
+        prompt();
+      },
+    });
+  };
+
+  command("hint", "A nudge toward the answer", () => runner.hint());
+  command("answer", "Show one correct statement", () => runner.answer());
+  command("next", "Skip to the next lesson", () => runner.next());
+  command("back", "Go back one lesson", () => runner.back());
+  command("lessons", "List lessons by level", () => runner.list());
+  command("level", `Jump to a level: ${LEVELS.join(", ")}`, (a) => runner.level(a));
+  command("goto", "Jump to lesson n", (a) => runner.goto(a));
+  command("reset", "Restore the practice data", () => runner.reset());
+  command("schema", "Fields of this lesson's collections", () => runner.printSchema());
+  command("help", "How the lessons work, and the commands", () => console.log(lessonHelp()));
+  const resettable = () => {
+    evaluator.reset();
+    server.clearBufferedCommand();
+  };
+  command("break", "Discard the current multi-line statement", resettable);
+  command("clear", "Discard the current multi-line statement", resettable);
+  const unsupported = () => console.error(chalk.dim("not available in the lessons"));
+  command("editor", "Not available", unsupported);
+  command("load", "Not available", unsupported);
+  command("save", "Not available", unsupported);
+
+  await new Promise<void>((resolve) => server.on("exit", () => resolve()));
+  await evaluator.drain();
+  return runner;
+}
diff --git a/src/cli/groups/tutorial.ts b/src/cli/groups/tutorial.ts
new file mode 100644
index 0000000..3c6aed1
--- /dev/null
+++ b/src/cli/groups/tutorial.ts
@@ -0,0 +1,132 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { expandTilde } from "../../config/paths.js";
+import { renderTutorial, type TutorialContext } from "../../tutorial/content.js";
+import { detectChannel } from "../../update/channel.js";
+import { CLI_VERSION, DITTO_SDK_VERSION } from "../version.js";
+
+export const DEFAULT_TUTORIAL_FILE = "dittosh-tutorial.md";
+
+export interface TutorialDeps {
+  detectChannel: () => Pick<ReturnType<typeof detectChannel>, "channel">;
+  now: () => Date;
+  platform: string;
+  /** Launch the interactive DQL lessons (wired in by the CLI entry). */
+  startInteractive?: (opts: { dataDir?: string; level?: string; plain?: boolean }) => Promise<void>;
+}
+
+export const defaultTutorialDeps: TutorialDeps = {
+  detectChannel,
+  now: () => new Date(),
+  platform: `${process.platform}/${process.arch}`,
+};
+
+export function tutorialContext(deps: TutorialDeps): TutorialContext {
+  return {
+    cliVersion: CLI_VERSION,
+    sdkVersion: DITTO_SDK_VERSION,
+    channel: deps.detectChannel().channel,
+    platform: deps.platform,
+    generatedOn: deps.now().toISOString().slice(0, 10),
+  };
+}
+
+export interface WriteTutorialOptions {
+  out?: string;
+  stdout?: boolean;
+  force?: boolean;
+}
+
+/** Generate the Markdown tutorial to a file (default) or stdout. Returns the exit code. */
+export function writeTutorial(
+  opts: WriteTutorialOptions,
+  deps: TutorialDeps = defaultTutorialDeps,
+): number {
+  const markdown = renderTutorial(tutorialContext(deps));
+  if (opts.stdout) {
+    if (opts.out) {
+      console.error(chalk.red("--stdout and --out can't be used together"));
+      return 2;
+    }
+    process.stdout.write(markdown);
+    return 0;
+  }
+  const target = path.resolve(expandTilde(opts.out ?? DEFAULT_TUTORIAL_FILE));
+  if (fs.existsSync(target) && !opts.force) {
+    console.error(
+      chalk.red(`${target} already exists — pass --force to overwrite, or --out <file>`),
+    );
+    return 2;
+  }
+  try {
+    fs.writeFileSync(target, markdown, "utf8");
+  } catch (err) {
+    console.error(chalk.red(`Cannot write ${target}: ${(err as NodeJS.ErrnoException).message}`));
+    return 1;
+  }
+  console.error(`Wrote the tutorial to ${target}`);
+  console.error(
+    chalk.dim("Open it in a Markdown viewer and follow along in a terminal. Prefer learning DQL"),
+  );
+  console.error(chalk.dim("step by step? Run: dittosh tutorial --interactive"));
+  return 0;
+}
+
+export function registerTutorialCommand(
+  program: Command,
+  deps: TutorialDeps = defaultTutorialDeps,
+): void {
+  program
+    .command("tutorial")
+    .description(
+      "Generate a hands-on Markdown tutorial for this install, or learn DQL interactively (--interactive)",
+    )
+    .option("-o, --out <file>", `write the tutorial here (default: ./${DEFAULT_TUTORIAL_FILE})`)
+    .option("--stdout", "print the Markdown to stdout instead of writing a file", false)
+    .option("--force", "overwrite an existing file", false)
+    .option("-i, --interactive", "learn DQL with guided lessons in an interactive shell", false)
+    .option("--level <level>", "with --interactive: start at beginner, intermediate, or advanced")
+    .option(
+      "--plain",
+      "with --interactive: a simple line-by-line shell instead of the full-screen view",
+    )
+    .option(
+      "-d, --data-dir <path>",
+      "with --interactive: practice store (default: a separate store in the config dir)",
+    )
+    .action(
+      async (
+        opts: WriteTutorialOptions & {
+          interactive: boolean;
+          dataDir?: string;
+          level?: string;
+          plain?: boolean;
+        },
+      ) => {
+        if (opts.interactive) {
+          if (!deps.startInteractive) {
+            console.error(chalk.red("interactive lessons are unavailable in this build"));
+            process.exitCode = 1;
+            return;
+          }
+          await deps.startInteractive({
+            dataDir: opts.dataDir,
+            level: opts.level,
+            plain: opts.plain,
+          });
+          return;
+        }
+        if (opts.level || opts.dataDir || opts.plain) {
+          console.error(
+            chalk.red("--level, --data-dir, and --plain only apply with --interactive"),
+          );
+          process.exitCode = 2;
+          return;
+        }
+        const code = writeTutorial(opts, deps);
+        if (code !== 0) process.exitCode = code;
+      },
+    );
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 3f99ceb..92690e1 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -1,14 +1,22 @@
 import chalk from "chalk";
 import { Command, CommanderError } from "commander";
+import { sdkDebugLevel } from "../ditto/session.js";
+import { isDiagnosticCommand, recordLastError, startStderrTail } from "../support/last-error.js";
+import { makeRedactor, secretEnvValues } from "../support/redact.js";
 import { rewriteDefaultSubcommand } from "./default-command.js";
-import { registerDqlGroup } from "./groups/dql/index.js";
+import { configureDoctorCommand } from "./groups/doctor.js";
+import { openSession, registerDqlGroup } from "./groups/dql/index.js";
 import { registerSkillsGroup } from "./groups/skills/index.js";
 import { registerSystemGroup } from "./groups/system/index.js";
+import { defaultTutorialDeps, registerTutorialCommand } from "./groups/tutorial.js";
+import { startTutorialShell } from "./groups/tutorial-repl.js";
 import { installStdoutGuard } from "./streams.js";
 import { maybeShowUpdateBanner } from "./update-banner.js";
 import { CLI_VERSION } from "./version.js";
 
 installStdoutGuard(); // quiet exit(0) on EPIPE — `| head` is a first-class flow
+// Remember what a failing command printed, for `dittosh doctor --report`.
+const stderrTail = startStderrTail();
 
 const program = new Command();
 
@@ -24,7 +32,11 @@ program
   .version(CLI_VERSION)
   .option("--no-color", "disable colored output (also: NO_COLOR, CI, non-TTY)")
   .option("--quiet", "suppress informational notes on stderr")
-  .option("--no-update-check", "skip the update banner");
+  .option("--no-update-check", "skip the update banner")
+  .option(
+    "--debug",
+    "show Ditto SDK debug logs and stack traces on stderr (also: DITTOSH_DEBUG=1)",
+  );
 
 const dql = program.command("dql");
 registerDqlGroup(dql);
@@ -34,14 +46,23 @@ registerSkillsGroup(skills);
 
 registerSystemGroup(program);
 
+// `dittosh doctor` is the same command as `dittosh dql doctor`.
+configureDoctorCommand(program.command("doctor"));
+
+registerTutorialCommand(program, {
+  ...defaultTutorialDeps,
+  startInteractive: (opts) => startTutorialShell(openSession, opts),
+});
+
 // Global flags take effect before any subcommand action runs.
 program.hook("preSubcommand", () => {
   // NOTE: `--no-color` is a negation flag → commander sets opts.color === false.
   // chalk 5.x does NOT read NO_COLOR itself — honor it here. The SDK never sees
   // NO_COLOR (scrubbed before load — its native layer panics on it).
-  const opts = program.opts<{ color?: boolean; quiet?: boolean }>();
+  const opts = program.opts<{ color?: boolean; quiet?: boolean; debug?: boolean }>();
   if (opts.color === false || process.env.CI || "NO_COLOR" in process.env) chalk.level = 0;
   if (opts.quiet) process.env.DITTOSH_QUIET = "1";
+  if (opts.debug && !process.env.DITTOSH_DEBUG) process.env.DITTOSH_DEBUG = "1";
 });
 
 // After a successful command: the update banner (cached, non-blocking, stderr).
@@ -49,6 +70,7 @@ program.hook("preSubcommand", () => {
 // Skipped for system-group commands (version/update handle updates themselves)
 // and for help/version exits.
 let commandErrored = false;
+let errorStack: string | undefined;
 let usedSystemCommand = false;
 try {
   const argv = process.argv.slice(2);
@@ -65,10 +87,29 @@ try {
     process.exitCode = err.exitCode === 0 ? 0 : 2;
   } else {
     console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+    errorStack = err instanceof Error ? err.stack : undefined;
+    if (errorStack && sdkDebugLevel(process.env.DITTOSH_DEBUG))
+      console.error(chalk.dim(errorStack));
     process.exitCode = 1;
   }
 }
 
+// Save the failure (not usage errors or help) so `doctor --report` can show it.
+const argv = process.argv.slice(2);
+const exitCode = Number(process.exitCode ?? 0);
+if (exitCode !== 0 && exitCode !== 2 && !isDiagnosticCommand(argv)) {
+  const redact = makeRedactor({ secrets: secretEnvValues() });
+  recordLastError({
+    time: new Date().toISOString(),
+    version: CLI_VERSION,
+    command: argv.map(redact),
+    exitCode,
+    stderr: stderrTail.lines().map(redact),
+    ...(errorStack ? { stack: redact(errorStack) } : {}),
+  });
+}
+stderrTail.stop();
+
 if (!process.exitCode && !commandErrored && !usedSystemCommand) {
   await maybeShowUpdateBanner(CLI_VERSION, {
     // commander stores --no-update-check under the POSITIVE name (updateCheck === false)
diff --git a/src/ditto/session.ts b/src/ditto/session.ts
index b65db23..a26062f 100644
--- a/src/ditto/session.ts
+++ b/src/ditto/session.ts
@@ -77,6 +77,13 @@ async function loadSdk(): Promise<DittoSdk> {
   return sdkModule;
 }
 
+/** DITTOSH_DEBUG → SDK log level: unset/0/false → off, "verbose" → Verbose, anything else → Debug. */
+export function sdkDebugLevel(value: string | undefined): "Debug" | "Verbose" | null {
+  const v = value?.trim().toLowerCase();
+  if (!v || v === "0" || v === "false" || v === "off") return null;
+  return v === "verbose" ? "Verbose" : "Debug";
+}
+
 export class DittoSession {
   private constructor(private readonly ditto: sdk.Ditto) {}
 
@@ -96,12 +103,25 @@ export class DittoSession {
       // Known cosmetic issue: the native tracing bootstrap still writes 7
       // WARN/INFO lines to stderr at init (fd-level writes, not suppressible
       // from JS). stdout stays clean; piping is unaffected.
-      sdk.Logger.enabled = false;
+      // `--debug` / DITTOSH_DEBUG turns SDK logs on. The native logger writes
+      // to stderr, so stdout stays results-only.
+      const debug = sdkDebugLevel(process.env.DITTOSH_DEBUG);
+      sdk.Logger.enabled = debug !== null;
+      if (debug) sdk.Logger.minimumLogLevel = debug;
       await sdk.init();
       initialized = true;
     }
 
-    const config = new sdk.DittoConfig(identity.appId, { mode: "smallPeersOnly" }, dataDir);
+    // `metrics_exporter_virtual_collection_enabled` is startup-gated (runtime
+    // ALTER SYSTEM is ignored) and only accepted through the options-object
+    // constructor (SDK 5.2+). It backs the REPL's `.metrics` command via
+    // `SELECT * FROM system:metrics`; Info-level metrics are cheap.
+    const config = new sdk.DittoConfig({
+      databaseID: identity.appId,
+      connect: { mode: "smallPeersOnly" },
+      persistenceDirectory: dataDir,
+      systemParameters: { metrics_exporter_virtual_collection_enabled: true },
+    });
     let ditto: sdk.Ditto;
     try {
       ditto = await sdk.Ditto.open(config);
@@ -145,6 +165,36 @@ export class DittoSession {
     return this.ditto.store.execute(statement, args);
   }
 
+  /** Copy an attachment (e.g. a support bundle .tar) to a file. */
+  async saveAttachment(
+    token: { id: string; len: number | bigint; metadata: Record<string, string> },
+    filePath: string,
+    timeoutMs = 60_000,
+  ): Promise<void> {
+    // The fetch completes through a native callback that doesn't keep Node's
+    // event loop alive: without a pending timer, Node can exit mid-fetch (an
+    // "unsettled top-level await", then a native abort). The timeout timer
+    // holds the loop open and turns a stuck fetch into an error.
+    const fetcher = this.ditto.store.fetchAttachment(token);
+    let timer: NodeJS.Timeout | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`fetching attachment ${token.id} timed out`)),
+        timeoutMs,
+      );
+    });
+    try {
+      const attachment = await Promise.race([fetcher, timeout]);
+      if (!attachment) throw new Error(`attachment ${token.id} is not available on this device`);
+      await Promise.race([attachment.copyToPath(filePath), timeout]);
+    } catch (err) {
+      fetcher.stop();
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   async close(): Promise<void> {
     await this.ditto.close();
   }
diff --git a/src/metrics/system-metrics.ts b/src/metrics/system-metrics.ts
new file mode 100644
index 0000000..78421b4
--- /dev/null
+++ b/src/metrics/system-metrics.ts
@@ -0,0 +1,223 @@
+/**
+ * Parser for the SDK's `system:metrics` virtual collection (SDK 5.1+).
+ *
+ * Facts verified against SDK 5.2.0 (and the Ditto VS Code extension's
+ * SystemMetricsService):
+ *  - The exporter is startup-gated by the `metrics_exporter_virtual_collection_enabled`
+ *    system parameter (see DittoSession.open). When off, the collection
+ *    returns a single placeholder row `{ status: "disabled", description }`.
+ *  - Counter/gauge rows carry `current` (running value since SDK start) and
+ *    `delta` (change since the previous read).
+ *  - Histogram rows carry running `count`/`sum` and all-time `abs_max`, plus
+ *    `dcount`/`dsum` and window stats `p50/p90/p95/p99/min/max` that cover only
+ *    the samples since the previous read (absent when nothing new arrived).
+ *  - Every read flushes the deltas, so `delta` is "since the last read".
+ *  - A labelled metric is emitted as an unlabelled aggregate parent plus one
+ *    row per label set (e.g. `fsync_total` + `{db:"main"}` + `{db:"attachment"}`).
+ *  - Every `dql.*` series is a legacy alias of a `ditto.query.*` series.
+ */
+
+export type MetricKind = "counter" | "histogram";
+
+export interface MetricSeries {
+  key: string;
+  labels: Record<string, string>;
+  description: string;
+  /** `count`, `seconds`, `bytes`, … as reported by the SDK. */
+  unit: string;
+  kind: MetricKind;
+  /** Counter: `current`. Histogram: number of observations (`count`). */
+  total: number;
+  /** Change since the previous read. Counter: `delta`. Histogram: `dcount`. */
+  delta: number;
+  /** Histogram only: running sum and mean since the session opened. */
+  sum?: number;
+  avg?: number;
+  /** Histogram only: largest observation since the session opened (`abs_max`). */
+  peak?: number;
+  /** Histogram only: percentiles and max of the samples since the previous read. */
+  p50?: number;
+  p90?: number;
+  p99?: number;
+  max?: number;
+}
+
+/** One display row: an aggregate series and its labelled breakdown. */
+export interface MetricGroup {
+  key: string;
+  /** Unlabelled aggregate; absent for labelled-only metrics. */
+  series?: MetricSeries;
+  /** Labelled series, sorted by label text. */
+  children: MetricSeries[];
+}
+
+export interface MetricSection {
+  id: SectionId;
+  label: string;
+  counters: MetricGroup[];
+  histograms: MetricGroup[];
+}
+
+export type SectionId =
+  | "store"
+  | "query"
+  | "network"
+  | "sync"
+  | "transport"
+  | "discovery"
+  | "peer"
+  | "other";
+
+/** Section routing by key prefix (same topics as the VS Code extension). */
+const SECTION_PREFIXES: readonly (readonly [SectionId, string, readonly string[]])[] = [
+  [
+    "store",
+    "Store",
+    [
+      "ditto.backend.",
+      "ditto.store.",
+      "ditto.small_peer_info.",
+      "ditto.storage.",
+      "ditto.blob_storage.",
+      "ditto.blob_storage_tiered.",
+    ],
+  ],
+  ["query", "Query (DQL)", ["ditto.query.", "dql."]],
+  ["network", "Network", ["ditto.network."]],
+  [
+    "sync",
+    "Sync",
+    [
+      "ditto.sync.",
+      "ditto.replication.",
+      "ditto.diffcaster.",
+      "ditto.riblt.",
+      "ditto.presence.",
+      "ditto.stream.",
+    ],
+  ],
+  [
+    "transport",
+    "Transport",
+    [
+      "ditto.transport.",
+      "ditto.multiplexer.",
+      "ditto.multicast.",
+      "ditto.multicast_attachment.",
+      "ditto._tcp.",
+    ],
+  ],
+  ["discovery", "Discovery", ["ditto.discovery."]],
+  ["peer", "Peer", ["ditto.peer."]],
+];
+
+export const SECTION_IDS: readonly SectionId[] = [...SECTION_PREFIXES.map(([id]) => id), "other"];
+
+export function sectionOf(key: string): SectionId {
+  for (const [id, , prefixes] of SECTION_PREFIXES) {
+    if (prefixes.some((p) => key.startsWith(p))) return id;
+  }
+  return "other";
+}
+
+function sectionLabel(id: SectionId): string {
+  return SECTION_PREFIXES.find(([s]) => s === id)?.[1] ?? "Other";
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/** True when the exporter isn't installed: only the `{ status: "disabled" }` placeholder. */
+export function isExporterDisabled(rows: Record<string, unknown>[]): boolean {
+  return (
+    rows.length > 0 &&
+    rows.every((r) => typeof r.key !== "string") &&
+    rows.some((r) => r.status === "disabled")
+  );
+}
+
+/** Parse one row; undefined for placeholder/garbage rows. */
+export function parseMetricRow(row: Record<string, unknown>): MetricSeries | undefined {
+  if (typeof row.key !== "string" || row.key.length === 0) return undefined;
+  const labels: Record<string, string> = {};
+  if (row.labels && typeof row.labels === "object" && !Array.isArray(row.labels)) {
+    for (const [k, v] of Object.entries(row.labels as Record<string, unknown>)) {
+      if (typeof v === "string") labels[k] = v;
+    }
+  }
+  const base = {
+    key: row.key,
+    labels,
+    description: typeof row.description === "string" ? row.description : "",
+    unit: typeof row.unit === "string" ? row.unit : "",
+  };
+  const isHistogram = num(row.count) !== undefined || num(row.dcount) !== undefined;
+  if (!isHistogram) {
+    return { ...base, kind: "counter", total: num(row.current) ?? 0, delta: num(row.delta) ?? 0 };
+  }
+  const count = num(row.count) ?? 0;
+  const sum = num(row.sum);
+  return {
+    ...base,
+    kind: "histogram",
+    total: count,
+    delta: num(row.dcount) ?? 0,
+    ...(sum !== undefined ? { sum } : {}),
+    ...(sum !== undefined && count > 0 ? { avg: sum / count } : {}),
+    ...optional("peak", num(row.abs_max)),
+    ...optional("p50", num(row.p50)),
+    ...optional("p90", num(row.p90)),
+    ...optional("p99", num(row.p99)),
+    ...optional("max", num(row.max)),
+  };
+}
+
+function optional<K extends string>(k: K, v: number | undefined): Partial<Record<K, number>> {
+  return v === undefined ? {} : ({ [k]: v } as Record<K, number>);
+}
+
+export function labelText(labels: Record<string, string>): string {
+  return Object.keys(labels)
+    .sort()
+    .map((k) => `${k}=${labels[k]}`)
+    .join(" ");
+}
+
+/**
+ * Parse rows into sections (in SECTION_IDS order), dropping `dql.*` aliases
+ * of `ditto.query.*` series and grouping labelled children under their
+ * aggregate. Empty sections are omitted.
+ */
+export function buildSections(rows: Record<string, unknown>[]): MetricSection[] {
+  const series = rows.map(parseMetricRow).filter((s): s is MetricSeries => s !== undefined);
+  const keys = new Set(series.map((s) => s.key));
+  const deduped = series.filter(
+    (s) => !(s.key.startsWith("dql.") && keys.has(`ditto.query.${s.key.slice(4)}`)),
+  );
+
+  const groups = new Map<string, MetricGroup & { kind: MetricKind }>();
+  for (const s of deduped) {
+    let g = groups.get(s.key);
+    if (!g) {
+      g = { key: s.key, kind: s.kind, children: [] };
+      groups.set(s.key, g);
+    }
+    if (Object.keys(s.labels).length === 0) g.series = s;
+    else g.children.push(s);
+  }
+
+  const sections = new Map<SectionId, MetricSection>();
+  for (const g of [...groups.values()].sort((a, b) => a.key.localeCompare(b.key))) {
+    g.children.sort((a, b) => labelText(a.labels).localeCompare(labelText(b.labels)));
+    const id = sectionOf(g.key);
+    let section = sections.get(id);
+    if (!section) {
+      section = { id, label: sectionLabel(id), counters: [], histograms: [] };
+      sections.set(id, section);
+    }
+    const { kind, ...group } = g;
+    (kind === "histogram" ? section.histograms : section.counters).push(group);
+  }
+  return SECTION_IDS.flatMap((id) => sections.get(id) ?? []);
+}
diff --git a/src/profile/hotspots.ts b/src/profile/hotspots.ts
index 9f97179..6006249 100644
--- a/src/profile/hotspots.ts
+++ b/src/profile/hotspots.ts
@@ -1,15 +1,25 @@
 import { stripControlChars } from "../render/sanitize.js";
 import type { PlanNode } from "./parse.js";
 
-/** Sum of exec time over a node's subtree (ns). */
+/** A node's nested plans in render order: children, then labeled subplans. */
+function nested(node: PlanNode): { plan: PlanNode; label?: string }[] {
+  return [
+    ...node.children.map((plan) => ({ plan })),
+    ...(node.subplans ?? []).map(({ key, plan }) => ({ plan, label: key })),
+  ];
+}
+
+/** Sum of exec time over a node's subtree, including subplans (ns). */
 export function subtreeExecNs(node: PlanNode): number {
   const own = node.stats?.phaseTimes?.exec ?? 0;
-  return own + node.children.reduce((s, c) => s + subtreeExecNs(c), 0);
+  return own + nested(node).reduce((s, c) => s + subtreeExecNs(c.plan), 0);
 }
 
 export interface AnnotatedNode {
   node: PlanNode;
   depth: number;
+  /** Subplan key when this node roots a subplan (e.g. `inner` under `nlJoin`). */
+  label?: string;
   execNs: number;
   /** exec as a fraction of the whole plan's subtree exec (0–1). */
   fraction: number;
@@ -23,17 +33,18 @@ export const HOTSPOT_THRESHOLD = 0.5;
 export function annotatePlan(root: PlanNode): AnnotatedNode[] {
   const total = subtreeExecNs(root);
   const out: AnnotatedNode[] = [];
-  const walk = (node: PlanNode, depth: number) => {
+  const walk = (node: PlanNode, depth: number, label?: string) => {
     const execNs = node.stats?.phaseTimes?.exec ?? 0;
     const fraction = total > 0 ? execNs / total : 0;
     out.push({
       node,
       depth,
+      ...(label ? { label } : {}),
       execNs,
       fraction,
       isHotspot: fraction >= HOTSPOT_THRESHOLD && execNs > 0,
     });
-    for (const child of node.children) walk(child, depth + 1);
+    for (const c of nested(node)) walk(c.plan, depth + 1, c.label);
   };
   walk(root, 0);
   return out;
diff --git a/src/profile/parse.ts b/src/profile/parse.ts
index 123f28d..10fe8a2 100644
--- a/src/profile/parse.ts
+++ b/src/profile/parse.ts
@@ -2,7 +2,9 @@
  * Parser for the `~request_profile` envelope the Ditto SDK appends to result
  * sets of `PROFILE <SELECT>` statements. Tolerant by design — the envelope
  * shape is not a stable upstream contract (see spec risks). Field names
- * verified against SDK 5.1.0 (Spike C) and Edge Studio's parser.
+ * verified against SDK 5.1.0 (Spike C), re-verified on SDK 5.2.0 (which adds
+ * `stor` phase time, `yields` counters, `documentsSkipped`, and `nlJoin.inner`
+ * subplans), and kept in parity with the Ditto VS Code extension's parser.
  */
 
 export interface ProfileTimes {
@@ -12,16 +14,39 @@ export interface ProfileTimes {
   startIso?: string;
 }
 
+export interface PhaseTimes {
+  /** CPU time inside the operator. */
+  exec?: number;
+  /** Time waiting on upstream operators to feed input. */
+  recv?: number;
+  /** Time pushing output to downstream operators. */
+  send?: number;
+  /** Time blocked on the store backend (SDK 5.1+). */
+  stor?: number;
+}
+
+export interface PlanStats {
+  documentsIn?: number;
+  documentsOut?: number;
+  /** Documents skipped without being emitted (SDK 5.1+). */
+  documentsSkipped?: number;
+  phaseTimes?: PhaseTimes;
+  /**
+   * Cooperative-scheduler yield counts keyed by reason (`budget`, `sender`,
+   * `receiver`, `heartbeat`; SDK 5.1+). Zero counts are dropped; absent when
+   * nothing yielded. Unknown future reasons pass through.
+   */
+  yields?: Record<string, number>;
+}
+
 export interface PlanNode {
   name: string;
-  stats?: {
-    documentsIn?: number;
-    documentsOut?: number;
-    phaseTimes?: { exec?: number; recv?: number; send?: number };
-  };
-  /** Operator-specific attributes, insertion-ordered (skip #operator/#stats/children). */
+  stats?: PlanStats;
+  /** Operator-specific attributes, insertion-ordered (skip #operator/#stats/children/subplans). */
   attributes: [string, unknown][];
   children: PlanNode[];
+  /** Labeled nested plans carried in non-`children` fields, e.g. `nlJoin.inner` (SDK 5.1+). */
+  subplans?: { key: string; plan: PlanNode }[];
 }
 
 export interface QueryProfile {
@@ -33,6 +58,8 @@ export interface QueryProfile {
   state?: string;
   text?: string;
   featureFlags?: string;
+  /** Request directives, e.g. `{ "#profile": true }`. */
+  directives?: Record<string, unknown>;
   times: ProfileTimes;
   plan?: PlanNode;
 }
@@ -94,6 +121,7 @@ function parseEnvelope(env: Record<string, unknown>): QueryProfile {
     state: typeof env.state === "string" ? env.state : undefined,
     text: typeof env.text === "string" ? env.text : undefined,
     featureFlags: typeof env.featureFlags === "string" ? env.featureFlags : undefined,
+    directives: isRecord(env.directives) ? env.directives : undefined,
     times: {
       elapsedNs: ns(times.elapsed),
       parseNs: ns(times.parse),
@@ -107,35 +135,60 @@ function parseEnvelope(env: Record<string, unknown>): QueryProfile {
   };
 }
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isPlanNode(v: unknown): v is Record<string, unknown> {
+  return isRecord(v) && typeof v["#operator"] === "string";
+}
+
+/** Non-zero numeric yield counters, or undefined when none fired. */
+function parseYields(raw: unknown): Record<string, number> | undefined {
+  if (!isRecord(raw)) return undefined;
+  const out: Record<string, number> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    const n = ns(v);
+    if (n !== undefined && n !== 0) out[k] = n;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function parseStats(raw: unknown): PlanStats | undefined {
+  if (!isRecord(raw) || Object.keys(raw).length === 0) return undefined;
+  const phase = isRecord(raw.phaseTimes) ? raw.phaseTimes : undefined;
+  return {
+    documentsIn: ns(raw.documentsIn),
+    documentsOut: ns(raw.documentsOut),
+    documentsSkipped: ns(raw.documentsSkipped),
+    phaseTimes:
+      phase && Object.keys(phase).length > 0
+        ? { exec: ns(phase.exec), recv: ns(phase.recv), send: ns(phase.send), stor: ns(phase.stor) }
+        : undefined,
+    yields: parseYields(raw.yields),
+  };
+}
+
+const RESERVED = new Set(["#operator", "#stats", "children"]);
+
 function parsePlanNode(node: Record<string, unknown>): PlanNode {
-  const statsRaw = (node["#stats"] ?? {}) as Record<string, unknown>;
-  const phaseRaw = (statsRaw.phaseTimes ?? {}) as Record<string, unknown>;
   const children = Array.isArray(node.children)
-    ? (node.children as unknown[])
-        .filter((c): c is Record<string, unknown> => typeof c === "object" && c !== null)
-        .map((c) => parsePlanNode(c))
+    ? (node.children as unknown[]).filter(isRecord).map((c) => parsePlanNode(c))
     : [];
 
-  const stats =
-    Object.keys(statsRaw).length === 0
-      ? undefined
-      : {
-          documentsIn: ns(statsRaw.documentsIn),
-          documentsOut: ns(statsRaw.documentsOut),
-          phaseTimes:
-            Object.keys(phaseRaw).length === 0
-              ? undefined
-              : { exec: ns(phaseRaw.exec), recv: ns(phaseRaw.recv), send: ns(phaseRaw.send) },
-        };
-
-  const attributes: [string, unknown][] = Object.entries(node)
-    .filter(([k]) => k !== "#operator" && k !== "#stats" && k !== "children")
-    .map(([k, v]) => [k, v]);
+  const attributes: [string, unknown][] = [];
+  const subplans: { key: string; plan: PlanNode }[] = [];
+  for (const [k, v] of Object.entries(node)) {
+    if (RESERVED.has(k)) continue;
+    if (isPlanNode(v)) subplans.push({ key: k, plan: parsePlanNode(v) });
+    else attributes.push([k, v]);
+  }
 
   return {
     name: typeof node["#operator"] === "string" ? node["#operator"] : "unknown",
-    stats,
+    stats: parseStats(node["#stats"]),
     attributes,
     children,
+    ...(subplans.length > 0 ? { subplans } : {}),
   };
 }
diff --git a/src/query/execute.ts b/src/query/execute.ts
index cd89b07..462d775 100644
--- a/src/query/execute.ts
+++ b/src/query/execute.ts
@@ -30,10 +30,14 @@ function stripLeadingTrivia(s: string): string {
   }
 }
 
+/** The statement's first keyword, upper-cased (after comments and whitespace). */
+export function firstKeyword(statement: string): string | undefined {
+  return /^([a-zA-Z]+)/.exec(stripLeadingTrivia(statement))?.[1]?.toUpperCase();
+}
+
 /** Classify a DQL statement by its first meaningful keyword. */
 export function classify(statement: string): StatementKind {
-  const word = /^([a-zA-Z]+)/.exec(stripLeadingTrivia(statement))?.[1]?.toUpperCase();
-  switch (word) {
+  switch (firstKeyword(statement)) {
     case "SELECT":
       return "select";
     case "EXPLAIN":
diff --git a/src/render/metrics.ts b/src/render/metrics.ts
new file mode 100644
index 0000000..e732a97
--- /dev/null
+++ b/src/render/metrics.ts
@@ -0,0 +1,331 @@
+import chalk from "chalk";
+import stringWidth from "string-width";
+import {
+  labelText,
+  type MetricGroup,
+  type MetricSection,
+  type MetricSeries,
+} from "../metrics/system-metrics.js";
+import { stripControlChars } from "./sanitize.js";
+
+/** The metric-name column never shrinks below this when fitting the terminal. */
+const MIN_NAME_WIDTH = 24;
+
+const SINCE_OPEN = "since session opened";
+const SINCE_LAST = "since last .metrics";
+
+export interface RenderMetricsOptions {
+  /** Terminal width to fit; undefined = never truncate names. */
+  maxWidth?: number;
+  /** First read of the session: "since last .metrics" covers the whole session. */
+  firstRead?: boolean;
+  /** Wall-clock time of the read (header). */
+  readAt?: Date;
+}
+
+interface Column {
+  header: string;
+  /** Spanning header above contiguous columns sharing the same group. */
+  group?: string;
+}
+
+interface Row {
+  name: string;
+  /** namespace header · metric leaf · labelled breakdown */
+  kind: "ns" | "metric" | "child";
+  cells: string[];
+}
+
+interface Table {
+  title: string;
+  columns: Column[];
+  rows: Row[];
+}
+
+/**
+ * System metrics as boxed tables. Per section: a counters table (total since
+ * the session opened, change since the last read) and a timings table for
+ * histograms, whose two header groups keep the SDK's two windows apart —
+ * Count/Avg/Peak run since the session opened, while New/p50/p90/p99/Max
+ * cover only the samples since the previous read. Labelled breakdowns render
+ * as indented `└ label=value` rows under their aggregate. Every table shares
+ * one name-column width so the sections line up.
+ */
+export function renderMetrics(sections: MetricSection[], opts: RenderMetricsOptions = {}): string {
+  const out: string[] = [];
+  const readAt = (opts.readAt ?? new Date()).toLocaleTimeString("en-US", { hour12: false });
+  const names = sections.map((s) => s.label).join(", ") || "none";
+  out.push(`${chalk.bold("System metrics")} ${chalk.dim(`· ${names} · read ${readAt}`)}`);
+  if (opts.firstRead) {
+    out.push(chalk.dim(`first read this session — "${SINCE_LAST}" covers the whole session`));
+  }
+  if (sections.length === 0) {
+    out.push("", chalk.dim("(no metrics reported for this selection yet)"));
+    return out.join("\n");
+  }
+
+  const tables: Table[] = sections.flatMap((section) => [
+    ...(section.counters.length > 0 ? [counterTable(section)] : []),
+    ...(section.histograms.length > 0 ? [histogramTable(section)] : []),
+  ]);
+
+  const valueWidths = tables.map((t) => columnWidths(t).slice(1));
+  let nameWidth = Math.max(
+    ...tables.flatMap((t) => t.rows.map((r) => stringWidth(nameText(r)))),
+    6,
+  );
+  if (opts.maxWidth !== undefined) {
+    const room = Math.min(...valueWidths.map((w) => opts.maxWidth! - tableChrome(w)));
+    nameWidth = Math.max(MIN_NAME_WIDTH, Math.min(nameWidth, room));
+  }
+
+  tables.forEach((t, i) => {
+    out.push("", chalk.bold.cyan(t.title), box(t, [nameWidth, ...valueWidths[i]!]));
+  });
+
+  out.push(
+    "",
+    chalk.dim(
+      `Total, Count, Avg, Peak = ${SINCE_OPEN} · Change, New, p50–p99, Max = ${SINCE_LAST}`,
+    ),
+  );
+  return out.join("\n");
+}
+
+function counterTable(section: MetricSection): Table {
+  return {
+    title: `${section.label} · counters`,
+    columns: [
+      { header: "Metric" },
+      { header: "Total", group: SINCE_OPEN },
+      { header: "Change", group: SINCE_LAST },
+    ],
+    rows: groupRows(section.counters, (s) => [formatValue(s.total, s.unit), formatChange(s)]),
+  };
+}
+
+function histogramTable(section: MetricSection): Table {
+  const value = (s: MetricSeries, v: number | undefined) =>
+    v === undefined ? chalk.dim("—") : formatValue(v, s.unit);
+  return {
+    title: `${section.label} · timings & distributions`,
+    columns: [
+      { header: "Metric" },
+      { header: "Count", group: SINCE_OPEN },
+      { header: "Avg", group: SINCE_OPEN },
+      { header: "Peak", group: SINCE_OPEN },
+      { header: "New", group: SINCE_LAST },
+      { header: "p50", group: SINCE_LAST },
+      { header: "p90", group: SINCE_LAST },
+      { header: "p99", group: SINCE_LAST },
+      { header: "Max", group: SINCE_LAST },
+    ],
+    rows: groupRows(section.histograms, (s) => [
+      formatValue(s.total, "count"),
+      value(s, s.avg),
+      value(s, s.peak),
+      formatChange(s),
+      value(s, s.p50),
+      value(s, s.p90),
+      value(s, s.p99),
+      value(s, s.max),
+    ]),
+  };
+}
+
+/**
+ * Rows grouped by namespace: a `backend.sqlite3` header, then indented leaf
+ * metrics (`fsync_total`), then their labelled breakdowns (`└ db=main`).
+ */
+function groupRows(groups: MetricGroup[], cells: (s: MetricSeries) => string[]): Row[] {
+  const rows: Row[] = [];
+  let currentNs: string | undefined;
+  for (const g of groups) {
+    const first = g.series ?? g.children[0];
+    if (!first) continue;
+    const blank = cells(first).map(() => "");
+    const { ns, leaf } = splitKey(g.key);
+    if (ns !== currentNs) {
+      rows.push({ name: ns, kind: "ns", cells: blank });
+      currentNs = ns;
+    }
+    rows.push({ name: leaf, kind: "metric", cells: g.series ? cells(g.series) : blank });
+    for (const c of g.children) {
+      rows.push({
+        name: `└ ${stripControlChars(labelText(c.labels))}`,
+        kind: "child",
+        cells: cells(c),
+      });
+    }
+  }
+  return rows;
+}
+
+/** `ditto.backend.sqlite3.fsync_total` → ns `backend.sqlite3`, leaf `fsync_total`. */
+function splitKey(key: string): { ns: string; leaf: string } {
+  const name = stripControlChars(key.startsWith("ditto.") ? key.slice("ditto.".length) : key);
+  const dot = name.lastIndexOf(".");
+  return dot === -1
+    ? { ns: name, leaf: name }
+    : { ns: name.slice(0, dot), leaf: name.slice(dot + 1) };
+}
+
+function nameText(r: Row): string {
+  return (r.kind === "ns" ? "" : r.kind === "metric" ? "  " : "    ") + r.name;
+}
+
+/** Natural widths: each column fits its header, its rows, and its share of the group label. */
+function columnWidths(t: Table): number[] {
+  const widths = t.columns.map((c, i) =>
+    Math.max(
+      stringWidth(c.header),
+      ...t.rows.map((r) => stringWidth(i === 0 ? nameText(r) : (r.cells[i - 1] ?? ""))),
+    ),
+  );
+  // Widen the last column of a group until the spanning label fits.
+  for (const span of groupSpans(t.columns)) {
+    const inner = span.indexes.reduce((a, i) => a + widths[i]!, 0) + 3 * (span.indexes.length - 1);
+    const need = stringWidth(span.label) - inner;
+    const last = span.indexes[span.indexes.length - 1]!;
+    if (need > 0) widths[last]! += need;
+  }
+  return widths;
+}
+
+/** Border/padding columns around `valueWidths` plus the name column. */
+function tableChrome(valueWidths: number[]): number {
+  return valueWidths.reduce((a, b) => a + b, 0) + 3 * (valueWidths.length + 1) + 1;
+}
+
+function groupSpans(columns: Column[]): { label: string; indexes: number[] }[] {
+  const spans: { label: string; indexes: number[] }[] = [];
+  columns.forEach((c, i) => {
+    const prev = spans[spans.length - 1];
+    if (c.group && prev?.label === c.group && prev.indexes.at(-1) === i - 1) prev.indexes.push(i);
+    else if (c.group) spans.push({ label: c.group, indexes: [i] });
+  });
+  return spans;
+}
+
+function box(t: Table, widths: number[]): string {
+  const bar = chalk.dim("│");
+  const pad = (text: string, w: number, right: boolean) => {
+    const gap = Math.max(0, w - stringWidth(text));
+    return right ? " ".repeat(gap) + text : text + " ".repeat(gap);
+  };
+  const row = (cells: string[]) =>
+    `${bar} ${cells.map((c, i) => pad(c, widths[i]!, i > 0)).join(` ${bar} `)} ${bar}`;
+
+  // Group header: the name cell is blank; each span is centered over its columns.
+  const spans = groupSpans(t.columns);
+  const groupCells: string[] = [];
+  const joins: string[] = []; // separator after each emitted cell: "┬" between spans, "─" inside
+  let i = 0;
+  while (i < widths.length) {
+    const span = spans.find((s) => s.indexes[0] === i);
+    if (span) {
+      const w = span.indexes.reduce((a, j) => a + widths[j]!, 0) + 3 * (span.indexes.length - 1);
+      const label = span.label;
+      const left = Math.floor((w - stringWidth(label)) / 2);
+      groupCells.push(
+        chalk.dim(" ".repeat(left) + label + " ".repeat(w - left - stringWidth(label))),
+      );
+      i += span.indexes.length;
+    } else {
+      groupCells.push(" ".repeat(widths[i]!));
+      i++;
+    }
+    joins.push("┬");
+  }
+  const spanWidths: number[] = [];
+  i = 0;
+  while (i < widths.length) {
+    const span = spans.find((s) => s.indexes[0] === i);
+    const n = span ? span.indexes.length : 1;
+    spanWidths.push(widths.slice(i, i + n).reduce((a, b) => a + b, 0) + 3 * (n - 1));
+    i += n;
+  }
+
+  const out: string[] = [];
+  out.push(chalk.dim(`┌${spanWidths.map((w) => "─".repeat(w + 2)).join("┬")}┐`));
+  out.push(`${bar} ${groupCells.join(` ${bar} `)} ${bar}`);
+  // Under the group row: "┼" where a span boundary continues, "┬" where a span splits.
+  const boundaries = new Set<number>();
+  let acc = 0;
+  for (const w of spanWidths.slice(0, -1)) {
+    acc += w + 3;
+    boundaries.add(acc);
+  }
+  let mid = "├";
+  let pos = 0;
+  widths.forEach((w, j) => {
+    mid += "─".repeat(w + 2);
+    pos += w + 3;
+    if (j < widths.length - 1) mid += boundaries.has(pos) ? "┼" : "┬";
+  });
+  out.push(chalk.dim(`${mid}┤`));
+  out.push(row(t.columns.map((c) => chalk.bold(c.header))));
+  out.push(chalk.dim(`├${widths.map((w) => "─".repeat(w + 2)).join("┼")}┤`));
+  for (const r of t.rows) {
+    const name = ellipsize(nameText(r), widths[0]!);
+    const styled = r.kind === "ns" ? chalk.bold(name) : r.kind === "child" ? chalk.dim(name) : name;
+    out.push(row([styled, ...r.cells]));
+  }
+  out.push(chalk.dim(`└${widths.map((w) => "─".repeat(w + 2)).join("┴")}┘`));
+  return out.join("\n");
+}
+
+function ellipsize(s: string, w: number): string {
+  if (stringWidth(s) <= w) return s;
+  let out = "";
+  for (const ch of s) {
+    if (stringWidth(out + ch) > w - 1) break;
+    out += ch;
+  }
+  return `${out}…`;
+}
+
+function formatChange(s: MetricSeries): string {
+  if (s.delta === 0) return chalk.dim("0");
+  const unit = s.kind === "histogram" ? "count" : s.unit;
+  const value = formatValue(Math.abs(s.delta), unit);
+  return s.delta > 0 ? chalk.green(`+${value}`) : chalk.yellow(`−${value}`);
+}
+
+/** Unit-aware value: seconds → ns/µs/ms/s, bytes → B/KB/MB/GB, else grouped numbers. */
+export function formatValue(n: number, unit: string): string {
+  if (unit === "seconds") return formatSeconds(n);
+  if (unit === "bytes") return formatBytes(n);
+  if (Number.isInteger(n)) return n.toLocaleString("en-US");
+  const a = Math.abs(n);
+  if (a < 10) return n.toFixed(2);
+  return n.toLocaleString("en-US", { maximumFractionDigits: a < 100 ? 1 : 0 });
+}
+
+export function formatSeconds(s: number): string {
+  const a = Math.abs(s);
+  if (a === 0) return "0";
+  if (a < 1e-6) return `${(s * 1e9).toFixed(0)} ns`;
+  if (a < 1e-3) return `${sig3(s * 1e6)} µs`;
+  if (a < 1) return `${sig3(s * 1e3)} ms`;
+  return `${sig3(s)} s`;
+}
+
+/** Three significant digits: 148.6 → "149", 22.43 → "22.4", 1.094 → "1.09". */
+function sig3(v: number): string {
+  const a = Math.abs(v);
+  return v.toFixed(a >= 99.95 ? 0 : a >= 9.995 ? 1 : 2);
+}
+
+export function formatBytes(b: number): string {
+  const a = Math.abs(b);
+  if (a < 1024) return `${Math.round(b)} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = b / 1024;
+  let i = 0;
+  while (Math.abs(v) >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${sig3(v)} ${units[i]}`;
+}
diff --git a/src/render/profile.ts b/src/render/profile.ts
index b2513c8..be7d183 100644
--- a/src/render/profile.ts
+++ b/src/render/profile.ts
@@ -1,12 +1,18 @@
 import chalk from "chalk";
 import { formatNs, percentOfTotal } from "../profile/format.js";
-import { annotatePlan, keyAttribute } from "../profile/hotspots.js";
-import type { QueryProfile } from "../profile/parse.js";
+import { type AnnotatedNode, annotatePlan, keyAttribute } from "../profile/hotspots.js";
+import type { PlanNode, PlanStats, QueryProfile } from "../profile/parse.js";
+import { stripControlChars } from "./sanitize.js";
+
+/** Longest attribute value shown before truncating with "…". */
+const ATTR_MAX = 80;
 
 /**
  * Edge Studio's profile view, rendered for the terminal:
- * header (query + capture time) → summary strip → ASCII plan tree with
- * per-operator exec/pct + docs in/out and hotspot flags → legend.
+ * header (query + capture time + envelope metadata) → summary strip → ASCII
+ * plan tree with per-operator exec/pct + docs in/out/skipped and hotspot
+ * flags, each followed by dim detail lines (recv/send/stor times, yield
+ * counters, remaining operator attributes) → legend.
  */
 export function renderProfile(profile: QueryProfile, originalQuery: string): string {
   const lines: string[] = [];
@@ -15,9 +21,13 @@ export function renderProfile(profile: QueryProfile, originalQuery: string): str
   lines.push(
     chalk.dim(`captured ${profile.times.startIso ?? "unknown"} · profile ${profile.id ?? "n/a"}`),
   );
+  const meta = envelopeMeta(profile);
+  if (meta) lines.push(chalk.dim(meta));
   lines.push(chalk.cyan(`  ${originalQuery}`));
   lines.push("");
 
+  const annotated = profile.plan ? annotatePlan(profile.plan) : [];
+
   // Summary strip
   const cells: [string, string][] = [
     ["Elapsed", formatNs(profile.times.elapsedNs)],
@@ -27,24 +37,22 @@ export function renderProfile(profile: QueryProfile, originalQuery: string): str
   if (profile.resultCount !== undefined) cells.push(["Results", String(profile.resultCount)]);
   if (profile.queryType) cells.push(["Type", profile.queryType]);
   if (profile.state) cells.push(["State", profile.state]);
+  const storTotal = sum(annotated.map((n) => n.node.stats?.phaseTimes?.stor));
+  if (storTotal !== undefined) cells.push(["Stor", formatNs(storTotal)]);
+  const yieldTotal = sum(annotated.flatMap((n) => Object.values(n.node.stats?.yields ?? {})));
+  if (yieldTotal !== undefined) cells.push(["Yields", yieldTotal.toLocaleString("en-US")]);
   lines.push(cells.map(([label, value]) => `${chalk.dim(label)} ${chalk.bold(value)}`).join("   "));
   lines.push("");
 
   if (profile.plan) {
     lines.push(chalk.bold("Execution plan"));
-    const annotated = annotatePlan(profile.plan);
     const totalExec = annotated.reduce((s, n) => s + n.execNs, 0);
-    for (const { node, depth, execNs, isHotspot } of annotated) {
-      const indent = "  ".repeat(depth);
-      const branch = depth === 0 ? "" : "└─ ";
-      const name = chalk.bold(node.name);
-      const keyAttr = keyAttribute(node);
-      const exec = formatNs(execNs);
-      const pct = percentOfTotal(execNs, totalExec, 0.005) ?? "";
-      const docs = formatDocs(node.stats?.documentsIn, node.stats?.documentsOut);
-      const parts = [exec + (pct ? ` (${pct})` : ""), docs].filter(Boolean).join(" · ");
-      const line = `${indent}${branch}${name}${keyAttr ? ` ${chalk.dim(keyAttr)}` : ""}${parts ? ` — ${parts}` : ""}`;
-      lines.push(isHotspot ? chalk.bgYellow.black(` ▲ HOT ${line.trim()} `) : line);
+    for (const entry of annotated) {
+      lines.push(operatorLine(entry, totalExec));
+      const detailIndent = `${"  ".repeat(entry.depth)}${entry.depth === 0 ? "" : "   "}   `;
+      for (const detail of operatorDetails(entry.node)) {
+        lines.push(chalk.dim(`${detailIndent}${detail}`));
+      }
     }
     if (annotated.some((n) => n.isHotspot)) {
       lines.push("");
@@ -57,15 +65,85 @@ export function renderProfile(profile: QueryProfile, originalQuery: string): str
   lines.push("");
   lines.push(
     chalk.dim(
-      "legend: exec = CPU inside operator · recv = waiting upstream · send = pushing downstream · in/out = documents",
+      "legend: exec = CPU inside operator · recv = waiting upstream · send = pushing downstream · stor = blocked on storage",
+    ),
+  );
+  lines.push(
+    chalk.dim(
+      "        in/out/skipped = documents · yields = scheduler yields by reason (budget, sender, receiver, heartbeat) · inner = join subplan",
     ),
   );
   return lines.join("\n");
 }
 
-function formatDocs(docsIn?: number, docsOut?: number): string {
-  if (docsIn === undefined && docsOut === undefined) return "";
-  if (docsIn === undefined) return `${docsOut} out`;
-  if (docsOut === undefined) return `${docsIn} in`;
-  return `${docsIn} in / ${docsOut} out`;
+function operatorLine(entry: AnnotatedNode, totalExec: number): string {
+  const { node, depth, label, execNs, isHotspot } = entry;
+  const indent = "  ".repeat(depth);
+  const branch = depth === 0 ? "" : "└─ ";
+  const prefix = label ? `${chalk.magenta(`${stripControlChars(label)}:`)} ` : "";
+  const keyAttr = keyAttribute(node);
+  const pct = percentOfTotal(execNs, totalExec, 0.005) ?? "";
+  const docs = formatDocs(node.stats);
+  const parts = [formatNs(execNs) + (pct ? ` (${pct})` : ""), docs].filter(Boolean).join(" · ");
+  const line = `${indent}${branch}${prefix}${chalk.bold(node.name)}${keyAttr ? ` ${chalk.dim(keyAttr)}` : ""}${parts ? ` — ${parts}` : ""}`;
+  return isHotspot ? `${indent}${chalk.bgYellow.black(` ▲ HOT ${line.trim()} `)}` : line;
+}
+
+/** Dim lines under an operator: phase times, yields, then remaining attributes. */
+function operatorDetails(node: PlanNode): string[] {
+  const out: string[] = [];
+  const phase = node.stats?.phaseTimes;
+  const times = (["recv", "send", "stor"] as const)
+    .filter((k) => phase?.[k] !== undefined)
+    .map((k) => `${k} ${formatNs(phase?.[k])}`);
+  if (times.length > 0) out.push(times.join(" · "));
+
+  const yields = node.stats?.yields;
+  if (yields) {
+    const parts = Object.entries(yields)
+      .sort(([, a], [, b]) => b - a)
+      .map(([k, v]) => `${stripControlChars(k)} ${v.toLocaleString("en-US")}`);
+    out.push(`yields: ${parts.join(" · ")}`);
+  }
+
+  const shownKey = keyAttribute(node)?.split("=")[0];
+  const attrs = node.attributes
+    .filter(([k]) => k !== shownKey)
+    .map(([k, v]) => `${stripControlChars(k)}=${truncate(stripControlChars(attrValue(v)))}`);
+  if (attrs.length > 0) out.push(attrs.join(" "));
+  return out;
+}
+
+function attrValue(v: unknown): string {
+  return typeof v === "string" ? v : (JSON.stringify(v) ?? String(v));
+}
+
+function truncate(s: string): string {
+  return s.length > ATTR_MAX ? `${s.slice(0, ATTR_MAX - 1)}…` : s;
+}
+
+/** Header line for the rest of the envelope: db, request type, flags, directives. */
+function envelopeMeta(profile: QueryProfile): string | undefined {
+  const parts: string[] = [];
+  if (profile.appId) parts.push(`db ${profile.appId}`);
+  if (profile.requestType) parts.push(`request ${profile.requestType}`);
+  if (profile.featureFlags) parts.push(`flags ${profile.featureFlags}`);
+  const directives = Object.entries(profile.directives ?? {}).map(([k, v]) =>
+    v === true ? k : `${k}=${attrValue(v)}`,
+  );
+  if (directives.length > 0) parts.push(`directives ${directives.join(", ")}`);
+  return parts.length > 0 ? stripControlChars(parts.join(" · ")) : undefined;
+}
+
+function sum(values: (number | undefined)[]): number | undefined {
+  const present = values.filter((v): v is number => v !== undefined);
+  return present.length > 0 ? present.reduce((a, b) => a + b, 0) : undefined;
+}
+
+function formatDocs(stats?: PlanStats): string {
+  const parts: string[] = [];
+  if (stats?.documentsIn !== undefined) parts.push(`${stats.documentsIn} in`);
+  if (stats?.documentsOut !== undefined) parts.push(`${stats.documentsOut} out`);
+  if (stats?.documentsSkipped) parts.push(`${stats.documentsSkipped} skipped`);
+  return parts.join(" / ");
 }
diff --git a/src/support/archive.ts b/src/support/archive.ts
new file mode 100644
index 0000000..846299a
--- /dev/null
+++ b/src/support/archive.ts
@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as tar from "tar";
+
+/**
+ * Write `files` (names relative to `dir`) into a gzipped tar at `outFile`.
+ * Entries sit under one top folder (`folder/…`) so extracting doesn't
+ * scatter files into the current directory.
+ */
+export async function writeArchive(
+  outFile: string,
+  dir: string,
+  folder: string,
+  files: string[],
+): Promise<number> {
+  // tar adds paths as given relative to cwd: stage them under `folder`, in
+  // a directory of its own so `folder` can't clash with a staged file name
+  // (e.g. `--report report.md`).
+  const root = fs.mkdtempSync(path.join(dir, "stage-"));
+  const stage = path.join(root, folder);
+  fs.mkdirSync(stage, { recursive: true });
+  for (const f of files) fs.renameSync(path.join(dir, f), path.join(stage, f));
+  fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true });
+  await tar.c({ gzip: true, file: outFile, cwd: root, portable: true }, [folder]);
+  return fs.statSync(outFile).size;
+}
diff --git a/src/support/last-error.ts b/src/support/last-error.ts
new file mode 100644
index 0000000..a86153f
--- /dev/null
+++ b/src/support/last-error.ts
@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { configDir } from "../config/paths.js";
+
+/** The most recent failed command, saved so `doctor --report` can include it. */
+export interface LastError {
+  time: string;
+  version: string;
+  /** Arguments after `dittosh`, redacted. */
+  command: string[];
+  exitCode: number;
+  /** The last lines the command wrote to stderr (colors stripped, redacted). */
+  stderr: string[];
+  /** Stack trace of an unexpected error, when there was one. */
+  stack?: string;
+}
+
+export const LAST_ERROR_FILE = "last-error.json";
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escapes is the point
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+export interface StderrTail {
+  lines(): string[];
+  stop(): void;
+}
+
+/**
+ * Keep the last `max` lines written to stderr, passing every write through
+ * unchanged. Lets a failure be saved with the message the user saw.
+ */
+export function startStderrTail(stream: NodeJS.WriteStream = process.stderr, max = 60): StderrTail {
+  const kept: string[] = [];
+  let partial = "";
+  const original = stream.write;
+  const push = (chunk: unknown) => {
+    const text =
+      typeof chunk === "string" ? chunk : Buffer.isBuffer(chunk) ? chunk.toString("utf8") : "";
+    const parts = (partial + text.replace(ANSI, "")).split(/\r?\n/);
+    partial = parts.pop() ?? "";
+    for (const line of parts) {
+      kept.push(line);
+      if (kept.length > max) kept.shift();
+    }
+  };
+  stream.write = function (this: NodeJS.WriteStream, chunk: unknown, ...rest: unknown[]) {
+    try {
+      push(chunk);
+    } catch {
+      // never let capture break output
+    }
+    return (original as (...a: unknown[]) => boolean).call(this, chunk, ...rest);
+  } as typeof stream.write;
+  return {
+    lines: () => {
+      const all = partial ? [...kept, partial] : [...kept];
+      return all.slice(-max);
+    },
+    stop: () => {
+      stream.write = original;
+    },
+  };
+}
+
+/** Best-effort: a read-only config dir must never turn into a second failure. */
+export function recordLastError(entry: LastError, dir: string = configDir()): void {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, LAST_ERROR_FILE);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(entry, null, 2)}\n`, "utf8");
+    fs.renameSync(tmp, file);
+  } catch {
+    // ignore
+  }
+}
+
+export function readLastError(dir: string = configDir()): LastError | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(dir, LAST_ERROR_FILE), "utf8")) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    const e = parsed as Partial<LastError>;
+    if (typeof e.time !== "string" || !Array.isArray(e.command)) return null;
+    return {
+      time: e.time,
+      version: String(e.version ?? "unknown"),
+      command: e.command.map(String),
+      exitCode: Number(e.exitCode ?? 1),
+      stderr: Array.isArray(e.stderr) ? e.stderr.map(String) : [],
+      ...(typeof e.stack === "string" ? { stack: e.stack } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Commands whose own failures shouldn't replace the error being diagnosed. */
+export function isDiagnosticCommand(argv: string[]): boolean {
+  return argv.some((a) => a === "doctor" || a === "support-bundle");
+}
diff --git a/src/support/redact.ts b/src/support/redact.ts
new file mode 100644
index 0000000..9660709
--- /dev/null
+++ b/src/support/redact.ts
@@ -0,0 +1,60 @@
+import os from "node:os";
+
+export interface RedactOptions {
+  /** Home directory shown as `~` (default: os.homedir()). */
+  home?: string;
+  /** Values never written to a report (tokens, license strings). */
+  secrets?: (string | undefined)[];
+}
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Build a redactor for diagnostic text: secrets → `[redacted]`, the home
+ * directory → `~`. Short secrets (< 8 chars) are skipped: replacing them
+ * would mangle ordinary words without protecting anything.
+ */
+export function makeRedactor(opts: RedactOptions = {}): (text: string) => string {
+  const home = opts.home ?? os.homedir();
+  const secrets = [
+    ...new Set((opts.secrets ?? []).filter((s): s is string => !!s && s.length >= 8)),
+  ]
+    // Longest first, so a secret that contains another is replaced whole.
+    .sort((a, b) => b.length - a.length);
+  const secretRe = secrets.length > 0 ? new RegExp(secrets.map(escapeRe).join("|"), "g") : null;
+  // Only a whole path component: `/Users/al` must not touch `/Users/alex`.
+  const homeRe =
+    home && home.length > 1 ? new RegExp(`${escapeRe(home)}(?=$|[\\\\/"'\\s:)])`, "g") : null;
+  return (text) => {
+    let out = text;
+    if (secretRe) out = out.replace(secretRe, "[redacted]");
+    if (homeRe) out = out.replace(homeRe, "~");
+    return out;
+  };
+}
+
+/** Env vars whose values are credentials: reports say only whether they're set. */
+export const SECRET_ENV = [
+  "OFFLINE_TOKEN",
+  "DQL_OFFLINE_LICENSE",
+  "DATABASE_ID",
+  "DITTO_APP_ID",
+  "DITTOSH_GITHUB_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+];
+
+/** Names that look like credentials (e.g. a future DITTOSH_*_TOKEN), hidden too. */
+const SECRET_NAME = /TOKEN|SECRET|PASSWORD|PASSWD|LICENSE|CREDENTIAL|API_?KEY|PRIVATE_?KEY|AUTH/i;
+
+/** True for an env var whose value must never appear in a report. */
+export function isSecretEnv(name: string): boolean {
+  return SECRET_ENV.includes(name) || SECRET_NAME.test(name);
+}
+
+/** Values of every credential-like env var, for the redactor to scrub anywhere. */
+export function secretEnvValues(env: NodeJS.ProcessEnv = process.env): string[] {
+  return Object.entries(env)
+    .filter(([k, v]) => v && isSecretEnv(k))
+    .map(([, v]) => v as string);
+}
diff --git a/src/support/report.ts b/src/support/report.ts
new file mode 100644
index 0000000..bb53dda
--- /dev/null
+++ b/src/support/report.ts
@@ -0,0 +1,360 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { DoctorCheck } from "../cli/groups/dql/doctor.js";
+import type { LastError } from "./last-error.js";
+import { isSecretEnv, SECRET_ENV } from "./redact.js";
+import type { BundleSession, SavedBundle } from "./sdk-bundle.js";
+
+/** Everything `doctor --report` gathers. Plain data: rendered to Markdown and JSON. */
+export interface Report {
+  generated: string;
+  environment: Record<string, string>;
+  checks: DoctorCheck[];
+  settings: Record<string, string>;
+  paths: Record<string, string>;
+  store: StoreSummary;
+  sdkBundle: { file?: string; detail: string };
+  lastError: LastError | null;
+}
+
+export interface StoreSummary {
+  /** Why there's no summary (no store yet, opted out, failed to open…). */
+  skipped?: string;
+  collections?: { name: string; documents: number | string }[];
+  indexes?: { id: string; collection: string; fields: string }[];
+}
+
+export type StoreSession = BundleSession & { close(): Promise<void> };
+
+export interface ReportInputs {
+  dataDir: string;
+  configDir: string;
+  /** Include collection names, counts, and indexes. */
+  includeStore: boolean;
+  /** Request a Ditto SDK support bundle into `workDir`. */
+  includeSdkBundle: boolean;
+  /** Where the SDK bundle is saved before archiving. */
+  workDir: string;
+  checks: DoctorCheck[];
+  environment: Record<string, string>;
+  lastError: LastError | null;
+  env?: NodeJS.ProcessEnv;
+  /** Opens the store; throws if it can't. */
+  openStore: () => Promise<StoreSession>;
+  saveBundle: (session: StoreSession, filePath: string) => Promise<SavedBundle>;
+  now?: () => Date;
+}
+
+/** Bytes as a short human string. */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(v >= 10 ? 0 : 1)} ${units[i]}`;
+}
+
+/** Total size of a directory tree (best-effort; unreadable entries are skipped). */
+export function dirSize(dir: string): number {
+  let total = 0;
+  const walk = (p: string) => {
+    let st: fs.Stats;
+    try {
+      st = fs.lstatSync(p);
+    } catch {
+      return;
+    }
+    if (st.isDirectory()) {
+      let entries: string[] = [];
+      try {
+        entries = fs.readdirSync(p);
+      } catch {
+        return;
+      }
+      for (const e of entries) walk(path.join(p, e));
+    } else {
+      total += st.size;
+    }
+  };
+  walk(dir);
+  return total;
+}
+
+/** Free space on the volume holding `p` (or its nearest existing ancestor). */
+export function freeSpace(p: string): number | null {
+  let probe = p;
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  try {
+    const s = fs.statfsSync(probe);
+    return Number(s.bavail) * Number(s.bsize);
+  } catch {
+    return null;
+  }
+}
+
+const SETTINGS_ENV = [
+  "NO_COLOR",
+  "FORCE_COLOR",
+  "CI",
+  "PAGER",
+  "LESS",
+  "TERM",
+  "TERM_PROGRAM",
+  "COLORTERM",
+  "LANG",
+  "LC_ALL",
+  "SHELL",
+];
+
+/** Settings that change dittosh's behavior. Credentials show only as set/not set. */
+export function collectSettings(env: NodeJS.ProcessEnv): Record<string, string> {
+  const out: Record<string, string> = {};
+  const names = [
+    ...Object.keys(env)
+      .filter((k) => k.startsWith("DITTOSH_"))
+      .sort(),
+    ...SETTINGS_ENV,
+  ];
+  for (const k of names) {
+    if (env[k] === undefined) continue;
+    out[k] = isSecretEnv(k) ? "set (value hidden)" : (env[k] ?? "");
+  }
+  for (const k of SECRET_ENV) out[k] = env[k] ? "set (value hidden)" : "not set";
+  return out;
+}
+
+/** Machine and terminal facts that commonly explain "works for me" bugs. */
+export function collectMachine(): Record<string, string> {
+  const cpus = os.cpus();
+  const intl = Intl.DateTimeFormat().resolvedOptions();
+  return {
+    os: `${os.type()} ${os.release()}${typeof os.version === "function" ? ` (${os.version()})` : ""}`,
+    platform: `${process.platform}/${process.arch}`,
+    cpu: cpus.length > 0 ? `${cpus[0]?.model ?? "unknown"} × ${cpus.length}` : "unknown",
+    memory: `${formatBytes(os.totalmem())} total, ${formatBytes(os.freemem())} free`,
+    node: `${process.version} (${process.execPath})`,
+    terminal: [
+      `stdout ${process.stdout.isTTY ? "TTY" : "not a TTY"}`,
+      `stderr ${process.stderr.isTTY ? "TTY" : "not a TTY"}`,
+      process.stdout.columns ? `${process.stdout.columns}×${process.stdout.rows}` : "size unknown",
+    ].join(", "),
+    locale: `${intl.locale}, ${intl.timeZone}`,
+  };
+}
+
+async function summarizeStore(session: StoreSession): Promise<StoreSummary> {
+  const cols = await session.execute("SELECT * FROM system:collections");
+  const names = cols.items
+    .map((i) => String((i.value as { name?: unknown }).name ?? ""))
+    .filter((n) => n && !n.startsWith("__"))
+    .sort();
+  const collections: StoreSummary["collections"] = [];
+  for (const name of names) {
+    try {
+      const r = await session.execute(`SELECT COUNT(*) AS n FROM \`${name.replace(/`/g, "``")}\``);
+      collections.push({ name, documents: Number((r.items[0]?.value as { n?: unknown })?.n ?? 0) });
+    } catch (err) {
+      collections.push({ name, documents: `count failed: ${(err as Error).message}` });
+    }
+  }
+  const idx = await session.execute("SELECT * FROM system:indexes");
+  const indexes = idx.items.map((i) => {
+    const v = i.value as { _id?: unknown; collection?: unknown; fields?: unknown };
+    const fields = Array.isArray(v.fields)
+      ? v.fields
+          .map((f: { key?: unknown; direction?: unknown }) => {
+            const key = Array.isArray(f.key) ? f.key.join(".") : String(f.key ?? "?");
+            return f.direction && f.direction !== "asc" ? `${key} ${String(f.direction)}` : key;
+          })
+          .join(", ")
+      : "";
+    return { id: String(v._id ?? ""), collection: String(v.collection ?? ""), fields };
+  });
+  return { collections, indexes };
+}
+
+/**
+ * Gather the report. Every section is best-effort: a failure is written into
+ * the report as text rather than stopping it, since a broken install is
+ * exactly when people need the report.
+ */
+export async function collectReport(inputs: ReportInputs): Promise<Report> {
+  const env = inputs.env ?? process.env;
+  const now = inputs.now ?? (() => new Date());
+
+  const storeExists = fs.existsSync(path.join(inputs.dataDir, "__ditto_lock_file"));
+  const free = freeSpace(inputs.dataDir);
+  const paths: Record<string, string> = {
+    "data directory": inputs.dataDir,
+    "store size": storeExists ? formatBytes(dirSize(inputs.dataDir)) : "no store yet",
+    "free disk space": free === null ? "unknown" : formatBytes(free),
+    "config directory": inputs.configDir,
+    "config files": (() => {
+      try {
+        return fs.readdirSync(inputs.configDir).sort().join(", ") || "(empty)";
+      } catch {
+        return "(none)";
+      }
+    })(),
+    executable: process.argv[1] ?? "unknown",
+  };
+
+  let store: StoreSummary = {};
+  let sdkBundle: Report["sdkBundle"] = { detail: "" };
+  if (!inputs.includeStore) store = { skipped: "left out (--no-store)" };
+  if (!inputs.includeSdkBundle) sdkBundle = { detail: "left out (--no-sdk-bundle)" };
+
+  if (!storeExists) {
+    const why = `no store at the data directory yet`;
+    if (inputs.includeStore) store = { skipped: why };
+    if (inputs.includeSdkBundle) sdkBundle = { detail: `not created: ${why}` };
+  } else if (inputs.includeStore || inputs.includeSdkBundle) {
+    let session: StoreSession | null = null;
+    try {
+      session = await inputs.openStore();
+    } catch (err) {
+      const why = `the store didn't open: ${(err as Error).message.split("\n")[0]}`;
+      if (inputs.includeStore) store = { skipped: why };
+      if (inputs.includeSdkBundle) sdkBundle = { detail: `not created: ${why}` };
+    }
+    if (session) {
+      try {
+        if (inputs.includeStore) {
+          try {
+            store = await summarizeStore(session);
+          } catch (err) {
+            store = { skipped: `summary failed: ${(err as Error).message}` };
+          }
+        }
+        if (inputs.includeSdkBundle) {
+          const file = path.join(inputs.workDir, "ditto-support-bundle.tar");
+          try {
+            const saved = await inputs.saveBundle(session, file);
+            sdkBundle = {
+              file: path.basename(file),
+              detail: `${formatBytes(saved.bytes)}, created ${saved.createdAt}${
+                saved.reusedBecause
+                  ? ` (an existing bundle: a new one wasn't allowed: ${saved.reusedBecause})`
+                  : ""
+              }`,
+            };
+          } catch (err) {
+            sdkBundle = { detail: `failed: ${(err as Error).message}` };
+          }
+        }
+      } finally {
+        await session.close().catch(() => {});
+      }
+    }
+  }
+
+  return {
+    generated: now().toISOString(),
+    environment: { ...inputs.environment, ...collectMachine() },
+    checks: inputs.checks,
+    settings: collectSettings(env),
+    paths,
+    store,
+    sdkBundle,
+    lastError: inputs.lastError,
+  };
+}
+
+// `|` as an HTML entity: Markdown renders it as a pipe, it can't end a cell,
+// and backslashes (Windows paths) stay readable in the raw file.
+const cell = (s: string) => s.replace(/\|/g, "&#124;").replace(/\r?\n/g, " ");
+
+function table(rows: Record<string, string>): string {
+  const lines = ["| | |", "|---|---|"];
+  for (const [k, v] of Object.entries(rows)) lines.push(`| ${cell(k)} | ${cell(v)} |`);
+  return lines.join("\n");
+}
+
+/** The Markdown report (also readable as plain text). */
+export function renderReport(r: Report): string {
+  const out: string[] = [];
+  out.push("# dittosh diagnostic report", "");
+  out.push(`Generated ${r.generated}. Review it before attaching it to an issue.`, "");
+
+  out.push("## Environment", "", table(r.environment), "");
+
+  out.push("## Checks", "");
+  for (const c of r.checks) out.push(`- ${c.ok ? "✓" : "✗"} **${c.label}**: ${c.detail}`);
+  out.push("");
+
+  out.push("## Paths and disk", "", table(r.paths), "");
+  out.push("## Settings", "", table(r.settings), "");
+
+  out.push("## Store", "");
+  if (r.store.skipped) {
+    out.push(`Not included: ${r.store.skipped}.`, "");
+  } else {
+    const cols = r.store.collections ?? [];
+    if (cols.length === 0) out.push("No collections.", "");
+    else {
+      out.push("| collection | documents |", "|---|---|");
+      for (const c of cols) out.push(`| ${cell(c.name)} | ${c.documents} |`);
+      out.push("");
+    }
+    const idx = r.store.indexes ?? [];
+    if (idx.length === 0) out.push("No indexes.", "");
+    else {
+      out.push("| index | collection | fields |", "|---|---|---|");
+      for (const i of idx)
+        out.push(`| ${cell(i.id)} | ${cell(i.collection)} | ${cell(i.fields)} |`);
+      out.push("");
+    }
+  }
+
+  out.push("## Ditto SDK support bundle", "");
+  out.push(
+    r.sdkBundle.file ? `\`${r.sdkBundle.file}\`: ${r.sdkBundle.detail}` : r.sdkBundle.detail,
+    "",
+  );
+
+  out.push("## Last error", "");
+  if (!r.lastError) out.push("No failed command recorded.", "");
+  else {
+    const e = r.lastError;
+    out.push(
+      `\`dittosh ${e.command.join(" ")}\` exited ${e.exitCode} at ${e.time} (v${e.version}).`,
+      "",
+    );
+    if (e.stderr.length > 0) out.push("```", ...e.stderr, "```", "");
+    if (e.stack) out.push("Stack trace:", "", "```", e.stack, "```", "");
+  }
+  return `${out.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * report.json, redacted string by string before encoding: JSON doubles
+ * backslashes, so a Windows home path wouldn't match once encoded.
+ */
+export function renderReportJson(r: Report, redact: (s: string) => string): string {
+  return `${JSON.stringify(r, (_key, value) => (typeof value === "string" ? redact(value) : value), 2)}\n`;
+}
+
+/** What the bundle contains, for the note printed after writing it. */
+export function describeContents(r: Report): string[] {
+  const items = [
+    "report.md / report.json: versions, OS, terminal, doctor checks, paths, dittosh settings (credentials only as set/not set)",
+  ];
+  if (r.store.collections)
+    items.push("store summary: collection names, document counts, indexes (no document contents)");
+  if (r.lastError)
+    items.push(`last error: the failed command line and its error output (${r.lastError.time})`);
+  if (r.sdkBundle.file)
+    items.push(
+      `${r.sdkBundle.file}: Ditto's support bundle, included as is (SDK debug logs and store config; holds the database ID, full file paths, and peer keys)`,
+    );
+  return items;
+}
diff --git a/src/support/sdk-bundle.ts b/src/support/sdk-bundle.ts
new file mode 100644
index 0000000..6d1cf50
--- /dev/null
+++ b/src/support/sdk-bundle.ts
@@ -0,0 +1,110 @@
+/**
+ * Ditto SDK support bundles (SDK 5.2+): `EXECUTE FUNCTION
+ * system_request_support_bundle()` builds a .tar on the device (device logs,
+ * config snapshot with secrets redacted, runtime telemetry) and returns an
+ * attachment token for it; `system:support_bundles` lists the bundles kept.
+ * Works offline. The SDK admits 3 requests per 10 minutes per store by
+ * default (`support_bundle_request_rate`), so a rejected request falls back
+ * to the newest bundle already on the device.
+ */
+
+export interface AttachmentToken {
+  id: string;
+  len: number | bigint;
+  metadata: Record<string, string>;
+}
+
+/** The slice of a session this module needs (DittoSession, or a test fake). */
+export interface BundleSession {
+  execute(statement: string): Promise<{ items: { value: unknown }[] }>;
+  saveAttachment(token: AttachmentToken, filePath: string): Promise<void>;
+}
+
+export interface SavedBundle {
+  path: string;
+  bytes: number;
+  createdAt: string;
+  reason: string;
+  /** Set when a new bundle couldn't be made and an existing one was saved instead. */
+  reusedBecause?: string;
+}
+
+interface BundleRow {
+  _id?: { created_at?: string; pk?: string };
+  reason?: string;
+  file?: AttachmentToken;
+}
+
+const NEWEST = "SELECT * FROM system:support_bundles ORDER BY _id.created_at DESC LIMIT 1";
+
+/** DQL object literal from plain strings (keys and values limited to safe characters). */
+function metadataLiteral(metadata: Record<string, string>): string {
+  const safe = (s: string) => s.replace(/[^\w.:@/ -]/g, "").slice(0, 100);
+  const pairs = Object.entries(metadata).map(([k, v]) => `'${safe(k)}': '${safe(v)}'`);
+  return `{'metadata': {${pairs.join(", ")}}}`;
+}
+
+function asRow(value: unknown): BundleRow {
+  return (value ?? {}) as BundleRow;
+}
+
+/** Strip the SDK's "Query failed: `…`. For more information…" wrapper. */
+export function bundleErrorMessage(err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  const inner = /Query failed: `([\s\S]*?)`\./.exec(msg)?.[1] ?? msg;
+  return inner.replace(
+    /^Support bundle request failure: (failed to request support bundle: )?/,
+    "",
+  );
+}
+
+/**
+ * Request a new support bundle and save it to `filePath`. If the SDK rejects
+ * the request (rate limit, one already in progress), save the newest
+ * existing bundle instead; if there is none, the error is thrown.
+ */
+export async function saveSupportBundle(
+  session: BundleSession,
+  filePath: string,
+  metadata: Record<string, string> = {},
+): Promise<SavedBundle> {
+  let row: BundleRow;
+  let reusedBecause: string | undefined;
+  try {
+    const r = await session.execute(
+      `EXECUTE FUNCTION system_request_support_bundle(${metadataLiteral(metadata)})`,
+    );
+    row = asRow(r.items[0]?.value);
+  } catch (err) {
+    reusedBecause = bundleErrorMessage(err);
+    const existing = await session.execute(NEWEST).catch(() => ({ items: [] }));
+    if (existing.items.length === 0) throw new Error(reusedBecause);
+    row = asRow(existing.items[0]?.value);
+  }
+  if (!row.file?.id) throw new Error("the SDK returned no support bundle file");
+  await session.saveAttachment(row.file, filePath);
+  return {
+    path: filePath,
+    bytes: Number(row.file.len),
+    createdAt: row._id?.created_at ?? "unknown",
+    reason: row.reason ?? "unknown",
+    ...(reusedBecause ? { reusedBecause } : {}),
+  };
+}
+
+/** The bundles kept on the device, newest first. */
+export async function listSupportBundles(
+  session: Pick<BundleSession, "execute">,
+): Promise<{ created_at: string; reason: string; bytes: number }[]> {
+  const r = await session.execute(
+    "SELECT * FROM system:support_bundles ORDER BY _id.created_at DESC",
+  );
+  return r.items.map((i) => {
+    const row = asRow(i.value);
+    return {
+      created_at: row._id?.created_at ?? "unknown",
+      reason: row.reason ?? "unknown",
+      bytes: Number(row.file?.len ?? 0),
+    };
+  });
+}
diff --git a/src/tutorial/content.ts b/src/tutorial/content.ts
new file mode 100644
index 0000000..f3fc51f
--- /dev/null
+++ b/src/tutorial/content.ts
@@ -0,0 +1,876 @@
+import type { InstallChannel } from "../update/channel.js";
+
+/**
+ * The hands-on tutorial behind `dittosh tutorial`, as structured content:
+ * prose blocks plus code blocks that know whether they can run unattended.
+ * The renderer turns it into Markdown; tests/e2e/tutorial.test.ts runs every
+ * runnable bash block in order against a fresh store, so a tutorial command
+ * that stops working fails CI instead of confusing a reader.
+ */
+
+export interface TutorialContext {
+  cliVersion: string;
+  sdkVersion: string;
+  channel: InstallChannel;
+  /** `${process.platform}/${process.arch}` */
+  platform: string;
+  /** YYYY-MM-DD */
+  generatedOn: string;
+}
+
+export type Block =
+  | { kind: "text"; md: string }
+  | {
+      kind: "code";
+      lang: "bash" | "sql" | "text";
+      code: string;
+      /** false: needs a TTY, the network, a package manager, or an optional tool. */
+      run: boolean;
+      /** Strings the block's stdout must contain when run by the tutorial test. */
+      expect?: string[];
+    };
+
+export interface Section {
+  title: string;
+  blocks: Block[];
+}
+
+/** Shell parameter expansion, kept out of a JS template placeholder. */
+const TMPDIR_DEFAULT = ["$", "{TMPDIR:-/tmp}"].join("");
+
+const text = (md: string): Block => ({ kind: "text", md: md.trim() });
+
+/** A bash block the tutorial test executes (shared shell state across blocks). */
+const sh = (code: string, expect?: string[]): Block => ({
+  kind: "code",
+  lang: "bash",
+  code: code.trim(),
+  run: true,
+  ...(expect ? { expect } : {}),
+});
+
+/** A bash block shown to the reader but not executed by the tutorial test. */
+const shManual = (code: string): Block => ({
+  kind: "code",
+  lang: "bash",
+  code: code.trim(),
+  run: false,
+});
+
+const listing = (lang: "sql" | "text", code: string): Block => ({
+  kind: "code",
+  lang,
+  code: code.trim(),
+  run: false,
+});
+
+function upgradeCommand(channel: InstallChannel): string {
+  return channel === "npm"
+    ? "npm install -g @dittolive/cli@latest"
+    : "brew update && brew upgrade getditto/tap/dittosh";
+}
+
+function channelName(channel: InstallChannel): string {
+  return channel === "homebrew" ? "Homebrew" : channel === "npm" ? "npm" : "an unknown method";
+}
+
+export function tutorialSections(ctx: TutorialContext): Section[] {
+  const windows = ctx.platform.startsWith("win32");
+  return [
+    {
+      title: "Check your installation",
+      blocks: [
+        sh(
+          `
+dittosh --version
+dittosh version
+dittosh --help
+`,
+          [ctx.cliVersion],
+        ),
+        text(`
+\`dittosh --version\` prints the CLI version. \`dittosh version\` also reports the
+Ditto SDK version, installation channel, license expiry, and data-directory path.
+This copy reports **${ctx.cliVersion}** with Ditto SDK **${ctx.sdkVersion}**, installed
+through **${channelName(ctx.channel)}**.
+
+The executable is **\`dittosh\`**, not the macOS \`ditto\` utility. To set it up on
+another machine, use either package manager:
+`),
+        shManual(`
+# Homebrew (Apple Silicon macOS, Linux x64/arm64)
+brew install getditto/tap/dittosh
+
+# npm (Node.js 22 or newer; also Windows x64)
+npm install -g @dittolive/cli
+`),
+        text(`
+Intel Macs are not supported by the native SDK bundled with this release.
+${windows ? "\nThe commands in this tutorial use Bash syntax. On Windows, run them in WSL or Git Bash.\n" : ""}`),
+      ],
+    },
+    {
+      title: "Create an isolated practice workspace",
+      blocks: [
+        sh(`
+DITTOSH_TUTORIAL="$(mktemp -d "${TMPDIR_DEFAULT}/dittosh-tutorial.XXXXXX")"
+cd "$DITTOSH_TUTORIAL"
+export DITTOSH_DATA_DIR="$DITTOSH_TUTORIAL/store"
+export DITTOSH_CONFIG_DIR="$DITTOSH_TUTORIAL/config"
+printf 'Practice directory: %s\\n' "$DITTOSH_TUTORIAL"
+dittosh dql doctor
+`),
+        text(`
+Keep this terminal open for the rest of the tutorial. \`doctor\` checks the native
+SDK, offline license, directory access, and whether the store can be opened.
+Save the printed directory path if you want to revisit your practice files.
+
+You may see native SDK startup messages on stderr. Query results are written to
+stdout separately, which lets you pipe them into other tools.
+`),
+      ],
+    },
+    {
+      title: "Import a product catalog",
+      blocks: [
+        text("Create a JSON array of documents:"),
+        sh(
+          `
+cat > products.json <<'JSON'
+[
+  {"_id":"p1","name":"Coffee beans","category":"coffee","price":12.5,"stock":20},
+  {"_id":"p2","name":"Paper filters","category":"coffee","price":5,"stock":100},
+  {"_id":"p3","name":"Green tea","category":"tea","price":9,"stock":30}
+]
+JSON
+
+dittosh dql import products.json products
+dittosh dql collections
+dittosh dql "SELECT count(*) AS total FROM products"
+`,
+          ['"total": 3'],
+        ),
+        text(`
+**Check:** the \`products\` collection contains **3 documents**.
+
+Imports also accept NDJSON: one JSON object per line. Supplying stable \`_id\`
+values makes re-imports update the matching documents. Without \`_id\`, the importer
+generates IDs, so importing the same file again creates additional documents.
+`),
+      ],
+    },
+    {
+      title: "Query, filter, sort, and bind parameters",
+      blocks: [
+        text("Show a few fields, ordered by price:"),
+        sh(`dittosh dql "SELECT name, category, price, stock FROM products ORDER BY price DESC"`),
+        text("Filter with named parameters:"),
+        sh(
+          String.raw`
+dittosh dql "SELECT name, price FROM products WHERE category = :category AND price >= :minimum ORDER BY price DESC" \
+  --param category=coffee --param minimum=10
+`,
+          ["Coffee beans", "12.5"],
+        ),
+        text(`
+**Check:** the filtered query returns **Coffee beans**, priced at **12.5**.
+Parameter values are interpreted as JSON when possible, with a string fallback.
+You can pass the parameters as a JSON object instead:
+`),
+        sh(
+          String.raw`
+dittosh dql "SELECT name, price FROM products WHERE category = :category AND price >= :minimum" \
+  --args '{"category":"coffee","minimum":10}'
+`,
+          ["Coffee beans"],
+        ),
+        text("Use `LIMIT` to keep exploratory queries small:"),
+        sh(`dittosh dql "SELECT * FROM products LIMIT 2" --format vertical`),
+        text("`vertical` displays one record at a time and is useful for wide documents."),
+      ],
+    },
+    {
+      title: "Insert, update, and remove a practice document",
+      blocks: [
+        text("Insert a mug. The conflict clause makes repeating this INSERT safe for the same ID:"),
+        sh(`
+dittosh dql "INSERT INTO products VALUES ({'_id':'p4','name':'Mug','category':'accessories','price':8,'stock':15}) ON ID CONFLICT DO UPDATE"
+dittosh dql "SELECT name, stock FROM products WHERE _id = 'p4'"
+`),
+        text("Update its stock, then query it again:"),
+        sh(
+          `
+dittosh dql "UPDATE products SET stock = 12 WHERE _id = 'p4'"
+dittosh dql "SELECT name, stock FROM products WHERE _id = 'p4'"
+`,
+          ['"stock": 12'],
+        ),
+        text(
+          "**Check:** Mug now has **12** units in stock.\n\nRemove that practice document from the local store:",
+        ),
+        sh(
+          `
+dittosh dql "EVICT FROM products WHERE _id = 'p4'"
+dittosh dql "SELECT count(*) AS total FROM products"
+`,
+          ['"total": 3'],
+        ),
+        text(`
+**Check:** the count is back to **3**. \`EVICT\` removes local data; it is distinct
+from a synchronized deletion. This CLI's database is offline-only.
+`),
+      ],
+    },
+    {
+      title: "Run a file of statements",
+      blocks: [
+        sh(`
+cat > report.dql <<'DQL'
+SELECT count(*) AS total FROM products;
+SELECT name, price FROM products WHERE category = 'coffee' ORDER BY price DESC;
+DQL
+
+dittosh dql --file report.dql --time
+`),
+        text(`
+Separate statements with semicolons. By default, a batch stops at its first
+error. Add \`--continue-on-error\` when you intentionally want later statements
+to run even if an earlier one fails.
+
+You can also feed a statement through stdin:
+`),
+        sh(String.raw`printf 'SELECT count(*) AS total FROM products;\n' | dittosh dql`, [
+          '"total": 3',
+        ]),
+      ],
+    },
+    {
+      title: "Export results and use pipes",
+      blocks: [
+        text("The output filename determines the format for these exports:"),
+        sh(`
+dittosh dql "SELECT name, price, stock FROM products ORDER BY name" --out products-report.csv
+dittosh dql "SELECT name, price, stock FROM products ORDER BY name" --out products-report.json
+dittosh dql "SELECT name, price, stock FROM products ORDER BY name" --out products-report.md
+dittosh dql "SELECT name, price, stock FROM products ORDER BY name" --out products-report.html
+`),
+        text(`
+These files are written into your practice directory. Open the HTML file in a
+browser or include the Markdown table in a document.
+
+For explicit terminal formats:
+`),
+        sh(`
+dittosh dql "SELECT name, price FROM products" --format json
+dittosh dql "SELECT name, price FROM products" --format markdown
+`),
+        text("**Optional: JSON pipelines with `jq`.** Install `jq` first if needed:"),
+        shManual(`
+dittosh dql "SELECT name, price FROM products ORDER BY price DESC" | jq '.[0].name'
+`),
+        text(`
+**Check:** the pipeline prints \`"Coffee beans"\`. When stdout is piped, the default
+query output is JSON. Progress and diagnostics stay on stderr.
+`),
+      ],
+    },
+    {
+      title: "Use the interactive DQL shell",
+      blocks: [
+        text("From your terminal, start the shell:"),
+        shManual("dittosh dql"),
+        text("At the `dql>` prompt, enter:"),
+        listing(
+          "sql",
+          `
+SELECT name, price FROM products ORDER BY price DESC;
+SELECT count(*) AS total FROM products;
+`,
+        ),
+        text(`
+Finish each DQL statement with \`;\`. You can split a statement across lines.
+Try these dot-commands **inside the interactive shell**:
+`),
+        listing(
+          "text",
+          `
+.help
+.collections
+.indexes products
+.metrics
+`,
+        ),
+        text(`
+\`.metrics\` shows the Ditto SDK's live system metrics for this session as tables:
+
+- **Store:** SQLite transactions, fsync, write-ahead log size, and commit and lock
+  timings.
+- **Query (DQL):** requests, selects, failures, and parse, plan, and execution times.
+
+Totals and averages run since the shell opened. The **Change**, **p50/p90/p99**,
+and **Max** columns cover only the time since your previous \`.metrics\`, so run a
+few statements and then \`.metrics\` again to see what they cost. \`.metrics query\`
+narrows the view; \`.metrics all\` adds network, sync, transport, and other sections.
+`),
+        listing(
+          "text",
+          `
+.metrics query
+.exit
+`,
+        ),
+        text(`
+Use \`.break\` to discard an unfinished statement. \`.exit\` returns you to your
+normal terminal. The remaining examples are normal terminal commands.
+`),
+      ],
+    },
+    {
+      title: "Explore built-in sample datasets",
+      blocks: [
+        sh(
+          `
+dittosh dql dataset list
+dittosh dql dataset show movies
+dittosh dql dataset load movies --docs 1000 --seed 42
+dittosh dql "SELECT count(*) AS total FROM movies"
+`,
+          ['"total": 1000'],
+        ),
+        text(`
+**Check:** the \`movies\` collection has **1,000 documents** in this fresh workspace.
+The movies dataset uses a structured \`_id\`: its title and year are accessed as
+\`_id.title\` and \`_id.year\`, and its year is stored as a string.
+`),
+        sh(`
+dittosh dql "SELECT _id.title, _id.year, rated FROM movies WHERE _id.year > '2000' LIMIT 5"
+dittosh dql dataset run count --dataset movies
+`),
+        text(`
+\`dataset run\` executes a named example from the dataset's query catalog. Use
+\`dataset show\` to see available names. \`--seed\` makes data generation repeatable;
+use the same seed for repeatable experiments.
+
+The available datasets include \`movies\`, \`retail\`, \`retail-joins\`, and \`pos\`.
+The retail datasets share collection names, so use separate stores when comparing
+them or when you already have a collection named \`products\`.
+`),
+      ],
+    },
+    {
+      title: "Inspect timing, plans, and profiles",
+      blocks: [
+        sh(
+          `
+dittosh dql "SELECT _id.title FROM movies WHERE rated = 'PG' LIMIT 5" --time
+dittosh dql "SELECT _id.title FROM movies WHERE rated = 'PG' LIMIT 5" --explain
+dittosh dql "SELECT _id.title FROM movies WHERE rated = 'PG' LIMIT 5" --profile --time
+`,
+        ),
+        text(`
+- \`--time\` reports execution timing.
+- \`--explain\` shows the query plan.
+- \`--profile\` runs the query with \`PROFILE\` and shows the operator tree. Each
+  operator lists its CPU time (with its share of the total) and documents in, out,
+  and skipped. Dim lines underneath show:
+  - \`recv\`: time spent waiting for input from upstream
+  - \`send\`: time spent pushing output downstream
+  - \`stor\`: time blocked on storage
+  - **yields**: how often the operator paused for the scheduler, by reason
+    (\`budget\`, \`sender\`, \`receiver\`, \`heartbeat\`)
+  - the operator's attributes
+
+  Any operator using at least half the CPU time is flagged \`▲ HOT\`.
+
+Compare the plans before and after adding an index in the next section. Timing
+varies by hardware and data size; a tiny dataset may not show a measurable speedup.
+`),
+      ],
+    },
+    {
+      title: "Ask for index advice",
+      blocks: [
+        text("First inspect the advice without changing the store:"),
+        sh(`dittosh dql --advise "SELECT * FROM movies WHERE rated = 'PG'"`),
+        text("Then apply the suggested index to this practice database:"),
+        sh(
+          `
+dittosh dql --advise --apply --yes "SELECT * FROM movies WHERE rated = 'PG'"
+dittosh dql indexes movies
+dittosh dql "SELECT _id.title FROM movies WHERE rated = 'PG' LIMIT 5" --explain
+`,
+          ["rated"],
+        ),
+        text(`
+**Check:** an index on \`rated\` should appear in the index list. Compare the new
+plan with the earlier one. \`--yes\` confirms the schema change without prompting.
+`),
+      ],
+    },
+    {
+      title: "Benchmark a query",
+      blocks: [
+        text(`
+One timing can mislead: the first run of a query pays for cold caches and query
+planning. \`dql bench\` runs a statement many times and reports the spread.
+`),
+        sh(
+          `dittosh dql bench "SELECT _id.title FROM movies WHERE rated = 'PG'" --runs 20 --warmup --format json`,
+          ['"p95_ms"'],
+        ),
+        text(`
+- \`--runs <n>\` sets how many timed runs to make (default 50).
+- \`--warmup\` runs the statement untimed first, enough times to fill about 250 ms.
+  \`--warmup 5\` runs exactly 5 warmup runs. Leave it out for no warmup.
+- With more than one run you get the mean, **p50** (the median), **p95**, **p99**,
+  min, max, and standard deviation, in milliseconds. p95 means 95% of runs were at
+  least this fast.
+
+Progress goes to stderr and the results to stdout, so \`--format json\`, \`-o\`, and
+pipes work as they do for queries.
+
+**Set up and clean up around the timing.** \`--pre\` runs a statement once before
+timing and \`--post\` runs one once afterwards, even if something failed. Use them to
+measure a query with an index, then remove it so the store is back where it started:
+`),
+        sh(`
+dittosh dql bench "SELECT * FROM movies WHERE _id.year = '1999'" --runs 20 \\
+  --pre "CREATE INDEX IF NOT EXISTS movies_year ON movies (_id.year)" \\
+  --post "DROP INDEX IF EXISTS movies_year ON movies"
+`),
+        text(`
+Run it again without \`--pre\` and \`--post\` to compare against a full scan.
+
+**Restore state between runs.** A write changes the data, so the second run of the
+same \`EVICT\` would find nothing to remove. \`--pre\` runs only once, so it can't help
+here: \`--before-each\` runs a statement before every run, untimed, to put the data back:
+`),
+        sh(`
+dittosh dql bench "EVICT FROM movies WHERE _id = 'bench-doc'" --runs 10 \\
+  --before-each "INSERT INTO movies VALUES ({'_id': 'bench-doc', 'rated': 'TEST'})"
+`),
+        text(`
+Each run inserts \`bench-doc\` (untimed) and then evicts it (timed), so every run
+measures a real eviction, and the store ends as it started. \`--pre\`,
+\`--before-each\` (also spelled \`--reset\`), and \`--post\` can each be repeated.
+
+**Keep benchmarks in a file.** A benchmark file is JSON: an object whose keys name
+the benchmarks. Each benchmark has a \`query\` (the statement that is timed) and,
+optionally, \`preQueries\`, \`resetQueries\`, and \`postQueries\` (lists of statements,
+the file versions of \`--pre\`, \`--before-each\`, and \`--post\`) and a \`description\`.
+They run in this order:
+
+1. \`preQueries\` once
+2. warmup runs, each preceded by \`resetQueries\`
+3. the timed runs, each preceded by \`resetQueries\` (untimed)
+4. \`postQueries\` once, even after a failure
+
+The fastest way to start is a sample file built from a sample dataset. It includes
+a plain read, an indexed read, and a write that restores its own data, each with a
+description of what its parts do:
+`),
+        sh(
+          `
+dittosh dql bench --example movies -o movies-bench.json
+dittosh dql bench -f movies-bench.json --runs 10 --warmup 2
+`,
+          ["filtered_query_with_index"],
+        ),
+        text(`
+Open \`movies-bench.json\` to see the format, then copy an entry and change it to
+time your own statements. \`--only <name>,<name>\` runs some of a file's benchmarks,
+and \`dataset run <query> --runs <n> --warmup\` benchmarks a single catalog query.
+The other samples are \`--example retail\`, \`retail-joins\`, and \`pos\`; load that
+dataset first. Timings depend on your hardware and data size, so compare runs made
+on the same machine with the same data.
+`),
+      ],
+    },
+    {
+      title: "Try a JOIN in a separate store",
+      blocks: [
+        text(
+          "Use a separate directory so the retail dataset does not mix with your product catalog:",
+        ),
+        sh(
+          String.raw`
+dittosh dql dataset load retail-joins --docs 50 --seed 42 \
+  --data-dir "$DITTOSH_TUTORIAL/joins-store"
+
+dittosh dql --data-dir "$DITTOSH_TUTORIAL/joins-store" \
+  "SELECT o._id, o.total, s.store_name, s.location.city
+   FROM orders AS o INNER JOIN stores AS s ON o.store_id = s._id
+   WHERE o._id = 'order_20221209_0001'"
+`,
+          ["Zava Retail Seattle", "164.25"],
+        ),
+        text(`
+**Check:** the anchor order joins to **Zava Retail Seattle**, with a total of
+**164.25**. A command's \`--data-dir\` overrides the environment variable only for
+that command; the next command without it uses your original practice store.
+
+Profile the same join to see how Ditto runs it. A nested-loop join (\`nlJoin\`)
+shows the lookup it repeats for every outer row as a labeled \`inner:\` subtree:
+`),
+        sh(
+          String.raw`
+dittosh dql --data-dir "$DITTOSH_TUTORIAL/joins-store" --profile \
+  "SELECT o._id, o.total, s.store_name
+   FROM orders AS o INNER JOIN stores AS s ON o.store_id = s._id
+   WHERE o._id = 'order_20221209_0001'"
+`,
+        ),
+      ],
+    },
+    {
+      title: "Diagnostics and advanced DQL",
+      blocks: [
+        text(`
+These examples cover the system collections you can use for diagnostics, and some
+more advanced DQL, using the \`products\` collection from section 3.
+
+**Sync health:** \`system:sync_degradations\` lists documents that cannot sync, such as
+documents that are too large. This offline CLI never syncs, so it is always empty
+here, but the same query works in your apps:
+`),
+        sh(`dittosh dql "SELECT count(*) AS degraded FROM system:sync_degradations"`, [
+          '"degraded": 0',
+        ]),
+        text(`
+**Support bundles:** one statement captures a diagnostic bundle, stored as an
+attachment, and \`system:support_bundles\` lists the bundles on this device:
+`),
+        sh(
+          `
+dittosh dql "EXECUTE FUNCTION system_request_support_bundle()"
+dittosh dql "SELECT _id.created_at AS created, reason, file.len AS bytes FROM system:support_bundles"
+`,
+          ["USER_INITIATED"],
+        ),
+        text(`
+**Storage facts:** \`system:system_info\` reports write-ahead-log size and checkpoint
+pressure for the SQLite storage engine:
+`),
+        sh(
+          `dittosh dql "SELECT DISTINCT key FROM system:system_info WHERE namespace = 'backend_sqlite3' ORDER BY key"`,
+          ["wal_current_size_bytes"],
+        ),
+        text(`
+**Query metrics:** query-engine counters use \`ditto.query.*\` names. Values cover the
+current process, so a one-shot command only counts itself — the interactive shell's
+\`.metrics\` shows them grow.
+`),
+        sh(
+          `dittosh dql "SELECT key, current, unit FROM system:metrics WHERE key LIKE 'ditto.query.%' ORDER BY key"`,
+          ["ditto.query.requests"],
+        ),
+        text(`
+**Conditions on array elements:** \`ANY … SATISFIES\` tests the elements of an array
+one at a time; with \`AND\`, both conditions must hold for the same element. Create
+two orders and find the one with a line for 2 × p1:
+`),
+        sh(
+          `
+dittosh dql "INSERT INTO orders VALUES ({'_id':'o1','lines':[{'sku':'p1','qty':2},{'sku':'p2','qty':1}]}), ({'_id':'o2','lines':[{'sku':'p1','qty':1},{'sku':'p3','qty':5}]}) ON ID CONFLICT DO UPDATE"
+dittosh dql "SELECT _id FROM orders WHERE ANY l IN lines SATISFIES l.sku = 'p1' AND l.qty = 2 END"
+`,
+          ['"o1"'],
+        ),
+        text("**Check:** only **o1** matches. o2 also contains p1, but with quantity 1."),
+        text(`
+**Addressing documents by ID:** \`USE IDS\` targets documents by \`_id\` without a
+WHERE clause. Evict p2, confirm it's gone, then restore it:
+`),
+        sh(
+          `
+dittosh dql "EVICT FROM products USE IDS 'p2'"
+dittosh dql "SELECT count(*) AS total FROM products"
+dittosh dql "INSERT INTO products VALUES ({'_id':'p2','name':'Paper filters','category':'coffee','price':5,'stock':100}) ON ID CONFLICT DO UPDATE"
+`,
+          ['"total": 2'],
+        ),
+        text(`
+**Comparisons written constant-first:** with an index on \`price\`, \`6 < price\` reads
+the same index range as \`price > 6\`. Run it with \`--explain\` and look for \`"low"\` in
+the index range:
+`),
+        sh(
+          `
+dittosh dql "CREATE INDEX IF NOT EXISTS idx_price ON products (price)"
+dittosh dql "SELECT name, price FROM products WHERE 6 < price ORDER BY price"
+dittosh dql "SELECT _id FROM products WHERE 6 < price" --explain
+`,
+          ["Green tea", "Coffee beans"],
+        ),
+        text(`
+**Indexes that mix sort directions:** a composite index on
+\`(category ASC, price DESC)\` returns the most expensive product first within each
+category:
+`),
+        sh(
+          `
+dittosh dql "CREATE INDEX IF NOT EXISTS idx_cat_price ON products (category ASC, price DESC)"
+dittosh dql "SELECT name, category, price FROM products ORDER BY category ASC, price DESC"
+`,
+        ),
+        text(`
+**Check:** Coffee beans (12.5) is listed before Paper filters (5). The interactive
+lessons (next section) cover these features step by step.
+`),
+      ],
+    },
+    {
+      title: "Learn DQL interactively",
+      blocks: [
+        text(`
+For a guided introduction to DQL itself, start the interactive lessons. They run in
+their own practice store, explain each concept (what a projection is, how
+functions and aggregation work, why indexes help), give you a task, and check your
+answer:
+`),
+        shManual(`
+dittosh tutorial --interactive
+dittosh tutorial --interactive --level intermediate
+`),
+        text(`
+Lessons are grouped as **beginner** (queries, filtering, projection, sorting,
+writes), **intermediate** (expressions, functions, \`CASE\`, MISSING vs NULL,
+aggregation, grouping), and **advanced** (joins, \`ANY … SATISFIES\`, indexes, query
+plans, profiling, system collections). The lessons open full screen (add
+\`--plain\` for a simple line-by-line shell). Type a statement and press Enter to run it
+(a trailing \`;\` is optional); a \`|\` prompt means it looks unfinished, so keep
+typing or use \`.break\`. Tab or \`.hint\` nudges you, \`?\` explains the keys,
+\`.answer\` shows a solution, \`.lessons\` lists your progress, and \`.exit\` saves it.
+`),
+      ],
+    },
+    {
+      title: "Install skills for an AI coding tool",
+      blocks: [
+        text(`
+Skills are downloaded from the public
+[Ditto agent-skills repository](https://github.com/getditto/agent-skills).
+They do not require installation through an agent marketplace. The CLI installs
+instruction files; it does not install or launch the AI tool itself.
+
+Create a practice project and inspect available skill releases:
+`),
+        shManual(`
+mkdir -p "$DITTOSH_TUTORIAL/agent-project"
+dittosh skills versions
+`),
+        text(`
+Choose the command for your tool. Each example installs the latest skills release
+into this practice project, rather than your global agent configuration:
+`),
+        shManual(`
+# Claude Code: DQL guidance
+dittosh skills add write-dql --agent claude --project "$DITTOSH_TUTORIAL/agent-project"
+
+# Codex: Swift SDK guidance
+dittosh skills add swift-sdk --agent codex --project "$DITTOSH_TUTORIAL/agent-project"
+
+# Antigravity: Kotlin SDK guidance
+dittosh skills add kotlin-sdk --agent antigravity --project "$DITTOSH_TUTORIAL/agent-project"
+`),
+        text("Check what was installed:"),
+        shManual(`dittosh skills list --project "$DITTOSH_TUTORIAL/agent-project"`),
+        text(`
+For these examples, expect project directories under \`.claude/skills\`,
+\`.codex/skills\`, or \`.agents/skills\` respectively. Open the practice project in
+your chosen AI tool and start a fresh session so it can discover the new files.
+For example, ask: “Use the Ditto DQL skill to explain how to query documents by
+category with a named parameter.” Actual skill loading depends on the AI tool.
+
+Other CLI targets include \`opencode\`, \`gemini\`, \`cursor\`, \`copilot\`, and
+\`windsurf\`. The last three require project-local installation. To install into
+your real project, replace the practice-project path with that project's path.
+`),
+      ],
+    },
+    {
+      title: "Install more skills, pin versions, and update them",
+      blocks: [
+        text(`
+**Optional:** install every skill for Claude Code in the practice project, pinned to
+one release. Pick a tag from \`dittosh skills versions\`:
+`),
+        shManual(`
+dittosh skills add --all --agent claude \\
+  --project "$DITTOSH_TUTORIAL/agent-project" --ref <tag>
+`),
+        text(`
+\`add\` skips existing installations by default. \`--force\` overwrites them. Use
+\`update\` when you want installed skills to move to a newer release:
+`),
+        shManual(`
+dittosh skills update --all --project "$DITTOSH_TUTORIAL/agent-project"
+dittosh skills list --project "$DITTOSH_TUTORIAL/agent-project"
+`),
+        text(`
+Without \`--ref\`, updates select the latest available skills release. If everything
+already matches, the update is a no-op. Omitting \`--all\` targets the default DQL
+skill unless you specify another skill by name.
+
+**The versions are independent:** \`dittosh\` **${ctx.cliVersion}** is the CLI; the
+agent-skills bundle has its own release tags. Updating skills does not upgrade
+the CLI, and upgrading the CLI does not automatically update skills.
+`),
+      ],
+    },
+    {
+      title: "Report a problem",
+      blocks: [
+        text(`
+When something goes wrong, \`dittosh doctor\` checks the platform, Node, the data
+directory, the license, the SDK, and the store lock. Add \`--report\` to save
+everything a maintainer needs into one file you can attach to a GitHub issue:
+`),
+        sh(
+          `
+dittosh doctor
+dittosh doctor --report "$DITTOSH_TUTORIAL/dittosh-report.tar.gz"
+tar -tzf "$DITTOSH_TUTORIAL/dittosh-report.tar.gz"
+`,
+          ["report.md", "ditto-support-bundle.tar"],
+        ),
+        text(`
+The bundle holds:
+
+- \`report.md\` (and the same data as \`report.json\`): versions, OS and terminal
+  details, the checks, paths and free space, and dittosh settings. Credentials
+  appear only as "set" or "not set", and your home folder shows as \`~\`.
+- A store summary: collection names, document counts, and indexes, with no
+  document contents. Leave it out with \`--no-store\`.
+- The last failed command and the error it printed. dittosh saves this
+  whenever a command fails, so you can make the report after the fact.
+- \`ditto-support-bundle.tar\`: Ditto's own support bundle, with the SDK's debug
+  logs and the store configuration, included as is. It holds the database ID,
+  full file paths, and peer keys. Leave it out with \`--no-sdk-bundle\`, or save
+  just this part with \`dittosh dql support-bundle\`.
+
+Extract the file and read it before you share it. To watch the SDK's logs
+while you reproduce a problem, add \`--debug\` to any command; the logs go to
+stderr, so results on stdout are unchanged.
+`),
+      ],
+    },
+    {
+      title: "Update the CLI and clean up",
+      blocks: [
+        text(
+          `Check for a newer release and upgrade through ${channelName(ctx.channel) === "an unknown method" ? "your package manager" : channelName(ctx.channel)}:`,
+        ),
+        shManual(`
+dittosh update --check
+dittosh update
+dittosh --version
+`),
+        text(`
+\`dittosh update\` detects how the CLI was installed and runs the matching upgrade.
+${
+  ctx.channel === "unknown"
+    ? "This copy could not tell how it was installed, so upgrade manually with `brew update && brew upgrade getditto/tap/dittosh` or `npm install -g @dittolive/cli@latest`."
+    : `The equivalent manual command for this installation is \`${upgradeCommand(ctx.channel)}\`.`
+}
+
+**Optional cleanup:** first exit any interactive DQL session. The following
+commands permanently remove only the two database directories created in this
+tutorial; they leave exported files and installed project skills in place:
+`),
+        sh(`
+dittosh dql delete-store --data-dir "$DITTOSH_TUTORIAL/store" --yes
+dittosh dql delete-store --data-dir "$DITTOSH_TUTORIAL/joins-store" --yes
+unset DITTOSH_DATA_DIR DITTOSH_CONFIG_DIR
+`),
+        text(`
+To remove the remaining practice files, delete the printed practice directory
+using your file manager when you no longer need it. Do not use \`delete-store\`
+without confirming which data directory it targets.
+`),
+      ],
+    },
+  ];
+}
+
+const TROUBLESHOOTING = `
+| What you see | What to do |
+| --- | --- |
+| \`dittosh: command not found\` | Follow your package manager's shell setup instructions and open a new terminal. |
+| Formula not found | Run \`brew update\`, then use the fully qualified name \`getditto/tap/dittosh\`. |
+| Store locked / exit 4 | Close another CLI process or REPL using the same directory, or choose a different \`--data-dir\`. |
+| Expired offline license | Run \`dittosh update\`. If the latest release also fails, report it to the CLI maintainers. |
+| Empty query results | Check the collection name and data directory; movie titles use \`_id.title\`, not \`title\`. |
+| \`.metrics\` says metrics are disabled | Restart the shell; metrics are enabled when the store opens. |
+| Agent skills are not discovered | Confirm the project path, inspect \`skills list\`, and start a fresh session in that AI tool. |
+| Startup warnings alongside results | Native SDK startup messages go to stderr; use stdout for JSON pipelines. |
+| Anything else | Run \`dittosh doctor --report\` and attach the file to a GitHub issue. |
+`;
+
+/** Render the tutorial as Markdown. */
+export function renderTutorial(ctx: TutorialContext): string {
+  const sections = tutorialSections(ctx);
+  const out: string[] = [];
+  out.push("# Ditto CLI: a hands-on tutorial", "");
+  out.push(
+    `**Release:** \`dittosh\` ${ctx.cliVersion} (Ditto SDK ${ctx.sdkVersion}) · **Time:** about 35 minutes · **Shell:** Bash or Zsh`,
+    "",
+  );
+  out.push(
+    `
+Use the Ditto CLI to explore an offline database, run DQL, import and export
+documents, investigate query performance, watch live system metrics, and install
+skills for AI coding tools. This walkthrough uses a separate practice directory,
+so its database exercises do not change your existing Ditto data.
+
+The CLI runs DQL locally with an embedded offline license. You do not need a Ditto
+account, database credentials, or a running server. This release does not connect
+to a cloud database or synchronize with other devices. Internet access is needed
+for installation, upgrades, and downloading agent skills.
+`.trim(),
+    "",
+  );
+  out.push("## What you will try", "");
+  sections.forEach((s, i) => {
+    out.push(`${i + 1}. ${s.title}`);
+  });
+  out.push(
+    "",
+    "Run the numbered sections in order in the same terminal. Optional examples are",
+    "marked. Commands shown inside the interactive shell are DQL, not shell commands.",
+    "",
+  );
+
+  sections.forEach((s, i) => {
+    out.push(`## ${i + 1}. ${s.title}`, "");
+    for (const b of s.blocks) {
+      if (b.kind === "text") {
+        if (b.md) out.push(b.md, "");
+      } else {
+        out.push(`\`\`\`${b.lang}`, b.code, "```", "");
+      }
+    }
+  });
+
+  out.push("## Quick troubleshooting", "", TROUBLESHOOTING.trim(), "");
+  out.push(
+    "For a bug report, include the failing command, `dittosh version`, your OS and",
+    "architecture, and the error output. Leave out credentials and private documents.",
+    "",
+  );
+  out.push(
+    "## Useful links",
+    "",
+    "- [CLI source and issues](https://github.com/getditto/ditto-cli)",
+    `- [CLI ${ctx.cliVersion} release](https://github.com/getditto/ditto-cli/releases/tag/v${ctx.cliVersion})`,
+    "- [Homebrew tap](https://github.com/getditto/homebrew-tap)",
+    "- [Ditto agent skills](https://github.com/getditto/agent-skills)",
+    "- [DQL documentation](https://docs.ditto.live/dql/dql)",
+    "",
+  );
+  out.push(
+    `_Generated by \`dittosh tutorial\` on ${ctx.generatedOn} for ${ctx.platform} (installed through ${channelName(ctx.channel)})._`,
+    "",
+  );
+  return out.join("\n");
+}
diff --git a/src/tutorial/lesson-eval.ts b/src/tutorial/lesson-eval.ts
new file mode 100644
index 0000000..5f1bda9
--- /dev/null
+++ b/src/tutorial/lesson-eval.ts
@@ -0,0 +1,154 @@
+import { Recoverable } from "node:repl";
+import chalk from "chalk";
+import {
+  endsInsideStringLiteral,
+  isBlankOrComments,
+  splitComplete,
+  splitStatements,
+  stripLiteralsAndComments,
+} from "../query/split.js";
+import type { LessonRunner } from "./runner.js";
+
+type ReplCallback = (err: Error | null, result?: unknown) => void;
+
+/** Words a statement can't end on — Enter after one continues to the next line. */
+const CONTINUATION_WORDS = new Set([
+  "select",
+  "from",
+  "where",
+  "and",
+  "or",
+  "not",
+  "by",
+  "order",
+  "group",
+  "having",
+  "on",
+  "join",
+  "set",
+  "into",
+  "documents",
+  "values",
+  "as",
+  "in",
+  "like",
+  "between",
+  "limit",
+  "offset",
+  "use",
+  "ids",
+  "update",
+  "evict",
+  "delete",
+  "insert",
+  "explain",
+  "profile",
+  "distinct",
+  "with",
+  "is",
+  "any",
+  "every",
+  "satisfies",
+  "case",
+  "when",
+  "then",
+  "else",
+]);
+
+/**
+ * True when the text is obviously unfinished: inside a string, unbalanced
+ * brackets, or ending on a comma, an operator, or a keyword like WHERE.
+ */
+export function looksUnfinished(text: string): boolean {
+  if (endsInsideStringLiteral(text)) return true;
+  const code = stripLiteralsAndComments(text);
+  let depth = 0;
+  for (const ch of code) {
+    if (ch === "(" || ch === "[" || ch === "{") depth++;
+    else if (ch === ")" || ch === "]" || ch === "}") depth--;
+  }
+  if (depth > 0) return true;
+  const tail = code.trimEnd();
+  if (/[,=<>+\-*/%|.:]$/.test(tail)) return true;
+  const lastWord = /([A-Za-z_]+)$/.exec(tail)?.[1]?.toLowerCase();
+  return lastWord !== undefined && CONTINUATION_WORDS.has(lastWord);
+}
+
+/** The statements in one submitted input (`;`-separated; the last `;` is optional). */
+export function splitInput(text: string): string[] {
+  const { statements, rest } = splitComplete(text);
+  return [...statements, ...splitStatements(rest)];
+}
+
+/**
+ * node:repl eval for the lesson shell. Enter runs the statement — a `;` is
+ * optional. Input continues on a `|` prompt only while it looks unfinished
+ * (open quote/bracket, trailing comma, operator, or keyword).
+ *
+ * After a Recoverable, node re-sends the whole accumulated input, so each
+ * call sees the full text. Statements are serialized through a promise chain
+ * because node:repl doesn't pause input for async evals.
+ */
+export function makeLessonEval(runner: Pick<LessonRunner, "submit">) {
+  let chain: Promise<void> = Promise.resolve();
+
+  const report = (err: unknown) => {
+    console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+  };
+  /** Run after everything queued so far; errors are reported, not thrown. */
+  const enqueue = (task: () => unknown): Promise<void> => {
+    chain = chain
+      .then(async () => {
+        await task();
+      })
+      .catch(report);
+    return chain;
+  };
+
+  return {
+    reset: () => {},
+    /** Resolves once every queued statement and command has finished. */
+    drain: () => chain,
+    /**
+     * Queue a dot-command's action behind any statement still running, so
+     * \`.next\` or \`.reset\` can't interleave with a statement being checked.
+     */
+    enqueue,
+    eval: (cmd: string, _ctx: unknown, _file: string, cb: ReplCallback) => {
+      const text = cmd.replace(/\n$/, "");
+      if (isBlankOrComments(text)) {
+        cb(null);
+        return;
+      }
+      if (looksUnfinished(text)) {
+        cb(new Recoverable(new Error("incomplete statement")));
+        return;
+      }
+      const all = splitInput(text);
+      enqueue(() => submitAll(runner, all)).then(() => cb(null));
+    },
+  };
+}
+
+/**
+ * Submit statements in order, stopping once one passes: the lesson has moved
+ * on, so the rest would be graded against a task the learner hasn't seen.
+ * Returns how many were skipped.
+ */
+export async function submitAll(
+  runner: Pick<LessonRunner, "submit">,
+  statements: readonly string[],
+  onSkipped: (n: number) => void = (n) =>
+    console.error(
+      chalk.dim(`Skipped ${n} more statement${n === 1 ? "" : "s"}: the lesson passed.`),
+    ),
+): Promise<number> {
+  for (const [i, s] of statements.entries()) {
+    if (await runner.submit(s)) {
+      const skipped = statements.length - i - 1;
+      if (skipped > 0) onSkipped(skipped);
+      return skipped;
+    }
+  }
+  return 0;
+}
diff --git a/src/tutorial/lessons.ts b/src/tutorial/lessons.ts
new file mode 100644
index 0000000..d94034e
--- /dev/null
+++ b/src/tutorial/lessons.ts
@@ -0,0 +1,875 @@
+import type { StatementKind } from "../query/execute.js";
+
+/**
+ * Interactive DQL lessons for `dittosh tutorial --interactive`, in three
+ * levels. Each lesson teaches a concept (what it is and why it matters, with
+ * an "if you know SQL" note), shows the syntax, then sets a task.
+ *
+ * Every lesson runs against a practice store seeded by RESET_STATEMENTS.
+ * Checks inspect the result rows (or, for writes, re-query the store), so any
+ * correct statement passes — not just the sample answer. Every sample answer
+ * is verified against the real SDK in tests/integration/lessons.test.ts.
+ */
+
+export type Level = "beginner" | "intermediate" | "advanced";
+export const LEVELS: readonly Level[] = ["beginner", "intermediate", "advanced"];
+
+export type CheckResult = { pass: true } | { pass: false; reason: string };
+
+export interface LessonCheckContext {
+  statement: string;
+  kind: StatementKind;
+  rows: Record<string, unknown>[];
+  /** Run a read-only follow-up query against the practice store. */
+  query: (statement: string) => Promise<Record<string, unknown>[]>;
+}
+
+export interface Lesson {
+  level: Level;
+  title: string;
+  /** The idea: what it is and why it matters. `code` spans are highlighted. */
+  concept: string;
+  /** Optional comparison for readers who know SQL. */
+  sql?: string;
+  /** Syntax examples, one per line. */
+  syntax: string[];
+  /** What to do. */
+  task: string;
+  hint: string;
+  /** A sample statement that passes. */
+  answer: string;
+  /** Statements run when the lesson starts, so lessons work in any order. */
+  setup?: string[];
+  check: (ctx: LessonCheckContext) => CheckResult | Promise<CheckResult>;
+  /** Shown after a pass: the takeaway. */
+  success: string;
+}
+
+export const SEED_PRODUCTS = [
+  {
+    _id: "p1",
+    name: "Coffee beans",
+    category: "coffee",
+    price: 12.5,
+    stock: 20,
+    tags: ["organic", "fair-trade"],
+    details: { origin: "Colombia", roast: "dark" },
+    supplier_id: "s1",
+  },
+  {
+    _id: "p2",
+    name: "Paper filters",
+    category: "coffee",
+    price: 5,
+    stock: 100,
+    tags: [],
+    supplier_id: "s2",
+  },
+  {
+    _id: "p3",
+    name: "Green tea",
+    category: "tea",
+    price: 9,
+    stock: 30,
+    tags: ["organic"],
+    details: { origin: "Japan" },
+    supplier_id: "s3",
+  },
+  {
+    _id: "p4",
+    name: "Espresso blend",
+    category: "coffee",
+    price: 15,
+    stock: 0,
+    tags: ["fair-trade"],
+    details: { origin: "Brazil", roast: "medium" },
+    supplier_id: "s1",
+    discount: 0.1,
+  },
+  {
+    _id: "p5",
+    name: "Chai spices",
+    category: "tea",
+    price: 7.25,
+    stock: 45,
+    tags: ["organic", "spicy"],
+    supplier_id: "s3",
+    discount: null,
+  },
+  {
+    _id: "p6",
+    name: "Travel mug",
+    category: "accessories",
+    price: 18,
+    stock: 12,
+    tags: [],
+    // No supplier s4 exists: the outer-join lesson finds this product.
+    supplier_id: "s4",
+  },
+] as const;
+
+export const SEED_SUPPLIERS = [
+  { _id: "s1", name: "Andes Roasters", country: "Colombia" },
+  { _id: "s2", name: "Kitchen Goods Co", country: "USA" },
+  { _id: "s3", name: "Leaf & Spice", country: "India" },
+] as const;
+
+export const SEED_ORDERS = [
+  {
+    _id: "o1",
+    lines: [
+      { sku: "p1", qty: 2 },
+      { sku: "p2", qty: 1 },
+    ],
+  },
+  {
+    _id: "o2",
+    lines: [
+      { sku: "p1", qty: 1 },
+      { sku: "p3", qty: 5 },
+    ],
+  },
+  { _id: "o3", lines: [{ sku: "p5", qty: 3 }] },
+] as const;
+
+export const PRACTICE_INDEX = "idx_products_category";
+export const COMPOSITE_INDEX = "idx_products_category_price";
+
+/** DQL object literal (single-quoted strings) for a plain JSON value. */
+function dqlLiteral(v: unknown): string {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return `[${v.map(dqlLiteral).join(", ")}]`;
+  if (typeof v === "object") {
+    return `{${Object.entries(v as object)
+      .map(([k, x]) => `'${k}': ${dqlLiteral(x)}`)
+      .join(", ")}}`;
+  }
+  if (typeof v === "string") return `'${v.replaceAll("'", "''")}'`;
+  return String(v);
+}
+
+function insertAll(collection: string, docs: readonly object[]): string {
+  return `INSERT INTO ${collection} VALUES ${docs.map((d) => `(${dqlLiteral(d)})`).join(", ")} ON ID CONFLICT DO UPDATE`;
+}
+
+/** Restore the practice data exactly (`.reset`, and every start). */
+export const RESET_STATEMENTS = [
+  "EVICT FROM products",
+  "EVICT FROM suppliers",
+  "EVICT FROM orders",
+  `DROP INDEX IF EXISTS ${PRACTICE_INDEX} ON products`,
+  `DROP INDEX IF EXISTS ${COMPOSITE_INDEX} ON products`,
+  insertAll("products", SEED_PRODUCTS),
+  insertAll("suppliers", SEED_SUPPLIERS),
+  insertAll("orders", SEED_ORDERS),
+];
+
+const NAME_BY_ID = new Map<string, string>(SEED_PRODUCTS.map((p) => [p._id, p.name]));
+const ALL_NAMES = SEED_PRODUCTS.map((p) => p.name);
+
+/** Product names in the rows (via `name`, or mapped from `_id`), or undefined. */
+function productNames(rows: Record<string, unknown>[]): string[] | undefined {
+  const names: string[] = [];
+  for (const r of rows) {
+    if (typeof r.name === "string") names.push(r.name);
+    else if (typeof r._id === "string" && NAME_BY_ID.has(r._id)) names.push(NAME_BY_ID.get(r._id)!);
+    else return undefined;
+  }
+  return names;
+}
+
+function sameSet(a: readonly unknown[], b: readonly unknown[]): boolean {
+  const key = (xs: readonly unknown[]) => xs.map(String).sort().join("\u0000");
+  return a.length === b.length && key(a) === key(b);
+}
+
+const fail = (reason: string): CheckResult => ({ pass: false, reason });
+const pass: CheckResult = { pass: true };
+
+/** Pass when the rows name exactly `expected` (any order). */
+function expectProducts(rows: Record<string, unknown>[], expected: readonly string[]): CheckResult {
+  const names = productNames(rows);
+  if (!names) return fail("Include the `name` field (or `_id`) so each product can be identified.");
+  if (sameSet(names, expected)) return pass;
+  return fail(
+    `Expected ${expected.length} product${expected.length === 1 ? "" : "s"}, got ${names.length}: ${names.join(", ") || "none"}.`,
+  );
+}
+
+/** Every primitive value in the rows, flattened (alias-agnostic checks). */
+function allValues(rows: Record<string, unknown>[]): unknown[] {
+  const out: unknown[] = [];
+  const walk = (v: unknown) => {
+    if (Array.isArray(v)) v.forEach(walk);
+    else if (v && typeof v === "object") Object.values(v).forEach(walk);
+    else out.push(v);
+  };
+  rows.forEach(walk);
+  return out;
+}
+
+const near = (a: unknown, b: number) => typeof a === "number" && Math.abs(a - b) < 1e-9;
+
+function rowFor(rows: Record<string, unknown>[], name: string) {
+  return rows.find((r) => r.name === name);
+}
+
+export const LESSONS: Lesson[] = [
+  // ─── Beginner ───────────────────────────────────────────────────────────
+  {
+    level: "beginner",
+    title: "Documents and collections",
+    concept: `A Ditto database stores **documents**: self-describing records made of fields,
+like \`{ name: 'Green tea', price: 9 }\`. Documents are grouped into **collections**,
+and every document has a unique \`_id\`. A **query** asks the database for the
+documents you want; DQL (Ditto Query Language) is how you write one.
+
+Collection and field names are **case-sensitive**: \`products\` and \`Products\` are
+two different collections, and querying one that doesn't exist just returns
+nothing. Keywords like \`SELECT\` and \`FROM\` work in any case.`,
+    sql: "A collection is like a table and a document like a row, except documents in one collection don't need the same fields.",
+    syntax: ["SELECT * FROM collection"],
+    task: "Show every document in the `products` collection.",
+    hint: "`SELECT *` means every field; the collection's name goes after `FROM`.",
+    answer: "SELECT * FROM products",
+    check: ({ rows }) => expectProducts(rows, ALL_NAMES),
+    success: "Six documents. Notice the different shapes: some have `details`, some a `discount`.",
+  },
+  {
+    level: "beginner",
+    title: "Projection: choosing fields",
+    concept: `A **projection** decides the **shape** of each result: which fields come back, and
+under what names. It doesn't change **which** documents match — that's filtering,
+next lesson. Think of filtering as picking rows and projection as picking columns.
+Asking only for what you need keeps results small and readable.`,
+    sql: "Same as listing columns in SQL's SELECT clause.",
+    syntax: [
+      "SELECT name, country FROM suppliers",
+      "SELECT name AS supplier FROM suppliers   -- rename",
+    ],
+    task: "Show only the `name` and `price` of each product.",
+    hint: "Replace `*` with a comma-separated list of fields.",
+    answer: "SELECT name, price FROM products",
+    check: ({ rows }) => {
+      if (rows.length !== SEED_PRODUCTS.length) return fail("Return all six products.");
+      const keys = (r: Record<string, unknown>) => Object.keys(r).sort().join(",");
+      return rows.every((r) => keys(r) === "name,price")
+        ? pass
+        : fail("Each row should contain exactly two fields: `name` and `price`.");
+    },
+    success: "`AS` renames a field in the output: `SELECT name AS product FROM products`.",
+  },
+  {
+    level: "beginner",
+    title: "Filtering with predicates",
+    concept: `A **predicate** is a condition that is true or false for each document, such as
+\`category = 'tea'\`. \`WHERE\` evaluates the predicate against every document and keeps
+only those where it's true. Text values go in single quotes; numbers don't.`,
+    sql: "Identical to SQL's WHERE clause.",
+    syntax: [
+      "SELECT * FROM products WHERE category = 'tea'",
+      "SELECT * FROM products WHERE price > 10      -- also: = != < <= >=",
+    ],
+    task: "Find the products whose category is `coffee`, and show their names.",
+    hint: "Compare the `category` field to a text value in a WHERE clause — text goes in single quotes.",
+    answer: "SELECT name, price FROM products WHERE category = 'coffee'",
+    check: ({ rows }) => expectProducts(rows, ["Coffee beans", "Paper filters", "Espresso blend"]),
+    success: "Filtering (WHERE) and projection (SELECT list) combine freely in one query.",
+  },
+  {
+    level: "beginner",
+    title: "Combining conditions",
+    concept: `Predicates combine with **boolean logic**: \`AND\` (both must be true), \`OR\` (either
+is enough), and \`NOT\` (flips true and false). \`AND\` binds tighter than \`OR\`, so use
+parentheses to make your intent clear. Shortcuts: \`BETWEEN low AND high\`
+(inclusive), \`IN [list]\`, and \`LIKE\` with \`%\` as a wildcard.`,
+    sql: "The same operators as SQL; DQL writes IN lists with square brackets.",
+    syntax: [
+      "SELECT name, stock FROM products WHERE stock BETWEEN 10 AND 40",
+      "WHERE category = 'tea' AND price < 8",
+      "WHERE (category = 'tea' OR category = 'coffee') AND stock > 0",
+      "WHERE category IN ['tea', 'accessories']",
+      "WHERE name LIKE '%tea%'",
+    ],
+    task: "Find the products that cost between 5 and 10 (including exactly 5 or 10), and show their names.",
+    hint: "`BETWEEN low AND high` includes both ends — or combine `>=` and `<=` with AND.",
+    answer: "SELECT name, price FROM products WHERE price BETWEEN 5 AND 10",
+    check: ({ rows }) => expectProducts(rows, ["Paper filters", "Green tea", "Chai spices"]),
+    success: "`BETWEEN` includes both ends, so Paper filters, at exactly 5, made the cut.",
+  },
+  {
+    level: "beginner",
+    title: "Sorting and limiting",
+    concept: `Results have **no guaranteed order** unless you ask for one. \`ORDER BY\` sorts by
+one or more fields — ascending by default, \`DESC\` for descending. \`LIMIT n\` keeps
+only the first n results, and \`OFFSET n\` skips some first (useful for paging).`,
+    sql: "Same as SQL's ORDER BY / LIMIT / OFFSET.",
+    syntax: [
+      "SELECT name, price FROM products ORDER BY price",
+      "SELECT name, stock FROM products ORDER BY stock DESC LIMIT 3",
+    ],
+    task: "Show the names of the two most expensive products, with the most expensive first.",
+    hint: "Sort high-to-low with `DESC`, then keep only the first rows with `LIMIT`.",
+    answer: "SELECT name, price FROM products ORDER BY price DESC LIMIT 2",
+    check: ({ rows }) => {
+      const names = productNames(rows);
+      if (!names) return fail("Include the `name` field.");
+      return names.join("|") === "Travel mug|Espresso blend"
+        ? pass
+        : fail(`Expected Travel mug, then Espresso blend — got ${names.join(", ") || "nothing"}.`);
+    },
+    success: "Add `LIMIT` to exploratory queries so large collections stay fast.",
+  },
+  {
+    level: "beginner",
+    title: "Inserting documents",
+    concept: `Queries read data; **statements** like INSERT, UPDATE, and EVICT change it.
+\`INSERT INTO … VALUES (…)\` adds documents written as object literals — one or
+more, separated by commas. If a document with that \`_id\` already exists, the
+insert fails — unless you add \`ON ID CONFLICT DO UPDATE\`, which makes the
+insert safe to repeat. (Older examples use \`DOCUMENTS\` in place of \`VALUES\`;
+the two work the same.)`,
+    sql: "The same INSERT … VALUES you know, except each value is a whole document rather than a row of columns.",
+    syntax: [
+      "INSERT INTO products VALUES ({'_id': 'p9', 'name': 'Kettle', 'price': 30})",
+      "… ON ID CONFLICT DO UPDATE   -- upsert",
+    ],
+    task: "Insert a new product with `_id` 'p7', name 'Cold brew kit', category 'coffee', and price 25.",
+    hint: "Write the fields as `'key': value` pairs inside `({ … })` — text in single quotes, numbers without.",
+    answer:
+      "INSERT INTO products VALUES ({'_id': 'p7', 'name': 'Cold brew kit', 'category': 'coffee', 'price': 25})",
+    setup: ["EVICT FROM products WHERE _id = 'p7'"],
+    check: async ({ query }) => {
+      const [doc] = await query("SELECT * FROM products WHERE _id = 'p7'");
+      if (!doc) return fail("No document with `_id` 'p7' yet.");
+      if (doc.name !== "Cold brew kit" || doc.category !== "coffee" || doc.price !== 25) {
+        return fail("p7 exists, but check its name, category, and price.");
+      }
+      return pass;
+    },
+    success: "Writes are saved locally at once. On a syncing device, peers would receive them.",
+  },
+  {
+    level: "beginner",
+    title: "Updating documents",
+    concept: `\`UPDATE … SET field = value WHERE …\` changes the documents the predicate matches.
+The new value can be computed from the old one (\`stock = stock + 10\`), and nested
+fields work too (\`SET details.roast = 'light'\`). **Always include WHERE** — without
+it, every document in the collection changes.`,
+    sql: "Same as SQL UPDATE.",
+    syntax: [
+      "UPDATE products SET price = 10 WHERE _id = 'p3'",
+      "UPDATE products SET stock = stock + 5 WHERE category = 'tea'",
+    ],
+    task: "The Espresso blend (`_id` 'p4') has been restocked. Set its `stock` to 25.",
+    hint: "SET the field to its new value, and use WHERE on `_id` so only that one document changes.",
+    answer: "UPDATE products SET stock = 25 WHERE _id = 'p4'",
+    setup: ["UPDATE products SET stock = 0 WHERE _id = 'p4'"],
+    check: async ({ query }) => {
+      const [doc] = await query("SELECT stock FROM products WHERE _id = 'p4'");
+      return doc?.stock === 25 ? pass : fail(`p4's stock is ${String(doc?.stock)}, not 25.`);
+    },
+    success: "Ditto merges concurrent updates from different devices field by field.",
+  },
+  {
+    level: "beginner",
+    title: "Removing local data",
+    concept: `\`EVICT FROM … WHERE …\` removes documents from **this device's** store only.
+That's different from \`DELETE\`, which is synchronized: it tells every peer the
+document is gone. This CLI is offline-only, so here both affect just your store.`,
+    sql: "EVICT has no SQL equivalent; DELETE is the closest.",
+    syntax: ["EVICT FROM products WHERE _id = 'p9'"],
+    task: "Evict the Cold brew kit (`_id` 'p7') from the local store.",
+    hint: "`EVICT FROM` the collection, with a WHERE that matches only that `_id`.",
+    answer: "EVICT FROM products WHERE _id = 'p7'",
+    setup: [
+      "INSERT INTO products VALUES ({'_id': 'p7', 'name': 'Cold brew kit', 'category': 'coffee', 'price': 25}) ON ID CONFLICT DO UPDATE",
+    ],
+    check: async ({ query }) => {
+      const rows = await query("SELECT _id FROM products WHERE _id = 'p7'");
+      return rows.length === 0 ? pass : fail("p7 is still in the store.");
+    },
+    success: "That's the beginner level: read, filter, shape, sort, and write documents.",
+  },
+
+  // ─── Intermediate ───────────────────────────────────────────────────────
+  {
+    level: "intermediate",
+    title: "Expressions and functions",
+    concept: `An **expression** computes a value for each document, such as \`price * 2\` or
+\`stock - 1\`. A **function** is a named operation that takes inputs (arguments) and
+returns a value: \`upper(name)\` turns 'Green tea' into 'GREEN TEA'. These are
+**scalar** functions — they run once per document. Others: \`lower\`, \`length\`,
+\`concat\`, \`round\`. Name a computed column with \`AS\`.`,
+    sql: "Scalar functions and expressions work as in SQL.",
+    syntax: [
+      "SELECT name, price * 1.2 AS with_tax FROM products",
+      "SELECT concat(name, ' (', category, ')') AS label FROM products",
+      "SELECT round(price / 3, 2) AS third FROM products",
+    ],
+    task: "Show the name of every product in upper case.",
+    hint: "DQL has text functions such as `lower()` and `upper()` — call one on `name` in the SELECT list.",
+    answer: "SELECT name, upper(name) AS shout FROM products",
+    check: ({ rows }) => {
+      if (rows.length !== SEED_PRODUCTS.length) return fail("Return all six products.");
+      return allValues(rows).includes("COFFEE BEANS")
+        ? pass
+        : fail("Expected values like 'COFFEE BEANS' — use `upper(name)`.");
+    },
+    success: "Functions nest: `length(upper(name))` passes one function's result to another.",
+  },
+  {
+    level: "intermediate",
+    title: "Conditional values with CASE",
+    concept: `\`CASE\` is an if/else expression: it checks conditions in order and returns the
+value of the first one that's true, or the \`ELSE\` value. It's handy for labels
+and buckets.`,
+    sql: "Same as SQL's searched CASE expression.",
+    syntax: [
+      "SELECT name, CASE WHEN price >= 10 THEN 'premium' ELSE 'standard' END AS tier FROM products",
+      "CASE WHEN condition THEN value WHEN … THEN … ELSE value END   -- the general form",
+    ],
+    task: "For each product, show its name and a label: 'in stock' if its stock is above 0, otherwise 'sold out'.",
+    hint: "Inside `CASE WHEN … THEN … ELSE … END`, test `stock > 0`, and name the result with `AS`.",
+    answer:
+      "SELECT name, CASE WHEN stock > 0 THEN 'in stock' ELSE 'sold out' END AS availability FROM products",
+    setup: ["UPDATE products SET stock = 0 WHERE _id = 'p4'"],
+    check: ({ rows }) => {
+      if (rows.length !== SEED_PRODUCTS.length) return fail("Return all six products.");
+      const espresso = rowFor(rows, "Espresso blend");
+      const tea = rowFor(rows, "Green tea");
+      if (!espresso || !tea) return fail("Include the `name` field.");
+      if (!Object.values(espresso).includes("sold out"))
+        return fail("The Espresso blend (stock 0) should be labeled 'sold out'.");
+      if (!Object.values(tea).includes("in stock"))
+        return fail("Products with stock should be labeled 'in stock'.");
+      return pass;
+    },
+    success: "CASE works anywhere an expression does: in WHERE, ORDER BY, even inside functions.",
+  },
+  {
+    level: "intermediate",
+    title: "MISSING versus NULL",
+    concept: `Because documents can differ, a field can be absent in two ways. **MISSING**
+means the document doesn't have the field at all. **NULL** means the field exists
+but holds no value. \`IS MISSING\` / \`IS NOT MISSING\` and \`IS NULL\` / \`IS NOT NULL\`
+test each case. In the practice data, only the Espresso blend has a real
+discount, the Chai spices has \`discount: null\`, and the rest have no discount
+field.`,
+    sql: "SQL has only NULL; MISSING is unique to document databases.",
+    syntax: [
+      "SELECT name, details FROM products WHERE details IS MISSING",
+      "WHERE details IS NOT MISSING",
+      "WHERE field IS NULL",
+    ],
+    task: "Find the product whose `discount` is NULL (the field is there but empty), and show its name.",
+    hint: "MISSING means the field isn't there; NULL means it's there but empty. You want NULL.",
+    answer: "SELECT name, discount FROM products WHERE discount IS NULL",
+    check: ({ rows }) => expectProducts(rows, ["Chai spices"]),
+    success: "`IS MISSING` would have found the other four, which have no discount field at all.",
+  },
+  {
+    level: "intermediate",
+    title: "Defaults with coalesce",
+    concept: `Arithmetic on a missing or null value has no result, so \`price * (1 - discount)\`
+yields nothing for products without a discount. \`coalesce(a, b, …)\` returns its
+first argument that has a value, so \`coalesce(discount, 0)\` supplies a default.`,
+    sql: "Same as SQL's COALESCE.",
+    syntax: [
+      "coalesce(value, fallback)   -- the first one that isn't NULL or MISSING",
+      "SELECT name, coalesce(details.roast, 'none') AS roast FROM products",
+    ],
+    task: "Show each product's name and its sale price, `price * (1 - discount)`. Treat a missing or NULL discount as 0.",
+    hint: "`coalesce(discount, 0)` is 0 when there's no discount — use it in place of `discount` in the formula.",
+    answer:
+      "SELECT name, price * (1 - coalesce(discount, 0)) AS sale_price FROM products ORDER BY sale_price",
+    check: ({ rows }) => {
+      if (rows.length !== SEED_PRODUCTS.length) return fail("Return all six products.");
+      const values = allValues(rows);
+      if (!values.some((v) => near(v, 13.5)))
+        return fail("The Espresso blend should cost 13.5 after its 10% discount.");
+      if (!values.some((v) => near(v, 7.25)))
+        return fail("Chai spices (null discount) should keep its 7.25 price — use `coalesce`.");
+      return pass;
+    },
+    success: "Without coalesce, five of the six products would have no sale price.",
+  },
+  {
+    level: "intermediate",
+    title: "Nested objects",
+    concept: `Fields can hold objects, which keeps related data together in one document.
+Some products have a \`details\` object holding their \`origin\` and \`roast\`:
+
+  { name: 'Espresso blend', details: { origin: 'Brazil', roast: 'medium' } }
+
+Reach inside with a **dot path**: \`details.origin\`. Dot paths work in projections,
+predicates, sorting, and indexes.`,
+    sql: "Like reading a JSON column, but without special JSON functions.",
+    syntax: ["SELECT name, details.roast FROM products WHERE details.origin = 'Brazil'"],
+    task: "Show the name and origin of each product whose `details` has a `dark` roast.",
+    hint: "Reach into the nested object with a dot: `details.roast` and `details.origin`.",
+    answer: "SELECT name, details.origin FROM products WHERE details.roast = 'dark'",
+    check: ({ rows }) => {
+      if (rows.length !== 1) return fail("Exactly one product has a dark roast.");
+      return allValues(rows).includes("Colombia")
+        ? pass
+        : fail("Include the origin (`details.origin`) in the result.");
+    },
+    success: "Updates use the same paths: `UPDATE products SET details.roast = 'light' WHERE …`.",
+  },
+  {
+    level: "intermediate",
+    title: "Arrays",
+    concept: `A field can hold an **array** (a list), like \`tags\`. Array functions inspect it:
+\`array_contains(tags, 'spicy')\` tests for a value and \`array_length(tags)\` counts
+the elements. \`tags[0]\` reads the first element.`,
+    sql: "Similar to PostgreSQL arrays.",
+    syntax: [
+      "WHERE array_contains(tags, 'fair-trade')",
+      "SELECT name, tags[0] AS first_tag FROM products WHERE array_length(tags) > 0",
+    ],
+    task: "Find the products tagged `organic`, and show their names.",
+    hint: "`array_contains(array, value)` is true when the array holds that value.",
+    answer: "SELECT name, tags FROM products WHERE array_contains(tags, 'organic')",
+    check: ({ rows }) => expectProducts(rows, ["Coffee beans", "Green tea", "Chai spices"]),
+    success: "Arrays are values too — you can return them, as you just did with `tags`.",
+  },
+  {
+    level: "intermediate",
+    title: "Aggregate functions",
+    concept: `Scalar functions run once per document. **Aggregate functions** do the opposite:
+they combine many documents into one value. \`count(*)\` counts documents,
+\`count(field)\` counts documents where the field has a value, and \`sum\`, \`avg\`,
+\`min\`, and \`max\` summarize numbers. Without GROUP BY, the whole result collapses
+into a single row.`,
+    sql: "Same aggregate functions as SQL.",
+    syntax: ["SELECT count(*) AS products, max(price) AS top_price FROM products"],
+    task: "In a single row, show the number of products and their average price.",
+    hint: "`count(*)` counts documents and `avg()` averages a field — both in one SELECT give a single row.",
+    answer: "SELECT count(*) AS products, avg(price) AS avg_price FROM products",
+    check: ({ rows }) => {
+      if (rows.length !== 1) return fail("Aggregates without GROUP BY return a single row.");
+      const values = allValues(rows);
+      if (!values.some((v) => v === SEED_PRODUCTS.length)) return fail("Include `count(*)` (6).");
+      return values.some((v) => near(v, 11.125)) ? pass : fail("Include `avg(price)` (11.125).");
+    },
+    success: "`count(discount)` would return 1: it skips missing and null values.",
+  },
+  {
+    level: "intermediate",
+    title: "Grouping",
+    concept: `\`GROUP BY field\` splits the documents into groups that share a value, then runs
+the aggregate functions once **per group**. Every field you select must be either
+grouped or aggregated.`,
+    sql: "Same as SQL GROUP BY.",
+    syntax: [
+      "SELECT country, count(*) AS suppliers FROM suppliers GROUP BY country",
+      "SELECT category, max(price) AS top_price FROM products GROUP BY category",
+    ],
+    task: "Show each category and how many products it has.",
+    hint: "GROUP BY the field you want one row for, and `count(*)` each group.",
+    answer: "SELECT category, count(*) AS products FROM products GROUP BY category",
+    check: ({ rows }) => {
+      const expected: Record<string, number> = { coffee: 3, tea: 2, accessories: 1 };
+      if (rows.length !== 3) return fail("Return one row per category (3 rows).");
+      for (const r of rows) {
+        const cat = r.category;
+        if (typeof cat !== "string" || !(cat in expected))
+          return fail("Include the `category` field.");
+        if (!Object.entries(r).some(([k, v]) => k !== "category" && v === expected[cat])) {
+          return fail(`The ${cat} row should count ${expected[cat]} products.`);
+        }
+      }
+      return pass;
+    },
+    success: "Add more aggregates to the same query: `avg(price)`, `sum(stock)`, …",
+  },
+  {
+    level: "intermediate",
+    title: "Filtering groups with HAVING",
+    concept: `\`WHERE\` filters documents **before** grouping. \`HAVING\` filters the groups **after**
+the aggregates are computed, so it can test them: \`HAVING sum(stock) > 50\`.`,
+    sql: "Same as SQL HAVING.",
+    syntax: [
+      "SELECT category, avg(price) AS avg_price FROM products GROUP BY category HAVING avg(price) > 10",
+    ],
+    task: "Show the categories whose total stock is more than 50 units.",
+    hint: "Total the stock per category with `sum(stock)`; HAVING keeps only the groups you want.",
+    answer:
+      "SELECT category, sum(stock) AS units FROM products GROUP BY category HAVING sum(stock) > 50",
+    setup: ["UPDATE products SET stock = 0 WHERE _id = 'p4'"],
+    check: ({ rows }) => {
+      const cats = rows.map((r) => r.category);
+      if (cats.some((c) => typeof c !== "string")) return fail("Include the `category` field.");
+      return sameSet(cats, ["coffee", "tea"])
+        ? pass
+        : fail(`Expected coffee (120 units) and tea (75) — got ${cats.join(", ") || "none"}.`);
+    },
+    success: "Accessories (12 units) was grouped, then removed by HAVING.",
+  },
+  {
+    level: "intermediate",
+    title: "Removing duplicates with DISTINCT",
+    concept: `\`SELECT DISTINCT\` removes duplicate result rows, so each combination of the
+selected values appears once. It's a quick way to see which values a field takes.`,
+    sql: "Same as SQL DISTINCT.",
+    syntax: ["SELECT DISTINCT supplier_id FROM products"],
+    task: "List each category once, with no duplicates.",
+    hint: "`DISTINCT` goes right after SELECT.",
+    answer: "SELECT DISTINCT category FROM products",
+    check: ({ rows }) =>
+      sameSet(
+        rows.map((r) => r.category),
+        ["coffee", "tea", "accessories"],
+      )
+        ? pass
+        : fail("Expected three rows: coffee, tea, and accessories."),
+    success:
+      "That's the intermediate level: expressions, functions, missing data, and aggregation.",
+  },
+
+  // ─── Advanced ───────────────────────────────────────────────────────────
+  {
+    level: "advanced",
+    title: "Joining collections",
+    concept: `Related data often lives in separate collections: products store a
+\`supplier_id\` that points at a document in \`suppliers\`. A **join** combines them by
+matching rows on a condition. An **inner join** returns only the pairs that match;
+give each collection an alias (\`p\`, \`s\`) to say which fields you mean.`,
+    sql: "Same as SQL INNER JOIN … ON.",
+    syntax: [
+      "SELECT a.field, b.field AS other",
+      "FROM collection_a AS a INNER JOIN collection_b AS b ON a.key = b._id",
+    ],
+    task: "Show each product's name together with the name of its supplier.",
+    hint: "Each product has a `supplier_id`; match it to the supplier's `_id`.",
+    answer:
+      "SELECT p.name, s.name AS supplier FROM products AS p INNER JOIN suppliers AS s ON p.supplier_id = s._id",
+    check: ({ rows }) => {
+      const values = allValues(rows);
+      if (!values.includes("Andes Roasters")) return fail("Include the supplier's name.");
+      if (!values.includes("Coffee beans")) return fail("Include the product's name.");
+      return rows.length === 5
+        ? pass
+        : fail(
+            `An inner join returns 5 rows here (one product's supplier doesn't exist) — got ${rows.length}.`,
+          );
+    },
+    success: "Only 5 rows: the Travel mug points at supplier s4, which doesn't exist.",
+  },
+  {
+    level: "advanced",
+    title: "Outer joins",
+    concept: `A **left (outer) join** keeps every row from the left collection, even when nothing
+matches on the right; the right side's fields are then missing. Filtering for
+that missing side finds orphans — an **anti-join**.`,
+    sql: "Same as SQL LEFT JOIN; DQL tests the unmatched side with IS MISSING.",
+    syntax: [
+      "SELECT … FROM a LEFT JOIN b ON a.key = b._id   -- keeps every row of a",
+      "-- rows of a with no match have b's fields MISSING",
+    ],
+    task: "Find the products whose supplier doesn't exist, and show their names.",
+    hint: "LEFT JOIN products to suppliers, then keep the rows where the supplier's `_id` IS MISSING.",
+    answer:
+      "SELECT p.name FROM products AS p LEFT JOIN suppliers AS s ON p.supplier_id = s._id WHERE s._id IS MISSING",
+    check: ({ rows }) => expectProducts(rows, ["Travel mug"]),
+    success: "Anti-joins are a quick data-quality check for broken references.",
+  },
+  {
+    level: "advanced",
+    title: "Conditions on array elements: ANY … SATISFIES",
+    concept: `\`array_contains\` tests for a simple value, but arrays often hold objects — like
+the \`lines\` of an order, each with a \`sku\` and a \`qty\`. A **quantified predicate**
+tests the elements one at a time: \`ANY l IN lines SATISFIES <condition> END\` is
+true when at least one element meets the whole condition. (\`EVERY … SATISFIES\`
+requires all of them.) The \`orders\` collection has three orders.`,
+    sql: "Like an EXISTS subquery over a child table, written inline.",
+    syntax: [
+      "SELECT _id FROM orders WHERE ANY l IN lines SATISFIES l.sku = 'p3' END",
+      "… SATISFIES l.sku = 'p5' AND l.qty > 1 END   -- both on the same element",
+    ],
+    task: "Find the orders that have a line for product 'p1' with a quantity of exactly 2, and show their `_id`.",
+    hint: "Put both conditions, on `l.sku` and on `l.qty`, inside one SATISFIES with AND.",
+    answer: "SELECT _id FROM orders WHERE ANY l IN lines SATISFIES l.sku = 'p1' AND l.qty = 2 END",
+    check: ({ rows }) => {
+      const ids = rows.map((r) => r._id);
+      if (ids.some((id) => typeof id !== "string")) return fail("Include the orders' `_id`.");
+      return sameSet(ids, ["o1"])
+        ? pass
+        : fail(
+            `Only o1 has a single line with 2 × p1 — got ${ids.join(", ") || "none"}. Both conditions must hold for the same line.`,
+          );
+    },
+    success:
+      "Order o2 also contains p1, but with quantity 1 — SATISFIES checks both conditions on each line together.",
+  },
+  {
+    level: "advanced",
+    title: "Indexes",
+    concept: `Without an **index**, a filter has to read every document in the collection (a
+**scan**). An index is a sorted lookup structure on one or more fields — like the
+index at the back of a book — so matching documents can be found directly. Indexes
+speed up reads but take space and make writes slightly slower, so add them for the
+queries you run often.`,
+    sql: "Same idea as SQL CREATE INDEX.",
+    syntax: [
+      "CREATE INDEX IF NOT EXISTS name ON collection (field)",
+      "SELECT * FROM system:indexes",
+    ],
+    task: `Create an index named \`${PRACTICE_INDEX}\` on the \`category\` field of \`products\`.`,
+    hint: "`CREATE INDEX IF NOT EXISTS <name> ON <collection> (<field>)`.",
+    answer: `CREATE INDEX IF NOT EXISTS ${PRACTICE_INDEX} ON products (category)`,
+    setup: [
+      `DROP INDEX IF EXISTS ${PRACTICE_INDEX} ON products`,
+      `DROP INDEX IF EXISTS ${COMPOSITE_INDEX} ON products`,
+    ],
+    check: async ({ query }) => {
+      const rows = await query("SELECT * FROM system:indexes");
+      const index = rows.find((r) => String(r._id).endsWith(PRACTICE_INDEX));
+      if (!index) return fail(`No index named \`${PRACTICE_INDEX}\` yet.`);
+      return index.collection === "products" &&
+        JSON.stringify(index.fields ?? "").includes('"category"')
+        ? pass
+        : fail(`\`${PRACTICE_INDEX}\` exists, but it should be on \`products (category)\`.`);
+    },
+    success:
+      "`system:indexes` is a virtual collection: you query the database's own metadata with DQL.",
+  },
+  {
+    level: "advanced",
+    title: "Composite indexes and sort order",
+    concept: `A **composite index** covers several fields, in order, and each key can have its
+own direction. An index on \`(category ASC, price DESC)\` keeps products grouped by
+category with the most expensive first — so a query that sorts the same way can
+read results straight from the index instead of sorting them.`,
+    sql: "Same as a multi-column SQL index with per-column ASC/DESC.",
+    syntax: [
+      "CREATE INDEX IF NOT EXISTS idx_name ON collection (field_a ASC, field_b DESC)",
+      "SELECT … ORDER BY field_a ASC, field_b DESC   -- matches the index",
+    ],
+    task: `Create the index \`${COMPOSITE_INDEX}\` on \`(category ASC, price DESC)\`. Then list the products sorted by category, with the most expensive first within each category.`,
+    hint: "Two statements: CREATE INDEX on `(category ASC, price DESC)`, then a SELECT whose ORDER BY matches it.",
+    answer: "SELECT name, category, price FROM products ORDER BY category ASC, price DESC",
+    setup: [`CREATE INDEX IF NOT EXISTS ${COMPOSITE_INDEX} ON products (category ASC, price DESC)`],
+    check: async ({ rows, kind, query }) => {
+      const indexes = await query("SELECT * FROM system:indexes");
+      if (!indexes.some((r) => String(r._id).endsWith(COMPOSITE_INDEX))) {
+        return fail(`Create the index \`${COMPOSITE_INDEX}\` first.`);
+      }
+      if (kind !== "select")
+        return fail("Now run the SELECT with `ORDER BY category ASC, price DESC`.");
+      const names = productNames(rows);
+      if (!names) return fail("Include the `name` field.");
+      const expected = [
+        "Travel mug",
+        "Espresso blend",
+        "Coffee beans",
+        "Paper filters",
+        "Green tea",
+        "Chai spices",
+      ];
+      return names.join("|") === expected.join("|")
+        ? pass
+        : fail(`Expected: ${expected.join(", ")}.`);
+    },
+    success: "Run it with EXPLAIN to see the indexScan feeding the results in order.",
+  },
+  {
+    level: "advanced",
+    title: "Reading query plans with EXPLAIN",
+    concept: `Before running a query, Ditto's **planner** decides how to execute it: which
+index to use, in what order to filter, sort, and project. \`EXPLAIN\` shows that
+plan as a tree of **operators** without running the query. Look for \`indexScan\`
+(uses an index) versus \`scan\` (reads every document).`,
+    sql: "Like SQL EXPLAIN.",
+    syntax: ["EXPLAIN SELECT name FROM products WHERE price > 10"],
+    task: "Use EXPLAIN on a query that finds the products in the `tea` category, and check that the plan uses your index.",
+    hint: "Put `EXPLAIN` in front of a SELECT that filters on `category`.",
+    answer: "EXPLAIN SELECT name FROM products WHERE category = 'tea'",
+    setup: [`CREATE INDEX IF NOT EXISTS ${PRACTICE_INDEX} ON products (category)`],
+    check: ({ kind, rows }) => {
+      if (kind !== "explain") return fail("Start the statement with `EXPLAIN`.");
+      const plan = JSON.stringify(rows);
+      return plan.includes("indexScan")
+        ? pass
+        : fail("This plan doesn't use the index — filter on `category`.");
+    },
+    success: "Try EXPLAIN on `WHERE price > 10`: with no index on price, you'll see a full `scan`.",
+  },
+  {
+    level: "advanced",
+    title: "Measuring with PROFILE",
+    concept: `\`EXPLAIN\` shows the plan; \`PROFILE\` **runs** the query and measures each operator:
+how many documents went in and out, CPU time, time waiting on storage (\`stor\`), and
+how often it yielded to the scheduler. The slowest operator is the one to optimize.`,
+    sql: "Like EXPLAIN ANALYZE in PostgreSQL.",
+    syntax: ["PROFILE SELECT name FROM products WHERE category = 'tea'"],
+    task: "Use PROFILE on a SELECT that finds the products priced over 10.",
+    hint: "Put `PROFILE` in front of a SELECT that filters on `price`.",
+    answer: "PROFILE SELECT name FROM products WHERE price > 10",
+    check: ({ kind, rows }) => {
+      if (kind !== "profile") return fail("Start the statement with `PROFILE`.");
+      return rows.some((r) => "~request_profile" in r)
+        ? pass
+        : fail("No profile came back — PROFILE works with SELECT statements.");
+    },
+    success: 'Outside the tutorial, `dittosh dql --profile "SELECT …"` gives the same view.',
+  },
+  {
+    level: "advanced",
+    title: "Addressing documents with USE IDS",
+    concept: `When you already know the document IDs, \`USE IDS\` targets them directly instead
+of evaluating a WHERE predicate: \`UPDATE products USE IDS 'p1', 'p2' SET …\`,
+\`EVICT FROM products USE IDS 'p7'\`. It's the cheapest way to touch specific
+documents.`,
+    syntax: [
+      "UPDATE products USE IDS 'p3' SET stock = 40",
+      "SELECT name FROM products USE IDS 'p1'",
+    ],
+    task: "Evict the Cold brew kit (`_id` 'p7') using `USE IDS`.",
+    hint: "`EVICT FROM` the collection, then `USE IDS` with the kit's `_id`.",
+    answer: "EVICT FROM products USE IDS 'p7'",
+    setup: [
+      "INSERT INTO products VALUES ({'_id': 'p7', 'name': 'Cold brew kit', 'category': 'coffee', 'price': 25}) ON ID CONFLICT DO UPDATE",
+    ],
+    check: async ({ statement, query }) => {
+      if (!/\bUSE\s+IDS\b/i.test(statement))
+        return fail("Use `USE IDS 'p7'` instead of WHERE this time.");
+      const rows = await query("SELECT _id FROM products WHERE _id = 'p7'");
+      return rows.length === 0 ? pass : fail("p7 is still in the store.");
+    },
+    success: "USE IDS works with UPDATE, EVICT, and DELETE.",
+  },
+  {
+    level: "advanced",
+    title: "Inspecting the database with system collections",
+    concept: `Ditto exposes its own state as **virtual collections** in the \`system:\` namespace,
+queryable with ordinary DQL: \`system:indexes\`, \`system:collections\`,
+\`system:system_info\` (engine settings and storage facts), \`system:metrics\` (live
+counters and timings), and \`system:sync_degradations\` (documents that can't
+sync — always empty in this offline CLI).`,
+    syntax: [
+      "SELECT * FROM system:collections",
+      "SELECT DISTINCT namespace FROM system:system_info",
+      "SELECT key, current FROM system:metrics WHERE key LIKE 'ditto.query.%'",
+    ],
+    task: "List the storage-engine keys: the distinct `key` values in `system:system_info` whose `namespace` is 'backend_sqlite3'.",
+    hint: "Start from `SELECT DISTINCT key FROM system:system_info` and filter on `namespace`.",
+    answer: "SELECT DISTINCT key FROM system:system_info WHERE namespace = 'backend_sqlite3'",
+    check: ({ rows }) =>
+      allValues(rows).includes("wal_current_size_bytes")
+        ? pass
+        : fail(
+            "Expected keys such as `wal_current_size_bytes` — filter on `namespace = 'backend_sqlite3'`.",
+          ),
+    success: "In the regular shell, `.metrics` turns `system:metrics` into readable tables.",
+  },
+];
+
+/** Index of the first lesson at `level`. */
+export function firstLessonOf(level: Level, lessons: readonly Lesson[] = LESSONS): number {
+  return Math.max(
+    0,
+    lessons.findIndex((l) => l.level === level),
+  );
+}
diff --git a/src/tutorial/practice-store.ts b/src/tutorial/practice-store.ts
new file mode 100644
index 0000000..6bb5bcc
--- /dev/null
+++ b/src/tutorial/practice-store.ts
@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { expandTilde } from "../config/paths.js";
+
+/**
+ * The lessons reset their store on every lesson change (EVICT FROM products,
+ * suppliers, orders). A marker file records that a directory is a practice
+ * store, so `-d` can never point that reset at real data.
+ */
+export const PRACTICE_MARKER = ".dittosh-tutorial-store";
+
+/**
+ * The store directory for `tutorial -i`: the `-d` value when it's non-blank
+ * (commander keeps `=` from `-d=x`), otherwise the tutorial's own store.
+ * Never falls back to DITTOSH_DATA_DIR or the default dql store.
+ */
+export function practiceStoreDir(flag: string | undefined, tutorialDir: string): string {
+  const cleaned = flag?.replace(/^=/, "").trim();
+  return cleaned ? path.resolve(expandTilde(cleaned)) : tutorialDir;
+}
+
+export type PracticeStoreCheck = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Safe to use as a practice store: the tutorial's own directory, a directory
+ * that doesn't exist or is empty, or one already marked as a practice store.
+ */
+export function checkPracticeStore(dir: string, tutorialDir: string): PracticeStoreCheck {
+  if (path.resolve(dir) === path.resolve(tutorialDir)) return { ok: true };
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { ok: true };
+    return { ok: false, reason: `can't read ${dir}: ${(err as Error).message}` };
+  }
+  if (entries.length === 0 || entries.includes(PRACTICE_MARKER)) return { ok: true };
+  return {
+    ok: false,
+    reason: `${dir} isn't a lesson practice store. The lessons replace the products, suppliers, and orders collections in their store, so they only use an empty directory or one they created. Leave out --data-dir to use the lessons' own store.`,
+  };
+}
+
+/** Record that `dir` is a practice store (after the store has been opened). */
+export function markPracticeStore(dir: string): void {
+  try {
+    fs.writeFileSync(
+      path.join(dir, PRACTICE_MARKER),
+      "Created by `dittosh tutorial --interactive`. The lessons reset this store's data.\n",
+    );
+  } catch {
+    // Best effort: without the marker a later -d run refuses, which is safe.
+  }
+}
diff --git a/src/tutorial/runner.ts b/src/tutorial/runner.ts
new file mode 100644
index 0000000..e9e22bf
--- /dev/null
+++ b/src/tutorial/runner.ts
@@ -0,0 +1,519 @@
+import chalk from "chalk";
+import type { QueryExecutor } from "../ditto/session.js";
+import { extractProfile } from "../profile/parse.js";
+import { classify, extractRows } from "../query/execute.js";
+import { renderExplain } from "../render/explain.js";
+import { renderProfile } from "../render/profile.js";
+import { renderTable } from "../render/table.js";
+import {
+  firstLessonOf,
+  LESSONS,
+  LEVELS,
+  type Lesson,
+  type Level,
+  RESET_STATEMENTS,
+  SEED_ORDERS,
+  SEED_PRODUCTS,
+  SEED_SUPPLIERS,
+} from "./lessons.js";
+import {
+  type CollectionSchema,
+  caseMismatch,
+  collectionsIn,
+  inferSchema,
+  schemaLines,
+} from "./schema.js";
+
+/** Practice collections and every field name in them, for case-mismatch hints. */
+const KNOWN_NAMES = {
+  collections: ["products", "suppliers", "orders"],
+  fields: [
+    ...new Set(
+      inferSchema([...SEED_PRODUCTS, ...SEED_SUPPLIERS, ...SEED_ORDERS] as never).flatMap((f) =>
+        f.path.split(/\.|\[\]\.?/).filter(Boolean),
+      ),
+    ),
+  ],
+};
+
+/** Documents read per collection for the schema view. */
+const SCHEMA_SAMPLE = 200;
+
+export interface RunnerIO {
+  print: (text: string) => void;
+  /** Terminal width for tables and rules; undefined = unbounded. */
+  width: () => number | undefined;
+  /**
+   * Set by a UI that draws the lesson card itself: called (after the lesson's
+   * setup) instead of printing the card, and the welcome banner is skipped.
+   */
+  onLesson?: () => void;
+  /** Also called with each verdict line (✓ / ✗ / query error), for a status bar. */
+  onVerdict?: (text: string) => void;
+}
+
+export interface Progress {
+  lesson: number;
+  completed: number[];
+}
+
+export interface LessonRunnerOptions {
+  lessons?: readonly Lesson[];
+  io: RunnerIO;
+  progress?: Progress;
+  saveProgress?: (p: Progress) => void;
+}
+
+const LEVEL_LABEL: Record<Level, string> = {
+  beginner: "Beginner",
+  intermediate: "Intermediate",
+  advanced: "Advanced",
+};
+
+const MAX_RULE = 78;
+
+/** `code` → cyan, **bold** → bold. */
+export function highlight(text: string): string {
+  return text
+    .replace(/\*\*([^*]+)\*\*/g, (_, t: string) => chalk.bold(t))
+    .replace(/`([^`]+)`/g, (_, t: string) => chalk.cyan(t));
+}
+
+/**
+ * Drives the interactive lessons. UI-free except for `io.print`, so it is unit
+ * testable with a fake session; tutorial-repl.ts wires it to node:repl.
+ */
+export class LessonRunner {
+  readonly lessons: readonly Lesson[];
+  private index: number;
+  private readonly completed: Set<number>;
+  private readonly io: RunnerIO;
+  private readonly save: (p: Progress) => void;
+
+  constructor(
+    private readonly session: QueryExecutor,
+    opts: LessonRunnerOptions,
+  ) {
+    this.lessons = opts.lessons ?? LESSONS;
+    this.io = opts.io;
+    this.save = opts.saveProgress ?? (() => {});
+    const saved = opts.progress;
+    this.index =
+      saved && saved.lesson >= 0 && saved.lesson < this.lessons.length ? saved.lesson : 0;
+    this.completed = new Set(
+      (saved?.completed ?? []).filter((i) => i >= 0 && i < this.lessons.length),
+    );
+  }
+
+  get current(): number {
+    return this.index;
+  }
+
+  get completedCount(): number {
+    return this.completed.size;
+  }
+
+  private rule(): string {
+    return chalk.dim("─".repeat(Math.min(this.io.width() ?? MAX_RULE, MAX_RULE)));
+  }
+
+  private persist(): void {
+    this.save({ lesson: this.index, completed: [...this.completed].sort((a, b) => a - b) });
+  }
+
+  private async rows(statement: string): Promise<Record<string, unknown>[]> {
+    return extractRows(await this.session.execute(statement));
+  }
+
+  /** Restore the practice data. */
+  /** The action in progress; the next one waits for it (see exclusive). */
+  private queue: Promise<unknown> = Promise.resolve();
+
+  /**
+   * Run lesson actions one at a time. Moving to a lesson resets the practice
+   * data, so a jump that started while an answer was still being checked
+   * could empty the store under the check.
+   */
+  private exclusive<T>(action: () => Promise<T>): Promise<T> {
+    const run = this.queue.then(action, action);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  start(opts: { level?: Level } = {}): Promise<void> {
+    return this.exclusive(() => this.startNow(opts));
+  }
+
+  /** Run a statement and check it against the current lesson. */
+  submit(statement: string): Promise<boolean> {
+    return this.exclusive(() => this.submitNow(statement));
+  }
+
+  next(): Promise<void> {
+    return this.exclusive(() => this.nextNow());
+  }
+
+  back(): Promise<void> {
+    return this.exclusive(() => this.backNow());
+  }
+
+  /** Jump to a 1-based lesson number. */
+  goto(arg: string | undefined): Promise<void> {
+    return this.exclusive(() => this.gotoNow(arg));
+  }
+
+  level(arg: string | undefined): Promise<void> {
+    return this.exclusive(() => this.levelNow(arg));
+  }
+
+  reset(): Promise<void> {
+    return this.exclusive(() => this.resetNow());
+  }
+
+  async resetData(): Promise<void> {
+    for (const s of RESET_STATEMENTS) await this.session.execute(s);
+  }
+
+  /** Welcome banner + the current lesson (show() restores the practice data). */
+  private async startNow(opts: { level?: Level } = {}): Promise<void> {
+    if (opts.level) this.index = firstLessonOf(opts.level, this.lessons);
+    if (this.io.onLesson) {
+      await this.show();
+      return;
+    }
+    const counts = LEVELS.map(
+      (l) => `${LEVEL_LABEL[l]} ${this.lessons.filter((x) => x.level === l).length}`,
+    ).join(" · ");
+    this.io.print(
+      [
+        chalk.bold("Learn DQL — interactive lessons"),
+        chalk.dim(`${this.lessons.length} lessons: ${counts}`),
+        "Type DQL at the learn> prompt and press Enter to run it — a trailing ; is optional.",
+        `New here? Type ${chalk.cyan(".help")} for how the lessons work and the commands.`,
+        ...(this.index > 0 && !opts.level
+          ? [chalk.dim(`Resuming at lesson ${this.index + 1} — .goto 1 starts over.`)]
+          : []),
+      ].join("\n"),
+    );
+    await this.show();
+  }
+
+  /**
+   * Restore the practice data, run the lesson's setup, and print its card.
+   * Every lesson starts from the same data, so writes from earlier lessons (or
+   * a skipped one) can't make a correct answer fail.
+   */
+  async show(): Promise<void> {
+    const lesson = this.lessons[this.index];
+    if (!lesson) return;
+    await this.resetData();
+    for (const s of lesson.setup ?? []) await this.session.execute(s);
+    if (this.io.onLesson) {
+      this.io.onLesson();
+      return;
+    }
+    const { position } = this.info();
+    const out = [
+      "",
+      this.rule(),
+      `${chalk.bold.cyan(`Lesson ${this.index + 1}/${this.lessons.length}`)} ${chalk.dim("·")} ${chalk.magenta(position)} ${chalk.dim("·")} ${chalk.bold(lesson.title)}${this.completed.has(this.index) ? chalk.green("  ✓") : ""}`,
+      this.rule(),
+      ...this.cardBody(),
+      this.dataTip(".schema"),
+      chalk.dim(
+        `Press ${chalk.reset("Enter")} to run it · stuck? ${chalk.reset(".hint")} or ${chalk.reset(".answer")} · ${chalk.reset(".help")} explains how this works`,
+      ),
+    ];
+    this.io.print(out.join("\n"));
+  }
+
+  /** Where the current lesson sits: "Beginner 3/8", plus its title and completion. */
+  info(): { title: string; level: Level; position: string; done: boolean } {
+    const lesson = this.lessons[this.index]!;
+    const levelLessons = this.lessons.filter((l) => l.level === lesson.level);
+    return {
+      title: lesson.title,
+      level: lesson.level,
+      position: `${LEVEL_LABEL[lesson.level]} ${levelLessons.indexOf(lesson) + 1}/${levelLessons.length}`,
+      done: this.completed.has(this.index),
+    };
+  }
+
+  /** The collections the current lesson works with (from its sample answer). */
+  collections(): string[] {
+    const lesson = this.lessons[this.index];
+    return lesson ? collectionsIn(lesson.answer) : [];
+  }
+
+  /** "Collections: products, suppliers · <key> shows their fields" */
+  dataTip(key: string): string {
+    const names = this.collections();
+    if (names.length === 0) return chalk.dim(`${key} shows the collections' fields`);
+    const label = names.length === 1 ? "Collection" : "Collections";
+    return chalk.dim(
+      `${label}: ${names.map((n) => chalk.cyan(n)).join(", ")} · ${chalk.reset(key)} shows ${names.length === 1 ? "its" : "their"} fields`,
+    );
+  }
+
+  /** The live schema of the current lesson's collections. */
+  async schema(): Promise<CollectionSchema[]> {
+    const out: CollectionSchema[] = [];
+    for (const collection of this.collections()) {
+      const rows = await this.rows(`SELECT * FROM ${collection} LIMIT ${SCHEMA_SAMPLE + 1}`);
+      const docs = rows.slice(0, SCHEMA_SAMPLE);
+      out.push({
+        collection,
+        documents: docs.length,
+        more: rows.length > SCHEMA_SAMPLE,
+        fields: inferSchema(docs),
+      });
+    }
+    return out;
+  }
+
+  /** `.schema` in the plain shell. */
+  async printSchema(): Promise<void> {
+    const width = Math.min(this.io.width() ?? MAX_RULE, MAX_RULE);
+    this.io.print(
+      [
+        ...schemaLines(await this.schema(), width),
+        chalk.dim(
+          `Names are case-sensitive: ${chalk.cyan("products")} and ${chalk.cyan("Products")} are different collections.`,
+        ),
+      ].join("\n"),
+    );
+  }
+
+  isCompleted(i: number): boolean {
+    return this.completed.has(i);
+  }
+
+  /**
+   * The lesson card's body (concept, SQL note, syntax, task) as styled lines.
+   * `unwrap` joins the source's hard-wrapped paragraphs so a UI can re-wrap them;
+   * blank lines and indented lines (examples) stay as they are.
+   */
+  cardBody(opts: { unwrap?: boolean } = {}): string[] {
+    const lesson = this.lessons[this.index];
+    if (!lesson) return [];
+    const t = (s: string) => highlight(opts.unwrap ? s.replace(/(?<!\n)\n(?![\n ])/g, " ") : s);
+    const out = [t(lesson.concept)];
+    if (lesson.sql) out.push("", `${chalk.dim("If you know SQL:")} ${t(lesson.sql)}`);
+    out.push("", chalk.dim("Syntax"), ...lesson.syntax.map((s) => `  ${chalk.cyan(s)}`));
+    out.push("", `${chalk.bold.yellow("Task:")} ${t(lesson.task)}`);
+    return out;
+  }
+
+  /** Run a submitted statement, show its result, and check it against the lesson. */
+  private async submitNow(statement: string): Promise<boolean> {
+    // Captured up front: a command run while this is awaiting (.next, .goto)
+    // must not change which lesson gets marked complete.
+    const index = this.index;
+    const lesson = this.lessons[index];
+    let rows: Record<string, unknown>[];
+    try {
+      rows = await this.rows(statement);
+    } catch (err) {
+      const verdict = chalk.red(`Query error: ${(err as Error).message}`);
+      this.io.print(`${verdict}\n${chalk.dim("Check the syntax — .hint can help.")}`);
+      this.io.onVerdict?.(verdict);
+      return false;
+    }
+    const kind = classify(statement);
+    this.io.print(this.renderResult(kind, statement, rows));
+    if (!lesson) return false;
+
+    let result: Awaited<ReturnType<Lesson["check"]>>;
+    try {
+      result = await lesson.check({ statement, kind, rows, query: (s) => this.rows(s) });
+    } catch (err) {
+      result = { pass: false, reason: `Couldn't check that: ${(err as Error).message}` };
+    }
+    if (!result.pass) {
+      // A wrong-case name runs fine but finds nothing; say so instead.
+      const reason = caseMismatch(statement, KNOWN_NAMES) ?? result.reason;
+      this.verdict(`${chalk.yellow("✗ Not quite.")} ${highlight(reason)}`);
+      return false;
+    }
+    this.completed.add(index);
+    this.verdict(`${chalk.green.bold("✓ Correct!")} ${highlight(lesson.success)}`);
+    if (this.index === index) await this.advance();
+    else this.persist();
+    return true;
+  }
+
+  private verdict(text: string): void {
+    this.io.print(text);
+    this.io.onVerdict?.(text);
+  }
+
+  private renderResult(
+    kind: ReturnType<typeof classify>,
+    statement: string,
+    rows: Record<string, unknown>[],
+  ): string {
+    if (kind === "explain") return renderExplain(rows[0]);
+    if (kind === "profile") {
+      const { rows: data, profile } = extractProfile(rows);
+      const table =
+        data.length > 0 ? `${renderTable(data, { maxWidth: this.io.width() })}\n\n` : "";
+      return profile ? table + renderProfile(profile, statement) : table || "(no rows)";
+    }
+    if (rows.length === 0 && kind !== "select") return chalk.dim("OK");
+    return renderTable(rows, { maxWidth: this.io.width() });
+  }
+
+  private async advance(): Promise<void> {
+    if (this.index + 1 >= this.lessons.length) {
+      this.persist();
+      this.io.print(this.finishedMessage());
+      return;
+    }
+    const prevLevel = this.lessons[this.index]?.level;
+    this.index++;
+    this.persist();
+    const level = this.lessons[this.index]?.level;
+    if (level && level !== prevLevel) {
+      this.io.print(`\n${chalk.bold.magenta(`★ On to ${LEVEL_LABEL[level]}!`)}`);
+    }
+    await this.show();
+  }
+
+  private finishedMessage(): string {
+    const all = this.completed.size === this.lessons.length;
+    return [
+      "",
+      chalk.bold.green(
+        all
+          ? `★ You finished all ${this.lessons.length} lessons!`
+          : `★ That was the last lesson (${this.completed.size}/${this.lessons.length} completed — .lessons shows the rest).`,
+      ),
+      "Next steps:",
+      `  ${chalk.cyan("dittosh dql")}               your own data in the interactive shell (try ${chalk.cyan(".metrics")})`,
+      `  ${chalk.cyan("dittosh dql dataset list")}  sample datasets to practice on`,
+      `  ${chalk.cyan("dittosh tutorial")}          a written walkthrough of the whole CLI`,
+    ].join("\n");
+  }
+
+  hint(): void {
+    const lesson = this.lessons[this.index];
+    if (lesson) this.io.print(`${chalk.yellow("Hint:")} ${highlight(lesson.hint)}`);
+  }
+
+  answer(): void {
+    const lesson = this.lessons[this.index];
+    if (!lesson) return;
+    this.io.print(
+      `${chalk.yellow("One answer:")} ${chalk.cyan(lesson.answer)}\n${chalk.dim("Type it (or your own version) and press Enter to continue.")}`,
+    );
+  }
+
+  private async nextNow(): Promise<void> {
+    if (this.index + 1 >= this.lessons.length) {
+      this.io.print(chalk.dim("This is the last lesson."));
+      return;
+    }
+    this.index++;
+    this.persist();
+    await this.show();
+  }
+
+  private async backNow(): Promise<void> {
+    if (this.index === 0) {
+      this.io.print(chalk.dim("This is the first lesson."));
+      return;
+    }
+    this.index--;
+    this.persist();
+    await this.show();
+  }
+
+  private async gotoNow(arg: string | undefined): Promise<void> {
+    const n = Number(arg?.trim());
+    if (!Number.isInteger(n) || n < 1 || n > this.lessons.length) {
+      this.io.print(chalk.red(`usage: .goto <1-${this.lessons.length}>`));
+      return;
+    }
+    this.index = n - 1;
+    this.persist();
+    await this.show();
+  }
+
+  private async levelNow(arg: string | undefined): Promise<void> {
+    const name = arg?.trim().toLowerCase() as Level;
+    if (!LEVELS.includes(name)) {
+      this.io.print(chalk.red(`usage: .level ${LEVELS.join("|")}`));
+      return;
+    }
+    this.index = firstLessonOf(name, this.lessons);
+    this.persist();
+    await this.show();
+  }
+
+  list(): void {
+    const out: string[] = [];
+    for (const level of LEVELS) {
+      out.push(chalk.bold.magenta(LEVEL_LABEL[level]));
+      this.lessons.forEach((l, i) => {
+        if (l.level !== level) return;
+        const mark = this.completed.has(i) ? chalk.green("✓") : " ";
+        const here = i === this.index ? chalk.cyan(" ← you are here") : "";
+        out.push(`  ${mark} ${String(i + 1).padStart(2)}. ${l.title}${here}`);
+      });
+    }
+    out.push(
+      chalk.dim(`${this.completed.size}/${this.lessons.length} completed · .goto <n> to jump`),
+    );
+    this.io.print(out.join("\n"));
+  }
+
+  private async resetNow(): Promise<void> {
+    this.io.print(chalk.dim("Practice data restored."));
+    await this.show();
+  }
+}
+
+/** The `.help` guide: how the lessons work, then the commands. */
+export function lessonHelp(): string {
+  const h = (t: string) => chalk.bold.magenta(t);
+  const c = (t: string) => chalk.cyan(t);
+  return [
+    h("How the lessons work"),
+    "  Each lesson explains one DQL idea, shows the syntax, and gives you a Task.",
+    "  Type a statement that does the task. You see its result, then",
+    `  ${chalk.green("✓ Correct!")} moves you on, or ${chalk.yellow("✗ Not quite.")} says what to change.`,
+    "  The check looks at what your statement returns or changes, not its exact",
+    "  wording — any statement that does the task passes.",
+    "",
+    h("Typing statements"),
+    `  Press ${c("Enter")} to run. A trailing ${c(";")} is optional.`,
+    `  A ${c("|")} prompt means the statement looks unfinished — an open quote or`,
+    `  bracket, or it ends on a comma, an operator, or a word like ${c("WHERE")}.`,
+    "  Keep typing to spread a statement over several lines, or",
+    `  ${c(".break")} to throw it away. ${c("↑")}/${c("↓")} recall earlier input.`,
+    "",
+    h("The practice store"),
+    `  Lessons run against their own store (collections ${c("products")}, ${c("suppliers")},`,
+    `  ${c("orders")}), separate from your ${c("dittosh dql")} data. Writes are safe to try.`,
+    `  ${c(".reset")} restores the starting data if you change something by mistake.`,
+    `  Collection and field names are case-sensitive (${c("products")}, not ${c("Products")});`,
+    "  keywords like SELECT aren't.",
+    "",
+    h("Levels and progress"),
+    "  Beginner → Intermediate → Advanced. Skipping around is fine.",
+    `  Progress is saved as you go; ${c(".exit")} and come back later to resume.`,
+    "",
+    h("Commands"),
+    `  ${c(".hint")}             a nudge toward the answer`,
+    `  ${c(".answer")}           show one correct statement`,
+    `  ${c(".next")} / ${c(".back")}     move between lessons`,
+    `  ${c(".lessons")}          list every lesson by level, with your progress`,
+    `  ${c(".level <name>")}     jump to beginner, intermediate, or advanced`,
+    `  ${c(".goto <n>")}         jump to lesson n`,
+    `  ${c(".schema")}           the fields of this lesson's collections`,
+    `  ${c(".reset")}            restore the practice data and show the lesson again`,
+    `  ${c(".break")}            discard an unfinished statement (the | prompt)`,
+    `  ${c(".help")}             this guide`,
+    `  ${c(".exit")}             leave (progress is saved; Ctrl+D also works)`,
+  ].join("\n");
+}
diff --git a/src/tutorial/schema.ts b/src/tutorial/schema.ts
new file mode 100644
index 0000000..0a07b6f
--- /dev/null
+++ b/src/tutorial/schema.ts
@@ -0,0 +1,149 @@
+import chalk from "chalk";
+import stringWidth from "string-width";
+
+/** One field seen across a collection's documents. */
+export interface FieldInfo {
+  /** Dot path; array elements that are objects use `[]`, e.g. `lines[].sku`. */
+  path: string;
+  /** Value types seen: string, number, boolean, null, object, array. */
+  types: string[];
+  /** How many documents have this field. */
+  count: number;
+  /** A sample scalar value, when there is one. */
+  example?: unknown;
+}
+
+export interface CollectionSchema {
+  collection: string;
+  /** Documents read (capped at the sample size). */
+  documents: number;
+  /** True when the sample hit its cap, so there may be more documents. */
+  more: boolean;
+  fields: FieldInfo[];
+}
+
+function typeOf(v: unknown): string {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v === "object" ? "object" : typeof v;
+}
+
+/** Infer the fields of a set of documents, nested objects and arrays of objects included. */
+export function inferSchema(docs: readonly Record<string, unknown>[]): FieldInfo[] {
+  const fields = new Map<string, { types: Set<string>; docs: Set<number>; example?: unknown }>();
+  const see = (path: string, value: unknown, doc: number) => {
+    let f = fields.get(path);
+    if (!f) {
+      f = { types: new Set(), docs: new Set() };
+      fields.set(path, f);
+    }
+    const t = typeOf(value);
+    f.types.add(t);
+    f.docs.add(doc);
+    if (f.example === undefined && t !== "object" && t !== "array" && t !== "null") {
+      f.example = value;
+    }
+    if (f.example === undefined && t === "array" && (value as unknown[]).length > 0) {
+      const scalars = (value as unknown[]).filter((x) => typeOf(x) !== "object");
+      if (scalars.length > 0) f.example = value;
+    }
+    walk(value, path, doc);
+  };
+  const walk = (value: unknown, path: string, doc: number) => {
+    const t = typeOf(value);
+    if (t === "object") {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        see(path ? `${path}.${k}` : k, v, doc);
+      }
+    } else if (t === "array") {
+      for (const el of value as unknown[]) {
+        if (typeOf(el) === "object") walk(el, `${path}[]`, doc);
+      }
+    }
+  };
+  docs.forEach((d, i) => {
+    walk(d, "", i);
+  });
+  const out = [...fields.entries()].map(([path, f]) => ({
+    path,
+    types: [...f.types],
+    count: f.docs.size,
+    ...(f.example === undefined ? {} : { example: f.example }),
+  }));
+  // _id first; otherwise keep first-seen order (parents before their children).
+  return out.sort((a, b) => Number(b.path === "_id") - Number(a.path === "_id"));
+}
+
+/** The collections a statement reads or writes, in order of appearance. */
+export function collectionsIn(statement: string): string[] {
+  const names: string[] = [];
+  const text = statement.replace(/'(?:[^'\\]|\\.)*'/g, "''");
+  const re =
+    /\b(?:FROM|JOIN|INTO|UPDATE)\s+([A-Za-z_][\w]*(?::[A-Za-z_]\w*)?)|\bON\s+([A-Za-z_]\w*)\s*\(/gi;
+  for (const m of text.matchAll(re)) {
+    const name = m[1] ?? m[2];
+    if (name && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+function exampleText(v: unknown): string {
+  if (typeof v === "string") return `'${v}'`;
+  return JSON.stringify(v).replace(/"/g, "'");
+}
+
+/** The schema as styled lines for a panel `width` columns wide. */
+export function schemaLines(schemas: readonly CollectionSchema[], width: number): string[] {
+  const out: string[] = [];
+  for (const [i, s] of schemas.entries()) {
+    if (i > 0) out.push("");
+    const n = `${s.documents}${s.more ? "+" : ""} document${s.documents === 1 ? "" : "s"}`;
+    out.push(`${chalk.bold.magenta(s.collection)}  ${chalk.dim(n)}`);
+    if (s.fields.length === 0) {
+      out.push(chalk.dim("  (no documents)"));
+      continue;
+    }
+    const pathWidth = Math.min(
+      Math.max(...s.fields.map((f) => stringWidth(f.path))),
+      Math.max(8, Math.floor(width * 0.45)),
+    );
+    for (const f of s.fields) {
+      const path = f.path.length > pathWidth ? `${f.path.slice(0, pathWidth - 1)}…` : f.path;
+      const partial = f.count < s.documents ? chalk.dim(` · ${f.count} of ${s.documents}`) : "";
+      let line = `  ${chalk.cyan(path.padEnd(pathWidth))}  ${f.types.join("|")}${partial}`;
+      if (f.example !== undefined) {
+        const room = width - stringWidth(line) - 2;
+        if (room >= 6) {
+          let ex = exampleText(f.example);
+          if (ex.length > room) ex = `${ex.slice(0, room - 1)}…`;
+          line += `  ${chalk.dim(ex)}`;
+        }
+      }
+      out.push(line);
+    }
+  }
+  return out;
+}
+
+/** Names are case-sensitive: point out a name that only differs in case from a known one. */
+export function caseMismatch(
+  statement: string,
+  known: { collections: readonly string[]; fields: readonly string[] },
+): string | null {
+  const text = statement.replace(/'(?:[^'\\]|\\.)*'/g, "''");
+  for (const name of collectionsIn(text)) {
+    const right = known.collections.find(
+      (c) => c !== name && c.toLowerCase() === name.toLowerCase(),
+    );
+    if (right) {
+      return `Collection names are case-sensitive: \`${name}\` is a different (empty) collection from \`${right}\`.`;
+    }
+  }
+  for (const token of text.match(/[A-Za-z_]\w*/g) ?? []) {
+    const right = known.fields.find((f) => f !== token && f.toLowerCase() === token.toLowerCase());
+    if (right) {
+      return `Field names are case-sensitive: \`${token}\` isn't the same field as \`${right}\`.`;
+    }
+  }
+  return null;
+}
diff --git a/src/tutorial/ui/app.tsx b/src/tutorial/ui/app.tsx
new file mode 100644
index 0000000..f4101f6
--- /dev/null
+++ b/src/tutorial/ui/app.tsx
@@ -0,0 +1,492 @@
+import chalk from "chalk";
+import {
+  Box,
+  type Key,
+  render,
+  Text,
+  useApp,
+  useCursor,
+  useInput,
+  usePaste,
+  useWindowSize,
+} from "ink";
+import { useEffect, useMemo, useRef, useState } from "react";
+import stringWidth from "string-width";
+import { splitInput } from "../lesson-eval.js";
+import type { Level } from "../lessons.js";
+import type { LessonRunner, RunnerIO } from "../runner.js";
+import { type CollectionSchema, schemaLines } from "../schema.js";
+import {
+  CONTINUE,
+  Footer,
+  Header,
+  HelpDrawer,
+  InputLine,
+  LessonCard,
+  LessonPicker,
+  OutlinePanel,
+  OutputPanel,
+  PROMPT,
+  StatusLine,
+} from "./components.js";
+import { TutorialProvider, useTutorial, useTutorialSnapshot } from "./context.js";
+import {
+  type EditAction,
+  type EditorState,
+  edit,
+  emptyEditor,
+  isEditorEmpty,
+  submit,
+  viewport,
+} from "./editor.js";
+import { drawerWidth, helpLines } from "./help.js";
+import { clip, fitCard, scrollWindow, wrapLines } from "./layout.js";
+import { MIN_COLUMNS, MIN_ROWS } from "./limits.js";
+import { OUTLINE_MIN_SCREEN, outlineLines, outlineWidth } from "./outline.js";
+import { createUiStore, type UiStore } from "./store.js";
+
+/** Continuation lines shown above the prompt; earlier ones collapse into "…". */
+const MAX_CONTINUATION_ROWS = 4;
+/** Below the card, the output panel keeps at least this many rows. */
+const MIN_OUTPUT_ROWS = 5;
+/** Narrowest lesson column beside the help drawer. */
+const MIN_MAIN_WIDTH = 44;
+
+/** Animate a width toward `target` in a few quick steps (the drawer slide). */
+function useSlide(target: number): number {
+  const [current, setCurrent] = useState(target);
+  useEffect(() => {
+    if (current === target) return;
+    const timer = setTimeout(() => {
+      setCurrent((c) => {
+        const step = Math.max(4, Math.ceil(Math.abs(target - c) / 2));
+        return c < target ? Math.min(target, c + step) : Math.max(target, c - step);
+      });
+    }, 16);
+    return () => clearTimeout(timer);
+  }, [current, target]);
+  return current;
+}
+
+/**
+ * The full-screen lesson view: header, lesson card, output, input, key bar.
+ * Reads the runner and store from <TutorialProvider>.
+ */
+export function LessonScreen() {
+  const { runner, store } = useTutorial();
+  const { log, lessonVersion, status } = useTutorialSnapshot();
+  const { exit } = useApp();
+  const { columns, rows } = useWindowSize();
+  const { setCursorPosition } = useCursor();
+
+  // A ref mirrors the editor so several keys arriving in one chunk all apply.
+  const [editor, setEditor] = useState<EditorState>(() => emptyEditor());
+  const editorRef = useRef(editor);
+  const update = (fn: (s: EditorState) => EditorState) => {
+    editorRef.current = fn(editorRef.current);
+    setEditor(editorRef.current);
+  };
+  const [busy, setBusy] = useState(false);
+  const [scroll, setScroll] = useState(0);
+  const [picker, setPicker] = useState<number | null>(null);
+  const [expanded, setExpanded] = useState(false);
+  /** The right-hand drawer: help (?) or the data view (Ctrl+T). */
+  const [panel, setPanel] = useState<"help" | "data" | null>(null);
+  const helpOpen = panel !== null;
+  const [helpScroll, setHelpScroll] = useState(0);
+  const [schemas, setSchemas] = useState<CollectionSchema[] | null>(null);
+  const [schemaError, setSchemaError] = useState<string | null>(null);
+  /** null = automatic (shown when the window is wide enough); Ctrl+B overrides. */
+  const [outlinePref, setOutlinePref] = useState<boolean | null>(null);
+
+  // ── layout ──────────────────────────────────────────────────────────────
+  // Below the minimum (the window shrank after start) a placeholder is drawn
+  // instead; these clamps only keep the layout maths sane meanwhile.
+  const tooSmall = columns < MIN_COLUMNS || rows < MIN_ROWS;
+  const width = Math.max(MIN_COLUMNS, columns);
+  const height = Math.max(MIN_ROWS, rows);
+  // Left: the lesson outline (when there's room). Right: the help drawer,
+  // which slides in; in a narrow window it takes the whole width instead of
+  // squeezing the lesson below a readable size.
+  const panelWidth = drawerWidth(width, panel === "data" ? "data" : "help");
+  const drawerTarget = helpOpen ? (width - panelWidth >= MIN_MAIN_WIDTH ? panelWidth : width) : 0;
+  const drawer = useSlide(drawerTarget);
+  const showMain = width - drawer >= MIN_MAIN_WIDTH;
+  const outlineWanted = outlinePref ?? width >= OUTLINE_MIN_SCREEN;
+  const sidebarWidth = outlineWidth(width);
+  const showOutline = outlineWanted && showMain && width - drawer - sidebarWidth >= MIN_MAIN_WIDTH;
+  const mainWidth = Math.max(MIN_MAIN_WIDTH, width - drawer - (showOutline ? sidebarWidth : 0));
+  const inner = mainWidth - 4; // border + one column of padding on each side
+  store.setWidth(inner);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: lessonVersion marks a lesson change
+  const card = useMemo(() => {
+    const lines = runner.cardBody({ unwrap: true });
+    // The task and the data tip stay visible however short the window is.
+    return {
+      body: wrapLines(lines.slice(0, -1), inner),
+      task: wrapLines([...lines.slice(-1), runner.dataTip("Ctrl+T")], inner),
+    };
+  }, [runner, inner, lessonVersion]);
+  const cardHeight = card.body.length + card.task.length;
+  // A long multi-line statement shows only its last few lines, so the
+  // lesson and results always keep their space.
+  const maxDone = Math.max(0, Math.min(MAX_CONTINUATION_ROWS, height - 16));
+  const doneShown = maxDone === 0 ? [] : editor.done.slice(-maxDone);
+  const doneHidden = editor.done.length - doneShown.length;
+  const inputRows = doneShown.length + (doneHidden > 0 ? 1 : 0) + 1;
+  const statusLines = useMemo(() => {
+    if (!status) return [];
+    const rows = wrapLines([status], width - 2);
+    return rows.length > 2 ? [rows[0]!, clip(rows.slice(1).join(" "), width - 2)] : rows;
+  }, [status, width]);
+  const body = height - 2 - inputRows - statusLines.length; // minus header, footer, status
+  const minOutput = expanded ? 1 : MIN_OUTPUT_ROWS;
+  const cardRows = Math.max(1, Math.min(cardHeight, body - 4 - minOutput));
+  const cardLines = fitCard(
+    card.body,
+    card.task,
+    cardRows,
+    chalk.dim(
+      expanded ? "… (the window is too short for the whole lesson)" : "… ^O shows the whole lesson",
+    ),
+  );
+  const outputRows = Math.max(1, body - (cardRows + 2) - 2);
+  const outputLines = useMemo(() => wrapLines(log, inner), [log, inner]);
+  const helpWidth = Math.max(10, (drawerTarget || drawer) - 4);
+  const help = useMemo(() => {
+    if (panel !== "data") return helpLines(helpWidth);
+    if (schemaError) return [chalk.red(schemaError)];
+    if (!schemas) return [chalk.dim("Reading the collections…")];
+    return [
+      ...schemaLines(schemas, helpWidth),
+      "",
+      ...wrapLines(
+        [
+          chalk.dim(
+            `Names are case-sensitive: ${chalk.cyan("products")} and ${chalk.cyan("Products")} are different collections.`,
+          ),
+        ],
+        helpWidth,
+      ),
+    ];
+  }, [helpWidth, panel, schemas, schemaError]);
+
+  // The data view reads the live collections: on opening, on a lesson change,
+  // and after each statement (an INSERT shows up straight away).
+  // biome-ignore lint/correctness/useExhaustiveDependencies: lessonVersion/log mark data changes
+  useEffect(() => {
+    if (panel !== "data") return;
+    let live = true;
+    const read = runner.schema();
+    store.track(read);
+    read
+      .then((s) => {
+        if (!live) return;
+        setSchemas(s);
+        setSchemaError(null);
+      })
+      .catch((err: unknown) => {
+        if (live) setSchemaError(`Couldn't read the data: ${(err as Error).message}`);
+      });
+    return () => {
+      live = false;
+    };
+  }, [panel, runner, lessonVersion, log]);
+  const helpRows = body - 2;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: lessonVersion/log mark progress changes
+  const outline = useMemo(
+    () =>
+      showOutline
+        ? outlineLines(
+            {
+              lessons: runner.lessons,
+              current: runner.current,
+              isCompleted: (i) => runner.isCompleted(i),
+            },
+            sidebarWidth - 4,
+            body - 2,
+          )
+        : [],
+    [showOutline, runner, body, lessonVersion, log, sidebarWidth],
+  );
+  const helpMax = Math.max(0, help.length - (helpRows - 1));
+
+  // The panel holds only the latest action's output, so new output opens at
+  // its top (a long table or the guide reads from the start). PgUp/PgDn hold
+  // until the next output arrives.
+  const seenLog = useRef(log);
+  if (log !== seenLog.current) {
+    seenLog.current = log;
+    const top = Math.max(0, outputLines.length - outputRows);
+    if (scroll !== top) setScroll(top);
+  }
+  const out = scrollWindow(outputLines, outputRows, scroll);
+  const page = Math.max(1, outputRows - 1);
+
+  // ── actions ─────────────────────────────────────────────────────────────
+  // busyRef answers "is something running?" synchronously (state lags a render).
+  const busyRef = useRef(false);
+  const run = (task: () => unknown) => {
+    busyRef.current = true;
+    setBusy(true);
+    const work = Promise.resolve()
+      .then(task)
+      .catch((err: unknown) =>
+        store.print(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`)),
+      )
+      .finally(() => {
+        busyRef.current = false;
+        setBusy(false);
+      });
+    // Quitting waits for this before the session closes (runLessonScreen).
+    store.track(work);
+  };
+  /**
+   * Each action starts with an empty results panel. Hints, answers, and help
+   * keep the ✓/✗ status (it's still about the current task); statements and
+   * lesson changes clear it.
+   */
+  const fresh = (opts: { keepStatus?: boolean } = {}) => {
+    store.clear();
+    if (!opts.keepStatus) store.setStatus(null);
+  };
+  /** Open, switch, or close the right-hand drawer. */
+  const togglePanel = (which: "help" | "data", open = panel !== which) => {
+    setPanel(open ? which : null);
+    if (open) setHelpScroll(0);
+  };
+  const toggleHelp = (open?: boolean) => togglePanel("help", open);
+  const hint = () => {
+    fresh({ keepStatus: true });
+    runner.hint();
+  };
+  const move = (task: () => Promise<void>) => {
+    fresh();
+    run(task);
+  };
+
+  const command = (name: string, arg: string) => {
+    switch (name) {
+      case "hint":
+        return hint();
+      case "answer":
+        fresh({ keepStatus: true });
+        return runner.answer();
+      case "next":
+        return move(() => runner.next());
+      case "back":
+        return move(() => runner.back());
+      case "goto":
+        return move(() => runner.goto(arg));
+      case "level":
+        return move(() => runner.level(arg));
+      case "reset":
+        return move(() => runner.reset());
+      case "lessons":
+        toggleHelp(false);
+        return setPicker(runner.current);
+      case "help":
+        return toggleHelp(true);
+      case "schema":
+      case "data":
+        return togglePanel("data", true);
+      case "break":
+      case "clear":
+        return;
+      case "exit":
+      case "quit":
+        return exit();
+      default:
+        fresh({ keepStatus: true });
+        store.print(chalk.yellow(`Unknown command .${name} — type .help for the list.`));
+    }
+  };
+
+  const onEnter = () => {
+    const r = submit(editorRef.current);
+    update(() => r.state);
+    if (r.kind === "command") command(r.name, r.arg);
+    else if (r.kind === "statement") {
+      fresh();
+      store.print(`${chalk.cyan(PROMPT)}${r.text.replace(/\n/g, `\n${CONTINUE}`)}`);
+      run(async () => {
+        for (const s of splitInput(r.text)) await runner.submit(s);
+      });
+    }
+  };
+
+  const onPickerKey = (input: string, key: Key, sel: number) => {
+    const last = runner.lessons.length - 1;
+    if (key.escape || input === "q" || (key.ctrl && input === "l")) setPicker(null);
+    else if (key.upArrow) setPicker(Math.max(0, sel - 1));
+    else if (key.downArrow) setPicker(Math.min(last, sel + 1));
+    else if (key.pageUp) setPicker(Math.max(0, sel - 10));
+    else if (key.pageDown) setPicker(Math.min(last, sel + 10));
+    else if (key.home) setPicker(0);
+    else if (key.end) setPicker(last);
+    else if (key.return) {
+      setPicker(null);
+      move(() => runner.goto(String(sel + 1)));
+    }
+  };
+
+  useInput((input, key) => {
+    if (picker !== null) return onPickerKey(input, key, picker);
+    const empty = isEditorEmpty(editorRef.current);
+    const apply = (a: EditAction) => update((s) => edit(s, a));
+    if (key.ctrl && input === "c") return empty ? exit() : apply({ type: "clear" });
+    if (key.ctrl && input === "d") return empty ? exit() : apply({ type: "delete" });
+    if (key.return) return busy ? undefined : onEnter();
+    if (key.tab) return hint();
+    const helpPage = Math.max(1, helpRows - 3);
+    if (helpOpen && key.pageUp) return setHelpScroll((s) => Math.max(0, s - helpPage));
+    if (helpOpen && key.pageDown) return setHelpScroll((s) => Math.min(helpMax, s + helpPage));
+    if (key.pageUp) {
+      const top = Math.max(0, outputLines.length - outputRows);
+      return setScroll((s) => Math.min(top, s + page));
+    }
+    if (key.pageDown) return setScroll((s) => Math.max(0, s - page));
+    if (key.escape) return helpOpen ? toggleHelp(false) : apply({ type: "clear" });
+    if (key.upArrow) return apply({ type: "historyPrev" });
+    if (key.downArrow) return apply({ type: "historyNext" });
+    if (key.leftArrow) return apply({ type: "left" });
+    if (key.rightArrow) return apply({ type: "right" });
+    if (key.home) return apply({ type: "home" });
+    if (key.end) return apply({ type: "end" });
+    if (key.backspace) return apply({ type: "backspace" });
+    if (key.delete) return apply({ type: "delete" });
+    if (key.ctrl) {
+      if (input === "a") return apply({ type: "home" });
+      if (input === "e") return apply({ type: "end" });
+      if (input === "u") return apply({ type: "killLine" });
+      if (input === "w") return apply({ type: "killWord" });
+      if (busy) return;
+      if (input === "n") return move(() => runner.next());
+      if (input === "p") return move(() => runner.back());
+      if (input === "l") {
+        toggleHelp(false);
+        return setPicker(runner.current);
+      }
+      if (input === "o") return setExpanded((x) => !x);
+      if (input === "t") return togglePanel("data");
+      if (input === "b") return setOutlinePref(!outlineWanted);
+      return;
+    }
+    if (key.meta) return;
+    if (input === "?" && empty) return toggleHelp();
+    // Text and Enter in one chunk (fast typing, or a paste without bracketed
+    // paste): type the text, then press Enter.
+    // Every line is kept: each newline presses Enter, and once a statement is
+    // running the rest stays in the editor for the next Enter.
+    const parts = input.split(/\r\n|\r|\n/);
+    for (const [i, part] of parts.entries()) {
+      if (part) apply({ type: "insert", text: part });
+      if (i === parts.length - 1) break;
+      if (busyRef.current) apply({ type: "insert", text: " " });
+      else onEnter();
+    }
+  });
+  usePaste((text) => update((s) => edit(s, { type: "insert", text })), {
+    isActive: picker === null,
+  });
+
+  // The real terminal cursor sits at the insertion point; long lines scroll
+  // sideways so it stays in view.
+  const promptWidth = stringWidth(PROMPT);
+  const view = viewport(editor.line, editor.cursor, width - promptWidth);
+  const cursorX = promptWidth + view.cursorCol;
+  const cursorY = height - 2;
+  setCursorPosition(picker === null && !busy && !tooSmall ? { x: cursorX, y: cursorY } : undefined);
+
+  if (tooSmall) {
+    return (
+      <Box flexDirection="column" width={columns} height={rows}>
+        <Text wrap="wrap">
+          {chalk.bold("Learn DQL")} — the window is too small. Make it at least {MIN_COLUMNS}×
+          {MIN_ROWS} (now {columns}×{rows}), or press Ctrl+D to quit; progress is saved.
+        </Text>
+      </Box>
+    );
+  }
+
+  return (
+    <Box flexDirection="column" width={width} height={height}>
+      <Header width={width} />
+      {picker === null ? (
+        <Box flexDirection="row" height={body}>
+          {showOutline && <OutlinePanel lines={outline} rows={body - 2} width={sidebarWidth} />}
+          {showMain && (
+            <Box flexDirection="column" width={mainWidth}>
+              <LessonCard lines={cardLines} rows={cardRows} />
+              <OutputPanel lines={out.visible} rows={outputRows} />
+            </Box>
+          )}
+          {drawer > 0 && (
+            <HelpDrawer
+              title={panel === "data" ? "Data" : "Help"}
+              lines={help}
+              rows={helpRows}
+              width={showMain ? drawer : width}
+              scroll={Math.min(helpScroll, helpMax)}
+              more={helpScroll < helpMax}
+            />
+          )}
+        </Box>
+      ) : (
+        <LessonPicker selected={picker} rows={body - 2} width={width - 4} />
+      )}
+      <StatusLine lines={statusLines} />
+      <InputLine
+        done={doneShown}
+        hidden={doneHidden}
+        line={view.text}
+        empty={isEditorEmpty(editor)}
+        busy={busy}
+      />
+      <Footer
+        mode={picker !== null ? "picker" : (panel ?? "lesson")}
+        above={picker === null && !helpOpen ? out.above : 0}
+        below={picker === null && !helpOpen ? out.below : 0}
+        width={width}
+      />
+    </Box>
+  );
+}
+
+/** Runner IO for the screen: prints go to the store's log; the screen draws the card. */
+export function screenIO(store: UiStore, runner: () => LessonRunner): RunnerIO {
+  return {
+    print: store.print,
+    width: store.width,
+    onVerdict: store.setStatus,
+    onLesson: () => {
+      const r = runner();
+      store.lessonChanged();
+      store.print(chalk.dim(`── Lesson ${r.current + 1}: ${r.info().title} ──`));
+    },
+  };
+}
+
+/**
+ * Full-screen lessons in the alternate screen buffer (like `less` or `vim`):
+ * the terminal's contents come back on exit. Resolves when the user quits.
+ */
+export async function runLessonScreen(
+  makeRunner: (io: RunnerIO) => LessonRunner,
+  opts: { level?: Level } = {},
+): Promise<LessonRunner> {
+  const store = createUiStore({ width: Math.max(MIN_COLUMNS, process.stdout.columns ?? 80) - 4 });
+  const runner: LessonRunner = makeRunner(screenIO(store, () => runner));
+  await runner.start(opts);
+  const instance = render(
+    <TutorialProvider runner={runner} store={store}>
+      <LessonScreen />
+    </TutorialProvider>,
+    { alternateScreen: true, exitOnCtrlC: false },
+  );
+  await instance.waitUntilExit();
+  // Let a statement or lesson change that was running finish before the
+  // caller closes the session.
+  await store.idle();
+  return runner;
+}
diff --git a/src/tutorial/ui/components.tsx b/src/tutorial/ui/components.tsx
new file mode 100644
index 0000000..e7f8579
--- /dev/null
+++ b/src/tutorial/ui/components.tsx
@@ -0,0 +1,277 @@
+import chalk from "chalk";
+import { Box, Text } from "ink";
+import { useMemo } from "react";
+import stringWidth from "string-width";
+import { LEVELS, type Level } from "../lessons.js";
+import { useTutorial } from "./context.js";
+import { clip, listWindow, progressBar } from "./layout.js";
+
+export const PROMPT = "learn> ";
+export const CONTINUE = "     | ";
+
+const LEVEL_LABEL: Record<Level, string> = {
+  beginner: "Beginner",
+  intermediate: "Intermediate",
+  advanced: "Advanced",
+};
+
+/** Top row: badge, lesson position and title, overall progress bar. */
+export function Header({ width }: { width: number }) {
+  const { runner } = useTutorial();
+  const info = runner.info();
+  const bar = progressBar(runner.completedCount, runner.lessons.length, Math.min(20, width >> 3));
+  const title = clip(
+    `${chalk.bold.cyan(`Lesson ${runner.current + 1}/${runner.lessons.length}`)} ${chalk.dim("·")} ${chalk.magenta(info.position)} ${chalk.dim("·")} ${chalk.bold(info.title)}${info.done ? chalk.green(" ✓") : ""}`,
+    width - stringWidth(bar) - 14,
+  );
+  return (
+    <Box justifyContent="space-between" height={1}>
+      <Text wrap="truncate-end">
+        {chalk.bgCyan.black(" Learn DQL ")} {title}
+      </Text>
+      <Text>{bar}</Text>
+    </Box>
+  );
+}
+
+/** Lines in a bordered panel; `lines` are already wrapped to fit. */
+function Panel({ lines, rows, color }: { lines: readonly string[]; rows: number; color: string }) {
+  return (
+    <Box
+      borderStyle="round"
+      borderColor={color}
+      paddingX={1}
+      flexDirection="column"
+      height={rows + 2}
+    >
+      {lines.map((l, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: positional lines, re-rendered wholesale
+        <Text key={i} wrap="truncate-end">
+          {l || " "}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+/** The lesson: concept, SQL note, syntax, task (already fitted to the panel). */
+export function LessonCard({ lines, rows }: { lines: readonly string[]; rows: number }) {
+  return <Panel lines={lines} rows={rows} color="cyan" />;
+}
+
+/** Results and feedback (the visible slice of the scrolled log). */
+export function OutputPanel({ lines, rows }: { lines: readonly string[]; rows: number }) {
+  return (
+    <Panel
+      lines={lines.length > 0 ? lines : [chalk.dim("Results and feedback appear here.")]}
+      rows={rows}
+      color="gray"
+    />
+  );
+}
+
+type PickerRow = { kind: "level"; label: string } | { kind: "lesson"; index: number };
+
+/** Ctrl+L: every lesson grouped by level, ✓ for completed, the selection highlighted. */
+export function LessonPicker({
+  selected,
+  rows,
+  width,
+}: {
+  selected: number;
+  rows: number;
+  width: number;
+}) {
+  const { runner } = useTutorial();
+  const items = useMemo<PickerRow[]>(
+    () =>
+      LEVELS.flatMap((level) => [
+        { kind: "level" as const, label: LEVEL_LABEL[level] },
+        ...runner.lessons.flatMap((l, index) =>
+          l.level === level ? [{ kind: "lesson" as const, index }] : [],
+        ),
+      ]),
+    [runner],
+  );
+  const selectedRow = items.findIndex((r) => r.kind === "lesson" && r.index === selected);
+  const [from, to] = listWindow(items.length, rows, selectedRow);
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="magenta"
+      paddingX={1}
+      flexDirection="column"
+      height={rows + 2}
+    >
+      {items.slice(from, to).map((r) => {
+        if (r.kind === "level") {
+          return <Text key={`level-${r.label}`}>{chalk.bold.magenta(r.label)}</Text>;
+        }
+        const l = runner.lessons[r.index]!;
+        const mark = runner.isCompleted(r.index) ? chalk.green("✓") : " ";
+        const line = clip(` ${mark} ${String(r.index + 1).padStart(2)}. ${l.title}`, width - 1);
+        return (
+          <Text key={`lesson-${r.index}`} inverse={r.index === selected}>
+            {line}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}
+
+/** The lesson outline sidebar (left). */
+export function OutlinePanel({
+  lines,
+  rows,
+  width,
+}: {
+  lines: readonly string[];
+  rows: number;
+  width: number;
+}) {
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="gray"
+      paddingX={1}
+      flexDirection="column"
+      width={width}
+      height={rows + 2}
+      flexShrink={0}
+    >
+      {lines.slice(0, rows).map((l, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: positional lines
+        <Text key={i} wrap="truncate-end">
+          {l || " "}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+/** The right-hand inspector (help or data): a column that slides in from the right. */
+export function HelpDrawer({
+  title,
+  lines,
+  rows,
+  width,
+  scroll,
+  more,
+}: {
+  title: string;
+  lines: readonly string[];
+  rows: number;
+  width: number;
+  scroll: number;
+  /** More lines below: say PgDn scrolls. */
+  more: boolean;
+}) {
+  const visible = lines.slice(scroll, scroll + rows - 1);
+  return (
+    <Box
+      borderStyle="round"
+      borderColor="magenta"
+      paddingX={1}
+      flexDirection="column"
+      width={width}
+      height={rows + 2}
+      flexShrink={0}
+    >
+      <Text wrap="truncate-end">
+        {chalk.bold.bgMagenta.black(` ${title} `)} {chalk.dim(more ? "PgDn more" : "Esc closes")}
+      </Text>
+      {visible.map((l, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: positional lines
+        <Text key={i} wrap="truncate-end">
+          {l || " "}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+/** The latest verdict, kept in view whatever the output panel shows. */
+export function StatusLine({ lines }: { lines: readonly string[] }) {
+  return (
+    <>
+      {lines.map((l, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: positional lines
+        <Text key={i} wrap="truncate-end">
+          {` ${l}`}
+        </Text>
+      ))}
+    </>
+  );
+}
+
+/** The prompt line, plus the last few lines of an unfinished statement. */
+export function InputLine({
+  done,
+  hidden,
+  line,
+  empty,
+  busy,
+}: {
+  /** Earlier lines to show (already capped). */
+  done: readonly string[];
+  /** Earlier lines not shown. */
+  hidden: number;
+  /** The current line, already scrolled to keep the cursor in view. */
+  line: string;
+  empty: boolean;
+  busy: boolean;
+}) {
+  const continuing = done.length > 0 || hidden > 0;
+  return (
+    <>
+      {hidden > 0 && (
+        <Text wrap="truncate-end">
+          {chalk.cyan(PROMPT)}
+          {chalk.dim(`… ${hidden} earlier line${hidden === 1 ? "" : "s"}`)}
+        </Text>
+      )}
+      {done.map((l, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: continuation lines are positional
+        <Text key={i} wrap="truncate-end">
+          {i === 0 && hidden === 0 ? chalk.cyan(PROMPT) : chalk.dim(CONTINUE)}
+          {l}
+        </Text>
+      ))}
+      <Text wrap="truncate-end">
+        {continuing ? chalk.dim(CONTINUE) : chalk.cyan(PROMPT)}
+        {busy && empty ? chalk.yellow("running…") : line}
+      </Text>
+    </>
+  );
+}
+
+/** Bottom row: key hints, and the scroll position when the output overflows. */
+export function Footer({
+  mode,
+  above,
+  below,
+  width,
+}: {
+  mode: "lesson" | "picker" | "help" | "data";
+  above: number;
+  below: number;
+  width: number;
+}) {
+  const keys = {
+    lesson: "Enter run · Tab hint · ^T data · ^L list · ? help · ^D quit",
+    picker: "↑/↓ choose · Enter open · Esc close",
+    help: "Enter run · ? or Esc close help · PgUp/Dn scroll help · ^D quit",
+    data: "Enter run · ^T or Esc close data · PgUp/Dn scroll data · ^D quit",
+  }[mode];
+  const parts = [above > 0 ? `↑${above}` : "", below > 0 ? `↓${below}` : ""].filter(Boolean);
+  const scroll = parts.length > 0 ? `${parts.join(" ")} PgUp/Dn` : "";
+  return (
+    <Box justifyContent="space-between" height={1}>
+      <Text dimColor wrap="truncate-end">
+        {clip(keys, width - stringWidth(scroll) - 2)}
+      </Text>
+      <Text dimColor>{scroll}</Text>
+    </Box>
+  );
+}
diff --git a/src/tutorial/ui/context.tsx b/src/tutorial/ui/context.tsx
new file mode 100644
index 0000000..8818d92
--- /dev/null
+++ b/src/tutorial/ui/context.tsx
@@ -0,0 +1,37 @@
+import { createContext, type ReactNode, useContext, useMemo, useSyncExternalStore } from "react";
+import type { LessonRunner } from "../runner.js";
+import type { UiSnapshot, UiStore } from "./store.js";
+
+/**
+ * Provider for the lesson screen. The LessonRunner owns the Ditto session
+ * (through its QueryExecutor), so components reach the store only via the
+ * runner and never see the SDK directly — tests swap in a runner over a
+ * fake executor.
+ */
+interface TutorialContextValue {
+  runner: LessonRunner;
+  store: UiStore;
+}
+
+const TutorialContext = createContext<TutorialContextValue | null>(null);
+
+export function TutorialProvider({
+  runner,
+  store,
+  children,
+}: TutorialContextValue & { children?: ReactNode }) {
+  const value = useMemo(() => ({ runner, store }), [runner, store]);
+  return <TutorialContext.Provider value={value}>{children}</TutorialContext.Provider>;
+}
+
+export function useTutorial(): TutorialContextValue {
+  const ctx = useContext(TutorialContext);
+  if (!ctx) throw new Error("useTutorial must be used inside <TutorialProvider>");
+  return ctx;
+}
+
+/** The output log and lesson-change counter; re-renders when either changes. */
+export function useTutorialSnapshot(): UiSnapshot {
+  const { store } = useTutorial();
+  return useSyncExternalStore(store.subscribe, store.snapshot);
+}
diff --git a/src/tutorial/ui/editor.ts b/src/tutorial/ui/editor.ts
new file mode 100644
index 0000000..1e3c49b
--- /dev/null
+++ b/src/tutorial/ui/editor.ts
@@ -0,0 +1,163 @@
+import { looksUnfinished } from "../lesson-eval.js";
+
+/**
+ * The lesson screen's input line: a small line editor with history and
+ * multi-line continuation. Pure state transitions, so it is unit testable
+ * without a terminal.
+ */
+export interface EditorState {
+  /** Earlier lines of an unfinished statement (shown on `|` prompts). */
+  done: string[];
+  line: string;
+  /** Cursor position within `line` (code-unit index). */
+  cursor: number;
+  history: string[];
+  /** Index into history while browsing it; -1 when editing a fresh line. */
+  hIndex: number;
+  /** The line being edited before history browsing started. */
+  draft: string;
+}
+
+export type EditAction =
+  | { type: "insert"; text: string }
+  | {
+      type:
+        | "left"
+        | "right"
+        | "home"
+        | "end"
+        | "backspace"
+        | "delete"
+        | "killLine"
+        | "killWord"
+        | "historyPrev"
+        | "historyNext"
+        | "clear";
+    };
+
+const HISTORY_MAX = 200;
+
+export function emptyEditor(history: string[] = []): EditorState {
+  return { done: [], line: "", cursor: 0, history, hIndex: -1, draft: "" };
+}
+
+export function isEditorEmpty(s: EditorState): boolean {
+  return s.done.length === 0 && s.line === "";
+}
+
+function setLine(s: EditorState, line: string, cursor = line.length): EditorState {
+  return { ...s, line, cursor: Math.max(0, Math.min(cursor, line.length)) };
+}
+
+export function edit(s: EditorState, a: EditAction): EditorState {
+  const { line, cursor } = s;
+  switch (a.type) {
+    case "insert": {
+      // Pasted newlines become spaces: the statement stays on the current line.
+      // Pasted newlines become spaces; other control characters (a stray
+      // Ctrl+D merged into a chunk of text) are dropped.
+      const text = a.text
+        .replace(/\r\n?|\n/g, " ")
+        .replace(/\t/g, "  ")
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: removing them is the point
+        .replace(/[\x00-\x1f\x7f]/g, "");
+      return setLine(s, line.slice(0, cursor) + text + line.slice(cursor), cursor + text.length);
+    }
+    case "left":
+      return setLine(s, line, cursor - 1);
+    case "right":
+      return setLine(s, line, cursor + 1);
+    case "home":
+      return setLine(s, line, 0);
+    case "end":
+      return setLine(s, line);
+    case "backspace":
+      if (cursor === 0) {
+        // Join back onto the previous continuation line.
+        if (s.done.length === 0) return s;
+        const prev = s.done[s.done.length - 1]!;
+        return { ...setLine(s, prev + line, prev.length), done: s.done.slice(0, -1) };
+      }
+      return setLine(s, line.slice(0, cursor - 1) + line.slice(cursor), cursor - 1);
+    case "delete":
+      return setLine(s, line.slice(0, cursor) + line.slice(cursor + 1), cursor);
+    case "killLine":
+      return setLine(s, line.slice(cursor), 0);
+    case "killWord": {
+      const before = line.slice(0, cursor).replace(/\S+\s*$/, "");
+      return setLine(s, before + line.slice(cursor), before.length);
+    }
+    case "historyPrev": {
+      if (s.history.length === 0) return s;
+      const hIndex = s.hIndex === -1 ? s.history.length - 1 : Math.max(0, s.hIndex - 1);
+      const draft = s.hIndex === -1 ? line : s.draft;
+      return { ...setLine(s, s.history[hIndex]!), hIndex, draft };
+    }
+    case "historyNext": {
+      if (s.hIndex === -1) return s;
+      const hIndex = s.hIndex + 1;
+      if (hIndex >= s.history.length) return { ...setLine(s, s.draft), hIndex: -1, draft: "" };
+      return { ...setLine(s, s.history[hIndex]!), hIndex };
+    }
+    case "clear":
+      return emptyEditor(s.history);
+  }
+}
+
+export type SubmitResult =
+  | { kind: "none"; state: EditorState }
+  | { kind: "continue"; state: EditorState }
+  | { kind: "command"; name: string; arg: string; state: EditorState }
+  | { kind: "statement"; text: string; state: EditorState };
+
+function remember(history: string[], entry: string): string[] {
+  const flat = entry.replace(/\s*\n\s*/g, " ").trim();
+  if (!flat || history[history.length - 1] === flat) return history;
+  return [...history, flat].slice(-HISTORY_MAX);
+}
+
+/**
+ * Enter: a dot-command, a statement to run, or — when the text looks
+ * unfinished (open quote/bracket, trailing comma/operator/keyword) — a new
+ * continuation line.
+ */
+export function submit(s: EditorState): SubmitResult {
+  const text = [...s.done, s.line].join("\n");
+  if (text.trim() === "") return { kind: "none", state: emptyEditor(s.history) };
+  if (s.done.length === 0) {
+    const m = /^\s*\.(\w+)\s*(.*)$/.exec(s.line);
+    if (m) {
+      return {
+        kind: "command",
+        name: m[1]!.toLowerCase(),
+        arg: m[2]!.trim(),
+        state: emptyEditor(remember(s.history, s.line)),
+      };
+    }
+  }
+  if (looksUnfinished(text)) {
+    return { kind: "continue", state: { ...s, done: [...s.done, s.line], line: "", cursor: 0 } };
+  }
+  return { kind: "statement", text, state: emptyEditor(remember(s.history, text)) };
+}
+
+/**
+ * The part of `line` to draw in `width` columns so the cursor stays in view:
+ * long lines scroll sideways, with "…" where text is cut off.
+ */
+export function viewport(
+  line: string,
+  cursor: number,
+  width: number,
+): { text: string; cursorCol: number } {
+  const room = Math.max(2, width - 1); // the last column holds the cursor
+  if (line.length <= room) return { text: line, cursorCol: cursor };
+  // Mid-line, keep one character visible right of the cursor (the "…" would
+  // otherwise sit under it); at the end, the cursor takes the last column.
+  const after = cursor < line.length ? 2 : 1;
+  const start = Math.max(0, Math.min(cursor - room + after, line.length - room + 1));
+  let text = line.slice(start, start + room);
+  if (start > 0) text = `…${text.slice(1)}`;
+  if (start + room < line.length) text = `${text.slice(0, -1)}…`;
+  return { text, cursorCol: cursor - start };
+}
diff --git a/src/tutorial/ui/help.ts b/src/tutorial/ui/help.ts
new file mode 100644
index 0000000..6a09598
--- /dev/null
+++ b/src/tutorial/ui/help.ts
@@ -0,0 +1,78 @@
+import chalk from "chalk";
+import { wrapLines } from "./layout.js";
+
+/** Drawer width: an inspector-style column beside the lesson (wider for the data view). */
+export function drawerWidth(screenWidth: number, mode: "help" | "data" = "help"): number {
+  if (mode === "data") return Math.max(34, Math.min(52, Math.floor(screenWidth * 0.45)));
+  return Math.max(30, Math.min(40, Math.floor(screenWidth * 0.38)));
+}
+
+const KEYS: [string, string][] = [
+  ["Enter", "run the statement"],
+  ["Tab", "hint"],
+  ["^T", "data: the collections' fields"],
+  ["^N / ^P", "next / previous lesson"],
+  ["^L", "lesson list"],
+  ["^O", "whole lesson (short window)"],
+  ["^B", "show / hide the outline"],
+  ["PgUp/PgDn", "scroll results"],
+  ["↑ / ↓", "earlier statements"],
+  ["Esc", "clear input · close help"],
+  ["?", "show / hide this help"],
+  ["^D", "quit (progress is saved)"],
+];
+
+const COMMANDS: [string, string][] = [
+  [".hint", "a nudge toward the answer"],
+  [".answer", "one correct statement"],
+  [".next .back", "move between lessons"],
+  [".goto <n>", "jump to lesson n"],
+  [".level <name>", "beginner, intermediate, advanced"],
+  [".lessons", "lesson list"],
+  [".schema", "the collections' fields (^T)"],
+  [".reset", "restore the practice data"],
+  [".break", "drop an unfinished statement"],
+  [".exit", "quit"],
+];
+
+const ABOUT = [
+  "Each lesson explains one idea and sets a **Task**. Type a statement that does it: you see the result, then ✓ or ✗ on the line above the prompt.",
+  "Any statement that does the task passes — the check looks at what it returns or changes, not its wording.",
+  "Enter runs; a trailing `;` is optional. A `|` prompt means the statement looks unfinished (an open quote or bracket, or a trailing comma, operator, or keyword like `WHERE`) — keep typing.",
+  "Lessons use their own practice store, separate from your `dittosh dql` data. Writes are safe; `.reset` restores it.",
+  "Collection and field names are case-sensitive: `products`, not `Products`. Keywords like `SELECT` work in any case.",
+  "Progress is saved as you go.",
+];
+
+/** `**bold**` / `` `code` `` in the help prose. */
+function style(text: string): string {
+  return text
+    .replace(/\*\*([^*]+)\*\*/g, (_, t: string) => chalk.bold(t))
+    .replace(/`([^`]+)`/g, (_, t: string) => chalk.cyan(t));
+}
+
+function table(rows: [string, string][], width: number): string[] {
+  const keyWidth = Math.min(14, Math.max(...rows.map(([k]) => k.length)));
+  return rows.flatMap(([k, v]) => {
+    const pad = " ".repeat(keyWidth + 2);
+    const wrapped = wrapLines([v], Math.max(8, width - keyWidth - 2));
+    return wrapped.map((line, i) =>
+      i === 0 ? `${chalk.cyan(k.padEnd(keyWidth))}  ${line}` : pad + line,
+    );
+  });
+}
+
+/** The drawer's lines, wrapped to its inner `width`. */
+export function helpLines(width: number): string[] {
+  const h = (t: string) => chalk.bold.magenta(t);
+  return [
+    h("Keys"),
+    ...table(KEYS, width),
+    "",
+    h("Commands"),
+    ...table(COMMANDS, width),
+    "",
+    h("How it works"),
+    ...ABOUT.flatMap((p, i) => [...(i > 0 ? [""] : []), ...wrapLines([style(p)], width)]),
+  ];
+}
diff --git a/src/tutorial/ui/layout.ts b/src/tutorial/ui/layout.ts
new file mode 100644
index 0000000..80ec2fa
--- /dev/null
+++ b/src/tutorial/ui/layout.ts
@@ -0,0 +1,91 @@
+import { stripVTControlCharacters } from "node:util";
+import chalk from "chalk";
+import stringWidth from "string-width";
+import wrapAnsi from "wrap-ansi";
+
+/** Box-drawing characters: tables, plan trees, profile bars. */
+const DRAWING = /[\u2500-\u257f]/;
+
+/**
+ * Word-wrap styled text to `width` columns; one array entry per screen line.
+ * Each source line keeps its indentation, and wrapped rows get the same indent.
+ * Drawn lines (tables, plan trees) are never wrapped — wrapping would break
+ * them apart — so the panel cuts them off with "…" instead.
+ */
+export function wrapLines(blocks: readonly string[], width: number): string[] {
+  const w = Math.max(1, width);
+  return blocks.flatMap((block) =>
+    block.split("\n").flatMap((line) => {
+      const plain = stripVTControlCharacters(line);
+      if (DRAWING.test(plain)) return [line];
+      const indent = /^ */.exec(plain)?.[0].length ?? 0;
+      if (indent === 0 || indent >= w - 4) {
+        return wrapAnsi(line, w, { hard: true, trim: indent === 0 }).split("\n");
+      }
+      const pad = " ".repeat(indent);
+      return wrapAnsi(line.replace(/^( *)/, ""), w - indent, { hard: true })
+        .split("\n")
+        .map((row) => pad + row);
+    }),
+  );
+}
+
+/**
+ * Fit the lesson card into `rows`: when it's too tall, the middle gives way so
+ * the task (the last lines) always stays visible.
+ */
+export function fitCard(
+  body: readonly string[],
+  task: readonly string[],
+  rows: number,
+  more: string,
+): string[] {
+  if (body.length + task.length <= rows) return [...body, ...task];
+  const keep = rows - task.length - 1;
+  if (keep < 1) return [...task.slice(0, Math.max(0, rows - 1)), more];
+  return [...body.slice(0, keep), more, ...task];
+}
+
+/**
+ * The `height` lines visible when scrolled `offset` lines up from the bottom.
+ * Returns the clamped offset too (it can't scroll past the top).
+ */
+export function scrollWindow(
+  lines: readonly string[],
+  height: number,
+  offset: number,
+): { visible: string[]; offset: number; above: number; below: number } {
+  const h = Math.max(0, height);
+  const maxOffset = Math.max(0, lines.length - h);
+  const o = Math.max(0, Math.min(offset, maxOffset));
+  const end = lines.length - o;
+  const start = Math.max(0, end - h);
+  return { visible: lines.slice(start, end), offset: o, above: start, below: o };
+}
+
+/** The slice of a list to show so that `selected` stays in view. */
+export function listWindow(count: number, height: number, selected: number): [number, number] {
+  const h = Math.max(1, height);
+  if (count <= h) return [0, count];
+  const start = Math.max(0, Math.min(selected - Math.floor(h / 2), count - h));
+  return [start, start + h];
+}
+
+/** `████░░░░ 4/27` */
+export function progressBar(done: number, total: number, width: number): string {
+  const w = Math.max(4, width);
+  const filled = total > 0 ? Math.round((done / total) * w) : 0;
+  return `${chalk.green("█".repeat(filled))}${chalk.dim("░".repeat(w - filled))} ${done}/${total}`;
+}
+
+/** Truncate styled text to `width` display columns (drops styling when cut). */
+export function clip(text: string, width: number): string {
+  if (stringWidth(text) <= width) return text;
+  const plain = stripVTControlCharacters(text);
+  let out = "";
+  for (const ch of plain) {
+    if (stringWidth(`${out + ch}…`) > width) break;
+    out += ch;
+  }
+  return `${out}…`;
+}
diff --git a/src/tutorial/ui/limits.ts b/src/tutorial/ui/limits.ts
new file mode 100644
index 0000000..1fc7fd6
--- /dev/null
+++ b/src/tutorial/ui/limits.ts
@@ -0,0 +1,3 @@
+/** Smallest terminal the full-screen lessons are drawn in; below it, the plain shell. */
+export const MIN_COLUMNS = 60;
+export const MIN_ROWS = 20;
diff --git a/src/tutorial/ui/outline.ts b/src/tutorial/ui/outline.ts
new file mode 100644
index 0000000..d3ab12f
--- /dev/null
+++ b/src/tutorial/ui/outline.ts
@@ -0,0 +1,83 @@
+import chalk from "chalk";
+import stringWidth from "string-width";
+import { LEVELS, type Lesson, type Level } from "../lessons.js";
+import { clip, listWindow, wrapLines } from "./layout.js";
+
+/** The narrowest window that shows the sidebar by default. */
+export const OUTLINE_MIN_SCREEN = 90;
+
+/** Sidebar width: wider on big screens so lesson titles fit. */
+export function outlineWidth(screenWidth: number): number {
+  return Math.max(28, Math.min(36, Math.floor(screenWidth * 0.26)));
+}
+
+const LEVEL_LABEL: Record<Level, string> = {
+  beginner: "Beginner",
+  intermediate: "Intermediate",
+  advanced: "Advanced",
+};
+
+export interface OutlineInput {
+  lessons: readonly Lesson[];
+  current: number;
+  isCompleted: (i: number) => boolean;
+}
+
+/**
+ * The sidebar: every level with its progress; the current level expanded to
+ * its lessons (✓ done, ▸ current). Fits `rows` lines of `width` columns,
+ * scrolling the lesson list so the current lesson stays in view.
+ */
+export function outlineLines(
+  { lessons, current, isCompleted }: OutlineInput,
+  width: number,
+  rows: number,
+): string[] {
+  const currentLevel = lessons[current]?.level;
+  const right = (left: string, r: string) => {
+    const l = clip(left, width - r.length - 1);
+    const gap = Math.max(1, width - stringWidth(l) - r.length);
+    return `${l}${" ".repeat(gap)}${chalk.dim(r)}`;
+  };
+  const done = lessons.filter((_, i) => isCompleted(i)).length;
+  const head = [right(chalk.bold("Lessons"), `${done}/${lessons.length}`), ""];
+
+  const levelRows: { level: Level; line: string }[] = LEVELS.map((level) => {
+    const idx = lessons.flatMap((l, i) => (l.level === level ? [i] : []));
+    const n = idx.filter(isCompleted).length;
+    const open = level === currentLevel;
+    const label = `${open ? "▾" : "▸"} ${LEVEL_LABEL[level]}`;
+    return {
+      level,
+      line: right(open ? chalk.bold.magenta(label) : chalk.magenta(label), `${n}/${idx.length}`),
+    };
+  });
+
+  const items = lessons.flatMap((l, i) => (l.level === currentLevel ? [i] : []));
+  // Each lesson: "  ✓ 12 Title words" with the title wrapped under itself.
+  const titleWidth = Math.max(6, width - 7);
+  const itemLines: string[] = [];
+  let currentLine = 0;
+  for (const i of items) {
+    const mark = i === current ? chalk.cyan("▸") : isCompleted(i) ? chalk.green("✓") : " ";
+    const style = (t: string) => (i === current ? chalk.bold.cyan(t) : t);
+    const titleRows = wrapLines([lessons[i]!.title], titleWidth);
+    if (i === current) currentLine = itemLines.length;
+    titleRows.forEach((row, r) => {
+      const prefix = r === 0 ? `  ${mark} ${String(i + 1).padStart(2)} ` : "       ";
+      itemLines.push(`${prefix}${style(row)}`);
+    });
+  }
+
+  // Rows left for the open level's lessons, after the header and level rows.
+  const room = Math.max(1, rows - head.length - levelRows.length);
+  const [from, to] = listWindow(itemLines.length, room, currentLine);
+  const shown = itemLines.slice(from, to);
+  if (from > 0) shown[0] = chalk.dim("    …");
+  if (to < itemLines.length) shown[shown.length - 1] = chalk.dim("    …");
+
+  return [
+    ...head,
+    ...levelRows.flatMap((r) => (r.level === currentLevel ? [r.line, ...shown] : [r.line])),
+  ];
+}
diff --git a/src/tutorial/ui/store.ts b/src/tutorial/ui/store.ts
new file mode 100644
index 0000000..23ad33f
--- /dev/null
+++ b/src/tutorial/ui/store.ts
@@ -0,0 +1,85 @@
+/**
+ * The bridge between LessonRunner (plain TypeScript) and the React screen.
+ * The runner prints into the log and signals lesson changes; components
+ * subscribe through useSyncExternalStore. No React here, so the runner
+ * never depends on the UI.
+ */
+export interface UiSnapshot {
+  log: readonly string[];
+  /** Bumped whenever the current lesson changes. */
+  lessonVersion: number;
+  /** Total entries ever printed (the log itself is capped). */
+  printed: number;
+  /** The latest verdict (✓ / ✗ / query error), shown above the prompt. */
+  status: string | null;
+}
+
+export interface UiStore {
+  print: (text: string) => void;
+  lessonChanged: () => void;
+  /** Empty the log (each action starts with a clean results panel). */
+  clear: () => void;
+  setStatus: (text: string | null) => void;
+  subscribe: (cb: () => void) => () => void;
+  snapshot: () => UiSnapshot;
+  /** Output panel width, so the runner fits result tables to it. */
+  width: () => number;
+  setWidth: (width: number) => void;
+  /** Note work in progress (a statement, a lesson change, a data-view read). */
+  track: (work: Promise<unknown>) => void;
+  /** Resolves once all tracked work has settled — wait for it before closing the store. */
+  idle: () => Promise<void>;
+}
+
+export function createUiStore(opts: { width?: number; maxEntries?: number } = {}): UiStore {
+  const maxEntries = opts.maxEntries ?? 300;
+  let width = opts.width ?? 76;
+  let snap: UiSnapshot = { log: [], lessonVersion: 0, printed: 0, status: null };
+  const subs = new Set<() => void>();
+  const pending = new Set<Promise<unknown>>();
+  const emit = () => {
+    for (const cb of subs) cb();
+  };
+  return {
+    print(text) {
+      snap = { ...snap, log: [...snap.log, text].slice(-maxEntries), printed: snap.printed + 1 };
+      emit();
+    },
+    clear() {
+      if (snap.log.length === 0) return;
+      snap = { ...snap, log: [] };
+      emit();
+    },
+    lessonChanged() {
+      snap = { ...snap, lessonVersion: snap.lessonVersion + 1 };
+      emit();
+    },
+    setStatus(status) {
+      if (status === snap.status) return;
+      snap = { ...snap, status };
+      emit();
+    },
+    subscribe(cb) {
+      subs.add(cb);
+      return () => {
+        subs.delete(cb);
+      };
+    },
+    snapshot: () => snap,
+    track(work) {
+      const settled = work.then(
+        () => {},
+        () => {},
+      );
+      pending.add(settled);
+      void settled.then(() => pending.delete(settled));
+    },
+    async idle() {
+      while (pending.size > 0) await Promise.all([...pending]);
+    },
+    width: () => width,
+    setWidth(w) {
+      width = w;
+    },
+  };
+}
diff --git a/tests/e2e/bench.test.ts b/tests/e2e/bench.test.ts
new file mode 100644
index 0000000..47f2583
--- /dev/null
+++ b/tests/e2e/bench.test.ts
@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execa } from "execa";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { hasDevCredentials, NO_CREDENTIALS, rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+const ROOT = path.resolve(import.meta.dirname, "../..");
+
+function cli(args: string[]) {
+  return execa(process.execPath, ["--import", "tsx", "src/cli/index.ts", ...args], {
+    cwd: ROOT,
+    reject: false,
+    input: "",
+  });
+}
+
+describe.skipIf(!hasDevCredentials)(`e2e: dittosh dql bench (${NO_CREDENTIALS})`, () => {
+  let dir: string;
+  beforeAll(async () => {
+    dir = tmpDataDir("ditto-bench-e2e-");
+    const r = await cli(["dql", "dataset", "load", "pos", "--docs", "100", "-d", dir]);
+    expect(r.exitCode).toBe(0);
+  }, 120_000);
+  afterAll(() => rmrf(dir));
+
+  it("--example writes a sample file to stdout without opening a store", async () => {
+    const r = await cli(["dql", "bench", "--example", "pos"]);
+    expect(r.exitCode).toBe(0);
+    const file = JSON.parse(r.stdout);
+    expect(file.pos_orders__insert__new_order.resetQueries.length).toBeGreaterThan(0);
+  });
+
+  it("runs the sample file: JSON results on stdout, progress on stderr", async () => {
+    const file = path.join(dir, "pos-bench.json");
+    expect((await cli(["dql", "bench", "--example", "pos", "-o", file])).exitCode).toBe(0);
+    const r = await cli(["dql", "bench", "-f", file, "--runs", "5", "--warmup", "2", "-d", dir]);
+    expect(r.exitCode).toBe(0);
+    const rows = JSON.parse(r.stdout);
+    expect(rows).toHaveLength(Object.keys(JSON.parse(fs.readFileSync(file, "utf8"))).length);
+    for (const row of rows) {
+      expect(row).toMatchObject({ runs: 5, warmup: 2 });
+      expect(row.p95_ms).toBeGreaterThan(0);
+    }
+    expect(r.stderr).toContain("Benchmarking 4 benchmarks: 5 timed runs each, 2 warmup runs.");
+  });
+
+  it("times a statement given on the command line (flags before bench too)", async () => {
+    const r = await cli(["dql", "-d", dir, "bench", "SELECT * FROM locations", "--runs", "3"]);
+    expect(r.exitCode).toBe(0);
+    expect(JSON.parse(r.stdout)[0]).toMatchObject({
+      benchmark: "SELECT * FROM locations",
+      rows: 7,
+    });
+  });
+
+  it("dataset run --runs benchmarks a catalog query", async () => {
+    const r = await cli([
+      "dql",
+      "dataset",
+      "run",
+      "pos_orders__agg__count_all",
+      "--runs",
+      "3",
+      "-d",
+      dir,
+    ]);
+    expect(r.exitCode).toBe(0);
+    expect(JSON.parse(r.stdout)[0]).toMatchObject({
+      benchmark: "pos_orders__agg__count_all",
+      runs: 3,
+    });
+  });
+
+  it("exits 1 when the query fails and 2 for usage errors", async () => {
+    const bad = await cli(["dql", "bench", "SELECT * FROM", "--runs", "2", "-d", dir]);
+    expect(bad.exitCode).toBe(1);
+    expect(bad.stderr).toContain("failed in query");
+    const usage = await cli(["dql", "bench", "-d", dir]);
+    expect(usage.exitCode).toBe(2);
+  });
+});
diff --git a/tests/e2e/doctor-report.test.ts b/tests/e2e/doctor-report.test.ts
new file mode 100644
index 0000000..22a0a37
--- /dev/null
+++ b/tests/e2e/doctor-report.test.ts
@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execa } from "execa";
+import * as tar from "tar";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { hasDevCredentials, NO_CREDENTIALS, rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+const ROOT = path.resolve(import.meta.dirname, "../..");
+
+describe.skipIf(!hasDevCredentials)(`e2e: doctor --report (${NO_CREDENTIALS})`, () => {
+  let dir: string;
+  let store: string;
+  let cfg: string;
+
+  const cli = (args: string[], env: Record<string, string> = {}) =>
+    execa(process.execPath, ["--import", "tsx", "src/cli/index.ts", ...args], {
+      cwd: ROOT,
+      reject: false,
+      input: "",
+      env: { DITTOSH_CONFIG_DIR: cfg, ...env },
+    });
+
+  beforeAll(async () => {
+    dir = tmpDataDir("ditto-report-e2e-");
+    store = path.join(dir, "store");
+    cfg = path.join(dir, "cfg");
+    const r = await cli(["dql", "INSERT INTO cars DOCUMENTS ({'_id': 'a'})", "-d", store]);
+    expect(r.exitCode).toBe(0);
+  }, 120_000);
+  afterAll(() => rmrf(dir));
+
+  it("a failed command is saved, and doctor --report bundles it with the SDK bundle", async () => {
+    const bad = await cli(["dql", "SELEC oops FROM cars", "-d", store]);
+    expect(bad.exitCode).toBe(1);
+    const last = JSON.parse(fs.readFileSync(path.join(cfg, "last-error.json"), "utf8"));
+    expect(last.command).toContain("SELEC oops FROM cars");
+    expect(last.stderr.join("\n")).toContain("Query error");
+
+    const out = path.join(dir, "report.tar.gz");
+    const r = await cli(["doctor", "-d", store, "--report", out]);
+    expect(r.exitCode).toBe(0);
+    expect(r.stdout).toContain("✓ platform");
+    expect(r.stdout).not.toContain("Wrote");
+    expect(r.stderr).toContain("Wrote");
+    expect(r.stderr).toContain("issues/new");
+
+    const names: string[] = [];
+    await tar.t({ file: out, onReadEntry: (e) => names.push(e.path) });
+    expect(names.sort()).toEqual([
+      "report/",
+      "report/ditto-support-bundle.tar",
+      "report/report.json",
+      "report/report.md",
+    ]);
+    const x = path.join(dir, "x");
+    fs.mkdirSync(x);
+    await tar.x({ file: out, cwd: x });
+    const md = fs.readFileSync(path.join(x, "report", "report.md"), "utf8");
+    expect(md).toContain("| cars | 1 |");
+    expect(md).toContain("SELEC oops FROM cars");
+
+    // Running doctor didn't replace the saved error.
+    expect(
+      JSON.parse(fs.readFileSync(path.join(cfg, "last-error.json"), "utf8")).command,
+    ).toContain("SELEC oops FROM cars");
+  }, 120_000);
+
+  it("dql support-bundle saves the SDK bundle; --list shows it as JSON when piped", async () => {
+    const out = path.join(dir, "sb.tar");
+    const r = await cli(["dql", "support-bundle", "-d", store, "-o", out]);
+    expect(r.exitCode).toBe(0);
+    expect(r.stdout).toBe("");
+    expect(fs.statSync(out).size).toBeGreaterThan(0);
+    const list = await cli(["dql", "support-bundle", "-d", store, "--list"]);
+    expect(list.exitCode).toBe(0);
+    expect(JSON.parse(list.stdout).length).toBeGreaterThanOrEqual(1);
+  }, 120_000);
+
+  it("--debug sends SDK logs to stderr and leaves stdout as clean JSON", async () => {
+    const r = await cli(["--debug", "dql", "SELECT count(*) AS n FROM cars", "-d", store]);
+    expect(r.exitCode).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual([{ n: 1 }]);
+    expect(r.stderr).toContain("DEBUG");
+    const quiet = await cli(["dql", "SELECT count(*) AS n FROM cars", "-d", store]);
+    expect(quiet.stderr).not.toContain("DEBUG");
+  }, 120_000);
+});
diff --git a/tests/e2e/tutorial.test.ts b/tests/e2e/tutorial.test.ts
new file mode 100644
index 0000000..dd6190c
--- /dev/null
+++ b/tests/e2e/tutorial.test.ts
@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { execa } from "execa";
+import { describe, expect, it } from "vitest";
+import { type TutorialContext, tutorialSections } from "../../src/tutorial/content.js";
+import { hasDevCredentials, NO_CREDENTIALS, rmrf } from "../helpers/credentials.js";
+
+const ROOT = path.resolve(import.meta.dirname, "../..");
+const TSX = pathToFileURL(path.join(ROOT, "node_modules/tsx/dist/loader.mjs")).href;
+const ENTRY = path.join(ROOT, "src/cli/index.ts");
+
+function cli(args: string[], opts: { cwd?: string } = {}) {
+  return execa(process.execPath, ["--import", TSX, ENTRY, ...args], {
+    cwd: opts.cwd ?? ROOT,
+    reject: false,
+    env: { DITTOSH_NO_UPDATE_CHECK: "1" },
+  });
+}
+
+const CTX: TutorialContext = {
+  cliVersion: JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8")).version,
+  sdkVersion: "5.2.0",
+  channel: "npm",
+  platform: `${process.platform}/${process.arch}`,
+  generatedOn: "2026-11-06",
+};
+
+describe("e2e: dittosh tutorial (Markdown generator)", () => {
+  it("writes the tutorial file, refuses to overwrite without --force", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dittosh-tut-"));
+    try {
+      const first = await cli(["tutorial"], { cwd: dir });
+      expect(first.exitCode).toBe(0);
+      expect(first.stdout).toBe("");
+      expect(first.stderr).toContain("Wrote the tutorial to");
+      const md = fs.readFileSync(path.join(dir, "dittosh-tutorial.md"), "utf8");
+      expect(md).toMatch(/^# Ditto CLI: a hands-on tutorial/);
+      expect(md).toContain("Diagnostics and advanced DQL");
+      expect(md).toContain("dittosh tutorial --interactive");
+
+      const again = await cli(["tutorial"], { cwd: dir });
+      expect(again.exitCode).toBe(2);
+      expect(again.stderr).toContain("--force");
+
+      const forced = await cli(["tutorial", "--force", "-o", "custom.md"], { cwd: dir });
+      expect(forced.exitCode).toBe(0);
+      expect(fs.existsSync(path.join(dir, "custom.md"))).toBe(true);
+    } finally {
+      rmrf(dir);
+    }
+  });
+
+  it("--stdout prints the Markdown; --interactive needs a terminal", async () => {
+    const r = await cli(["tutorial", "--stdout"]);
+    expect(r.exitCode).toBe(0);
+    expect(r.stdout).toContain("## 1. Check your installation");
+
+    const both = await cli(["tutorial", "--stdout", "--out", "x.md"]);
+    expect(both.exitCode).toBe(2);
+
+    for (const flag of [["--level", "advanced"], ["--plain"]]) {
+      const stray = await cli(["tutorial", ...flag]);
+      expect(stray.exitCode).toBe(2);
+      expect(stray.stderr).toContain("only apply with --interactive");
+    }
+
+    const notty = await cli(["tutorial", "--interactive"]);
+    expect(notty.exitCode).toBe(2);
+    expect(notty.stderr).toContain("need a terminal");
+  });
+});
+
+/**
+ * Runs every runnable bash block of the generated tutorial, in order, in one
+ * bash process — exactly as a reader would — with `dittosh` pointing at this
+ * checkout. Catches tutorial commands that drift out of date.
+ */
+describe.skipIf(!hasDevCredentials)(
+  `e2e: tutorial commands run as written (${NO_CREDENTIALS})`,
+  () => {
+    it("every runnable block succeeds and shows its expected output", async () => {
+      const blocks = tutorialSections(CTX).flatMap((s, si) =>
+        s.blocks.flatMap((b, bi) =>
+          b.kind === "code" && b.run ? [{ id: `${si + 1}.${bi}`, title: s.title, ...b }] : [],
+        ),
+      );
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "dittosh-tut-run-"));
+      const script = [
+        "set -euo pipefail",
+        `dittosh() { "${process.execPath}" --import "${TSX}" "${ENTRY}" "$@"; }`,
+        ...blocks.flatMap((b) => [`echo "@@BLOCK ${b.id}"`, b.code]),
+        'echo "@@END"',
+      ].join("\n");
+      try {
+        const r = await execa("bash", ["-c", script], {
+          cwd: tmp,
+          reject: false,
+          env: { TMPDIR: tmp, DITTOSH_NO_UPDATE_CHECK: "1" },
+        });
+        const failedAt = r.stdout.match(/@@BLOCK (\S+)(?![\s\S]*@@BLOCK)/)?.[1];
+        expect(
+          r.exitCode,
+          `tutorial failed in block ${failedAt}:\n${r.stderr.split("\n").slice(-15).join("\n")}`,
+        ).toBe(0);
+        expect(r.stdout).toContain("@@END");
+        const outputs = new Map<string, string>();
+        for (const part of r.stdout.split("@@BLOCK ").slice(1)) {
+          const nl = part.indexOf("\n");
+          outputs.set(part.slice(0, nl), part.slice(nl + 1));
+        }
+        for (const b of blocks) {
+          for (const want of b.expect ?? []) {
+            expect(outputs.get(b.id), `block ${b.id} (${b.title}) should print ${want}`).toContain(
+              want,
+            );
+          }
+        }
+      } finally {
+        rmrf(tmp);
+      }
+    }, 300_000);
+  },
+);
diff --git a/tests/integration/bench.test.ts b/tests/integration/bench.test.ts
new file mode 100644
index 0000000..9ed06ae
--- /dev/null
+++ b/tests/integration/bench.test.ts
@@ -0,0 +1,76 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { exampleBenchFile } from "../../src/bench/example.js";
+import { runBenchmark } from "../../src/bench/runner.js";
+import { parseBenchFile } from "../../src/bench/spec.js";
+import { loadDataset } from "../../src/datasets/loader.js";
+import { DATASETS } from "../../src/datasets/registry.js";
+import { DittoSession } from "../../src/ditto/session.js";
+import { loadIdentity } from "../../src/identity/token.js";
+import { extractRows } from "../../src/query/execute.js";
+import { hasDevCredentials, NO_CREDENTIALS, rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+describe.skipIf(!hasDevCredentials)(`integration: bench (${NO_CREDENTIALS})`, () => {
+  let dataDir: string;
+  let session: DittoSession;
+
+  beforeAll(async () => {
+    dataDir = tmpDataDir("ditto-bench-");
+    session = await DittoSession.open(loadIdentity(), dataDir);
+  });
+
+  afterAll(async () => {
+    await session?.close();
+    rmrf(dataDir);
+  });
+
+  /** Document counts per collection plus the index list: the state a benchmark must restore. */
+  async function snapshot(collections: string[]) {
+    const counts: Record<string, unknown> = {};
+    for (const c of collections) {
+      counts[c] = extractRows(await session.execute(`SELECT count(*) AS n FROM ${c}`))[0]!.n;
+    }
+    const indexes = extractRows(await session.execute("SELECT _id FROM system:indexes"))
+      .map((r) => JSON.stringify(r._id))
+      .sort();
+    return { counts, indexes };
+  }
+
+  it.each(DATASETS.map((d) => d.name))(
+    "the %s sample file runs cleanly and leaves the store as it found it",
+    async (name) => {
+      const suite = DATASETS.find((d) => d.name === name)!;
+      await loadDataset(session, suite, { docs: 60, seed: 42, batchSize: 500 });
+      const collections = suite.collections.map((c) => c.name);
+      const before = await snapshot(collections);
+
+      const specs = parseBenchFile(JSON.stringify(exampleBenchFile(suite)), name);
+      for (const spec of specs) {
+        const r = await runBenchmark(session, spec, { runs: 3, warmup: 2 });
+        expect(r.failure, `${spec.name}: ${r.failure?.error}`).toBeUndefined();
+        expect(r.cleanupFailures, spec.name).toEqual([]);
+        expect(r.runs).toBe(3);
+        expect(r.stats!.p99).toBeGreaterThan(0);
+      }
+
+      expect(await snapshot(collections)).toEqual(before);
+    },
+    60_000,
+  );
+
+  it("auto warmup runs at least once against a real store", async () => {
+    const r = await runBenchmark(
+      session,
+      {
+        name: "n",
+        query: "SELECT count(*) FROM movies",
+        preQueries: [],
+        resetQueries: [],
+        postQueries: [],
+      },
+      { runs: 2, warmup: "auto" },
+    );
+    expect(r.ok).toBe(true);
+    expect(r.warmup).toBeGreaterThanOrEqual(1);
+    expect(r.rows).toBe(1);
+  });
+});
diff --git a/tests/integration/lessons.test.ts b/tests/integration/lessons.test.ts
new file mode 100644
index 0000000..89a8d50
--- /dev/null
+++ b/tests/integration/lessons.test.ts
@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { DittoSession } from "../../src/ditto/session.js";
+import { loadIdentity } from "../../src/identity/token.js";
+import { LESSONS, LEVELS } from "../../src/tutorial/lessons.js";
+import { LessonRunner } from "../../src/tutorial/runner.js";
+import { hasDevCredentials, NO_CREDENTIALS, rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+describe.skipIf(!hasDevCredentials)(`integration: tutorial lessons (${NO_CREDENTIALS})`, () => {
+  let dataDir: string;
+  let session: DittoSession;
+  let output: string[];
+  let runner: LessonRunner;
+
+  beforeAll(async () => {
+    dataDir = tmpDataDir();
+    session = await DittoSession.open(loadIdentity(), dataDir);
+    output = [];
+    runner = new LessonRunner(session, {
+      io: { print: (t) => output.push(t), width: () => 100 },
+    });
+    await runner.start();
+  });
+
+  afterAll(async () => {
+    await session?.close();
+    rmrf(dataDir);
+  });
+
+  it("covers all three levels, in order", () => {
+    const levels = LESSONS.map((l) => l.level);
+    for (const level of LEVELS) expect(levels).toContain(level);
+    expect([...levels]).toEqual([...levels].sort((a, b) => LEVELS.indexOf(a) - LEVELS.indexOf(b)));
+  });
+
+  it("every lesson's sample answer passes its own check, in sequence", async () => {
+    for (const [i, lesson] of LESSONS.entries()) {
+      expect(runner.current, `lesson ${i + 1}`).toBe(i);
+      output.length = 0;
+      const ok = await runner.submit(lesson.answer);
+      expect(ok, `lesson ${i + 1} "${lesson.title}":\n${output.join("\n")}`).toBe(true);
+    }
+    expect(runner.completedCount).toBe(LESSONS.length);
+    expect(output.join("\n")).toContain(`finished all ${LESSONS.length} lessons`);
+  });
+
+  it("each lesson's sample answer also passes when started directly (setup is self-contained)", async () => {
+    await runner.resetData();
+    for (const [i, lesson] of LESSONS.entries()) {
+      await runner.goto(String(i + 1));
+      output.length = 0;
+      const ok = await runner.submit(lesson.answer);
+      expect(ok, `lesson ${i + 1} "${lesson.title}":\n${output.join("\n")}`).toBe(true);
+    }
+  });
+
+  it("every complete syntax example is valid DQL against the practice data", async () => {
+    const runnable = /^(SELECT|INSERT|UPDATE|EVICT|EXPLAIN|PROFILE|CREATE)\b/i;
+    const placeholder = /…|\bcollection(_a|_b)?\b|\bfield(_a|_b)?\b|\bidx_name\b|</;
+    let ran = 0;
+    for (const [i, lesson] of LESSONS.entries()) {
+      for (const line of lesson.syntax) {
+        const statement = line.replace(/\s+--.*$/, "").trim();
+        if (!runnable.test(statement) || placeholder.test(statement)) continue;
+        await runner.resetData();
+        for (const s of lesson.setup ?? []) await session.execute(s);
+        await expect(
+          session.execute(statement),
+          `lesson ${i + 1} example: ${statement}`,
+        ).resolves.toBeDefined();
+        ran++;
+      }
+    }
+    expect(ran).toBeGreaterThan(15);
+    await runner.resetData();
+  });
+
+  it("the data view reads every lesson's collections from the real store", async () => {
+    await runner.resetData();
+    for (const [i] of LESSONS.entries()) {
+      await runner.goto(String(i + 1));
+      const schemas = await runner.schema();
+      expect(schemas.length, `lesson ${i + 1}`).toBeGreaterThan(0);
+      for (const s of schemas) {
+        expect(s.fields.length, `lesson ${i + 1} ${s.collection}`).toBeGreaterThan(0);
+      }
+    }
+    await runner.goto(String(LESSONS.findIndex((l) => l.title === "Joining collections") + 1));
+    const [products, suppliers] = await runner.schema();
+    expect(products?.fields.map((f) => f.path)).toContain("supplier_id");
+    expect(suppliers?.fields.map((f) => f.path)).toContain("country");
+  });
+
+  it("a wrong-case collection name is explained, not just 'no rows'", async () => {
+    await runner.goto("1");
+    output.length = 0;
+    expect(await runner.submit("SELECT * FROM Products")).toBe(false);
+    expect(output.join("\n")).toContain("Collection names are case-sensitive");
+  });
+
+  it("skipping a lesson can't leave data behind that breaks a later answer", async () => {
+    const at = (title: string) => LESSONS.findIndex((l) => l.title === title);
+    // Insert p7, then skip the lesson that evicts it, plus a stray write.
+    await runner.goto(String(at("Inserting documents") + 1));
+    expect(await runner.submit(LESSONS[at("Inserting documents")]!.answer)).toBe(true);
+    await session.execute(
+      "INSERT INTO products VALUES ({'_id': 'p9', 'name': 'Kettle', 'price': 30})",
+    );
+    for (const title of ["Expressions and functions", "Aggregate functions", "Outer joins"]) {
+      await runner.goto(String(at(title) + 1));
+      output.length = 0;
+      const ok = await runner.submit(LESSONS[at(title)]!.answer);
+      expect(ok, `${title}:\n${output.join("\n")}`).toBe(true);
+    }
+  });
+
+  it("a command while a statement is being checked can't mark the wrong lesson", async () => {
+    const fresh = new LessonRunner(session, { io: { print: () => {}, width: () => 100 } });
+    await fresh.start();
+    const submitted = fresh.submit(LESSONS[0]!.answer);
+    const moved = fresh.goto("5"); // concurrently, as a plain-shell command could
+    await Promise.all([submitted, moved]);
+    expect(fresh.isCompleted(0)).toBe(true);
+    expect(fresh.isCompleted(4)).toBe(false);
+    expect(fresh.current).toBe(4); // the jump wins; no extra advance
+  });
+
+  it("wrong answers are rejected with a reason and don't advance", async () => {
+    await runner.resetData();
+    await runner.goto("3"); // Filtering: coffee products
+    output.length = 0;
+    expect(await runner.submit("SELECT name FROM products WHERE category = 'tea'")).toBe(false);
+    expect(output.join("\n")).toContain("Not quite");
+    expect(runner.current).toBe(2);
+  });
+
+  it("query errors are reported without advancing", async () => {
+    output.length = 0;
+    expect(await runner.submit("SELEKT * FROM products")).toBe(false);
+    expect(output.join("\n")).toContain("Query error");
+    expect(runner.current).toBe(2);
+  });
+});
diff --git a/tests/integration/session.test.ts b/tests/integration/session.test.ts
index 76d6582..a01d046 100644
--- a/tests/integration/session.test.ts
+++ b/tests/integration/session.test.ts
@@ -1,7 +1,9 @@
 import fs from "node:fs";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { makeMetricsCommand } from "../../src/cli/groups/dql/metrics.js";
 import { DittoSession, LockError } from "../../src/ditto/session.js";
 import { loadIdentity } from "../../src/identity/token.js";
+import { buildSections, isExporterDisabled } from "../../src/metrics/system-metrics.js";
 import { classify, extractRows } from "../../src/query/execute.js";
 import { hasDevCredentials, NO_CREDENTIALS, rmrf, tmpDataDir } from "../helpers/credentials.js";
 
@@ -28,6 +30,24 @@ describe.skipIf(!hasDevCredentials)(`integration: DittoSession (${NO_CREDENTIALS
     expect(rows.map((r) => r.title)).toEqual(["Alien", "Blade Runner", "Toy Story"]);
   });
 
+  it("exposes system:metrics (exporter enabled at open) with store and query series", async () => {
+    await session.execute("SELECT * FROM movies");
+    const rows = extractRows(await session.execute("SELECT * FROM system:metrics"));
+    expect(isExporterDisabled(rows)).toBe(false);
+    const ids = buildSections(rows).map((s) => s.id);
+    expect(ids).toContain("store");
+    expect(ids).toContain("query");
+  });
+
+  it(".metrics renders the store and query tables from the live store", async () => {
+    const metrics = makeMetricsCommand(session, { maxWidth: () => 120 });
+    const r = await metrics();
+    expect(r.ok).toBe(true);
+    expect(r.text).toContain("Store · counters");
+    expect(r.text).toContain("Query (DQL) · timings & distributions");
+    expect(r.text).toMatch(/requests/);
+  });
+
   it("persists data across sessions in the same data dir", async () => {
     await session.close();
     session = await DittoSession.open(loadIdentity(), dataDir);
diff --git a/tests/integration/support.test.ts b/tests/integration/support.test.ts
new file mode 100644
index 0000000..4a1ac30
--- /dev/null
+++ b/tests/integration/support.test.ts
@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import * as tar from "tar";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { DittoSession } from "../../src/ditto/session.js";
+import { loadIdentity } from "../../src/identity/token.js";
+import { collectReport, renderReport } from "../../src/support/report.js";
+import { listSupportBundles, saveSupportBundle } from "../../src/support/sdk-bundle.js";
+import { hasDevCredentials, NO_CREDENTIALS, rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+async function tarEntries(file: string): Promise<string[]> {
+  const names: string[] = [];
+  await tar.t({ file, onReadEntry: (e) => names.push(e.path) });
+  return names;
+}
+
+describe.skipIf(!hasDevCredentials)(`integration: support bundles (${NO_CREDENTIALS})`, () => {
+  let dataDir: string;
+  let work: string;
+
+  beforeAll(async () => {
+    dataDir = tmpDataDir("ditto-support-int-");
+    work = tmpDataDir("ditto-support-work-");
+    const session = await DittoSession.open(loadIdentity(), dataDir);
+    try {
+      await session.execute("INSERT INTO cars DOCUMENTS ({'_id': 'a', 'make': 'Ford'})");
+      await session.execute("INSERT INTO cars DOCUMENTS ({'_id': 'b', 'make': 'Kia'})");
+      await session.execute("CREATE INDEX cars_make ON cars (make)");
+    } finally {
+      await session.close();
+    }
+  });
+
+  afterAll(() => {
+    rmrf(dataDir);
+    rmrf(work);
+  });
+
+  it("requests an SDK support bundle, saves the .tar, and lists it", async () => {
+    const identity = loadIdentity();
+    const session = await DittoSession.open(identity, dataDir);
+    try {
+      const out = path.join(work, "bundle.tar");
+      const saved = await saveSupportBundle(session, out, { source: "integration test" });
+      expect(saved.reusedBecause).toBeUndefined();
+      expect(fs.statSync(out).size).toBe(saved.bytes);
+      const names = await tarEntries(out);
+      expect(names).toEqual(
+        expect.arrayContaining([
+          "ditto-logs.log.gz",
+          "device_logs_METADATA.json",
+          "config_snapshot.json",
+        ]),
+      );
+      // The license token never ends up in the bundle.
+      expect(fs.readFileSync(out).includes(Buffer.from(identity.token))).toBe(false);
+
+      const list = await listSupportBundles(session);
+      expect(list[0]).toMatchObject({ created_at: saved.createdAt, reason: "USER_INITIATED" });
+    } finally {
+      await session.close();
+    }
+  }, 60_000);
+
+  it("collects a full report from a real store", async () => {
+    const identity = loadIdentity();
+    const report = await collectReport({
+      dataDir,
+      configDir: work,
+      includeStore: true,
+      includeSdkBundle: true,
+      workDir: work,
+      checks: [],
+      environment: {},
+      lastError: null,
+      openStore: () => DittoSession.open(identity, dataDir),
+      saveBundle: (s, f) => saveSupportBundle(s, f),
+    });
+    expect(report.store.collections).toEqual([{ name: "cars", documents: 2 }]);
+    expect(report.store.indexes).toEqual([
+      { id: "cars.cars_make", collection: "cars", fields: "make" },
+    ]);
+    expect(report.sdkBundle.file).toBe("ditto-support-bundle.tar");
+    expect(fs.existsSync(path.join(work, "ditto-support-bundle.tar"))).toBe(true);
+    expect(renderReport(report)).toContain("| cars | 2 |");
+
+    // The store was closed: it opens again (no lock left behind).
+    const again = await DittoSession.open(identity, dataDir);
+    await again.close();
+  }, 60_000);
+});
diff --git a/tests/setup/env.ts b/tests/setup/env.ts
index 60a88bf..0d58e65 100644
--- a/tests/setup/env.ts
+++ b/tests/setup/env.ts
@@ -4,10 +4,18 @@
  * OFFLINE_TOKEN. Integration suites skip themselves when credentials are absent.
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 process.env.FORCE_COLOR = "0";
 
+// Every failing CLI run now saves last-error.json to the config dir. Give
+// tests (and the CLI processes they spawn) a throwaway one, so test failures
+// never land in the developer's real config.
+if (!process.env.DITTOSH_CONFIG_DIR) {
+  process.env.DITTOSH_CONFIG_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "dittosh-test-config-"));
+}
+
 const envFile = path.resolve(import.meta.dirname, "../../.env");
 if (fs.existsSync(envFile) && typeof process.loadEnvFile === "function") {
   try {
diff --git a/tests/unit/bench.test.ts b/tests/unit/bench.test.ts
new file mode 100644
index 0000000..74f840c
--- /dev/null
+++ b/tests/unit/bench.test.ts
@@ -0,0 +1,438 @@
+import { describe, expect, it } from "vitest";
+import { exampleBenchFile } from "../../src/bench/example.js";
+import { type BenchStage, resultRows, runBenchmark } from "../../src/bench/runner.js";
+import {
+  type BenchSpec,
+  BenchSpecError,
+  cleanStatement,
+  parseBenchFile,
+  selectBenchmarks,
+} from "../../src/bench/spec.js";
+import { computeStats, decideWarmup, WARMUP_MAX } from "../../src/bench/stats.js";
+import { DATASETS, getDataset } from "../../src/datasets/registry.js";
+import type { QueryExecutor } from "../../src/ditto/session.js";
+
+describe("computeStats", () => {
+  it("matches the benchmark runners: true median, floor-indexed p95/p99, population stddev", () => {
+    const samples = Array.from({ length: 100 }, (_, i) => 100 - i); // 1..100, unsorted
+    const s = computeStats(samples);
+    expect(s.mean).toBe(50.5);
+    expect(s.p50).toBe(50.5);
+    expect(s.p95).toBe(96); // sorted[95]
+    expect(s.p99).toBe(100); // sorted[99]
+    expect(s.min).toBe(1);
+    expect(s.max).toBe(100);
+    expect(s.stdDev).toBeCloseTo(28.866, 3);
+  });
+
+  it("handles odd counts and a single sample", () => {
+    expect(computeStats([3, 1, 2]).p50).toBe(2);
+    expect(computeStats([7])).toEqual({
+      mean: 7,
+      p50: 7,
+      p95: 7,
+      p99: 7,
+      min: 7,
+      max: 7,
+      stdDev: 0,
+    });
+    expect(() => computeStats([])).toThrow();
+  });
+});
+
+describe("decideWarmup", () => {
+  it("fills ~250 ms, between 1 and 1000 runs", () => {
+    expect(decideWarmup(1)).toBe(250);
+    expect(decideWarmup(3)).toBe(84);
+    expect(decideWarmup(500)).toBe(1);
+    expect(decideWarmup(0.001)).toBe(WARMUP_MAX);
+    expect(decideWarmup(0)).toBe(WARMUP_MAX);
+    expect(decideWarmup(-1)).toBe(1);
+  });
+});
+
+describe("parseBenchFile", () => {
+  it("reads the benchmarks.json map shape and ignores the benchmark repo's extra keys", () => {
+    const specs = parseBenchFile(
+      JSON.stringify({
+        by_rated: {
+          query: "SELECT * FROM movies WHERE rated = 'PG';",
+          category: "INDEX_SELECT",
+          expected_count: 3,
+          sql_equivalent: "SELECT 1",
+          qb: { x: 1 },
+          preQueries: ["CREATE INDEX r ON movies (rated)"],
+          postQueries: "DROP INDEX r ON movies",
+        },
+      }),
+      "f.json",
+    );
+    expect(specs).toEqual([
+      {
+        name: "by_rated",
+        query: "SELECT * FROM movies WHERE rated = 'PG'",
+        preQueries: ["CREATE INDEX r ON movies (rated)"],
+        resetQueries: [],
+        postQueries: ["DROP INDEX r ON movies"],
+        description: undefined,
+      },
+    ]);
+  });
+
+  it("reads a list (names optional) and a single object", () => {
+    const list = parseBenchFile(
+      JSON.stringify([{ name: "a", query: "SELECT 1" }, { query: "SELECT 2" }]),
+      "f",
+    );
+    expect(list.map((s) => s.name)).toEqual(["a", "benchmark_2"]);
+    const one = parseBenchFile(
+      JSON.stringify({
+        query: "SELECT 1",
+        description: "x",
+        resetQueries: ["EVICT FROM t WHERE true"],
+      }),
+      "f",
+    );
+    expect(one[0]).toMatchObject({ name: "benchmark", description: "x" });
+    expect(one[0]!.resetQueries).toEqual(["EVICT FROM t WHERE true"]);
+  });
+
+  it.each([
+    ["not json", "{", /isn't valid JSON/],
+    ["a scalar", "3", /must hold a JSON object or list/],
+    ["no benchmarks", "{}", /has no benchmarks/],
+    ["an empty list", "[]", /has no benchmarks/],
+    ["a non-object entry", '{"a": 1}', /must be an object/],
+    ["a missing query", '{"a": {"preQueries": []}}', /needs a "query"/],
+    ["a blank query", '{"a": {"query": " ; "}}', /needs a "query"/],
+    [
+      "a misspelled key",
+      '{"a": {"query": "SELECT 1", "prequeries": []}}',
+      /did you mean "preQueries"/,
+    ],
+    [
+      "a snake_case key",
+      '{"a": {"query": "SELECT 1", "post_queries": []}}',
+      /did you mean "postQueries"/,
+    ],
+    [
+      "an unknown key",
+      '{"a": {"query": "SELECT 1", "runs": 5}}',
+      /unknown key "runs"\. Known keys/,
+    ],
+    ["a list that isn't one", '{"a": {"query": "SELECT 1", "preQueries": 5}}', /must be a list/],
+    ["a blank statement", '{"a": {"query": "SELECT 1", "preQueries": [""]}}', /preQueries\[0\]/],
+    ["a name inside a map entry", '{"a": {"query": "SELECT 1", "name": "b"}}', /goes in the key/],
+    ["a blank name", '[{"query": "SELECT 1", "name": " "}]', /name must be a non-empty/],
+    [
+      "a non-string description",
+      '[{"query": "SELECT 1", "description": 1}]',
+      /description must be a string/,
+    ],
+    [
+      "duplicate names",
+      '[{"query": "SELECT 1", "name": "a"}, {"query": "SELECT 2", "name": "a"}]',
+      /two benchmarks are named "a"/,
+    ],
+  ])("rejects %s", (_label, text, error) => {
+    expect(() => parseBenchFile(text, "f.json")).toThrow(error);
+    expect(() => parseBenchFile(text, "f.json")).toThrow(BenchSpecError);
+  });
+
+  it("cleanStatement trims and drops a trailing semicolon", () => {
+    expect(cleanStatement("  SELECT 1 ;  ")).toBe("SELECT 1");
+  });
+});
+
+describe("selectBenchmarks", () => {
+  const specs = parseBenchFile('{"a": {"query": "SELECT 1"}, "b": {"query": "SELECT 2"}}', "f");
+  it("keeps file order, all when no names are given", () => {
+    expect(selectBenchmarks(specs, ["b", "a"]).map((s) => s.name)).toEqual(["a", "b"]);
+    expect(selectBenchmarks(specs, [])).toBe(specs);
+  });
+  it("names unknown benchmarks and lists the real ones", () => {
+    expect(() => selectBenchmarks(specs, ["c"])).toThrow(
+      'No benchmark named "c". In this file: a, b',
+    );
+  });
+});
+
+/** A fake store: records statements, can fail on a pattern, advances a fake clock. */
+function fakeSession(opts: { fail?: RegExp; rows?: number; costMs?: number } = {}) {
+  const calls: string[] = [];
+  let clock = 0;
+  const session: QueryExecutor = {
+    execute: async (s: string) => {
+      calls.push(s);
+      clock += opts.costMs ?? 2;
+      if (opts.fail?.test(s)) throw Object.assign(new Error("boom"), { code: "query/x" });
+      return { items: Array.from({ length: opts.rows ?? 1 }, () => ({})) } as never;
+    },
+  };
+  return { session, calls, now: () => clock };
+}
+
+const spec = (over: Partial<BenchSpec> = {}): BenchSpec => ({
+  name: "b",
+  query: "SELECT * FROM t",
+  preQueries: [],
+  resetQueries: [],
+  postQueries: [],
+  ...over,
+});
+
+describe("runBenchmark", () => {
+  it("runs pre once, reset before every warmup and timed run, post once", async () => {
+    const f = fakeSession({ rows: 3 });
+    const notes: string[] = [];
+    const r = await runBenchmark(
+      f.session,
+      spec({ preQueries: ["PRE"], resetQueries: ["RESET"], postQueries: ["POST"] }),
+      { runs: 2, warmup: 1, now: f.now, note: (m) => notes.push(m) },
+    );
+    expect(f.calls).toEqual([
+      "PRE",
+      "RESET",
+      "SELECT * FROM t", // warmup
+      "RESET",
+      "SELECT * FROM t",
+      "RESET",
+      "SELECT * FROM t",
+      "POST",
+    ]);
+    expect(r).toMatchObject({ ok: true, runs: 2, warmup: 1, rows: 3, samples: [2, 2] });
+    expect(r.stats?.p50).toBe(2);
+    expect(notes).toEqual(["  b: 1 warmup runs"]);
+  });
+
+  it("auto warmup sizes itself from a pilot run", async () => {
+    const f = fakeSession({ costMs: 50 });
+    const r = await runBenchmark(f.session, spec(), { runs: 1, warmup: "auto", now: f.now });
+    expect(r.warmup).toBe(5); // 250 ms / 50 ms
+    expect(f.calls).toHaveLength(6);
+  });
+
+  it("no warmup by default count 0, and no note", async () => {
+    const f = fakeSession();
+    const notes: string[] = [];
+    const r = await runBenchmark(f.session, spec(), {
+      runs: 1,
+      warmup: 0,
+      note: (m) => notes.push(m),
+    });
+    expect(r.warmup).toBe(0);
+    expect(notes).toEqual([]);
+  });
+
+  it.each([
+    ["pre", { preQueries: ["CREATE INDEX x"] }, /CREATE/],
+    ["reset", { resetQueries: ["EVICT x"] }, /EVICT/],
+    ["query", {}, /SELECT/],
+  ] as [BenchStage, Partial<BenchSpec>, RegExp][])(
+    "a failure in %s stops timing but still runs postQueries",
+    async (stage, over, fail) => {
+      const f = fakeSession({ fail });
+      const r = await runBenchmark(f.session, spec({ ...over, postQueries: ["DROP INDEX x"] }), {
+        runs: 3,
+        warmup: 0,
+      });
+      expect(r.ok).toBe(false);
+      expect(r.failure).toMatchObject({ stage, error: "[query/x] boom" });
+      expect(r.stats).toBeUndefined();
+      expect(f.calls.at(-1)).toBe("DROP INDEX x");
+    },
+  );
+
+  it("a warmup failure is reported as warmup", async () => {
+    const f = fakeSession({ fail: /SELECT/ });
+    const r = await runBenchmark(f.session, spec(), { runs: 3, warmup: "auto" });
+    expect(r.failure?.stage).toBe("warmup");
+  });
+
+  it("a failed postQuery marks the benchmark failed but keeps its timings", async () => {
+    const f = fakeSession({ fail: /DROP/ });
+    const r = await runBenchmark(f.session, spec({ postQueries: ["DROP INDEX x", "EVICT y"] }), {
+      runs: 2,
+      warmup: 0,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.failure).toBeUndefined();
+    expect(r.cleanupFailures).toEqual([{ statement: "DROP INDEX x", error: "boom" }]);
+    expect(r.stats).toBeDefined();
+    expect(f.calls.at(-1)).toBe("EVICT y"); // later cleanup still runs
+  });
+
+  it("warns when a repeated write has no resetQueries", async () => {
+    const warns: string[] = [];
+    const write = spec({ query: "EVICT FROM t WHERE _id = 'x'" });
+    await runBenchmark(fakeSession().session, write, {
+      runs: 2,
+      warmup: 0,
+      warn: (m) => warns.push(m),
+    });
+    expect(warns[0]).toContain("no resetQueries");
+    warns.length = 0;
+    await runBenchmark(fakeSession().session, write, {
+      runs: 1,
+      warmup: 0,
+      warn: (m) => warns.push(m),
+    });
+    await runBenchmark(
+      fakeSession().session,
+      { ...write, resetQueries: ["INSERT …"] },
+      {
+        runs: 5,
+        warmup: "auto",
+        warn: (m) => warns.push(m),
+      },
+    );
+    await runBenchmark(fakeSession().session, spec(), {
+      runs: 5,
+      warmup: 0,
+      warn: (m) => warns.push(m),
+    });
+    // An UPDATE does the same work every run (the --example samples use one).
+    await runBenchmark(
+      fakeSession().session,
+      spec({ query: "-- note\nUPDATE t SET x = 1 WHERE _id = 'a'" }),
+      { runs: 5, warmup: 2, warn: (m) => warns.push(m) },
+    );
+    expect(warns).toEqual([]);
+  });
+
+  it("samples from --example never trigger the reset warning", async () => {
+    for (const d of DATASETS) {
+      for (const s of parseBenchFile(
+        JSON.stringify(exampleBenchFile(getDataset(d.name)!)),
+        d.name,
+      )) {
+        const warns: string[] = [];
+        await runBenchmark(fakeSession().session, s, {
+          runs: 5,
+          warmup: 2,
+          warn: (m) => warns.push(m),
+        });
+        expect(warns, `${d.name}/${s.name}`).toEqual([]);
+      }
+    }
+  });
+
+  it("rethrows errors that aren't from a statement", async () => {
+    const session: QueryExecutor = { execute: async () => ({}) as never }; // no items
+    await expect(runBenchmark(session, spec(), { runs: 1, warmup: 0 })).rejects.toThrow(TypeError);
+  });
+});
+
+describe("resultRows", () => {
+  const ok = (name: string, samples: number[]) => ({
+    name,
+    ok: true,
+    cleanupFailures: [],
+    runs: samples.length,
+    warmup: 0,
+    rows: 4,
+    samples,
+    stats: samples.length > 0 ? computeStats(samples) : undefined,
+  });
+
+  it("one run shows just the time", () => {
+    expect(resultRows([ok("a", [1.23456])], 1)).toEqual([
+      { benchmark: "a", rows: 4, time_ms: 1.235 },
+    ]);
+  });
+
+  it("several runs show the distribution", () => {
+    const [row] = resultRows([ok("a", [1, 2, 3, 4])], 4);
+    expect(Object.keys(row!)).toEqual([
+      "benchmark",
+      "runs",
+      "warmup",
+      "rows",
+      "mean_ms",
+      "p50_ms",
+      "p95_ms",
+      "p99_ms",
+      "min_ms",
+      "max_ms",
+      "stddev_ms",
+    ]);
+    expect(row).toMatchObject({ runs: 4, mean_ms: 2.5, p50_ms: 2.5, p95_ms: 4, max_ms: 4 });
+  });
+
+  it("adds a status column when anything failed", () => {
+    const failed = {
+      ...ok("b", []),
+      ok: false,
+      stats: undefined,
+      runs: 0,
+      failure: { stage: "pre" as const, statement: "x", error: "e" },
+    };
+    const cleanup = {
+      ...ok("c", [1, 2]),
+      ok: false,
+      cleanupFailures: [{ statement: "y", error: "e" }],
+    };
+    const rows = resultRows([ok("a", [1, 2]), failed, cleanup], 2);
+    expect(rows.map((r) => r.status)).toEqual(["ok", "failed (pre)", "cleanup failed"]);
+    expect(rows[1]!.p95_ms).toBeNull();
+    expect(resultRows([failed], 1)[0]).toEqual({
+      benchmark: "b",
+      status: "failed (pre)",
+      rows: 4,
+      time_ms: null,
+    });
+  });
+
+  it("keeps the distribution columns when every benchmark failed early", () => {
+    const failed = {
+      ...ok("b", []),
+      ok: false,
+      stats: undefined,
+      runs: 0,
+      failure: { stage: "warmup" as const, statement: "x", error: "e" },
+    };
+    const [row] = resultRows([failed], 5);
+    expect(row).toMatchObject({ status: "failed (warmup)", runs: 0, p95_ms: null });
+    expect(row).not.toHaveProperty("time_ms");
+  });
+});
+
+describe("exampleBenchFile", () => {
+  it.each(DATASETS.map((d) => d.name))("%s: a valid file that teaches each part", (name) => {
+    const file = exampleBenchFile(getDataset(name)!);
+    const specs = parseBenchFile(JSON.stringify(file), name);
+    expect(specs.length).toBeGreaterThanOrEqual(3);
+    for (const [key, e] of Object.entries(file)) {
+      expect(e.description.length, key).toBeGreaterThan(20);
+      // Keys appear in the order they run.
+      const order = Object.keys(e).filter((k) => k !== "description");
+      const expected = ["preQueries", "resetQueries", "query", "postQueries"].filter((k) => k in e);
+      expect(order, key).toEqual(expected);
+      expect(JSON.stringify(e), key).not.toMatch(/\bDOCUMENTS\b/);
+    }
+    // A plain read, an indexed read (pre + post), and a write that is safe to repeat.
+    expect(specs.some((s) => s.preQueries.length === 0 && s.query.startsWith("SELECT"))).toBe(true);
+    expect(
+      specs.some(
+        (s) => s.preQueries.some((q) => q.startsWith("CREATE INDEX")) && s.postQueries.length > 0,
+      ),
+    ).toBe(true);
+    const write = specs.find((s) => !s.query.startsWith("SELECT"));
+    expect(write).toBeDefined();
+    expect(write!.resetQueries.length + write!.postQueries.length).toBeGreaterThan(0);
+  });
+
+  it("pos uses resetQueries for its write; retail-joins includes a join", () => {
+    const pos = parseBenchFile(JSON.stringify(exampleBenchFile(getDataset("pos")!)), "pos");
+    expect(pos.find((s) => s.query.startsWith("INSERT"))?.resetQueries.length).toBeGreaterThan(0);
+    const joins = exampleBenchFile(getDataset("retail-joins")!);
+    expect(Object.values(joins).some((e) => /\bJOIN\b/.test(e.query))).toBe(true);
+  });
+
+  it("skips catalog queries with known issues", () => {
+    const suite = getDataset("movies")!;
+    const firstSelect = Object.entries(suite.catalog).find(([, q]) => q.category === "SELECT")![0];
+    const file = exampleBenchFile({ ...suite, knownIssues: { [firstSelect]: "hangs" } });
+    expect(Object.keys(file)).not.toContain(firstSelect);
+  });
+});
diff --git a/tests/unit/cli-bench.test.ts b/tests/unit/cli-bench.test.ts
new file mode 100644
index 0000000..1d21c7c
--- /dev/null
+++ b/tests/unit/cli-bench.test.ts
@@ -0,0 +1,409 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+// Same pattern as cli-dataset.test.ts: mock only the native SDK boundary.
+const h = vi.hoisted(() => ({
+  calls: [] as string[],
+  failPattern: null as RegExp | null,
+}));
+
+vi.mock("../../src/ditto/session.js", async (importOriginal) => {
+  const mod = await importOriginal<typeof import("../../src/ditto/session.js")>();
+  class FakeSession {
+    static async open() {
+      return new FakeSession();
+    }
+    async execute(statement: string) {
+      h.calls.push(statement);
+      if (h.failPattern?.test(statement)) throw new Error("injected failure");
+      return { items: [{ value: { n: 1 } }] };
+    }
+    async close() {}
+  }
+  return { ...mod, DittoSession: FakeSession };
+});
+
+const { registerDqlGroup } = await import("../../src/cli/groups/dql/index.js");
+const { parseWarmup } = await import("../../src/cli/groups/dql/bench.js");
+
+let outSpy: ReturnType<typeof vi.spyOn>;
+let errSpy: ReturnType<typeof vi.spyOn>;
+let writeSpy: ReturnType<typeof vi.spyOn>;
+let dir: string;
+
+beforeEach(() => {
+  h.calls = [];
+  h.failPattern = null;
+  process.env.DATABASE_ID = "test-app";
+  process.env.OFFLINE_TOKEN = "test-token";
+  process.exitCode = undefined;
+  outSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  dir = tmpDataDir("ditto-bench-unit-");
+});
+
+afterEach(() => {
+  outSpy.mockRestore();
+  errSpy.mockRestore();
+  writeSpy.mockRestore();
+  rmrf(dir);
+  process.exitCode = undefined;
+});
+
+async function run(...args: string[]) {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({ writeOut: () => {}, writeErr: () => {} });
+  registerDqlGroup(program.command("dql"));
+  await program.parseAsync(["node", "dittosh", "dql", ...args]);
+}
+
+const stdout = () => outSpy.mock.calls.flat().join("\n");
+const stderr = () => errSpy.mock.calls.flat().join("\n");
+const json = () => JSON.parse(stdout().slice(stdout().indexOf("[")));
+
+describe("dittosh dql bench", () => {
+  it("times a statement with pre, reset, and post, and reports percentiles", async () => {
+    await run(
+      "bench",
+      "SELECT * FROM t;",
+      "--runs",
+      "3",
+      "--warmup",
+      "1",
+      "--pre",
+      "CREATE INDEX i ON t (a)",
+      "--reset",
+      "EVICT FROM t WHERE _id = 'x'",
+      "--post",
+      "DROP INDEX i ON t",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBeUndefined();
+    expect(h.calls[0]).toBe("CREATE INDEX i ON t (a)");
+    expect(h.calls.filter((c) => c === "SELECT * FROM t")).toHaveLength(4);
+    expect(h.calls.filter((c) => c.startsWith("EVICT"))).toHaveLength(4);
+    expect(h.calls.at(-1)).toBe("DROP INDEX i ON t");
+    const [row] = json();
+    expect(row).toMatchObject({ benchmark: "SELECT * FROM t", runs: 3, warmup: 1, rows: 1 });
+    expect(row.p99_ms).toEqual(expect.any(Number));
+    expect(stderr()).toContain("Benchmarking 1 benchmark: 3 timed runs each, 1 warmup run.");
+  });
+
+  it("--before-each is --reset by another name; both keep the order given", async () => {
+    await run(
+      "bench",
+      "EVICT FROM t WHERE _id = 'x'",
+      "--runs",
+      "2",
+      "--before-each",
+      "INSERT A",
+      "--reset",
+      "INSERT B",
+      "--before-each",
+      "INSERT C",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBeUndefined();
+    const run1 = ["INSERT A", "INSERT B", "INSERT C", "EVICT FROM t WHERE _id = 'x'"];
+    expect(h.calls).toEqual([...run1, ...run1]);
+    expect(stderr()).not.toContain("no resetQueries");
+  });
+
+  it("defaults to 50 runs and no warmup; long statements get a short name", async () => {
+    const long = `SELECT * FROM t WHERE ${"a = 1 AND ".repeat(10)}b = 2`;
+    await run("bench", long, "-d", dir, "--format", "json");
+    expect(h.calls).toHaveLength(50);
+    expect(json()[0].benchmark).toHaveLength(60);
+    expect(json()[0].benchmark.endsWith("…")).toBe(true);
+  });
+
+  it("one run prints just the time, with a tip about --runs", async () => {
+    await run("bench", "SELECT 1", "--runs", "1", "-d", dir, "--format", "json");
+    expect(Object.keys(json()[0])).toEqual(["benchmark", "rows", "time_ms"]);
+    expect(stderr()).toContain("Use --runs <n>");
+  });
+
+  it("a statement swallowed by a bare --warmup still runs, with auto warmup", async () => {
+    await run("bench", "--warmup", "SELECT 1", "--runs", "2", "-d", dir, "--format", "json");
+    expect(process.exitCode).toBeUndefined();
+    expect(json()[0].warmup).toBeGreaterThan(0);
+    expect(stderr()).toContain("warmup to ~250 ms");
+  });
+
+  it("runs a benchmark file; --only picks entries; CLI --pre/--post wrap each one", async () => {
+    const file = path.join(dir, "b.json");
+    fs.writeFileSync(
+      file,
+      JSON.stringify({
+        a: { query: "SELECT a FROM t", preQueries: ["PRE_A"], postQueries: ["POST_A"] },
+        b: { query: "SELECT b FROM t" },
+        c: { query: "SELECT c FROM t" },
+      }),
+    );
+    await run(
+      "bench",
+      "-f",
+      file,
+      "--only",
+      "a, c",
+      "--runs",
+      "2",
+      "--pre",
+      "PRE",
+      "--post",
+      "POST",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(json().map((r: { benchmark: string }) => r.benchmark)).toEqual(["a", "c"]);
+    expect(h.calls.slice(0, 2)).toEqual(["PRE", "PRE_A"]);
+    expect(h.calls.slice(4, 6)).toEqual(["POST_A", "POST"]);
+    expect(h.calls).not.toContain("SELECT b FROM t");
+  });
+
+  it("writes results to a file with -o", async () => {
+    const out = path.join(dir, "results.csv");
+    await run("bench", "SELECT 1", "--runs", "2", "-o", out, "-d", dir);
+    expect(fs.readFileSync(out, "utf8")).toMatch(/^benchmark,runs,warmup,rows,mean_ms,p50_ms/);
+    expect(stdout()).toContain("Wrote 1 benchmark result to");
+  });
+
+  it("a failing benchmark exits 1, names the stage, and still cleans up", async () => {
+    h.failPattern = /^SELECT/;
+    await run(
+      "bench",
+      "SELECT 1",
+      "--post",
+      "DROP INDEX i ON t",
+      "--runs",
+      "2",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBe(1);
+    expect(stderr()).toContain("failed in query: injected failure");
+    expect(h.calls.at(-1)).toBe("DROP INDEX i ON t");
+    expect(json()[0].status).toBe("failed (query)");
+  });
+
+  it("a failing cleanup statement is reported and exits 1", async () => {
+    h.failPattern = /^DROP/;
+    await run(
+      "bench",
+      "SELECT 1",
+      "--post",
+      "DROP INDEX i ON t",
+      "--runs",
+      "2",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBe(1);
+    expect(stderr()).toContain("cleanup failed: injected failure");
+  });
+
+  it.each([
+    [["bench"], "Give a statement to time, or -f <file>"],
+    [["bench", "SELECT 1", "-f", "x.json"], "not both"],
+    [["bench", "SELECT 1", "--only", "a"], "use it with -f"],
+    [["bench", "SELECT 1", "--runs", "0"], "--runs must be an integer ≥ 1"],
+    [["bench", "SELECT 1", "--runs", "10001"], "--runs must be at most 10,000"],
+    [["bench", "SELECT 1", "--warmup", "lots"], '--warmup takes a number of runs or "auto"'],
+    [["bench", "SELECT 1", "--format", "xml"], "--format must be one of"],
+    [["bench", "SELECT 1", "-o", "/no/such/dir/x.json"], "no such directory"],
+    [["bench", ";"], "The statement is empty."],
+    [["bench", "-f", "/no/such/file.json"], "Cannot read /no/such/file.json"],
+    [["bench", "--example", "nope"], "Unknown dataset: nope"],
+    [["bench", "--example", "pos", "SELECT 1"], "--example only writes a sample file"],
+    [["bench", "--example", "pos", "-o", "/no/such/dir/x.json"], "no such directory"],
+  ])("usage error: %j", async (args, message) => {
+    await run(...args, "-d", dir);
+    expect(process.exitCode).toBe(2);
+    expect(stderr()).toContain(message);
+    expect(h.calls).toEqual([]); // the store is never touched
+  });
+
+  it("a bad file is a usage error that names the problem", async () => {
+    const file = path.join(dir, "bad.json");
+    fs.writeFileSync(file, '{"a": {"query": "SELECT 1", "prequeries": []}}');
+    await run("bench", "-f", file, "-d", dir);
+    expect(process.exitCode).toBe(2);
+    expect(stderr()).toContain('did you mean "preQueries"');
+  });
+
+  it("--example prints a sample file to stdout", async () => {
+    await run("bench", "--example", "pos");
+    const text = writeSpy.mock.calls.flat().join("");
+    const file = JSON.parse(text);
+    expect(Object.keys(file)).toContain("pos_orders__insert__new_order");
+    expect(h.calls).toEqual([]);
+  });
+
+  it("--example -o saves it and says how to run it", async () => {
+    const out = path.join(dir, "retail.json");
+    await run("bench", "--example", "retail", "-o", out);
+    expect(Object.keys(JSON.parse(fs.readFileSync(out, "utf8"))).length).toBeGreaterThan(2);
+    expect(stdout()).toContain("Wrote a sample benchmark file for retail");
+    expect(stderr()).toContain("dittosh dql dataset load retail");
+    expect(stderr()).toContain(`dittosh dql bench -f ${out} --runs 50 --warmup`);
+  });
+
+  it("parseWarmup: bare and auto adapt, numbers are exact, absent is undefined", () => {
+    expect(parseWarmup(undefined)).toBeUndefined();
+    expect(parseWarmup(false)).toBeUndefined();
+    expect(parseWarmup(true)).toBe("auto");
+    expect(parseWarmup("auto")).toBe("auto");
+    expect(parseWarmup("=7")).toBe(7);
+    expect(parseWarmup("0")).toBe(0);
+  });
+});
+
+describe("dittosh dql dataset run --runs/--warmup", () => {
+  it("benchmarks a read catalog query (index DDL only with --setup, kept afterwards)", async () => {
+    await run(
+      "dataset",
+      "run",
+      "filtered_query_with_index",
+      "--dataset",
+      "movies",
+      "--runs",
+      "3",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBeUndefined();
+    expect(h.calls).toEqual(Array(3).fill("SELECT * FROM movies WHERE rated = 'PG'"));
+    expect(json()[0]).toMatchObject({ benchmark: "filtered_query_with_index", runs: 3 });
+
+    h.calls = [];
+    outSpy.mockClear();
+    await run(
+      "dataset",
+      "run",
+      "filtered_query_with_index",
+      "--dataset",
+      "movies",
+      "--runs",
+      "2",
+      "--setup",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(h.calls[1]).toBe("CREATE INDEX movies_rated ON movies (rated)");
+    expect(h.calls.at(-1)).toBe("SELECT * FROM movies WHERE rated = 'PG'"); // no DROP
+  });
+
+  it("benchmarks a write with its fixtures, resets, and cleanup (needs --yes)", async () => {
+    await run(
+      "dataset",
+      "run",
+      "pos_orders__insert__new_order",
+      "--warmup",
+      "1",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBe(2);
+    expect(h.calls).toEqual([]);
+
+    process.exitCode = undefined;
+    await run(
+      "dataset",
+      "run",
+      "pos_orders__insert__new_order",
+      "--warmup",
+      "1",
+      "--runs",
+      "2",
+      "--yes",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBeUndefined();
+    const inserts = h.calls.filter((c) => c.startsWith("INSERT"));
+    const evicts = h.calls.filter((c) => c.startsWith("EVICT"));
+    expect(inserts).toHaveLength(3); // warmup + 2 runs
+    expect(evicts).toHaveLength(4); // a reset before each + the cleanup
+    expect(json()[0]).toMatchObject({ runs: 2, warmup: 1 });
+  });
+
+  it("shows a known-issue warning before benchmarking", async () => {
+    await run(
+      "dataset",
+      "run",
+      "joins__left__products_inventory_stock_value",
+      "--runs",
+      "2",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(stderr()).toContain("known issue");
+  });
+
+  it("a failing query exits 1", async () => {
+    h.failPattern = /^SELECT/;
+    await run(
+      "dataset",
+      "run",
+      "filtered_query_with_index",
+      "--dataset",
+      "movies",
+      "--runs",
+      "2",
+      "-d",
+      dir,
+      "--format",
+      "json",
+    );
+    expect(process.exitCode).toBe(1);
+  });
+
+  it.each([
+    [["--runs", "2", "--profile"], "don't combine with --runs/--warmup"],
+    [["--warmup", "--time"], "don't combine with --runs/--warmup"],
+    [["--runs", "2", "--max-rows", "5"], "--max-rows doesn't apply"],
+    [["--runs", "nope"], "--runs must be an integer"],
+    [["--runs", "2", "--format", "xml"], "--format must be one of"],
+  ])("usage error: %j", async (flags, message) => {
+    await run(
+      "dataset",
+      "run",
+      "filtered_query_with_index",
+      "--dataset",
+      "movies",
+      ...flags,
+      "-d",
+      dir,
+    );
+    expect(process.exitCode).toBe(2);
+    expect(stderr()).toContain(message);
+    expect(h.calls).toEqual([]);
+  });
+});
diff --git a/tests/unit/cli-doctor.test.ts b/tests/unit/cli-doctor.test.ts
new file mode 100644
index 0000000..1ed60d7
--- /dev/null
+++ b/tests/unit/cli-doctor.test.ts
@@ -0,0 +1,376 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Command } from "commander";
+import * as tar from "tar";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  configureDoctorCommand,
+  type DoctorDeps,
+  defaultReportName,
+  ISSUE_URL,
+} from "../../src/cli/groups/doctor.js";
+import type { DoctorCheck } from "../../src/cli/groups/dql/doctor.js";
+import {
+  defaultBundleName,
+  registerSupportBundleCommand,
+} from "../../src/cli/groups/dql/support-bundle.js";
+import type { DittoSession } from "../../src/ditto/session.js";
+import { recordLastError } from "../../src/support/last-error.js";
+import type { StoreSession } from "../../src/support/report.js";
+import { rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+const TOKEN = "unit-test-offline-token-123";
+const BUNDLE_ROW = {
+  _id: { pk: "pk1", created_at: "2026-11-07T12:00:00+00:00" },
+  reason: "USER_INITIATED",
+  file: { id: "att1", len: 2048, metadata: {} },
+};
+
+let outSpy: ReturnType<typeof vi.spyOn>;
+let errSpy: ReturnType<typeof vi.spyOn>;
+let dir: string;
+let savedEnv: NodeJS.ProcessEnv;
+
+beforeEach(() => {
+  savedEnv = { ...process.env };
+  dir = tmpDataDir("ditto-doctor-cli-");
+  process.env.DATABASE_ID = "test-app";
+  process.env.OFFLINE_TOKEN = TOKEN;
+  process.env.DITTOSH_CONFIG_DIR = path.join(dir, "cfg");
+  process.exitCode = undefined;
+  outSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  outSpy.mockRestore();
+  errSpy.mockRestore();
+  process.env = savedEnv;
+  rmrf(dir);
+  process.exitCode = undefined;
+});
+
+const stdout = () => outSpy.mock.calls.flat().join("\n");
+const stderr = () => errSpy.mock.calls.flat().join("\n");
+
+function fakeSession(opts: { requestFails?: Error; existing?: unknown[] } = {}) {
+  const calls: string[] = [];
+  let closed = false;
+  const session = {
+    async execute(statement: string) {
+      calls.push(statement);
+      if (statement.startsWith("EXECUTE FUNCTION")) {
+        if (opts.requestFails) throw opts.requestFails;
+        return { items: [{ value: BUNDLE_ROW }] };
+      }
+      if (statement.startsWith("SELECT * FROM system:support_bundles")) {
+        return { items: (opts.existing ?? []).map((value) => ({ value })) };
+      }
+      if (statement === "SELECT * FROM system:collections") {
+        return { items: [{ value: { name: "movies" } }] };
+      }
+      if (statement.startsWith("SELECT COUNT")) return { items: [{ value: { n: 7 } }] };
+      return { items: [] };
+    },
+    async saveAttachment(_token: unknown, file: string) {
+      fs.writeFileSync(file, "tar-bytes");
+    },
+    async close() {
+      closed = true;
+    },
+  };
+  return { session, calls, closed: () => closed };
+}
+
+function deps(checks: DoctorCheck[], store?: StoreSession): DoctorDeps {
+  return {
+    collectChecks: async () => checks,
+    openStore: async () => store ?? fakeSession().session,
+    channelDetail: () => "npm (/usr/local)",
+    now: () => new Date(2026, 10, 7, 9, 5, 3),
+  };
+}
+
+const OK: DoctorCheck[] = [{ ok: true, label: "platform", detail: "fine" }];
+
+async function runDoctor(d: DoctorDeps, ...args: string[]) {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({ writeOut: () => {}, writeErr: () => {} });
+  configureDoctorCommand(program.command("doctor"), d);
+  await program.parseAsync(["node", "dittosh", "doctor", ...args]);
+}
+
+async function entries(file: string): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  await tar.t({
+    file,
+    onReadEntry: (e) => {
+      const chunks: Buffer[] = [];
+      e.on("data", (c: Buffer) => chunks.push(c));
+      e.on("end", () => out.set(e.path, Buffer.concat(chunks).toString("utf8")));
+    },
+  });
+  return out;
+}
+
+function makeStore(): string {
+  const store = path.join(dir, "store");
+  fs.mkdirSync(store, { recursive: true });
+  fs.writeFileSync(path.join(store, "__ditto_lock_file"), "");
+  return store;
+}
+
+describe("dittosh doctor", () => {
+  it("prints checks and sets the exit code (3 for a failure, 4 for a lock)", async () => {
+    await runDoctor(deps(OK));
+    expect(stdout()).toContain("platform — fine");
+    expect(process.exitCode).toBe(0);
+
+    await runDoctor(deps([{ ok: false, label: "node", detail: "old" }]));
+    expect(process.exitCode).toBe(3);
+
+    await runDoctor(deps([{ ok: false, label: "lock", detail: "held" }]));
+    expect(process.exitCode).toBe(4);
+  });
+
+  it("--report writes a redacted bundle with the report, SDK bundle, and last error", async () => {
+    const store = makeStore();
+    recordLastError(
+      {
+        time: "2026-11-07T08:00:00Z",
+        version: "0.2.0",
+        command: ["dql", "SELEC"],
+        exitCode: 1,
+        stderr: [`failed in ${os.homedir()}/project`],
+      },
+      path.join(dir, "cfg"),
+    );
+    const f = fakeSession();
+    const out = path.join(dir, "out", "my-report.tar.gz");
+    await runDoctor(deps(OK, f.session), "-d", store, "--report", out);
+    expect(process.exitCode).toBe(0);
+    expect(f.closed()).toBe(true);
+
+    const files = await entries(out);
+    expect([...files.keys()].sort()).toEqual([
+      "my-report/",
+      "my-report/ditto-support-bundle.tar",
+      "my-report/report.json",
+      "my-report/report.md",
+    ]);
+    const md = files.get("my-report/report.md")!;
+    expect(md).toContain("| dittosh |");
+    expect(md).toContain("| installed | npm (/usr/local) |");
+    expect(md).toContain("| movies | 7 |");
+    expect(md).toContain("`dittosh dql SELEC` exited 1");
+    expect(md).toContain("failed in ~/project");
+    expect(md).toContain("| OFFLINE_TOKEN | set (value hidden) |");
+    const all = [...files.values()].join("\n");
+    expect(all).not.toContain(TOKEN);
+    expect(all).not.toContain(`${os.homedir()}/`);
+    JSON.parse(files.get("my-report/report.json")!);
+
+    expect(stderr()).toContain("Wrote");
+    expect(stderr()).toContain("It contains:");
+    expect(stderr()).toContain(ISSUE_URL);
+    expect(stdout()).not.toContain("Wrote"); // status stays off stdout
+  });
+
+  it("--report never contains DITTOSH_GITHUB_TOKEN or other credential-like values", async () => {
+    const gh = "ghp_FAKEtoken1234567890abcdef";
+    const other = "zz-some-future-secret-value";
+    process.env.DITTOSH_GITHUB_TOKEN = gh;
+    process.env.DITTOSH_FUTURE_SECRET = other;
+    const store = makeStore();
+    recordLastError(
+      {
+        time: "2026-11-07T08:00:00Z",
+        version: "0.2.0",
+        command: ["skills", "add", "x"],
+        exitCode: 1,
+        stderr: [`auth failed with ${gh}`],
+      },
+      path.join(dir, "cfg"),
+    );
+    const out = path.join(dir, "r.tar.gz");
+    await runDoctor(deps(OK), "-d", store, "--report", out);
+    const all = [...(await entries(out)).values()].join("\n");
+    expect(all).not.toContain(gh);
+    expect(all).not.toContain(other);
+    expect(all).toContain("| DITTOSH_GITHUB_TOKEN | set (value hidden) |");
+    expect(all).toContain("| DITTOSH_FUTURE_SECRET | set (value hidden) |");
+    expect(all).toContain("auth failed with [redacted]");
+  });
+
+  it("--report with no file name uses a timestamped name in the current folder", async () => {
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      await runDoctor(deps(OK), "-d", path.join(dir, "none"), "--report", "--no-sdk-bundle");
+    } finally {
+      process.chdir(cwd);
+    }
+    const file = path.join(dir, "dittosh-report-20261107-090503.tar.gz");
+    expect(fs.existsSync(file)).toBe(true);
+    const md = (await entries(file)).get("dittosh-report-20261107-090503/report.md")!;
+    expect(md).toContain("left out (--no-sdk-bundle)");
+    expect(md).toContain("no store at the data directory yet");
+    expect(stderr()).toContain("no SDK support bundle");
+  });
+
+  it("--no-store leaves out the store summary", async () => {
+    const store = makeStore();
+    const out = path.join(dir, "r.tar.gz");
+    await runDoctor(deps(OK), "-d", store, "--report", out, "--no-store");
+    const md = (await entries(out)).get("r/report.md")!;
+    expect(md).toContain("left out (--no-store)");
+    expect(md).toContain("ditto-support-bundle.tar");
+  });
+
+  it("reports a missing license token instead of failing", async () => {
+    delete process.env.OFFLINE_TOKEN;
+    delete process.env.DQL_OFFLINE_LICENSE;
+    const store = makeStore();
+    const out = path.join(dir, "r.tar.gz");
+    await runDoctor(deps(OK), "-d", store, "--report", out);
+    const md = (await entries(out)).get("r/report.md")!;
+    expect(md).toMatch(/\| token expires \| unavailable/);
+    expect(md).toContain("no license token loaded");
+  });
+
+  it("refuses to overwrite a file, before running any checks (exit 2)", async () => {
+    const out = path.join(dir, "existing.tar.gz");
+    fs.writeFileSync(out, "keep");
+    let ran = false;
+    const d = {
+      ...deps(OK),
+      collectChecks: async () => {
+        ran = true;
+        return OK;
+      },
+    };
+    await runDoctor(d, "--report", out);
+    expect(process.exitCode).toBe(2);
+    expect(ran).toBe(false);
+    expect(fs.readFileSync(out, "utf8")).toBe("keep");
+    expect(stderr()).toContain("already exists");
+  });
+
+  it("given a directory, writes the default name inside it", async () => {
+    await runDoctor(deps(OK), "-d", path.join(dir, "none"), "--report", dir, "--no-sdk-bundle");
+    expect(fs.existsSync(path.join(dir, "dittosh-report-20261107-090503.tar.gz"))).toBe(true);
+  });
+
+  it("accepts a file named like an entry inside the archive", async () => {
+    const out = path.join(dir, "report.md");
+    await runDoctor(deps(OK), "-d", path.join(dir, "none"), "--report", out, "--no-sdk-bundle");
+    expect(process.exitCode).toBe(0);
+    expect([...(await entries(out)).keys()]).toContain("report.md/report.md");
+  });
+
+  it("exits 1 when the report can't be written", async () => {
+    const blocker = path.join(dir, "file");
+    fs.writeFileSync(blocker, "x");
+    await runDoctor(
+      deps(OK),
+      "-d",
+      path.join(dir, "none"),
+      "--report",
+      path.join(blocker, "r.tar.gz"),
+    );
+    expect(process.exitCode).toBe(1);
+    expect(stderr()).toContain("Could not write the report");
+  });
+
+  it("names reports and bundles by local time", () => {
+    const d = new Date(2026, 0, 2, 3, 4, 5);
+    expect(defaultReportName(d)).toBe("dittosh-report-20260102-030405.tar.gz");
+    expect(defaultBundleName(d)).toBe("ditto-support-bundle-20260102-030405.tar");
+  });
+});
+
+describe("dittosh dql support-bundle", () => {
+  async function runBundle(session: unknown, ...args: string[]) {
+    const program = new Command();
+    program.exitOverride();
+    program.configureOutput({ writeOut: () => {}, writeErr: () => {} });
+    const dql = program.command("dql");
+    registerSupportBundleCommand(dql, {
+      openSession: async () => session as DittoSession | null,
+      now: () => new Date(2026, 10, 7, 9, 5, 3),
+    });
+    await program.parseAsync(["node", "dittosh", "dql", "support-bundle", ...args]);
+  }
+
+  it("saves a bundle to -o and notes where", async () => {
+    const f = fakeSession();
+    const out = path.join(dir, "sub", "b.tar");
+    await runBundle(f.session, "-o", out);
+    expect(fs.readFileSync(out, "utf8")).toBe("tar-bytes");
+    expect(f.calls[0]).toContain("system_request_support_bundle");
+    expect(stderr()).toContain("Saved");
+    expect(stderr()).toContain("2.0 KB");
+    expect(f.closed()).toBe(true);
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it("uses a timestamped default name", async () => {
+    const cwd = process.cwd();
+    process.chdir(dir);
+    try {
+      await runBundle(fakeSession().session);
+    } finally {
+      process.chdir(cwd);
+    }
+    expect(fs.existsSync(path.join(dir, "ditto-support-bundle-20261107-090503.tar"))).toBe(true);
+  });
+
+  it("falls back to the newest bundle when the rate limit is hit", async () => {
+    const f = fakeSession({ requestFails: new Error("rate exceeded"), existing: [BUNDLE_ROW] });
+    await runBundle(f.session, "-o", path.join(dir, "b.tar"));
+    expect(stderr()).toContain("A new bundle wasn't allowed (rate exceeded)");
+  });
+
+  it("exits 1 with the SDK's reason when nothing can be saved", async () => {
+    const f = fakeSession({ requestFails: new Error("rate exceeded") });
+    await runBundle(f.session, "-o", path.join(dir, "b.tar"));
+    expect(process.exitCode).toBe(1);
+    expect(stderr()).toContain("Could not save a support bundle: rate exceeded");
+    expect(f.closed()).toBe(true);
+  });
+
+  it("refuses to overwrite a file", async () => {
+    const out = path.join(dir, "b.tar");
+    fs.writeFileSync(out, "keep");
+    await runBundle(fakeSession().session, "-o", out);
+    expect(process.exitCode).toBe(2);
+    expect(fs.readFileSync(out, "utf8")).toBe("keep");
+  });
+
+  it("--list prints the bundles, or a note when there are none", async () => {
+    await runBundle(fakeSession({ existing: [BUNDLE_ROW] }).session, "--list", "--format", "json");
+    expect(JSON.parse(stdout())).toEqual([
+      { created_at: "2026-11-07T12:00:00+00:00", reason: "USER_INITIATED", bytes: 2048 },
+    ]);
+    outSpy.mockClear();
+    await runBundle(fakeSession().session, "--list");
+    expect(stdout()).toBe("");
+    expect(stderr()).toContain("No support bundles");
+  });
+
+  it("rejects a bad --format, and --format without --list", async () => {
+    await runBundle(fakeSession().session, "--list", "--format", "yaml");
+    expect(process.exitCode).toBe(2);
+    process.exitCode = undefined;
+    await runBundle(fakeSession().session, "--format", "json");
+    expect(process.exitCode).toBe(2);
+    expect(stderr()).toContain("--format only applies with --list");
+  });
+
+  it("does nothing more when the store can't open", async () => {
+    await runBundle(null, "-o", path.join(dir, "b.tar"));
+    expect(fs.existsSync(path.join(dir, "b.tar"))).toBe(false);
+  });
+});
diff --git a/tests/unit/default-command.test.ts b/tests/unit/default-command.test.ts
index b15773d..e4508a2 100644
--- a/tests/unit/default-command.test.ts
+++ b/tests/unit/default-command.test.ts
@@ -31,6 +31,7 @@ describe("rewriteDefaultSubcommand", () => {
       "collections",
       "indexes",
       "dataset",
+      "bench",
       "delete-store",
       "import",
     ]) {
@@ -85,6 +86,16 @@ describe("rewriteDefaultSubcommand", () => {
     ]);
   });
 
+  it("relocates flags before bench past it (dql -d X bench <stmt>)", () => {
+    expect(rewriteDefaultSubcommand(["dql", "-d", "/tmp/x", "bench", "SELECT 1"])).toEqual([
+      "dql",
+      "bench",
+      "-d",
+      "/tmp/x",
+      "SELECT 1",
+    ]);
+  });
+
   it("dql -- <stmt> doesn't duplicate the statement", () => {
     expect(rewriteDefaultSubcommand(["dql", "--", "SELECT 1"])).toEqual([
       "dql",
@@ -267,4 +278,20 @@ describe("rewriteDefaultSubcommand", () => {
       "SELECT 1",
     ]);
   });
+
+  it("--debug is a global flag and support-bundle is a known subcommand", () => {
+    expect(rewriteDefaultSubcommand(["dql", "--debug", "SELECT 1"])).toEqual([
+      "--debug",
+      "dql",
+      "exec",
+      "SELECT 1",
+    ]);
+    expect(rewriteDefaultSubcommand(["dql", "-d", "/tmp/x", "support-bundle", "--list"])).toEqual([
+      "dql",
+      "support-bundle",
+      "-d",
+      "/tmp/x",
+      "--list",
+    ]);
+  });
 });
diff --git a/tests/unit/explain.test.ts b/tests/unit/explain.test.ts
index 9e11942..4dbd38a 100644
--- a/tests/unit/explain.test.ts
+++ b/tests/unit/explain.test.ts
@@ -8,7 +8,7 @@ const fixture = JSON.parse(
 ) as { explain: Record<string, unknown> };
 
 describe("renderExplain", () => {
-  it("renders the operator tree from a real EXPLAIN doc (SDK 5.1.0)", () => {
+  it("renders the operator tree from a real EXPLAIN doc (SDK 5.2.0)", () => {
     const out = renderExplain(fixture.explain);
     expect(out).toContain("Query plan");
     expect(out).toContain("sequence");
diff --git a/tests/unit/fixtures/profile-envelope.json b/tests/unit/fixtures/profile-envelope.json
index 5602caa..787bf0a 100644
--- a/tests/unit/fixtures/profile-envelope.json
+++ b/tests/unit/fixtures/profile-envelope.json
@@ -1,14 +1,14 @@
 {
-  "capturedAt": "2026-08-30T00:13:30.899Z",
-  "sdkVersion": "5.1.0",
+  "capturedAt": "2026-11-06T16:40:11.929Z",
+  "sdkVersion": "5.2.0",
   "profiles": [
     {
       "query": "PROFILE SELECT * FROM movies WHERE rated = 'PG'",
-      "itemCount": 51,
+      "itemCount": 501,
       "envelope": {
         "~request_profile": {
-          "_id": "494464d7-68ca-4cf4-adf3-43a4daeef076",
-          "database_id": "eeb08fe8-e140-4b5f-83ef-784907a507dc",
+          "_id": "44cfe867-9735-4940-84c5-8828506a26c1",
+          "database_id": "bd701078-953b-4b01-b35e-1b0346a748a2",
           "directives": {
             "#profile": true
           },
@@ -19,15 +19,15 @@
               {
                 "#operator": "scan",
                 "#stats": {
-                  "documentsOut": 200,
+                  "documentsOut": 2000,
                   "phaseTimes": {
-                    "exec": 27973,
-                    "recv": 220293,
-                    "send": 245004
+                    "exec": 210768,
+                    "recv": 200579,
+                    "send": 1337157
                   },
                   "yields": {
-                    "budget": 3,
-                    "receiver": 1
+                    "budget": 31,
+                    "receiver": 2
                   }
                 },
                 "alias": "movies",
@@ -40,11 +40,11 @@
               {
                 "#operator": "filter",
                 "#stats": {
-                  "documentsIn": 200,
-                  "documentsOut": 50,
+                  "documentsIn": 2000,
+                  "documentsOut": 500,
                   "phaseTimes": {
-                    "exec": 126843,
-                    "send": 15077
+                    "exec": 791852,
+                    "send": 176993
                   }
                 },
                 "condition": "(`movies`.`rated` = \"PG\")"
@@ -52,15 +52,15 @@
               {
                 "#operator": "finalProjection",
                 "#stats": {
-                  "documentsIn": 50,
-                  "documentsOut": 50,
+                  "documentsIn": 500,
+                  "documentsOut": 500,
                   "phaseTimes": {
-                    "exec": 2245,
-                    "recv": 497996,
-                    "send": 11006
+                    "exec": 18718,
+                    "recv": 1726864,
+                    "send": 91837
                   },
                   "yields": {
-                    "receiver": 32
+                    "receiver": 269
                   }
                 }
               }
@@ -68,14 +68,14 @@
           },
           "queryType": "select",
           "requestType": "SDK",
-          "resultCount": 50,
+          "resultCount": 500,
           "state": "completed",
           "text": "PROFILE SELECT * FROM movies WHERE rated = 'PG'",
           "times": {
-            "elapsed": 3122137,
-            "parse": 1542862,
-            "plan": 452645,
-            "start": "2026-08-29T19:13:30.849-05:00"
+            "elapsed": 2094461,
+            "parse": 36059,
+            "plan": 45018,
+            "start": "2026-11-06T10:40:11.889-06:00"
           }
         }
       }
@@ -85,8 +85,8 @@
       "itemCount": 11,
       "envelope": {
         "~request_profile": {
-          "_id": "0f03dec7-918a-40ed-a8d9-d72e334fd770",
-          "database_id": "eeb08fe8-e140-4b5f-83ef-784907a507dc",
+          "_id": "32ae1a16-ed37-4e7e-ad3b-e20ca049c7e6",
+          "database_id": "bd701078-953b-4b01-b35e-1b0346a748a2",
           "directives": {
             "#profile": true
           },
@@ -97,14 +97,14 @@
               {
                 "#operator": "scan",
                 "#stats": {
-                  "documentsOut": 200,
+                  "documentsOut": 2000,
                   "phaseTimes": {
-                    "exec": 18021,
-                    "recv": 317389,
-                    "send": 170150
+                    "exec": 138639,
+                    "recv": 187788,
+                    "send": 1512285
                   },
                   "yields": {
-                    "budget": 3,
+                    "budget": 31,
                     "receiver": 2
                   }
                 },
@@ -118,11 +118,11 @@
               {
                 "#operator": "filter",
                 "#stats": {
-                  "documentsIn": 200,
-                  "documentsOut": 12,
+                  "documentsIn": 2000,
+                  "documentsOut": 156,
                   "phaseTimes": {
-                    "exec": 140110,
-                    "send": 11833
+                    "exec": 1060739,
+                    "send": 73463
                   }
                 },
                 "condition": "((`movies`.`year` > \"2000\") AND (`movies`.`rated` = \"R\"))"
@@ -130,15 +130,15 @@
               {
                 "#operator": "sort",
                 "#stats": {
-                  "documentsIn": 12,
+                  "documentsIn": 156,
                   "documentsOut": 10,
                   "phaseTimes": {
-                    "exec": 82493,
-                    "recv": 423770,
-                    "send": 1791
+                    "exec": 195890,
+                    "recv": 1698197,
+                    "send": 2124
                   },
                   "yields": {
-                    "receiver": 5
+                    "receiver": 87
                   }
                 },
                 "limit": 10,
@@ -155,9 +155,9 @@
                   "documentsIn": 10,
                   "documentsOut": 10,
                   "phaseTimes": {
-                    "exec": 585,
-                    "recv": 533701,
-                    "send": 747
+                    "exec": 334,
+                    "recv": 1921663,
+                    "send": 542
                   },
                   "yields": {
                     "receiver": 1
@@ -172,10 +172,192 @@
           "state": "completed",
           "text": "PROFILE SELECT * FROM movies WHERE year > '2000' AND rated = 'R' ORDER BY year DESC LIMIT 10",
           "times": {
-            "elapsed": 1153271,
-            "parse": 56620,
-            "plan": 413836,
-            "start": "2026-08-29T19:13:30.854-05:00"
+            "elapsed": 2072919,
+            "parse": 30975,
+            "plan": 45018,
+            "start": "2026-11-06T10:40:11.895-06:00"
+          }
+        }
+      }
+    },
+    {
+      "query": "PROFILE SELECT m._id, y.label FROM movies m JOIN years y ON m.year = y.year WHERE m.rated = 'G' LIMIT 50",
+      "itemCount": 51,
+      "envelope": {
+        "~request_profile": {
+          "_id": "8572f531-6374-43ca-a8fa-0601f87f5899",
+          "database_id": "bd701078-953b-4b01-b35e-1b0346a748a2",
+          "directives": {
+            "#profile": true
+          },
+          "featureFlags": "0x83a",
+          "plan": {
+            "#operator": "sequence",
+            "children": [
+              {
+                "#operator": "scan",
+                "#stats": {
+                  "documentsOut": 1228,
+                  "phaseTimes": {
+                    "exec": 94639,
+                    "recv": 259329,
+                    "send": 2080333
+                  },
+                  "yields": {
+                    "budget": 19,
+                    "receiver": 9
+                  }
+                },
+                "alias": "m",
+                "collection": "movies",
+                "datasource": "default",
+                "descriptor": {
+                  "diff_scan_condition": "never"
+                }
+              },
+              {
+                "#operator": "filter",
+                "#stats": {
+                  "documentsIn": 1229,
+                  "documentsOut": 307,
+                  "phaseTimes": {
+                    "exec": 496452,
+                    "send": 1368817
+                  }
+                },
+                "condition": "(`m`.`rated` = \"G\")"
+              },
+              {
+                "#operator": "nlJoin",
+                "#stats": {
+                  "documentsIn": 51,
+                  "documentsOut": 50,
+                  "phaseTimes": {
+                    "exec": 57555,
+                    "recv": 2424685,
+                    "send": 56536
+                  },
+                  "yields": {
+                    "receiver": 52
+                  }
+                },
+                "condition": "(`m`.`year` = `y`.`year`)",
+                "inner": {
+                  "#operator": "sequence",
+                  "children": [
+                    {
+                      "#operator": "indexScan",
+                      "#stats": {
+                        "documentsIn": 51,
+                        "documentsOut": 51,
+                        "phaseTimes": {
+                          "exec": 376623,
+                          "recv": 2081209,
+                          "send": 31975
+                        },
+                        "yields": {
+                          "receiver": 1
+                        }
+                      },
+                      "alias": "y",
+                      "collection": "years",
+                      "datasource": "default",
+                      "desc": {
+                        "index": "years_year",
+                        "spans": [
+                          [
+                            {
+                              "index_key": {
+                                "direction": "asc",
+                                "include_missing": true,
+                                "key": ["year"]
+                              },
+                              "range": {
+                                "high": {
+                                  "expr": "`m`.`year`",
+                                  "included": true
+                                },
+                                "low": {
+                                  "expr": "`m`.`year`",
+                                  "included": true
+                                }
+                              }
+                            }
+                          ]
+                        ]
+                      }
+                    },
+                    {
+                      "#operator": "fetch",
+                      "#stats": {
+                        "documentsIn": 51,
+                        "documentsOut": 51,
+                        "phaseTimes": {
+                          "exec": 65431,
+                          "recv": 1702885,
+                          "send": 50519,
+                          "stor": 716356
+                        },
+                        "yields": {
+                          "receiver": 53
+                        }
+                      },
+                      "alias": "y",
+                      "collection": "years",
+                      "datasource": "default"
+                    }
+                  ]
+                }
+              },
+              {
+                "#operator": "limit",
+                "#stats": {
+                  "documentsIn": 51,
+                  "documentsOut": 50,
+                  "phaseTimes": {
+                    "exec": 1665,
+                    "send": 27854
+                  }
+                },
+                "limit": 50
+              },
+              {
+                "#operator": "projection",
+                "#stats": {
+                  "documentsIn": 50,
+                  "documentsOut": 50,
+                  "phaseTimes": {
+                    "exec": 94949,
+                    "recv": 2391204,
+                    "send": 44978
+                  },
+                  "yields": {
+                    "receiver": 51
+                  }
+                },
+                "projections": [
+                  {
+                    "alias": "_id",
+                    "expression": "`m`.`_id`"
+                  },
+                  {
+                    "alias": "label",
+                    "expression": "`y`.`label`"
+                  }
+                ]
+              }
+            ]
+          },
+          "queryType": "select",
+          "requestType": "SDK",
+          "resultCount": 50,
+          "state": "completed",
+          "text": "PROFILE SELECT m._id, y.label FROM movies m JOIN years y ON m.year = y.year WHERE m.rated = 'G' LIMIT 50",
+          "times": {
+            "elapsed": 2744770,
+            "parse": 26934,
+            "plan": 87346,
+            "start": "2026-11-06T10:40:11.899-06:00"
           }
         }
       }
diff --git a/tests/unit/fixtures/system-metrics.json b/tests/unit/fixtures/system-metrics.json
new file mode 100644
index 0000000..9068e47
--- /dev/null
+++ b/tests/unit/fixtures/system-metrics.json
@@ -0,0 +1,1936 @@
+{
+  "sdkVersion": "5.2.0",
+  "note": "Real SELECT * FROM system:metrics rows (scratch probe): afterActivity = after 300 inserts + 20 selects + 1 failed query; idle = an immediate re-read (deltas flushed). disabled = the real placeholder returned when the exporter is off.",
+  "afterActivity": [
+    {
+      "current": 1279,
+      "delta": 1225,
+      "description": "Number of times a transaction permit was granted by the connection pool",
+      "key": "ditto.backend.sqlite3.txn_permits",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1279
+    },
+    {
+      "current": 323,
+      "delta": 322,
+      "description": "Number of DQL requests processed",
+      "key": "ditto.query.requests",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 323
+    },
+    {
+      "current": 323,
+      "delta": 322,
+      "description": "Number of DQL requests processed",
+      "key": "dql.requests",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 323
+    },
+    {
+      "current": 9,
+      "delta": 0,
+      "description": "Number of SQLite xSync (fsync) operations intercepted by the VFS wrapper.",
+      "key": "ditto.backend.sqlite3.fsync_total",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 9
+    },
+    {
+      "current": 641,
+      "delta": 602,
+      "description": "Number of transaction requests that timed out in the connection pool",
+      "key": "ditto.backend.sqlite3.txn_attempts",
+      "labels": {
+        "mode": "write",
+        "outcome": "started"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 641
+    },
+    {
+      "current": 1279,
+      "delta": 1225,
+      "description": "Number of transaction requests that timed out in the connection pool",
+      "key": "ditto.backend.sqlite3.txn_attempts",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1279
+    },
+    {
+      "current": 641,
+      "delta": 602,
+      "description": "Number of times a transaction permit was granted by the connection pool",
+      "key": "ditto.backend.sqlite3.txn_permits",
+      "labels": {
+        "mode": "write",
+        "outcome": "immediate"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 641
+    },
+    {
+      "current": 300,
+      "delta": 300,
+      "description": "Number of other DQL requests processed",
+      "key": "dql.other",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 300
+    },
+    {
+      "current": 638,
+      "delta": 623,
+      "description": "Number of times a transaction permit was granted by the connection pool",
+      "key": "ditto.backend.sqlite3.txn_permits",
+      "labels": {
+        "mode": "read",
+        "outcome": "immediate"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 638
+    },
+    {
+      "current": 22,
+      "delta": 21,
+      "description": "Number of DQL SELECT requests processed",
+      "key": "dql.selects",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 22
+    },
+    {
+      "current": 1,
+      "delta": 1,
+      "description": "Number of DQL requests that failed",
+      "key": "ditto.query.failed",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 300,
+      "delta": 300,
+      "description": "Number of other (create, alter, show, etc.) DQL requests processed",
+      "key": "ditto.query.other",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 300
+    },
+    {
+      "current": 6,
+      "delta": 0,
+      "description": "Number of SQLite xSync (fsync) operations intercepted by the VFS wrapper.",
+      "key": "ditto.backend.sqlite3.fsync_total",
+      "labels": {
+        "db": "attachment"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 6
+    },
+    {
+      "current": 3,
+      "delta": 0,
+      "description": "Number of SQLite xSync (fsync) operations intercepted by the VFS wrapper.",
+      "key": "ditto.backend.sqlite3.fsync_total",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 3
+    },
+    {
+      "current": 1,
+      "delta": 1,
+      "description": "Number of DQL requests that failed",
+      "key": "dql.failed",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 22,
+      "delta": 21,
+      "description": "Number of DQL SELECT requests processed",
+      "key": "ditto.query.selects",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 22
+    },
+    {
+      "current": 638,
+      "delta": 623,
+      "description": "Number of transaction requests that timed out in the connection pool",
+      "key": "ditto.backend.sqlite3.txn_attempts",
+      "labels": {
+        "mode": "read",
+        "outcome": "started"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 638
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of unique authenticated peers with at least one established connection",
+      "key": "ditto.network.peers.established",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 799,
+      "delta": 799,
+      "description": "Process-wide serialized CRDT bytes retained by active observer result snapshots",
+      "key": "ditto.store.observer.retained_bytes",
+      "labels": {},
+      "level": "info",
+      "unit": "bytes",
+      "updates": 1206
+    },
+    {
+      "current": 10312392,
+      "delta": 10184640,
+      "description": "Size of the SQLite WAL file in bytes.",
+      "key": "ditto.backend.sqlite3.wal_file_size_bytes",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "unit": "bytes",
+      "updates": 309
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Current multicast peers represented in the local Presence graph. Sum the state series for the total; `state=provisional` means identity is pending and `state=resolved` means the peer's announced identity has been applied.",
+      "key": "ditto.multicast.presence_peers",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being established by the Transport Connection Manager",
+      "key": "ditto.network.connections.connecting",
+      "labels": {
+        "direction": "outbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being established by the Transport Connection Manager",
+      "key": "ditto.network.connections.connecting",
+      "labels": {
+        "direction": "inbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of established connections currently managed by the Transport Connection Manager",
+      "key": "ditto.network.connections.established",
+      "labels": {
+        "direction": "inbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Number of documents with degraded sync",
+      "key": "ditto.store.database.sync_degraded_document_count",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Current multicast peers represented in the local Presence graph. Sum the state series for the total; `state=provisional` means identity is pending and `state=resolved` means the peer's announced identity has been applied.",
+      "key": "ditto.multicast.presence_peers",
+      "labels": {
+        "state": "resolved"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being disconnected by the Transport Connection Manager",
+      "key": "ditto.network.connections.disconnecting",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being established by the Transport Connection Manager",
+      "key": "ditto.network.connections.connecting",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of established connections currently managed by the Transport Connection Manager",
+      "key": "ditto.network.connections.established",
+      "labels": {
+        "direction": "outbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 10312392,
+      "delta": 10184640,
+      "description": "Size of the SQLite WAL file in bytes.",
+      "key": "ditto.backend.sqlite3.wal_file_size_bytes",
+      "labels": {},
+      "level": "info",
+      "unit": "bytes",
+      "updates": 309
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of established connections currently managed by the Transport Connection Manager",
+      "key": "ditto.network.connections.established",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of unique authenticated peers with at least one established connection",
+      "key": "ditto.network.peers.established",
+      "labels": {
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being disconnected by the Transport Connection Manager",
+      "key": "ditto.network.connections.disconnecting",
+      "labels": {
+        "direction": "inbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being disconnected by the Transport Connection Manager",
+      "key": "ditto.network.connections.disconnecting",
+      "labels": {
+        "direction": "outbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Current multicast peers represented in the local Presence graph. Sum the state series for the total; `state=provisional` means identity is pending and `state=resolved` means the peer's announced identity has been applied.",
+      "key": "ditto.multicast.presence_peers",
+      "labels": {
+        "state": "provisional"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "abs_max": 0.001072707,
+      "count": 322,
+      "dabs_max": 0,
+      "dcount": 321,
+      "description": "Time taken to parse statements",
+      "dmax": -0.000797213,
+      "dmin": -0.001071874,
+      "dp50": -0.001062832,
+      "dp90": -0.001052772,
+      "dp95": -0.001049064,
+      "dp99": -0.0010247706,
+      "dsample_rate": 0,
+      "dsum": 0.004035201,
+      "key": "dql.parse_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.000275494,
+      "min": 8.33e-7,
+      "p50": 9.875e-6,
+      "p90": 1.9935e-5,
+      "p95": 2.3643e-5,
+      "p99": 4.79364e-5,
+      "sample_rate": 1,
+      "sum": 0.005107908,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 4,
+      "count": 323,
+      "dabs_max": 3,
+      "dcount": 322,
+      "description": "Shared Statement Cache size",
+      "dmax": 3,
+      "dmin": 1,
+      "dp50": 1,
+      "dp90": 1,
+      "dp95": 2,
+      "dp99": 2,
+      "dsample_rate": 0,
+      "dsum": 668,
+      "key": "dql.shared_statement_cache",
+      "labels": {},
+      "level": "info",
+      "max": 4,
+      "min": 2,
+      "p50": 2,
+      "p90": 2,
+      "p95": 3,
+      "p99": 3,
+      "sample_rate": 1,
+      "sum": 669,
+      "unit": "count"
+    },
+    {
+      "abs_max": 0.000448084,
+      "count": 303,
+      "dabs_max": 0.000329501,
+      "dcount": 301,
+      "description": "Time spent in the backend commit/rollback call itself.",
+      "dmax": 0.000329501,
+      "dmin": 3.3329999999999967e-6,
+      "dp50": -1.2834000000000006e-5,
+      "dp90": 9.98359999999999e-6,
+      "dp95": 2.8909299999999998e-5,
+      "dp99": 0.00010250666000000002,
+      "dsample_rate": 0,
+      "dsum": 0.025920343,
+      "key": "ditto.store.transaction.commit_secs",
+      "labels": {},
+      "level": "info",
+      "max": 0.000448084,
+      "min": 5.875e-5,
+      "p50": 7.4166e-5,
+      "p90": 0.00012225,
+      "p95": 0.000144334,
+      "p99": 0.000220458,
+      "sample_rate": 1,
+      "sum": 0.026094343,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 4.306e-5,
+      "count": 299,
+      "dabs_max": 4.306e-5,
+      "dcount": 299,
+      "description": "Wall time of a complete get_multiple producer run (all chunks, all rows sent)",
+      "dsample_rate": 0,
+      "dsum": 0.0007992580000000004,
+      "key": "ditto.backend.sqlite3.get_multiple_total_wall_secs",
+      "labels": {},
+      "level": "info",
+      "max": 4.306e-5,
+      "min": 1.083e-6,
+      "p50": 2.042e-6,
+      "p90": 3.6087999999999984e-6,
+      "p95": 5.029199999999991e-6,
+      "p99": 1.4098799999999964e-5,
+      "sample_rate": 1,
+      "sum": 0.0007992580000000004,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 4,
+      "count": 323,
+      "dabs_max": 3,
+      "dcount": 322,
+      "description": "Shared Statement Cache size",
+      "dmax": 3,
+      "dmin": 1,
+      "dp50": 1,
+      "dp90": 1,
+      "dp95": 2,
+      "dp99": 2,
+      "dsample_rate": 0,
+      "dsum": 668,
+      "key": "ditto.query.shared_statement_cache",
+      "labels": {},
+      "level": "info",
+      "max": 4,
+      "min": 2,
+      "p50": 2,
+      "p90": 2,
+      "p95": 3,
+      "p99": 3,
+      "sample_rate": 1,
+      "sum": 669,
+      "unit": "count"
+    },
+    {
+      "abs_max": 0.005865333,
+      "count": 303,
+      "dabs_max": 0,
+      "dcount": 301,
+      "description": "Time the write transaction held the lock, from MonotonicSender acquisition to commit/rollback.",
+      "dmax": -0.004001333,
+      "dmin": -0.001256,
+      "dp50": -0.003431729,
+      "dp90": -0.005059112199999999,
+      "dp95": -0.0052264931,
+      "dp99": -0.0051515324199999995,
+      "dsample_rate": 0,
+      "dsum": 0.07340449299999997,
+      "key": "ditto.store.transaction.lock_hold_secs",
+      "labels": {},
+      "level": "info",
+      "max": 0.001864,
+      "min": 0.000145875,
+      "p50": 0.000201875,
+      "p90": 0.000359875,
+      "p95": 0.000415667,
+      "p99": 0.000669166,
+      "sample_rate": 1,
+      "sum": 0.08067170099999997,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.002151917,
+      "count": 637,
+      "dabs_max": 0.0012533400000000001,
+      "dcount": 623,
+      "description": "The time spent executing the background transaction loop for a given transaction",
+      "dmax": 0.0012533400000000001,
+      "dmin": 1.4809999999999999e-5,
+      "dp50": 2.0312000000000005e-5,
+      "dp90": -0.00022733740000000017,
+      "dp95": -0.00042678879999999983,
+      "dp99": -0.0004741846399999996,
+      "dsample_rate": 0,
+      "dsum": 0.05847998100000006,
+      "key": "ditto.backend.sqlite3.txn_duration_secs",
+      "labels": {
+        "mode": "read"
+      },
+      "level": "info",
+      "max": 0.002151917,
+      "min": 2.9018e-5,
+      "p50": 7.7952e-5,
+      "p90": 0.0001216208,
+      "p95": 0.00014970539999999998,
+      "p99": 0.00035997579999999996,
+      "sample_rate": 1,
+      "sum": 0.060803937000000065,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.005871175,
+      "count": 1278,
+      "dabs_max": 0,
+      "dcount": 1225,
+      "description": "The time spent executing the background transaction loop for a given transaction",
+      "dmax": -0.003719258,
+      "dmin": 1.4809999999999999e-5,
+      "dp50": -0.00012553800000000002,
+      "dp90": -0.00024760390000000014,
+      "dp95": -0.0010331559999999997,
+      "dp99": -0.003210651119999987,
+      "dsample_rate": -0.1640816326530612,
+      "dsum": 0.1662791349999998,
+      "key": "ditto.backend.sqlite3.txn_duration_secs",
+      "labels": {},
+      "level": "info",
+      "max": 0.002151917,
+      "min": 2.9018e-5,
+      "p50": 0.00010347899999999999,
+      "p90": 0.00024090930000000014,
+      "p95": 0.00034612639999999985,
+      "p99": 0.0004698798399999999,
+      "sample_rate": 0.8359183673469388,
+      "sum": 0.1874139279999998,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001072707,
+      "count": 322,
+      "dabs_max": 0,
+      "dcount": 321,
+      "description": "Time taken to parse statements",
+      "dmax": -0.000797213,
+      "dmin": -0.001071874,
+      "dp50": -0.001062832,
+      "dp90": -0.001052772,
+      "dp95": -0.001049064,
+      "dp99": -0.0010247706,
+      "dsample_rate": 0,
+      "dsum": 0.004035201,
+      "key": "ditto.query.parse_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.000275494,
+      "min": 8.33e-7,
+      "p50": 9.875e-6,
+      "p90": 1.9935e-5,
+      "p95": 2.3643e-5,
+      "p99": 4.79364e-5,
+      "sample_rate": 1,
+      "sum": 0.005107908,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.000173875,
+      "count": 303,
+      "dabs_max": 9.116700000000002e-5,
+      "dcount": 301,
+      "description": "Time spent acquiring the backend write transaction lock.",
+      "dmax": 9.116700000000002e-5,
+      "dmin": -3.3750999999999996e-5,
+      "dp50": -3.589599999999999e-5,
+      "dp90": -2.1045599999999987e-5,
+      "dp95": -1.0105299999999993e-5,
+      "dp99": 2.1262739999999998e-5,
+      "dsample_rate": 0,
+      "dsum": 0.011276629999999998,
+      "key": "ditto.store.transaction.lock_wait_secs",
+      "labels": {},
+      "level": "info",
+      "max": 0.000173875,
+      "min": 1.8583e-5,
+      "p50": 3.1625e-5,
+      "p90": 5.8625e-5,
+      "p95": 7.1084e-5,
+      "p99": 0.000103667,
+      "sample_rate": 1,
+      "sum": 0.011411671999999998,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.000613416,
+      "count": 3,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Duration of SQLite xSync (fsync) operations.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.fsync_duration_secs",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.001242333,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.00054475,
+      "count": 6,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Duration of SQLite xSync (fsync) operations.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.fsync_duration_secs",
+      "labels": {
+        "db": "attachment"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.002214083,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.005871175,
+      "count": 641,
+      "dabs_max": 0,
+      "dcount": 602,
+      "description": "The time spent executing the background transaction loop for a given transaction",
+      "dmax": -0.004002236,
+      "dmin": -1.916e-6,
+      "dp50": -7.860750000000002e-5,
+      "dp90": -0.0003516009000000023,
+      "dp95": -0.0011665151,
+      "dp99": -0.003733216509999989,
+      "dsample_rate": 0,
+      "dsum": 0.10779915399999995,
+      "key": "ditto.backend.sqlite3.txn_duration_secs",
+      "labels": {
+        "mode": "write"
+      },
+      "level": "info",
+      "max": 0.001868939,
+      "min": 6.1828e-5,
+      "p50": 0.00015945249999999998,
+      "p90": 0.0003076786999999999,
+      "p95": 0.00036244939999999996,
+      "p99": 0.0005371032300000002,
+      "sample_rate": 1,
+      "sum": 0.12660999099999995,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.000613416,
+      "count": 9,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Duration of SQLite xSync (fsync) operations.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.fsync_duration_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0034564160000000003,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001302017,
+      "count": 321,
+      "dabs_max": 0.001302017,
+      "dcount": 321,
+      "description": "Time taken to execute statements",
+      "dsample_rate": 0,
+      "dsum": 0.04108974800000002,
+      "key": "dql.execution_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.001302017,
+      "min": 5.8785e-5,
+      "p50": 9.1035e-5,
+      "p90": 0.000197191,
+      "p95": 0.000324904,
+      "p99": 0.0003805080000000003,
+      "sample_rate": 1,
+      "sum": 0.04108974800000002,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 2503,
+      "count": 309,
+      "dabs_max": 2472,
+      "dcount": 301,
+      "description": "SQLite WAL file size, in pages, at WAL-hook-fire time.",
+      "dmax": 2472,
+      "dmin": 44,
+      "dp50": 1259.5,
+      "dp90": 2224.8,
+      "dp95": 2342.9,
+      "dp99": 2441.98,
+      "dsample_rate": 0,
+      "dsum": 381235,
+      "key": "ditto.backend.sqlite3.wal_size_pages",
+      "labels": {},
+      "level": "info",
+      "max": 2503,
+      "min": 45,
+      "p50": 1267,
+      "p90": 2246,
+      "p95": 2369,
+      "p99": 2472,
+      "sample_rate": 1,
+      "sum": 381320,
+      "unit": "count"
+    },
+    {
+      "abs_max": 1.031e-5,
+      "count": 299,
+      "dabs_max": 1.031e-5,
+      "dcount": 299,
+      "description": "Per-row sqlite3_step duration inside get_multiple",
+      "dsample_rate": 0,
+      "dsum": 0.000314623,
+      "key": "ditto.backend.sqlite3.get_multiple_sqlite_step_secs",
+      "labels": {},
+      "level": "info",
+      "max": 1.031e-5,
+      "min": 4.16e-7,
+      "p50": 9.17e-7,
+      "p90": 1.5e-6,
+      "p95": 1.708e-6,
+      "p99": 3.6495199999999933e-6,
+      "sample_rate": 1,
+      "sum": 0.000314623,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001008339,
+      "count": 302,
+      "dabs_max": 0,
+      "dcount": 301,
+      "description": "Time taken to plan statements",
+      "dmax": -0.000652,
+      "dmin": -0.0010075050000000001,
+      "dp50": -0.001006464,
+      "dp90": -0.0010042550000000001,
+      "dp95": -0.001003089,
+      "dp99": -0.000998089,
+      "dsample_rate": 0,
+      "dsum": 0.0012293189999999996,
+      "key": "dql.plan_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.000356339,
+      "min": 8.34e-7,
+      "p50": 1.875e-6,
+      "p90": 4.084e-6,
+      "p95": 5.25e-6,
+      "p99": 1.025e-5,
+      "sample_rate": 1,
+      "sum": 0.0022376579999999996,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 1.166e-6,
+      "count": 299,
+      "dabs_max": 1.166e-6,
+      "dcount": 299,
+      "description": "Per-chunk time from prepare_cached to first rows.next() in get_multiple",
+      "dsample_rate": 0,
+      "dsum": 4.372500000000003e-5,
+      "key": "ditto.backend.sqlite3.get_multiple_chunk_overhead_secs",
+      "labels": {},
+      "level": "info",
+      "max": 1.166e-6,
+      "min": 4.1e-8,
+      "p50": 1.25e-7,
+      "p90": 2.5e-7,
+      "p95": 2.92e-7,
+      "p99": 4.19339999999997e-7,
+      "sample_rate": 1,
+      "sum": 4.372500000000003e-5,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 6,
+      "count": 2,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "SQLite WAL file size, in pages, at WAL-hook-fire time.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.wal_size_pages",
+      "labels": {
+        "db": "attachment"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 9,
+      "unit": "count"
+    },
+    {
+      "abs_max": 0.000112334,
+      "count": 303,
+      "dabs_max": 0,
+      "dcount": 301,
+      "description": "Time spent waiting for the MonotonicSender after the backend write lock is held.",
+      "dmax": -0.0001065,
+      "dmin": -2.625e-6,
+      "dp50": -5.6729000000000005e-5,
+      "dp90": -9.93134e-5,
+      "dp95": -0.00010432319999999998,
+      "dp99": -0.00010719824,
+      "dsample_rate": 0,
+      "dsum": 0.00035147300000000004,
+      "key": "ditto.store.transaction.monotonic_wait_secs",
+      "labels": {},
+      "level": "info",
+      "max": 5.834e-6,
+      "min": 3.33e-7,
+      "p50": 9.17e-7,
+      "p90": 2.083e-6,
+      "p95": 2.542e-6,
+      "p99": 4.042e-6,
+      "sample_rate": 1,
+      "sum": 0.000466765,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 1.0125e-5,
+      "count": 909,
+      "dabs_max": 8.417000000000001e-6,
+      "dcount": 904,
+      "description": "The time spent attempting to send a database event on a full channel.",
+      "dmax": 8.417000000000001e-6,
+      "dmin": -2.0899999999999998e-7,
+      "dp50": -3.339999999999999e-7,
+      "dp90": 1.0171e-6,
+      "dp95": 1.6270499999999963e-6,
+      "dp99": 3.1254100000000013e-6,
+      "dsample_rate": 0,
+      "dsum": 0.0012219399999999993,
+      "key": "ditto.store.database.event_delay_secs",
+      "labels": {},
+      "level": "info",
+      "max": 1.0125e-5,
+      "min": 4.1e-8,
+      "p50": 1.25e-6,
+      "p90": 2.7087e-6,
+      "p95": 3.3268499999999964e-6,
+      "p99": 4.831770000000001e-6,
+      "sample_rate": 1,
+      "sum": 0.0012286489999999992,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 1.0125e-5,
+      "count": 909,
+      "dabs_max": 8.417000000000001e-6,
+      "dcount": 904,
+      "description": "The time spent attempting to send a database event on a full channel.",
+      "dmax": 8.417000000000001e-6,
+      "dmin": -2.0899999999999998e-7,
+      "dp50": -3.339999999999999e-7,
+      "dp90": 1.0171e-6,
+      "dp95": 1.6270499999999963e-6,
+      "dp99": 3.1254100000000013e-6,
+      "dsample_rate": 0,
+      "dsum": 0.0012219399999999993,
+      "key": "ditto.store.database.event_delay_secs",
+      "labels": {
+        "outcome": "immediate"
+      },
+      "level": "info",
+      "max": 1.0125e-5,
+      "min": 4.1e-8,
+      "p50": 1.25e-6,
+      "p90": 2.7087e-6,
+      "p95": 3.3268499999999964e-6,
+      "p99": 4.831770000000001e-6,
+      "sample_rate": 1,
+      "sum": 0.0012286489999999992,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001008339,
+      "count": 302,
+      "dabs_max": 0,
+      "dcount": 301,
+      "description": "Time taken to plan statements",
+      "dmax": -0.000652,
+      "dmin": -0.0010075050000000001,
+      "dp50": -0.001006464,
+      "dp90": -0.0010042550000000001,
+      "dp95": -0.001003089,
+      "dp99": -0.000998089,
+      "dsample_rate": 0,
+      "dsum": 0.0012293189999999996,
+      "key": "ditto.query.plan_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.000356339,
+      "min": 8.34e-7,
+      "p50": 1.875e-6,
+      "p90": 4.084e-6,
+      "p95": 5.25e-6,
+      "p99": 1.025e-5,
+      "sample_rate": 1,
+      "sum": 0.0022376579999999996,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001302017,
+      "count": 321,
+      "dabs_max": 0.001302017,
+      "dcount": 321,
+      "description": "Time taken to execute statements",
+      "dsample_rate": 0,
+      "dsum": 0.04108974800000002,
+      "key": "ditto.query.execution_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.001302017,
+      "min": 5.8785e-5,
+      "p50": 9.1035e-5,
+      "p90": 0.000197191,
+      "p95": 0.000324904,
+      "p99": 0.0003805080000000003,
+      "sample_rate": 1,
+      "sum": 0.04108974800000002,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 2503,
+      "count": 307,
+      "dabs_max": 2472,
+      "dcount": 301,
+      "description": "SQLite WAL file size, in pages, at WAL-hook-fire time.",
+      "dmax": 2472,
+      "dmin": 44,
+      "dp50": 1256,
+      "dp90": 2222,
+      "dp95": 2341.5,
+      "dp99": 2441.7,
+      "dsample_rate": 0,
+      "dsum": 381235,
+      "key": "ditto.backend.sqlite3.wal_size_pages",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "max": 2503,
+      "min": 45,
+      "p50": 1267,
+      "p90": 2246,
+      "p95": 2369,
+      "p99": 2472,
+      "sample_rate": 1,
+      "sum": 381311,
+      "unit": "count"
+    }
+  ],
+  "idle": [
+    {
+      "current": 1280,
+      "delta": 1,
+      "description": "Number of times a transaction permit was granted by the connection pool",
+      "key": "ditto.backend.sqlite3.txn_permits",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1280
+    },
+    {
+      "current": 324,
+      "delta": 1,
+      "description": "Number of DQL requests processed",
+      "key": "ditto.query.requests",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 324
+    },
+    {
+      "current": 324,
+      "delta": 1,
+      "description": "Number of DQL requests processed",
+      "key": "dql.requests",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 324
+    },
+    {
+      "current": 9,
+      "delta": 0,
+      "description": "Number of SQLite xSync (fsync) operations intercepted by the VFS wrapper.",
+      "key": "ditto.backend.sqlite3.fsync_total",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 9
+    },
+    {
+      "current": 641,
+      "delta": 0,
+      "description": "Number of transaction requests that timed out in the connection pool",
+      "key": "ditto.backend.sqlite3.txn_attempts",
+      "labels": {
+        "mode": "write",
+        "outcome": "started"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 641
+    },
+    {
+      "current": 1280,
+      "delta": 1,
+      "description": "Number of transaction requests that timed out in the connection pool",
+      "key": "ditto.backend.sqlite3.txn_attempts",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1280
+    },
+    {
+      "current": 641,
+      "delta": 0,
+      "description": "Number of times a transaction permit was granted by the connection pool",
+      "key": "ditto.backend.sqlite3.txn_permits",
+      "labels": {
+        "mode": "write",
+        "outcome": "immediate"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 641
+    },
+    {
+      "current": 300,
+      "delta": 0,
+      "description": "Number of other DQL requests processed",
+      "key": "dql.other",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 300
+    },
+    {
+      "current": 639,
+      "delta": 1,
+      "description": "Number of times a transaction permit was granted by the connection pool",
+      "key": "ditto.backend.sqlite3.txn_permits",
+      "labels": {
+        "mode": "read",
+        "outcome": "immediate"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 639
+    },
+    {
+      "current": 23,
+      "delta": 1,
+      "description": "Number of DQL SELECT requests processed",
+      "key": "dql.selects",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 23
+    },
+    {
+      "current": 1,
+      "delta": 0,
+      "description": "Number of DQL requests that failed",
+      "key": "ditto.query.failed",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 300,
+      "delta": 0,
+      "description": "Number of other (create, alter, show, etc.) DQL requests processed",
+      "key": "ditto.query.other",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 300
+    },
+    {
+      "current": 6,
+      "delta": 0,
+      "description": "Number of SQLite xSync (fsync) operations intercepted by the VFS wrapper.",
+      "key": "ditto.backend.sqlite3.fsync_total",
+      "labels": {
+        "db": "attachment"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 6
+    },
+    {
+      "current": 3,
+      "delta": 0,
+      "description": "Number of SQLite xSync (fsync) operations intercepted by the VFS wrapper.",
+      "key": "ditto.backend.sqlite3.fsync_total",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 3
+    },
+    {
+      "current": 1,
+      "delta": 0,
+      "description": "Number of DQL requests that failed",
+      "key": "dql.failed",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 23,
+      "delta": 1,
+      "description": "Number of DQL SELECT requests processed",
+      "key": "ditto.query.selects",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 23
+    },
+    {
+      "current": 639,
+      "delta": 1,
+      "description": "Number of transaction requests that timed out in the connection pool",
+      "key": "ditto.backend.sqlite3.txn_attempts",
+      "labels": {
+        "mode": "read",
+        "outcome": "started"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 639
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of unique authenticated peers with at least one established connection",
+      "key": "ditto.network.peers.established",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 799,
+      "delta": 0,
+      "description": "Process-wide serialized CRDT bytes retained by active observer result snapshots",
+      "key": "ditto.store.observer.retained_bytes",
+      "labels": {},
+      "level": "info",
+      "unit": "bytes",
+      "updates": 1206
+    },
+    {
+      "current": 10312392,
+      "delta": 0,
+      "description": "Size of the SQLite WAL file in bytes.",
+      "key": "ditto.backend.sqlite3.wal_file_size_bytes",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "unit": "bytes",
+      "updates": 309
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Current multicast peers represented in the local Presence graph. Sum the state series for the total; `state=provisional` means identity is pending and `state=resolved` means the peer's announced identity has been applied.",
+      "key": "ditto.multicast.presence_peers",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being established by the Transport Connection Manager",
+      "key": "ditto.network.connections.connecting",
+      "labels": {
+        "direction": "outbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being established by the Transport Connection Manager",
+      "key": "ditto.network.connections.connecting",
+      "labels": {
+        "direction": "inbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of established connections currently managed by the Transport Connection Manager",
+      "key": "ditto.network.connections.established",
+      "labels": {
+        "direction": "inbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Number of documents with degraded sync",
+      "key": "ditto.store.database.sync_degraded_document_count",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Current multicast peers represented in the local Presence graph. Sum the state series for the total; `state=provisional` means identity is pending and `state=resolved` means the peer's announced identity has been applied.",
+      "key": "ditto.multicast.presence_peers",
+      "labels": {
+        "state": "resolved"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being disconnected by the Transport Connection Manager",
+      "key": "ditto.network.connections.disconnecting",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being established by the Transport Connection Manager",
+      "key": "ditto.network.connections.connecting",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of established connections currently managed by the Transport Connection Manager",
+      "key": "ditto.network.connections.established",
+      "labels": {
+        "direction": "outbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 10312392,
+      "delta": 0,
+      "description": "Size of the SQLite WAL file in bytes.",
+      "key": "ditto.backend.sqlite3.wal_file_size_bytes",
+      "labels": {},
+      "level": "info",
+      "unit": "bytes",
+      "updates": 309
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of established connections currently managed by the Transport Connection Manager",
+      "key": "ditto.network.connections.established",
+      "labels": {},
+      "level": "info",
+      "unit": "count",
+      "updates": 2
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of unique authenticated peers with at least one established connection",
+      "key": "ditto.network.peers.established",
+      "labels": {
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being disconnected by the Transport Connection Manager",
+      "key": "ditto.network.connections.disconnecting",
+      "labels": {
+        "direction": "inbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "The number of connections currently being disconnected by the Transport Connection Manager",
+      "key": "ditto.network.connections.disconnecting",
+      "labels": {
+        "direction": "outbound",
+        "transport_type": "websocket"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "current": 0,
+      "delta": 0,
+      "description": "Current multicast peers represented in the local Presence graph. Sum the state series for the total; `state=provisional` means identity is pending and `state=resolved` means the peer's announced identity has been applied.",
+      "key": "ditto.multicast.presence_peers",
+      "labels": {
+        "state": "provisional"
+      },
+      "level": "info",
+      "unit": "count",
+      "updates": 1
+    },
+    {
+      "abs_max": 0.001072707,
+      "count": 323,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "Time taken to parse statements",
+      "dmax": -0.000274244,
+      "dmin": 4.170000000000001e-7,
+      "dp50": -8.625e-6,
+      "dp90": -1.8685e-5,
+      "dp95": -2.2393e-5,
+      "dp99": -4.6686399999999994e-5,
+      "dsample_rate": 0,
+      "dsum": 1.2500000000003827e-6,
+      "key": "dql.parse_time",
+      "labels": {},
+      "level": "info",
+      "max": 1.25e-6,
+      "min": 1.25e-6,
+      "p50": 1.25e-6,
+      "p90": 1.25e-6,
+      "p95": 1.25e-6,
+      "p99": 1.25e-6,
+      "sample_rate": 1,
+      "sum": 0.005109158000000001,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 4,
+      "count": 324,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "Shared Statement Cache size",
+      "dmax": 0,
+      "dmin": 2,
+      "dp50": 2,
+      "dp90": 2,
+      "dp95": 1,
+      "dp99": 1,
+      "dsample_rate": 0,
+      "dsum": 4,
+      "key": "dql.shared_statement_cache",
+      "labels": {},
+      "level": "info",
+      "max": 4,
+      "min": 4,
+      "p50": 4,
+      "p90": 4,
+      "p95": 4,
+      "p99": 4,
+      "sample_rate": 1,
+      "sum": 673,
+      "unit": "count"
+    },
+    {
+      "abs_max": 0.000448084,
+      "count": 303,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Time spent in the backend commit/rollback call itself.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.store.transaction.commit_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.026094343,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 4.306e-5,
+      "count": 299,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Wall time of a complete get_multiple producer run (all chunks, all rows sent)",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.get_multiple_total_wall_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0007992580000000004,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 4,
+      "count": 324,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "Shared Statement Cache size",
+      "dmax": 0,
+      "dmin": 2,
+      "dp50": 2,
+      "dp90": 2,
+      "dp95": 1,
+      "dp99": 1,
+      "dsample_rate": 0,
+      "dsum": 4,
+      "key": "ditto.query.shared_statement_cache",
+      "labels": {},
+      "level": "info",
+      "max": 4,
+      "min": 4,
+      "p50": 4,
+      "p90": 4,
+      "p95": 4,
+      "p99": 4,
+      "sample_rate": 1,
+      "sum": 673,
+      "unit": "count"
+    },
+    {
+      "abs_max": 0.005865333,
+      "count": 303,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Time the write transaction held the lock, from MonotonicSender acquisition to commit/rollback.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.store.transaction.lock_hold_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.08067170099999997,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.002151917,
+      "count": 638,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "The time spent executing the background transaction loop for a given transaction",
+      "dmax": -0.0018090130000000002,
+      "dmin": 0.000313886,
+      "dp50": 0.000264952,
+      "dp90": 0.00022128319999999998,
+      "dp95": 0.00019319860000000002,
+      "dp99": -1.707179999999996e-5,
+      "dsample_rate": 0,
+      "dsum": 0.00034290399999999804,
+      "key": "ditto.backend.sqlite3.txn_duration_secs",
+      "labels": {
+        "mode": "read"
+      },
+      "level": "info",
+      "max": 0.000342904,
+      "min": 0.000342904,
+      "p50": 0.000342904,
+      "p90": 0.000342904,
+      "p95": 0.000342904,
+      "p99": 0.000342904,
+      "sample_rate": 1,
+      "sum": 0.06114684100000006,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.005871175,
+      "count": 1279,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "The time spent executing the background transaction loop for a given transaction",
+      "dmax": -0.0018090130000000002,
+      "dmin": 0.000313886,
+      "dp50": 0.000239425,
+      "dp90": 0.00010199469999999986,
+      "dp95": -3.222399999999856e-6,
+      "dp99": -0.00012697583999999988,
+      "dsample_rate": 0.1640816326530612,
+      "dsum": 0.000342904000000005,
+      "key": "ditto.backend.sqlite3.txn_duration_secs",
+      "labels": {},
+      "level": "info",
+      "max": 0.000342904,
+      "min": 0.000342904,
+      "p50": 0.000342904,
+      "p90": 0.000342904,
+      "p95": 0.000342904,
+      "p99": 0.000342904,
+      "sample_rate": 1,
+      "sum": 0.18775683199999982,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001072707,
+      "count": 323,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "Time taken to parse statements",
+      "dmax": -0.000274244,
+      "dmin": 4.170000000000001e-7,
+      "dp50": -8.625e-6,
+      "dp90": -1.8685e-5,
+      "dp95": -2.2393e-5,
+      "dp99": -4.6686399999999994e-5,
+      "dsample_rate": 0,
+      "dsum": 1.2500000000003827e-6,
+      "key": "ditto.query.parse_time",
+      "labels": {},
+      "level": "info",
+      "max": 1.25e-6,
+      "min": 1.25e-6,
+      "p50": 1.25e-6,
+      "p90": 1.25e-6,
+      "p95": 1.25e-6,
+      "p99": 1.25e-6,
+      "sample_rate": 1,
+      "sum": 0.005109158000000001,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.000173875,
+      "count": 303,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Time spent acquiring the backend write transaction lock.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.store.transaction.lock_wait_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.011411671999999998,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.000613416,
+      "count": 3,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Duration of SQLite xSync (fsync) operations.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.fsync_duration_secs",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.001242333,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.00054475,
+      "count": 6,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Duration of SQLite xSync (fsync) operations.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.fsync_duration_secs",
+      "labels": {
+        "db": "attachment"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.002214083,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.005871175,
+      "count": 641,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "The time spent executing the background transaction loop for a given transaction",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.txn_duration_secs",
+      "labels": {
+        "mode": "write"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.12660999099999995,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.000613416,
+      "count": 9,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Duration of SQLite xSync (fsync) operations.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.fsync_duration_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0034564160000000003,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001302017,
+      "count": 322,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "Time taken to execute statements",
+      "dmax": -0.000982487,
+      "dmin": 0.000260745,
+      "dp50": 0.000228495,
+      "dp90": 0.000122339,
+      "dp95": -5.373999999999993e-6,
+      "dp99": -6.097800000000032e-5,
+      "dsample_rate": 0,
+      "dsum": 0.0003195299999999984,
+      "key": "dql.execution_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.00031953,
+      "min": 0.00031953,
+      "p50": 0.00031953,
+      "p90": 0.00031953,
+      "p95": 0.00031953,
+      "p99": 0.00031953,
+      "sample_rate": 1,
+      "sum": 0.04140927800000002,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 2503,
+      "count": 309,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "SQLite WAL file size, in pages, at WAL-hook-fire time.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.wal_size_pages",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 381320,
+      "unit": "count"
+    },
+    {
+      "abs_max": 1.031e-5,
+      "count": 299,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Per-row sqlite3_step duration inside get_multiple",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.get_multiple_sqlite_step_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.000314623,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001008339,
+      "count": 302,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Time taken to plan statements",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "dql.plan_time",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0022376579999999996,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 1.166e-6,
+      "count": 299,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Per-chunk time from prepare_cached to first rows.next() in get_multiple",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.get_multiple_chunk_overhead_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 4.372500000000003e-5,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 6,
+      "count": 2,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "SQLite WAL file size, in pages, at WAL-hook-fire time.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.wal_size_pages",
+      "labels": {
+        "db": "attachment"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 9,
+      "unit": "count"
+    },
+    {
+      "abs_max": 0.000112334,
+      "count": 303,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Time spent waiting for the MonotonicSender after the backend write lock is held.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.store.transaction.monotonic_wait_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.000466765,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 1.0125e-5,
+      "count": 909,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "The time spent attempting to send a database event on a full channel.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.store.database.event_delay_secs",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0012286489999999992,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 1.0125e-5,
+      "count": 909,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "The time spent attempting to send a database event on a full channel.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.store.database.event_delay_secs",
+      "labels": {
+        "outcome": "immediate"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0012286489999999992,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001008339,
+      "count": 302,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "Time taken to plan statements",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.query.plan_time",
+      "labels": {},
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 0.0022376579999999996,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 0.001302017,
+      "count": 322,
+      "dabs_max": 0,
+      "dcount": 1,
+      "description": "Time taken to execute statements",
+      "dmax": -0.000982487,
+      "dmin": 0.000260745,
+      "dp50": 0.000228495,
+      "dp90": 0.000122339,
+      "dp95": -5.373999999999993e-6,
+      "dp99": -6.097800000000032e-5,
+      "dsample_rate": 0,
+      "dsum": 0.0003195299999999984,
+      "key": "ditto.query.execution_time",
+      "labels": {},
+      "level": "info",
+      "max": 0.00031953,
+      "min": 0.00031953,
+      "p50": 0.00031953,
+      "p90": 0.00031953,
+      "p95": 0.00031953,
+      "p99": 0.00031953,
+      "sample_rate": 1,
+      "sum": 0.04140927800000002,
+      "unit": "seconds"
+    },
+    {
+      "abs_max": 2503,
+      "count": 307,
+      "dabs_max": 0,
+      "dcount": 0,
+      "description": "SQLite WAL file size, in pages, at WAL-hook-fire time.",
+      "dsample_rate": 0,
+      "dsum": 0,
+      "key": "ditto.backend.sqlite3.wal_size_pages",
+      "labels": {
+        "db": "main"
+      },
+      "level": "info",
+      "sample_rate": 1,
+      "sum": 381311,
+      "unit": "count"
+    }
+  ],
+  "disabled": [
+    {
+      "description": "set the system parameter METRICS_EXPORTER_VIRTUAL_COLLECTION_ENABLED to true at startup to enable the metrics virtual collection exporter",
+      "status": "disabled"
+    }
+  ]
+}
diff --git a/tests/unit/profile.test.ts b/tests/unit/profile.test.ts
index 15103ab..26b977b 100644
--- a/tests/unit/profile.test.ts
+++ b/tests/unit/profile.test.ts
@@ -11,7 +11,8 @@ import {
 import { extractProfile, type PlanNode, parseProfileItem } from "../../src/profile/parse.js";
 import { renderProfile } from "../../src/render/profile.js";
 
-// Real envelope captured from SDK 5.1.0 (scripts/spike-c.mjs). `envelope` is
+// Real envelopes captured from SDK 5.2.0 (scripts/spike-c.mjs): [0] filtered
+// SELECT, [1] sorted SELECT, [2] JOIN with an `nlJoin.inner` subplan. `envelope` is
 // the result-row object: `{ "~request_profile": { … } }`.
 const fixture = JSON.parse(
   fs.readFileSync(path.join(import.meta.dirname, "fixtures", "profile-envelope.json"), "utf8"),
@@ -22,8 +23,9 @@ const fixture = JSON.parse(
 
 const wrappedRow = fixture.profiles[0]!.envelope!;
 const bareEnvelope = wrappedRow["~request_profile"] as Record<string, unknown>;
+const joinRow = fixture.profiles[2]!.envelope!;
 
-describe("parseProfileItem (real SDK 5.1.0 envelope)", () => {
+describe("parseProfileItem (real SDK 5.2.0 envelope)", () => {
   it("parses the wrapped form", () => {
     const p = parseProfileItem(wrappedRow)!;
     expect(p.id).toBeTruthy();
@@ -78,6 +80,58 @@ describe("parseProfileItem (real SDK 5.1.0 envelope)", () => {
   });
 });
 
+describe("parseProfileItem (SDK 5.1+ stats: stor, yields, skipped, subplans)", () => {
+  const withStats = (stats: Record<string, unknown>, extra: Record<string, unknown> = {}) =>
+    parseProfileItem({
+      "~request_profile": {
+        times: { elapsed: 1 },
+        state: "completed",
+        plan: { "#operator": "fetch", "#stats": stats, ...extra },
+      },
+    })!.plan!;
+
+  it("parses stor phase time and documentsSkipped", () => {
+    const node = withStats({ documentsSkipped: 3, phaseTimes: { exec: 1, stor: 42 } });
+    expect(node.stats?.phaseTimes?.stor).toBe(42);
+    expect(node.stats?.documentsSkipped).toBe(3);
+  });
+
+  it("keeps non-zero yield counters (including unknown reasons) and drops zeros", () => {
+    const node = withStats({ yields: { budget: 61, sender: 0, receiver: 1, future: 2, bad: "x" } });
+    expect(node.stats?.yields).toEqual({ budget: 61, receiver: 1, future: 2 });
+  });
+
+  it("leaves yields undefined when every counter is zero or missing", () => {
+    expect(withStats({ yields: { budget: 0 } }).stats?.yields).toBeUndefined();
+    expect(withStats({ yields: null }).stats?.yields).toBeUndefined();
+    expect(withStats({ documentsOut: 1 }).stats?.yields).toBeUndefined();
+  });
+
+  it("treats object-valued fields with #operator as labeled subplans, not attributes", () => {
+    const node = withStats({}, { inner: { "#operator": "scan" }, desc: { index: "i" } });
+    expect(node.subplans).toEqual([
+      { key: "inner", plan: expect.objectContaining({ name: "scan" }) },
+    ]);
+    expect(node.attributes.map(([k]) => k)).toEqual(["desc"]);
+  });
+
+  it("parses envelope directives", () => {
+    expect(parseProfileItem(wrappedRow)!.directives).toEqual({ "#profile": true });
+  });
+
+  it("parses the real nlJoin.inner subplan with stor + yields from SDK 5.2.0", () => {
+    const p = parseProfileItem(joinRow)!;
+    const join = p.plan!.children.find((c) => c.name === "nlJoin")!;
+    expect(join.subplans?.[0]?.key).toBe("inner");
+    expect(join.attributes.map(([k]) => k)).not.toContain("inner");
+    const inner = join.subplans![0]!.plan;
+    const fetch = inner.children.find((c) => c.name === "fetch")!;
+    expect(fetch.stats?.phaseTimes?.stor).toBeGreaterThan(0);
+    const yielded = annotatePlan(p.plan!).filter((n) => n.node.stats?.yields);
+    expect(yielded.length).toBeGreaterThan(0);
+  });
+});
+
 describe("extractProfile", () => {
   it("strips the envelope from the row set", () => {
     const rows = [{ _id: "1" }, wrappedRow];
@@ -150,6 +204,28 @@ describe("hotspots", () => {
     expect(HOTSPOT_THRESHOLD).toBe(0.5);
   });
 
+  it("includes subplans in subtree exec and labels them in the walk", () => {
+    const join: PlanNode = {
+      name: "nlJoin",
+      attributes: [],
+      stats: { phaseTimes: { exec: 10 } },
+      children: [],
+      subplans: [
+        {
+          key: "inner",
+          plan: { name: "scan", attributes: [], stats: { phaseTimes: { exec: 90 } }, children: [] },
+        },
+      ],
+    };
+    expect(subtreeExecNs(join)).toBe(100);
+    const annotated = annotatePlan(join);
+    expect(annotated.map((n) => [n.node.name, n.depth, n.label])).toEqual([
+      ["nlJoin", 0, undefined],
+      ["scan", 1, "inner"],
+    ]);
+    expect(annotated[1]?.isHotspot).toBe(true);
+  });
+
   it("keyAttribute prefers collection over condition", () => {
     expect(keyAttribute(tree.children[0]!)).toBe("collection=movies");
     expect(keyAttribute(tree.children[1]!)).toBe("condition=rated = PG");
@@ -173,6 +249,66 @@ describe("renderProfile", () => {
     expect(out).toContain("▲ HOT"); // filter dominates exec in this fixture
   });
 
+  it("renders SDK 5.2.0 detail: phase times, yields, attributes, inner subplan, totals", () => {
+    const profile = parseProfileItem(joinRow)!;
+    const out = renderProfile(profile, "SELECT …");
+    expect(out).toMatch(/directives #profile/);
+    expect(out).toMatch(/request \S+/);
+    expect(out).toMatch(/flags 0x/);
+    expect(out).toMatch(/Stor \d/);
+    expect(out).toMatch(/Yields \d/);
+    expect(out).toContain("inner: sequence");
+    expect(out).toMatch(/stor \d/);
+    expect(out).toMatch(/recv \d/);
+    expect(out).toMatch(/yields: \w+ \d/);
+    expect(out).toContain("alias=y");
+    expect(out).toContain("legend");
+    expect(out).toContain("yields = scheduler yields");
+  });
+
+  it("renders skipped docs, sorts yields by count, and truncates long attributes", () => {
+    const out = renderProfile(
+      {
+        times: { elapsedNs: 1 },
+        plan: {
+          name: "fetch",
+          attributes: [
+            ["collection", "c"],
+            ["desc", { spans: "x".repeat(200) }],
+          ],
+          stats: {
+            documentsIn: 5,
+            documentsOut: 2,
+            documentsSkipped: 3,
+            phaseTimes: { exec: 1, stor: 2_000 },
+            yields: { receiver: 1, budget: 1_500 },
+          },
+          children: [],
+        },
+      },
+      "SELECT 1",
+    );
+    expect(out).toContain("5 in / 2 out / 3 skipped");
+    expect(out).toContain("yields: budget 1,500 · receiver 1");
+    expect(out).toContain("stor 2.00 µs");
+    expect(out).toContain("Stor 2.00 µs");
+    expect(out).toContain("Yields 1,501");
+    expect(out).toMatch(/desc=\{"spans":"x+…/);
+    expect(out).not.toContain("x".repeat(100));
+    expect(out).not.toContain("collection=c collection"); // key attribute isn't repeated
+  });
+
+  it("omits the metadata line, totals, and detail lines when the envelope lacks them", () => {
+    const out = renderProfile(
+      { times: {}, plan: { name: "scan", attributes: [], children: [] } },
+      "SELECT 1",
+    );
+    expect(out).not.toContain("directives");
+    expect(out).not.toContain("Stor ");
+    expect(out).not.toContain("Yields ");
+    expect(out).not.toContain("yields:");
+  });
+
   it("handles a profile with no plan gracefully", () => {
     const out = renderProfile({ times: {} }, "SELECT 1");
     expect(out).toContain("(plan unavailable)");
diff --git a/tests/unit/session-mock.test.ts b/tests/unit/session-mock.test.ts
index d0fc3cb..208c3df 100644
--- a/tests/unit/session-mock.test.ts
+++ b/tests/unit/session-mock.test.ts
@@ -9,6 +9,7 @@ const h = vi.hoisted(() => ({
   openCalls: 0,
   licenseCalls: 0,
   closeCalls: 0,
+  configArgs: [] as unknown[],
 }));
 
 vi.mock("@dittolive/ditto", () => {
@@ -20,7 +21,11 @@ vi.mock("@dittolive/ditto", () => {
     init: async () => {
       h.initCalls++;
     },
-    DittoConfig: class {},
+    DittoConfig: class {
+      constructor(...args: unknown[]) {
+        h.configArgs = args;
+      }
+    },
     Ditto: {
       open: async () => {
         h.openCalls++;
@@ -97,6 +102,24 @@ describe("DittoSession (mocked SDK)", () => {
     }
   });
 
+  it("opens offline-only with the system:metrics exporter enabled (startup-gated)", async () => {
+    const dir = tmpDataDir("ditto-sess-");
+    try {
+      const session = await DittoSession.open(IDENTITY, dir);
+      expect(h.configArgs).toEqual([
+        {
+          databaseID: "app",
+          connect: { mode: "smallPeersOnly" },
+          persistenceDirectory: dir,
+          systemParameters: { metrics_exporter_virtual_collection_enabled: true },
+        },
+      ]);
+      await session.close();
+    } finally {
+      rmrf(dir);
+    }
+  });
+
   it("lock error → LockError (exit 4)", async () => {
     h.openBehavior = "lock";
     const dir = tmpDataDir("ditto-sess-");
diff --git a/tests/unit/support.test.ts b/tests/unit/support.test.ts
new file mode 100644
index 0000000..15c4a85
--- /dev/null
+++ b/tests/unit/support.test.ts
@@ -0,0 +1,568 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PassThrough } from "node:stream";
+import * as tar from "tar";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { DoctorCheck } from "../../src/cli/groups/dql/doctor.js";
+import { sdkDebugLevel } from "../../src/ditto/session.js";
+import { writeArchive } from "../../src/support/archive.js";
+import {
+  isDiagnosticCommand,
+  LAST_ERROR_FILE,
+  type LastError,
+  readLastError,
+  recordLastError,
+  startStderrTail,
+} from "../../src/support/last-error.js";
+import { isSecretEnv, makeRedactor, secretEnvValues } from "../../src/support/redact.js";
+import {
+  collectReport,
+  collectSettings,
+  describeContents,
+  dirSize,
+  formatBytes,
+  freeSpace,
+  type ReportInputs,
+  renderReport,
+  renderReportJson,
+  type StoreSession,
+} from "../../src/support/report.js";
+import {
+  type AttachmentToken,
+  bundleErrorMessage,
+  listSupportBundles,
+  saveSupportBundle,
+} from "../../src/support/sdk-bundle.js";
+import { rmrf, tmpDataDir } from "../helpers/credentials.js";
+
+let dir: string;
+beforeEach(() => {
+  dir = tmpDataDir("ditto-support-");
+});
+afterEach(() => rmrf(dir));
+
+const BUNDLE_ROW = {
+  _id: { pk: "pk1", created_at: "2026-11-07T12:00:00+00:00" },
+  reason: "USER_INITIATED",
+  file: { id: "att1", len: 30720, metadata: { source: "test" } },
+};
+const RATE_ERROR = new Error(
+  "Query failed: `Support bundle request failure: failed to request support bundle: support bundle request rate exceeded: at most 3 requests are allowed per 10 minutes; retry in 600 seconds`. For more information on Ditto's query language see: https://ditto.com/link/dql-guide",
+);
+
+/** A fake store: answers the support-bundle and summary queries. */
+function fakeStore(
+  opts: {
+    requestFails?: Error;
+    existing?: unknown[];
+    bundleRow?: unknown;
+    collections?: string[];
+    countFails?: string;
+    summaryFails?: boolean;
+  } = {},
+) {
+  const calls: string[] = [];
+  const saved: { token: AttachmentToken; file: string }[] = [];
+  let closed = false;
+  const session: StoreSession = {
+    async execute(statement: string) {
+      calls.push(statement);
+      if (statement.startsWith("EXECUTE FUNCTION system_request_support_bundle")) {
+        if (opts.requestFails) throw opts.requestFails;
+        return { items: [{ value: opts.bundleRow ?? BUNDLE_ROW }] };
+      }
+      if (statement.startsWith("SELECT * FROM system:support_bundles")) {
+        return { items: (opts.existing ?? []).map((value) => ({ value })) };
+      }
+      if (statement === "SELECT * FROM system:collections") {
+        if (opts.summaryFails) throw new Error("summary boom");
+        const names = opts.collections ?? ["movies", "__feature_flags", "my `odd` cars"];
+        return { items: names.map((name) => ({ value: { name } })) };
+      }
+      if (statement.startsWith("SELECT COUNT(*)")) {
+        if (opts.countFails && statement.includes(opts.countFails)) throw new Error("count boom");
+        return { items: [{ value: { n: 42 } }] };
+      }
+      if (statement === "SELECT * FROM system:indexes") {
+        return {
+          items: [
+            {
+              value: {
+                _id: "movies.by_year",
+                collection: "movies",
+                fields: [
+                  { key: ["_id", "year"], direction: "asc" },
+                  { key: ["rated"], direction: "desc" },
+                ],
+              },
+            },
+            { value: { _id: "odd", collection: "c", fields: "weird" } },
+          ],
+        };
+      }
+      throw new Error(`unexpected statement: ${statement}`);
+    },
+    async saveAttachment(token, file) {
+      saved.push({ token, file });
+      fs.writeFileSync(file, "tar-bytes");
+    },
+    async close() {
+      closed = true;
+    },
+  };
+  return { session, calls, saved, closed: () => closed };
+}
+
+describe("makeRedactor", () => {
+  it("hides secrets and shows the home folder as ~", () => {
+    const r = makeRedactor({
+      home: "/Users/al",
+      secrets: ["supersecrettoken", undefined, "short"],
+    });
+    expect(r("token=supersecrettoken in /Users/al/x and /Users/al")).toBe(
+      "token=[redacted] in ~/x and ~",
+    );
+    // A different user whose name starts with the same letters is untouched.
+    expect(r("/Users/alex/file")).toBe("/Users/alex/file");
+    // Short secrets would mangle ordinary words, so they're skipped.
+    expect(r("a short word")).toBe("a short word");
+  });
+
+  it("replaces the longer of two overlapping secrets whole", () => {
+    const r = makeRedactor({ home: "/", secrets: ["abcdefgh", "abcdefghijkl"] });
+    expect(r("x abcdefghijkl y")).toBe("x [redacted] y");
+  });
+
+  it("does nothing without secrets or a usable home", () => {
+    expect(makeRedactor({ home: "/" })("/a/b")).toBe("/a/b");
+    expect(makeRedactor()("plain")).toBe("plain");
+  });
+});
+
+describe("credential env vars", () => {
+  it("recognizes credentials by list and by name", () => {
+    for (const k of [
+      "DITTOSH_GITHUB_TOKEN",
+      "OFFLINE_TOKEN",
+      "DATABASE_ID",
+      "DITTOSH_SOME_SECRET",
+      "MY_API_KEY",
+      "DITTOSH_PASSWORD",
+    ]) {
+      expect(isSecretEnv(k), k).toBe(true);
+    }
+    for (const k of ["DITTOSH_DATA_DIR", "DITTOSH_QUIET", "TERM", "PAGER"]) {
+      expect(isSecretEnv(k), k).toBe(false);
+    }
+  });
+
+  it("collects the values of set credential vars only", () => {
+    expect(
+      secretEnvValues({ DITTOSH_GITHUB_TOKEN: "ghp_x", OTHER: "y", EMPTY_TOKEN: "" }).sort(),
+    ).toEqual(["ghp_x"]);
+  });
+});
+
+describe("last error", () => {
+  it("keeps the last lines written to a stream, without colors, and passes writes through", () => {
+    const stream = new PassThrough() as unknown as NodeJS.WriteStream;
+    const seen: string[] = [];
+    (stream as unknown as PassThrough).on("data", (d) => seen.push(String(d)));
+    const tail = startStderrTail(stream, 3);
+    stream.write("\x1b[31mone\x1b[39m\ntwo\n");
+    stream.write(Buffer.from("three\nfour\npar"));
+    stream.write("tial");
+    stream.write(new Uint8Array([1]) as unknown as string); // not a string or Buffer: ignored by capture
+    expect(tail.lines()).toEqual(["three", "four", "partial"]);
+    tail.stop();
+    stream.write("after\n");
+    expect(tail.lines()).toEqual(["three", "four", "partial"]);
+    expect(seen.join("")).toContain("one");
+    expect(seen.join("")).toContain("after");
+  });
+
+  it("records and reads the last error", () => {
+    const entry: LastError = {
+      time: "2026-11-07T00:00:00Z",
+      version: "0.2.0",
+      command: ["dql", "SELEC"],
+      exitCode: 1,
+      stderr: ["Query error"],
+      stack: "Error: x\n  at y",
+    };
+    recordLastError(entry, dir);
+    expect(readLastError(dir)).toEqual(entry);
+    // Without a stack, the field is left out.
+    recordLastError({ ...entry, stack: undefined }, dir);
+    expect(readLastError(dir)).not.toHaveProperty("stack");
+  });
+
+  it("returns null for a missing, corrupt, or wrong-shaped file, and fills defaults", () => {
+    expect(readLastError(dir)).toBeNull();
+    const f = path.join(dir, LAST_ERROR_FILE);
+    fs.writeFileSync(f, "{not json");
+    expect(readLastError(dir)).toBeNull();
+    fs.writeFileSync(f, "[1]");
+    expect(readLastError(dir)).toBeNull();
+    fs.writeFileSync(f, JSON.stringify({ time: 5, command: [] }));
+    expect(readLastError(dir)).toBeNull();
+    fs.writeFileSync(f, JSON.stringify({ time: "t", command: ["a", 1] }));
+    expect(readLastError(dir)).toEqual({
+      time: "t",
+      version: "unknown",
+      command: ["a", "1"],
+      exitCode: 1,
+      stderr: [],
+    });
+  });
+
+  it("never throws when the config dir can't be written", () => {
+    const file = path.join(dir, "a-file");
+    fs.writeFileSync(file, "x");
+    expect(() =>
+      recordLastError(
+        { time: "t", version: "v", command: [], exitCode: 1, stderr: [] },
+        path.join(file, "sub"),
+      ),
+    ).not.toThrow();
+  });
+
+  it("knows which commands are diagnostics", () => {
+    expect(isDiagnosticCommand(["doctor", "--report"])).toBe(true);
+    expect(isDiagnosticCommand(["dql", "support-bundle"])).toBe(true);
+    expect(isDiagnosticCommand(["dql", "SELECT 1"])).toBe(false);
+  });
+});
+
+describe("sdkDebugLevel", () => {
+  it.each([
+    [undefined, null],
+    ["", null],
+    ["0", null],
+    ["false", null],
+    ["off", null],
+    ["1", "Debug"],
+    ["true", "Debug"],
+    ["VERBOSE", "Verbose"],
+  ])("%s → %s", (value, level) => {
+    expect(sdkDebugLevel(value)).toBe(level);
+  });
+});
+
+describe("SDK support bundle", () => {
+  it("requests a bundle with metadata and saves its attachment", async () => {
+    const f = fakeStore();
+    const out = path.join(dir, "b.tar");
+    const saved = await saveSupportBundle(f.session, out, { source: "dittosh 'x'", v: "1.0" });
+    expect(f.calls[0]).toBe(
+      "EXECUTE FUNCTION system_request_support_bundle({'metadata': {'source': 'dittosh x', 'v': '1.0'}})",
+    );
+    expect(f.saved[0]).toEqual({ token: BUNDLE_ROW.file, file: out });
+    expect(saved).toEqual({
+      path: out,
+      bytes: 30720,
+      createdAt: "2026-11-07T12:00:00+00:00",
+      reason: "USER_INITIATED",
+    });
+  });
+
+  it("saves the newest existing bundle when a new one is refused", async () => {
+    const f = fakeStore({ requestFails: RATE_ERROR, existing: [BUNDLE_ROW] });
+    const saved = await saveSupportBundle(f.session, path.join(dir, "b.tar"));
+    expect(saved.reusedBecause).toBe(
+      "support bundle request rate exceeded: at most 3 requests are allowed per 10 minutes; retry in 600 seconds",
+    );
+    expect(f.calls[1]).toContain("ORDER BY _id.created_at DESC LIMIT 1");
+  });
+
+  it("throws the refusal when there's no bundle to fall back on", async () => {
+    const f = fakeStore({ requestFails: RATE_ERROR });
+    await expect(saveSupportBundle(f.session, path.join(dir, "b.tar"))).rejects.toThrow(
+      /rate exceeded/,
+    );
+  });
+
+  it("throws when the SDK returns no file, and defaults missing fields", async () => {
+    await expect(
+      saveSupportBundle(fakeStore({ bundleRow: {} }).session, path.join(dir, "b.tar")),
+    ).rejects.toThrow(/no support bundle file/);
+    const saved = await saveSupportBundle(
+      fakeStore({ bundleRow: { file: { id: "a", len: 5n, metadata: {} } } }).session,
+      path.join(dir, "c.tar"),
+    );
+    expect(saved).toMatchObject({ bytes: 5, createdAt: "unknown", reason: "unknown" });
+  });
+
+  it("lists bundles newest first", async () => {
+    const f = fakeStore({ existing: [BUNDLE_ROW, {}] });
+    expect(await listSupportBundles(f.session)).toEqual([
+      { created_at: "2026-11-07T12:00:00+00:00", reason: "USER_INITIATED", bytes: 30720 },
+      { created_at: "unknown", reason: "unknown", bytes: 0 },
+    ]);
+  });
+
+  it("strips the SDK's error wrapper", () => {
+    expect(bundleErrorMessage(RATE_ERROR)).toMatch(/^support bundle request rate exceeded/);
+    expect(bundleErrorMessage("plain")).toBe("plain");
+  });
+});
+
+describe("report helpers", () => {
+  it("formats bytes", () => {
+    expect(formatBytes(512)).toBe("512 B");
+    expect(formatBytes(1536)).toBe("1.5 KB");
+    expect(formatBytes(20 * 1024 * 1024)).toBe("20 MB");
+    expect(formatBytes(3 * 1024 ** 5)).toBe("3072 TB");
+  });
+
+  it("sizes a directory tree and finds free space for a missing path", () => {
+    fs.mkdirSync(path.join(dir, "a/b"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "a/b/f"), "12345");
+    fs.writeFileSync(path.join(dir, "g"), "123");
+    expect(dirSize(dir)).toBe(8);
+    expect(dirSize(path.join(dir, "missing"))).toBe(0);
+    expect(freeSpace(path.join(dir, "not/yet/here"))).toBeGreaterThan(0);
+  });
+
+  it("lists settings and hides credential values", () => {
+    const s = collectSettings({
+      DITTOSH_DATA_DIR: "/d",
+      NO_COLOR: "",
+      OFFLINE_TOKEN: "secret-token",
+      PATH: "/bin",
+    });
+    expect(s.DITTOSH_DATA_DIR).toBe("/d");
+    expect(s.NO_COLOR).toBe("");
+    expect(s.OFFLINE_TOKEN).toBe("set (value hidden)");
+    expect(s.DATABASE_ID).toBe("not set");
+    expect(s).not.toHaveProperty("PATH");
+    expect(JSON.stringify(s)).not.toContain("secret-token");
+    const t = collectSettings({
+      DITTOSH_GITHUB_TOKEN: "ghp_FAKEtoken1234567890",
+      DITTOSH_FUTURE_SECRET: "another-secret-value",
+    });
+    expect(t.DITTOSH_GITHUB_TOKEN).toBe("set (value hidden)");
+    expect(t.DITTOSH_FUTURE_SECRET).toBe("set (value hidden)");
+    expect(JSON.stringify(t)).not.toMatch(/ghp_FAKE|another-secret/);
+  });
+});
+
+describe("collectReport", () => {
+  const checks: DoctorCheck[] = [
+    { ok: true, label: "platform", detail: "darwin/arm64 supported" },
+    { ok: false, label: "lock", detail: "locked" },
+  ];
+  const lastError: LastError = {
+    time: "2026-11-07T00:00:00Z",
+    version: "0.2.0",
+    command: ["dql", "SELEC x"],
+    exitCode: 1,
+    stderr: ["Query error"],
+    stack: "Error: boom\n  at here",
+  };
+
+  function inputs(over: Partial<ReportInputs> = {}): ReportInputs {
+    const f = fakeStore();
+    return {
+      dataDir: path.join(dir, "store"),
+      configDir: path.join(dir, "cfg"),
+      includeStore: true,
+      includeSdkBundle: true,
+      workDir: dir,
+      checks,
+      environment: { dittosh: "0.2.0" },
+      lastError: null,
+      env: {},
+      openStore: async () => f.session,
+      saveBundle: (s, file) => saveSupportBundle(s, file),
+      now: () => new Date("2026-11-07T10:00:00Z"),
+      ...over,
+    };
+  }
+
+  function makeStoreDir() {
+    fs.mkdirSync(path.join(dir, "store"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "store", "__ditto_lock_file"), "");
+    fs.mkdirSync(path.join(dir, "cfg"), { recursive: true });
+    fs.writeFileSync(path.join(dir, "cfg", "state.json"), "{}");
+  }
+
+  it("summarizes the store, saves the SDK bundle, and closes the store", async () => {
+    makeStoreDir();
+    const f = fakeStore({ countFails: "odd" });
+    const r = await collectReport(inputs({ openStore: async () => f.session, lastError }));
+    expect(r.generated).toBe("2026-11-07T10:00:00.000Z");
+    expect(r.environment.dittosh).toBe("0.2.0");
+    expect(r.environment.platform).toBe(`${process.platform}/${process.arch}`);
+    expect(r.paths["config files"]).toBe("state.json");
+    expect(r.store.collections).toEqual([
+      { name: "movies", documents: 42 },
+      { name: "my `odd` cars", documents: "count failed: count boom" },
+    ]);
+    // Backticks in a collection name are doubled inside the quoted identifier.
+    expect(f.calls).toContain("SELECT COUNT(*) AS n FROM `my ``odd`` cars`");
+    expect(r.store.indexes).toEqual([
+      { id: "movies.by_year", collection: "movies", fields: "_id.year, rated desc" },
+      { id: "odd", collection: "c", fields: "" },
+    ]);
+    expect(r.sdkBundle).toEqual({
+      file: "ditto-support-bundle.tar",
+      detail: "30 KB, created 2026-11-07T12:00:00+00:00",
+    });
+    expect(fs.existsSync(path.join(dir, "ditto-support-bundle.tar"))).toBe(true);
+    expect(f.closed()).toBe(true);
+
+    const md = renderReport(r);
+    expect(md).toContain("# dittosh diagnostic report");
+    expect(md).toContain("- ✓ **platform**: darwin/arm64 supported");
+    expect(md).toContain("- ✗ **lock**: locked");
+    expect(md).toContain("| movies | 42 |");
+    expect(md).toContain("| movies.by_year | movies | _id.year, rated desc |");
+    expect(md).toContain("`ditto-support-bundle.tar`: 30 KB");
+    expect(md).toContain("`dittosh dql SELEC x` exited 1");
+    expect(md).toContain("Error: boom");
+    const contents = describeContents(r).join("\n");
+    expect(contents).toContain("store summary");
+    expect(contents).toContain("last error");
+    expect(contents).toContain("ditto-support-bundle.tar");
+  });
+
+  it("explains a reused SDK bundle", async () => {
+    makeStoreDir();
+    const f = fakeStore({ requestFails: RATE_ERROR, existing: [BUNDLE_ROW] });
+    const r = await collectReport(inputs({ openStore: async () => f.session }));
+    expect(r.sdkBundle.detail).toContain("an existing bundle");
+  });
+
+  it("reports when there's no store yet, without opening one", async () => {
+    let opened = false;
+    const r = await collectReport(
+      inputs({
+        openStore: async () => {
+          opened = true;
+          throw new Error("should not open");
+        },
+      }),
+    );
+    expect(opened).toBe(false);
+    expect(r.paths["store size"]).toBe("no store yet");
+    expect(r.paths["config files"]).toBe("(none)");
+    expect(r.store.skipped).toBe("no store at the data directory yet");
+    expect(r.sdkBundle.detail).toContain("not created");
+    const md = renderReport(r);
+    expect(md).toContain("Not included: no store at the data directory yet.");
+    expect(md).toContain("No failed command recorded.");
+    expect(describeContents(r)).toHaveLength(1);
+  });
+
+  it("respects --no-store and --no-sdk-bundle", async () => {
+    makeStoreDir();
+    const r = await collectReport(inputs({ includeStore: false, includeSdkBundle: false }));
+    expect(r.store.skipped).toBe("left out (--no-store)");
+    expect(r.sdkBundle.detail).toBe("left out (--no-sdk-bundle)");
+    // No store yet either: the opt-out text still wins for skipped parts.
+    rmrf(path.join(dir, "store"));
+    const r2 = await collectReport(inputs({ includeStore: false, includeSdkBundle: false }));
+    expect(r2.store.skipped).toBe("left out (--no-store)");
+  });
+
+  it("records a store that won't open", async () => {
+    makeStoreDir();
+    const r = await collectReport(
+      inputs({
+        openStore: async () => {
+          throw new Error("locked by another process\nmore detail");
+        },
+      }),
+    );
+    expect(r.store.skipped).toBe("the store didn't open: locked by another process");
+    expect(r.sdkBundle.detail).toBe(
+      "not created: the store didn't open: locked by another process",
+    );
+  });
+
+  it("records summary and bundle failures and still closes the store", async () => {
+    makeStoreDir();
+    const f = fakeStore({ summaryFails: true, requestFails: new Error("boom") });
+    const r = await collectReport(inputs({ openStore: async () => f.session }));
+    expect(r.store.skipped).toBe("summary failed: summary boom");
+    expect(r.sdkBundle.detail).toBe("failed: boom");
+    expect(f.closed()).toBe(true);
+  });
+
+  it("keeps table cells intact with pipes, backslashes, and newlines", async () => {
+    const r = await collectReport(
+      inputs({ environment: { path: "C:\\Users\\x\\|y", note: "a|b\nc" } }),
+    );
+    const md = renderReport(r);
+    expect(md).toContain("| path | C:\\Users\\x\\&#124;y |");
+    expect(md).toContain("| note | a&#124;b c |");
+  });
+
+  it("renders empty stores and a last error without output", async () => {
+    makeStoreDir();
+    const f = fakeStore({ collections: [] });
+    f.session.execute = async () => ({ items: [] });
+    const r = await collectReport(
+      inputs({
+        openStore: async () => f.session,
+        includeSdkBundle: false,
+        lastError: { ...lastError, stderr: [], stack: undefined },
+      }),
+    );
+    const md = renderReport(r);
+    expect(md).toContain("No collections.");
+    expect(md).toContain("No indexes.");
+    expect(md).toContain("left out (--no-sdk-bundle)");
+    expect(md).not.toContain("Stack trace");
+  });
+});
+
+describe("renderReportJson", () => {
+  it("redacts Windows home paths and secrets that JSON would escape", () => {
+    const redact = makeRedactor({ home: "C:\\Users\\al", secrets: ['tok"en\\secret'] });
+    const report = {
+      generated: "t",
+      environment: { node: "C:\\Users\\al\\node.exe", note: 'value tok"en\\secret here' },
+      checks: [],
+      settings: {},
+      paths: { "data directory": "C:\\Users\\al\\AppData\\Local\\dittosh" },
+      store: {},
+      sdkBundle: { detail: "" },
+      lastError: null,
+    };
+    const json = renderReportJson(report, redact);
+    expect(json).not.toContain("Users");
+    expect(json).not.toContain("secret");
+    const parsed = JSON.parse(json);
+    expect(parsed.paths["data directory"]).toBe("~\\AppData\\Local\\dittosh");
+    expect(parsed.environment.note).toBe("value [redacted] here");
+  });
+});
+
+describe("writeArchive", () => {
+  it("puts the files under one folder in a .tar.gz", async () => {
+    const work = path.join(dir, "work");
+    fs.mkdirSync(work);
+    fs.writeFileSync(path.join(work, "report.md"), "# hi");
+    fs.writeFileSync(path.join(work, "report.json"), "{}");
+    const out = path.join(dir, "out", "r.tar.gz");
+    const size = await writeArchive(out, work, "r", ["report.md", "report.json"]);
+    expect(size).toBe(fs.statSync(out).size);
+    const entries: string[] = [];
+    await tar.t({ file: out, onReadEntry: (e) => entries.push(e.path) });
+    expect(entries.sort()).toEqual(["r/", "r/report.json", "r/report.md"]);
+  });
+
+  it("works when the folder name matches a staged file (--report report.md)", async () => {
+    const work = path.join(dir, "work");
+    fs.mkdirSync(work);
+    fs.writeFileSync(path.join(work, "report.md"), "# hi");
+    fs.writeFileSync(path.join(work, "report.json"), "{}");
+    const out = path.join(dir, "report.md");
+    await writeArchive(out, work, "report.md", ["report.md", "report.json"]);
+    const entries: string[] = [];
+    await tar.t({ file: out, onReadEntry: (e) => entries.push(e.path) });
+    expect(entries.sort()).toEqual(["report.md/", "report.md/report.json", "report.md/report.md"]);
+  });
+});
diff --git a/tests/unit/system-metrics.test.ts b/tests/unit/system-metrics.test.ts
new file mode 100644
index 0000000..fff535a
--- /dev/null
+++ b/tests/unit/system-metrics.test.ts
@@ -0,0 +1,315 @@
+import fs from "node:fs";
+import path from "node:path";
+import stringWidth from "string-width";
+import { describe, expect, it } from "vitest";
+import {
+  METRICS_USAGE,
+  makeMetricsCommand,
+  parseMetricsArgs,
+} from "../../src/cli/groups/dql/metrics.js";
+import { dotHelp } from "../../src/cli/groups/dql/repl-core.js";
+import type { QueryExecutor } from "../../src/ditto/session.js";
+import {
+  buildSections,
+  isExporterDisabled,
+  parseMetricRow,
+  SECTION_IDS,
+  sectionOf,
+} from "../../src/metrics/system-metrics.js";
+import {
+  formatBytes,
+  formatSeconds,
+  formatValue,
+  renderMetrics,
+} from "../../src/render/metrics.js";
+
+// Real `SELECT * FROM system:metrics` rows from SDK 5.2.0 (see the fixture's note).
+const fixture = JSON.parse(
+  fs.readFileSync(path.join(import.meta.dirname, "fixtures", "system-metrics.json"), "utf8"),
+) as Record<"afterActivity" | "idle" | "disabled", Record<string, unknown>[]>;
+
+const rowsOf = (rows: Record<string, unknown>[]) =>
+  ({ items: rows.map((value) => ({ value })) }) as unknown as Awaited<
+    ReturnType<QueryExecutor["execute"]>
+  >;
+
+const fakeSession = (next: () => Record<string, unknown>[] | Error): QueryExecutor => ({
+  execute: async () => {
+    const r = next();
+    if (r instanceof Error) throw r;
+    return rowsOf(r);
+  },
+});
+
+describe("parseMetricRow", () => {
+  it("parses a counter: current is the total, delta the change since the last read", () => {
+    const s = parseMetricRow({
+      key: "ditto.query.requests",
+      labels: {},
+      current: 323,
+      delta: 322,
+      unit: "count",
+      description: "Number of DQL requests processed",
+    })!;
+    expect(s).toMatchObject({ kind: "counter", total: 323, delta: 322, unit: "count" });
+    expect(s.description).toContain("DQL requests");
+  });
+
+  it("parses a histogram: running count/sum/abs_max plus since-last-read window stats", () => {
+    const s = parseMetricRow({
+      key: "ditto.query.parse_time",
+      count: 4,
+      sum: 0.2,
+      abs_max: 0.1,
+      dcount: 1,
+      p50: 0.01,
+      p90: 0.02,
+      p99: 0.03,
+      max: 0.04,
+      unit: "seconds",
+      labels: { a: "x", ignored: 3 },
+    })!;
+    expect(s).toMatchObject({
+      kind: "histogram",
+      total: 4,
+      delta: 1,
+      sum: 0.2,
+      avg: 0.05,
+      peak: 0.1,
+      p50: 0.01,
+      p90: 0.02,
+      p99: 0.03,
+      max: 0.04,
+      labels: { a: "x" },
+    });
+  });
+
+  it("omits window stats that weren't reported and avg when count is zero", () => {
+    const s = parseMetricRow({ key: "k", count: 0, dcount: 0, sum: 0 })!;
+    expect(s.avg).toBeUndefined();
+    expect(s.p50).toBeUndefined();
+    expect(s.max).toBeUndefined();
+  });
+
+  it("rejects placeholder and keyless rows", () => {
+    expect(parseMetricRow(fixture.disabled[0]!)).toBeUndefined();
+    expect(parseMetricRow({ key: "" })).toBeUndefined();
+  });
+});
+
+describe("isExporterDisabled", () => {
+  it("detects the real disabled placeholder", () => {
+    expect(isExporterDisabled(fixture.disabled)).toBe(true);
+  });
+  it("is false for real metric rows and for an empty result", () => {
+    expect(isExporterDisabled(fixture.afterActivity)).toBe(false);
+    expect(isExporterDisabled([])).toBe(false);
+  });
+});
+
+describe("buildSections", () => {
+  const sections = buildSections(fixture.afterActivity);
+  const byId = Object.fromEntries(sections.map((s) => [s.id, s]));
+
+  it("routes keys to sections in display order", () => {
+    expect(sections.map((s) => s.id)).toEqual(
+      SECTION_IDS.filter((id) => sections.some((s) => s.id === id)),
+    );
+    expect(sectionOf("ditto.backend.sqlite3.fsync_total")).toBe("store");
+    expect(sectionOf("ditto.storage.total_bytes")).toBe("store");
+    expect(sectionOf("dql.requests")).toBe("query");
+    expect(sectionOf("ditto.multicast.x")).toBe("transport");
+    expect(sectionOf("ditto.metrics.self")).toBe("other");
+  });
+
+  it("drops dql.* aliases of ditto.query.* series", () => {
+    const keys = [...byId.query!.counters, ...byId.query!.histograms].map((g) => g.key);
+    expect(keys).toContain("ditto.query.requests");
+    expect(keys.some((k) => k.startsWith("dql."))).toBe(false);
+  });
+
+  it("keeps a dql.* series that has no ditto.query.* twin", () => {
+    const [query] = buildSections([{ key: "dql.only_legacy", current: 1, delta: 1 }]);
+    expect(query?.counters.map((g) => g.key)).toEqual(["dql.only_legacy"]);
+  });
+
+  it("groups labelled series under their aggregate, sorted by label", () => {
+    const fsync = byId.store!.counters.find((g) => g.key === "ditto.backend.sqlite3.fsync_total")!;
+    expect(fsync.series?.total).toBe(9);
+    expect(fsync.children.map((c) => c.labels.db)).toEqual(["attachment", "main"]);
+  });
+
+  it("splits counters from histograms", () => {
+    expect(byId.store!.histograms.some((g) => g.key.endsWith("txn_duration_secs"))).toBe(true);
+    expect(byId.store!.counters.some((g) => g.key.endsWith("txn_duration_secs"))).toBe(false);
+  });
+
+  it("keeps labelled-only metrics (no aggregate parent)", () => {
+    const [section] = buildSections([
+      { key: "ditto.store.x", labels: { db: "b" }, current: 2, delta: 0 },
+      { key: "ditto.store.x", labels: { db: "a" }, current: 1, delta: 0 },
+    ]);
+    const g = section!.counters[0]!;
+    expect(g.series).toBeUndefined();
+    expect(g.children.map((c) => c.labels.db)).toEqual(["a", "b"]);
+  });
+});
+
+describe("value formatting", () => {
+  it("scales seconds to three significant digits", () => {
+    expect(formatSeconds(0)).toBe("0");
+    expect(formatSeconds(4.2e-7)).toBe("420 ns");
+    expect(formatSeconds(0.0001486)).toBe("149 µs");
+    expect(formatSeconds(0.00002243)).toBe("22.4 µs");
+    expect(formatSeconds(0.001094)).toBe("1.09 ms");
+    expect(formatSeconds(2.5)).toBe("2.50 s");
+  });
+
+  it("scales bytes", () => {
+    expect(formatBytes(799)).toBe("799 B");
+    expect(formatBytes(6_750)).toBe("6.59 KB");
+    expect(formatBytes(10_312_392)).toBe("9.83 MB");
+    expect(formatBytes(5 * 1024 ** 4)).toBe("5.00 TB");
+  });
+
+  it("groups counts and trims fractions", () => {
+    expect(formatValue(1279, "count")).toBe("1,279");
+    expect(formatValue(2.07, "count")).toBe("2.07");
+    expect(formatValue(26.33, "count")).toBe("26.3");
+    expect(formatValue(1242.1, "count")).toBe("1,242");
+  });
+});
+
+describe("renderMetrics", () => {
+  const storeAndQuery = buildSections(fixture.afterActivity).filter(
+    (s) => s.id === "store" || s.id === "query",
+  );
+
+  it("renders counter and timing tables with two-level headers and namespace rows", () => {
+    const out = renderMetrics(storeAndQuery, {
+      firstRead: true,
+      readAt: new Date("2026-11-06T10:45:12"),
+    });
+    expect(out).toContain("System metrics");
+    expect(out).toContain("Store, Query (DQL)");
+    expect(out).toContain("read 10:45:12");
+    expect(out).toContain("first read this session");
+    for (const title of [
+      "Store · counters",
+      "Store · timings & distributions",
+      "Query (DQL) · counters",
+      "Query (DQL) · timings & distributions",
+    ]) {
+      expect(out).toContain(title);
+    }
+    expect(out).toContain("since session opened");
+    expect(out).toContain("since last .metrics");
+    expect(out).toMatch(/│ backend\.sqlite3 +│/); // namespace header row
+    expect(out).toMatch(/│ {3}fsync_total +│ +9 │/); // leaf under it
+    expect(out).toMatch(/│ {5}└ db=main +│ +3 │/); // labelled breakdown
+    expect(out).toMatch(/│ {3}requests +│ +323 │ +\+322 │/);
+    expect(out).toMatch(/execution_time +│ +321 │ +128 µs │/);
+    expect(out).toContain("9.83 MB");
+    expect(out).toContain("—"); // window stats absent for fsync (no new samples)
+  });
+
+  it("gives every table the same width for the name column", () => {
+    const out = renderMetrics(storeAndQuery);
+    const nameCols = out
+      .split("\n")
+      .filter((l) => l.startsWith("┌"))
+      .map((l) => l.indexOf("┬"));
+    expect(new Set(nameCols).size).toBe(1);
+  });
+
+  it("fits the terminal width by ellipsizing metric names", () => {
+    const out = renderMetrics(storeAndQuery, { maxWidth: 110 });
+    const tableLines = out.split("\n").filter((l) => /^[┌├│└]/.test(l));
+    expect(Math.max(...tableLines.map((l) => stringWidth(l)))).toBeLessThanOrEqual(110);
+    expect(out).toContain("…");
+  });
+
+  it("never shrinks names below the floor on very narrow terminals", () => {
+    const out = renderMetrics(storeAndQuery, { maxWidth: 40 });
+    expect(out).toMatch(/│ backend\.sqlite3 +│/);
+  });
+
+  it("shows negative changes and leaves labelled-only parents blank", () => {
+    const out = renderMetrics(
+      buildSections([
+        { key: "ditto.store.size", current: 10, delta: -4, unit: "bytes" },
+        { key: "ditto.store.x", labels: { db: "a" }, current: 1, delta: 0 },
+      ]),
+    );
+    expect(out).toContain("−4 B");
+    expect(out).toMatch(/│ {3}x +│ +│ +│/);
+  });
+
+  it("says so when the selection has no metrics", () => {
+    expect(renderMetrics([])).toContain("no metrics reported");
+  });
+});
+
+describe(".metrics command", () => {
+  it("parses section arguments", () => {
+    expect(parseMetricsArgs(undefined)).toEqual(["store", "query"]);
+    expect(parseMetricsArgs("  ")).toEqual(["store", "query"]);
+    expect(parseMetricsArgs("QUERY")).toEqual(["query"]);
+    expect(parseMetricsArgs("query, store")).toEqual(["store", "query"]);
+    expect(parseMetricsArgs("all")).toEqual(SECTION_IDS);
+    expect(parseMetricsArgs("bogus")).toBeUndefined();
+    expect(METRICS_USAGE).toContain("all");
+  });
+
+  it("notes the first read only once and renders the selected sections", async () => {
+    const reads = [fixture.afterActivity, fixture.idle];
+    const cmd = makeMetricsCommand(
+      fakeSession(() => reads.shift()!),
+      { maxWidth: () => undefined },
+    );
+    const first = await cmd();
+    expect(first.ok).toBe(true);
+    expect(first.text).toContain("first read this session");
+    expect(first.text).toContain("Store · counters");
+    const second = await cmd("query");
+    expect(second.text).not.toContain("first read this session");
+    expect(second.text).not.toContain("Store ·");
+    expect(second.text).toContain("Query (DQL) · counters");
+  });
+
+  it("uses the terminal width by default", async () => {
+    const cmd = makeMetricsCommand(fakeSession(() => fixture.afterActivity));
+    expect((await cmd()).ok).toBe(true);
+  });
+
+  it("rejects unknown sections without querying", async () => {
+    let calls = 0;
+    const cmd = makeMetricsCommand(
+      fakeSession(() => {
+        calls++;
+        return [];
+      }),
+    );
+    const r = await cmd("bogus");
+    expect(r.ok).toBe(false);
+    expect(r.text).toContain("unknown metrics section: bogus");
+    expect(r.text).toContain("usage: .metrics");
+    expect(calls).toBe(0);
+  });
+
+  it("explains a disabled exporter", async () => {
+    const r = await makeMetricsCommand(fakeSession(() => fixture.disabled))();
+    expect(r.ok).toBe(false);
+    expect(r.text).toContain("System metrics are disabled");
+  });
+
+  it("reports query failures", async () => {
+    const r = await makeMetricsCommand(fakeSession(() => new Error("boom")))();
+    expect(r.ok).toBe(false);
+    expect(r.text).toContain("Cannot read system metrics: boom");
+  });
+
+  it("is listed in .help", () => {
+    expect(dotHelp()).toContain(".metrics");
+  });
+});
diff --git a/tests/unit/tutorial-practice-store.test.ts b/tests/unit/tutorial-practice-store.test.ts
new file mode 100644
index 0000000..023778b
--- /dev/null
+++ b/tests/unit/tutorial-practice-store.test.ts
@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  checkPracticeStore,
+  markPracticeStore,
+  PRACTICE_MARKER,
+  practiceStoreDir,
+} from "../../src/tutorial/practice-store.js";
+
+const dirs: string[] = [];
+const tmp = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), "dittosh-practice-"));
+  dirs.push(d);
+  return d;
+};
+afterEach(() => {
+  for (const d of dirs.splice(0)) fs.rmSync(d, { recursive: true, force: true });
+});
+
+describe("practice store guard", () => {
+  const own = "/cfg/tutorial-store";
+
+  it("a blank or missing -d means the tutorial's own store, never the default dql store", () => {
+    for (const flag of [undefined, "", "  ", "=", "= "]) {
+      expect(practiceStoreDir(flag, own), JSON.stringify(flag)).toBe(own);
+    }
+    expect(practiceStoreDir("=/tmp/x", own)).toBe(path.resolve("/tmp/x"));
+    expect(practiceStoreDir("~/learn", own)).toBe(path.join(os.homedir(), "learn"));
+  });
+
+  it("allows the tutorial's own store, a new or empty directory, or a marked one", () => {
+    expect(checkPracticeStore(own, own)).toEqual({ ok: true });
+    const base = tmp();
+    expect(checkPracticeStore(path.join(base, "new"), own)).toEqual({ ok: true });
+    expect(checkPracticeStore(base, own)).toEqual({ ok: true });
+    fs.writeFileSync(path.join(base, "ditto.db"), "x");
+    markPracticeStore(base);
+    expect(fs.existsSync(path.join(base, PRACTICE_MARKER))).toBe(true);
+    expect(checkPracticeStore(base, own)).toEqual({ ok: true });
+  });
+
+  it("refuses an existing store the lessons didn't create", () => {
+    const real = tmp();
+    fs.writeFileSync(path.join(real, "ditto.db"), "user data");
+    const r = checkPracticeStore(real, own);
+    expect(r.ok).toBe(false);
+    expect(r.ok ? "" : r.reason).toContain("isn't a lesson practice store");
+    // A file where a directory is expected can't be read as a store.
+    const file = path.join(real, "ditto.db");
+    expect(checkPracticeStore(file, own).ok).toBe(false);
+    // Marking a path that can't be written is best effort and doesn't throw.
+    expect(() => markPracticeStore(path.join(file, "nested"))).not.toThrow();
+  });
+});
diff --git a/tests/unit/tutorial-schema.test.ts b/tests/unit/tutorial-schema.test.ts
new file mode 100644
index 0000000..78f0c31
--- /dev/null
+++ b/tests/unit/tutorial-schema.test.ts
@@ -0,0 +1,174 @@
+import { stripVTControlCharacters as strip } from "node:util";
+import { describe, expect, it } from "vitest";
+import type { QueryExecutor } from "../../src/ditto/session.js";
+import { LESSONS, SEED_PRODUCTS, SEED_SUPPLIERS } from "../../src/tutorial/lessons.js";
+import { LessonRunner } from "../../src/tutorial/runner.js";
+import {
+  caseMismatch,
+  collectionsIn,
+  inferSchema,
+  schemaLines,
+} from "../../src/tutorial/schema.js";
+
+describe("inferSchema", () => {
+  it("lists every field path with types, counts, and a sample value", () => {
+    const fields = inferSchema(SEED_PRODUCTS as never);
+    const by = Object.fromEntries(fields.map((f) => [f.path, f]));
+    expect(fields[0]!.path).toBe("_id");
+    expect(by.name).toMatchObject({ types: ["string"], count: 6, example: "Coffee beans" });
+    expect(by.details).toMatchObject({ types: ["object"], count: 3 });
+    expect(by["details.origin"]).toMatchObject({ count: 3, example: "Colombia" });
+    expect(by["details.roast"]?.count).toBe(2);
+    expect(by.discount).toMatchObject({ types: ["number", "null"], count: 2 });
+    expect(by.tags).toMatchObject({ types: ["array"], count: 6 });
+    expect(by.tags?.example).toEqual(["organic", "fair-trade"]);
+  });
+
+  it("describes arrays of objects with [] paths", () => {
+    const fields = inferSchema([
+      { _id: "o1", lines: [{ sku: "p1", qty: 2 }] },
+      { _id: "o2", lines: [] },
+      { _id: "o3", flag: true, nothing: null },
+    ]);
+    const by = Object.fromEntries(fields.map((f) => [f.path, f]));
+    expect(by.lines).toMatchObject({ types: ["array"], count: 2 });
+    expect(by.lines?.example).toBeUndefined(); // objects, not scalars
+    expect(by["lines[].sku"]).toMatchObject({ types: ["string"], count: 1, example: "p1" });
+    expect(by["lines[].qty"]?.example).toBe(2);
+    expect(by.flag?.example).toBe(true);
+    expect(by.nothing).toMatchObject({ types: ["null"] });
+    expect(by.nothing?.example).toBeUndefined();
+    expect(inferSchema([])).toEqual([]);
+  });
+});
+
+describe("collectionsIn", () => {
+  it("finds the collections a statement uses", () => {
+    expect(collectionsIn("SELECT * FROM products")).toEqual(["products"]);
+    expect(
+      collectionsIn(
+        "SELECT p.name FROM products AS p LEFT JOIN suppliers AS s ON p.supplier_id = s._id",
+      ),
+    ).toEqual(["products", "suppliers"]);
+    expect(collectionsIn("INSERT INTO products VALUES ({'_id': 'x'})")).toEqual(["products"]);
+    expect(collectionsIn("UPDATE products SET stock = 1")).toEqual(["products"]);
+    expect(collectionsIn("EVICT FROM products USE IDS 'p7'")).toEqual(["products"]);
+    expect(collectionsIn("CREATE INDEX IF NOT EXISTS i ON products (category)")).toEqual([
+      "products",
+    ]);
+    expect(collectionsIn("SELECT key FROM system:system_info")).toEqual(["system:system_info"]);
+    // Words inside strings don't count.
+    expect(collectionsIn("SELECT * FROM products WHERE name = 'from orders'")).toEqual([
+      "products",
+    ]);
+  });
+
+  it("every lesson names at least one collection, and the join lessons name two", () => {
+    for (const l of LESSONS) expect(collectionsIn(l.answer).length, l.title).toBeGreaterThan(0);
+    const join = LESSONS.find((l) => l.title === "Joining collections")!;
+    expect(collectionsIn(join.answer)).toEqual(["products", "suppliers"]);
+  });
+});
+
+describe("schemaLines", () => {
+  const schema = (docs: Record<string, unknown>[], more = false) => ({
+    collection: "suppliers",
+    documents: docs.length,
+    more,
+    fields: inferSchema(docs),
+  });
+
+  it("shows the collection, its fields, partial counts, and examples that fit", () => {
+    const lines = schemaLines(
+      [schema(SEED_SUPPLIERS as never), schema([{ _id: "a" }, { _id: "b", x: 1 }], true)],
+      60,
+    ).map(strip);
+    expect(lines[0]).toBe("suppliers  3 documents");
+    expect(lines).toContainEqual(expect.stringMatching(/^ {2}name\s+string\s+'Andes Roasters'$/));
+    expect(lines).toContain("");
+    expect(lines).toContain("suppliers  2+ documents");
+    expect(lines).toContainEqual(expect.stringMatching(/^ {2}x\s+number · 1 of 2\s+1$/));
+  });
+
+  it("drops examples when there's no room, and handles an empty collection", () => {
+    const narrow = schemaLines([schema(SEED_SUPPLIERS as never)], 22).map(strip);
+    expect(narrow.some((l) => l.includes("'Andes"))).toBe(false);
+    const empty = schemaLines([schema([])], 40).map(strip);
+    expect(empty).toEqual(["suppliers  0 documents", "  (no documents)"]);
+    const one = schemaLines([schema([{ _id: "a" }])], 40).map(strip);
+    expect(one[0]).toBe("suppliers  1 document");
+  });
+});
+
+describe("caseMismatch", () => {
+  const known = { collections: ["products", "suppliers"], fields: ["name", "category"] };
+
+  it("points out names that differ only in case", () => {
+    expect(caseMismatch("SELECT * FROM Products", known)).toContain(
+      "`Products` is a different (empty) collection from `products`",
+    );
+    expect(caseMismatch("SELECT Name FROM products", known)).toContain(
+      "`Name` isn't the same field as `name`",
+    );
+  });
+
+  it("is quiet when names match, and ignores text in strings", () => {
+    expect(caseMismatch("select name from products where category = 'tea'", known)).toBeNull();
+    expect(caseMismatch("SELECT * FROM products WHERE name = 'Name'", known)).toBeNull();
+    expect(caseMismatch("SELECT * FROM orders", known)).toBeNull();
+  });
+});
+
+describe("LessonRunner data view", () => {
+  function runner(at: string) {
+    const executed: string[] = [];
+    const printed: string[] = [];
+    const session: QueryExecutor = {
+      execute: async (s: string) => {
+        executed.push(s);
+        const rows = /FROM products/.test(s)
+          ? SEED_PRODUCTS
+          : /FROM suppliers/.test(s)
+            ? SEED_SUPPLIERS
+            : [];
+        return { items: rows.map((value) => ({ value })) } as never;
+      },
+    };
+    const r = new LessonRunner(session, {
+      io: { print: (t) => printed.push(t), width: () => 80 },
+      progress: { lesson: LESSONS.findIndex((l) => l.title === at), completed: [] },
+    });
+    return { r, executed, printed };
+  }
+
+  it("lists the lesson's collections and reads their live schema", async () => {
+    const { r, executed, printed } = runner("Joining collections");
+    expect(r.collections()).toEqual(["products", "suppliers"]);
+    expect(strip(r.dataTip("Ctrl+T"))).toBe(
+      "Collections: products, suppliers · Ctrl+T shows their fields",
+    );
+    const schemas = await r.schema();
+    expect(schemas.map((s) => [s.collection, s.documents, s.more])).toEqual([
+      ["products", 6, false],
+      ["suppliers", 3, false],
+    ]);
+    expect(executed).toContain("SELECT * FROM products LIMIT 201");
+    await r.printSchema();
+    const out = strip(printed.join("\n"));
+    expect(out).toContain("supplier_id");
+    expect(out).toContain("Names are case-sensitive");
+  });
+
+  it("one collection reads 'its fields'; the plain card shows the .schema tip", async () => {
+    const { r, printed } = runner("Documents and collections");
+    expect(strip(r.dataTip(".schema"))).toBe("Collection: products · .schema shows its fields");
+    await r.show();
+    expect(strip(printed.join("\n"))).toContain(".schema shows its fields");
+  });
+
+  it("a wrong-case collection name gets a case-sensitivity explanation", async () => {
+    const { r, printed } = runner("Documents and collections");
+    expect(await r.submit("SELECT * FROM Products")).toBe(false);
+    expect(strip(printed.join("\n"))).toContain("Collection names are case-sensitive");
+  });
+});
diff --git a/tests/unit/tutorial-ui.test.ts b/tests/unit/tutorial-ui.test.ts
new file mode 100644
index 0000000..d00bf2b
--- /dev/null
+++ b/tests/unit/tutorial-ui.test.ts
@@ -0,0 +1,692 @@
+import { EventEmitter } from "node:events";
+import { stripVTControlCharacters } from "node:util";
+import { type Instance, render } from "ink";
+import { createElement, type ReactElement } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { QueryExecutor } from "../../src/ditto/session.js";
+import { LESSONS, SEED_PRODUCTS } from "../../src/tutorial/lessons.js";
+import { LessonRunner } from "../../src/tutorial/runner.js";
+import { LessonScreen, screenIO } from "../../src/tutorial/ui/app.js";
+import { TutorialProvider, useTutorial } from "../../src/tutorial/ui/context.js";
+import {
+  type EditorState,
+  edit,
+  emptyEditor,
+  isEditorEmpty,
+  submit,
+  viewport,
+} from "../../src/tutorial/ui/editor.js";
+import { drawerWidth, helpLines } from "../../src/tutorial/ui/help.js";
+import {
+  clip,
+  fitCard,
+  listWindow,
+  progressBar,
+  scrollWindow,
+  wrapLines,
+} from "../../src/tutorial/ui/layout.js";
+import { outlineLines, outlineWidth } from "../../src/tutorial/ui/outline.js";
+import { createUiStore } from "../../src/tutorial/ui/store.js";
+
+const strip = (s: string | undefined) => stripVTControlCharacters(s ?? "");
+
+// ─── editor ────────────────────────────────────────────────────────────────
+
+describe("lesson screen editor", () => {
+  const type = (s: EditorState, text: string) => edit(s, { type: "insert", text });
+
+  it("edits a line: insert, cursor moves, delete, kill", () => {
+    let s = type(emptyEditor(), "SELEC FROM");
+    s = edit(s, { type: "home" });
+    s = edit(s, { type: "right" });
+    for (let i = 0; i < 4; i++) s = edit(s, { type: "right" });
+    s = type(s, "T *");
+    expect(s.line).toBe("SELECT * FROM");
+    s = edit(s, { type: "end" });
+    s = edit(s, { type: "backspace" });
+    expect(s.line).toBe("SELECT * FRO");
+    s = edit(s, { type: "home" });
+    s = edit(s, { type: "delete" });
+    expect(s.line).toBe("ELECT * FRO");
+    s = edit(s, { type: "left" }); // clamps at 0
+    expect(s.cursor).toBe(0);
+    s = edit(s, { type: "end" });
+    s = edit(s, { type: "killWord" });
+    expect(s.line).toBe("ELECT * ");
+    s = edit(s, { type: "killLine" });
+    expect(s.line).toBe("");
+    expect(isEditorEmpty(s)).toBe(true);
+    expect(edit(s, { type: "backspace" })).toBe(s); // nothing to join
+  });
+
+  it("viewport scrolls long lines so the cursor stays in view", () => {
+    expect(viewport("short", 2, 20)).toEqual({ text: "short", cursorCol: 2 });
+    const line = "abcdefghijklmnopqrstuvwxyz";
+    const end = viewport(line, line.length, 10);
+    expect(end.text.startsWith("…")).toBe(true);
+    // 8 characters, then the cursor in the 9th column.
+    expect(end.text.length).toBe(8);
+    expect(end.cursorCol).toBe(8);
+    const start = viewport(line, 0, 10);
+    expect(start).toEqual({ text: "abcdefgh…", cursorCol: 0 });
+    const mid = viewport(line, 13, 10);
+    expect(mid.text.startsWith("…") && mid.text.endsWith("…")).toBe(true);
+    expect(mid.text[mid.cursorCol]).toBe(line[13]);
+  });
+
+  it("pasted newlines and tabs become spaces", () => {
+    expect(type(emptyEditor(), "SELECT *\nFROM\tproducts").line).toBe("SELECT * FROM  products");
+    expect(type(emptyEditor(), "SELECT 1\x04\x1b").line).toBe("SELECT 1");
+  });
+
+  it("Enter: statement, continuation, command, or nothing", () => {
+    expect(submit(type(emptyEditor(), "   ")).kind).toBe("none");
+
+    const r = submit(type(emptyEditor(), "SELECT * FROM products"));
+    expect(r).toMatchObject({ kind: "statement", text: "SELECT * FROM products" });
+    expect(r.state.history).toEqual(["SELECT * FROM products"]);
+
+    const cont = submit(type(emptyEditor(), "SELECT name,"));
+    expect(cont.kind).toBe("continue");
+    expect(cont.state.done).toEqual(["SELECT name,"]);
+    // Backspace at the start of a continuation line joins it back.
+    const joined = edit(cont.state, { type: "backspace" });
+    expect(joined.done).toEqual([]);
+    expect(joined.line).toBe("SELECT name,");
+    const done = submit(type(cont.state, "price FROM products"));
+    expect(done).toMatchObject({ kind: "statement", text: "SELECT name,\nprice FROM products" });
+    expect(done.state.history).toEqual(["SELECT name, price FROM products"]);
+
+    expect(submit(type(emptyEditor(), " .goto  5 "))).toMatchObject({
+      kind: "command",
+      name: "goto",
+      arg: "5",
+    });
+    // A leading dot on a continuation line is DQL, not a command.
+    expect(submit(type(cont.state, ".x")).kind).toBe("statement");
+  });
+
+  it("history: ↑ recalls, ↓ returns to the draft, duplicates collapse", () => {
+    let s = emptyEditor(["SELECT 1", "SELECT 2"]);
+    expect(edit(s, { type: "historyNext" })).toBe(s);
+    s = type(s, "draft");
+    s = edit(s, { type: "historyPrev" });
+    expect(s.line).toBe("SELECT 2");
+    s = edit(s, { type: "historyPrev" });
+    s = edit(s, { type: "historyPrev" }); // clamps at the oldest
+    expect(s.line).toBe("SELECT 1");
+    s = edit(s, { type: "historyNext" });
+    expect(s.line).toBe("SELECT 2");
+    s = edit(s, { type: "historyNext" });
+    expect(s.line).toBe("draft");
+    expect(edit(emptyEditor(), { type: "historyPrev" }).line).toBe("");
+    expect(submit(type(emptyEditor(["SELECT 1"]), "SELECT 1")).state.history).toEqual(["SELECT 1"]);
+    expect(edit(type(emptyEditor(["x"]), "y"), { type: "clear" })).toEqual(emptyEditor(["x"]));
+  });
+});
+
+// ─── layout ────────────────────────────────────────────────────────────────
+
+describe("lesson card unwrapping", () => {
+  it("joins hard-wrapped lines but keeps blank lines and indented examples", () => {
+    const lesson = { ...LESSONS[0]!, concept: "one\ntwo\n\n  { x: 1 }\n\nthree\nfour" };
+    const store = createUiStore();
+    const runner = new LessonRunner(
+      { execute: async () => ({ items: [] }) as never },
+      {
+        lessons: [lesson],
+        io: screenIO(store, () => runner),
+      },
+    );
+    expect(strip(runner.cardBody({ unwrap: true })[0])).toBe("one two\n\n  { x: 1 }\n\nthree four");
+  });
+});
+
+describe("lesson screen layout helpers", () => {
+  it("wrapLines word-wraps and keeps indentation on wrapped rows", () => {
+    expect(wrapLines(["one two three four"], 9)).toEqual(["one two", "three", "four"]);
+    expect(wrapLines(["  alpha beta gamma"], 10)).toEqual(["  alpha", "  beta", "  gamma"]);
+    expect(wrapLines(["a\nb"], 10)).toEqual(["a", "b"]);
+    // Drawn lines (tables) are never wrapped; the panel cuts them off.
+    expect(wrapLines(["│ a long table row │"], 5)).toEqual(["│ a long table row │"]);
+  });
+
+  it("fitCard keeps the task when the card is too tall", () => {
+    const body = ["c1", "c2", "c3", "c4"];
+    expect(fitCard(body, ["T"], 9, "…")).toEqual([...body, "T"]);
+    expect(fitCard(body, ["T"], 4, "…")).toEqual(["c1", "c2", "…", "T"]);
+    expect(fitCard(body, ["T1", "T2"], 2, "…")).toEqual(["T1", "…"]);
+  });
+
+  it("scrollWindow shows the bottom by default and clamps the offset", () => {
+    const lines = ["1", "2", "3", "4", "5"];
+    expect(scrollWindow(lines, 2, 0)).toEqual({
+      visible: ["4", "5"],
+      offset: 0,
+      above: 3,
+      below: 0,
+    });
+    expect(scrollWindow(lines, 2, 1).visible).toEqual(["3", "4"]);
+    expect(scrollWindow(lines, 2, 99)).toMatchObject({ visible: ["1", "2"], offset: 3, below: 3 });
+    expect(scrollWindow(lines, 10, 5)).toMatchObject({ visible: lines, above: 0, below: 0 });
+  });
+
+  it("listWindow keeps the selection in view", () => {
+    expect(listWindow(5, 10, 3)).toEqual([0, 5]);
+    expect(listWindow(30, 10, 0)).toEqual([0, 10]);
+    expect(listWindow(30, 10, 15)).toEqual([10, 20]);
+    expect(listWindow(30, 10, 29)).toEqual([20, 30]);
+  });
+
+  it("progressBar and clip", () => {
+    expect(strip(progressBar(1, 2, 4))).toBe("██░░ 1/2");
+    expect(strip(progressBar(0, 0, 4))).toBe("░░░░ 0/0");
+    expect(clip("short", 10)).toBe("short");
+    expect(clip("\x1b[1mlonger text\x1b[22m", 6)).toBe("longe…");
+  });
+});
+
+describe("help drawer and outline content", () => {
+  it("helpLines has the keys, commands, and how-it-works sections, wrapped to width", () => {
+    const lines = helpLines(30).map(strip);
+    expect(lines).toContain("Keys");
+    expect(lines).toContain("Commands");
+    expect(lines).toContain("How it works");
+    expect(lines.some((l) => l.startsWith("Enter"))).toBe(true);
+    for (const l of lines) expect(l.length).toBeLessThanOrEqual(30);
+    expect(drawerWidth(80)).toBe(30);
+    expect(drawerWidth(200)).toBe(40);
+  });
+
+  it("outlineLines expands the current level and windows long lists", () => {
+    const input = { lessons: LESSONS, current: 12, isCompleted: (i: number) => i < 3 };
+    const all = outlineLines(input, 26, 40).map(strip);
+    expect(all[0]).toMatch(/^Lessons\s+3\/27$/);
+    expect(all).toContainEqual(expect.stringMatching(/^▸ Beginner\s+3\/8$/));
+    expect(all).toContainEqual(expect.stringMatching(/^▾ Intermediate\s+0\/10$/));
+    expect(all.some((l) => l.includes("▸ 13"))).toBe(true);
+    // Long titles wrap under themselves instead of being cut off.
+    const advanced = outlineLines({ ...input, current: 20 }, 26, 40).map(strip);
+    const at = advanced.findIndex((l) => l.includes("21 Conditions"));
+    expect(advanced[at + 1]).toMatch(/^ {7}\S/);
+    expect(advanced.join("\n")).toContain("SATISFIES");
+    // Too short for all ten intermediate lessons: the list scrolls with "…".
+    const short = outlineLines(input, 26, 9).map(strip);
+    expect(short.filter((l) => l.trim() === "…").length).toBeGreaterThan(0);
+    expect(short.some((l) => l.includes("▸ 13"))).toBe(true);
+    expect(outlineWidth(80)).toBe(28);
+    expect(outlineWidth(200)).toBe(36);
+  });
+});
+
+// ─── store + provider ──────────────────────────────────────────────────────
+
+describe("lesson screen store and provider", () => {
+  it("store: capped log, total count, lesson version, width, unsubscribe", () => {
+    const store = createUiStore({ maxEntries: 2, width: 50 });
+    let calls = 0;
+    const off = store.subscribe(() => calls++);
+    store.print("a");
+    store.print("b");
+    store.print("c");
+    store.lessonChanged();
+    store.setStatus("✓");
+    store.setStatus("✓"); // unchanged: no emit
+    expect(store.snapshot()).toEqual({
+      log: ["b", "c"],
+      lessonVersion: 1,
+      printed: 3,
+      status: "✓",
+    });
+    expect(calls).toBe(5);
+    store.clear();
+    store.clear(); // already empty: no emit
+    expect(store.snapshot().log).toEqual([]);
+    expect(calls).toBe(6);
+    off();
+    store.print("d");
+    expect(calls).toBe(6);
+    expect(store.width()).toBe(50);
+    store.setWidth(70);
+    expect(store.width()).toBe(70);
+  });
+
+  it("track/idle: idle waits for every tracked piece of work, failures included", async () => {
+    const store = createUiStore();
+    await store.idle(); // nothing tracked
+    let done = 0;
+    let release: () => void = () => {};
+    store.track(
+      new Promise<void>((r) => {
+        release = r;
+      }).then(() => done++),
+    );
+    store.track(Promise.reject(new Error("ignored")));
+    const idle = store.idle().then(() => done * 10);
+    await new Promise((r) => setTimeout(r, 5));
+    expect(done).toBe(0);
+    release();
+    expect(await idle).toBe(10);
+  });
+
+  it("useTutorial outside the provider throws", async () => {
+    function Orphan() {
+      useTutorial();
+      return null;
+    }
+    const { app } = mount(createElement(Orphan));
+    await expect(app.waitUntilExit()).rejects.toThrow("inside <TutorialProvider>");
+  });
+});
+
+// ─── the screen ────────────────────────────────────────────────────────────
+
+const tick = (ms = 30) => new Promise((r) => setTimeout(r, ms));
+
+/** A fake 100×30 TTY: Ink renders frames into `lastFrame`, keys go in via `stdin.write`. */
+class FakeStdout extends EventEmitter {
+  columns = 100;
+  rows = 30;
+  isTTY = true;
+  frame = "";
+  write = (s: string, cb?: () => void) => {
+    // Cursor show/hide/move writes aren't frames.
+    if (strip(s).trim() !== "" || !s.includes("\x1b")) this.frame = s;
+    cb?.();
+    return true;
+  };
+}
+class FakeStdin extends EventEmitter {
+  isTTY = true;
+  private data: string | null = null;
+  write(data: string) {
+    this.data = data;
+    this.emit("readable");
+    this.emit("data", data);
+  }
+  read = () => {
+    const d = this.data;
+    this.data = null;
+    return d;
+  };
+  setEncoding() {}
+  setRawMode() {}
+  resume() {}
+  pause() {}
+  ref() {}
+  unref() {}
+}
+const mounted: Instance[] = [];
+function mount(tree: ReactElement, rows = 30, columns = 100) {
+  const stdout = new FakeStdout();
+  stdout.rows = rows;
+  stdout.columns = columns;
+  const stdin = new FakeStdin();
+  const app = render(tree, {
+    stdout: stdout as never,
+    stderr: new FakeStdout() as never,
+    stdin: stdin as never,
+    debug: true,
+    exitOnCtrlC: false,
+    patchConsole: false,
+  });
+  mounted.push(app);
+  return { app, stdin, lastFrame: () => stdout.frame };
+}
+
+/** The screen over a fake store: SELECTs on products return the seed rows. */
+async function mountScreen(rows = 30, columns = 100) {
+  const executed: string[] = [];
+  const session: QueryExecutor = {
+    execute: async (s: string) => {
+      executed.push(s);
+      if (/^SELEKT/i.test(s)) throw new Error("syntax error near SELEKT");
+      const rows = /FROM products/i.test(s) && /^SELECT/i.test(s) ? SEED_PRODUCTS : [];
+      return { items: rows.map((value) => ({ value })) } as never;
+    },
+  };
+  const store = createUiStore({ width: 96 });
+  const runner: LessonRunner = new LessonRunner(session, { io: screenIO(store, () => runner) });
+  await runner.start();
+  const { app, stdin, lastFrame } = mount(
+    createElement(TutorialProvider, { runner, store }, createElement(LessonScreen)),
+    rows,
+    columns,
+  );
+  const screen = () => strip(lastFrame());
+  const press = async (keys: string, ms?: number) => {
+    stdin.write(keys);
+    await tick(ms);
+  };
+  await tick();
+  return { app, runner, store, screen, press, executed };
+}
+
+describe("LessonScreen", () => {
+  afterEach(() => {
+    for (const app of mounted.splice(0)) app.unmount();
+  });
+
+  it("draws the header, the lesson card, the output panel, and the key bar", async () => {
+    const { screen } = await mountScreen();
+    const s = screen();
+    expect(s).toContain("Learn DQL");
+    expect(s).toContain(`Lesson 1/${LESSONS.length}`);
+    expect(s).toContain("Beginner 1/8");
+    expect(s).toContain("Task: Show every document in the products collection.");
+    expect(s).toContain("── Lesson 1: Documents and collections ──");
+    expect(s).toContain("learn>");
+    expect(s).toContain("Enter run · Tab hint");
+  });
+
+  it("Enter runs the statement, checks it, and moves to the next lesson", async () => {
+    const { screen, press, runner } = await mountScreen();
+    for (const ch of "SELECT * FROM products") await press(ch, 1);
+    await press("\r", 80);
+    const s = screen();
+    expect(s).toContain("learn> SELECT * FROM products");
+    // The verdict stays in view on the status line, above the prompt.
+    expect(s).toMatch(/✓ Correct!.*\n.*learn>/);
+    expect(runner.current).toBe(1);
+    expect(s).toContain("Lesson 2/");
+  });
+
+  it("text and Enter in one chunk still run", async () => {
+    const { screen, press } = await mountScreen();
+    await press("SELEKT 1\r", 80);
+    expect(screen()).toMatch(/Query error.*\n(.*\n)?learn>/);
+    // The next statement clears the old verdict.
+    await press("SELECT 1\r", 80);
+    expect(/\n(.*)\nlearn>/.exec(screen())?.[1]).not.toContain("Query error");
+  });
+
+  it("an unfinished statement continues on a | line", async () => {
+    const { screen, press, runner } = await mountScreen();
+    await press("SELECT *,");
+    await press("\r");
+    expect(screen()).toMatch(/learn> SELECT \*,\n\s+\|/);
+    await press("\x7f"); // backspace joins the lines again
+    expect(screen()).toContain("learn> SELECT *,");
+    await press("\x1b"); // Esc clears
+    await press("SELECT *");
+    await press("\r");
+    await press(" FROM products");
+    await press("\r", 80);
+    expect(runner.current).toBe(1);
+  });
+
+  it("Tab hints, ? shows the guide, dot-commands work, unknown ones are reported", async () => {
+    const { screen, press, runner } = await mountScreen();
+    await press("\t");
+    expect(screen()).toContain("Hint:");
+    await press("?", 120);
+    expect(screen()).toContain("Help");
+    await press("?", 120); // toggles closed
+    await press(".answer\r");
+    expect(screen()).toContain("One answer:");
+    await press(".bogus\r");
+    expect(screen()).toContain("Unknown command .bogus");
+    await press(".goto 3\r", 60);
+    expect(runner.current).toBe(2);
+    await press(".back\r", 60);
+    await press(".next\r", 60);
+    await press(".level advanced\r", 60);
+    expect(runner.info().level).toBe("advanced");
+    await press(".reset\r", 60);
+    expect(screen()).toContain("Practice data restored.");
+    await press(".help\r");
+    await press(".break\r");
+    expect(screen()).toContain("learn>");
+  });
+
+  it("Ctrl+O toggles the whole lesson in a short window", async () => {
+    const { screen, press } = await mountScreen(22);
+    await press(".goto 23\r", 60); // a long lesson with a 5.2 note
+    expect(screen()).toContain("^O shows the whole lesson");
+    expect(screen()).toContain("Task:");
+    await press("\x0f");
+    expect(screen()).not.toContain("^O shows the whole lesson");
+    expect(screen()).toContain("Task:");
+    await press("\x0f");
+    expect(screen()).toContain("^O shows the whole lesson");
+  });
+
+  it("each action starts with an empty results panel", async () => {
+    const { screen, press, store } = await mountScreen();
+    await press(".answer\r");
+    expect(screen()).toContain("One answer:");
+    await press("SELECT name FROM products\r", 80);
+    let s = screen();
+    expect(s).not.toContain("One answer:");
+    expect(s).toContain("learn> SELECT name FROM products");
+    expect(s).toMatch(/✓ Correct!/); // lesson 1 only checks the names
+    // A hint replaces the results but keeps the verdict on the status line.
+    await press("\t");
+    s = screen();
+    expect(s).not.toContain("learn> SELECT name FROM products");
+    expect(s).toContain("Hint:");
+    expect(store.snapshot().status).toContain("Correct");
+    // Moving to another lesson clears both.
+    await press("\x0e", 60);
+    expect(screen()).not.toContain("Hint:");
+    expect(store.snapshot().status).toBeNull();
+    expect(store.snapshot().log).toHaveLength(1); // just the lesson divider
+  });
+
+  it("quitting while a statement runs: the work is tracked so the caller can wait", async () => {
+    const { press, store, app, runner } = await mountScreen();
+    await press("SELECT * FROM products\r", 0);
+    await press("\x04", 0); // Ctrl+D right away
+    await app.waitUntilExit();
+    await store.idle();
+    expect(runner.current).toBe(1); // the check and lesson change completed
+  });
+
+  it("long input scrolls sideways; many continuation lines collapse", async () => {
+    const { screen, press } = await mountScreen(24, 70);
+    await press(`SELECT ${"name, ".repeat(20)}price FROM products`);
+    let s = screen();
+    expect(s).toMatch(/learn> …[^\n]*price FROM products/);
+    await press("\x1b"); // clear
+    for (let i = 0; i < 8; i++) {
+      await press(`f${i},`);
+      await press("\r");
+    }
+    s = screen();
+    expect(s).toMatch(/… \d+ earlier lines/);
+    expect(s).toContain("f7,");
+    expect(s).not.toContain("f0,");
+    expect(s).toContain("Task:"); // the lesson still has room
+  });
+
+  it("a chunk with several lines keeps all of them", async () => {
+    const { screen, press, runner } = await mountScreen();
+    await press("SELECT *\rFROM products\rSELECT 1", 80);
+    expect(runner.current).toBe(1); // "SELECT *" + "FROM products" ran as one statement
+    expect(screen()).toContain("learn> SELECT 1"); // the rest waits in the editor
+  });
+
+  it("PgUp stops at the top, so PgDn responds straight away", async () => {
+    const { screen, press } = await mountScreen(24);
+    await press("SELECT * FROM products\r", 80);
+    for (let i = 0; i < 6; i++) await press("\x1b[6~", 5); // to the bottom
+    for (let i = 0; i < 10; i++) await press("\x1b[5~", 5); // far past the top
+    const atTop = screen();
+    await press("\x1b[6~");
+    expect(screen()).not.toBe(atTop);
+  });
+
+  it("a window shrunk below the minimum shows a placeholder", async () => {
+    const { screen } = await mountScreen(12, 50);
+    const s = screen();
+    expect(s).toContain("the window is too small");
+    expect(s).toContain("now 50×12");
+    expect(s).not.toContain("Task:");
+  });
+
+  it("Ctrl+N / Ctrl+P move between lessons", async () => {
+    const { press, runner } = await mountScreen();
+    await press("\x0e", 60);
+    expect(runner.current).toBe(1);
+    await press("\x10", 60);
+    expect(runner.current).toBe(0);
+  });
+
+  it("Ctrl+L opens the lesson picker; arrows and Enter jump to a lesson", async () => {
+    const { screen, press, runner } = await mountScreen();
+    await press("\x0c");
+    let s = screen();
+    expect(s).toContain("Intermediate");
+    expect(s).toContain("↑/↓ choose · Enter open · Esc close");
+    await press("\x1b[B");
+    await press("\x1b[B");
+    await press("\x1b[A");
+    await press("\r", 60);
+    expect(runner.current).toBe(1);
+    await press(".lessons\r");
+    await press("\x1b[F"); // End
+    await press("\x1b[H"); // Home
+    await press("\x1b[6~"); // PgDn
+    await press("\x1b[5~"); // PgUp
+    await press("\x1b", 60); // Esc closes without moving
+    s = screen();
+    expect(s).toContain("learn>");
+    expect(runner.current).toBe(1);
+  });
+
+  it("line editing keys and history", async () => {
+    const { screen, press } = await mountScreen();
+    await press("SELECT 1");
+    await press("\r", 60);
+    await press("\x1b[A"); // ↑ recalls
+    expect(screen()).toContain("learn> SELECT 1");
+    await press("\x1b[B"); // ↓ back to empty
+    await press("abc");
+    await press("\x1b[D"); // ←
+    await press("\x1b[C"); // →
+    await press("\x01"); // Ctrl+A
+    await press("\x05"); // Ctrl+E
+    await press("\x17"); // Ctrl+W
+    expect(screen()).not.toContain("learn> abc");
+    await press("xyz");
+    await press("\x1b[H"); // Home
+    await press("\x1b[3~"); // Delete
+    await press("\x04"); // Ctrl+D with text = delete
+    await press("\x1b[F"); // End
+    expect(screen()).toContain("learn> z");
+    await press("\x03"); // Ctrl+C with text clears; empty Ctrl+C would quit
+    expect(screen()).toMatch(/learn>\s*\n/);
+    await press("abc");
+    await press("\x15"); // Ctrl+U
+    expect(screen()).toMatch(/learn>\s*\n/);
+  });
+
+  it("PgUp / PgDn scroll long output, which opens at its top", async () => {
+    const { screen, press } = await mountScreen(24);
+    await press("SELECT * FROM products\r", 80);
+    expect(screen()).toContain("learn> SELECT * FROM products");
+    expect(screen()).toMatch(/↓\d+ PgUp\/Dn/);
+    for (let i = 0; i < 6; i++) await press("\x1b[6~", 5);
+    expect(screen()).not.toMatch(/↓\d+/);
+    expect(screen()).toContain("6 rows");
+    await press("\x1b[5~");
+    expect(screen()).toMatch(/↓\d+/);
+  });
+
+  it("? slides the help drawer in on the right; PgUp/PgDn scroll it; Esc closes", async () => {
+    const { screen, press, store } = await mountScreen(24);
+    await press("?", 150);
+    let s = screen();
+    expect(s).toMatch(/│ Task:.*│\s*│ \S/); // lesson stays on the left, drawer beside it
+    expect(s).toContain(" Help ");
+    expect(s).toContain("PgDn more");
+    expect(s).toContain("? or Esc close help");
+    expect(store.snapshot().log.join("")).not.toContain("Keys"); // not in the results
+    for (let i = 0; i < 8; i++) await press("\x1b[6~", 5);
+    s = screen();
+    expect(s).toContain("Progress is saved as you go.");
+    expect(s).toContain("Esc closes");
+    await press("\x1b[5~");
+    // Typing still goes to the prompt while the drawer is open.
+    await press("SEL");
+    expect(screen()).toContain("learn> SEL");
+    await press("\x1b", 150); // Esc closes the drawer first…
+    expect(screen()).not.toContain(" Help ");
+    expect(screen()).toContain("learn> SEL");
+    await press("\x1b"); // …then clears the input
+    expect(screen()).not.toContain("learn> SEL");
+    await press(".help\r", 150);
+    expect(screen()).toContain(" Help ");
+    await press("\x0c"); // the lesson list closes it
+    await press("\x1b", 150);
+    expect(screen()).not.toContain(" Help ");
+  });
+
+  it("Ctrl+T opens the data view with the lesson's collections; .schema too", async () => {
+    const { screen, press } = await mountScreen(30, 110);
+    expect(screen()).toContain("Collection: products · Ctrl+T shows its fields");
+    expect(screen()).toContain("^T data");
+    await press("\x14", 200);
+    const s = screen();
+    expect(s).toContain(" Data ");
+    expect(s).toMatch(/products\s+6 documents/);
+    expect(s).toContain("details.origin");
+    expect(s).toContain("^T or Esc close data");
+    await press("?", 150); // switches the drawer to help
+    expect(screen()).toContain(" Help ");
+    expect(screen()).not.toContain(" Data ");
+    await press("\x1b", 150);
+    expect(screen()).not.toContain(" Help ");
+    await press(".schema\r", 200);
+    expect(screen()).toContain(" Data ");
+    await press("\x14", 150); // Ctrl+T again closes it
+    expect(screen()).not.toContain(" Data ");
+  });
+
+  it("the data view shows an error if the collections can't be read", async () => {
+    const { screen, press, runner } = await mountScreen(30, 110);
+    runner.schema = async () => {
+      throw new Error("store closed");
+    };
+    await press("\x14", 200);
+    expect(screen()).toContain("Couldn't read the data: store closed");
+  });
+
+  it("the outline sidebar lists the current level's lessons; Ctrl+B toggles it", async () => {
+    const { screen, press } = await mountScreen(30, 110);
+    let s = screen();
+    expect(s).toMatch(/Lessons\s+0\/27/);
+    expect(s).toMatch(/▾ Beginner\s+0\/8/);
+    expect(s).toContain("▸  1 Documents");
+    expect(s).toMatch(/▸ Advanced\s+0\/9/);
+    await press("SELECT * FROM products\r", 80);
+    s = screen();
+    expect(s).toContain("✓  1 Documents");
+    expect(s).toMatch(/Lessons\s+1\/27/);
+    await press(".goto 20\r", 60);
+    expect(screen()).toMatch(/▾ Advanced\s+0\/9/);
+    await press("\x02");
+    expect(screen()).not.toContain("Lessons ");
+    await press("\x02");
+    expect(screen()).toContain("Lessons ");
+  });
+
+  it("in a narrow window the outline hides and help takes the full width", async () => {
+    const { screen, press } = await mountScreen(24, 70);
+    expect(screen()).not.toContain("Lessons ");
+    await press("?", 200);
+    const s = screen();
+    expect(s).toContain(" Help ");
+    expect(s).not.toContain("Task:");
+    await press("\x02"); // Ctrl+B can't fit the outline beside full-width help
+    expect(screen()).not.toContain("Lessons ");
+  });
+
+  it(".exit, Ctrl+C, and Ctrl+D on an empty line quit", async () => {
+    for (const key of [".exit\r", "\x03", "\x04"]) {
+      const { app, press } = await mountScreen();
+      await press(key);
+      await expect(app.waitUntilExit()).resolves.toBeUndefined();
+    }
+  });
+});
diff --git a/tests/unit/tutorial.test.ts b/tests/unit/tutorial.test.ts
new file mode 100644
index 0000000..53f1917
--- /dev/null
+++ b/tests/unit/tutorial.test.ts
@@ -0,0 +1,740 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Recoverable } from "node:repl";
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { registerTutorialCommand, writeTutorial } from "../../src/cli/groups/tutorial.js";
+import type { QueryExecutor } from "../../src/ditto/session.js";
+import {
+  renderTutorial,
+  type TutorialContext,
+  tutorialSections,
+} from "../../src/tutorial/content.js";
+import { looksUnfinished, makeLessonEval, submitAll } from "../../src/tutorial/lesson-eval.js";
+import {
+  firstLessonOf,
+  LESSONS,
+  type Lesson,
+  RESET_STATEMENTS,
+  SEED_PRODUCTS,
+} from "../../src/tutorial/lessons.js";
+import { highlight, LessonRunner, lessonHelp, type Progress } from "../../src/tutorial/runner.js";
+
+const CTX: TutorialContext = {
+  cliVersion: "0.2.0",
+  sdkVersion: "5.2.0",
+  channel: "homebrew",
+  platform: "darwin/arm64",
+  generatedOn: "2026-11-06",
+};
+
+describe("renderTutorial", () => {
+  it("numbers sections and lists them under 'What you will try'", () => {
+    const md = renderTutorial(CTX);
+    const titles = tutorialSections(CTX).map((s) => s.title);
+    titles.forEach((t, i) => {
+      expect(md).toContain(`${i + 1}. ${t}`);
+      expect(md).toContain(`## ${i + 1}. ${t}`);
+    });
+    expect(md).toContain("**Release:** `dittosh` 0.2.0 (Ditto SDK 5.2.0)");
+    expect(md).toContain("## Quick troubleshooting");
+    expect(md).toContain("releases/tag/v0.2.0");
+    expect(md).toContain("_Generated by `dittosh tutorial` on 2026-11-06 for darwin/arm64");
+  });
+
+  it("tailors install and upgrade text to the channel", () => {
+    const brew = renderTutorial(CTX);
+    expect(brew).toContain("installed\nthrough **Homebrew**");
+    expect(brew).toContain("`brew update && brew upgrade getditto/tap/dittosh`");
+
+    const npm = renderTutorial({ ...CTX, channel: "npm" });
+    expect(npm).toContain("`npm install -g @dittolive/cli@latest`");
+
+    const unknown = renderTutorial({ ...CTX, channel: "unknown" });
+    expect(unknown).toContain("could not tell how it was installed");
+    expect(unknown).toContain("through your package manager");
+  });
+
+  it("adds a WSL note on Windows only", () => {
+    expect(renderTutorial({ ...CTX, platform: "win32/x64" })).toContain("WSL or Git Bash");
+    expect(renderTutorial(CTX)).not.toContain("WSL");
+  });
+
+  it("fences every code block and keeps the shell default expansion literal", () => {
+    const md = renderTutorial(CTX);
+    expect(md.match(/```/g)!.length % 2).toBe(0);
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: the shell's literal ${TMPDIR:-/tmp} is what we check for
+    expect(md).toContain('mktemp -d "${TMPDIR:-/tmp}/dittosh-tutorial.XXXXXX"');
+    expect(md).toContain("printf 'Practice directory: %s\\n'");
+  });
+
+  it("covers the 0.2.0 features and the SDK 5.2 DQL changes", () => {
+    const md = renderTutorial(CTX);
+    for (const s of [
+      ".metrics",
+      "inner:",
+      "system:sync_degradations",
+      "system_request_support_bundle()",
+      "SATISFIES",
+      "USE IDS",
+      "6 < price",
+      "(category ASC, price DESC)",
+      "dittosh tutorial --interactive --level intermediate",
+    ]) {
+      expect(md).toContain(s);
+    }
+  });
+});
+
+describe("writeTutorial", () => {
+  let dir: string;
+  let errors: string[];
+  const deps = {
+    detectChannel: () => ({ channel: "npm" as const }),
+    now: () => new Date("2026-11-06T12:00:00Z"),
+    platform: "linux/x64",
+  };
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "tut-unit-"));
+    errors = [];
+    vi.spyOn(console, "error").mockImplementation((m: string) => {
+      errors.push(m);
+    });
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("writes a file and refuses to overwrite without force", () => {
+    const out = path.join(dir, "t.md");
+    expect(writeTutorial({ out }, deps)).toBe(0);
+    expect(fs.readFileSync(out, "utf8")).toContain("linux/x64");
+    expect(writeTutorial({ out }, deps)).toBe(2);
+    expect(errors.join("\n")).toContain("already exists");
+    expect(writeTutorial({ out, force: true }, deps)).toBe(0);
+  });
+
+  it("reports unwritable targets", () => {
+    expect(writeTutorial({ out: path.join(dir, "missing", "t.md") }, deps)).toBe(1);
+    expect(errors.join("\n")).toContain("Cannot write");
+  });
+
+  it("prints to stdout, and rejects --stdout with --out", () => {
+    const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    expect(writeTutorial({ stdout: true }, deps)).toBe(0);
+    expect(String(write.mock.calls[0]?.[0])).toContain("# Ditto CLI");
+    expect(writeTutorial({ stdout: true, out: "x.md" }, deps)).toBe(2);
+  });
+});
+
+// ─── Interactive lessons (fake store) ─────────────────────────────────────
+
+/** Fake session: canned rows per statement prefix; records every statement. */
+function fakeSession(responder: (s: string) => Record<string, unknown>[] | Error = () => []) {
+  const executed: string[] = [];
+  const session: QueryExecutor = {
+    execute: async (s: string) => {
+      executed.push(s);
+      const r = responder(s);
+      if (r instanceof Error) throw r;
+      return { items: r.map((value) => ({ value })) } as never;
+    },
+  };
+  return { session, executed };
+}
+
+function makeRunner(
+  responder?: Parameters<typeof fakeSession>[0],
+  opts: { lessons?: Lesson[]; progress?: Progress } = {},
+) {
+  const { session, executed } = fakeSession(responder);
+  const printed: string[] = [];
+  const saved: Progress[] = [];
+  const runner = new LessonRunner(session, {
+    lessons: opts.lessons,
+    progress: opts.progress,
+    io: { print: (t) => printed.push(t), width: () => 80 },
+    saveProgress: (p) => saved.push(p),
+  });
+  const out = () => printed.join("\n");
+  return { runner, executed, printed, saved, out };
+}
+
+const products = () => SEED_PRODUCTS.map((p) => ({ ...p }));
+
+describe("LessonRunner", () => {
+  it("resets data, prints the banner and first lesson, and shows level badges", async () => {
+    const { runner, executed, out } = makeRunner();
+    await runner.start();
+    expect(executed.slice(0, RESET_STATEMENTS.length)).toEqual(RESET_STATEMENTS);
+    expect(out()).toContain("Learn DQL — interactive lessons");
+    expect(out()).toContain("Beginner");
+    expect(out()).toContain("Lesson 1/");
+    expect(out()).toContain("Documents and collections");
+    expect(out()).toContain("If you know SQL:");
+    expect(out()).toContain("Task:");
+  });
+
+  it("resumes from saved progress, or starts at a requested level", async () => {
+    const resumed = makeRunner(undefined, { progress: { lesson: 4, completed: [0, 1, 99] } });
+    await resumed.runner.start();
+    expect(resumed.runner.current).toBe(4);
+    expect(resumed.runner.completedCount).toBe(2);
+    expect(resumed.out()).toContain("Resuming at lesson 5");
+
+    const adv = makeRunner(undefined, { progress: { lesson: 4, completed: [] } });
+    await adv.runner.start({ level: "advanced" });
+    expect(adv.runner.current).toBe(firstLessonOf("advanced"));
+    expect(adv.out()).not.toContain("Resuming");
+
+    const bad = makeRunner(undefined, { progress: { lesson: 999, completed: [] } });
+    expect(bad.runner.current).toBe(0);
+  });
+
+  it("passes a correct answer, saves progress, and moves on", async () => {
+    const { runner, out, saved } = makeRunner((s) =>
+      s.startsWith("SELECT * FROM products") ? products() : [],
+    );
+    await runner.start();
+    expect(await runner.submit("SELECT * FROM products")).toBe(true);
+    expect(out()).toContain("✓ Correct!");
+    expect(runner.current).toBe(1);
+    expect(saved.at(-1)).toEqual({ lesson: 1, completed: [0] });
+    expect(out()).toContain("Projection: choosing fields");
+  });
+
+  it("explains a wrong answer and stays put", async () => {
+    const { runner, out } = makeRunner(() => [{ name: "Green tea" }]);
+    await runner.start();
+    expect(await runner.submit("SELECT name FROM products WHERE category = 'tea'")).toBe(false);
+    expect(out()).toContain("✗ Not quite.");
+    expect(runner.current).toBe(0);
+  });
+
+  it("reports query errors and checker crashes without advancing", async () => {
+    const { runner, out } = makeRunner((s) =>
+      s.startsWith("SELEKT") ? new Error("parse error") : [],
+    );
+    await runner.start();
+    expect(await runner.submit("SELEKT 1")).toBe(false);
+    expect(out()).toContain("Query error: parse error");
+
+    const crashing: Lesson = {
+      ...LESSONS[0]!,
+      check: () => {
+        throw new Error("boom");
+      },
+    };
+    const c = makeRunner(undefined, { lessons: [crashing] });
+    await c.runner.start();
+    expect(await c.runner.submit("SELECT 1")).toBe(false);
+    expect(c.out()).toContain("Couldn't check that: boom");
+  });
+
+  it("renders writes as OK and EXPLAIN / PROFILE with the diagnostic renderers", async () => {
+    const { runner, out } = makeRunner((s) => {
+      if (s.startsWith("EXPLAIN")) return [{ plan: { "#operator": "indexScan" } }];
+      if (s.startsWith("PROFILE"))
+        return [
+          { name: "x" },
+          {
+            "~request_profile": {
+              times: { elapsed: 1 },
+              state: "completed",
+              plan: { "#operator": "scan" },
+            },
+          },
+        ];
+      return [];
+    });
+    await runner.start();
+    await runner.submit("UPDATE products SET stock = 1 WHERE _id = 'p1'");
+    expect(out()).toContain("OK");
+    await runner.submit("EXPLAIN SELECT * FROM products");
+    expect(out()).toContain("indexScan");
+    await runner.submit("PROFILE SELECT * FROM products");
+    expect(out()).toContain("Execution Profile");
+  });
+
+  it("navigates with next/back/goto/level and lists progress", async () => {
+    const { runner, out, printed } = makeRunner();
+    await runner.start();
+    await runner.back();
+    expect(out()).toContain("This is the first lesson.");
+    await runner.next();
+    expect(runner.current).toBe(1);
+    await runner.back();
+    expect(runner.current).toBe(0);
+    await runner.goto(String(LESSONS.length));
+    expect(runner.current).toBe(LESSONS.length - 1);
+    await runner.next();
+    expect(out()).toContain("This is the last lesson.");
+    await runner.goto("0");
+    expect(out()).toContain("usage: .goto");
+    await runner.level("intermediate");
+    expect(runner.current).toBe(firstLessonOf("intermediate"));
+    await runner.level("expert");
+    expect(out()).toContain("usage: .level beginner|intermediate|advanced");
+    printed.length = 0;
+    runner.list();
+    expect(out()).toContain("Intermediate");
+    expect(out()).toContain("← you are here");
+    expect(out()).toContain(`0/${LESSONS.length} completed`);
+  });
+
+  it("shows hints, answers, and help; reset restores the data", async () => {
+    const { runner, out, executed } = makeRunner();
+    await runner.start();
+    runner.hint();
+    expect(out()).toContain("Hint:");
+    runner.answer();
+    expect(out()).toContain(LESSONS[0]!.answer);
+    executed.length = 0;
+    await runner.reset();
+    expect(executed.slice(0, RESET_STATEMENTS.length)).toEqual(RESET_STATEMENTS);
+    expect(out()).toContain("Practice data restored.");
+    expect(lessonHelp()).toContain(".level <name>");
+    expect(lessonHelp()).toContain("How the lessons work");
+    expect(lessonHelp()).toContain("optional");
+  });
+
+  it("announces a new level and finishes after the last lesson", async () => {
+    const lessons: Lesson[] = [
+      { ...LESSONS[0]!, check: () => ({ pass: true }) },
+      { ...LESSONS.find((l) => l.level === "advanced")!, check: () => ({ pass: true }) },
+    ];
+    const { runner, out } = makeRunner(undefined, { lessons });
+    await runner.start();
+    await runner.submit("SELECT 1");
+    expect(out()).toContain("On to Advanced!");
+    await runner.submit("SELECT 1");
+    expect(out()).toContain("You finished all 2 lessons!");
+
+    const partial = makeRunner(undefined, { lessons: [lessons[1]!] });
+    await partial.runner.start();
+    await partial.runner.goto("1");
+    partial.runner.list();
+    await partial.runner.submit("SELECT 1");
+    expect(partial.out()).toContain("finished all 1 lessons");
+  });
+
+  it("highlights code and bold spans", () => {
+    expect(highlight("use `SELECT` and **care**")).toBe("use SELECT and care"); // FORCE_COLOR=0
+  });
+});
+
+describe("lesson checks reject wrong answers with a reason", () => {
+  const query = async () => [] as Record<string, unknown>[];
+  const ctx = (rows: Record<string, unknown>[], kind = "select", statement = "SELECT 1") => ({
+    rows,
+    kind: kind as never,
+    statement,
+    query,
+  });
+
+  // "Removing local data" passes when its follow-up query finds no p7 — an empty
+  // fake store means it's gone; its failure path is covered below.
+  it.each(
+    LESSONS.map((l, i) => [i + 1, l.title, l] as const).filter(
+      ([, t]) => t !== "Removing local data",
+    ),
+  )("lesson %i (%s) fails on an empty result", async (_n, _title, lesson) => {
+    const r = await lesson.check(ctx([]));
+    expect(r.pass).toBe(false);
+    if (!r.pass) expect(r.reason.length).toBeGreaterThan(10);
+  });
+
+  const byTitle = (t: string) => LESSONS.find((l) => l.title.startsWith(t))!;
+
+  it("asks for identifiable products when names and ids are absent", async () => {
+    const r = await byTitle("Filtering").check(ctx([{ price: 1 }]));
+    expect(r).toMatchObject({ pass: false, reason: expect.stringContaining("`name`") });
+  });
+
+  it("accepts _id instead of name for product sets", async () => {
+    const r = await byTitle("Filtering").check(ctx([{ _id: "p1" }, { _id: "p2" }, { _id: "p4" }]));
+    expect(r.pass).toBe(true);
+  });
+
+  it("checks projections, ordering, groups, and labels precisely", async () => {
+    const all = products();
+    expect((await byTitle("Projection").check(ctx(all))).pass).toBe(false);
+    expect(
+      (await byTitle("Sorting").check(ctx([{ name: "Espresso blend" }, { name: "Travel mug" }])))
+        .pass,
+    ).toBe(false);
+    expect((await byTitle("Sorting").check(ctx([{ price: 1 }]))).pass).toBe(false);
+    expect(
+      (
+        await byTitle("Grouping").check(
+          ctx([
+            { category: "coffee", n: 2 },
+            { category: "tea", n: 2 },
+            { category: "accessories", n: 1 },
+          ]),
+        )
+      ).pass,
+    ).toBe(false);
+    expect((await byTitle("Grouping").check(ctx([{ n: 3 }, { n: 2 }, { n: 1 }]))).pass).toBe(false);
+    const labels = all.map((p) => ({ name: p.name, a: "in stock" }));
+    expect((await byTitle("Conditional").check(ctx(labels))).pass).toBe(false);
+    expect((await byTitle("Conditional").check(ctx(all.map(() => ({ a: 1 }))))).pass).toBe(false);
+    const espressoOnly = all.map((p) => ({ name: p.name, a: "sold out" }));
+    expect((await byTitle("Conditional").check(ctx(espressoOnly))).pass).toBe(false);
+  });
+
+  it("checks calculated values and aggregates", async () => {
+    const six = (v: number) => SEED_PRODUCTS.map(() => ({ v }));
+    expect((await byTitle("Expressions").check(ctx(six(1)))).pass).toBe(false);
+    expect((await byTitle("Defaults").check(ctx(six(1)))).pass).toBe(false);
+    expect((await byTitle("Defaults").check(ctx([...six(1).slice(1), { v: 13.5 }]))).pass).toBe(
+      false,
+    );
+    expect((await byTitle("Aggregate").check(ctx([{ c: 5 }]))).pass).toBe(false);
+    expect((await byTitle("Aggregate").check(ctx([{ c: 6, a: 1 }]))).pass).toBe(false);
+    expect((await byTitle("Nested").check(ctx([{ name: "Coffee beans" }]))).pass).toBe(false);
+    expect((await byTitle("Filtering groups").check(ctx([{ units: 1 }]))).pass).toBe(false);
+    expect((await byTitle("Filtering groups").check(ctx([{ category: "tea" }]))).pass).toBe(false);
+  });
+
+  it("checks joins and array predicates", async () => {
+    expect((await byTitle("Joining").check(ctx([{ name: "Coffee beans" }]))).pass).toBe(false);
+    expect((await byTitle("Joining").check(ctx([{ s: "Andes Roasters" }]))).pass).toBe(false);
+    expect(
+      (await byTitle("Joining").check(ctx([{ name: "Coffee beans", s: "Andes Roasters" }]))).pass,
+    ).toBe(false);
+    expect((await byTitle("Conditions on array").check(ctx([{ x: 1 }]))).pass).toBe(false);
+    expect(
+      (await byTitle("Conditions on array").check(ctx([{ _id: "o1" }, { _id: "o2" }]))).pass,
+    ).toBe(false);
+  });
+
+  it("checks writes and metadata through follow-up queries", async () => {
+    const q = (rows: Record<string, unknown>[]) => async () => rows;
+    const insert = byTitle("Inserting");
+    expect((await insert.check({ ...ctx([]), query: q([{ _id: "p7", name: "x" }]) })).pass).toBe(
+      false,
+    );
+    expect(
+      (
+        await insert.check({
+          ...ctx([]),
+          query: q([{ _id: "p7", name: "Cold brew kit", category: "coffee", price: 25 }]),
+        })
+      ).pass,
+    ).toBe(true);
+    expect((await byTitle("Updating").check({ ...ctx([]), query: q([{ stock: 25 }]) })).pass).toBe(
+      true,
+    );
+    expect((await byTitle("Removing").check({ ...ctx([]), query: q([{ _id: "p7" }]) })).pass).toBe(
+      false,
+    );
+    const useIds = byTitle("Addressing");
+    expect(
+      (
+        await useIds.check({
+          ...ctx([], "evict", "EVICT FROM products WHERE _id = 'p7'"),
+          query: q([]),
+        })
+      ).pass,
+    ).toBe(false);
+    expect(
+      (
+        await useIds.check({
+          ...ctx([], "evict", "EVICT FROM products USE IDS 'p7'"),
+          query: q([{ _id: "p7" }]),
+        })
+      ).pass,
+    ).toBe(false);
+    const idx = [
+      {
+        _id: "products.idx_products_category_price",
+        collection: "products",
+        fields: [{ key: ["category"] }],
+      },
+    ];
+    const composite = byTitle("Composite");
+    expect((await composite.check({ ...ctx([], "ddl"), query: q(idx) })).pass).toBe(false);
+    expect((await composite.check({ ...ctx([{ x: 1 }]), query: q(idx) })).pass).toBe(false);
+    expect((await composite.check({ ...ctx(products()), query: q(idx) })).pass).toBe(false);
+    // The composite index doesn't count: the task names idx_products_category.
+    expect((await byTitle("Indexes").check({ ...ctx([]), query: q(idx) })).pass).toBe(false);
+    const own = [
+      {
+        _id: "products.idx_products_category",
+        collection: "products",
+        fields: [{ key: ["category"] }],
+      },
+    ];
+    expect((await byTitle("Indexes").check({ ...ctx([]), query: q(own) })).pass).toBe(true);
+    const wrong = [
+      {
+        _id: "products.idx_products_category",
+        collection: "products",
+        fields: [{ key: ["price"] }],
+      },
+    ];
+    const r = await byTitle("Indexes").check({ ...ctx([]), query: q(wrong) });
+    expect(r.pass).toBe(false);
+    expect(
+      (await byTitle("Reading query plans").check(ctx([{ plan: "scan" }], "explain"))).pass,
+    ).toBe(false);
+    expect((await byTitle("Measuring").check(ctx([{ x: 1 }], "profile"))).pass).toBe(false);
+  });
+});
+
+describe("lesson content", () => {
+  const norm = (t: string) =>
+    t
+      .replace(/\s+--.*$/gm, "")
+      .replace(/`/g, "")
+      .replace(/\s+/g, " ")
+      .trim()
+      .toLowerCase();
+
+  it("syntax examples and hints never give away the answer", () => {
+    for (const [i, l] of LESSONS.entries()) {
+      const answer = norm(l.answer);
+      expect(norm(l.syntax.join(" ")), `lesson ${i + 1} syntax`).not.toContain(answer);
+      for (const s of l.syntax) expect(norm(s), `lesson ${i + 1} syntax`).not.toBe(answer);
+      expect(norm(l.hint), `lesson ${i + 1} hint`).not.toContain(answer);
+    }
+  });
+});
+
+describe("looksUnfinished", () => {
+  it("continues on open quotes/brackets, trailing commas, operators, and keywords", () => {
+    for (const t of [
+      "SELECT name,",
+      "SELECT *",
+      "SELECT * FROM products WHERE",
+      "SELECT * FROM products WHERE price >",
+      "SELECT * FROM products WHERE name = 'Green",
+      "INSERT INTO products VALUES ({'_id': 'x'",
+      "SELECT * FROM products ORDER BY",
+    ]) {
+      expect(looksUnfinished(t), t).toBe(true);
+    }
+  });
+
+  it("runs complete-looking statements, ignoring keywords inside strings and comments", () => {
+    for (const t of [
+      "SELECT * FROM products",
+      "SELECT name FROM products WHERE category = 'where'",
+      "SELECT * FROM products -- where",
+      "SELECT [1, 2] AS xs FROM products",
+      "SELECT COUNT(*) FROM products",
+    ]) {
+      expect(looksUnfinished(t), t).toBe(false);
+    }
+  });
+});
+
+describe("submitAll", () => {
+  it("stops once a statement passes, and reports how many it skipped", async () => {
+    const submitted: string[] = [];
+    const runner = {
+      submit: async (s: string) => {
+        submitted.push(s);
+        return s === "PASS";
+      },
+    };
+    const skipped: number[] = [];
+    expect(await submitAll(runner, ["a", "PASS", "b", "c"], (n) => skipped.push(n))).toBe(2);
+    expect(submitted).toEqual(["a", "PASS"]);
+    expect(skipped).toEqual([2]);
+    expect(await submitAll(runner, ["x", "PASS"], (n) => skipped.push(n))).toBe(0);
+    expect(await submitAll(runner, ["x"])).toBe(0);
+    expect(skipped).toEqual([2]);
+    const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+    await submitAll(runner, ["PASS", "y"]);
+    expect(String(errors.mock.calls[0]?.[0])).toContain("Skipped 1 more statement");
+    errors.mockRestore();
+  });
+
+  it("queued commands run after the statement in flight", async () => {
+    const order: string[] = [];
+    let release: () => void = () => {};
+    const ev = makeLessonEval({
+      submit: async () => {
+        await new Promise<void>((r) => {
+          release = r;
+        });
+        order.push("submit");
+        return false;
+      },
+    });
+    ev.eval("SELECT 1\n", {}, "repl", () => {});
+    const cmd = ev.enqueue(() => order.push("command"));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(order).toEqual([]);
+    release();
+    await cmd;
+    expect(order).toEqual(["submit", "command"]);
+    await ev.enqueue(() => {
+      throw new Error("boom");
+    });
+  });
+});
+
+describe("makeLessonEval", () => {
+  const setup = () => {
+    const submitted: string[] = [];
+    const ev = makeLessonEval({
+      submit: async (s) => {
+        submitted.push(s);
+        return false;
+      },
+    });
+    const call = (cmd: string) =>
+      new Promise<Error | null>((resolve) => ev.eval(cmd, {}, "repl", (err) => resolve(err)));
+    return { submitted, ev, call };
+  };
+
+  it("runs on Enter without a semicolon; continues only while unfinished", async () => {
+    const { submitted, ev, call } = setup();
+    expect(await call("SELECT * FROM products\n")).toBeNull();
+    expect(await call("SELECT name,\n")).toBeInstanceOf(Recoverable);
+    // node:repl re-sends the whole accumulation after a Recoverable
+    expect(await call("SELECT name,\nprice FROM products\n")).toBeNull();
+    expect(await call("-- just a comment\n")).toBeNull();
+    expect(await call("SELECT 1; SELECT 2;\n")).toBeNull();
+    expect(await call("SELECT 3; SELECT 4\n")).toBeNull();
+    ev.reset();
+    await ev.drain();
+    expect(submitted).toEqual([
+      "SELECT * FROM products",
+      "SELECT name,\nprice FROM products",
+      "SELECT 1",
+      "SELECT 2",
+      "SELECT 3",
+      "SELECT 4",
+    ]);
+  });
+
+  it("reports submit failures", async () => {
+    const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+    const failing = makeLessonEval({
+      submit: async () => {
+        throw new Error("kaboom");
+      },
+    });
+    await new Promise((r) => failing.eval("SELECT 1\n", {}, "repl", r));
+    await failing.drain();
+    expect(errors.mock.calls.flat().join(" ")).toContain("kaboom");
+    errors.mockRestore();
+  });
+});
+
+describe("tutorial command wiring", () => {
+  const deps = {
+    detectChannel: () => ({ channel: "npm" as const }),
+    now: () => new Date("2026-11-06T12:00:00Z"),
+    platform: "linux/x64",
+  };
+  const run = async (
+    args: string[],
+    extra: Partial<Parameters<typeof registerTutorialCommand>[1]> = {},
+  ) => {
+    const program = new Command().exitOverride();
+    registerTutorialCommand(program, { ...deps, ...extra });
+    process.exitCode = undefined;
+    await program.parseAsync(["node", "dittosh", "tutorial", ...args]);
+    const code = process.exitCode;
+    process.exitCode = undefined;
+    return code;
+  };
+
+  afterEach(() => vi.restoreAllMocks());
+
+  it("dispatches --interactive with level and data dir", async () => {
+    const calls: unknown[] = [];
+    const code = await run(["--interactive", "--level", "advanced", "-d", "/tmp/x"], {
+      startInteractive: async (o) => {
+        calls.push(o);
+      },
+    });
+    expect(code).toBeUndefined();
+    expect(calls).toEqual([{ dataDir: "/tmp/x", level: "advanced" }]);
+  });
+
+  it("rejects --interactive when unavailable and --level without --interactive", async () => {
+    const err = vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(await run(["--interactive"])).toBe(1);
+    expect(await run(["--level", "beginner"])).toBe(2);
+    expect(err.mock.calls.flat().join(" ")).toContain("only apply with --interactive");
+  });
+
+  it("writes the Markdown by default", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tut-cmd-"));
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      expect(await run(["-o", path.join(dir, "t.md")])).toBeUndefined();
+      expect(fs.existsSync(path.join(dir, "t.md"))).toBe(true);
+      expect(await run(["-o", path.join(dir, "t.md")])).toBe(2);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("LessonRunner runs one action at a time", () => {
+  it("a jump waits for the answer being checked, so the data reset can't empty the store under it", async () => {
+    const log: string[] = [];
+    let releaseCheck: () => void = () => {};
+    let checking = false;
+    const session: QueryExecutor = {
+      execute: async (s: string) => {
+        if (s === LESSONS[0]!.answer && !checking) {
+          checking = true;
+          log.push("answer:start");
+          await new Promise<void>((resolve) => {
+            releaseCheck = resolve;
+          });
+          log.push("answer:end");
+        } else if (RESET_STATEMENTS.includes(s)) {
+          log.push("reset");
+        }
+        return { items: SEED_PRODUCTS.map((value) => ({ value })) } as never;
+      },
+    };
+    const runner = new LessonRunner(session, {
+      io: { print: () => {}, width: () => 80 },
+      progress: { lesson: 0, completed: [] },
+      saveProgress: () => {},
+    });
+    const submitted = runner.submit(LESSONS[0]!.answer);
+    const moved = runner.goto("5");
+    await new Promise((r) => setTimeout(r, 10));
+    expect(log).toEqual(["answer:start"]); // the jump hasn't reset anything yet
+    releaseCheck();
+    await Promise.all([submitted, moved]);
+    expect(log.indexOf("answer:end")).toBeLessThan(log.lastIndexOf("reset"));
+    expect(runner.isCompleted(0)).toBe(true);
+    expect(runner.current).toBe(4);
+  });
+
+  it("a failed action doesn't block the next one", async () => {
+    let fail = true;
+    const session: QueryExecutor = {
+      execute: async () => {
+        if (fail) {
+          fail = false;
+          throw new Error("store went away");
+        }
+        return { items: [] } as never;
+      },
+    };
+    const runner = new LessonRunner(session, {
+      io: { print: () => {}, width: () => 80 },
+      progress: { lesson: 0, completed: [] },
+      saveProgress: () => {},
+    });
+    await expect(runner.next()).rejects.toThrow("store went away");
+    await runner.goto("3");
+    expect(runner.current).toBe(2);
+  });
+});
diff --git a/tsconfig.json b/tsconfig.json
index a72520b..80a23ba 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,7 +11,8 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "outDir": "dist",
-    "types": ["node"]
+    "types": ["node"],
+    "jsx": "react-jsx"
   },
   "include": ["src", "datasets", "scripts", "tests"]
 }
diff --git a/tsup.config.ts b/tsup.config.ts
index 13bee89..53710eb 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -41,12 +41,25 @@ export default defineConfig({
     ].join("\n"),
   },
   // Bundle all JS deps; only the Ditto SDK stays external (native .node binaries).
-  noExternal: ["commander", "chalk", "env-paths", "tar", "@inquirer/prompts"],
-  external: ["@dittolive/ditto"],
+  noExternal: [
+    "commander",
+    "chalk",
+    "env-paths",
+    "tar",
+    "@inquirer/prompts",
+    "string-width",
+    "wrap-ansi",
+    "ink",
+    "react",
+  ],
+  // react-devtools-core: Ink only imports it when DEV=true; it isn't installed.
+  external: ["@dittolive/ditto", "react-devtools-core"],
   define: {
     __CLI_VERSION__: JSON.stringify(pkg.version),
     __DITTO_SDK_VERSION__: JSON.stringify(sdkPkg.version),
     RELEASE: JSON.stringify(release ? "true" : "false"),
+    // React/Ink production builds: smaller and faster; dev-only code is dropped.
+    "process.env.NODE_ENV": JSON.stringify("production"),
   },
   esbuildPlugins: release
     ? [
diff --git a/vitest.config.ts b/vitest.config.ts
index 4feac16..f981fc9 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -8,7 +8,11 @@ export default defineConfig({
       include: ["src/**"],
       // The process entry point and the node:repl wiring are exercised by e2e
       // subprocess / pty tests, which v8 coverage cannot see — excluded deliberately.
-      exclude: ["src/cli/index.ts", "src/cli/groups/dql/repl.ts"],
+      exclude: [
+        "src/cli/index.ts",
+        "src/cli/groups/dql/repl.ts",
+        "src/cli/groups/tutorial-repl.ts",
+      ],
       // Hard gate (PM decision): coverage must stay at or above 85%.
       thresholds: { statements: 85, branches: 85, functions: 85, lines: 85 },
     },