vibecarbon 0.1.0

package/src/create.js

@@ -0,0 +1,1499 @@
+/**
+ * Vibecarbon Create Command
+ * Scaffolds a complete Hono + Vite + React 19 + Supabase self-hosted stack
+ *
+ * Usage:
+ *   vibecarbon create my-app              # Create new project
+ *   vibecarbon create my-app -y           # Skip prompts, use defaults
+ *   vibecarbon create my-app --use-npm    # Use npm instead of pnpm
+ *   vibecarbon create --help              # Show help
+ */
+
+import { execFileSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as p from '@clack/prompts';
+import { hashContent } from './lib/checksum.js';
+import { renderHelp } from './lib/cli/help.js';
+import { parseFlags } from './lib/cli/parse-flags.js';
+import { c, printBanner } from './lib/colors.js';
+import { runCommand } from './lib/command.js';
+import { registerProject } from './lib/config.js';
+import {
+  adaptDockerfileForPackageManager,
+  getPackageManagerVersion,
+} from './lib/package-manager.js';
+import { saveManifest, validateGitignore } from './lib/project.js';
+import {
+  generateJWT,
+  generatePassword,
+  generateReplPassword,
+  hashPassword,
+} from './lib/secrets.js';
+import { escapeDotenv } from './lib/shell.js';
+import { createTracker } from './lib/tracker.js';
+import { getUpgradeableFiles } from './lib/upgrade-policy.js';
+import {
+  validateAdminEmail,
+  validateAdminPassword,
+  validateProjectName,
+} from './lib/validators.js';
+import { VERSION } from './lib/version.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATE_DIR = join(__dirname, '..', 'carbon');
+
+// Launch decision (2026-05-06): hide the interactive package-manager
+// prompt and default to pnpm. The bun + npm code paths work — adapter
+// rewrites the Dockerfile correctly, lockfile gets generated at create
+// time — but pnpm has by far the most e2e-matrix coverage. Power
+// users can still pick npm or bun via `--use-npm` / `--use-bun`. Flip
+// this to `true` to bring the prompt back once bun/npm have matrix
+// coverage parity.
+const SHOW_PACKAGE_MANAGER_PROMPT = false;
+
+// Template variable placeholders
+const PLACEHOLDERS = {
+  PROJECT_NAME: '{{PROJECT_NAME}}',
+  GITHUB_OWNER: '{{GITHUB_OWNER}}',
+  DB_PASSWORD: '{{DB_PASSWORD}}',
+  JWT_SECRET: '{{JWT_SECRET}}',
+  ANON_KEY: '{{ANON_KEY}}',
+  SERVICE_ROLE_KEY: '{{SERVICE_ROLE_KEY}}',
+  REALTIME_SECRET: '{{REALTIME_SECRET}}',
+  LOGFLARE_API_KEY: '{{LOGFLARE_API_KEY}}',
+  VAULT_ENC_KEY: '{{VAULT_ENC_KEY}}',
+  PG_META_CRYPTO_KEY: '{{PG_META_CRYPTO_KEY}}',
+  DB_ENC_KEY: '{{DB_ENC_KEY}}',
+  REPL_PASSWORD: '{{REPL_PASSWORD}}',
+  SITE_URL: '{{SITE_URL}}',
+  ADMIN_EMAIL: '{{ADMIN_EMAIL}}',
+  ADMIN_PASSWORD: '{{ADMIN_PASSWORD}}',
+  ADMIN_PASSWORD_HASH: '{{ADMIN_PASSWORD_HASH}}',
+};
+
+// Placeholders that are NEVER substituted into checked-in template files at
+// create time. Their values land in `.env.local` (gitignored) via direct
+// dotenv writes; the deploy code (src/lib/deploy/**) patches them into k8s
+// manifests at deploy time. Substituting them here would bake a high-entropy
+// secret into a file that lands in `git ls-files` and trips the preflight
+// secret-scan during the next `vibecarbon deploy` — the exact regression
+// fixed by this set (k8s/values/supabase.values.yaml ADMIN_PASSWORD).
+//
+// ADMIN_PASSWORD_HASH is intentionally NOT in this set: volumes/db/super-admin.sql
+// is a Postgres init script with no deploy-time substitution layer, so its
+// bcrypt hash must be substituted at create time for first-boot admin user
+// creation to work. The scanner does not match `password_hash :=` (its regex
+// requires `password\s*[:=]`, not `password_hash\s*:=`), so a hash leak there
+// is benign for the scanner. If a future template adds a hash to another
+// file, treat it as a separate fix.
+const SECRET_PLACEHOLDERS = new Set([
+  'DB_PASSWORD',
+  'JWT_SECRET',
+  'ANON_KEY',
+  'SERVICE_ROLE_KEY',
+  'REALTIME_SECRET',
+  'LOGFLARE_API_KEY',
+  'VAULT_ENC_KEY',
+  'PG_META_CRYPTO_KEY',
+  'DB_ENC_KEY',
+  'REPL_PASSWORD',
+  'ADMIN_PASSWORD',
+]);
+
+// ============================================================================
+// CLI ARGUMENT PARSING
+// ============================================================================
+
+// ============================================================================
+// COMMAND SPEC — single source of truth for argv parsing AND help output.
+// ============================================================================
+
+/** @type {import('./lib/cli/parse-flags.js').CommandSpec & { summary?: string, description?: string, examples?: Array<{ command: string, description?: string }> }} */
+const SPEC = {
+  name: 'create',
+  summary: 'Scaffold a new Vibecarbon project',
+  description: [
+    "What's included:",
+    '  • Hono API server with TypeScript',
+    '  • Vite + React 19 SPA',
+    '  • Supabase self-hosted (Auth, Database, Storage, Realtime)',
+    '  • PostgreSQL with Row Level Security',
+    '  • Kong API Gateway + Supabase Studio',
+    '  • Docker Compose for local development',
+    '  • Kubernetes for production with autoscaling',
+    '  • Traefik reverse proxy with automatic HTTPS',
+    '  • Shadcn UI component library',
+    '  • GitHub Actions CI/CD',
+    '  • Automated backups',
+  ].join('\n'),
+  positional: [
+    {
+      name: 'projectName',
+      optional: true,
+      description: 'Project directory name (skips the name prompt)',
+    },
+  ],
+  flags: [
+    { name: 'h', boolean: true, description: 'Show this help' },
+    { name: 'v', boolean: true, description: 'Show version' },
+    {
+      name: 'y',
+      boolean: true,
+      description: 'Skip prompts (requires -admin-email and -admin-password)',
+    },
+    {
+      name: 'git',
+      boolean: true,
+      description: 'Initialize a git repository (default: off; opt-in)',
+    },
+    {
+      name: 'install',
+      boolean: true,
+      description: "Run the package manager's install during create (default: off)",
+    },
+    {
+      name: 'skip-lockfile',
+      boolean: true,
+      description:
+        'Skip lockfile generation (faster; deploy will need `vibecarbon up` first to install)',
+    },
+    {
+      name: 'pm',
+      value: '<name>',
+      enum: ['npm', 'pnpm', 'bun'],
+      description: 'Package manager to use (default: pnpm)',
+    },
+    {
+      name: 'admin-email',
+      value: '<email>',
+      description: 'Admin email for dashboard access (required with -y)',
+    },
+    {
+      name: 'admin-password',
+      value: '<pw>',
+      description: 'Admin password for dashboard access (required with -y)',
+    },
+  ],
+  examples: [
+    { command: 'vibecarbon create my-saas', description: 'create a project interactively' },
+    {
+      command:
+        'vibecarbon create my-saas -y -admin-email admin@example.com -admin-password secret123',
+      description: 'non-interactive (CI/CD)',
+    },
+    {
+      command: 'vibecarbon create my-saas -git -install',
+      description: 'create + initialize git + run pm install',
+    },
+  ],
+};
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+function isCI() {
+  return (
+    process.env.CI === 'true' ||
+    process.env.CONTINUOUS_INTEGRATION === 'true' ||
+    process.env.GITHUB_ACTIONS === 'true' ||
+    process.env.GITLAB_CI === 'true' ||
+    process.env.CIRCLECI === 'true' ||
+    process.env.JENKINS_URL !== undefined
+  );
+}
+
+function detectPackageManager() {
+  // Check user agent first (set by npm/pnpm/bun when running npx/pnpx/etc)
+  // Only detect pnpm/bun from user agent - if someone runs via npx, we still
+  // want to default to pnpm rather than assuming they want npm for their project
+  const ua = process.env.npm_config_user_agent || '';
+  if (ua.startsWith('pnpm')) return 'pnpm';
+  if (ua.startsWith('bun')) return 'bun';
+
+  // Check for lockfiles in cwd
+  if (existsSync('pnpm-lock.yaml')) return 'pnpm';
+  if (existsSync('bun.lock') || existsSync('bun.lockb')) return 'bun';
+  if (existsSync('package-lock.json')) return 'npm';
+
+  return 'pnpm'; // default
+}
+
+function getInstallCommand(pm) {
+  switch (pm) {
+    case 'npm':
+      return 'npm install';
+    case 'bun':
+      return 'bun install';
+    default:
+      // Use --no-frozen-lockfile for new projects (no lockfile exists yet)
+      // This is needed in CI environments where pnpm defaults to frozen-lockfile
+      return 'pnpm install --no-frozen-lockfile';
+  }
+}
+
+// Recommended minimum versions for best experience
+const RECOMMENDED_VERSIONS = {
+  npm: { min: 10, message: 'npm 10+ recommended for better performance and security' },
+  pnpm: { min: 9, message: 'pnpm 9+ recommended for better performance' },
+  bun: { min: 1.2, message: 'bun 1.2+ recommended (uses text-based bun.lock)' },
+};
+
+function checkPackageManagerVersion(pm) {
+  try {
+    const version = runCommand([pm, '--version'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    const parts = version.split('.');
+    const major = parseInt(parts[0], 10);
+    const minor = parseInt(parts[1] || '0', 10);
+    const recommended = RECOMMENDED_VERSIONS[pm];
+
+    if (recommended) {
+      const reqMajor = Math.floor(recommended.min);
+      const reqMinor = Math.round((recommended.min - reqMajor) * 10);
+      if (major < reqMajor || (major === reqMajor && minor < reqMinor)) {
+        return {
+          current: version,
+          isOutdated: true,
+          message: recommended.message,
+        };
+      }
+    }
+    return { current: version, isOutdated: false };
+  } catch {
+    return { current: null, isOutdated: false };
+  }
+}
+
+const INSTALL_INSTRUCTIONS = {
+  pnpm: 'npm install -g pnpm',
+  bun: 'curl -fsSL https://bun.sh/install | bash',
+};
+
+function isPackageManagerInstalled(pm) {
+  try {
+    execFileSync(pm, ['--version'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensurePackageManagerInstalled(pm, skipPrompts = false) {
+  if (isPackageManagerInstalled(pm)) return pm;
+
+  const installCmd = INSTALL_INSTRUCTIONS[pm];
+  if (installCmd) {
+    p.log.warn(`${c.bold(pm)} is not installed. To install it, run:\n\n  ${c.info(installCmd)}\n`);
+  } else {
+    p.log.warn(`${c.bold(pm)} is not installed.`);
+  }
+
+  if (skipPrompts) {
+    p.log.info(`Falling back to ${c.bold('npm')}.`);
+    return 'npm';
+  }
+
+  const fallback = await p.select({
+    message: 'Choose a package manager',
+    options: [
+      { value: 'npm', label: 'npm', hint: 'already installed with Node.js' },
+      { value: 'pnpm', label: 'pnpm' },
+      { value: 'bun', label: 'bun' },
+    ].filter((opt) => opt.value !== pm),
+  });
+
+  if (p.isCancel(fallback)) {
+    p.cancel('Operation cancelled.');
+    process.exit(0);
+  }
+
+  // Recurse in case the fallback isn't installed either
+  return ensurePackageManagerInstalled(fallback);
+}
+
+function copyTemplate(templatePath, destPath, variables) {
+  const fullTemplatePath = join(TEMPLATE_DIR, templatePath);
+
+  if (!existsSync(fullTemplatePath)) {
+    return false;
+  }
+
+  let content = readFileSync(fullTemplatePath, 'utf-8');
+
+  for (const [key, placeholder] of Object.entries(PLACEHOLDERS)) {
+    if (SECRET_PLACEHOLDERS.has(key)) continue;
+    if (variables[key] !== undefined) {
+      content = content.replaceAll(placeholder, variables[key]);
+    }
+  }
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, content);
+  return true;
+}
+
+function copyTemplateDir(templateSubdir, destDir, variables, exclude = [], rawCopy = []) {
+  const fullTemplatePath = join(TEMPLATE_DIR, templateSubdir);
+
+  if (!existsSync(fullTemplatePath)) {
+    return;
+  }
+
+  const entries = readdirSync(fullTemplatePath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const destPath = join(destDir, entry.name);
+
+    if (exclude.includes(entry.name)) continue;
+
+    if (entry.isDirectory()) {
+      mkdirSync(destPath, { recursive: true });
+      copyTemplateDir(join(templateSubdir, entry.name), destPath, variables, exclude, rawCopy);
+    } else if (rawCopy.includes(entry.name)) {
+      mkdirSync(dirname(destPath), { recursive: true });
+      copyFileSync(join(fullTemplatePath, entry.name), destPath);
+    } else {
+      copyTemplate(join(templateSubdir, entry.name), destPath, variables);
+    }
+  }
+}
+
+/**
+ * Validate that no unreplaced {{PLACEHOLDER}} patterns remain in generated files.
+ * Only checks for placeholders that should have been replaced during creation
+ * (those in PLACEHOLDERS minus SECRET_PLACEHOLDERS — the latter are intentionally
+ * left as placeholders for deploy-time substitution). Deploy-only placeholders
+ * like {{DOMAIN}}, {{ACME_EMAIL}} etc. are also expected to remain.
+ *
+ * Returns an array of { file, placeholders } objects for files with issues.
+ */
+function validatePlaceholders(projectDir, exclude = []) {
+  const issues = [];
+
+  // Build pattern to match only creation-time placeholders (secrets are
+  // deploy-time substituted, so they're expected to remain unreplaced).
+  const creationPlaceholders = Object.keys(PLACEHOLDERS).filter(
+    (key) => !SECRET_PLACEHOLDERS.has(key),
+  );
+  const placeholderPattern = new RegExp(`\\{\\{(${creationPlaceholders.join('|')})\\}\\}`, 'g');
+
+  // Files/directories to skip (binary files, lockfiles, etc.)
+  const skipPatterns = [
+    'node_modules',
+    '.git',
+    'pnpm-lock.yaml',
+    'package-lock.json',
+
+    'bun.lock',
+    'bun.lockb',
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.ico',
+    '.woff',
+    '.woff2',
+    '.ttf',
+    '.eot',
+  ];
+
+  function scanDir(dir) {
+    if (!existsSync(dir)) return;
+
+    const entries = readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      const relativePath = fullPath.replace(`${projectDir}/`, '');
+
+      // Skip excluded paths
+      if (exclude.includes(entry.name)) continue;
+      if (skipPatterns.some((p) => entry.name.includes(p) || entry.name.endsWith(p))) continue;
+
+      if (entry.isDirectory()) {
+        scanDir(fullPath);
+      } else {
+        try {
+          const content = readFileSync(fullPath, 'utf-8');
+          const matches = content.match(placeholderPattern);
+          if (matches) {
+            // Get unique placeholders
+            const uniquePlaceholders = [...new Set(matches)];
+            issues.push({ file: relativePath, placeholders: uniquePlaceholders });
+          }
+        } catch {
+          // Skip files that can't be read as text (binary files)
+        }
+      }
+    }
+  }
+
+  scanDir(projectDir);
+  return issues;
+}
+
+// Helper to allow UI updates between operations
+function tick() {
+  return new Promise((resolve) => setTimeout(resolve, 400));
+}
+
+// ============================================================================
+// MAIN BOOTSTRAP FUNCTION
+// ============================================================================
+
+async function bootstrap(cliArgs) {
+  const { values, positional, errors } = parseFlags(cliArgs, SPEC);
+
+  if (errors.length > 0) {
+    for (const e of errors) {
+      process.stderr.write(`${c.error('✗')} ${e}\n`);
+    }
+    process.stderr.write(`Run ${c.info('vibecarbon create -h')} for usage.\n`);
+    process.exit(1);
+  }
+
+  if (values.h) {
+    process.stdout.write(renderHelp(SPEC));
+    process.exit(0);
+  }
+  if (values.v) {
+    console.log(`create-vibecarbon v${VERSION}`);
+    process.exit(0);
+  }
+
+  // Build the legacy `args` shape that the orchestration code reads.
+  // -git is opt-in (default off), so noGit (the legacy field) is the
+  // INVERSE of values.git.
+  const args = {
+    projectName: positional.projectName || null,
+    yes: !!values.y,
+    install: !!values.install,
+    skipLockfile: !!values['skip-lockfile'],
+    noGit: !values.git,
+    packageManager: /** @type {string|null} */ (values.pm),
+    adminEmail: /** @type {string|null} */ (values['admin-email']),
+    adminPassword: /** @type {string|null} */ (values['admin-password']),
+  };
+
+  const skipPrompts = args.yes || isCI();
+
+  // Start interactive UI
+  printBanner();
+  p.intro(`${c.bold('vibecarbon create')} ${c.dim(`v${VERSION}`)}`);
+
+  // Gather configuration.
+  // projectName is the basename; it's also the directory name created in cwd.
+  // Legacy behavior allowed paths like '../my-app'; we now require a bare
+  // basename so the generated project always lands in a predictable place
+  // and can't escape cwd (CVE-class path-traversal).
+  let projectName = args.projectName;
+  let packageManager = args.packageManager || detectPackageManager();
+  let initGit = !args.noGit;
+  let adminEmail = args.adminEmail;
+  let adminPassword = args.adminPassword;
+
+  if (!skipPrompts) {
+    // Interactive prompts
+    const project = await p.group(
+      {
+        name: () => {
+          if (projectName) return Promise.resolve(projectName);
+          return p.text({
+            message: 'What is your project name?',
+            placeholder: 'my-saas',
+            validate: (value) => {
+              const err = validateProjectName(value);
+              if (err) return err;
+              if (existsSync(join(process.cwd(), value))) {
+                return `Directory "${value}" already exists`;
+              }
+            },
+          });
+        },
+        adminEmail: () => {
+          if (adminEmail) return Promise.resolve(adminEmail);
+          return p.text({
+            message: 'Admin email (for all dashboard access):',
+            placeholder: 'admin@example.com',
+            validate: (value) => {
+              const err = validateAdminEmail(value);
+              if (err) return err;
+            },
+          });
+        },
+        adminPassword: () => {
+          if (adminPassword) return Promise.resolve(adminPassword);
+          return p.password({
+            message: 'Admin password (min 8 characters):',
+            validate: (value) => {
+              const err = validateAdminPassword(value);
+              if (err) return err;
+            },
+          });
+        },
+        packageManager: () => {
+          if (args.packageManager) return Promise.resolve(args.packageManager);
+          // Launch decision (2026-05-06): hide the interactive package-
+          // manager prompt and default to pnpm. The bun + npm code paths
+          // work (vibecarbon create --use-bun and --use-npm both produce
+          // green builds end-to-end), but pnpm has the most e2e-
+          // matrix coverage by far. Power users can still pick npm/bun
+          // via the CLI flags. Re-enable the prompt by flipping
+          // SHOW_PACKAGE_MANAGER_PROMPT back to true once bun/npm have
+          // matrix coverage parity.
+          if (!SHOW_PACKAGE_MANAGER_PROMPT) return Promise.resolve('pnpm');
+          return p.select({
+            message: 'Which package manager?',
+            options: [
+              { value: 'pnpm', label: 'pnpm', hint: 'recommended' },
+              { value: 'npm', label: 'npm' },
+              { value: 'bun', label: 'bun' },
+            ],
+            initialValue: packageManager,
+          });
+        },
+        git: () => {
+          if (args.noGit) return Promise.resolve(false);
+          return p.confirm({
+            message: 'Initialize a git repository for version control?',
+            initialValue: true,
+          });
+        },
+      },
+      {
+        onCancel: () => {
+          p.cancel('Operation cancelled.');
+          process.exit(0);
+        },
+      },
+    );
+
+    projectName = project.name;
+    adminEmail = project.adminEmail;
+    adminPassword = project.adminPassword;
+    packageManager = project.packageManager;
+    initGit = project.git;
+  } else {
+    // Non-interactive validation
+    if (!projectName) {
+      p.log.error('Project name required. Usage: npx create-vibecarbon <project-name> [options]');
+      process.exit(1);
+    }
+    const nameErr = validateProjectName(projectName);
+    if (nameErr) {
+      p.log.error(`Invalid project name "${projectName}": ${nameErr}`);
+      process.exit(1);
+    }
+    if (existsSync(join(process.cwd(), projectName))) {
+      p.log.error(`Directory "${projectName}" already exists.`);
+      process.exit(1);
+    }
+    // Require admin credentials in non-interactive mode
+    if (!adminEmail) {
+      p.log.error('Admin email required. Use --admin-email=you@example.com');
+      process.exit(1);
+    }
+    if (!adminPassword) {
+      p.log.error('Admin password required. Use --admin-password=yourpassword');
+      process.exit(1);
+    }
+    const emailErr = validateAdminEmail(adminEmail);
+    if (emailErr) {
+      p.log.error(`Invalid --admin-email "${adminEmail}": ${emailErr}`);
+      process.exit(1);
+    }
+    const pwErr = validateAdminPassword(adminPassword);
+    if (pwErr) {
+      p.log.error(`Invalid --admin-password: ${pwErr}`);
+      process.exit(1);
+    }
+  }
+
+  // projectDir is the full path where files are created.
+  // projectName is also the directory name since we require basenames only.
+  const projectDir = join(process.cwd(), projectName);
+
+  // Show configuration
+  p.note(
+    [
+      `Project:          ${projectName}`,
+      `Admin:            ${adminEmail}`,
+      `Package manager:  ${packageManager}`,
+      `Git:              ${initGit ? 'yes' : 'no'}`,
+    ].join('\n'),
+    'Configuration',
+  );
+
+  // Verify package manager is installed
+  packageManager = await ensurePackageManagerInstalled(packageManager, skipPrompts);
+
+  // Check for outdated package manager and warn
+  const versionCheck = checkPackageManagerVersion(packageManager);
+  if (versionCheck.isOutdated) {
+    p.log.warn(
+      `${c.dim(`${packageManager} ${versionCheck.current} detected.`)} ${versionCheck.message}`,
+    );
+  }
+
+  // Generate secure secrets
+  const dbPassword = generatePassword();
+  const jwtSecret = generatePassword(64);
+  const realtimeSecret = generatePassword(64); // SECRET_KEY_BASE (min 64 chars)
+  const logflareApiKey = generatePassword(32);
+  const vaultEncKey = generatePassword(16); // VAULT_ENC_KEY (exactly 32 hex chars = 16 bytes)
+  const pgMetaCryptoKey = generatePassword(32); // PG_META_CRYPTO_KEY (min 32 chars)
+  const dbEncKey = generatePassword(16); // DB_ENC_KEY for Realtime aes_128_ecb (must be exactly 16 bytes)
+  const replPassword = generateReplPassword();
+  const anonKey = generateJWT(jwtSecret, {
+    role: 'anon',
+    iss: 'supabase',
+    ref: projectName,
+  });
+
+  const serviceRoleKey = generateJWT(jwtSecret, {
+    role: 'service_role',
+    iss: 'supabase',
+    ref: projectName,
+  });
+
+  const variables = {
+    PROJECT_NAME: projectName,
+    GITHUB_OWNER: projectName, // Default to project name; rewritten by `vibecarbon configure` → CI/CD (or by deploy's rewriteOwnerAndRepo fallback)
+    DB_PASSWORD: dbPassword,
+    JWT_SECRET: jwtSecret,
+    ANON_KEY: anonKey,
+    SERVICE_ROLE_KEY: serviceRoleKey,
+    REALTIME_SECRET: realtimeSecret,
+    LOGFLARE_API_KEY: logflareApiKey,
+    VAULT_ENC_KEY: vaultEncKey,
+    PG_META_CRYPTO_KEY: pgMetaCryptoKey,
+    DB_ENC_KEY: dbEncKey,
+    REPL_PASSWORD: replPassword,
+    SITE_URL: 'http://localhost:5173',
+    ADMIN_EMAIL: adminEmail,
+    ADMIN_PASSWORD: adminPassword || '',
+    ADMIN_PASSWORD_HASH: adminPassword ? hashPassword(adminPassword) : '',
+  };
+
+  // Create project
+  const tracker = createTracker('create', { project: projectName });
+  const s = tracker.spinner();
+
+  s.start('Creating project structure');
+  mkdirSync(projectDir, { recursive: true });
+
+  const dirs = [
+    'src/server/routes/api',
+    'src/server/routes/_internal',
+    'src/server/routes/v1',
+    'src/server/lib',
+    'src/client/components/auth',
+    'src/client/components/ui',
+    'src/client/pages',
+    'src/client/lib',
+    'src/shared',
+    'supabase/migrations',
+    'db',
+    'public',
+    'backup',
+    'volumes/kong',
+    'volumes/db',
+    'volumes/traefik',
+    'volumes/prometheus',
+    'volumes/loki',
+    'volumes/promtail',
+    'volumes/grafana/provisioning/dashboards',
+    'volumes/grafana/provisioning/datasources',
+    'volumes/grafana/dashboards',
+    'volumes/grafana/dashboards.dev',
+    '.github/workflows',
+    'k8s/base/app',
+    'k8s/base/backup',
+    'k8s/base/config',
+    'k8s/base/hetzner-ccm',
+    'k8s/base/hetzner-csi',
+    'k8s/base/traefik',
+    'k8s/infra/cert-manager-resources',
+    'k8s/infra/traefik-crds',
+    'k8s/overlays/production',
+    'k8s/overlays/local',
+    'k8s/flux/clusters/primary',
+    'k8s/flux/clusters/standby',
+    'k8s/gitops/supabase',
+    'k8s/gitops/cert-manager-webhook-hetzner',
+    'k8s/values',
+  ];
+  for (const dir of dirs) {
+    mkdirSync(join(projectDir, dir), { recursive: true });
+  }
+  await tick();
+
+  s.message('Generating configuration files');
+  copyTemplate('package.json', join(projectDir, 'package.json'), variables);
+  // Lock files are generated by the package manager during install — don't copy stale ones
+  copyTemplate('tsconfig.json', join(projectDir, 'tsconfig.json'), variables);
+  copyTemplate('tsconfig.server.json', join(projectDir, 'tsconfig.server.json'), variables);
+  copyTemplate('vite.config.ts', join(projectDir, 'vite.config.ts'), variables);
+  copyTemplate('biome.json', join(projectDir, 'biome.json'), variables);
+  copyTemplate('components.json', join(projectDir, 'components.json'), variables);
+
+  // Test scaffolding — three-tier vitest setup + helpers + golden seed tests.
+  // See carbon/TESTING.md for the tier conventions; the test-maintainer
+  // subagent extends from this seed when writing new tests.
+  copyTemplate('vitest.config.ts', join(projectDir, 'vitest.config.ts'), variables);
+  copyTemplate('tsconfig.test.json', join(projectDir, 'tsconfig.test.json'), variables);
+  copyTemplate('TESTING.md', join(projectDir, 'TESTING.md'), variables);
+  copyTemplateDir('tests', join(projectDir, 'tests'), variables);
+  // Copy .env.example WITHOUT replacing placeholders (it's committed to git as documentation)
+  const envExampleContent = readFileSync(join(TEMPLATE_DIR, '.env.example'), 'utf-8');
+  writeFileSync(join(projectDir, '.env.example'), envExampleContent);
+  const envLocal = generateEnvLocal(projectName, variables);
+  writeFileSync(join(projectDir, '.env.local'), envLocal, { mode: 0o600 });
+  // Also create .env for docker-compose (reads .env by default)
+  writeFileSync(join(projectDir, '.env'), envLocal, { mode: 0o600 });
+  await tick();
+
+  s.message('Generating Docker configuration');
+  copyTemplate('Dockerfile', join(projectDir, 'Dockerfile'), variables);
+  adaptDockerfileForPackageManager(projectDir, packageManager);
+  copyTemplate('docker-entrypoint.sh', join(projectDir, 'docker-entrypoint.sh'), variables);
+  copyTemplate('.dockerignore', join(projectDir, '.dockerignore'), variables);
+  copyTemplate('docker-compose.yml', join(projectDir, 'docker-compose.yml'), variables);
+  copyTemplate('docker-compose.prod.yml', join(projectDir, 'docker-compose.prod.yml'), variables);
+  copyTemplate(
+    'docker-compose.observability.yml',
+    join(projectDir, 'docker-compose.observability.yml'),
+    variables,
+  );
+  copyTemplate(
+    'docker-compose.override.yml',
+    join(projectDir, 'docker-compose.override.yml'),
+    variables,
+  );
+  copyTemplate(
+    'docker-compose.observability.override.yml',
+    join(projectDir, 'docker-compose.observability.override.yml'),
+    variables,
+  );
+  copyTemplate('PRODUCTION.md', join(projectDir, 'PRODUCTION.md'), variables);
+  copyTemplate('DEVELOPMENT.md', join(projectDir, 'DEVELOPMENT.md'), variables);
+  copyTemplate(
+    'docker-compose.dev-init.yml',
+    join(projectDir, 'docker-compose.dev-init.yml'),
+    variables,
+  );
+  copyTemplate(
+    'docker-compose.observability.prod.yml',
+    join(projectDir, 'docker-compose.observability.prod.yml'),
+    variables,
+  );
+  chmodSync(join(projectDir, 'docker-entrypoint.sh'), 0o755);
+
+  await tick();
+
+  s.message('Generating backend files');
+  copyTemplate('volumes/kong/kong.yml', join(projectDir, 'volumes/kong/kong.yml'), variables);
+  copyTemplate(
+    'volumes/kong/docker-entrypoint.sh',
+    join(projectDir, 'volumes/kong/docker-entrypoint.sh'),
+    variables,
+  );
+  copyTemplate('volumes/db/roles.sql', join(projectDir, 'volumes/db/roles.sql'), variables);
+  copyTemplate(
+    'volumes/db/set-passwords.sh',
+    join(projectDir, 'volumes/db/set-passwords.sh'),
+    variables,
+  );
+  copyTemplate('volumes/db/jwt.sql', join(projectDir, 'volumes/db/jwt.sql'), variables);
+  copyTemplate('volumes/db/realtime.sql', join(projectDir, 'volumes/db/realtime.sql'), variables);
+  copyTemplate(
+    'volumes/db/super-admin.sql',
+    join(projectDir, 'volumes/db/super-admin.sql'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/db/super-admin.dev.sql',
+    join(projectDir, 'volumes/db/super-admin.dev.sql'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/traefik/middlewares.yml',
+    join(projectDir, 'volumes/traefik/middlewares.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/traefik/middlewares.dev.yml',
+    join(projectDir, 'volumes/traefik/middlewares.dev.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/traefik/vite-dev.yml',
+    join(projectDir, 'volumes/traefik/vite-dev.yml'),
+    variables,
+  );
+
+  // Observability config files (used by deploy --observability)
+  copyTemplate(
+    'volumes/prometheus/prometheus.yml',
+    join(projectDir, 'volumes/prometheus/prometheus.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/loki/loki-config.yml',
+    join(projectDir, 'volumes/loki/loki-config.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/promtail/promtail-config.yml',
+    join(projectDir, 'volumes/promtail/promtail-config.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/provisioning/dashboards/dashboards.yml',
+    join(projectDir, 'volumes/grafana/provisioning/dashboards/dashboards.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/provisioning/dashboards/dashboards.dev.yml',
+    join(projectDir, 'volumes/grafana/provisioning/dashboards/dashboards.dev.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/provisioning/datasources/datasources.yml',
+    join(projectDir, 'volumes/grafana/provisioning/datasources/datasources.yml'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/dashboards/logs.json',
+    join(projectDir, 'volumes/grafana/dashboards/logs.json'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/dashboards/overview.json',
+    join(projectDir, 'volumes/grafana/dashboards/overview.json'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/dashboards/postgresql.json',
+    join(projectDir, 'volumes/grafana/dashboards/postgresql.json'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/dashboards.dev/logs.json',
+    join(projectDir, 'volumes/grafana/dashboards.dev/logs.json'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/dashboards.dev/overview.json',
+    join(projectDir, 'volumes/grafana/dashboards.dev/overview.json'),
+    variables,
+  );
+  copyTemplate(
+    'volumes/grafana/dashboards.dev/postgresql.json',
+    join(projectDir, 'volumes/grafana/dashboards.dev/postgresql.json'),
+    variables,
+  );
+
+  copyTemplate('backup/backup.sh', join(projectDir, 'backup/backup.sh'), variables);
+  copyTemplate('backup/compose-backup.sh', join(projectDir, 'backup/compose-backup.sh'), variables);
+  copyTemplate('backup/Dockerfile', join(projectDir, 'backup/Dockerfile'), variables);
+  chmodSync(join(projectDir, 'backup/backup.sh'), 0o755);
+  chmodSync(join(projectDir, 'backup/compose-backup.sh'), 0o755);
+  // CI/CD workflow files are NOT shipped at create time — `vibecarbon
+  // configure` → CI/CD installs them from src/lib/ci-setup.js when the user
+  // explicitly opts in. Direct deploy is the default; shipping the workflow
+  // files in fresh projects would silently flip ciAvailable() and force
+  // every deploy through GitHub Actions.
+  copyTemplate(
+    'supabase/migrations/00001_init.sql',
+    join(projectDir, 'supabase/migrations/00001_init.sql'),
+    variables,
+  );
+  copyTemplate('supabase/seed.sql', join(projectDir, 'supabase/seed.sql'), variables);
+  // Copy entire src directory (server, client, shared)
+  copyTemplateDir('src', join(projectDir, 'src'), variables);
+
+  // Blog content
+  copyTemplateDir('content', join(projectDir, 'content'), variables);
+
+  // Custom database files (WAL-G Dockerfile)
+  copyTemplateDir('db', join(projectDir, 'db'), variables);
+
+  // Kubernetes manifests (exclude optional features like n8n - they're added via `vibecarbon add`)
+  copyTemplateDir('k8s', join(projectDir, 'k8s'), variables, ['n8n']);
+
+  // Scripts (manifest-based docker/k8s commands)
+  // generate-dev-configs.sh contains {{PLACEHOLDER}} tokens as its own substitution keys,
+  // so it must be copied verbatim to avoid leaking real secrets into the script.
+  copyTemplateDir(
+    'scripts',
+    join(projectDir, 'scripts'),
+    variables,
+    [],
+    ['generate-dev-configs.sh'],
+  );
+
+  // Make shell scripts executable
+  const shellScripts = [
+    'k8s/test-local.sh',
+    'backup/backup.sh',
+    'docker-entrypoint.sh',
+    'volumes/kong/docker-entrypoint.sh',
+    'volumes/db/set-passwords.sh',
+  ];
+  for (const script of shellScripts) {
+    const scriptPath = join(projectDir, script);
+    if (existsSync(scriptPath)) {
+      chmodSync(scriptPath, 0o755);
+    }
+  }
+  await tick();
+
+  // Validate no unreplaced placeholders remain
+  s.message('Validating generated files');
+  const placeholderIssues = validatePlaceholders(projectDir, ['generate-dev-configs.sh', 'agents']);
+  if (placeholderIssues.length > 0) {
+    s.stop('Validation warning');
+    p.log.warn('Some files contain unreplaced placeholders:');
+    for (const issue of placeholderIssues.slice(0, 5)) {
+      p.log.warn(`  ${c.dim(issue.file)}: ${issue.placeholders.join(', ')}`);
+    }
+    if (placeholderIssues.length > 5) {
+      p.log.warn(`  ... and ${placeholderIssues.length - 5} more files`);
+    }
+    p.log.warn('This may indicate a bug in the template. Please report this issue.');
+  }
+  await tick();
+
+  s.message('Generating documentation and AI rules');
+  const readme = generateReadme(projectName, packageManager);
+  writeFileSync(join(projectDir, 'README.md'), readme);
+
+  // AI development experience files
+  copyTemplate('AGENTS.md', join(projectDir, 'AGENTS.md'), variables);
+  copyTemplate('CLAUDE.md', join(projectDir, 'CLAUDE.md'), variables);
+  copyTemplate('.windsurfrules', join(projectDir, '.windsurfrules'), variables);
+  copyTemplate(
+    '.github/copilot-instructions.md',
+    join(projectDir, '.github/copilot-instructions.md'),
+    variables,
+  );
+  mkdirSync(join(projectDir, '.cursor', 'rules'), { recursive: true });
+  copyTemplate(
+    '.cursor/rules/vibecarbon.mdc',
+    join(projectDir, '.cursor/rules/vibecarbon.mdc'),
+    variables,
+  );
+
+  // Claude Code subagents — copy from repo root, stripping auto-generated memory footer
+  const agentsSourceDir = join(__dirname, '..', '.claude', 'agents');
+  if (existsSync(agentsSourceDir)) {
+    const agentsDestDir = join(projectDir, '.claude', 'agents');
+    mkdirSync(agentsDestDir, { recursive: true });
+    for (const file of readdirSync(agentsSourceDir)) {
+      if (!file.endsWith('.md')) continue;
+      let content = readFileSync(join(agentsSourceDir, file), 'utf-8');
+      // Strip the auto-generated "Persistent Agent Memory" section — Claude Code
+      // re-injects it at runtime based on the `memory:` frontmatter field
+      content = content.replace(/\n# Persistent Agent Memory[\s\S]*$/, '\n');
+      writeFileSync(join(agentsDestDir, file), content);
+    }
+  }
+
+  // Copy .claude/settings.json (agent team config + hooks)
+  const settingsSource = join(TEMPLATE_DIR, '.claude', 'settings.json');
+  if (existsSync(settingsSource)) {
+    const settingsDest = join(projectDir, '.claude', 'settings.json');
+    mkdirSync(dirname(settingsDest), { recursive: true });
+    copyTemplate(join('.claude', 'settings.json'), settingsDest, variables);
+  }
+
+  // Copy .claude/hooks/
+  const hooksSourceDir = join(TEMPLATE_DIR, '.claude', 'hooks');
+  if (existsSync(hooksSourceDir)) {
+    const hooksDestDir = join(projectDir, '.claude', 'hooks');
+    mkdirSync(hooksDestDir, { recursive: true });
+    for (const file of readdirSync(hooksSourceDir)) {
+      copyTemplate(join('.claude', 'hooks', file), join(hooksDestDir, file), variables);
+    }
+    for (const file of readdirSync(hooksDestDir)) {
+      if (file.endsWith('.sh')) chmodSync(join(hooksDestDir, file), 0o755);
+    }
+  }
+
+  // Create agent memory directories
+  for (const agent of [
+    'backend-engineer',
+    'frontend-engineer',
+    'security-reviewer',
+    'test-maintainer',
+    'lead-coordinator',
+  ]) {
+    mkdirSync(join(projectDir, '.claude', 'agent-memory', agent), { recursive: true });
+  }
+
+  // Update package.json with project name and package manager
+  const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+  packageJson.packageManager = getPackageManagerVersion(packageManager);
+  packageJson.name = projectName;
+
+  // Replace pnpm references in scripts with the selected package manager
+  if (packageManager !== 'pnpm' && packageJson.scripts) {
+    const run = packageManager === 'npm' ? 'npm run' : packageManager;
+    for (const [key, value] of Object.entries(packageJson.scripts)) {
+      if (typeof value === 'string' && value.includes('pnpm ')) {
+        packageJson.scripts[key] = value.replaceAll('pnpm ', `${run} `);
+      }
+    }
+  }
+
+  writeFileSync(join(projectDir, 'package.json'), `${JSON.stringify(packageJson, null, 2)}\n`);
+
+  // Deps are deferred to `vibecarbon up` — it auto-installs on first run if
+  // node_modules is missing. Keeps `create` fast (e2e saw ~35s shaved
+  // when running many `create` calls in parallel) and avoids running the
+  // wrong PM against an empty tree. Opt-in via --install if you want the old
+  // behavior.
+  if (args.install) {
+    s.message(`Installing dependencies with ${packageManager}`);
+    await tick();
+    const installCmd = getInstallCommand(packageManager);
+    if (!runCommand(installCmd, { cwd: projectDir, cleanEnv: true })) {
+      s.stop('Failed to install dependencies');
+      p.log.error('Installation failed. You can try running the install command manually.');
+      process.exit(1);
+    }
+    await tick();
+  } else if (args.skipLockfile) {
+    // Caller opted out of lockfile gen — they'll run `vibecarbon up` (or
+    // the install manually) before `deploy`. Used by tests that only
+    // verify scaffolding, and by scripted CI flows that install later.
+  } else {
+    // Generate the lockfile so the Dockerfile's `COPY package.json
+    // <lockfile> ./` step has something to copy. Without this, going from
+    // `vibecarbon create` straight to `vibecarbon deploy` (skipping `up`)
+    // fails the docker build at the COPY step. `vibecarbon up` would
+    // generate the lockfile too, but we shouldn't make `up` a hard
+    // prerequisite for `deploy`.
+    //
+    // pnpm/npm have lockfile-only modes that skip node_modules (fast,
+    // ~2s). Bun has no equivalent — `bun install` always touches
+    // node_modules — but bun installs fast enough that the cost is
+    // acceptable for create. Either way, `vibecarbon up` later sees
+    // node_modules present and skips re-install.
+    let lockfileCmd = null;
+    let lockfileMsg = null;
+    if (packageManager === 'pnpm') {
+      lockfileCmd = ['pnpm', 'install', '--lockfile-only'];
+      lockfileMsg = 'Generating pnpm-lock.yaml (lockfile only)';
+    } else if (packageManager === 'npm') {
+      lockfileCmd = ['npm', 'install', '--package-lock-only'];
+      lockfileMsg = 'Generating package-lock.json (lockfile only)';
+    } else if (packageManager === 'bun') {
+      lockfileCmd = ['bun', 'install'];
+      lockfileMsg = 'Generating bun.lock (full install — bun has no lockfile-only mode)';
+    }
+    if (lockfileCmd) {
+      s.message(lockfileMsg);
+      await tick();
+      // Non-fatal if this fails — CI will regenerate or the user can install.
+      runCommand(lockfileCmd, {
+        cwd: projectDir,
+        cleanEnv: true,
+        ignoreError: true,
+      });
+      await tick();
+    }
+  }
+
+  // Initialize git
+  if (initGit) {
+    s.message('Initializing git repository');
+    copyTemplate('.gitignore', join(projectDir, '.gitignore'), variables);
+
+    const missingPatterns = validateGitignore(join(projectDir, '.gitignore'));
+    if (missingPatterns.length > 0) {
+      p.log.error(
+        `Generated .gitignore is missing required patterns: ${missingPatterns.join(', ')}`,
+      );
+      process.exit(1);
+    }
+
+    runCommand('git init', { cwd: projectDir, cleanEnv: true });
+
+    // Install pre-commit hook. Two responsibilities:
+    //   1. Lint staged code (catches biome/format issues early).
+    //   2. Run vibecarbon's secret scanner against staged files. The
+    //      scanner script lives at scripts/secret-scan.mjs (copied from
+    //      the template) so this hook works without the vibecarbon CLI
+    //      installed globally — every clone of the project gets the
+    //      same protection on a fresh `git init`.
+    //
+    // We don't install lefthook here because most projects already have
+    // a pre-commit setup of their own; a plain shell hook is simpler
+    // and harder to break. If a contributor wants a richer hook
+    // manager, lefthook.yml in the template gives them a starting
+    // point — `npx lefthook install` will replace this with that
+    // config.
+    const hooksDir = join(projectDir, '.git', 'hooks');
+    const runCmd =
+      packageManager === 'npm' ? 'npm run' : packageManager === 'bun' ? 'bun run' : 'pnpm';
+    const preCommitHook = `#!/bin/sh
+# Pre-commit hook installed by vibecarbon create.
+# Edit freely — but please keep the secret-scan step; it's the first
+# layer of defense against committing API keys, JWTs, private keys,
+# etc. \`vibecarbon deploy\` will refuse to push if it finds them
+# anyway, so removing this just delays the failure.
+
+set -e
+
+# 1. Lint
+${runCmd} lint
+
+# 2. Secret scan over staged files. Skip if the script is missing
+#    (e.g. the user wiped scripts/ during a refactor); the deploy gate
+#    will still catch it.
+if [ -f scripts/secret-scan.mjs ]; then
+  staged=$(git diff --cached --name-only --diff-filter=ACMR)
+  if [ -n "$staged" ]; then
+    echo "$staged" | node scripts/secret-scan.mjs --stdin
+  fi
+fi
+`;
+    writeFileSync(join(hooksDir, 'pre-commit'), preCommitHook);
+    chmodSync(join(hooksDir, 'pre-commit'), 0o755);
+
+    // Install pre-push hook. Runs the project's `test:prepush` script —
+    // lint + unit + component + integration. Integration mocks externals,
+    // so this works without Docker and is fast enough for every push.
+    // Bypass via `git push --no-verify` if you understand why your tests
+    // are red. The test-maintainer subagent shipped with the project
+    // keeps this suite green as code changes.
+    const prePushHook = `#!/bin/sh
+# Pre-push hook installed by vibecarbon create.
+# Runs lint + unit + component + integration tests.
+#
+# No-ops gracefully if node_modules isn't present yet — a fresh
+# \`vibecarbon create -git\` lands you on a commit that's pushable
+# before you've run \`pnpm install\`. Once deps land the hook gates
+# every subsequent push. Bypass at will with \`git push --no-verify\`.
+
+set -e
+
+if [ ! -d node_modules ]; then
+  echo "pre-push: node_modules not present — skipping tests."
+  echo "          Run '${runCmd} install' to enable the test gate."
+  exit 0
+fi
+
+${runCmd} test:prepush
+`;
+    writeFileSync(join(hooksDir, 'pre-push'), prePushHook);
+    chmodSync(join(hooksDir, 'pre-push'), 0o755);
+    await tick();
+  }
+
+  // Store template version and file checksums for `vibecarbon upgrade`
+  s.message('Recording file checksums');
+  const upgradeableFiles = getUpgradeableFiles(TEMPLATE_DIR);
+  const fileChecksums = {};
+  for (const relPath of upgradeableFiles) {
+    const filePath = join(projectDir, relPath);
+    if (existsSync(filePath)) {
+      try {
+        const content = readFileSync(filePath, 'utf-8');
+        fileChecksums[relPath] = hashContent(content);
+      } catch {
+        // Skip files that can't be read as text (binary)
+      }
+    }
+  }
+  saveManifest(
+    {
+      version: '1',
+      templateVersion: VERSION,
+      fileChecksums,
+      services: {},
+    },
+    projectDir,
+  );
+  await tick();
+
+  s.stop('Project created successfully');
+  registerProject(projectName, projectDir);
+  tracker.finish();
+  await tick();
+
+  // Next steps
+  const nextSteps = [
+    '# Change directory:',
+    `cd ${projectName}`,
+    '',
+    '# Run locally:',
+    'vibecarbon up',
+    '',
+    '# Deploy to cloud:',
+    'vibecarbon deploy',
+  ];
+
+  p.note(nextSteps.join('\n'), 'Next steps');
+  await tick();
+
+  p.outro(`Happy building! Admin: ${adminEmail}`);
+}
+
+// ============================================================================
+// GENERATOR FUNCTIONS
+// ============================================================================
+
+function generateEnvLocal(projectName, variables) {
+  // Quote-style policy:
+  //   - Machine-generated secrets (JWT_SECRET, ANON_KEY, etc) use double-quoted
+  //     form because they are drawn from the base64/base64url alphabet and can
+  //     never contain a shell metacharacter.
+  //   - User-supplied secrets (ADMIN_PASSWORD, REPL_PASSWORD) use escapeDotenv
+  //     (single-quoted, POSIX) so any hostile character round-trips safely.
+  return `# =============================================================================
+# SUPABASE CONFIGURATION
+# Generated by create-vibecarbon - DO NOT COMMIT THIS FILE
+# =============================================================================
+
+# Project name (used by docker-compose for container naming and Vite HTML title)
+PROJECT_NAME="${projectName}"
+VITE_PROJECT_NAME="${projectName}"
+
+# Supabase URLs
+SUPABASE_URL="http://localhost:8000"
+VITE_SUPABASE_URL="http://localhost:8000"
+
+# Supabase Keys
+SUPABASE_ANON_KEY="${variables.ANON_KEY}"
+VITE_SUPABASE_ANON_KEY="${variables.ANON_KEY}"
+SUPABASE_SERVICE_ROLE_KEY="${variables.SERVICE_ROLE_KEY}"
+
+# JWT Secret (for token generation)
+JWT_SECRET="${variables.JWT_SECRET}"
+
+# Database
+DB_PASSWORD="${variables.DB_PASSWORD}"
+POSTGRES_PASSWORD="${variables.DB_PASSWORD}"
+
+# Encryption Keys
+REALTIME_SECRET="${variables.REALTIME_SECRET}"
+VAULT_ENC_KEY="${variables.VAULT_ENC_KEY}"
+PG_META_CRYPTO_KEY="${variables.PG_META_CRYPTO_KEY}"
+DB_ENC_KEY="${variables.DB_ENC_KEY}"
+LOGFLARE_API_KEY="${variables.LOGFLARE_API_KEY}"
+
+# HA PostgreSQL replication (used by vibecarbon deploy --ha)
+REPL_PASSWORD=${escapeDotenv(variables.REPL_PASSWORD)}
+
+# =============================================================================
+# ADMIN CREDENTIALS
+# =============================================================================
+
+# Admin user with dashboard access (created during project setup)
+# Note: Password stored here for your reference only. Database stores bcrypt hash.
+ADMIN_EMAIL="${variables.ADMIN_EMAIL}"
+ADMIN_PASSWORD=${escapeDotenv(variables.ADMIN_PASSWORD)}
+
+# Site URL
+SITE_URL="http://localhost:5173"
+
+# =============================================================================
+# OAUTH PROVIDERS (optional)
+# =============================================================================
+
+GOOGLE_ENABLED="false"
+GOOGLE_CLIENT_ID=""
+GOOGLE_CLIENT_SECRET=""
+
+MICROSOFT_ENABLED="false"
+MICROSOFT_CLIENT_ID=""
+MICROSOFT_CLIENT_SECRET=""
+MICROSOFT_TENANT_ID=""
+
+# =============================================================================
+# EXTERNAL SERVICES (optional)
+# =============================================================================
+
+# Stripe
+STRIPE_SECRET_KEY=""
+STRIPE_WEBHOOK_SECRET=""
+
+# SMTP Email (shared by Supabase Auth and app transactional emails)
+SMTP_HOST=""
+SMTP_PORT=465
+SMTP_USER=""
+SMTP_PASS=""
+SMTP_ADMIN_EMAIL="noreply@example.com"
+SMTP_SENDER_NAME="${variables.PROJECT_NAME}"
+
+# =============================================================================
+# OPTIONAL SERVICES (for admin dashboard visibility)
+# =============================================================================
+# These control which services appear in the admin dashboard
+# Set automatically when using 'vibecarbon add' or manual docker-compose files
+
+VITE_N8N_ENABLED="false"
+VITE_OBSERVABILITY_ENABLED="false"
+
+# =============================================================================
+# PORT CONFIGURATION (for running multiple projects)
+# =============================================================================
+# Use DEV_PORT_OFFSET to shift all ports when running multiple projects.
+# Example: DEV_PORT_OFFSET=100 shifts Vite to 5273, API to 3100, etc.
+
+DEV_PORT_OFFSET="0"
+
+# Override individual ports (takes precedence over offset):
+# DEV_VITE_PORT="5173"
+# DEV_API_PORT="3000"
+# DEV_KONG_PORT="8000"
+# DEV_KONG_SSL_PORT="8443"
+# DEV_TRAEFIK_PORT="80"
+
+# =============================================================================
+# ENVIRONMENT
+# =============================================================================
+
+NODE_ENV="development"
+PORT="3000"
+`.trim();
+}
+
+function generateReadme(projectName, packageManager = 'pnpm') {
+  const run = packageManager === 'npm' ? 'npm run' : packageManager;
+  let readme = `# ${projectName}
+
+A modern web app built with Vibecarbon.
+
+## Stack
+
+- **Hono** - Fast, lightweight web framework
+- **Vite** - Next-generation frontend tooling
+- **React 19** - UI library (SPA mode)
+- **Supabase** - Self-hosted backend (Auth, Database, Storage, Realtime)
+- **PostgreSQL** - Database (via Supabase)
+- **Tailwind CSS** - Utility-first styling
+- **Shadcn UI** - Component library
+- **Kubernetes** - Container orchestration & autoscaling
+- **Traefik** - Reverse proxy with automatic HTTPS
+
+## Getting Started
+
+Start everything with a single command:
+
+\`\`\`bash
+vibecarbon up
+\`\`\`
+
+This starts Docker containers, runs database migrations, and launches the dev servers.
+
+## Services
+
+| Service | URL | Description |
+|---------|-----|-------------|
+| Vite Dev | http://localhost:5173 | Frontend development server |
+| Hono API | http://localhost:3000 | Application API |
+| Supabase API | http://localhost:8000 | Supabase API Gateway (Kong) |
+| Supabase Studio | http://studio.localhost | Database management UI (requires admin login) |
+| Traefik Dashboard | http://traefik.localhost | Reverse proxy dashboard (requires admin login) |
+
+## Available Scripts
+
+- \`${run} dev:start\` - Full cold start (Docker + migrations + dev servers)
+- \`${run} dev\` - Start both API and frontend dev servers (fast restart)
+- \`${run} dev:server\` - Start Hono API server only
+- \`${run} dev:client\` - Start Vite dev server only
+- \`${run} build\` - Build for production
+- \`${run} start\` - Run production build
+- \`${run} docker:up\` - Start all services
+- \`${run} dev:stop\` - Stop all services
+- \`${run} docker:logs\` - View service logs
+- \`${run} db:migrate\` - Run database migrations
+`;
+
+  readme += `
+## Troubleshooting
+
+### Database connection errors
+
+If services fail with "password authentication failed", the database volume was created with different credentials. Reset it:
+
+\`\`\`bash
+${run} docker:reset
+${run} db:migrate
+\`\`\`
+
+> **Note:** This deletes all data. For production, back up first.
+
+### Services not starting
+
+Check logs for specific errors:
+
+\`\`\`bash
+${run} docker:logs
+\`\`\`
+
+### Port conflicts
+
+If ports 5173, 3000, 3001, or 8000 are in use, stop conflicting services or modify \`docker-compose.yml\`.
+
+## Learn More
+
+- [Supabase Documentation](https://supabase.com/docs)
+- [Hono Documentation](https://hono.dev)
+- [Vite Documentation](https://vitejs.dev)
+`;
+
+  return readme.trim();
+}
+
+// ============================================================================
+// RUN FUNCTION (called by CLI entry point)
+// ============================================================================
+
+export async function run(args) {
+  await bootstrap(args);
+}
+
+// ============================================================================
+// EXPORTS FOR TESTING
+// ============================================================================
+
+export {
+  bootstrap,
+  checkPackageManagerVersion,
+  copyTemplate,
+  copyTemplateDir,
+  detectPackageManager,
+  generateEnvLocal,
+  generateJWT,
+  generatePassword,
+  generateReadme,
+  getInstallCommand,
+  getPackageManagerVersion,
+  isCI,
+  PLACEHOLDERS,
+  RECOMMENDED_VERSIONS,
+  runCommand,
+  SPEC,
+  TEMPLATE_DIR,
+  VERSION,
+  validatePlaceholders,
+};