@tulipes/cli 0.2.0 → 0.3.0-rc.2

package/templates/app/modules/users/controllers/{users.controllers.ts → bo.users.controllers.ts}

@@ -4,42 +4,18 @@ import type { Ctx } from "@tulipes/core/boot";
 import { HttpError } from "@tulipes/core/http";
 
 /**
- * One class per controller, holding the context. Each method returns a
- * handler, so the routes file stays a table of contents.
- *
- * Every response goes through `res.respond`, which wraps the payload in
- * the app's envelope. Failures are thrown rather than responded — the
- * framework's terminal handler builds the same envelope from them — so a
- * handler only ever writes the happy path.
- *
- * Thrown messages are i18n KEYS: the handler translates them in this
- * module's namespace and derives the error code from the key, so
- * "notFound" becomes NOT_FOUND with a translated message.
+ * The users back office — the users:bo:* endpoints, granted to admin
+ * through its users:* grant. Same shape as the web controller beside it:
+ * one class holding the context, one handler per method, failures thrown
+ * as i18n keys.
  */
-export class UsersController {
+export class BoUsersController {
   readonly #ctx: Ctx;
 
   constructor(ctx: Ctx) {
     this.#ctx = ctx;
   }
 
-  list(): RequestHandler {
-    return async (req: Request, res: Response) => {
-      // ?page and ?per_page, already clamped by config.pagination.
-      const { per_page, skip } = req.page;
-      const User = this.#ctx.models!.get("User");
-
-      const [users, total_items] = await Promise.all([
-        User.find().select("email role -_id").skip(skip).limit(per_page).lean(),
-        User.countDocuments(),
-      ]);
-
-      // Passing total_items is what marks this a page: respond fills in
-      // page, per_page and total_pages from the request and the count.
-      res.respond({ data: users, meta: { total_items } });
-    };
-  }
-
   /** Soft delete: the row stays in mongo but leaves every ordinary query. */
   softDelete(): RequestHandler {
     return async (req: Request, res: Response) => {
@@ -84,30 +60,4 @@ export class UsersController {
       res.respond({ status: 201, data: { email, welcome_queued: true } });
     };
   }
-
-  ping(): RequestHandler {
-    return (req: Request, res: Response) => {
-      res.respond({
-        data: {
-          module: "users",
-          locale: req.locale,
-          max_sessions: this.#ctx.config.users?.maxSessions,
-        },
-      });
-    };
-  }
-
-  /** Demonstrates HttpError — the framework renders it into the envelope. */
-  demoMissing(): RequestHandler {
-    return async () => {
-      throw new HttpError(404, "notFound", { details: { hint: "demo endpoint" } });
-    };
-  }
-
-  /** Demonstrates an unexpected error: anonymous 500 outside development. */
-  demoBoom(): RequestHandler {
-    return async () => {
-      throw new Error("secret internals that must not leak in production");
-    };
-  }
 }

package/templates/{overlays/no-queues/modules/users/controllers/users.controllers.ts → app/modules/users/controllers/web.users.controllers.ts}

@@ -1,11 +1,12 @@
-import { forgetUser } from "@app/auth";
 import type { Request, RequestHandler, Response } from "express";
 import type { Ctx } from "@tulipes/core/boot";
 import { HttpError } from "@tulipes/core/http";
 
 /**
  * One class per controller, holding the context. Each method returns a
- * handler, so the routes file stays a table of contents.
+ * handler, so the routes file stays a table of contents. The class is
+ * named after its file — web.users.controllers.ts, WebUsersController —
+ * and serves the users:web:* endpoints; the back office has its own.
  *
  * Every response goes through `res.respond`, which wraps the payload in
  * the app's envelope. Failures are thrown rather than responded — the
@@ -16,7 +17,7 @@ import { HttpError } from "@tulipes/core/http";
  * module's namespace and derives the error code from the key, so
  * "notFound" becomes NOT_FOUND with a translated message.
  */
-export class UsersController {
+export class WebUsersController {
   readonly #ctx: Ctx;
 
   constructor(ctx: Ctx) {
@@ -40,45 +41,6 @@ export class UsersController {
     };
   }
 
-  /** Soft delete: the row stays in mongo but leaves every ordinary query. */
-  softDelete(): RequestHandler {
-    return async (req: Request, res: Response) => {
-      const user = await this.#ctx.models!.get("User").findOne({ email: req.params.email });
-      if (!user) throw new HttpError(404, "notFound");
-
-      // The account leaves every query, so its sessions resolve to nobody on
-      // the cold path; the cached identities would not know, so they go too.
-      await forgetUser(this.#ctx, String(user._id));
-      await (user as unknown as { softDelete(): Promise<unknown> }).softDelete();
-      res.respond({ data: { email: req.params.email, soft_deleted: true } });
-    };
-  }
-
-  listDeleted(): RequestHandler {
-    return async (_req: Request, res: Response) => {
-      const deleted = await this.#ctx.models!
-        .get("User")
-        .find({ is_deleted: true })
-        .setOptions({ withDeleted: true } as Record<string, unknown>)
-        .select("email role -_id")
-        .lean();
-
-      res.respond({ data: deleted });
-    };
-  }
-
-  create(): RequestHandler {
-    return async (req: Request, res: Response) => {
-      const { email } = (req.body ?? {}) as { email?: string };
-      // `field` is what puts this against the input in the envelope.
-      if (!email) throw new HttpError(422, "emailRequired", { field: "email" });
-
-      await this.#ctx.models!.get("User").create({ email });
-
-      res.respond({ status: 201, data: { email } });
-    };
-  }
-
   ping(): RequestHandler {
     return (req: Request, res: Response) => {
       res.respond({

package/templates/app/modules/users/module.acl.ts

@@ -1,10 +1,10 @@
 import type { AclBuilder } from "@tulipes/core/acl";
 
 export default function usersAcl(acl: AclBuilder): void {
-  acl.allow("user", "users:read", "users:ping");
+  acl.allow("user", "users:web:list", "users:web:ping");
   // The demo endpoints are open so the error-handling examples stay
   // curl-able without a token.
-  acl.allow("guest", "users:demo-missing", "users:demo-boom", "users:ping");
-  // Everything else — create, delete, read-deleted — stays with admin,
-  // which already holds "*".
+  acl.allow("guest", "users:web:demo:*", "users:web:ping");
+  // The back office — users:bo:create, :delete, :list:deleted — stays with
+  // admin and sysadmin, whose users:* grant in the auth module covers it.
 }

package/templates/app/modules/users/queues/users.queues.ts

@@ -16,7 +16,7 @@ export const jobs = {
 export default function usersQueues(ctx: Ctx, queues: QueueRegistry): void {
   // The same logger the backend uses. In the worker process it writes
   // to app-worker.log, so the two processes never share a file.
-  const log = moduleLogger(ctx.Environment, "users", ctx.mode);
+  const log = moduleLogger(ctx, "users");
 
   queues.process("users.welcome", async (job) => {
     // No request here to negotiate a locale from, so the one the caller

package/templates/app/modules/users/routes/bo.users.routes.ts

@@ -0,0 +1,39 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+
+import { BoUsersController } from "../controllers/bo.users.controllers.ts";
+import { createBody, emailParam } from "../schemas/users.schemas.ts";
+
+/**
+ * The users back office: every id is users:bo:…, so `users:bo:*` grants
+ * all of it and `tulipes routes --scope bo` lists it. Mounted under /users
+ * like the web routes beside it.
+ */
+export default function boUsersRoutes(ctx: BackendCtx): void {
+  const { rai, routes } = ctx;
+  const router = Router();
+  const users = new BoUsersController(ctx);
+
+  router.post("/", rai({
+      id: "users:bo:create",
+      status: 201,
+      name: "Create a user",
+      description: "Adds the account and queues its welcome email",
+      body: createBody,
+    }), users.create());
+
+  router.get("/deleted", rai({
+      id: "users:bo:list:deleted",
+      name: "List soft-deleted users",
+    }), users.listDeleted());
+
+  router.delete("/:email", rai({
+      id: "users:bo:delete",
+      name: "Soft-delete a user",
+      description: "Flags the account; ordinary queries stop returning it",
+      params: emailParam,
+    }), users.softDelete());
+
+  // Deliberately outside the API prefix, to show a mount of its own.
+  routes.mount(router, "/users");
+}

package/templates/app/modules/users/routes/web.users.routes.ts

@@ -0,0 +1,45 @@
+import { Router } from "express";
+import type { BackendCtx } from "@tulipes/core/boot";
+import { z } from "zod/v4";
+
+import { WebUsersController } from "../controllers/web.users.controllers.ts";
+import { listQuery, userShape } from "../schemas/users.schemas.ts";
+
+/**
+ * The users endpoints a signed-in client calls. The back office's sit in
+ * bo.users.routes.ts beside this file, under the same mount: one file per
+ * scope, named scope-first.
+ */
+export default function webUsersRoutes(ctx: BackendCtx): void {
+  const { rai, routes } = ctx;
+  const router = Router();
+  const users = new WebUsersController(ctx);
+
+  router.get("/", rai({
+      id: "users:web:list",
+      name: "List users",
+      description: "Page through accounts, clamped by the shared bounds",
+      // Validated on the way in, and described on the way out: one
+      // declaration, so the spec cannot drift from what is enforced.
+      query: listQuery,
+      returns: z.array(userShape),
+    }), users.list());
+
+  router.get("/ping", rai({
+      id: "users:web:ping",
+      name: "Users module status",
+    }), users.ping());
+
+  router.get("/missing", rai({
+      id: "users:web:demo:missing",
+      name: "HttpError demo",
+    }), users.demoMissing());
+
+  router.get("/boom", rai({
+      id: "users:web:demo:boom",
+      name: "Unhandled error demo",
+    }), users.demoBoom());
+
+  // Deliberately outside the API prefix, to show a mount of its own.
+  routes.mount(router, "/users");
+}

package/templates/app/nginx/production.conf

@@ -18,7 +18,7 @@ server {
         root /var/www/html;
     }
 
-    # Keep in step with the BODY_LIMIT variable. If nginx is stricter,
+    # Keep in step with the security.bodyLimit setting. If nginx is stricter,
     # oversized requests die here as an nginx HTML page instead of the
     # API's JSON 413.
     client_max_body_size 1m;

package/templates/app/scripts/deploy-nginx.ts

@@ -40,9 +40,10 @@ try {
 }
 
 async function deploy(): Promise<void> {
-  const { appEnv } = handle.env;
+  const { appEnv } = handle.ctx;
   const domain = String(handle.ctx.config.core?.publicDomain ?? "localhost").trim();
-  const port = Number(handle.env.get("PORT"));
+  // What app.config wired from PORT — the same port the backend listens on.
+  const port = Number(handle.ctx.config.server?.port ?? 3000);
 
   const templatePath = join(rootDir, "nginx", `${appEnv}.conf`);
   if (!existsSync(templatePath)) {

package/templates/app/tests/support.ts

@@ -2,9 +2,10 @@ import { randomBytes } from "node:crypto";
 
 /**
  * What every module test boots the app with. The services are dedicated:
- * the suite writes users, sessions and settings. The variables are the
- * eleven the app declares; everything else the request pipeline needs is a
- * setting, written after the boot the way an operator writes it.
+ * the suite writes users, sessions and settings. The variables are the ones
+ * the core and auth modules declare, by their env names; everything else the
+ * request pipeline needs is a setting, written after the boot the way an
+ * operator writes it.
  */
 export function testEnv(): Record<string, string> {
   if (!process.env.TEST_MONGO_URI || !process.env.TEST_REDIS_URL) {

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

@@ -27,13 +27,13 @@ export default defineAgent({
   summary: "Greets callers and counts how often each greeting is used.",
   actions: [
     action({
-      id: "hello:list-greetings",
+      id: "hello:web:greetings",
       description: "The stored greetings, with how often each was used",
       readOnly: true,
       handler: async (ctx) => (await findGreetings(ctx))[0],
     }),
     action({
-      id: "hello:reset-counts",
+      id: "hello:bo:greetings:reset",
       description: "Reset the usage counter of every greeting to zero",
       input: z.object({ confirm: z.literal(true) }),
       handler: async (ctx) => {
@@ -50,7 +50,9 @@ no service or `.env` needed; `--role admin` shows what one role gets.
 
 ## Rules
 
-- **An action's id is a permission like any route's.** The ACL decides on
+- **An action's id is a RAI like any route's**, `module:scope:resource[:extra]`:
+  the scope says who it is for (`hello:bo:greetings:reset` is a back-office
+  action). 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`).
@@ -65,7 +67,7 @@ no service or `.env` needed; `--role admin` shows what one role gets.
   text the model sees before choosing the tool. Say what the tool does, what
   it changes and what it returns; keep `readOnly: true` honest.
 - **One `agent/*.agent.ts` per module.** Tool names come from the id
-  (`hello:reset-counts` → `hello_reset-counts`); a name two modules claim
+  (`hello:bo:greetings:reset` → `hello_bo_greetings_reset`); a name two modules claim
   is a boot error.
 
 ## An agent inside the app

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

@@ -26,13 +26,16 @@ problems the report has not reached yet.
 |---|---|---|
 | `environment` | `required variable "X" has no value` | Declared `required` but nothing supplies it. Add it to `.envs/.env.<APP_ENV>`, or give the spec a `default`. |
 | `environment` | `"abc" is not a number` / `not one of: …` | Value fails its declared `type`/`enum`. Fix the value or the spec. |
-| `environment` | `variable "X" is already declared by module "y"` | Two modules declare the same name. Delete the duplicate; read the other module's variable instead. |
+| `environment` | `variable "X" is already declared by module "y"` | Two modules declare the same `key`. Delete the duplicate; read the other module's config instead. |
+| `environment` | `config.x.name is both a setting and an environment value` | A `tulipes.env` name is also a field of that module's settings schema. Rename one; they share the namespace. |
+| `environment` | `tulipes.env is an object keyed by config name since 0.12` | The 0.11 array form. Run `tulipes migrate 0.12`, which rewrites it and the reads. |
 | `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/`. |
 | `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()`. |
+| `modules` | `tulipes.offline is gone` / `meta.variables.json … moved to package.json` | The 0.10 forms. Delete the flag; run `tulipes migrate 0.11` then `0.12` for the variables. |
+| `routes` | `routes function threw: ctx.models is not available during inspection` / `config.x.name is an environment value, not available during inspection` | A routes file or a controller constructor touched infrastructure or an environment value while building. Move the read into the handler, or build the middleware with `lazy()`. |
+| `config` | `app.config returns "x", which is the config namespace of module "x"` | `config/app.config.ts` seeded a key named after a module; that namespace holds the module's settings and environment values. Rename the key. |
 | `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. |
@@ -43,13 +46,13 @@ problems the report has not reached yet.
 | `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. |
-| `providers` | `provider "bullmq" is selected but "REDIS_URL" is not declared/set` | Add the variable to the sys `core` module's meta file and set it. |
+| `providers` | `provider "bullmq" is selected but config.bullmq.redisUrl is not set` | Wire it in `config/app.config.ts` — `bullmq: { redisUrl: env.core.redisUrl }` — from a variable the sys `core` module declares, and set that variable. |
 | `providers` | `"@tulipes/core/queues" no longer contains the BullMQ provider` | Install `@tulipes/bullmq`, declare it, and import `QueueRegistry`/`QueuesFn` from it. |
 | `providers` | `[x] requires capability "sockets" … declares no provider for it` | A module has a `sockets/` file (or `requires: ["sockets"]`) but the app's `package.json` has no `"tulipes": { "providers": { "sockets": "@tulipes/socket.io" } }`. Add that line. |
 | `providers` | `"@tulipes/core/sockets" no longer contains the Socket.IO provider` | Install `@tulipes/socket.io`, declare it, and import `SocketRegistry`/`SocketsFn` from it. |
 | `providers` | `provider "socket.io" failed to attach to the HTTP server` | The transport could not bind to the server core created; the message carries the driver's reason. |
-| `providers` | `provider "mongoose" is selected but "MONGO_URI" is not declared/set` | Add the variable to the sys `core` module's meta file and set it. |
-| `providers` | `database connection failed` | Mongo unreachable or `MONGO_URI` wrong. Check the service is running. |
+| `providers` | `provider "mongoose" is selected but config.mongoose.uri is not set` | Wire it in `config/app.config.ts` — `mongoose: { uri: env.core.mongodbUri }` (or the host, user, pass and dbName parts) — from variables the sys `core` module declares, and set them. |
+| `providers` | `database connection failed (config.mongoose.uri)` | Mongo unreachable or the URI wrong. Check the service is running and what `pnpm check` resolved. |
 | `providers` | `package.json "tulipes" key: providers — Unrecognized key` | Typo in the capability name; only `models` exists. |
 | `providers` | `queue name … is invalid` | Queue names use `.`, not `:`. |
 | `routes` | `must default-export a routes function` | Missing `export default` in a `*.routes.ts`. |
@@ -72,7 +75,10 @@ runs, check in this order:
 
 ## Other symptoms
 
-- **Types are `unknown` or a new variable is not typed** → run `pnpm sync`.
+- **Types are `unknown` or a new environment value is not typed** → run `pnpm sync`.
+- **`console.log(ctx.config.core)` does not show an environment value** →
+  by design; they are non-enumerable so a secret never reaches a log or a
+  response. `pnpm check` shows them.
 - **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

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

@@ -38,7 +38,9 @@ object is replaced in place when a write lands.
   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`
+  `secret`; a secret is an environment value, declared in the module's
+  package.json and read beside the settings at `ctx.config.<module>`, never
+  listed. → 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
@@ -57,12 +59,12 @@ object is replaced in place when a write lands.
 
 | | |
 |---|---|
-| `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` | every module in load order: manifest, environment values (config name, variable, type, source — 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
+`config:bo:read` and `config:bo:describe` are granted to `admin` and `sysadmin`;
+`config:bo: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

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

@@ -9,14 +9,25 @@ Two files: a controller class holding the work, and a shared declaration file wi
 it up. Every route declares a RAI — a Resource Access Identifier — and the
 app refuses to boot if one is missing.
 
-`modules/billing/controllers/billing.controllers.ts`:
+Name both files **scope-first**: the scope is the surface the endpoint
+serves (`web`, `bo`, `mobile`), and it is also the second segment of the
+endpoint's RAI. A convention, not a rule core checks, but it is what lets
+anyone find the back office of a module by looking at its folder.
+
+```
+routes/{scope}.{module}[.{extra}].routes.ts              web.billing.routes.ts, bo.billing.refunds.routes.ts
+controllers/{scope}.{module}[.{extra}].controllers.ts    web.billing.controllers.ts → WebBillingController
+routes/{scope}/{module}[.{extra}].routes.ts              several files for one scope go in a folder
+```
+
+`modules/billing/controllers/web.billing.controllers.ts`:
 
 ```ts
 import type { Request, RequestHandler, Response } from "express";
 import type { Ctx } from "@tulipes/core/boot";
 import { HttpError } from "@tulipes/core/http";
 
-export class BillingController {
+export class WebBillingController {
   constructor(private readonly ctx: Ctx) {}
 
   show(): RequestHandler {
@@ -33,18 +44,18 @@ Each method **returns** a handler rather than being one, so the routes file
 reads as a table of contents and the class can keep private helpers beside
 the handlers that use them without threading ctx through every signature.
 
-`modules/billing/routes/billing.routes.ts`:
+`modules/billing/routes/web.billing.routes.ts`:
 
 ```ts
 import { Router } from "express";
 import type { BackendCtx } from "@tulipes/core/boot";
 
-import { BillingController } from "../controllers/billing.controllers.js";
+import { WebBillingController } from "../controllers/web.billing.controllers.ts";
 
 export default function billingRoutes(ctx: BackendCtx): Router {
   const router = Router();
-  const billing = new BillingController(ctx);
-  router.get("/:id", ctx.rai({ id: "billing:read", name: "Read an invoice" }), billing.show());
+  const billing = new WebBillingController(ctx);
+  router.get("/:id", ctx.rai({ id: "billing:web:invoice", name: "Read an invoice" }), billing.show());
   return router;                          // mounted under config.api.prefix
 }
 ```
@@ -57,15 +68,19 @@ child for inherited parameters). A file that only mounts global middleware
 on `ctx.app` returns nothing.
 
 **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:
+and `tulipes spec` build every router with nothing acquired: an environment
+value (`ctx.config.<module>.<name>`) throws when read, 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 an environment value 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")) })));
+import { appCache, lazy } from "@app/core";
+app.use(lazy(() => {
+  const cache = appCache(ctx); // opens Redis from config.core.redisUrl
+  return (req, res, next) => { /* … */ next(); };
+}));
 ```
 
 Use router.use for shared middleware, router.param for parameter callbacks, and
@@ -76,7 +91,10 @@ changes run the app tests, `tulipes routes` and `pnpm spec`; inspect generated d
 
 ## The RAI is not optional
 
-`id` names a resource and an access to it, and **is** the ACL permission.
+`id` is `module:scope:resource[:extra]` — `billing:web:invoice`,
+`billing:bo:invoice:refund` — and **is** the ACL permission. Leaving the
+scope out (`billing:read`) is a type error and a boot error. → skill
+`tulipes-permissions` for the format and the grants.
 One declaration identifies the endpoint, gates it, marks the route as
 declared, and binds `req.t` to the declaring module's i18n namespace —
 which is why the message above needs no namespace of its own. → skill
@@ -94,7 +112,8 @@ 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` lists every declared endpoint with the roles that reach it,
-without a service, a secret or a `.env`.
+without a service, a secret or a `.env`; `tulipes routes --scope bo` lists one
+surface.
 
 A route is never a tool: what the module offers to agents is declared apart,
 in `agent/<module>.agent.ts`, and shares the route's logic through `helpers/`.