@cosmicdrift/kumiko-framework 0.369.0 → 0.371.0

package/agents/examples/env-composition.md

@@ -0,0 +1,278 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/env-composition. Do not edit. -->
+
+# env-composition
+
+Typed app env from the env blocks bundled features register, plus app-level blocks in extend.
+
+## README
+
+# Env composition
+
+Build the app's env schema from the blocks the mounted features register,
+instead of keeping a hand-written copy of every feature's variables.
+
+## What it shows
+
+- **Feature blocks**: `createSecretsFeature`, `createCryptoShreddingFeature`
+  and `createFileProviderS3Feature({ fromEnv: true })` register `secretsEnvSchema`,
+  `kmsEnvSchema` and `s3EnvSchema`. `composeEnvSchema` collects them and
+  records which feature declared each variable.
+- **App-level blocks in `extend`**: `buildInfoEnvSchema`, `demoAdminEnvSchema`,
+  `stripeEnvSchema({ prices })` and `createS3EnvSchema({ prefix })` for a
+  second bucket. These belong to no mounted feature, so the app adds them.
+- **Typed result**: `parseEnv(composed.schema, …)` returns the merged type,
+  so `parsed.S3_BUCKET` is `string | undefined` and `parsed.APP_PUBLIC_URL` is
+  `string` without a cast.
+- **Error report**: a missing required variable is listed with its source
+  (`secrets`, `app`, …).
+
+## Blocks
+
+| Block | Where it lives | Registered by |
+| --- | --- | --- |
+| `kmsEnvSchema` | `crypto-shredding` | `createCryptoShreddingFeature()` |
+| `smtpEnvSchema` | `channel-email` | `createChannelEmailFeature()` |
+| `s3EnvSchema`, `createS3EnvSchema({ prefix })` | `file-provider-s3` | `createFileProviderS3Feature({ fromEnv: true })` |
+| `stripeEnvSchema({ prices })` | `subscription-stripe` | app (`extend`); the feature registers the bridge keys |
+| `mfaTokenSecretsEnvSchema` | `auth-mfa` | `createAuthMfaFeature()` |
+| `buildInfoEnvSchema`, `demoAdminEnvSchema` | `foundation-shared` | app (`extend`) |
+| `prometheusMetricsEnvSchema` | `framework/observability` | app (`extend`) |
+
+## When to reach for it
+
+Every app that boots with `runProdApp`. Pass the composed schema as
+`envSchema` and read the parsed values instead of `process.env`.
+
+## Source files
+
+### src/__tests__/dry-run-boot.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { composeAppEnv } from "../env";
+
+const serverEntry = join(import.meta.dir, "..", "..", "bin", "server.ts");
+
+const completeValues = {
+  DATABASE_URL: "postgres://app@127.0.0.1:1/app",
+  REDIS_URL: "redis://127.0.0.1:1",
+  JWT_SECRET: "j".repeat(32),
+  KUMIKO_SECRETS_MASTER_KEY_V1: Buffer.alloc(32, 7).toString("base64"),
+  DEMO_ADMIN_EMAIL: "admin@example.com",
+  DEMO_SYSADMIN_EMAIL: "root@example.com",
+  APP_PUBLIC_URL: "https://app.example.com",
+};
+
+// The child gets only these variables, never the test runner's env, so a
+// DATABASE_URL on the CI host cannot leak into the "empty env" case.
+async function runBootDryRun(variables: Readonly<Record<string, string>>) {
+  const child = Bun.spawn([process.execPath, serverEntry], {
+    env: { PATH: process.env["PATH"] ?? "", KUMIKO_DRY_RUN_ENV: "boot", ...variables },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  return { stdout, stderr, exitCode };
+}
+
+function requiredVariableNames(): readonly string[] {
+  const { schema } = composeAppEnv();
+  return Object.entries(schema.shape)
+    .filter(([, field]) => !field.safeParse(undefined).success)
+    .map(([name]) => name);
+}
+
+describe("KUMIKO_DRY_RUN_ENV=boot", () => {
+  test("exits 0 on an empty env and lists every required variable as missing", async () => {
+    const { stdout, exitCode } = await runBootDryRun({});
+
+    expect(exitCode).toBe(0);
+    const required = requiredVariableNames();
+    expect(required).toContain("DATABASE_URL");
+    for (const name of [...required, "JWT_SECRET"]) {
+      expect(stdout).toMatch(new RegExp(`^\\s+${name}\\s+\\S+\\s+required\\s+missing$`, "m"));
+    }
+    expect(stdout).toContain("Feature wiring was NOT validated");
+  });
+
+  test("exits 0 on an empty env with NODE_ENV=production", async () => {
+    const { exitCode } = await runBootDryRun({ NODE_ENV: "production" });
+
+    expect(exitCode).toBe(0);
+  });
+
+  test("validates the wiring once every required variable is set", async () => {
+    const { stdout, exitCode } = await runBootDryRun(completeValues);
+
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("All variables present.");
+  });
+
+  test("rejects a keyring the master-key provider cannot use", async () => {
+    const { exitCode } = await runBootDryRun({
+      ...completeValues,
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+    });
+
+    expect(exitCode).toBe(1);
+  });
+
+  test("prints no value even when every variable is invalid", async () => {
+    const { schema } = composeAppEnv();
+    const leaking = Object.fromEntries(
+      Object.keys(schema.shape).map((name) => [name, `LEAK_${name}`]),
+    );
+    const { stdout, stderr, exitCode } = await runBootDryRun(leaking);
+
+    expect(exitCode).toBe(1);
+    expect(`${stdout}${stderr}`).not.toContain("LEAK_");
+  });
+
+  test("exits 1 on an invalid value and never prints it", async () => {
+    const endpoint = "http://s3.leak-check.example.com";
+    const { stdout, stderr, exitCode } = await runBootDryRun({
+      NODE_ENV: "production",
+      S3_ENDPOINT: endpoint,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toMatch(/S3_ENDPOINT\s+file-provider-s3-env\s+optional\s+invalid/);
+    expect(`${stdout}${stderr}`).not.toContain("leak-check");
+  });
+});
+```
+
+### src/__tests__/env.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { KumikoBootError, parseEnv } from "@cosmicdrift/kumiko-framework/env";
+import { composeAppEnv } from "../env";
+
+const masterKey = randomBytes(32).toString("base64");
+
+const minimalValidValues = {
+  DATABASE_URL: "postgres://app@localhost/app",
+  REDIS_URL: "redis://localhost:6379",
+  KUMIKO_SECRETS_MASTER_KEY_V1: masterKey,
+  DEMO_ADMIN_EMAIL: "admin@example.com",
+  DEMO_SYSADMIN_EMAIL: "root@example.com",
+  APP_PUBLIC_URL: "https://app.example.com",
+};
+
+describe("env composition", () => {
+  test("collects every block with the feature that declared it", () => {
+    const { sources } = composeAppEnv();
+
+    expect(sources["KUMIKO_SECRETS_MASTER_KEY_V1"]).toBe("secrets");
+    expect(sources["PLATFORM_KEK"]).toBe("crypto-shredding");
+    expect(sources["S3_BUCKET"]).toBe("file-provider-s3-env");
+    expect(sources["RELEASES_S3_BUCKET"]).toBe("app");
+    expect(sources["STRIPE_PRICE_PRO"]).toBe("app");
+  });
+
+  test("parses into a typed env", () => {
+    const composed = composeAppEnv();
+    const parsed = parseEnv(composed.schema, {
+      ...minimalValidValues,
+      S3_BUCKET: "uploads",
+      STRIPE_PRICE_PRO: "price_pro",
+    });
+
+    const bucket: string | undefined = parsed.S3_BUCKET;
+    const publicUrl: string = parsed.APP_PUBLIC_URL;
+    expect(bucket).toBe("uploads");
+    expect(publicUrl).toBe("https://app.example.com");
+    expect(parsed.KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION).toBe("1");
+  });
+
+  test("reports every missing required variable with its source", () => {
+    const composed = composeAppEnv();
+    let report = "";
+    try {
+      parseEnv(composed.schema, {}, { sources: composed.sources });
+    } catch (err) {
+      if (!(err instanceof KumikoBootError)) throw err;
+      report = err.format();
+    }
+
+    expect(report).toContain("DATABASE_URL (framework-core, required, missing)");
+    expect(report).toContain("KUMIKO_SECRETS_MASTER_KEY_V1 (secrets, required, missing)");
+    expect(report).toContain("DEMO_ADMIN_EMAIL (app, required, missing)");
+    expect(report).toContain("APP_PUBLIC_URL (app, required, missing)");
+    expect(report).not.toContain("S3_BUCKET");
+  });
+
+  test("rejects a remote http S3 endpoint in production", () => {
+    const composed = composeAppEnv();
+    const originalNodeEnv = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      expect(() =>
+        parseEnv(composed.schema, { ...minimalValidValues, S3_ENDPOINT: "http://s3.example.com" }),
+      ).toThrow(KumikoBootError);
+    } finally {
+      if (originalNodeEnv === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = originalNodeEnv;
+    }
+  });
+});
+```
+
+### src/env.ts
+
+```ts
+// Env Composition Sample
+// Shows: the app env schema is composed from the blocks the mounted features
+// register, plus app-level blocks in `extend`. The parsed env is typed from
+// those blocks, so no app keeps a hand-written twin of a feature's variables.
+
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createCryptoShreddingFeature } from "@cosmicdrift/kumiko-bundled-features/crypto-shredding";
+import { createFileFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/file-foundation";
+import {
+  createFileProviderS3Feature,
+  createS3EnvSchema,
+} from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import {
+  buildInfoEnvSchema,
+  demoAdminEnvSchema,
+} from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { stripeEnvSchema } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
+import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import * as z from "zod";
+
+export function createEnvCompositionFeatures() {
+  return [
+    createConfigFeature(),
+    createSecretsFeature(),
+    createCryptoShreddingFeature(),
+    createFileFoundationFeature(),
+    createFileProviderS3Feature({ fromEnv: true }),
+  ] as const;
+}
+
+// App-level blocks: none of these belong to a mounted feature, so they go
+// into extend. A second bucket reuses the S3 block under its own prefix.
+const appEnvSchema = z.object({
+  ...buildInfoEnvSchema.shape,
+  ...demoAdminEnvSchema.shape,
+  ...stripeEnvSchema({ prices: ["PRO", "TEAM"] }).shape,
+  ...createS3EnvSchema({ prefix: "RELEASES_S3_" }).shape,
+  APP_PUBLIC_URL: z.url().describe("Public origin of the app, used in mail links."),
+});
+
+export function composeAppEnv(
+  features: ReturnType<typeof createEnvCompositionFeatures> = createEnvCompositionFeatures(),
+) {
+  return composeEnvSchema({ core: frameworkCoreEnvSchema, features, extend: appEnvSchema });
+}
+```

package/agents/examples/host-routing.md

@@ -0,0 +1,181 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/host-routing. Do not edit. -->
+
+# host-routing
+
+createHostRoutingFeature + createHostDispatch — tenant per subdomain, per-host HTML and CSP, locale redirect, shared by runProdApp and the dev server.
+
+## README
+
+# Host Routing
+
+Tenant per subdomain with one options object for the API and the HTML pages.
+
+## What it shows
+
+- `createHostRoutingFeature(options)`: the Host header is the only source of the
+  anonymous tenant; a forged `X-Tenant` header answers `400 tenant_mismatch`.
+- `createHostDispatch(options)`: HTML file and CSP per host, a 404 page for
+  unknown shops, and `/de/...` redirecting to the unprefixed path.
+- The same `hostDispatch` goes into `runProdApp({ hostDispatch })`; the dev
+  server takes it through `toDevHostDispatch` from `@cosmicdrift/kumiko-dev-server`.
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/host-routing
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createAuthFoundationFeature,
+  resolveAnonymousAccessFromRegistry,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import {
+  configValuesTable,
+  createConfigFeature,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createTenantFeature,
+  tenantEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { seedTenant } from "@cosmicdrift/kumiko-bundled-features/tenant/seeding";
+import { createUserFeature, userEntity } from "@cosmicdrift/kumiko-bundled-features/user";
+import { createAnonymousUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-testing/stack";
+import { hostDispatch, hostRoutingFeature, routingOptions, storefrontFeature } from "../feature";
+
+const SHOPS = [
+  { id: "00000000-0000-4000-8000-0000000000b1" as TenantId, key: "acme", name: "Acme" },
+  { id: "00000000-0000-4000-8000-0000000000b2" as TenantId, key: "globex", name: "Globex" },
+  { id: "00000000-0000-4000-8000-0000000000b3" as TenantId, key: "initech", name: "Initech" },
+] as const;
+
+let stack: TestStack;
+
+const systemQuery = (type: string, payload: unknown, tenantId: TenantId) =>
+  stack.dispatcher.query(type, payload, createAnonymousUser(tenantId));
+
+function whoami(host: string, headers: Record<string, string> = {}) {
+  return stack.http.raw(
+    "POST",
+    "/api/query",
+    { type: "storefront:query:whoami", payload: {} },
+    { Host: host, ...headers },
+  );
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthFoundationFeature(),
+      hostRoutingFeature,
+      storefrontFeature,
+    ],
+    // The app opts into anonymous access; the routing feature supplies the
+    // resolver and existence check through the registry, as in runProdApp.
+    anonymousAccess: {},
+    enrichAnonymousAccess: (base, deps) => resolveAnonymousAccessFromRegistry(base, deps),
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+  for (const shop of SHOPS) await seedTenant(stack.db, shop);
+});
+
+afterAll(async () => stack?.cleanup());
+
+describe("host-routing recipe", () => {
+  test("three shop hosts land on three tenants", async () => {
+    for (const shop of SHOPS) {
+      const res = await whoami(`${shop.key}.${routingOptions.baseDomain}`);
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { data: { tenantId: string } };
+      expect(body.data.tenantId).toBe(shop.id);
+    }
+  });
+
+  test("a forged X-Tenant header is rejected", async () => {
+    const res = await whoami(`acme.${routingOptions.baseDomain}`, { "X-Tenant": SHOPS[1].id });
+    expect(res.status).toBe(400);
+  });
+
+  test("the page dispatch serves the shop shell with its CSP, or the 404 page", async () => {
+    expect(
+      await hostDispatch({ host: "globex.shop.test", path: "/", search: "" }, { systemQuery }),
+    ).toEqual({ kind: "html", file: "shop.html", csp: routingOptions.tenant.csp });
+    expect(
+      await hostDispatch({ host: "nope.shop.test", path: "/", search: "" }, { systemQuery }),
+    ).toEqual({ kind: "not-found", file: "unknown-shop.html" });
+  });
+
+  test("the default-locale prefix redirects, the English prefix gets its own file", async () => {
+    expect(
+      await hostDispatch({ host: "shop.test", path: "/de/about", search: "?a=1" }, { systemQuery }),
+    ).toEqual({ kind: "redirect", to: "/about?a=1", status: 301 });
+    expect(
+      await hostDispatch({ host: "shop.test", path: "/en/about", search: "" }, { systemQuery }),
+    ).toEqual({ kind: "html", file: "en/index.html" });
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Host routing: one options object drives both halves. The feature makes the
+// Host header the only source of the anonymous tenant; the dispatch picks the
+// HTML file per host for runProdApp's `hostDispatch` (and, through
+// toDevHostDispatch, for the dev server).
+
+import {
+  createHostDispatch,
+  createHostRoutingFeature,
+  type HostRoutingOptions,
+} from "@cosmicdrift/kumiko-bundled-features/host-routing";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const routingOptions: HostRoutingOptions = {
+  tenantBy: "host",
+  baseDomain: "shop.test",
+  apex: { file: "index.html", localeFiles: { en: "en/index.html" } },
+  tenant: { file: "shop.html", csp: "default-src 'self'; frame-ancestors 'none'" },
+  unknownTenant: { file: "unknown-shop.html" },
+  locales: { default: "de", prefixed: ["en"] },
+};
+
+export const hostRoutingFeature = createHostRoutingFeature(routingOptions);
+export const hostDispatch = createHostDispatch(routingOptions);
+
+// A public query that reports which tenant the request landed on.
+export const storefrontFeature = defineFeature("storefront", (r) => {
+  r.queryHandler({
+    name: "whoami",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    handler: async (query) => ({ tenantId: query.user.tenantId }),
+  });
+});
+```

package/agents/examples/inbound-mail-triage.md

@@ -237,7 +237,7 @@ describe("inbound-mail triage sample", () => {
     } finally {
       await entry.stop();
     }
-  }, 30_000);
+  });
 });
 ```
 

package/agents/examples/legal-pages.md

@@ -71,6 +71,7 @@ import { createLegalPagesFeature } from "@cosmicdrift/kumiko-bundled-features/le
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 
 await runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   features: [
     createTemplateResolverFeature(),
     createLegalPagesFeature(),
@@ -151,6 +152,20 @@ await seedTextBlock(db, {
 → Templates for full legally-sound texts: e-recht24.de
 or datenschutz-generator.de by Dr. Schwenke.
 
+With `runProdApp` the same blocks can come from a JSON file on every boot.
+`legalContentSeed` updates existing blocks, so the file stays authoritative:
+
+```typescript illustration
+import legalContent from "./legal-content.json" with { type: "json" };
+import { legalContentSeed } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
+
+runProdApp({ /* ... */ seeds: [legalContentSeed({ blocks: legalContent })] });
+```
+
+The recipe mounts `createLegalPagesFeature({ terms: true, wrapLayout })`, so it
+also serves `/legal/nutzungsbedingungen` and `/legal/terms`, and wraps every
+page in `createLegalPagesLayout({ siteName })`.
+
 ### 4. Visit the pages
 
 After the seed these URLs are immediately live:
@@ -216,6 +231,7 @@ from SYSTEM_TENANT:
 
 ```ts
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { legalContentSeed } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
 import {
   createTemplateResolverApi,
   templateResourceEntity,
@@ -229,7 +245,12 @@ import {
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-testing/stack";
-import { LEGAL_ROUTES, legalPagesFeature, templateResolverFeature } from "../feature";
+import {
+  LEGAL_ROUTES,
+  LEGAL_TERMS_ROUTES,
+  legalPagesFeature,
+  templateResolverFeature,
+} from "../feature";
 
 let stack: TestStack;
 let db: DbConnection;
@@ -334,6 +355,23 @@ describe("legal-pages sample", () => {
     const res = await stack.app.request("/legal/impressum");
     expect(res.headers.get("cache-control")).toBe("public, max-age=60, must-revalidate");
   });
+
+  test("terms from legalContentSeed render in both languages inside the app layout", async () => {
+    await legalContentSeed({
+      blocks: [
+        { slug: "terms", locale: "de", title: "Nutzungsbedingungen", content: "## Geltung" },
+        { slug: "terms", locale: "en", title: "Terms of Service", content: "## Scope" },
+      ],
+    })({ db });
+    const expected = { de: "<h2>Geltung</h2>", en: "<h2>Scope</h2>" } as const;
+    for (const route of LEGAL_TERMS_ROUTES) {
+      const res = await stack.app.request(route.path);
+      expect(res.status).toBe(200);
+      const body = await res.text();
+      expect(body).toContain(expected[route.lang]);
+      expect(body).toContain("· Sample App</title>");
+    }
+  });
 });
 ```
 
@@ -377,8 +415,10 @@ describe("legal-pages sample", () => {
 
 import {
   createLegalPagesFeature,
+  createLegalPagesLayout,
   LEGAL_REQUIRED_BLOCKS,
   LEGAL_ROUTES,
+  LEGAL_TERMS_ROUTES,
 } from "@cosmicdrift/kumiko-bundled-features/legal-pages";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 
@@ -386,8 +426,17 @@ import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-featu
 // requires sie. r.requires({ features: ["template-resolver"] }) greift automatisch im
 // legal-pages-Feature.
 export const templateResolverFeature = createTemplateResolverFeature();
-export const legalPagesFeature = createLegalPagesFeature();
+// `terms: true` adds the opt-in terms routes; the layout puts the app's chrome
+// around every legal page.
+export const legalPagesFeature = createLegalPagesFeature({
+  terms: true,
+  wrapLayout: createLegalPagesLayout({
+    siteName: "Sample App",
+    footerHtml: (lang) =>
+      lang === "de" ? "<footer>Sample App</footer>" : "<footer>Sample App (en)</footer>",
+  }),
+});
 
 // Re-exports für Tests + andere Demos
-export { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES };
+export { LEGAL_REQUIRED_BLOCKS, LEGAL_ROUTES, LEGAL_TERMS_ROUTES };
 ```

package/agents/examples/managed-config.md

@@ -77,6 +77,7 @@ const masterKeyProvider = createEnvMasterKeyProvider({ env: process.env });
 const resolver = createConfigResolver();
 
 await runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   extraContext: ({ db, registry }) => ({
     configResolver: resolver,
     _configAccessorFactory: createConfigAccessorFactory(registry, resolver),

package/agents/examples/managed-pages.md

@@ -61,6 +61,7 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
 
 await runProdApp({
+  envSchema, // composeEnvSchema({ core: frameworkCoreEnvSchema, features })
   features: [
     createManagedPagesFeature({
       // Host → tenantId. Single-tenant returns a constant; multi-tenant maps