create-patties 0.0.6 → 0.0.9

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# create-patties
+
+## 0.0.8
+
+### Patch Changes
+
+- 3b3f80d: Scaffolder DX overhaul (specs 09 + 10).
+
+  - **Tool probes** — fail fast with a clear message when `bun` is missing
+    from PATH; skip-and-warn when `git` is missing instead of silently
+    swallowing failures.
+  - **Interactive prompts** — when stdin is a TTY and flags were not passed,
+    prompt for project name, target, deploy, and agent. Add `--yes` / `-y`
+    to accept all defaults non-interactively.
+  - **`--agent` alias** — the spec-05 `--agent claude-code` form is kept as
+    a backwards-compatible alias for `--template claude`.
+  - **Expanded agent overlays** — `_claude` now ships
+    `.claude/settings.json` (with `bun`/`bunx`/`patties` permissions and a
+    Biome PostToolUse hook), `.claude/hooks/biome-check.sh` (no-ops when
+    Biome is not installed), and empty `.claude/agents/` /
+    `.claude/commands/` directories with README pointers. `_codex` now
+    ships a `.codex/README.md`.
+  - **Templated README** — `templates/default/README-template.md` is now a
+    real onboarding doc with `{{name}}` / `{{agent}}` / `{{target}}` /
+    `{{deploy}}` placeholders and HTML-comment conditional blocks. A
+    generic templating pass also interpolates `{{name}}` into CLAUDE.md
+    and AGENTS.md.
+
+  - **Todo demo template** — the default scaffold now ships a `TodoApp.tsx`
+    island and a route that mounts it. The README explains that buttons
+    don't react under `bun dev` today (dev hydration lands with framework
+    spec 18) and tells the user to `bun run build && bun start` to see the
+    island work; it also includes a "Remove the demo" section for when the
+    user is ready to start their real app.
+  - **`--blank` flag** — `bunx create-patties@latest <name> --blank`
+    (alias: `--empty`) scaffolds a hello-world page with no demo and no
+    `app/islands/` directory.
+  - **Demo prompt** — interactive flow asks "Include the interactive
+    todo demo? [Y/n]" right after the agent question.
+  - **Git is now opt-in** — `git init` no longer runs by default. Pass
+    `--git` to opt in. The success output reminds the user how to
+    initialise a repo when they're ready. `--no-git` is kept as a no-op
+    for back-compat.
+  - **`_claude` overlay restructured.** The empty `.claude/agents/` and
+    `.claude/commands/` placeholders are gone. Replaced with:
+    - `.claude/skills/patties-cli/SKILL.md` — a real skill teaching
+      Claude how to use the project CLI (`patties dev/build/start/deploy/secret`).
+    - `.claude/rules/` — scaffolded meta-framework knowledge:
+      `bun-native.md`, `web-standards-boundary.md`,
+      `filesystem-routing.md`, `islands.md`, `build-time-discovery.md`,
+      `optional-ai.md`. Mirrors the framework's own rules but tuned
+      for users of the framework.

package/README.md

@@ -0,0 +1,53 @@
+# create-patties
+
+The official scaffolder for [Patties](https://github.com/bihaviour-ai/bun-patties-framework) —
+a Bun-native full-stack meta-framework with React 19 rendering.
+
+```sh
+bunx create-patties@latest my-app
+```
+
+Runs an interactive prompt (project name, agent overlay, demo template,
+runtime target, deploy target), then scaffolds, installs, and gets you
+to `bun dev` in one shot.
+
+## Options
+
+```sh
+bunx create-patties@latest my-app \
+  --template claude|codex|none \
+  --target   bun|edge \
+  --deploy   cloudflare|vercel|deno|netlify|bun|none \
+  --blank \
+  --git \
+  --no-install \
+  --yes
+```
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--template` | `claude` | Agent-platform overlay (`claude`, `codex`, or `none`). |
+| `--target` | `bun` | Runtime target written into `patties.config.ts`. |
+| `--deploy` | `none` | Records the intended deploy target. |
+| `--blank` / `--empty` | off | Skip the interactive todo demo; ship a hello-world page. |
+| `--git` | off | Run `git init` + initial commit (opt-in). |
+| `--no-install` | off | Skip `bun install`. |
+| `--yes` / `-y` | off | Accept all defaults; skip prompts. |
+
+`--agent claude-code` is retained as a back-compat alias for
+`--template claude`.
+
+## What you get
+
+A minimal Patties app with filesystem routing under `app/routes/`,
+optional client islands under `app/islands/`, and either the `_claude`
+or `_codex` agent overlay scaffolding conventions for your chosen
+coding agent.
+
+See [the Patties docs](https://bun-patties.com) for the full framework
+guide.
+
+## Requires
+
+Bun 1.0+. `bunx create-patties@latest` won't work under Node — install
+Bun first from [bun.sh](https://bun.sh).

package/bin/create-patties.ts

@@ -1,5 +1,13 @@
 #!/usr/bin/env bun
-import { run } from "../src/index.ts";
+export {};
 
+if (typeof Bun === "undefined") {
+	console.error(
+		"create-patties requires Bun. Install Bun first: https://bun.sh",
+	);
+	process.exit(1);
+}
+
+const { run } = await import("../src/index.ts");
 const code = await run(process.argv.slice(2));
 process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-patties",
-	"version": "0.0.6",
+	"version": "0.0.9",
 	"type": "module",
 	"description": "Scaffolder for new Patties projects.",
 	"bin": {
@@ -13,6 +13,15 @@
 		"bin",
 		"src",
 		"templates",
-		"README.md"
-	]
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check ."
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	}
 }

package/src/index.ts

@@ -1,15 +1,56 @@
 import { existsSync, readdirSync } from "node:fs";
 import { dirname, isAbsolute, resolve } from "node:path";
+import { hasGit, probeTools } from "./probes.ts";
+import {
+	type AgentTemplate,
+	isInteractive,
+	promptAgent,
+	promptDeploy,
+	promptName,
+	promptScaffold,
+	promptTarget,
+} from "./prompts.ts";
+import { renderTemplatesInTree } from "./readme.ts";
 
-type AgentTemplate = "claude" | "codex" | "none";
+// Step logger — visible progress so the user can see what scaffolding does.
+// Honors NO_COLOR; degrades gracefully on non-TTY streams.
+function colorOn(): boolean {
+	if (process.env.NO_COLOR) return false;
+	return Boolean((process.stdout as NodeJS.WriteStream).isTTY);
+}
+const COL = colorOn();
+const c = {
+	dim: (s: string) => (COL ? `\x1b[2m${s}\x1b[0m` : s),
+	green: (s: string) => (COL ? `\x1b[32m${s}\x1b[0m` : s),
+	cyan: (s: string) => (COL ? `\x1b[36m${s}\x1b[0m` : s),
+	bold: (s: string) => (COL ? `\x1b[1m${s}\x1b[0m` : s),
+};
+function step(msg: string): void {
+	process.stdout.write(`  ${c.green("✓")} ${msg}\n`);
+}
+function pending(msg: string): void {
+	process.stdout.write(`  ${c.dim("…")} ${msg}\n`);
+}
+function header(msg: string): void {
+	process.stdout.write(`\n${c.bold(c.cyan("▲"))} ${msg}\n\n`);
+}
+function fmtMs(ms: number): string {
+	return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
 
 interface Args {
 	name?: string;
 	template: AgentTemplate;
+	templateExplicit: boolean;
 	target: "bun" | "edge";
+	targetExplicit: boolean;
 	deploy: "cloudflare" | "vercel" | "deno" | "netlify" | "bun" | "none";
+	deployExplicit: boolean;
 	install: boolean;
 	git: boolean;
+	yes: boolean;
+	scaffold: "demo" | "blank";
+	scaffoldExplicit: boolean;
 }
 
 const TEMPLATES_ROOT = resolve(dirname(import.meta.dir), "templates");
@@ -18,10 +59,19 @@ const VALID_TEMPLATES: AgentTemplate[] = ["claude", "codex", "none"];
 
 export async function run(argv: string[]): Promise<number> {
 	const args = parseArgs(argv);
+	const interactive = !args.yes && isInteractive();
 
 	if (!args.name) {
-		printUsage();
-		return 2;
+		if (interactive) {
+			args.name = promptName(undefined, isValidName);
+			if (!args.name) {
+				stderr("✗ failed to read a valid project name");
+				return 2;
+			}
+		} else {
+			printUsage();
+			return 2;
+		}
 	}
 
 	if (!isValidName(args.name)) {
@@ -29,6 +79,15 @@ export async function run(argv: string[]): Promise<number> {
 		return 2;
 	}
 
+	if (interactive) {
+		if (!args.templateExplicit) args.template = promptAgent();
+		if (!args.scaffoldExplicit) args.scaffold = promptScaffold();
+		if (!args.targetExplicit) args.target = promptTarget();
+		if (args.target === "edge" && !args.deployExplicit) {
+			args.deploy = promptDeploy();
+		}
+	}
+
 	if (!VALID_TEMPLATES.includes(args.template)) {
 		stderr(
 			`✗ unknown --template "${args.template}" (expected: ${VALID_TEMPLATES.join(", ")})`,
@@ -51,36 +110,84 @@ export async function run(argv: string[]): Promise<number> {
 		return 1;
 	}
 
+	probeTools();
+
+	header(`create-patties — scaffolding ${c.bold(args.name)}`);
+
 	await Bun.$`mkdir -p ${targetDir}`.quiet();
+	step(`created directory ${c.dim(targetDir)}`);
+
 	await Bun.$`cp -R ${baseDir}/. ${targetDir}`.quiet();
+	step(`copied base template ${c.dim("(default)")}`);
 
 	await renameTemplateFiles(targetDir);
 	await writePackageJson(targetDir, args.name);
+	step(`wrote package.json ${c.dim(`(name: ${args.name})`)}`);
 	await patchPattiesConfig(targetDir, args);
+	step(`patched patties.config.ts ${c.dim(`(target: ${args.target})`)}`);
 
 	if (args.template !== "none") {
 		const overlay = resolve(TEMPLATES_ROOT, `_${args.template}`);
 		if (existsSync(overlay)) {
 			await Bun.$`cp -R ${overlay}/. ${targetDir}`.quiet();
+			step(`applied agent overlay ${c.dim(`(${args.template})`)}`);
 		}
 	}
 
+	if (args.scaffold === "blank") {
+		await applyBlankScaffold(targetDir);
+		step("applied blank scaffold (no demo)");
+	} else {
+		step("included interactive todo demo");
+	}
+
+	await renderTemplatesInTree(targetDir, {
+		name: args.name,
+		agent: args.template,
+		target: args.target,
+		deploy: args.deploy,
+		scaffold: args.scaffold,
+	});
+	step("rendered template variables (README, AGENTS.md, …)");
+
 	if (args.install) {
-		await Bun.$`bun install`.cwd(targetDir).quiet().nothrow();
+		pending("installing dependencies (bun install)…");
+		const t0 = performance.now();
+		const proc = await Bun.$`bun install`.cwd(targetDir).quiet().nothrow();
+		const dt = performance.now() - t0;
+		if (proc.exitCode === 0) {
+			step(`installed dependencies ${c.dim(`(${fmtMs(dt)})`)}`);
+		} else {
+			step(
+				`bun install exited with code ${proc.exitCode} — you may need to retry it manually`,
+			);
+		}
+	} else {
+		step(`skipped ${c.dim("`bun install`")} (--no-install)`);
 	}
 
+	let gitSkippedReason: string | undefined;
 	if (args.git) {
-		await Bun.$`git init`.cwd(targetDir).quiet().nothrow();
-		await Bun.$`git add -A`.cwd(targetDir).quiet().nothrow();
-		await Bun.$`git commit -m ${"chore: initial commit from create-patties"}`
-			.cwd(targetDir)
-			.quiet()
-			.nothrow();
+		if (hasGit()) {
+			await Bun.$`git init`.cwd(targetDir).quiet().nothrow();
+			await Bun.$`git add -A`.cwd(targetDir).quiet().nothrow();
+			await Bun.$`git commit -m ${"chore: initial commit from create-patties"}`
+				.cwd(targetDir)
+				.quiet()
+				.nothrow();
+			step("initialized git and committed");
+		} else {
+			gitSkippedReason = "git-missing";
+		}
 	}
 
-	process.stdout.write(
-		`\n✓ created ${args.name}\n\n  cd ${args.name}\n  bun dev\n`,
-	);
+	const nextSteps = args.git
+		? `\n  cd ${args.name}\n  bun dev\n`
+		: `\n  cd ${args.name}\n  bun dev\n\n  # when you're ready to track this in git:\n  git init && git add -A && git commit -m "initial commit"\n`;
+	process.stdout.write(`\n✓ created ${args.name}\n${nextSteps}`);
+	if (gitSkippedReason === "git-missing") {
+		stderr("create-patties: `git` not found — skipping `git init`.");
+	}
 	if (args.template === "claude") {
 		process.stdout.write(
 			"\nClaude Code is configured (CLAUDE.md). Run `claude` in the project to start a session.\n",
@@ -96,30 +203,66 @@ export async function run(argv: string[]): Promise<number> {
 function parseArgs(argv: string[]): Args {
 	const out: Args = {
 		template: "claude",
+		templateExplicit: false,
 		target: "bun",
+		targetExplicit: false,
 		deploy: "none",
+		deployExplicit: false,
 		install: true,
-		git: true,
+		git: false,
+		yes: false,
+		scaffold: "demo",
+		scaffoldExplicit: false,
+	};
+	const setTemplate = (raw: string) => {
+		out.template = aliasTemplate(raw);
+		out.templateExplicit = true;
 	};
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i];
 		if (a === undefined) continue;
-		if (a === "--template") out.template = next(argv, ++i) as AgentTemplate;
-		else if (a.startsWith("--template="))
-			out.template = a.slice(11) as AgentTemplate;
-		else if (a === "--target") out.target = next(argv, ++i) as Args["target"];
-		else if (a.startsWith("--target="))
+		if (a === "--template") setTemplate(next(argv, ++i));
+		else if (a.startsWith("--template=")) setTemplate(a.slice(11));
+		// --agent: spec-05 alias kept for backwards compatibility.
+		else if (a === "--agent") setTemplate(next(argv, ++i));
+		else if (a.startsWith("--agent=")) setTemplate(a.slice(8));
+		else if (a === "--target") {
+			out.target = next(argv, ++i) as Args["target"];
+			out.targetExplicit = true;
+		} else if (a.startsWith("--target=")) {
 			out.target = a.slice(9) as Args["target"];
-		else if (a === "--deploy") out.deploy = next(argv, ++i) as Args["deploy"];
-		else if (a.startsWith("--deploy="))
+			out.targetExplicit = true;
+		} else if (a === "--deploy") {
+			out.deploy = next(argv, ++i) as Args["deploy"];
+			out.deployExplicit = true;
+		} else if (a.startsWith("--deploy=")) {
 			out.deploy = a.slice(9) as Args["deploy"];
-		else if (a === "--no-install") out.install = false;
+			out.deployExplicit = true;
+		} else if (a === "--no-install") out.install = false;
+		else if (a === "--git") out.git = true;
+		// --no-git: kept as a no-op for back-compat. Git is now opt-in
+		// (default off) so most users don't need either flag.
 		else if (a === "--no-git") out.git = false;
-		else if (!out.name && !a.startsWith("-")) out.name = a;
+		else if (a === "--yes" || a === "-y") out.yes = true;
+		else if (a === "--blank" || a === "--empty") {
+			out.scaffold = "blank";
+			out.scaffoldExplicit = true;
+		} else if (a === "--demo") {
+			out.scaffold = "demo";
+			out.scaffoldExplicit = true;
+		} else if (!out.name && !a.startsWith("-")) out.name = a;
 	}
 	return out;
 }
 
+// Translate spec-05 --agent values (claude-code/none) and current --template
+// values (claude/codex/none) into the unified AgentTemplate type.
+function aliasTemplate(raw: string): AgentTemplate {
+	if (raw === "claude-code") return "claude";
+	if (raw === "claude" || raw === "codex" || raw === "none") return raw;
+	return raw as AgentTemplate;
+}
+
 function next(argv: string[], i: number): string {
 	return argv[i] ?? "";
 }
@@ -144,6 +287,28 @@ async function renameTemplateFiles(dir: string): Promise<void> {
 	}
 }
 
+// --blank scaffold: drop the interactive demo and ship a single hello page.
+// We start from the same default template and prune so we keep exactly one
+// source-of-truth for things like patties.config.ts / tsconfig.json.
+async function applyBlankScaffold(dir: string): Promise<void> {
+	await Bun.$`rm -rf ${dir}/app/islands`.quiet();
+	await Bun.write(
+		`${dir}/app/routes/index.tsx`,
+		`export default function Index(): JSX.Element {
+	return (
+		<main>
+			<h1>Hello from {{name}}</h1>
+			<p>
+				This page is server-rendered by Patties. Add more files under{" "}
+				<code>app/routes/</code> to grow your app.
+			</p>
+		</main>
+	);
+}
+`,
+	);
+}
+
 async function writePackageJson(dir: string, name: string): Promise<void> {
 	const pkg = {
 		name,
@@ -202,11 +367,15 @@ Options:
   --target   <bun|edge>             Runtime target (default: bun)
   --deploy   <cloudflare|vercel|deno|netlify|bun|none>
   --no-install                      Skip 'bun install'
-  --no-git                          Skip 'git init'
+  --git                             Run 'git init' + initial commit (opt-in)
+  --yes, -y                         Accept all defaults, skip prompts
+  --blank, --empty                  Scaffold a hello-world page only (no demo)
+  --demo                            Scaffold the interactive todo demo (default)
 
 Examples:
   bunx create-patties@latest my-app
   bunx create-patties@latest my-app --template codex
-  bunx create-patties@latest my-app --template none --no-git
+  bunx create-patties@latest my-app --template none
+  bunx create-patties@latest my-app --git           # opt-in git init
 `);
 }

package/src/probes.ts

@@ -0,0 +1,28 @@
+// Tool probes for the scaffolder. See spec cli/10-scaffold-probes.
+//
+// `bun` is required to run the resulting project — if it is missing from PATH
+// at scaffold time, fail before any FS writes so the user does not end up with
+// half a project on disk.
+// `git` is optional — if it is missing, skip the `git init` step and warn at
+// the end of the scaffold rather than letting git fail mid-pipeline.
+
+export interface ProbeIO {
+	stderr?: (msg: string) => void;
+	exit?: (code: number) => never;
+}
+
+export function probeTools(io: ProbeIO = {}): void {
+	const stderr = io.stderr ?? ((m: string) => process.stderr.write(`${m}\n`));
+	const exit = io.exit ?? ((c: number) => process.exit(c) as never);
+
+	if (!Bun.which("bun")) {
+		stderr(
+			"create-patties: `bun` not found in PATH. Install Bun from https://bun.sh and re-run.",
+		);
+		exit(1);
+	}
+}
+
+export function hasGit(): boolean {
+	return Bun.which("git") !== null;
+}

package/src/prompts.ts

@@ -0,0 +1,98 @@
+// Interactive prompts for create-patties. See spec cli/09-create-patties-dx
+// items 3 + 5. Uses Bun's built-in prompt() — no new dependency.
+//
+// Non-TTY callers must supply the equivalent flags; the run loop only invokes
+// these helpers when stdin is a TTY and --yes was not passed.
+
+export type AgentTemplate = "claude" | "codex" | "none";
+export type Target = "bun" | "edge";
+export type Scaffold = "demo" | "blank";
+export type Deploy =
+	| "cloudflare"
+	| "vercel"
+	| "deno"
+	| "netlify"
+	| "bun"
+	| "none";
+
+export interface PromptIO {
+	prompt?: (q: string) => string | null;
+	stdout?: (msg: string) => void;
+	isTTY?: boolean;
+}
+
+const DEFAULT_NAME = "my-patties-app";
+
+export function isInteractive(io: PromptIO = {}): boolean {
+	if (io.isTTY !== undefined) return io.isTTY;
+	return Boolean(process.stdin.isTTY);
+}
+
+export function promptName(
+	current: string | undefined,
+	isValid: (name: string) => boolean,
+	io: PromptIO = {},
+): string | undefined {
+	if (current) return current;
+	const ask = io.prompt ?? prompt;
+	const out = io.stdout ?? ((m: string) => process.stdout.write(m));
+
+	for (let attempt = 0; attempt < 5; attempt++) {
+		const answer = (ask(`Project name: (${DEFAULT_NAME}) `) ?? "").trim();
+		const candidate = answer === "" ? DEFAULT_NAME : answer;
+		if (isValid(candidate)) return candidate;
+		out(
+			`✗ invalid project name: "${candidate}" — use lowercase letters, digits, _ or -\n`,
+		);
+	}
+	return undefined;
+}
+
+export function promptAgent(io: PromptIO = {}): AgentTemplate {
+	const ask = io.prompt ?? prompt;
+	const answer = (
+		ask("Which AI coding agent will you use? [claude/codex/none] (claude) ") ??
+		""
+	)
+		.trim()
+		.toLowerCase();
+	if (answer === "codex") return "codex";
+	if (answer === "none") return "none";
+	return "claude";
+}
+
+export function promptScaffold(io: PromptIO = {}): Scaffold {
+	const ask = io.prompt ?? prompt;
+	const answer = (ask("Include the interactive todo demo? [Y/n] (Y) ") ?? "")
+		.trim()
+		.toLowerCase();
+	if (answer === "n" || answer === "no" || answer === "blank") return "blank";
+	return "demo";
+}
+
+export function promptTarget(io: PromptIO = {}): Target {
+	const ask = io.prompt ?? prompt;
+	const answer = (ask("Runtime target? [bun/edge] (bun) ") ?? "")
+		.trim()
+		.toLowerCase();
+	return answer === "edge" ? "edge" : "bun";
+}
+
+export function promptDeploy(io: PromptIO = {}): Deploy {
+	const ask = io.prompt ?? prompt;
+	const answer = (
+		ask("Deploy plugin? [cloudflare/vercel/deno/netlify/bun/none] (none) ") ??
+		""
+	)
+		.trim()
+		.toLowerCase();
+	const valid: Deploy[] = [
+		"cloudflare",
+		"vercel",
+		"deno",
+		"netlify",
+		"bun",
+		"none",
+	];
+	return (valid as string[]).includes(answer) ? (answer as Deploy) : "none";
+}

package/src/readme.ts

@@ -0,0 +1,67 @@
+// README + template-file rendering. See spec cli/09-create-patties-dx item 2.
+//
+// `applyTemplate` does two passes:
+//   1. Strip/keep conditional blocks delimited by:
+//        <!-- if:KEY=VALUE -->...<!-- /if -->
+//      The block is kept iff `vars[KEY] === VALUE`.
+//   2. Replace `{{name}}`, `{{agent}}`, `{{target}}`, `{{deploy}}` placeholders
+//      with the corresponding `vars` entry.
+//
+// `renderTemplatesInTree` walks a scaffolded project and applies the template
+// to every text file we care about (README.md, *.md, *.json, *.ts, *.tsx).
+// Anything else is left untouched so we don't corrupt binary assets.
+
+export interface TemplateVars {
+	name: string;
+	agent: "claude" | "codex" | "none";
+	target: "bun" | "edge";
+	deploy: "cloudflare" | "vercel" | "deno" | "netlify" | "bun" | "none";
+	scaffold: "demo" | "blank";
+}
+
+const CONDITIONAL_RE =
+	/<!--\s*if:([a-zA-Z_]+)=([a-zA-Z0-9_-]+)\s*-->([\s\S]*?)<!--\s*\/if\s*-->\n?/g;
+
+const TEXT_EXT_RE =
+	/\.(md|mdx|json|jsonc|ts|tsx|js|jsx|sh|toml|yml|yaml|gitignore)$/;
+
+export function applyTemplate(source: string, vars: TemplateVars): string {
+	const stripped = source.replace(
+		CONDITIONAL_RE,
+		(_match, key: string, value: string, body: string) => {
+			const v = (vars as unknown as Record<string, string>)[key];
+			return v === value ? body : "";
+		},
+	);
+	return (
+		stripped
+			.replaceAll("{{name}}", vars.name)
+			.replaceAll("{{agent}}", vars.agent)
+			.replaceAll("{{target}}", vars.target)
+			.replaceAll("{{deploy}}", vars.deploy)
+			.replaceAll("{{scaffold}}", vars.scaffold)
+			// Legacy placeholders from earlier overlay revisions — kept so existing
+			// CLAUDE.md / AGENTS.md template text keeps interpolating.
+			.replaceAll("{{PROJECT_NAME}}", vars.name)
+			.replaceAll("{{DEPLOY_TARGET}}", vars.deploy)
+	);
+}
+
+export async function renderTemplatesInTree(
+	dir: string,
+	vars: TemplateVars,
+): Promise<void> {
+	const glob = new Bun.Glob("**/*");
+	for await (const rel of glob.scan({ cwd: dir, onlyFiles: true, dot: true })) {
+		if (!TEXT_EXT_RE.test(rel) && !rel.endsWith("README.md")) continue;
+		const path = `${dir}/${rel}`;
+		const file = Bun.file(path);
+		const text = await file.text();
+		if (!hasTemplateMarkers(text)) continue;
+		await Bun.write(path, applyTemplate(text, vars));
+	}
+}
+
+function hasTemplateMarkers(text: string): boolean {
+	return text.includes("{{") || text.includes("<!-- if:");
+}

package/templates/_claude/.claude/hooks/biome-check.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# PostToolUse hook: run Biome on the file Claude just touched.
+# No-ops cleanly when Biome is not installed so it's safe to ship by default.
+set -euo pipefail
+
+file="${CLAUDE_FILE_PATH:-${1:-}}"
+if [[ -z "${file}" ]]; then exit 0; fi
+case "${file}" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.jsonc) ;;
+  *) exit 0 ;;
+esac
+
+if command -v biome >/dev/null 2>&1; then
+  biome check --write --no-errors-on-unmatched "${file}" || exit 2
+elif command -v bunx >/dev/null 2>&1; then
+  bunx --bun @biomejs/biome check --write --no-errors-on-unmatched "${file}" 2>/dev/null || exit 0
+fi