@cosmicdrift/kumiko-dev-server 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # @cosmicdrift/kumiko-dev-server
 
+## 0.13.0
+
+### Minor Changes
+
+- 7bd5c88: `KUMIKO_DRY_RUN_ENV=boot` mode for runProdApp — runs env-validation +
+  composeFeatures + validateBoot + createRegistry without DB/Redis
+  connect, exits with status 0 on success. Used by the
+  `samples/apps/use-all-bundled` smoke-app (Sprint 9.8 Phase C / Empfehlung
+  1 / canonical bug-catcher) and downstream by enterprise's
+  `use-all-features` mirror. Render-modes (human|json|pulumi|k8s|1)
+  behavior unchanged.
+- 575752f: `scaffoldAppFeature` + `kumiko add feature <name>` — DX-2 aus DX-Roadmap.
+  Scaffolded ein neues Feature in `src/features/<name>/` einer bereits via
+  `kumiko new app` scaffolded App + **auto-mountet** es in `src/run-config.ts`
+  via ts-morph (import + `APP_FEATURES`-array-entry, idempotent).
+
+  User-Promise "defineFeature → nichts woanders eintragen" erfüllt für die
+  run-config-Seite. FEATURE_IMPORT_REGISTRY in drizzle/generate.ts ist
+  DX-4's Refactor — bei DX-1+DX-2-App noch nicht vorhanden.
+
+  Usage (in einer DX-1-gescaffoldeten App):
+
+  ```sh
+  bunx kumiko add feature product-catalog
+  # → src/features/product-catalog/{feature.ts,index.ts}
+  # → src/run-config.ts auto-edited: import + APP_FEATURES-entry
+  ```
+
+- 3d5e9ef: `kumiko-schema-check` CLI — Empfehlung 3 aus Sprint-9.8-Retro
+  (`luminous-watching-moler.md`). Diff't APP_FEATURES (runtime, aus
+  `src/run-config.ts`) gegen FEATURE_IMPORT_REGISTRY (statisch, aus
+  `drizzle/generate.ts`). Fängt Studio's 9.8-Drama: registry 18 features
+  hinter APP_FEATURES → migrations fehlten für mounted features.
+
+  Usage (im app-workspace):
+
+  ```sh
+  bunx kumiko-schema-check
+  # or with custom paths:
+  bunx kumiko-schema-check --run-config src/run-config.ts --generate drizzle/generate.ts
+  ```
+
+  Plus: 5 bundled-features hatten camelCase feature-names statt kebab-case
+  (Memory `feedback_kebab_aggregates`) — aufgedeckt durch den schema-check
+  gegen use-all-bundled. Fix: `channelEmail` → `channel-email`,
+  `channelInApp` → `channel-in-app`, `channelPush` → `channel-push`,
+  `rateLimiting` → `rate-limiting`, `rendererSimple` → `renderer-simple`.
+
+  Plus `CHANNEL_IN_APP_FEATURE` und `RATE_LIMITING_FEATURE` Konstanten
+  angepasst (waren intern auf camelCase, jetzt kebab-case).
+
+- 46b84d0: `scaffoldApp` + `kumiko new app <name>` — DX-1.0 aus DX-Roadmap. Generiert
+  ein lauffähiges App-Skelett (package.json, tsconfig, run-config mit
+  secrets+sessions, bin/main.ts mit auth-admin-stub + deterministische
+  tenant-UUID, .env.example, README) in `<cwd>/<name>/`.
+
+  Boot-Pfad: `KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts` läuft ohne DB/Redis.
+
+  Held-back für spätere DX-Phasen: drizzle-setup (DX-1.1, blocked-by DX-4
+  auto-registry), Dockerfile (existing `kumiko init-deploy`), first feature
+  scaffold (existing `kumiko create` bzw. DX-2 `kumiko add feature`).
+
+  Usage:
+
+  ```sh
+  bunx kumiko new app my-shop
+  cd my-shop && yarn install
+  cp .env.example .env  # JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1 setzen
+  bun run boot          # → boot validation OK
+  ```
+
+### Patch Changes
+
+- 2bd60c1: `buildServerBundle` BUILD_ONLY_EXTERNALS erweitert um drizzle-kit's
+  dialect-resolver dynamic-imports: `@planetscale/database`, `@libsql/client`,
+  `better-sqlite3`, `@neondatabase/serverless`, `@vercel/postgres`, `mysql2`.
+
+  Aufgedeckt durch C1 Empfehlung 4 (bundle-smoke). Bisher schlug
+  `bun build` an dynamic-imports im drizzle-kit auch wenn der App nur
+  postgres nutzt. Externalisieren = build durchläuft + tree-shake wirft
+  die ungenutzten driver-modules eh raus.
+
+- 8bfb284: Dockerfile.template setzt `YARN_ENABLE_SCRIPTS=false` im Build-Stage. Fixt msgpackr-extract native-build-Failures (ARM, CI) und generell jeden transitiven Native-Dep — der Build-Stage bundlet nur JS via `bun build`, Runtime-Native-Deps werden separat im Runtime-Stage via `bun install --production` installiert. Apps die bisher per-package-Workarounds via `dependenciesMeta.<pkg>.built=false` in der App-package.json brauchten (studio, enterprise) können diese Entries nach Upgrade auf diese dev-server-Version entfernen.
+- cc0ddc0: `Dockerfile.template` emits an inline `start.sh` for createBunServer command-override target.
+
+  `infra/pulumi/bun-server.ts`'s `createBunServer` overrides the container command with `exec ./start.sh` after injecting DATABASE_URL from the init-container. Apps deployed via createBunServer crashed with `./start.sh: not found` until each one added a per-app `start.sh` in repo root (= studio's PR #22).
+
+  Now the Dockerfile-template emits the file inline (`RUN printf … > ./start.sh && chmod +x`). Apps no longer need to ship one — the runtime stage generates it. Apps that don't go through createBunServer's command-override still boot via the bottom CMD; start.sh is dead-code in that case.
+
+- Updated dependencies [7f56b2f]
+- Updated dependencies [68b8118]
+- Updated dependencies [9121928]
+- Updated dependencies [72518fa]
+- Updated dependencies [0a00e7b]
+- Updated dependencies [aca1443]
+- Updated dependencies [c6cb96c]
+- Updated dependencies [3d5e9ef]
+  - @cosmicdrift/kumiko-framework@0.13.0
+  - @cosmicdrift/kumiko-bundled-features@0.13.0
+
+## 0.12.2
+
+### Patch Changes
+
+- Updated dependencies [597de52]
+  - @cosmicdrift/kumiko-framework@0.12.2
+  - @cosmicdrift/kumiko-bundled-features@0.12.2
+
 ## 0.12.1
 
 ### Patch Changes

package/bin/kumiko-schema-check.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+// biome-ignore-all lint/suspicious/noConsole: CLI-Script, console ist Feature.
+//
+// kumiko schema check — Empfehlung 3 aus Sprint-9.8-Retro
+// (luminous-watching-moler.md). Diff't APP_FEATURES (runtime, aus
+// `src/run-config.ts`) gegen FEATURE_IMPORT_REGISTRY (statisch, aus
+// `drizzle/generate.ts`). Catches:
+//
+//   1. Mount-without-registry: ein neues feature in APP_FEATURES ohne
+//      Entry in FEATURE_IMPORT_REGISTRY. Resultiert in Schema-Drift:
+//      Runtime mountet feature, Migration kennt seine Tabellen nicht.
+//   2. Stale-registry: ein Entry in FEATURE_IMPORT_REGISTRY ohne
+//      matching mount in APP_FEATURES. Dead-code; im Schema entsteht
+//      eine Tabelle ohne Runtime-Konsument.
+//
+// Studio's 9.8-Drama: FEATURE_IMPORT_REGISTRY war 18 features hinter
+// APP_FEATURES. Hätte mit diesem check eine Sekunde Lokal gefangen.
+//
+// Usage (aus dem app-workspace):
+//   bunx kumiko-schema-check
+//   # oder mit explicit pfaden:
+//   bunx kumiko-schema-check --run-config src/run-config.ts --generate drizzle/generate.ts
+//
+// Exit 0 wenn alles in sync, exit 1 wenn drift.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+type Args = {
+  readonly runConfigPath: string;
+  readonly generatePath: string;
+};
+
+function parseArgs(argv: readonly string[]): Args {
+  const cwd = process.cwd();
+  let runConfigPath = resolve(cwd, "src/run-config.ts");
+  let generatePath = resolve(cwd, "drizzle/generate.ts");
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (flag === "--run-config" && value) {
+      runConfigPath = resolve(cwd, value);
+      i++;
+    } else if (flag === "--generate" && value) {
+      generatePath = resolve(cwd, value);
+      i++;
+    }
+  }
+  return { runConfigPath, generatePath };
+}
+
+function readRegistryFeatures(generateSrc: string): Set<string> {
+  // Match object-keys mit Discriminator `kind: "factory" | "named"`.
+  // Quoted ("billing-foundation") oder unquoted (config, user) — beides
+  // ist gültig in JS. Pattern aus use-all-bundled/scripts/check-coverage.ts
+  // dupliziert hier weil per-app-CLI nicht von sample-script lesen darf.
+  const re = /(?:"([a-z][a-z0-9-]*)"|([a-z][a-z0-9]*)):\s*\{\s*kind:\s*"(factory|named)"/g;
+  const out = new Set<string>();
+  for (const m of generateSrc.matchAll(re)) {
+    const name = m[1] ?? m[2];
+    if (name) out.add(name);
+  }
+  return out;
+}
+
+async function readMountedFeatures(runConfigPath: string): Promise<Set<string>> {
+  const mod = (await import(runConfigPath)) as {
+    APP_FEATURES?: ReadonlyArray<{ name: string }>;
+    HAS_AUTH?: boolean;
+  };
+  if (!mod.APP_FEATURES) {
+    throw new Error(
+      `kumiko-schema-check: ${runConfigPath} hat kein 'APP_FEATURES' export. ` +
+        `Convention: 'export const APP_FEATURES = [...] as const'.`,
+    );
+  }
+  // composeFeatures auto-prepends config + user + tenant + auth-email-
+  // password im auth-mode. Wenn HAS_AUTH=true (oder default), die 4
+  // implicit-mounted features auch in die Set tun damit der Diff nicht
+  // false-positive "auth-email-password is mounted but no registry-entry"
+  // produziert. Studio/use-all-bundled HAS_AUTH=true ist convention.
+  const set = new Set<string>();
+  for (const f of mod.APP_FEATURES) {
+    set.add(f.name);
+  }
+  if (mod.HAS_AUTH ?? true) {
+    set.add("config");
+    set.add("user");
+    set.add("tenant");
+    set.add("auth-email-password");
+  }
+  return set;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!existsSync(args.runConfigPath)) {
+    console.error(`✗ run-config not found: ${args.runConfigPath}`);
+    process.exit(1);
+  }
+  if (!existsSync(args.generatePath)) {
+    console.error(`✗ generate not found: ${args.generatePath}`);
+    process.exit(1);
+  }
+
+  const registry = readRegistryFeatures(readFileSync(args.generatePath, "utf-8"));
+  const mounted = await readMountedFeatures(args.runConfigPath);
+
+  // Mounted but not in registry → schema-drift (runtime ↔ migration mismatch).
+  const mountedWithoutEntry: string[] = [];
+  for (const name of mounted) {
+    if (!registry.has(name)) mountedWithoutEntry.push(name);
+  }
+  // In registry but not mounted → stale entry (dead schema-mapping).
+  const staleEntries: string[] = [];
+  for (const name of registry) {
+    if (!mounted.has(name)) staleEntries.push(name);
+  }
+
+  let ok = true;
+
+  if (mountedWithoutEntry.length > 0) {
+    console.error(
+      `\n✗ ${mountedWithoutEntry.length} feature(s) mounted in APP_FEATURES but NOT in FEATURE_IMPORT_REGISTRY:`,
+    );
+    for (const name of mountedWithoutEntry.sort()) {
+      console.error(`   - ${name}`);
+    }
+    console.error(
+      "\n  Action: in drizzle/generate.ts FEATURE_IMPORT_REGISTRY den Eintrag ergänzen,",
+    );
+    console.error("  damit Schema-Generator + Migration die feature-Tabellen kennt.");
+    ok = false;
+  }
+
+  if (staleEntries.length > 0) {
+    console.error(
+      `\n✗ ${staleEntries.length} stale FEATURE_IMPORT_REGISTRY entry/entries (kein matching mount):`,
+    );
+    for (const name of staleEntries.sort()) {
+      console.error(`   - ${name}`);
+    }
+    console.error("\n  Action: entry aus drizzle/generate.ts FEATURE_IMPORT_REGISTRY entfernen,");
+    console.error("  oder das feature in src/run-config.ts mounten.");
+    ok = false;
+  }
+
+  if (ok) {
+    console.log(
+      `✓ schema check: ${mounted.size} mounted ↔ ${registry.size} registry entries, no drift`,
+    );
+    process.exit(0);
+  } else {
+    process.exit(1);
+  }
+}
+
+await main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Development server bootstrap for Kumiko apps. Bundles the client, mints dev-JWTs, injects the resolved AppSchema, and seeds an admin. Not for production.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -45,11 +45,12 @@
   },
   "bin": {
     "kumiko-build": "./bin/kumiko-build.ts",
-    "kumiko-dev": "./bin/kumiko-dev.ts"
+    "kumiko-dev": "./bin/kumiko-dev.ts",
+    "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.12.1",
-    "@cosmicdrift/kumiko-framework": "0.12.1"
+    "@cosmicdrift/kumiko-bundled-features": "0.13.0",
+    "@cosmicdrift/kumiko-framework": "0.13.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/__tests__/env-schema.integration.ts

@@ -182,4 +182,54 @@ describe("runProdApp envSchema integration", () => {
       console.log = realLog;
     }
   });
+
+  it("KUMIKO_DRY_RUN_ENV=boot runs validators + exits before DB-connect", async () => {
+    const logs: string[] = [];
+    const realLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    try {
+      const handle = await runProdApp({
+        features: [secretsFeature, authFeature],
+        envSchema: composed,
+        envSource: {
+          KUMIKO_DRY_RUN_ENV: "boot",
+          KUMIKO_SECRETS_MASTER_KEY_V1: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          JWT_SECRET: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          STUDIO_ADMIN_EMAIL: "ops@example.com",
+          DATABASE_URL: "postgres://dummy:dummy@127.0.0.1:1/dummy",
+          REDIS_URL: "redis://127.0.0.1:1",
+        },
+        migrations: false,
+      });
+      expect(logs.join("\n")).toContain("boot validation OK");
+      expect(handle).toBeDefined();
+    } finally {
+      console.log = realLog;
+    }
+  });
+
+  it("KUMIKO_DRY_RUN_ENV=boot still aggregates env-errors before exit", async () => {
+    let captured: KumikoBootError | undefined;
+    try {
+      await runProdApp({
+        features: [secretsFeature, authFeature],
+        envSchema: composed,
+        envSource: {
+          KUMIKO_DRY_RUN_ENV: "boot",
+          JWT_SECRET: "short",
+          STUDIO_ADMIN_EMAIL: "not-an-email",
+        },
+        bootErrorReporter: (err) => {
+          captured = err;
+          throw err;
+        },
+      });
+    } catch (err) {
+      expect(err).toBeInstanceOf(KumikoBootError);
+    }
+    expect(captured).toBeDefined();
+    expect(captured!.errors.length).toBeGreaterThanOrEqual(3);
+  });
 });

package/src/__tests__/scaffold-app-feature.test.ts

@@ -0,0 +1,88 @@
+// scaffoldAppFeature unit-tests (DX-2).
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { scaffoldApp } from "../scaffold-app";
+import { scaffoldAppFeature } from "../scaffold-app-feature";
+
+describe("scaffoldAppFeature", () => {
+  let tmp: string;
+  let appRoot: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "scaffold-app-feature-"));
+    appRoot = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: appRoot });
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("scaffolds src/features/<name>/feature.ts + index.ts", () => {
+    const result = scaffoldAppFeature({ name: "product-catalog", appRoot });
+    expect(result.featureName).toBe("product-catalog");
+    expect(result.files).toEqual([
+      "src/features/product-catalog/feature.ts",
+      "src/features/product-catalog/index.ts",
+    ]);
+    expect(existsSync(join(appRoot, "src/features/product-catalog/feature.ts"))).toBe(true);
+    expect(existsSync(join(appRoot, "src/features/product-catalog/index.ts"))).toBe(true);
+  });
+
+  test("feature.ts uses kebab-name + camelCase variable", () => {
+    scaffoldAppFeature({ name: "product-catalog", appRoot });
+    const feature = readFileSync(join(appRoot, "src/features/product-catalog/feature.ts"), "utf-8");
+    expect(feature).toContain(`defineFeature("product-catalog"`);
+    expect(feature).toContain("export const productCatalogFeature");
+    expect(feature).toContain('r.entity("product-catalog-item"');
+  });
+
+  test("auto-mounts in src/run-config.ts (import + APP_FEATURES entry)", () => {
+    const result = scaffoldAppFeature({ name: "product-catalog", appRoot });
+    expect(result.autoMounted).toBe(true);
+    const runConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
+    expect(runConfig).toContain(
+      `import { productCatalogFeature } from "./features/product-catalog";`,
+    );
+    expect(runConfig).toContain("productCatalogFeature");
+    // APP_FEATURES still ends with `as const`
+    expect(runConfig).toMatch(/\]\s*as const;/);
+  });
+
+  test("idempotent: re-mount of existing feature is a no-op", () => {
+    scaffoldAppFeature({ name: "product-catalog", appRoot });
+    const firstRunConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
+    // Now re-mount (second feature creates dir-already-exists error;
+    // we instead simulate "feature dir exists, only run-config dance").
+    // → Real DX-2 flow: scaffold fails on dir-exists; manual remount
+    //   would call mountInRunConfig directly. Test the mount-side
+    //   idempotency by triggering a second feature with a different
+    //   name and asserting the first import stays exactly once.
+    scaffoldAppFeature({ name: "billing", appRoot });
+    const secondRunConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
+    expect(secondRunConfig).toContain("productCatalogFeature");
+    expect(secondRunConfig).toContain("billingFeature");
+    // Count: each feature-import appears exactly once.
+    const occurrences = secondRunConfig.match(/productCatalogFeature/g) ?? [];
+    expect(occurrences.length).toBe(2); // 1 import + 1 array-entry
+    expect(firstRunConfig.length).toBeLessThan(secondRunConfig.length);
+  });
+
+  test("rejects non-kebab-case", () => {
+    expect(() => scaffoldAppFeature({ name: "ProductCatalog", appRoot })).toThrow(/kebab-case/);
+    expect(() => scaffoldAppFeature({ name: "product_catalog", appRoot })).toThrow(/kebab-case/);
+  });
+
+  test("refuses to overwrite existing feature dir", () => {
+    scaffoldAppFeature({ name: "billing", appRoot });
+    expect(() => scaffoldAppFeature({ name: "billing", appRoot })).toThrow(/already exists/);
+  });
+
+  test("autoMounted=false when run-config.ts is missing", () => {
+    const emptyRoot = join(tmp, "no-app");
+    expect(() => scaffoldAppFeature({ name: "foo", appRoot: emptyRoot })).not.toThrow();
+    const result = scaffoldAppFeature({ name: "bar", appRoot: emptyRoot });
+    expect(result.autoMounted).toBe(false);
+  });
+});

package/src/__tests__/scaffold-app.test.ts

@@ -0,0 +1,104 @@
+// scaffoldApp unit-tests (DX-1.0).
+
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { scaffoldApp } from "../scaffold-app";
+
+describe("scaffoldApp", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "scaffold-app-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("scaffolds 6 files into <cwd>/<name>", () => {
+    const dest = join(tmp, "my-shop");
+    const result = scaffoldApp({ name: "my-shop", destination: dest });
+
+    expect(result.appName).toBe("my-shop");
+    expect(result.destination).toBe(dest);
+    expect(result.files).toEqual([
+      "package.json",
+      "tsconfig.json",
+      "src/run-config.ts",
+      "bin/main.ts",
+      ".env.example",
+      "README.md",
+    ]);
+    for (const f of result.files) {
+      expect(existsSync(join(dest, f))).toBe(true);
+    }
+  });
+
+  test("package.json has @cosmicdrift/* deps with version pin", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: dest, frameworkVersion: "^0.13.0" });
+
+    const pkg = JSON.parse(readFileSync(join(dest, "package.json"), "utf-8")) as {
+      name: string;
+      dependencies: Record<string, string>;
+      scripts: Record<string, string>;
+    };
+    expect(pkg.name).toBe("my-shop");
+    expect(pkg.dependencies["@cosmicdrift/kumiko-bundled-features"]).toBe("^0.13.0");
+    expect(pkg.dependencies["@cosmicdrift/kumiko-dev-server"]).toBe("^0.13.0");
+    expect(pkg.dependencies["@cosmicdrift/kumiko-framework"]).toBe("^0.13.0");
+    expect(pkg.scripts["boot"]).toContain("KUMIKO_DRY_RUN_ENV=boot");
+  });
+
+  test("bin/main.ts contains runProdApp + auth.admin stub", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: dest });
+
+    const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
+    expect(main).toContain("runProdApp");
+    expect(main).toContain("auth: {");
+    expect(main).toContain("admin@my-shop.local");
+    expect(main).toContain('tenantKey: "my-shop"');
+    // Tenant-ID is a valid UUID-v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx).
+    expect(main).toMatch(/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/);
+  });
+
+  test("src/run-config.ts mounts secrets + sessions as foundation", () => {
+    const dest = join(tmp, "my-shop");
+    scaffoldApp({ name: "my-shop", destination: dest });
+
+    const runConfig = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
+    expect(runConfig).toContain("createSecretsFeature()");
+    expect(runConfig).toContain("createSessionsFeature()");
+    expect(runConfig).toContain("export const APP_FEATURES");
+  });
+
+  test("rejects non-kebab-case names", () => {
+    expect(() => scaffoldApp({ name: "MyShop", destination: tmp })).toThrow(/kebab-case/);
+    expect(() => scaffoldApp({ name: "my_shop", destination: tmp })).toThrow(/kebab-case/);
+    expect(() => scaffoldApp({ name: "0shop", destination: tmp })).toThrow(/kebab-case/);
+  });
+
+  test("refuses to overwrite existing destination", () => {
+    const dest = join(tmp, "existing");
+    scaffoldApp({ name: "existing", destination: dest });
+    expect(() => scaffoldApp({ name: "existing", destination: dest })).toThrow(/already exists/);
+  });
+
+  test("deterministic tenantId for same name (reproducible boots)", () => {
+    const a = join(tmp, "a");
+    const b = join(tmp, "b");
+    scaffoldApp({ name: "stable", destination: a });
+    scaffoldApp({ name: "stable", destination: b });
+    const mainA = readFileSync(join(a, "bin/main.ts"), "utf-8");
+    const mainB = readFileSync(join(b, "bin/main.ts"), "utf-8");
+    const uuidA = mainA.match(
+      /[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/,
+    )?.[0];
+    const uuidB = mainB.match(
+      /[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/,
+    )?.[0];
+    expect(uuidA).toBeDefined();
+    expect(uuidA).toBe(uuidB);
+  });
+});

package/src/__tests__/scaffold-deploy.test.ts

@@ -56,6 +56,17 @@ describe("scaffoldDeploy", () => {
     expect(migrate).toContain("ghcr.io/cosmicdriftgamestudio/minimal:latest");
   });
 
+  it("Dockerfile emits inline start.sh (createBunServer command-override target)", () => {
+    scaffoldDeploy({ appName: "boot-target", destination: tmp });
+    const dockerfile = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
+    // Inline RUN that creates a start.sh inside the runtime image.
+    // bun-server.ts's createBunServer overrides the container command with
+    // `exec ./start.sh` after injecting DATABASE_URL; without this line the
+    // pod exited 127. Memory: `feedback_audit_drift_root_cause_now`.
+    expect(dockerfile).toContain("> ./start.sh && chmod +x ./start.sh");
+    expect(dockerfile).toContain("exec bun run server.js");
+  });
+
   it("skips existing files by default", () => {
     const existing = join(tmp, "deploy");
     scaffoldDeploy({ appName: "first", destination: tmp });
@@ -140,6 +151,7 @@ describe("scaffoldDeploy", () => {
       const df = readFileSync(join(tmp, "deploy", "Dockerfile"), "utf-8");
       expect(df).toContain("ARG GITHUB_TOKEN=");
       expect(df).toContain("ARG GITHUB_TOKEN\n");
+      // biome-ignore lint/suspicious/noTemplateCurlyInString: shell variable expansion, not a JS template
       expect(df).toContain("ENV GITHUB_TOKEN=${GITHUB_TOKEN}");
     });
 

package/src/build-server-bundle.ts

@@ -82,7 +82,25 @@ const RUNTIME_EXTERNALS = [
 // Markierung scheitert bun build an dynamic-imports (z.B. drizzle-kit →
 // @libsql/client). Tree-Shake wirft sie eh aus dem Bundle — der Marker
 // schaltet nur das resolution-during-build ab. NICHT in runtime-deps.
-const BUILD_ONLY_EXTERNALS = ["meilisearch", "pino", "pino-pretty", "@aws-sdk/*"] as const;
+//
+// drizzle-kit's dialect-resolver macht dynamic-imports zu allen DB-driver-
+// packages (planetscale/libsql/sqlite/neon/vercel/mysql2). Wir nutzen nur
+// postgres → diese werden never-loaded zur Runtime, aber der Bundler will
+// sie resolven. Aufgedeckt durch C1 Empfehlung 4 (bundle-smoke).
+const BUILD_ONLY_EXTERNALS = [
+  "meilisearch",
+  "pino",
+  "pino-pretty",
+  "@aws-sdk/*",
+  "@planetscale/database",
+  "@libsql/client",
+  "better-sqlite3",
+  "@neondatabase/serverless",
+  "@vercel/postgres",
+  "mysql2",
+  // ink (kumiko-tui) hat react-devtools-core als dev-only transitive import.
+  "react-devtools-core",
+] as const;
 
 export type BuildServerBundleOptions = {
   /** App-Root. Default: process.cwd(). */

package/src/index.ts

@@ -54,6 +54,13 @@ export type {
   SignupSetup,
 } from "./run-prod-app";
 export { runProdApp } from "./run-prod-app";
+export type { ScaffoldAppOptions, ScaffoldAppResult } from "./scaffold-app";
+export { scaffoldApp } from "./scaffold-app";
+export type {
+  ScaffoldAppFeatureOptions,
+  ScaffoldAppFeatureResult,
+} from "./scaffold-app-feature";
+export { runConfigPathForApp, scaffoldAppFeature } from "./scaffold-app-feature";
 export type {
   ScaffoldDeployOptions,
   ScaffoldDeployResult,

package/src/run-prod-app.ts

@@ -126,23 +126,28 @@ function readEnv(name: string): string | undefined {
   return value === undefined || value === "" ? undefined : value;
 }
 
-// Parse `KUMIKO_DRY_RUN_ENV=…` into a DryRunMode. Truthy "1" aliases
-// "human" — the most common deploy-Q quick-look. Unknown values are
-// warned-and-ignored: a typo like `=humans` would otherwise look like
-// a confused boot 30 seconds later when the schema fails.
-function parseDryRunMode(raw: string | undefined): DryRunMode | null {
+// `boot` is the C1 smoke-test path — validators run, no DB/Redis connect,
+// exit after registry-build. Render-modes (human|json|pulumi|k8s|1)
+// inspect the env-schema and exit before any feature wiring.
+type RunMode = DryRunMode | "boot";
+
+function parseRunMode(raw: string | undefined): RunMode | null {
   if (!raw) return null;
   const v = raw.toLowerCase();
   if (v === "1" || v === "true" || v === "human") return "human";
-  if (v === "json" || v === "pulumi" || v === "k8s") return v;
+  if (v === "json" || v === "pulumi" || v === "k8s" || v === "boot") return v;
   // biome-ignore lint/suspicious/noConsole: boot-time warn for typo discovery
   console.warn(
     `[runProdApp] KUMIKO_DRY_RUN_ENV="${raw}" unrecognized ` +
-      `(expected 1|human|json|pulumi|k8s); continuing with normal boot.`,
+      `(expected 1|human|json|pulumi|k8s|boot); continuing with normal boot.`,
   );
   return null;
 }
 
+function isRenderMode(mode: RunMode | null): mode is DryRunMode {
+  return mode !== null && mode !== "boot";
+}
+
 function defaultBootErrorReporter(err: KumikoBootError): never {
   // biome-ignore lint/suspicious/noConsole: boot-time error, no logger configured yet
   console.error(err.format());
@@ -485,13 +490,13 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   //    at parse-time before the polyfill loads. Plain strings + .regex /
   //    .min / .email / .url cover every env-var shape we've actually
   //    needed in 9.1's audit (37 references, 25 distinct vars).
+  const envSource = options.envSource ?? process.env;
+  const runMode = parseRunMode(envSource["KUMIKO_DRY_RUN_ENV"]);
   if (options.envSchema) {
-    const envSource = options.envSource ?? process.env;
-    const dryRunMode = parseDryRunMode(envSource["KUMIKO_DRY_RUN_ENV"]);
-    if (dryRunMode !== null) {
+    if (isRenderMode(runMode)) {
       // biome-ignore lint/suspicious/noConsole: dry-run output IS the deliverable
       console.log(
-        renderDryRun(options.envSchema, dryRunMode, {
+        renderDryRun(options.envSchema, runMode, {
           ...(options.pulumiPrefix ? { pulumiPrefix: options.pulumiPrefix } : {}),
           sources: options.envSchema.sources,
         }),
@@ -504,6 +509,9 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
       }
       return makeDryRunHandle();
     }
+    // boot-mode AND normal-boot both run env-validation. boot-mode wants
+    // a real env-check (all required vars present + schema-valid) before
+    // it asserts feature-wiring works.
     try {
       parseEnv(options.envSchema.schema, envSource, {
         sources: options.envSchema.sources,
@@ -554,6 +562,22 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   validateBoot(features);
   const registry = createRegistry(features);
 
+  // C1 boot-mode exit: validators ran, registry built, no DB/Redis
+  // operations executed yet (postgres.js + ioredis are lazy). Tear down
+  // the lazy clients so Bun doesn't keep them open, then exit / return.
+  if (runMode === "boot") {
+    // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+    console.log(
+      `[runProdApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`,
+    );
+    await closeDb();
+    redis.disconnect();
+    if (options.envSource === undefined) {
+      process.exit(0);
+    }
+    return makeDryRunHandle();
+  }
+
   // Sprint-8a Tier-Composition auto-wire: scan features for a
   // tenantTierResolver-extension. If found AND user didn't supply own
   // effectiveFeatures, build the resolver here (db + registry are

package/src/scaffold-app-feature.ts

@@ -0,0 +1,154 @@
+// scaffoldAppFeature — DX-2. Scaffolds a fresh feature inside an
+// existing Kumiko-app workspace + auto-mounts it in src/run-config.ts.
+//
+// Sister to `scaffoldFeature` (which targets samples/recipes/ for the
+// framework workspace). This one targets `src/features/<name>/` of an
+// already-scaffolded app (output of `kumiko new app`).
+//
+// Auto-mount via ts-morph: opens src/run-config.ts, finds
+// `export const APP_FEATURES = [...]`, prepends import + appends entry.
+// User's promise "defineFeature → nichts woanders eintragen" is met
+// for the run-config side. Drizzle FEATURE_IMPORT_REGISTRY is NOT
+// touched here — DX-4 auto-discovery resolves that.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Project, SyntaxKind } from "ts-morph";
+
+export type ScaffoldAppFeatureOptions = {
+  /** kebab-case feature name (e.g. "product-catalog"). */
+  readonly name: string;
+  /** App workspace root. Defaults to cwd. */
+  readonly appRoot?: string;
+};
+
+export type ScaffoldAppFeatureResult = {
+  readonly featureName: string;
+  readonly featureDir: string;
+  readonly files: readonly string[];
+  /** Whether src/run-config.ts was auto-mounted. False if run-config
+   *  is missing — caller gets the scaffolded files but must hand-mount. */
+  readonly autoMounted: boolean;
+};
+
+const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+
+export function scaffoldAppFeature(options: ScaffoldAppFeatureOptions): ScaffoldAppFeatureResult {
+  if (!KEBAB_RE.test(options.name)) {
+    throw new Error(
+      `scaffoldAppFeature: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`,
+    );
+  }
+  const appRoot = resolve(options.appRoot ?? process.cwd());
+  const featureDir = join(appRoot, "src", "features", options.name);
+  if (existsSync(featureDir)) {
+    throw new Error(`scaffoldAppFeature: ${featureDir} already exists — refusing to overwrite`);
+  }
+  mkdirSync(featureDir, { recursive: true });
+
+  const files: string[] = [];
+  const featureFile = join(featureDir, "feature.ts");
+  writeFileSync(featureFile, renderFeature(options.name));
+  files.push(`src/features/${options.name}/feature.ts`);
+
+  const indexFile = join(featureDir, "index.ts");
+  writeFileSync(indexFile, renderIndex(options.name));
+  files.push(`src/features/${options.name}/index.ts`);
+
+  const runConfigPath = join(appRoot, "src", "run-config.ts");
+  const autoMounted = existsSync(runConfigPath)
+    ? mountInRunConfig(runConfigPath, options.name)
+    : false;
+
+  return {
+    featureName: options.name,
+    featureDir,
+    files,
+    autoMounted,
+  };
+}
+
+function renderFeature(name: string): string {
+  const camel = kebabToCamel(name);
+  return `// ${name} feature — scaffolded by \`kumiko add feature\`. Edit freely.
+//
+// Doc-Pointer: https://docs.kumiko.so/en/patterns/ for the \`r.*\` API
+// (r.entity, r.writeHandler, r.queryHandler, hooks, …).
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+export const ${camel}Feature = defineFeature("${name}", (r) => {
+  // Starter: declare an entity. Drop and replace with your domain.
+  r.entity("${name}-item", {
+    fields: {
+      title: { type: "text", required: true },
+    },
+  });
+});
+`;
+}
+
+function renderIndex(name: string): string {
+  const camel = kebabToCamel(name);
+  return `export { ${camel}Feature } from "./feature";\n`;
+}
+
+function kebabToCamel(name: string): string {
+  return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+}
+
+// ts-morph: open run-config, prepend import, append APP_FEATURES entry.
+// Returns true on success, throws on shape-mismatch (caller swallows the
+// scaffolded files but warns).
+function mountInRunConfig(runConfigPath: string, name: string): boolean {
+  const camel = kebabToCamel(name);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  const sf = project.addSourceFileAtPath(runConfigPath);
+
+  // Already mounted? short-circuit (idempotent re-runs).
+  const existingImport = sf.getImportDeclaration(`./features/${name}`);
+  if (existingImport) return true;
+
+  // 1. Prepend import after the last existing import.
+  const imports = sf.getImportDeclarations();
+  const insertIndex = imports.length > 0 ? imports[imports.length - 1]!.getChildIndex() + 1 : 0;
+  sf.insertImportDeclaration(insertIndex, {
+    moduleSpecifier: `./features/${name}`,
+    namedImports: [`${camel}Feature`],
+  });
+
+  // 2. Find `export const APP_FEATURES = [...]` and append the new entry.
+  const appFeaturesDecl = sf.getVariableDeclaration("APP_FEATURES");
+  if (!appFeaturesDecl) {
+    throw new Error(
+      `mountInRunConfig: ${runConfigPath} has no 'APP_FEATURES' declaration — ` +
+        `cannot auto-mount. Hand-edit: add '${camel}Feature' to APP_FEATURES.`,
+    );
+  }
+  const initializer =
+    appFeaturesDecl.getInitializerIfKind(SyntaxKind.AsExpression) ??
+    appFeaturesDecl.getInitializer();
+  if (!initializer) {
+    throw new Error(`mountInRunConfig: APP_FEATURES has no initializer — cannot auto-mount.`);
+  }
+  // Strip `as const` wrapper if present.
+  const arr =
+    initializer.getKind() === SyntaxKind.AsExpression
+      ? initializer.getFirstChildByKind(SyntaxKind.ArrayLiteralExpression)
+      : initializer.asKind(SyntaxKind.ArrayLiteralExpression);
+  if (!arr) {
+    throw new Error(`mountInRunConfig: APP_FEATURES is not an array literal — cannot auto-mount.`);
+  }
+  arr.addElement(`${camel}Feature`);
+
+  sf.saveSync();
+  return true;
+}
+
+// Re-export so consumers can hint at the file (e.g. for kumiko-cli output).
+export function runConfigPathForApp(appRoot: string): string {
+  return join(appRoot, "src", "run-config.ts");
+}

package/src/scaffold-app.ts

@@ -0,0 +1,270 @@
+// scaffoldApp — generate a runnable Kumiko app workspace from a name.
+//
+// Used by `kumiko new app <name>`. Produces the minimal app shape that
+// `KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts` runs successfully against:
+// run-config with 5 foundation features, bin/main.ts with auth-admin
+// stub, package.json with @cosmicdrift/* deps, tsconfig, .env.example,
+// README.
+//
+// Intentionally NOT included in DX-1.0:
+// - drizzle/ setup (DX-1.1 — needs FEATURE_IMPORT_REGISTRY decision from DX-4)
+// - deploy/Dockerfile (already covered by scaffoldDeploy — separate cmd)
+// - first feature scaffold (use scaffoldFeature after this)
+//
+// The generated app is born "boots cleanly, mounts nothing fancy". User
+// runs `kumiko add feature` (DX-2) or hand-edits src/run-config.ts to grow.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export type ScaffoldAppOptions = {
+  /** kebab-case app name (e.g. "my-shop"). Becomes package-name + folder. */
+  readonly name: string;
+  /** Absolute or cwd-relative target dir. Default: <cwd>/<name>. */
+  readonly destination?: string;
+  /** npm-version-pin for @cosmicdrift/* deps. Default "*" for latest. */
+  readonly frameworkVersion?: string;
+};
+
+export type ScaffoldAppResult = {
+  readonly destination: string;
+  readonly files: readonly string[];
+  readonly appName: string;
+};
+
+const KEBAB_RE = /^[a-z][a-z0-9-]*$/;
+
+export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
+  if (!KEBAB_RE.test(options.name)) {
+    throw new Error(`scaffoldApp: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`);
+  }
+  const cwd = process.cwd();
+  const destination = resolve(cwd, options.destination ?? options.name);
+  if (existsSync(destination)) {
+    throw new Error(`scaffoldApp: ${destination} already exists — refusing to overwrite`);
+  }
+  const version = options.frameworkVersion ?? "*";
+
+  mkdirSync(join(destination, "bin"), { recursive: true });
+  mkdirSync(join(destination, "src"), { recursive: true });
+
+  const files: string[] = [];
+
+  write(join(destination, "package.json"), renderPackageJson(options.name, version));
+  files.push("package.json");
+
+  write(join(destination, "tsconfig.json"), renderTsconfig());
+  files.push("tsconfig.json");
+
+  write(join(destination, "src", "run-config.ts"), renderRunConfig());
+  files.push("src/run-config.ts");
+
+  write(join(destination, "bin", "main.ts"), renderMain(options.name));
+  files.push("bin/main.ts");
+
+  write(join(destination, ".env.example"), renderEnvExample());
+  files.push(".env.example");
+
+  write(join(destination, "README.md"), renderReadme(options.name));
+  files.push("README.md");
+
+  return { destination, files, appName: options.name };
+}
+
+function write(path: string, content: string): void {
+  writeFileSync(path, content);
+}
+
+function renderPackageJson(name: string, version: string): string {
+  return `${JSON.stringify(
+    {
+      name,
+      version: "0.1.0",
+      private: true,
+      type: "module",
+      scripts: {
+        boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
+        check: "tsc --noEmit",
+      },
+      dependencies: {
+        "@cosmicdrift/kumiko-bundled-features": version,
+        "@cosmicdrift/kumiko-dev-server": version,
+        "@cosmicdrift/kumiko-framework": version,
+        zod: "^4.4.3",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function renderTsconfig(): string {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        forceConsistentCasingInFileNames: true,
+        verbatimModuleSyntax: true,
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        esModuleInterop: true,
+        skipLibCheck: true,
+        lib: ["ESNext"],
+        types: ["bun-types"],
+        noEmit: true,
+      },
+      include: ["bin", "src"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function renderRunConfig(): string {
+  return `// Single source of truth für die Feature-Komposition deiner App.
+// Bundled-Foundation: secrets + sessions. config/user/tenant/auth-email-password
+// werden via composeFeatures(includeBundled:true) automatisch ergänzt
+// wenn runProdApp mit \`auth: {…}\` aufgerufen wird (siehe bin/main.ts).
+//
+// Neue features hinzufügen:
+//   - bunx kumiko add feature <name>  (DX-2, automatisch)
+//   - oder: hand-edit + import unten ergänzen
+
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+
+export const APP_FEATURES = [
+  createSecretsFeature(),
+  createSessionsFeature(),
+] as const;
+`;
+}
+
+function renderMain(appName: string): string {
+  // Deterministic tenant-UUID derived from appName for the seed-admin
+  // membership. Reproducible across boots; tenants table sees the same
+  // ID. Format: 8-4-4-4-12 hex chars, version-4 marker at position 14.
+  // We hash the name into the digits using a tiny PRNG so two apps
+  // get different IDs without bun's crypto dependency.
+  const tenantId = deriveTenantId(appName);
+  return `// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
+// composeFeatures + validateBoot + createRegistry without DB/Redis-connect
+// (siehe @cosmicdrift/kumiko-dev-server runProdApp). Echter Dev-Boot
+// passiert via \`bunx kumiko dev\` mit Docker-stack — DX-1.0 deckt nur
+// den boot-mode-Pfad ab; \`kumiko dev\` kommt in einer späteren DX-Phase.
+
+import { frameworkCoreEnvSchema, runProdApp } from "@cosmicdrift/kumiko-dev-server";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
+import { APP_FEATURES } from "../src/run-config";
+
+const DEFAULT_TENANT_ID = "${tenantId}" as TenantId;
+
+const envSchema = composeEnvSchema({
+  core: frameworkCoreEnvSchema,
+  features: APP_FEATURES,
+});
+
+await runProdApp({
+  features: APP_FEATURES,
+  envSchema,
+  migrations: false,
+  auth: {
+    admin: {
+      email: "admin@${appName}.local",
+      password: "change-me-on-first-deploy",
+      displayName: "Admin",
+      memberships: [
+        {
+          tenantId: DEFAULT_TENANT_ID,
+          tenantKey: "${appName}",
+          tenantName: "${appName}",
+          roles: ["TenantAdmin"],
+        },
+      ],
+    },
+  },
+});
+`;
+}
+
+function renderEnvExample(): string {
+  return `# Required env-vars für boot-mode + dev. Production: über Pulumi/k8s-Secrets.
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app
+REDIS_URL=redis://127.0.0.1:6379
+
+# JWT_SECRET: min 32 chars. Generate with: openssl rand -base64 32
+JWT_SECRET=change-me-min-32-chars-change-me-min-32
+
+# KUMIKO_SECRETS_MASTER_KEY_V1: base64-encoded 32 bytes (AES-256 KEK).
+# Generate with: openssl rand -base64 32
+KUMIKO_SECRETS_MASTER_KEY_V1=
+`;
+}
+
+function renderReadme(appName: string): string {
+  return `# ${appName}
+
+Scaffolded by \`kumiko new app\`. Boots out-of-the-box with secrets + sessions
+mounted (foundation set). Add features with \`bunx kumiko add feature <name>\`.
+
+## First boot
+
+\`\`\`sh
+yarn install
+cp .env.example .env
+# edit .env — set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1
+bun run boot
+\`\`\`
+
+Expected: \`[runProdApp] boot validation OK (… features, … registry entries)\` + exit 0.
+
+## Adding features
+
+\`\`\`sh
+bunx kumiko add feature my-domain
+# → editiert src/run-config.ts automatisch + scaffolded src/features/my-domain/
+\`\`\`
+
+## Architecture
+
+- \`src/run-config.ts\` — single source of truth: which features your app mounts.
+- \`bin/main.ts\` — production-bootstrap. Reads env, mounts features, starts server.
+
+For full docs see https://docs.kumiko.so.
+`;
+}
+
+// Deterministic tenant-ID from app-name. Format: UUID-v4 with the
+// version-marker at the right spot. NOT cryptographically random —
+// just a stable per-app default the user can change later.
+function deriveTenantId(name: string): string {
+  // Tiny xorshift PRNG seeded from the name's char-codes. Same name →
+  // same ID. Sufficient for "give every scaffolded app a deterministic
+  // default tenant" — production sets its own via the create-tenant
+  // flow anyway.
+  let state = 2166136261;
+  for (const ch of name) {
+    state ^= ch.charCodeAt(0);
+    state = Math.imul(state, 16777619) >>> 0;
+  }
+  const hex = (n: number, len: number): string => n.toString(16).padStart(len, "0").slice(0, len);
+  const a = hex(state, 8);
+  state ^= state << 13;
+  state >>>= 0;
+  const b = hex(state, 4);
+  // version-4 marker at first char of 3rd group:
+  state ^= state >>> 17;
+  state >>>= 0;
+  const c = `4${hex(state, 3)}`;
+  // RFC 4122 variant: 10xx (set top two bits of 4th group to 10):
+  state ^= state << 5;
+  state >>>= 0;
+  const d4 = (0x8 | (state & 0x3)).toString(16);
+  const d = `${d4}${hex(state >>> 4, 3)}`;
+  state = Math.imul(state, 16777619) >>> 0;
+  const e = hex(state, 12);
+  return `${a}-${b}-${c}-${d}-${e}`;
+}

package/templates/deploy/Dockerfile.template

@@ -58,6 +58,15 @@ COPY package.json yarn.lock .yarnrc.yml ./
 # bin/kumiko-build.ts), which writes .kumiko/define.ts and turns the
 # symlink real before the bundle is built.
 ENV YARN_ENABLE_INLINE_BUILDS=true
+# Skip postinstall scripts for ALL deps in the build stage. Reason:
+# `bun build` bundles JS source only — no native bindings needed at bundle-
+# time. msgpackr-extract is the most common offender (ARM/CI native-build
+# failures), but the rule applies broadly: any native dep loaded at runtime
+# gets re-installed via `bun install --production` in the runtime stage,
+# which uses bun's own postinstall handling. Apps that needed per-package
+# opt-outs via `dependenciesMeta.<pkg>.built=false` in package.json (e.g.
+# studio, enterprise) can remove those entries after adopting this template.
+ENV YARN_ENABLE_SCRIPTS=false
 {{#hasPrivateGhPackages}}
 # Re-export GITHUB_TOKEN as env so yarn-4's `${GITHUB_TOKEN:-…}` expansion
 # in .yarnrc.yml finds it during the install step.
@@ -89,6 +98,14 @@ COPY --from=build --chown=app:app /app/dist ./dist
 COPY --from=build --chown=app:app /app/dist-server/drizzle.config.ts ./drizzle.config.ts
 COPY --from=build --chown=app:app /app/drizzle ./drizzle
 
+# Container entrypoint — `infra/pulumi/bun-server.ts` overrides the container
+# command to inject DATABASE_URL from the init-container's /shared/database-url
+# then execs `./start.sh`. We generate it inline so app-source-roots stay
+# clean (no per-app start.sh duplication). Apps that don't go through
+# createBunServer's command-override still boot via the CMD at the bottom
+# (`exec bun run server.js`) — start.sh is dead-code in that case.
+RUN printf '#!/bin/sh\nset -e\nexec bun run server.js\n' > ./start.sh && chmod +x ./start.sh
+
 {{#hasSeeds}}
 # ES-Operations seed migrations — runtime-loaded via dynamic import. Bun
 # does NOT bundle these into dist-server/server.js (await import on a