@shaferllc/keel 0.68.0 → 0.74.0

package/llms-full.txt

@@ -1547,6 +1547,80 @@ string. Pass a fallback of the type you expect and the type follows it.
 Use `env()` **only inside config files**, not scattered through your app. That
 keeps all environment coupling in one layer.
 
+## Validating the environment
+
+`env("DATABASE_URL")` hands back whatever is — or isn't — in `process.env`. A
+missing variable is `undefined`, the app boots looking perfectly healthy, and then
+dies on the first request that actually needs it. In production. At night.
+
+`defineEnv()` checks the whole environment **at boot** and refuses to start
+otherwise:
+
+```ts
+// config/env.ts
+import { defineEnv, envVar } from "@shaferllc/keel/core";
+
+export const env = defineEnv({
+  APP_KEY: envVar.string({ required: true, description: "32+ random characters" }),
+  PORT: envVar.number({ default: 3000 }),
+  NODE_ENV: envVar.enum(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: envVar.url({ required: true }),
+  SENTRY_DSN: envVar.string(), // optional
+});
+```
+
+```ts
+env.PORT; // number — not "3000"
+env.NODE_ENV; // "development" | "test" | "production" — not string
+env.SENTRY_DSN; // string | undefined
+```
+
+The types are **inferred from the rules**. A `number` rule gives you a `number`; an
+`enum` gives you the union, not `string`; anything optional without a default is
+`| undefined`, so you can't forget to handle it.
+
+### It reports every problem at once
+
+```
+The environment is not valid:
+
+  • APP_KEY is required but not set (32+ random characters).
+  • PORT must be a number, got "eighty".
+  • NODE_ENV must be one of development, test, production, got "staging".
+  • DATABASE_URL must be a valid URL, got "not a url".
+
+Set these in your .env (or your host's environment) and start again.
+```
+
+Not the first problem — **all** of them. Fixing a deploy one missing variable per
+restart is its own small hell.
+
+### Rules
+
+| Rule | Value | Notes |
+|------|-------|-------|
+| `envVar.string()` | `string` | |
+| `envVar.number()` | `number` | rejects `"eighty"` |
+| `envVar.boolean()` | `boolean` | accepts `true/false/1/0/yes/no/on/off` |
+| `envVar.enum([...])` | the union | typed as the literal union |
+| `envVar.url()` | `string` | must parse as a URL — catches a truncated connection string |
+
+Each takes `required`, `default`, `description` (shown in the error, so they know
+what to set), and `validate` for anything else:
+
+```ts
+APP_KEY: envVar.string({
+  required: true,
+  validate: (value) => (value.length >= 32 ? true : "must be at least 32 characters"),
+});
+```
+
+**An empty string counts as absent.** `PORT=` in a `.env` file is a typo, not a
+deliberate empty port.
+
+The returned object is frozen, so nothing can quietly reassign your config at
+runtime.
+
 ## Config files
 
 Each file in `config/` exports a default object and is loaded under its
@@ -4414,6 +4488,131 @@ output.
 
 
 
+---
+
+<!-- source: docs/api-resources.md -->
+
+# API Resources
+
+`apiResource(router, Model, options)` generates a full CRUD REST API from a Keel
+[model](./models.md) — the [Remult](https://remult.dev) idea done the Keel way:
+explicit, server-side, and composed from pieces you already have. It's imported
+from `@shaferllc/keel/api`.
+
+```ts
+import { apiResource } from "@shaferllc/keel/api";
+import { Post } from "../app/Models/Post.js";
+import { z } from "zod";
+
+export default function routes(router) {
+  apiResource(router, Post, {
+    filter: ["status", "authorId"],
+    sort: ["createdAt", "title"],
+    body: z.object({ title: z.string(), body: z.string(), status: z.string() }),
+    access: { read: true, write: (c) => isEditor(c) },
+  });
+}
+```
+
+That registers five routes:
+
+| Method | Path | Action |
+|--------|------|--------|
+| `GET` | `/posts` | list (filtered, sorted, paginated) |
+| `GET` | `/posts/:id` | read one |
+| `POST` | `/posts` | create |
+| `PUT` / `PATCH` | `/posts/:id` | update |
+| `DELETE` | `/posts/:id` | delete |
+
+They're real routes, so [`@shaferllc/keel/openapi`](./openapi.md) documents them
+automatically, and writes go through the model's mass-assignment guard and your
+Zod schema.
+
+## Access is deny-by-default
+
+An auto-generated API that's open by default is a footgun. Every action whose
+access you don't declare returns **403**. You opt routes open — never shut.
+
+```ts
+access: {
+  read: true,                    // list + read: anyone
+  write: (c) => auth().check(),  // create + update + delete: signed-in only
+}
+```
+
+Rules resolve per action: the action's own key (`list`, `get`, `create`,
+`update`, `delete`), then the `read` / `write` shorthand, then `all`, then denied.
+Each rule is a boolean or a `(c) => boolean | Promise<boolean>` predicate.
+
+## Filtering, sorting, pagination — allow-listed
+
+The list endpoint reads the query string, but **only** columns you allow-list:
+
+- `filter: ["status"]` → `GET /posts?status=published` filters; `?secret=x` is
+  ignored. Nothing reaches SQL unless it's on the list.
+- `sort: ["title", "createdAt"]` → `GET /posts?sort=title,-createdAt` (a `-`
+  prefix is descending); unknown columns are dropped.
+- `GET /posts?page=2&perPage=20` paginates. `perPage` is clamped to `maxPerPage`
+  (default 100) — the guard against "give me everything".
+
+The response is a paginated envelope:
+
+```json
+{ "data": [ … ], "meta": { "total": 42, "perPage": 20, "currentPage": 2, "lastPage": 3 } }
+```
+
+## Row-level security with `scope`
+
+`scope` constrains the base query for **every** row operation — list, read,
+update, delete. A row outside the scope reads as 404, so it can't be fetched,
+changed, or removed:
+
+```ts
+apiResource(router, Post, {
+  access: { read: true, write: true },
+  scope: (q, c) => q.where("authorId", currentUserId(c)), // only your own posts
+});
+```
+
+## Shaping input and output
+
+- **`body` / `createBody` / `updateBody`** — a Zod schema validating writes
+  (a failure is a 422). It also becomes the request-body schema in the OpenAPI
+  docs.
+- **`beforeWrite(data, c, action)`** — mutate the write payload (stamp an owner
+  id, a timestamp) before it's saved.
+- **`transform`** — shape the output: a `(model, c) => …` function, or a Keel
+  [Transformer](./transformers.md) (its `item`/`collection` are used).
+
+## Options reference
+
+| Option | Purpose |
+|--------|---------|
+| `path` | Base path (default: the model's table). |
+| `name` | Route-name prefix (default: the path). |
+| `only` / `except` | Restrict which of the five actions are generated. |
+| `filter` / `sort` | Allow-listed columns for `?filter` and `?sort`. |
+| `perPage` / `maxPerPage` | Page-size default and ceiling. |
+| `body` / `createBody` / `updateBody` | Write validation schemas. |
+| `access` | Per-action access rules (deny by default). |
+| `scope` | Row-level query constraint for every operation. |
+| `transform` | Output shaping. |
+| `beforeWrite` | Mutate the payload before save. |
+| `tags` | OpenAPI tags for the routes. |
+
+Global pagination defaults live in `config/api.ts` (register the optional
+`ApiServiceProvider`, then `keel vendor:publish --tag api-config`).
+
+## What this isn't
+
+Remult also ships an isomorphic, type-safe **frontend** client that shares the
+model with the server. Keel deliberately stops at the server boundary: this
+generates a plain REST API you call however you like (fetch, your Inertia pages,
+a mobile app). That keeps the model server-only and the wire contract explicit —
+and it's exactly the contract the OpenAPI docs describe.
+
+
+
 ---
 
 <!-- source: docs/authentication.md -->
@@ -6606,24 +6805,204 @@ write the stub, confirming with:
 
 Delete the existing file first if you truly mean to regenerate it.
 
-## Adding your own commands
+## Writing your own commands
 
-Commands are defined with [commander](https://github.com/tj/commander.js) in
-[`src/core/cli/index.ts`](../src/core/cli/index.ts). Register a new one on the
-`program`:
+`keel make:command greet` scaffolds `app/Commands/greet.ts`. Everything in
+`app/Commands` is discovered automatically — no registration step.
 
 ```ts
-program
-  .command("cache:clear")
-  .description("Clear the application cache")
-  .action(async () => {
-    const app = await createApplication();
-    // ...your logic, with full access to the container
-  });
+import { defineCommand, arg, flag } from "@shaferllc/keel/core";
+
+export const greet = defineCommand({
+  name: "greet",
+  description: "Greet someone",
+
+  args: { name: arg.string({ description: "who to greet" }) },
+  flags: { loud: flag.boolean({ alias: "l", description: "SHOUT IT" }) },
+
+  async run({ args, flags, ui }) {
+    const message = `Hello, ${args.name}!`;
+    ui.success(flags.loud ? message.toUpperCase() : message);
+  },
+});
+```
+
+```bash
+keel greet Ada --loud     # ✔ HELLO, ADA!
+keel greet --help         # generated usage, args, and options
+```
+
+**`args.name` is a `string` and `flags.loud` is a `boolean` — inferred, not cast.**
+That's the point of declaring them: the parsing is generated from the types, so the
+two can't drift apart. Make an arg optional and its type becomes
+`string | undefined`; give it a default and it's a `string` again.
+
+Commands run with the application booted, so they get the same container, config,
+and providers your HTTP requests do.
+
+### Arguments
+
+Positional, in declaration order. Required by default.
+
+| Builder | Value |
+|---------|-------|
+| `arg.string()` | `string` |
+| `arg.number()` | `number` — rejected with a clear error if it isn't one |
+| `arg.spread()` | `string[]` — swallows the rest; must be last |
+
+Options: `description`, `required: false`, `default`, `parse`.
+
+### Flags
+
+| Builder | Value |
+|---------|-------|
+| `flag.boolean()` | `boolean` — defaults to `false`, so it's never `undefined` |
+| `flag.string()` | `string \| undefined` |
+| `flag.number()` | `number \| undefined` |
+| `flag.array()` | `string[]` — repeatable, defaults to `[]` |
+
+Options: `description`, `alias` (a single letter), `required`, `default`, `parse`.
+
+The parser understands `--flag value`, `--flag=value`, `--no-flag`, `-f value`,
+bundled shorthands (`-lt 5`), and `--`, after which everything is passed through
+untouched in `rest`.
+
+An **unknown flag is an error**, not a shrug — a typo'd `--forse` should tell you,
+not silently do nothing. Set `allowUnknownFlags: true` if a command genuinely needs
+to pass flags on to something else.
+
+### Exit codes
+
+Return a number to set the exit code; return nothing for `0`. A thrown error is
+caught, reported, and exits `1` — a console is a bad place to show a user a stack
+trace because they mistyped a flag. A **usage** error (missing arg, bad flag) prints
+what's wrong *and the command's help*.
+
+## Terminal UI
+
+Every command gets a `ui`:
+
+```ts
+ui.info("Checking…");
+ui.success("Migrated 3 tables");
+ui.warning("Nothing to do");
+ui.error("Failed"); // stderr
+ui.debug("verbose detail");
+
+ui.action("create", "app/Models/User.ts"); // CREATE  app/Models/User.ts
+ui.action("skip", "app/Models/Post.ts", "skipped");
+
+ui.table(["Name", "Rows"]).row(["users", "42"]).row(["orgs", "7"]).render();
+
+ui.sticker(["http://localhost:3000"], "Server running");
+ui.instructions(["cd my-app", "npm install", "keel serve"], "Next steps");
+
+ui.colors("green", "done"); // paint a string yourself
+```
+
+### Tasks
+
+For a command that does several things in a row:
+
+```ts
+await ui
+  .tasks()
+  .add("Install dependencies", async (task) => {
+    task.update("resolving…");
+    return "42 packages";
+  })
+  .add("Run migrations", async () => "3 tables")
+  .run();
+```
+
+It **stops at the first failure**, because the tasks after it almost certainly
+depended on it and a cascade of red tells you nothing new. `run()` resolves to
+`false` if anything failed.
+
+## Prompts
+
+```ts
+const name = await prompt.ask("Project name?", { default: "my-app" });
+const secret = await prompt.secure("API key?");
+const ok = await prompt.confirm("Delete everything?");
+const driver = await prompt.choice("Database?", ["sqlite", "postgres"]);
+const features = await prompt.multiple("Features?", ["auth", "queue", "mail"]);
+```
+
+`ask` re-asks on a failed `validate` rather than dying — a typo shouldn't cost
+someone the whole command. Every prompt takes `default`, `hint`, `validate`, and
+`result`.
+
+## Testing a command
+
+A command that asks questions is normally a command you can't test. So prompts can
+be **trapped**: script the answers up front, and nothing touches the terminal.
+
+```ts
+import { ConsoleKernel, createUi, createPrompt } from "@shaferllc/keel/core";
+
+const ui = createUi({ raw: true }); // buffer the output, drop the colors
+const prompt = createPrompt({ trap: true });
+const kernel = new ConsoleKernel({ ui, prompt }).register(setup);
+
+prompt.trap("Project name?").replyWith("keel-app");
+prompt.trap("Database?").chooseOption(1);
+prompt.trap("Write the config?").accept();
+
+const code = await kernel.run(["setup"]);
+
+assert.equal(code, 0);
+assert.match(ui.logs.join("\n"), /keel-app on postgres/);
+prompt.assertAllTrapsUsed(); // every scripted question was actually asked
+```
+
+An **untrapped prompt throws** instead of hanging. That matters more than it
+sounds: without it, the test would block forever on stdin no test will ever
+provide, and your suite would simply stop — with no failure to read.
+
+A trap can also assert the prompt's own validation:
+
+```ts
+prompt
+  .trap("Email?")
+  .assertFails("", "Email is required")
+  .assertPasses("ada@example.com")
+  .replyWith("ada@example.com");
+```
+
+`ui.logs` and `ui.errors` hold every line written, colorless, so you can assert on
+exactly what the command said.
+
+## The REPL
+
+```bash
+keel repl
+```
+
+An interactive shell with the **application booted** — the container is up, the
+providers have run, and the helpers are in scope:
+
 ```
+keel > await db("users").where("active", 1).get()
+keel > make(Router).all()
+keel > await cache().get("stats")
+keel > .ls        # what's in scope
+keel > .exit
+```
+
+Poking at a model in a REPL is the fastest debugging loop there is, and it
+shouldn't cost you a throwaway script to get one. History persists in
+`.keel_repl_history`.
 
-Because commands boot the application, they get the same container, config, and
-providers your HTTP requests do.
+---
+
+## A note on the built-ins
+
+The commands *above* (`serve`, `routes`, `make:*`, `migrate:*`) still run through
+Keel's original console wrapper, and package-contributed commands do too. Your
+commands — anything in `app/Commands` — run on the system documented here, and take
+precedence over a built-in of the same name. Migrating the built-ins across is
+mechanical and will happen; nothing about the API here changes when it does.
 
 
 
@@ -6869,6 +7248,107 @@ SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
 > matches the current `where` clause — with no `where`, that's the whole table.
 > Always scope a write with `where` unless you truly mean to touch every row.
 
+## Transactions
+
+Two related writes should either both land or neither should. `transaction()`
+commits when your callback returns and **rolls back if it throws**:
+
+```ts
+import { transaction, db } from "@shaferllc/keel/core";
+
+await transaction(async () => {
+  await db("orders").insert(order);
+  await db("stock").where("id", id).decrement("count"); // a throw here undoes the insert
+});
+```
+
+The error still reaches you — it's rethrown after the rollback. Nothing is
+swallowed.
+
+### Queries inside are ambient
+
+You don't have to thread a transaction object through your code. `db()`, models,
+and relations all pick up the open transaction automatically:
+
+```ts
+await transaction(async () => {
+  const user = await User.create({ email }); // the model is in the transaction
+  await user.related("posts").create({ title }); // so is the relation
+  await db("audit").insert({ userId: user.id }); // and the raw builder
+});
+```
+
+That works because the transaction lives in `AsyncLocalStorage`, not a module
+global — so two requests running transactions at the same time can't steal each
+other's connection.
+
+If you'd rather be explicit, the callback gets a handle:
+
+```ts
+await transaction(async (tx) => {
+  await tx.table("orders").insert(order);
+  await tx.write("UPDATE stock SET count = count - 1 WHERE id = ?", [id]);
+});
+```
+
+`tx.rollback()` abandons the transaction without committing. `inTransaction()`
+tells you whether one is open.
+
+### Nesting uses savepoints
+
+A `transaction()` inside another doesn't open a second one — databases don't have
+those. It takes a **savepoint**, so an inner failure rolls back only the inner
+work and the outer transaction carries on:
+
+```ts
+await transaction(async () => {
+  await db("orders").insert(order); // survives
+
+  try {
+    await transaction(async () => {
+      await db("items").insert(item);
+      throw new Error("out of stock"); // only this is rolled back
+    });
+  } catch {
+    // handle it
+  }
+
+  await db("audit").insert(entry); // still in the outer transaction
+});
+
+// the outer transaction commits: the order and the audit row are both saved
+```
+
+Without savepoints, a nested helper's failure would silently abandon its caller's
+writes too — which is the sort of bug you find in production, months later.
+
+### Drivers and the pooling trap
+
+A transaction needs every statement to run on **one** connection. A connection
+*pool* hands each statement to whichever connection is free — so issuing `BEGIN`
+through a pool wraps nothing: the `INSERT` after it can land on a different
+connection entirely, the `COMMIT` commits nothing, and a failure half-writes.
+It looks like it works. It doesn't.
+
+So a pooled driver implements `begin()` on its `Connection`, checking one
+connection out and running the whole transaction on it. Keel's Postgres adapter
+does this automatically when you hand it a `Pool` (it checks for `connect()`), and
+releases the connection afterwards even if the `COMMIT` throws.
+
+| Driver | Transactions |
+|--------|--------------|
+| Postgres (`Pool`) | ✅ a dedicated connection is checked out |
+| Postgres (`Client`), SQLite, libSQL | ✅ `BEGIN` / `COMMIT` on the one connection they have |
+| **Cloudflare D1** | ❌ — no interactive transactions; use `database.batch([...])` |
+
+D1 can't hold a transaction open across awaits, so `transaction()` on it **throws
+a clear error** rather than letting a `BEGIN` fail cryptically. A transaction that
+quietly isn't one is far worse than one that refuses to start.
+
+Writing your own driver? Implement `begin(): Promise<TransactionConnection>` if it
+pools. If it owns a single connection, you can leave it out and Keel will use
+`BEGIN`/`COMMIT`/`ROLLBACK`.
+
 ## Typed rows
 
 Pass a row type for typed results — it flows through to `get()` and `first()`:
@@ -8905,10 +9385,10 @@ with **200** while `isHealthy` is true and **503** the moment a check fails.
 | `RedisCheck` | Reads a key — a failed read means a broken connection |
 | `CacheCheck` | Writes a key, reads it back, deletes it |
 
-Notably **absent**: AdonisJS's disk-space, heap, and RSS checks. Those measure a
-Node process, and on Workers there isn't one — a memory threshold you can't
-observe is worse than no check at all. If you're on Node and want them, `check()`
-below takes ten lines.
+Notably **absent**: disk-space, heap, and RSS checks. Those measure a Node
+process, and on Workers there isn't one — a memory threshold you can't observe is
+worse than no check at all. If you're on Node and want them, `check()` below takes
+ten lines.
 
 ## Your own checks
 
@@ -9742,82 +10222,391 @@ The signature of `onReady` / `onShutdown` hooks.
 
 ---
 
-<!-- source: docs/inertia.md -->
+<!-- source: docs/i18n.md -->
 
-# Inertia
+# Internationalization
 
-Keel ships a server-side [Inertia.js](https://inertiajs.com) adapter. Pair Keel's
-routing with an Inertia client (React, Vue, or Svelte) and render page components
-from the server without building an API — `inertia("Page", props)` returns the
-right response automatically.
+Translations with ICU message formatting, plus the `Intl` formatters that go with
+them.
 
-## Configure it
+```ts
+import { setTranslations, t } from "@shaferllc/keel/core";
 
-Bind an `Inertia` instance in a service provider. You supply the **root view**
-(the HTML shell that embeds the page data and loads your client bundle) and an
-optional asset **version**:
+setTranslations({
+  en: { "cart.items": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}" },
+  fr: { "cart.items": "{count, plural, =0 {Panier vide} one {# article} other {# articles}}" },
+});
+
+t("cart.items", { count: 3 }); // "3 items" — in the request's locale
+```
+
+There is **no dependency here, and there doesn't need to be.** `Intl` ships with
+every modern runtime — Node and Cloudflare Workers both carry the full ICU data —
+so plurals, currencies, dates, and relative times are the platform's job. What Keel
+adds is the message parser on top, which is the part `Intl` doesn't do.
+
+## Setting it up
+
+Register translations once (in a service provider), and add the middleware that
+works out each request's locale:
 
 ```ts
-import { ServiceProvider, singleton, Inertia, inertiaPageAttr } from "@shaferllc/keel/core";
+import { setI18n, I18nManager, setTranslations, detectLocale, HttpKernel } from "@shaferllc/keel/core";
 
-export class InertiaServiceProvider extends ServiceProvider {
-  register(): void {
-    singleton(
-      Inertia,
-      () =>
-        new Inertia({
-          version: "1",
-          rootView: (page) =>
-            `<!DOCTYPE html><html><head><meta charset="utf-8"></head>` +
-            `<body><div id="app" data-page="${inertiaPageAttr(page)}"></div>` +
-            `<script src="/assets/app.js"></script></body></html>`,
-        }),
-    );
+export class I18nServiceProvider extends ServiceProvider {
+  boot(): void {
+    setI18n(new I18nManager({ defaultLocale: "en" }));
+
+    setTranslations({
+      en: await import("../resources/lang/en.json", { with: { type: "json" } }).then((m) => m.default),
+      fr: await import("../resources/lang/fr.json", { with: { type: "json" } }).then((m) => m.default),
+    });
+
+    this.app.make(HttpKernel).use(detectLocale());
   }
 }
 ```
 
-`inertiaPageAttr(page)` serializes and HTML-escapes the page object for the
-`data-page` attribute.
+Now `t()` works anywhere in the request — a controller, a view, a transformer —
+without threading a locale through every call.
 
-> **The version defaults to `"1"`.** Omit it and every deploy reports the same
-> asset version — fine until you ship new assets, at which point stale clients
-> won't be told to hard-reload. Bump it (a build hash, a timestamp) whenever your
-> bundle changes so the adapter can force a full reload on mismatch.
+## Translation files
 
-## Render a page
+Nested objects and flat dot-keys are the same thing, and you can mix them:
 
-From a controller, or straight from a route:
+```json
+{
+  "cart": {
+    "items": "{count, plural, one {# item} other {# items}}",
+    "empty": "Your cart is empty"
+  },
+  "checkout.title": "Checkout"
+}
+```
 
-```ts
-import { inertia } from "@shaferllc/keel/core";
+Both `t("cart.items")` and `t("checkout.title")` resolve.
 
-// controller
-show() {
-  return inertia("Users/Show", { user: getUser(param("id")) });
-}
+## The message format
+
+The supported ICU subset is the part people actually use.
+
+### Interpolation
 
-// brisk route
-router.on("/dashboard").renderInertia("Dashboard", { title: "Welcome" });
+```
+Hello {name}!
 ```
 
-`inertia()` looks up the bound `Inertia` instance and delegates to its `render`.
-The component name is the client-side path Inertia resolves (e.g. `Users/Show`
-maps to your `Pages/Users/Show` component); `props` is any JSON-serializable
-object.
+### Plurals
 
-> **Configure the adapter before you render.** `inertia()` throws
-> `Inertia is not configured…` if no `Inertia` instance is bound in the
-> container. Register the provider (above) during boot, before any route runs.
+```
+{count, plural, =0 {Your cart is empty} one {# item} other {# items}}
+```
 
-## What the adapter does
+`#` becomes the count, formatted for the locale (`1,234 items`). An exact `=N`
+branch beats the plural category — which is the whole point of `=0`, because "Your
+cart is empty" reads better than "0 items".
 
-It implements the Inertia protocol for you. Every branch below is decided from
-the incoming request headers — you call `inertia("Page", props)` once and the
-adapter picks the response:
+**Categories are the locale's, not English's.** French treats 0 and 1 as singular;
+Polish has `one`/`few`/`many`/`other`. That's exactly why you write a message rather
+than `count === 1 ? "item" : "items"` — that ternary is a bug in most of the world.
 
-| Situation | Response |
-|-----------|----------|
+### Ordinals
+
+```
+{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
+```
+
+→ 1st, 2nd, 3rd, 4th, 11th.
+
+### Select
+
+```
+{gender, select, male {He} female {She} other {They}} replied
+```
+
+An unmatched value (or a missing one) takes the `other` branch.
+
+### Numbers, dates, times
+
+```
+{n, number}                 1,234.5
+{n, number, percent}        25%
+{n, number, integer}        4
+{n, number, ::currency/USD} $9.50
+{d, date, medium}           Jul 11, 2026
+{d, time, short}            3:30 PM
+```
+
+### Nesting
+
+Branches are themselves messages, so they nest as deep as you need:
+
+```
+{count, plural,
+  =0 {No messages for {name}}
+  one {{name} has # message}
+  other {{name} has # messages}}
+```
+
+### Literal braces
+
+`'{'` and `'}'` render as literal braces.
+
+## Formatters
+
+`Intl`, bound to the request's locale:
+
+```ts
+const l = i18n();
+
+l.formatNumber(1234.5); // "1,234.5"      (de-DE: "1.234,5")
+l.formatCurrency(9.5, "USD"); // "$9.50"
+l.formatDate(order.createdAt); // "Jul 11, 2026"
+l.formatTime(order.createdAt); // "3:30:00 PM"
+l.formatRelativeTime(post.publishedAt); // "3 days ago"
+l.formatList(["a", "b", "c"]); // "a, b, and c"
+l.formatList(names, { type: "disjunction" }); // "a, b, or c"
+l.formatPlural(5); // "other"
+l.formatDisplayName("fr"); // "French"
+```
+
+`formatRelativeTime` picks a sensible unit from the distance on its own — seconds,
+hours, days — or takes one: `formatRelativeTime(date, "hour")`.
+
+These are worth using even in a **single-locale** app: they're the correct way to
+render money and dates, and they cost nothing.
+
+## Locale detection
+
+`detectLocale()` works out the request's locale and stashes it, in this order:
+
+1. a custom `resolve(c)` you supply
+2. a query param — `detectLocale({ query: "lang" })` → `?lang=fr`
+3. a cookie — `detectLocale({ cookie: "locale" })`
+4. the `Accept-Language` header (turn it off with `header: false`)
+5. the default locale
+
+**Only supported locales are honored**, so `?lang=xx` can't push the app into a
+locale you have no translations for — it falls through to the next source.
+
+`negotiateLocale()` is the header parser on its own, if you want it:
+
+```ts
+negotiateLocale("fr-CA,fr;q=0.9,en;q=0.8", ["en", "fr"], "en"); // "fr"
+```
+
+It honors `q` weights and matches `fr-CA` against a supported `fr`.
+
+## Fallbacks
+
+A key with no translation in the active locale falls back — down a chain, not off
+a cliff:
+
+1. the locale itself (`es-MX`)
+2. its configured fallback (`fallbackLocales: { "es-MX": "es" }`)
+3. its **base language** (`es`)
+4. the default locale (`en`)
+
+So you can ship `es` fully and `es-MX` as a handful of regional overrides, and
+everything else still resolves:
+
+```ts
+setTranslations({
+  es: { greeting: "Hola", chair: "silla" },
+  "es-MX": { chair: "banca" }, // just the override
+});
+
+i18n("es-MX").t("chair"); // "banca"
+i18n("es-MX").t("greeting"); // "Hola" — from `es`
+```
+
+## Missing keys
+
+A missing key **does not throw**. It renders as the key itself (`cart.items`), so
+the page still works and the gap is obvious rather than blank. It also fires an
+`i18n.missing` event, which is how you find them in production:
+
+```ts
+listen("i18n.missing", ({ key, locale }) => {
+  logger().warn("missing translation", { key, locale });
+});
+```
+
+Override what's rendered with the `missing` option:
+
+```ts
+new I18nManager({ missing: (key, locale) => `[${locale}:${key}]` });
+```
+
+---
+
+## API reference
+
+### `t(key, data?)`
+
+`t(key: string, data?: Record<string, unknown>): string`
+
+Translate a key in the **current request's** locale (or the default, outside a
+request), formatting its ICU message with `data`.
+
+### `i18n(locale?)`
+
+`i18n(locale?: string): I18n`
+
+An `I18n` for a locale — or, with no argument, the current request's.
+
+### `I18n`
+
+| Method | Signature |
+|--------|-----------|
+| `t` | `(key, data?) => string` |
+| `has` | `(key) => boolean` |
+| `formatNumber` | `(value, options?: Intl.NumberFormatOptions) => string` |
+| `formatCurrency` | `(value, currency, options?) => string` |
+| `formatDate` | `(value, options?: Intl.DateTimeFormatOptions) => string` |
+| `formatTime` | `(value, options?) => string` |
+| `formatRelativeTime` | `(value, unit?, options?) => string` |
+| `formatList` | `(items, options?: Intl.ListFormatOptions) => string` |
+| `formatPlural` | `(count, options?) => Intl.LDMLPluralRule` |
+| `formatDisplayName` | `(code, type?) => string` |
+| `locale` | the locale code |
+
+### `I18nManager`
+
+| Method | Signature |
+|--------|-----------|
+| `add` | `(data: TranslationsByLocale) => this` |
+| `load` | `(...loaders: TranslationLoader[]) => Promise<this>` |
+| `locale` | `(code?) => I18n` |
+| `supported` | `() => string[]` |
+| `defaultLocale` | the default locale code |
+
+`new I18nManager(options)` — see `I18nOptions`.
+
+### `setI18n(manager)` / `getI18n()` / `setTranslations(data)`
+
+Replace the active manager, read it, or add translations to it.
+
+### `detectLocale(options?)`
+
+`detectLocale(options?: DetectLocaleOptions): MiddlewareHandler`
+
+Work out the request's locale and stash it for `t()` / `i18n()`.
+
+### `negotiateLocale(header, supported, defaultLocale)`
+
+`negotiateLocale(header: string | null | undefined, supported: string[], defaultLocale: string): string`
+
+The `Accept-Language` parser, standalone.
+
+### `formatMessage(message, data?, locale?)`
+
+`formatMessage(message: string, data?: Record<string, unknown>, locale?: string): string`
+
+Format an ICU message directly, without a translation lookup.
+
+### `objectLoader(data)`
+
+`objectLoader(data: TranslationsByLocale): TranslationLoader` — the simplest loader.
+
+### Interfaces & types
+
+#### `I18nOptions`
+
+`{ defaultLocale?, supportedLocales?, fallbackLocales?, missing? }`.
+
+#### `DetectLocaleOptions`
+
+`{ query?, cookie?, header?, resolve? }`.
+
+#### `Translations` / `TranslationsByLocale`
+
+A locale's messages (nested or flat), and those keyed by locale.
+
+#### `TranslationLoader`
+
+`{ load(): Promise<TranslationsByLocale> | TranslationsByLocale }`.
+
+
+
+---
+
+<!-- source: docs/inertia.md -->
+
+# Inertia
+
+Keel ships a server-side [Inertia.js](https://inertiajs.com) adapter. Pair Keel's
+routing with an Inertia client (React, Vue, or Svelte) and render page components
+from the server without building an API — `inertia("Page", props)` returns the
+right response automatically.
+
+## Configure it
+
+Bind an `Inertia` instance in a service provider. You supply the **root view**
+(the HTML shell that embeds the page data and loads your client bundle) and an
+optional asset **version**:
+
+```ts
+import { ServiceProvider, singleton, Inertia, inertiaPageAttr } from "@shaferllc/keel/core";
+
+export class InertiaServiceProvider extends ServiceProvider {
+  register(): void {
+    singleton(
+      Inertia,
+      () =>
+        new Inertia({
+          version: "1",
+          rootView: (page) =>
+            `<!DOCTYPE html><html><head><meta charset="utf-8"></head>` +
+            `<body><div id="app" data-page="${inertiaPageAttr(page)}"></div>` +
+            `<script src="/assets/app.js"></script></body></html>`,
+        }),
+    );
+  }
+}
+```
+
+`inertiaPageAttr(page)` serializes and HTML-escapes the page object for the
+`data-page` attribute.
+
+> **The version defaults to `"1"`.** Omit it and every deploy reports the same
+> asset version — fine until you ship new assets, at which point stale clients
+> won't be told to hard-reload. Bump it (a build hash, a timestamp) whenever your
+> bundle changes so the adapter can force a full reload on mismatch.
+
+## Render a page
+
+From a controller, or straight from a route:
+
+```ts
+import { inertia } from "@shaferllc/keel/core";
+
+// controller
+show() {
+  return inertia("Users/Show", { user: getUser(param("id")) });
+}
+
+// brisk route
+router.on("/dashboard").renderInertia("Dashboard", { title: "Welcome" });
+```
+
+`inertia()` looks up the bound `Inertia` instance and delegates to its `render`.
+The component name is the client-side path Inertia resolves (e.g. `Users/Show`
+maps to your `Pages/Users/Show` component); `props` is any JSON-serializable
+object.
+
+> **Configure the adapter before you render.** `inertia()` throws
+> `Inertia is not configured…` if no `Inertia` instance is bound in the
+> container. Register the provider (above) during boot, before any route runs.
+
+## What the adapter does
+
+It implements the Inertia protocol for you. Every branch below is decided from
+the incoming request headers — you call `inertia("Page", props)` once and the
+adapter picks the response:
+
+| Situation | Response |
+|-----------|----------|
 | First visit (no `X-Inertia` header) | The full HTML document from your `rootView` (a `string`) |
 | Inertia navigation (`X-Inertia: true`) | `{ component, props, url, version }` JSON + `X-Inertia: true` and `Vary: X-Inertia` headers |
 | Asset version changed (GET) | `409` + `X-Inertia-Location` so the client hard-reloads |
@@ -10353,23 +11142,94 @@ field; steer clear of those names in your payloads.
 
 ## Levels
 
-`debug` < `info` < `warn` < `error`. Only events at or above the configured
-level are emitted. Set the threshold via config:
+`trace` < `debug` < `info` < `warn` < `error` < `fatal`. Only events at or above
+the configured level are emitted. Set the threshold via config:
 
 ```ts
 // config/logger.ts
 export default { level: env("LOG_LEVEL", "info") };
 ```
 
-Under the hood the levels are ordinal (`debug` 10, `info` 20, `warn` 30,
-`error` 40); a line is dropped when its level sits below the threshold. The
-default threshold is `"info"`, so `debug` lines stay silent until you lower it.
+Under the hood the levels are ordinal (`trace` 10, `debug` 20, `info` 30, `warn`
+40, `error` 50, `fatal` 60); a line is dropped when its level sits below the
+threshold. The default threshold is `"info"`, so `debug` and `trace` stay silent
+until you lower it.
+
+`log(level, message, context?)` takes the level at runtime, when it isn't known
+statically.
 
 Pretty output turns on automatically when `app.debug` is true. In pretty mode
 each event is a single human-readable line —
 `[2026-07-10T…] INFO  user registered {"userId":42}` — and the writer routes by
-level: `warn` goes to `console.warn`, `error` to `console.error`, everything else
-to `console.log`. In JSON mode every level is written to `console.log`.
+level: `warn` goes to `console.warn`, `error` and `fatal` to `console.error`,
+everything else to `console.log`. In JSON mode every level is written to
+`console.log`.
+
+`enabled: false` silences a logger entirely, at every level.
+
+### Don't pay for lines you won't emit
+
+The threshold drops the *line*, but the **context object is built either way** —
+so an expensive snapshot costs you even when nobody sees it. Gate it:
+
+```ts
+if (logger().isLevelEnabled("debug")) {
+  logger().debug("state", { snapshot: expensiveSnapshot() });
+}
+
+// ...or the callback form
+logger().ifLevelEnabled("debug", (log) => log.debug("state", { snapshot: expensiveSnapshot() }));
+```
+
+## Where the lines go
+
+A **sink** is where log records land. The default writes to the console (JSON, or
+pretty), but it's just a function, so logs can go anywhere — a file, an HTTP
+collector, a buffer:
+
+```ts
+import { Logger, type Sink } from "@shaferllc/keel/core";
+
+const httpSink: Sink = (record) => {
+  void fetch("https://logs.example.com", { method: "POST", body: JSON.stringify(record) });
+};
+
+new Logger({ sink: httpSink });
+```
+
+A sink receives the structured `LogRecord` — `{ level, time, msg, fields }` — not a
+formatted string, so it can do what it likes with the shape. `fields` is already
+redacted.
+
+`MemorySink` collects records in memory, which is what you want in a test:
+
+```ts
+import { Logger, MemorySink } from "@shaferllc/keel/core";
+
+const sink = new MemorySink();
+const log = new Logger({ level: "trace", sink: sink.sink });
+
+log.info("hello", { userId: 1 });
+
+sink.messages(); // ["hello"]
+sink.at("info"); // the records at one level
+sink.records[0].fields; // { userId: 1 }
+sink.clear();
+```
+
+## Named loggers
+
+Give a subsystem its own level or destination:
+
+```ts
+import { setLogger, namedLogger, Logger } from "@shaferllc/keel/core";
+
+setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+
+namedLogger("audit").trace("permission granted", { userId });
+```
+
+The application's own logger stays where it is — reach that with `logger()`.
 
 ## Child loggers
 
@@ -10437,7 +11297,8 @@ middleware), `requestLog()` falls back to the base `logger()`.
 ## Redaction
 
 Keep secrets out of your logs with `redact` — top-level keys or dot paths. Matched
-values are replaced with `"[redacted]"`; the original object is never mutated:
+values are replaced with `"[redacted]"`; **the original object is never mutated**,
+so redacting doesn't corrupt the data you're still using:
 
 ```ts
 const log = new Logger({
@@ -10448,8 +11309,30 @@ log.info("login", { user: "ada", password: "s3cret", req: { headers: { authoriza
 // {"level":"info",…,"user":"ada","password":"[redacted]","req":{"headers":{"authorization":"[redacted]"}}}
 ```
 
+A `*` segment matches every key at that level — which is how you catch a secret
+that appears under a key you don't know in advance:
+
+```ts
+new Logger({ redact: ["*.password", "creds.*.token"] });
+
+log.info("audit", {
+  alice: { password: "a", name: "Alice" },
+  bob: { password: "b", name: "Bob" },
+});
+// both passwords redacted; both names kept
+```
+
+Pass an object instead of an array to change the placeholder, or drop the key
+outright:
+
+```ts
+new Logger({ redact: { paths: ["password"], censor: "***" } });
+new Logger({ redact: { paths: ["password"], remove: true } }); // the key disappears
+```
+
 Redaction is inherited by child loggers, so a redacting base logger keeps
-per-request loggers safe too.
+per-request loggers safe too, and it runs **before** the sink — a custom sink can
+never see the unredacted values.
 
 ---
 
@@ -10603,7 +11486,7 @@ const log = new Logger({ level: "debug", pretty: true, bindings: { app: "api" }
 
 #### `LogLevel`
 
-`type LogLevel = "debug" | "info" | "warn" | "error"`
+`type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"`
 
 The four severity levels, in ascending order. Used for the `level` option and
 selected implicitly by each method.
@@ -10613,6 +11496,58 @@ const threshold: LogLevel = "warn";
 new Logger({ level: threshold });
 ```
 
+### `isLevelEnabled(level)` / `ifLevelEnabled(level, fn)`
+
+`isLevelEnabled(level: LogLevel): boolean` — whether a level would be emitted.
+Check it before building an expensive context object.
+
+`ifLevelEnabled(level: LogLevel, fn: (log: Logger) => void): void` — the callback
+form.
+
+### `log(level, message, context?)`
+
+`log(level: LogLevel, message: string, context?: Record<string, unknown>): void` —
+log at a level chosen at runtime.
+
+### `consoleSink(pretty?)`
+
+`consoleSink(pretty = false): Sink` — the default sink. JSON to stdout, or a pretty
+single line.
+
+### `MemorySink`
+
+Collects records in memory — for tests.
+
+| Member | Signature |
+|--------|-----------|
+| `sink` | `Sink` — hand this to `LoggerOptions.sink` |
+| `records` | `LogRecord[]` |
+| `at` | `(level) => LogRecord[]` |
+| `messages` | `() => string[]` |
+| `clear` | `() => void` |
+
+### `setLogger(logger, name)` / `namedLogger(name)`
+
+Register a logger under a name, and resolve it. `namedLogger` throws for an unknown
+name.
+
+### Interfaces & types (added)
+
+#### `Sink`
+
+`type Sink = (record: LogRecord) => void` — where log lines go.
+
+#### `LogRecord`
+
+`{ level: LogLevel; time: string; msg: string; fields: Record<string, unknown> }` —
+`fields` is already redacted.
+
+#### `RedactOptions`
+
+`{ paths: string[]; censor?: string; remove?: boolean }` — a `*` path segment
+matches every key at that level. `LoggerOptions.redact` also accepts a bare
+`string[]`.
+
 
 
 ---
@@ -11298,29 +12233,102 @@ const opts: FetchTransportOptions = {
 };
 ```
 
+### `mailer(name?)`
 
+`mailer(name?: string): Mailer` — the default mailer, or a named one. Throws for an
+unknown name.
 
----
+### `send(email, name?)` / `sendLater(email, name?)`
 
-<!-- source: docs/migrations.md -->
+`send(email: BaseMail, name?: string): Promise<Message>` — build a class-based mail
+and send it. `sendLater` queues it instead.
 
-# Migrations
+### `BaseMail`
 
-Version your database schema. A migration is a `{ name, up, down }` object; a
-fluent **schema builder** describes tables, and the **migrator** runs them
-against your [connection](./database.md), tracking what's applied. The SQL is
-dialect-aware (sqlite / mysql / postgres) and the core imports no driver.
+Abstract. Implement `build(message: PendingMail): void | Promise<void>` to compose
+the message.
 
-## Define migrations
+### `PendingMail.sendLater()`
 
-```ts
-import type { Migration } from "@shaferllc/keel/core";
+`sendLater(): Promise<void>` — validate now, then put the message on the queue.
 
-export const migrations: Migration[] = [
-  {
-    name: "01_create_users",
-    up: (schema) =>
-      schema.createTable("users", (t) => {
+### `PendingMail.attach()` / `.embed()`
+
+`attach(filename, content: string | Uint8Array, contentType?): this` — content type
+inferred from the extension when omitted.
+
+`embed(cid, content, filename?, contentType?): this` — an inline attachment,
+referenced from the HTML as `cid:<cid>`.
+
+### `PendingMail.toMessage()`
+
+`toMessage(): Message` — the message as composed, before the mailer applies its
+defaults.
+
+### Testing
+
+#### `fakeMail(name?)` / `restoreMail(name?)`
+
+`fakeMail(name?): FakeMailer` swaps a mailer for one that records instead of
+delivering. `restoreMail(name?)` puts the real one back — with no name, every faked
+mailer.
+
+`FakeMailer`:
+
+| Method | Signature |
+|--------|-----------|
+| `assertSent` | `(where?) => void` |
+| `assertNotSent` | `(where?) => void` |
+| `assertSentCount` | `(count) => void` |
+| `assertQueued` | `(where?) => void` |
+| `assertNotQueued` | `(where?) => void` |
+| `assertQueuedCount` | `(count) => void` |
+| `assertNothingSent` | `() => void` — nothing sent *and* nothing queued |
+| `sent()` / `queued()` | `() => Message[]` |
+
+### Interfaces & types
+
+#### `Attachment`
+
+`{ filename, content: string | Uint8Array, contentType?, cid? }` — a `cid` makes it
+an inline attachment.
+
+#### `MailerOptions`
+
+`{ from?, replyTo? }` — defaults applied to messages that don't set their own.
+
+#### `RecordedMail`
+
+`{ message: Message, queued: boolean }` — what a `FakeMailer` records.
+
+#### `SendMailJob`
+
+The `Job` that carries a queued message. Exported so a custom queue driver can
+recognize it.
+
+
+
+---
+
+<!-- source: docs/migrations.md -->
+
+# Migrations
+
+Version your database schema. A migration is a `{ name, up, down }` object; a
+fluent **schema builder** describes tables, and the **migrator** runs them
+against your [connection](./database.md), tracking what's applied. The SQL is
+dialect-aware (sqlite / mysql / postgres) and the core imports no driver.
+
+## Define migrations
+
+```ts
+import type { Migration } from "@shaferllc/keel/core";
+
+export const migrations: Migration[] = [
+  {
+    name: "01_create_users",
+    up: (schema) =>
+      schema.createTable("users", (t) => {
         t.id();
         t.string("email").unique();
         t.string("name");
@@ -12962,122 +13970,589 @@ The `database` channel. Persists the `toArray` payload through the query builder
 
 `new DatabaseChannel(table?: string)`
 
-Creates a channel that writes to `table`.
+Creates a channel that writes to `table`.
+
+```ts
+new DatabaseChannel();          // → "notifications"
+new DatabaseChannel("alerts");  // → "alerts"
+```
+
+**Notes:** defaults to the `notifications` table.
+
+#### `send(notifiable, notification)`
+
+`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+
+Inserts one row: `type` (the notification's class name), `notifiable_id`
+(`routeFor(notifiable, "database")`, or `null`), and `data` (JSON of `toArray`).
+
+```ts
+await new DatabaseChannel().send(user, new InvoicePaid(4200));
+```
+
+**Notes:** stores `"{}"` for `data` when the notification has no `toArray`. The
+target table must exist — create it in a migration.
+
+### `ArrayChannel`
+
+An in-memory channel for tests — records deliveries instead of sending them.
+
+#### `sent`
+
+`readonly sent: { notifiable: Notifiable; notification: Notification }[]`
+
+The log of everything this channel received, in delivery order.
+
+```ts
+const array = new ArrayChannel();
+// … after notify …
+array.sent[0].notification; // the Notification instance
+```
+
+**Notes:** it keeps the notification *instance*, so you can `instanceof`-check it
+or read its fields — no serialization through `toArray`.
+
+#### `send(notifiable, notification)`
+
+`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+
+Pushes `{ notifiable, notification }` onto `sent`. Never touches the network.
+
+```ts
+new Notifier().channel("array", new ArrayChannel());
+```
+
+### Interfaces & types
+
+#### `Notifiable`
+
+```ts
+interface Notifiable {
+  routeNotificationFor?(channel: string): string | number | undefined;
+  [key: string]: unknown;
+}
+```
+
+A recipient — anything with routing info, most often a `User` model. Implement
+`routeNotificationFor` to steer specific channels; otherwise `routeFor` reads
+`email`/`id` off the index signature.
+
+```ts
+class User extends Model {
+  routeNotificationFor(channel: string) {
+    return channel === "mail" ? this.billing_email : undefined;
+  }
+}
+```
+
+#### `MailContent`
+
+```ts
+interface MailContent {
+  subject: string;
+  text?: string;
+  html?: string;
+  from?: string;
+  to?: string;
+}
+```
+
+What `toMail()` returns and the `mail` channel consumes. `subject` is required;
+supply `text`, `html`, or both. `to` overrides the resolved recipient; `from`
+overrides the mailer default.
+
+```ts
+toMail(): MailContent {
+  return { subject: "Welcome", html: "<h1>Hi</h1>", to: "override@app.com" };
+}
+```
+
+#### `Channel`
+
+```ts
+interface Channel {
+  send(notifiable: Notifiable, notification: Notification): Promise<void>;
+}
+```
+
+The seam a custom transport implements — SMS, Slack, push, anything. One method:
+`send`. Register your implementation with `Notifier.channel(name, channel)`.
+
+```ts
+const slack: Channel = {
+  async send(notifiable, notification) {
+    const payload = notification.toArray?.(notifiable) ?? {};
+    // POST payload to a Slack webhook via fetch…
+  },
+};
+```
+
+
+
+---
+
+<!-- source: docs/openapi.md -->
+
+# OpenAPI
+
+Keel OpenAPI generates an [OpenAPI 3](https://spec.openapis.org/oas/v3.0.3) spec
+from your routes and serves [Swagger UI](https://swagger.io/tools/swagger-ui/) to
+explore it. It's a Keel [package](./packages.md): one `register()` mounts the docs
+at `/docs` and the spec at `/docs/openapi.json`.
+
+Nothing is scraped or guessed. The generator reads Keel's own route table —
+methods, paths, names, and param constraints are always correct — and enriches
+each operation with whatever the route attaches via `.config(apiDoc(...))`.
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+
+export const providers = [AppServiceProvider, OpenApiServiceProvider];
+```
+
+Open `http://localhost:3000/docs`. That's enough for a spec of every route (paths,
+methods, path params). To add summaries, request/response schemas, and tags,
+document the routes.
+
+## Documenting a route
+
+`apiDoc()` returns route config the generator understands. Its `request` field is
+the same `{ body, query, params }` shape you hand `validateRequest`, so one set of
+Zod schemas both validates and documents:
+
+```ts
+import { apiDoc } from "@shaferllc/keel/openapi";
+import { validateRequest } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+
+router
+  .post("/users", [Users, "store"])
+  .config(apiDoc({
+    summary: "Create a user",
+    tags: ["users"],
+    request: { body: NewUser },
+    responses: { 201: { description: "The created user", schema: UserShape } },
+  }))
+  .middleware([validateRequest({ body: NewUser })]);
+```
+
+What the generator does with it:
+
+- **Path params** — `/users/:id` becomes `/users/{id}`; a `.where("id", /\d+/)`
+  constraint becomes a `pattern`.
+- **Query params** — a `request.query` schema's fields expand into query
+  parameters (each `required` per the schema).
+- **Request body** — a `request.body` schema becomes a JSON request body
+  (Zod → JSON Schema via Zod 4's `z.toJSONSchema`).
+- **Responses** — your documented responses, plus an automatic `422` when the
+  route validates input. Undocumented routes get a default `200`.
+- **Tags** — `tags`, or the first path segment.
+- **operationId** — the route's `.name()`, else `method_path`.
+
+Fields on `apiDoc`: `summary`, `description`, `tags`, `operationId`,
+`deprecated`, `request`, `responses`, and `hidden` (leave the route out entirely).
+Response and request schemas accept a Zod schema **or** a plain JSON Schema
+object.
+
+## Configuration
+
+`config/openapi.ts` (publish with `keel vendor:publish --tag openapi-config`):
+
+```ts
+export default {
+  enabled: true,
+  path: "docs",                 // /docs and /docs/openapi.json
+  title: "",                    // defaults to config("app.name")
+  version: "1.0.0",
+  servers: [],                  // e.g. ["https://api.example.com"]
+  public: false,                // serve in production too
+  cdn: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14",
+  ignorePaths: ["/watch"],      // route prefixes to leave out
+};
+```
+
+## Access
+
+Like [Watch](./watch.md), the docs are gated shut in production by default (open
+only when `app.debug` is on or the app isn't in production). Set `public: true` to
+serve them everywhere, or plug in your own check:
+
+```ts
+import { OpenApi } from "@shaferllc/keel/openapi";
+OpenApi.auth((c) => auth().check());
+```
+
+The gate guards the spec endpoint too.
+
+## Exporting the spec
+
+Write the spec to a file — for CI, client generation, or committing it:
+
+```bash
+keel openapi:export --out openapi.json
+```
+
+## On the UI dependency
+
+The spec (`/docs/openapi.json`) is generated with **zero dependencies** and runs
+anywhere Keel does, including the edge. The Swagger **UI** loads its assets from
+the configured `cdn` — the one external dependency, confined to the browser. Pin
+the version (the default is pinned) or point `cdn` at a copy you host if you need
+a fully self-contained deployment.
+
+
+
+---
+
+<!-- source: docs/packages.md -->
+
+# Packages
+
+A **package** is a redistributable slice of a Keel app — routes, a UI, config,
+migrations, console commands — that installs with a single `app.register(...)`.
+Keel's `ServiceProvider` is already the unit of composition; `PackageProvider`
+adds the conventions a *shippable* package needs so it can carry its own schema
+and assets instead of asking the app to wire them by hand.
+
+[Keel Watch](./watch.md) — the debug dashboard — is a first-party package and the
+reference implementation of everything below.
+
+## The shape of a package
+
+```ts
+import { PackageProvider, type Router } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export class BillingServiceProvider extends PackageProvider {
+  readonly name = "billing"; // used for publish grouping and diagnostics
+
+  register(): void {
+    this.mergeConfig("billing", { enabled: true, path: "billing" });
+    this.migrations([createInvoicesTable]);
+    this.publishes({ [join(here, "config.stub")]: "config/billing.ts" }, "billing-config");
+    this.commands([syncInvoicesCommand]);
+  }
+
+  boot(): void {
+    this.assets("billing/assets", join(here, "ui/dist"), { maxAge: 3600 });
+    this.routes((r: Router) => registerBillingRoutes(r), { prefix: "billing", as: "billing" });
+  }
+}
+```
+
+Scaffold that skeleton with `keel make:package billing`.
+
+## The helpers
+
+Each is a thin wrapper over an existing Keel primitive — the value is the
+convention, not new machinery.
+
+| Helper | What it does |
+|--------|--------------|
+| `mergeConfig(key, defaults)` | Set config defaults under `key`. The app's `config/<key>.ts` deep-merges **over** them, so the app always wins. |
+| `routes(register, { prefix, middleware, as })` | Register a route group (the callback gets the `Router`), already prefixed/guarded/name-prefixed. |
+| `assets(urlPrefix, dir, { maxAge, immutable })` | Serve a directory of built files (a bundled UI) under a URL prefix. Node-only. |
+| `migrations(list)` | Contribute migrations, run by `keel migrate` alongside the app's own. |
+| `commands(list)` | Add `keel` console commands (e.g. `billing:sync`). |
+| `publishes(map, tag?)` | Declare files a consuming app can copy in with `keel vendor:publish`. |
+
+## Lifecycle: mind the kernel
+
+`register()` and `boot()` run **before** the app's HTTP kernel is bound (see
+`bootstrap/app.ts`). So a package must not reach for `HttpKernel`. That's why
+`routes()` and `assets()` go through the `Router` (bound in the Application
+constructor) — routes are compiled onto the kernel later, at build time. Use
+`register()` for config/bindings and `boot()` for wiring; both are safe for the
+helpers above.
+
+## Migrations
+
+Package migrations join the app's under one command:
+
+```bash
+keel migrate           # run pending (app + package) migrations
+keel migrate:status    # show which have run
+keel migrate:rollback  # roll back the last batch
+```
+
+App migrations are discovered from `database/migrations/*.ts` (each file
+default-exports a `Migration` or `Migration[]`); package migrations come from
+`this.migrations(...)`. Both run against the default connection.
+
+## Publishing files
+
+`publishes()` declares source→destination copies; `keel vendor:publish` performs
+them (skipping files that already exist unless `--force`):
+
+```bash
+keel vendor:publish                     # everything
+keel vendor:publish --tag billing-config # just one tagged group
+```
+
+This is how a package ships an overridable config stub, or copies a starter view
+into the consuming app.
+
+## Observing the framework
+
+A package often wants to *see* what the app is doing — every query, request, or
+job — without patching anything. The framework emits a typed **instrumentation
+event stream** for exactly this; subscribe with `listen()`:
+
+```ts
+import { listen, type QueryEvent } from "@shaferllc/keel/core";
+
+listen<QueryEvent>("db.query", (e) => metrics.timing("db", e.durationMs));
+```
+
+| Event | Fired when |
+|-------|-----------|
+| `db.query` | a query runs (sql, bindings, durationMs, connection, kind) |
+| `request.handled` | a request finishes (method, path, status, durationMs, headers) |
+| `exception` | an error reaches the HTTP kernel |
+| `job.processing` / `job.processed` / `job.failed` | a queued job's lifecycle |
+| `cache.hit` / `cache.miss` | a cache lookup |
+| `notification.sent` | a notification is delivered |
+| `schedule.task.run` | a scheduled task runs |
+| `mail.sending` / `mail.sent` | mail lifecycle |
+
+Every request opens a scope with a **request id** that flows through async work,
+so anything emitted inside a request can attribute itself to it via
+`currentRequestId()` — that's what lets [Watch](./watch.md) tie a request to the
+queries and logs it produced. Emitting is fire-and-forget: a broken listener can
+never break the work it observes.
+```
+
+
+
+---
+
+<!-- source: docs/pages.md -->
+
+# Pages
+
+Page-based routing — **a file is a route**.
+
+```
+resources/pages/index.tsx           →  /
+resources/pages/about.tsx           →  /about
+resources/pages/users/index.tsx     →  /users
+resources/pages/users/[id].tsx      →  /users/:id
+resources/pages/docs/[...slug].tsx  →  /docs/*   (catch-all)
+```
+
+```tsx
+// resources/pages/users/[id].tsx
+import { db, type Ctx, type PageProps } from "@shaferllc/keel/core";
+
+export const loader = (c: Ctx) => db("users").where("id", c.req.param("id")).first();
+
+export default function UserPage({ params, data }: PageProps<{ id: string }, User>) {
+  return (
+    <Layout>
+      <h1>{data.name}</h1>
+      <p>User #{params.id}</p>
+    </Layout>
+  );
+}
+```
+
+That's the whole page. No route file to keep in sync, no controller, no wiring.
+
+## It doesn't replace the router — it drives it
+
+Every page becomes an **ordinary named route**. `url()` finds it, route middleware
+applies to it, and `keel routes` lists it. You can mix pages and hand-written
+routes freely, and reach for a controller the moment a page outgrows a file.
+
+That matters, because file-based routing is a lovely default and a bad prison.
+Here it's a *convenience over* the router, not a replacement for it.
+
+## Registering them
+
+In a service provider's `boot()`:
+
+```ts
+import { pages } from "@shaferllc/keel/core";
+
+export class PageServiceProvider extends ServiceProvider {
+  async boot(): Promise<void> {
+    await pages(); // scans resources/pages
+  }
+}
+```
+
+`pages()` reads the filesystem, so it's **Node-only**. On the edge, hand
+`definePages()` a build-time manifest instead — Vite's `import.meta.glob` produces
+exactly the map it wants:
+
+```ts
+definePages(import.meta.glob("./pages/**/*.tsx", { eager: true }));
+```
+
+Same behavior, no filesystem.
+
+## The file conventions
+
+| File | URL |
+|------|-----|
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `users/index.tsx` | `/users` |
+| `users/[id].tsx` | `/users/:id` |
+| `users/[id]/edit.tsx` | `/users/:id/edit` |
+| `teams/[team]/users/[id].tsx` | `/teams/:team/users/:id` |
+| `docs/[...slug].tsx` | `/docs/*` — a catch-all; `params.slug` is the whole rest |
+| `_layout.tsx` | **not a route** — a leading `_` keeps a file private |
+
+A trailing `index` names its directory rather than a child of it. A leading
+underscore is how layouts, partials, and helpers live *beside* your pages without
+becoming URLs.
+
+## Specificity is decided for you
+
+This is the part file-based routing usually gets wrong:
+
+```
+users/[id].tsx      →  /users/:id
+users/new.tsx       →  /users/new
+```
+
+Register `:id` first and `/users/new` is **unreachable forever** — `:id` happily
+matches `"new"`. Whether your app works would come down to the order the
+filesystem happened to hand back.
+
+So pages are **sorted before they're registered**: literal segments beat
+parameters, parameters beat catch-alls, and a catch-all is always the last resort.
+`/users/new` wins, and the file layout stops being a trap.
+
+## Loading data
+
+`loader` runs before the page renders; whatever it returns arrives as `data`.
+
+```tsx
+export const loader = async (c: Ctx) => {
+  const post = await db("posts").where("slug", c.req.param("slug")).first();
+  if (!post) throw new NotFoundException();
+  return post;
+};
+
+export default function PostPage({ data }: PageProps<{ slug: string }, Post>) {
+  return <article>{data.body}</article>;
+}
+```
+
+It takes the request context, so it can read params, query, headers, or the
+session. A page with no `loader` simply gets `data: undefined`.
+
+## Middleware
+
+Per page:
+
+```tsx
+export const middleware = [authGuard()];
+```
+
+Or for every page at once:
 
 ```ts
-new DatabaseChannel();          // → "notifications"
-new DatabaseChannel("alerts");  // → "alerts"
+await pages({ middleware: [authGuard()] });
 ```
 
-**Notes:** defaults to the `notifications` table.
-
-#### `send(notifiable, notification)`
+Both run before the `loader`, so a page that's refused never loads its data.
 
-`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+## Names and URLs
 
-Inserts one row: `type` (the notification's class name), `notifiable_id`
-(`routeFor(notifiable, "database")`, or `null`), and `data` (JSON of `toArray`).
+Each page gets a route name derived from its path — `users/[id].tsx` becomes
+`users.id` — so URL generation works without you naming anything:
 
 ```ts
-await new DatabaseChannel().send(user, new InvoicePaid(4200));
+router.url("users.id", { id: 5 }); // "/users/5"
 ```
 
-**Notes:** stores `"{}"` for `data` when the notification has no `toArray`. The
-target table must exist — create it in a migration.
+Override it when the derived name is ugly:
 
-### `ArrayChannel`
+```tsx
+export const name = "users.show";
+```
 
-An in-memory channel for tests — records deliveries instead of sending them.
+## Escape hatches
 
-#### `sent`
+Move a page's URL without moving the file:
 
-`readonly sent: { notifiable: Notifiable; notification: Notification }[]`
+```tsx
+export const path = "/pricing"; // even though the file is at marketing/plans.tsx
+```
 
-The log of everything this channel received, in delivery order.
+Mount every page under a prefix:
 
 ```ts
-const array = new ArrayChannel();
-// … after notify …
-array.sent[0].notification; // the Notification instance
+await pages({ prefix: "/app" }); // index.tsx is now /app
+await pages({ dir: "app/pages" }); // ...or keep them somewhere else
 ```
 
-**Notes:** it keeps the notification *instance*, so you can `instanceof`-check it
-or read its fields — no serialization through `toArray`.
+---
 
-#### `send(notifiable, notification)`
+## API reference
 
-`send(notifiable: Notifiable, notification: Notification): Promise<void>`
+### `pages(options?)`
 
-Pushes `{ notifiable, notification }` onto `sent`. Never touches the network.
+`pages(options?: PagesOptions): Promise<RegisteredPage[]>`
 
-```ts
-new Notifier().channel("array", new ArrayChannel());
-```
+Scan a directory and register every page in it. **Node only** — it reads the
+filesystem (`node:fs` is imported dynamically, so the core still loads on the
+edge).
 
-### Interfaces & types
+### `definePages(modules, options?)`
 
-#### `Notifiable`
+`definePages(modules: Record<string, PageModule>, options?: PagesOptions): RegisteredPage[]`
 
-```ts
-interface Notifiable {
-  routeNotificationFor?(channel: string): string | number | undefined;
-  [key: string]: unknown;
-}
-```
+Register pages from a `file path → module` map. The edge-safe half — pair it with
+`import.meta.glob`.
 
-A recipient — anything with routing info, most often a `User` model. Implement
-`routeNotificationFor` to steer specific channels; otherwise `routeFor` reads
-`email`/`id` off the index signature.
+### `PagesOptions`
 
-```ts
-class User extends Model {
-  routeNotificationFor(channel: string) {
-    return channel === "mail" ? this.billing_email : undefined;
-  }
-}
-```
+| Option | Meaning |
+|--------|---------|
+| `dir` | Where the pages live. Default `"resources/pages"` |
+| `prefix` | Prefix every page's URL |
+| `middleware` | Middleware applied to every page |
+| `router` | The router to register on. Defaults to the application's |
 
-#### `MailContent`
+### `PageModule`
 
-```ts
-interface MailContent {
-  subject: string;
-  text?: string;
-  html?: string;
-  from?: string;
-  to?: string;
-}
-```
+What a page file exports.
 
-What `toMail()` returns and the `mail` channel consumes. `subject` is required;
-supply `text`, `html`, or both. `to` overrides the resolved recipient; `from`
-overrides the mailer default.
+| Export | Meaning |
+|--------|---------|
+| `default` | **Required.** The component. May be async |
+| `loader` | `(ctx) => data` — runs before the page renders |
+| `middleware` | Middleware for this page alone |
+| `name` | The route name. Defaults to one derived from the path |
+| `path` | Override the URL entirely |
 
-```ts
-toMail(): MailContent {
-  return { subject: "Welcome", html: "<h1>Hi</h1>", to: "override@app.com" };
-}
-```
+### `PageProps<P, D>`
 
-#### `Channel`
+What the component receives: `params` (typed by `P`), `data` (whatever `loader`
+returned, typed by `D`), and `ctx`.
 
-```ts
-interface Channel {
-  send(notifiable: Notifiable, notification: Notification): Promise<void>;
-}
-```
+### `RegisteredPage`
 
-The seam a custom transport implements — SMS, Slack, push, anything. One method:
-`send`. Register your implementation with `Notifier.channel(name, channel)`.
+`{ file, pattern, name }` — what `pages()` / `definePages()` return, so you can
+see exactly what got mounted.
 
-```ts
-const slack: Channel = {
-  async send(notifiable, notification) {
-    const payload = notification.toArray?.(notifiable) ?? {};
-    // POST payload to a Slack webhook via fetch…
-  },
-};
-```
+### `routePattern(file)` / `routeName(file)`
+
+The two pure functions behind the conventions, exported so you can test or reuse
+them. `routePattern("users/[id].tsx")` → `"/users/:id"`;
+`routeName("users/[id].tsx")` → `"users.id"`.
 
 
 
@@ -15199,9 +16674,11 @@ file.
 
 > **The disk's `url()` prefix and `basePath` must agree.** `signedUrl()` signs the
 > path the *disk* reports, so if the disk hands out `/storage/…` while
-> `serveStorage` listens on `/private`, every signed URL will 403. Give the disk
-> the matching base — `new MemoryDisk("/private")`, or `localDisk("./storage",
-> "/private")` — or keep both on the default `/storage`.
+> `serveStorage` listens on `/private`, no signature could ever match. Rather than
+> 403 every request — which reads as "your link expired" and sends you hunting in
+> the wrong place — `serveStorage` **throws** with the two paths and how to line
+> them up. Give the disk the matching base (`new MemoryDisk("/private")`, or
+> `localDisk("./storage", "/private")`), or keep both on the default `/storage`.
 
 ## Direct browser uploads
 
@@ -15435,108 +16912,378 @@ const s3Disk = (options: {
     },
     url: (path) => `${options.baseUrl}/${path}`,
 
-    // The capabilities that matter: the bucket signs, so the bytes skip your app.
-    signedUrl: (path, o) => presign(path, "GET", o?.expiresIn ?? 3600),
-    signedUploadUrl: (path, o) => presign(path, "PUT", o?.expiresIn ?? 3600, o?.contentType),
-  };
-};
+    // The capabilities that matter: the bucket signs, so the bytes skip your app.
+    signedUrl: (path, o) => presign(path, "GET", o?.expiresIn ?? 3600),
+    signedUploadUrl: (path, o) => presign(path, "PUT", o?.expiresIn ?? 3600, o?.contentType),
+  };
+};
+```
+
+## API reference
+
+### `storage(name?)`
+
+`storage(name?: string): Storage`
+
+The default disk, or a named one registered with `setDisk(disk, name)`. Throws
+for an unknown name.
+
+### `setDisk(disk, name?)`
+
+`setDisk(disk: Disk, name?: string): Storage`
+
+Registers a disk (default name `"default"`) and returns the wrapping `Storage`.
+
+### `Storage`
+
+Wraps a `Disk`.
+
+| Method | Signature |
+|--------|-----------|
+| `put` | `(path, contents: string \| Uint8Array \| ArrayBuffer, options?: WriteOptions) => Promise<void>` |
+| `get` | `(path) => Promise<Uint8Array \| null>` |
+| `getText` | `(path) => Promise<string \| null>` |
+| `exists` / `delete` | `(path) => Promise<boolean>` / `Promise<void>` |
+| `list` | `(prefix?) => Promise<string[]>` |
+| `metadata` | `(path) => Promise<FileMetadata \| null>` |
+| `size` | `(path) => Promise<number \| null>` |
+| `copy` / `move` | `(from, to) => Promise<void>` |
+| `url` | `(path) => string` — the public URL |
+| `signedUrl` | `(path, options?: SignedFileOptions) => Promise<string>` |
+| `signedUploadUrl` | `(path, options?: SignedUploadOptions) => Promise<string>` |
+| `driver` | the underlying `Disk` |
+
+### `fakeDisk(name?)` / `restoreDisk(name?)`
+
+`fakeDisk(name?: string): FakeStorage` swaps a disk for an in-memory
+`FakeStorage`. `restoreDisk(name?)` puts the real one back — with no name, every
+faked disk.
+
+`FakeStorage` is a `Storage` plus `assertExists(path)`, `assertMissing(path)`,
+`assertContents(path, text)`, and `assertCount(n, prefix?)`.
+
+### `serveStorage(options?)`
+
+`serveStorage(options?: ServeStorageOptions): MiddlewareHandler`
+
+Serves a disk's files over HTTP. Options: `disk` (name, default `"default"`),
+`basePath` (default `"/storage"`), `signed` (require a valid signature, 403
+otherwise), `maxAge` (`Cache-Control` seconds).
+
+### `signStorageUrl(url, expiresIn?)` / `verifyStorageUrl(url)`
+
+`signStorageUrl(url: string, expiresIn?: number): Promise<string>` adds `expires`
+and `signature` params, signed with `config('app.key')` (default one hour).
+`verifyStorageUrl(url: string): Promise<boolean>` checks them. Signing covers the
+path and query, not the host.
+
+### `contentTypeFor(path)`
+
+`contentTypeFor(path: string): string` — the MIME type for a path's extension, or
+`application/octet-stream`.
+
+### `MemoryDisk`
+
+`class MemoryDisk implements Disk` — in-memory, the default and ideal for tests.
+`new MemoryDisk(baseUrl?)` sets the `url()` prefix. Not shared across processes.
+
+### Interfaces & types
+
+#### `Disk`
+
+The driver seam. Required: `put` / `get` / `exists` / `delete` / `list` / `url`.
+Optional capabilities: `metadata` / `copy` / `move` / `signedUrl` /
+`signedUploadUrl`.
+
+#### `WriteOptions`
+
+`{ contentType?, cacheControl?, visibility?, metadata? }` — passed to `put`.
+
+#### `FileMetadata`
+
+`{ size, contentType?, cacheControl?, visibility?, lastModified?, metadata? }`.
+
+#### `SignedFileOptions` / `SignedUploadOptions`
+
+`{ expiresIn? }` (seconds, default 3600), plus `contentType?` for uploads.
+
+#### `FileVisibility`
+
+`type FileVisibility = "public" | "private"`.
+
+#### `Contents`
+
+`type Contents = string | Uint8Array | ArrayBuffer` — accepted by `put`.
+
+
+
+---
+
+<!-- source: docs/telemetry.md -->
+
+# Telemetry
+
+Distributed tracing — spans, W3C trace context, and an OTLP exporter — with **no
+SDK**.
+
+```ts
+import { setTelemetry, Tracer, otlpExporter, tracing, trace } from "@shaferllc/keel/core";
+
+setTelemetry(
+  new Tracer({
+    serviceName: "api",
+    exporter: otlpExporter({ url: "http://localhost:4318/v1/traces" }),
+    sampleRatio: 0.1, // 10% of traces in production
+  }),
+);
+
+// in your HTTP kernel
+this.use(tracing()); // a server span per request
+```
+
+```ts
+// your own spans, anywhere
+await trace("charge", async (span) => {
+  span.setAttributes({ "order.id": order.id });
+  await stripe.charge(order);
+});
+```
+
+## Why there's no SDK here
+
+The OpenTelemetry Node SDK is a large tree of packages that assumes a Node
+process. What a trace actually **is**, though, is small: an id, a parent, a start
+and an end, some attributes — and a documented JSON shape to POST them in.
+
+That's what this is. It speaks **OTLP/HTTP over `fetch`**, so it runs on Workers as
+happily as on Node, and any OTLP collector accepts it — Jaeger, Tempo, Honeycomb,
+Grafana, Datadog. You don't get the SDK's auto-instrumentation of every library
+under the sun; you get the part that matters, in about 400 lines you can read.
+
+## Spans
+
+`trace(name, fn)` opens a span, runs your function inside it, and closes it — even
+if the function throws, in which case the error is recorded on the span and
+rethrown.
+
+```ts
+const receipt = await trace("charge", async (span) => {
+  span.setAttributes({ "order.id": id, currency: "USD" });
+  span.addEvent("calling stripe");
+
+  return stripe.charge(id); // a throw here marks the span failed, then propagates
+});
+```
+
+**Spans nest automatically.** A `trace()` inside another `trace()` becomes its
+child, sharing the trace id — you don't thread anything through:
+
+```ts
+await trace("checkout", async () => {
+  await trace("reserve-stock", async () => { … }); // child
+  await trace("charge", async () => { … }); // sibling of the above
+});
+```
+
+That works across `await` boundaries, and across **concurrent** traces, because
+the current span is tracked in `AsyncLocalStorage` rather than a global. Two
+requests in flight at once don't get tangled.
+
+From anywhere inside a span:
+
+```ts
+setAttributes({ tenant: "acme" }); // add to the current span
+addEvent("cache miss", { key }); // a timestamped annotation
+currentSpan(); // the Span itself, or undefined
+```
+
+All of these are **no-ops outside a span**, so instrumented code stays safe to call
+from a script or a test.
+
+## HTTP requests
+
+`tracing()` opens a **server span** per request, records the method, path, and
+status, and closes it when the response is sent.
+
+```ts
+this.use(tracing());
+```
+
+A 5xx marks the span failed; a 404 doesn't — that's a valid answer, not a fault.
+
+It also writes a `traceparent` header onto the **response**, so when a user says
+"this page was slow", you can look up their exact trace.
+
+`/health/*`, `/metrics`, and `/favicon.ico` are ignored by default — they're noise.
+Change that with `ignore`, and name spans yourself with `name`:
+
+```ts
+this.use(
+  tracing({
+    ignore: (path) => path.startsWith("/internal"),
+    name: (method, path) => `${method} ${path.replace(/\/\d+/, "/:id")}`,
+  }),
+);
+```
+
+## Following a trace between services
+
+This is the point of tracing: one id spanning every service a request touches.
+
+**Incoming.** `tracing()` reads the caller's `traceparent` header and makes your
+span a **child of theirs**, so both land in the same trace. A missing or malformed
+header just starts a fresh trace — never an error.
+
+**Outgoing.** `injectTraceContext()` puts the current context on your request
+headers, so the service you call joins this trace instead of starting its own:
+
+```ts
+await fetch(url, {
+  headers: injectTraceContext({ accept: "application/json" }),
+});
+```
+
+`parseTraceparent()` and `traceparent()` are the two halves on their own, if you
+need to carry the context somewhere odd — a queue payload, say.
+
+## Connecting logs to traces
+
+`traceIds()` returns the current `trace_id` and `span_id`. Bind them to your logger
+and every line becomes a jumping-off point into the trace it came from:
+
+```ts
+const log = logger().child(traceIds());
+log.info("charging card", { orderId }); // carries trace_id + span_id
 ```
 
-## API reference
+## Sampling
 
-### `storage(name?)`
+Recording every trace in production is expensive. `sampleRatio` records a fraction:
 
-`storage(name?: string): Storage`
+```ts
+new Tracer({ sampleRatio: 0.1 }); // 10%
+```
 
-The default disk, or a named one registered with `setDisk(disk, name)`. Throws
-for an unknown name.
+The decision is made **once, at the root span, and inherited by every child** —
+because half a trace is worse than no trace. An unsampled span still runs (your
+code is unaffected); it just isn't exported.
 
-### `setDisk(disk, name?)`
+## Exporters
 
-`setDisk(disk: Disk, name?: string): Storage`
+| Exporter | Use |
+|----------|-----|
+| `otlpExporter({ url, headers, resource })` | Any OTLP/HTTP collector. Production. |
+| `consoleExporter()` | Prints each span. Local development, no collector needed. |
+| `MemoryExporter` | Collects spans in memory. Tests. |
 
-Registers a disk (default name `"default"`) and returns the wrapping `Storage`.
+```ts
+otlpExporter({
+  url: "https://api.honeycomb.io/v1/traces",
+  headers: { "x-honeycomb-team": env("HONEYCOMB_KEY") },
+  resource: { "service.name": "api", "deployment.environment": "prod" },
+});
+```
 
-### `Storage`
+Spans are **buffered** and sent in batches (100 by default, via `batchSize`).
 
-Wraps a `Disk`.
+**Flush before the process — or the isolate — goes away**, or the last few spans
+die with it:
 
-| Method | Signature |
-|--------|-----------|
-| `put` | `(path, contents: string \| Uint8Array \| ArrayBuffer, options?: WriteOptions) => Promise<void>` |
-| `get` | `(path) => Promise<Uint8Array \| null>` |
-| `getText` | `(path) => Promise<string \| null>` |
-| `exists` / `delete` | `(path) => Promise<boolean>` / `Promise<void>` |
-| `list` | `(prefix?) => Promise<string[]>` |
-| `metadata` | `(path) => Promise<FileMetadata \| null>` |
-| `size` | `(path) => Promise<number \| null>` |
-| `copy` / `move` | `(from, to) => Promise<void>` |
-| `url` | `(path) => string` — the public URL |
-| `signedUrl` | `(path, options?: SignedFileOptions) => Promise<string>` |
-| `signedUploadUrl` | `(path, options?: SignedUploadOptions) => Promise<string>` |
-| `driver` | the underlying `Disk` |
+```ts
+onShutdown(() => flushTelemetry());
+```
 
-### `fakeDisk(name?)` / `restoreDisk(name?)`
+On Workers, call it at the end of a request (ideally inside `waitUntil`).
 
-`fakeDisk(name?: string): FakeStorage` swaps a disk for an in-memory
-`FakeStorage`. `restoreDisk(name?)` puts the real one back — with no name, every
-faked disk.
+## Testing
 
-`FakeStorage` is a `Storage` plus `assertExists(path)`, `assertMissing(path)`,
-`assertContents(path, text)`, and `assertCount(n, prefix?)`.
+`MemoryExporter` collects spans so you can assert on them:
 
-### `serveStorage(options?)`
+```ts
+import { Tracer, MemoryExporter, setTelemetry, trace } from "@shaferllc/keel/core";
 
-`serveStorage(options?: ServeStorageOptions): MiddlewareHandler`
+const exporter = new MemoryExporter();
+setTelemetry(new Tracer({ exporter, batchSize: 1 })); // batchSize 1 = export immediately
 
-Serves a disk's files over HTTP. Options: `disk` (name, default `"default"`),
-`basePath` (default `"/storage"`), `signed` (require a valid signature, 403
-otherwise), `maxAge` (`Cache-Control` seconds).
+await trace("charge", async (span) => span.setAttributes({ "order.id": 1 }));
 
-### `signStorageUrl(url, expiresIn?)` / `verifyStorageUrl(url)`
+const span = exporter.named("charge")[0];
+assert.equal(span.status, "unset");
+assert.equal(span.attributes["order.id"], 1);
+```
 
-`signStorageUrl(url: string, expiresIn?: number): Promise<string>` adds `expires`
-and `signature` params, signed with `config('app.key')` (default one hour).
-`verifyStorageUrl(url: string): Promise<boolean>` checks them. Signing covers the
-path and query, not the host.
+`exporter.trace(traceId)` returns every span in one trace; `exporter.clear()`
+empties it between tests.
 
-### `contentTypeFor(path)`
+---
 
-`contentTypeFor(path: string): string` — the MIME type for a path's extension, or
-`application/octet-stream`.
+## API reference
 
-### `MemoryDisk`
+### `trace(name, fn, options?)`
 
-`class MemoryDisk implements Disk` — in-memory, the default and ideal for tests.
-`new MemoryDisk(baseUrl?)` sets the `url()` prefix. Not shared across processes.
+`trace<T>(name: string, fn: (span: Span) => Promise<T> | T, options?: SpanOptions): Promise<T>`
 
-### Interfaces & types
+Run `fn` inside a span. The span is current for the duration, ends when `fn`
+settles, and records a throw before rethrowing it.
 
-#### `Disk`
+### `currentSpan()` / `setAttributes(attrs)` / `addEvent(name, attrs?)`
 
-The driver seam. Required: `put` / `get` / `exists` / `delete` / `list` / `url`.
-Optional capabilities: `metadata` / `copy` / `move` / `signedUrl` /
-`signedUploadUrl`.
+Reach the span in scope. All no-ops outside one.
 
-#### `WriteOptions`
+### `traceIds()`
 
-`{ contentType?, cacheControl?, visibility?, metadata? }` — passed to `put`.
+`traceIds(): { trace_id?: string; span_id?: string }` — the ids to hang on a log
+line.
 
-#### `FileMetadata`
+### `tracing(options?)`
 
-`{ size, contentType?, cacheControl?, visibility?, lastModified?, metadata? }`.
+`tracing(options?: TracingOptions): MiddlewareHandler`
 
-#### `SignedFileOptions` / `SignedUploadOptions`
+A server span per request. Options: `ignore(path)` (default: `/health`, `/metrics`,
+`/favicon.ico`), `name(method, path)`.
 
-`{ expiresIn? }` (seconds, default 3600), plus `contentType?` for uploads.
+### `Tracer`
 
-#### `FileVisibility`
+`new Tracer(options: TracerOptions)`
 
-`type FileVisibility = "public" | "private"`.
+| Option | Meaning |
+|--------|---------|
+| `serviceName` | Added to every span as `service.name` |
+| `exporter` | Where finished spans go. Omit and nothing is exported |
+| `sampleRatio` | 0–1, decided once at the root. Default 1 |
+| `enabled` | `false` turns tracing off |
+| `resource` | Attributes describing the service, sent with each batch |
+| `batchSize` | Export once this many spans are buffered. Default 100 |
 
-#### `Contents`
+Methods: `startSpan(name, options?)`, `trace(name, fn, options?)`, `flush()`.
 
-`type Contents = string | Uint8Array | ArrayBuffer` — accepted by `put`.
+### `Span`
+
+`setAttribute(k, v)` / `setAttributes(attrs)` / `addEvent(name, attrs?)` /
+`setStatus(status, message?)` / `recordException(error)` / `end()`, plus a
+`context` (`{ traceId, spanId, sampled }`).
+
+### `setTelemetry(tracer)` / `telemetry()` / `flushTelemetry()`
+
+Register the active tracer, read it, and drain its buffer.
+
+### Trace context
+
+`parseTraceparent(header)` → `SpanContext | null` (null on anything malformed).
+`traceparent(context)` → the header string.
+`injectTraceContext(headers?)` → headers with the current context added.
+
+### Exporters
+
+`otlpExporter({ url, headers?, resource? })`, `consoleExporter()`, and
+`MemoryExporter` (`.spans`, `.named(name)`, `.trace(traceId)`, `.clear()`).
+
+### Interfaces & types
+
+`SpanData`, `SpanContext`, `SpanEvent`, `SpanKind`
+(`internal | server | client | producer | consumer`), `SpanStatus`
+(`unset | ok | error`), `SpanAttributes`, `SpanExporter`, `TracerOptions`,
+`TracingOptions`, `OtlpOptions`.
 
 
 
@@ -15546,10 +17293,9 @@ Optional capabilities: `metadata` / `copy` / `move` / `signedUrl` /
 
 # Templates
 
-A string templating engine in the spirit of AdonisJS **Edge** — `{{ }}`
-interpolation and `@`-prefixed tags for logic, includes, layouts, and
-components. Reach for it when you want plain-text templates instead of (or
-alongside) [JSX views](./views.md).
+A string templating engine — `{{ }}` interpolation and `@`-prefixed tags for
+logic, includes, layouts, and components. Reach for it when you want plain-text
+templates instead of (or alongside) [JSX views](./views.md).
 
 Unlike engines that compile a template to a function with `eval` /
 `new Function`, Keel **interprets** templates against a small, safe expression
@@ -15958,6 +17704,257 @@ kernel.use(requestLogger());
 const client = testClient(kernel);
 ```
 
+## Authenticated requests
+
+The client's `withX` methods return a **copy**, so a client configured once can be
+reused without leaking into other tests:
+
+```ts
+const authed = client.withToken("tok_123"); // Authorization: Bearer tok_123
+
+await authed.get("/me");
+await client.get("/me"); // still anonymous
+```
+
+| Method | Sends |
+|--------|-------|
+| `withToken(token)` | `Authorization: Bearer <token>` |
+| `withBasicAuth(user, pass)` | `Authorization: Basic <base64>` |
+| `withHeader(name, value)` / `withHeaders({…})` | any header |
+| `withCookie(name, value)` / `withCookies({…})` | a `Cookie` header |
+| `acceptJson()` | `Accept: application/json` |
+
+## Forms and uploads
+
+```ts
+await client.form("/login", { email: "a@b.com", password: "s3cret" }); // url-encoded
+await client.multipart("/avatar", { file: new Blob([png]), name: "ada" }); // file upload
+```
+
+## More response assertions
+
+```ts
+res.assertOk(); // 2xx
+res.assertCreated(); // 201
+res.assertNoContent(); // 204
+res.assertUnauthorized(); // 401
+res.assertForbidden(); // 403
+res.assertNotFound(); // 404
+res.assertUnprocessable(); // 422
+res.assertServerError(); // 5xx
+```
+
+**`assertJsonContains` is a subset match** — the one you usually want. It pins the
+fields the test is about and ignores the rest, so adding a field to a response
+doesn't break twenty tests:
+
+```ts
+res.assertJsonContains({ user: { email: "a@b.com" } });
+```
+
+`assertJson` still deep-equals the whole body, when that's what you mean.
+
+```ts
+res.assertSee("Welcome back"); // body contains
+res.assertDontSee("Sign up");
+
+res.assertHeader("content-type", "application/json");
+res.assertHeaderMissing("x-debug");
+
+res.assertCookie("session"); // was set
+res.assertCookie("session", "abc123"); // ...with this value
+res.assertCookieMissing("admin");
+
+res.dump(); // print status, headers, body — when you're stuck
+```
+
+### Validation
+
+A failed `validate()` returns a 422 with per-field errors, so a test can assert on
+the field rather than the message:
+
+```ts
+const res = await client.post("/users", { email: "nope" });
+
+res.assertValidationErrors("email", "password");
+res.assertNoValidationError("name");
+```
+
+## Test doubles
+
+Keel's fakes swap out a real backend for a recording one, so a test can assert
+that something *would* have happened without it actually happening — no email
+sent, no card charged, no file uploaded.
+
+| Fake | Replaces | Assertions |
+|------|----------|------------|
+| [`fakeMail()`](./mail.md#in-tests) | the mailer | `assertSent`, `assertQueued`, … |
+| [`fakeQueue()`](./queues.md#in-tests) | the queue | `assertPushed`, `assertNothingPushed`, … |
+| [`fakeDisk()`](./storage.md#testing) | a storage disk | `assertExists`, `assertContents`, … |
+| [`events().fake()`](./events.md#testing) | the emitter | `assertEmitted`, `assertNotEmitted`, … |
+| [`hash.fake()`](./hashing.md) | PBKDF2 | — (just makes it fast) |
+
+```ts
+const mailer = fakeMail();
+const queue = fakeQueue();
+
+await registerUser({ email: "ada@example.com" });
+
+mailer.assertQueued((m) => m.subject === "Welcome");
+queue.assertPushed(SendWelcome);
+```
+
+For anything else, `swap()` replaces a container binding:
+
+```ts
+swap(PaymentGateway, () => new FakeGateway());
+```
+
+### Spies
+
+The smallest double: a function that records how it was called.
+
+```ts
+import { spy, spyOn, restoreSpies } from "@shaferllc/keel/core";
+
+const send = spy<[string], void>();
+notify(send);
+
+assert.equal(send.callCount, 1);
+assert.ok(send.calledWith("hello"));
+```
+
+`spyOn` replaces a method on an object. It **calls through** by default — so you're
+observing, not stubbing — until you tell it otherwise:
+
+```ts
+const charge = spyOn(gateway, "charge"); // still really charges
+charge.returns(receipt); // now it doesn't
+
+restoreSpies(); // put every spied method back
+```
+
+## Controlling time
+
+Testing "this token expires in an hour" shouldn't take an hour.
+
+```ts
+import { freezeTime, timeTravel, restoreTime } from "@shaferllc/keel/core";
+
+freezeTime("2026-07-11T12:00:00Z");
+
+const token = await jwt.sign({ sub: "1" }, { expiresIn: "1h" });
+assert.ok(await jwt.verify(token)); // valid now
+
+timeTravel(61 * 60 * 1000); // an hour and a minute later
+assert.equal(await jwt.verify(token), null); // expired
+
+restoreTime();
+```
+
+`freezeTime()` mocks `Date` and `Date.now()`. It does **not** mock timers — a
+`setTimeout` still fires on the real clock — and `new Date("2020-01-01")` still
+parses normally. Only "what time is it *now*" is frozen.
+
+## Resetting state between tests
+
+Keel's fakes, disks, queues, and cache are process-global, so one test can leak
+into the next. `resetState()` puts it all back:
+
+```ts
+import { resetState } from "@shaferllc/keel/core";
+
+afterEach(() => resetState());
+```
+
+It restores every fake (mail, queue, disk, hash), unfreezes the clock, drops event
+listeners, empties the cache, and gives you a fresh lock store. It does **not**
+touch the database.
+
+For that, `truncate()`:
+
+```ts
+afterEach(() => truncate("comments", "posts", "users")); // children before parents
+```
+
+It deletes rows rather than rolling back a transaction, so it works on every driver
+(D1, Postgres, libSQL) instead of only the ones with savepoints.
+
+## Database assertions
+
+Assert against the database directly, rather than through an endpoint:
+
+```ts
+import { assertDatabaseHas, assertDatabaseMissing, assertDatabaseCount } from "@shaferllc/keel/core";
+
+await client.post("/users", { email: "ada@example.com" });
+
+await assertDatabaseHas("users", { email: "ada@example.com" });
+await assertDatabaseHas("users", { active: 1 }, 1); // exactly one match
+await assertDatabaseMissing("users", { email: "deleted@example.com" });
+await assertDatabaseCount("users", 1);
+await assertDatabaseEmpty("sessions");
+```
+
+A failure tells you what it looked for and how many rows the table actually holds.
+
+## Console tests
+
+Run a command in-process — no subprocess, so it's fast and you can assert on it:
+
+```ts
+import { runCommand } from "@shaferllc/keel/core";
+import { run } from "../bin/keel"; // your app's console entry point
+
+const result = await runCommand(() => run(["node", "keel", "routes"]));
+
+result
+  .assertSucceeded() // exit code 0
+  .assertOutputContains("GET  /users")
+  .assertOutputMatches(/POST\s+\/users/);
+```
+
+You pass the command **in**, because the console entry point belongs to your app —
+it's the thing that knows how to build your application — not to the core. Anything
+that prints and sets an exit code works, so it's equally good for testing a
+function you wrote yourself.
+
+`console.log`/`warn` are captured as stdout and `console.error` as stderr; a
+command that *throws* is recorded as a failure rather than blowing up the test.
+
+`assertFailed()`, `assertExitCode(n)`, and `assertErrorContains(text)` cover the
+rest. `result.stdout`, `result.stderr`, and `result.exitCode` are there if you'd
+rather assert by hand.
+
+## Browser tests
+
+Keel doesn't ship a browser driver — that's [Playwright](https://playwright.dev)'s
+job, and wrapping it would only put a thinner API in front of a better one.
+
+The test client injects requests *without a server*, which is what makes it fast;
+a browser needs a real one. Start the app on a port, point Playwright at it, and
+tear it down:
+
+```ts
+import { serve } from "@hono/node-server";
+import { chromium } from "playwright";
+
+const server = serve({ fetch: new HttpKernel(app).build().fetch, port: 3001 });
+const browser = await chromium.launch();
+
+const page = await browser.newPage();
+await page.goto("http://localhost:3001/login");
+await page.fill("[name=email]", "ada@example.com");
+await page.click("button[type=submit]");
+await page.waitForURL("**/dashboard");
+
+await browser.close();
+server.close();
+```
+
+Everything else on this page — the fakes, `freezeTime`, `resetState`, the database
+assertions — works the same in a browser test, because it's the same process.
+
 ## API reference
 
 ### `testClient(target)`
@@ -17692,3 +19689,128 @@ interface ManifestChunk {
 Vite's `manifest.json`, as produced by the build. You rarely touch it directly —
 `generateEntryPointsTags` and `assetPath` read it for you.
 
+
+
+---
+
+<!-- source: docs/watch.md -->
+
+# Watch
+
+Keel Watch is a debug dashboard — a Telescope for Keel. It records the requests,
+queries, exceptions, logs, jobs, mail, notifications, cache lookups, events, and
+scheduled tasks flowing through your app, and shows them in a single-page UI at
+`/watch`, with every request linked to the queries and logs it produced.
+
+It ships as a Keel [package](./packages.md) and is its reference implementation:
+one `register()` turns it on, and its watchers observe the framework's
+instrumentation event stream — they patch nothing, so installing Watch changes no
+behaviour, only visibility.
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { WatchServiceProvider } from "@shaferllc/keel/watch";
+
+export const providers = [AppServiceProvider, WatchServiceProvider];
+```
+
+Publish the config and create the table:
+
+```bash
+keel vendor:publish --tag watch-config   # writes config/watch.ts
+keel migrate                             # creates watch_entries
+```
+
+Then open `http://localhost:3000/watch`.
+
+> Watch exposes requests, payloads, and stack traces. It is gated shut in
+> production by default (see [Access](#access)) — keep it that way, or lock it
+> down with your own check.
+
+## What it records
+
+A tab per type, each behind an on/off switch:
+
+| Watcher | Records |
+|---------|---------|
+| Requests | method, path, status, duration, headers (auth/cookies redacted) |
+| Queries | SQL, bindings, duration, connection; slow queries are tagged |
+| Exceptions | class, message, stack, the request that threw |
+| Logs | every log line, at any level |
+| Mail | sent messages (subject, recipients, body) |
+| Jobs | queued jobs as they complete or fail |
+| Notifications | deliveries and their channels |
+| Cache | hits and misses *(off by default — noisy)* |
+| Events | app events *(off by default — noisy)* |
+| Schedule | scheduled tasks as they run |
+
+Clicking any entry shows its full detail and **everything else in its batch** —
+the request it belonged to and every query, log, and exception that request
+produced.
+
+## Configuration
+
+`config/watch.ts` (publish it, then edit):
+
+```ts
+export default {
+  enabled: env("WATCH_ENABLED", true),
+  path: "watch",                 // the dashboard mounts at /watch
+  storage: "database",           // "database" persists; "memory" is a per-process ring
+  connection: undefined,         // which DB connection (default when omitted)
+  table: "watch_entries",
+  limit: 100,                    // API page size; the memory ring is 10× this
+  sampling: 1,                   // record this fraction of entries (0–1)
+  slowQueryMs: 100,              // queries at/above this are tagged "slow"
+  ignorePaths: [],               // request paths to skip
+  retentionHours: 24,            // keel watch:prune deletes entries older than this
+  watchers: { cache: false, event: false /* … the rest default on */ },
+};
+```
+
+### Storage
+
+- **`database`** (default) — a `watch_entries` table via any registered
+  connection. Survives restarts, shared across processes; needs `keel migrate`.
+- **`memory`** — a per-process ring buffer. Zero setup, great for a single dev
+  process or the edge; entries vanish on restart and aren't shared.
+
+## Access
+
+By default the dashboard is open only when `app.debug` is on or the app isn't in
+production. Anywhere else, lock it to your own check:
+
+```ts
+import { Watch } from "@shaferllc/keel/watch";
+import { auth } from "@shaferllc/keel/core";
+
+Watch.auth(() => auth().check() && Boolean(auth().user()?.isAdmin));
+```
+
+The gate guards the JSON API too, so entries can't be read by anyone the
+dashboard wouldn't show them to.
+
+## Pruning
+
+With database storage, keep the table small:
+
+```bash
+keel watch:prune            # delete entries older than retentionHours
+keel watch:prune --hours=6
+```
+
+Schedule it (see [Scheduling](./scheduling.md)) to run it automatically.
+
+## How it works
+
+Watch never wraps or monkey-patches the framework. The core emits a typed
+[instrumentation event stream](./packages.md#observing-the-framework) —
+`db.query`, `request.handled`, `exception`, `job.*`, and so on — and each watcher
+is just a listener that turns an event into a stored entry, stamped with the
+current request id so related entries group into one batch. Recording is
+fire-and-forget: it never blocks or breaks the request it's watching, and the
+store's own queries are filtered out so it never records itself.
+```
+