@zerotal/arch 1.8.1 → 1.9.0

package/docs/config-system.md

@@ -42,6 +42,45 @@ const apiKey = env("API_KEY"); // no fallback → string | undefined
 
 > **Note** — When you need a value to be present, use `requireEnv("APP_KEY")` instead — it throws a `ConfigError` at boot if the variable is unset, rather than returning `undefined`.
 
+### Declaring the whole environment — `EnvSchema`
+
+`env()` is per-call and forgiving: an unset variable is `undefined` and you find out where it is
+used. `@zerotal/core/env` is the other end — declare every variable the app reads, once, and the
+boot either produces a fully typed frozen object or fails with every problem listed at the same
+time:
+
+```typescript fragment
+// env.ts
+import { EnvSchema, t } from "@zerotal/core/env";
+
+export const env = EnvSchema.define({
+  APP_KEY: t.string().min(32),
+  PORT: t.port().default(3000),
+  DATABASE_URL: t.string(),
+  LOG_LEVEL: t.enum(["debug", "info", "warn", "error"]).default("info"),
+  SENTRY_DSN: t.url().optional(),
+});
+
+env.PORT; // number — never undefined, because it has a default
+env.LOG_LEVEL; // "debug" | "info" | "warn" | "error", narrowed to the literals
+```
+
+**It reports every failure at once.** A schema with three missing variables fails the boot
+naming all three, rather than one per restart — which is the difference between one fix and
+three round trips through a deploy. The failure is an `EnvSchemaError` carrying an
+`EnvFieldError` per field.
+
+| Type             | What it is                                                                  |
+| ---------------- | --------------------------------------------------------------------------- |
+| `EnvSchemaError` | The boot failure, listing every field that did not validate.                |
+| `EnvFieldError`  | One field's problem: which variable, and what was wrong with it.            |
+| `FieldType`      | The builders `t` offers — string, number, boolean, port, url, enum.         |
+| `EnvOutput<S>`   | The typed object a schema produces. `typeof env` where you need to pass it. |
+| `InferDef<D>`    | The type one field definition resolves to.                                  |
+
+Use `env()` for a value read in one place and `EnvSchema` for the set an app cannot start
+without. They coexist; the schema is not a replacement for the helper.
+
 ## Config files
 
 Config files live in `config/`. Each file exports a typed object via a package helper:
@@ -250,6 +289,21 @@ if (config("app.env") === "production") {
 | `ConfigLoader.get`      | `get(key: string, fallback?): value`                       | Dot-path read against the loaded map.                                                     |
 | `ConfigLoader.validate` | `validate(): this`                                         | Run each file's optional `validate(config)` export, throwing on failure.                  |
 
+## Types
+
+| Type                | What it is                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `ConfigValidator`   | What `registerConfigValidator` takes — a function handed the config, reporting issues. |
+| `ConfigIssue`       | One finding: its namespace, message, and level.                                        |
+| `ConfigIssueLevel`  | Whether an issue refuses a production boot or is only worth reading.                   |
+| `ConventionsConfig` | The `conventions` namespace — where the framework looks for models, jobs and the rest. |
+| `AppTlsConfig`      | TLS settings under `app.tls`.                                                          |
+| `AssetLoaderKind`   | How an asset is loaded by the build — the `loader` values `assets.loaders` accepts.    |
+
+A validator reporting a **fatal** issue refuses a production-like boot rather than warning. That
+is the whole point of the level: an app that boots with a broken configuration serves wrong
+answers rather than failing, and the failure is the cheaper outcome.
+
 ## Next steps
 
 - [Conventions](/docs/conventions) — the auto-discovery settings under the `conventions` key.

package/docs/cookies.md

@@ -93,6 +93,12 @@ You rarely set cookies by hand — two parts of the framework manage their own:
   (non-`HttpOnly`) cookie after every request so Axios/Inertia can echo it back as
   the `X-XSRF-TOKEN` header.
 
+## Types
+
+`CookieOptions` is what every cookie-setting call accepts — `maxAge`, `path`, `domain`,
+`httpOnly`, `secure`, `sameSite`. It is exported so a helper that sets a cookie in more than one
+place can take the same shape.
+
 ## Next steps
 
 - [Session](/docs/session) — signed, `HttpOnly` cookie-backed state (the usual choice).

package/docs/deployment.md

@@ -63,18 +63,45 @@ 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. It
+cannot know that this workspace has no cancellation policy, that mail is still wired to the
+`log` driver so nothing is ever sent, 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,14 +109,16 @@ 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
@@ -180,6 +209,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
@@ -350,6 +427,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 +595,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 +606,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.