@tulipes/cli 0.2.0 → 0.3.0-rc.2

package/dist/spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0B7C,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAe,EAAE,OAAoB;IACjE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACzC,OAAO,CAAC,KAAK,CACX;YACE,8CAA8C;YAC9C,EAAE;YACF,uCAAuC;YACvC,0CAA0C;YAC1C,+FAA+F;YAC/F,qDAAqD;SACtD,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO;IAElB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;IAEzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAGlG,CAAC;QACF,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;gBACrC,CAAC,CAAC,0CAA0C;gBAC5C,CAAC,CAAC,uBAAuB,OAAO,CAAC,KAAK,yBAAyB,CAAC,CAAC;YACnE,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9F,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QAEnC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxF,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACtF,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,CAAC,GAAG,CACT,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,eAAe,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,KAAK,GAAG,GAAG;YAC1G,UAAU,MAAM,CAAC,OAAO,CAAC,MAAM,cAAc;YAC7C,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAC5B,CAAC;QAEF,mEAAmE;QACnE,gEAAgE;QAChE,6DAA6D;QAC7D,IAAI,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,oCAAoC,CAAC,CAAC;YACrE,KAAK,MAAM,OAAO,IAAI,QAAQ;gBAAE,OAAO,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,aAAa,CAAC,OAAe;IAC1C,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IACxB,CAAC;IAED,OAAO,CAAC,KAAK,CACX;QACE,6CAA6C;QAC7C,EAAE;QACF,6BAA6B;QAC7B,EAAE;QACF,yEAAyE;KAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,OAAe,EAAmC,EAAE,CACnE,aAAa,CAAa,OAAO,EAAE,eAAe,CAAC,CAAC;AAEtD,0EAA0E;AAC1E,KAAK,UAAU,OAAO;IACpB,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,eAAe,CAAC,CAA0B,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CAAC,cAAuB,EAAE,IAA4C;IACvF,MAAM,IAAI,GAAG,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,IAAI,EAAE,YAAY,KAAK,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;IAE7G,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,MAAM,EAAE,CAAC;AACnF,CAAC;AAED,SAAS,KAAK,CAAC,MAAc,EAAE,QAAiB;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,WAAW,MAAM,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/sync.js

@@ -1,22 +1,21 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { BootReport } from "@tulipes/core/errors";
-import { discoverModuleMeta } from "@tulipes/core/env";
-import { discoverModules } from "@tulipes/core/modules";
-import { sortModules } from "@tulipes/core/modules";
-import { exploreModules } from "@tulipes/core/modules";
+import { discoverModules, exploreModules, sortModules } from "@tulipes/core/modules";
 /**
  * `tulipes sync` — everything derivable from the declarations, derived:
  *
- *   types/tulipes.d.ts  KnownVariables, GlobalConfig, KnownModels and
- *                       KnownJobs augmentations. A config namespace is typed
- *                       as the OUTPUT of the schema its module.config.ts
- *                       declares, a model as its file's default export and a
- *                       queue's job data as its file's `jobs` schema, all via
- *                       `typeof import(...)` — the compiler does the
- *                       inference, codegen never executes module code. The
- *                       one thing read from source is each model's name,
- *                       which keys the interface and so must be a literal.
+ *   types/tulipes.d.ts  EnvValues, GlobalConfig, KnownModels and KnownJobs
+ *                       augmentations. A config namespace is typed as the
+ *                       OUTPUT of the schema its module.config.ts declares,
+ *                       intersected with the read-only environment values
+ *                       its package.json declares; a model as its file's
+ *                       default export and a queue's job data as its file's
+ *                       `jobs` schema, all via `typeof import(...)` — the
+ *                       compiler does the inference, codegen never executes
+ *                       module code. The one thing read from source is each
+ *                       model's name, which keys the interface and so must
+ *                       be a literal.
  *   .env.example        every variable, grouped by module and `group`.
  *
  * Both files are committed and marked generated.
@@ -28,18 +27,14 @@ export const TYPES_FILE = "tulipes.d.ts";
 export async function runSync(rootDir) {
     const report = new BootReport();
     const modulesDir = join(rootDir, "modules");
-    const metas = discoverModuleMeta(modulesDir, report);
+    // The manifests carry the environment declarations; load order keeps
+    // the output stable.
     const order = sortModules(discoverModules(modulesDir, report), report);
     report.throwIfAny("sync");
-    const metaByModule = new Map(metas.map((meta) => [meta.module, meta]));
-    // Meta discovery walks folders; align it to load order for stable output.
-    const orderedMetas = order
-        .map((module) => metaByModule.get(module.name))
-        .filter((meta) => meta !== undefined);
     const typesDir = join(rootDir, "types");
     mkdirSync(typesDir, { recursive: true });
     const dtsPath = join(typesDir, TYPES_FILE);
-    writeFileSync(dtsPath, renderDts(rootDir, orderedMetas, order));
+    writeFileSync(dtsPath, renderDts(rootDir, order));
     console.log(`wrote ${relative(rootDir, dtsPath)}`);
     const legacyPath = join(typesDir, LEGACY_DTS);
     if (existsSync(legacyPath) && readFileSync(legacyPath, "utf8").startsWith(GENERATED_MARKER)) {
@@ -47,29 +42,39 @@ export async function runSync(rootDir) {
         console.log(`removed ${relative(rootDir, legacyPath)} (now ${TYPES_FILE})`);
     }
     const envExamplePath = join(rootDir, ".env.example");
-    writeFileSync(envExamplePath, renderEnvExample(orderedMetas));
+    writeFileSync(envExamplePath, renderEnvExample(order));
     console.log(`wrote ${relative(rootDir, envExamplePath)}`);
 }
-function renderDts(rootDir, metas, order) {
-    const variableLines = metas.flatMap((meta) => meta.variables.flatMap((spec) => [
-        `    /** [${meta.module}] ${spec.description} */`,
-        `    ${spec.name}: ${tsTypeOf(spec)};`,
-    ]));
+function renderDts(rootDir, order) {
+    // `env.<module>.<name>` in config/app.config.ts: one block per module that
+    // declares anything, each value read-only, optional when nothing
+    // guarantees it (no default, not required).
+    const envLines = order
+        .filter((module) => Object.keys(module.env).length > 0)
+        .flatMap((module) => [
+        `    ${JSON.stringify(module.name)}: {`,
+        ...envFieldLines(module, "      "),
+        `    };`,
+    ]);
     const explored = exploreModules(order);
     // `.ts` specifiers: the app imports its own files that way (Node strips
     // the types natively) and tsconfig allows importing them.
     const specifierOf = (file) => "./" + relative(join(rootDir, "types"), file);
-    // Only modules with a declaration get a typed namespace; the rest fall
-    // back to GlobalConfig's index signature.
+    // A module's namespace is its settings' output, its environment values,
+    // or both; a module with neither falls back to GlobalConfig's index
+    // signature. Optional on purpose: a namespace only exists once phase 6
+    // has loaded it, and an empty config seed must stay assignable.
     const configLines = explored
-        .filter((files) => files.configFile)
-        .flatMap((files) => [
-        // Optional on purpose: a namespace only exists once phase 6 has loaded
-        // it, and an empty config seed must stay assignable.
-        `    ${JSON.stringify(files.module.name)}?: import("zod/v4").output<`,
-        `      (typeof import("${specifierOf(files.configFile)}"))["default"]["schema"]`,
-        `    >;`,
-    ]);
+        .filter((files) => files.configFile || Object.keys(files.module.env).length > 0)
+        .flatMap((files) => {
+        const parts = [];
+        if (files.configFile) {
+            parts.push(`import("zod/v4").output<(typeof import("${specifierOf(files.configFile)}"))["default"]["schema"]>`);
+        }
+        if (Object.keys(files.module.env).length > 0)
+            parts.push(`EnvValues[${JSON.stringify(files.module.name)}]`);
+        return [`    ${JSON.stringify(files.module.name)}?: ${parts.join(" & ")};`];
+    });
     // A model's name keys the interface, so it is read from the file — the
     // one place codegen looks at source rather than types. A name that is not
     // a literal is reported and the model stays reachable through the
@@ -109,13 +114,10 @@ function renderDts(rootDir, metas, order) {
     return [
         `${GENERATED_MARKER} — do not edit.`,
         "",
-        'declare module "@tulipes/core/env" {',
-        "  interface KnownVariables {",
-        ...variableLines,
-        "  }",
-        "}",
-        "",
         'declare module "@tulipes/core/config" {',
+        "  interface EnvValues {",
+        ...envLines,
+        "  }",
         "  interface GlobalConfig {",
         ...configLines,
         "  }",
@@ -135,6 +137,16 @@ export function modelNameOf(file) {
     const scope = DEFAULT_EXPORT_OBJECT.exec(source)?.[1] ?? source;
     return NAME_LITERAL.exec(scope)?.[2] ?? NAME_LITERAL.exec(source)?.[2];
 }
+/** `/** doc *\/ readonly name: type;` for each of a module's declared values. */
+function envFieldLines(module, indent) {
+    return Object.entries(module.env).flatMap(([name, spec]) => {
+        const guaranteed = spec.required === true || spec.default !== undefined;
+        return [
+            `${indent}/** ${spec.key} — ${spec.description} */`,
+            `${indent}readonly ${name}: ${tsTypeOf(spec)}${guaranteed ? "" : " | undefined"};`,
+        ];
+    });
+}
 function tsTypeOf(spec) {
     switch (spec.type) {
         case "number":
@@ -147,29 +159,30 @@ function tsTypeOf(spec) {
             return "string";
     }
 }
-function renderEnvExample(metas) {
+function renderEnvExample(order) {
     const lines = [
         "# AUTO-GENERATED by `tulipes sync` from every module's package.json tulipes.env.",
         "# Copy into .envs/.env.<mode> and fill in the blanks.",
     ];
-    for (const meta of metas) {
-        if (meta.variables.length === 0)
+    for (const module of order) {
+        const variables = Object.entries(module.env);
+        if (variables.length === 0)
             continue;
-        lines.push("", `# ━━━ ${meta.module} ━━━`);
-        // Stable grouping: order of first appearance, ungrouped vars last.
+        lines.push("", `# ━━━ ${module.name} ━━━`);
+        // Stable grouping: order of first appearance, ungrouped variables last.
         const groups = new Map();
-        for (const spec of meta.variables) {
-            const key = spec.group ?? "";
-            (groups.get(key) ?? groups.set(key, []).get(key)).push(spec);
+        for (const entry of variables) {
+            const group = entry[1].group ?? "";
+            (groups.get(group) ?? groups.set(group, []).get(group)).push(entry);
         }
         for (const [group, specs] of [...groups.entries()].sort(([a], [b]) => Number(a === "") - Number(b === ""))) {
             if (group)
                 lines.push("", `# ── ${group} ──`);
-            for (const spec of specs) {
+            for (const [name, spec] of specs) {
                 const constraint = spec.type === "enum" ? `enum: ${spec.enum.join(" | ")}` : spec.type;
                 const requirement = spec.required ? ", REQUIRED" : "";
-                lines.push(`# ${spec.description} (${constraint}${requirement})`);
-                lines.push(`${spec.name}=${spec.default ?? ""}`);
+                lines.push(`# ${spec.description} (${constraint}${requirement}) → config.${module.name}.${name}`);
+                lines.push(`${spec.key}=${spec.default ?? ""}`);
             }
         }
     }

package/dist/sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAmB,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,gBAAgB,GAAG,qCAAqC,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,UAAU,GAAG,aAAa,CAAC;AACjC,MAAM,CAAC,MAAM,UAAU,GAAG,cAAc,CAAC;AAEzC,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAe;IAC3C,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;IAChC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAE5C,MAAM,KAAK,GAAG,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,WAAW,CAAC,eAAe,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IACvE,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAE1B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACvE,0EAA0E;IAC1E,MAAM,YAAY,GAAG,KAAK;SACvB,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;SAC9C,MAAM,CAAC,CAAC,IAAI,EAAsB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACxC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEzC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC3C,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,SAAS,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAEnD,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC9C,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC5F,MAAM,CAAC,UAAU,CAAC,CAAC;QACnB,OAAO,CAAC,GAAG,CAAC,WAAW,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,SAAS,UAAU,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACrD,aAAa,CAAC,cAAc,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,SAAS,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,SAAS,CAChB,OAAe,EACf,KAA4B,EAC5B,KAAqC;IAErC,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAC3C,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,YAAY,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,WAAW,KAAK;QACjD,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,GAAG;KACvC,CAAC,CACH,CAAC;IAEF,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACvC,wEAAwE;IACxE,0DAA0D;IAC1D,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,EAAE,CACnC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IAEhD,uEAAuE;IACvE,0CAA0C;IAC1C,MAAM,WAAW,GAAG,QAAQ;SACzB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC;SACnC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QAClB,uEAAuE;QACvE,qDAAqD;QACrD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,6BAA6B;QACrE,yBAAyB,WAAW,CAAC,KAAK,CAAC,UAAW,CAAC,0BAA0B;QACjF,QAAQ;KACT,CAAC,CAAC;IAEL,uEAAuE;IACvE,0EAA0E;IAC1E,kEAAkE;IAClE,qCAAqC;IACrC,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAC5C,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAChC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,6EAA6E,CAAC,CAAC;YACtH,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO;YACL,YAAY,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK;YAC9D,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,qBAAqB,WAAW,CAAC,IAAI,CAAC,iBAAiB;SACnF,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEF,yEAAyE;IACzE,qEAAqE;IACrE,kBAAkB;IAClB,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAC7C,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,yBAAyB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAChF,CAAC;IAEF,uEAAuE;IACvE,mEAAmE;IACnE,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACjD,EAAE;QACF,sCAAsC;QACtC,2BAA2B;QAC3B,GAAG,UAAU;QACb,KAAK;QACL,GAAG;KACJ,CAAC;IACF,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAChD,EAAE;QACF,oCAAoC;QACpC,+BAA+B;QAC/B,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,MAAM,GAAG,KAAK,KAAK,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QACvG,GAAG;KACJ,CAAC;IAEF,OAAO;QACL,GAAG,gBAAgB,iBAAiB;QACpC,EAAE;QACF,sCAAsC;QACtC,8BAA8B;QAC9B,GAAG,aAAa;QAChB,KAAK;QACL,GAAG;QACH,EAAE;QACF,yCAAyC;QACzC,4BAA4B;QAC5B,GAAG,WAAW;QACd,KAAK;QACL,GAAG;QACH,GAAG,WAAW;QACd,GAAG,SAAS;QACZ,EAAE;QACF,YAAY;QACZ,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,qBAAqB,GAAG,mCAAmC,CAAC;AAClE,MAAM,YAAY,GAAG,yCAAyC,CAAC;AAE/D,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IAChE,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,IAAkB;IAClC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;QACnB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,IAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtE,SAAS,sBAAsB;YAC7B,OAAO,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,KAA4B;IACpD,MAAM,KAAK,GAAG;QACZ,kFAAkF;QAClF,uDAAuD;KACxD,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,IAAI,CAAC,MAAM,MAAM,CAAC,CAAC;QAE3C,mEAAmE;QACnE,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;QACjD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7B,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,CAAC;QAED,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CACrD,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,CAClD,EAAE,CAAC;YACF,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,KAAK,KAAK,CAAC,CAAC;YAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,UAAU,GACd,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,IAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBACvE,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,WAAW,KAAK,UAAU,GAAG,WAAW,GAAG,CAAC,CAAC;gBAClE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC"}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tulipes/cli",
-  "version": "0.2.0",
+  "version": "0.3.0-rc.2",
   "description": "The tulipes command line: scaffold, sync, inspect, describe and run Tulipes apps",
   "type": "module",
   "bin": {
@@ -19,12 +19,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@tulipes/core": "^0.11.0"
+    "@tulipes/core": "^0.12.0-rc.2"
   },
   "devDependencies": {
     "@types/node": "^24.2.0",
     "typescript": "^7.0.2",
-    "@tulipes/spec": "0.3.2"
+    "@tulipes/spec": "0.4.0-rc.2"
   },
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
     "url": "https://github.com/kemora13conf/bp-backend-express/issues"
   },
   "peerDependencies": {
-    "@tulipes/spec": "^0.3.2"
+    "@tulipes/spec": "^0.4.0-rc.1"
   },
   "peerDependenciesMeta": {
     "@tulipes/spec": {

package/templates/AGENTS.md

@@ -27,10 +27,12 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
 ## Non-negotiable rules
 
 1. **Never read `process.env` directly, and keep the environment small.**
-   A value is an environment variable only if boot needs it before the
+   A value is an environment value only if boot needs it before the
    database answers (connection strings, the port, log destination) or it
-   is a secret: declared under `tulipes.env` in the module's `package.json`, read with
-   `ctx.Environment.get("NAME")`. Everything else is a *setting*: declared
+   is a secret: declared under `tulipes.env` in the module's `package.json`
+   as `"name": { "key": "VARIABLE", … }`, read as
+   `ctx.config.<module>.<name>` — read-only, invisible to listings, beside
+   the module's settings. Everything else is a *setting*: declared
    with a zod schema in that module's `module.config.ts`, stored in the
    settings store (the `settings` collection here; a JSON file under
    `config/` in an app without the Mongo store), edited through the
@@ -52,9 +54,10 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
 5. **Run `pnpm sync` after touching a module's `tulipes.env`, a
    settings schema in `module.config.ts`, a model file or a queue file's
    `jobs` export.** It regenerates `types/tulipes.d.ts` and `.env.example`;
-   stale generated types are a lie. With it, `ctx.models.get("User")` is
-   typed from the model's schema and `queues.add("users.welcome", …)` from
-   the queue's job schema, so a wrong name or payload does not compile. `module.config.ts`
+   stale generated types are a lie. With it, `ctx.config.core.port` is a
+   `number`, `ctx.models.get("User")` is typed from the model's schema and
+   `queues.add("users.welcome", …)` from the queue's job schema, so a wrong
+   name or payload does not compile. `module.config.ts`
    has exactly one export, `defineConfig({ schema })`; initialization and
    cleanup belong to `bootstrap/*.bootstrap.ts`, which may return the
    function that closes what it opened, and long-lived work ends on
@@ -64,11 +67,14 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
    `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 on a nested router.
-   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`
+7. **Every route declares a RAI**: put `rai({ id: "users:bo:list" })` first
+   in each endpoint handler chain, including routes on a nested router.
+   The id is always `module:scope:resource[:extra]` — `users:mobile:profile`,
+   `users:bo:detail:delete` — where the scope is the surface it serves
+   (`web`, `bo`, …). It is also the ACL permission, and core refuses to boot
+   if a route is missing one or the id has another shape. Public is
+   `acl.allow("guest", "users:web:list")`, never a missing check.
+   → skills `tulipes-endpoint`, `tulipes-permissions`
 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
@@ -85,7 +91,7 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
     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 `config:write` and `settings:*` and make
+    `*` — a wildcard would reach `config:bo:write` and `settings:*` and make
     the sysadmin boundary a label rather than a rule. → skills
     `tulipes-config`, `tulipes-settings`
 13. **Cross-module imports use the package name** (`@app/users`,
@@ -106,19 +112,23 @@ require dedicated TEST_MONGO_URI and TEST_REDIS_URL services.
    never reach into another module's files from a test.
 
 For endpoint changes, read `tulipes-endpoint`: native routers live in
-`routes/*.routes.ts`, plain `(ctx) => Router` functions: build the router from
-the context, return it for the configured prefix, and read models, settings
-and the environment inside handlers, never while building — `tulipes routes`
-and `tulipes spec` build every router with nothing acquired. Global
-middleware that needs the environment is built on its first request with
-`lazy()` from `@app/core`.
+`routes/`, named scope-first — `routes/web.users.routes.ts`,
+`routes/bo.users.routes.ts`, and a folder per scope when one scope has
+several files (`routes/web/hello.greetings.routes.ts`); controllers mirror
+them (`controllers/bo.users.controllers.ts` exports `BoUsersController`).
+They are plain `(ctx) => Router` functions: build the router from
+the context, return it for the configured prefix, and read models and
+config inside handlers, never while building — `tulipes routes` and
+`tulipes spec` build every router with nothing acquired, and an environment
+value read while building throws. Global middleware that needs one is built
+on its first request with `lazy()` from `@app/core`.
 
 ## Where things go
 
 | Decision | Location |
 |---|---|
-| Connection string, secret, or anything boot needs before the database answers | `tulipes.env` in that module's `package.json` |
-| Policy shared by ≥2 modules and the same everywhere (pagination, locales) | `config/app.config.ts` |
+| Connection string, secret, or anything boot needs before the database answers | `tulipes.env` in that module's `package.json`, read at `ctx.config.<module>.<name>` |
+| Policy shared by ≥2 modules and the same everywhere (pagination, locales); wiring the environment to what core and the providers read (`server.port`, `mongoose.*`, `bullmq.redisUrl`) | `config/app.config.ts` |
 | A value an operator may change at runtime (limits, modes, toggles, lifetimes) | a field in that module's `module.config.ts` schema, read at `ctx.config.<module>` |
 | Opening a client, seeding rows, ensuring indexes, and closing them again | that module's `bootstrap/*.bootstrap.ts`, returning the cleanup |
 | A string a user will read | that module's `i18n/<locale>.json`, reached with `req.t` |
@@ -128,7 +138,7 @@ middleware that needs the environment is built on its first request with
 | Helper used by ≥2 modules | the sys core module, exported from its `lib/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` |
+| Anything you would `console.log` | `moduleLogger(ctx, "<module>")` from `@app/core` |
 
 ## Boot order (why load order matters)
 
@@ -145,11 +155,13 @@ luck.
 | `pnpm dev` | run the backend process (regenerates types first) |
 | `pnpm worker` | run the queue-consumer process |
 | `pnpm sync` | regenerate `types/tulipes.d.ts` + `.env.example` |
+| `pnpm tulipes routes [--scope s]` | every endpoint with the roles that reach it, offline |
+| `pnpm tulipes roles [--role r]` | every role with its description, extras and grants, offline |
 | `pnpm tulipes agent manifest [--role r]` | print every tool the app exposes to agents, offline |
 | `pnpm test` | every `tests/` and `modules/*/tests/` file; each boots the app once through `@tulipes/testing` |
-| `pnpm check` | validate the environment without booting |
+| `pnpm check` | resolve every environment value and show where it lands, without booting |
 | `pnpm typecheck` | typecheck the whole app |
-| `pnpm tulipes new module <name>` | scaffold a module |
+| `pnpm tulipes new module <name> [--scope s]` | scaffold a module (its first endpoint in scope `s`, default `web`) |
 | `tulipes update` | upgrade the global cli and the framework in every manifest |
 | `pnpm script scripts/x.ts` | run a one-off script against the real app |
 

package/templates/app/.envs/.env.development

@@ -1,7 +1,8 @@
 # Development. NOT committed — .gitignore excludes .envs/, because a
 # file holding working credentials does not belong in a repository.
 # The committed contract is .env.example at the root: copy it here and
-# fill it in. Real deployments inject variables through the container
+# fill it in. Each variable lands on one module's config — `pnpm check`
+# shows where. Real deployments inject variables through the container
 # environment, which always wins over this file.
 
 PORT=3000

package/templates/app/.envs/.env.production

@@ -5,8 +5,8 @@
 # The blanks below are intentional. Real deployments inject MONGO_URI,
 # REDIS_URL and any secret through the container environment, which
 # always wins over this file. Booting without them fails closed with a
-# report naming every missing variable — run `pnpm check` to see it
-# without starting the app.
+# report naming every missing variable — run `pnpm check` to see it,
+# and where each value lands, without starting the app.
 
 PORT=3000
 LOG_LEVEL=info

package/templates/app/.envs/.env.staging

@@ -5,8 +5,8 @@
 # The blanks below are intentional. Real deployments inject MONGO_URI,
 # REDIS_URL and any secret through the container environment, which
 # always wins over this file. Booting without them fails closed with a
-# report naming every missing variable — run `pnpm check` to see it
-# without starting the app.
+# report naming every missing variable — run `pnpm check` to see it,
+# and where each value lands, without starting the app.
 
 PORT=3000
 LOG_LEVEL=info

package/templates/app/README.md

@@ -10,9 +10,10 @@ pnpm install
 pnpm dev          # boot the backend process → http://localhost:3000/api/v1/hello
 ```
 
-Needs mongo and redis running — see `MONGO_URI` and `REDIS_URL` in
-`.envs/.env.development`. Run `pnpm worker` in a second terminal to
-consume queued jobs.
+Needs mongo and redis running — see `MONGO_URI` (or the `MONGO_HOST`,
+`MONGO_USERNAME`, `MONGO_PASSWORD` and `MONGO_DBNAME` parts) and
+`REDIS_URL` in `.envs/.env.development`. Run `pnpm worker` in a second
+terminal to consume queued jobs.
 
 `.envs/` is git-ignored: those files hold working credentials. On a
 fresh clone there is nothing in it, so copy `.env.example` — which is
@@ -23,7 +24,7 @@ declared variables — and fill it in:
 pnpm sync                              # refresh .env.example and types
 mkdir -p .envs                         # git does not track empty dirs
 cp .env.example .envs/.env.development
-pnpm check                             # validate it without booting
+pnpm check                             # resolve it without booting, and see where each value lands
 ```
 
 ## Verify
@@ -33,7 +34,8 @@ services: `TEST_MONGO_URI=mongodb://127.0.0.1:27017/tulipes_tests TEST_REDIS_URL
 Use test-only data: the suite creates users and sessions. `pnpm spec` writes
 OpenAPI/Postman documents offline, without services or runtime secrets.
 Change the shared API prefix in `config/routes.ts`. Runtime middleware stays
-with endpoints in `routes/*.routes.ts`, plain functions of the context.
+with endpoints in `routes/`, plain functions of the context, named
+scope-first (`routes/web.users.routes.ts`, `routes/bo.users.routes.ts`).
 Staging/production boot rejects development credentials and equal JWT keys.
 Auth, settings and deployment examples are application policy you own.
 
@@ -44,11 +46,11 @@ before writing your own:
 
 | File | Contract |
 |---|---|
-| `package.json` `tulipes.env` | the module's environment contract |
+| `package.json` `tulipes.env` | the module's environment values, read at `ctx.config.hello.<name>` (hello declares none) |
 | `module.config.ts` | `defineConfig({ schema })`: this module's settings |
-| `module.acl.ts` | permission grants on `hello:*` |
-| `routes/*.routes.ts` | native routers, shared middleware and RAI schemas |
-| `controllers/` | the work; constructed from the context while routes build |
+| `module.acl.ts` | permission grants on `hello:web:*` ids, with prefix wildcards |
+| `routes/web/*.routes.ts` | native routers, shared middleware and RAI schemas; one folder per scope |
+| `controllers/web/` | the work; constructed from the context while routes build |
 | `helpers/` | pure logic, no framework |
 | `i18n/<locale>.json` | this module's strings — the module is the namespace |
 | `sockets/*.sockets.ts` | a claimed Socket.IO namespace | <!-- feature:sockets -->
@@ -64,7 +66,9 @@ before writing your own:
 | `pnpm worker` | run the queue-consumer process (needs a queue first) | <!-- feature:queues -->
 | `pnpm sync` | regenerate `types/tulipes.d.ts` + `.env.example` |
 | `pnpm check` | validate env against every module contract — CI gate |
-| `pnpm tulipes new module <name>` | scaffold a module |
+| `pnpm tulipes new module <name>` | scaffold a module (`--scope bo` for the back office) |
+| `pnpm tulipes routes` | every endpoint and the roles that reach it (`--scope bo` for one surface) |
+| `pnpm tulipes roles` | every role, its description and the grants it holds |
 | `pnpm tulipes update` | upgrade the framework everywhere it is declared |
 
 ## Authentication
@@ -75,21 +79,29 @@ becomes the **guest** caller, which is what makes a public endpoint
 an ordinary ACL grant instead of a second mechanism:
 
 ```ts
-acl.allow("guest", "auth:login");   // that is why login is reachable
+acl.allow("guest", "auth:web:login");   // that is why login is reachable
 ```
 
 Guarding is the RAI itself — its `id` IS the permission, so there is
-no second call to forget. 401 means "sign in"; 403 means "signed in,
-still not allowed":
+no second call to forget. An id is always `module:scope:resource[:extra]`:
+`users:web:list`, `users:bo:list:deleted`. 401 means "sign in"; 403 means
+"signed in, still not allowed":
 
 ```ts
 router.get(
   `${base}/invoices`,
-  rai({ id: "invoices:read", name: "List invoices" }),
+  rai({ id: "billing:web:invoices", name: "List invoices" }),
   billing.list(),
 );
 ```
 
+Roles are defined once in `modules/auth/module.acl.ts`, each with a
+description and any extra the app reads back (`level` here):
+
+```ts
+acl.defineRole("admin", { description: "Runs the back office", level: 2 });
+```
+
 A route that declares no RAI would be reachable by guest, so core
 scans the router stack after mounting and refuses to boot when it
 finds one. Run `pnpm tulipes routes` to see every endpoint with the
@@ -139,8 +151,9 @@ TTL indexes.
 ## The console
 
 `modules/config` is the operator's console: `GET /api/v1/config`
-describes every module — manifest, declared variables (names, types and
-sources; a secret's value never), settings with their schema, live values
+describes every module — manifest, environment values (config name,
+variable, type and source; a secret's value never), settings with their
+schema, live values
 and stored version, endpoints with the roles that reach them — and
 `PATCH /api/v1/config/:module` changes a module's settings: validated by
 its schema, refused on a stale version, audited (names, never values)
@@ -149,7 +162,7 @@ writing needs `sysadmin`. Settings live in MongoDB (`settings` and
 `settings_history`) because the root `package.json` declares
 `@tulipes/mongoose/settings`; the request pipeline — proxy trust, CORS,
 HSTS, the body limit, the rate limits — is configured from
-`config.security` this way, so none of it is an environment variable.
+`config.security` this way, so none of it is an environment value.
 
 ## Logging
 
@@ -158,7 +171,7 @@ The logger lives in the core module and is shared by every other one:
 ```ts
 import { moduleLogger } from "@app/core";
 
-const log = moduleLogger(ctx.Environment, "billing", ctx.mode);
+const log = moduleLogger(ctx, "billing");
 log.info({ invoiceId }, "invoice sent");
 ```
 
@@ -173,9 +186,10 @@ Files carry the process mode — `app-backend.log`, `app-worker.log` —
 because backend and worker run at the same time and two processes
 rotating one file will race.
 
-The destinations are environment, because the logger exists before the
-settings store answers: `LOG_LEVEL`, `LOG_CONSOLE`, `LOG_FILE` and
-`LOG_DIR`, declared in `modules/core/package.json`. The file names and
+The destinations are environment values, because the logger exists before
+the settings store answers: `LOG_LEVEL`, `LOG_CONSOLE`, `LOG_FILE` and
+`LOG_DIR`, declared in `modules/core/package.json` and read as
+`config.core.logLevel`, `logConsole`, `logFile` and `logDir`. The file names and
 the rotation (daily or 20m, whichever trips first; fourteen rotated
 files kept) never needed to differ per deployment, so they are the
 `LOG_FILES` constants in `modules/core/helpers/logger/`. A `sysadmin`
@@ -268,8 +282,8 @@ redis hold the event loop open, so a script that forgets
 `nginx/{development,staging,production}.conf` are templates with
 `{{DOMAIN}}` and `{{PORT}}` placeholders. The deploy script renders
 the one matching `APP_ENV`, using that same environment's
-the `core.publicDomain` setting and `PORT`, so template, domain and port can never
-disagree:
+`core.publicDomain` setting and the port `config/app.config.ts` wired from
+`PORT`, so template, domain and port can never disagree:
 
 ```sh
 APP_ENV=production pnpm script scripts/deploy-nginx.ts --dry-run
@@ -309,12 +323,13 @@ PM2 remembers the environment a process was started with:
 
 `.envs/` holds one file per mode and is **git-ignored** — those files
 carry working credentials. What is committed is `.env.example`,
-generated by `pnpm sync`, naming every variable any module declares:
-a clone copies it into `.envs/.env.<mode>` and fills it in. Servers
-usually skip the file entirely and inject variables through the
-container environment, which always wins over it. `pnpm check`
-validates the current environment without booting, so a deploy can
-fail on configuration before it fails on traffic.
+generated by `pnpm sync`, naming every variable any module declares
+and the `config.<module>.<name>` it lands on: a clone copies it into
+`.envs/.env.<mode>` and fills it in. Servers usually skip the file
+entirely and inject variables through the container environment, which
+always wins over it. `pnpm check` resolves the current environment
+without booting, so a deploy can fail on configuration before it fails
+on traffic.
 
 PM2 is a devDependency so the scripts work straight after install;
 servers usually install it globally instead (`npm i -g pm2`), in