@raiyyan/brisk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # brisk
 
-A small, typed, opinionated layer over Express 5 and Zod. You keep the Express you know: plain functions, plain classes, any Express middleware. brisk removes the wiring you write by hand in every Express app: request validation, response DTOs, typed request data, error responses, environment validation, dependency injection, lifecycle and graceful shutdown, and scaffolding.
+A small, typed, opinionated layer over Express 5 and Zod. You keep the Express you know: plain functions, plain classes, any Express middleware. brisk removes the wiring you write by hand in every Express app: request validation, response DTOs, typed request data, error responses, environment validation, dependency injection, lifecycle and graceful shutdown, a typed client and an OpenAPI document. Choices such as the database, the auth scheme and the tooling stay yours: they live in starters and in your project's own templates.
 
 ```ts
 import { defineApp, defineController, inject, NotFoundError, z } from "@raiyyan/brisk";
@@ -28,6 +28,7 @@ await app.listen(3000);
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Quick start](#quick-start)
+- [Starters](#starters)
 - [Project structure](#project-structure)
 - [Configuration](#configuration)
 - [Controllers and routes](#controllers-and-routes)
@@ -45,6 +46,7 @@ await app.listen(3000);
 - [OpenAPI](#openapi)
 - [Testing](#testing)
 - [CLI](#cli)
+- [Templates](#templates)
 - [Working with the ecosystem](#working-with-the-ecosystem)
 - [Production checklist](#production-checklist)
 - [Performance](#performance)
@@ -67,6 +69,7 @@ brisk sits in between:
 - **Typed client and OpenAPI from the same routes.** Named routes become `api.users.get(...)` in tests and frontends, and an OpenAPI 3.1 document.
 - **Production lifecycle.** Init, ready, drain and shutdown hooks on provider classes, graceful shutdown, crash handling.
 - **No build step in development.** Node runs your TypeScript directly.
+- **Mechanisms, not choices.** brisk provides routing, validation, dependency injection, lifecycle, errors, the typed client, OpenAPI, the test client, and a CLI that renders templates. The database, the auth scheme, lint and format tools, Docker, CI, folder conventions and pagination shape come from a [starter](#starters) and live in your project, where you can change them.
 
 Six ideas, nothing else:
 
@@ -82,7 +85,7 @@ Six ideas, nothing else:
 ## Requirements
 
 - Node.js 24 or later.
-- npm or pnpm (any package manager works).
+- npm, pnpm or yarn.
 - TypeScript 5.8 or later (including 7) with `erasableSyntaxOnly`, so Node can run your `.ts` files directly.
 - ES modules (`"type": "module"`).
 
@@ -90,16 +93,16 @@ Six ideas, nothing else:
 
 ```bash
 npm install @raiyyan/brisk
-npm install --save-dev typescript @types/node vitest
 ```
 
 ```bash
 pnpm add @raiyyan/brisk
-pnpm add --save-dev typescript @types/node vitest
 ```
 
 Zod, Express and pino come with brisk. Import Zod from brisk (`import { z } from "@raiyyan/brisk"`) so your schemas and brisk use the same Zod. If your own code imports Express (`express.static`, `express.raw`, the `Request` and `Response` types), add it yourself: `pnpm add express` and `pnpm add -D @types/express` (pnpm does not let you import a dependency's dependencies). For colored development logs also install the optional `pino-pretty`.
 
+Without a starter, also add `typescript`, `@types/node` and a test runner such as `vitest` as dev dependencies. `brisk init` adds what its starter needs.
+
 ## Quick start
 
 In an empty folder, with npm:
@@ -107,12 +110,11 @@ In an empty folder, with npm:
 ```bash
 npm init -y
 npm install @raiyyan/brisk
-npm install --save-dev typescript @types/node vitest
 npx brisk init
 cp .env.example .env
 npx brisk g feature products
-npx tsc --noEmit
-npx vitest run
+npm run typecheck
+npm test
 npm run dev
 ```
 
@@ -121,7 +123,6 @@ With pnpm:
 ```bash
 pnpm init
 pnpm add @raiyyan/brisk
-pnpm add --save-dev typescript @types/node vitest
 pnpm exec brisk init
 cp .env.example .env
 pnpm brisk g feature products
@@ -138,33 +139,52 @@ curl localhost:3000/api/products
 curl -X POST localhost:3000/api/products -H 'content-type: application/json' -d '{"name":""}'   # 400 with field issues
 ```
 
-`brisk init` asks about a database, auth, Docker, CI and web extras (or takes [flags](#brisk-init)), then installs the packages it needs. It never overwrites existing files, so it is safe in an existing project: it only adds missing files, `"type": "module"` and missing scripts.
+`brisk init` copies the `minimal` [starter](#starters) into the folder, adds its scripts and dependencies to `package.json`, installs them and writes the guide for AI coding agents. It never overwrites a file, so it is safe in an existing project. `brisk g feature products` renders the project's own `templates/feature/` (see [Templates](#templates)).
 
 ### Adding brisk to an existing Express project
 
-Move your existing Express setup into `configureExpress`. Routers, middlewares and routes keep working unchanged, and new features are written as brisk controllers next to them:
+Mount your existing Express router, and put its app-wide middlewares in `use`. Routers, middlewares and routes keep working unchanged, and new features are written as brisk controllers next to them:
 
 ```ts
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => {
-    expressApp.use(express.json()); // your legacy routes read req.body before brisk parses JSON
-    expressApp.use(legacyRouter); // your existing express.Router()
-  },
+  use: [fromExpress(cors({ origin: env.WEB_ORIGIN }))],
+  mount: { "/": [express.json(), legacyRouter] }, // brisk does not parse mount bodies; your routes read req.body
 });
 ```
 
+brisk's routes answer first, and the legacy router gets every request they did not match.
+
 Then migrate route by route: write the new route in a controller, delete the old one.
 
+## Starters
+
+A starter is a complete, tested app that makes the choices brisk leaves to you: storage, auth, tooling, Docker. `brisk init --starter <name>` copies one into your project; from then on the code is yours. `brisk init --starter list` lists them.
+
+| Starter       | What it brings                                                                                                                                                                                                                                                                                    |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal`     | The app, env and test setup, and a feature template that stores records in memory. No database                                                                                                                                                                                                    |
+| `sqlite-auth` | Node's built-in `node:sqlite` with migrations applied at startup, accounts with scrypt password hashes and HS256 bearer tokens, an admin created from `ADMIN_EMAIL` / `ADMIN_PASSWORD`, CORS, rate limiting, static files, and a Dockerfile and `compose.yaml` that keep the database in a volume |
+
+Both starters:
+
+- ship oxlint and oxfmt, with `lint`, `format` and `format:check` scripts, and `dev`, `start`, `typecheck`, `test` and `brisk` scripts;
+- require Node 24 or later (`engines`);
+- include a `notes` feature generated from their own `templates/feature/`, as a working example; delete it when you no longer need it (its folder, its test files and its line in `src/features/index.ts`; in `sqlite-auth` also its migration, before anything ships);
+- keep shared schema helpers in `src/schemas.ts`: `isoDate()` (a timestamp sent as an ISO string), `PageQuery` and `page(item)` (paged lists). These are starter code, not brisk exports: change the page shape there.
+
+The sources are in [starters/](https://github.com/MohammadRaiyyan/brisk/tree/main/starters).
+
 ## Project structure
 
-`brisk init` and `brisk g feature` create this layout:
+The `minimal` starter, after `brisk g feature products`:
 
 ```
 src/
   env.ts                        defineEnv: typed configuration
   app.ts                        export const app = defineApp({ prefix: "/api", ... }); export type Api = typeof app
   main.ts                       await app.listen(env.PORT)
+  schemas.ts                    isoDate(), PageQuery, page(item): shared schema helpers
   middlewares/<name>.ts         defineMiddleware (brisk g middleware)
   features/
     index.ts                    export const controllers = { products: productsController }  (keep the @brisk markers)
@@ -173,17 +193,19 @@ src/
       products.repository.ts    data access only
       products.service.ts       business rules; throws error classes
       products.controller.ts    defineController: HTTP only, delegates to the service
+templates/
+  feature/                      what `brisk g feature <name>` renders
+  middleware/                   what `brisk g middleware <name>` renders
 test/
   products.test.ts              HTTP tests with createTestClient
+  products.service.test.ts      service tests without HTTP
 .env.example
-.gitignore
+.oxlintrc.json, .oxfmtrc.json   lint and format settings (they ignore templates/)
 tsconfig.json                   lets Node run .ts directly
 vitest.config.ts                test environment variables
 AGENTS.md, CLAUDE.md            guide for AI coding agents (brisk agents)
 ```
 
-The options of `brisk init` add more (a database provider, auth, Docker, CI); see [CLI](#cli).
-
 `src/app.ts` declares the app and `src/main.ts` starts it. Declaring runs nothing, so tests, `brisk client` and `brisk openapi` import the same `app` without opening a port or a database:
 
 ```ts
@@ -196,6 +218,7 @@ export const app = defineApp({
   prefix: "/api",
   controllers,
   logger: createLogger({ level: env.NODE_ENV === "test" ? "silent" : env.LOG_LEVEL }),
+  openapi: { title: "API", version: "0.1.0" },
   errors: { exposeInternal: env.NODE_ENV === "development" },
 });
 
@@ -238,11 +261,11 @@ export interface Product {
 export class ProductsRepository {
   readonly #rows = new Map<string, Product>();
 
-  findById(id: string): Product | undefined {
+  async findById(id: string): Promise<Product | undefined> {
     return this.#rows.get(id);
   }
 
-  save(row: Product): Product {
+  async insert(row: Product): Promise<Product> {
     this.#rows.set(row.id, row);
     return row;
   }
@@ -259,14 +282,14 @@ import type { CreateProductBody } from "./products.schema.ts";
 export class ProductsService {
   readonly #repository = inject(ProductsRepository);
 
-  get(id: string): Product {
-    const row = this.#repository.findById(id);
+  async get(id: string): Promise<Product> {
+    const row = await this.#repository.findById(id);
     if (!row) throw new NotFoundError("Product not found");
     return row;
   }
 
-  create(input: CreateProductBody): Product {
-    return this.#repository.save({ id: randomUUID(), ...input });
+  create(input: CreateProductBody): Promise<Product> {
+    return this.#repository.insert({ id: randomUUID(), ...input });
   }
 }
 ```
@@ -344,10 +367,13 @@ export const ordersController = defineController({ prefix: "/orders", use: [auth
 
 `defineController(options, setup)`:
 
-| Option   | Type           | Description                                                                |
-| -------- | -------------- | -------------------------------------------------------------------------- |
-| `prefix` | `string`       | Mount path, joined to the app's `prefix`                                   |
-| `use`    | `Middleware[]` | Middlewares for every route; their outputs are typed on each handler's ctx |
+| Option      | Type                    | Description                                                                                          |
+| ----------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `prefix`    | `string`                | Mount path, joined to the app's `prefix`                                                             |
+| `use`       | `Middleware[]`          | Middlewares for every route; their outputs are typed on each handler's ctx                           |
+| `providers` | `(Provider \| Class)[]` | Providers the feature brings, such as its WebSocket gateway: created at startup with the app (below) |
+
+A controller's `providers` are created at startup like the app's own, so removing the controller removes them. They come before the app's providers, so a value the app or a test provides for the same token wins.
 
 `setup` runs once per app instance, when the instance is built (`listen`, `start`, `create` or `createTestClient`), and can call `inject()`. It returns the controller's routes as an object of names. The names are how the [typed client](#typed-client) calls the routes (`api.orders.create(...)`, `api.orders.admin.remove(...)`) and become OpenAPI operation ids (`orders.create`).
 
@@ -374,7 +400,7 @@ Without a `params` schema, path params are typed from the full path, controller
 | `"/files/*path"`                        | `{ path: string[] }`            |
 | `"/posts{/:slug}"`                      | `{ slug?: string }`             |
 
-Express matches routes in the order they are declared, across all controllers in the order they are listed. Declare wildcard and optional-segment routes after the more specific routes they would otherwise catch.
+Express matches routes in the order they are declared, across all controllers in the order they are listed. Declare wildcard and optional-segment routes after the more specific routes they would otherwise catch. Two routes with the same method and path (paths that differ only in parameter names, such as `/:id` and `/:userId`, count as the same) are an error naming both, thrown when an instance is built.
 
 ### What a handler returns
 
@@ -445,23 +471,31 @@ export const ListOrdersQuery = z.object({
 ## Middleware
 
 ```ts
-import { defineMiddleware, ForbiddenError, UnauthorizedError } from "@raiyyan/brisk";
-
-export const authenticate = defineMiddleware(async ({ req }) => {
-  const user = await verifyToken(req.get("authorization"));
+import {
+  defineMiddleware,
+  ForbiddenError,
+  inject,
+  UnauthorizedError,
+  type SecuritySchemes,
+} from "@raiyyan/brisk";
+
+const bearer = { bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" } } satisfies SecuritySchemes;
+
+export const authenticate = defineMiddleware({ security: bearer }, async ({ req, log }) => {
+  const user = await inject(Sessions).verify(req.get("authorization"));
   if (!user) throw new UnauthorizedError("Invalid token", { challenge: "Bearer" });
-  return { user };
-}, "authenticate");
+  return { user, log: log.child({ userId: user.id }) };
+});
 
 export const requireRole = (role: "admin" | "member") =>
-  defineMiddleware(async (ctx) => {
+  defineMiddleware({ security: bearer }, async (ctx) => {
     const { user } = await authenticate.run(ctx);
     if (user.role !== role) throw new ForbiddenError(`Requires role: ${role}`);
     return { user };
   });
 ```
 
-`defineMiddleware(fn, name?)`:
+`defineMiddleware(fn)` or `defineMiddleware(options, fn)`:
 
 - **Return an object** to add typed fields to the handler's ctx (`return { user }` gives `ctx.user`).
 - **Return nothing** for a pure check.
@@ -469,9 +503,53 @@ export const requireRole = (role: "admin" | "member") =>
 - **Each middleware runs at most once per request.** `other.run(ctx)` reuses another middleware's result, so `requireRole` above does not authenticate twice. A handler can call `run(ctx)` too.
 - **Reserved names:** a middleware may not return `req`, `res`, `requestId`, `params`, `query`, `body` or `headers`; the compiler rejects them, because validated input would silently replace them. Returning `log` (such as `log.child({ userId })`) replaces the request logger for the rest of the request.
 - **Sync or async**, and `inject()` works inside.
-- Order: controller `use`, then group `use`, then route `use`, then validation. Unauthenticated requests are rejected before their input is validated. The JSON body is parsed earlier, for every request (up to `http.bodyLimit`), so malformed JSON gets 400 even without credentials.
+- Order: controller `use`, then group `use`, then route `use`, then the route's validation. Unauthenticated requests are rejected before their input is validated. The JSON body is parsed earlier, for every request (up to `http.bodyLimit`), so malformed JSON gets 400 even without credentials.
+
+| Option     | Type              | Description                                                                                            |
+| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `params`   | Zod schema        | Path params the middleware reads: validated before it runs (400 `VALIDATION_FAILED`), typed on its ctx |
+| `query`    | Zod schema        | Query fields the middleware reads, validated and typed the same way                                    |
+| `security` | `SecuritySchemes` | The OpenAPI security schemes it enforces, such as `{ bearer: { type: "http", scheme: "bearer" } }`     |
+
+### Middleware that needs input
 
-Plain Express middleware (`cors()`, `helmet()`, rate limiters, multer) goes in [`configureExpress`](#working-with-the-ecosystem).
+A permission check often depends on the request, such as the project a route belongs to. Declare what the middleware reads, and it gets validated, typed input before it runs; async refinements work:
+
+```ts
+export const requireProjectRole = (role: ProjectRole) =>
+  defineMiddleware({ params: z.object({ projectId: z.uuid() }), security: bearer }, async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    const projectRole = await inject(ProjectAccess).require(user.id, ctx.params.projectId, role);
+    return { projectRole };
+  });
+```
+
+`ProjectAccess` is a plain service, so the WebSocket gateway and GraphQL resolvers use the same rules ([shared access rules](#shared-access-rules)).
+
+### Security schemes
+
+Every route behind a middleware with `security` lists those schemes under `security` in the [OpenAPI](#openapi) document, and the document lists them under `components.securitySchemes`. Routes without such a middleware stay public. `middleware.security` reads the schemes back.
+
+### Express middleware on one route
+
+App-wide Express middleware (`cors()`, `helmet()`, rate limiters) goes in the app's [`use`](#use-mount-and-a-routes-use). For Express middleware that only some routes need, such as multer, wrap it with `fromExpress` and put it in `use`; it runs in order with the others, so it runs after authentication:
+
+```ts
+import { fromExpress } from "@raiyyan/brisk";
+import multer from "multer";
+
+const upload = fromExpress(multer({ dest: "uploads/", limits: { fileSize: 5_000_000 } }).single("file"));
+
+return {
+  attach: route.post("/:taskId/attachments", { use: [authenticate, upload] }, ({ req, params }) =>
+    attachments.save(params.taskId, req.file),
+  ),
+};
+```
+
+- An error the Express middleware passes to `next` goes to the app's error handler: an `http-errors` `status` and `expose` are honored, and `errors.mappers` apply.
+- If the Express middleware ends the response itself, the route stops there.
+- The route path is declared once, in the controller.
 
 ## Dependency injection
 
@@ -495,10 +573,10 @@ export const app = defineApp({ controllers, providers: [provide(Clock, () => new
 
 - **A class is its own token.** It needs a no-argument constructor, takes its dependencies with `inject()` in field initializers, and is created once per app, on first use.
 - **`defineToken<T>(name, factory?)`** names anything that is not a class: config, clients, functions, interface implementations. Without a factory it must be given a value with `provide`.
-- **`provide(token, value)`** fixes a value for a token in `defineApp({ providers })`, in the `providers` of `listen`, `start`, `create` or `createTestClient` (which replace the app's own, for fakes in tests), or in `new Container([...])`. Later entries win.
+- **`provide(token, value)`** fixes a value for a token in `defineApp({ providers })`, in `defineController({ providers })`, in the `providers` of `listen`, `start`, `create` or `createTestClient`, or in `new Container([...])`. Later entries win. The order is: controllers' providers, then the app's, then those given to `listen`, `start`, `create` or `createTestClient`. Those last ones are added to the app's own, not swapped in for them: a value for the same token wins, and every listed class is still created.
 - **Classes listed in `providers`** are created at boot even when nothing injects them, so WebSocket gateways, consumers and jobs get their lifecycle hooks. Listing a class is not required to make it injectable (every class is); it means "start this at boot".
 - **`injectLazy(token)`** returns `() => T` and creates the dependency on first call: for heavy clients, or to break a circular dependency.
-- **Where `inject()` works:** wherever the app runs your code: class fields, token factories, controller setup, every request (brisk routes, middlewares, and everything in `configureExpress`, so GraphQL resolvers and tRPC procedures too), lifecycle hooks, and timers and promises started from any of those.
+- **Where `inject()` works:** wherever the app runs your code: class fields, token factories, controller setup, every request (brisk routes, middlewares, the app's `use` and every `mount`, so GraphQL resolvers and tRPC procedures too), lifecycle hooks, and timers and promises started from any of those.
 - **Where it does not:** callbacks a library fires from its own events, outside any request (a gRPC handler, a queue client's message callback, a `ws` message listener). Resolve the dependency in a class field and use the field there. Outside the app entirely (a script, a REPL), use the instance's container: `instance.container.get(...)`. brisk never guesses which app you mean, so code behaves the same with one app in the process or several.
 - **`HttpServer`** exists only once the instance listens: inject it in `onReady`. Injecting it in a class field or `onInit` throws.
 - **Circular dependencies** are reported as `A -> B -> A`. Break them with `injectLazy`.
@@ -540,13 +618,15 @@ export class Database implements OnInit, OnShutdown {
 }
 ```
 
-Startup and shutdown work always lives in a provider class. `defineApp({ hooks })` takes only per-request hooks: `onRequest(ctx)`, `onResponse(ctx, { status, durationMs, aborted })` and `onError(error, ctx)`. `onResponse` runs once for every request, including ones the client abandoned (`aborted: true`). `onError` sees client errors too; an error tracker usually wants `if (error instanceof HttpError && error.status < 500) return;`.
+Startup and shutdown work always lives in a provider class. `defineApp({ hooks })` takes only per-request hooks: `onResponse(ctx, { status, durationMs, aborted })` and `onError(error, ctx)`. Logic that can reject a request is a middleware in the app's `use`. `onResponse` runs once for every request, including ones the client abandoned (`aborted: true`). `onError` sees client errors too; an error tracker usually wants `if (error instanceof HttpError && error.status < 500) return;`.
 
 ```
 boot      providers' onInit (dependencies first) -> listen -> providers' onReady
-request   configureExpress -> JSON body -> hooks.onRequest -> middlewares -> validation -> handler
-          -> response -> hooks.onResponse            (any error -> hooks.onError -> error response)
-shutdown  SIGINT/SIGTERM -> stop accepting connections -> providers' onDrain (reverse)
+request   security headers -> request id -> /health and /openapi.json -> app use
+          -> brisk route: JSON body -> middlewares -> validation -> handler -> response
+          -> 405 / OPTIONS -> mount -> 404
+          (any error -> error response -> hooks.onError; hooks.onResponse when the response closes)
+shutdown  SIGINT/SIGTERM -> /health answers 503 -> stop accepting connections -> providers' onDrain (reverse)
           -> in-flight requests finish, with Connection: close (sockets still open after shutdownTimeoutMs are destroyed)
           -> providers' onShutdown (reverse) -> exit 0
           (a different second signal is ignored; the same signal again exits 1 at once;
@@ -556,7 +636,9 @@ crash     unhandled rejection or uncaught exception -> logged as fatal -> shutdo
 
 A failing `onDrain` or `onShutdown` is logged and shutdown continues. `app.start()` runs the same lifecycle without an HTTP server.
 
-Each `listen`, `start` or `create` builds a new, independent instance with its own container, so one app can run in many tests at once. If startup fails (an `onInit` throws, the port is taken), brisk runs the drain and shutdown hooks for what already started, then rethrows, so pools and clients are released.
+Each `listen`, `start` or `create` builds a new, independent instance with its own container, so one app can run in many tests at once.
+
+If startup fails (an `onInit` or `onReady` throws, the port is taken), brisk logs it at `fatal` as `startup failed`, with `provider` and `hook` fields naming the class and hook that threw. It then runs the drain and shutdown hooks for what already started, so pools and clients are released, and rethrows the error.
 
 ## Errors
 
@@ -666,9 +748,11 @@ export const app = defineApp({
 
 `defaultErrorFormatter` is exported for formatters that only add fields. A mapper or `onError` hook that throws is logged and never breaks the response.
 
-ORMs often wrap the driver's error (Drizzle keeps it in `cause`), so a mapper should walk the `cause` chain. `brisk init --db sqlite` or `--db postgres` generates one in `src/database/errors.ts` that turns a unique violation into 409 `ALREADY_EXISTS`:
+ORMs often wrap the driver's error (Drizzle keeps it in `cause`), so a mapper should walk the `cause` chain. This one turns a Postgres unique violation into 409 `ALREADY_EXISTS`; the `sqlite-auth` starter has the SQLite version in `src/database/errors.ts`:
 
 ```ts
+import { ConflictError, type ErrorMapper } from "@raiyyan/brisk";
+
 export const uniqueViolation: ErrorMapper = (error) => {
   for (let current: unknown = error; current instanceof Error; current = current.cause) {
     if ("code" in current && current.code === "23505") {
@@ -679,6 +763,20 @@ export const uniqueViolation: ErrorMapper = (error) => {
 };
 ```
 
+### Errors outside brisk's routes
+
+Code that answers outside a brisk route, such as a GraphQL error mask or a WebSocket close, can translate an error the way a route would with the `ErrorTranslator` token. It returns `{ status, code, message, details }` with `errors.mappers` applied, and hides the message of unexpected errors unless `errors.exposeInternal` is on:
+
+```ts
+import { ErrorTranslator, inject, NotFoundError } from "@raiyyan/brisk";
+
+const translate = inject(ErrorTranslator); // inside the app: a request, a class field, a lifecycle hook
+translate(new NotFoundError("Project not found")); // { status: 404, code: "NOT_FOUND", message: "Project not found", details: undefined }
+translate(new Error("password=hunter2")); // { status: 500, code: "INTERNAL_SERVER_ERROR", message: "Internal server error", ... }
+```
+
+Inside a request (a mount, a GraphQL resolver or `maskError`) call `inject(ErrorTranslator)` directly. In callbacks a library fires on its own, such as a `ws` message listener, resolve it in a class field. Outside the app, use `instance.container.get(ErrorTranslator)`.
+
 ## The request context
 
 Every handler and middleware receives a context:
@@ -692,7 +790,7 @@ Every handler and middleware receives a context:
 
 Handlers also get every middleware's output and the validated `params`, `query`, `body` and `headers`. Destructure what you need (`({ params, user, log }) => ...`) rather than copying the whole context.
 
-Code that only has the Express `req` (plain middlewares and routes in `configureExpress`) uses `getContext(req)`:
+Code that only has the Express `req` (Express middlewares and mounts) uses `getContext(req)`:
 
 ```ts
 import { getContext } from "@raiyyan/brisk";
@@ -734,27 +832,28 @@ export const app = defineApp({
 
 - **Request ids** from callers are accepted only when short and plain (letters, digits, `_ . : -`, up to 128 characters), so they cannot forge log lines.
 - **Body limit** of `1mb` for JSON (`http.bodyLimit`).
-- **Flat query strings:** query values are strings or arrays of strings, never nested objects. If you need nested query objects, enable them with `configureExpress: (expressApp) => expressApp.set("query parser", "extended")`.
+- **Flat query strings:** query values are strings or arrays of strings, never nested objects. If you need nested query objects, enable them with `http: { settings: { "query parser": "extended" } }`.
 - **No mass assignment:** unknown body fields are stripped by your schemas.
-- **`trust proxy`** stays off unless you set `http.trustProxy`. Set it only behind a proxy you control, otherwise clients can spoof `req.ip`.
+- **`trust proxy`** stays off unless you set it in `http.settings` (`{ "trust proxy": 1 }`). Set it only behind a proxy you control, otherwise clients can spoof `req.ip`.
 - **Internal error messages** never reach clients unless `errors.exposeInternal` is on (development only).
-- CORS and rate limiting are plain Express middlewares in `configureExpress`.
+- CORS and rate limiting are plain Express middlewares in the app's `use`.
 
 ## defineApp options
 
 `defineApp(options)` declares the app. Every option is optional.
 
-| Option             | Type                     | Default          | Description                                                                     |
-| ------------------ | ------------------------ | ---------------- | ------------------------------------------------------------------------------- |
-| `prefix`           | `string`                 | `"/"`            | Path every controller is mounted under, such as `/api`                          |
-| `controllers`      | `{ [name]: Controller }` | `{}`             | Controllers by name; the names are the typed client's top level                 |
-| `providers`        | `(Provider \| Class)[]`  | `[]`             | `provide(token, value)` entries, and classes to create at startup               |
-| `logger`           | `Logger`                 | `createLogger()` | The app logger; injectable as `Logger`                                          |
-| `configureExpress` | `(expressApp) => void`   | none             | Full Express access, before JSON parsing and before brisk's routes              |
-| `hooks`            | `AppHooks`               | `{}`             | `onRequest`, `onResponse`, `onError` (startup and shutdown belong in providers) |
-| `openapi`          | `OpenApiOptions`         | not served       | Serve an [OpenAPI](#openapi) document                                           |
-| `errors`           | `ErrorOptions`           | `{}`             | How errors become responses (below)                                             |
-| `http`             | `HttpOptions`            | `{}`             | HTTP-level settings (below)                                                     |
+| Option        | Type                                             | Default          | Description                                                                                                                                        |
+| ------------- | ------------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`      | `string`                                         | `"/"`            | Path every controller is mounted under, such as `/api`                                                                                             |
+| `controllers` | `{ [name]: Controller }`                         | `{}`             | Controllers by name; the names are the typed client's top level                                                                                    |
+| `providers`   | `(Provider \| Class)[]`                          | `[]`             | `provide(token, value)` entries, and classes to create at startup                                                                                  |
+| `logger`      | `Logger`                                         | `createLogger()` | The app logger; injectable as `Logger`                                                                                                             |
+| `use`         | `Middleware[]`                                   | `[]`             | Middlewares for every request after `/health` and `/openapi.json`, before brisk's routes and mounts ([use and mount](#use-mount-and-a-routes-use)) |
+| `mount`       | `{ [path]: RequestHandler \| RequestHandler[] }` | `{}`             | Express handlers that answer what brisk's routes did not: static files, GraphQL, webhooks                                                          |
+| `hooks`       | `AppHooks`                                       | `{}`             | `onResponse`, `onError` (startup and shutdown belong in providers)                                                                                 |
+| `openapi`     | `OpenApiOptions`                                 | not served       | Serve an [OpenAPI](#openapi) document                                                                                                              |
+| `errors`      | `ErrorOptions`                                   | `{}`             | How errors become responses (below)                                                                                                                |
+| `http`        | `HttpOptions`                                    | `{}`             | HTTP-level settings (below)                                                                                                                        |
 
 `errors`:
 
@@ -766,13 +865,13 @@ export const app = defineApp({
 
 `http`:
 
-| Option              | Type                                         | Default     | Description                                                                          |
-| ------------------- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
-| `bodyLimit`         | `string`                                     | `"1mb"`     | JSON body size limit                                                                 |
-| `trustProxy`        | `boolean \| number \| string`                | not set     | Express `trust proxy` setting; only behind a proxy you control                       |
-| `securityHeaders`   | `boolean \| Record<string, string \| false>` | `true`      | Strict API headers; an object overrides individual headers, `false` removes one      |
-| `healthPath`        | `string \| false`                            | `"/health"` | Health route answering `{ "status": "ok" }`, outside the prefix; `false` disables it |
-| `shutdownTimeoutMs` | `number`                                     | `10000`     | How long shutdown waits for in-flight requests before closing remaining connections  |
+| Option              | Type                                         | Default     | Description                                                                                                                                                   |
+| ------------------- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bodyLimit`         | `string`                                     | `"1mb"`     | JSON body size limit                                                                                                                                          |
+| `settings`          | `Record<string, unknown>`                    | `{}`        | Express app settings, applied with `app.set(name, value)` after brisk's defaults: `{ "trust proxy": 1 }`, `{ etag: false }`, `{ "query parser": "extended" }` |
+| `securityHeaders`   | `boolean \| Record<string, string \| false>` | `true`      | Strict API headers; an object overrides individual headers, `false` removes one                                                                               |
+| `healthPath`        | `string \| false`                            | `"/health"` | Health route, outside the prefix: `{ "status": "ok" }`, or 503 `{ "status": "shutting down" }` once shutdown begins; `false` disables it                      |
+| `shutdownTimeoutMs` | `number`                                     | `10000`     | How long shutdown waits for in-flight requests before closing remaining connections                                                                           |
 
 ## App reference
 
@@ -790,7 +889,7 @@ Each call builds a new, independent instance with its own container. Configurati
 
 | Option          | On                          | Default           | Description                                                                              |
 | --------------- | --------------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
-| `providers`     | `listen`, `start`, `create` | `[]`              | Replace the app's own providers, typically with fakes                                    |
+| `providers`     | `listen`, `start`, `create` | `[]`              | Added after the app's own providers: a value for the same token wins, typically a fake   |
 | `manageProcess` | `listen`, `start`           | `true`            | SIGINT/SIGTERM shut down gracefully and exit 0; crashes are logged, shut down and exit 1 |
 | `host`          | `listen`                    | all interfaces    | Interface to bind, such as `0.0.0.0` in a container or `127.0.0.1` for local only        |
 | `server`        | `listen`                    | a new HTTP server | Your own `http.Server` or `https.Server`; brisk serves its requests                      |
@@ -870,9 +969,11 @@ await api.users.remove({ params: { id } }, { signal: AbortSignal.timeout(5000) }
 ```
 
 - The input has `params`, `query`, `body` and `headers`, each typed by the route's schema as clients send it (the schema's input type). A field is absent when the route has nothing for it, and optional when everything in it is optional.
+- `params` and `query` fields also accept the schema's output type when a URL can carry it: a `z.stringbool()` field takes `true` as well as `"true"`, and a `z.coerce.number()` field takes `2`.
 - Every call accepts extra headers, such as `authorization` for a middleware that reads it.
 - The second argument is passed to `fetch`: `signal`, `credentials`, and so on.
 - Array query values become repeated keys (`?tag=a&tag=b`); a `*splat` param takes an array of segments.
+- A `FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer` (or typed array) or `ReadableStream` body is sent as it is, so `fetch` sets the content type and multipart boundary. Any other body, strings included, is sent as JSON.
 
 A call resolves to:
 
@@ -903,7 +1004,21 @@ try {
 }
 ```
 
-Types: `ApiOf<T>` (an app's routes), `Client<T>` (the client for them), `Jsonify<T>` (a type after JSON), `Manifest`.
+### Raw responses
+
+Every call also has `.raw(input, init?)`, which sends the same request and resolves to the `Response` whatever its status, without throwing. Use it for downloads, uploads and anything that is not JSON. The client's `headers` are still applied, and a string body is sent as it is. Its `body` accepts the route's body type or any `RawBody`:
+
+```ts
+const form = new FormData();
+form.append("file", file);
+const res = await api.tasks.attach.raw({ params: { taskId }, body: form });
+if (!res.ok) throw new Error(`Upload failed with ${res.status}`);
+
+const report = await api.reports.download.raw({ params: { id } });
+const blob = await report.blob();
+```
+
+Types from `@raiyyan/brisk/client`: `ApiOf<T>` (an app's routes), `Client<T>` (the client for them), `Call<I, O>` (one route as a function, with `.raw`), `RawBody` (a body `.raw` sends as it is), `Jsonify<T>` (a type after JSON), `Manifest`.
 
 ## OpenAPI
 
@@ -928,6 +1043,7 @@ export const app = defineApp({
 - The `operationId` is the route's name, `controller.route` (`users.get`, `orders.admin.remove`), and the controller's name is the tag. Routes of a controller whose setup returns nothing have no `operationId`.
 - `params`, `query` and `headers` schemas become parameters, and the `body` schema the request body, as clients send them. The `response` schema is documented under the route's success status as clients receive it. Every operation lists the error body as its `default` response.
 - Express paths are converted: `:id` and `*path` become `{id}` and `{path}`, and an optional group (`/posts{/:slug}`) gives two paths.
+- A route behind a middleware declared with `security` lists those schemes (several middlewares: all of them, together), and the document lists every scheme under `components.securitySchemes`. Routes without one stay public. See [security schemes](#security-schemes).
 - A schema JSON Schema cannot express, such as `z.date()` or a transform, is documented as "any". For dates sent as strings, end the schema in the string it produces:
 
   ```ts
@@ -937,7 +1053,7 @@ export const app = defineApp({
     .pipe(z.iso.datetime()), // documented as { type: "string", format: "date-time" }
   ```
 
-  The typed client then types the field as `string` too.
+  The typed client then types the field as `string` too. The starters' `isoDate()` in `src/schemas.ts` does this and also accepts an ISO string.
 
 ## Testing
 
@@ -969,67 +1085,134 @@ it("rejects an invalid product", async () => {
 - A raw `body` is sent as JSON, except a string or `Uint8Array`, which is sent as is (webhook payloads, forms). `content-type` defaults to `application/json` when there is a body; set it in `headers` to override.
 - Raw responses are `{ status, headers, body }`; `body` is parsed JSON, text, or `undefined`, typed `unknown`. Parse it with a Zod schema or assert with `toMatchObject`.
 - `readError(res)` returns the typed `error` object and fails the test if the body is not an error response.
-- Swap dependencies with `providers`: they replace the app's own. Unit-test services without HTTP with `new Container([...]).get(Service)`.
-- To test `304 Not Modified`, use `node:http` rather than `fetch`: `fetch` adds `Cache-Control: no-cache` to requests with `If-None-Match`, which correctly disables 304.
+- Swap dependencies with `providers`: they are added after the app's own, so a value for the same token wins, and the app's listed classes still start. Unit-test services without HTTP with `new Container([...]).get(Service)`.
+- To test `304 Not Modified`, use `node:http`, or send `cache-control: max-age=0` with the request. `fetch`, and so the test client's raw methods, adds `Cache-Control: no-cache` to a request that carries `If-None-Match` and no `Cache-Control`, which correctly disables 304.
 
 ## CLI
 
 The package installs a `brisk` command. Run it from the app's root.
 
-| Command                      | What it does                                                                                                                    |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `brisk init`                 | Scaffolds a runnable app in the current folder (see below), installs missing packages, then runs `brisk agents`                 |
-| `brisk g feature <name>`     | Writes `src/features/<name>/` (schema, repository, service, controller) and `test/<name>.test.ts`, and registers the controller |
-| `brisk g middleware <name>`  | Writes a typed middleware in `src/middlewares/<name>.ts`                                                                        |
-| `brisk client --out <file>`  | Writes the route manifest for a frontend's [typed client](#typed-client)                                                        |
-| `brisk openapi --out <file>` | Writes the [OpenAPI](#openapi) document as JSON                                                                                 |
-| `brisk agents`               | Adds or refreshes the brisk guide for AI coding agents in `AGENTS.md` and `CLAUDE.md`                                           |
-| `brisk help`, `--version`    | Lists commands; prints the installed version                                                                                    |
+| Command                      | What it does                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------- |
+| `brisk init`                 | Copies a [starter](#starters) into the current folder, installs its packages, runs `brisk agents` |
+| `brisk g <kind> <name>`      | Renders the project's `templates/<kind>/` for `<name>` (see [Templates](#templates))              |
+| `brisk client --out <file>`  | Writes the route manifest for a frontend's [typed client](#typed-client)                          |
+| `brisk openapi --out <file>` | Writes the [OpenAPI](#openapi) document as JSON                                                   |
+| `brisk agents`               | Adds or refreshes the brisk guide for AI coding agents in `AGENTS.md` and `CLAUDE.md`             |
+| `brisk help`, `--version`    | Lists commands; prints the installed version                                                      |
 
 ### brisk init
 
-`brisk init` creates `src/env.ts`, `src/app.ts` (`export const app = defineApp(...)` with prefix `/api`, and `export type Api`), `src/main.ts` (`await app.listen(env.PORT)`), `src/features/index.ts`, `.env.example` and a `tsconfig.json` that lets Node run `.ts` directly. It never overwrites existing files. It adds `"type": "module"` and any missing `dev`, `start`, `typecheck`, `test` and `brisk` scripts to `package.json`.
+```bash
+npx brisk init [--starter <name>] [--pm pnpm|npm|yarn] [--no-install]
+```
 
-It also writes `vitest.config.ts` (test environment variables) and `.gitignore`. Without flags it asks about each option; flags answer the questions up front:
+| Flag                     | Effect                                                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `--starter <name>`       | The starter to copy. Default: `minimal`. `--starter list` lists the starters                            |
+| `--pm <pnpm\|npm\|yarn>` | The package manager. Default: the one running the CLI, else the one whose lockfile is present, else npm |
+| `--no-install`           | Print the install command instead of running it                                                         |
 
-| Flag                     | Adds                                                                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--db sqlite`            | A `Database` provider on Node's built-in `node:sqlite` (no dependency), opened in `onInit` and closed in `onShutdown`                                   |
-| `--db postgres`          | A `Database` provider with `pg` and Drizzle, `src/database/schema.ts`, `drizzle.config.ts`, and `db:generate` / `db:migrate` scripts                    |
-| `--db` (either)          | `src/database/errors.ts`: an error mapper that turns a unique violation into 409 `ALREADY_EXISTS`, registered in `errors.mappers`                       |
-| `--auth`                 | HS256 bearer tokens signed with `node:crypto` (`src/auth/tokens.ts`), `authenticate` and `requireRole` middlewares, and their tests                     |
-| `--docker`               | A `Dockerfile` (runs as a non-root user, with a health check), `compose.yaml` (with the database for postgres, a volume for sqlite) and `.dockerignore` |
-| `--ci`                   | A GitHub Actions workflow running typecheck and tests                                                                                                   |
-| `--web`                  | CORS, `express-rate-limit`, `express.static` for `public/`, and `pino-pretty` for development logs                                                      |
-| `--pm <pnpm\|npm\|yarn>` | The package manager. Default: the one running the CLI, else the one whose lockfile is present, else npm                                                 |
-| `--yes`, `-y`            | Take the defaults (no database, no extras) for every option not given, and ask nothing                                                                  |
-| `--no-install`           | Print the install commands instead of running them                                                                                                      |
+What it does:
 
-```bash
-npx brisk init --db postgres --auth --docker --ci --yes
-```
+- Copies the starter's files. A file that already exists is kept, never overwritten, and listed as `kept`.
+- Skips `node_modules`, `dist`, `coverage`, `.env`, database and log files, and `AGENTS.md` / `CLAUDE.md` (written next by `brisk agents`).
+- Merges the starter's `package.json` into yours: `type`, `engines`, scripts and dependencies are added where yours has none; your own values win. `@raiyyan/brisk` is pinned to the version that is running. The `test` script `npm init` writes (which only fails) is replaced.
+- Writes the agent guide (`brisk agents`).
+- Installs the packages. If the install fails, the files stay in place and the CLI says what to run again; with pnpm it also points to `pnpm approve-builds`, for packages whose build scripts pnpm blocked.
 
-Packages are installed after the files are written. If an install fails, the files stay in place and the CLI prints the commands to run again; with pnpm it also points to `pnpm approve-builds`, for packages whose build scripts pnpm blocked.
+### brisk g
 
-### brisk g feature
+```bash
+npx brisk g feature products
+npx brisk g middleware tenant
+```
 
-- `brisk g feature products` writes `products.schema.ts`, `.repository.ts`, `.service.ts` and `.controller.ts` with singular entity names (`Product`, `CreateProductBody`, `ProductResponse`), a test, and registers `products: productsController` in `src/features/index.ts`. The key is the controller's name in the typed client.
-- Names may be `kebab-case`, `camelCase`, `PascalCase` or `snake_case`; files use kebab-case.
-- `g` is short for `generate`.
-- When `oxfmt` or `prettier` is installed in the project, generated files are formatted with it, so they match your style.
-- Keep the `// @brisk:imports` and `// @brisk:controllers` markers in `src/features/index.ts`; the CLI registers new controllers there.
+`brisk g <kind> <name>` renders the project's own `templates/<kind>/` folder; `g` is short for `generate`. The starters ship `feature` and `middleware`; any folder you add under `templates/` is a new kind. Names may be `kebab-case`, `camelCase`, `PascalCase` or `snake_case`.
 
 ### brisk client and brisk openapi
 
 Both import `src/app.ts` (or the module given with `--app <file>`), read its `app` export, and write `--out`. Nothing listens or starts. The module runs, so its environment must be valid, as for starting the app.
 
+## Templates
+
+Templates are files in your project, not in brisk: `brisk g <kind> <name>` copies `templates/<kind>/` into the project root, rendering each file's path and contents. Edit them when your conventions change, and every later feature follows.
+
+| Token             | `brisk g feature blog-posts` gives |
+| ----------------- | ---------------------------------- |
+| `{{kebab}}`       | `blog-posts`                       |
+| `{{camel}}`       | `blogPosts`                        |
+| `{{pascal}}`      | `BlogPosts`                        |
+| `{{snake}}`       | `blog_posts`                       |
+| `{{entity}}`      | `BlogPost` (singular)              |
+| `{{entityCamel}}` | `blogPost`                         |
+
+- **New files:** every file in the folder is written to the same relative path, with tokens replaced in both the path and the contents.
+- **Additions to existing files:** a file named `<target>.<marker>.insert` is not copied. Its text is inserted into the existing `<target>`, right before the line that contains `@brisk:<marker>`. This is how a feature registers its controller (`// @brisk:imports` and `// @brisk:controllers` in `src/features/index.ts`) and, in `sqlite-auth`, its table (`// @brisk:migrations` in `src/database/migrations.ts`). Keep the marker lines.
+- **All or nothing:** everything is checked before anything is written. An unknown token, a file that already exists, or a missing target or marker stops the command with nothing changed.
+- **Formatting:** when the project has `oxfmt`, `prettier` or `biome` installed, the written files are formatted with it, so they match your style.
+
+A worked example: a `job` kind that writes a scheduled job and lists it in `src/jobs/index.ts`.
+
+```
+templates/job/
+  src/jobs/{{kebab}}.job.ts
+  src/jobs/index.ts.imports.insert
+  src/jobs/index.ts.jobs.insert
+```
+
+```ts
+// templates/job/src/jobs/{{kebab}}.job.ts
+import type { OnDrain, OnReady } from "@raiyyan/brisk";
+
+export class {{pascal}}Job implements OnReady, OnDrain {
+  #timer: NodeJS.Timeout | undefined;
+
+  onReady() {
+    this.#timer = setInterval(() => {
+      // the job's work
+    }, 60_000);
+  }
+
+  onDrain() {
+    clearInterval(this.#timer);
+  }
+}
+```
+
+```ts
+// templates/job/src/jobs/index.ts.imports.insert
+import { {{pascal}}Job } from "./{{kebab}}.job.ts";
+```
+
+```ts
+// templates/job/src/jobs/index.ts.jobs.insert
+  {{pascal}}Job,
+```
+
+```ts
+// src/jobs/index.ts, written once by hand; list it in defineApp({ providers: [...jobs] })
+// @brisk:imports
+
+export const jobs = [
+  // @brisk:jobs
+];
+```
+
+`brisk g job nightly-digest` then writes `src/jobs/nightly-digest.job.ts` and adds `NightlyDigestJob` to the list.
+
+Template files are not valid TypeScript until rendered, so keep `templates/` out of lint, format, typecheck and test runs; the starters' configs already do.
+
 ## Working with the ecosystem
 
 ### Not in your way
 
 brisk owns only its own routes. Everything else is plain Express on a plain Node server, so any Express middleware or Node library works as it would without brisk:
 
-- `configureExpress(expressApp)`: full Express access, before JSON parsing and before brisk's routes.
+- `use` with `fromExpress(handler)`: any Express middleware for every request, before brisk's routes.
+- `mount`: Express handlers that are not brisk routes (static files, GraphQL, tRPC, webhooks, a legacy router).
+- `http.settings`: Express app settings (`trust proxy`, `etag`, `query parser`).
+- `fromExpress(handler)`: any Express middleware in one route's `use`, in order with brisk's middlewares.
 - `instance.express`: the Express app (adapters, serverless with `app.create()`).
 - `instance.server` and the `HttpServer` token: the Node server (WebSockets, timeouts).
 - `ListenOptions.server`: your own server (HTTPS, tuned timeouts).
@@ -1037,29 +1220,62 @@ brisk owns only its own routes. Everything else is plain Express on a plain Node
 - `app.start()`: the same app without HTTP.
 - `ctx.res`: write a raw response from any handler.
 
-Requests in `configureExpress` have a context (`getContext(req)`), and errors thrown there get the same error responses. Because it runs before JSON parsing, raw, form and multipart bodies are yours to parse; a form body parsed there reaches a brisk route's `body` schema.
+### use, mount and a route's use
+
+- **The app's `use`** runs for every request: brisk routes, mounts and 404s. `/health` and `/openapi.json` are answered before it, so a rate limiter or an auth check there never blocks a probe. `fromExpress(...)` entries run as plain Express middleware, so CORS preflights are answered before routing. A `defineMiddleware` entry runs once per request, stops the request by throwing, and adds its `security` to every OpenAPI operation.
+- **`mount`** holds Express handlers that are not brisk routes. They answer only what brisk's routes did not, so a mount never shadows a route and `mount: { "/": spaFallback }` works as a fallback. Paths are absolute (the `prefix` does not apply) and must start with `/`; Express strips the path from `req.url`. brisk does not parse their bodies: add `express.json()` or `express.raw()` to the mount that needs one. Mounts get the request context (`getContext(req)`), `inject()` and the same error responses, and the startup log lists them as `MOUNT /path`.
+- **A route's `use`** (controller, group or route) holds middlewares for those routes only. Their output is typed on the handler's `ctx`.
+
+Controllers are declared before the app, so the output of a `defineMiddleware` in the app's `use` is not typed on handler `ctx`. To type it, list the middleware in the controller's `use` as well (it still runs once per request), or read it with `await middleware.run(ctx)`.
 
-### Express middleware, static files, uploads, webhooks
+brisk parses JSON only on its own routes. A form body parsed in the app's `use` reaches a brisk route's `body` schema.
+
+### Express middleware, static files, webhooks
 
 ```ts
 import cors from "cors";
 import express from "express";
-import multer from "multer";
 
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => {
-    expressApp.use(cors({ origin: env.WEB_ORIGIN }));
-    expressApp.use("/static", express.static("public"));
-    expressApp.post("/webhooks/stripe", express.raw({ type: "application/json" }), stripeWebhook); // raw bytes for signatures
-    expressApp.post("/upload", multer({ dest: "uploads/" }).single("file"), (req, res) => {
-      res.json({ name: req.file?.originalname });
-    });
-    expressApp.use(express.urlencoded({ extended: false })); // form bodies reach brisk `body` schemas
+  use: [
+    fromExpress(cors({ origin: env.WEB_ORIGIN })),
+    fromExpress(express.urlencoded({ extended: false })), // form bodies reach brisk `body` schemas
+  ],
+  mount: {
+    "/static": express.static("public"),
+    "/webhooks/stripe": [express.raw({ type: "application/json" }), stripeWebhook], // raw bytes for signatures
   },
 });
 ```
 
+### Uploads
+
+Parse multipart bodies on the route that takes them, after authentication, with `fromExpress`:
+
+```ts
+import { BadRequestError, defineController, fromExpress, inject } from "@raiyyan/brisk";
+import multer from "multer";
+
+const upload = fromExpress(multer({ dest: "uploads/", limits: { fileSize: 5_000_000 } }).single("file"));
+
+export const attachmentsController = defineController(
+  { prefix: "/tasks/:taskId/attachments", use: [authenticate] },
+  (route) => {
+    const attachments = inject(AttachmentsService);
+
+    return {
+      create: route.post("/", { use: [upload] }, ({ req, params }) => {
+        if (!req.file) throw new BadRequestError("Send the file in the `file` field");
+        return attachments.save(params.taskId, req.file);
+      }),
+    };
+  },
+);
+```
+
+An unauthenticated upload is rejected before multer reads a byte. Errors multer passes on reach `errors.mappers`, so a mapper can turn its file-size error into `PayloadTooLargeError`. Clients send the file with [`.raw`](#raw-responses) and a `FormData` body. Files written to local disk exist only on the instance that received them; use object storage when you run more than one.
+
 ### Server-Sent Events
 
 ```ts
@@ -1117,26 +1333,139 @@ export class Realtime implements OnReady, OnDrain {
 export const app = defineApp({ controllers, providers: [Realtime] });
 ```
 
+### Shared access rules
+
+Put authorization rules in a service, and call it from every entry point: the HTTP middleware, the WebSocket gateway and the GraphQL resolvers. Each one then enforces the same rules instead of its own copy.
+
+```ts
+// src/features/projects/project-access.ts
+import { ForbiddenError, inject, NotFoundError } from "@raiyyan/brisk";
+
+export type ProjectRole = "viewer" | "editor" | "owner";
+const RANK: Record<ProjectRole, number> = { viewer: 0, editor: 1, owner: 2 };
+
+/** Who may do what in a project. */
+export class ProjectAccess {
+  readonly #members = inject(MembersRepository);
+
+  /** The user's role in the project, or `undefined` when they are not a member. */
+  async roleIn(userId: string, projectId: string): Promise<ProjectRole | undefined> {
+    return (await this.#members.find(projectId, userId))?.role;
+  }
+
+  /** The user's role, or an error: 404 for a non-member, so project ids do not leak; 403 for too low a role. */
+  async require(userId: string, projectId: string, role: ProjectRole): Promise<ProjectRole> {
+    const actual = await this.roleIn(userId, projectId);
+    if (!actual) throw new NotFoundError("Project not found");
+    if (RANK[actual] < RANK[role]) throw new ForbiddenError(`Requires the ${role} role`);
+    return actual;
+  }
+}
+```
+
+HTTP routes use it through a middleware that declares the param it reads ([middleware that needs input](#middleware-that-needs-input)):
+
+```ts
+export const tasksController = defineController({ prefix: "/projects/:projectId/tasks" }, (route) => {
+  const tasks = inject(TasksService);
+
+  return {
+    list: route.get("/", { use: [requireProjectRole("viewer")] }, ({ params }) =>
+      tasks.list(params.projectId),
+    ),
+    create: route.post(
+      "/",
+      { use: [requireProjectRole("editor")], body: CreateTaskBody },
+      ({ params, body }) => tasks.create(params.projectId, body),
+    ),
+  };
+});
+```
+
+A WebSocket gateway resolves it in a class field, because `ws` callbacks run outside the app:
+
+```ts
+import type { IncomingMessage } from "node:http";
+import { HttpServer, inject, type OnDrain, type OnReady } from "@raiyyan/brisk";
+import { WebSocketServer, type WebSocket } from "ws";
+
+export class ProjectsGateway implements OnReady, OnDrain {
+  readonly #access = inject(ProjectAccess);
+  readonly #sessions = inject(Sessions);
+  #wss: WebSocketServer | undefined;
+
+  onReady() {
+    this.#wss = new WebSocketServer({ server: inject(HttpServer), path: "/ws" });
+    this.#wss.on("connection", (socket, req) => void this.#admit(socket, req));
+  }
+
+  async #admit(socket: WebSocket, req: IncomingMessage) {
+    const user = await this.#sessions.verify(req.headers.authorization);
+    const projectId = new URL(req.url ?? "/", "http://localhost").searchParams.get("projectId");
+    if (!user || !projectId || !(await this.#access.roleIn(user.id, projectId))) {
+      socket.close(4403, "forbidden");
+      return;
+    }
+    // subscribe the socket to the project's events
+  }
+
+  onDrain() {
+    for (const client of this.#wss?.clients ?? []) client.close(1001, "server shutting down");
+    this.#wss?.close();
+  }
+}
+```
+
+GraphQL resolvers call `inject(ProjectAccess).require(...)` (next section).
+
 ### GraphQL with Yoga
 
 ```ts
+// src/graphql.ts
+import { ErrorTranslator, inject, UnauthorizedError } from "@raiyyan/brisk";
+import type { Request, Response } from "express";
+import { GraphQLError } from "graphql";
 import { createSchema, createYoga } from "graphql-yoga";
 
-const yoga = createYoga({
-  schema: createSchema({
-    typeDefs: "type Query { user(id: ID!): User } type User { id: ID! name: String! }",
-    resolvers: { Query: { user: (_parent, args: { id: string }) => inject(UsersService).get(args.id) } },
+interface GraphQLContext {
+  user: User | undefined;
+}
+
+export const yoga = createYoga<{ req: Request; res: Response }, GraphQLContext>({
+  schema: createSchema<GraphQLContext>({
+    typeDefs: "type Query { project(id: ID!): Project } type Project { id: ID! name: String! }",
+    resolvers: {
+      Query: {
+        project: async (_parent, args: { id: string }, { user }) => {
+          if (!user) throw new UnauthorizedError("Sign in first");
+          await inject(ProjectAccess).require(user.id, args.id, "viewer");
+          return inject(ProjectsService).get(args.id);
+        },
+      },
+    },
   }),
+  context: async ({ req }) => ({ user: await inject(Sessions).verify(req.get("authorization")) }),
+  maskError: (error) => {
+    if (error instanceof GraphQLError && !error.originalError) return error; // query syntax and validation errors
+    const cause = error instanceof GraphQLError ? error.originalError : error;
+    const { status, code, message } = inject(ErrorTranslator)(cause);
+    return new GraphQLError(message, { extensions: { code, status } });
+  },
 });
+```
 
+```ts
+// src/app.ts
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => expressApp.use(yoga.graphqlEndpoint, yoga),
+  mount: { [yoga.graphqlEndpoint]: (req, res) => yoga(req, res) },
   http: { securityHeaders: { "content-security-policy": false } }, // GraphiQL loads scripts; or set a GraphiQL-compatible policy
 });
 ```
 
-Resolvers call `inject()` directly.
+- Resolvers, the context factory and `maskError` call `inject()` directly: they run inside the request.
+- Mount Yoga through a function, as above: Yoga's own type is not an Express `RequestHandler`.
+- `maskError` gives GraphQL clients the same status, code and message a route would send: `errors.mappers` apply and internal messages stay hidden.
 
 ### GraphQL with Apollo Server
 
@@ -1150,11 +1479,11 @@ await apollo.start();
 
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => expressApp.use("/graphql", express.json(), expressMiddleware(apollo)),
+  mount: { "/graphql": [express.json(), expressMiddleware(apollo)] },
 });
 ```
 
-`configureExpress` runs before brisk parses JSON, so the Apollo route adds `express.json()` itself.
+brisk does not parse mount bodies, so the Apollo mount adds `express.json()` itself.
 
 ### tRPC
 
@@ -1171,7 +1500,7 @@ const router = t.router({
 
 export const app = defineApp({
   controllers,
-  configureExpress: (expressApp) => expressApp.use("/trpc", createExpressMiddleware({ router })),
+  mount: { "/trpc": createExpressMiddleware({ router }) },
 });
 ```
 
@@ -1230,10 +1559,8 @@ export const app = defineApp({
       "x-frame-options": false, // only when the frontend is embedded in iframes
     },
   },
-  configureExpress: (expressApp) => {
-    expressApp.use(cors({ origin: env.SHELL_ORIGIN }));
-    expressApp.use("/remotes/checkout", express.static("dist/checkout"));
-  },
+  use: [fromExpress(cors({ origin: env.SHELL_ORIGIN }))],
+  mount: { "/remotes/checkout": express.static("dist/checkout") },
 });
 ```
 
@@ -1243,7 +1570,7 @@ A frontend calls the API through the [typed client](#typed-client), with the man
 
 ### Caching
 
-- ETags and `304 Not Modified` work automatically for GET responses.
+- ETags and `304 Not Modified` work automatically for GET responses (to test them, see the 304 note under [Testing](#testing)).
 - Set `Cache-Control` in the handler: `res.set("cache-control", "public, max-age=60")`.
 - A Redis or in-memory cache client is a provider: connect in `onInit`, quit in `onShutdown`, `inject(Cache)` where needed.
 
@@ -1344,22 +1671,23 @@ export const handler = serverlessAdapter(instance.express); // your platform's E
 
 ### Clusters, PM2 and Kubernetes
 
-- brisk keeps no per-process state: run one process per core with PM2, `node:cluster` or replicas.
+- brisk keeps no per-process state: run one process per core with PM2, `node:cluster` or replicas. Your own in-process state (an in-memory event bus, files uploaded to local disk, an in-memory rate limit) does not span them; move it to shared services first.
 - Behind a load balancer, set the server's keep-alive timeout above the balancer's idle timeout (for example 65 seconds behind a 60-second idle timeout) to avoid 502s: `instance.server.keepAliveTimeout = 65_000` on the instance `listen` resolves with, or pass your own server.
 - Bind `host: "0.0.0.0"` in containers when the default does not reach the container network.
-- Point liveness and readiness probes at `/health`. SIGTERM triggers graceful shutdown; give the pod a termination grace period longer than `http.shutdownTimeoutMs`.
+- Point liveness and readiness probes at `/health`. It answers 503 once shutdown begins, so load balancers stop sending traffic. SIGTERM triggers graceful shutdown; give the pod a termination grace period longer than `http.shutdownTimeoutMs`.
 
 ## Production checklist
 
 - Validate every variable in `defineEnv`; keep `.env` out of version control.
 - Give every route that takes input a schema, and a `response` schema for anything that returns stored data.
 - Keep `errors.exposeInternal` off in production.
-- Set `http.trustProxy` only to match your proxy setup.
-- Add CORS with an explicit origin list and a rate limiter in `configureExpress`.
+- Set `trust proxy` in `http.settings` only to match your proxy setup.
+- Add CORS with an explicit origin list and a rate limiter in the app's `use`.
 - Use JSON logs in production (no `pretty`); report 5xx errors with `hooks.onError`.
 - Connect clients in `onInit`, close them in `onShutdown`; stop long-lived work in `onDrain`.
 - Set `http.shutdownTimeoutMs` below your orchestrator's grace period, and the keep-alive timeout above your load balancer's idle timeout.
 - Map database and SDK errors with `errors.mappers` instead of try/catch in services.
+- Before running more than one instance, move in-process state to shared services: event buses, uploaded files on local disk and in-memory rate limits each see only their own instance.
 - Run `npm audit` (or `pnpm audit`) in CI.
 
 ## Performance
@@ -1386,10 +1714,10 @@ It writes a brisk section between `<!-- brisk:start -->` and `<!-- brisk:end -->
 ## FAQ
 
 **Can I use plain Express middleware?**
-Yes. Put it in `configureExpress` (`app.use(helmet())`, `app.use(cors())`), globally or on specific paths.
+Yes. App-wide middleware goes in the app's `use` (`use: [fromExpress(helmet()), fromExpress(cors())]`). Middleware for some routes only, such as multer, goes in the route's `use` through `fromExpress(...)`.
 
 **Where do I put CORS?**
-In `configureExpress`: `app.use(cors({ origin: ["https://app.example.com"] }))`. It runs before brisk's routes, so preflight requests are answered first.
+In the app's `use`: `use: [fromExpress(cors({ origin: ["https://app.example.com"] }))]`. It runs before brisk's routes, so preflight requests are answered first.
 
 **How do I return a file?**
 Set headers on `res` and return a `Readable` (`return createReadStream(path)`), or call `res.sendFile(path)` or `res.download(path)` and return nothing.