@cosmicdrift/kumiko-dev-server 0.105.2 → 0.108.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.105.2",
+  "version": "0.108.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>",
@@ -50,8 +50,8 @@
     "kumiko-schema-check": "./bin/kumiko-schema-check.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.105.2",
-    "@cosmicdrift/kumiko-framework": "0.105.2",
+    "@cosmicdrift/kumiko-bundled-features": "0.108.0",
+    "@cosmicdrift/kumiko-framework": "0.108.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/compose-features-wiring.integration.test.ts

@@ -50,7 +50,6 @@ import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-featu
 import { tenantEntity, tenantMembershipsTable } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { seedTenantMembership } from "@cosmicdrift/kumiko-bundled-features/tenant/testing";
 import { UserHandlers, userEntity, userTable } from "@cosmicdrift/kumiko-bundled-features/user";
-import { deleteMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   setupTestStack,
@@ -59,6 +58,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { deleteRows } from "@cosmicdrift/kumiko-framework/testing";
 import { composeFeatures } from "../compose-features";
 
 const RESET_HMAC = randomBytes(32).toString("base64");
@@ -184,8 +184,8 @@ describe("composeFeatures wiring — passwordReset", () => {
   });
 
   beforeEach(async () => {
-    await deleteMany(suite.stack.db, userTable, {});
-    await deleteMany(suite.stack.db, tenantMembershipsTable, {});
+    await deleteRows(suite.stack.db, userTable, {});
+    await deleteRows(suite.stack.db, tenantMembershipsTable, {});
     suite.emailTransport.sent.length = 0;
   });
 
@@ -257,8 +257,8 @@ describe("composeFeatures wiring — emailVerification", () => {
   });
 
   beforeEach(async () => {
-    await deleteMany(suite.stack.db, userTable, {});
-    await deleteMany(suite.stack.db, tenantMembershipsTable, {});
+    await deleteRows(suite.stack.db, userTable, {});
+    await deleteRows(suite.stack.db, tenantMembershipsTable, {});
     suite.emailTransport.sent.length = 0;
   });
 
@@ -302,8 +302,8 @@ describe("composeFeatures wiring — asymmetric activation", () => {
   });
 
   beforeEach(async () => {
-    await deleteMany(suite.stack.db, userTable, {});
-    await deleteMany(suite.stack.db, tenantMembershipsTable, {});
+    await deleteRows(suite.stack.db, userTable, {});
+    await deleteRows(suite.stack.db, tenantMembershipsTable, {});
     suite.emailTransport.sent.length = 0;
   });
 
@@ -355,8 +355,8 @@ describe("composeFeatures wiring — fail-closed ohne authOptions", () => {
   });
 
   afterEach(async () => {
-    await deleteMany(suite.stack.db, userTable, {});
-    await deleteMany(suite.stack.db, tenantMembershipsTable, {});
+    await deleteRows(suite.stack.db, userTable, {});
+    await deleteRows(suite.stack.db, tenantMembershipsTable, {});
     suite.emailTransport.sent.length = 0;
   });
 

package/src/__tests__/require-env.test.ts

@@ -0,0 +1,29 @@
+// requireEnv — the missing-var error message must match the actual caller.
+// Regression (728/2): the advice text was hardcoded to prod/container
+// wording ("Coolify secrets") regardless of the `context` param, so a
+// runDevApp caller got misleading production-deploy instructions for a
+// missing local .env var.
+
+import { describe, expect, test } from "bun:test";
+import { requireEnv } from "../run-prod-app";
+
+describe("requireEnv", () => {
+  test("default context (runProdApp) gives container/production advice", () => {
+    expect(() => requireEnv("MISSING_VAR", {})).toThrow(/container env.*Coolify secrets/);
+  });
+
+  test("runDevApp context gives local .env advice, not production advice", () => {
+    expect(() => requireEnv("MISSING_VAR", {}, "runDevApp")).toThrow(
+      /\.env \/ shell before running the dev server/,
+    );
+  });
+
+  test("runDevApp context error does NOT mention Coolify", () => {
+    try {
+      requireEnv("MISSING_VAR", {}, "runDevApp");
+      throw new Error("expected requireEnv to throw");
+    } catch (err) {
+      expect(String(err)).not.toContain("Coolify");
+    }
+  });
+});

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

@@ -10,10 +10,10 @@ import { scaffoldAppFeature } from "../scaffold-app-feature";
 describe("scaffoldAppFeature", () => {
   let tmp: string;
   let appRoot: string;
-  beforeEach(() => {
+  beforeEach(async () => {
     tmp = mkdtempSync(join(tmpdir(), "scaffold-app-feature-"));
     appRoot = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: appRoot });
+    await scaffoldApp({ name: "my-shop", destination: appRoot });
   });
   afterEach(() => {
     rmSync(tmp, { recursive: true, force: true });

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

@@ -1,4 +1,4 @@
-// scaffoldApp unit-tests (DX-1.0).
+// scaffoldApp unit-tests (DX-1.0 + #352 deploy/schema scaffold).
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -6,6 +6,29 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { scaffoldApp } from "../scaffold-app";
 
+const SCAFFOLD_FILES = [
+  "package.json",
+  "tsconfig.json",
+  "biome.json",
+  "bunfig.toml",
+  "bunfig.ci.toml",
+  "src/run-config.ts",
+  "kumiko/schema.ts",
+  "bin/main.ts",
+  "bin/dev.ts",
+  "bin/kumiko.ts",
+  "src/client.tsx",
+  "src/styles.css",
+  ".env.example",
+  "docker-compose.yml",
+  "kumiko/migrations/0001_init.sql",
+  "kumiko/migrations/.snapshot.json",
+  "deploy/Dockerfile",
+  "deploy/Dockerfile.dockerignore",
+  "deploy/migrate-step.sh",
+  "README.md",
+] as const;
+
 describe("scaffoldApp", () => {
   let tmp: string;
   beforeEach(() => {
@@ -15,31 +38,21 @@ describe("scaffoldApp", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("scaffolds the expected files into <cwd>/<name>", () => {
+  test("scaffolds the expected files into <cwd>/<name>", async () => {
     const dest = join(tmp, "my-shop");
-    const result = scaffoldApp({ name: "my-shop", destination: dest });
+    const result = await 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",
-      "bin/dev.ts",
-      "src/client.tsx",
-      ".env.example",
-      "docker-compose.yml",
-      "README.md",
-    ]);
-    for (const f of result.files) {
+    for (const f of SCAFFOLD_FILES) {
+      expect(result.files).toContain(f);
       expect(existsSync(join(dest, f))).toBe(true);
     }
   });
 
-  test("package.json has @cosmicdrift/* deps with version pin", () => {
+  test("package.json has @cosmicdrift/* deps with version pin", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest, frameworkVersion: "^0.13.0" });
+    await scaffoldApp({ name: "my-shop", destination: dest, frameworkVersion: "^0.13.0" });
 
     const pkg = JSON.parse(readFileSync(join(dest, "package.json"), "utf-8")) as {
       name: string;
@@ -53,70 +66,82 @@ describe("scaffoldApp", () => {
     expect(pkg.dependencies["@cosmicdrift/kumiko-renderer-web"]).toBe("^0.13.0");
     expect(pkg.scripts["boot"]).toContain("KUMIKO_DRY_RUN_ENV=boot");
     expect(pkg.scripts["dev"]).toBe("bun --watch bin/dev.ts");
+    expect(pkg.scripts["build"]).toBe("bun kumiko-build");
+    expect(pkg.scripts["start"]).toBe("bun run bin/main.ts");
+    expect(pkg.scripts["lint"]).toBe("biome check .");
+  });
+
+  test("init migration includes auth-mode tables (read_users)", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const sql = readFileSync(join(dest, "kumiko/migrations/0001_init.sql"), "utf-8");
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "read_users"');
   });
 
-  test("bin/dev.ts contains runDevApp + welcomeBanner + admin login + clientEntry", () => {
+  test("kumiko/schema.ts + bin/kumiko.ts wire HAS_AUTH single-source", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
+
+    const schema = readFileSync(join(dest, "kumiko/schema.ts"), "utf-8");
+    expect(schema).toContain("APP_FEATURES, HAS_AUTH");
+    expect(schema).toContain("collectTableMetas");
+
+    const kumikoBin = readFileSync(join(dest, "bin/kumiko.ts"), "utf-8");
+    expect(kumikoBin).toContain("runSchemaCli");
+    expect(kumikoBin).toContain("includeBundled: HAS_AUTH");
+  });
+
+  test("bin/dev.ts contains runDevApp + welcomeBanner + admin login + clientEntry", async () => {
+    const dest = join(tmp, "my-shop");
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const dev = readFileSync(join(dest, "bin/dev.ts"), "utf-8");
     expect(dev).toContain("runDevApp");
     expect(dev).toContain("welcomeBanner: true");
     expect(dev).toContain("admin@my-shop.local");
     expect(dev).toContain(`password: "changeme"`);
-    // Without clientEntry the default HTML still <script src="/client.js">'s,
-    // and the dev-server 404s on it — every fresh scaffold rendered blank.
     expect(dev).toContain(`clientEntry: "./src/client.tsx"`);
   });
 
-  test("src/client.tsx bundles createKumikoApp + emailPasswordClient + DefaultAppShell", () => {
+  test("src/client.tsx bundles createKumikoApp + emailPasswordClient + DefaultAppShell", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const client = readFileSync(join(dest, "src/client.tsx"), "utf-8");
     expect(client).toContain("createKumikoApp");
     expect(client).toContain("emailPasswordClient");
-    // Without shell:DefaultAppShell post-login renders only the active
-    // screen (no sidebar / topbar) — the e2e hero-demo proved this dead-
-    // ends on "Screen not found" because routing has no layout chrome.
     expect(client).toContain("DefaultAppShell");
     expect(client).toContain("shell: DefaultAppShell");
     expect(client).toContain('from "@cosmicdrift/kumiko-renderer-web"');
     expect(client).toContain('from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web"');
   });
 
-  test(".env.example carries KUMIKO_DEV_DB_NAME default so reboots are persistent", () => {
+  test(".env.example carries KUMIKO_DEV_DB_NAME default so reboots are persistent", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const env = readFileSync(join(dest, ".env.example"), "utf-8");
     expect(env).toContain("KUMIKO_DEV_DB_NAME=my_shop_dev");
   });
 
-  test(".env.example lists both TEST_DATABASE_URL (bun dev) + DATABASE_URL (prod)", () => {
+  test(".env.example lists both TEST_DATABASE_URL (bun dev) + DATABASE_URL (prod)", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const env = readFileSync(join(dest, ".env.example"), "utf-8");
-    // runDevApp → setupTestStack needs TEST_DATABASE_URL; previously the
-    // template only listed DATABASE_URL, so every fresh `bun dev` crashed
-    // with "Missing required env var: TEST_DATABASE_URL".
     expect(env).toContain("TEST_DATABASE_URL=");
     expect(env).toContain("DATABASE_URL=");
   });
 
-  test("docker-compose.yml ports + credentials match the .env.example *_URL defaults", () => {
+  test("docker-compose.yml ports + credentials match the .env.example *_URL defaults", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const compose = readFileSync(join(dest, "docker-compose.yml"), "utf-8");
     const env = readFileSync(join(dest, ".env.example"), "utf-8");
-    // README tells the user to run `docker compose up -d`; that only works if
-    // the compose service matches what the generated .env points its *_URLs at.
     expect(env).toContain("127.0.0.1:5432");
     expect(env).toContain("127.0.0.1:6379");
-    // Ports bind to loopback only — weak dev creds / auth-less Redis must not
-    // be reachable from the LAN (security review of the scaffold).
     expect(compose).toContain('"127.0.0.1:5432:5432"');
     expect(compose).toContain('"127.0.0.1:6379:6379"');
     expect(compose).not.toContain('"5432:5432"');
@@ -126,9 +151,9 @@ describe("scaffoldApp", () => {
     expect(compose).toContain("image: redis:");
   });
 
-  test("README lists the mounted features dynamically", () => {
+  test("README lists the mounted features dynamically", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({
+    await scaffoldApp({
       name: "my-shop",
       destination: dest,
       features: [
@@ -153,78 +178,75 @@ describe("scaffoldApp", () => {
     expect(readme).toContain("- `delivery`");
   });
 
-  test("bin/main.ts contains runProdApp + auth.admin stub", () => {
+  test("bin/main.ts contains runProdApp + auth.admin stub + staticDir", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
     expect(main).toContain("runProdApp");
+    expect(main).toContain('staticDir: "./dist"');
     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("bin/main.ts composes the auth-mode feature set into envSchema (JWT_SECRET boot-gate)", () => {
+  test("bin/main.ts composes the auth-mode feature set into envSchema (JWT_SECRET boot-gate)", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await scaffoldApp({ name: "my-shop", destination: dest });
 
     const main = readFileSync(join(dest, "bin/main.ts"), "utf-8");
-    // envSchema must cover the same features runProdApp auto-mixes via
-    // auth-mode — otherwise auth-email-password's JWT_SECRET (min-32) is
-    // absent from the boot-gate and a too-short secret slips through.
-    expect(main).toContain("composeFeatures(APP_FEATURES, { includeBundled: true })");
+    expect(main).toContain("composeFeatures(APP_FEATURES, { includeBundled: HAS_AUTH })");
     expect(main).toContain(
       "composeEnvSchema({ core: frameworkCoreEnvSchema, features: bootFeatures })",
     );
-    expect(main).toContain("composeFeatures");
   });
 
-  test("src/run-config.ts mounts secrets + sessions as foundation", () => {
+  test("src/run-config.ts mounts secrets + sessions + HAS_AUTH", async () => {
     const dest = join(tmp, "my-shop");
-    scaffoldApp({ name: "my-shop", destination: dest });
+    await 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");
+    expect(runConfig).toContain("export const HAS_AUTH");
   });
 
-  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("rejects non-kebab-case names", async () => {
+    await expect(scaffoldApp({ name: "MyShop", destination: tmp })).rejects.toThrow(/kebab-case/);
+    await expect(scaffoldApp({ name: "my_shop", destination: tmp })).rejects.toThrow(/kebab-case/);
+    await expect(scaffoldApp({ name: "0shop", destination: tmp })).rejects.toThrow(/kebab-case/);
   });
 
-  test("rejects trailing- and double-hyphen names (invalid package segment)", () => {
-    expect(() => scaffoldApp({ name: "my-shop-", destination: tmp })).toThrow(/kebab-case/);
-    expect(() => scaffoldApp({ name: "my--shop", destination: tmp })).toThrow(/kebab-case/);
+  test("rejects trailing- and double-hyphen names (invalid package segment)", async () => {
+    await expect(scaffoldApp({ name: "my-shop-", destination: tmp })).rejects.toThrow(/kebab-case/);
+    await expect(scaffoldApp({ name: "my--shop", destination: tmp })).rejects.toThrow(/kebab-case/);
   });
 
-  test("resolves a relative destination against the supplied cwd, not process.cwd()", () => {
-    // The CLI passes ctx.cwd; the scaffold must land under it so the
-    // displayed path matches the actual write location.
-    const result = scaffoldApp({ name: "shop", destination: "apps/shop", cwd: tmp });
+  test("resolves a relative destination against the supplied cwd, not process.cwd()", async () => {
+    const result = await scaffoldApp({ name: "shop", destination: "apps/shop", cwd: tmp });
     expect(result.destination).toBe(join(tmp, "apps/shop"));
     expect(existsSync(join(tmp, "apps/shop", "package.json"))).toBe(true);
   });
 
-  test("resolves the name-default destination against the supplied cwd", () => {
-    const result = scaffoldApp({ name: "shop", cwd: tmp });
+  test("resolves the name-default destination against the supplied cwd", async () => {
+    const result = await scaffoldApp({ name: "shop", cwd: tmp });
     expect(result.destination).toBe(join(tmp, "shop"));
     expect(existsSync(join(tmp, "shop", "package.json"))).toBe(true);
   });
 
-  test("refuses to overwrite existing destination", () => {
+  test("refuses to overwrite existing destination", async () => {
     const dest = join(tmp, "existing");
-    scaffoldApp({ name: "existing", destination: dest });
-    expect(() => scaffoldApp({ name: "existing", destination: dest })).toThrow(/already exists/);
+    await scaffoldApp({ name: "existing", destination: dest });
+    await expect(scaffoldApp({ name: "existing", destination: dest })).rejects.toThrow(
+      /already exists/,
+    );
   });
 
-  test("features-param: custom selection lands in run-config.ts imports + APP_FEATURES", () => {
+  test("features-param: custom selection lands in run-config.ts imports + APP_FEATURES", async () => {
     const dest = join(tmp, "custom-features");
-    scaffoldApp({
+    await scaffoldApp({
       name: "custom-features",
       destination: dest,
       features: [
@@ -251,23 +273,20 @@ describe("scaffoldApp", () => {
     expect(cfg).not.toContain("createSessionsFeature");
   });
 
-  test("features-param: empty array falls back to foundation (backwards-compat)", () => {
+  test("features-param: empty array falls back to foundation (backwards-compat)", async () => {
     const dest = join(tmp, "empty-features");
-    scaffoldApp({ name: "empty-features", destination: dest, features: [] });
+    await scaffoldApp({ name: "empty-features", destination: dest, features: [] });
     const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
     expect(cfg).toContain("createSecretsFeature()");
     expect(cfg).toContain("createSessionsFeature()");
   });
 
-  test("features-param: composeFeatures auto-mounted (config/user/tenant/auth-email-password) are filtered out — no boot-time dedupe-warn spam", () => {
+  test("features-param: composeFeatures auto-mounted names are filtered out", async () => {
     const dest = join(tmp, "filtered");
-    scaffoldApp({
+    await scaffoldApp({
       name: "filtered",
       destination: dest,
       features: [
-        // Picker's recommended set includes the 4 auto-mounted bundled
-        // features; without the filter they'd land in APP_FEATURES and
-        // composeFeatures would log 4 dedupe warnings on every boot.
         {
           name: "config",
           importPath: "@cosmicdrift/kumiko-bundled-features/config",
@@ -308,11 +327,48 @@ describe("scaffoldApp", () => {
     expect(cfg).toContain("createDeliveryFeature()");
   });
 
-  test("deterministic tenantId for same name (reproducible boots)", () => {
+  test("features-param: ONLY auto-mounted names → empty effective set, no foundation fallback", async () => {
+    const dest = join(tmp, "only-auto-mounted");
+    await scaffoldApp({
+      name: "only-auto-mounted",
+      destination: dest,
+      features: [
+        {
+          name: "config",
+          importPath: "@cosmicdrift/kumiko-bundled-features/config",
+          exportName: "createConfigFeature",
+          callExpression: "createConfigFeature()",
+        },
+        {
+          name: "user",
+          importPath: "@cosmicdrift/kumiko-bundled-features/user",
+          exportName: "createUserFeature",
+          callExpression: "createUserFeature()",
+        },
+        {
+          name: "tenant",
+          importPath: "@cosmicdrift/kumiko-bundled-features/tenant",
+          exportName: "createTenantFeature",
+          callExpression: "createTenantFeature()",
+        },
+        {
+          name: "auth-email-password",
+          importPath: "@cosmicdrift/kumiko-bundled-features/auth-email-password",
+          exportName: "createAuthEmailPasswordFeature",
+          callExpression: "createAuthEmailPasswordFeature()",
+        },
+      ],
+    });
+    const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
+    expect(cfg).not.toContain("createSecretsFeature");
+    expect(cfg).not.toContain("createSessionsFeature");
+  });
+
+  test("deterministic tenantId for same name (reproducible boots)", async () => {
     const a = join(tmp, "a");
     const b = join(tmp, "b");
-    scaffoldApp({ name: "stable", destination: a });
-    scaffoldApp({ name: "stable", destination: b });
+    await scaffoldApp({ name: "stable", destination: a });
+    await 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(

package/src/__tests__/walkthrough.integration.test.ts

@@ -32,23 +32,17 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     rmSync(tmp, { recursive: true, force: true });
   });
 
-  test("Step 1 (kumiko new app) — produces walkthrough's scaffold files", () => {
-    const result = scaffoldApp({ name: "my-notes", destination: appRoot });
-    expect(result.files).toEqual([
-      "package.json",
-      "tsconfig.json",
-      "src/run-config.ts",
-      "bin/main.ts",
-      "bin/dev.ts",
-      "src/client.tsx",
-      ".env.example",
-      "docker-compose.yml",
-      "README.md",
-    ]);
+  test("Step 1 (kumiko new app) — produces walkthrough's scaffold files", async () => {
+    const result = await scaffoldApp({ name: "my-notes", destination: appRoot });
+    expect(result.files).toContain("package.json");
+    expect(result.files).toContain("kumiko/schema.ts");
+    expect(result.files).toContain("bin/kumiko.ts");
+    expect(result.files).toContain("deploy/Dockerfile");
+    expect(result.files).toContain("kumiko/migrations/0001_init.sql");
   });
 
-  test("Step 2 (kumiko add feature) — auto-mounts + walkthrough diff matches", () => {
-    scaffoldApp({ name: "my-notes", destination: appRoot });
+  test("Step 2 (kumiko add feature) — auto-mounts + walkthrough diff matches", async () => {
+    await scaffoldApp({ name: "my-notes", destination: appRoot });
     const result = scaffoldAppFeature({ name: "notes", appRoot });
     expect(result.autoMounted).toBe(true);
 
@@ -63,8 +57,8 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     expect(runConfig).toContain("createSessionsFeature()");
   });
 
-  test("Step 3 (boot validation) — scaffolded run-config matches walkthrough's APP_FEATURES claim", () => {
-    scaffoldApp({ name: "my-notes", destination: appRoot });
+  test("Step 3 (boot validation) — scaffolded run-config matches walkthrough's APP_FEATURES claim", async () => {
+    await scaffoldApp({ name: "my-notes", destination: appRoot });
     scaffoldAppFeature({ name: "notes", appRoot });
 
     // Text-assert: scaffolded run-config.ts contains exactly the 3 features
@@ -108,8 +102,8 @@ describe("walkthrough — DX-3.1 snapshot", () => {
     expect(registry.features.size).toBe(7);
   });
 
-  test("bin/main.ts contains the auth.admin stub the walkthrough relies on", () => {
-    scaffoldApp({ name: "my-notes", destination: appRoot });
+  test("bin/main.ts contains the auth.admin stub the walkthrough relies on", async () => {
+    await scaffoldApp({ name: "my-notes", destination: appRoot });
     const main = readFileSync(join(appRoot, "bin/main.ts"), "utf-8");
     // composeFeatures(includeBundled:true)-trigger is `auth: { admin: { … } }`.
     // Walkthrough explicitly says this is what auto-mounts the 4 bundled features.

package/src/run-dev-app.ts

@@ -22,12 +22,19 @@ import {
   buildEnvConfigOverrides,
   createConfigResolver,
 } from "@cosmicdrift/kumiko-bundled-features/config";
+import {
+  createPatResolver,
+  PAT_FEATURE,
+  patRateLimitFromFeature,
+  patScopesFromFeature,
+} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import {
   createSessionCallbacks,
   type SessionCallbacks,
 } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
-import type { SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
+import type { PatResolver, SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
+import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
 import {
   collectWriteHandlerQns,
   createRegistry,
@@ -226,9 +233,8 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
-  // Ein explizit gewireter File-Provider (options.files) erfüllt das
-  // FILE_STORAGE_PROVIDER-Boot-Gate — der Provider IST konfiguriert, nur
-  // nicht über die env-Bridge. Setzen bevor validateBoot greift.
+  // An explicitly wired file provider (options.files) satisfies the
+  // FILE_STORAGE_PROVIDER boot gate — set it before validateBoot runs.
   if (options.files !== undefined && process.env["FILE_STORAGE_PROVIDER"] === undefined) {
     process.env["FILE_STORAGE_PROVIDER"] = "configured";
   }
@@ -339,6 +345,26 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     }
     return sessionCallbacks;
   };
+  // PAT opt-in: same late-bound holder pattern — the resolver needs the real
+  // db (only concrete after setupTestStack). Wired when the feature is mounted;
+  // scopes come from the feature's exports (single source with its handlers).
+  let patResolver: PatResolver | undefined;
+  const patFeature = features.find((f) => f.name === PAT_FEATURE);
+  const patAuthFragment = patFeature
+    ? {
+        patResolver: (rawToken: string) => {
+          if (!patResolver) {
+            throw new Error("[runDevApp] pat-resolver accessed before onAfterSetup");
+          }
+          return patResolver(rawToken);
+        },
+        patRateLimiter: (() => {
+          const rl = patRateLimitFromFeature(patFeature);
+          return createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs);
+        })(),
+      }
+    : {};
+
   const sessionAuthFragment =
     effectiveAuth?.sessions !== undefined
       ? {
@@ -392,6 +418,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
         ...sessionAuthFragment,
+        ...patAuthFragment,
         ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,
@@ -437,6 +464,9 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
           ...(expiresInMs !== undefined && { expiresInMs }),
         });
       }
+      if (patFeature) {
+        patResolver = createPatResolver({ db: stack.db, scopes: patScopesFromFeature(patFeature) });
+      }
       if (effectiveAuth) {
         await seedAdmin(stack.db, effectiveAuth.admin);
       }

package/src/run-prod-app.ts

@@ -50,6 +50,12 @@ import {
   createDeliveryService,
   DELIVERY_FEATURE,
 } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import {
+  createPatResolver,
+  PAT_FEATURE,
+  patRateLimitFromFeature,
+  patScopesFromFeature,
+} from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import {
   createSecretsContext,
   SECRETS_FEATURE_NAME,
@@ -66,6 +72,7 @@ import {
   cachedResponse,
   computeStrongEtag,
   computeWeakEtag,
+  createInMemoryLoginRateLimiter,
   createSseBroker,
   type SseBroker,
 } from "@cosmicdrift/kumiko-framework/api";
@@ -84,7 +91,6 @@ import {
   findTierResolverUsage,
   type NotifyFactory,
   type Registry,
-  type TenantId,
   type TierResolverPlugin,
   validateAppCustomScreenWriteQns,
   validateBoot,
@@ -170,10 +176,11 @@ export function requireEnv(
 ): string {
   const value = src[name];
   if (value === undefined || value === "") {
-    throw new Error(
-      `${context}: required env var "${name}" is missing or empty. ` +
-        `Set it in your container env / .env.production / Coolify secrets.`,
-    );
+    const advice =
+      context === "runProdApp"
+        ? "Set it in your container env / .env.production / Coolify secrets."
+        : "Set it in your .env / shell before running the dev server.";
+    throw new Error(`${context}: required env var "${name}" is missing or empty. ${advice}`);
   }
   return value;
 }
@@ -523,7 +530,7 @@ export type RunProdAppOptions = {
    *  liche features aktiv via globalFeatureToggleRuntime. Pattern:
    *  createLateBoundHolder + post-boot runtime.initialize in einem
    *  seed-fn (db ist erst nach migrations + features ready). */
-  readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+  readonly effectiveFeatures?: EffectiveFeaturesResolver;
   /** Composed Zod-schema for env-validation (from `composeEnvSchema({
    *  features, extend })` in @cosmicdrift/kumiko-framework/env). When set:
    *  - `process.env` is parsed against it BEFORE any boot work; missing
@@ -570,14 +577,7 @@ export type ProdAppHandle = {
   readonly stop: () => Promise<void>;
 };
 
-// Mint `ctx.config` per request: the dispatcher only builds a per-user
-// ConfigAccessor when `_configAccessorFactory` is on the AppContext
-// (pipeline/dispatcher.ts). Without it `ctx.config` stays undefined and any
-// handler reading it — e.g. createFileProviderForTenant for the GDPR export
-// download — throws "ctx.config is missing". Built from the EFFECTIVE resolver
-// so an app-supplied configResolver override (its appOverrides) is the one
-// ctx.config reads. Shared with runDevApp (mergeConfigResolverDefault) for
-// dev/prod parity.
+// Shared with runDevApp (mergeConfigResolverDefault) for dev/prod parity.
 export function addConfigAccessorFactory<T extends { readonly configResolver?: ConfigResolver }>(
   resolved: T,
   registry: Registry,
@@ -957,6 +957,24 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     ? buildProdSessionAuth(db, resolveProdSessionsConfig(effectiveAuth?.sessions))
     : undefined;
 
+  // PAT opt-in: if the personal-access-tokens feature is mounted, wire its
+  // resolver (bearer PATs → SessionUser, before jwt.verify). Scopes come from
+  // the feature's exports — the same declaration its handlers use.
+  const patFeature = features.find((f) => f.name === PAT_FEATURE);
+  let patAuthFragment:
+    | {
+        patResolver: ReturnType<typeof createPatResolver>;
+        patRateLimiter: ReturnType<typeof createInMemoryLoginRateLimiter>;
+      }
+    | undefined;
+  if (effectiveAuth && patFeature) {
+    const rl = patRateLimitFromFeature(patFeature);
+    patAuthFragment = {
+      patResolver: createPatResolver({ db, scopes: patScopesFromFeature(patFeature) }),
+      patRateLimiter: createInMemoryLoginRateLimiter(rl.maxRequests, rl.windowMs),
+    };
+  }
+
   const baseEntrypointOptions = {
     registry,
     context: {
@@ -994,6 +1012,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
         ...sessionAuthFragment,
+        ...patAuthFragment,
         ...(effectiveAuth.passwordReset && {
           passwordReset: {
             requestHandler: AuthHandlers.requestPasswordReset,

package/src/scaffold-app.ts

@@ -12,9 +12,17 @@
 // Static files (package.json, tsconfig, .env, README) stay text-based.
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
+import {
+  collectTableMetas,
+  generateMigration,
+  writeSnapshotJson,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { IndentationText, Project, VariableDeclarationKind } from "ts-morph";
+import { composeFeatures } from "./compose-features";
 import { isKebabSegment } from "./kebab";
+import { scaffoldDeploy } from "./scaffold-deploy";
 
 // Single bundled-feature entry the scaffolder mounts into run-config.ts.
 // importPath is the from-spec ("@cosmicdrift/kumiko-bundled-features/files"),
@@ -52,7 +60,7 @@ export type ScaffoldAppResult = {
   readonly appName: string;
 };
 
-export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
+export async function scaffoldApp(options: ScaffoldAppOptions): Promise<ScaffoldAppResult> {
   if (!isKebabSegment(options.name)) {
     throw new Error(`scaffoldApp: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`);
   }
@@ -65,6 +73,7 @@ export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
 
   mkdirSync(join(destination, "bin"), { recursive: true });
   mkdirSync(join(destination, "src"), { recursive: true });
+  mkdirSync(join(destination, "kumiko"), { recursive: true });
 
   const files: string[] = [];
 
@@ -74,24 +83,52 @@ export function scaffoldApp(options: ScaffoldAppOptions): ScaffoldAppResult {
   write(join(destination, "tsconfig.json"), renderTsconfig());
   files.push("tsconfig.json");
 
+  write(join(destination, "biome.json"), renderBiomeJson());
+  files.push("biome.json");
+
+  write(join(destination, "bunfig.toml"), renderBunfigToml());
+  files.push("bunfig.toml");
+
+  write(join(destination, "bunfig.ci.toml"), renderBunfigCiToml());
+  files.push("bunfig.ci.toml");
+
   write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
   files.push("src/run-config.ts");
 
+  write(join(destination, "kumiko", "schema.ts"), renderKumikoSchema());
+  files.push("kumiko/schema.ts");
+
   write(join(destination, "bin", "main.ts"), renderMain(options.name));
   files.push("bin/main.ts");
 
   write(join(destination, "bin", "dev.ts"), renderDev(options.name));
   files.push("bin/dev.ts");
 
+  write(join(destination, "bin", "kumiko.ts"), renderBinKumiko());
+  files.push("bin/kumiko.ts");
+
   write(join(destination, "src", "client.tsx"), renderClient());
   files.push("src/client.tsx");
 
+  write(join(destination, "src", "styles.css"), renderStylesCss());
+  files.push("src/styles.css");
+
   write(join(destination, ".env.example"), renderEnvExample(options.name));
   files.push(".env.example");
 
   write(join(destination, "docker-compose.yml"), renderDockerCompose());
   files.push("docker-compose.yml");
 
+  await writeInitMigration(destination, options.features);
+  files.push("kumiko/migrations/0001_init.sql", "kumiko/migrations/.snapshot.json");
+
+  const deploy = scaffoldDeploy({ appName: options.name, destination });
+  for (const f of deploy.files) {
+    if (f.written) {
+      files.push(relative(destination, f.path));
+    }
+  }
+
   write(join(destination, "README.md"), renderReadme(options.name, options.features));
   files.push("README.md");
 
@@ -112,16 +149,31 @@ function renderPackageJson(name: string, version: string): string {
       type: "module",
       scripts: {
         dev: "bun --watch bin/dev.ts",
+        build: "bun kumiko-build",
+        start: "bun run bin/main.ts",
         boot: "KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts",
-        check: "tsc --noEmit",
+        typecheck: "tsc --noEmit",
+        lint: "biome check .",
+        test: "bun --config=bunfig.ci.toml test --dots",
+        "schema:apply": "bun kumiko-schema apply",
+        "schema:generate": "bun kumiko-schema generate",
       },
       dependencies: {
         "@cosmicdrift/kumiko-bundled-features": version,
         "@cosmicdrift/kumiko-dev-server": version,
         "@cosmicdrift/kumiko-framework": version,
         "@cosmicdrift/kumiko-renderer-web": version,
+        react: "^19.2.6",
+        "react-dom": "^19.2.6",
         zod: "^4.4.3",
       },
+      devDependencies: {
+        "@biomejs/biome": "^2.4.15",
+        "@tailwindcss/cli": "^4.3.0",
+        "bun-types": "^1.3.14",
+        tailwindcss: "^4.3.0",
+        typescript: "^6.0.3",
+      },
     },
     null,
     2,
@@ -141,17 +193,107 @@ function renderTsconfig(): string {
         moduleResolution: "bundler",
         esModuleInterop: true,
         skipLibCheck: true,
-        lib: ["ESNext"],
+        lib: ["ESNext", "DOM"],
         types: ["bun-types"],
+        jsx: "react-jsx",
         noEmit: true,
       },
-      include: ["bin", "src"],
+      include: ["bin", "src", "kumiko"],
     },
     null,
     2,
   )}\n`;
 }
 
+function renderBiomeJson(): string {
+  return `${JSON.stringify(
+    {
+      $schema: "https://biomejs.dev/schemas/2.4.15/schema.json",
+      vcs: {
+        enabled: true,
+        clientKind: "git",
+        useIgnoreFile: true,
+        defaultBranch: "main",
+      },
+      files: {
+        includes: ["src/**", "bin/**", "kumiko/**", "!**/dist", "!kumiko/migrations"],
+      },
+      formatter: {
+        enabled: true,
+        indentStyle: "space",
+        indentWidth: 2,
+        lineWidth: 100,
+        lineEnding: "lf",
+      },
+      css: {
+        parser: { cssModules: false, tailwindDirectives: true },
+      },
+      javascript: {
+        formatter: {
+          quoteStyle: "double",
+          jsxQuoteStyle: "double",
+          semicolons: "always",
+          trailingCommas: "all",
+          arrowParentheses: "always",
+        },
+      },
+      json: { formatter: { indentWidth: 2, lineWidth: 80 } },
+      linter: {
+        enabled: true,
+        rules: {
+          recommended: true,
+          correctness: { noUnusedVariables: "error", noUnusedImports: "error" },
+          suspicious: { noExplicitAny: "error", noDebugger: "error", noConsole: "warn" },
+          complexity: { useLiteralKeys: "off" },
+          style: { useConst: "error" },
+          nursery: { noFloatingPromises: "error" },
+        },
+      },
+      overrides: [
+        {
+          includes: ["**/*.test.ts", "**/*.spec.ts", "**/*.integration.ts", "**/*.e2e.ts"],
+          linter: {
+            rules: {
+              suspicious: { noConsole: "off" },
+              style: { noNonNullAssertion: "off" },
+            },
+          },
+        },
+      ],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function renderBunfigToml(): string {
+  return `[install]
+linker = "hoisted"
+
+[test]
+concurrency = 8
+pathIgnorePatterns = [
+  "**/e2e/**",
+  "**/*.spec.ts",
+  "**/dist/**",
+]
+`;
+}
+
+function renderBunfigCiToml(): string {
+  return `[install]
+linker = "hoisted"
+
+[test]
+concurrency = 8
+pathIgnorePatterns = [
+  "**/e2e/**",
+  "**/*.spec.ts",
+  "**/dist/**",
+]
+`;
+}
+
 function newTsProject(): Project {
   return new Project({
     useInMemoryFileSystem: true,
@@ -187,8 +329,13 @@ function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string
   const project = newTsProject();
   const sf = project.createSourceFile("run-config.ts", "");
 
-  const filtered = (features ?? []).filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
-  const effective = filtered.length > 0 ? filtered : FOUNDATION_FEATURES;
+  // Fallback decided BEFORE filtering: if the caller passed features (even
+  // if every one of them is an auto-mounted name), an all-filtered-out empty
+  // result is the correct outcome — falling back to FOUNDATION_FEATURES here
+  // would silently substitute a different feature set than the caller asked
+  // for.
+  const base = features?.length ? features : FOUNDATION_FEATURES;
+  const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
   const grouped = new Map<string, string[]>();
   for (const entry of effective) {
     const existing = grouped.get(entry.importPath) ?? [];
@@ -211,6 +358,12 @@ function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string
     ],
   });
 
+  sf.addVariableStatement({
+    declarationKind: VariableDeclarationKind.Const,
+    isExported: true,
+    declarations: [{ name: "HAS_AUTH", initializer: "true" }],
+  });
+
   sf.insertText(
     0,
     [
@@ -250,7 +403,7 @@ function renderMain(appName: string): string {
   });
   sf.addImportDeclaration({
     moduleSpecifier: "../src/run-config",
-    namedImports: ["APP_FEATURES"],
+    namedImports: ["APP_FEATURES", "HAS_AUTH"],
   });
 
   sf.addVariableStatement({
@@ -265,7 +418,7 @@ function renderMain(appName: string): string {
 
   // The envSchema must cover the SAME features runProdApp mounts at boot.
   // `auth: { admin: … }` below makes runProdApp auto-mix config/user/tenant/
-  // auth-email-password via composeFeatures(includeBundled:true); compose the
+  // auth-email-password via composeFeatures(includeBundled:HAS_AUTH); compose the
   // identical set here so the auth feature's JWT_SECRET (min-32) declaration
   // is part of the boot-gate — otherwise a too-short JWT_SECRET slips through.
   sf.addVariableStatement({
@@ -273,7 +426,7 @@ function renderMain(appName: string): string {
     declarations: [
       {
         name: "bootFeatures",
-        initializer: "composeFeatures(APP_FEATURES, { includeBundled: true })",
+        initializer: "composeFeatures(APP_FEATURES, { includeBundled: HAS_AUTH })",
       },
     ],
   });
@@ -294,7 +447,7 @@ function renderMain(appName: string): string {
       .inlineBlock(() => {
         writer.writeLine("features: APP_FEATURES,");
         writer.writeLine("envSchema,");
-        writer.writeLine("migrations: false,");
+        writer.writeLine('staticDir: "./dist",');
         writer.write("auth: ").inlineBlock(() => {
           writer.write("admin: ").inlineBlock(() => {
             writer.writeLine(`email: "admin@${appName}.local",`);
@@ -458,19 +611,20 @@ KUMIKO_DEV_DB_NAME=${devDb}
 `;
 }
 
-// Local Postgres + Redis for `bun dev`. Ports + credentials match the *_URL
-// defaults in renderEnvExample, so `docker compose up -d` (referenced by the
-// README) just works with the generated .env. Named pg volume so dev data
-// survives `docker compose down` (pairs with KUMIKO_DEV_DB_NAME persistence).
-// Ports bind to 127.0.0.1 only: the dev DB (postgres/postgres) and auth-less
-// Redis must not be reachable from the LAN on a machine without a firewall.
+// Ports + credentials match the *_URL defaults in renderEnvExample, so
+// `docker compose up -d` just works with the generated .env. Named pg volume
+// so dev data survives `docker compose down` (pairs with KUMIKO_DEV_DB_NAME
+// persistence) — the loopback-binding rationale is in the generated file's
+// own comment (657/1), no need to duplicate it here.
 function renderDockerCompose(): string {
   return `# Local Postgres + Redis for \`bun dev\`. Matches the *_URL defaults in .env.example.
 # Start: docker compose up -d   ·   Stop: docker compose down   ·   Reset: docker compose down -v
 # Ports bind to 127.0.0.1 only — weak dev credentials must not be exposed on the LAN.
 services:
   postgres:
-    image: postgres:18
+    # Pinned to the project's own compose-file tag (663/1) — Alpine variant
+    # (~90MB vs ~400MB) and a reproducible patch version, bump on PG18 minors.
+    image: postgres:18.3-alpine
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
@@ -530,17 +684,140 @@ bun run boot
 Runs \`KUMIKO_DRY_RUN_ENV=boot bun bin/main.ts\` — validates feature composition
 + env schema, exits 0 without touching DB/Redis. Useful in CI.
 
+## Production build + schema
+
+\`\`\`sh
+bun run build          # kumiko-build → dist/ + dist-server/
+bun run schema:apply   # apply checked-in kumiko/migrations (needs DATABASE_URL)
+bun run start          # runProdApp against dist/
+\`\`\`
+
+After adding entities/features, regenerate migrations:
+
+\`\`\`sh
+bun run schema:generate <name>
+\`\`\`
+
+## Deploy
+
+\`deploy/Dockerfile\` + \`deploy/migrate-step.sh\` are scaffolded for container
+deploys. Build context = app repo root; migrations ship in \`kumiko/migrations/\`.
+
 ## Architecture
 
-- \`src/run-config.ts\` — single source of truth: which features your app mounts.
+- \`src/run-config.ts\` — single source of truth: which features your app mounts (\`APP_FEATURES\`, \`HAS_AUTH\`).
+- \`kumiko/schema.ts\` — same feature set → \`ENTITY_METAS\` for \`kumiko schema\`.
 - \`bin/dev.ts\` — dev-server entry (\`bun dev\`).
-- \`bin/main.ts\` — production-bootstrap (\`bun run boot\` smoke + production deploy).
+- \`bin/main.ts\` — production-bootstrap (\`bun run start\`).
+- \`bin/kumiko.ts\` — schema-CLI bundled into \`dist-server/kumiko.js\`.
 - \`docker-compose.yml\` — local Postgres + Redis for \`bun dev\`.
 
 For full docs see https://docs.kumiko.rocks.
 `;
 }
 
+function renderStylesCss(): string {
+  return [
+    '@import "@cosmicdrift/kumiko-renderer-web/styles.css";',
+    "",
+    '@source "./**/*.{ts,tsx}";',
+    "",
+  ].join("\n");
+}
+
+function renderKumikoSchema(): string {
+  return [
+    "// Live ENTITY_METAS source for `kumiko schema generate|apply|status`.",
+    "//",
+    "// Computes table-metas from the SAME composeFeatures(APP_FEATURES) the",
+    "// runtime sees (runProdApp/runDevApp) — migration and runtime cannot drift.",
+    "",
+    'import { composeFeatures } from "@cosmicdrift/kumiko-dev-server/compose-features";',
+    'import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";',
+    'import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";',
+    'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
+    "",
+    "export const FEATURES: readonly FeatureDefinition[] = composeFeatures([...APP_FEATURES], {",
+    "  includeBundled: HAS_AUTH,",
+    "});",
+    "",
+    "export const ENTITY_METAS: readonly EntityTableMeta[] = collectTableMetas(FEATURES);",
+    "",
+  ].join("\n");
+}
+
+function renderBinKumiko(): string {
+  return [
+    "#!/usr/bin/env bun",
+    "",
+    "// Standalone kumiko schema-CLI for the production bundle. The deploy",
+    "// migrate-step runs `bun /app/kumiko.js schema apply`; kumiko-build bundles",
+    "// this file to dist-server/kumiko.js.",
+    "",
+    'import { composeFeatures } from "@cosmicdrift/kumiko-dev-server/compose-features";',
+    'import { runSchemaCli } from "@cosmicdrift/kumiko-framework/schema-cli";',
+    'import { APP_FEATURES, HAS_AUTH } from "../src/run-config";',
+    "",
+    "const [, , cmd, ...rest] = Bun.argv;",
+    'if (cmd !== "schema") {',
+    "  // biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
+    '  console.error("\\n  Unbekannt: kumiko " + (cmd ?? "") + " — nur \'kumiko schema <sub>\' im Standalone-Bundle.\\n");',
+    "  process.exit(1);",
+    "}",
+    "",
+    "const features = composeFeatures([...APP_FEATURES], { includeBundled: HAS_AUTH });",
+    "// biome-ignore lint/suspicious/noConsole: CLI output is the feature.",
+    "const out = { log: (l: string) => console.log(l), err: (l: string) => console.error(l) };",
+    "process.exit(await runSchemaCli(rest, process.env.INIT_CWD ?? process.cwd(), out, { features }));",
+    "",
+  ].join("\n");
+}
+
+async function instantiateScaffoldFeatures(
+  features?: ReadonlyArray<ScaffoldFeatureEntry>,
+): Promise<readonly FeatureDefinition[]> {
+  const base = features?.length ? features : FOUNDATION_FEATURES;
+  const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
+  const instances: FeatureDefinition[] = [];
+  for (const entry of effective) {
+    const mod = (await import(entry.importPath)) as Record<string, unknown>;
+    const exp = mod[entry.exportName];
+    if (exp === undefined) {
+      throw new Error(
+        `scaffoldApp: ${entry.importPath} missing export ${entry.exportName} for ${entry.callExpression}`,
+      );
+    }
+    if (entry.callExpression.endsWith("()")) {
+      if (typeof exp !== "function") {
+        throw new Error(`scaffoldApp: ${entry.exportName} is not callable (${entry.importPath})`);
+      }
+      instances.push((exp as () => FeatureDefinition)());
+    } else {
+      instances.push(exp as FeatureDefinition);
+    }
+  }
+  return instances;
+}
+
+async function writeInitMigration(
+  destination: string,
+  features?: ReadonlyArray<ScaffoldFeatureEntry>,
+): Promise<void> {
+  const instances = await instantiateScaffoldFeatures(features);
+  const composed = composeFeatures(instances, { includeBundled: true });
+  const metas = collectTableMetas(composed);
+  const result = generateMigration({
+    metas,
+    prevSnapshot: null,
+    name: "init",
+    sequenceNumber: 1,
+  });
+  const migrationsDir = join(destination, "kumiko", "migrations");
+  mkdirSync(migrationsDir, { recursive: true });
+  writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
+  writeSnapshotJson(join(migrationsDir, ".snapshot.json"), result.snapshot);
+}
+
 // 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.