@tulipes/cli 0.1.0-rc.1

package/templates/CLAUDE.md

@@ -0,0 +1,120 @@
+# Working in this project
+
+This is a **Tulipes** application (`@tulipes/core`) — a module-based Express
+framework. It is convention-driven and deliberately fail-closed: almost
+everything that can be validated at boot is, and a violation crashes the
+process with a report rather than degrading quietly.
+
+Writing plain Express here will fight the framework. Read the rule that
+applies before you write code.
+
+## Preset scope
+
+Read the installed modules and package scripts before applying integration examples.
+The minimal preset has core, security and hello only. Auth, users, settings,
+MongoDB, Redis, queues, sockets, shared logger/cache helpers and PM2 examples
+below apply when those modules are installed (the production preset). Minimal
+requests use the framework guest identity. Grant permissions to roles the app
+actually defines. Use the generated Vitest suite for changes; production tests
+require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
+
+## Non-negotiable rules
+
+1. **Never read `process.env` directly.** Every configuration value is
+   declared in a module's `meta.variables.json` and read with
+   `ctx.Environment.get("NAME")`. Reading an undeclared name throws on
+   purpose. → skill `tulipes-env-variable`
+2. **A feature is a module, not a layer.** Everything a feature needs —
+   routes, models, config, permissions, jobs — lives in one folder under
+   `modules/`. Never add a top-level `services/` or `middlewares/` folder.
+   → skill `tulipes-module`
+3. **Never call `mongoose.model()` yourself.** Models are declarations
+   picked up by the framework and read from `ctx.models`. Persisted and
+   wire field names are `snake_case` (`created_at`, never `createdAt`);
+   camelCase is for TypeScript-only names. → skill `tulipes-model`
+4. **Global middleware belongs to a sys-tier module**, not to the
+   entrypoint. `app.ts` stays three lines. → skill `tulipes-endpoint`
+5. **Run `yarn sync` after touching any `meta.variables.json` or
+   `module.config.ts`.** It regenerates `types/config.d.ts` and
+   `.env.example`; stale generated types are a lie.
+6. **Every response is `res.respond({ data, meta })`** — never `res.json`,
+   which ships a raw body outside the envelope. Failures are **thrown**:
+   `throw new HttpError(404, "notFound")`, where the message is an i18n
+   key and the code derives from it. Never hand-roll an error shape.
+   → skill `tulipes-response`
+7. **Every route declares a RAI**: put `rai({ id: "x:read" })` first in
+   each endpoint handler chain, including routes inside `defineRoutes()`.
+   The id is also the ACL permission, and core refuses to boot if a route
+   is missing one. Public is `acl.allow("guest", "x:read")`, never a
+   missing check. → skill `tulipes-endpoint`
+8. **Validate input with a zod schema on the RAI** (`body`, `query`,
+   `params`, from `zod/v4`) rather than hand-rolled `if` checks. The same
+   declaration generates the OpenAPI and Postman documents, so they cannot
+   describe a shape the endpoint rejects. → skill `tulipes-spec`
+9. **User-facing strings are keys, never literals.** `req.t("notFound")`
+   inside a route reads that module's `i18n/<locale>.json` — the module is
+   the namespace and `rai()` binds it. Never concatenate a translated
+   string with a variable. → skill `tulipes-i18n`
+10. **`req.auth` is who is calling** — `{ isAuthenticated, user, session }`,
+    resolved before any feature route and never undefined inside one. Never
+    re-parse the Authorization header or trust a claim from a token.
+    → skill `tulipes-permissions`
+11. **When auth is installed, secrets never go on the User model.** Passwords and keys belong in
+    the auth module's `Credential` model, which is `select: false`.
+12. **When auth is installed, a new feature module's namespace goes in BOTH the `admin` and
+    `sysadmin` grants** in `modules/auth/module.acl.ts`. Neither role holds
+    `*` — a wildcard would reach `settings:*` and make the sysadmin
+    boundary a label rather than a rule. → skill `tulipes-settings`
+13. **Cross-module imports use the package name** (`@app/users`,
+    `@app/core`), never a relative path that climbs out of the module. The
+    workspace boundary is what keeps modules independent, and a package
+    name makes the dependency visible in package.json — declare it there
+    and in `dependsOn`.
+
+For endpoint changes, read `tulipes-endpoint`: native routers live in
+`routes/*.routes.ts`. Use `defineRoutes()` and `runtime()` for offline inspection;
+keep shared middleware and param callbacks beside their endpoints.
+
+## Where things go
+
+| Decision | Location |
+|---|---|
+| Value differs per deployment (URL, secret, toggle) | that module's `meta.variables.json` |
+| Policy shared by ≥2 modules (pagination, body limit) | `config/app.config.ts` |
+| Config for one feature | that module's `module.config.ts` |
+| A string a user will read | that module's `i18n/<locale>.json`, reached with `req.t` |
+| The shape of a request body/query | a zod schema on the route's `rai()` |
+| Middleware for every request | a sys-tier module's routes file |
+| Middleware for one feature's routes | that module's own `Router` |
+| Helper used by ≥2 modules | the sys core module, exported from its `index.ts` and imported as `@app/core` |
+| Helper used by one module | that module's `helpers/` |
+| One-off task (backfill, export, admin chore) | `scripts/`, booted with `mode: "script"` |
+| Anything you would `console.log` | `moduleLogger(ctx.Environment, "<module>", ctx.mode)` from `@app/core` |
+
+## Boot order (why load order matters)
+
+`sys` modules load before `app` modules; within a tier, lower `priority`
+first; then `dependsOn` topological order. Config → translations → ACL →
+database → queues → routes. If code needs something another module
+provides, declare `dependsOn` — do not rely on luck.
+
+## Commands
+
+| Command | Use |
+|---|---|
+| `yarn dev` | run the backend process (regenerates types first) |
+| `yarn worker` | run the queue-consumer process |
+| `yarn sync` | regenerate `types/config.d.ts` + `.env.example` |
+| `yarn check` | validate the environment without booting |
+| `yarn typecheck` | typecheck the whole app |
+| `yarn tulipes new module <name>` | scaffold a module |
+| `tulipes update` | upgrade the global cli and the framework in every manifest |
+| `yarn script scripts/x.ts` | run a one-off script against the real app |
+
+## Verifying your work
+
+A change is not done until the app boots. Run `yarn typecheck`, then
+`yarn dev` and confirm the startup banner lists what you added (modules,
+queues, sockets, roles). Boot failures print an aggregate report naming
+every problem at once — read all of it before fixing anything. → skill
+`tulipes-boot-errors`

package/templates/browser-auth.md

@@ -0,0 +1,120 @@
+# Browser authentication and cookies
+
+This production starter returns access and refresh tokens in JSON. It does not
+issue authentication cookies, read credentials from cookies, or install CSRF
+middleware. Its current transport contract is:
+
+| Operation | Credential source |
+|---|---|
+| Protected HTTP routes | `Authorization: Bearer <access_token>` |
+| Login and registration | Email and password in an `application/json` body |
+| Refresh | `refresh_token` in an `application/json` body |
+| Logout, password change and device revocation | Access-token header |
+
+The access-token extractor ignores cookies and URL parameters. Keep tokens out of
+URLs: URLs can reach history, logs and referrers. The built-in auth routes do not
+parse form or text bodies as JSON. Preserve these boundaries when extending them.
+
+## Connect a browser using the current contract
+
+Set `CORS_ORIGINS` to the exact browser origins, including scheme and port, such as
+`https://console.example.com`. An empty value grants no cross-origin response
+access. `*` allows every origin; reserve it for intentionally public APIs.
+`CORS_CREDENTIALS=false` is the default. A caller can supply a Bearer header
+explicitly without enabling credential mode for cookies; that header requires a
+successful CORS preflight. [Fetch CORS protocol](https://fetch.spec.whatwg.org/#cors-protocol-and-credentials).
+
+```ts
+// The caller holds this token in memory after login; do not put it in the URL.
+const response = await fetch(`${apiBase}/api/v1/auth/me`, {
+  credentials: "omit",
+  headers: { Authorization: `Bearer ${accessToken}` },
+});
+
+if (!response.ok) {
+  throw new Error("The authenticated request failed");
+}
+
+const profile = await response.json();
+```
+
+CORS supplies browser response-access headers. A disallowed origin can still send
+some requests, and command-line clients do not enforce CORS. Authentication and
+ACLs remain necessary. `CORS_CREDENTIALS=true` only emits a CORS response header;
+it neither reads cookies nor adds CSRF checks. The starter rejects combining it
+with `CORS_ORIGINS=*`. [Express CORS middleware](https://expressjs.com/en/resources/middleware/cors/).
+
+A browser frontend needs its own storage policy. Prefer memory for short-lived
+Bearer credentials. Persistent JavaScript-readable storage exposes tokens to any
+script running in that origin; do not treat localStorage as a secure session
+vault. An XSS flaw can also steal in-memory tokens or make requests as the user.
+A server-backed browser session can keep refresh credentials away from frontend
+JavaScript, but requires the cookie controls below.
+[OWASP session management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html).
+
+## If the application adopts cookies
+
+Treat cookie authentication as an application change with retained abuse tests.
+Apply CSRF validation before actions on every affected route, including login,
+refresh, logout, password changes and settings. Prefer an existing maintained
+implementation using a session-bound synchronizer token, or a signed double-submit
+token bound to the session. Reject absent or invalid tokens. Check the exact
+trusted source origin, with a defined Referer fallback and missing-header policy.
+Keep state-changing operations off GET. Restrict accepted content types and CORS
+origins; do not trust arbitrary sibling subdomains. Same-site and same-origin are
+different boundaries: sibling origins can be same-site. SameSite provides additional
+protection but does not replace these checks. XSS can defeat CSRF defenses.
+[OWASP CSRF prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).
+
+Use HTTPS with `Secure` and `HttpOnly` authentication cookies. Choose an explicit
+`SameSite=Strict` or `Lax` policy that fits the login/navigation flow. Cross-site
+cookies require `SameSite=None; Secure`, and browser third-party-cookie restrictions
+may still block them. Prefer host-only cookies without a Domain attribute. A
+`__Host-` cookie requires Secure, Path=/ and no Domain; a narrower Path cannot use
+that prefix. Path is not an authorization boundary. Align cookie lifetime with
+server session expiry, and clear cookies using the same name, path and domain when
+revoking the server session. HttpOnly prevents script reads, but browsers still
+attach the cookie to requests. [MDN Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie).
+
+For cross-origin cookie requests, configure the browser with
+`credentials: "include"`, exact allowed origins and `CORS_CREDENTIALS=true`.
+Browser cookie restrictions still apply. This setup does not supply CSRF
+validation. [MDN CORS guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS).
+
+If HttpOnly cookies are intended to hide refresh credentials from JavaScript,
+remove those credentials from response bodies as part of the adaptation too.
+
+## Evidence required for a cookie adaptation
+
+Test rejected CSRF tokens and hostile origins without side effects, login CSRF,
+refresh/logout and administrative operations, plus expiration and revocation.
+Use real browsers to check same-site sibling origins, cross-site preflights,
+credential mode, cookie flags and third-party-cookie behavior through the deployed
+TLS/proxy topology. Include missing Origin/Referer cases in the chosen policy.
+
+The starter's HTTP tests retain header/body-only authentication, absent Set-Cookie,
+and rejection of cookie-only, query-token and non-JSON refresh attempts. They run
+in Node and do not establish browser enforcement or validate a future cookie flow.
+
+## Refresh rotation and suspected theft
+
+One login creates one token family, identified by the session's `sid`. Refresh
+rotates within that family. Reusing any valid, unexpired superseded refresh token
+expires the whole family, including its access tokens. Other devices stay active;
+changing the account password invalidates all devices. This strict policy follows
+the replay-detection rationale in [RFC 9700 section 4.14.2](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.14.2);
+the starter itself is not an OAuth authorization server.
+
+Serialize refreshes per session, coordinating tabs that share credentials. A
+concurrent duplicate causes one success and one rejection, but makes the success
+pair unusable too. After a refresh rejection, lost response or
+`REFRESH_UNAVAILABLE` (503), discard the local pair and sign in again. There is no
+retry grace period: a request that committed before its response was lost may
+already have consumed the token.
+
+Reuse does not reveal which caller is legitimate. Someone with an old unexpired
+token can force the device to sign in again; an expired token cannot trigger this
+revocation. Theft without reuse is not detected. A database failure may prevent
+revocation or obscure its outcome, and requests already authorized are not
+cancelled. Use password change for suspected account-wide compromise and apply
+your own incident-response and alerting policy.

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

@@ -0,0 +1,74 @@
+---
+name: tulipes-boot-errors
+description: Use when a Tulipes app fails to boot, when a route/model/queue you added is not being picked up, or when reading a TulipesBootError report. Maps each boot phase's crash message to its cause and fix.
+---
+
+# Diagnosing a boot failure
+
+Boot crashes with a `TulipesBootError` naming the phase and listing
+**every** problem found in that phase:
+
+```
+TulipesBootError: Boot aborted during "environment" — 3 issue(s):
+  ✖ [core] required variable "MONGO_URI" has no value (…)
+  ✖ [users] variable "USERS_MAX_SESSIONS": "abc" is not a number
+  ✖ [users] required variable "USERS_ADMIN_EMAIL" has no value (…)
+```
+
+**Read the whole list before changing anything.** The report is complete
+for that phase — fixing one line at a time wastes restarts. Phases run in
+order and stop at the first failing one, so a later phase may still hold
+problems the report has not reached yet.
+
+## By phase
+
+| Phase | Typical message | Cause and fix |
+|---|---|---|
+| `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. |
+| `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`. |
+| `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` | `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` | `"@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` | `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`. |
+
+## "My file is being ignored"
+
+The framework discovers files by convention. If something you added never
+runs, check in this order:
+
+1. **Filename suffix** — `*.routes.ts`, `*.model.ts`, `*.queues.ts`,
+   `*.sockets.ts`, `*.bootstrap.ts`, `module.config.ts`, `module.acl.ts`.
+   A file named `users.route.ts` (no `s`) is invisible.
+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
+   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`.
+- **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`.

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

@@ -0,0 +1,132 @@
+---
+name: tulipes-endpoint
+description: Use when adding or changing an HTTP endpoint in a Tulipes app, writing a controller, mounting middleware, or handling request errors. Covers the rai() declaration every route must carry, controller classes, and the request pipeline.
+---
+
+# Adding an endpoint
+
+Two files: a controller class holding the work, and a shared declaration file wiring
+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`:
+
+```ts
+import type { Request, RequestHandler, Response } from "express";
+import type { Ctx } from "@tulipes/core/boot";
+import { HttpError } from "@tulipes/core/http";
+
+export class BillingController {
+  constructor(private readonly ctx: Ctx) {}
+
+  show(): RequestHandler {
+    return async (req: Request, res: Response) => {
+      const invoice = await this.ctx.models!.get("Invoice").findById(req.params.id).lean();
+      if (!invoice) throw new HttpError(404, "noSuchInvoice");
+      res.respond({ data: invoice });
+    };
+  }
+}
+```
+
+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`:
+
+```ts
+import { Router } from "express";
+import { defineRoutes } from "@tulipes/core/http";
+
+export default defineRoutes(({ app, rai, routes, runtime }) => {
+  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);
+});
+```
+
+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.
+
+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.
+
+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.
+
+## The RAI is not optional
+
+`id` names a resource and an access to it, and **is** the ACL permission.
+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
+`tulipes-i18n` Core walks the router stack after mounting; a route without a
+RAI, or two routes sharing an id, abort the boot:
+
+```
+TulipesBootError: Boot aborted during "routes" — 1 issue(s):
+  ✖ GET /api/v1/invoices has no rai() declaration — every route must
+    declare one, or it is reachable by anyone
+```
+
+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.
+
+## Responses and errors
+
+Every response goes through `res.respond`, which builds the app's
+envelope — `{ success, data, errors, meta }`. Failures are **thrown**, and
+the terminal handler builds the same envelope from them, so a handler only
+ever writes the happy path. → skill `tulipes-response`
+
+```ts
+res.respond({ data: invoice });
+res.respond({ data: invoices, meta: { total_items } });   // paginated
+throw new HttpError(404, "noSuchInvoice");                // → NOT_FOUND
+```
+
+Express 5 forwards rejected async handlers to the terminal handler, so
+`throw` works inside `async` without a try/catch.
+
+- Middleware errors carrying a 4xx pass through (oversized body → 413,
+  malformed JSON → 400).
+- Anything else → anonymous `500`, real message only in development.
+  **Never** catch an error just to `res.status(500).json(...)` yourself;
+  that leaks what the framework hides.
+- **Never `res.json`** — it ships a raw, unenveloped body. Development
+  logs a warning naming the route; production does not.
+
+## The request pipeline
+
+```
+module routers, in load order:
+  sys modules      request ids, helmet, cors, logging, body parsing,
+                   then auth resolving req.auth (guest if no token)
+  app modules      your feature routes, each gated by its RAI
+notFoundHandler    framework — 404 for anything unclaimed
+errorHandler       framework — terminal
+```
+
+- **Middleware for every request** → a sys-tier module's routes file,
+  mounted on `ctx.app` (that file returns nothing).
+- **Middleware for one router** → router.use before its endpoints.
+- **Middleware for one endpoint** → put callbacks after its rai() handler.
+- Never mount middleware in `app.ts`, and never reorder by moving
+  `app.use` calls — ordering is `tier` + `priority`.

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

@@ -0,0 +1,78 @@
+---
+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.
+---
+
+# 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`.
+
+## 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`:
+
+```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
+    }
+  ]
+}
+```
+
+3. Add a value to `.envs/.env.development` for anything `required`.
+4. `yarn sync` — regenerates `types/config.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`.
+
+## 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. |
+| `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.
+
+## Precedence
+
+`process.env` › `.envs/.env.<APP_ENV>` › `default`. Container-injected
+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.
+- Value used by one module and never changed per deployment → that
+  module's `module.config.ts`.
+
+## 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.
+- `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-i18n/SKILL.md

@@ -0,0 +1,98 @@
+---
+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.
+---
+
+# Translating
+
+Every user-facing string is a key. A module is a namespace, and it owns
+its strings:
+
+```
+modules/users/i18n/
+  en.json          the default locale — must be complete
+  fr.json          gaps fall back to en
+  fr.missing.json  generated; never edit, never commit
+```
+
+## In an endpoint
+
+`req.t` is already bound to the module that declared the route, because
+`rai()` binds it. Nothing to import, nothing to pass:
+
+```ts
+res.json({ message: req.t("created", { email }) });
+throw new HttpError(404, req.t("notFound"));
+```
+
+with `modules/users/i18n/en.json`:
+
+```json
+{
+  "created": "User {{email}} created",
+  "notFound": "No such user",
+  "list": { "count_one": "{{count}} user", "count_other": "{{count}} users" }
+}
+```
+
+- **Nesting** is a `.` in the key: `req.t("list.count", { count })`.
+- **Plurals** come from `count` — i18next picks `_one` / `_other` (and the
+  categories a language actually has) so no handler writes a ternary.
+- **Another module's strings**: name the namespace, `req.t("auth:invalid")`.
+  Rare, and worth a second thought — a string two modules need usually
+  belongs to whichever one owns the concept.
+- `req.locale` is the negotiated locale, if you need it in a payload.
+
+## Outside a request
+
+A queue processor, script or bootstrap task has no request to negotiate
+from, so it names both the namespace and the locale:
+
+```ts
+const t = ctx.t("users", recipient.locale);
+await sendMail(t("welcome.subject", { name }));
+```
+
+Which means the locale has to travel with the work — put it in the job
+payload when you enqueue, since the worker cannot recover it later:
+
+```ts
+await ctx.queues!.add("users.welcome", "welcome", { email, locale: req.locale });
+```
+
+`ctx.i18n` is the i18next instance underneath, for anything else.
+
+## How a locale is chosen
+
+1. `?lang=fr` — an explicit override, so a locale is testable with curl
+   and survives a shared link
+2. `Accept-Language`, q-values honoured
+3. `config.i18n.defaultLocale`
+
+Every candidate is narrowed to `config.i18n.supportedLocales`, so an
+unsupported `?lang=xx` falls through rather than serving raw keys. A
+region the app does not ship resolves to its base language: `fr-CA` is
+served by `fr` unless `fr-CA.json` exists.
+
+## Adding a locale
+
+1. Add it to `supportedLocales` in `config/app.config.ts`.
+2. Boot. Every module now has `<locale>.missing.json` listing everything
+   it needs, with the English text as the value.
+3. Translate into `<locale>.json`, delete nothing — the missing file
+   disappears on the next boot once the gaps are gone.
+
+## Rules
+
+- **Never concatenate a translated string.** Put the variable in the key:
+  `"Welcome, {{name}}"`, not `t("welcome") + name`. Word order differs
+  between languages, and the concatenation is untranslatable.
+- **Only `en.json` (the default locale) must be complete.** A missing key
+  in another locale falls back to it — a feature can ship before its
+  translations do.
+- **`*.missing.json` is generated.** It is git-ignored, rewritten on every
+  non-production boot, and never written in production.
+- Invalid JSON in a locale file, or an `i18n/` folder with no
+  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.