@cosmicdrift/kumiko-dev-server 0.410.0 → 0.412.0

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export type { ScaffoldAppOptions, ScaffoldAppResult, ScaffoldFeatureEntry, } fro
 export { SCAFFOLD_BIOME_VERSION, scaffoldApp } from "./scaffold-app.ts";
 export type { ScaffoldAppFeatureOptions, ScaffoldAppFeatureResult, } from "./scaffold-app-feature.ts";
 export { runConfigPathForApp, scaffoldAppFeature } from "./scaffold-app-feature.ts";
+export { SCAFFOLD_STARTERS, type ScaffoldStarter } from "./scaffold-blank-starter.ts";
 export type { CheckDeployDriftResult, DeployDriftEntry, RenderDeployFilesOptions, RenderDeployFilesResult, RenderedDeployFile, ScaffoldDeployDetected, ScaffoldDeployOptions, ScaffoldDeployResult, ScaffoldedFile, } from "./scaffold-deploy.ts";
 export { checkDeployDrift, renderDeployFiles, scaffoldDeploy } from "./scaffold-deploy.ts";
 export type { ScaffoldFeatureOptions, ScaffoldFeatureResult } from "./scaffold-feature.ts";

package/dist/index.js

@@ -29,6 +29,7 @@ export { runInitDeployCli } from "./init-deploy-cli.js";
 export { runDevApp } from "./run-dev-app.js";
 export { SCAFFOLD_BIOME_VERSION, scaffoldApp } from "./scaffold-app.js";
 export { runConfigPathForApp, scaffoldAppFeature } from "./scaffold-app-feature.js";
+export { SCAFFOLD_STARTERS } from "./scaffold-blank-starter.js";
 export { checkDeployDrift, renderDeployFiles, scaffoldDeploy } from "./scaffold-deploy.js";
 export { scaffoldFeature } from "./scaffold-feature.js";
 export { setupTestStackFromFeatures, } from "./setup-test-stack-from-features.js";

package/dist/scaffold-agent-docs.d.ts

@@ -1,13 +1,14 @@
 export declare const FRAMEWORK_AGENTS_IMPORT = "@node_modules/@cosmicdrift/kumiko-framework/AGENTS.md";
 export declare function renderMountedFeatureList(features: ReadonlyArray<{
     readonly name: string;
-}> | undefined): string;
+}> | undefined, starter?: "demo" | "blank"): string;
 export type AgentsMdOptions = {
     readonly productName: string;
     readonly features: ReadonlyArray<{
         readonly name: string;
     }> | undefined;
     readonly scriptNames: readonly string[];
+    readonly starter?: "demo" | "blank";
 };
 export declare function renderAgentsMd(options: AgentsMdOptions): string;
 export declare function renderClaudeMd(): string;

package/dist/scaffold-agent-docs.js

@@ -20,11 +20,11 @@ const SCRIPT_DESCRIPTIONS = {
 };
 const DEMO_TASKS_FEATURE_LINE = "- `tasks` (demo — list + edit screens)";
 const FOUNDATION_FEATURE_LINES = ["- `secrets` (foundation)", "- `sessions` (foundation)"];
-export function renderMountedFeatureList(features) {
+export function renderMountedFeatureList(features, starter = "demo") {
     const lines = features && features.length > 0
         ? features.map((f) => `- \`${f.name}\``)
         : FOUNDATION_FEATURE_LINES;
-    return [...lines, DEMO_TASKS_FEATURE_LINE].join("\n");
+    return (starter === "demo" ? [...lines, DEMO_TASKS_FEATURE_LINE] : lines).join("\n");
 }
 function renderCommandList(scriptNames) {
     return scriptNames
@@ -42,7 +42,7 @@ function agentsTemplatePath() {
 export function renderAgentsMd(options) {
     return render(readFileSync(agentsTemplatePath(), "utf-8"), {
         productName: options.productName,
-        featureList: renderMountedFeatureList(options.features),
+        featureList: renderMountedFeatureList(options.features, options.starter),
         commands: renderCommandList(options.scriptNames),
     }, {});
 }

package/dist/scaffold-app.d.ts

@@ -1,3 +1,5 @@
+import { type ScaffoldStarter } from "./scaffold-blank-starter.ts";
+export { SCAFFOLD_STARTERS, type ScaffoldStarter } from "./scaffold-blank-starter.ts";
 export type ScaffoldFeatureEntry = {
     readonly name: string;
     readonly importPath: string;
@@ -15,6 +17,7 @@ export type ScaffoldTestSetup = {
 export type ScaffoldTestSetupFactory = (input: {
     readonly appName: string;
     readonly frameworkVersion: string;
+    readonly starter?: ScaffoldStarter;
 }) => ScaffoldTestSetup;
 export declare const SCAFFOLD_BIOME_VERSION = "2.6.4";
 export type ScaffoldAppOptions = {
@@ -40,6 +43,9 @@ export type ScaffoldAppOptions = {
     readonly testSetup?: ScaffoldTestSetupFactory;
     /** Infra tag written to `package.json#kumiko.deploy.infraRef`. Default: CURRENT_INFRA_REF. */
     readonly infraRef?: string;
+    /** "demo" (default): demo tasks feature, admin seeded from DEMO_ADMIN_PASSWORD.
+     *  "blank": no demo; the creator is seeded from KUMIKO_BOOTSTRAP_ADMIN_EMAIL without a password. */
+    readonly starter?: ScaffoldStarter;
 };
 export type ScaffoldAppResult = {
     readonly destination: string;

package/dist/scaffold-app.js

@@ -28,7 +28,10 @@ import { resolveFrameworkVersion } from "./framework-version.js";
 import { isKebabSegment } from "./kebab.js";
 import { CURRENT_INFRA_REF, PREPARE_SCRIPT, resolveManagedAppFacts, syncManagedFiles, } from "./managed-files/index.js";
 import { renderAgentsMd, renderClaudeMd, renderMountedFeatureList } from "./scaffold-agent-docs.js";
+import { BLANK_ENV_EXAMPLE_ADMIN_BLOCK, BLANK_STARTER_DELIVERY_FEATURE, blankReadmeCopy, renderBlankEnvSchema, renderBlankMain, renderBlankServer, } from "./scaffold-blank-starter.js";
 import { createDemoTasksFeature, renderDemoSeedFile, renderDemoTasksFeatureFile, renderDemoTasksI18n, renderDemoTasksIndex, renderDemoTasksWebIndex, } from "./scaffold-demo-tasks.js";
+import { deriveTenantId, MAX_LINE_WIDTH, renderAdminAuthBlock, renderDefaultAppShellElement, renderSortedImports, } from "./scaffold-render-helpers.js";
+export { SCAFFOLD_STARTERS } from "./scaffold-blank-starter.js";
 // Exact pin (no caret): the generated files are formatted to this Biome's output,
 // and a scaffold-lint test keeps it equal to the monorepo's own Biome version.
 export const SCAFFOLD_BIOME_VERSION = "2.6.4";
@@ -39,7 +42,30 @@ dist-server/
 test-results/
 playwright-report/
 `;
-export async function scaffoldApp(options) {
+function writeDemoTasksFiles(destination, files) {
+    mkdirSync(join(destination, "src", "features", "tasks", "web"), { recursive: true });
+    write(join(destination, "src", "features", "tasks", "feature.ts"), renderDemoTasksFeatureFile());
+    files.push("src/features/tasks/feature.ts");
+    write(join(destination, "src", "features", "tasks", "i18n.ts"), renderDemoTasksI18n());
+    files.push("src/features/tasks/i18n.ts");
+    write(join(destination, "src", "features", "tasks", "index.ts"), renderDemoTasksIndex());
+    files.push("src/features/tasks/index.ts");
+    write(join(destination, "src", "features", "tasks", "web", "index.ts"), renderDemoTasksWebIndex());
+    files.push("src/features/tasks/web/index.ts");
+    write(join(destination, "src", "seed.ts"), renderDemoSeedFile());
+    files.push("src/seed.ts");
+}
+function writeBinFiles(destination, appName, isBlank, files) {
+    write(join(destination, "bin", "main.ts"), isBlank ? renderBlankMain(appName) : renderMain(appName));
+    files.push("bin/main.ts");
+    write(join(destination, "bin", "server.ts"), isBlank ? renderBlankServer(appName) : renderServer(appName));
+    files.push("bin/server.ts");
+    write(join(destination, "bin", "env-schema.ts"), isBlank ? renderBlankEnvSchema() : renderEnvSchema(appName));
+    files.push("bin/env-schema.ts");
+    write(join(destination, "bin", "kumiko.ts"), renderBinKumiko());
+    files.push("bin/kumiko.ts");
+}
+function resolveScaffoldTarget(options) {
     if (!isKebabSegment(options.name)) {
         throw new Error(`scaffoldApp: name must be kebab-case (a-z, 0-9, -); got "${options.name}"`);
     }
@@ -52,7 +78,17 @@ export async function scaffoldApp(options) {
     if (version === undefined) {
         throw new Error("scaffoldApp: cannot resolve the framework version; pass frameworkVersion explicitly");
     }
-    const testSetup = options.testSetup?.({ appName: options.name, frameworkVersion: version });
+    return { destination, version };
+}
+export async function scaffoldApp(options) {
+    const { destination, version } = resolveScaffoldTarget(options);
+    const starter = options.starter ?? "demo";
+    const isBlank = starter === "blank";
+    const testSetup = options.testSetup?.({
+        appName: options.name,
+        frameworkVersion: version,
+        ...(isBlank && { starter }),
+    });
     mkdirSync(join(destination, "bin"), { recursive: true });
     mkdirSync(join(destination, "src"), { recursive: true });
     mkdirSync(join(destination, "kumiko"), { recursive: true });
@@ -63,48 +99,30 @@ export async function scaffoldApp(options) {
     files.push("kumiko.json");
     write(join(destination, ".gitignore"), SCAFFOLD_GITIGNORE);
     files.push(".gitignore");
-    write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features));
+    write(join(destination, "src", "run-config.ts"), renderRunConfig(options.features, starter));
     files.push("src/run-config.ts");
-    mkdirSync(join(destination, "src", "features", "tasks", "web"), { recursive: true });
-    write(join(destination, "src", "features", "tasks", "feature.ts"), renderDemoTasksFeatureFile());
-    files.push("src/features/tasks/feature.ts");
-    write(join(destination, "src", "features", "tasks", "i18n.ts"), renderDemoTasksI18n());
-    files.push("src/features/tasks/i18n.ts");
-    write(join(destination, "src", "features", "tasks", "index.ts"), renderDemoTasksIndex());
-    files.push("src/features/tasks/index.ts");
-    write(join(destination, "src", "features", "tasks", "web", "index.ts"), renderDemoTasksWebIndex());
-    files.push("src/features/tasks/web/index.ts");
-    write(join(destination, "src", "seed.ts"), renderDemoSeedFile());
-    files.push("src/seed.ts");
+    if (!isBlank)
+        writeDemoTasksFiles(destination, files);
     write(join(destination, APP_CONFIG_FILE), renderAppConfig());
     files.push(APP_CONFIG_FILE);
-    write(join(destination, "bin", "main.ts"), renderMain(options.name));
-    files.push("bin/main.ts");
-    write(join(destination, "bin", "server.ts"), renderServer(options.name));
-    files.push("bin/server.ts");
-    write(join(destination, "bin", "env-schema.ts"), renderEnvSchema(options.name));
-    files.push("bin/env-schema.ts");
-    write(join(destination, "bin", "kumiko.ts"), renderBinKumiko());
-    files.push("bin/kumiko.ts");
-    write(join(destination, "src", "client.tsx"), renderClient(options.name));
+    writeBinFiles(destination, options.name, isBlank, files);
+    write(join(destination, "src", "client.tsx"), renderClient(options.name, starter));
     files.push("src/client.tsx");
     write(join(destination, "src", "styles.css"), renderStylesCss());
     files.push("src/styles.css");
     mkdirSync(join(destination, "public"), { recursive: true });
     write(join(destination, "public", "index.html"), renderIndexHtml(options.name));
     files.push("public/index.html");
-    write(join(destination, ".env.example"), renderEnvExample(options.name));
+    write(join(destination, ".env.example"), renderEnvExample(options.name, starter));
     files.push(".env.example");
     write(join(destination, "docker-compose.yml"), renderDockerCompose());
     files.push("docker-compose.yml");
-    await writeInitMigration(destination, options.features);
+    await writeInitMigration(destination, options.features, starter);
     files.push("kumiko/migrations/0001_init.sql", "kumiko/migrations/.snapshot.json");
-    if (testSetup !== undefined) {
-        for (const [rel, content] of Object.entries(testSetup.files)) {
-            mkdirSync(dirname(join(destination, rel)), { recursive: true });
-            write(join(destination, rel), content);
-            files.push(rel);
-        }
+    for (const [rel, content] of Object.entries(testSetup?.files ?? {})) {
+        mkdirSync(dirname(join(destination, rel)), { recursive: true });
+        write(join(destination, rel), content);
+        files.push(rel);
     }
     const managedFacts = resolveManagedAppFacts({
         appRoot: destination,
@@ -115,11 +133,12 @@ export async function scaffoldApp(options) {
         if (action.action === "create")
             files.push(action.path);
     }
-    write(join(destination, "README.md"), `${renderReadme(options.name, options.features)}${testSetup === undefined ? "" : `\n${testSetup.rulesMarkdown}`}`);
+    write(join(destination, "README.md"), `${renderReadme(options.name, options.features, starter)}${testSetup === undefined ? "" : `\n${testSetup.rulesMarkdown}`}`);
     files.push("README.md");
     write(join(destination, "AGENTS.md"), renderAgentsMd({
         productName: options.name,
         features: options.features,
+        starter,
         scriptNames: Object.keys(appScripts(testSetup)),
     }));
     files.push("AGENTS.md");
@@ -207,42 +226,7 @@ const FOUNDATION_FEATURES = [
 // scaffolded `bun dev`; filtering also protects direct scaffoldApp() calls that
 // pass all bundled-feature entries, keeping these four out of run-config.ts.
 const COMPOSE_AUTO_MOUNTED_NAMES = new Set(["config", "user", "tenant", "auth-email-password"]);
-const MAX_LINE_WIDTH = 100;
-// Mirrors Biome's import sort so generated files pass `biome check` untouched:
-// packages alphabetically by specifier, relative paths last.
-function compareImportKeys(a, b) {
-    const lowerA = a.replace(/^type /, "").toLowerCase();
-    const lowerB = b.replace(/^type /, "").toLowerCase();
-    if (lowerA !== lowerB)
-        return lowerA < lowerB ? -1 : 1;
-    return a < b ? -1 : a > b ? 1 : 0;
-}
-function isRelativeSpecifier(specifier) {
-    return specifier.startsWith("./") || specifier.startsWith("../");
-}
-function renderImportLine({ specifier, names, typeOnly, defaultName }) {
-    if (defaultName !== undefined)
-        return `import ${defaultName} from "${specifier}";`;
-    const sorted = [...names].sort(compareImportKeys);
-    const keyword = typeOnly === true ? "import type" : "import";
-    const oneLine = `${keyword} { ${sorted.join(", ")} } from "${specifier}";`;
-    if (sorted.length === 1 || oneLine.length <= MAX_LINE_WIDTH)
-        return oneLine;
-    return `${keyword} {\n${sorted.map((n) => `  ${n},`).join("\n")}\n} from "${specifier}";`;
-}
-function renderSortedImports(imports) {
-    return [...imports]
-        .sort((a, b) => {
-        const relativeA = isRelativeSpecifier(a.specifier);
-        const relativeB = isRelativeSpecifier(b.specifier);
-        if (relativeA !== relativeB)
-            return relativeA ? 1 : -1;
-        return compareImportKeys(a.specifier, b.specifier);
-    })
-        .map(renderImportLine)
-        .join("\n");
-}
-function renderRunConfig(features) {
+function effectiveScaffoldFeatures(features, starter) {
     // 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
@@ -250,6 +234,12 @@ function renderRunConfig(features) {
     // for.
     const base = features?.length ? features : FOUNDATION_FEATURES;
     const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
+    const needsDelivery = starter === "blank" && !effective.some((f) => f.name === BLANK_STARTER_DELIVERY_FEATURE.name);
+    return needsDelivery ? [...effective, BLANK_STARTER_DELIVERY_FEATURE] : effective;
+}
+function renderRunConfig(features, starter) {
+    const effective = effectiveScaffoldFeatures(features, starter);
+    const hasTasks = starter === "demo";
     const grouped = new Map();
     for (const entry of effective) {
         const existing = grouped.get(entry.importPath) ?? [];
@@ -260,9 +250,13 @@ function renderRunConfig(features) {
     const imports = [
         ...[...grouped].map(([specifier, names]) => ({ specifier, names })),
         { specifier: "@cosmicdrift/kumiko-locale-de", names: ["localeDe"] },
-        { specifier: "./features/tasks", names: ["tasksFeature"] },
+        ...(hasTasks ? [{ specifier: "./features/tasks", names: ["tasksFeature"] }] : []),
+    ];
+    const callExprs = [
+        ...effective.map((f) => f.callExpression),
+        "localeDe()",
+        ...(hasTasks ? ["tasksFeature"] : []),
     ];
-    const callExprs = [...effective.map((f) => f.callExpression), "localeDe()", "tasksFeature"];
     const oneLineFeatures = `export const APP_FEATURES = [${callExprs.join(", ")}] as const;`;
     const appFeatures = oneLineFeatures.length <= MAX_LINE_WIDTH
         ? oneLineFeatures
@@ -283,23 +277,6 @@ ${appFeatures}
 export const HAS_AUTH = true;
 `;
 }
-function renderAdminAuthBlock(appName, extraAdminLines) {
-    const passwordAndExtras = extraAdminLines.map((l) => `      ${l}`).join("\n");
-    return `  auth: {
-    admin: {
-      email: "admin@${appName}.local",
-${passwordAndExtras}
-      memberships: [
-        {
-          tenantId: DEFAULT_TENANT_ID,
-          tenantKey: "${appName}",
-          tenantName: "${appName}",
-          roles: ["TenantAdmin"],
-        },
-      ],
-    },
-  },`;
-}
 // Ports match runDevApp's default and kumiko-testing's SCAFFOLD_E2E_PORT.
 const SCAFFOLD_DEV_PORT = 4173;
 const SCAFFOLD_E2E_PORT = 4174;
@@ -442,42 +419,15 @@ ${authBlock}
 });
 `;
 }
-// Tiers mirror how Biome wraps the JSX as the name grows. The user spread
-// is part of every tier so the line-width math covers it.
-function renderDefaultAppShellElement(appName) {
-    const spanOpen = '<span className="font-semibold tracking-tight">';
-    const userSpread = "{...(user !== undefined && { user })}";
-    // html-ok: appName is kebab-validated (a-z/0-9/-); this is generated .tsx source, not runtime HTML.
-    const brandInline = `${spanOpen}${appName}</span>`;
-    const singleLine = `    <DefaultAppShell brand={${brandInline}} schema={schema} ${userSpread}>`;
-    if (singleLine.length <= MAX_LINE_WIDTH)
-        return singleLine;
-    const brandAttrInline = `      brand={${brandInline}}`;
-    const brandAttribute = brandAttrInline.length <= MAX_LINE_WIDTH
-        ? brandAttrInline
-        : `${[
-            "      brand={",
-            ...(`        ${brandInline}`.length <= MAX_LINE_WIDTH
-                ? [`        ${brandInline}`]
-                : [`        ${spanOpen}`, `          ${appName}`, "        </span>"]),
-            "      }",
-        ].join("\n")}`;
-    return [
-        "    <DefaultAppShell",
-        brandAttribute,
-        "      schema={schema}",
-        `      ${userSpread}`,
-        "    >",
-    ].join("\n");
-}
-function renderClient(appName) {
+function renderClient(appName, starter) {
+    const hasTasks = starter === "demo";
     const imports = renderSortedImports([
         {
             specifier: "@cosmicdrift/kumiko-bundled-features/auth-email-password/web",
             names: ["emailPasswordClient", "useShellUser"],
         },
         { specifier: "@cosmicdrift/kumiko-locale-de/web", names: ["localeDeClient"] },
-        { specifier: "./features/tasks/web", names: ["tasksClient"] },
+        ...(hasTasks ? [{ specifier: "./features/tasks/web", names: ["tasksClient"] }] : []),
         {
             specifier: "@cosmicdrift/kumiko-renderer/web",
             names: ["type AppSchema", "createKumikoApp", "DefaultAppShell"],
@@ -511,12 +461,19 @@ ${renderDefaultAppShellElement(appName)}
 
 createKumikoApp({
   shell: AppShell,
-  clientFeatures: [localeDeClient(), emailPasswordClient(), tasksClient],
+  clientFeatures: [localeDeClient(), emailPasswordClient()${hasTasks ? ", tasksClient" : ""}],
 });
 `;
 }
-function renderEnvExample(appName) {
+function renderEnvExample(appName, starter) {
     const devDb = `${appName.replace(/-/g, "_")}_dev`;
+    const adminBlock = starter === "blank"
+        ? BLANK_ENV_EXAMPLE_ADMIN_BLOCK
+        : `# DEMO_ADMIN_PASSWORD: password of the admin seeded on first prod boot
+# (admin@${appName}.local). Required by \`bun run boot\` and \`bun run start\`,
+# min 12 chars. Generate with: openssl rand -hex 24
+DEMO_ADMIN_PASSWORD=
+`;
     return `# bun dev (runDevApp → setupTestStack) needs TEST_DATABASE_URL.
 # Production (bun bin/main.ts → runProdApp) needs DATABASE_URL.
 # Both default to the same local Postgres — runDevApp creates its own
@@ -536,11 +493,7 @@ JWT_SECRET=change-me-min-32-chars-change-me-min-32
 # Generate with: openssl rand -base64 32
 KUMIKO_SECRETS_MASTER_KEY_V1=
 
-# DEMO_ADMIN_PASSWORD: password of the admin seeded on first prod boot
-# (admin@${appName}.local). Required by \`bun run boot\` and \`bun run start\`,
-# min 12 chars. Generate with: openssl rand -hex 24
-DEMO_ADMIN_PASSWORD=
-
+${adminBlock}
 # Subject-keys KMS for PII fields (user, tenant-invitation, fileRef). All-or-none.
 # Unset → local boot with plaintext PII + warning; NODE_ENV=production requires
 # the trio (requireKmsWiring). Generate PLATFORM_KEK / KUMIKO_BLIND_INDEX_KEY
@@ -590,20 +543,28 @@ volumes:
   kumiko-pg:
 `;
 }
-function renderReadme(appName, features) {
-    const featureList = renderMountedFeatureList(features);
+function demoReadmeCopy(appName) {
+    return {
+        intro: "Scaffolded by `kumiko new app`. Includes a demo **tasks** feature with list +\nedit screens, sidebar nav, and seeded rows — `bun dev` shows a working admin UI\nafter login. Add more features via `bunx @cosmicdrift/kumiko-cli add feature <name>`.",
+        runConfigNote: "Edit `src/run-config.ts` to add bundled features. The demo lives in\n`src/features/tasks/`.",
+        devLogin: `The welcome banner prints the URL (default \`http://localhost:4173\`) and admin\nlogin. Sign in as \`admin@${appName}.local\` / \`changeme\`, then open **Tasks**\nin the sidebar — demo rows are pre-seeded.`,
+        bootEnvNote: "a missing one exits 0 without validating the wiring, so set\n`DEMO_ADMIN_PASSWORD` (min 12 chars, `openssl rand -hex 24`) in `.env`.",
+        prodSeed: `The first prod boot seeds \`admin@${appName}.local\` with the password from\n\`DEMO_ADMIN_PASSWORD\` (required, min 12 chars). Log in with that.`,
+        demoArchitectureLines: "- `src/features/tasks/` — demo feature (entity + handlers + screens + nav).\n- `src/seed.ts` — dev seed for demo tasks (`bun dev` only).\n",
+    };
+}
+function renderReadme(appName, features, starter) {
+    const copy = starter === "blank" ? blankReadmeCopy(appName) : demoReadmeCopy(appName);
+    const featureList = renderMountedFeatureList(features, starter);
     return `# ${appName}
 
-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>\`.
+${copy.intro}
 
 ## Mounted features
 
 ${featureList}
 
-Edit \`src/run-config.ts\` to add bundled features. The demo lives in
-\`src/features/tasks/\`.
+${copy.runConfigNote}
 
 ## First run (browser)
 
@@ -615,9 +576,7 @@ docker compose up -d   # local Postgres + Redis (skip if you already have them)
 bun dev
 \`\`\`
 
-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.
+${copy.devLogin}
 
 ## Boot-only smoke (no DB needed)
 
@@ -628,8 +587,7 @@ 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. It prints every
 variable with its feature and status, never the value. An invalid value exits 1;
-a missing one exits 0 without validating the wiring, so set
-\`DEMO_ADMIN_PASSWORD\` (min 12 chars, \`openssl rand -hex 24\`) in \`.env\`.
+${copy.bootEnvNote}
 
 Without \`PLATFORM_KEK\` / \`SUBJECT_KEYS_DATABASE_URL\` / \`KUMIKO_BLIND_INDEX_KEY\`
 set (see \`.env.example\`), both \`bun run boot\` and \`bun run start\` boot with
@@ -644,8 +602,7 @@ bun run schema:apply   # apply checked-in kumiko/migrations (needs DATABASE_URL)
 bun run start          # runProdApp against dist/
 \`\`\`
 
-The first prod boot seeds \`admin@${appName}.local\` with the password from
-\`DEMO_ADMIN_PASSWORD\` (required, min 12 chars). Log in with that.
+${copy.prodSeed}
 
 After adding entities/features, regenerate migrations:
 
@@ -669,9 +626,7 @@ Files whose first line reads \`kumiko-managed\` (deploy/, .github/workflows/,
 ## 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.config.ts\` — the composed feature list, client entries and ports the tooling reads.
+${copy.demoArchitectureLines}- \`kumiko.config.ts\` — the composed feature list, client entries and ports the tooling reads.
 - \`kumiko/schema.ts\` — generated (\`kumiko-managed\`): \`ENTITY_METAS\` from kumiko.config.ts for \`kumiko schema\`.
 - \`bin/server.ts\` — dev-server entry (\`bun dev\`).
 - \`bin/env-schema.ts\` — env contract of the production processes.
@@ -770,9 +725,8 @@ function renderBinKumiko() {
         "",
     ].join("\n");
 }
-async function instantiateScaffoldFeatures(features) {
-    const base = features?.length ? features : FOUNDATION_FEATURES;
-    const effective = base.filter((f) => !COMPOSE_AUTO_MOUNTED_NAMES.has(f.name));
+async function instantiateScaffoldFeatures(features, starter) {
+    const effective = effectiveScaffoldFeatures(features, starter);
     const instances = [];
     for (const entry of effective) {
         const mod = (await import(__rewriteRelativeImportExtension(entry.importPath)));
@@ -791,11 +745,12 @@ async function instantiateScaffoldFeatures(features) {
             instances.push(exp);
         }
     }
-    instances.push(createDemoTasksFeature());
+    if (starter === "demo")
+        instances.push(createDemoTasksFeature());
     return instances;
 }
-async function writeInitMigration(destination, features) {
-    const instances = await instantiateScaffoldFeatures(features);
+async function writeInitMigration(destination, features, starter) {
+    const instances = await instantiateScaffoldFeatures(features, starter);
     const composed = composeFeatures(instances, { includeBundled: true });
     const metas = collectTableMetas(composed);
     const result = generateMigration({
@@ -810,29 +765,3 @@ async function writeInitMigration(destination, features) {
     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.
-function deriveTenantId(name) {
-    let state = 2166136261;
-    for (const ch of name) {
-        state ^= ch.charCodeAt(0);
-        state = Math.imul(state, 16777619) >>> 0;
-    }
-    // @wrapper-known semantic-alias
-    const hex = (n, len) => n.toString(16).padStart(len, "0").slice(0, len);
-    const a = hex(state, 8);
-    state ^= state << 13;
-    state >>>= 0;
-    const b = hex(state, 4);
-    state ^= state >>> 17;
-    state >>>= 0;
-    const c = `4${hex(state, 3)}`;
-    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/dist/scaffold-blank-starter.d.ts

@@ -0,0 +1,21 @@
+export declare const SCAFFOLD_STARTERS: readonly ["demo", "blank"];
+export type ScaffoldStarter = (typeof SCAFFOLD_STARTERS)[number];
+export declare const BLANK_STARTER_DELIVERY_FEATURE: {
+    readonly name: "delivery";
+    readonly importPath: "@cosmicdrift/kumiko-bundled-features/delivery";
+    readonly exportName: "createDeliveryFeature";
+    readonly callExpression: "createDeliveryFeature()";
+};
+export declare function renderBlankEnvSchema(): string;
+export declare function renderBlankMain(appName: string): string;
+export declare function renderBlankServer(appName: string): string;
+export declare const BLANK_ENV_EXAMPLE_ADMIN_BLOCK = "# KUMIKO_BOOTSTRAP_ADMIN_EMAIL: login of the person who created the app. The first prod\n# boot makes it the admin WITHOUT a password; set one via \"forgot password\". That needs\n# SMTP_HOST (+ SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM) and APP_BASE_URL (e.g.\n# https://app.example.com); without them the reset mail flow stays off.\n# KUMIKO_BOOTSTRAP_ADMIN_EMAIL=\n# SMTP_HOST=\n# APP_BASE_URL=\n";
+export type ReadmeCopy = {
+    readonly intro: string;
+    readonly runConfigNote: string;
+    readonly devLogin: string;
+    readonly bootEnvNote: string;
+    readonly prodSeed: string;
+    readonly demoArchitectureLines: string;
+};
+export declare function blankReadmeCopy(appName: string): ReadmeCopy;

package/dist/scaffold-blank-starter.js

@@ -0,0 +1,142 @@
+// The `blank` starter of scaffoldApp: no demo feature and no admin password in the env. The
+// person who creates the app is seeded from KUMIKO_BOOTSTRAP_ADMIN_EMAIL and sets a password
+// through "forgot password".
+import { deriveTenantId, renderAdminAuthBlock, renderSortedImports, } from "./scaffold-render-helpers.js";
+export const SCAFFOLD_STARTERS = ["demo", "blank"];
+// Delivery is what the `mail` boot option sends through.
+export const BLANK_STARTER_DELIVERY_FEATURE = {
+    name: "delivery",
+    importPath: "@cosmicdrift/kumiko-bundled-features/delivery",
+    exportName: "createDeliveryFeature",
+    callExpression: "createDeliveryFeature()",
+};
+export function renderBlankEnvSchema() {
+    const imports = renderSortedImports([
+        { specifier: "@cosmicdrift/kumiko-dev-server/env-schema", names: ["frameworkCoreEnvSchema"] },
+        { specifier: "@cosmicdrift/kumiko-framework/config", names: ["allAppFeatures"] },
+        { specifier: "@cosmicdrift/kumiko-framework/env", names: ["composeEnvSchema"] },
+    ]);
+    return `// Env contract of the production processes (bin/main.ts, bin/kumiko.ts).
+// Importing it must not read process.env; validation happens in runProdApp.
+// KUMIKO_BOOTSTRAP_ADMIN_EMAIL joins the schema through the seeds option in bin/main.ts.
+
+${imports}
+import appConfig from "../kumiko.config";
+
+export const envSchema = composeEnvSchema({
+  core: frameworkCoreEnvSchema,
+  features: allAppFeatures(appConfig),
+});
+`;
+}
+export function renderBlankMain(appName) {
+    const imports = renderSortedImports([
+        { specifier: "@cosmicdrift/kumiko-server-runtime", names: ["runProdApp"] },
+        { specifier: "@cosmicdrift/kumiko-framework/engine", names: ["TenantId"], typeOnly: true },
+        {
+            specifier: "@cosmicdrift/kumiko-framework/crypto",
+            names: ["requireKmsWiring", "resolveKmsWiring"],
+        },
+        {
+            specifier: "@cosmicdrift/kumiko-bundled-features/auth-email-password",
+            names: ["DEFAULT_AUTH_PATHS"],
+        },
+        { specifier: "../src/run-config", names: ["APP_FEATURES"] },
+        { specifier: "../kumiko.config", names: [], defaultName: "appConfig" },
+        { specifier: "./env-schema", names: ["envSchema"] },
+    ]);
+    return `// Production-bootstrap. KUMIKO_DRY_RUN_ENV=boot exits after
+// composeFeatures + validateBoot + createRegistry without DB/Redis-connect
+// (see @cosmicdrift/kumiko-server-runtime runProdApp).
+
+${imports}
+
+const DEFAULT_TENANT_ID = "${deriveTenantId(appName)}" as TenantId;
+
+const kmsOpts = {
+  logPrefix: "[${appName}]",
+  plaintextReason:
+    "no PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY set — see .env.example",
+} as const;
+
+const kmsWiring =
+  process.env["NODE_ENV"] === "production"
+    ? requireKmsWiring(process.env, kmsOpts)
+    : resolveKmsWiring(process.env, kmsOpts);
+
+// The bootstrap admin has no password; password reset is the only way it gets one. Without SMTP
+// and APP_BASE_URL (local boot) the mail flow stays off and the app still boots.
+const appBaseUrl = process.env["APP_BASE_URL"];
+const mailAppUrl = process.env["SMTP_HOST"] && appBaseUrl ? appBaseUrl : undefined;
+
+await runProdApp({
+  features: APP_FEATURES,
+  ...(appConfig.validateBootOptions && { validateBootOptions: appConfig.validateBootOptions }),
+  ...(appConfig.rowLevelSecurity && { rowLevelSecurity: appConfig.rowLevelSecurity }),
+  envSchema,
+  staticDir: "./dist",
+  ...kmsWiring,
+  ...(mailAppUrl !== undefined && { mail: { transport: "smtp-env" } }),
+  auth: {
+    ...(mailAppUrl !== undefined && {
+      passwordReset: { appUrl: \`\${mailAppUrl}\${DEFAULT_AUTH_PATHS.resetPassword}\` },
+    }),
+  },
+  seeds: {
+    bootstrapAdminFromEnv: {
+      tenant: { id: DEFAULT_TENANT_ID, key: "${appName}", name: "${appName}" },
+    },
+  },
+});
+`;
+}
+export function renderBlankServer(appName) {
+    const imports = renderSortedImports([
+        { specifier: "@cosmicdrift/kumiko-dev-server", names: ["runDevApp"] },
+        { specifier: "@cosmicdrift/kumiko-framework/engine", names: ["TenantId"], typeOnly: true },
+        { specifier: "../src/run-config", names: ["APP_FEATURES"] },
+        { specifier: "../kumiko.config", names: [], defaultName: "appConfig" },
+    ]);
+    const authBlock = renderAdminAuthBlock(appName, [
+        'password: "changeme",',
+        'displayName: "Admin",',
+    ]);
+    return `// Dev bootstrap. \`bun --watch bin/server.ts\` (see package.json scripts.dev)
+// starts a full-featured dev server with auto-reload on code changes.
+// setupTestStack creates missing entity tables automatically — a new
+// r.entity(...) in a feature becomes a CREATE TABLE on the next reboot,
+// no manual \`kumiko schema apply\` needed (that's prod-only).
+// Persistent DB via KUMIKO_DEV_DB_NAME (.env) so admin + data survive reboots.
+// The local admin below is dev-only: no mail runs locally, so there is no password reset.
+
+${imports}
+
+const DEFAULT_TENANT_ID = "${deriveTenantId(appName)}" as TenantId;
+
+await runDevApp({
+  features: APP_FEATURES,
+  ...(appConfig.validateBootOptions && { validateBootOptions: appConfig.validateBootOptions }),
+  welcomeBanner: true,
+  clientEntry: "./src/client.tsx",
+${authBlock}
+});
+`;
+}
+export const BLANK_ENV_EXAMPLE_ADMIN_BLOCK = `# KUMIKO_BOOTSTRAP_ADMIN_EMAIL: login of the person who created the app. The first prod
+# boot makes it the admin WITHOUT a password; set one via "forgot password". That needs
+# SMTP_HOST (+ SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM) and APP_BASE_URL (e.g.
+# https://app.example.com); without them the reset mail flow stays off.
+# KUMIKO_BOOTSTRAP_ADMIN_EMAIL=
+# SMTP_HOST=
+# APP_BASE_URL=
+`;
+export function blankReadmeCopy(appName) {
+    return {
+        intro: "Scaffolded by `kumiko new app --blank`. An empty app with login, tenants and sessions.\nAdd features via `bunx @cosmicdrift/kumiko-cli add feature <name>`.",
+        runConfigNote: "Edit `src/run-config.ts` to add bundled features.",
+        devLogin: `The welcome banner prints the URL (default \`http://localhost:4173\`) and the local\ndev login \`admin@${appName}.local\` / \`changeme\` (dev server only).`,
+        bootEnvNote: "a missing one exits 0 without validating the wiring.",
+        prodSeed: 'The first prod boot makes `KUMIKO_BOOTSTRAP_ADMIN_EMAIL` the admin of the app, without a\npassword. Open the app, choose "forgot password" and set one through the mail link. That\nneeds `SMTP_HOST` (+ `SMTP_*`) and `APP_BASE_URL`; without them nobody can set a password.\nWhile the variable is unset, nobody is seeded.',
+        demoArchitectureLines: "",
+    };
+}

package/dist/scaffold-render-helpers.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_LINE_WIDTH = 100;
+export type ImportSpec = {
+    readonly specifier: string;
+    readonly names: readonly string[];
+    readonly typeOnly?: boolean;
+    readonly defaultName?: string;
+};
+export declare function renderSortedImports(imports: readonly ImportSpec[]): string;
+export declare function renderDefaultAppShellElement(appName: string): string;
+export declare function deriveTenantId(name: string): string;
+export declare function renderAdminAuthBlock(appName: string, extraAdminLines: readonly string[]): string;

package/dist/scaffold-render-helpers.js

@@ -0,0 +1,108 @@
+// Text-rendering helpers shared by the scaffold renderers: import blocks formatted like Biome's
+// output and the per-app derived tenant id.
+export const MAX_LINE_WIDTH = 100;
+// Mirrors Biome's import sort so generated files pass `biome check` untouched:
+// packages alphabetically by specifier, relative paths last.
+function compareImportKeys(a, b) {
+    const lowerA = a.replace(/^type /, "").toLowerCase();
+    const lowerB = b.replace(/^type /, "").toLowerCase();
+    if (lowerA !== lowerB)
+        return lowerA < lowerB ? -1 : 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function isRelativeSpecifier(specifier) {
+    return specifier.startsWith("./") || specifier.startsWith("../");
+}
+function renderImportLine({ specifier, names, typeOnly, defaultName }) {
+    if (defaultName !== undefined)
+        return `import ${defaultName} from "${specifier}";`;
+    const sorted = [...names].sort(compareImportKeys);
+    const keyword = typeOnly === true ? "import type" : "import";
+    const oneLine = `${keyword} { ${sorted.join(", ")} } from "${specifier}";`;
+    if (sorted.length === 1 || oneLine.length <= MAX_LINE_WIDTH)
+        return oneLine;
+    return `${keyword} {\n${sorted.map((n) => `  ${n},`).join("\n")}\n} from "${specifier}";`;
+}
+export function renderSortedImports(imports) {
+    return [...imports]
+        .sort((a, b) => {
+        const relativeA = isRelativeSpecifier(a.specifier);
+        const relativeB = isRelativeSpecifier(b.specifier);
+        if (relativeA !== relativeB)
+            return relativeA ? 1 : -1;
+        return compareImportKeys(a.specifier, b.specifier);
+    })
+        .map(renderImportLine)
+        .join("\n");
+}
+// Tiers mirror how Biome wraps the JSX as the name grows. The user spread
+// is part of every tier so the line-width math covers it.
+export function renderDefaultAppShellElement(appName) {
+    const spanOpen = '<span className="font-semibold tracking-tight">';
+    const userSpread = "{...(user !== undefined && { user })}";
+    // html-ok: appName is kebab-validated (a-z/0-9/-); this is generated .tsx source, not runtime HTML.
+    const brandInline = `${spanOpen}${appName}</span>`;
+    const singleLine = `    <DefaultAppShell brand={${brandInline}} schema={schema} ${userSpread}>`;
+    if (singleLine.length <= MAX_LINE_WIDTH)
+        return singleLine;
+    const brandAttrInline = `      brand={${brandInline}}`;
+    const brandAttribute = brandAttrInline.length <= MAX_LINE_WIDTH
+        ? brandAttrInline
+        : `${[
+            "      brand={",
+            ...(`        ${brandInline}`.length <= MAX_LINE_WIDTH
+                ? [`        ${brandInline}`]
+                : [`        ${spanOpen}`, `          ${appName}`, "        </span>"]),
+            "      }",
+        ].join("\n")}`;
+    return [
+        "    <DefaultAppShell",
+        brandAttribute,
+        "      schema={schema}",
+        `      ${userSpread}`,
+        "    >",
+    ].join("\n");
+}
+// 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.
+export function deriveTenantId(name) {
+    let state = 2166136261;
+    for (const ch of name) {
+        state ^= ch.charCodeAt(0);
+        state = Math.imul(state, 16777619) >>> 0;
+    }
+    // @wrapper-known semantic-alias
+    const hex = (n, len) => n.toString(16).padStart(len, "0").slice(0, len);
+    const a = hex(state, 8);
+    state ^= state << 13;
+    state >>>= 0;
+    const b = hex(state, 4);
+    state ^= state >>> 17;
+    state >>>= 0;
+    const c = `4${hex(state, 3)}`;
+    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}`;
+}
+export function renderAdminAuthBlock(appName, extraAdminLines) {
+    const passwordAndExtras = extraAdminLines.map((l) => `      ${l}`).join("\n");
+    return `  auth: {
+    admin: {
+      email: "admin@${appName}.local",
+${passwordAndExtras}
+      memberships: [
+        {
+          tenantId: DEFAULT_TENANT_ID,
+          tenantKey: "${appName}",
+          tenantName: "${appName}",
+          roles: ["TenantAdmin"],
+        },
+      ],
+    },
+  },`;
+}

package/dist/welcome-banner.d.ts

@@ -4,7 +4,7 @@ export type WelcomeBannerInput = {
     /** Login the seeded admin uses (from runDevApp options.auth.admin). */
     readonly admin?: {
         readonly email: string;
-        readonly password: string;
+        readonly password?: string | undefined;
     };
     /** Hot-reload hint shown in the "add a feature" line. Defaults to
      *  `src/features/`. */

package/dist/welcome-banner.js

@@ -10,7 +10,9 @@ export function renderWelcomeBanner(input) {
     lines.push(`✓ kumiko-app läuft`);
     lines.push(`→ Browser:        ${input.url}`);
     if (input.admin) {
-        lines.push(`→ Login als:      ${input.admin.email} / ${input.admin.password}`);
+        lines.push(input.admin.password === undefined
+            ? `→ Login als:      ${input.admin.email}`
+            : `→ Login als:      ${input.admin.email} / ${input.admin.password}`);
     }
     lines.push(`→ Feature add:    edit ${featuresDir}`);
     lines.push(`→ Docs:           ${docsUrl}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.410.0",
+  "version": "0.412.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -77,15 +77,15 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.410.0",
-    "@cosmicdrift/kumiko-feature-ast": "0.410.0",
-    "@cosmicdrift/kumiko-framework": "0.410.0",
-    "@cosmicdrift/kumiko-renderer": "0.410.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.410.0",
-    "@cosmicdrift/kumiko-guards": "0.410.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.410.0",
-    "@cosmicdrift/kumiko-testing": "0.410.0",
-    "@cosmicdrift/kumiko-types": "0.410.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.412.0",
+    "@cosmicdrift/kumiko-feature-ast": "0.412.0",
+    "@cosmicdrift/kumiko-framework": "0.412.0",
+    "@cosmicdrift/kumiko-renderer": "0.412.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.412.0",
+    "@cosmicdrift/kumiko-guards": "0.412.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.412.0",
+    "@cosmicdrift/kumiko-testing": "0.412.0",
+    "@cosmicdrift/kumiko-types": "0.412.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.411.0",
+    "type": "improvement",
+    "title": "scaffoldApp starter \"blank\"",
+    "detail": "`scaffoldApp({ starter: \"blank\" })` (`SCAFFOLD_STARTERS`, `ScaffoldStarter`) writes an app without the tasks demo, `src/seed.ts` and `DEMO_ADMIN_PASSWORD`. `bin/main.ts` seeds the creator through `seeds.bootstrapAdminFromEnv` and wires SMTP mail and password reset when `SMTP_HOST` and `APP_BASE_URL` are set; `delivery` is mounted. The welcome banner prints only the email when the dev admin has no password. The default starter `demo` is unchanged."
+  },
   {
     "version": "0.408.0",
     "type": "fix",