@tulipes/cli 0.2.0-rc.2 → 0.3.0-rc.2

package/templates/app/modules/settings/tests/settings.test.ts

@@ -1,4 +1,8 @@
 import { randomBytes } from "node:crypto";
+import { mkdtempSync } from "node:fs";
+import { readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod/v4";
 import { afterAll, beforeAll, expect, test, vi } from "vitest";
@@ -8,7 +12,15 @@ import { useTestApp } from "@tulipes/testing";
 import { testEnv, testSettings } from "../../../tests/support.ts";
 
 const rootDir = fileURLToPath(new URL("../../../", import.meta.url));
-const app = useTestApp({ rootDir, env: testEnv(), settings: testSettings() }, { beforeAll, afterAll });
+
+/**
+ * Where this boot's logger writes and the stream reads: environment values
+ * are bound once at boot, so the file logging the stream needs is on for
+ * the whole file, into a directory the suite owns and empties per test.
+ */
+const logDir = mkdtempSync(join(tmpdir(), "tulipes-log-http-"));
+const app = useTestApp({ rootDir, env: { ...testEnv(), LOG_FILE: "true", LOG_DIR: logDir }, settings: testSettings() }, { beforeAll, afterAll });
+afterAll(() => rm(logDir, { recursive: true, force: true }));
 
 
 const tokens = z.object({
@@ -59,30 +71,16 @@ async function sysadmin() {
   return user;
 }
 
+/** `run` sees the log directory empty: one test's files never serve another's stream. */
 async function logFiles(run: (dir: string) => Promise<void>) {
-  const { mkdtemp, rm } = await import("node:fs/promises");
-  const { tmpdir } = await import("node:os");
-  const { join } = await import("node:path");
-  const dir = await mkdtemp(join(tmpdir(), "tulipes-log-http-"));
-  const env = app.handle.ctx.Environment;
-
-  const previous = {
-    file: env.get("LOG_FILE"),
-    dir: env.get("LOG_DIR"),
+  const empty = async () => {
+    for (const entry of await readdir(logDir)) await rm(join(logDir, entry), { recursive: true, force: true });
   };
-
-  env.store.set("LOG_FILE", true);
-
-  env.store.set("LOG_DIR", dir);
-
+  await empty();
   try {
-    await run(dir);
+    await run(logDir);
   } finally {
-    env.store.set("LOG_FILE", previous.file);
-
-    env.store.set("LOG_DIR", previous.dir);
-
-    await rm(dir, { recursive: true, force: true });
+    await empty();
   }
 }
 
@@ -378,10 +376,8 @@ test("shutdown drains settings streams and a later boot owns fresh stream admiss
       });
 
       try {
-        next.env.store.set("LOG_FILE", true);
-
-        next.env.store.set("LOG_DIR", dir);
-
+        // LOG_FILE and LOG_DIR are still set on the process, so this boot
+        // reads the same directory.
         const address = next.server!.address();
 
         if (!address || typeof address === "string")

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

@@ -1,16 +1,14 @@
 ---
 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.
+description: Use when a Tulipes module should offer something to AI agents — declaring an action, describing the module, building an agent inside the app from the other modules' actions, or wiring the app to Claude Code through MCP. Covers agent/*.agent.ts, ctx.agent, the manifest, the agent door and tulipes-mcp.
 ---
 
-# Exposing a module to agents
+# Offering a module's actions 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.
+Routes are the API. What a module offers to agents — and to an agent
+module inside the same app — is a separate, explicit list: its **actions**,
+declared in `agent/<module>.agent.ts`. Nothing is derived from the routes,
+and a module with no `agent/` file offers nothing.
 
 The agent surface and `@tulipes/mcp` are **experimental** in 0.11: they may
 change in any release without a deprecation period. Check `MIGRATING.md`
@@ -23,19 +21,22 @@ import { action, defineAgent } from "@tulipes/core/agent";
 import { requireModels } from "@tulipes/core/boot";
 import { z } from "zod/v4";
 
+import { findGreetings } from "../helpers/greetings.ts";
+
 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.
+  actions: [
     action({
-      id: "hello:reset-counts",
+      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:bo:greetings:reset",
       description: "Reset the usage counter of every greeting to zero",
       input: z.object({ confirm: z.literal(true) }),
-      handler: async (ctx, input, actor) => {
+      handler: async (ctx) => {
         const { modifiedCount } = await requireModels(ctx).get("Greeting").updateMany({}, { times_used: 0 });
         return { reset: modifiedCount };
       },
@@ -49,33 +50,47 @@ 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
+- **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`).
-  Grant it in `module.acl.ts`; a wildcard such as `hello:*` already covers it.
+  Grant it in `module.acl.ts`; a wildcard such as `hello:*` already covers
+  it. An action that does what a route does may share the route's id, so
+  one grant covers both.
+- **Logic lives in `helpers/`, called from both.** A route controller and
+  an action call the same helper; a route never calls an action and an
+  action never calls a route. An action that grows a second step is a
+  controller in disguise.
 - **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.
+- **One `agent/*.agent.ts` per module.** Tool names come from the id
+  (`hello:bo:greetings:reset` → `hello_bo_greetings_reset`); a name two modules claim
+  is a boot error.
+
+## An agent inside the app
+
+`ctx.agent` exists in every process — backend, worker, script — once the
+ACL is loaded. An agent module runs a model against the other modules'
+actions without any HTTP:
+
+```ts
+const { tools } = ctx.agent.manifest(actor.role);   // name, description, input_schema: a tool definition each
+const result = await ctx.agent.invoke(name, input, actor); // ACL, then schema, then the handler
+```
+
+A long run belongs in a queue job (`queues/`), where `ctx.agent` is the
+same registry.
 
 ## 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:
+For agents outside the process, 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

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