@tulipes/cli 0.1.0-rc.1

package/templates/claude/skills/tulipes-model/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: tulipes-model
+description: Use when adding or changing a database model in a Tulipes app, querying from a route or job, seeding data, or ensuring indexes. Covers the ModelDef contract, the model store and bootstrap tasks.
+---
+
+# Adding a model
+
+Model files are **declarations**, not registrations. Never call
+`mongoose.model()` — the framework compiles the schema on its own
+connection and puts it in the model store.
+
+`modules/billing/models/invoice.model.ts`:
+
+```ts
+import { Schema } from "mongoose";
+import type { ModelDef } from "@tulipes/mongoose";
+import { baseSchemaOptions } from "@app/core";
+
+const invoiceSchema = new Schema(
+  {
+    customer: { type: Schema.Types.ObjectId, ref: "User", required: true },
+    amount_cents: { type: Number, required: true, min: 0 },
+    status: { type: String, enum: ["draft", "paid"], default: "draft", index: true },
+  },
+  baseSchemaOptions,
+);
+
+export default { name: "Invoice", schema: invoiceSchema } satisfies ModelDef;
+```
+
+## Field names are snake_case
+
+Every persisted field — and therefore every field that reaches a response
+body — is `snake_case`: `amount_cents`, `created_at`, `last_seen_at`,
+`password_hash`. camelCase is for TypeScript-only names: locals, function
+parameters, helper return shapes that never reach mongo or the wire.
+
+**Never declare `createdAt` / `updatedAt` yourself.** `baseSchemaOptions`
+already provides them as `created_at` and `updated_at`, and a hand-declared
+camelCase field silently shadows the plugin, leaving you with both.
+
+Renaming a persisted field is a data migration, not a rename: existing
+documents keep the old key and stop matching queries. Write a bootstrap
+task with `$rename` when you change one on live data.
+
+Read it anywhere the context reaches:
+
+```ts
+const Invoice = models!.get("Invoice");
+```
+
+`models.get()` throws on an unregistered name (listing what does exist),
+so a typo fails at the call site instead of returning `undefined`.
+
+## Requirements
+
+- The app selects its database once, in its root `package.json`:
+  `"tulipes": { "providers": { "models": "@tulipes/mongoose" } }`. A module
+  with `models/` or `bootstrap/` files in an app without that line is a boot
+  refusal before any model is imported. A module that reads models but owns
+  none declares `"tulipes": { "requires": ["models"] }` in its own manifest.
+- The provider needs `MONGO_URI` declared (sys `core` module) and set;
+  selected without a value is a boot refusal, not a warning.
+- Model names are globally unique; two modules registering `Invoice`
+  crashes the boot naming both.
+- Reference other modules' models by name (`ref: "User"`) — no import,
+  therefore no coupling.
+
+## Seeding and indexes
+
+Put anything that must run after models exist but before the server
+accepts traffic in `modules/<name>/bootstrap/*.bootstrap.ts`:
+
+```ts
+import type { Ctx } from "@tulipes/core/boot";
+
+export default async function seedPlans({ models }: Ctx): Promise<void> {
+  const Plan = models!.get("Plan");
+  await Plan.updateOne(
+    { code: "free" },
+    { $setOnInsert: { code: "free", price_cents: 0 } },
+    { upsert: true },
+  );
+}
+```
+
+**Make bootstrap tasks idempotent** — they run on every boot, in every
+process, including each worker. Upsert; never blind-insert.
+
+**And tolerate concurrency.** Backend and worker start together, so two
+processes run the same seed at the same time. Concurrent upserts on a
+unique index race: one inserts, the other gets a duplicate-key error
+(`code: 11000`). Catch that one code and carry on — the row exists, which
+is all the task wanted.
+
+## Gotchas
+
+- Global plugins (timestamps, soft delete) only apply to schemas compiled
+  *after* registration, which is why `registerBasePlugins()` is called from
+  the sys core module's `module.config.ts` — phase 6, before models compile
+  in phase 8. That covers every mode, scripts included; calling it from
+  `app.ts` instead would leave scripts compiling models without the
+  soft-delete guard.
+- Mongoose queries are lazy: `await` them, and prefer `.lean()` for reads
+  you only serialize.
+- If the app soft-deletes, ordinary queries already exclude deleted rows;
+  use `.withDeleted()` / `.onlyDeleted()` to opt out deliberately.

package/templates/claude/skills/tulipes-module/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: tulipes-module
+description: Use when adding a new feature to a Tulipes app — a new module under modules/ — or when deciding whether something belongs in an existing module or a new one. Covers the tulipes manifest key, tier, priority, dependsOn and workspace wiring.
+---
+
+# Adding a module
+
+A module is one feature, one folder, one workspace package. It owns its
+routes, models, config, permissions and jobs, and can be deleted without
+touching anything else.
+
+## Decide first
+
+- **Extend an existing module** when the work is part of that feature
+  (another users endpoint → `modules/users`).
+- **New module** when it is a separate feature with its own vocabulary.
+- **The sys core module** when it is a shared helper with no routes or
+  models of its own — export it from `modules/core/index.ts` and import it
+  as `@app/core`. There is no top-level `lib/`: a helper two modules need
+  is owned by a module like everything else.
+
+## Steps
+
+1. Scaffold: `yarn tulipes new module billing`. It creates every
+   contract — package.json (scope detected from siblings), meta.variables,
+   config with lifecycle hooks, ACL, helper, a controller class, routes
+   declaring a RAI, model, bootstrap, queue and socket. Delete the ones this feature does not
+   need. For offline inspection, keep tulipes.offline: true and wrap route
+   factories in defineRoutes(); modules without routes need no placeholder file.
+2. Set ordering in `modules/billing/package.json`:
+
+```json
+{
+  "name": "@app/billing",
+  "tulipes": { "tier": "app", "priority": 100, "dependsOn": ["users"] },
+  "dependencies": { "@tulipes/core": "^0.7.0", "express": "^5" }
+}
+```
+
+3. `yarn install` — the module is a workspace, so the package manager must
+   link it before imports resolve.
+4. Put endpoints and shared middleware in native `routes/*.routes.ts` factories.
+   Add optional files as needed:
+   `models/`, `queues/`, `sockets/`, `bootstrap/`, `module.acl.ts`,
+   `i18n/` — the module is its own i18n namespace. → skill `tulipes-i18n`
+5. `yarn sync && yarn dev` — the banner must list the module.
+
+## The manifest key
+
+| Field | Meaning |
+|---|---|
+| `tier` | `sys` loads before every `app` module. Use `sys` **only** for framework-level concerns: global middleware, roles, infra variables. A business feature is always `app`. |
+| `priority` | Lower loads earlier within a tier. Default 100. Use it for coarse ordering, not for dependencies. |
+| `dependsOn` | Short names (`"users"`, not `"@app/users"`) of modules that must load first. Declare this whenever you import from another module or read its config. |
+
+## Gotchas
+
+- **`dependsOn` and the npm dependency are two different things.** To
+  import `@app/users` you need it in `dependencies` (resolution) *and* in
+  `dependsOn` (load order). Missing the first fails at import; missing the
+  second gives you a module whose config namespace may not exist yet.
+- A `sys` module may not `dependsOn` an `app` module — that inverts the
+  tier guarantee and crashes the boot.
+- Cycles crash the boot with the cycle printed. If two modules need each
+  other, the shared part belongs in the core module or a third module.
+- The folder name is cosmetic; the **short name** (last segment of the
+  package name) is what `dependsOn` and the config namespace use.

package/templates/claude/skills/tulipes-permissions/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: tulipes-permissions
+description: Use when adding roles or permissions to a Tulipes app, guarding an endpoint by role, making a route public, or deciding who may do what. Covers module.acl.ts, the guest role, and module-namespaced resources.
+---
+
+# Adding permissions
+
+Roles are **global** and defined once by the sys `auth` module. Every other
+module **grants** permissions on its own resources to those roles.
+
+`modules/auth/module.acl.ts` — the vocabulary:
+
+```ts
+export default function authAcl(acl: AclBuilder): void {
+  acl.defineRole("guest").defineRole("user").defineRole("admin");
+  acl.allow("guest", "auth:login", "auth:register", "auth:refresh");
+  acl.allow("admin", "*");
+}
+```
+
+`modules/billing/module.acl.ts` — grants for this feature:
+
+```ts
+export default function billingAcl(acl: AclBuilder): void {
+  acl.allow("user", "invoices:read");
+}
+```
+
+Guarding is the route's RAI — its `id` **is** the permission, so there is
+no second call to forget:
+
+```ts
+router.get(
+  `${base}/invoices`,
+  rai({ id: "invoices:read", name: "List invoices" }),
+  billing.list(),
+);
+```
+
+## Public routes are grants, not exceptions
+
+A request with no valid token is not rejected — it becomes the **`guest`**
+caller. So "public" means guest holds the permission:
+
+```ts
+acl.allow("guest", "docs:read");   // now anyone may read the docs
+```
+
+There is no allowlist, no `skipAuth` flag, no second mechanism. Access is
+decided in one place, and the whole policy is readable by reading the
+`module.acl.ts` files.
+
+**The corollary matters: a route with no permission check is public.**
+Because the pipeline authenticates rather than rejects, forgetting a guard
+does not fail closed — it silently exposes the route. Name a permission on
+every route, even ones you expect everybody to reach.
+
+## Rules
+
+- **Resources are namespaced by module**: `invoices:read`, `users:write`.
+  Match the module's short name so ownership is obvious.
+- **Grant, don't define.** A feature module calling `defineRole()` usually
+  means the role belongs in `auth`. `allow()` on an unknown role is a boot
+  error, never an implicit creation.
+- The same role+resource granted twice crashes the boot.
+- Wildcards: `*` (everything), `invoices:*` (a namespace). Give `*` to
+  `admin` only.
+- Unknown roles always deny at runtime.
+
+## Who is calling
+
+`req.auth` is resolved before any feature route runs, and is never
+undefined inside a declared route:
+
+```ts
+const { isAuthenticated, user, session } = req.auth;
+user?.email          // the hydrated user document, or null for a guest
+session?.sid         // this device's session row, or null
+session?.accessJti   // the token in hand, for revoking exactly it
+```
+
+Never re-parse the Authorization header or trust a claim out of a token —
+the pipeline already resolved both, and reloads the user on every request
+so a demotion takes effect immediately.
+
+A route that only cares that somebody is signed in still declares a RAI
+and grants it to `user`; there is no separate "just needs auth" guard.
+
+## Denials
+
+The RAI answers 401 when the caller is a guest (signing in would help) and
+403 when they are authenticated but lack the grant (it would not).
+
+## Gotchas
+
+- Load order: roles must exist before grants, which is why `auth` is
+  `tier: "sys", priority: 20`. A module granting on those roles is app-tier
+  and therefore loads later; if you make one sys-tier, give it a higher
+  priority than auth or it will crash with "unknown role".
+- `acl.can()` answers *what a role may do*, not *who the caller is*.
+  Resolving the caller is the auth module's job — it sets `req.auth`.
+- The role core checks is `req.auth.user.role`. An app whose roles live
+  elsewhere replaces the decision with `ctx.routes.setAccessChecker()`
+  rather than inventing a fake user.
+- Roles are lowercase kebab-case; resources are `name:action`.

package/templates/claude/skills/tulipes-queue/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: tulipes-queue
+description: Use when adding background work to a Tulipes app — emails, webhooks, exports, scheduled retries — or when a request handler is doing something slow. Covers the queues contract, producing jobs, and the backend/worker process split.
+---
+
+# Adding a background job
+
+One file declares both sides of a queue, and the process mode decides what
+happens with it: the **backend** process registers the queue so routes can
+produce into it; the **worker** process turns the processor into a live
+consumer. Never duplicate the definition.
+
+`modules/billing/queues/invoices.queues.ts`:
+
+```ts
+import type { Ctx } from "@tulipes/core/boot";
+import type { QueueRegistry } from "@tulipes/bullmq";
+
+export default function invoiceQueues({ models }: Ctx, queues: QueueRegistry): void {
+  queues.define("billing.send-invoice");
+
+  queues.process("billing.send-invoice", async (job) => {
+    const invoice = await models!.get("Invoice").findById(job.data.invoiceId);
+    // …do the slow thing here…
+    return { sent: true };
+  });
+}
+```
+
+Produce from anywhere with the context:
+
+```ts
+await queues!.add("billing.send-invoice", "send", { invoiceId: invoice.id });
+```
+
+Run a consumer with `yarn worker`. Without it, jobs pile up in Redis and
+nothing processes them — that is the correct behaviour, not a bug.
+
+## Rules
+
+- **Queue names use `.`, never `:`** (`billing.send-invoice`). BullMQ
+  reserves `:` as its Redis key separator; a `:` name crashes the boot.
+- Names are globally unique, and a queue may have only one processor —
+  duplicates crash the boot naming both modules.
+- A processor registered for a queue nobody defined is a boot error; call
+  `define()` in the same file.
+- The app selects its queue provider once, in its root `package.json`:
+  `"tulipes": { "providers": { "queues": "@tulipes/bullmq" } }`. A module with a
+  `queues/` file in an app without that line is a boot refusal before any
+  module is imported; a module that only produces declares
+  `"tulipes": { "requires": ["queues"] }` in its own manifest.
+- The provider needs `REDIS_URL` declared (sys `core` module) and set;
+  selected without a value is a boot refusal. The app's own Redis users
+  (cache, rate limiter) keep their own connections and their own `ioredis`.
+- Worker mode with zero processors refuses to start: a consumer with
+  nothing to consume is a misconfigured deployment.
+
+## Writing a processor
+
+- **Jobs retry.** Make the handler idempotent — the same job may run twice
+  after a crash or timeout.
+- Pass identifiers in `job.data`, not whole documents; re-read from the
+  database inside the processor so the job acts on current state.
+- Keep payloads small and JSON-serializable.
+- Throwing marks the job failed and schedules a retry per its options; let
+  it throw rather than swallowing errors.
+- Both processes run the full boot pipeline, so `models`, `config` and
+  `Environment` are all available inside a processor.

package/templates/claude/skills/tulipes-response/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: tulipes-response
+description: Use when writing any endpoint response in a Tulipes app — returning data, paginating a list, reporting a validation failure, or setting meta.action. Covers res.respond, the response envelope, error codes and req.page.
+---
+
+# Responding
+
+Every endpoint answers with one shape, so a client writes its unwrapping
+once:
+
+```jsonc
+{
+  "success": true,
+  "data": { },      // or [ ], or null on failure
+  "errors": [ ],    // [{ field, message, code }] on failure
+  "meta": { }       // action, pagination
+}
+```
+
+`res.respond` builds it. Express is untouched — `res.json`, `res.send` and
+`res.status` behave exactly as they always did — so `respond` is a method
+you call, never a wrapper you fight.
+
+## Success
+
+```ts
+res.respond({ data: user });                        // 200
+res.respond({ data: user, status: 201 });           // created
+res.respond({ data: null, meta: { action: "complete_profile" } });
+```
+
+## Lists and pagination
+
+`req.page` is already parsed from `?page` and `?per_page` and clamped by
+`config.pagination`, so no endpoint re-derives it and none can be talked
+into ten thousand rows:
+
+```ts
+const { per_page, skip } = req.page;
+const [items, total_items] = await Promise.all([
+  Model.find().skip(skip).limit(per_page).lean(),
+  Model.countDocuments(),
+]);
+res.respond({ data: items, meta: { total_items } });
+```
+
+**Passing `total_items` is what marks a response as a page.** `respond`
+fills in `page`, `per_page` and `total_pages` from the request and the
+count. Without it, `meta` stays clean — a single record does not carry
+four null pagination keys.
+
+## Failures are thrown, never responded
+
+The terminal handler builds the same envelope from a thrown error, so a
+handler only ever writes the happy path.
+
+```ts
+throw new HttpError(404, "notFound");
+throw new HttpError(422, "emailTaken", { field: "email" });
+```
+
+The message is an **i18n key**. The handler translates it in the module's
+namespace — the one the route's RAI recorded — and derives the code from
+the key, so `notFound` becomes `NOT_FOUND` and `emailTaken` becomes
+`EMAIL_TAKEN`. One string, no second thing to keep in step.
+
+An already-translated message also works, because a string that resolves
+to no key is used as written:
+
+```ts
+throw new HttpError(403, req.t("registrationClosed", { mode }), {
+  code: "REGISTRATION_CLOSED",   // no key to derive from, so name it
+});
+```
+
+Prefer the key form. Pass `vars` when the key interpolates
+(`{ vars: { name } }`), and `code` only to override what the key derives.
+
+### Several fields at once
+
+A form wrong in three places should say so once:
+
+```ts
+const issues: FieldIssue[] = [];
+if (!email) issues.push({ field: "email", message: "emailRequired" });
+if (!password) issues.push({ field: "password", message: "passwordTooShort" });
+if (issues.length > 0) throw new ValidationError(issues);   // 422
+```
+
+## meta.action
+
+`action` tells the client what to do next — `complete_profile`,
+`redirect_to_signin`. Declare the set and every call site is checked:
+
+```ts
+declare module "@tulipes/core/http" {
+  interface MetaActions {
+    complete_profile: true;
+    redirect_to_signin: true;
+  }
+}
+```
+
+Until you declare any, `action` accepts any string.
+
+## Rules
+
+- **Never `res.json` in a handler.** It ships a raw, unenveloped body.
+  Development logs a warning naming the route when this happens; nothing
+  catches it in production.
+- **Never build an error body by hand.** `throw` and let the terminal
+  handler shape it — a hand-rolled 500 leaks what the framework hides.
+- `data` and `errors` are mutually exclusive: a failure carries `data:
+  null`, whatever was passed.
+- **Field names on the wire are `snake_case`**, envelope and payload
+  alike. → skill `tulipes-model`
+- Codes are stable and never translated; messages are translated and
+  never parsed. A client branches on `code`.

package/templates/claude/skills/tulipes-settings/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: tulipes-settings
+description: Use when working with the settings module — the sysadmin console that describes every module, edits environment variables and translations, restarts the app, or streams logs. Covers the sysadmin role, where a written variable actually lands, and why some writes cannot take effect.
+---
+
+# The settings module
+
+An infrastructure console: what every module declares, what its variables
+resolve to and from where, its translations, and a live view of the logs.
+
+Everything it reports comes from the **booted context** — `ctx.modules`,
+the variable store, the ACL, the RAI registry — so it cannot describe an
+app different from the one running.
+
+## Access is `sysadmin`, and that is a real boundary
+
+`settings:*` is granted only to `sysadmin`. This works because the auth
+module grants `admin` its namespaces **explicitly** rather than `*`:
+
+```ts
+acl.allow("admin",    "auth:*", "users:*", "hello:*");
+acl.allow("sysadmin", "auth:*", "users:*", "hello:*");   // + settings:* from settings
+```
+
+**A wildcard would reach `settings:*` like any other id**, and "sysadmin
+only" would be a label rather than a rule. When you add a feature module,
+add its namespace to *both* grants — a new module is invisible to admin
+otherwise.
+
+A fresh app seeds an `admin`, so the console is inert until someone is
+deliberately promoted to `sysadmin`.
+
+## Endpoints
+
+| | |
+|---|---|
+| `GET /settings/modules` | every module: manifest, variables with full spec + resolved source, config, i18n, routes |
+| `GET /settings/variables/:name` | one variable; `?reveal=true` returns a secret's value, audited |
+| `PUT /settings/variables/:name` | set a value — validated against the variable's own spec |
+| `GET`/`PUT /settings/i18n/:module/:locale` | read or replace a module's translations |
+| `POST /settings/reboot` | restart via PM2 so written values take effect |
+| `GET /settings/logs/stream` | SSE; `?process=backend\|worker&level=warn&tail=200` |
+
+## Where a written variable actually lands
+
+**Always `.envs/.env.<APP_ENV>` — never `meta.variables.json`.** That file
+is the module's committed contract: rewriting a default there would change
+it for every environment and be lost on the next deploy. The env file is
+what exists to hold per-deployment values.
+
+The file is edited **surgically** — one line replaced, comments and
+ordering untouched — because these files are half explanation and a
+`stringify(parse(file))` round trip would erase all of it.
+
+### The case that catches people
+
+Precedence is `process.env` → env file → default. A variable injected by
+the **container** outranks both, so writing the file changes nothing, and
+a restart re-reads the same container environment and it wins again.
+
+When that happens the write still lands in the file *and* sets
+`process.env` live, and the response says so:
+
+```jsonc
+{ "meta": { "action": "restart_required_shadowed" } }
+```
+
+That makes the change real for **this process only**. Other replicas keep
+the old value until the container's environment itself is changed.
+
+## Nothing takes effect until a restart
+
+Variables resolve once at boot, and `config.<module>` is derived from them
+by factories that also run once. A write persists; it does not move the
+running app. Every write response carries `requires_reboot: true`.
+
+`POST /settings/reboot` restarts through PM2, ordering the process serving
+the request **last** so the caller still gets its response. Under `yarn
+dev` there is no PM2, and it answers `503 NOT_SUPERVISED` rather than
+exiting a process nothing would restart.
+
+## Logs are read from files, not hooked in-process
+
+The stream tails `LOG_DIR`, which is what lets it show the **worker** —
+backend and worker are separate processes writing separate files, and an
+in-process stream could only ever show its own. The tailer is
+rotation-aware: pino-roll renames and starts a new file, and a naive watch
+on one path goes silent the moment it rolls.
+
+`LOG_FILE=false` means there are no files; the endpoint says so rather
+than streaming nothing.
+
+## Audit
+
+Every reveal, write and reboot logs at `warn` with actor, role, IP and
+old→new. **A secret's value is never recorded in either direction** — an
+audit entry that reconstructs a rotated key defeats rotating it; those
+entries carry `redacted: true` and no values.
+
+`?level=warn` on the log stream shows the audit trail and nothing else.
+
+## Rules
+
+- Never add a `settings:*` grant to another role. If someone needs part of
+  it, give them `sysadmin`, or split the ids.
+- Never widen a write to `meta.variables.json`. It is a contract, not
+  storage.
+- A new feature module needs its namespace in **both** the `admin` and
+  `sysadmin` grants.
+- Treat a `restart_required_shadowed` response as a warning to fix the
+  deployment's environment, not as a successful change.

package/templates/claude/skills/tulipes-socket/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: tulipes-socket
+description: Use when adding realtime features to a Tulipes app — websockets, live updates, presence, notifications — or when emitting events from a route or background job. Covers the sockets contract and namespace ownership.
+---
+
+# Adding realtime
+
+Socket.IO namespaces are claimed by modules, one owner each, in
+`modules/<name>/sockets/*.sockets.ts`. Websockets are opt-in: an app with
+no socket files starts no Socket.IO server at all.
+
+```ts
+import type { Ctx } from "@tulipes/core/boot";
+import type { SocketRegistry } from "@tulipes/socket.io";
+
+export default function billingSockets({ config }: Ctx, sockets: SocketRegistry): void {
+  sockets.namespace("/billing", (nsp) => {
+    nsp.on("connection", (socket) => {
+      socket.emit("ready", { plan: config.billing?.plan });
+
+      socket.on("subscribe", (invoiceId: string) => {
+        socket.join(`invoice:${invoiceId}`);
+      });
+    });
+  });
+}
+```
+
+Emit from anywhere with the context — a route, a bootstrap task, a queue
+processor in the backend process:
+
+```ts
+ctx.sockets!.of("/billing").to(`invoice:${id}`).emit("invoice:paid", payload);
+```
+
+## Rules
+
+- The app selects its socket provider once, in its root `package.json`:
+  `"tulipes": { "providers": { "sockets": "@tulipes/socket.io" } }`. A module
+  with a `sockets/` file in an app without that line is a boot refusal before
+  any module is imported; a module that only emits declares
+  `"tulipes": { "requires": ["sockets"] }`.
+- **Namespaces are claimed once.** A second module claiming `/billing`
+  crashes the boot naming both.
+- `sockets.of()` throws on a namespace nobody claimed. Socket.IO's raw
+  `io.of()` would silently create it and emit into the void — use the
+  framework accessor so typos surface.
+- Sockets exist in **backend mode only**. `ctx.sockets` is undefined in the
+  worker process, so a queue processor cannot emit directly — publish to
+  Redis, or have the backend process subscribe.
+- Namespace names are lowercase kebab-case with a leading slash.
+
+## Gotchas
+
+- Authenticate in namespace middleware (`nsp.use(...)`), not per event —
+  the framework's HTTP pipeline does not run for socket connections.
+- Scaling past one backend process needs the Socket.IO Redis adapter;
+  otherwise an emit only reaches clients connected to that instance.
+- Socket handlers run outside the request pipeline: no `HttpError`, no
+  request logging. Handle failures explicitly and emit an error event.