@tulipes/cli 0.1.1 → 0.2.0-rc.2

package/templates/claude/skills/tulipes-agent-tool/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: tulipes-agent-tool
+description: Use when exposing a Tulipes module to AI agents — describing it, choosing which endpoints an agent sees, adding an action that is not an endpoint, or wiring the app to Claude Code through MCP. Covers agent/*.agent.ts, the manifest, the agent door and tulipes-mcp.
+---
+
+# Exposing a module to agents
+
+Every endpoint is already a tool: its `rai()` declares the name, the
+description, the input schema (`params`, `query`, `body`) and the
+permission, and the boot derives a tool from it — `hello:list-greetings`
+becomes `hello_list-greetings`, a `GET` is marked read-only. A module with
+no `agent/` folder exposes every route it declares. The folder adds what
+cannot be derived.
+
+The agent surface and `@tulipes/mcp` are **experimental** in 0.11: they may
+change in any release without a deprecation period. Check `MIGRATING.md`
+after each `@tulipes/core` upgrade before relying on a manifest shape.
+
+`modules/hello/agent/hello.agent.ts`:
+
+```ts
+import { action, defineAgent } from "@tulipes/core/agent";
+import { requireModels } from "@tulipes/core/boot";
+import { z } from "zod/v4";
+
+export default defineAgent({
+  summary: "Greets callers and counts how often each greeting is used.",
+  tools: [
+    // Derived from the route; the description overrides the RAI's for agents only.
+    { route: "hello:list-greetings", description: "The stored greetings, most used first" },
+    { route: "hello:use-greeting" },
+
+    // Declared: not an endpoint. The id is a permission, granted in module.acl.ts.
+    action({
+      id: "hello:reset-counts",
+      description: "Reset the usage counter of every greeting to zero",
+      input: z.object({ confirm: z.literal(true) }),
+      handler: async (ctx, input, actor) => {
+        const { modifiedCount } = await requireModels(ctx).get("Greeting").updateMany({}, { times_used: 0 });
+        return { reset: modifiedCount };
+      },
+    }),
+  ],
+});
+```
+
+`pnpm tulipes agent manifest` prints the result from an inspection boot —
+no service or `.env` needed; `--role admin` shows what one role gets.
+
+## Rules
+
+- **`tools` omitted exposes every route; given, it is the whole list.**
+  `{ route: "*" }` is every route of the module, `{ route: "hello:*" }` a
+  namespace, an exact id one route. A route id the module never declared is
+  a boot error. One `agent/*.agent.ts` per module.
+- **An endpoint that must stay out of the manifest says `agent: false`** on
+  its `rai()` — the agent door's own routes do.
+- **An action's id is a permission like any route's.** The ACL decides on
+  it first (401 for a guest, 403 for a role without it), then the `input`
+  schema validates (422 with field issues), then the handler runs with the
+  runtime context, the parsed input and the actor (`req.auth` plus `role`).
+  Grant it in `module.acl.ts`; a wildcard such as `hello:*` already covers it.
+- **Write the description for the agent, not the operator.** It is the only
+  text the model sees before choosing the tool. Say what the tool does, what
+  it changes and what it returns; keep `readOnly: true` honest.
+- **Route tools are called at their own path**, through the app's middleware
+  and auth, never around it. The manifest gives the method and path; the
+  input is `{ params, query, body }` as the RAI declares them. A path
+  parameter without a `params` schema is still listed as a required string.
+- **Keep handlers small.** An action that grows a second step is a
+  controller in disguise: move the logic to `helpers/` and call it from both.
+
+## The door and MCP
+
+The app's `agent` module serves the manifest at `GET <prefix>/agent/tools`,
+filtered to the caller's role, and runs actions at
+`POST <prefix>/agent/tools/<name>`. Any client with a bearer token the auth
+module accepts can use it. For Claude Code or Claude Desktop:
+
+```sh
+pnpm add -D @tulipes/mcp
+claude mcp add my-app -- pnpm tulipes-mcp --url http://localhost:3000/api/v1/agent --token "$TOKEN"
+```
+
+`tulipes-mcp` lists the manifest as MCP tools and calls each through the
+door with that token, so the app's own auth and ACL decide — it adds no
+identity of its own and never touches the database.

package/templates/claude/skills/tulipes-boot-errors/SKILL.md

@@ -30,10 +30,16 @@ problems the report has not reached yet.
 | `module graph` | `dependsOn "x" — no such module exists` | Typo, or you used the package name. `dependsOn` takes short names (`"users"`). |
 | `module graph` | `dependency cycle: a → b → a` | Mutual dependency. Move the shared part into the core module or a third module. |
 | `module graph` | `sys module cannot depend on app module` | A sys module needs something app-tier. Either it is not really sys, or the dependency belongs in `lib/`. |
-| `config` | `module.config must default-export a function` | Missing/misspelled `export default`. |
+| `modules` | `x does not belong at the module root` | Only `package.json`, `module.config.ts` and `module.acl.ts` live there; the message names the folder the file belongs in. |
+| `modules` | `tulipes.offline is gone` / `meta.variables.json moved to package.json` | The 0.10 forms. Delete the flag; move the variables under `tulipes.env`. |
+| `routes` | `routes function threw: ctx.models is not available during inspection` | A routes file or a controller constructor touched infrastructure while building. Move the read into the handler, or build the middleware with `lazy()`. |
+| `config` | `module.config must default-export defineConfig({ schema })` | Missing/misspelled `export default`, or the 0.10 factory form: values now live in the settings store. |
+| `config` | `module.config exports "onReady"` | The 0.10 lifecycle exports. Initialization is a `bootstrap/*.bootstrap.ts` file, which may return its cleanup; long-lived work ends on `ctx.signal`. |
+| `config` | `field "x" has no default — every setting needs one` | Give the field a `.default()`; an operator is never asked for a value the process needs to boot. |
+| `settings` | `stored setting "users.maxSessions": …` | The store holds a value the schema no longer accepts. Fix it in the store (or the file the message names). |
 | `acl` | `allow() on unknown role "x"` | Role never defined. Roles live in the sys `auth` module; define it there and `dependsOn: ["auth"]`. |
 | `acl` | `already granted … duplicate grant` | Two modules grant the same role+resource. Namespace the resource by module. |
-| `providers` | `[x] requires capability "models" … declares no provider for it` | A module has `models/` or `bootstrap/` files (or `requires: ["models"]`) but the app's `package.json` has no `"tulipes": { "providers": { "models": "@tulipes/mongoose" } }`. Add that line; an installed package or a `MONGO_URI` alone selects nothing. |
+| `providers` | `[x] requires capability "models" … declares no provider for it` | A module has `models/` files (or `requires: ["models"]`) but the app's `package.json` has no `"tulipes": { "providers": { "models": "@tulipes/mongoose" } }`. Add that line; an installed package or a `MONGO_URI` alone selects nothing. |
 | `providers` | `provider "…" cannot be resolved from …` | The declared specifier is not installed in the app. Install it (or fix the path). |
 | `providers` | `"@tulipes/core/db" no longer contains the Mongoose provider` | The app still declares the pre-extraction specifier. Install `@tulipes/mongoose`, declare it, and import `ModelDef`/`BootstrapFn` from it. |
 | `providers` | `[x] requires capability "queues" … declares no provider for it` | A module has a `queues/` file (or `requires: ["queues"]`) but the app's `package.json` has no `"tulipes": { "providers": { "queues": "@tulipes/bullmq" } }`. Add that line. |
@@ -59,16 +65,16 @@ runs, check in this order:
 2. **Directory** — routes in `routes/`, models in `models/`, and so on.
    Nested subfolders are not scanned.
 3. **The module is registered** — it needs a `package.json` and a
-   `yarn install` after creation. The startup banner lists every module it
+   `pnpm install` after creation. The startup banner lists every module it
    found; if yours is missing, the problem is there.
 4. **`export default`** — every contract file except models exports a
    function as its default.
 
 ## Other symptoms
 
-- **Types are `unknown` or a new variable is not typed** → run `yarn sync`.
+- **Types are `unknown` or a new variable is not typed** → run `pnpm sync`.
 - **Worker exits immediately** → no processors registered; it refuses to
   idle. Add a `*.queues.ts` with `process()`.
 - **Env change has no effect** → `process.env` beats the file. Check for a
   shell export or container variable of the same name.
-- To validate configuration without booting the whole app: `yarn check`.
+- To validate configuration without booting the whole app: `pnpm check`.

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

@@ -0,0 +1,74 @@
+---
+name: tulipes-config
+description: Use when adding or changing a setting — a value an operator should be able to edit at runtime — or when working on the config module, the console that describes every module and edits settings. Covers defineConfig, onChange, restart-tagged fields, the console endpoints, versions and the audit.
+---
+
+# Settings and the config module
+
+A setting is declared once, in the module's `module.config.ts`, the file's
+only export:
+
+```ts
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+export default defineConfig({
+  schema: z.object({
+    maxSessions: z.number().int().positive().default(5)
+      .describe("Max concurrent sessions per user; the oldest is evicted past it"),
+    signupMode: z.enum(["open", "invite", "closed"]).default("open")
+      .describe("Who can register"),
+    listenPort: z.number().int().default(8080).meta({ restart: true })
+      .describe("Applied on the next boot"),
+  }),
+  /** Optional: rebuild what was built from a value. Runs in every replica after a write lands. */
+  onChange(next, ctx) {
+    rebuildRateLimits(ctx, next.rateLimits);
+  },
+});
+```
+
+`pnpm sync` types it: `ctx.config.users.maxSessions` is a `number` at
+every call site. Read it where it is used, never capture it at boot — the
+object is replaced in place when a write lands.
+
+## Rules
+
+- **Every field has a default.** A namespace never written is its
+  defaults; the first boot writes them. There is no "required setting",
+  because an operator cannot be asked for a value the process needs to boot.
+- **No secrets.** `defineConfig` refuses a field whose metadata says
+  `secret`; a secret is an environment variable. → skill `tulipes-env-variable`
+- **Describe every field.** `.describe()` is what the console form, the
+  generated types and an agent reading the manifest see.
+- **Validate in the schema, not in `onChange`.** The store persists before
+  `onChange` runs, so a refinement that throws there would leave a value
+  stored that the module cannot use. `.refine()` keeps it out of the store.
+- **Rebuild in `onChange` what you built from a value.** A middleware
+  constructed from a setting at boot does not see the write; either build
+  it per request from the live value (helmet, CORS, the body parser do) or
+  rebuild it in `onChange` (the rate limiter does, because it holds a Redis
+  client).
+- **Tag what cannot be hot-applied** with `.meta({ restart: true })`. The
+  write persists, applies on the next boot, and the response carries
+  `requires_restart` and `meta.action: "restart_required"`.
+
+## The console: the `config` module
+
+| | |
+|---|---|
+| `GET /config` | every module in load order: manifest, declared variables (names, types, sources — a secret's value never), settings with schema, live values and stored version, endpoints with the roles that reach them |
+| `GET /config/:module` | the same for one module |
+| `PATCH /config/:module` | `{ values: { … }, version? }` — a patch over the stored values, validated by the module's schema (422 with the field), refused when `version` is not the stored one (409 `STALE_VERSION`), audited before it lands, applied at once in every replica |
+
+`config:read` and `config:describe` are granted to `admin` and `sysadmin`;
+`config:write` to `sysadmin` only. The audit (`config_audit_events`) holds
+the namespace, the field names, the version the caller read, the actor and
+the client IP — never a value — and is acknowledged by a majority before
+the write happens: a change nobody can account for is worse than one that
+did not happen. Variables are read-only here: what boot needs before the
+store answers, and secrets, are not edited at runtime.
+
+The same three endpoints are tools in the agent manifest, so an agent with
+`sysadmin` reconfigures the app through the door an operator uses, with
+the same audit. → skill `tulipes-agent-tool`

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

@@ -37,35 +37,42 @@ the handlers that use them without threading ctx through every signature.
 
 ```ts
 import { Router } from "express";
-import { defineRoutes } from "@tulipes/core/http";
+import type { BackendCtx } from "@tulipes/core/boot";
 
-export default defineRoutes(({ app, rai, routes, runtime }) => {
+import { BillingController } from "../controllers/billing.controllers.js";
+
+export default function billingRoutes(ctx: BackendCtx): Router {
   const router = Router();
-  const billing = runtime(async ctx => {
-    const { BillingController } = await import("../controllers/billing.controllers.js");
-    return new BillingController(ctx);
-  });
-  router.get("/:id", rai({ id: "billing:read", name: "Read an invoice" }),
-    billing(value => value.show()));
-  routes.mount(app, "/invoices", router);
-});
+  const billing = new BillingController(ctx);
+  router.get("/:id", ctx.rai({ id: "billing:read", name: "Read an invoice" }), billing.show());
+  return router;                          // mounted under config.api.prefix
+}
 ```
 
-Set tulipes.offline: true in the module manifest. runtime() acquires each controller
-once at boot, and its binder selects callbacks before listening. Offline inspection
-builds real routers without running acquisition functions or callback selectors.
-Keep service-dependent imports inside runtime(). Pure callbacks need no binding.
+A routes file is a plain function of the context. A returned router is
+mounted under `config.api.prefix`; `ctx.routes.mount(router, "/invoices")`
+chooses another path, and `ctx.routes.mount(parent, "/tenants/:tenant",
+child)` nests one router in another (`Router({ mergeParams: true })` on the
+child for inherited parameters). A file that only mounts global middleware
+on `ctx.app` returns nothing.
 
-Use router.use for shared middleware, router.param for parameter callbacks, and
-router.route for chained method registrations. The same binder supports all
-callback kinds, including error handlers. Preserve native registration order.
-Parameter callbacks run before endpoint RAI; authorization-sensitive loading
-belongs after rai() or behind an appropriate earlier authorization check.
+**Build with the context, use infrastructure in handlers.** `tulipes routes`
+and `tulipes spec` build every router with nothing acquired: the environment
+is declared but unresolved and `ctx.models`, `ctx.queues` and `ctx.sockets`
+are stubs that throw. So a controller keeps `ctx` and reads `ctx.models`
+inside its handlers (as every controller in this app does), and a middleware
+that needs a variable or a client is built on its first request:
+
+```ts
+import { lazy } from "@app/core";
+app.use(lazy(() => express.json({ limit: String(Environment.get("BODY_LIMIT")) })));
+```
 
-Use routes.mount for nested/shared prefixes, including named parameters. Set
-Router({mergeParams:true}) on children needing inherited parameter values.
-Existing RoutesFn factories remain supported with --runtime. After changes run
-the app tests, tulipes routes --offline and yarn spec; inspect generated diffs.
+Use router.use for shared middleware, router.param for parameter callbacks, and
+router.route for chained method registrations. Preserve native registration
+order. Parameter callbacks run before the endpoint's RAI; authorization-sensitive
+loading belongs after rai() or behind an earlier authorization check. After
+changes run the app tests, `tulipes routes` and `pnpm spec`; inspect generated diffs.
 
 ## The RAI is not optional
 
@@ -86,8 +93,14 @@ This exists because the pipeline authenticates rather than rejects: an
 undeclared route is not merely undocumented, it is reachable by `guest`.
 Grant the id in `module.acl.ts` — to `guest` if the endpoint is public.
 
-`tulipes routes --offline` lists every declared endpoint with the roles that reach
-it.
+`tulipes routes` lists every declared endpoint with the roles that reach it,
+without a service, a secret or a `.env`.
+
+The same declaration is the endpoint's **tool definition**: `tulipes agent
+manifest` lists every route as a tool an agent may call, with the `name`,
+`description` and schemas as written here. Write the description for a model
+choosing between tools; `agent: false` keeps a route out of the manifest.
+→ skill `tulipes-agent-tool`
 
 ## Responses and errors
 

package/templates/claude/skills/tulipes-env-variable/SKILL.md

@@ -1,44 +1,72 @@
 ---
 name: tulipes-env-variable
-description: Use when adding or changing any configuration value in a Tulipes app — API keys, connection strings, feature toggles, limits — or when tempted to read process.env. Covers meta.variables.json, the resolution precedence and typed reads.
+description: Use when adding or changing any configuration value in a Tulipes app — API keys, connection strings, feature toggles, limits — or when tempted to read process.env. Covers the split between environment variables (tulipes.env in package.json) and settings (the module.config.ts schema), the resolution precedence and typed reads.
 ---
 
 # Adding a configuration value
 
-**Never read `process.env` directly.** Every value is declared by exactly
-one module and read through the typed store. An undeclared read throws, so
-a typo can never reach production as `undefined`.
+**First decide which of two things it is.** An *environment variable* is
+what the process needs before the database answers — a connection string,
+the port, where logs go — or a secret. Everything else is a *setting*:
+declared with a default in the module's `module.config.ts` schema, stored
+in the settings store, editable by an operator at runtime without a
+restart, read at `ctx.config.<module>`:
+
+```ts
+// modules/billing/module.config.ts — the file's only export
+import { defineConfig } from "@tulipes/core/config";
+import { z } from "zod/v4";
+
+export default defineConfig({
+  schema: z.object({
+    trialDays: z.number().int().positive().default(14).describe("Free trial length"),
+    // a field the process cannot apply without a restart:
+    workers: z.number().int().positive().default(2).meta({ restart: true }),
+  }),
+});
+```
+
+Every field needs a default, secrets are refused, and `pnpm sync` types
+`ctx.config.billing.trialDays` as `number`. The rest of this guide is the
+environment variable.
+
+**Never read `process.env` directly.** Every variable is declared by
+exactly one module and read through the typed store. An undeclared read
+throws, so a typo can never reach production as `undefined`.
 
 ## Steps
 
 1. Choose the owning module. Infra shared by everything (`PORT`,
    `MONGO_URI`, `REDIS_URL`) belongs to the sys `core` module; anything
    feature-specific belongs to that feature's module.
-2. Declare it in that module's `meta.variables.json`:
+2. Declare it under `tulipes.env` in that module's `package.json`:
 
 ```json
 {
-  "variables": [
-    {
-      "name": "STRIPE_API_KEY",
-      "type": "secret",
-      "group": "billing",
-      "required": true,
-      "description": "Server-side Stripe key"
-    },
-    {
-      "name": "BILLING_TRIAL_DAYS",
-      "type": "number",
-      "group": "billing",
-      "description": "Free trial length",
-      "default": 14
-    }
-  ]
+  "name": "@app/billing",
+  "tulipes": {
+    "env": [
+        {
+          "name": "STRIPE_API_KEY",
+          "type": "secret",
+          "group": "billing",
+          "required": true,
+          "description": "Server-side Stripe key"
+        },
+        {
+          "name": "BILLING_TRIAL_DAYS",
+          "type": "number",
+          "group": "billing",
+          "description": "Free trial length",
+          "default": 14
+        }
+    ]
+  }
 }
 ```
 
 3. Add a value to `.envs/.env.development` for anything `required`.
-4. `yarn sync` — regenerates `types/config.d.ts` (so the read is typed)
+4. `pnpm sync` — regenerates `types/tulipes.d.ts` (so the read is typed)
    and `.env.example` (so deployments know what to set).
 5. Read it: `Environment.get("BILLING_TRIAL_DAYS")` → typed `number`.
 
@@ -65,14 +93,14 @@ values always win, which is why deployments need no file.
 
 - Value shared by several modules but the same everywhere (pagination
   limits, body size) → `config/app.config.ts`, not a variable.
-- Value used by one module and never changed per deployment → that
-  module's `module.config.ts`.
+- Any value an operator may want to change at runtime → a setting in that
+  module's `module.config.ts` schema (above), not a variable.
 
 ## Gotchas
 
 - `Environment.get()` on an undeclared name **throws**. If you added the
-  entry and still get the error, you did not run `yarn sync`, or you
-  edited a different module's meta file than the one you are reading from.
+  entry and still get the error, you did not run `pnpm sync`, or you
+  edited a different module's manifest than the one you are reading from.
 - `APP_ENV` (not `NODE_ENV`) selects the env file.
 - A missing `required` variable is not a runtime surprise — the boot
   aborts and lists every missing variable at once.

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

@@ -49,8 +49,15 @@ Read it anywhere the context reaches:
 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`.
+Run `pnpm sync` after adding a model: it records the model's name and file
+in `types/tulipes.d.ts`, so `models.get("Invoice")` is typed from the
+schema above (its fields, methods and statics) and a name that no model
+file declares does not compile. The name must be a string literal in the
+file for that; a computed name stays reachable only through
+`models.get<T>(name)`, the caller-side generic, which also serves code that
+builds names at runtime. `models.get()` throws on an unregistered name
+(listing what does exist), so a typo in dynamic code still fails at the
+call site instead of returning `undefined`.
 
 ## Requirements
 
@@ -97,8 +104,8 @@ is all the task wanted.
 
 - 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
+  the sys core module's `module.config.ts` — declaration time (phase 4),
+  before models compile in phase 5. 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

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

@@ -15,18 +15,19 @@ touching anything else.
   (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
+  models of its own — export it from `modules/core/lib/index.ts` (what its
+  `package.json` "exports" points at) 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.
+1. Scaffold: `pnpm tulipes new module billing`. It creates every
+   contract — package.json (scope detected from siblings), a settings
+   declaration, ACL, helper, a controller class, a plain routes function
+   declaring a RAI, model, a bootstrap that may return its cleanup, queue and
+   socket. Delete the ones this feature does not need. The module root holds
+   only `package.json`, `module.config.ts` and `module.acl.ts`; everything
+   else has a folder, and the boot refuses a stray root file.
 2. Set ordering in `modules/billing/package.json`:
 
 ```json
@@ -37,13 +38,13 @@ touching anything else.
 }
 ```
 
-3. `yarn install` — the module is a workspace, so the package manager must
+3. `pnpm 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.
+5. `pnpm sync && pnpm dev` — the banner must list the module.
 
 ## The manifest key
 

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

@@ -14,11 +14,15 @@ consumer. Never duplicate the definition.
 
 ```ts
 import type { Ctx } from "@tulipes/core/boot";
-import type { QueueRegistry } from "@tulipes/bullmq";
+import type { JobSchemas, QueueRegistry } from "@tulipes/bullmq";
+import { z } from "zod/v4";
 
-export default function invoiceQueues({ models }: Ctx, queues: QueueRegistry): void {
-  queues.define("billing.send-invoice");
+// The declaration: defines the queue, validates every add(), types both sides.
+export const jobs = {
+  "billing.send-invoice": z.object({ invoiceId: z.string() }),
+} satisfies JobSchemas;
 
+export default function invoiceQueues({ models }: Ctx, queues: QueueRegistry): void {
   queues.process("billing.send-invoice", async (job) => {
     const invoice = await models!.get("Invoice").findById(job.data.invoiceId);
     // …do the slow thing here…
@@ -33,7 +37,16 @@ Produce from anywhere with the context:
 await queues!.add("billing.send-invoice", "send", { invoiceId: invoice.id });
 ```
 
-Run a consumer with `yarn worker`. Without it, jobs pile up in Redis and
+Run `pnpm sync` after adding a queue: it records the `jobs` export in
+`types/tulipes.d.ts`, so the payload above and `job.data` in the processor
+are both typed from the schema, and a queue name no file declares does not
+compile. At runtime `add()` parses the payload with the schema — defaults
+applied, a bad payload refused at the producer rather than in the worker.
+A queue that needs options (`defaultJobOptions`, a prefix) calls
+`queues.define(name, options)` as well; a queue without a schema is defined
+that way alone and takes any payload.
+
+Run a consumer with `pnpm worker`. Without it, jobs pile up in Redis and
 nothing processes them — that is the correct behaviour, not a bug.
 
 ## Rules
@@ -42,8 +55,9 @@ nothing processes them — that is the correct behaviour, not a bug.
   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.
+- A processor registered for a queue nobody defined is a boot error; list
+  it in `jobs` or call `define()` in the same file. One schema per queue:
+  a second module declaring one is a boot error naming the first.
 - 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