create-pracht 0.2.6 → 0.4.0

package/src/index.js

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { copyFile, mkdir, readdir, stat, symlink, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, stat, symlink, writeFile } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 
 export class ValidationError extends Error {
   constructor(message) {
@@ -18,7 +19,9 @@ const FALLBACK_VERSION_RANGES = {
   "@pracht/cli": "^1.3.1",
   "@pracht/core": "^0.5.0",
   "@pracht/vite-plugin": "^0.3.2",
-  vercel: "latest",
+  "@tailwindcss/vite": "^4.1.0",
+  tailwindcss: "^4.1.0",
+  vercel: "^56.5.0",
 };
 
 async function fetchLatestVersion(packageName) {
@@ -56,6 +59,12 @@ const ADAPTERS = {
 
 const DEFAULT_DIRECTORY = "pracht-app";
 
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+// The published package bundles a copy of the repo skills (see
+// scripts/sync-skills.js); inside the monorepo we fall back to the source.
+const SKILL_DIRS = [resolve(PACKAGE_ROOT, "skills"), resolve(PACKAGE_ROOT, "../../skills")];
+
 export async function run(argv = process.argv.slice(2)) {
   const options = parseArgs(argv);
   const packageManager = getPackageManager();
@@ -68,12 +77,22 @@ export async function run(argv = process.argv.slice(2)) {
   const dir = options.dir ?? (options.yes ? DEFAULT_DIRECTORY : null);
   const adapterId = options.adapter ?? (options.yes ? "node" : null);
   const router = options.router ?? (options.yes ? "manifest" : null);
+  const tailwind = options.tailwind ?? (options.yes ? false : null);
+  const agentTools = options.agentTools ?? (options.yes ? true : null);
 
   let resolvedDir = dir;
   let resolvedAdapter = adapterId;
   let resolvedRouter = router;
+  let resolvedTailwind = tailwind;
+  let resolvedAgentTools = agentTools;
 
-  if (resolvedDir == null || resolvedAdapter == null || resolvedRouter == null) {
+  if (
+    resolvedDir == null ||
+    resolvedAdapter == null ||
+    resolvedRouter == null ||
+    resolvedTailwind == null ||
+    resolvedAgentTools == null
+  ) {
     const readline = createInterface({
       input: process.stdin,
       output: process.stdout,
@@ -83,6 +102,8 @@ export async function run(argv = process.argv.slice(2)) {
       resolvedDir = resolvedDir ?? (await promptForDirectory(readline));
       resolvedAdapter = resolvedAdapter ?? (await promptForAdapter(readline));
       resolvedRouter = resolvedRouter ?? (await promptForRouter(readline));
+      resolvedTailwind = resolvedTailwind ?? (await promptForTailwind(readline));
+      resolvedAgentTools = resolvedAgentTools ?? (await promptForAgentTools(readline));
     } finally {
       readline.close();
     }
@@ -95,10 +116,12 @@ export async function run(argv = process.argv.slice(2)) {
   if (options.dryRun) {
     const files = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
+      agentTools: resolvedAgentTools,
       packageManager,
       projectName: toPackageName(basename(targetDir)),
       resolveRemoteVersions: false,
       router: resolvedRouter,
+      tailwind: resolvedTailwind,
     });
 
     const fileList = Object.keys(files).sort();
@@ -107,10 +130,12 @@ export async function run(argv = process.argv.slice(2)) {
       console.log(
         JSON.stringify({
           adapter: resolvedAdapter,
+          agentTools: resolvedAgentTools,
           directory: resolvedDir,
           dryRun: true,
           files: fileList,
           router: resolvedRouter,
+          tailwind: resolvedTailwind,
         }),
       );
     } else {
@@ -126,8 +151,10 @@ export async function run(argv = process.argv.slice(2)) {
 
   await scaffoldProject({
     adapter: ADAPTERS[resolvedAdapter],
+    agentTools: resolvedAgentTools,
     packageManager,
     router: resolvedRouter,
+    tailwind: resolvedTailwind,
     targetDir,
   });
 
@@ -138,22 +165,44 @@ export async function run(argv = process.argv.slice(2)) {
     installSucceeded = await installDependencies(targetDir, packageManager);
   }
 
+  let gitInitialized = false;
+  if (options.git) {
+    const gitResult = await initGitRepository(targetDir);
+    gitInitialized = gitResult.initialized;
+
+    if (gitResult.initialized) {
+      log("");
+      log("Initialized a git repository with an initial commit.");
+    } else if (gitResult.reason === "existing-repo") {
+      log("");
+      log("Skipped git init — the target directory is already inside a git repository.");
+    } else if (gitResult.reason === "git-not-found") {
+      log("");
+      log("Skipped git init — git is not available on this machine.");
+    }
+  }
+
   if (options.json) {
     const files = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
+      agentTools: resolvedAgentTools,
       packageManager,
       projectName: toPackageName(basename(targetDir)),
       resolveRemoteVersions: false,
       router: resolvedRouter,
+      tailwind: resolvedTailwind,
     });
 
     console.log(
       JSON.stringify({
         adapter: resolvedAdapter,
+        agentTools: resolvedAgentTools,
         directory: resolvedDir,
         files: Object.keys(files).sort(),
+        gitInitialized,
         installed: options.skipInstall ? false : installSucceeded,
         router: resolvedRouter,
+        tailwind: resolvedTailwind,
       }),
     );
   } else {
@@ -167,13 +216,24 @@ export async function run(argv = process.argv.slice(2)) {
   }
 }
 
-export async function scaffoldProject({ adapter, packageManager, router = "manifest", targetDir }) {
+export async function scaffoldProject({
+  adapter,
+  agentTools = true,
+  packageManager,
+  resolveRemoteVersions = true,
+  router = "manifest",
+  tailwind = false,
+  targetDir,
+}) {
   const packageName = toPackageName(basename(targetDir));
   const files = await buildProjectFiles({
     adapter,
+    agentTools,
     packageManager,
     projectName: packageName,
+    resolveRemoteVersions,
     router,
+    tailwind,
   });
 
   await mkdir(targetDir, { recursive: true });
@@ -205,11 +265,14 @@ export function getPackageManager(userAgent = process.env.npm_config_user_agent
 export function parseArgs(argv) {
   const options = {
     adapter: undefined,
+    agentTools: undefined,
     dir: undefined,
     dryRun: false,
+    git: true,
     json: false,
     router: undefined,
     skipInstall: false,
+    tailwind: undefined,
     yes: false,
   };
 
@@ -219,6 +282,42 @@ export function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--tailwind") {
+      options.tailwind = true;
+      continue;
+    }
+
+    if (arg === "--no-tailwind") {
+      options.tailwind = false;
+      continue;
+    }
+
+    if (arg === "--no-git") {
+      options.git = false;
+      continue;
+    }
+
+    if (arg === "--agent-tools") {
+      options.agentTools = true;
+      continue;
+    }
+
+    if (arg === "--no-agent-tools") {
+      options.agentTools = false;
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      const value = normalizeTemplate(arg.slice("--template=".length));
+      if (!value) {
+        throw new ValidationError(
+          `Invalid template: ${arg.slice("--template=".length)}. Use minimal or tailwind.`,
+        );
+      }
+      options.tailwind = value === "tailwind";
+      continue;
+    }
+
     if (arg === "--yes" || arg === "-y") {
       options.yes = true;
       continue;
@@ -322,6 +421,46 @@ async function promptForRouter(readline) {
   }
 }
 
+async function promptForTailwind(readline) {
+  while (true) {
+    const answer = await readline.question("Use Tailwind CSS? (y/N): ");
+    const normalized = normalizeYesNo(answer.trim() || "no");
+
+    if (normalized != null) {
+      return normalized;
+    }
+
+    console.log("Answer y/yes or n/no.");
+  }
+}
+
+async function promptForAgentTools(readline) {
+  while (true) {
+    const answer = await readline.question("Set up Claude Code skills + MCP? (Y/n): ");
+    const normalized = normalizeYesNo(answer.trim() || "yes");
+
+    if (normalized != null) {
+      return normalized;
+    }
+
+    console.log("Answer y/yes or n/no.");
+  }
+}
+
+function normalizeYesNo(value) {
+  const normalized = value.toLowerCase();
+
+  if (normalized === "y" || normalized === "yes") {
+    return true;
+  }
+
+  if (normalized === "n" || normalized === "no") {
+    return false;
+  }
+
+  return null;
+}
+
 async function ensureTargetDirectory(targetDir) {
   const error = await validateTargetDirectory(targetDir);
 
@@ -348,6 +487,20 @@ async function validateTargetDirectory(targetDir) {
   return null;
 }
 
+function normalizeTemplate(value) {
+  const normalized = value.toLowerCase();
+
+  if (normalized === "minimal") {
+    return "minimal";
+  }
+
+  if (normalized === "tailwind") {
+    return "tailwind";
+  }
+
+  return null;
+}
+
 function normalizeRouter(value) {
   const normalized = value.toLowerCase();
 
@@ -402,10 +555,12 @@ async function resolveVersions(packageNames, { remote = true } = {}) {
 
 async function buildProjectFiles({
   adapter,
+  agentTools = true,
   packageManager,
   projectName,
   resolveRemoteVersions = true,
   router,
+  tailwind = false,
 }) {
   const packagesToResolve = [
     "@pracht/cli",
@@ -416,26 +571,41 @@ async function buildProjectFiles({
   if (adapter.id === "vercel") {
     packagesToResolve.push("vercel");
   }
+  if (tailwind) {
+    packagesToResolve.push("tailwindcss", "@tailwindcss/vite");
+  }
 
   const versions = await resolveVersions(packagesToResolve, { remote: resolveRemoteVersions });
 
   const files = {
-    ".gitignore": "dist\nnode_modules\n.wrangler\n.vercel\n.env*\n!.env.example\n.dev.vars\n",
-    "README.md": createReadme({ adapter, packageManager, projectName, router }),
-    "package.json": createPackageJson({ adapter, projectName, versions }),
+    ".gitignore":
+      "dist\nnode_modules\n.wrangler\n.vercel\n.env*\n!.env.example\n.dev.vars\n# Keep .pracht/app-graph.json committed — it is the `pracht plan` snapshot.\n",
+    "README.md": createReadme({
+      adapter,
+      agentTools,
+      packageManager,
+      projectName,
+      router,
+      tailwind,
+    }),
+    "package.json": createPackageJson({ adapter, projectName, tailwind, versions }),
     "src/api/health.ts": createHealthRoute(adapter),
-    "vite.config.ts": createViteConfig(adapter, router),
+    "vite.config.ts": createViteConfig(adapter, router, tailwind),
     "tsconfig.json": createBaseTSConfig(adapter),
-    "AGENTS.md": createAgentInstructions({ adapter, packageManager, router }),
+    "AGENTS.md": createAgentInstructions({ adapter, agentTools, packageManager, router, tailwind }),
   };
 
   if (router === "pages") {
-    files["src/pages/_app.tsx"] = createShellFile(projectName);
+    files["src/pages/_app.tsx"] = createShellFile(projectName, tailwind);
     files["src/pages/index.tsx"] = createPagesHomeRoute(adapter);
   } else {
     files["src/routes.ts"] = createRoutesFile();
     files["src/routes/home.tsx"] = createHomeRoute(adapter);
-    files["src/shells/public.tsx"] = createShellFile(projectName);
+    files["src/shells/public.tsx"] = createShellFile(projectName, tailwind);
+  }
+
+  if (tailwind) {
+    files["src/styles/global.css"] = '@import "tailwindcss";\n';
   }
 
   if (adapter.id === "cloudflare") {
@@ -443,16 +613,61 @@ async function buildProjectFiles({
     files["src/env.d.ts"] = createCloudflareEnvDeclaration();
   }
 
+  if (adapter.id === "node") {
+    files["Dockerfile"] = createDockerfile(packageManager);
+    files[".dockerignore"] = createDockerignore();
+  }
+
+  if (agentTools) {
+    files[".mcp.json"] = createMcpConfig();
+    Object.assign(files, await readSkillFiles());
+  }
+
   return files;
 }
 
-function createPackageJson({ adapter, projectName, versions }) {
+function createMcpConfig() {
+  return `${JSON.stringify(
+    {
+      mcpServers: {
+        pracht: {
+          command: "npx",
+          args: ["pracht", "mcp"],
+        },
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+async function readSkillFiles() {
+  const skillsDir = SKILL_DIRS.find((dir) => existsSync(dir));
+
+  if (!skillsDir) {
+    return {};
+  }
+
+  const files = {};
+  for (const name of await readdir(skillsDir)) {
+    const skillFile = resolve(skillsDir, name, "SKILL.md");
+    if (!existsSync(skillFile)) {
+      continue;
+    }
+    files[`.claude/skills/${name}/SKILL.md`] = await readFile(skillFile, "utf-8");
+  }
+
+  return files;
+}
+
+function createPackageJson({ adapter, projectName, tailwind, versions }) {
   const scripts = {
     build: "pracht build",
     dev: "pracht dev",
   };
 
   if (adapter.id === "node") {
+    scripts.preview = "pracht preview";
     scripts.start = "node dist/server/server.js";
   }
 
@@ -466,6 +681,7 @@ function createPackageJson({ adapter, projectName, versions }) {
 
   if (adapter.id === "cloudflare") {
     scripts.deploy = "pracht build && wrangler deploy";
+    scripts.preview = "pracht preview";
     devDependencies.wrangler = "^4.81.0";
   }
 
@@ -474,6 +690,11 @@ function createPackageJson({ adapter, projectName, versions }) {
     devDependencies.vercel = versions["vercel"];
   }
 
+  if (tailwind) {
+    devDependencies["@tailwindcss/vite"] = versions["@tailwindcss/vite"];
+    devDependencies.tailwindcss = versions["tailwindcss"];
+  }
+
   return `${JSON.stringify(
     {
       dependencies: {
@@ -492,7 +713,7 @@ function createPackageJson({ adapter, projectName, versions }) {
   )}\n`;
 }
 
-function createViteConfig(adapter, router) {
+function createViteConfig(adapter, router, tailwind) {
   const ADAPTER_IMPORTS = {
     node: { fn: "nodeAdapter", pkg: "@pracht/adapter-node" },
     cloudflare: { fn: "cloudflareAdapter", pkg: "@pracht/adapter-cloudflare" },
@@ -506,16 +727,23 @@ function createViteConfig(adapter, router) {
       ? `{ pagesDir: "/src/pages", adapter: ${info.fn}() }`
       : `{ adapter: ${info.fn}() }`;
 
-  return [
+  const plugins = tailwind
+    ? `[pracht(${prachtOptions}), tailwindcss()]`
+    : `[pracht(${prachtOptions})]`;
+
+  const lines = [
     'import { defineConfig } from "vite";',
     'import { pracht } from "@pracht/vite-plugin";',
     `import { ${info.fn} } from "${info.pkg}";`,
-    "",
-    "export default defineConfig({",
-    `  plugins: [pracht(${prachtOptions})],`,
-    "});",
-    "",
-  ].join("\n");
+  ];
+
+  if (tailwind) {
+    lines.push('import tailwindcss from "@tailwindcss/vite";');
+  }
+
+  lines.push("", "export default defineConfig({", `  plugins: ${plugins},`, "});", "");
+
+  return lines.join("\n");
 }
 
 function createRoutesFile() {
@@ -529,14 +757,27 @@ function createRoutesFile() {
     "  routes: [",
     '    route("/", "./routes/home.tsx", { id: "home", render: "ssg", shell: "public" }),',
     "  ],",
+    "  // Custom 404 page — any module in ./routes, rendered when nothing matches:",
+    '  // notFound: "./routes/not-found.tsx",',
+    "  // Declarative invariants enforced by `pracht verify` — uncomment to use",
+    "  // (add the helpers to the @pracht/core import):",
+    "  // constraints: [",
+    '  //   requireHead("**"),',
+    "  // ],",
     "});",
     "",
   ].join("\n");
 }
 
-function createShellFile(projectName) {
+function createShellFile(projectName, tailwind = false) {
+  const lines = ['import type { ShellProps } from "@pracht/core";'];
+
+  if (tailwind) {
+    lines.push('import "../styles/global.css";');
+  }
+
   return [
-    'import type { ShellProps } from "@pracht/core";',
+    ...lines,
     "",
     "export function Shell({ children }: ShellProps) {",
     "  return (",
@@ -705,7 +946,80 @@ function createCloudflareEnvDeclaration() {
   ].join("\n");
 }
 
-function createAgentInstructions({ adapter, packageManager, router }) {
+function createDockerfile(packageManager) {
+  const COMMANDS = {
+    npm: {
+      build: "npm run build",
+      install: "npm install",
+      lockfile: "package-lock.json*",
+      prune: "npm prune --omit=dev",
+      setup: null,
+    },
+    pnpm: {
+      build: "pnpm build",
+      install: "pnpm install",
+      lockfile: "pnpm-lock.yaml*",
+      prune: "pnpm prune --prod",
+      setup: "corepack enable pnpm",
+    },
+    yarn: {
+      build: "yarn build",
+      install: "yarn install",
+      lockfile: "yarn.lock*",
+      prune: "yarn install --production --ignore-scripts --prefer-offline",
+      setup: "corepack enable yarn",
+    },
+  };
+
+  // The runtime image ships Node.js, so bun scaffolds fall back to npm inside Docker.
+  const commands = COMMANDS[packageManager] ?? COMMANDS.npm;
+
+  const lines = ["# syntax=docker/dockerfile:1", "", "FROM node:22-alpine AS base", "WORKDIR /app"];
+
+  if (commands.setup) {
+    lines.push(`RUN ${commands.setup}`);
+  }
+
+  lines.push(
+    "",
+    "FROM base AS deps",
+    `COPY package.json ${commands.lockfile} ./`,
+    `RUN ${commands.install}`,
+    "",
+    "FROM deps AS build",
+    "COPY . .",
+    `RUN ${commands.build}`,
+    `RUN ${commands.prune}`,
+    "",
+    "FROM node:22-alpine AS runtime",
+    "WORKDIR /app",
+    "ENV NODE_ENV=production",
+    "ENV PORT=3000",
+    "COPY --from=build /app/package.json ./package.json",
+    "COPY --from=build /app/node_modules ./node_modules",
+    "COPY --from=build /app/dist ./dist",
+    "EXPOSE 3000",
+    'CMD ["node", "dist/server/server.js"]',
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+function createDockerignore() {
+  return [
+    "node_modules",
+    "dist",
+    ".git",
+    ".env*",
+    "!.env.example",
+    "Dockerfile",
+    ".dockerignore",
+    "",
+  ].join("\n");
+}
+
+function createAgentInstructions({ adapter, agentTools, packageManager, router, tailwind }) {
   const runCmd = packageManager === "npm" ? "npm run" : packageManager;
 
   const lines = [
@@ -717,6 +1031,10 @@ function createAgentInstructions({ adapter, packageManager, router }) {
     `- \`${runCmd} build\` — production build`,
   ];
 
+  if (adapter.id === "node" || adapter.id === "cloudflare") {
+    lines.push(`- \`${runCmd} preview\` — build and serve the production build locally`);
+  }
+
   if (adapter.id === "node") {
     lines.push(`- \`${runCmd} start\` — run the built server`);
   }
@@ -735,6 +1053,12 @@ function createAgentInstructions({ adapter, packageManager, router }) {
   lines.push("- `pracht generate middleware --name auth` — add middleware");
   lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
   lines.push("- `pracht doctor` — check project health");
+  lines.push("- `pracht verify` — enforce route and constraint invariants");
+  lines.push(
+    "- `pracht plan --write` — refresh the committed `.pracht/app-graph.json` snapshot after route changes",
+  );
+  lines.push("- `pracht report` — PR-ready markdown summary (plan diff, verify, budgets)");
+  lines.push("- `pracht llms --write` — write an `llms.txt` authoring guide for coding agents");
 
   lines.push("");
   lines.push("## Project structure");
@@ -756,19 +1080,40 @@ function createAgentInstructions({ adapter, packageManager, router }) {
   lines.push("- `src/api/` — API route handlers");
   lines.push(`- \`vite.config.ts\` — Vite config with the ${adapter.label} adapter`);
 
+  if (tailwind) {
+    lines.push("- `src/styles/global.css` — Tailwind CSS entry stylesheet, imported by the shell");
+  }
+
+  if (adapter.id === "node") {
+    lines.push("- `Dockerfile` — multi-stage container build that runs the built server");
+  }
+
   if (adapter.id === "cloudflare") {
     lines.push("- `wrangler.jsonc` — Cloudflare Workers configuration");
     lines.push("- `src/env.d.ts` — TypeScript types for Cloudflare bindings");
   }
 
+  if (agentTools) {
+    lines.push("");
+    lines.push("## Agent tooling");
+    lines.push("");
+    lines.push(
+      "- `.claude/skills/` — pracht Claude Code skills (audits, scaffolds, testing, debugging); invoke with `/<skill-name>`",
+    );
+    lines.push(
+      "- `.mcp.json` — registers the `pracht mcp` server so MCP clients can inspect the app graph, run doctor/verify, and scaffold natively",
+    );
+  }
+
   lines.push("");
 
   return lines.join("\n");
 }
 
-function createReadme({ adapter, packageManager, projectName, router }) {
+function createReadme({ adapter, agentTools, packageManager, projectName, router, tailwind }) {
   const installCommand = packageManager === "npm" ? "npm install" : `${packageManager} install`;
   const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
+  const previewCommand = packageManager === "npm" ? "npm run preview" : `${packageManager} preview`;
   const startCommand = packageManager === "npm" ? "npm run start" : `${packageManager} start`;
   const deployCommand = packageManager === "npm" ? "npm run deploy" : `${packageManager} deploy`;
 
@@ -784,10 +1129,12 @@ function createReadme({ adapter, packageManager, projectName, router }) {
   ];
 
   if (adapter.id === "node") {
+    lines.push(`- \`${previewCommand}\``);
     lines.push(`- \`${startCommand}\``);
   }
 
   if (adapter.id === "cloudflare") {
+    lines.push(`- \`${previewCommand}\``);
     lines.push(`- \`${deployCommand}\``);
     lines.push("");
     lines.push(
@@ -816,9 +1163,98 @@ function createReadme({ adapter, packageManager, projectName, router }) {
 
   lines.push("- `src/api/health.ts` is a sample API route.");
 
+  if (tailwind) {
+    lines.push("- `src/styles/global.css` is the Tailwind CSS entry, imported by the shell.");
+  }
+
+  if (agentTools) {
+    lines.push(
+      "- `.claude/skills/` and `.mcp.json` wire up the pracht Claude Code skills and MCP server.",
+    );
+  }
+
+  lines.push("");
+  lines.push("## Checks");
+  lines.push("");
+  lines.push(
+    router === "pages"
+      ? "- `pracht verify` validates routes."
+      : "- `pracht verify` validates routes and constraints.",
+  );
+  lines.push(
+    "- `pracht plan --write` commits an app-graph snapshot to `.pracht/`; `pracht plan` diffs against it.",
+  );
+  lines.push("- `pracht report` prints a PR-ready summary of both.");
+
+  if (adapter.id === "node") {
+    lines.push("");
+    lines.push("## Docker");
+    lines.push("");
+    lines.push("A multi-stage `Dockerfile` builds the app and runs the Node server:");
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`docker build -t ${projectName} .`);
+    lines.push(`docker run -p 3000:3000 ${projectName}`);
+    lines.push("```");
+  }
+
   return `${lines.join("\n")}\n`;
 }
 
+export async function initGitRepository(targetDir) {
+  if (!(await execCommand("git", ["--version"]))) {
+    return { initialized: false, reason: "git-not-found" };
+  }
+
+  if (await execCommand("git", ["rev-parse", "--is-inside-work-tree"], targetDir)) {
+    return { initialized: false, reason: "existing-repo" };
+  }
+
+  if (!(await execCommand("git", ["init"], targetDir))) {
+    return { initialized: false, reason: "init-failed" };
+  }
+
+  if (!(await execCommand("git", ["add", "-A"], targetDir))) {
+    return { initialized: false, reason: "commit-failed" };
+  }
+
+  // Fall back to a scoped identity when the user has no git identity configured,
+  // so the initial commit still succeeds (e.g. on fresh machines or CI).
+  const hasIdentity = await execCommand("git", ["config", "user.email"], targetDir);
+  const identityArgs = hasIdentity
+    ? []
+    : ["-c", "user.name=create-pracht", "-c", "user.email=create-pracht@localhost"];
+
+  const committed = await execCommand(
+    "git",
+    [...identityArgs, "commit", "-m", "Initial commit from create-pracht"],
+    targetDir,
+  );
+
+  if (!committed) {
+    return { initialized: false, reason: "commit-failed" };
+  }
+
+  return { initialized: true };
+}
+
+function execCommand(command, args, cwd) {
+  return new Promise((resolveExec) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "ignore",
+    });
+
+    child.on("close", (code) => {
+      resolveExec(code === 0);
+    });
+
+    child.on("error", () => {
+      resolveExec(false);
+    });
+  });
+}
+
 async function installDependencies(targetDir, packageManager) {
   const args = packageManager === "yarn" ? ["install"] : ["install"];
 
@@ -868,13 +1304,18 @@ Usage:
   create-pracht [directory] [options]
 
 Options:
-  --adapter=node|cf|vercel   Choose hosting adapter (default: node)
-  --router=manifest|pages    Choose routing system (default: manifest)
-  --skip-install             Skip dependency installation
-  --yes, -y                  Accept defaults, skip all prompts
-  --json                     Output JSON summary instead of prose
-  --dry-run                  Show which files would be created without writing
-  -h, --help                 Show this help message
+  --adapter=node|cf|vercel     Choose hosting adapter (default: node)
+  --router=manifest|pages      Choose routing system (default: manifest)
+  --template=minimal|tailwind  Choose starter template (minimal, or minimal + Tailwind CSS)
+  --tailwind / --no-tailwind   Enable or disable Tailwind CSS wiring (default: prompt)
+  --agent-tools / --no-agent-tools
+                               Seed Claude Code skills and a pracht MCP config (default: prompt, yes)
+  --no-git                     Skip git init and the initial commit
+  --skip-install               Skip dependency installation
+  --yes, -y                    Accept defaults, skip all prompts
+  --json                       Output JSON summary instead of prose
+  --dry-run                    Show which files would be created without writing
+  -h, --help                   Show this help message
 `);
 }