@zerotal/arch 1.8.1 → 1.10.0

package/docs/helpers.md

@@ -214,6 +214,105 @@ singularize("people"); // 'person'
 tableNameFor("BlogPost"); // 'blog_posts'
 ```
 
+## Sharing helpers with the browser — `zerotal/shared`
+
+Importing `zerotal` into a client bundle drags the server in behind it. So the helpers that
+have no server in them are also published on their own entry point:
+
+```tsx
+// resources/js/pages/Trips/Index.tsx — a browser bundle
+import { pluralize, formatMoney, Str } from "zerotal/shared";
+```
+
+Everything reachable from `zerotal/shared` is pure — no `node:` imports, no `Bun` globals, no
+config, no container, no request context. Importing it pulls in these functions and nothing
+else, and a test in the framework's own suite bundles the entry point for the browser to keep
+that true.
+
+It carries `pluralize`, `singularize`, `snakeCase`, `camelCase`, `tableNameFor`, the whole
+`Str` namespace, and the formatters below.
+
+**Why it matters more than convenience.** Without it, a page that needs `pluralize` gets a
+second implementation written by hand — and the second copy is always the worse one, because
+the irregulars and the inflect-only-the-last-word rule are exactly what someone re-deriving
+it leaves out. `pluralize("supplier line")` is `"supplier lines"`; the naive rule gives
+`"suppliers line"`. One import removes the divergence rather than managing it.
+
+### Formatting both sides can agree on
+
+`Intl` is in both runtimes and does the work; the risk is that a server helper and a browser
+helper make the same decision twice. A total that reads `R 39 147` on screen and `R39,147.00`
+on the invoice looks like two different numbers to the person paying it.
+
+```typescript
+import { formatMoney, formatNumber, formatDate } from "zerotal/shared";
+
+// Minor units by default — how a column that must not lose a cent stores it.
+formatMoney(3_914_700, { currency: "ZAR", locale: "en-ZA" });
+formatMoney(39_147, { currency: "USD", locale: "en-US", minorUnits: false });
+
+formatNumber(39147.5, { locale: "en-GB", maximumFractionDigits: 1 }); // '39,147.5'
+
+formatDate("2026-08-28T21:30:00Z", { locale: "en-ZA", timeZone: "Africa/Johannesburg" });
+```
+
+Pass `locale` explicitly wherever the two sides must match. Left off, it is the machine's on
+the server and the reader's in the browser, and those are not the same. Pass `timeZone` for
+the same reason: a machine on UTC and a reader in Cape Town disagree about which _day_ an
+11pm booking happened on, and that is the shape the bug takes.
+
+Each formatter takes its own options interface, all extending `FormatOptions` (which carries
+`locale`):
+
+| Interface       | Used by        | Adds                                                                   |
+| --------------- | -------------- | ---------------------------------------------------------------------- |
+| `FormatOptions` | — (the base)   | `locale`                                                               |
+| `MoneyOptions`  | `formatMoney`  | `currency` (required), `minorUnits` (default `true`), `fractionDigits` |
+| `NumberOptions` | `formatNumber` | `minimumFractionDigits`, `maximumFractionDigits`                       |
+| `DateOptions`   | `formatDate`   | `dateStyle`, `timeStyle`, `timeZone`                                   |
+
+`formatDate` returns an empty string for an unparseable value rather than `Invalid Date`, so
+a bad timestamp renders as a blank rather than as words in the middle of a page.
+
+## Outbound HTTP — Http
+
+`Http` is the fluent client for calling another service. It is `fetch` with the things you would
+otherwise write around every call — auth, timeout, retry, JSON — already there, and one place to
+intercept in a test:
+
+```typescript fragment
+import { Http } from "zerotal/http";
+
+const response = await Http.withToken(apiKey).timeout(5_000).retry(3).post("/charges", { amount });
+
+if (response.ok) {
+  const charge = await response.json<{ id: string }>();
+}
+```
+
+Every verb — `get`, `post`, `put`, `patch`, `delete`, `head` — returns a `PendingRequest`, which
+is awaitable _and_ chainable: `withHeaders`, `withToken`, `withBasicAuth`, `acceptJson`,
+`timeout`, `retry`, `withJson`, `withFormData`. Awaiting it gives an `HttpClientResponse` with
+`status`, `ok`, `headers`, `json()`, `text()` and `blob()`.
+
+**A failed response is not a thrown error by default.** A 404 is an answer, and an integration
+that treats every non-2xx as an exception cannot tell "no such customer" from "the service is
+down". Call `.throw()` on the response when you do want the non-2xx to raise — it throws
+`HttpClientError`, which carries the response so a handler can still read the status.
+
+```typescript fragment
+// Let a 404 be a value, and anything else be a problem.
+const response = await Http.get(`/customers/${id}`);
+if (response.status === 404) return null;
+return response.throw().json<Customer>();
+```
+
+In tests, `Http.fake()` intercepts all of it — see [Mocking](/docs/testing/mocking#outbound-http).
+
+`Http` is a class rather than a facade, so a request is made with the same import everywhere.
+`QueryInput` is what a query object may hold, and `PaginatedData` the shape of a paginated body
+when the other end returns one.
+
 ## Objects — deepMerge
 
 Recursively merge an override object onto a base, lodash-style: nested plain
@@ -294,6 +393,57 @@ matches how you want overrides to behave.
 > configured `driver`) are replaced by reference — they keep their prototype and are
 > never merged into.
 
+### `definedOnly` and `Resolved<T>` — merging a shallow options bag
+
+Every public option shape in the framework declares its optional properties as
+`?: T | undefined`, so that the most ordinary thing there is compiles under the
+`exactOptionalPropertyTypes` the generated `tsconfig.json` turns on:
+
+```typescript
+// in a controller
+import { Media } from "zerotal/media";
+
+await Media.store(file, { collection: request.input("collection") ?? undefined });
+```
+
+That flexibility moves a problem to the merge. **Object spread copies own properties
+even when their value is `undefined`**, so `{ ...DEFAULTS, ...options }` lets an
+explicitly-`undefined` field overwrite a default rather than leave it standing —
+which is how a `pingInterval` of `undefined` once became `setInterval(fn, 0)` and
+~830 pings a second. `definedOnly` is the fix: it drops the keys whose value is
+`undefined`, so "supplied as undefined" reads as "not supplied".
+
+```typescript fragment
+// in a class that takes options
+const merged = { ...DEFAULTS, ...definedOnly(options) };
+```
+
+`deepMerge` already does this for you — it skips `undefined` overrides at every
+depth — so `definedOnly` is for the shallow case where a spread is all you need.
+
+`Resolved<T>` is the type of what comes out. **`Required<T>` is not the same thing**,
+and that is the trap: `-?` removes the optionality a `?` introduced, but it does not
+remove an `undefined` written into the type. So `Required<MediaOptions>` still hands
+back `string | undefined` for a `collection?: string | undefined`, and a "defaults
+have been applied" type quietly stops meaning that.
+
+```typescript fragment
+// in a class that takes options
+interface Options {
+  retentionDays?: number | undefined;
+  storage?: string | undefined;
+}
+
+// Required<Pick<Options, "retentionDays">>  →  { retentionDays: number | undefined }  ✗
+// Resolved<Pick<Options, "retentionDays">>  →  { retentionDays: number }              ✓
+private readonly _opts: Resolved<Pick<Options, "retentionDays">> &
+  Omit<Options, "retentionDays">;
+```
+
+`Omit` rather than `& Options` for the rest: intersecting with the whole shape puts
+the optional declaration of each resolved field back alongside the required one, so
+the field reads as possibly `undefined` in the very code that just gave it a default.
+
 ## Fluent wrappers
 
 ### fluent

package/docs/i18n.md

@@ -509,6 +509,11 @@ res.assertSee("Votre panier est vide");
 
 See [Configuration](#configuration) for the `config/i18n.ts` fields.
 
+## Types
+
+`LocaleResolver` decides the locale for a request — the header, a route param, or the signed-in
+user's preference. `TranslatorOptions` configures the translator itself.
+
 ## Next steps
 
 - [Validator](/docs/validator) — pair form validation with translated messages.

package/docs/inertia/middleware.md

@@ -50,6 +50,50 @@ would just register it twice (and `useOnce` guards against that anyway).
 > the authenticated user is always populated by the time props are built; you don't
 > need to hand-order `InertiaMiddleware` relative to auth.
 
+## Which redirects are covered
+
+**All of them.** `useOnce()` registers `InertiaMiddleware` as _global_ middleware, so it
+runs on every request the app serves — however that route declared its own middleware,
+whether as an array, a map form (`{ ALL, POST }`), a group, or nothing at all. There is
+no route that reaches a controller without passing through it, so there is no redirect
+it does not mark.
+
+This is worth stating plainly because the opposite belief is expensive. An app that
+thinks some routes miss the middleware writes its own global `InertiaRedirectMiddleware`
+to cover them, and then cannot tell whether it is still needed: removing it leaves every
+test green either way, because the tests assert a status and a `Location` and those were
+never the part that broke.
+
+Three things have to be true for the Inertia client to follow a redirect, and the
+middleware guarantees all three:
+
+|                                                                              | Set on                                                                             |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| A redirect status — `303` after a non-GET, so the browser follows with `GET` | every Inertia redirect                                                             |
+| `Location`                                                                   | your handler; carried through untouched, along with `Set-Cookie`                   |
+| `X-Inertia: true`                                                            | **every** Inertia redirect, including one your handler already returned as a `303` |
+
+That last row is the one that was wrong before 1.8.0: the marker was set inside the
+302→303 conversion, so a handler doing the protocol-correct thing already —
+`http.redirect(to, 303)` — skipped the only line that marked the response as Inertia's.
+The request succeeded, the row was written, and the form sat there with its fields still
+filled in.
+
+### Pinning it from a test
+
+`assertRedirect` checks the two headers that were never the problem. `assertInertiaRedirect`
+checks all three:
+
+```typescript fragment
+// tests/Feature/OrdersTest.ts
+const res = await app.post("/orders", data, { headers: { "X-Inertia": "true" } });
+
+res.assertInertiaRedirect("/orders/1");
+```
+
+Send the request with the `X-Inertia` header, or there is nothing to assert — a redirect
+to a browser that is not running Inertia is just a redirect.
+
 ## Asset versioning
 
 The asset version is a string sent as part of every page object. When it changes, the

package/docs/inertia/props.md

@@ -25,6 +25,70 @@ import { Inertia } from "@zerotal/inertia";
 > `defer()` loads after first paint; `merge()`/`scroll()` combine new data with what
 > the client already has.
 
+## Page props are page source
+
+**A page receives a projection chosen by its route, never a model — unless that model has
+declared which of its columns are safe to publish.**
+
+Everything you hand to `inertia()` is serialised into the HTML document, or returned as JSON
+on an XHR visit. Anyone who views source reads all of it. That is how the protocol works, and
+it is fine right up to the moment a model goes through it:
+
+```ts fragment
+// in a controller
+return inertia("Trips/Show", { trip }); // ← every column of the row, in the page
+```
+
+`trip.toJSON()` ships the whole row. If that row has an internal cost, a margin, a supplier
+reference or a note somebody left about the customer, all of it is now on the customer's own
+screen. Nothing fails, nothing logs, and the page looks right. This is the one mistake on this
+page that does not announce itself.
+
+### Declare the boundary at the model
+
+The ORM's `hidden` and `visible` lists are honoured by `toJSON()`, which is exactly what
+serialises a prop — so declaring them once at the model covers every route that ever passes it:
+
+```ts fragment
+import { Model, type Columns } from "zerotal/orm";
+
+class Trip extends Model {
+  // Never leaves the server, whoever passes this model to whatever page.
+  static hidden: Columns<Trip>[] = ["cost_cents", "markup_percent", "internal_notes"];
+}
+```
+
+`visible` is the allow-list form and takes precedence: state the columns a page may have, and a
+column added to the table later is private by default rather than published by default.
+
+In development, passing a model that declares neither list writes a warning naming the model and
+the number of fields it is about to publish. It fires once per model class and goes quiet as soon
+as either list exists.
+
+### When a route needs its own shape
+
+A `hidden` list is one decision for the whole app. Where two audiences need different columns of
+the same model, project per route and keep the dangerous fields out of the client-facing shape
+entirely:
+
+```ts fragment
+// in a controller
+function forCustomer(trip: Trip) {
+  return { id: trip.id, title: trip.title, total_cents: trip.total_cents };
+}
+
+function forOps(trip: Trip, options: { showCost: boolean }) {
+  return {
+    ...forCustomer(trip),
+    // Absent, not zeroed. A zero looks like a fact; a missing key cannot be misread.
+    ...(options.showCost ? { cost_cents: trip.cost_cents } : {}),
+  };
+}
+```
+
+Prefer omitting a field over blanking it. A `cost_cents: 0` in page source reads as "this trip
+cost us nothing", and somebody will eventually believe it.
+
 ## Partial reloads
 
 On a visit to the _same page_, the client can request a subset of props with `only` / `except`.
@@ -501,6 +565,12 @@ still override one, and no page is forced to pass it.
 - **Before you rebuild the registry**, every name and every prop bag compiles, as
   it always did.
 
+## Types
+
+`PageObject` is what Inertia serialises into the page — component, props, url and version.
+`MergeConfig` and `ScrollConfig` configure `merge()` and `scroll()`, and `PaginatorLike` is what
+`scroll()` accepts from a paginator so the ORM's own and a hand-built one both work.
+
 ## Next steps
 
 - [Inertia overview](/docs/inertia) — the guide's front page and the rest of the sections.

package/docs/inertia/ssr.md

@@ -75,27 +75,112 @@ export class PostController {
 ### Requirements
 
 - `react-dom/server` ≥ 18 (for `renderToReadableStream`)
+- `@inertiajs/react` — the same adapter the browser entry point uses; the server
+  renders through its `<App>` so `<Head>` works (see below)
 - The HTML template must contain `<!-- @inertia -->`
 - The page component must exist under your pages directory (`resources/js/pages/<component>.tsx`)
 
-It throws if the template hasn't loaded, or if the component name contains path
-traversal (`..` or a leading `/`).
-
 ### inertia vs. inertiaStream
 
-| Criterion      | `inertia()`            | `inertiaStream()`                  |
-| -------------- | ---------------------- | ---------------------------------- |
-| Return type    | `Promise<void>`        | `Promise<void>`                    |
-| Rendering      | Buffered HTML string   | Streaming `renderToReadableStream` |
-| Response body  | Fully buffered string  | Streaming `ReadableStream`         |
-| TTFB           | After full render      | After the prefix is flushed        |
-| XHR navigation | JSON (the normal path) | N/A — only the first-page document |
+| Criterion      | `inertia()`              | `inertiaStream()`                  |
+| -------------- | ------------------------ | ---------------------------------- |
+| Return type    | `Promise<void>`          | `Promise<void>`                    |
+| Rendering      | None — empty root + JSON | Streaming `renderToReadableStream` |
+| Response body  | Fully buffered string    | Streaming `ReadableStream`         |
+| TTFB           | Immediate                | After the shell is ready           |
+| Page `<Head>`  | Client only              | Collected into the served `<head>` |
+| XHR navigation | JSON (the normal path)   | N/A — only the first-page document |
 
 For XHR navigations (`X-Inertia: true`), keep using `inertia()` — streaming only
 benefits the initial HTML document load.
 
 > **Tip** — Stream the heaviest landing pages and leave everything else on `inertia()`.
 
+## Page metadata: `<Head>` on the server
+
+Both server-rendered paths — `inertiaStream()` and the `/__ssr` endpoint — collect
+whatever your page's `<Head>` declares and splice it into the template's `<head>`
+before the response goes out. A page writes its metadata once, in the component, and
+gets it in the HTML as well as in the browser:
+
+```tsx fragment
+// resources/js/pages/Trips/Show.tsx
+import { Head } from "@inertiajs/react";
+
+export default function Show({ trip }) {
+  return (
+    <>
+      <Head>
+        <title>{trip.name}</title>
+        <meta name="description" content={trip.summary} />
+        <meta property="og:title" content={trip.name} />
+        <meta property="og:image" content={trip.heroUrl} />
+      </Head>
+      …
+    </>
+  );
+}
+```
+
+An injected tag **replaces** the template's tag of the same identity rather than
+being added after it — `<title>` by being a title, `<meta>` by its `name` or
+`property`. That is not a detail: a document with two `<title>` tags is a document
+with the _first_ one, so an appended title would be present, correct and ignored.
+Anything the template does not already declare is appended before `</head>`.
+
+Two things it does not do:
+
+- **The title callback is client-side.** `createInertiaApp({ title })` in your
+  browser entry point is not visible to the server, so a page rendering
+  `<Head><title>Kruger</title></Head>` serves `Kruger` and the browser then shows
+  `Kruger — App`. Put the suffix in the `<Head>` itself if the served title matters
+  to you, which for a link preview it usually does.
+- **`inertia()` does not render, so it does not collect.** A page returned through
+  plain `inertia()` sends the template's `<head>` as written. See
+  [What a crawler sees](#what-a-crawler-sees).
+
+## What a crawler sees
+
+`inertia()` — the default — **does not server-render the component at all.** Its
+response body is the template with an empty root and the page object beside it:
+
+```html
+<body>
+  <div id="app"></div>
+  <script type="application/json" data-page="app">
+    { … }
+  </script>
+</body>
+```
+
+That is the normal Inertia arrangement and it is the right default: the page is
+built by the client, and every navigation after the first is JSON. But it means the
+served document contains **a title and a JSON blob**, and it is worth knowing which
+readers of your site run JavaScript and which do not:
+
+| Reader                                               | Runs JavaScript       | Sees your page    |
+| ---------------------------------------------------- | --------------------- | ----------------- |
+| A browser                                            | yes                   | yes               |
+| Googlebot, Bingbot                                   | yes, on a second pass | yes, later        |
+| WhatsApp, Slack, iMessage, X, Facebook link previews | **no**                | title + meta only |
+| `curl`, uptime checks, most RSS and reader tools     | **no**                | title + meta only |
+
+So the link preview a page produces is decided entirely by its `<head>` — which is
+the template's, identically, on every page, unless you do one of these:
+
+1. **Switch the page to `inertiaStream()`.** The component is rendered, `<Head>` is
+   collected, and the served `<head>` is the page's own. This is the smallest change
+   and the one to reach for on pages that get shared.
+2. **Turn on endpoint SSR** (`ssr: true`) for the whole app.
+3. **Set the tags in middleware**, if the metadata is server-side data the component
+   does not otherwise need.
+
+`curl` is also how most people first check whether a deploy worked. An empty
+`<div id="app">` in that output is not a broken deploy.
+
+It throws if the template hasn't loaded, or if the component name contains path
+traversal (`..` or a leading `/`).
+
 ## Next steps
 
 - [Inertia overview](/docs/inertia) — the guide's front page and the rest of the sections.

package/docs/lock.md

@@ -447,6 +447,21 @@ sees an isolated, deterministic lock table with no network or file I/O.
 | `exists()`       | `exists(key: string): Promise<boolean>`                                     | `true` if the lock is currently held.               |
 | `dispose?()`     | `dispose?(): void`                                                          | Release background resources (timers, connections). |
 
+### Types
+
+| Type                | What it is                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `LockedCallback<T>` | What `try` and `block` run while holding the lock.                                 |
+| `TryOptions`        | `try`'s options — the TTL and whether a failure throws or returns.                 |
+| `RefreshOptions`    | How a long-running hold extends its own TTL rather than letting it lapse mid-work. |
+
+The three built-in drivers are exported under their own names, so a custom driver can wrap one
+rather than reimplement it: `MemoryLockDriver` (single process — the default, and wrong the
+moment there are two), `SqliteLockDriver` (a file every process on the box can see) and
+`RedisLockDriver` (across machines).
+
+Picking the wrong one fails in the way locks always do: not at all, until there are two workers.
+
 ## Next steps
 
 - [Scheduler](/docs/scheduler#preventing-overlapping-runs) — `withoutOverlapping` builds on the same idea for cron tasks.

package/docs/logger.md

@@ -171,6 +171,44 @@ export default LoggingConfig({
 });
 ```
 
+### Writing your own channel
+
+A channel is one method. Implement `LogChannel` and register it as a driver when the five
+built-ins do not reach where you need entries to go — a hosted log service, a socket, a table:
+
+```typescript
+import type { LogChannel, LogEntry } from "zerotal/logger";
+
+class WebhookChannel implements LogChannel {
+  constructor(private readonly url: string) {}
+
+  async write(entry: LogEntry): Promise<void> {
+    // Failures are swallowed on purpose: a logging sink that throws turns a
+    // warning into an outage, and the entry it was carrying is lost either way.
+    await fetch(this.url, { method: "POST", body: JSON.stringify(entry) }).catch(() => {});
+  }
+}
+```
+
+The built-ins implement the same interface and are exported, so a custom channel can wrap one
+rather than reimplement it — `StackChannel` is itself only a fan-out over other channels.
+
+### Types
+
+| Type            | What it is                                                                     |
+| --------------- | ------------------------------------------------------------------------------ |
+| `LogLevel`      | `"debug" \| "info" \| "warn" \| "error" \| "fatal"` — the severity ladder.     |
+| `LogEntry`      | One record: level, message, context, scope, timestamp, and any captured error. |
+| `LogChannel`    | The one-method sink contract: `write(entry): Promise<void>`.                   |
+| `BoundLogger`   | A logger pinned to a channel and/or a fixed context bag.                       |
+| `ChannelConfig` | The discriminated union of the five driver configs below.                      |
+| `LoggerOptions` | What `LoggingConfig()` accepts.                                                |
+| `TableData`     | Rows for `Log.table()`.                                                        |
+
+The five built-in channels are exported under their own names — `ConsoleChannel`,
+`SingleChannel`, `DailyChannel`, `StackChannel`, `NullChannel` — each matching the `driver`
+value in the table above.
+
 ## The Log facade
 
 `Log` is a static proxy over the `LogManager` singleton. Use it anywhere —

package/docs/middleware.md

@@ -206,6 +206,37 @@ The package ships several middleware you can drop straight into `app.use([...])`
 or a route's middleware array. Each extends `BaseMiddleware`, so `.with({ … })`
 bakes options into a zero-argument class.
 
+### Names the framework already occupies
+
+Middleware live in a flat namespace: your `app/middleware/` classes are discovered by
+class name, and so are the ones a package exports. Naming one of yours after one of
+these is not caught as a conflict — it surfaces later as a type error somewhere that
+does not mention either file, which is a confusing way to learn that
+`TwoFactorMiddleware` was taken.
+
+The full list, so you can check before you name:
+
+| Middleware                                                                             | Package                          |
+| -------------------------------------------------------------------------------------- | -------------------------------- |
+| `CorsMiddleware`, `SecureHeadersMiddleware`, `ThrottleMiddleware`, `WebhookMiddleware` | `@zerotal/core`                  |
+| `AuthMiddleware`, `GuestMiddleware`, `PersistUserMiddleware`, `RememberMeMiddleware`   | `@zerotal/auth`                  |
+| `BasicAuthMiddleware`, `BearerTokenMiddleware`, `JwtGuardMiddleware`                   | `@zerotal/auth`                  |
+| `RequireRoleMiddleware`, `RequirePermissionMiddleware`, `TwoFactorMiddleware`          | `@zerotal/auth`                  |
+| `ValidateSignatureMiddleware`                                                          | `@zerotal/auth`                  |
+| `SessionMiddleware`, `CsrfMiddleware`, `AuthSessionMiddleware`                         | `@zerotal/session`               |
+| `InertiaMiddleware`, `PrecognitionMiddleware`                                          | `@zerotal/inertia`               |
+| `AdminGuardMiddleware`, `AdminAbilityMiddleware`                                       | `@zerotal/admin`                 |
+| `MonitorAuthMiddleware`, `MonitorPayloadMiddleware`                                    | `@zerotal/monitor`               |
+| `IdempotencyMiddleware`                                                                | `@zerotal/cache`                 |
+| `LocaleMiddleware`                                                                     | `@zerotal/i18n`                  |
+| `EnsureTenancyMiddleware`                                                              | `@zerotal/tenancy`               |
+| `TelemetryMiddleware`                                                                  | `@zerotal/telemetry`             |
+| `BaseMiddleware`                                                                       | `@zerotal/core` (the base class) |
+
+If yours does something different from the framework's, say so in the name rather
+than shadowing it — `RequireTwoFactorMiddleware` for "fence the console until staff
+have enrolled" reads better than `TwoFactorMiddleware` anyway, and cannot collide.
+
 ### CorsMiddleware
 
 ```ts fragment

package/docs/migrations.md

@@ -81,6 +81,13 @@ bun zt migrate:rollback
 bun zt migrate:status
 ```
 
+`bun zt doctor` warns when migrations on disk have not run, and names them. It is a warning
+rather than a failure — pending migrations are the ordinary state of a checkout that just
+pulled — but it is the cheapest moment to hear about them: the alternative is finding out from
+a request that fails with `no such table`, an error whose stack is entirely framework frames.
+The [development error page](/docs/errors#missing-tables-and-columns) answers the same question
+after the fact, and can run them for you.
+
 `migrate --fresh`, `migrate:fresh` and `migrate:refresh` all do the same thing:
 roll everything back through each migration's `down()`, then re-run from scratch.
 `migrate:refresh` exists because that is the name the command has elsewhere,
@@ -521,6 +528,46 @@ test("backfills a slug for every existing post", async () => {
 | `hasTable`          | `hasTable(table: string): Promise<boolean>`                        | Whether a table exists.               |
 | `hasColumn`         | `hasColumn(table: string, column: string): Promise<boolean>`       | Whether a column exists.              |
 
+### Types
+
+The builders a migration's `up()` receives, and the shapes they take:
+
+| Type                     | What it is                                                                         |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| `ColumnBuilder`          | What every `table.string(…)` returns — the chain that adds modifiers.              |
+| `ColumnOptions`          | Length, precision and the other per-type settings a column accepts.                |
+| `ColumnShorthand`        | The short forms (`"string"`, `"integer"`, …) accepted where a full builder fits.   |
+| `ForeignIdColumnBuilder` | What `table.foreignId(…)` returns, adding `.constrained()` to the chain.           |
+| `ForeignKeyBuilder`      | The `.references(…).on(…)` chain, and where `onDelete` / `onUpdate` are set.       |
+| `FKAction`               | `"cascade" \| "restrict" \| "set null" \| "no action"` — what a FK does on change. |
+| `TableOptions`           | Table-level settings: engine, charset, and whether it is temporary.                |
+
+### Running migrations yourself
+
+`MigrationRunner` is the class behind `zt migrate`. Reach for it when you need the runner
+somewhere a command cannot go — a test harness, a deploy script, a tenant provisioner that
+migrates a database it has just created:
+
+```typescript fragment
+import { MigrationRunner } from "@zerotal/orm";
+
+const runner = new MigrationRunner({ connection });
+const ran = await runner.run(entries); // names of the migrations applied
+const status = await runner.status(entries); // ran / pending, per migration
+```
+
+| Type              | What it is                                                                 |
+| ----------------- | -------------------------------------------------------------------------- |
+| `MigrationEntry`  | One migration handed to the runner: its name and its instance.             |
+| `MigrationRecord` | A row of the `migrations` table — name, batch, and when it ran.            |
+| `MigrationStatus` | What `status()` reports per migration: whether it ran, and in which batch. |
+| `MigrationError`  | Thrown when a migration fails, carrying which one and what it was doing.   |
+
+`runner.willRollBackOnFailure` says whether this engine has transactional DDL. On MySQL it is
+false — every DDL statement implicitly commits, so a migration that fails part-way leaves the
+half that succeeded. `zt migrate` warns about this before it starts, while taking a backup is
+still an option.
+
 ## Next steps
 
 - [ORM](/docs/orm) — the models your migrations build tables for.