@tulipes/cli 0.2.0 → 0.3.0-rc.2

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

@@ -1,16 +1,15 @@
 ---
 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 the split between environment variables (tulipes.env in package.json) and settings (the module.config.ts schema), 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 values (tulipes.env in package.json, read at ctx.config.<module>.<name>) and settings (the module.config.ts schema), the resolution precedence and what the console may show.
 ---
 
 # Adding a configuration value
 
-**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>`:
+**First decide which of two things it is.** An *environment value* 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:
 
 ```ts
 // modules/billing/module.config.ts — the file's only export
@@ -28,39 +27,44 @@ export default defineConfig({
 
 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.
+environment value.
 
-**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`.
+**Both land in the same place.** A module's settings and its environment
+values share its namespace, `ctx.config.<module>`: `config.billing.trialDays`
+is a setting an operator edits, `config.billing.stripeApiKey` is an
+environment value the deployment sets. Code reads them the same way; the
+console (`GET /config`) shows the first with its value and the second by
+name, type and source only. **Never read `process.env` directly.**
 
 ## 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 under `tulipes.env` in that module's `package.json`:
+2. Declare it under `tulipes.env` in that module's `package.json`, keyed by
+   the **config name** you will read it as, with `key` naming the variable
+   the deployment sets:
 
 ```json
 {
   "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
-        }
-    ]
+    "env": {
+      "stripeApiKey": {
+        "key": "STRIPE_API_KEY",
+        "type": "secret",
+        "group": "billing",
+        "required": true,
+        "description": "Server-side Stripe key"
+      },
+      "webhookTolerance": {
+        "key": "BILLING_WEBHOOK_TOLERANCE",
+        "type": "number",
+        "group": "billing",
+        "description": "Seconds a webhook signature may be old",
+        "default": 300
+      }
+    }
   }
 }
 ```
@@ -68,21 +72,41 @@ throws, so a typo can never reach production as `undefined`.
 3. Add a value to `.envs/.env.development` for anything `required`.
 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`.
+5. Read it where it is used: `ctx.config.billing.stripeApiKey`, typed
+   `string`; a value with no default and not `required` is typed
+   `| undefined`.
+
+The framework and the providers read fixed keys that `config/app.config.ts`
+wires from these values — `server.port`, `mongoose.uri`, `bullmq.redisUrl`.
+A module's own values need no wiring.
 
 ## Field rules
 
 | Field | Rule |
 |---|---|
-| `name` | UPPER_SNAKE, and **globally unique** — two modules declaring the same name crash the boot. Do not re-declare a variable another module owns; just read it. |
+| name (the object key) | camelCase, like a settings field. Unique within the module, and not also a settings field — the boot refuses a name used by both. |
+| `key` | UPPER_SNAKE, and **unique across the app** — two modules declaring the same key crash the boot. Do not re-declare a variable another module owns; read that module's config. |
 | `type` | `string` · `number` · `boolean` · `enum` · `url` · `secret`. Values are coerced (`"14"` → `14`) and validated. |
 | `enum` | Required with `type: "enum"`. Generates a literal union type. |
 | `required` | No value anywhere → boot crash. Mutually exclusive with `default`. |
 | `default` | Used when nothing supplies a value. Never put a real credential here. |
 | `group` | Free-form label; groups the variable in the generated `.env.example`. |
 
-Use `secret` for anything sensitive — those values are redacted in logs,
-reports and the startup banner.
+Use `secret` for anything sensitive: its value is withheld from `GET
+/config`, from `tulipes env:check` and from the startup banner.
+
+## How the values behave
+
+- **Read-only.** Assigning to `ctx.config.billing.stripeApiKey` throws. A
+  deployment value is not something code changes.
+- **Invisible to listings.** `{ ...ctx.config.billing }`, `JSON.stringify`,
+  `Object.keys` and `console.log` skip environment values — that is what
+  keeps a secret out of a response body, a log line and the settings
+  store. To see them, run `pnpm check` (`tulipes env:check`).
+- **Refused under inspection.** `tulipes routes` and `tulipes spec` boot
+  with nothing acquired; reading an environment value while *building* a
+  router throws, naming it. Read it inside the handler, or build the
+  middleware with `lazy()` from `@app/core`.
 
 ## Precedence
 
@@ -92,15 +116,16 @@ values always win, which is why deployments need no file.
 ## Where it does NOT go
 
 - Value shared by several modules but the same everywhere (pagination
-  limits, body size) → `config/app.config.ts`, not a variable.
+  limits, locales) → `config/app.config.ts`, not a variable.
 - 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 `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 read is `undefined` and you expected a value: you did not run
+  `pnpm sync` (the type would have told you), or the name is spelled
+  differently from the manifest, or the value is optional and nothing
+  supplied it.
+- `APP_ENV` (not `NODE_ENV`) selects the env file; read it as `ctx.appEnv`.
 - A missing `required` variable is not a runtime surprise — the boot
   aborts and lists every missing variable at once.

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

@@ -1,6 +1,6 @@
 ---
 name: tulipes-i18n
-description: Use when writing any user-facing string in a Tulipes app — an error message, a response body, an email subject — or when adding a locale, translating a module, or working out why an endpoint answers in the wrong language. Covers req.t, ctx.t, module namespaces and the missing-key files.
+description: Use when writing any user-facing string in a Tulipes app — an error message, a response body, an email subject — or when adding a locale, translating a module, or working out why an endpoint answers in the wrong language. Covers req.t, ctx.t, module namespaces, the missing-key files, and time zones (req.timezone, req.time, ctx.time).
 ---
 
 # Translating
@@ -96,3 +96,22 @@ served by `fr` unless `fr-CA.json` exists.
   default-locale file, aborts the boot — i18next would otherwise serve raw
   keys with nothing in the log to explain it.
 - A module with no `i18n/` folder is fine; it simply has nothing to say.
+
+## Time zones
+
+Dates are stored and returned as UTC; never convert them in a response
+body. A zone is how a date is *read*, and it is negotiated like the locale:
+`?tz=Europe/Paris`, then an `X-Timezone` header, then
+`config.timezone.default` (`config/app.config.ts`).
+
+```ts
+const since = req.time.startOfDay();              // the caller's midnight, as a UTC Date
+const label = req.time.format(order.created_at);  // in req.timezone and req.locale
+const at = req.time.toISO(new Date());            // "2026-10-13T15:00:00.000+01:00"
+```
+
+Without a request — a queue processor, an email to a user — read in the
+recipient's zone: `ctx.time.in(user.timezone, user.locale).format(date)`.
+Never call `getHours()`/`toLocaleString()` without a zone, and never build
+"today" from `new Date().setHours(0)`: both read the process zone, which is
+the app's default, not the caller's.

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

@@ -21,11 +21,12 @@ touching anything else.
 
 ## Steps
 
-1. Scaffold: `pnpm tulipes new module billing`. It creates every
+1. Scaffold: `pnpm tulipes new module billing` (add `--scope bo` for a
+   back-office module; the default is `web`). 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
+   declaring the RAI `billing:web:list`, 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`:
@@ -40,7 +41,11 @@ touching anything else.
 
 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.
+4. Put endpoints and shared middleware in native routes factories, named
+   scope-first: `routes/web.billing.routes.ts`, `routes/bo.billing.routes.ts`,
+   or `routes/web/billing.invoices.routes.ts` when one scope has several
+   files. Every id they declare is `billing:<scope>:<resource>[:<extra>]`.
+   → skill `tulipes-permissions`
    Add optional files as needed:
    `models/`, `queues/`, `sockets/`, `bootstrap/`, `module.acl.ts`,
    `i18n/` — the module is its own i18n namespace. → skill `tulipes-i18n`
@@ -50,7 +55,7 @@ touching anything else.
 
 | 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`. |
+| `tier` | `sys` loads before every `app` module. Use `sys` **only** for framework-level concerns: global middleware, roles, the infrastructure environment values. 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. |
 

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

@@ -1,49 +1,113 @@
 ---
 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.
+description: Use when adding roles or permissions to a Tulipes app, naming a RAI id, guarding an endpoint by role, making a route public, choosing a scope (bo, web, mobile), or deciding who may do what. Covers the module:scope:resource[:extra] format, module.acl.ts, wildcards, role descriptions and extras, and the guest role.
 ---
 
 # 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.
+## The RAI format
 
-`modules/auth/module.acl.ts` — the vocabulary:
+Every route and every agent action declares a RAI id, and that id **is**
+the permission. It always has this shape:
+
+```
+{module}:{scope}:{resource}[:{extra}]
+```
+
+| Segment | Required | What it is | Examples |
+|---|---|---|---|
+| module | yes | the declaring module's name, as its folder spells it | `users`, `user-profiles` |
+| scope | yes | the surface the endpoint serves | `bo`, `web`, `mobile` |
+| resource | yes | what is reached | `list`, `detail`, `profile` |
+| extra | no | a variant or sub-action of the resource | `delete`, `deleted`, `by-name` |
+
+```
+users:bo:list              the back office lists users
+users:mobile:profile       the mobile app reads the caller's profile
+users:bo:detail            the back office reads one user
+users:bo:detail:delete     ...and deletes it
+```
+
+Each segment is lowercase, starts with a letter, and may hold digits and
+hyphens. `users:read` (no scope), `Users:bo:list` and a fifth segment are
+refused: in the editor, because `id` is typed, and at boot with the route
+and module named.
+
+Scopes are the app's own vocabulary. This app uses `web` for what a
+signed-in client calls and `bo` for the back office; add `mobile` the day
+a mobile client needs endpoints of its own. Nothing declares a scope
+first. Keep the list short and spell it the same everywhere, because
+`tulipes routes --scope bo` and `tulipes spec --scope mobile` filter on it.
+
+## Roles are defined once, with what they mean
+
+Roles are **global** and defined by the `auth` module. A definition can
+carry a description and any other property the app wants to read back:
 
 ```ts
+// modules/auth/module.acl.ts
+declare module "@tulipes/core/acl" {
+  interface RoleMeta { level?: number }   // types the extra everywhere
+}
+
 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", "*");
+  acl
+    .defineRole("guest", { description: "Any request without a valid token", level: 0 })
+    .defineRole("user", { description: "A signed-in account", level: 1 })
+    .defineRole("admin", { description: "Runs the back office", level: 2 });
+
+  acl.allow("guest", "auth:web:login", "auth:web:register", "auth:web:refresh");
 }
 ```
 
-`modules/billing/module.acl.ts` — grants for this feature:
+Read a role back anywhere with `ctx.acl.role("admin")`: it returns
+`{ name, definedBy, description, level }`, frozen. `ctx.acl.describeRoles()`
+lists them all. `pnpm tulipes roles` prints each role with its
+description, extras and every grant it holds, and the OpenAPI document
+lists them under `x-tulipes-roles`.
+
+`RoleMeta` is optional. Undeclared extras are accepted and returned as
+`unknown`; declaring them is what types them and catches
+`level: "high"` in the editor.
+
+## Every other module grants on its own ids
 
 ```ts
+// modules/billing/module.acl.ts
 export default function billingAcl(acl: AclBuilder): void {
-  acl.allow("user", "invoices:read");
+  acl.allow("user", "billing:web:invoices", "billing:web:invoices:download");
+  acl.allow("admin", "billing:bo:*");
 }
 ```
 
-Guarding is the route's RAI — its `id` **is** the permission, so there is
-no second call to forget:
+Guarding is the route's RAI, so there is no second call to forget:
 
 ```ts
-router.get(
-  `${base}/invoices`,
-  rai({ id: "invoices:read", name: "List invoices" }),
-  billing.list(),
-);
+router.get("/invoices", rai({ id: "billing:web:invoices", name: "List my invoices" }), billing.list());
 ```
 
+## Wildcards
+
+A grant is an exact id, `*`, or a prefix ending in `:*`. A prefix covers
+everything under it, **the bare resource included**:
+
+| Grant | Covers |
+|---|---|
+| `billing:bo:invoices:*` | `billing:bo:invoices`, `billing:bo:invoices:refund`, … |
+| `billing:bo:*` | every billing permission in the back office |
+| `billing:*` | every billing permission, any scope |
+| `*` | everything. Give it to nobody but a true superuser. |
+
+A scope across modules (`*:bo:*`) is not a grant: each module grants its
+own ids, so the whole policy is readable module by module.
+
 ## 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:
+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
+acl.allow("guest", "docs:web:read");   // now anyone may read the docs
 ```
 
 There is no allowlist, no `skipAuth` flag, no second mechanism. Access is
@@ -52,20 +116,30 @@ decided in one place, and the whole policy is readable by reading the
 
 **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
+does not fail closed. It silently exposes the route. Name a permission on
 every route, even ones you expect everybody to reach.
 
-## Rules
+## Files follow the scope (a convention)
 
-- **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.
+Name routes and controllers scope-first, so a module's surfaces read off
+its folder. Core does not check this; it reads every `*.routes.ts` under
+`routes/`, at any depth.
+
+```
+modules/users/
+  routes/web.users.routes.ts            users:web:*
+  routes/bo.users.routes.ts             users:bo:*
+  routes/bo.users.passwords.routes.ts   a second bo file: the extra slot
+  controllers/web.users.controllers.ts  export class WebUsersController
+  controllers/bo.users.controllers.ts   export class BoUsersController
+
+modules/hello/                          several files in one scope: a folder
+  routes/web/hello.routes.ts
+  routes/web/hello.greetings.routes.ts
+  controllers/web/hello.greetings.controllers.ts   HelloGreetingsController
+```
+
+`tulipes new module billing --scope bo` scaffolds the flat form.
 
 ## Who is calling
 
@@ -79,8 +153,15 @@ 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
+The route's own declaration is `req.rai`, and `parseRai` splits its id:
+
+```ts
+import { parseRai } from "@tulipes/core/http";
+const { scope } = parseRai(req.rai!.id);   // "bo"
+```
+
+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
@@ -93,13 +174,20 @@ The RAI answers 401 when the caller is a guest (signing in would help) and
 
 ## Gotchas
 
+- **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.
 - 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`.
+- `acl.can(role, id)` answers *what a role may do*; `acl.rolesFor(id)`
+  answers *who may do this*. Neither says 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`.
+- Unknown roles always deny at runtime.
+- Roles are lowercase kebab-case. `name` and `definedBy` are set by the
+  ACL and cannot be part of a definition.

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

@@ -78,5 +78,6 @@ nothing processes them — that is the correct behaviour, not a bug.
 - 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.
+- Both processes run the full boot pipeline, so `ctx.models` and
+  `ctx.config` (settings and environment values alike) are available
+  inside a processor.

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

@@ -5,13 +5,14 @@ description: Use when streaming an app's logs, or when deciding whether a value
 
 # Settings and the settings module
 
-Two layers of configuration. **Environment** is what the process needs
-before the settings store can answer — the port, the connection strings,
-the log destinations — plus secrets: declared under `tulipes.env` in a
-module's `package.json`, read with `ctx.Environment.get()`, resolved once
-at boot. **Settings** are everything else: declared with a zod schema in
-`module.config.ts`, stored per module, validated on every write,
-hot-applied, read live at `ctx.config.<module>`. The test is mechanical:
+Two layers of configuration, one place to read them. **Environment values**
+are what the process needs before the settings store can answer — the
+port, the connection strings, the log destinations — plus secrets:
+declared under `tulipes.env` in a module's `package.json`, resolved once at
+boot, read-only at `ctx.config.<module>.<name>`. **Settings** are everything
+else: declared with a zod schema in `module.config.ts`, stored per module,
+validated on every write, hot-applied, read live at the same
+`ctx.config.<module>`. The test is mechanical:
 if boot does not need it before the database answers and it is not a
 secret, it is a setting. → skills `tulipes-env-variable`, `tulipes-config`
 
@@ -54,7 +55,7 @@ and refuses when `LOG_FILE` is off.
 | 0.10 endpoint | 0.11 |
 |---|---|
 | `GET /settings/modules` | `GET /config` — the `config` module |
-| `GET`/`PUT /settings/variables/:name` | gone: no editable secrets; variables are read-only in `GET /config` |
+| `GET`/`PUT /settings/variables/:name` | gone: no editable secrets; environment values are described (never a secret's value) in `GET /config` |
 | `POST /settings/reboot` | gone: nothing needs a restart to take effect; a restart-tagged field says so in the write's response |
 | `GET`/`PUT /settings/i18n/:module/:locale` | gone: translations are code, edited in the repository |
 | the `.env` file editor, PM2 control, the audit of those | gone with them; the console's writes are audited by the `config` module |

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

@@ -14,7 +14,7 @@ endpoint would reject.
 import { z } from "zod/v4";           // v4, not the classic import
 
 router.post("/users", rai({
-  id: "users:create",
+  id: "users:bo:create",
   name: "Create a user",
   body: z.object({ email: z.email("emailInvalid") }),
   returns: z.object({ id: z.string(), email: z.string() }),
@@ -64,7 +64,7 @@ split one module's routes apart, or to gather several modules under one
 heading:
 
 ```ts
-rai({ id: "auth:sessions", name: "List sessions", folder: "sessions" })
+rai({ id: "auth:web:sessions", name: "List sessions", folder: "sessions" })
 ```
 
 ## Generating
@@ -73,6 +73,16 @@ rai({ id: "auth:sessions", name: "List sessions", folder: "sessions" })
 pnpm spec     # tulipes spec --openapi docs/openapi.json --postman docs/collection.json
 ```
 
+One document per client surface: the RAI's scope is a filter, so a mobile
+team gets only what the mobile app calls. Every operation carries
+`x-tulipes-scope`, and the document lists the app's roles (with their
+descriptions and extras) under `x-tulipes-roles`.
+
+```sh
+pnpm tulipes spec --openapi docs/mobile.json --scope mobile
+pnpm tulipes spec --postman docs/backoffice.json --scope bo
+```
+
 Generation is an inspection boot: every routes file runs with nothing
 acquired, so no service, secret or `.env` is needed, and a routes file that
 touches infrastructure while building fails with its path. `--url` sets the

package/templates/minimal/config/app.config.ts

@@ -2,15 +2,25 @@ import type { AppConfigFn } from "@tulipes/core/boot";
 
 /**
  * App-wide values that belong to no module. `api.prefix` is where a router
- * a routes file returns is mounted; `app.name` titles the startup banner.
+ * a routes file returns is mounted; `app.name` titles the startup banner;
+ * `timezone.default` is the zone instants are read in (requests may ask for
+ * another with `?tz=` or X-Timezone) and, from boot on, the process zone.
+ *
+ * `env` is every module's environment values — here `env.core.port`, from
+ * the `PORT` the core module declares in its package.json — and this is
+ * where they are wired to what core reads: `server.port`. A module reads
+ * its own values as `ctx.config.<module>.<name>` without any wiring.
  */
-const appConfig = (() => ({
+const appConfig = ((env) => ({
   app: { name: "tulipes-example" },
   api: { prefix: "/api/v1" },
+  server: { port: env.core.port },
+  timezone: { default: "UTC" },
 })) satisfies AppConfigFn;
 
 export default appConfig;
 
+/** `server` is left out: core already types the key it reads. */
 declare module "@tulipes/core/config" {
-  interface GlobalConfig extends Partial<ReturnType<typeof appConfig>> {}
+  interface GlobalConfig extends Partial<Omit<ReturnType<typeof appConfig>, "server">> {}
 }

package/templates/minimal/modules/agent/routes/{agent.routes.ts → web.agent.routes.ts}

@@ -7,11 +7,11 @@ import { roleOf } from "@tulipes/core/http";
 export default function agentRoutes(ctx: BackendCtx): Router {
   const { rai } = ctx;
   const router = Router();
-  router.get("/agent/tools", rai({ id: "agent:tools", name: "Tools an agent may call" }), (req, res) => {
+  router.get("/agent/tools", rai({ id: "agent:web:tools", name: "Tools an agent may call" }), (req, res) => {
     res.respond({ data: ctx.agent.manifest(roleOf(req)) });
   });
   router.post("/agent/tools/:name", rai({
-    id: "agent:invoke", name: "Run a declared action",
+    id: "agent:web:invoke", name: "Run a declared action",
     params: z.object({ name: z.string() }), body: z.looseObject({}),
   }), async (req, res) => {
     res.respond({ data: await ctx.agent.invoke(String(req.params.name), req.body, { ...req.auth, role: roleOf(req) }, req) });

package/templates/minimal/modules/core/module.acl.ts

@@ -1,4 +1,10 @@
 import type { AclBuilder } from "@tulipes/core/acl";
+
+/**
+ * The roles, defined once. A RAI id is "module:scope:resource[:extra]";
+ * a grant names one or a prefix ending in ":*". `pnpm tulipes roles`
+ * prints every role with its grants.
+ */
 export default function permissions(acl: AclBuilder) {
-  acl.defineRole("guest").allow("guest", "core:health");
+  acl.defineRole("guest", { description: "Any request without a valid token" });
 }

package/templates/minimal/modules/core/package.json

@@ -6,14 +6,14 @@
   "tulipes": {
     "tier": "sys",
     "priority": 0,
-    "env": [
-      {
-        "name": "PORT",
+    "env": {
+      "port": {
+        "key": "PORT",
         "type": "number",
         "default": 3000,
         "description": "HTTP listener port"
       }
-    ]
+    }
   },
   "dependencies": {
     "@tulipes/core": "workspace:*"

package/templates/minimal/modules/hello/module.acl.ts

@@ -1,2 +1,2 @@
 import type { AclBuilder } from "@tulipes/core/acl";
-export default function permissions(acl: AclBuilder) { acl.allow("guest", "hello:read"); }
+export default function permissions(acl: AclBuilder) { acl.allow("guest", "hello:web:read", "hello:web:health"); }

package/templates/minimal/modules/hello/routes/{health.routes.ts → web.hello.health.routes.ts}

@@ -2,7 +2,7 @@ import { Router } from "express";
 import type { BackendCtx } from "@tulipes/core/boot";
 export default function healthRoutes({ rai, routes }: BackendCtx): void {
   const router = Router();
-  router.get("/health", rai({ id: "core:health", name: "Health" }), (_req, res) => {
+  router.get("/health", rai({ id: "hello:web:health", name: "Health" }), (_req, res) => {
     res.respond({ data: { status: "ok" } });
   });
   routes.mount(router, "");

package/templates/minimal/modules/hello/routes/{hello.routes.ts → web.hello.routes.ts}

@@ -3,7 +3,7 @@ import { z } from "zod/v4";
 import type { BackendCtx } from "@tulipes/core/boot";
 export default function helloRoutes({ rai }: BackendCtx): Router {
   const router = Router();
-  router.get("/hello", rai({ id: "hello:read", name: "Hello", returns: z.object({ message: z.string() }) }), (req, res) => {
+  router.get("/hello", rai({ id: "hello:web:read", name: "Hello", returns: z.object({ message: z.string() }) }), (req, res) => {
     res.respond({ data: { message: req.t("greeting") } });
   });
   return router;

package/templates/overlays/no-queues/modules/hello/controllers/{greetings.controllers.ts → web/hello.greetings.controllers.ts}

@@ -2,7 +2,7 @@ import type { Request, RequestHandler, Response } from "express";
 import { requireModels, type Ctx } from "@tulipes/core/boot";
 import { HttpError } from "@tulipes/core/http";
 
-export class GreetingsController {
+export class HelloGreetingsController {
   readonly #ctx: Ctx;
 
   constructor(ctx: Ctx) {