@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/README.md

@@ -1,1999 +1,1265 @@
-# Honey
+# @lovrozagar/honey
 
-Type-safe API framework on Web Standards. Builder-pattern DX, precompiled radix-tree router, OpenAPI, and generated clients for TypeScript, Python, Go, and Rust.
+A typed web framework for the Fetch API whose routes are the source of its clients. You write a route once, with its
+input and output schemas; honey serves it on Node, Bun or Cloudflare Workers, and
+[`@lovrozagar/honey-clients`](https://www.npmjs.com/package/@lovrozagar/honey-clients) turns the same routes into an
+OpenAPI 3.1 document, typed SDKs for six languages, a command-line client and an MCP server.
 
-This repo is the source of the [`@lovrozagar/honey`](https://www.npmjs.com/package/@lovrozagar/honey) npm package. The CLI binary is still `honey`.
+Nothing is inferred at runtime: the schemas you declare are what the handler receives, what the document says, and
+what every generated client's types promise.
 
-This README is the full usage manual. An agent that reads only this file should be able to build, serve, generate, and consume a Honey app without opening source.
+This page is the whole framework. Every TypeScript block below is type-checked by the repository's tests against this
+package, so nothing here is pseudocode.
 
-## Table of contents
-
-- [Start](#start)
-- [What Honey is](#what-honey-is)
 - [Install](#install)
-- [First app](#first-app)
-- [CLI](#cli)
-  - [`honey init`](#honey-init)
-  - [`honey generate`](#honey-generate)
-- [Builder](#builder)
-  - [Create the app](#create-the-app)
-  - [Routes and methods](#routes-and-methods)
-  - [Path matching](#path-matching)
-  - [Prefixes and slashes](#prefixes-and-slashes)
-  - [Context](#context)
-  - [Responses](#responses)
-  - [Status keys](#status-keys)
-  - [Input](#input)
-  - [Output](#output)
-  - [Errors](#errors)
-  - [Middleware](#middleware)
-  - [Shipped middleware](#shipped-middleware)
-  - [Composition](#composition)
-  - [Taps](#taps)
-  - [Proxy routes](#proxy-routes)
-  - [Static files](#static-files)
-  - [Logging, telemetry, production tree](#logging-telemetry-production-tree)
-- [Serve](#serve)
-  - [Bun, Node, Deno](#bun-node-deno)
-  - [Cloudflare Workers](#cloudflare-workers)
-  - [Feature auto-load](#feature-auto-load)
-- [OpenAPI, docs, and manifest](#openapi-docs-and-manifest)
-  - [Meta spec](#meta-spec)
-- [WebSockets](#websockets)
-- [Realtime](#realtime)
-- [SSE and streaming](#sse-and-streaming)
-- [Generated clients](#generated-clients)
-  - [Plugin codegen config](#plugin-codegen-config)
-  - [TypeScript `createClient`](#typescript-createclient)
-  - [Generated SDK usage](#generated-sdk-usage)
-  - [Go CLI](#go-cli)
-  - [Programmatic codegen](#programmatic-codegen)
-- [Type inference](#type-inference)
+- [A route, end to end](#a-route-end-to-end)
+- [The app](#the-app)
+- [Routing](#routing)
+- [Input and output](#input-and-output)
+- [Responses](#responses)
+- [Errors](#errors)
+- [Middleware](#middleware)
+- [The request context](#the-request-context)
+- [Cookies](#cookies)
+- [Streaming, WebSockets and realtime](#streaming-websockets-and-realtime)
+- [Serving on Node, Bun and Cloudflare Workers](#serving-on-node-bun-and-cloudflare-workers)
+- [Static files and proxying](#static-files-and-proxying)
+- [The OpenAPI document](#the-openapi-document)
+- [The MCP server](#the-mcp-server)
+- [Logging and tracing](#logging-and-tracing)
+- [Internationalization and crypto](#internationalization-and-crypto)
 - [Testing](#testing)
-- [Utilities](#utilities)
-- [Package exports](#package-exports)
-- [Repository layout](#repository-layout)
-- [Develop](#develop)
-  - [Test matrix](#test-matrix)
-  - [E2E apps and runtimes](#e2e-apps-and-runtimes)
-  - [Live Cloudflare proof](#live-cloudflare-proof)
-  - [Bench](#bench)
-- [Releases](#releases)
+- [The build plugin and the honey CLI](#the-build-plugin-and-the-honey-cli)
+- [Generated clients](#generated-clients)
+- [Every export](#every-export)
+- [Type helpers](#type-helpers)
+- [Documentation](#documentation)
 - [License](#license)
 
-## Start
-
-```bash
-bun add @lovrozagar/honey
-honey init
-bun run dev
-```
-
-```ts
-import { honey } from "@lovrozagar/honey"
-
-export const app = honey()
-	.get("/health")
-	.handler((ctx) => ctx.res.text("ok", "ok"))
-	.openapi({ docs: "scalar", title: "My API", version: "1.0.0" })
-
-await app.serve({ cors: true, port: 3000 })
-```
-
-```bash
-curl http://127.0.0.1:3000/health
-# ok
-
-curl http://127.0.0.1:3000/openapi.json
-# open http://127.0.0.1:3000/docs
-```
-
-`honey init` writes `src/app.ts`, `src/server.ts`, `vite.config.ts`, and `dev` / `generate` scripts. `honey init --cf` also writes `wrangler.jsonc` and a worker that exports `fetch`.
-
-`honey generate` loads the app in a fresh process with `app.serve()` stubbed, so the one-file shape above does not start a listener while generating, and the process exits when it is done. Other top-level side effects in the app module (database clients, timers) still run during generation; keep them behind a function or in `src/server.ts`.
-
-`app.serve()` detects bun / node / deno and loads only that WebSocket adapter. Pass `runtime` to pin it. Cloudflare Workers cannot listen — export `fetch: (req, env, ctx) => app.fetch(req, env, ctx)`.
-
-`app.serve()`, `app.openapi()`, and `app.errorI18n()` load their implementations when called. A fetch-only production bundle does not include listen adapters, spec generation, or i18n. Spec and docs routes stay out of the generated document.
-
-```bash
-honey generate          # writes src/_gen/
-honey generate --watch
-```
-
-## What Honey is
-
-Honey is a single TypeScript builder that becomes a Web-standard `fetch(request, env)` handler. The same app runs on Bun, Node, Deno, and Cloudflare Workers.
-
-- **Builder DX.** `honey().get("/users/:id").input(...).handler(...)` is how you write routes. Types flow from path params, Standard Schema input, output maps, and middleware additions into `ctx`.
-- **Radix tree.** Routes compile into a radix tree. Production can load a generated tree so unknown paths 404 without walking a catch-all.
-- **Web Standards.** Handlers see `Request` and return `Response`. `app.fetch()` is the public entry. On Node, `serve()` wraps `IncomingMessage` / `ServerResponse` so the hot path does not build a native Fetch pair.
-- **OpenAPI from the app.** `app.openapi()` serves JSON and YAML from the same document. Scalar or Swagger mounts at `/docs`. Spec and docs routes are internal — they do not appear in the spec they serve.
-- **Clients from the spec.** `honey generate` writes route types, a manifest, OpenAPI, and optional SDKs (TypeScript, Python, Go, Rust) plus an optional Go CLI.
-
-Honey is not Express with types bolted on. There is no `req.body` parser stack. Input is declared per route with Standard Schema (Zod, Valibot, ArkType, Effect Schema, Yup — anything that implements the Standard Schema `~standard` interface).
-
 ## Install
 
-Requires [Bun](https://bun.sh) 1.3+ to develop this repo. The published package runs on Node 22.12 or later, Bun, Deno, and Cloudflare Workers; it ships compiled JavaScript, so plain Node imports it from `node_modules` without a TypeScript loader. The `honey` CLI and the Vite plugin run on Node from npm as well as on Bun.
+1.0 is out as a release candidate, published under npm's `next` tag, so an install without a tag still gives 0.7.3.
+Add `@next` until the final release:
 
-```bash
-bun add @lovrozagar/honey
-# or
-npm add @lovrozagar/honey
-# or
-pnpm add @lovrozagar/honey
+```sh
+npm install @lovrozagar/honey@next
+npx honey init
 ```
 
-The CLI ships with the package (`honey` in `package.json` `bin`). After install:
+Node 22.12 or later, Bun 1.3 or later, or Cloudflare Workers. A schema library is yours to pick: honey validates
+through [Standard Schema](https://standardschema.dev), so Zod, Valibot, ArkType, Effect Schema and Yup all work. The
+examples here use Zod.
 
-```bash
-honey init
-honey generate
-```
+`honey init` writes `src/app.ts`, `src/server.ts` and a Vite config; `honey init --cf` adds a Worker entry and a
+`wrangler.jsonc`.
 
-The published package depends only on `jiti` (for generate/watch). Validation libraries are your choice. Two optional peer dependencies:
+## A route, end to end
 
-- `ws`, for WebSocket and realtime routes on **Node** (`npm install ws`). Bun, Deno and Workers have WebSockets built in. Without it, a WebSocket upgrade on Node answers 500 and logs the install hint.
-- `ts-morph`, as a **dev** dependency, for type generation (`codegen.types`).
+Declare what a route takes and what it answers. `ctx.input` is typed by the schemas, and so is `ctx.res.json`'s
+payload for the status key you name:
 
-## First app
-
-`honey init` is the supported scaffold.
-
-```bash
-mkdir my-api && cd my-api
-bun init -y
-bun add @lovrozagar/honey
-honey init
-bun run dev
-```
+```ts
+import { defineErrors, honey } from "@lovrozagar/honey"
+import * as z from "zod"
 
-That writes:
+const errors = defineErrors({ not_found: "not_found" })
 
-| File             | Role                                                     |
-| ---------------- | -------------------------------------------------------- |
-| `src/app.ts`     | App export: health route + `openapi({ docs: "scalar" })` |
-| `src/server.ts`  | `await app.serve({ port })`                              |
-| `vite.config.ts` | `honey({ app: "src/app.ts" })` plugin                    |
+const app = honey()
 
-Scripts added to `package.json`: `dev` (runs `src/server.ts`) and `generate` (`honey generate`).
+app
+	.get("/books/:id")
+	.input({ params: z.object({ id: z.string() }), search: z.object({ lang: z.string().optional() }) })
+	.output({ "application/json": { ok: z.object({ id: z.string(), title: z.string() }) } })
+	.errors(errors, "not_found")
+	.handler((ctx) => {
+		if (ctx.input.params.id === "0") throw errors.not_found()
+		return ctx.res.json("ok", { id: ctx.input.params.id, title: "Dune" })
+	})
 
-Cloudflare from the start:
+app
+	.post("/books")
+	.input({ json: z.object({ title: z.string().min(1) }) })
+	.handler((ctx) => ctx.res.json("created", { id: "b-1", title: ctx.input.json.title }))
 
-```bash
-honey init --cf
+export default app
 ```
 
-Also writes `src/worker.ts` (`export default { fetch }`) and `wrangler.jsonc`. Existing files refuse to overwrite unless you pass `--force`.
-
-Minimal app without the scaffold:
+Serving is the same for any app, and the reference UI comes from the document the routes already describe:
 
 ```ts
 import { honey } from "@lovrozagar/honey"
-import * as z from "zod"
+import { serveOpenApi } from "@lovrozagar/honey/openapi"
+import { serve } from "@lovrozagar/honey/serve"
 
-const app = honey<{ DATABASE_URL: string }>()
-	.basePath("/api")
-	.trailingSlash("strip")
-	.get("/health")
-	.handler((ctx) => ctx.res.json("ok", { status: "ok" }))
-	.post("/users")
-	.input({ json: z.object({ email: z.string().email(), name: z.string() }) })
-	.output({ "application/json": { created: z.object({ id: z.string() }) } })
-	.handler((ctx) => ctx.res.json("created", { id: "u-1" }))
-
-await app.serve({ env: { DATABASE_URL: process.env.DATABASE_URL! }, port: 3000 })
-```
-
-## CLI
+const app = honey()
+app.get("/health").handler((ctx) => ctx.res.text("ok", "ok"))
 
+await serve(serveOpenApi(app, { docs: "scalar", title: "Books", version: "1.0.0" }), { port: 3000 })
 ```
-honey generate [--watch] [--config <path>] [--plugin <n>] [--app <path>] [flags]
-honey init [--cf] [--force]
-```
-
-Flags take `--flag value` or `--flag=value`. Unknown flags, stray arguments, a missing value and a `--config` that does not exist are errors: the CLI prints usage and exits `1`. Any other first argument does the same.
-
-### `honey init`
-
-| Flag      | Meaning                                                                 |
-| --------- | ----------------------------------------------------------------------- |
-| `--cf`    | Also write a Workers entry and `wrangler.jsonc` (alias `--cloudflare`)  |
-| `--force` | Overwrite `src/app.ts`, `src/server.ts`, `vite.config.ts` if they exist |
-
-`honey init` adds `@lovrozagar/honey` to `dependencies`. In an existing `package.json` it keeps your `dev` / `generate` scripts and `type` unless you pass `--force`.
-
-### `honey generate`
-
-Reads the Vite `honey()` plugin config (default `vite.config.ts`) and writes artifacts next to the app. Jiti loads the app and the Vite config with `fsCache` and `moduleCache` off, so a second generate after you add a route is not stale.
-
-If there is no Vite config, you must pass `--app`.
-
-The CLI loads the app on the runtime that started it. Started from a Bun script (`bun run generate`, `bunx honey`), it runs under that Bun even though the bin's shebang is `node`, so an app that relies on Bun's module loading (text imports such as `.md`, Bun-only APIs) generates as it runs. Under Node it stays on Node. Set `HONEY_NO_BUN_HANDOFF=1` to keep Node.
-
-A route tree that is stale or was written by an older honey does not stop the generation that replaces it: while `honey generate` loads the app, `routeTree()` ignores such a tree and the routes the app registers are used instead. Outside generation the stale tree still fails with an error naming the routes.
 
-| Flag                           | Meaning                                                                                                       |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `--watch`                      | Regenerate when the route tree checksum changes. Ignores `_gen` / `.gen.*`. Requires `--app` or plugin `app`. |
-| `--config <path>`              | Vite config to load (default `vite.config.ts`)                                                                |
-| `--plugin <n>`                 | Which `honey()` plugin in the config, 0-based, when it holds several                                          |
-| `--app <path>`                 | App module, overrides plugin `app`                                                                            |
-| `--tree`                       | Enable writing the generated route tree                                                                       |
-| `--types`                      | Enable writing TypeScript route types (needs `ts-morph`)                                                      |
-| `--manifest`                   | Enable writing `manifest.gen.json`                                                                            |
-| `--sdk`                        | Enable TypeScript SDK at `src/_gen` (same as `codegen.sdk: true`)                                             |
-| `--cli`                        | Enable Go CLI; **requires** `--cli-out` and `--cli-binary-name`                                               |
-| `--merge-tree <path>`          | Merge this generated tree into the write                                                                      |
-| `--cli-out <dir>`              | Go CLI output directory                                                                                       |
-| `--cli-binary-name <name>`     | Binary name                                                                                                   |
-| `--cli-config-name <name>`     | Optional config file name                                                                                     |
-| `--cli-default-base-url <url>` | Default base URL baked into the CLI                                                                           |
-| `--cli-env-prefix <prefix>`    | Env prefix for CLI config                                                                                     |
-| `--cli-module-path <path>`     | Go module path                                                                                                |
-| `--cli-sdk-module-path <path>` | Import an existing Go SDK instead of embedding one                                                            |
-
-CLI boolean flags **turn features on**. They do not turn plugin-configured features off. Plugin config is the source of truth for paths and SDK ports.
-
-Default plugin resolution (when a flag/`true` enables the feature):
-
-| Artifact               | Default path                                 | Default on?                        |
-| ---------------------- | -------------------------------------------- | ---------------------------------- |
-| Route tree             | `src/_gen/routes.gen.ts`                     | yes (`tree` defaults on)           |
-| Types                  | `src/_gen/types.gen.d.ts`                    | no                                 |
-| Manifest               | `src/_gen/manifest.gen.json`                 | no                                 |
-| OpenAPI                | `src/_gen/openapi.gen.json` (+ YAML sibling) | no, until `codegen.openApi` is set |
-| TS SDK                 | `src/_gen/sdk.*.gen.ts`                      | no                                 |
-| Python / Go / Rust SDK | only if `codegen.sdk.ports` is set           | no                                 |
-| Go CLI                 | only if `codegen.cli` object is set          | no                                 |
-
-Typical plugin config:
-
-```ts
-import { honey } from "@lovrozagar/honey/plugin"
-
-export default {
-	plugins: [
-		honey({
-			app: "src/app.ts",
-			watch: ["src/**/*.ts"],
-			codegen: {
-				tree: true,
-				types: true,
-				manifest: true,
-				openApi: { title: "My API", version: "1.0.0" },
-				sdk: {
-					name: "MySDK",
-					ports: {
-						typescript: { outDir: "src/_gen" },
-						python: { outDir: "sdk/python" },
-						go: { outDir: "sdk/go", modulePath: "example.com/myapi" },
-						rust: { outDir: "sdk/rust", crateName: "myapi" },
-					},
-				},
-				cli: { out: "cli", binaryName: "myapi" },
-			},
-		}),
-	],
-}
+```sh
+curl http://127.0.0.1:3000/health
+# ok
+# the API reference: open http://127.0.0.1:3000/docs
 ```
 
-`watch` patterns are anchored at the project root (`src/**/*.ts` matches `src/a/b.ts`, never `node_modules/x/src/a.ts`). A save that matches still gets its normal HMR update; generated outputs never retrigger a generation.
+Then generate a client from the app module itself, with no document to keep in step by hand:
 
-`codegen.invalidate` (default `"warn"`) lists mutations that declare no `invalidate` but have
-sibling read routes they plausibly affect. `"error"` to fail the build; `"off"` to silence it.
-
-`generateFromApp(app)` (from `@lovrozagar/honey/plugin`) is the in-process helper: it returns `{ routeTree, manifest?, openApi?, openApiYaml? }` without writing files.
-
-## Builder
-
-### Create the app
-
-```ts
-import { honey } from "@lovrozagar/honey"
-
-const app = honey<{ DATABASE_URL: string; API_KEY: string }>()
+```sh
+npx honey-clients generate --app src/app.ts --target ts --out generated
 ```
 
-The type argument is `ctx.env`. Pass the same object to `app.fetch(req, env)` or `app.serve({ env })`. On Cloudflare, `env` is the Worker bindings object.
+## The app
 
-### Routes and methods
+`honey<TEnv>()` returns an app typed to its runtime environment — a Worker's bindings, or whatever your adapter
+passes. The chain derives handles that share one settings graph: `basePath()` rebases every route registered through
+it, `context()` adds static values the handler finds on `ctx`, and `use()` installs middleware for that handle and
+its descendants.
 
 ```ts
-app.get("/items")
-app.post("/items")
-app.put("/items/:id")
-app.patch("/items/:id")
-app.delete("/items/:id")
-app.head("/items/:id")
-app.options("/items")
-app.all("/echo") // every method
-app.on(["GET"], "/health") // methods are always a list
-app.on(["GET", "HEAD"], "/resource") // same handler, extra methods
-```
-
-Each verb returns a **route builder**. Chain `.input()`, `.output()`, `.errors()`, `.boundary()`, `.meta()`, then finish with `.handler()` or `.proxy()`. After `.handler()` you are back on the app, so you can keep chaining routes.
+import { honey } from "@lovrozagar/honey"
 
-There is no `.head` convenience beyond `.head(path)` itself. Use `.on(["GET", "HEAD"], path)` when GET and HEAD share a handler.
+type Env = { GREETING: string }
 
-### Path matching
+const app = honey<Env>().basePath("/api").context({ startedAt: Date.now() })
 
-```ts
-app.get("/orgs/:orgId/members/:memberId").handler((ctx) => {
-	ctx.params.orgId
-	ctx.params.memberId
-	return ctx.res.json("ok", ctx.params)
-})
+app.get("/hello").handler((ctx) => ctx.res.json("ok", { greeting: ctx.env.GREETING, since: ctx.startedAt }))
 
-app.get("/files/*path").handler((ctx) => {
-	// GET /files/a/b/c  →  ctx.params.path === "a/b/c"
-	return ctx.res.json("ok", { path: ctx.params.path })
-})
+export default app
 ```
 
-- `:name` is one whole segment. Names use letters, digits, `_`, `$` and `-`; `/f/:name.json` is rejected at registration.
-- `:name?` is an optional last segment: `/items/:id?` serves `/items` and `/items/42`.
-- `*name` (or bare `*`, read as `ctx.params["*"]`) is the remainder of the path and must be the last segment.
-- Patterns are normalized: `admin/x`, `//admin/x` and `/admin/x/` all register `/admin/x`; `basePath("/api/")` is `/api`. `.` and `..` segments, query strings and fragments are rejected.
-- Precedence at each segment: static, then param, then wildcard. When the preferred branch dead-ends — no route further down, or no route for the request's method — the router backtracks to the next one. With `GET /users/me/settings` and `GET /users/:id/profile`, `/users/me/profile` reaches the second; with `GET /u/me` and `DELETE /u/:id`, `DELETE /u/me` reaches the second. A 405 lists every method of every route that matches the path.
-- Static paths (`/health`) use an O(1) map. Dynamic and wildcard segments walk the radix tree.
-
-#### Request paths
-
-Every request path is normalized once, before anything looks at it. The router, scoped middleware, `ctx.path`, `staticFiles()` and `proxy()` all see the same result, on every runtime:
-
-- Empty segments collapse: `//admin///users` is `/admin/users`.
-- Dot segments resolve: `/files/../admin` is `/admin`, never above the root; `%2e` counts as a dot.
-- A backslash is a `/`, and characters a URL path cannot hold raw (space, controls, `"`, `<`, `>`, `` ` ``, `{`, `}`, non-ASCII) are percent-encoded — what URL parsing does, so Deno (which hands the app the raw target) and Bun or Node (which parse it) route the same bytes the same way.
-- An encoded `/` or `\` (`%2F`, `%5C`) is **400**: a segment that decodes to a separator means one thing to this router and another to a proxy upstream or a file system. `app.encodedSlashes("allow")` keeps them encoded in the path so they decode into a param (`/repos/group%2Fproject` gives `id === "group/project"`); only allow them when nothing downstream treats a decoded slash as a separator.
-- Everything else stays percent-encoded in `ctx.path`; params are decoded when extracted.
-- A trailing slash is kept; `trailingSlash()` decides what it means.
-
-On Node, `serve()` also answers **400** for a `Host` header that is not `host[:port]` and for request targets other than `/path` or `http(s)://host/path`; on Deno, `serve()` (and `Deno.serve(app.fetch)`) reject such a `Host`, since Deno builds the request URL from it.
-
-Optional extra validation of params (beyond “it is a string”):
-
-```ts
-app
-	.get("/orgs/:orgId")
-	.input({ params: z.object({ orgId: z.string().uuid() }) })
-	.handler((ctx) => ctx.res.json("ok", { id: ctx.input.params.orgId }))
-```
+`context()` values are fixed at registration; per-request data belongs in middleware, which passes it through
+`next({ … })`.
 
-### Prefixes and slashes
+Settings sit on the same chain and apply to the whole app:
 
 ```ts
-const api = app.basePath("/api") // routes registered on `api` are prefixed
-app.trailingSlash("strip") // 308 /health/ → /health (Location is relative: /health)
-app.trailingSlash("enforce") // 308 /health → /health/
-app.trailingSlash("ignore") // both match (default)
-app.stripPrefix("/app") // inbound /app/api/x is matched as /api/x
-```
+import { honey } from "@lovrozagar/honey"
 
-- `basePath` returns a new handle; only routes registered through it (or handles derived from it) are prefixed.
-- `stripPrefix` is a gateway rewrite. Requests without the prefix still match. It will not strip a partial segment (`/apple` is not stripped by `/app`).
-- `.use(mw)` / `.basePath()` / `.context()` / `.meta()` return a new **handle** on the same app. A route captures its handle's chain, prefix, context values and meta when it is registered; serving any handle of the app behaves the same. The handle you call them on is unchanged, so `app.use(auth)` as a bare statement installs nothing — finalize (the first request, `toRouteTree()` or codegen) throws when a `use(mw)` handle never registers, mounts or serves anything, and when a route builder never got `.handler()`.
-- **Lifecycle.** An app is built, then finalized: the first request, `toRouteTree()` or codegen resolves every route's full middleware chain, scopes and error keys once into a per-app table, and requests only look routes up in it. Registering a route, a scope or a mount afterwards (dev/HMR patching, lazy plugins) is allowed: it moves the app to a new epoch, and the next request finalizes again. Served documents cache per epoch too. Finalize is where misconfiguration surfaces — a `use(mw)` handle that registers nothing, a builder without `.handler()`, a stale generated tree — as an error naming the route.
-- Settings — `trailingSlash`, `stripPrefix`, `encodedSlashes`, `trustProxy`, `errorFactory`, `defaultErrors`, `defaultBoundary`, `outputValidation`, `onError`, `onNotFound`, `onMethodNotAllowed`, error formatters, `errorI18n`, `logger`, `telemetry`, `tap`, `wsAdapter` — belong to the app: calling one on any handle applies to every handle and every route, registered before or after.
-
-### Context
-
-`ctx` is a `HoneyContext`. Fields:
-
-| Field                          | Meaning                                                                                    |
-| ------------------------------ | ------------------------------------------------------------------------------------------ |
-| `ctx.req`                      | Web `Request`; on Node serve, a Request-shaped view (see below)                            |
-| `ctx.res`                      | `HoneyRes` — see [Responses](#responses)                                                   |
-| `ctx.env`                      | Bindings you passed to `fetch` / `serve`                                                   |
-| `ctx.params`                   | Path params (`:id`, `*path`)                                                               |
-| `ctx.search` / `ctx.searchAll` | First value / all values of the query string (lazy)                                        |
-| `ctx.headers` / `ctx.cookies`  | Lazy records (lowercase cookie names as sent)                                              |
-| `ctx.ip`                       | Client IP, canonical; see [Client address](#client-address)                                |
-| `ctx.input`                    | Validated input when `.input()` is declared                                                |
-| `ctx.errors`                   | Typed error factory when `.errorFactory()` is set                                          |
-| `ctx.meta`                     | Merged route + chain `.meta()`                                                             |
-| `ctx.path`                     | Normalized request path after `stripPrefix`                                                |
-| `ctx.signal`                   | Aborts on disconnect, `timeout()` or shutdown; see [SSE and streaming](#sse-and-streaming) |
-| `ctx.routePattern`             | Registered pattern, e.g. `/users/:id`                                                      |
-| `ctx.realtime`                 | `{ publish, namespace(name).publish }` when realtime routes exist                          |
-| `ctx.tap(key, payload)`        | Queue a tap (only if `.taps()` was declared)                                               |
-| `ctx.background(promise)`      | `waitUntil` on Workers, otherwise fire-and-forget                                          |
-| `ctx.executionCtx`             | Workers `ExecutionContext` when `fetch` received one                                       |
-| `ctx.log`                      | Present when `logger({ instance })` middleware ran                                         |
-| `ctx.requestId`                | Present when `requestId()` middleware ran                                                  |
-| `ctx.timing`                   | Present when `serverTiming()` middleware ran                                               |
-
-Reserved keys that middleware / `.context()` **cannot** overwrite: every field above that Honey sets (`req`, `res`, `env`, `params`, `headers`, `cookies`, `search`, `searchAll`, `ip`, `path`, `signal`, `meta`, `errors`, …).
-
-`ctx.search`, `ctx.searchAll`, `ctx.headers` and validated `search`/`headers`/`form` records have no prototype, so a query like `?__proto__=x` or `?constructor=x` is plain data. Read them with `ctx.search.key`, `key in ctx.search` or `Object.hasOwn(ctx.search, key)`; they have no `hasOwnProperty` method.
-
-On Node, `ctx.req` reads the `IncomingMessage` directly instead of building a Fetch `Request` per request. It behaves like one (headers, body methods, `clone()`, `signal`; the same conformance tests run against both), but it is not one: `ctx.req instanceof Request` is `false`, and `new Request(ctx.req)` or `fetch(ctx.req)` throw. Pass it through `toFetchRequest(ctx.req)` (from `@lovrozagar/honey`) first; on other runtimes that returns `ctx.req` itself. The Fetch Request then owns the body, so read it through one or the other.
-
-#### Client address
-
-`ctx.ip` is the client's address in canonical form (`::ffff:1.2.3.4` is `1.2.3.4`, IPv6 lowercase and compressed), or `null` when unknown. `clientInfo(ctx)` (from `@lovrozagar/honey`) also returns the `protocol` and `host` the client used. One app setting decides all three, and every feature that needs them (`ipRestrict`, loggers, `proxy()`) reads the same answer:
+const app = honey()
+	.trailingSlash("strip")
+	.encodedSlashes("reject")
+	.outputValidation("always")
+	.errorFormat("problem+json")
+	.onNotFound((ctx) => new Response(`no route for ${new URL(ctx.req.url).pathname}`, { status: 404 }))
+	.onMethodNotAllowed((ctx) => new Response(null, { headers: { allow: ctx.allowed.join(", ") }, status: 405 }))
+
+app.get("/").handler((ctx) => ctx.res.text("ok", "up"))
+```
+
+| Setting                                          | What it does                                                           |
+| ------------------------------------------------ | ---------------------------------------------------------------------- |
+| `basePath(prefix)`                               | rebases every route and OpenAPI path registered through the handle     |
+| `context(values)`                                | static values on `ctx`, typed into the handler                         |
+| `use(mw)` / `use(path, mw)`                      | middleware for this handle and its descendants, or for one path        |
+| `route(prefix, sub)`                             | mounts a sub-app under a prefix                                        |
+| `meta(values)`                                   | app-level route meta every route inherits                              |
+| `errorFactory(factory)`, `defaultErrors(…)`      | the error factory routes throw from, and the keys every route declares |
+| `defaultBoundary(key)`                           | the error an unexpected throw becomes                                  |
+| `onError(handler)`                               | maps a thrown value to a response before error telemetry               |
+| `onNotFound(handler)`, `onMethodNotAllowed(…)`   | the two misses                                                         |
+| `logger(logger \| false)`, `requestLog(…)`       | where lines go, and the one-line-per-request log                       |
+| `telemetry(value)`                               | the tracing adapter (`otelAdapter`)                                    |
+| `errorFormat(format)`                            | `"honey"` (the default) or `"problem+json"` (RFC 9457)                 |
+| `defaultErrorFormatter`, `customErrorFormatter`  | your own error body, schema-checked                                    |
+| `outputValidation(mode)`                         | what a response that does not match its `.output()` does               |
+| `trailingSlash`, `encodedSlashes`, `stripPrefix` | path normalization, and the prefix a gateway already consumed          |
+| `wsAdapter(adapter)`                             | the WebSocket adapter, when `serve()` does not pick one                |
+| `fetch(request, env, ctx)`                       | the Fetch handler an adapter calls                                     |
+
+Full reference: [the app](https://github.com/lovrozagar/honey/blob/main/docs/app-settings.md).
+
+## Routing
+
+One method per call (`get`, `post`, `put`, `patch`, `delete`, `head`, `options`), `all` for any, and `on` for a named
+set. Paths take `:params` and a trailing `*` wildcard; `meta()` carries what the document says about the route.
 
 ```ts
-import "@lovrozagar/honey/trust" // needed for a hop count or a list; not for the default
-
-app.trustProxy(false) // default: the TCP peer is the client; X-Forwarded-* is ignored
-app.trustProxy(1) // one reverse proxy in front, appending to X-Forwarded-For (nginx, most load balancers)
-app.trustProxy(["10.0.0.0/8", "fd00::/8"]) // proxies recognized by address; the first other hop is the client
-```
+import { honey } from "@lovrozagar/honey"
+import { serveOpenApi } from "@lovrozagar/honey/openapi"
 
-- The peer address comes from the runtime: the socket on Node, `server.requestIP()` on Bun, `info.remoteAddr` on Deno, `CF-Connecting-IP` on Cloudflare Workers (the edge sets it; a client cannot). `app.fetch(req, env)` without a server reports no peer; in tests pass `testClient(app, { env, ip: "203.0.113.1" })`.
-- With a hop count, the client is the `X-Forwarded-For` entry the outermost trusted proxy wrote; entries further left were sent by the client and are never read. With ranges, trusted hops are skipped from the right. `X-Forwarded-Proto` and `X-Forwarded-Host` are read only through a trusted hop.
-- A value at the position the setting reads that is not an address makes `ctx.ip` `null`, never a guess. `X-Real-IP`, `Forwarded` and `True-Client-IP` are not read.
+const app = honey()
 
-```ts
 app
-	.context({ version: "1.0.0" })
-	.get("/")
-	.handler((ctx) => {
-		return ctx.res.json("ok", { version: ctx.version })
-	})
-```
-
-`ctx.res.json("ok", data)` is branded at the type level (`TypedResponse<"application/json", "ok">`) and is a real `Response` on Bun / Workers. On Node `serve()`, known-size bodies skip `new Response()` and write with `writeHead` / `end`.
-
-### Responses
-
-Every `ctx.res.*` method takes a **status key** (except `noContent`, `redirect`, `sse`, `stream`, `generate`, `raw`). Optional third argument (or last for the exceptions):
-
-```ts
-type ResponseOptions = {
-	status?: number // override numeric status (redirect only by default)
-	headers?: Record<string, string>
-	cookies?: Record<string, CookieOptions>
-}
+	.get("/users/:id")
+	.meta({ operationId: "users.get", summary: "One user", tags: ["users"] })
+	.handler((ctx) => ctx.res.json("ok", { id: ctx.params.id }))
 
-type CookieOptions = {
-	value: string
-	domain?: string
-	expires?: Date
-	httpOnly?: boolean
-	maxAge?: number
-	path?: string
-	sameSite?: "lax" | "none" | "strict"
-	secure?: boolean
-}
-```
+app.delete("/users/:id").handler((ctx) => ctx.res.noContent())
 
-```ts
-ctx.res.json("ok", { id: "1" })
-ctx.res.json(
-	"created",
-	{ id: "1" },
-	{
-		headers: { "x-request-id": "r1" },
-		cookies: { sid: { value: "abc", httpOnly: true, sameSite: "lax", path: "/" } },
-	},
-)
-ctx.res.text("ok", "hello")
-ctx.res.html("ok", "<h1>Hi</h1>")
-ctx.res.csv("ok", "id,name\n1,Ada")
-ctx.res.xml("ok", "<ok/>")
-ctx.res.binary("ok", new Uint8Array([0x48, 0x49]))
-ctx.res.noContent()
-ctx.res.redirect("/elsewhere") // 302
-ctx.res.redirect("/gone", { status: 301 })
-ctx.res.raw(new Response("passthrough"))
+serveOpenApi(app, { title: "Users", version: "1.0.0", docs: "scalar" })
 ```
 
-`__Host-` cookies require `secure: true`, `path: "/"`, and no `domain`.
-
-SSE / stream / generate: see [SSE and streaming](#sse-and-streaming).
-
-### Status keys
-
-`ctx.res.json("created", data)` sets HTTP 201. Use the snake_case key, not the number, except `redirect({ status })`.
-
-| Key                               | Code | Key                               | Code |
-| --------------------------------- | ---- | --------------------------------- | ---- |
-| `ok`                              | 200  | `bad_request`                     | 400  |
-| `created`                         | 201  | `unauthorized`                    | 401  |
-| `accepted`                        | 202  | `payment_required`                | 402  |
-| `non_authoritative_information`   | 203  | `forbidden`                       | 403  |
-| `no_content`                      | 204  | `not_found`                       | 404  |
-| `reset_content`                   | 205  | `method_not_allowed`              | 405  |
-| `partial_content`                 | 206  | `not_acceptable`                  | 406  |
-| `multi_status`                    | 207  | `proxy_authentication_required`   | 407  |
-| `already_reported`                | 208  | `request_timeout`                 | 408  |
-| `im_used`                         | 226  | `conflict`                        | 409  |
-| `multiple_choices`                | 300  | `gone`                            | 410  |
-| `moved_permanently`               | 301  | `length_required`                 | 411  |
-| `found`                           | 302  | `precondition_failed`             | 412  |
-| `see_other`                       | 303  | `content_too_large`               | 413  |
-| `not_modified`                    | 304  | `uri_too_long`                    | 414  |
-| `temporary_redirect`              | 307  | `unsupported_media_type`          | 415  |
-| `permanent_redirect`              | 308  | `range_not_satisfiable`           | 416  |
-| `internal_server_error`           | 500  | `expectation_failed`              | 417  |
-| `not_implemented`                 | 501  | `im_a_teapot`                     | 418  |
-| `bad_gateway`                     | 502  | `misdirected_request`             | 421  |
-| `service_unavailable`             | 503  | `unprocessable_entity`            | 422  |
-| `gateway_timeout`                 | 504  | `locked`                          | 423  |
-| `http_version_not_supported`      | 505  | `failed_dependency`               | 424  |
-| `variant_also_negotiates`         | 506  | `too_early`                       | 425  |
-| `insufficient_storage`            | 507  | `upgrade_required`                | 426  |
-| `loop_detected`                   | 508  | `precondition_required`           | 428  |
-| `not_extended`                    | 510  | `too_many_requests`               | 429  |
-| `network_authentication_required` | 511  | `request_header_fields_too_large` | 431  |
-|                                   |      | `unavailable_for_legal_reasons`   | 451  |
-
-`.output()` only accepts **2xx success keys** plus a `redirect` map. Error statuses belong on `.errors()`, not `.output()`.
-
-### Input
-
-`.input()` takes Standard Schema objects. `json` and `form` are mutually exclusive (one Content-Type per request).
+Sub-apps mount with `route()`, and `on()` registers one handler for several methods:
 
 ```ts
-app
-	.put("/in/all/:resourceId")
-	.input({
-		json: z.object({ title: z.string() }),
-		search: z.object({ draft: z.coerce.boolean().optional() }),
-		headers: z.object({ "x-request-id": z.string() }),
-		cookies: z.object({ sid: z.string() }),
-		params: z.object({ resourceId: z.string().min(1) }),
-	})
-	.handler((ctx) => {
-		ctx.input.json.title
-		ctx.input.search.draft
-		ctx.input.headers["x-request-id"]
-		ctx.input.cookies.sid
-		ctx.input.params.resourceId
-		return ctx.res.json("ok", { ok: true })
-	})
-```
+import { honey } from "@lovrozagar/honey"
 
-Form + file (Zod `z.file()` or equivalent):
+const admin = honey()
+admin.get("/stats").handler((ctx) => ctx.res.json("ok", { users: 1 }))
 
-```ts
-app
-	.post("/upload")
-	.input({ form: z.object({ title: z.string(), upload: z.file() }) })
-	.handler((ctx) => ctx.res.json("ok", { name: ctx.input.form.upload.name, title: ctx.input.form.title }))
+const app = honey()
+app.route("/admin", admin)
+app.on(["POST", "PUT"], "/webhooks/:source").handler((ctx) => ctx.res.json("accepted", { from: ctx.params.source }))
 ```
 
-Leave the body for the handler (no Honey parse):
+A gateway merges the route trees its services publish, each tree tagged with meta of its own:
 
 ```ts
-import { readableStream } from "@lovrozagar/honey/input"
-
-app
-	.post("/pipe")
-	.input({ json: readableStream(z.unknown()) })
-	.handler(async (ctx) => {
-		const body = ctx.req.body
-		return ctx.res.json("ok", { piped: body !== null })
-	})
-```
-
-Content-Type selection (case-insensitive, parameters ignored):
-
-- `application/json` or any `+json` type (`application/vnd.api+json`) → `json`
-- `application/x-www-form-urlencoded` or `multipart/form-data` → `form` (`req.formData()`)
-- Anything else — a missing Content-Type, a look-alike such as `application/jsonx`, or a header with two media types — is **415** `unsupported_media_type`.
-- A body the declared parser cannot read (malformed JSON or multipart, an empty JSON body) is **400** with `error_key: "malformed_body"` and `vars.format`. `onError` sees it as that 400 `HoneyError`.
-- Invalid input is **400** with `error_key: "validation_failed"` and `fields: { name: [{ error_key, message, path }] }`.
-
-A `json` or `form` schema is validated for every method that declares it, `DELETE` and `OPTIONS` included (a missing body is 415). Declaring one on a `GET` or `HEAD` route throws at registration — put that data in `search`.
-
-Repeated keys in `search` and `form` follow one policy, read from the schema's JSON Schema (Zod 4.2+, ArkType):
+import { mergeTree } from "@lovrozagar/honey"
+import type { RouteTree } from "@lovrozagar/honey/tree"
 
-- A key the schema types as an array always gets an array, even for one value — so a single file validates against `z.array(z.instanceof(File))`.
-- A key typed as a scalar gets the **first** value, the same one `ctx.search.key` returns.
-- With schemas that expose no JSON Schema (Valibot, Yup, Effect), one value is a scalar and a repeated key is an array.
+declare const orders: RouteTree
+declare const billing: RouteTree
 
-```ts
-// ?tag=a&tag=b&page=1&page=2
-app
-	.get("/items")
-	.input({ search: z.object({ tag: z.array(z.string()), page: z.coerce.number() }) })
-	.handler((ctx) => ctx.res.json("ok", ctx.input.search)) // { tag: ["a", "b"], page: 1 }
+const gateway = mergeTree([orders, { service: "orders" }], [billing, { service: "billing" }])
 ```
 
-Cookies with a repeated name keep the first; headers follow Fetch (repeated values joined with `, `).
+Full reference: [routing](https://github.com/lovrozagar/honey/blob/main/docs/routing.md).
 
-Valibot / ArkType work the same way — pass any Standard Schema:
+## Input and output
 
-```ts
-import * as v from "valibot"
-app
-	.post("/v")
-	.input({ json: v.object({ n: v.number() }) })
-	.handler((ctx) => ctx.res.json("ok", ctx.input.json))
-```
+`.input()` validates the request: `params`, `search`, `headers`, `json`, `form` and `text`, each a Standard Schema.
+`.output()` declares what the route answers, by media type and status key, and the declared response headers. A
+media type other than JSON is just another key, so an image or a CSV is as typed as a JSON body:
 
-### Output
+```ts
+import { honey } from "@lovrozagar/honey"
+import * as z from "zod"
 
-`.output()` maps content type → status key → schema. Only 2xx keys plus `redirect`.
+const app = honey()
 
-```ts
 app
-	.post("/items")
+	.get("/avatar/:id")
 	.output({
-		"application/json": {
-			created: z.object({ id: z.string() }),
-			ok: z.object({ id: z.string() }),
-		},
+		"image/png": { ok: z.instanceof(Uint8Array) },
+		headers: { ok: z.object({ etag: z.string() }) },
 	})
-	.handler((ctx) => ctx.res.json("created", { id: "1" }))
-```
-
-Declared content types unlock the matching `ctx.res` method at the type level:
-
-| Content type               | Method                                |
-| -------------------------- | ------------------------------------- |
-| `application/json`         | `json`                                |
-| `text/plain`               | `text`                                |
-| `text/html`                | `html`                                |
-| `text/csv`                 | `csv`                                 |
-| `application/xml`          | `xml`                                 |
-| `application/octet-stream` | `binary`                              |
-| `text/event-stream`        | `sse`                                 |
-| `redirect`                 | `redirect` (map of 3xx keys → `true`) |
-
-Always available: `noContent`, `raw`, `redirect`, `stream`. Also recognized in the map (no dedicated helper): `application/cbor`, `application/msgpack`, `application/pdf`.
-
-```ts
-app
-	.get("/go")
-	.output({ redirect: { found: true, moved_permanently: true } })
-	.handler((ctx) => ctx.res.redirect("/next"))
-```
-
-`.outputValidation("off" | "dev" | "always")` controls runtime checks. `"dev"` (typical) validates when `NODE_ENV !== "production"`. Mismatch is **500** (`output_validation_failed` or `output_content_type_mismatch`).
-
-```ts
-app.outputValidation("always")
+	.handler((ctx) =>
+		ctx.res.binary("ok", new Uint8Array([137, 80, 78, 71]), { contentType: "image/png", headers: { etag: '"v1"' } }),
+	)
 ```
 
-### Errors
-
-<!-- snippet:name errors-app -->
+A body you do not want in memory is input too: `readableStream()` hands the handler the stream itself.
 
 ```ts
-import { defineErrors, HoneyError, honey } from "@lovrozagar/honey"
-
-const errors = defineErrors({
-	unauthorized: "unauthorized",
-	org_slug_taken: "conflict",
-	item_not_found: {
-		status: "not_found",
-		schema: z.object({ reason: z.string() }),
-	},
-	api_error: "internal_server_error",
-	orgs_unavailable: "service_unavailable",
-})
+import { honey } from "@lovrozagar/honey"
+import { readableStream } from "@lovrozagar/honey/input"
+import * as z from "zod"
 
 const app = honey()
-	.errorFactory(errors)
-	.defaultErrors("unauthorized") // every route may throw these
-	.defaultBoundary("api_error") // unexpected throws become this key
-	.onError((error, ctx) => {
-		if (error instanceof HoneyError && error.errorKey === "org_slug_taken") {
-			return ctx.jsonFromError(error)
-		}
-		return undefined // fall through to default handling
-	})
-	.onNotFound((ctx) => ctx.jsonFromError(errors.item_not_found({ reason: "no route" })))
-	.onMethodNotAllowed((ctx) => {
-		// ctx.allowed is the Allow list
-		return new Response(null, { status: 405, headers: { allow: ctx.allowed.join(", ") } })
-	})
-```
-
-Throw from a handler:
-
-```ts
-throw ctx.errors.org_slug_taken({ vars: { slug: "acme" } })
-throw ctx.errors.item_not_found({ reason: "deleted" })
-throw ctx.errors.unauthorized({
-	fields: { token: [{ error_key: "required", message: "missing", path: "token" }] },
-	headers: { "www-authenticate": "Bearer" },
-})
-```
-
-Standard error JSON (matches OpenAPI / generated `_ErrEnvelope`):
-
-```json
-{
-	"error_key": "org_slug_taken",
-	"status": 409,
-	"status_key": "conflict",
-	"message": "org_slug_taken",
-	"success": false,
-	"fields": {}
-}
-```
-
-`vars` are **ICU input only** — used by `.errorI18n()` to interpolate the top-level `message`, and included in `HoneyError.serialize` for logs. They are **not** part of the public envelope. With i18n on, clients read the interpolated `message` (e.g. `"Slug acme is taken"`); they must not re-translate from `vars` + `error_key`.
 
-For structured client extras (numbers a CLI can chart, typed payloads), use a **custom-schema** error (`defineErrors({ key: { status, schema } })`) and its `data` body — not `vars`.
-
-Custom-schema errors serialize **the schema payload** as the body (not the envelope), unless you set `customErrorFormatter`.
-
-Per-route:
-
-<!-- snippet:continue errors-app -->
-
-```ts
 app
-	.post("/orgs")
-	.errors("org_slug_taken") // default errors ("unauthorized") need no listing
-	.boundary("orgs_unavailable") // this route's unexpected-throw key
-	.handler((ctx) => {
-		throw ctx.errors.org_slug_taken({ vars: { slug: "x" } })
+	.post("/ingest")
+	.input({ json: readableStream(z.object({ chunks: z.number(), fileName: z.string() })) })
+	.handler(async (ctx) => {
+		/* the schema is what the document and the clients promise; the body itself stays on the request */
+		const reader = (ctx.req.body as ReadableStream<Uint8Array>).getReader()
+		await reader.cancel()
+		return ctx.res.json("accepted", { taken: true })
 	})
 ```
 
-`.errors(factory, ...keys)` also accepts the factory object as the first argument (kitchen style). Undeclared `HoneyError` keys fail the boundary check and become the boundary error.
-
-Formatters:
-
-```ts
-app.defaultErrorFormatter((error, defaultShape) => ({
-	...defaultShape,
-	request_id: "r1",
-}))
-
-app.defaultErrorFormatter(z.object({ error_key: z.string(), status: z.number() }), (error) => ({
-	error_key: error.errorKey,
-	status: error.status,
-}))
-
-app.customErrorFormatter((error, data) => ({ ...data, error_key: error.errorKey }))
-```
-
-i18n (loads `@lovrozagar/honey/i18n` when called):
-
-```ts
-import "@lovrozagar/honey/i18n"
-
-app.errorI18n({
-	errors: {
-		en: { org_slug_taken: "Slug {slug} is taken", unauthorized: "Sign in" },
-		de: { org_slug_taken: "Name {slug} ist vergeben", unauthorized: "Anmeldung nötig" },
-	},
-	fieldNames: {
-		en: { email: "Email" },
-	},
-	resolveLocale: (ctx) => {
-		const accept = ctx.req.headers.get("accept-language")
-		return accept?.startsWith("de") ? "de" : "en"
-	},
-})
-```
-
-Messages are ICU: `{slug}`, `{n, number}`, `{n, plural, one {# item} other {# items}}`, `{k, select, a {A} other {X}}`. Pass matching values as `vars` on the throw. `cause` is reserved and is not a template var. Field `path` labels use `fieldNames`; field `message` strings are not interpolated with top-level `vars`.
-
-`HoneyError` fields: `errorKey`, `status` (number), `statusKey`, `fields`, `vars` (ICU / logs only), `data`, `headers`. `HoneyError.serialize(err)` is a JSON-safe dump for logs (includes `vars` when set; never put on the public JSON).
-
-Framework-owned keys you do not declare: `validation_failed` (400), `malformed_body` (400), `bad_request` (400, e.g. an encoded `/` in the path), `forbidden` (403, `csrf` / `ipRestrict`), `output_validation_failed` (500), plus routing / content-negotiation keys (`not_found`, `method_not_allowed`, `unsupported_media_type`, `content_too_large`, …).
-
-### Middleware
+Content negotiation, when a route answers in more than one shape, reads the request directly:
 
 ```ts
-import { createMiddleware, defineErrors, honey } from "@lovrozagar/honey"
+import { accepts } from "@lovrozagar/honey/accepts"
+import { honey } from "@lovrozagar/honey"
 
-const errors = defineErrors({ unauthorized: "unauthorized" })
-const app = honey().errorFactory(errors)
+const app = honey()
 
-const withAuth = createMiddleware(async (ctx: { req: Request }, next) => {
-	const token = ctx.req.headers.get("authorization")
-	if (!token) throw errors.unauthorized()
-	return next({ user: { id: "u-1" } })
+app.get("/report").handler((ctx) => {
+	const type = accepts(ctx.req, ["text/csv", "application/json"])
+	if (type === "text/csv") return ctx.res.csv("ok", "name,count\nada,1\n")
+	return ctx.res.json("ok", [{ count: 1, name: "ada" }])
 })
-
-const authed = app.use(withAuth) // routes registered on `authed` run withAuth
-authed.get("/me").handler((ctx) => ctx.res.json("ok", ctx.user))
-
-app.use("/admin", withAuth) // scoped: every request under /admin, whichever handle registered the route
-```
-
-`createMiddleware` infers additions from `next({ ... })`. Later handlers see `ctx.user`. Return `next()` with no argument to add nothing. Type the `ctx` parameter with the fields the middleware reads (`{ req: Request }`); a middleware can run on any route, so it throws errors from the factory itself (`errors.unauthorized()`) rather than `ctx.errors`, which handlers get typed. Without an error factory, throw a `HoneyError`.
-
-`.use(mw)` returns a new handle and leaves the one it is called on unchanged: keep the returned value (or keep chaining) and register routes on it. `app.use(mw)` as a bare statement installs nothing, and the first request (or codegen) throws to say so.
-
-What a route runs is fixed when it is registered or mounted, in this order: the chain of the handle it was registered on (a mounting handle's chain first), then every scope that covers it, then its own `.get(...).use(mw)`, then input validation.
-
-- **Scopes guard request paths.** `app.use("/admin", mw)` uses the route grammar (`/orgs/:id`, `/admin/*`) and covers every request whose path is under it — including requests that reach `all("/*")` or `/:section/users`, where the request path is checked at runtime. It applies to routes registered before or after it, on any handle, and to mounted sub-apps.
-- **Errors become responses at every `next()`.** A throw in a handler or a middleware is turned into the error response at that layer, so every middleware around it gets a `Response` from `await next()` and its post-`next()` code (CORS headers, request id, logging, timing) runs on errors too. A `try/catch` around `next()` no longer sees throws: read `ctx.error` instead — the `HoneyError` behind the error response (`errorKey`, `status`, and `cause`, the original throw when it was not a `HoneyError`), `undefined` when nothing failed. 404 and 405 are plain responses and leave it unset.
-
-  ```ts
-  const metrics = createMiddleware(async (ctx, next) => {
-  	const res = await next()
-  	record(res.status, ctx.error?.errorKey)
-  	return res
-  })
-  ```
-
-- **404, 405 and CORS preflight** run the same pipeline: the middleware every route of the app starts with, plus the scopes covering the request path, with `ctx.errors`, `ctx.path` and context values set. A preflight (`OPTIONS` with `Access-Control-Request-Method`) runs the chain of the route for the requested method, never its handler.
-- Middleware `errors` and `meta` count for every route the middleware runs on — chain, scoped or route level.
-- **Mounting** (`parent.route(sub)`): the sub's routes keep the sub's error factory, default errors, boundary, output validation, taps and context values; the parent's `onError`, formatters, logger and telemetry serve them. A sub-app's own `fetch` keeps serving the sub alone — mounting copies its routes and never changes it.
-
-### Shipped middleware
-
-Import each from its path. Do **not** `import { cors } from "@lovrozagar/honey"`. Each example keeps the handle `use()` returns — register routes on `api`. To run one for the whole app, put it at the start of the chain every route is registered on (`const app = honey().use(cors())`).
-
-#### `cors` — `@lovrozagar/honey/cors`
-
-```ts
-import { cors } from "@lovrozagar/honey/cors"
-
-const api = app.use(cors())
-const custom = app.use(
-	cors({
-		origin: "https://app.example.com", // or "*" | string[] | (origin) => boolean
-		credentials: true, // needs an explicit origin (string, list or predicate); with "*" or none, cors() throws
-		methods: ["GET", "POST"],
-		headers: ["authorization", "content-type"],
-		exposeHeaders: ["x-request-id"],
-		maxAge: 86400,
-	}),
-)
-```
-
-No `Origin` header → no CORS headers are added. Preflight is `OPTIONS` + `access-control-request-method`. `app.serve({ cors: true })` runs `cors()` with defaults before every route, 404 and preflight of the app. `app.serve({ cors: { origin } })` passes the object through, and throws at `serve()` for `credentials: true` without an origin.
-
-- `credentials: true` requires an explicit `origin`: a wildcard would let every site make credentialed requests and read the answers, so construction throws.
-- The opaque origin `null` (sandboxed iframes, `file:`) is never reflected; any page can produce it.
-- Every response carries `Vary: Origin` unless the policy is a plain `"*"`, so a shared cache never serves one origin's answer to another. 101 upgrade responses pass through untouched.
-- What it does not cover: CORS only decides what a browser lets a page _read_. It does not stop a cross-site form post or `no-cors` fetch from reaching the handler — use `csrf()` for that.
-
-#### `csrf` — `@lovrozagar/honey/csrf`
-
-```ts
-import { csrf } from "@lovrozagar/honey/csrf"
-
-const api = app.use(csrf({ origin: "https://app.example.com" }))
 ```
 
-Every unsafe request is checked, whatever its Content-Type (the algorithm of Go's `http.CrossOriginProtection`):
-
-1. `GET`, `HEAD` and `OPTIONS` pass.
-2. With `Sec-Fetch-Site` (every current browser sends it): `same-origin` and `none` pass. `same-site` and `cross-site` pass only for an `Origin` in `origin` (a string, list or predicate) — a sibling subdomain is same-site but not trusted.
-3. Without it: a request with no `Origin` passes (curl, server-to-server, clients a browser cannot drive cross-site), an `Origin` whose host equals `Host` passes, an allow-listed `Origin` passes, anything else is rejected.
-
-Failure is **403** `forbidden`. Cross-origin browser callers of your JSON API must be listed in `origin`. What it does not cover: safe methods (keep `GET` side-effect free), and same-origin attackers (XSS).
-
-#### `body-limit` — `@lovrozagar/honey/body-limit`
-
-```ts
-import { bodyLimit } from "@lovrozagar/honey/body-limit"
-
-const api = app.use(
-	bodyLimit({
-		maxSize: 1_048_576,
-		limits: { "application/json": 64_000, "multipart/": 10_485_760 },
-		trustContentLength: false, // default; true skips counting when Content-Length is in range
-	}),
-)
-```
+Full reference: [input and output](https://github.com/lovrozagar/honey/blob/main/docs/input-output.md).
 
-Applies to every request that has a body, `DELETE` included. Oversize is **413** `content_too_large`; the rest of the upload is drained up to 1 MiB so the client sees the 413, then the stream is cancelled. `limits` keys are media-type prefixes matched case-insensitively against the request's media type (parameters dropped, the shared Content-Type parser); the longest matching key wins. Node and Bun `serve()` also cap every request body at 128 MiB (`maxRequestBodySize`), with or without this middleware.
+## Responses
 
-#### `logger` — `@lovrozagar/honey/logger`
+`ctx.res` builds a typed response: `json`, `text`, `html`, `xml`, `csv`, `binary`, `noContent`, `redirect`, `raw` for
+a `Response` you made yourself, and `sse`, `stream` and `generate` for bodies that arrive over time. The first
+argument is the status key the route declared, which is what makes the payload's type the right one.
 
 ```ts
-import { createLogger, logger } from "@lovrozagar/honey/logger"
-
-const log = createLogger({
-	level: "info", // trace | debug | info | warn | error | fatal
-	base: { service: "api" },
-	write: (line) => console.log(line),
-})
-
-const api = app.use(logger())
-const custom = app.use(
-	logger({
-		instance: log, // pino-shaped; sets ctx.log
-		skip: (data) => data.path === "/health",
-		log: (data) => {
-			// used when instance is omitted
-			console.log(`${data.method} ${data.path} ${data.status} ${data.duration}ms`)
-		},
-	}),
-)
-```
-
-`createLogger` writes one JSON line per call (`level`, `msg`, `time`, plus `base`). `ctx.log.info("hello")` / `ctx.log.info({ k: 1 }, "hello")`. The logged `path` is the normalized `ctx.path` (no query string). A throwing `log`, `skip` or sink is reported with `console.error` and never turns the response into a 500.
+import { honey } from "@lovrozagar/honey"
 
-#### `curl-logger` — `@lovrozagar/honey/curl-logger`
+const app = honey()
 
-```ts
-import { curlLogger, defaultRedactHeader, defaultRedactQueryParam } from "@lovrozagar/honey/curl-logger"
-
-const api = app.use(
-	curlLogger({
-		body: { maxBytes: 2048, allowContentTypes: ["application/json"] },
-		redactHeader: (name, value) => (name === "x-tenant" ? "***" : defaultRedactHeader(name, value)),
-		redactQueryParam: (name, value) => defaultRedactQueryParam(name, value),
-		skip: (data) => data.path === "/health", // { duration, method, path, requestId, status }
+app.get("/page").handler((ctx) => ctx.res.html("ok", "<h1>hi</h1>"))
+app.get("/feed").handler((ctx) => ctx.res.xml("ok", "<feed />"))
+app.get("/old").handler((ctx) => ctx.res.redirect("/new"))
+app.get("/nothing").handler((ctx) => ctx.res.noContent())
+app.get("/bytes").handler((ctx) =>
+	ctx.res.stream(async (writable) => {
+		const writer = writable.getWriter()
+		await writer.write(new TextEncoder().encode("chunk"))
+		await writer.close()
 	}),
 )
 ```
 
-Credentials are masked by default: `authorization`, `cookie`, `set-cookie`, `proxy-authorization`, API-key and token headers, and token-like query params (`token`, `access_token`, `api_key`, `sig`, `code`, …) print as `[REDACTED]`. A custom `redactHeader` / `redactQueryParam` replaces the default — compose with the exported `defaultRedactHeader` / `defaultRedactQueryParam` to extend it; return `null` to drop the header or param. `skip` runs before the curl command is built. Every part of the command is shell-quoted (`-X 'POST'`, `$'…'` for control characters), so a logged command is safe to paste. A failing callback never fails the request.
-
-#### `request-id` — `@lovrozagar/honey/request-id`
-
-```ts
-import { requestId } from "@lovrozagar/honey/request-id"
-
-const api = app.use(requestId())
-const custom = app.use(requestId({ header: "x-request-id", generator: () => crypto.randomUUID() }))
-```
-
-Adds `ctx.requestId` and echoes the header on the response. Reuses an inbound id only when it is 1–128 characters of `A-Z a-z 0-9 . _ : + / = -` (UUIDs, ULIDs, base64, W3C trace ids); anything else is replaced with a generated id, so a client cannot put arbitrary text into your logs. `validate: (id) => boolean` overrides the check.
-
-#### `etag` — `@lovrozagar/honey/etag`
+Caching, entity tags and byte ranges are middleware and helpers over any of those:
 
 ```ts
+import { honey } from "@lovrozagar/honey"
+import { cacheControl } from "@lovrozagar/honey/cache-control"
 import { etag } from "@lovrozagar/honey/etag"
-
-const api = app.use(etag()) // weak ETag (default)
-const custom = app.use(etag({ weak: false }))
-```
-
-GET/HEAD only, and only on 200 responses. Never reads a stream: `sse()`, `stream()`, `generate()` and native bodies without a `content-length` pass through untagged. A handler-set `ETag` is kept. Responds **304** when `If-None-Match` matches (weak comparison, lists and `*`).
-
-#### `timeout` — `@lovrozagar/honey/timeout`
-
-```ts
-import { timeout } from "@lovrozagar/honey/timeout"
-
-const api = app.use(timeout({ duration: 5_000 }))
-```
-
-Slow handlers reject with **504** `request_timeout`, and `ctx.signal` aborts with a `TimeoutError` so the handler's work stops: pass the signal to `fetch()`, your database driver or anything else that takes one. Work that ignores it runs to completion and its response is dropped.
-
-#### `secure-headers` — `@lovrozagar/honey/secure-headers`
-
-```ts
-import { secureHeaders } from "@lovrozagar/honey/secure-headers"
-
-const api = app.use(secureHeaders())
-const custom = app.use(
-	secureHeaders({
-		contentSecurityPolicy: "default-src 'self'",
-		strictTransportSecurity: "max-age=63072000; includeSubDomains",
-		permissionsPolicy: "camera=()",
-		referrerPolicy: "strict-origin-when-cross-origin", // or false to omit
-		xContentTypeOptions: "nosniff", // or false
-		xFrameOptions: "SAMEORIGIN",
-		xXssProtection: "0",
-		crossOriginOpenerPolicy: "same-origin",
-		crossOriginEmbedderPolicy: "require-corp",
-		crossOriginResourcePolicy: "same-site",
-	}),
-)
-```
-
-Defaults when omitted: `x-content-type-options: nosniff`, `x-frame-options: SAMEORIGIN`, `referrer-policy: strict-origin-when-cross-origin`, `x-xss-protection: 0`. A header the handler already set wins (a route's stricter CSP is never overwritten). Works on immutable responses (`fetch()`, `Response.redirect()`) and leaves 101 upgrades alone.
-
-#### `server-timing` — `@lovrozagar/honey/server-timing`
-
-```ts
-import { serverTiming } from "@lovrozagar/honey/server-timing"
-
-const api = app.use(serverTiming())
-api.get("/work").handler((ctx) => {
-	ctx.timing.start("db", "query")
-	ctx.timing.end("db")
-	return ctx.res.json("ok", {})
-})
-```
-
-#### `ip-restrict` — `@lovrozagar/honey/ip-restrict`
-
-```ts
-import { ipRestrict } from "@lovrozagar/honey/ip-restrict"
-import "@lovrozagar/honey/trust"
-
-const api = app
-	.trustProxy(1) // behind one reverse proxy; see Client address
-	.use(
-		ipRestrict({
-			allowList: ["127.0.0.1", "10.0.0.0/8"],
-			denyList: ["192.168.1.50"],
-		}),
-	)
-```
-
-- The client address is `ctx.ip`, decided by `app.trustProxy()` — see [Client address](#client-address). `getIp: (req) => ...` replaces it with your own source.
-- Rules and addresses are compared as numbers, so `::ffff:203.0.113.7`, `203.0.113.7` and `203.0.113.7:51234` are one address, and `2001:DB8::1` equals `2001:db8::1`.
-- Construction throws on an invalid rule (`10.0.0.0/33`, `010.0.0.1`, `abc`), on `allowList: []` (it would reject everyone), and with no list at all.
-- Fails closed: a request whose address is unknown or not an address is **403**, for allow and deny lists alike. Denied / not-allowed is **403**.
-- What it does not cover: it trusts whatever `trustProxy()` says. Behind a proxy you did not declare, every request has the proxy's address.
-
-#### `powered-by` — `@lovrozagar/honey/powered-by`
-
-```ts
-import { poweredBy } from "@lovrozagar/honey/powered-by"
-
-const api = app.use(poweredBy()) // x-powered-by: Honey
-const custom = app.use(poweredBy({ name: "api" }))
-```
-
-#### `pretty-json` — `@lovrozagar/honey/pretty-json`
-
-```ts
 import { prettyJson } from "@lovrozagar/honey/pretty-json"
+import { rangeResponse } from "@lovrozagar/honey/range"
 
-const api = app.use(prettyJson()) // ?pretty=
-const custom = app.use(prettyJson({ query: "pretty", space: 2 }))
-```
-
-Rewrites buffered `application/json` (and `+json`) bodies when the query string has a parameter with exactly that name (`?pretty`, `?pretty=1`; not `?prettyx`). Streams, empty bodies and invalid JSON pass through untouched.
-
-#### What the middleware does not cover
+const video = new Blob([new Uint8Array(1024)], { type: "video/mp4" })
 
-| Middleware      | Does not cover                                                                                                                                       |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cors`          | Requests reaching the handler: it only controls what a browser lets a page read. Pair it with `csrf` for cookie-authenticated writes.                |
-| `csrf`          | Safe methods (keep `GET` side-effect free), same-origin attackers (XSS), non-browser clients (they have no ambient credentials to abuse).            |
-| `ipRestrict`    | Proxies you did not declare in `trustProxy()`: behind one, every request has the proxy's address.                                                    |
-| `bodyLimit`     | Bodies a handler reads before the middleware runs. Node and Bun `serve()` add their own cap (`maxRequestBodySize`).                                  |
-| `timeout`       | Work that ignores `ctx.signal` keeps running after the 504.                                                                                          |
-| `secureHeaders` | Content it does not see: a header the handler set wins, and the CSP is yours to write.                                                               |
-| `staticFiles`   | What `resolve` does with the path: it is safe to join onto a root, but symlinks inside the root are followed if your file API follows them.          |
-| `proxy()`       | Where requests go: build the URL from a fixed origin in `destination`, never from request data. Upstream responses are passed through, not filtered. |
-| `requestId`     | Uniqueness of inbound ids: a client can still send an id that collides with another request's.                                                       |
-| loggers         | Secrets in bodies (`curlLogger({ body })`) and in header or param names the default patterns miss; extend the redact callbacks.                      |
-
-### Composition
-
-```ts
-const users = honey()
-	.basePath("/users")
-	.get("/:id")
-	.handler((ctx) => ctx.res.json("ok", { id: ctx.params.id }))
-
-const app = honey().route(users) // merges routes, realtime, taps, static map
-const v1 = honey().route("/v1", users) // serves /v1/users/:id
-```
-
-`.route(sub)` copies the sub-app's routes into this one, under the chain of the handle you call it on: `app.use(auth).route(admin)` runs `auth` on every admin route. The sub's paths land under that handle's `basePath`, after the sub's own: `app.basePath("/v1").route(users)` serves `/v1/users/:id`, and `route("/v1", users)` is the same thing. The sub's scoped middleware and realtime routes move with it. Duplicate paths throw.
-
-### Taps
-
-Taps run **after** a successful handler. They do not run on thrown errors.
-
-```ts
 const app = honey()
-	.taps<{ audit: { action: string } }>()
-	.tap("audit", (ctx, payload) => {
-		ctx.background(
-			fetch("https://logs.example.com", {
-				method: "POST",
-				body: JSON.stringify({ path: ctx.req.url, ...payload }),
-			}),
-		)
-	})
-	.post("/items")
-	.handler((ctx) => {
-		ctx.tap("audit", { action: "create" })
-		return ctx.res.json("created", { id: "1" })
-	})
-```
-
-### Proxy routes
-
-Finish a route with `.proxy()` instead of `.handler()`. The proxy is not part of the core bundle: import its entry once in the app, or `.proxy()` throws at registration.
+	.use(etag())
+	.use(prettyJson({ query: "pretty" }))
+	.use(cacheControl({ public: true, maxAge: 60, staleWhileRevalidate: 300 }))
 
-```ts
-import "@lovrozagar/honey/proxy"
-
-app.all("/upstream/*path").proxy({
-	destination: (ctx, url, init) => fetch(`https://api.internal${url}`, init),
-	rewriteUrl: (url) => url.replace(/^\/upstream/, ""),
-	requestHeaders: { "x-forwarded-by": "honey" },
-	// or requestHeaders: (ctx, headers) => { headers.set("x-user", ctx.user.id) }
-	timeout: 10_000, // time to response headers (default 60 s); 0 for none; disabled for WS upgrades
-	idleTimeout: 30_000, // max gap between body chunks; omit for none (SSE)
-	onResponse: (ctx, response) => {
-		response.headers.set("x-proxied", "1")
-	},
-})
+app.get("/prices").handler((ctx) => ctx.res.json("ok", { eur: 1.08 }))
+app.get("/video").handler((ctx) => ctx.res.raw(rangeResponse(ctx.req, video)))
 ```
 
-`destination` receives the normalized path + query (after `rewriteUrl`) and a prepared `RequestInit` (method, headers, body for every method but GET/HEAD, a signal following `ctx.signal` and the timeouts, `redirect: "manual"`). Hop-by-hop headers and headers named in `Connection` are stripped both ways; the client's `Host`, `Expect` and forwarding headers are dropped, and `X-Forwarded-For`/`-Proto`/`-Host` describe the client as `trustProxy()` decided (`forwardedHeaders: false` to omit). Encoded responses lose `Content-Encoding`/`Content-Length` because `fetch()` decodes them (`decoded: false` for destinations returning encoded bytes). Network failures answer 502, a headers timeout 504, any other throw 500. `onResponse` gets a mutable copy and is not called for 101 upgrades.
+`etag()` answers a conditional GET with 304, `rangeResponse` a `Range` request with 206, and `cacheControl` sets the
+header once for every route under it. `httpDate` from the same subpath formats an HTTP date, and `notModified` from
+`@lovrozagar/honey/etag` turns a response into its 304.
 
-What it does not cover: `destination` decides where the request goes — build the URL from a fixed origin (as above), never from request data.
+Streaming bodies clean up when the client leaves — the generator's `finally` runs:
 
-### Static files
+```ts run
+import { honey } from "@lovrozagar/honey"
+import { serve } from "@lovrozagar/honey/serve"
 
-```ts
-import { staticFiles } from "@lovrozagar/honey/static"
+let ended = (_: string) => {}
+const cleanedUp = new Promise<string>((resolve) => (ended = resolve))
+
+const app = honey()
 
-const site = app.use(
-	staticFiles({
-		prefix: "/assets",
-		resolve: async (_ctx, filePath) => {
-			const file = Bun.file(`./public${filePath}`)
-			if (!(await file.exists())) return null
-			return new Response(file)
+app.get("/ticks").handler((ctx) =>
+	ctx.res.sse(
+		async (stream) => {
+			try {
+				for (let tick = 1; !stream.closed; tick++) {
+					await stream.send({ data: String(tick), event: "tick", id: String(tick) })
+					await new Promise((resolve) => setTimeout(resolve, 50))
+				}
+			} finally {
+				stream.close()
+				ended("cleaned up")
+			}
 		},
-		headers: { "cache-control": "public, max-age=3600" },
-		// or headers: (filePath) => ({ "content-type": mime(filePath) })
-		rewritePath: (filePath) => (filePath === "/" ? "/index.html" : filePath),
-	}),
+		{ defaultRetry: 3000 },
+	),
 )
-```
 
-GET/HEAD only. `resolve` returning `null` falls through to the next route.
+const server = await serve(app, { hostname: "127.0.0.1", port: 0 })
+const leave = new AbortController()
+const response = await fetch(`${server.url}/ticks`, { signal: leave.signal })
+const reader = (response.body as ReadableStream<Uint8Array>).getReader()
+const first = new TextDecoder().decode((await reader.read()).value)
+console.log(first.includes("retry: 3000") ? "retry sent" : "no retry")
+leave.abort()
+console.log(await cleanedUp)
+await server.close()
+// prints: retry sent
+// prints: cleaned up
+```
 
-- `staticFiles` matches `ctx.path` — the normalized path the router saw, after `stripPrefix` — on whole segments: `prefix: "/assets"` serves `/assets/x`, never `/assets-private/x`.
-- `filePath` is decoded once and contains no `.`, `..`, empty, NUL, `:`, `/` or `\` segments, so joining it onto a root directory cannot leave the root, on POSIX or Windows. Anything else, including malformed percent-encoding, falls through to the next handler. A `rewritePath` result is checked again.
-- `headers(filePath)` receives the same path `resolve` got. Headers are added copy-on-write, so a `Response` with immutable headers (from `fetch()` or a Workers `ASSETS` binding) works.
+Full reference: [streaming](https://github.com/lovrozagar/honey/blob/main/docs/streaming.md),
+[media types](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/media-types.md),
+[range requests](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/range.md) and
+[Cache-Control](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/cache-control.md).
 
-### Logging, telemetry, production tree
+## Errors
 
-App-level logger (Honey internals, not request logs):
+`defineErrors` maps your own keys to HTTP statuses and gives you the factory a route throws from. A route declares
+which keys it can throw with `.errors()`, and those keys are what the document and every generated client know
+about.
 
 ```ts
-app.logger({ warn: (msg, ...args) => console.warn(msg, ...args) })
+import { defineErrors, honey } from "@lovrozagar/honey"
+
+const errors = defineErrors({ out_of_stock: "conflict" })
+
+const app = honey().errorFormat("problem+json")
+
+app
+	.post("/orders")
+	.errors(errors, "out_of_stock")
+	.handler(() => {
+		throw errors.out_of_stock()
+	})
 ```
 
-OpenTelemetry-shaped adapter:
+`errorFormat("problem+json")` answers RFC 9457 Problem Details instead of honey's own body. Anything thrown becomes a
+`HoneyError`; `onError` sees it first, and `ERROR_META` is the symbol a thrown value carries its status under, so a
+value from elsewhere can present itself as one. `createErrorResponse` builds the body outside a request, which is
+what a custom formatter or a test harness needs.
 
 ```ts
-import { otelAdapter } from "@lovrozagar/honey/telemetry/otel"
-
-app.telemetry(otelAdapter({ tracer }))
-// or a hand-rolled adapter:
-app.telemetry({
-	onRequest: ({ req }) => {},
-	onRoute: ({ method, path, route, params }) => {},
-	onHandler: ({ route, status, duration }) => {},
-	onResponse: ({ status, duration }) => {},
-	onError: ({ error, duration }) => {},
-	onMiddleware: ({ name, duration, error }) => {},
-	onNotFound: ({ method, path }) => {},
-	onMethodNotAllowed: ({ allowed }) => {},
+import {
+	createErrorResponse,
+	defineErrors,
+	ERROR_META,
+	type ErrorFormatter,
+	HoneyError,
+	honey,
+} from "@lovrozagar/honey"
+
+const errors = defineErrors({ db_timeout: "service_unavailable" })
+
+const app = honey().onError((error, ctx) => {
+	if (error instanceof HoneyError && error.errorKey === "db_timeout") return ctx.jsonFromError(error)
+	return undefined
 })
-```
 
-`onResponse` fires exactly once for every request that fired `onRequest` — trailing-slash redirects, 404, 405, preflights, upgrades and errors included. `route` is the matched pattern (`/users/:id`); otel records it as `http.route` and never puts the query string in an attribute (`url.path`, `http.url` without query or fragment).
+app.get("/").handler((ctx) => ctx.res.text("ok", "up"))
 
-Production tree: load the generated `routes.gen.ts` before registering routes. The tree supplies only the router topology (route ids at the leaves) and per-route data (meta, error keys); every route the app registers afterwards binds to its leaf by `METHOD /pattern`. Several apps can load the same module: it is frozen, and each app serves its own handlers.
-
-```ts
-import { routeTree } from "./_gen/routes.gen.ts"
+/* a thrown value of your own, carrying the status honey should answer with */
+const refusal = Object.assign(new Error("nope"), { [ERROR_META]: { errorKey: "forbidden", status: 403 } })
 
-const app = honey().routeTree(routeTree)
-app.get("/health").handler((ctx) => ctx.res.text("ok", "ok"))
+/* the body an error answers with: the default shape, plus whatever your API adds to it */
+const formatter: ErrorFormatter = (error, defaultShape) => ({ ...defaultShape, retriable: error.status >= 500 })
+const answer = createErrorResponse(errors.db_timeout(), formatter, null, { format: "problem+json" })
 ```
 
-- A route the app registers that the tree does not hold, or a tree from an older honey, means the generated file is stale: the first request throws an error naming the routes. Run `honey generate`.
-- A tree leaf the app does not register is answered with 404 but still documented by `app.openapi()`.
-- Spec, docs and manifest routes are not part of the generated tree; `app.openapi()` mounts them either way.
-- `routeTree()` must come before any route registration and can be called once.
+Full reference: [problem+json](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/problem-json.md) and
+[logging, errors and tracing](https://github.com/lovrozagar/honey/blob/main/docs/observability.md).
 
-`app.toRouteTree()` snapshots an app — a copy of its topology plus each route's data and live handler. `mergeTree` from `honey` / `honey/tree` merges several trees (optional extra meta per tree) without touching its inputs. Loading a snapshot or a merge serves those live handlers; loading the same tree twice gives two independent apps.
+## Middleware
 
-Gateways: a gateway loads a tree that holds downstream routes it does not implement, and registers a root wildcard (`app.all("/*")`) as its catch-all. Every leaf without a local handler is delegated to the catch-all, which then runs with that route's own pattern (`ctx.routePattern`), params, meta and scoped middleware. Paths that are not in the tree 404 — for every method, including `HEAD` — without reaching the catch-all.
+A middleware is a function of `(ctx, next)`. Calling `next({ … })` adds typed values to the context every route below
+it sees — that is how per-request data (a user, a tenant, a database handle) reaches a handler without a global.
 
 ```ts
-import { routeTree } from "./_gen/routes.gen.ts"
+import { type MiddlewareFn, honey } from "@lovrozagar/honey"
+import { cors } from "@lovrozagar/honey/cors"
+import { rateLimit } from "@lovrozagar/honey/rate-limit"
+import { secureHeaders } from "@lovrozagar/honey/secure-headers"
+
+type UserCtx = { user: { id: string } | null }
 
-import "@lovrozagar/honey/proxy"
+const withUser: MiddlewareFn<{ req: Request }, UserCtx> = (ctx, next) => {
+	const token = ctx.req.headers.get("authorization")
+	return next({ user: token === null ? null : { id: "u1" } })
+}
+
+const app = honey()
+	.use(secureHeaders())
+	.use(cors({ origin: ["https://app.example.com"], credentials: true }))
+	.use(rateLimit({ limit: 100, windowMs: 60_000 }))
+	.use(withUser)
 
-const gateway = honey().routeTree(routeTree)
-gateway.all("/*").proxy({ destination: (ctx) => `https://${ctx.meta.worker}.internal${ctx.path}` })
+app.get("/me").handler((ctx) => ctx.res.json("ok", { user: ctx.user }))
 ```
 
-Gateway codegen: point `codegen.mergeTree` at a generate-only module that merges live downstream apps with `app.toRouteTree()`. Generated `routes.gen.ts` omits JSON Schema, so merging another service's generated tree documents no request or response bodies. `honey generate` copies the merged schemas onto the gateway app before it writes OpenAPI; the gateway runtime still serves its own generated tree.
+`createMiddleware` is the same thing with the context type given once, and `defineMiddleware` keeps a middleware
+reusable across apps:
 
 ```ts
-// gateway/src/route-tree.ts — codegen only, never imported at runtime
-import { mergeTree } from "@lovrozagar/honey"
-import { app as usersApp } from "@acme/users/app"
+import { createMiddleware, defineMiddleware, honey } from "@lovrozagar/honey"
+
+const requireKey = createMiddleware<{ req: Request }>((ctx, next) =>
+	ctx.req.headers.get("x-api-key") === null ? new Response(null, { status: 401 }) : next(),
+)
+
+const stamp = defineMiddleware({ fn: (_ctx: { req: Request }, next) => next({ at: Date.now() }) })
 
-export const tree = mergeTree([usersApp.toRouteTree(), { worker: "users" }])
+const app = honey().use(requireKey).use(stamp)
+app.get("/me").handler((ctx) => ctx.res.json("ok", { at: ctx.at }))
 ```
 
-`app.fetch(request, env, executionCtx?)` is always valid. Sync handlers return a `Response` directly; async handlers and middleware return a `Promise<Response>`. Callers should `await app.fetch(...)`.
+The bundled set, each its own subpath so an app that does not import it bundles none of it:
 
-## Serve
+```ts
+import { honey } from "@lovrozagar/honey"
+import { bodyLimit } from "@lovrozagar/honey/body-limit"
+import { compress } from "@lovrozagar/honey/compress"
+import { csrf } from "@lovrozagar/honey/csrf"
+import { ipRestrict } from "@lovrozagar/honey/ip-restrict"
+import { poweredBy } from "@lovrozagar/honey/powered-by"
+import { requestId } from "@lovrozagar/honey/request-id"
+import { serverTiming } from "@lovrozagar/honey/server-timing"
+import { timeout } from "@lovrozagar/honey/timeout"
 
-### Bun, Node, Deno
+const app = honey()
+	.use(requestId())
+	.use(poweredBy())
+	.use(serverTiming())
+	.use(timeout({ duration: 10_000 }))
+	.use(bodyLimit({ maxSize: 1024 * 1024 }))
+	.use(compress({ threshold: 2048 }))
+	.use(csrf({ origin: ["https://app.example.com"] }))
+	.use(ipRestrict({ allowList: ["203.0.113.0/24"] }))
+
+app.get("/report").handler((ctx) => ctx.res.text("ok", "row\n".repeat(5000)))
+```
+
+| Middleware                | From                               | What it does                                               |
+| ------------------------- | ---------------------------------- | ---------------------------------------------------------- |
+| `cors(options)`           | `@lovrozagar/honey/cors`           | the CORS headers and the preflight answer                  |
+| `secureHeaders(options?)` | `@lovrozagar/honey/secure-headers` | CSP, HSTS and the rest of the hardening headers            |
+| `csrf(options?)`          | `@lovrozagar/honey/csrf`           | refuses a cross-origin unsafe method                       |
+| `rateLimit(options)`      | `@lovrozagar/honey/rate-limit`     | a window per key, with `memoryStore()` or one of your own  |
+| `compress(options?)`      | `@lovrozagar/honey/compress`       | gzip or brotli over a threshold                            |
+| `cacheControl(options)`   | `@lovrozagar/honey/cache-control`  | the `Cache-Control` header, and `httpDate`                 |
+| `etag(options?)`          | `@lovrozagar/honey/etag`           | an entity tag, 304 on a conditional GET, and `notModified` |
+| `prettyJson(options?)`    | `@lovrozagar/honey/pretty-json`    | indents a JSON body when the query asks                    |
+| `requestId(options?)`     | `@lovrozagar/honey/request-id`     | one id per request, on the response and in the log         |
+| `timeout(options)`        | `@lovrozagar/honey/timeout`        | a deadline per request                                     |
+| `bodyLimit(options)`      | `@lovrozagar/honey/body-limit`     | refuses a body over a size                                 |
+| `ipRestrict(options)`     | `@lovrozagar/honey/ip-restrict`    | an allow or deny list over `ctx.ip`                        |
+| `serverTiming()`          | `@lovrozagar/honey/server-timing`  | `Server-Timing`, and `ctx.timing` to add to it             |
+| `poweredBy(options?)`     | `@lovrozagar/honey/powered-by`     | the `X-Powered-By` header                                  |
+| `staticFiles(options)`    | `@lovrozagar/honey/static`         | serves files under a prefix                                |
+| `curlLogger(options?)`    | `@lovrozagar/honey/curl-logger`    | logs each request as the command that would repeat it      |
+
+Full reference: [middleware](https://github.com/lovrozagar/honey/blob/main/docs/middleware.md),
+[rate limiting](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/rate-limit.md) and
+[compression](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/compress.md).
+
+## The request context
+
+The handler's `ctx` is one object, and these keys are reserved on it: `req`, `env`, `executionCtx`, `path`,
+`params`, `search`, `searchAll`, `headers`, `input`, `ip`, `res`, `errors`, `error`, `meta`, `routePattern`,
+`cookies`, `log`, `logger`, `signal`, `background` and `tap`. Everything else on `ctx` is yours, from `context()` or
+from a middleware's `next({ … })`.
 
 ```ts
-const handle = await app.serve({
-	port: 3000,
-	hostname: "0.0.0.0",
-	cors: true, // or a CORS options object
-	env: { DATABASE_URL },
-	runtime: "bun", // optional; detected if omitted
-})
+import { honey } from "@lovrozagar/honey"
 
-handle.url // http://127.0.0.1:3000
-handle.port
-handle.hostname
-handle.runtime // "bun" | "node" | "deno"
-await handle.close() // or close(timeoutMs), default 1000
+const app = honey()
+
+app.get("/where/:id").handler((ctx) => {
+	ctx.log.info({ id: ctx.params.id }, "asked")
+	ctx.background(Promise.resolve())
+	return ctx.res.json("ok", {
+		accept: ctx.headers.accept ?? null,
+		aborted: ctx.signal.aborted,
+		id: ctx.params.id,
+		ip: ctx.ip,
+		pattern: ctx.routePattern,
+		path: ctx.path,
+		tags: ctx.searchAll.tag ?? [],
+		verbose: ctx.search.verbose ?? null,
+	})
+})
 ```
 
-Defaults: `port` 3000, `hostname` `0.0.0.0` (Deno defaults to `127.0.0.1`). Bound `0.0.0.0` / `::` is printed as `127.0.0.1` in `url`.
+`background(promise)` keeps work alive past the response where the runtime allows it, `signal` aborts when the client
+leaves, and `log` is the request's logger with the request id already bound. `HoneyContext` is the class behind it
+and `HoneyRes` the response builder, both exported for a helper of your own that takes either.
 
-More options:
+## Cookies
 
-| Option               | Runtimes  | Meaning                                                                                  |
-| -------------------- | --------- | ---------------------------------------------------------------------------------------- |
-| `maxRequestBodySize` | Node, Bun | Largest request body in bytes; bigger is 413 and the connection closes. Default 128 MiB. |
-| `headersTimeout`     | Node      | `server.headersTimeout` (ms)                                                             |
-| `requestTimeout`     | Node      | `server.requestTimeout` (ms)                                                             |
-| `keepAliveTimeout`   | Node      | `server.keepAliveTimeout` (ms)                                                           |
-| `upgradeTimeout`     | Node      | How long an upgrade request may take to become a WebSocket (ms). Default 30 000.         |
+`ctx.cookies` reads them, and a response sets them. Signed cookies are a signer you build from your secrets, newest
+first, so a rotation keeps the old ones verifying:
 
-`close(timeout?)` is the same on every runtime: stop accepting connections, close WebSockets with 1001, let in-flight requests finish for up to `timeout` ms, then cut what is left (Deno has no forced close: a request still running finishes on its own).
+```ts
+import { honey } from "@lovrozagar/honey"
+import { createCookieSigner } from "@lovrozagar/honey/cookie-sign"
 
-`app.serve()` keeps an adapter you set with `app.wsAdapter(...)` (for example `nodeWebSocket({ keepalive })`), and attaches the runtime's default adapter otherwise.
+const signer = createCookieSigner([process.env.COOKIE_SECRET ?? ""])
+
+const app = honey()
 
-| Runtime | How it listens                                |
-| ------- | --------------------------------------------- |
-| Bun     | `Bun.serve({ fetch })` + `honey/ws/bun`       |
-| Node    | `node:http` + `honey/serve` + `honey/ws/node` |
-| Deno    | `Deno.serve` + `honey/ws/deno`                |
+app.post("/login").handler(async (ctx) => {
+	const session = await signer.sign("user-1")
+	const cookie = { value: session, httpOnly: true, secure: true, sameSite: "lax" as const, path: "/" }
+	return ctx.res.json("ok", { signedIn: true }, { cookies: { session: cookie } })
+})
 
-On Node, import `honey/serve` (or call `app.serve()`, which loads it) so the listen implementation is registered. The Node adapter wraps `IncomingMessage` instead of `new Request()` on the inbound hot path, and writes known JSON/text bodies with `res.end` instead of draining a Fetch `Response`.
+app.get("/me").handler(async (ctx) => {
+	const raw = ctx.cookies.session
+	const user = raw === undefined ? null : await signer.verify(raw)
+	return ctx.res.json("ok", { user })
+})
+```
 
-Low-level Node listen (same adapter, no runtime detect):
+`@lovrozagar/honey/cookie` has the header functions on their own (`serializeCookie`, `parseCookieHeader`) and
+`@lovrozagar/honey/cookie-sign` the one-shot `sign` and `verify`:
 
 ```ts
-import { serve } from "@lovrozagar/honey/node"
-const server = serve(app, { env: {}, port: 3000, hostname: "0.0.0.0" })
-await server.shutdown(10_000)
-```
+import { parseCookieHeader, serializeCookie } from "@lovrozagar/honey/cookie"
+import { sign, verify } from "@lovrozagar/honey/cookie-sign"
 
-`shutdown(timeout?)` stops accepting connections and lets in-flight requests finish. Responses that are already streaming (SSE, `generate()`) never finish on their own, so their `ctx.signal` aborts at once and they end; WebSockets get a 1001 close; handlers still working get until `timeout`, then their signal aborts and every connection, WebSockets included, is closed. Idle keep-alive connections close immediately.
+declare const req: Request
+declare const SECRET: string
+declare const OLD_SECRET: string
 
-The low-level `serve()` takes the same `maxRequestBodySize`, `headersTimeout`, `requestTimeout`, `keepAliveTimeout` and `upgradeTimeout` options, plus `onError(err)` for failures the adapter cannot hand to the app (default `console.error`; the client gets 500).
+const jar = parseCookieHeader(req.headers.get("cookie") ?? "")
+const header = serializeCookie("theme", { value: "dark", httpOnly: true, path: "/", sameSite: "lax" })
 
-On Node, bodies Honey built in memory, or that declare a small `content-length`, are written in one `res.end`. Anything else is piped as it is produced, whatever its content type, and the reader is cancelled when the client goes away. A streamed body's `content-length` is never trusted (Node chunks it), and hop-by-hop headers (`Connection`, `Keep-Alive`, `Transfer-Encoding`, and any header `Connection` names) on a Response are dropped: Node writes its own.
+/* a signature bound to the cookie's name; verify takes every secret still accepted, newest first */
+const signed = await sign("abc", SECRET, { name: "sid" })
+const value = await verify(signed, [SECRET, OLD_SECRET], { name: "sid" })
+```
 
-Only a WebSocket handshake takes Node's upgrade path. Any other `Upgrade` request (`h2c`, …) is served as the normal request it is, with its body. A rejected handshake (auth failure, 404, an SSE route) gets a real response with every header and its status text.
+Full reference: [cookies](https://github.com/lovrozagar/honey/blob/main/docs/cookies.md).
 
-`runtime: "cloudflare"` throws. Workers cannot listen.
+## Streaming, WebSockets and realtime
 
-Detect without serving:
+A WebSocket route is `ws(app, path)`; a resumable connection — one logical subscription over WebSocket, SSE or
+long-poll, whichever the client can hold — is `realtime(app, path, options)`. Both publish to rooms, and a plain
+route can publish into them.
 
 ```ts
-import { detectRuntime } from "@lovrozagar/honey"
-detectRuntime() // "bun" | "node" | "deno" | "cloudflare"
-```
+import { honey } from "@lovrozagar/honey"
+import { realtime } from "@lovrozagar/honey/realtime"
+import { ws } from "@lovrozagar/honey/ws"
 
-### Cloudflare Workers
+const app = honey()
 
-```ts
-import { cfWebSocket } from "@lovrozagar/honey/ws/cloudflare"
-import { app } from "./app.ts"
+ws(app, "/echo").handler({
+	onMessage(_ctx, socket, data) {
+		socket.send(data)
+	},
+})
 
-app.wsAdapter(cfWebSocket())
+const chat = realtime(app, "/chat/:room", {
+	namespace: "chat",
+	handler: (_ctx, conn) => {
+		conn.join("lobby")
+		conn.on("message", (payload) => conn.publish("lobby", payload))
+	},
+})
 
-export default {
-	fetch: (req: Request, env: Env, ctx: ExecutionContext) => app.fetch(req, env, ctx),
-}
+app.post("/announce").handler(async (ctx) => {
+	chat.publish("lobby", await ctx.req.json())
+	return ctx.res.json("ok", { sent: true })
+})
 ```
 
-`honey init --cf` writes this stub. Local e2e uses wrangler / workerd. The live proof worker is documented under [Live Cloudflare proof](#live-cloudflare-proof).
+A publisher outside a connection works the same way, which is what a ticker is:
 
-Adapters if you wire them yourself: `bunWebSocket` (`honey/ws/bun`), `nodeWebSocket` (`honey/ws/node`), `denoWebSocket` (`honey/ws/deno`), `cfWebSocket` (`honey/ws/cloudflare`). `app.serve()` attaches the matching one.
-
-### Feature auto-load
+```ts
+import { honey } from "@lovrozagar/honey"
+import { realtime } from "@lovrozagar/honey/realtime"
 
-`honey()` stays fetch-only until you opt in:
+const app = honey()
 
-| Call or import                                                             | Loads                                              |
-| -------------------------------------------------------------------------- | -------------------------------------------------- |
-| `app.serve()` or `import "@lovrozagar/honey/serve"`                        | Listen adapters                                    |
-| `app.openapi()` / `app.manifest()` or `import "@lovrozagar/honey/openapi"` | Spec + docs (codegen; live Zod)                    |
-| `import { spec } from "@lovrozagar/honey/openapi/spec"`                    | Spec walker (live tree; intern has no JSON Schema) |
-| `app.errorI18n()` or `import "@lovrozagar/honey/i18n"`                     | Error i18n                                         |
+const prices = realtime(app, "/prices", {
+	namespace: "prices",
+	handler: (_ctx, conn) => {
+		conn.join("ticker")
+	},
+})
 
-Production bundles that only call `app.fetch` do not pull listen, OpenAPI, or i18n code. The load uses an opaque `import(["@lovrozagar/honey", name].join("/"))` so bundlers do not follow unused feature entries.
+setInterval(() => prices.publish("ticker", { eur: 1.08, at: Date.now() }), 1000)
+```
 
-`createBuildPlugin` (`honey/build`) is a Vite plugin that injects those imports per target (`bun` | `node` | `deno` | `cloudflare`).
+`serve()` picks the adapter for Node and Bun; a Worker sets one itself. `createWsSession` from
+`@lovrozagar/honey/ws/session` is the session runtime those adapters share, for an adapter of your own:
 
 ```ts
-import { createBuildPlugin } from "@lovrozagar/honey/build"
+import { createWsSession } from "@lovrozagar/honey/ws/session"
+import { bunWebSocket } from "@lovrozagar/honey/ws/bun"
+import { cfWebSocket } from "@lovrozagar/honey/ws/cloudflare"
+import { nodeWebSocket } from "@lovrozagar/honey/ws/node"
+import { honey } from "@lovrozagar/honey"
 
-createBuildPlugin(
-	{ target: "bun", port: 3000, minify: true, outDir: "dist", external: [] },
-	{ entry: "src/app.ts", export: "app" }, // or export: "default"
-)
+/* each runtime's adapter; serve() sets the first two, a Worker entry the third */
+const adapters = [bunWebSocket(), nodeWebSocket(), cfWebSocket()]
+const app = honey().wsAdapter(cfWebSocket())
+
+/* the ordered lane a custom adapter drives: open, then messages, then close */
+const session = createWsSession({
+	callbacks: { onMessage: (_ctx, socket, data) => socket.send(data) },
+	ctx: {},
+	log: null,
+	reconnectToken: null,
+	route: "/echo",
+})
 ```
 
-Which features a bundle needs is detected from the app's import graph (`.openapi()` / `.manifest()`, `.errorI18n()`, `.serve()` calls). Force one on or off with `features: { openapi: true, serve: false }`.
+`nodeWebSocket()` needs the optional `ws` peer installed; the Bun and Workers adapters use their runtime's own
+sockets. A resumed connection replays from the client's `Last-Event-ID` or `reconnect_token`.
 
-## OpenAPI, docs, and manifest
+Full reference: [WebSockets, realtime and SSE](https://github.com/lovrozagar/honey/blob/main/docs/realtime.md) and
+[realtime resume](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/realtime-resume.md).
 
-```ts
-app.openapi({
-	title: "My API",
-	version: "1.0.0",
-	description: "Optional",
-	docs: "scalar", // or "swagger"
-	docsPath: "/docs", // default /docs, then /reference if a user route owns /docs
-	path: "/openapi", // stem → /openapi.json, .yaml, .yml
-	filterRoutes: (route) => route.path !== "/debug",
-	securitySchemes: {
-		bearerAuth: { type: "http", scheme: "bearer" },
-	},
-	enabled: process.env.NODE_ENV !== "production", // false mounts nothing; default true
-})
+## Serving on Node, Bun and Cloudflare Workers
 
-app.manifest()
-app.manifest({ path: "/manifest.json" })
-```
+One app runs on each of them; only how it is served differs.
 
-Each `openapi()` call serves its own document, so an internal and a public profile can live side by side at different paths (`openapi({ path: "/internal/openapi" })` and `openapi({ path: "/openapi", profile: "public" })`). A document is generated once per route change, serialized once, and sent with a strong `ETag` (a matching `If-None-Match` is 304), `Cache-Control: no-cache` and `X-Content-Type-Options: nosniff`. A generation that fails is not retried until the routes change. A path an earlier call or a user route already owns throws at the `openapi()` / `manifest()` call — give a second call its own `path` and `docsPath`.
+| Runtime            | How it runs                                                                       |
+| ------------------ | --------------------------------------------------------------------------------- |
+| Node               | `serve(app)` from `@lovrozagar/honey/serve`                                       |
+| Bun                | `serve(app)`, or `Bun.serve({ fetch: app.fetch })`                                |
+| Cloudflare Workers | `export default app` — the Worker's `fetch` handler, with named exports beside it |
 
-The docs UIs load pinned asset versions (Scalar 1.73.1, Swagger UI 5.33.1 from jsDelivr) with Subresource Integrity, under a per-response CSP nonce and `nosniff`; the inline config is escaped. The UI's spec URL includes `stripPrefix`.
+```ts
+import { detectRuntime, honey, toFetchRequest } from "@lovrozagar/honey"
+import { serve } from "@lovrozagar/honey/serve"
 
-Served (cached, invalidated when the route graph changes):
+const app = honey()
+app.get("/health").handler((ctx) => ctx.res.text("ok", detectRuntime()))
 
-| Path                             | Body                                               |
-| -------------------------------- | -------------------------------------------------- |
-| `/openapi.json`                  | OpenAPI 3.1                                        |
-| `/openapi.yaml` / `/openapi.yml` | Same document as YAML                              |
-| `/docs`                          | Scalar or Swagger UI pointing at the JSON spec     |
-| `/manifest.json`                 | Route methods, paths, middleware names, error keys |
+/* a request from an adapter that handed you its own Request subclass */
+declare const incoming: Request
+const request = toFetchRequest(incoming)
 
-Those routes are marked internal. They do not appear inside the spec or the manifest. Routes with `.meta({ internal: true })` are left out of the served document and the served manifest too. The served manifest follows the document's visibility policy: it carries only meta keys the `metaSpec` maps, plus the built-ins.
+const server = await serve(app, { hostname: "127.0.0.1", maxRequestBodySize: 8 * 1024 * 1024, port: 0 })
+console.log(server.url)
+await server.close()
+```
 
-`.meta({ operationId, tags, summary, description })` on a route feeds the document. App-level `.meta<Shape>()` / `.meta({ auth: "required" })` sets defaults and constrains route meta.
+`@lovrozagar/honey/serve` is the one to reach for: it resolves the runtime itself and returns a `ServeHandle` with
+the bound `url` and a `close()` that drains. `@lovrozagar/honey/node` is `node:http` directly, for an existing
+server or a framework that hands you one:
 
-Generate-time sanitize (plugin `codegen.openApi.sanitize`):
+```ts
+import { honey } from "@lovrozagar/honey"
+import { serve } from "@lovrozagar/honey/node"
 
-<!-- snippet:skip -->
+const app = honey()
+app.get("/health").handler((ctx) => ctx.res.text("ok", "ok"))
 
-```ts
-{
-  stripSecuritySchemes: ["legacy"],
-  stripSecurityRequirements: ["legacy"],
-  stripXExtensions: true,          // or ["x-internal"]
-}
+const server = await serve(app, { env: {}, port: 0 })
+await server.close()
 ```
 
-### Meta spec
-
-`.metaSpec()` declares what flows from route meta and route schemas into the document. Without it, the built-in policy maps the eight fields above and drops everything else silently.
+On Workers the app is the default export, and `app.fetch` the handler to wrap when you need to:
 
 ```ts
-const app = honey<Env>()
-	.meta<HoneyMeta<AppRouteMeta>>()
-	.metaSpec({
-		strict: "error", // an app meta key with no entry fails the build
-		meta: {
-			permissions: "x-permissions", // verbatim
-			rateLimit: { key: "x-rate-limit", map: (v) => ({ category: v, rps: RPS[v] }) },
-			worker: false, // deliberately internal — never emitted
-			captcha: false,
-		},
-		schema: {
-			// read off `.meta({ entity })` stamped on the route's schemas, fan out to several tags
-			entity: {
-				from: ["output"],
-				search: "deep", // looks inside `{ articles: [Article], nextCursor }` envelopes
-				expand: (e) => ({
-					"x-entity": e.table,
-					"x-generated": e.generated,
-					"x-soft-delete": e.softDelete ? { field: e.softDelete } : undefined,
-				}),
-			},
-		},
-		profiles: {
-			// allowlist — a tag added later stays out of the public document until opted in
-			public: { include: ["x-entity", "x-query"] },
-		},
-	})
-```
+import { honey } from "@lovrozagar/honey"
 
-Every key of the app's meta type needs an entry — mapped, or `false` — enforced by the type of the `meta` section and again at codegen. Route meta beats schema-derived facts; `meta.extensions` (a record of `x-*` keys) is the escape hatch and outranks both. `profile` on `app.openapi()` or on a `codegen.openApi` entry emits several documents with different extension sets from one policy. Codegen-time only; nothing runs per request.
+type Env = { readonly SECRET: string }
 
-Full reference, precedence rules, error taxonomy and migration path: [meta-spec.md](./docs/meta-spec.md).
+const app = honey<Env>()
+app.get("/health").handler((ctx) => ctx.res.text("ok", "ok"))
+
+export default { fetch: (...args: Parameters<typeof app.fetch>) => app.fetch(...args) }
+```
 
-#### Middleware-contributed meta
+## Static files and proxying
 
-A fact that middleware already enforces should not be retyped on every route it protects:
+`staticFiles()` serves what a resolver of yours returns, so the bytes can come from a bundle, a KV store or a disk
+read — honey never assumes a filesystem.
 
 ```ts
-export const shard = createMiddleware(fn, { meta: { tenant: "project_id" } })
+import { honey } from "@lovrozagar/honey"
+import { cacheControl } from "@lovrozagar/honey/cache-control"
+import { staticFiles } from "@lovrozagar/honey/static"
 
-const tenant = app.use(shard) // every route registered on `tenant` — or app.use("/orgs", shard), or .get("/x").use(shard)
+const assets = new Map<string, Blob>([["/app.js", new Blob(["console.log(1)"])]])
+
+const app = honey()
+	.use(cacheControl({ public: true, maxAge: 3600 }))
+	.use(staticFiles({ prefix: "/assets", resolve: (_ctx, path) => assets.get(path) ?? null }))
 ```
 
-Explicit `.meta()` (route, then chain) always outranks a contributed value; among middleware, the one that runs later wins (chain, then scoped, then route level — the order they run in). Contributed meta lands in the route's `mt`, so it reaches `ctx.meta`, the manifest, and the policy — with `strict: "error"` a middleware cannot contribute a key that has no entry. A path-scoped middleware registered _after_ the routes it covers still applies to them, and mounted routes get the meta of the chain they are mounted on. `internal` may not be contributed, since a middleware that removed routes from the document would be invisible from both sides.
+`proxy()` is a handler that forwards, which is what makes an app a gateway: you own the destination call, so the
+upstream is explicit and nothing is reachable by accident.
 
-Resolved once when the app finalizes (first request, `toRouteTree()` or codegen), never per request, from the same chain the route runs. Change what a middleware contributes, then regenerate.
+```ts
+import { honey } from "@lovrozagar/honey"
+import { proxy } from "@lovrozagar/honey/proxy"
 
-## WebSockets
+const app = honey()
 
-```ts
-app.ws("/echo-ws").handler({
-	onOpen(_ctx, ws) {
-		ws.send("connected")
-		ws.send({ hello: true }) // objects are JSON.stringified
-	},
-	onMessage(_ctx, ws, data) {
-		ws.send(data) // string | ArrayBuffer
-	},
-	onReconnect(_ctx, ws, token) {
-		ws.send(JSON.stringify({ event: "reconnected", token }))
-	},
-	onClose(_ctx, _ws, code, reason) {},
-	onError(_ctx, _ws, error) {},
-})
+app.all("/billing/*").handler(
+	proxy({
+		destination: (_ctx, url, init) => fetch(`https://billing.internal.example.com${url}`, init),
+		requestHeaders: { "x-gateway": "edge" },
+		timeout: 10_000,
+	}),
+)
 ```
 
-`ws` is `{ send, close, readyState, bufferedAmount, raw }`. `readyState` is `0|1|2|3`. Sends before open are buffered (max 32); sends after close are dropped. `close(code, reason)` cuts a reason longer than 123 UTF-8 bytes to fit. Middleware on the chain runs for the HTTP upgrade, and so does `.input()` validation of search, headers and cookies (400 before the upgrade). Auth middleware works: throw to reject.
+Full reference: [static files](https://github.com/lovrozagar/honey/blob/main/docs/static.md) and
+[proxying and gateways](https://github.com/lovrozagar/honey/blob/main/docs/proxy.md).
 
-Callbacks run on one ordered queue per connection: `onOpen` (or `onReconnect`), then each message, then `onClose`, each awaited, so a message never runs before an async `onOpen` finished. A callback that throws or rejects goes to `onError`; without `onError`, or when `onError` throws itself, the error is logged (app logger, else `console.error`) and the queue moves on. Nothing a callback throws reaches the runtime. More than 1024 messages waiting for the handler close the connection with 1008.
+## The OpenAPI document
 
-**Origin.** Browsers let any page open a socket to any host and send that host's cookies with it. So by default a cross-origin upgrade that carries `Cookie` or `Authorization` gets **403**; same-origin upgrades, and requests without `Origin` (non-browser clients), pass. Allow other origins per route:
+`serveOpenApi(app, options)` returns the app with the document and its reference UI mounted; `generateOpenApi` gives
+you the document as a value instead, for a file you commit or a build step. Tags, servers with variables,
+externalDocs and webhooks are all declared, never guessed.
 
 ```ts
-app
-	.ws("/feed")
-	.origins(["https://app.example.com"]) // or "*", or (origin) => boolean
-	.handler({
-		onOpen(_ctx, ws) {
-			ws.send("hi")
-		},
-	})
-
-app.realtime("/rt", { allowedOrigins: ["https://app.example.com"], handler })
-```
-
-"Same origin" compares the `Origin` host with the request host (`clientInfo(ctx).host`, which follows `trustProxy`).
+import { honey } from "@lovrozagar/honey"
+import { serveOpenApi } from "@lovrozagar/honey/openapi"
 
-**Adapter options.** Every adapter takes the same options with the same defaults:
+const app = honey()
 
-| Option               | Default       | Meaning                                                                                                                                                                              |
-| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `maxPayload`         | 1 MiB         | Largest inbound message; bigger closes with 1009 (Bun drops the connection: 1006).                                                                                                   |
-| `backpressureLimit`  | 8 MiB         | Unsent outbound bytes before `backpressurePolicy` applies to the next `send()`.                                                                                                      |
-| `backpressurePolicy` | `"close"`     | `"close"` closes with 1013 (try again later); `"drop"` discards the message.                                                                                                         |
-| `idleTimeout`        | 120 000 ms    | Close a connection that received nothing (message or pong) for this long; quiet peers are pinged. `0` disables. Bun and Deno take whole seconds; Workers evicts idle sockets itself. |
-| `protocol`           | first offered | `(offered, req) => string \| null`: the subprotocol to answer with.                                                                                                                  |
+app
+	.get("/orders")
+	.meta({ summary: "List orders", tags: ["orders"] })
+	.handler((ctx) => ctx.res.json("ok", []))
+
+serveOpenApi(app, {
+	title: "Shop",
+	version: "1.2.0",
+	servers: [{ url: "https://{region}.api.example.com", variables: { region: { default: "eu" } } }],
+	tags: [{ name: "orders", description: "Placing and tracking orders" }],
+	docs: "scalar",
+})
+```
 
-`nodeWebSocket()` also takes `keepalive: { interval, timeout }`: ping every `interval` ms and terminate a peer whose pong is `timeout` ms late. Binary messages arrive as `ArrayBuffer` on every runtime.
+The document as a value, the route manifest, YAML, and either reference page explicitly:
 
 ```ts
-app.wsAdapter(nodeWebSocket({ maxPayload: 64 * 1024, keepalive: { interval: 30_000, timeout: 10_000 } }))
-```
+import { honey } from "@lovrozagar/honey"
+import { generateManifest, generateOpenApi, serveManifest, toYaml } from "@lovrozagar/honey/openapi"
+import { scalar } from "@lovrozagar/honey/openapi/scalar"
+import { swagger } from "@lovrozagar/honey/openapi/swagger"
 
-A GET **without** `Upgrade: websocket` to a WS/realtime path returns **426** with `upgrade: websocket`.
+const app = honey()
+app.get("/orders").handler((ctx) => ctx.res.json("ok", []))
 
-Reconnect: pass `?reconnect_token=` on the next handshake; Honey calls `onReconnect` instead of `onOpen`.
+const document = generateOpenApi(app, { info: { title: "Shop", version: "1.2.0" } })
+const manifest = generateManifest(app, {})
+const yaml = toYaml(document)
 
-`app.serve()` attaches the runtime adapter unless you set one. On Node it needs the `ws` package (an optional peer dependency). On Cloudflare, call `app.wsAdapter(cfWebSocket())` yourself. The adapters bring the websocket session runtime with them, so an app without websockets does not bundle it; a custom `WSAdapter` in a bundled build needs `import "@lovrozagar/honey/ws/session"`.
+serveManifest(app, { path: "/manifest.json" })
 
-## Realtime
+/* the two reference pages, if you mount one yourself rather than through docs: */
+const pages = [scalar({ title: "Shop", url: "/openapi.json" }), swagger({ title: "Shop", url: "/openapi.json" })]
+```
 
-A topic bus over WebSockets: connections join topics, and anyone can publish to a topic. Only the WebSocket transport ships, with no resume, replay or acknowledgements. A client that reconnects is a new connection. The realtime server is not part of the core bundle: import `@lovrozagar/honey/realtime` once in the app, or `app.realtime()` throws at registration.
+Webhooks — the requests your API sends out — are declared with the document, signature and all, so a generated
+client gets a typed parser and a verifier for them:
 
 ```ts
-import "@lovrozagar/honey/realtime"
+import { honey } from "@lovrozagar/honey"
+import { serveOpenApi } from "@lovrozagar/honey/openapi"
+import * as z from "zod"
 
-const authed = app.use(withAuth)
+const app = honey()
 
-authed.realtime("/realtime/chat/:roomId", {
-	namespace: "chat",
-	identify: (ctx) => ctx.user.id, // becomes conn.userId; a throw rejects the upgrade
-	handler: (ctx, conn) => {
-		const room = `room:${ctx.params.roomId}`
-		conn.join(room)
-		conn.send({ event: "joined", id: conn.id, userId: conn.userId })
-		conn.on("message", (payload) => {
-			conn.publish(room, { from: conn.userId, payload })
-		})
-		conn.on("close", () => {
-			conn.publish(room, { left: conn.userId })
-		})
+serveOpenApi(app, {
+	title: "Shop",
+	version: "1.0.0",
+	webhooks: {
+		orderShipped: {
+			body: z.object({ orderId: z.string(), shippedAt: z.string() }),
+			signature: { algorithm: "hmac-sha256", encoding: "hex", header: "x-signature", prefix: "sha256=" },
+			summary: "An order left the warehouse",
+		},
 	},
-	onError: (error, conn) => log.error({ error, conn: conn.id }),
-})
-
-// publishing from HTTP needs the same auth as the socket
-authed.post("/realtime/broadcast/:roomId").handler(async (ctx) => {
-	ctx.realtime.namespace("chat").publish(`room:${ctx.params.roomId}`, await ctx.req.json())
-	return ctx.res.json("ok", { published: true })
 })
 ```
 
-**Wire format.** Every frame, in both directions, is one JSON text. `conn.send(x)` and `publish(topic, x)` send `JSON.stringify(x)`, strings included (`"hi"`), and throw for values JSON cannot represent. An inbound text frame is parsed and handed to the `message` handler as is. Non-JSON and binary frames are dropped.
-
-**Namespaces.** Topics belong to a namespace. It defaults to the route's full path pattern, so two realtime routes never see each other's topics unless both set the same `namespace`. `ctx.realtime.namespace(name).publish(topic, data)` publishes from any request. `ctx.realtime.publish(topic, data)` works only while the app has exactly one namespace; with several it throws.
+Full reference: [the OpenAPI document](https://github.com/lovrozagar/honey/blob/main/docs/openapi.md) and
+[webhooks](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/webhooks.md).
 
-**Callbacks.** `handler`, then each inbound frame, then the `close` handler run in order, one at a time. Async callbacks are awaited. Frames that arrive before `conn.on("message")` wait for it. A throw or rejection goes to `onError`, or to the app logger when there is none; it never reaches the runtime. A failing `handler` closes the connection with 1011. On close, the connection leaves every topic before the `close` handler runs. After close, `join` and `send` do nothing, and `publish` still works, for "left" announcements.
+## The MCP server
 
-`conn`:
+There are two ways to serve your API's tools over the Model Context Protocol, and they run in different places. The
+standalone server `honey-clients generate --target mcp` writes needs Node, and is what a local stdio install
+(Claude Desktop, Claude Code, Cursor) starts. The mounted endpoint below runs wherever the app runs — Workers
+included — dispatches in process, and is guarded by the app's own auth. It is the one to use remotely.
 
-| Field                          | Meaning                                    |
-| ------------------------------ | ------------------------------------------ |
-| `id`                           | Connection id                              |
-| `userId`                       | What `identify(ctx)` returned, else `null` |
-| `transport`                    | Always `"ws"`                              |
-| `closed`                       | `true` once closed                         |
-| `state`                        | Mutable bag                                |
-| `join(topic)` / `leave(topic)` | Topic membership in this route's namespace |
-| `send(payload)`                | One JSON frame to this connection          |
-| `publish(topic, payload)`      | One JSON frame to everyone on the topic    |
-| `close(reason?)`               | Close with 1000 (reason cut to 123 bytes)  |
-| `on("message" \| "close", fn)` | Inbound frames / teardown                  |
+`mcp(app, path, handler, options)` mounts the handler `codegen.mcp` generated beside your app:
 
-`limits` (per connection):
-
-| Option             | Default | Past it                                                      |
-| ------------------ | ------- | ------------------------------------------------------------ |
-| `maxTopics`        | 128     | `join` throws                                                |
-| `maxFrameBytes`    | 1 MiB   | close 1009                                                   |
-| `maxPendingFrames` | 64      | close 1008 (frames waiting for a slow or missing handler)    |
-| `maxBufferedBytes` | 4 MiB   | `slowConsumer`: `"close"` (1013, default) or `"drop"` frames |
+```ts
+import { honey } from "@lovrozagar/honey"
+import { type McpHandler, mcp } from "@lovrozagar/honey/mcp"
 
-`maxBufferedBytes` applies where the runtime reports how much it holds for a client (`bufferedAmount`). Cap inbound frame size at the adapter as well, because the runtime reads a frame before Honey sees it.
+/* in the app: import { mcpHandler } from "./_gen/mcp.gen.ts" */
+declare const mcpHandler: McpHandler
 
-The `use` option adds middleware for this socket only. Duplicate `realtime()` paths throw, and so do the unsupported `reconnectBuffer` and `transports` options. The bus is in-process: it does not cross processes or Cloudflare isolates (REST publish to another connection is skipped on the CF e2e env).
+const app = honey()
+mcp(app, "/mcp", mcpHandler, {
+	authenticate: (request) => /^ApiKey \S+$/.test(request.headers.get("authorization") ?? ""),
+})
+```
 
-## SSE and streaming
+Three opt-ins ride on the mount. `oauth()` makes the endpoint an OAuth 2.1 resource server (RFC 9728 metadata and
+Bearer challenges), which is what ChatGPT requires; `uploads()` takes files out of band, so a large file never goes
+through a tool argument; `urlFiles()` lets a file argument be an https URL from a host you list.
 
 ```ts
-app.get("/events").handler((ctx) =>
-	ctx.res.sse(
-		async (stream) => {
-			if (stream.lastEventId) {
-				await stream.send({ event: "resume", data: `from ${stream.lastEventId}` })
-			}
-			try {
-				for (const update of await feed.since(stream.lastEventId, { signal: stream.signal })) {
-					await stream.send({ event: "data", data: update, id: update.id })
-				}
-			} finally {
-				stream.close()
-			}
-		},
-		{ defaultRetry: 3000, keepalive: 15_000 },
-	),
-)
-```
+import { honey } from "@lovrozagar/honey"
+import { type McpHandler, mcp } from "@lovrozagar/honey/mcp"
+import { oauth } from "@lovrozagar/honey/mcp/oauth"
+import { memoryUploadStore, uploads } from "@lovrozagar/honey/mcp/uploads"
+import { urlFiles } from "@lovrozagar/honey/mcp/url-files"
 
-`Last-Event-Id` is read automatically. Event names and ids must not contain newlines. `keepalive` writes `: heartbeat` comments.
+/* in the app: import { mcpHandler } from "./_gen/mcp.gen.ts" */
+declare const mcpHandler: McpHandler
+declare const UPLOAD_SECRET: string
 
-```ts
-app.get("/stream").handler((ctx) =>
-	ctx.res.stream(async (writable, signal) => {
-		const w = writable.getWriter()
-		while (!signal.aborted) {
-			await w.write(new TextEncoder().encode("chunk"))
-			await sleep(1_000)
-		}
+const app = honey()
+mcp(app, "/mcp", mcpHandler, {
+	authenticate: (request) => /^ApiKey \S+$/.test(request.headers.get("authorization") ?? ""),
+	oauth: oauth({
+		authorizationServers: ["https://auth.example.com"],
+		resource: "https://mcp.example.com/mcp",
+		resourceName: "Example",
+		scopesSupported: ["mcp:read"],
 	}),
-)
-
-app.get("/gen").handler((ctx) =>
-	ctx.res.generate(
-		(async function* () {
-			try {
-				yield "one"
-				yield "two"
-			} finally {
-				/* runs on a normal end, a disconnect, a timeout or shutdown */
-			}
-		})(),
-		{ contentType: "text/plain", status: 200 },
-	),
-)
+	uploads: uploads({ secret: UPLOAD_SECRET, store: memoryUploadStore() }),
+	urlFiles: urlFiles({ hosts: ["files.example.com"] }),
+})
 ```
 
-All three share one lifecycle:
-
-- **Lazy start.** The callback (or generator) runs when the body is first read. A HEAD request, or middleware that replaces the response, never starts it.
-- **One end.** The stream ends when the producer finishes, when the client disconnects, or when `ctx.signal` aborts (`timeout()`, server shutdown). `stream.signal` / the `signal` argument abort with it, a generator gets `return()` so its `finally` runs, and the keepalive timer is cleared.
-- **Writes after the end.** `stream.send()` and `writer.write()` reject with an `AbortError`, which ends an awaiting loop. Honey does not report that rejection, and an unawaited send never becomes an unhandled rejection. `stream.close()` is synchronous and idempotent, so it is safe in a `finally`.
-- **Errors.** A callback or generator that throws breaks the body (the client sees an aborted transfer, not a clean end) and is logged through the app logger, or `console.error` without one.
-- **Flushing.** `ctx.res.stream()` ends the body after queued writes flush when the callback returns, whether or not you closed the writable.
+`memoryUploadStore()` is for one process; on Workers the store is yours (a Durable Object for the claim, R2 for the
+bytes), and the MCP page shows that end to end. Only a route marked `meta({ mcp: true })` becomes a tool, and each
+tool's input and output schemas come from the route's own.
 
-`ctx.signal` is the same signal for any handler: it aborts when the client disconnects, when `timeout()` fires, or when the server shuts down. On Deno, `request.signal` also aborts once a response has been delivered (Deno's legacy behavior; it prints a notice the first time a handler listens), so treat an abort after the response as normal.
+Full reference: [the generated MCP server](https://github.com/lovrozagar/honey/blob/main/docs/mcp.md) and
+[MCP structured output](https://github.com/lovrozagar/honey/blob/main/docs/capabilities/mcp-structured-output.md).
 
-## Generated clients
+## Logging and tracing
 
-One OpenAPI document, four printers. Parity: typed operations, typed errors, `onAuthExpired` + one 401 retry, cancellation, per-call timeout/headers, request/response hooks, invalidation, SSE, realtime, WebSocket, streaming bodies, `onLog`. Python and Rust also emit a sync runtime.
+`logger()` sets where lines go, `requestLog()` turns on the one line per request, and `onError` maps a thrown value
+to a response before the error is reported.
 
-### Plugin codegen config
+```ts
+import { HoneyError, honey } from "@lovrozagar/honey"
+import { createLogger } from "@lovrozagar/honey/logger"
+import { requestId } from "@lovrozagar/honey/request-id"
 
-See [honey generate](#honey-generate). `codegen.sdk: true` is TypeScript-only into `src/_gen`. Object form selects ports. `codegen.sdk.specs: ["a.json"]` builds from existing specs (no app required for SDK). `codegen.cli=true` is invalid — pass `{ out, binaryName }`.
+const app = honey()
+	.use(requestId())
+	.logger(createLogger({ level: "info" }))
+	.requestLog(true)
+	.onError((error, ctx) => {
+		if (error instanceof HoneyError && error.errorKey === "db_timeout") return ctx.jsonFromError(error)
+		return undefined
+	})
 
-### TypeScript `createClient`
+app.get("/").handler((ctx) => ctx.res.text("ok", "up"))
+```
 
-Hand-typed client against `InferRoutes<typeof app>` (no generate):
+Tracing is an adapter: `otelAdapter` nests `http.request` → `middleware.*` → `http.handler` and continues an incoming
+W3C `traceparent`, so a span from a caller stays one trace. With it on, the logger's child binds `trace_id` and
+`span_id`, and `requestId` stays the client-facing id.
 
-<!-- snippet:define client-app
 ```ts
 import { honey } from "@lovrozagar/honey"
-import * as z from "zod"
-
-const root = honey()
-root.ws("/echo-ws").handler({ onMessage: (_ctx, ws, data) => ws.send(data) })
-const app = root
-	.basePath("/api")
-	.get("/health")
-	.handler((ctx) => ctx.res.json("ok", { status: "ok" }))
-	.get("/users/:id")
-	.handler((ctx) => ctx.res.json("ok", { id: ctx.params.id }))
-	.post("/users")
-	.input({ json: z.object({ email: z.string(), name: z.string() }) })
-	.output({ "application/json": { created: z.object({ id: z.string() }) } })
-	.handler((ctx) => ctx.res.json("created", { id: "u-1" }))
-```
--->
-<!-- snippet:continue client-app -->
+import { createLogger } from "@lovrozagar/honey/logger"
+import { otelAdapter, type OtelApi } from "@lovrozagar/honey/telemetry/otel"
 
-```ts
-import { createClient, isClientError } from "@lovrozagar/honey/client"
-
-const client = createClient<typeof app>({
-	baseURL: "http://127.0.0.1:3000",
-	headers: { authorization: "Bearer t" },
-	timeout: 10_000,
-	throwOnError: false,
-	credentials: "include",
-	onAuthExpired: async () => "new-token",
-	onRequest: [
-		async (ctx) => {
-			ctx.headers.set("x-trace", "1")
-		},
-	],
-	onResponse: [async (ctx) => ctx.response],
-})
+declare const api: OtelApi
 
-/* Browser, same-origin: a path is resolved against location.origin.
-   Omit fetch — the default is the environment fetch, bound for window. */
-const sameOrigin = createClient<typeof app>({
-	baseURL: "/api",
-	credentials: "include",
-})
-
-const res = await client.get("/api/health")
-const created = await client.post("/api/users", { json: { email: "a@b.com", name: "Ada" } })
+const app = honey()
+	.logger(createLogger({ level: "info" }))
+	.telemetry(otelAdapter(api))
+	.requestLog(true)
 
-client.$url("/api/users/:id", { params: { id: "1" }, search: { x: "1" } })
-client.$path("/api/users/:id", { params: { id: "1" } })
-const ws = client.ws("/echo-ws", { reconnectToken: "t" })
+app.get("/").handler((ctx) => ctx.res.text("ok", "up"))
 ```
 
-`baseURL` may be an absolute `http(s):` / `ws(s):` URL or a same-origin path (`"/api"`). Paths resolve against `location.origin`. Omit `fetch` to use the environment `fetch` (bound for browsers). In Node and Workers without an origin, pass an absolute URL.
-
-Per-call options: `json`, `form`, `search`, `params`, `headers`, `cookies`, `timeout`, `signal`, `lastEventId`.
+A request logged as the command that would repeat it is its own middleware, and the same formatter is available on
+its own for a failing call you want to paste into a terminal — both redact credentials by default:
 
-More config:
+```ts
+import { honey } from "@lovrozagar/honey"
+import { curlLogger } from "@lovrozagar/honey/curl-logger"
+import { requestToCurl } from "@lovrozagar/honey/request-to-curl"
 
-- `onAuthExpired({ rejectedToken })` runs on a 401 and returns the new token; the request is retried once with it (not for stream bodies). The token goes in `authHeaderName` (default `Authorization`) with `authHeaderPrefix` (default `"Bearer "`).
-- `redirect` — redirects are followed only to the same origin by default, so custom auth headers never follow a cross-origin redirect.
-- `requestId: false` stops the client from sending `x-request-id` (which makes every cross-origin request preflighted).
-- A path param that is `""`, `.` or `..` throws `PathParamError` before anything is sent.
+declare const req: Request
 
-`throwOnError: true` throws `ClientError` subclasses (`BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, … `GatewayTimeoutError`). `isClientError(e)` is the guard. In safe mode, `error` is set (truthy) for every non-2xx, even when the body is empty or not JSON.
+const app = honey().use(curlLogger())
+app.get("/").handler((ctx) => ctx.res.text("ok", "up"))
 
-Awaiting a call to an SSE route returns an async iterable of events: `for await (const ev of await client.get("/events"))`. On `client.ws(...)`, text frames go to `"message"` and binary frames to `"binary"` (an `ArrayBuffer`).
+/* the authorization header left out of the logged command */
+const command = await requestToCurl(req, { excludeHeader: (name) => name === "authorization" })
+```
 
-### Generated SDK usage
+Full reference: [logging, errors and tracing](https://github.com/lovrozagar/honey/blob/main/docs/observability.md).
 
-After `honey generate` with `codegen.sdk.ports.typescript`:
+## Internationalization and crypto
 
-```ts
-import { MySDK, isClientError, UnauthorizedError } from "./_gen/sdk.index.gen.ts"
-
-const sdk = new MySDK({
-	baseURL: "http://127.0.0.1:3000",
-	headers: { Authorization: "Bearer t" },
-	onAuthExpired: () => Promise.resolve("new-token"),
-	onLog: (entry) => console.debug(entry.event, entry.operation, entry.duration_ms),
-	onRequest: [
-		(ctx) => {
-			ctx.headers["X-Trace-Id"] = crypto.randomUUID()
-		},
-	],
-	throwOnError: true,
-	timeout: 10_000,
-	invalidation: { staleTime: 5 },
-})
+Error messages translate through a dictionary you supply, and ICU messages interpolate with plurals:
 
-const browserSdk = new MySDK({
-	baseURL: "/api",
-	credentials: "include",
-	throwOnError: true,
-})
+```ts run
+import { interpolate } from "@lovrozagar/honey/i18n"
 
-const user = await sdk.createUser({ json: { email: "a@b.com", name: "Ada" } })
+const message = "{count, plural, one {# new message} other {# new messages}} for {name}"
+console.log(interpolate(message, { count: 3, name: "Ada" }, "en"))
+// prints: 3 new messages for Ada
 ```
 
-- Method names come from `operationId`; an operation without one gets a derived name from its method and path (`getUsersById`). One `operationId` that expands to several methods or optional-param variants gets a method or variant suffix.
-- A resource name that would shadow a client member or an `Object.prototype` key (`state`, `dispose`, `then`, `toString`) gets a trailing `_` (`sdk.state_`). Schemas named like SDK or language types get a `Model` suffix in Go, Rust and Python (`Config` → `ConfigModel`).
-- A path param that is `""`, `.` or `..` is refused before sending. Redirects are followed only to the same origin by default (`redirect` option). In safe mode, `error` is truthy for every non-2xx.
-- The same request rules hold in every language (base path and query kept, `URLSearchParams` query encoding, one auth refresh for concurrent 401s, no retry of streamed bodies); a shared conformance suite runs them against each generated SDK.
+```ts
+import { defineErrors, honey } from "@lovrozagar/honey"
+import { errorI18n, translateError } from "@lovrozagar/honey/i18n"
 
-Python / Go / Rust: point `ports.*.outDir` at a folder and import that package (`replace` in `go.mod`, `path =` in Cargo). Sync clients exist for Python and Rust only.
+const errors = defineErrors({ not_found: "not_found" })
 
-Capability details and four-language snippets: [SDK index](./docs/sdk.md) and [examples](https://github.com/lovrozagar/honey/tree/main/packages/core/examples).
+/* locale, then error key, then the ICU template that key's message reads from */
+const translations = { errors: { de: { not_found: "Nicht gefunden" }, en: { not_found: "Not found" } } }
 
-### Go CLI
+const app = honey().errorI18n(
+	errorI18n({ ...translations, resolveLocale: (ctx) => ctx.headers["accept-language"]?.slice(0, 2) ?? "en" }),
+)
 
-<!-- snippet:skip -->
+app.get("/books/:id").handler((ctx) => ctx.res.json("ok", { id: ctx.params.id }))
 
-```ts
-codegen: {
-  cli: {
-    out: "cli",
-    binaryName: "myapi",
-    modulePath: "example.com/myapi/cli",
-    sdkModulePath: "example.com/myapi",  // omit to embed the SDK
-    defaultBaseURL: "http://127.0.0.1:3000",
-    envPrefix: "MYAPI",
-    configName: "myapi",
-  },
-}
+const german = translateError(errors.not_found(), translations, "de")
 ```
 
-Equivalent CLI: `honey generate --cli --cli-out cli --cli-binary-name myapi`.
+Crypto is WebCrypto, with the comparison that does not leak by timing:
 
-### Programmatic codegen
+```ts run
+import { timingSafeEqual } from "@lovrozagar/honey/crypto"
 
-```ts
-import {
-	generateOpenApi,
-	generateManifest,
-	generateSDK,
-	generateRouteTreeFromApp,
-	mergeSpecs,
-	sanitizeOpenApiSpec,
-} from "@lovrozagar/honey/codegen"
-import { generateGoCLI } from "@lovrozagar/honey/codegen-go-cli"
-
-const spec = await generateOpenApi(app, { info: { title: "API", version: "1" } })
-const { files } = generateSDK(spec, { name: "MySDK", stem: "sdk" })
+const expected = "s3cret-token"
+console.log(await timingSafeEqual("s3cret-token", expected), await timingSafeEqual("guess", expected))
+// prints: true false
 ```
 
-Language printers used by the plugin (`generatePythonSDK`, `generateGoSDK`, `generateRustSDK`) are not separate package exports — call `honey generate`.
-
-## Type inference
-
-Exported from `@lovrozagar/honey`. They describe the **app you built**:
-
-| Type                                                                         | Meaning                              |
-| ---------------------------------------------------------------------------- | ------------------------------------ |
-| `InferRoutes<typeof app>`                                                    | Path → methods → input/output/errors |
-| `InferRoutePaths<typeof app>`                                                | Union of paths                       |
-| `InferRouteMethods<typeof app, Path>`                                        | Methods on one path                  |
-| `InferRouteInput<typeof app, Path, Method>`                                  | Validated input                      |
-| `InferRouteOutput<typeof app, Path, Method>`                                 | Output map                           |
-| `InferRouteErrors<typeof app, Path, Method>`                                 | Declared error keys                  |
-| `InferRouteMeta<typeof app, Path, Method>`                                   | Route meta                           |
-| `InferRouteCtx<typeof app, Path, Method>`                                    | Handler ctx for one route            |
-| `InferCtx<typeof app>`                                                       | Handler context (no `res` brand)     |
-| `InferEnv<typeof app>`                                                       | `ctx.env`                            |
-| `InferMeta<typeof app>`                                                      | App-level meta                       |
-| `InferErrorFactory<typeof app>`                                              | Error factory                        |
-| `InferBasePath<typeof app>`                                                  | Base path string                     |
-| `StatusKey` / `SuccessStatusKey`                                             | Status-key unions                    |
-| `HoneyCtx<TEnv>`                                                             | Untyped context shape                |
-| `HoneyServeOptions` / `ServeHandle` / `ServeRuntime`                         | Serve types                          |
-| `WSHandler` / `WSContext` / `WSAdapter`                                      | Socket types                         |
-| `ConnContext` / `RealtimeRouteOpts` / `RealtimeLimits` / `RealtimePublisher` | Realtime types                       |
-
-<!-- snippet:continue client-app -->
-
-```ts
-import type { InferCtx, InferRouteInput, InferRoutes } from "@lovrozagar/honey"
-
-type AppRoutes = InferRoutes<typeof app>
-type CreateInput = InferRouteInput<typeof app, "/api/users", "post">
-type Ctx = InferCtx<typeof app>
-```
+Full reference: [internationalization](https://github.com/lovrozagar/honey/blob/main/docs/i18n.md) and
+[crypto](https://github.com/lovrozagar/honey/blob/main/docs/crypto.md).
 
 ## Testing
 
-```ts
+`testClient(app, options)` calls the app the way a client would, in process by default — no port, no server — and
+over real HTTP when you ask for it. Request fields a handler reads but a test cannot easily forge, such as `ip`, are
+options rather than mocks.
+
+```ts run
+import { honey } from "@lovrozagar/honey"
 import { testClient } from "@lovrozagar/honey/testing"
 
-const client = testClient(app, { env: { DATABASE_URL: "…" }, cookies: true })
+const app = honey()
+app.get("/hello").handler((ctx) => ctx.res.json("ok", { hello: ctx.search.name ?? "world", ip: ctx.ip }))
 
-const res = await client.get("/api/health")
-await client.post("/api/users", {
-	json: { email: "a@b.com", name: "Ada" },
-	headers: { authorization: "Bearer t" },
-	search: { dry: "1" },
-})
-await client.post("/login", { form: { user: "a", pass: "b" } })
+const client = testClient(app, { env: {} })
+const answer = await client.get("/hello", { search: { name: "Ada" }, ip: "203.0.113.7" })
+console.log(answer.status, JSON.stringify(await answer.json()))
+// prints: 200 {"hello":"Ada","ip":"203.0.113.7"}
 ```
 
-Methods: `get` `post` `put` `patch` `delete` `head` `options` `request`. `cookies: true` stores `Set-Cookie` and sends them back; a cookie set with `Max-Age=0` (or a past `Expires`) is removed.
+Full reference: [testing an app](https://github.com/lovrozagar/honey/blob/main/docs/testing.md) and
+[SDK conformance](https://github.com/lovrozagar/honey/blob/main/docs/conformance.md), which is how the generated
+clients are held to behaving alike.
 
-`transport: "node"` serves the app with honey's Node adapter on a random local port and sends real HTTP, so the request goes through the Node `Request` view and response writer, as in production on Node. Call `await client.close()` when done.
+## The build plugin and the honey CLI
 
-## Utilities
+The Vite plugin writes the app's artifacts — the route tree, the types, the manifest, the OpenAPI document and the
+MCP handler — at build start, and again on each save in dev:
 
 ```ts
-import { accepts } from "@lovrozagar/honey/accepts"
-accepts(req, ["application/json", "text/html"]) // best match or first if no Accept
+import { honey } from "@lovrozagar/honey/plugin"
+import { defineConfig } from "vite"
 
-import { serializeCookie } from "@lovrozagar/honey/cookie"
-serializeCookie("sid", { value: "abc", httpOnly: true, path: "/" })
+export default defineConfig({
+	plugins: [honey({ app: "src/app.ts" })],
+})
+```
 
-import { sign, verify } from "@lovrozagar/honey/cookie-sign"
-const signed = await sign("abc", SECRET, { name: "sid" }) // binds the cookie name
-const raw = await verify(signed, [SECRET, OLD_SECRET], { name: "sid" }) // null if none match or malformed
-// `legacy: false` stops accepting signatures from earlier releases, which were not bound to a name
+What it generates is `codegen`, and each output takes a path or a config of its own:
 
-import { timingSafeEqual } from "@lovrozagar/honey/crypto"
-await timingSafeEqual(a, b)
+```ts
+import { honey } from "@lovrozagar/honey/plugin"
 
-import { requestToCurl } from "@lovrozagar/honey/request-to-curl"
-await requestToCurl(req, { excludeHeader: (n) => n === "authorization" })
+export default {
+	plugins: [
+		honey({
+			app: "src/app.ts",
+			codegen: {
+				manifest: true,
+				mcp: true,
+				openApi: { title: "Shop", version: "1.0.0", securitySchemes: {} },
+				tree: true,
+				types: { baseCtxName: "AppCtx" },
+			},
+			watch: ["src/**/*.ts"],
+		}),
+	],
+}
 ```
 
-`honey/openapi/spec` walks a live tree without pulling `codegen.ts`. Intern trees omit JSON Schema — serve generate-time OpenAPI JSON as Worker assets. `honey/openapi/scalar` and `honey/openapi/swagger` are the docs UIs `app.openapi()` loads. `honey/cli` is the generate/init binary. `honey/codegen/extract` is the ts-morph extractor used by `--types`.
-
-## Package exports
-
-Import features from their path.
-
-| Export                                                                                                                                                                                                                                                 | Purpose                                                                                                                |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| `@lovrozagar/honey`                                                                                                                                                                                                                                    | `honey`, `defineErrors`, `HoneyError`, `createMiddleware`, `HoneyRes`, Infer* types, `mergeTree`, `detectRuntime`      |
-| `honey/serve`                                                                                                                                                                                                                                          | Register Node/Bun/Deno listen                                                                                          |
-| `honey/node`                                                                                                                                                                                                                                           | Low-level Node `serve()`                                                                                               |
-| `honey/openapi`                                                                                                                                                                                                                                        | Register live spec generation (pulls codegen)                                                                          |
-| `honey/openapi/spec`                                                                                                                                                                                                                                   | Runtime spec walker — live tree, no codegen. Intern omits JSON Schema                                                  |
-| `honey/openapi/scalar` `honey/openapi/swagger`                                                                                                                                                                                                         | Docs UI                                                                                                                |
-| `honey/i18n`                                                                                                                                                                                                                                           | Register error i18n                                                                                                    |
-| `@lovrozagar/honey/plugin`                                                                                                                                                                                                                             | Vite plugin + `generateFromApp`                                                                                        |
-| `honey/client` / `honey/client/sdk`                                                                                                                                                                                                                    | Typed TS client runtime / generated-SDK helpers                                                                        |
-| `honey/cors` `honey/csrf` `honey/body-limit` `honey/logger` `honey/curl-logger` `honey/etag` `honey/timeout` `honey/request-id` `honey/secure-headers` `honey/server-timing` `honey/ip-restrict` `honey/powered-by` `honey/pretty-json` `honey/static` | Middleware                                                                                                             |
-| `honey/proxy`                                                                                                                                                                                                                                          | Registers `.proxy()` on route builders (import once); `ProxyConfig` type                                               |
-| `honey/realtime`                                                                                                                                                                                                                                       | Registers `app.realtime()` (import once)                                                                               |
-| `honey/trust`                                                                                                                                                                                                                                          | Registers hop counts and address lists for `app.trustProxy()` (import once)                                            |
-| `honey/input`                                                                                                                                                                                                                                          | `readableStream()`                                                                                                     |
-| `honey/testing`                                                                                                                                                                                                                                        | `testClient`                                                                                                           |
-| `honey/ws/bun` `honey/ws/node` `honey/ws/deno` `honey/ws/cloudflare`                                                                                                                                                                                   | WS adapters                                                                                                            |
-| `honey/ws/session`                                                                                                                                                                                                                                     | The websocket session runtime. Every honey adapter imports it; a custom `WSAdapter` in a bundled build imports it once |
-| `honey/accepts` `honey/cookie` `honey/cookie-sign` `honey/crypto` `honey/request-to-curl`                                                                                                                                                              | Utilities                                                                                                              |
-| `honey/telemetry/otel`                                                                                                                                                                                                                                 | `otelAdapter`                                                                                                          |
-| `honey/codegen`                                                                                                                                                                                                                                        | `generateOpenApi`, `generateSDK`, `generateManifest`, trees, sanitize                                                  |
-| `honey/codegen-go-cli`                                                                                                                                                                                                                                 | `generateGoCLI`                                                                                                        |
-| `honey/codegen/extract`                                                                                                                                                                                                                                | ts-morph chain extractor                                                                                               |
-| `honey/build`                                                                                                                                                                                                                                          | `createBuildPlugin`                                                                                                    |
-| `honey/tree`                                                                                                                                                                                                                                           | Tree types + `mergeTree`                                                                                               |
-| `honey/cli`                                                                                                                                                                                                                                            | `honey` binary                                                                                                         |
-| `honey/errors`                                                                                                                                                                                                                                         | `defineErrors` (also on the root export)                                                                               |
-
-## Repository layout
+`@lovrozagar/honey/build` adds the production bundle for a deploy target, so `vite build` emits one file to run:
 
-```
-packages/core/     published `honey` package (src, tests, docs, examples)
-e2e/apps/          consumer apps (kitchen, defaults, compose, surface, gateway)
-e2e/{bun,node,deno,cf-workers}/   runtime hosts + Playwright
-e2e/run.ts         env × app runner
-bench/             bombardier vs Hono / Elysia / Express / Nest (bun + node)
-```
+```ts
+import { createBuildPlugin } from "@lovrozagar/honey/build"
+import { defineConfig } from "vite"
 
-`e2e/apps/*` own the tests. Runtimes only listen. `HONEY_E2E_APP` and `HONEY_E2E_ENV` select which app and host.
-
-## Develop
-
-`packages/core` is the published package. `e2e/*` imports `honey` over `workspace:*`.
-
-Requires [Bun](https://bun.sh) 1.3+.
-
-```bash
-bun install
-bun run generate        # honey generate for every e2e app
-bun run test            # core unit + in-process integration (default CI)
-bun run test:consumers  # e2e apps import honey like a real app
-bun run test:e2e        # Playwright, bun × every e2e app
-bun run test:e2e:node   # same matrix against Node (tsx)
-bun run test:e2e:deno   # same matrix against Deno
-bun run test:e2e:cf     # same matrix against local wrangler / workerd
-bun run test:e2e:all    # bun + node + deno + local cf × every e2e app
-bun run typecheck            # core src (TypeScript 7)
-bun run typecheck:consumers  # every e2e app + generated types
-bun run lint                 # oxlint
-bun run lint:fix             # oxlint --fix
-bun run fmt                  # oxfmt
-bun run fmt:check            # oxfmt --check
+export default defineConfig({
+	plugins: [createBuildPlugin({ target: "cloudflare", minify: true }, { entry: "src/app.ts", export: "app" })],
+})
 ```
 
-Opt-in locally (CI `harness` job runs the first one):
+The `honey` CLI does the same generation without Vite, which is what a CI step or a `package.json` script wants:
 
-```bash
-bun run test:harness       # TS / Go / Python / Rust / MCP compile + behavioral
-bun run test:harness:rust  # rust-only subset of the same loop
-bun run test:all           # default suite + language harnesses
+```sh
+honey generate                       # reads vite.config.* and the honey() plugin in it
+honey generate --app src/app.ts --tree --types --manifest
+honey generate --config vite.config.ts --plugin 0 --watch
+honey generate --merge-tree src/_gen/routes.gen.ts   # a gateway's merged tree
+honey init --cf --force
 ```
 
-The harness needs Go, cargo and `python3` on PATH. Python packages come from
-`packages/core/tests/python-requirements.txt`: on first run the harness creates
-`.cache/python-venv` and installs them there, then reuses it until the file changes.
-Set `HONEY_PYTHON` to use your own interpreter instead. Without a usable Python
-(no `python3`, no `venv` module, or offline on first run) the Python tests skip
-with a warning; `HONEY_REQUIRE_PYTHON=1` (set in CI) turns that into a failure.
-
-Typecheck stays strict. Do not weaken `strict` or add `as any` to make it pass.
-
-### Test matrix
-
-| Command                  | What it proves                                                                   |
-| ------------------------ | -------------------------------------------------------------------------------- |
-| `bun run test`           | Core unit + integration. Default CI gate.                                        |
-| `bun run test:consumers` | Each e2e app imports `honey` and hits a few routes in-process.                   |
-| `bun run test:e2e`       | Playwright against Bun listen, every app.                                        |
-| `bun run test:e2e:node`  | Same tests, Node (`tsx`) listen.                                                 |
-| `bun run test:e2e:deno`  | Same tests, Deno listen.                                                         |
-| `bun run test:e2e:cf`    | Same tests, local workerd. Kitchen REST publish is skipped (`HONEY_E2E_ENV=cf`). |
-| `bun run test:build`     | Every app builds for every deploy target; artifacts and size budgets hold.       |
-| `bun run test:harness`   | Generated SDKs compile and behave.                                               |
-
-```bash
-bun e2e/run.ts --env node --app kitchen
-bun e2e/run.ts --env all --app surface
-bun e2e/run.ts --env bun --mode prod
-
-bun e2e/run-build.ts --app kitchen --target cloudflare
-bun e2e/run-build.ts --runtime all           # run the builds under node and bun
-bun e2e/run-build.ts --check-generated       # CI: a build must not rewrite committed files
-```
+| Flag                  | What it does                                                               |
+| --------------------- | -------------------------------------------------------------------------- |
+| `--config <path>`     | the Vite config holding `honey()` (default: `vite.config.{ts,mts,js,mjs}`) |
+| `--plugin <n>`        | which `honey()` plugin in the config, 0-based                              |
+| `--app <path>`        | the app entry; overrides the config's app, or replaces the config          |
+| `--tree`              | the route tree module                                                      |
+| `--types`             | the ambient types                                                          |
+| `--manifest`          | the route manifest                                                         |
+| `--merge-tree <path>` | the route tree source of a gateway                                         |
+| `--watch`             | generate again when files next to the app change                           |
 
-The build tier builds each e2e app through its own `vite.config.ts` plus
-`createBuildPlugin`, once per target (`node`, `bun`, `deno`, `cloudflare`). A cell
-passes when the build exits 0, emits `dist/<target>/index.js`, and stays under its
-gzipped size budget. The budget is not decoration: honey loads `zod` and `effect`
-dynamically, and a bundler that resolves one of those dynamic imports silently adds
-~300KB to every worker bundle. Size is the only signal that catches it.
+The SDKs, the CLI and the MCP server are honey-clients's: `honey-clients generate --app <path>`.
 
-### E2E apps and runtimes
+Full reference: [the build plugin](https://github.com/lovrozagar/honey/blob/main/docs/plugin.md).
 
-| App        | Covers                                                               |
-| ---------- | -------------------------------------------------------------------- |
-| `kitchen`  | Auth, CRUD, i18n, OpenAPI, SSE, WS, realtime, trailing slash, errors |
-| `defaults` | Empty-middleware app, root OpenAPI, no CORS by default               |
-| `compose`  | `.route()` groups, Scalar collision with a user `/docs`              |
-| `surface`  | Every input source, output type, method, SSE, WS, uploads            |
-| `gateway`  | `stripPrefix` + enforce slash, Swagger behind a prefix               |
+## Generated clients
 
-Runtimes: `e2e/bun`, `e2e/node`, `e2e/deno`, `e2e/cf-workers`.
+`honey-clients` reads the app module or the document and writes clients that know the routes:
 
-### Live Cloudflare proof
+```sh
+npx honey-clients generate --app src/app.ts --target ts --target python --out generated
+```
 
-Same kitchen app on workerd: https://honey-cf-e2e.lovro-zagar5.workers.dev
+A call answers your value and throws a typed error by status; its `client.safe` mirror answers the same calls as a
+`Result` instead, so a failure is a value rather than a throw. All six SDKs have both styles.
 
-See `e2e/cf-workers/README.md`. Redeploy with `bun run deploy:e2e:cf`. Live soak: `bun run test:live:cf`.
+```ts sdk
+import { DecodeError, Kitchen, NotFoundError } from "./kitchen"
 
-### Bench
+export function newClient(): Kitchen {
+	return new Kitchen({
+		baseURL: "https://api.example.com",
+		headers: { authorization: `Bearer ${process.env.KITCHEN_TOKEN ?? ""}` },
+		timeout: 10_000,
+	})
+}
 
-`bench/` compares Honey, Hono, Elysia, Express, and Nest on Bun and Node (naked + Zod). Bombardier, 10s / 100 connections, localhost.
+export async function organization(client: Kitchen, orgId: string): Promise<string | null> {
+	try {
+		await client.getApiV1OrganizationsByOrgId({ params: { orgId } })
+		return orgId
+	} catch (error) {
+		if (error instanceof NotFoundError) return null
+		throw error
+	}
+}
 
-```bash
-bun run --filter @honey/bench build:all
-bun run --filter @honey/bench bench:bun
-bun run --filter @honey/bench bench:node
+export async function health(client: Kitchen): Promise<string> {
+	const result = await client.safe.getApiHealth()
+	if (result.ok) return "up"
+	if (result.error instanceof DecodeError) return `unreadable answer: ${result.error.message}`
+	return `answered ${result.error.status}`
+}
 ```
 
-Numbers and bundle sizes: [`bench/RESULTS.md`](https://github.com/lovrozagar/honey/blob/main/bench/RESULTS.md).
-
-`bun run bench:hotpath` is the hot-path regression gate CI runs: in-process `app.fetch` cost on static, param, chain-middleware, scoped-middleware and 404 paths, as a ratio to a hand-written fetch handler in the same process, against `bench/hotpath-baseline.json` (`--update` records a new baseline). It fails when a ratio grows past `HOTPATH_THRESHOLD` (default 25%). Baselines are kept per Bun minor version.
-
-Python runtime tests skip without `httpx` (`pip install httpx`). Rust cargo tests skip without `cargo` or when `HONEY_RUST_INTEGRATION=0`. Go tests skip without `go`. Cargo artifacts go to `.cache/cargo-target`, not `/tmp`.
-
-## Releases
-
-The published package is [`@lovrozagar/honey`](https://www.npmjs.com/package/@lovrozagar/honey). That URL is the repository website. GitHub Releases match npm versions. Pushing a tag `vX.Y.Z` (same as this `package.json` `version`) runs the repo [`.github/workflows/release.yml`](https://github.com/lovrozagar/honey/blob/main/.github/workflows/release.yml): unit + typecheck + consumer tests, `npm publish` via trusted publishing, GitHub Packages, then a GitHub Release.
+That block is a verbatim slice of
+[the compiled example](https://github.com/lovrozagar/honey/blob/main/docs/examples/ts/example.ts): the tests
+type-check it against an SDK generated from a real document, so it cannot drift from what the generator writes.
+
+Full reference: [code generation](https://github.com/lovrozagar/honey/blob/main/docs/codegen.md),
+[the generated clients](https://github.com/lovrozagar/honey/blob/main/docs/client.md),
+[their per-language recipes](https://github.com/lovrozagar/honey/blob/main/docs/sdk-recipes.md),
+[the generated CLI](https://github.com/lovrozagar/honey/blob/main/docs/cli.md) and
+[releasing it](https://github.com/lovrozagar/honey/blob/main/docs/cli-release.md).
+
+## Every export
+
+Each feature is a subpath: import what the app uses, and a bundle carries nothing else. An app that never imports
+`@lovrozagar/honey/ws` bundles no WebSocket code, and one that never imports `@lovrozagar/honey/openapi` no document
+generator.
+
+| Export                              | What it holds                                                                                                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `@lovrozagar/honey`                 | `honey`, `HoneyError`, `defineErrors`, `createMiddleware`, `defineMiddleware`, `mergeTree`, `detectRuntime`, and the type helpers below |
+| `@lovrozagar/honey/serve`           | `serve(app, options)`: Node or Bun, whichever runs it                                                                                   |
+| `@lovrozagar/honey/node`            | `serve` for `node:http` directly                                                                                                        |
+| `@lovrozagar/honey/ws`              | `ws(app, path)`, a WebSocket route                                                                                                      |
+| `@lovrozagar/honey/ws/bun`          | `bunWebSocket`                                                                                                                          |
+| `@lovrozagar/honey/ws/node`         | `nodeWebSocket` (with the optional `ws` peer)                                                                                           |
+| `@lovrozagar/honey/ws/cloudflare`   | `cfWebSocket`                                                                                                                           |
+| `@lovrozagar/honey/ws/session`      | `createWsSession`: the session runtime a custom WebSocket adapter builds on                                                             |
+| `@lovrozagar/honey/realtime`        | `realtime(app, path, options)`: a resumable connection over WebSocket, SSE and long-poll                                                |
+| `@lovrozagar/honey/mcp`             | `mcp(app, path, handler, options?)`: the app's tools over MCP's Streamable HTTP, the handler `codegen.mcp` writes                       |
+| `@lovrozagar/honey/mcp/oauth`       | `oauth(options)`: `mcp()`'s opt-in OAuth 2.1 resource server (RFC 9728 metadata, Bearer challenges)                                     |
+| `@lovrozagar/honey/mcp/uploads`     | `uploads(options)`, `memoryUploadStore()`: `mcp()`'s opt-in out-of-band file uploads (the file-uploads extension's flow)                |
+| `@lovrozagar/honey/mcp/url-files`   | `urlFiles(options)`: `mcp()`'s opt-in file arguments as https URLs from listed hosts                                                    |
+| `@lovrozagar/honey/openapi`         | `serveOpenApi`, `serveManifest`, `generateOpenApi`, `generateManifest`, `toYaml`                                                        |
+| `@lovrozagar/honey/openapi/scalar`  | `scalar`, the Scalar API reference page                                                                                                 |
+| `@lovrozagar/honey/openapi/swagger` | `swagger`, the Swagger UI page                                                                                                          |
+| `@lovrozagar/honey/errors`          | `defineErrors` (also on the root)                                                                                                       |
+| `@lovrozagar/honey/i18n`            | `errorI18n`, `translateError`, `interpolate`, `createInterpolator`                                                                      |
+| `@lovrozagar/honey/input`           | `readableStream()`, a streamed request body as input                                                                                    |
+| `@lovrozagar/honey/range`           | `rangeResponse`, a `Range` request answered from bytes                                                                                  |
+| `@lovrozagar/honey/cache-control`   | `cacheControl`, `httpDate`                                                                                                              |
+| `@lovrozagar/honey/compress`        | `compress`                                                                                                                              |
+| `@lovrozagar/honey/etag`            | `etag`, `notModified`                                                                                                                   |
+| `@lovrozagar/honey/rate-limit`      | `rateLimit`, `memoryStore`                                                                                                              |
+| `@lovrozagar/honey/cors`            | `cors`                                                                                                                                  |
+| `@lovrozagar/honey/csrf`            | `csrf`                                                                                                                                  |
+| `@lovrozagar/honey/body-limit`      | `bodyLimit`                                                                                                                             |
+| `@lovrozagar/honey/timeout`         | `timeout`                                                                                                                               |
+| `@lovrozagar/honey/ip-restrict`     | `ipRestrict`                                                                                                                            |
+| `@lovrozagar/honey/request-id`      | `requestId`                                                                                                                             |
+| `@lovrozagar/honey/secure-headers`  | `secureHeaders`                                                                                                                         |
+| `@lovrozagar/honey/server-timing`   | `serverTiming`                                                                                                                          |
+| `@lovrozagar/honey/powered-by`      | `poweredBy`                                                                                                                             |
+| `@lovrozagar/honey/pretty-json`     | `prettyJson`                                                                                                                            |
+| `@lovrozagar/honey/logger`          | `createLogger`                                                                                                                          |
+| `@lovrozagar/honey/curl-logger`     | `curlLogger`, a request logged as a command that repeats it                                                                             |
+| `@lovrozagar/honey/telemetry/otel`  | `otelAdapter`                                                                                                                           |
+| `@lovrozagar/honey/static`          | `staticFiles`                                                                                                                           |
+| `@lovrozagar/honey/proxy`           | `proxy`, a route that forwards to an upstream                                                                                           |
+| `@lovrozagar/honey/accepts`         | `accepts`, content negotiation                                                                                                          |
+| `@lovrozagar/honey/cookie`          | `serializeCookie`, `parseCookieHeader`                                                                                                  |
+| `@lovrozagar/honey/cookie-sign`     | `sign`, `verify`, `createCookieSigner`                                                                                                  |
+| `@lovrozagar/honey/crypto`          | `timingSafeEqual`                                                                                                                       |
+| `@lovrozagar/honey/request-to-curl` | `requestToCurl`                                                                                                                         |
+| `@lovrozagar/honey/testing`         | `testClient`, an app called in process or over `serve`                                                                                  |
+| `@lovrozagar/honey/tree`            | the route tree's types and helpers                                                                                                      |
+| `@lovrozagar/honey/plugin`          | `honey()`, the Vite plugin that generates the app's artifacts                                                                           |
+| `@lovrozagar/honey/build`           | `createBuildPlugin`, a production bundle for a deploy target                                                                            |
+
+The root export's values: `honey()` and the `Honey` class behind it, `HoneyContext` and `HoneyRes` (the handler's
+`ctx` and its `ctx.res`), `HoneyError`, `defineErrors` and `ERROR_META`, `createErrorResponse`, `createMiddleware`
+and `defineMiddleware`, `mergeTree`, `detectRuntime` and `toFetchRequest`.
+
+## Type helpers
+
+Exported from `@lovrozagar/honey`, each over the app you built (`typeof app`). This is how a test, a client or a
+helper of yours stays tied to the routes rather than to a copy of their shapes.
+
+```ts
+import { honey, type InferRouteInput, type InferRoutePaths, type InferRoutes } from "@lovrozagar/honey"
+import * as z from "zod"
 
-Configure the trusted publisher once on this package (Settings → Trusted Publisher → GitHub Actions): repository `lovrozagar/honey`, workflow `release.yml`, no environment, allow npm publish. Do not put an npm token in GitHub secrets.
+const app = honey()
+	.get("/books/:id")
+	.input({ params: z.object({ id: z.string() }) })
+	.handler((ctx) => ctx.res.json("ok", { id: ctx.input.params.id }))
+
+type Paths = InferRoutePaths<typeof app>
+type Routes = InferRoutes<typeof app>
+type BookInput = InferRouteInput<typeof app, "/books/:id", "get">
+
+const path: Paths = "/books/:id"
+declare const input: BookInput
+const id: string = input.params.id
+```
+
+| Type                                         | What it describes                                                |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| `InferRoutes<typeof app>`                    | every path, its methods, and each one's input, output and errors |
+| `InferRoutePaths<typeof app>`                | the paths, as a union                                            |
+| `InferRouteMethods<typeof app, Path>`        | one path's methods                                               |
+| `InferRouteInput<typeof app, Path, Method>`  | a route's validated input                                        |
+| `InferRouteOutput<typeof app, Path, Method>` | a route's output map                                             |
+| `InferRouteErrors<typeof app, Path, Method>` | a route's declared error keys                                    |
+| `InferRouteMeta<typeof app, Path, Method>`   | a route's meta                                                   |
+| `InferRouteCtx<typeof app, Path, Method>`    | a route's handler `ctx`                                          |
+| `InferCtx<typeof app>`                       | the app's handler context                                        |
+| `InferEnv<typeof app>`                       | `ctx.env`                                                        |
+| `InferMeta<typeof app>`                      | the app-level meta                                               |
+| `InferErrorFactory<typeof app>`              | the error factory                                                |
+| `InferBasePath<typeof app>`                  | the base path, as a string                                       |
+| `InferMethods<typeof app>`                   | the methods the app serves                                       |
+
+## Documentation
+
+Every page's examples are compiled by the repository's tests.
+
+- [All the docs](https://github.com/lovrozagar/honey/blob/main/docs/README.md)
+- [Migrating from 0.7](https://github.com/lovrozagar/honey/blob/main/docs/migration.md)
+- [Package exports](https://github.com/lovrozagar/honey/blob/main/docs/packages.md)
+- [What a tarball ships, and why](https://github.com/lovrozagar/honey/blob/main/packages/core/docs/packaging.md)
+- [The repository](https://github.com/lovrozagar/honey)
 
 ## License