@cosmicdrift/kumiko-dev-server 0.118.0 → 0.119.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.118.0",
+  "version": "0.119.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.118.0",
-    "@cosmicdrift/kumiko-framework": "0.118.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.119.0",
+    "@cosmicdrift/kumiko-framework": "0.119.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/__tests__/pii-boot-gate.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { assertPiiBootInvariants } from "../pii-boot-gate";
+
+const piiFeature = defineFeature("gate-pii", (r) => {
+  r.entity(
+    "person",
+    createEntity({
+      table: "read_gate_persons",
+      fields: { email: createTextField({ required: true, pii: true, lookupable: true }) },
+    }),
+  );
+});
+const plainFeature = defineFeature("gate-plain", (r) => {
+  r.entity(
+    "thing",
+    createEntity({ table: "read_gate_things", fields: { name: createTextField() } }),
+  );
+});
+
+const kms = new InMemoryKmsAdapter();
+const KEY = Buffer.alloc(32, 7).toString("base64");
+
+describe("assertPiiBootInvariants — prod", () => {
+  test("PII without a KMS aborts boot", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "prod" })).toThrow(
+      /BOOT ABORTED.*PLAINTEXT.*allowPlaintextPii/s,
+    );
+  });
+
+  test("explicit allowPlaintextPii downgrades to a warning", () => {
+    expect(() =>
+      assertPiiBootInvariants([piiFeature], {
+        mode: "prod",
+        allowPlaintextPii: "kms rollout pending, infra#188",
+      }),
+    ).not.toThrow();
+  });
+
+  test("KMS + blindIndexKey boots", () => {
+    expect(() =>
+      assertPiiBootInvariants([piiFeature], { mode: "prod", kms, blindIndexKey: KEY }),
+    ).not.toThrow();
+  });
+
+  test("KMS without blindIndexKey aborts when lookupable fields exist", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "prod", kms })).toThrow(
+      /blindIndexKey/,
+    );
+  });
+
+  test("no PII entities → nothing to gate", () => {
+    expect(() => assertPiiBootInvariants([plainFeature], { mode: "prod" })).not.toThrow();
+  });
+});
+
+describe("assertPiiBootInvariants — dev", () => {
+  test("PII without a KMS only warns in dev", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "dev" })).not.toThrow();
+  });
+
+  test("KMS without blindIndexKey aborts in dev too (lookups broken in any mode)", () => {
+    expect(() => assertPiiBootInvariants([piiFeature], { mode: "dev", kms })).toThrow(
+      /blindIndexKey/,
+    );
+  });
+});

package/src/__tests__/run-prod-app.integration.test.ts

@@ -789,7 +789,10 @@ describe("runProdApp — auth allowedOrigins forwarding", () => {
 
   test("cookieDomain without allowedOrigins fails closed — guard is wired through runProdApp", async () => {
     await expect(
-      boot(undefined, { auth: { admin: ADMIN, cookieDomain: "example.eu" } }),
+      boot(undefined, {
+        auth: { admin: ADMIN, cookieDomain: "example.eu" },
+        allowPlaintextPii: "test: origin-guard focus, not crypto",
+      }),
     ).rejects.toThrow(/allowedOrigins is empty/);
   });
 
@@ -884,3 +887,29 @@ describe("runProdApp job-lane wiring (runSingleInstance)", () => {
     await expect(boot(undefined, { kms: unhealthyKms })).rejects.toThrow(/KMS health check failed/);
   });
 });
+
+describe("hard PII boot gate (#818 step 2)", () => {
+  const gatePiiFeature = defineFeature("gate-pii", (r) => {
+    r.entity(
+      "gate-person",
+      createEntity({
+        table: "read_gate_persons",
+        fields: { email: createTextField({ required: true, pii: true }) },
+      }),
+    );
+  });
+
+  test("PII entities without a kms abort the boot", async () => {
+    await expect(boot(undefined, { features: [gatePiiFeature] })).rejects.toThrow(
+      /BOOT ABORTED.*PLAINTEXT.*allowPlaintextPii/s,
+    );
+  });
+
+  test("allowPlaintextPii boots with a warning instead", async () => {
+    const handle = await boot(undefined, {
+      features: [gatePiiFeature],
+      allowPlaintextPii: "test: kms rollout pending",
+    });
+    expect(handle).toBeDefined();
+  });
+});

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

@@ -13,6 +13,9 @@ const SCAFFOLD_FILES = [
   "bunfig.toml",
   "bunfig.ci.toml",
   "src/run-config.ts",
+  "src/features/tasks/feature.ts",
+  "src/features/tasks/index.ts",
+  "src/seed.ts",
   "kumiko/schema.ts",
   "bin/main.ts",
   "bin/dev.ts",
@@ -202,13 +205,15 @@ describe("scaffoldApp", () => {
     );
   });
 
-  test("src/run-config.ts mounts secrets + sessions + HAS_AUTH", async () => {
+  test("src/run-config.ts mounts secrets + sessions + tasks + HAS_AUTH", async () => {
     const dest = join(tmp, "my-shop");
     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("tasksFeature");
+    expect(runConfig).toContain('from "./features/tasks"');
     expect(runConfig).toContain("export const APP_FEATURES");
     expect(runConfig).toContain("export const HAS_AUTH");
   });
@@ -362,6 +367,7 @@ describe("scaffoldApp", () => {
     const cfg = readFileSync(join(dest, "src/run-config.ts"), "utf-8");
     expect(cfg).not.toContain("createSecretsFeature");
     expect(cfg).not.toContain("createSessionsFeature");
+    expect(cfg).toContain("tasksFeature");
   });
 
   test("deterministic tenantId for same name (reproducible boots)", async () => {

package/src/pii-boot-gate.ts

@@ -0,0 +1,62 @@
+import {
+  collectLookupableFields,
+  collectPiiSubjectFields,
+  type KmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+type PiiGateOptions = {
+  readonly kms?: KmsAdapter | undefined;
+  readonly blindIndexKey?: string | undefined;
+  readonly allowPlaintextPii?: string | undefined;
+  /** prod fails hard on plaintext PII (opt-out via allowPlaintextPii);
+   *  dev only warns — local data, and an InMemory KMS against a persistent
+   *  dev DB would strand every row after a restart. */
+  readonly mode: "prod" | "dev";
+};
+
+export function assertPiiBootInvariants(
+  features: readonly FeatureDefinition[],
+  opts: PiiGateOptions,
+): void {
+  const tag = opts.mode === "prod" ? "runProdApp" : "runDevApp";
+
+  const lookupableEntities = features.flatMap((feature) =>
+    Object.entries(feature.entities ?? {})
+      .filter(([, entity]) => collectLookupableFields(entity).length > 0)
+      .map(([name]) => name),
+  );
+  if (opts.kms && !opts.blindIndexKey && lookupableEntities.length > 0) {
+    throw new Error(
+      `[${tag}] BOOT ABORTED — entities [${lookupableEntities.join(", ")}] declare lookupable fields and a KMS is configured, but no blindIndexKey was passed. Equality lookups on encrypted fields would silently stop matching. Pass { blindIndexKey } (env: KUMIKO_BLIND_INDEX_KEY, generate: openssl rand -base64 32).`,
+    );
+  }
+
+  // skip: KMS configured — PII fields are encrypted, nothing left to gate.
+  if (opts.kms) return;
+  const piiEntities = features.flatMap((feature) =>
+    Object.entries(feature.entities ?? {})
+      .filter(([, entity]) => collectPiiSubjectFields(entity).length > 0)
+      .map(([name]) => name),
+  );
+  // skip: no PII-annotated entities mounted — plaintext gate is moot.
+  if (piiEntities.length === 0) return;
+
+  if (opts.mode === "dev") {
+    // biome-ignore lint/suspicious/noConsole: boot-time security warning
+    console.warn(
+      `[${tag}] ${piiEntities.length} entities carry pii/userOwned/tenantOwned annotations but no \`kms\` adapter is configured — fields are stored in PLAINTEXT locally. Pass { kms: new InMemoryKmsAdapter() } (ephemeral DB) or createPgKmsAdapter(...) to exercise crypto-shredding in dev.`,
+    );
+    return;
+  }
+  if (opts.allowPlaintextPii) {
+    // biome-ignore lint/suspicious/noConsole: boot-time security warning
+    console.warn(
+      `[${tag}] ${piiEntities.length} entities carry PII annotations but no \`kms\` adapter is configured — fields are stored in PLAINTEXT (allowPlaintextPii: "${opts.allowPlaintextPii}"). GDPR erasure via crypto-shredding is NOT possible until a KMS is provisioned.`,
+    );
+    return;
+  }
+  throw new Error(
+    `[${tag}] BOOT ABORTED — entities [${piiEntities.join(", ")}] carry pii/userOwned/tenantOwned annotations but no \`kms\` adapter is configured. The fields would be stored in PLAINTEXT and GDPR erasure (crypto-shredding) could not work. Pass runProdApp({ kms: createPgKmsAdapter({ databaseUrl, platformKek }) }) — or acknowledge explicitly with { allowPlaintextPii: "<reason>" } until your KMS is provisioned.`,
+  );
+}

package/src/run-dev-app.ts

@@ -37,6 +37,11 @@ import {
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import type { PatResolver, SessionMetadata } from "@cosmicdrift/kumiko-framework/api";
 import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  type KmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
 import {
   collectWriteHandlerQns,
@@ -56,7 +61,6 @@ import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { applyBootSeeds } from "./boot/apply-boot-seeds";
 import { resolveBootCrypto } from "./boot/boot-crypto";
-
 import { watchAndRegenerate } from "./codegen";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
 import {
@@ -64,6 +68,7 @@ import {
   createKumikoServer,
   type KumikoServerHandle,
 } from "./create-kumiko-server";
+import { assertPiiBootInvariants } from "./pii-boot-gate";
 import { renderWelcomeBanner } from "./welcome-banner";
 
 // Re-export der shared Auth-Setup-Types damit Apps nur einen Import-Pfad
@@ -187,6 +192,16 @@ export type RunDevAppOptions = {
    *  `createEnvMasterKeyProvider`. Override für KMS-Backends. Nur relevant
    *  wenn das secrets-Feature gemountet ist. Symmetrisch zu runProdApp. */
   readonly masterKey?: MasterKeyProvider;
+  /** Subject-Key-KMS für pii-annotierte Felder (Crypto-Shredding) — dev-
+   *  Pendant zu runProdApp({ kms }). Ephemere DB: InMemoryKmsAdapter reicht.
+   *  Persistente Dev-DB: createPgKmsAdapter gegen dieselbe DB, sonst sind
+   *  alte Rows nach dem Restart unlesbar (DEKs weg). Ohne Adapter: Klartext
+   *  + Boot-Warnung. */
+  readonly kms?: KmsAdapter;
+  /** 32-Byte-Key (base64) für Blind-Index-HMACs — Pflicht sobald `kms`
+   *  gesetzt ist und lookupable-Felder gemountet sind (sonst Boot-Abbruch,
+   *  symmetrisch zu runProdApp). */
+  readonly blindIndexKey?: string;
   /** Env-Quelle für die ENV→config-app-override-Brücke (Keys mit `env:`
    *  bekommen ihren env-Wert als app-override-Default — symmetrisch zu
    *  runProdApp). Default `process.env`. Injizierbar als Test-Seam, damit
@@ -326,6 +341,16 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
   // App-wide cipher for `encrypted: true` entity fields (symmetrisch zu
   // runProdApp) — executors resolve it lazily.
   configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+  // Subject-KMS + Blind-Index (symmetrisch zu runProdApp). Dev warnt bei
+  // Klartext-PII statt zu failen; kms+lookupable ohne blindIndexKey bricht
+  // auch hier (Lookups wären in jedem Modus kaputt).
+  configurePiiSubjectKms(options.kms);
+  configureBlindIndexKey(options.blindIndexKey);
+  assertPiiBootInvariants(features, {
+    kms: options.kms,
+    blindIndexKey: options.blindIndexKey,
+    mode: "dev",
+  });
   const cfgExtra = effectiveAuth
     ? mergeConfigResolverDefault(
         options.extraContext,

package/src/run-prod-app.ts

@@ -77,7 +77,11 @@ import {
   createSseBroker,
   type SseBroker,
 } from "@cosmicdrift/kumiko-framework/api";
-import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  type KmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import {
   configureEntityFieldEncryption,
   createDbConnection,
@@ -134,6 +138,7 @@ import { ASSETS_DIR } from "./build-prod-bundle";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features";
 import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
 import { injectSchema } from "./inject-schema";
+import { assertPiiBootInvariants } from "./pii-boot-gate";
 import {
   type ProdSessionsConfig,
   type ProdSessionsOption,
@@ -484,6 +489,20 @@ export type RunProdAppOptions = {
    *  (Silent-Start würde jeden PII-Read mit 503 beantworten). Kein Default:
    *  ohne Adapter bleibt Crypto-Shredding aus. */
   readonly kms?: KmsAdapter;
+  /** 32-Byte-Key (base64) für Blind-Index-HMACs auf `lookupable`-Feldern
+   *  (env: KUMIKO_BLIND_INDEX_KEY, `openssl rand -base64 32`). Bewusst
+   *  getrennt vom PLATFORM_KEK und nicht Teil des KmsAdapter-Contracts.
+   *  Pflicht sobald `kms` gesetzt ist UND ein Feature lookupable-Felder
+   *  deklariert — sonst bricht jeder Equality-Lookup auf Ciphertext
+   *  (Login by email!) und der Boot failt hart. */
+  readonly blindIndexKey?: string;
+  /** Explizites Opt-out aus dem harten PII-Boot-Gate: Features deklarieren
+   *  pii/userOwned/tenantOwned-Felder, aber es ist (noch) kein `kms`
+   *  provisioniert — die Felder liegen dann als KLARTEXT in Rows und
+   *  Events und DSGVO-Erasure via Crypto-Shredding ist unmöglich. Der Wert
+   *  ist eine Begründung für den Audit-Trail (z.B. "kms rollout pending,
+   *  infra#188"). Ohne Flag und ohne `kms` bricht der Boot ab. */
+  readonly allowPlaintextPii?: string;
   /** Deploy-Topologie. Default `true` (Single-Container): dieser Prozess
    *  fährt HTTP + BEIDE Job-Lanes (api + worker) + den Event-Dispatcher
    *  (MSP-Anwendung) inline — via `createAllInOneEntrypoint`. Damit laufen
@@ -837,6 +856,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   validateBoot(features);
   warnIfNonUtcServerTimeZone();
   validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
+  assertPiiBootInvariants(features, {
+    kms: options.kms,
+    blindIndexKey: options.blindIndexKey,
+    allowPlaintextPii: options.allowPlaintextPii,
+    mode: "prod",
+  });
   const registry = createRegistry(features);
 
   // C1 boot-mode exit: validators ran + registry built; no DB/Redis client
@@ -943,6 +968,16 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // App-wide cipher for `encrypted: true` entity fields — executors resolve
   // it lazily, entities without encrypted fields never touch it.
   configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+  // Subject-key KMS for pii-annotated fields (crypto-shredding, #724).
+  // No adapter = engine off, plaintext as before — the warning keeps the gap
+  // visible until the prod-grade PgKmsAdapter (phase E) makes a hard boot
+  // gate viable (InMemory in prod would lose every DEK on restart).
+  configurePiiSubjectKms(options.kms);
+  // Blind-Index-Key (#818) — Boot-Gate: mit aktivem KMS würden lookupable-
+  // Felder als Ciphertext gespeichert, ohne Key gäbe es keinen bidx-Arm und
+  // jeder Equality-Lookup (Login by email!) liefe ins Leere. Fail-fast statt
+  // silent-broken-auth.
+  configureBlindIndexKey(options.blindIndexKey);
   const autoExtraContext = buildBootExtraContext({
     db,
     features,

package/src/scaffold-app.ts

@@ -22,6 +22,12 @@ 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 {
+  createDemoTasksFeature,
+  renderDemoSeedFile,
+  renderDemoTasksFeatureFile,
+  renderDemoTasksIndex,
+} from "./scaffold-demo-tasks";
 import { scaffoldDeploy } from "./scaffold-deploy";
 
 // Single bundled-feature entry the scaffolder mounts into run-config.ts.
@@ -95,6 +101,14 @@ export async function scaffoldApp(options: ScaffoldAppOptions): Promise<Scaffold
   write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
   files.push("src/run-config.ts");
 
+  mkdirSync(join(destination, "src", "features", "tasks"), { recursive: true });
+  write(join(destination, "src", "features", "tasks", "feature.ts"), renderDemoTasksFeatureFile());
+  files.push("src/features/tasks/feature.ts");
+  write(join(destination, "src", "features", "tasks", "index.ts"), renderDemoTasksIndex());
+  files.push("src/features/tasks/index.ts");
+  write(join(destination, "src", "seed.ts"), renderDemoSeedFile());
+  files.push("src/seed.ts");
+
   write(join(destination, "kumiko", "schema.ts"), renderKumikoSchema());
   files.push("kumiko/schema.ts");
 
@@ -345,15 +359,19 @@ function renderRunConfig(features?: ReadonlyArray<ScaffoldFeatureEntry>): string
   for (const [importPath, namedImports] of grouped) {
     sf.addImportDeclaration({ moduleSpecifier: importPath, namedImports });
   }
+  sf.addImportDeclaration({
+    moduleSpecifier: "./features/tasks",
+    namedImports: ["tasksFeature"],
+  });
 
-  const callList = effective.map((f) => f.callExpression).join(", ");
+  const callExprs = [...effective.map((f) => f.callExpression), "tasksFeature"];
   sf.addVariableStatement({
     declarationKind: VariableDeclarationKind.Const,
     isExported: true,
     declarations: [
       {
         name: "APP_FEATURES",
-        initializer: `[${callList}] as const`,
+        initializer: `[${callExprs.join(", ")}] as const`,
       },
     ],
   });
@@ -504,6 +522,10 @@ function renderDev(appName: string): string {
     moduleSpecifier: "../src/run-config",
     namedImports: ["APP_FEATURES"],
   });
+  sf.addImportDeclaration({
+    moduleSpecifier: "../src/seed",
+    namedImports: ["seedDemoTasks"],
+  });
 
   sf.addVariableStatement({
     declarationKind: VariableDeclarationKind.Const,
@@ -522,6 +544,7 @@ function renderDev(appName: string): string {
         writer.writeLine("features: APP_FEATURES,");
         writer.writeLine("welcomeBanner: true,");
         writer.writeLine(`clientEntry: "./src/client.tsx",`);
+        writer.writeLine("seeds: [seedDemoTasks],");
         writer.write("auth: ").inlineBlock(() => {
           writer.write("admin: ").inlineBlock(() => {
             writer.writeLine(`email: "admin@${appName}.local",`);
@@ -647,33 +670,36 @@ function renderReadme(
 ): string {
   const featureList =
     features && features.length > 0
-      ? features.map((f) => `- \`${f.name}\``).join("\n")
-      : "- `secrets` (foundation)\n- `sessions` (foundation)";
+      ? [...features.map((f) => `- \`${f.name}\``), "- `tasks` (demo — list + edit screens)"].join(
+          "\n",
+        )
+      : "- `secrets` (foundation)\n- `sessions` (foundation)\n- `tasks` (demo — list + edit screens)";
   return `# ${appName}
 
-Scaffolded by \`bun create kumiko-app\`. Boots out-of-the-box with the picked
-feature stack mounted. Add features by editing \`src/run-config.ts\` or via
-\`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
+Scaffolded by \`kumiko new app\`. Includes a demo **tasks** feature with list +
+edit screens, sidebar nav, and seeded rows — \`bun dev\` shows a working admin UI
+after login. Add more features via \`bunx @cosmicdrift/kumiko-cli add feature <name>\`.
 
 ## Mounted features
 
 ${featureList}
 
-Edit \`src/run-config.ts\` to add or remove.
+Edit \`src/run-config.ts\` to add bundled features. The demo lives in
+\`src/features/tasks/\`.
 
-## First run
+## First run (browser)
 
 \`\`\`sh
 bun install
 cp .env.example .env
-# edit .env — set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1, point DATABASE_URL/REDIS_URL at a real PG+Redis
-docker compose up -d   # if you don't have PG+Redis running already
+# set JWT_SECRET + KUMIKO_SECRETS_MASTER_KEY_V1 in .env
+docker compose up -d   # local Postgres + Redis (skip if you already have them)
 bun dev
 \`\`\`
 
-The dev-server prints a welcome banner with the URL + admin login when ready.
-Edits to \`src/features/**\` trigger a process restart (\`bun --watch\`); new
-\`r.entity(...)\` calls auto-create tables on reboot — no manual migration.
+The welcome banner prints the URL (default \`http://localhost:4173\`) and admin
+login. Sign in as \`admin@${appName}.local\` / \`changeme\`, then open **Tasks**
+in the sidebar — demo rows are pre-seeded.
 
 ## Boot-only smoke (no DB needed)
 
@@ -706,6 +732,8 @@ 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 (\`APP_FEATURES\`, \`HAS_AUTH\`).
+- \`src/features/tasks/\` — demo feature (entity + handlers + screens + nav).
+- \`src/seed.ts\` — dev seed for demo tasks (\`bun dev\` only).
 - \`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 start\`).
@@ -796,6 +824,7 @@ async function instantiateScaffoldFeatures(
       instances.push(exp as FeatureDefinition);
     }
   }
+  instances.push(createDemoTasksFeature());
   return instances;
 }
 

package/src/scaffold-demo-tasks.ts

@@ -0,0 +1,173 @@
+// Demo `tasks` feature + seed for scaffolded apps — wasp-like starter UX.
+// `createDemoTasksFeature()` feeds init-migration generation; the render*
+// functions emit the same shape into the user's repo.
+
+import {
+  createBooleanField,
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+const taskEntity = createEntity({
+  fields: {
+    title: createTextField({ required: true, sortable: true }),
+    status: createTextField({ sortable: true }),
+    priority: createNumberField(),
+    isUrgent: createBooleanField({ default: false }),
+  },
+});
+
+const listScreen: EntityListScreenDefinition = {
+  id: "task-list",
+  type: "entityList",
+  entity: "task",
+  columns: ["title", "status", "isUrgent", "priority"],
+  defaultSort: { field: "title", dir: "asc" },
+};
+
+const editScreen: EntityEditScreenDefinition = {
+  id: "task-edit",
+  type: "entityEdit",
+  entity: "task",
+  layout: {
+    sections: [{ title: "Task", fields: ["title", "status", "priority", "isUrgent"] }],
+  },
+};
+
+const open = { access: { openToAll: true } } as const;
+
+/** Canonical demo feature — keep in sync with `renderDemoTasksFeatureFile()`. */
+export function createDemoTasksFeature(): FeatureDefinition {
+  return defineFeature("tasks", (r) => {
+    r.entity("task", taskEntity);
+    r.writeHandler(defineEntityCreateHandler("task", taskEntity, open));
+    r.writeHandler(defineEntityUpdateHandler("task", taskEntity, open));
+    r.writeHandler(defineEntityDeleteHandler("task", taskEntity, open));
+    r.queryHandler(defineEntityListHandler("task", taskEntity, open));
+    r.queryHandler(defineEntityDetailHandler("task", taskEntity, open));
+    r.screen(listScreen);
+    r.screen(editScreen);
+    r.nav({ id: "tasks", label: "Tasks", order: 10, screen: "tasks:screen:task-list" });
+    r.nav({
+      id: "task-new",
+      label: "New task",
+      parent: "tasks:nav:tasks",
+      screen: "tasks:screen:task-edit",
+      order: 10,
+    });
+  });
+}
+
+export function renderDemoTasksFeatureFile(): string {
+  return `// Demo tasks feature — scaffolded by \`kumiko new app\`. Edit or replace.
+// Entity + CRUD handlers + list/edit screens + sidebar nav.
+
+import {
+  createBooleanField,
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type {
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+const taskEntity = createEntity({
+  fields: {
+    title: createTextField({ required: true, sortable: true }),
+    status: createTextField({ sortable: true }),
+    priority: createNumberField(),
+    isUrgent: createBooleanField({ default: false }),
+  },
+});
+
+const listScreen: EntityListScreenDefinition = {
+  id: "task-list",
+  type: "entityList",
+  entity: "task",
+  columns: ["title", "status", "isUrgent", "priority"],
+  defaultSort: { field: "title", dir: "asc" },
+};
+
+const editScreen: EntityEditScreenDefinition = {
+  id: "task-edit",
+  type: "entityEdit",
+  entity: "task",
+  layout: {
+    sections: [{ title: "Task", fields: ["title", "status", "priority", "isUrgent"] }],
+  },
+};
+
+const open = { access: { openToAll: true } } as const;
+
+export const tasksFeature = defineFeature("tasks", (r) => {
+  r.entity("task", taskEntity);
+  r.writeHandler(defineEntityCreateHandler("task", taskEntity, open));
+  r.writeHandler(defineEntityUpdateHandler("task", taskEntity, open));
+  r.writeHandler(defineEntityDeleteHandler("task", taskEntity, open));
+  r.queryHandler(defineEntityListHandler("task", taskEntity, open));
+  r.queryHandler(defineEntityDetailHandler("task", taskEntity, open));
+  r.screen(listScreen);
+  r.screen(editScreen);
+  r.nav({ id: "tasks", label: "Tasks", order: 10, screen: "tasks:screen:task-list" });
+  r.nav({
+    id: "task-new",
+    label: "New task",
+    parent: "tasks:nav:tasks",
+    screen: "tasks:screen:task-edit",
+    order: 10,
+  });
+});
+`;
+}
+
+export function renderDemoTasksIndex(): string {
+  return `export { tasksFeature } from "./feature";
+`;
+}
+
+export function renderDemoSeedFile(): string {
+  return `// Demo seed — a few tasks so \`bun dev\` shows a non-empty list.
+// Idempotent: skips when the tenant already has tasks (persistent dev DB).
+
+import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+
+const DEMO_TASKS = [
+  { title: "Welcome to Kumiko", status: "todo", priority: 1, isUrgent: false },
+  { title: "Try editing me", status: "in progress", priority: 2, isUrgent: true },
+] as const;
+
+export const seedDemoTasks: SeedFn = async (stack) => {
+  const admin = TestUsers.admin;
+  const existing = await stack.http.queryOk<{ rows: unknown[] }>(
+    "tasks:query:task:list",
+    {},
+    admin,
+  );
+  if (existing.rows.length > 0) return;
+  for (const task of DEMO_TASKS) {
+    await stack.http.write("tasks:write:task:create", task, admin);
+  }
+};
+`;
+}