@getstrata/starter 1.0.0 → 1.0.1

package/dist/cli.js

@@ -3,7 +3,7 @@
 
 // src/generate.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, rmSync as rmSync2 } from "fs";
-import { join as join2, resolve } from "path";
+import { basename, join as join2, resolve } from "path";
 
 // src/copy.ts
 import {
@@ -110,6 +110,12 @@ function usesTenantTable(tenancy) {
 function htmlAuthKit(auth) {
   return authUsesCookie(auth);
 }
+function needsFrontendBuild(frontend) {
+  return frontend === "spa-react" || frontend === "hybrid";
+}
+function nowTimestampLiteral(database) {
+  return database === "mysql" ? `new Date().toISOString().slice(0, 19).replace("T", " ")` : "new Date().toISOString()";
+}
 function extraApplies(extra, auth) {
   if (extra === "metrics") {
     return true;
@@ -485,6 +491,20 @@ function applyDockerFlags(layers, flags) {
   }
   return layers;
 }
+function extraFlagName(extra) {
+  return extra === "emailVerification" ? "email-verification" : extra;
+}
+function dropInapplicableExtras(layers, flags) {
+  for (const key of Object.keys(layers.extras)) {
+    if (extraApplies(key, layers.auth)) {
+      continue;
+    }
+    if (flags.extras[key] === true) {
+      console.warn(`Ignoring --${extraFlagName(key)}: not available with --auth ${layers.auth}.`);
+    }
+    layers.extras[key] = false;
+  }
+}
 function applyFlagOverrides(base, flags) {
   const next = {
     ...base,
@@ -499,8 +519,10 @@ function applyFlagOverrides(base, flags) {
     extras: { ...base.extras, ...flags.extras }
   };
   if (next.database !== "postgres" && next.tenancy === "rls") {
+    console.warn(`Using --tenancy column: rls is Postgres-only (SET LOCAL app.tenant_id) and ${next.database} has no equivalent.`);
     next.tenancy = "column";
   }
+  dropInapplicableExtras(next, flags);
   return reconcileDocker(applyDockerFlags(next, flags));
 }
 function layersFromFlags(flags) {
@@ -1113,16 +1135,13 @@ function sqlTrue(layers) {
 }
 function renderPendingMfaTs() {
   return `import { createHmac, timingSafeEqual } from "node:crypto";
+import { sessionSecret } from "./config.ts";
 
 const COOKIE = "strata_mfa_pending";
 
-function secret(): string {
-  return process.env.SESSION_SECRET?.trim() || "dev-session-secret-change-me-please-32ch";
-}
-
 function sign(userId: number, issuedAt: number): string {
   const payload = \`\${userId}.\${issuedAt}\`;
-  const signature = createHmac("sha256", secret()).update(payload).digest("hex");
+  const signature = createHmac("sha256", sessionSecret()).update(payload).digest("hex");
   return \`\${payload}.\${signature}\`;
 }
 
@@ -1203,6 +1222,8 @@ function renderAuthModule(layers) {
   imports.push(`import { hashPassword, verifyPassword } from "@getstrata/core/auth/password";`);
   if (authUsesToken(layers.auth)) {
     imports.push(`import { hashApiToken } from "@getstrata/core/auth/tokenHash";`);
+    imports.push(`import { sqlTimestamp } from "@getstrata/core/database/dialect";`);
+    imports.push(`import { resolveDefaultTokenExpiryDays } from "@getstrata/core/security/tokenExpiry";`);
   }
   if (mfa) {
     imports.push(`import { protectMfaSecret, revealMfaSecret } from "@getstrata/core/crypto/mfaSecret";`);
@@ -1261,11 +1282,22 @@ function sessionUser(user: { id: number; name?: string | null; email?: string |
               return jsonResponse({ error: "Invalid credentials" }, { status: 422 });
             }
             const plain = \`strp_\${randomBytes(24).toString("hex")}\`;
+            // API_TOKEN_DEFAULT_EXPIRY_DAYS bounds every minted token; unset means no expiry.
+            const expiryDays = resolveDefaultTokenExpiryDays();
+            const expiresAt = expiryDays
+              ? new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000)
+              : null;
             await getSql().unsafe(
-              "INSERT INTO api_tokens (user_id, name, token_hash, abilities) VALUES (${ph(layers, 4)})",
-              [user.id, "spa", hashApiToken(plain), JSON.stringify(["profile:read"])],
+              "INSERT INTO api_tokens (user_id, name, token_hash, abilities, expires_at) VALUES (${ph(layers, 5)})",
+              [
+                user.id,
+                "spa",
+                hashApiToken(plain),
+                JSON.stringify(["profile:read"]),
+                expiresAt ? sqlTimestamp(expiresAt) : null,
+              ],
             );
-            return jsonResponse({ token: plain });
+            return jsonResponse({ token: plain, expires_at: expiresAt?.toISOString() ?? null });
           })),
         },
         "/api/v1/auth/me": {
@@ -1372,7 +1404,7 @@ function sessionUser(user: { id: number; name?: string | null; email?: string |
             }
             await getSql().unsafe(
               "UPDATE users SET email_verified_at = ${verifiedPh} WHERE id = ${idPh}",
-              [new Date().toISOString(), id],
+              [${nowTimestampLiteral(layers.database)}, id],
             );
             return jsonResponse({ ok: true });
           })),
@@ -1533,7 +1565,7 @@ function sessionUser(user: { id: number; name?: string | null; email?: string |
               if (Number.isInteger(id) && id > 0) {
                 await getSql().unsafe(
                   "UPDATE users SET email_verified_at = ${verifiedPh} WHERE id = ${idPh}",
-                  [new Date().toISOString(), id],
+                  [${nowTimestampLiteral(layers.database)}, id],
                 );
                 const record = await starterAuthDirectory.findByIdOrThrow(id);
                 return flashResponse(
@@ -1668,17 +1700,27 @@ export default authModule;
 function renderSiteModule(_layers) {
   return `import type { AppModule } from "@getstrata/bootstrap/contracts";
 import { withErrorHandling } from "@getstrata/core/http/response";
-import { pingDatabase } from "../../bootstrap/database.ts";
+import { getSql, pingDatabase } from "../../bootstrap/database.ts";
 import { plainText, renderPage } from "../../lib/view.ts";
 
+// Proves the database answers and the schema is migrated. Point it at a table your app owns.
+async function schemaReady(): Promise<boolean> {
+  try {
+    await getSql().unsafe("SELECT 1 FROM notes LIMIT 1");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 const siteModule: AppModule = {
   name: "site",
   order: 1,
   routes({ kernel }) {
     return {
       "/health": kernel.wrap("api", withErrorHandling(async () => {
-        const dbOk = await pingDatabase();
-        return plainText(dbOk ? "ok" : "degraded");
+        const ok = (await pingDatabase()) && (await schemaReady());
+        return plainText(ok ? "ok" : "degraded", ok ? 200 : 503);
       })),
     };
   },
@@ -2009,7 +2051,7 @@ function renderAuthDirectory(layers) {
     }
     const hashed = hashApiToken(token);
     const rows = await getSql().unsafe<
-      Array<{
+      {
         id: number;
         user_id: number;
         abilities: string;
@@ -2017,7 +2059,7 @@ function renderAuthDirectory(layers) {
         role?: string;
         is_admin?: number | boolean;
         email_verified_at?: Date | string | null;
-      }>
+      }
     >(
       \`SELECT t.id, t.user_id, t.abilities, t.expires_at, u.is_admin, u.email_verified_at
        FROM api_tokens t INNER JOIN users u ON u.id = t.user_id
@@ -2052,83 +2094,74 @@ function renderAuthDirectory(layers) {
   const hashImport = authUsesToken(layers.auth) ? `import { hashApiToken } from "@getstrata/core/auth/tokenHash";
 ` : "";
   const mfaSelect = layers.extras.mfa ? ", mfa_enabled, mfa_secret, mfa_recovery_codes" : "";
+  const mfaColumns = layers.extras.mfa ? `
+  mfa_enabled?: number | boolean;
+  mfa_secret?: string | null;
+  mfa_recovery_codes?: string | null;` : "";
   const mfaReturn = layers.extras.mfa ? `
-      mfa_enabled: row.mfa_enabled === true || row.mfa_enabled === 1,
-      mfa_secret: row.mfa_secret ?? null,
-      mfa_recovery_codes: row.mfa_recovery_codes ?? null,` : "";
+    mfa_enabled: row.mfa_enabled === true || row.mfa_enabled === 1,
+    mfa_secret: row.mfa_secret ?? null,
+    mfa_recovery_codes: row.mfa_recovery_codes ?? null,` : "";
+  const userColumns = `id, name, email, is_admin, email_verified_at, password${mfaSelect}`;
   return `import type { AuthUser } from "@getstrata/core/auth/authContext";
 import { verifyPassword } from "@getstrata/core/auth/password";
 ${hashImport}import type { AuthUserDirectory } from "@getstrata/core/contracts/authUserDirectory";
 import { getSql } from "./database.ts";
 
+type UserRow = {
+  id: number;
+  name: string;
+  email: string;
+  is_admin: number | boolean;
+  email_verified_at: Date | string | null;
+  password: string;${mfaColumns}
+};
+
 function mapRole(isAdmin: unknown): string {
   return isAdmin === true || isAdmin === 1 || isAdmin === "1" ? "admin" : "member";
 }
 
+function mapUserRow(row: UserRow) {
+  return {
+    id: Number(row.id),
+    name: row.name,
+    email: row.email,
+    role: mapRole(row.is_admin),
+    email_verified_at: row.email_verified_at ?? null,
+    password: row.password,${mfaReturn}
+  };
+}
+
+async function findUserById(id: number) {
+  const rows = await getSql().unsafe<UserRow>(
+    "SELECT ${userColumns} FROM users WHERE id = ${placeholder}",
+    [id],
+  );
+  const row = rows[0];
+  if (!row) {
+    throw new Error(\`User \${id} not found.\`);
+  }
+  return mapUserRow(row);
+}
+
+async function findUserByEmail(email: string) {
+  const rows = await getSql().unsafe<UserRow>(
+    "SELECT ${userColumns} FROM users WHERE email = ${placeholder}",
+    [email.trim().toLowerCase()],
+  );
+  const row = rows[0];
+  return row ? mapUserRow(row) : null;
+}
+
 export const starterAuthDirectory: AuthUserDirectory = {
 ${tokenLookup.replace("WHERE t.token_hash = ?", `WHERE t.token_hash = ${placeholder}`)}
 
-  async findByIdOrThrow(id: number) {
-    const rows = await getSql().unsafe<
-      Array<{
-        id: number;
-        name: string;
-        email: string;
-        is_admin: number | boolean;
-        email_verified_at: Date | string | null;
-        password: string;
-        mfa_enabled?: number | boolean;
-        mfa_secret?: string | null;
-        mfa_recovery_codes?: string | null;
-      }>
-    >(\`SELECT id, name, email, is_admin, email_verified_at, password${mfaSelect} FROM users WHERE id = ${placeholder}\`, [id]);
-    const row = rows[0];
-    if (!row) {
-      throw new Error(\`User \${id} not found.\`);
-    }
-    return {
-      id: Number(row.id),
-      name: row.name,
-      email: row.email,
-      role: mapRole(row.is_admin),
-      email_verified_at: row.email_verified_at ?? null,
-      password: row.password,${mfaReturn}
-    };
-  },
+  findByIdOrThrow: findUserById,
 
-  async findByEmail(email: string) {
-    const rows = await getSql().unsafe<
-      Array<{
-        id: number;
-        name: string;
-        email: string;
-        is_admin: number | boolean;
-        email_verified_at: Date | string | null;
-        password: string;
-        mfa_enabled?: number | boolean;
-        mfa_secret?: string | null;
-        mfa_recovery_codes?: string | null;
-      }>
-    >(
-      \`SELECT id, name, email, is_admin, email_verified_at, password${mfaSelect} FROM users WHERE email = ${placeholder}\`,
-      [email.trim().toLowerCase()],
-    );
-    const row = rows[0];
-    if (!row) {
-      return null;
-    }
-    return {
-      id: Number(row.id),
-      name: row.name,
-      email: row.email,
-      role: mapRole(row.is_admin),
-      email_verified_at: row.email_verified_at ?? null,
-      password: row.password,${mfaReturn}
-    };
-  },
+  findByEmail: findUserByEmail,
 
   async verifyCredentials(email: string, password: string): Promise<AuthUser | null> {
-    const user = await this.findByEmail(email);
+    const user = await findUserByEmail(email);
     if (!user?.password || !(await verifyPassword(password, user.password))) {
       return null;
     }
@@ -2187,7 +2220,7 @@ export default authProvider;
 `;
   }
   const cookieBlock = authUsesCookie(layers.auth) ? `    const auth = createCookieSessionAuthManager({
-      secret: process.env.SESSION_SECRET?.trim() || "dev-session-secret-change-me-please-32ch",
+      secret: sessionSecret(),
       cookieName: "strata_session",
       mapUser: (user) => ({
         id: user.id,
@@ -2233,6 +2266,9 @@ export default authProvider;
   `)},
 } from "@getstrata/core/contracts/serviceTokens";`);
   imports.push(`import { starterAuthDirectory } from "../authDirectory.ts";`);
+  if (authUsesCookie(layers.auth)) {
+    imports.push(`import { sessionSecret } from "../config.ts";`);
+  }
   return `${imports.join(`
 `)}
 
@@ -2258,7 +2294,7 @@ function envFlag(value) {
   return value ? "true" : "false";
 }
 function appDatabaseName(projectName) {
-  return `${projectName.replace(/[^A-Za-z0-9_]/g, "_")}_test`;
+  return projectName.replace(/[^A-Za-z0-9_]/g, "_");
 }
 function defaultDatabaseUrl(layers, projectName) {
   if (layers.database === "sqlite") {
@@ -2278,6 +2314,10 @@ function renderEnvExample(projectName, layers) {
     "PORT=3000",
     "APP_URL=http://localhost:3000",
     `DATABASE_URL=${defaultDatabaseUrl(layers, projectName)}`,
+    ...layers.database === "sqlite" ? [] : [
+      "# Optional. Migrate and boot against a different database than DATABASE_URL.",
+      "# APP_DATABASE_URL="
+    ],
     `DB_CONNECTION=${layers.database === "postgres" ? "pgsql" : layers.database}`,
     `FRONTEND_MODE=${layers.frontend}`,
     `SPA_PREFIX=${layers.spaPrefix}`,
@@ -2285,9 +2325,13 @@ function renderEnvExample(projectName, layers) {
     `CACHE_DRIVER=${layers.cache}`,
     `QUEUE_DRIVER=${layers.queue}`,
     `MAIL_DRIVER=${layers.mail}`,
-    `AUTH_DEV_HEADERS=${envFlag(layers.auth === "headers")}`,
-    `FEATURE_PUBLIC_READS=${envFlag(layers.frontend !== "api")}`
+    `AUTH_DEV_HEADERS=${envFlag(layers.auth === "headers")}`
   ];
+  if (layers.frontend === "api") {
+    lines.push("FEATURE_PUBLIC_READS=false");
+  } else {
+    lines.push("# Local convenience so the welcome page reads without a login.", "# Production boot is blocked unless this is false.", "FEATURE_PUBLIC_READS=true");
+  }
   if (needsRedis(layers)) {
     lines.push("REDIS_URL=redis://127.0.0.1:6379");
   } else {
@@ -2338,6 +2382,7 @@ function renderEnvExample(projectName, layers) {
     lines.push("# MAIL_HOST=");
     lines.push("# MAIL_FROM=");
   }
+  lines.push("# Behind a reverse proxy, trust X-Forwarded-For (rightmost public hop) for throttles and session IPs.");
   lines.push("# TRUST_FORWARDED_FOR=true");
   return `${lines.join(`
 `)}
@@ -2424,35 +2469,90 @@ dist
 frontend/dist
 storage/*.sqlite
 storage/*.sqlite-journal
+storage/*.sqlite-wal
+storage/*.sqlite-shm
 coverage
 *.tsbuildinfo
 `;
 }
+function renderDockerfile(layers) {
+  const frontend = needsFrontendBuild(layers.frontend);
+  const lines = [
+    '# Production image. Build once, run with env from your platform; see README "Deploy".',
+    "FROM oven/bun:1.4 AS deps",
+    "WORKDIR /app",
+    "COPY package.json bun.lock ./",
+    "RUN bun install --frozen-lockfile --production",
+    ""
+  ];
+  if (frontend) {
+    lines.push("FROM oven/bun:1.4 AS frontend", "WORKDIR /app/frontend", "COPY frontend/package.json frontend/bun.lock ./", "RUN bun install --frozen-lockfile", "COPY frontend/ ./", "RUN bun run build", "");
+  }
+  lines.push("FROM oven/bun:1.4-slim AS runtime", "WORKDIR /app", "ENV APP_ENV=production", "ENV AUTH_DEV_HEADERS=false", "ENV PORT=3000", "COPY --from=deps /app/node_modules ./node_modules", "COPY . .");
+  if (frontend) {
+    lines.push("COPY --from=frontend /app/frontend/dist ./frontend/dist");
+  }
+  lines.push("RUN mkdir -p storage && chown -R bun:bun /app", "USER bun", "EXPOSE 3000");
+  if (layers.database === "sqlite") {
+    lines.push("# SQLite lives in storage/; mount a volume there or the data dies with the container.", 'VOLUME ["/app/storage"]');
+  }
+  lines.push(`HEALTHCHECK --interval=30s --timeout=3s --start-period=10s CMD ["bun", "-e", "fetch('http://127.0.0.1:' + process.env.PORT + '/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]`, 'CMD ["bun", "run", "start"]');
+  return `${lines.join(`
+`)}
+`;
+}
+function renderDockerignore(layers) {
+  const lines = [
+    ".git",
+    "node_modules",
+    ".env",
+    ".env.*",
+    "!.env.example",
+    "storage/*.sqlite",
+    "storage/*.sqlite-journal",
+    "storage/*.sqlite-wal",
+    "storage/*.sqlite-shm",
+    "coverage",
+    "docker-compose.yml"
+  ];
+  if (needsFrontendBuild(layers.frontend)) {
+    lines.push("frontend/node_modules", "frontend/dist");
+  }
+  return `${lines.join(`
+`)}
+`;
+}
 function renderPackageJson(projectName, options = {}) {
   const coreDeps = options.workspaceDependencies ? {
     "@getstrata/bootstrap": "workspace:*",
     "@getstrata/cli": "workspace:*",
     "@getstrata/core": "workspace:*"
   } : {
-    "@getstrata/bootstrap": "^1.0.0",
-    "@getstrata/cli": "^1.0.0",
-    "@getstrata/core": "^1.0.0"
+    "@getstrata/bootstrap": "^1.0.1",
+    "@getstrata/cli": "^1.0.1",
+    "@getstrata/core": "^1.0.1"
   };
   if (options.layers?.database === "mysql") {
     coreDeps.mysql2 = "^3.24.3";
   }
+  const scripts = {
+    dev: "strata dev",
+    start: "strata start",
+    "db:migrate": "strata migrate",
+    "db:fresh": "strata migrate:fresh",
+    check: "tsc --noEmit"
+  };
+  if (options.layers && needsFrontendBuild(options.layers.frontend)) {
+    scripts["frontend:install"] = "cd frontend && bun install";
+    scripts["frontend:build"] = "cd frontend && bun run build";
+    scripts["frontend:dev"] = "cd frontend && bun run dev";
+  }
   return `${JSON.stringify({
     name: projectName,
     version: "0.1.0",
     private: true,
     type: "module",
-    scripts: {
-      dev: "strata dev",
-      start: "strata start",
-      "db:migrate": "strata migrate",
-      "db:fresh": "strata migrate:fresh",
-      check: "tsc --noEmit"
-    },
+    scripts,
     dependencies: coreDeps,
     devDependencies: {
       "@types/bun": "^1.4.0",
@@ -2524,13 +2624,86 @@ function renderSupportingToolsReadme(layers) {
 `)}
 `;
 }
+function renderApiDocs(projectName, layers) {
+  const rows = ["| Method | Path | Notes |", "| --- | --- | --- |"];
+  rows.push("| `GET` | `/health` | Plain text `ok` (200), or `degraded` (503) when the database or the migrated schema is unavailable. `/ready` returns the same checks as JSON. |");
+  rows.push("| `GET` | `/` | Welcome page. Restyle or replace it. |");
+  if (authUsesToken(layers.auth)) {
+    rows.push("| `POST` | `/api/v1/auth/login` | `{ email, password }` returns `{ token }`. |", "| `POST` | `/api/v1/auth/register` | Creates a user and returns a token. |", "| `GET` | `/api/v1/auth/me` | Requires `Authorization: Bearer <token>`. |");
+  }
+  if (authUsesJwt(layers.auth)) {
+    rows.push("| `POST` | `/api/auth/token` | Mints a short-lived JWT. Not an HTML session. |");
+  }
+  if (authNeedsUsers(layers.auth)) {
+    rows.push("| `POST` | `/api/v1/auth/forgot-password` | Sends a signed reset link through the mail driver. |", "| `POST` | `/api/v1/auth/reset-password` | Consumes the signed link. |", "| `GET` | `/api/user` | Current user for the active guard. |");
+  }
+  if (layers.extras.metrics) {
+    rows.push("| `GET` | `/metrics` | Prometheus text. Production requires `Authorization: Bearer <METRICS_TOKEN>`. |");
+  }
+  const authNote = layers.auth === "headers" ? `Auth is \`headers\`. Send \`x-authenticated-user-id\` (and optional \`x-authenticated-user-role\`) for local work and tests. There are no login endpoints and no \`users\` table. Production must set \`AUTH_DEV_HEADERS=false\`, which turns those headers off and leaves you without a guard, so pick another auth layer before you ship.` : authUsesToken(layers.auth) ? `Sign in with \`POST /api/v1/auth/login\`, then send \`Authorization: Bearer <token>\` on every request. Tokens are stored hashed in \`api_tokens\` and expire after \`API_TOKEN_DEFAULT_EXPIRY_DAYS\` (30 in \`.env.example\`). The response includes \`expires_at\`.` : `Mint a JWT with \`POST /api/auth/token\`, then send \`Authorization: Bearer <jwt>\`. JWTs expire; re-mint rather than refreshing in place.`;
+  return `# ${projectName} API
+
+\`FRONTEND_MODE=${layers.frontend}\`. ${layers.frontend === "api" ? "No server-rendered views beyond the welcome page and no SPA assets." : `HTML is served alongside this API. The SPA is mounted at \`${layers.spaPrefix}\`.`}
+
+## Routes this app serves today
+
+${rows.join(`
+`)}
+
+There is no CRUD endpoint for the seeded \`notes\` table. Adding your own routes is the first thing you do.
+
+## Auth
+
+${authNote}
+
+## Adding a route
+
+Create a module under \`src/modules/\` and return a route map. Modules are discovered on boot.
+
+\`\`\`typescript
+// src/modules/notes/index.ts
+import type { AppModule } from "@getstrata/bootstrap/contracts";
+import { jsonResponse } from "@getstrata/core/http/response";
+import { getSql } from "../../bootstrap/database.ts";
+
+const notesModule: AppModule = {
+  name: "notes",
+  order: 2,
+  routes({ kernel }) {
+    return {
+      "/api/v1/notes": kernel.wrap("api", async () => {
+        const rows = await getSql().unsafe<{ id: number; body: string }>(
+          "SELECT id, body FROM notes ORDER BY id DESC",
+        );
+        return jsonResponse({ data: rows });
+      }),
+    };
+  },
+};
+
+export default notesModule;
+\`\`\`
+
+Import from \`@getstrata/core/...\` subpaths rather than the package root, so singleton state such as the database pool stays shared.
+
+## Docs
+
+- [Building apps](https://github.com/EyK-26/strata/blob/main/docs/BUILDING-APPS.md)
+- [Auth choices](https://github.com/EyK-26/strata/blob/main/docs/AUTH.md)
+- [Databases](https://github.com/EyK-26/strata/blob/main/docs/DATABASE.md)
+`;
+}
 function renderReadme(projectName, layers) {
   const docker = renderDockerCompose(projectName, layers);
   const next = [`cd ${projectName}`, "cp .env.example .env"];
   if (docker) {
     next.push("docker compose up -d");
   }
-  next.push("bun install", "strata migrate", "strata dev");
+  next.push("bun install");
+  if (needsFrontendBuild(layers.frontend)) {
+    next.push("bun run frontend:install", "bun run frontend:build");
+  }
+  next.push("bun run db:migrate", "bun run dev");
   const extras = Object.entries(layers.extras).filter(([, on]) => on).map(([key]) => key);
   const dockerServices = selectedDockerServices(layers);
   const neededTools = neededDockerServices(layers);
@@ -2585,13 +2758,49 @@ Cookie name is \`strata_session\`. Forms send CSRF as \`_token\`.
 ` : ""}${authUsesToken(layers.auth) ? `
 Opaque token login: \`POST /api/v1/auth/login\` with \`{ "email", "password" }\`. Register: \`POST /api/v1/auth/register\`. Forgot/reset: \`POST /api/v1/auth/forgot-password\` and signed \`POST /api/v1/auth/reset-password\`. Send \`Authorization: Bearer\` after login.
 ` : ""}${authUsesJwt(layers.auth) ? `
-JWT mint: \`POST /api/auth/token\` with email and password. Short-lived. Not a portal session.
+JWT mint: \`POST /api/auth/token\` with email and password. Short-lived. Do not use JWT as an HTML cookie session.
 ` : ""}${layers.extras.metrics ? `
 Prometheus scrape: \`GET /metrics\`. Production requires \`Authorization: Bearer <METRICS_TOKEN>\`.
-` : ""}
+` : ""}${needsFrontendBuild(layers.frontend) ? `
+## Frontend
+
+The React app lives in \`frontend/\` with its own \`package.json\`. It is not built by \`bun install\` at the root.
+
+\`\`\`bash
+bun run frontend:install
+bun run frontend:build
+\`\`\`
+
+Until \`frontend/dist\` exists, \`${layers.spaPrefix}\` answers 503. Use \`bun run frontend:dev\` for the Vite-style dev server with hot reload.${layers.frontend === "hybrid" ? ` HTML stays at \`/\` and the SPA is served under \`${layers.spaPrefix}/*\`.` : ""}
+` : ""}${layers.database === "sqlite" ? "" : `
+## Database
+
+The app uses the database named in \`DATABASE_URL\` and creates it on first migrate when the connection user may. Set \`APP_DATABASE_URL\` only when migrations and the app should target a different database than \`DATABASE_URL\`.
+`}
+## Deploy
+
+\`Dockerfile\` builds a production image from the committed \`bun.lock\` (run \`bun install\` once and commit the lockfile).${needsFrontendBuild(layers.frontend) ? " The React frontend is built inside the image." : ""}
+
+\`\`\`bash
+docker build -t ${projectName} .
+docker run --rm -p 3000:3000 --env-file .env.production ${projectName}
+\`\`\`
+
+Migrations are a deploy step, not a boot step: run \`docker run --rm --env-file .env.production ${projectName} bun run db:migrate\` before the new version takes traffic.${layers.database === "sqlite" ? " SQLite stores its file in `/app/storage`; mount a volume there (`-v strata_data:/app/storage`) or the data is lost with the container." : ""}
+The image sets \`APP_ENV=production\` and \`AUTH_DEV_HEADERS=false\`; everything else in the Production list below comes from your environment (the \`.env.production\` file above is one way).
+
 ## Production
 
-\`createApp\` calls \`assertProductionSecrets()\` when \`APP_ENV=production\`. Set real secrets before you ship. Cookie HTML apps need \`SESSION_SECRET\` (32+ characters). Token apps need \`TOKEN_HASH_PEPPER\`. Set \`AUTH_DEV_HEADERS=false\`.
+\`createApp\` calls \`assertProductionSecrets()\` when \`APP_ENV=production\`. That check fails closed, so read this before your first production boot.
+
+- Replace every \`change-me\` placeholder in \`.env\`. The guard rejects the values this generator wrote, not just empty ones.
+- Set \`APP_URL\` to the public origin (for example \`https://app.example.com\`). Signed links and redirects are built from it; localhost is rejected.
+- Set \`AUTH_DEV_HEADERS=false\`.
+- Set \`FEATURE_PUBLIC_READS=false\`. ${layers.frontend === "api" ? "This app already ships `false`." : "This app ships `true` so the local welcome page reads without a login. Production requires `false`."}
+- Cross-origin browser calls are off in production until you set \`CORS_ALLOWED_ORIGINS\` to explicit origins. A \`*\` entry is rejected. Non-browser clients are unaffected.
+- Behind a reverse proxy or load balancer, set \`TRUST_FORWARDED_FOR=true\` so throttles and session records see the client address instead of the proxy. Only the rightmost public hop of \`X-Forwarded-For\` is trusted.
+${authUsesCookie(layers.auth) ? "- Set `SESSION_SECRET` to 32+ characters.\n" : ""}${authUsesToken(layers.auth) ? "- Set `TOKEN_HASH_PEPPER`.\n" : ""}${layers.extras.scim ? "- Set `SCIM_BEARER_TOKEN`.\n" : ""}${layers.extras.metrics ? "- Set `METRICS_TOKEN`.\n" : ""}
+\`strata start\` does not migrate when \`APP_ENV=production\`. Run \`bun run db:migrate\` as a deploy step. \`GET /health\` answers 503 until the schema exists, so a fresh deploy stays out of rotation until it is migrated.
 `;
 }
 
@@ -2612,6 +2821,8 @@ function dialectFragments(database) {
     return {
       id: "INTEGER PRIMARY KEY AUTOINCREMENT",
       text: "TEXT",
+      keyText: "TEXT",
+      defaultText: "TEXT",
       timestamp: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
       timestampNull: "TEXT",
       bool: "INTEGER NOT NULL DEFAULT 0"
@@ -2621,6 +2832,8 @@ function dialectFragments(database) {
     return {
       id: "INT AUTO_INCREMENT PRIMARY KEY",
       text: "TEXT",
+      keyText: "VARCHAR(255)",
+      defaultText: "VARCHAR(1024)",
       timestamp: "DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP",
       timestampNull: "DATETIME NULL",
       bool: "TINYINT(1) NOT NULL DEFAULT 0"
@@ -2629,6 +2842,8 @@ function dialectFragments(database) {
   return {
     id: "SERIAL PRIMARY KEY",
     text: "TEXT",
+    keyText: "TEXT",
+    defaultText: "TEXT",
     timestamp: "TIMESTAMPTZ NOT NULL DEFAULT NOW()",
     timestampNull: "TIMESTAMPTZ",
     bool: "BOOLEAN NOT NULL DEFAULT FALSE"
@@ -2820,9 +3035,9 @@ function renderMigrateTs(layers) {
   if (tenancyOn) {
     statements.push(`CREATE TABLE IF NOT EXISTS tenant (
     id ${d.id},
-    slug ${d.text} NOT NULL UNIQUE,
-    plan ${d.text} NOT NULL DEFAULT 'enterprise',
-    region ${d.text} NOT NULL DEFAULT 'eu'
+    slug ${d.keyText} NOT NULL UNIQUE,
+    plan ${d.defaultText} NOT NULL DEFAULT 'enterprise',
+    region ${d.defaultText} NOT NULL DEFAULT 'eu'
   )`);
   }
   statements.push(`CREATE TABLE IF NOT EXISTS notes (
@@ -2840,7 +3055,7 @@ function renderMigrateTs(layers) {
     statements.push(`CREATE TABLE IF NOT EXISTS users (
     id ${d.id},
     name ${d.text} NOT NULL,
-    email ${d.text} NOT NULL UNIQUE,
+    email ${d.keyText} NOT NULL UNIQUE,
     password ${d.text} NOT NULL,
     is_admin ${d.bool},${tenantColumn}${mfaColumns}
     email_verified_at ${d.timestampNull},
@@ -2849,7 +3064,7 @@ function renderMigrateTs(layers) {
   }
   if (authUsesCookie(layers.auth)) {
     statements.push(`CREATE TABLE IF NOT EXISTS sessions (
-    id ${d.text} PRIMARY KEY,
+    id ${d.keyText} PRIMARY KEY,
     user_id INTEGER NOT NULL,
     expires_at ${d.timestamp},
     user_agent ${d.text},
@@ -2862,8 +3077,8 @@ function renderMigrateTs(layers) {
     id ${d.id},
     user_id INTEGER NOT NULL,
     name ${d.text} NOT NULL,
-    token_hash ${d.text} NOT NULL UNIQUE,
-    abilities ${d.text} NOT NULL DEFAULT '[]',
+    token_hash ${d.keyText} NOT NULL UNIQUE,
+    abilities ${d.defaultText} NOT NULL DEFAULT '[]',
     expires_at ${d.timestampNull},
     last_used_at ${d.timestampNull},
     created_at ${d.timestamp}
@@ -2878,10 +3093,10 @@ function renderMigrateTs(layers) {
   const userPlaceholders = verifyOn ? ph ? "$1, $2, $3, $4, $5), ($6, $7, $8, $9, $10" : "?, ?, ?, ?, ?), (?, ?, ?, ?, ?" : ph ? "$1, $2, $3, $4), ($5, $6, $7, $8" : "?, ?, ?, ?), (?, ?, ?, ?";
   const adminFlag = ph ? "false" : "0";
   const adminTrue = ph ? "true" : "1";
-  const verifiedNow = "new Date().toISOString()";
+  const verifiedNow = nowTimestampLiteral(layers.database);
   const userValues = verifyOn ? `["Demo User", "demo@example.com", password, ${adminFlag}, ${verifiedNow}, "Admin User", "admin@example.test", password, ${adminTrue}, ${verifiedNow}]` : `["Demo User", "demo@example.com", password, ${adminFlag}, "Admin User", "admin@example.test", password, ${adminTrue}]`;
   const seedTenant = tenancyOn ? `
-  const [{ count: tenantCount }] = await sql.unsafe<Array<{ count: string | number }>>(
+  const [{ count: tenantCount }] = await sql.unsafe<{ count: string | number }>(
     "SELECT COUNT(*) AS count FROM tenant",
   );
   if (Number(tenantCount) === 0) {
@@ -2891,7 +3106,7 @@ function renderMigrateTs(layers) {
     );
   }` : "";
   const seedUsers = authNeedsUsers(layers.auth) ? `
-  const [{ count: userCount }] = await sql.unsafe<Array<{ count: string | number }>>(
+  const [{ count: userCount }] = await sql.unsafe<{ count: string | number }>(
     "SELECT COUNT(*) AS count FROM users",
   );
   if (Number(userCount) === 0) {
@@ -2904,7 +3119,7 @@ function renderMigrateTs(layers) {
   const hashImport = authNeedsUsers(layers.auth) ? `import { hashPassword } from "@getstrata/core/auth/password";
 ` : "";
   const seedBlock = `${seedTenant}${seedUsers}`;
-  return `${hashImport}${ensureImport(layers)}import { getSql } from "../bootstrap/database.ts";
+  return `${hashImport}${ensureImport(layers)}import { closeDatabase, getSql } from "../bootstrap/database.ts";
 
 const migrations = [
 ${list}
@@ -2912,7 +3127,7 @@ ${list}
 
 export async function seed() {
 ${ensureCall(layers)}  const sql = getSql();
-  const [{ count }] = await sql.unsafe<Array<{ count: string | number }>>(
+  const [{ count }] = await sql.unsafe<{ count: string | number }>(
     "SELECT COUNT(*) AS count FROM notes",
   );
   if (Number(count) === 0) {
@@ -2930,9 +3145,15 @@ ${ensureCall(layers)}  const sql = getSql();
   await seed();
 }
 
+/** The CLI calls this after migrate() so pooled drivers do not hold the process open. */
+export async function close() {
+  await closeDatabase();
+}
+
 if (import.meta.main) {
   await migrate();
   console.log("Database migrated and seeded.");
+  await close();
   process.exit(0);
 }
 `;
@@ -2957,7 +3178,7 @@ function dropTables(layers) {
 function renderFreshTs(layers) {
   const tables = dropTables(layers);
   const cascade = layers.database === "sqlite" ? "" : " CASCADE";
-  return `${ensureImport(layers)}import { getSql } from "../bootstrap/database.ts";
+  return `${ensureImport(layers)}import { closeDatabase, getSql } from "../bootstrap/database.ts";
 import { migrate } from "./migrate.ts";
 
 const tables = ${JSON.stringify(tables)};
@@ -2970,9 +3191,15 @@ ${ensureCall(layers)}  const sql = getSql();
   await migrate();
 }
 
+/** The CLI calls this after fresh() so pooled drivers do not hold the process open. */
+export async function close() {
+  await closeDatabase();
+}
+
 if (import.meta.main) {
   await fresh();
   console.log("Database reset, migrated, and seeded.");
+  await close();
   process.exit(0);
 }
 `;
@@ -3000,7 +3227,7 @@ ${ensureCall(layers)}  const sql = getSql();
   console.log("Starter schema (inline SQL, not a migration runner):");
   for (const table of tables) {
     try {
-      const rows = await sql.unsafe<Array<{ count: string | number }>>(
+      const rows = await sql.unsafe<{ count: string | number }>(
         \`SELECT COUNT(*) AS count FROM \${table}\`,
       );
       console.log(\`- [present] \${table} (rows: \${rows[0]?.count ?? 0})\`);
@@ -3073,6 +3300,17 @@ export function loadConfig(): AppConfig {
     databaseUrl,
   };
 }
+
+/** Cookie sessions and signed cookies are keyed by this; there is no default. */
+export function sessionSecret(): string {
+  const secret = process.env.SESSION_SECRET?.trim();
+  if (!secret) {
+    throw new Error(
+      "SESSION_SECRET is required. Copy .env.example to .env and set it (32+ characters).",
+    );
+  }
+  return secret;
+}
 `;
 }
 function renderConfigProvider(layers) {
@@ -3133,50 +3371,62 @@ function renderEnsureDatabaseTs(layers, projectName) {
   }
   const database = appDatabaseName(projectName);
   const fallback = layers.database === "mysql" ? `mysql://root:root@localhost:3306/${database}` : `postgresql://postgres:postgres@localhost:5432/${database}`;
-  if (layers.database === "mysql") {
-    return `const APP_DATABASE = ${JSON.stringify(database)};
-
+  const resolveUrl = `/**
+ * The database name comes from DATABASE_URL. Set APP_DATABASE_URL to point
+ * migrations and the app at a different database than DATABASE_URL.
+ */
 function resolveAppDatabaseUrl(): string {
   const explicit = process.env.APP_DATABASE_URL?.trim();
   if (explicit) {
     return explicit;
   }
+  return process.env.DATABASE_URL?.trim() || DEFAULT_DATABASE_URL;
+}
 
-  const base = process.env.DATABASE_URL?.trim() || ${JSON.stringify(fallback)};
+/** Reject anything we would have to quote before interpolating into DDL. */
+function safeDatabaseName(url: string): string {
+  let name = "";
   try {
-    const url = new URL(base);
-    url.pathname = \`/\${APP_DATABASE}\`;
-    return url.toString();
+    name = decodeURIComponent(new URL(url).pathname.replace(/^\\//, ""));
   } catch {
-    return base;
+    throw new Error(\`DATABASE_URL is not a valid URL: \${url}\`);
+  }
+  if (!name) {
+    throw new Error("DATABASE_URL is missing a database name.");
+  }
+  if (name.replace(/[^A-Za-z0-9_]/g, "") !== name) {
+    throw new Error(\`Refusing to create a database with an unsafe name: \${name}\`);
   }
+  return name;
 }
+`;
+  if (layers.database === "mysql") {
+    return `import { createConnection } from "mysql2/promise";
+
+const DEFAULT_DATABASE_URL = ${JSON.stringify(fallback)};
 
+${resolveUrl}
 export async function ensureAppDatabase(): Promise<string> {
   const url = resolveAppDatabaseUrl();
+  const name = safeDatabaseName(url);
+
+  const admin = new URL(url);
+  admin.pathname = "/";
+  const connection = await createConnection(admin.toString());
+  try {
+    await connection.query(\`CREATE DATABASE IF NOT EXISTS \${name}\`);
+  } finally {
+    await connection.end();
+  }
+
   process.env.DATABASE_URL = url;
   return url;
 }
 `;
   }
-  return `const APP_DATABASE = ${JSON.stringify(database)};
-
-function resolveAppDatabaseUrl(): string {
-  const explicit = process.env.APP_DATABASE_URL?.trim();
-  if (explicit) {
-    return explicit;
-  }
-
-  const base = process.env.DATABASE_URL?.trim() || ${JSON.stringify(fallback)};
-  try {
-    const url = new URL(base);
-    url.pathname = \`/\${APP_DATABASE}\`;
-    return url.toString();
-  } catch {
-    return base;
-  }
-}
+  return `const DEFAULT_DATABASE_URL = ${JSON.stringify(fallback)};
 
+${resolveUrl}
 function adminCandidateUrls(url: string): string[] {
   const names = ["postgres", "template1"];
   try {
@@ -3212,16 +3462,7 @@ async function openAdminConnection(url: string): Promise<Bun.SQL> {
 
 export async function ensureAppDatabase(): Promise<string> {
   const url = resolveAppDatabaseUrl();
-  const parsed = new URL(url);
-  const name = decodeURIComponent(parsed.pathname.replace(/^\\//, ""));
-  if (!name) {
-    throw new Error("DATABASE_URL is missing a database name.");
-  }
-
-  const identifier = name.replace(/[^A-Za-z0-9_]/g, "");
-  if (identifier !== name) {
-    throw new Error(\`Refusing to create a database with an unsafe name: \${name}\`);
-  }
+  const name = safeDatabaseName(url);
 
   const adminSql = await openAdminConnection(url);
   try {
@@ -3229,14 +3470,13 @@ export async function ensureAppDatabase(): Promise<string> {
       SELECT 1 AS ok FROM pg_database WHERE datname = \${name}
     \`;
     if (rows.length === 0) {
-      await adminSql.unsafe(\`CREATE DATABASE \${identifier}\`);
+      await adminSql.unsafe(\`CREATE DATABASE \${name}\`);
     }
   } finally {
     await adminSql.close();
   }
 
   process.env.DATABASE_URL = url;
-  process.env.APP_DATABASE_URL = url;
   return url;
 }
 `;
@@ -3350,9 +3590,12 @@ function createAppContext(): AppContext {
 }
 
 export async function bootstrapApp(options: BootstrapOptions = {}): Promise<BootstrappedApp> {
-  const { migrate: runMigrate = true } = options;
+  const isProduction = process.env.APP_ENV === "production";
+  // Dev boots migrate for convenience. Production must not mutate schema on
+  // start, so run \`strata migrate\` as an explicit deploy step instead.
+  const { migrate: runMigrate = !isProduction } = options;
 
-  if (process.env.APP_ENV === "production") {
+  if (isProduction) {
     assertProductionSecrets();
   }
 
@@ -3452,8 +3695,8 @@ ${userBlock}
   return htmlResponse(html, { status });
 }
 
-export function plainText(body: string): Response {
-  return new Response(body, { headers: { "content-type": "text/plain; charset=utf-8" } });
+export function plainText(body: string, status = 200): Response {
+  return new Response(body, { status, headers: { "content-type": "text/plain; charset=utf-8" } });
 }
 `;
 }
@@ -3611,12 +3854,12 @@ const scimModule: AppModule = {
             const match = /userName\\s+eq\\s+"([^"]+)"/i.exec(filter);
             let rows: UserRow[];
             if (match?.[1]) {
-              rows = await getSql().unsafe<UserRow[]>(
+              rows = await getSql().unsafe<UserRow>(
                 "SELECT id, name, email FROM users WHERE email = ${emailPh}",
                 [match[1].trim().toLowerCase()],
               );
             } else {
-              rows = await getSql().unsafe<UserRow[]>("SELECT id, name, email FROM users");
+              rows = await getSql().unsafe<UserRow>("SELECT id, name, email FROM users");
             }
             const startIndex = Math.max(1, Number.parseInt(url.searchParams.get("startIndex") ?? "1", 10) || 1);
             const count = Math.min(200, Math.max(1, Number.parseInt(url.searchParams.get("count") ?? String(rows.length || 1), 10) || 200));
@@ -3639,7 +3882,7 @@ const scimModule: AppModule = {
             if (!email) {
               return scimError("userName is required.", 400);
             }
-            const existing = await getSql().unsafe<UserRow[]>(
+            const existing = await getSql().unsafe<UserRow>(
               "SELECT id, name, email FROM users WHERE email = ${emailPh}",
               [email],
             );
@@ -3652,7 +3895,7 @@ const scimModule: AppModule = {
               "INSERT INTO users (${insertCols}) VALUES (${insertPh})",
               [name, email, hashed${insertTail}],
             );
-            const created = await getSql().unsafe<UserRow[]>(
+            const created = await getSql().unsafe<UserRow>(
               "SELECT id, name, email FROM users WHERE email = ${emailPh}",
               [email],
             );
@@ -3669,7 +3912,7 @@ const scimModule: AppModule = {
           "api",
           wrapScim(async (request) => {
             const id = Number.parseInt(routeParams(request).id ?? "", 10);
-            const rows = await getSql().unsafe<UserRow[]>(
+            const rows = await getSql().unsafe<UserRow>(
               "SELECT id, name, email FROM users WHERE id = ${idPh}",
               [id],
             );
@@ -3694,7 +3937,7 @@ const scimModule: AppModule = {
               "UPDATE users SET name = ${updatePh.split(", ")[0]}, email = ${updatePh.split(", ")[1]} WHERE id = ${updatePh.split(", ")[2]}",
               [name, email, id],
             );
-            const rows = await getSql().unsafe<UserRow[]>(
+            const rows = await getSql().unsafe<UserRow>(
               "SELECT id, name, email FROM users WHERE id = ${idPh}",
               [id],
             );
@@ -3709,7 +3952,7 @@ const scimModule: AppModule = {
           "api",
           wrapScim(async (request) => {
             const id = Number.parseInt(routeParams(request).id ?? "", 10);
-            const existing = await getSql().unsafe<UserRow[]>(
+            const existing = await getSql().unsafe<UserRow>(
               "SELECT id, name, email FROM users WHERE id = ${idPh}",
               [id],
             );
@@ -3801,13 +4044,16 @@ function assertProjectName(projectName) {
     throw new Error("Project name must contain only letters, numbers, hyphens, and underscores.");
   }
 }
+function resolveProjectTarget(rawTarget, cwd) {
+  const targetDir = resolve(cwd, rawTarget.trim());
+  const projectName = basename(targetDir);
+  assertProjectName(projectName);
+  return { projectName, targetDir };
+}
 function applyFrontendOverlays(overlayRoot, targetDir, layers) {
   if (layers.frontend === "hybrid" || layers.frontend === "spa-react") {
     copyOverlayTree(join2(overlayRoot, "spa-react"), targetDir);
   }
-  if (layers.frontend === "api") {
-    copyOverlayTree(join2(overlayRoot, "api"), targetDir);
-  }
 }
 function writeGeneratedFiles(options) {
   const { targetDir, projectName, layers } = options;
@@ -3816,7 +4062,14 @@ function writeGeneratedFiles(options) {
   writeText(join2(targetDir, ".gitignore"), renderGitignore());
   writeText(join2(targetDir, "package.json"), renderPackageJson(projectName, { ...options, layers }));
   writeText(join2(targetDir, "README.md"), renderReadme(projectName, layers));
+  if (layers.frontend === "api") {
+    writeText(join2(targetDir, "docs/API.md"), renderApiDocs(projectName, layers));
+  } else {
+    removeIfExists(join2(targetDir, "docs/API.md"));
+  }
   writeText(join2(targetDir, "strata.layers.json"), renderLayersManifest(projectName, layers));
+  writeText(join2(targetDir, "Dockerfile"), renderDockerfile(layers));
+  writeText(join2(targetDir, ".dockerignore"), renderDockerignore(layers));
   const compose = renderDockerCompose(projectName, layers);
   if (compose) {
     writeText(join2(targetDir, "docker-compose.yml"), compose);
@@ -3887,7 +4140,7 @@ function writeGeneratedFiles(options) {
   mkdirSync2(join2(targetDir, "storage"), { recursive: true });
   writeText(join2(targetDir, "storage/.gitkeep"), "");
 }
-function printNextSteps(projectName, layers, compose) {
+function printNextSteps(projectName, layers, compose, cdTarget = projectName) {
   const dockerOn = selectedDockerServices(layers);
   const neededTools = neededDockerServices(layers);
   const localOn = neededTools.filter((name) => !dockerOn.includes(name));
@@ -3898,7 +4151,7 @@ Created Strata app in ${projectName}/
   console.log(`frontend=${layers.frontend}  db=${layers.database}  auth=${layers.auth}  docker=${dockerSummary}`);
   console.log(`
 Next steps:`);
-  console.log(`  cd ${projectName}`);
+  console.log(`  cd ${cdTarget}`);
   console.log("  cp .env.example .env");
   if (compose) {
     console.log("  docker compose up -d");
@@ -3910,8 +4163,15 @@ Next steps:`);
     console.log(`  Point env at local ${localOn.join(", ")} (see README).`);
   }
   console.log("  bun install");
-  console.log("  strata migrate");
-  console.log(`  strata dev
+  if (needsFrontendBuild(layers.frontend)) {
+    console.log("  bun run frontend:install");
+    console.log("  bun run frontend:build");
+  }
+  console.log("  bun run db:migrate");
+  console.log(`  bun run dev
+`);
+  console.log("The strata binary is local to the app, so use the bun run scripts above.");
+  console.log(`Run it directly with bunx strata <command> from inside the app directory.
 `);
 }
 function generateProject(options) {
@@ -3940,16 +4200,16 @@ async function runCreateStrata(argv, cwd = process.cwd()) {
   }
   try {
     const plan = await resolveStarterPlan(flags);
-    const targetDir = resolve(cwd, plan.projectName);
+    const { projectName, targetDir } = resolveProjectTarget(plan.projectName, cwd);
     generateProject({
-      projectName: plan.projectName,
+      projectName,
       targetDir,
       layers: plan.layers,
       templateRoot: resolveTemplateRoot(),
       overlayRoot: resolveOverlayRoot(),
       force: flags.force
     });
-    printNextSteps(plan.projectName, plan.layers, renderDockerCompose(plan.projectName, plan.layers) !== null);
+    printNextSteps(projectName, plan.layers, renderDockerCompose(projectName, plan.layers) !== null, plan.projectName);
     return 0;
   } catch (error) {
     console.error(error instanceof Error ? error.message : error);