@zerotal/arch 1.8.1 → 1.10.0

package/docs/deployment.md

@@ -38,6 +38,7 @@ deliberate: systemd, your container runtime or your deploy script owns process
 lifecycle, and this gives it a gate to restart behind.
 
 ```bash
+bun zt deploy:production --check            # run the gate only — see below
 bun zt deploy:production --dry-run          # print the plan, run none of it
 bun zt deploy:production --skip-migrations  # release without touching the schema
 bun zt deploy:production --probe=https://example.com  # real handshake at the end
@@ -63,18 +64,46 @@ the wrong database.
 
 Each entry is a `DeployTarget`:
 
-| Field   | Meaning                                                                                                                                                                                                                                  |
-| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`   | The public URL in this environment. What `--probe` handshakes against when given no URL of its own.                                                                                                                                      |
-| `steps` | Override the release steps. Defaults to `DEFAULT_DEPLOY_STEPS` — `assets:build`, `inertia:build`, `migrate`. Each names a `zt` command, and one that is not registered is skipped, so an app without Inertia simply has no Inertia step. |
+| Field       | Meaning                                                                                                                                                                                                                                         |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`       | The public URL in this environment. What `--probe` handshakes against when given no URL of its own.                                                                                                                                             |
+| `steps`     | Override the release steps. Defaults to `DEFAULT_DEPLOY_STEPS` — `assets:build`, `inertia:build`, `migrate`. Each names a `zt` command, and one that is not registered is skipped, so an app without Inertia simply has no Inertia step.        |
+| `preflight` | Your own commands, run in the preflight phase — after the config validators and `doctor`, before anything is built or migrated. A non-zero exit refuses the release. Defaults to `release:check` when the app registers a command by that name. |
 
 Omit the file entirely and you get `DEFAULT_DEPLOY_TARGETS`: `production` and
 `staging`, both with the default steps.
 
-The defaults build and migrate; they do not check anything you wrote. A preflight command
-of your own — `release:check`, a smoke test — has to be named in `steps` to run, and
-nothing prompts you to add it, so a command written precisely to guard a release can sit
-there never running. Name every step you want, in the order you want them:
+### Your own release gate
+
+The framework's preflight knows the things a framework can know: that this really is the
+environment you think it is, that the config validators pass, that `doctor` is happy —
+which now includes refusing a production release whose `mail.driver` is still `log`,
+because mail written to a log file is delivered to nobody and says so nowhere. It
+cannot know that this workspace has no cancellation policy, or that the owner account
+is still on the password `admin:create` issued it. Those refusals are yours.
+
+Write them as a command and name it `release:check` (exported as
+`CONVENTIONAL_PREFLIGHT_COMMAND`). The pipeline finds it by name — nothing to wire up:
+
+```ts
+// app/commands/ReleaseCheckCommand.ts
+import { Command } from "zerotal";
+
+export class ReleaseCheckCommand extends Command {
+  static commandName = "release:check";
+  static description = "Refuse a release this app is not ready for";
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    const problems: string[] = [];
+    if (Bun.env["APP_KEY"] === "base64:CHANGE_ME") problems.push("APP_KEY is the example one.");
+    if (problems.length > 0) throw new Error(problems.join(" "));
+  }
+}
+```
+
+A throw, or any non-zero exit, stops the release before `assets:build` has run. To run
+something else — or more than one thing — name them:
 
 ```ts
 // config/deploy.ts
@@ -82,19 +111,42 @@ export default {
   targets: {
     production: {
       url: "https://example.com",
-      steps: ["release:check", "assets:build", "inertia:build", "migrate"],
+      preflight: ["release:check", "smoke:mail"],
     },
   },
 };
 ```
 
-Put a check first. A step that fails stops the release, and a check that runs after the
-migration has already run has missed its moment.
+A name in `preflight` that is not a registered command **fails the deploy** rather than being
+skipped. That is the opposite of how `steps` treats an absent command, and deliberately so: a
+missing `inertia:build` means the app has no Inertia, while a missing gate means the gate is
+not running — which is the state this exists to prevent. A gate nothing calls is a comment.
 
 Two things worth adding while you are there: `assets:build` and `inertia:build` accept
 `--clean`, which removes anything in the output directory the build did not write — see
 [Build assets](#build-assets).
 
+### `--check`: the gate on its own
+
+A release script has a moment where the new code is on disk and the service has not
+restarted yet. That is the moment to ask whether this release is fit to go live, and
+`--check` is the whole preflight and nothing else:
+
+```bash
+# on the box, after the new release is unpacked and before the restart
+APP_ENV=production bun zt deploy:production --check || exit 1
+systemctl restart app
+```
+
+It runs the environment check, the config validators with production semantics,
+`doctor`, and your own `release:check` — everything that can refuse — and builds
+nothing, migrates nothing, restarts nothing. Exit 0 and restart; exit non-zero and
+keep serving the previous release, which is the point. A workspace that has lost its
+banking details, or had its mail driver knocked back to `log`, never goes live broken.
+
+`--check` and `--dry-run` answer different questions. `--dry-run` prints the plan
+without running any of it, including the gate. `--check` runs the gate for real.
+
 > **Note** — `deploy:<env>` runs **where the app runs**, with that environment's
 > variables. It does not reach another machine over SSH. Run it on the box, or in
 > the container build, as the step before the restart.
@@ -180,6 +232,54 @@ bun zt migrate
 Auto-`synchronize` is **hard-off in production** — generate and commit
 [migrations](/docs/migrations) during development and run them on deploy.
 
+## Back up the database
+
+On SQLite the database is one file, which makes `cp` look like a backup. It is not one. A
+live SQLite database has pages in flight; copying the file while the server is serving can
+capture a half-written page, and the result is a file that sits in your retention directory
+for months and turns out to be corrupt on the one morning you open it.
+
+`zt db:backup` uses SQLite's own `VACUUM INTO`, which takes a read lock and writes a
+complete database while the server keeps serving. It needs no `sqlite3` binary on the box:
+
+```bash
+# in your project root
+bun zt db:backup --dir=/var/backups/app --keep=30 --require-rows=bookings,invoices
+```
+
+| Flag             | What it does                                                                 |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `--dir`          | Where snapshots go. Default `storage/backups`.                               |
+| `--keep`         | How many to keep, newest first. `0` keeps every one. Default `14`.           |
+| `--require-rows` | Tables that must not be empty in the snapshot. **Set this.**                 |
+| `--rehearse`     | Also perform the restore — copy the snapshot, open the copy, check it there. |
+
+Every snapshot is opened and integrity-checked the moment it is written, and **every failure
+path exits non-zero**. That is what makes it safe to run from a timer: a bad night leaves a
+failed unit somebody can see, rather than a green one and no file.
+
+`--require-rows` is the flag that turns "a file was written" into "the file has the business
+in it". An empty `bookings` table in a snapshot of a live system is not a small discrepancy,
+and it is invisible in a byte count.
+
+Run `--rehearse` on a schedule of its own — weekly is plenty. A backup nobody has restored is
+a hope, and the restore is the operation you will be doing at 3am.
+
+```ini
+# /etc/systemd/system/app-backup.service
+[Service]
+Type=oneshot
+WorkingDirectory=/srv/app
+Environment=APP_ENV=production
+ExecStart=/srv/app/node_modules/.bin/bun zt db:backup --keep=30 --require-rows=bookings
+```
+
+Pair it with a `.timer`, and let the failed unit be your alert. Retention is handled by
+`--keep`; anything the command did not write is never touched.
+
+On PostgreSQL or MySQL the command refuses and points at `pg_dump` / `mysqldump`, which is
+where that job belongs.
+
 ## Build assets
 
 Build the frontend bundle as a release step, so `public/` holds compiled output before
@@ -233,6 +333,31 @@ Ordering matters if the old release is still serving traffic: clearing the direc
 its bundles away, so do it as close to the swap as you can, or stage the release in a new
 directory and move it into place.
 
+### `assets:prune` — clearing up after the extract instead of before it
+
+Clearing the directory first has a cost the ordering note above hints at: between the
+`rm -rf` and the new files landing, the release still serving traffic has no bundles.
+If you would rather extract over the top and tidy afterwards, `assets:build` records
+what it wrote and `assets:prune` removes what that record does not claim:
+
+```bash
+# on the build machine — the record is written under .zerotal/
+bun zt assets:build
+tar -czf release.tgz public .zerotal   # ship the record with the release
+
+# on the server, after extracting and before the restart
+bun zt assets:prune --dry-run          # list what would go
+bun zt assets:prune
+```
+
+**Ship `.zerotal/` with the release** — that is the part that makes it work. Without
+the record, "which files belong to this release" has no answer on a server that never
+ran a build, and `assets:prune` says so and removes nothing rather than guessing.
+
+It is conservative by design: it deletes a file only when the record does not claim it
+_and_ it is named the way the bundler names a code-split chunk. Your images and
+favicon are never candidates, because an output directory is usually `public/`.
+
 ### `--clean` for a directory the build does not own outright
 
 The cleanup above recognises the filenames `Bun.build()` produces. An app that sets its own
@@ -350,6 +475,11 @@ The symptom is a legitimate visitor getting a 429 they did not earn.
 Count the proxies you actually run. Setting `trustedProxies: 3` with one proxy in front
 reads an entry the client supplied.
 
+`zt doctor` warns about this: a production-like deployment with a registered throttle and no
+`trustedProxies` is reported as almost certainly wrong. It is a warning rather than a failure
+because the framework cannot see your deployment — an app served directly, with nothing in
+front of it, is correctly configured exactly as it stands.
+
 ### Never gate the transport path
 
 **Browsers do not attach basic-auth credentials to a WebSocket handshake.** An HTTP auth
@@ -513,8 +643,9 @@ Run the worker as a **second** container/service from the same image with the co
 `bun zt worker`.
 
 On a server with no Node installed, `bun install` can fail on a transitive package whose
-`postinstall` shells out to `node`. `--ignore-scripts` resolves it, but check what you are
-skipping first:
+`postinstall` shells out to `node`. The `bun` npm package is the usual one — its
+`postinstall` downloads a Bun binary the box already has, and there is no `node` to run the
+script with. `--ignore-scripts` resolves it, but check what you are skipping first:
 
 ```bash
 # every package with an install script, before you skip them all
@@ -523,6 +654,13 @@ for p in node_modules/*/package.json node_modules/@*/*/package.json; do
 done
 ```
 
+### `startZerotal` options
+
+`StartZerotalOptions` is what `zt.ts` may pass — currently `configDir`, for an app whose config
+does not live at `./config`. `isDevSurfaceAllowed(env)` is the check every dev-only surface
+gates on, exported so an app's own dev tooling can gate the same way; it **fails closed**, so an
+unset `APP_ENV` does not qualify.
+
 ## Next steps
 
 - [Configuration](/docs/config-system) — environment variables and config files.

package/docs/devtools.md

@@ -1004,6 +1004,11 @@ meaningfully different from `{}` — a node can be both a branch and a leaf.
 unfiltered list plus whether it heads a group (`groupKey`, `groupSize`) or is a
 folded follow-up (`child`).
 
+## Types
+
+`TraceStoreOptions` sets how many traces are kept and for how long.
+`DevtoolsClientOptions` configures the browser side.
+
 ## Next steps
 
 - [Logger](/docs/logger) — structured logging that surfaces in the Logs tab.

package/docs/email-verification.md

@@ -49,12 +49,29 @@ register ──▶ Url.sign(/auth/verify?id&email, ttl) ──▶ email link
 
 ## Migration
 
-Add a nullable `email_verified_at` column to your users table:
+Whether you need one **depends on what your schema's source of truth is** — `zt doctor`
+reports which mode this app is in.
+
+- **Models are the source of truth** (`synchronize` on). You do not need a migration. The
+  mixin registers `email_verified_at` imperatively and the table is built from what the
+  models declare, so the column comes with it.
+- **Migrations are the source of truth** (`synchronize` off — the production default). You
+  do. The boot-time concern only _adds_ a column to a table that already exists; it never
+  revisits one it has seen. A `create users` migration that does not mention
+  `email_verified_at` produces a table without it, and then every query touching the column
+  fails with `no such column: email_verified_at` — all at once, in tests that have nothing to
+  do with email, with nothing pointing at the mixin.
+
+`zt doctor` fails on that combination and names the table, so you find it before the suite
+does.
+
+Write the migration **guarded**:
 
 ```typescript fragment
 // database/migrations/002_add_email_verified_at.ts
 export default class AddEmailVerifiedAt extends Migration {
   async up(schema: Schema) {
+    if (await schema.hasColumn("users", "email_verified_at")) return;
     await schema.table("users", (table) => {
       table.timestamp("email_verified_at").nullable();
     });
@@ -67,6 +84,14 @@ export default class AddEmailVerifiedAt extends Migration {
 }
 ```
 
+The guard is not defensive habit. Any database that has booted the app since the mixin was
+composed already **has** the column — the concern added it. An unguarded migration then fails
+with `duplicate column name`, during the `migrate` step of `deploy:production`, which is the
+worst possible moment to learn this.
+
+`remember_token` from `Authenticatable` is provisioned the same way and carries the same
+condition.
+
 ## User model
 
 Expose the column and a convenience getter the middleware and controller can read:

package/docs/encryption.md

@@ -373,6 +373,27 @@ it works only after the app has booted. In a unit test that never boots, constru
 | `Url.sign(base, params?, min?, secret?)` | `(base: string, params?, expiresInMinutes?, secret?) => string` | Build an HMAC-signed, time-limited URL.              |
 | `Url.verify(url, secret?)`               | `(signedUrl: string, secret?: string) => boolean`               | Verify a signed URL; `false` if tampered or expired. |
 
+## Hashing helpers
+
+Three pure helpers sit beside `Crypt`, for the cases that are not encryption:
+
+| Helper                | Use                                                                    |
+| --------------------- | ---------------------------------------------------------------------- |
+| `sha256Hex(value)`    | A hex digest. For a lookup key or a blind index, never for a password. |
+| `hmacHex(value, key)` | A keyed digest — a webhook signature, a tamper-evident token.          |
+| `safeEqual(a, b)`     | Constant-time comparison. Use it for every secret comparison.          |
+
+**`safeEqual` is the one that matters.** `a === b` on a token returns as soon as two bytes
+differ, and the time it took is a measurement of how much of the prefix was right — enough, over
+many attempts, to recover a secret a character at a time. Comparing anything an attacker
+supplies against anything you hold goes through `safeEqual`.
+
+### Signed URLs
+
+`URLSigner` is what `signedUrl()` and `ValidateSignatureMiddleware` are built on. Reach for it
+directly when you need to sign or verify outside a request — a link minted by a scheduled job,
+or a signature checked by a worker.
+
 ## Next steps
 
 - [Authentication](/docs/authentication) — where hashed passwords are verified at login.

package/docs/errors.md

@@ -273,6 +273,8 @@ So a package that owns an error class can contribute a **diagnosis**, rendered a
 
 It works on SQLite, PostgreSQL and MySQL — matched on the driver's error code where there is one (`42P01`, `42703`, `1146`, `1054`) and on the message otherwise.
 
+`bun zt doctor` asks the same question before anything breaks, and warns when migrations are pending — see [Migrations](/docs/migrations#running-migrations). The overlay is reactive by nature: it needs a request to have already failed, which means somebody has already lost the thread of what they were doing.
+
 > **The button exists only in development.** The endpoint behind it refuses unless [`devSurfacesEnabled()`](/docs/deployment) is true, and that gate **fails closed**: an unset `APP_ENV` does not qualify. The route is not even registered otherwise.
 >
 > It also requires a single-use token minted into the page, and passes the same origin check the WebSocket endpoints use. A dev server on `localhost:3000` is reachable by any site you have open in another tab, and "run every pending migration" is not something a random page should be able to trigger.

package/docs/flow/components.md

@@ -859,6 +859,60 @@ Content-Security-Policy:
 }
 ```
 
+## Types
+
+Every built-in component exports the type of its own props, named after it. Reach for one when
+you wrap a component rather than use it directly — the usual reason an app needs the type at all:
+
+```tsx
+import { Modal, type ModalProps } from "@zerotal/flow";
+
+/** Our confirm dialog: the same API, one decision already made. */
+export function ConfirmModal(props: Omit<ModalProps, "closeable">) {
+  return <Modal closeable={false} {...props} />;
+}
+```
+
+```text
+DescriptionProps  DisclosureProps   DrawerProps       DropdownProps
+ErrorBoundaryProps                  ErrorProps        ErrorsProps
+FieldsetProps     FileUploadProps   FlashProps        ForProps
+InfiniteScrollProps                 LegendProps       LinkProps
+ListboxProps      LoadingProps      ModalProps        PagerProps
+SectionContentProps                 SectionOutletProps
+VirtualizeProps
+```
+
+`ListboxOption` is one entry in a `<Listbox>`, and `UploadRef` is what `<FileUpload>` hands back
+for a file the server has accepted.
+
+### The flash API
+
+`this.flash(…)` is the short form. The builder underneath it is exported, and so are the shapes
+it produces — worth having when a helper composes a message rather than writing one inline:
+
+| Type                 | What it is                                                               |
+| -------------------- | ------------------------------------------------------------------------ |
+| `FlashLevel`         | `"info" \| "success" \| "warning" \| "error"` — what colours the toast.  |
+| `FlashMessage`       | One flash: its level, text, and any actions.                             |
+| `FlashOptions`       | Per-message overrides — duration, position, whether it can be dismissed. |
+| `FlashBuilder`       | The fluent form, for a message assembled in more than one step.          |
+| `FlashPosition`      | Where the container puts it, matching `<Flash position>`.                |
+| `FlashAction`        | A button on the toast: its label and what it does.                       |
+| `FlashActionStyle`   | How that button is drawn.                                                |
+| `FlashActionVariant` | Its emphasis.                                                            |
+| `FlashCallback`      | What runs when the action is pressed.                                    |
+| `RedirectFlash`      | A flash that survives a redirect, so it appears on the page you land on. |
+
+`ErrorField` and `ValidationRules` are the validation side of the same story: what one field's
+errors look like, and the rules a component declares.
+
+### Elsewhere
+
+`DurableOption` configures `@durable` state, `SessionOptions` the session a component reads, and
+`UrlOptions` how `@url` state is written into the query string. `EventName` is the union of
+events a component can listen for.
+
 ## Next steps
 
 - [Flow overview](/docs/flow) — the guide's front page and the rest of the sections.

package/docs/flow/forms.md

@@ -545,6 +545,63 @@ export class AvatarUploader extends Component {
   dedicated `temp` disk are natural follow-ups; the `TemporaryUploadedFile` API is designed to
   absorb them without changing component code.
 
+## Enhancing a plain form — no component
+
+Everything above needs a Flow component. This does not.
+
+A page that is just server-rendered HTML — no `Router.flow`, no `Component` — can still have a
+form that submits without the page flashing. Add `data-enhance`:
+
+```html
+<form method="post" action="/subscribe" data-enhance>
+  <p class="error">{{ error }}</p>
+  <input name="email" />
+  <button type="submit">Subscribe</button>
+</form>
+```
+
+The form posts through `fetch`, and **the matching form in the response replaces this one in
+place**. A validation error re-renders the form with the message in it, and that is what lands
+on the page — the rest of the document is untouched, so nothing scrolls, nothing flashes, and
+what the person typed is still there.
+
+### Include the script
+
+The enhancement is a separate, dependency-free bundle. Flow pages get
+`/__flow/runtime.js`; a plain page gets nothing, which is the whole reason this exists. Put the
+tag in the layout that renders your non-Flow pages:
+
+```tsx
+import { flowEnhanceTag } from "@zerotal/flow";
+
+// in your layout's <head>
+flowEnhanceTag(); // <script src="/__flow/enhance.js" defer></script>
+```
+
+Nothing fails if you forget it — the forms simply post the way they always did. That is the
+design, and it is also why the tag is easy to leave out and never notice.
+
+### What it does
+
+| Situation        | What happens                                                                    |
+| ---------------- | ------------------------------------------------------------------------------- |
+| Normal submit    | The response's matching form replaces this one; focus and caret are restored.   |
+| Validation error | Same — the server re-rendered the form, so the error is in the markup.          |
+| Redirect         | Followed, the document swapped, and `pushState`d so the address bar agrees.     |
+| Network failure  | Falls back to a native submit, so nothing typed is lost.                        |
+| No JavaScript    | An ordinary form post. `data-enhance` is additive; there is no fallback to rot. |
+
+`data-enhance-target="#selector"` replaces something else instead of the form — a results
+panel, a list. `data-enhance="false"` opts a form out. While a submission is in flight the form
+carries `data-enhance-busy`, which is a styling hook and a re-entry guard.
+
+A `flow:enhanced` event fires on `window` after each swap, with
+`detail.navigated` saying whether it followed a redirect.
+
+> **Note** — This is enhancement, not a component. There is no state, no socket and no server
+> round-trip beyond the form's own post. When the page needs live state, reach for a
+> [component](/docs/flow/components).
+
 ## Next steps
 
 - [Flow overview](/docs/flow) — the guide's front page and the rest of the sections.

package/docs/flow/references.md

@@ -216,6 +216,20 @@ override async render() {
 | `x-show="$flow.open && $flow.count > 0"` | Raw Alpine expression                                        |
 | `flow:click="increment"`                 | Hand-written Flow directive (accepted but not needed in JSX) |
 
+## Plain-form enhancement
+
+For forms on pages with no Flow component. See
+[Forms](/docs/flow/forms#enhancing-a-plain-form--no-component).
+
+| Attribute / export    | Meaning                                                                                |
+| --------------------- | -------------------------------------------------------------------------------------- |
+| `data-enhance`        | Submit through `fetch` and patch the response in. `"false"` opts out.                  |
+| `data-enhance-target` | CSS selector for what to replace, instead of the form itself.                          |
+| `data-enhance-busy`   | Set on the form while a submission is in flight. Styling hook and re-entry guard.      |
+| `flowEnhanceTag()`    | The `<script>` tag to put in a non-Flow layout.                                        |
+| `FLOW_ENHANCE_PATH`   | `/__flow/enhance.js` — the path the bundle is served at.                               |
+| `flow:enhanced`       | Window event after each swap; `detail.navigated` says whether a redirect was followed. |
+
 ## Client expressions
 
 Inside a client expression — `onClick={() => this.X(...)}` — `this.` resolves to the live client runtime (no server round-trip to start it). You write the **same names as on the server** — no `$`-prefixed syntax, and it all type-checks.

package/docs/getting-started.md

@@ -16,6 +16,44 @@ provider.
   is configured for **SQLite**, which needs nothing installed — PostgreSQL and
   MySQL are supported and are a `DATABASE_URL` away.
 
+### One project, one Bun
+
+`engines.bun` is a floor, not a lock, and nothing in npm enforces it. A project can end up
+with two runtimes in it without anyone choosing that: the shell's `bun`, and a different one
+in `node_modules/bun`, put there by a transitive peer dependency nobody declared. The work
+then splits between them — the server served by one, the suite run by the other — and nothing
+says so.
+
+That is expensive because the difference is real but narrow. The SQLite bindings, `node:`
+compatibility and the test runner itself all change between releases, so a couple of
+assertions happen to be runtime-sensitive and the rest are not. When those two fail you go
+looking for a bug in the code they touch. And a suite that passes is not evidence either: it
+only means no test happened to stand on a difference.
+
+So **`zt` refuses to run when the two disagree**:
+
+```
+Two Bun runtimes are in play. This process is Bun 1.3.14, but the project
+installs Bun 1.4.0 (/srv/app/node_modules/bun/package.json).
+```
+
+This is not a pin. The version to agree on is whichever one the project installed, so
+`bun update bun` moves it and nothing needs editing — what is enforced is that there is only
+one. Fix it either way:
+
+```bash
+bun update bun          # move the installed one to match your shell
+node_modules/.bin/bun   # or run everything through the installed one
+```
+
+Most projects never see this, because most have no `bun` in `node_modules` to disagree with.
+To boot anyway — mid-upgrade, say — set `ZT_ALLOW_RUNTIME_MISMATCH=1`, which downgrades the
+refusal to a warning. The refusal is a `RuntimeMismatchError`, which carries both versions in
+its `context` for anything scripting around it.
+
+`zt test` spawns the binary running it, not whatever `bun` resolves to on `PATH`, so the
+suite runs on the runtime the guard just checked.
+
 ## Create a new project
 
 ```bash

package/docs/health.md

@@ -271,6 +271,25 @@ What a check returns to describe its own state. A check may also return nothing
 | `message` | `string`                       | Optional human-readable detail.                         |
 | `meta`    | `Record<string, unknown>`      | Optional structured metadata surfaced in the report.    |
 
+### Types
+
+| Type                   | What it is                                                                  |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `HealthStatus`         | `"ok" \| "degraded" \| "down"` — what one check, and the aggregate, report. |
+| `HealthCheckReport`    | One check's result: its name, status, duration, and any message.            |
+| `HealthConfigShape`    | What `HealthConfig()` accepts.                                              |
+| `ResolvedHealthConfig` | The same after defaults are filled in — what the endpoint actually reads.   |
+
+### The doctor's own types
+
+`zt doctor` is extensible: a provider contributes checks through `doctorChecks()`, and
+`runDoctor(app)` runs them all. A check returns a `DoctorCheckResult` — `ok`, `warn` or `fail`,
+with a message and the `fix` printed under it — and the report is `DoctorReportEntry[]`, each
+pairing a check with what it found.
+
+A `fail` refuses a deploy; a `warn` does not. Choose deliberately: a check that warns about
+something fatal is ignored, and one that fails on something conditional gets worked around.
+
 ## Next steps
 
 - [Telemetry](/docs/telemetry) — collect the metrics behind your readiness checks.