kizlo 0.8.4 → 0.9.0

package/dist/cli/banner.js

@@ -1,13 +1,4 @@
 //#region src/cli/banner.ts
-const KIZLO_CLI_WORD_MARK = [
-	"██╗  ██╗██╗███████╗██╗      ██████╗ ",
-	"██║ ██╔╝██║╚══███╔╝██║     ██╔═══██╗",
-	"█████╔╝ ██║  ███╔╝ ██║     ██║   ██║",
-	"██╔═██╗ ██║ ███╔╝  ██║     ██║   ██║",
-	"██║  ██╗██║███████╗███████╗╚██████╔╝",
-	"╚═╝  ╚═╝╚═╝╚══════╝╚══════╝ ╚═════╝ "
-];
-const KIZLO_TAGLINE = "Headless WordPress framework for TypeScript";
 function colorSupported() {
 	return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === void 0 && process.env.TERM !== "dumb";
 }
@@ -22,16 +13,6 @@ function palette() {
 		reset: on ? "\x1B[0m" : ""
 	};
 }
-function printBanner(version) {
-	const color = colorSupported();
-	const cyan = color ? "\x1B[38;5;44m" : "";
-	const bold = color ? "\x1B[1m" : "";
-	const dim = color ? "\x1B[2m" : "";
-	const reset = color ? "\x1B[0m" : "";
-	const art = KIZLO_CLI_WORD_MARK.map((line) => `${cyan}${line}${reset}`).join("\n");
-	process.stdout.write(`\n${art}\n\n`);
-	process.stdout.write(`${dim}${KIZLO_TAGLINE}${reset}  ${bold}v${version}${reset}\n\n`);
-}
 
 //#endregion
-export { palette, printBanner };
+export { palette };

package/dist/cli/commands/_setup.js

@@ -11,6 +11,7 @@ import path from "node:path";
 import fs from "node:fs";
 import * as p from "@clack/prompts";
 import { randomBytes } from "node:crypto";
+import getPort, { portNumbers } from "get-port";
 
 //#region src/cli/commands/_setup.ts
 /** Production connection keys — what a real deploy needs, and what `.env.example` always lists. */
@@ -84,15 +85,34 @@ function withApiPath(baseUrl, apiPath) {
 		return baseUrl;
 	}
 }
+/** The conventional starting port a scaffolded app's dev server serves from. */
+const DEFAULT_APP_PORT = 3e3;
+/**
+* Pick a free port for a freshly scaffolded app, preferring {@link DEFAULT_APP_PORT} and stepping
+* upward when it's taken. `create` builds the app URL from this and writes it into `.env`, which is
+* synced to WordPress as the event/webhook delivery target — so defaulting it to a port already in use
+* would hand WordPress an unreachable URL, and it fails *silently* there (events just never arrive).
+* `get-port` probes every loopback family (including the IPv6 `::1` a dev server often binds on macOS),
+* so it never returns a port that's really in use. `init` doesn't use this — an existing project owns
+* its own port, so it asks the user instead.
+*/
+function pickAppPort() {
+	return getPort({ port: portNumbers(DEFAULT_APP_PORT, DEFAULT_APP_PORT + 100) });
+}
 /**
 * Collect the WordPress connection interactively: the backend/site URLs, the webhook signing
 * secret, and either the local-dev folder or a remote site's credentials. The caller layers any
 * framework-specific prompts (directory, import alias) on top of what this returns.
+*
+* When `baseUrl` is supplied the public-URL prompt is skipped and that value is used verbatim —
+* `create` scaffolds a brand-new app that has no public URL yet, so it defaults to the local dev
+* origin and lets the user fill in production later.
 */
-async function collectConnectionInteractively(preset) {
+async function collectConnectionInteractively(preset, opts = {}) {
 	let siteUrl;
 	let baseUrl;
-	if (preset.apiPath) baseUrl = orCancel(await p.text({
+	if (opts.baseUrl !== void 0) baseUrl = opts.baseUrl;
+	else if (preset.apiPath) baseUrl = orCancel(await p.text({
 		message: "Public app URL",
 		placeholder: "https://your-app.com",
 		validate: validate(urlString)
@@ -260,10 +280,9 @@ async function setupLocalWordPress(cwd, conn) {
 		conn.wpUrl = local.url;
 		conn.wpUsername = local.username;
 		conn.wpPassword = local.appPassword;
+		conn.adminPassword = local.adminPassword;
 		s.stop("Local WordPress ready");
 		if (local.secretSyncError) p.log.warn(`Could not sync KIZLO_DEV_SITE_SECRET to the local plugin (${local.secretSyncError})`);
-		p.log.success(`Local WordPress configured (${conn.devPath}) — .env points at ${conn.wpUrl}`);
-		if (local.adminPassword) p.log.warn(`wp-admin login: ${conn.wpUsername} / ${local.adminPassword} — save it, it's shown only once`);
 	} catch (error) {
 		s.stop("Local WordPress setup failed");
 		p.cancel(error instanceof Error ? error.message : String(error));
@@ -321,26 +340,23 @@ async function syncRemote(conn) {
 	});
 	if (!sync.ok) p.log.warn(`Could not sync the site settings to WordPress (${sync.error}) — make sure the kizlo plugin is active, then set them from the Kizlo settings.`);
 }
-/** The "Next steps" lines, branched on whether a local dev stack was set up. */
-function nextStepsLines(mode, prefix = "") {
+/** The "Next steps" lines. `kizlo dev` is the single entry point for development. */
+function nextStepsLines(conn, prefix = "") {
+	const login = conn.mode === "local" && conn.adminPassword ? [
+		``,
+		`Log in to wp-admin (${conn.wpUrl}/wp-admin):`,
+		`  ${conn.wpUsername} / ${conn.adminPassword} — save it, it's shown only once`
+	] : [];
 	return [
-		...mode === "local" ? [
-			`Start your local WordPress dev stack:`,
-			`  ${prefix}npx kizlo dev`,
-			``
-		] : [
-			`Watch your extensions and regenerate the contract during development:`,
-			`  ${prefix}npx kizlo watch`,
-			``
-		],
-		`Generate the contract once for production builds:`,
-		`  ${prefix}npx kizlo generate`
+		`Start developing:`,
+		`  ${prefix}npx kizlo dev`,
+		...login
 	];
 }
-/** The shared "Next steps" note, branched on whether a local dev stack was set up. */
-function nextStepsNote(mode, prefix = "") {
-	p.note(nextStepsLines(mode, prefix).join("\n"), "Next steps");
+/** The shared "Next steps" note. */
+function nextStepsNote(conn, prefix = "") {
+	p.note(nextStepsLines(conn, prefix).join("\n"), "Next steps");
 }
 
 //#endregion
-export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };
+export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, pickAppPort, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };

package/dist/cli/commands/_wiring.js

@@ -1,6 +1,6 @@
 import { resolveModuleImport, writeFileIfAbsent } from "../utils.js";
 import { applyPatchToSource, patchChanged, renderPatchCode } from "../presets/patch.js";
-import { findRootLayout, patchEntries, resolvePatch } from "../presets/template.js";
+import { findRootLayout, resolvePatch } from "../presets/template.js";
 import { orCancel } from "./_setup.js";
 import { CONTRACT_BARREL } from "../daemon/generate.js";
 import path from "node:path";
@@ -19,7 +19,7 @@ export default defineConfig({
 `;
 }
 /**
-* Build the {@link ScaffoldContext} that adapts a template's tokenized paths and imports to a real
+* Build the {@link ScaffoldContext} that adapts a template's conventions (paths and imports) to a real
 * project. `dirRel` is the Kizlo home directory, `appDir` the App Router directory, and `alias` the
 * import-alias prefix (empty for relative imports). The server-entry import is resolved per calling
 * file so each scaffolded file references the server through the right specifier.
@@ -65,7 +65,7 @@ function reportScaffold(file, result, yes) {
 	if (result === "kept") p.log.info(`Kept existing ${file.label} (${file.relPath})${yes ? " — pass --force to overwrite" : ""}`);
 	else p.log.success(`${result === "overwritten" ? "Overwrote" : "Created"} ${file.label} (${file.relPath})`);
 }
-/** Seed the generated-contract directory so imports resolve before the first `kizlo watch`/`generate`. */
+/** Seed the generated-contract directory so imports resolve before the first `kizlo dev`/`generate`. */
 function writeGeneratedContract(cwd, serverDirRel) {
 	const generatedDirRel = path.join(serverDirRel, "generated");
 	writeFileIfAbsent(path.join(cwd, generatedDirRel, "contract.json"), "{}\n");
@@ -78,10 +78,10 @@ function writeGeneratedContract(cwd, serverDirRel) {
 * rather than written to a guessed-at file. A confident apply is an idempotent upsert: it replaces
 * our exports if present, adds them if not.
 */
-function applyLayoutPatches(cwd, manifest, scaffold) {
+function applyLayoutPatches(cwd, patches, conventions, scaffold) {
 	const manualSteps = [];
-	for (const entry of patchEntries(manifest)) {
-		const resolved = resolvePatch(entry, manifest.tokens, scaffold);
+	for (const entry of patches) {
+		const resolved = resolvePatch(entry, conventions, scaffold);
 		const target = findRootLayout(cwd, scaffold.appDir, resolved.relPath);
 		if (!target) {
 			manualSteps.push(resolved);
@@ -101,12 +101,7 @@ function applyLayoutPatches(cwd, manifest, scaffold) {
 		const { text, changes } = applied;
 		if (patchChanged(changes)) {
 			fs.writeFileSync(target, text);
-			const parts = [
-				...changes.replacedExports.length ? [`replaced ${changes.replacedExports.join(", ")}`] : [],
-				...changes.addedExports.length ? [`added ${changes.addedExports.join(", ")}`] : [],
-				...changes.addedImports.length ? ["imports"] : []
-			];
-			p.log.success(`Wired Kizlo into your ${resolved.label} (${relTarget}) — ${parts.join(", ")}`);
+			p.log.success(`Wired Kizlo into your ${resolved.label} (${relTarget})`);
 		} else p.log.info(`Your ${resolved.label} is already wired (${relTarget})`);
 	}
 	for (const resolved of manualSteps) p.note(renderPatchCode(resolved), `Add these to your ${resolved.label} (the layout that renders <html>)`);

package/dist/cli/commands/create.js

@@ -1,10 +1,9 @@
 import { dockerAvailable } from "../wp/docker.js";
 import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, getVersion, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
-import { printBanner } from "../banner.js";
 import { getPreset } from "../presets/index.js";
 import { fetchTemplate } from "../presets/source.js";
-import { adaptOwnFile, ownEntries, readManifest } from "../presets/template.js";
-import { collectConnectionInteractively, nextStepsLines, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
+import { adaptFile, changesFor, fileEntries, isExample, patchEntries, readManifest } from "../presets/template.js";
+import { collectConnectionInteractively, nextStepsLines, orCancel, pickAppPort, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
 import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import z from "zod/v4";
 import path from "node:path";
@@ -58,14 +57,16 @@ function bootstrapArgs(manifest, pm, name) {
 * Layer Kizlo's wiring onto a freshly bootstrapped app in `dir`, from an already-fetched template
 * directory + manifest. The framework CLI has produced the base project (package.json, config,
 * tsconfig, the root layout); this drives the manifest — the same engine `init` uses — to record the
-* `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's own files (wiring plus the demo
-* starter pages), seed the generated contract, ignore `.env`, and patch the root layout's SEO exports.
-* The target directory layout comes straight from the manifest tokens, which the bootstrap flags are
-* chosen to match, so files land where the manifest expects. Fresh files are written with `force`,
-* silently replacing the framework defaults.
+* `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's files (the `base` plumbing and
+* the `create` layout/styles always, the `example`-flagged demo pages only when `includeExamples`),
+* seed the generated contract, and ignore `.env`. On a fresh app Kizlo owns the layout, so `create`
+* writes it whole (already SEO-wired) rather than patching — `applyLayoutPatches` runs over `create`'s
+* patches, which are none today. The target directory layout comes straight from the manifest's
+* conventions, which the bootstrap flags are chosen to match, so files land where they expect. Fresh
+* files are written with `force`, silently replacing the framework defaults.
 */
 async function applyManifestWiring(dir, templateDir, manifest, opts) {
-	const { kizloDir, appDir, alias } = manifest.tokens;
+	const { kizloDir, appDir, alias } = manifest.conventions;
 	const scaffold = buildScaffoldContext(dir, {
 		dirRel: kizloDir,
 		appDir,
@@ -73,18 +74,19 @@ async function applyManifestWiring(dir, templateDir, manifest, opts) {
 		clientUrl: void 0
 	});
 	recordKizloDependency(dir, manifest);
+	const changes = changesFor(manifest, "create").filter((change) => opts.includeExamples || !isExample(change));
 	const files = [{
 		label: "Kizlo config",
 		relPath: "kizlo.config.ts",
 		contents: kizloConfigTemplate(kizloDir, alias, opts.devPath)
-	}, ...ownEntries(manifest, { includeStarter: opts.includeStarter }).map((entry) => adaptOwnFile(templateDir, entry, manifest.tokens, scaffold))];
+	}, ...fileEntries(changes).map((entry) => adaptFile(templateDir, entry, manifest.conventions, scaffold))];
 	for (const file of files) reportScaffold(file, await scaffoldFile(dir, file, {
 		force: true,
 		yes: false
 	}), false);
 	writeGeneratedContract(dir, path.join(kizloDir, "server"));
 	ensureGitignored(dir, ".env");
-	applyLayoutPatches(dir, manifest, scaffold);
+	applyLayoutPatches(dir, patchEntries(changes), manifest.conventions, scaffold);
 }
 const create = defineCommand({
 	meta: {
@@ -105,8 +107,7 @@ const create = defineCommand({
 	},
 	async run({ args }) {
 		const cwd = process.cwd();
-		printBanner(getVersion());
-		p.intro("kizlo create");
+		p.intro(`Let's create a new Kizlo application`);
 		const requested = args.template;
 		let template;
 		if (requested) {
@@ -155,11 +156,11 @@ const create = defineCommand({
 			})),
 			initialValue: defaultPm
 		}));
-		const includeStarter = orCancel(await p.confirm({
+		const includeExamples = orCancel(await p.confirm({
 			message: "Add example pages?",
 			initialValue: true
 		}));
-		const conn = await collectConnectionInteractively(preset);
+		const conn = await collectConnectionInteractively(preset, { baseUrl: `http://localhost:${await pickAppPort()}` });
 		if (preset.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, preset.apiPath);
 		if (conn.mode === "local" && !await dockerAvailable()) {
 			p.cancel("Docker isn't available — start Docker (or install it) and re-run, or choose “Use my own WordPress”.");
@@ -189,7 +190,7 @@ const create = defineCommand({
 		try {
 			await applyManifestWiring(dir, fetched.dir, manifest, {
 				devPath: conn.devPath,
-				includeStarter
+				includeExamples
 			});
 		} catch (error) {
 			fail(error instanceof Error ? error.message : String(error));
@@ -216,7 +217,7 @@ const create = defineCommand({
 			`cd ${name}`,
 			...depsInstalled ? [] : [`${pm} install`],
 			``,
-			...nextStepsLines(conn.mode)
+			...nextStepsLines(conn)
 		].join("\n"), "Next steps");
 		p.outro("Kizlo is ready 🎉");
 	}

package/dist/cli/commands/dev.js

@@ -1,11 +1,11 @@
 import { createStack } from "../wp/docker.js";
-import { ensureGitignored, envGroups, getVersion, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
-import { palette, printBanner } from "../banner.js";
-import { resolveDevConfig } from "../daemon/config.js";
+import { ensureGitignored, envGroups, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
+import { hasDevStack, resolveDevConfig } from "../daemon/config.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
+import { palette } from "../banner.js";
 import { startWatcher } from "../daemon/watch.js";
 import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -20,6 +20,18 @@ async function resolve$1(cwd) {
 		stack: createStack(devStack(cfg))
 	};
 }
+/**
+* The stack lifecycle subcommands (`stop`/`down`/`reset`) only act on a local WordPress
+* Docker stack. A bring-your-own-WordPress project (no `dev.path`) has no stack to manage,
+* so — rather than fall through to `resolveDevConfig`'s hard "`dev.path` is required" error —
+* print a plain note explaining there's nothing to do and exit cleanly. Returns true when a
+* local stack is configured and the caller may proceed.
+*/
+async function requireDevStack(cwd) {
+	if (await hasDevStack(cwd)) return true;
+	note("No local WordPress stack is configured (`dev.path` is unset) — nothing to manage here.");
+	return false;
+}
 /** A dim, untagged one-liner (no consola timestamp) for the clean dev output. */
 function note(text) {
 	const { dim, reset } = palette();
@@ -157,8 +169,8 @@ function armForegroundTeardown(cfg) {
 	}
 }
 /**
-* Boot the stack and run in the foreground until exit — the shared path behind bare
-* `kizlo dev` and `kizlo dev reset`. Arms teardown first (so a mid-startup cancel still
+* Boot the stack and run in the foreground until exit — the path behind bare
+* `kizlo dev`. Arms teardown first (so a mid-startup cancel still
 * stops partial containers), shows a timed spinner, prints the summary + stop hint, then
 * parks. A referenced timer holds the event loop open — an unresolved promise alone would
 * not, so without it Node would empty its loop and exit straight after printing.
@@ -213,15 +225,39 @@ async function startForeground(cfg) {
 	await new Promise(() => {});
 }
 /**
+* Run the contract watcher in the foreground until exit — the path bare `kizlo dev` takes when no
+* local dev stack is configured (a bring-your-own-WordPress project). Generates once, then watches
+* the server files and regenerates on save. Returns immediately when another watcher already holds
+* the lock; otherwise the persistent watcher keeps the process alive on its own.
+*/
+async function watchOnly(cwd) {
+	const stop = await startWatcher(cwd);
+	if (!stop) return;
+	process.on("exit", stop);
+	for (const signal of [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	]) process.on(signal, () => {
+		stop();
+		process.exit(0);
+	});
+}
+/**
 * Start (or resume) the dev stack. Backs bare `kizlo dev`. Always runs in the foreground
 * and stops the stack on exit, so it never outlives the session — the subcommands
-* (`stop`/`down`/`reset`) manage everything else.
+* (`stop`/`down`/`reset`) manage everything else. Without a local dev stack configured
+* (`dev.path` unset), there's nothing to boot, so it runs the contract watcher alone.
 */
 async function bringUp() {
-	printBanner(getVersion());
+	const cwd = process.cwd();
+	if (!await hasDevStack(cwd)) {
+		await watchOnly(cwd);
+		return;
+	}
 	const reaped = await reapOrphans();
 	if (reaped.length) note(`Stopped ${reaped.length} orphaned dev stack${reaped.length === 1 ? "" : "s"}: ${reaped.join(", ")}`);
-	const cfg = await resolveDevConfig(process.cwd());
+	const cfg = await resolveDevConfig(cwd);
 	if (!cfg.wordpressPath.startsWith("..")) ensureGitignored(cfg.configDir, cfg.wordpressPath);
 	await startForeground(cfg);
 }
@@ -232,6 +268,7 @@ const subCommands = {
 			description: "Stop the dev stack, keeping the database volume"
 		},
 		async run() {
+			if (!await requireDevStack(process.cwd())) return;
 			const { stack } = await resolve$1(process.cwd());
 			await withSpinner("Stopping WordPress dev stack", () => stack.composeStop(), "Stack stopped (volumes kept)");
 		}
@@ -242,6 +279,7 @@ const subCommands = {
 			description: "Stop and remove the dev stack containers (keeps the database and files)"
 		},
 		async run() {
+			if (!await requireDevStack(process.cwd())) return;
 			const { stack } = await resolve$1(process.cwd());
 			await withSpinner("Removing WordPress dev stack", () => stack.composeDown(), "Stack removed (database and files kept)");
 		}
@@ -249,24 +287,24 @@ const subCommands = {
 	reset: defineCommand({
 		meta: {
 			name: "reset",
-			description: "Wipe the database and the install folder, then rebuild fresh"
+			description: "Wipe the database and the install folder so the next `kizlo dev` rebuilds fresh"
 		},
 		async run() {
-			printBanner(getVersion());
+			if (!await requireDevStack(process.cwd())) return;
 			const { cfg, stack } = await resolve$1(process.cwd());
-			await withSpinner("Wiping WordPress dev stack", () => stack.composeDown({ volumes: true }), "Stack wiped");
+			await withSpinner("Wiping WordPress dev stack", () => stack.composeDown({ volumes: true }), "Local WordPress reset successfully");
 			rmSync(cfg.wordpressDir, {
 				recursive: true,
 				force: true
 			});
-			await startForeground(cfg);
+			note("Run `kizlo dev` to rebuild a fresh stack.");
 		}
 	})
 };
 const dev = defineCommand({
 	meta: {
 		name: "dev",
-		description: "Manage the local WordPress dev stack (stop | down | reset)"
+		description: "Run the dev stack and contract watcher (stop | down | reset)"
 	},
 	subCommands,
 	run: groupDefault(Object.keys(subCommands), bringUp)

package/dist/cli/commands/init.js

@@ -1,9 +1,8 @@
 import { dockerAvailable } from "../wp/docker.js";
 import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, runCommandAsync } from "../utils.js";
-import { printBanner } from "../banner.js";
 import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
 import { fetchTemplate } from "../presets/source.js";
-import { adaptOwnFile, ownEntries, readManifest } from "../presets/template.js";
+import { adaptFile, changesFor, fileEntries, patchEntries, readManifest } from "../presets/template.js";
 import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
 import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import path from "node:path";
@@ -139,10 +138,17 @@ const init = defineCommand({
 		const force = Boolean(args.force);
 		const cwd = process.cwd();
 		const pkgPath = path.join(cwd, "package.json");
-		if (!yes) printBanner(getVersion());
-		p.intro("kizlo init");
+		p.intro(`Let's configure Kizlo in your existing application`);
 		if (!fs.existsSync(pkgPath)) {
-			p.cancel("No package.json found — run `kizlo init` inside a project.");
+			p.note([
+				"`kizlo init` adds Kizlo to an existing app, but this directory has no package.json.",
+				"",
+				"Start a new project (scaffolds an app with Kizlo already wired):",
+				"  npx kizlo@latest create",
+				"",
+				"Already have an app? cd into it, then run `kizlo init` again."
+			].join("\n"), "Nothing to configure here");
+			p.cancel("No package.json found in this directory.");
 			process.exit(1);
 		}
 		const pkg = readPkg(pkgPath);
@@ -183,10 +189,6 @@ const init = defineCommand({
 		});
 		if (args.alias !== void 0) setup.alias = String(args.alias).trim();
 		setup.alias = aliasWithSlash(setup.alias);
-		const includeStarter = preset.template ? yes || orCancel(await p.confirm({
-			message: "Add example pages?",
-			initialValue: true
-		})) : false;
 		if (setup.mode === "local" && !await dockerAvailable()) {
 			p.cancel("Docker isn't available — start Docker (or install it) and re-run, or choose “Use my own WordPress”.");
 			process.exit(1);
@@ -226,7 +228,7 @@ const init = defineCommand({
 			try {
 				manifest = readManifest(fetched.dir);
 				await alignKizloVersion(cwd, pm, pkg, manifest);
-				for (const entry of ownEntries(manifest, { includeStarter })) files.push(adaptOwnFile(fetched.dir, entry, manifest.tokens, scaffold));
+				for (const entry of fileEntries(changesFor(manifest, "init"))) files.push(adaptFile(fetched.dir, entry, manifest.conventions, scaffold));
 			} finally {
 				fetched.cleanup();
 			}
@@ -242,9 +244,9 @@ const init = defineCommand({
 		writeGeneratedContract(cwd, serverDirRel);
 		const gitignore = ensureGitignored(cwd, ".env");
 		for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
-		if (manifest) applyLayoutPatches(cwd, manifest, scaffold);
+		if (manifest) applyLayoutPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
 		if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
-		nextStepsNote(setup.mode);
+		nextStepsNote(setup);
 		p.outro("Kizlo is ready 🎉");
 	}
 });

package/dist/cli/daemon/config.js

@@ -118,10 +118,20 @@ async function resolveTestConfig(cwd) {
 	};
 }
 /**
+* Whether a local WordPress dev stack is configured (`dev.path` is set). When false, `kizlo dev`
+* has no stack to boot and runs the contract watcher alone — the path a bring-your-own-WordPress
+* project takes. Loads `kizlo.config.*` from the config dir; a missing config counts as no stack.
+*/
+async function hasDevStack(cwd) {
+	const fileConfig = await loadConfigFile(findConfigDir(cwd));
+	return Boolean(fileConfig?.dev?.path);
+}
+/**
 * Resolve the `dev` block from `kizlo.config.*` into concrete values for the `dev`
 * command, applying defaults (port 8080). `dev.path` is required — the whole
 * WordPress install lives there, so we make the user choose a real folder rather
-* than hide it under a default.
+* than hide it under a default. Callers gate on {@link hasDevStack} first, since a
+* project without a local stack runs the watcher alone rather than reaching here.
 */
 async function resolveDevConfig(cwd) {
 	const configDir = findConfigDir(cwd);
@@ -150,4 +160,4 @@ async function resolveDevConfig(cwd) {
 }
 
 //#endregion
-export { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig };
+export { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, hasDevStack, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig };

package/dist/cli/daemon/watch.js

@@ -37,10 +37,10 @@ async function watch(cfg) {
 /**
 * Acquire the single-instance lock, generate the contract once, and start the file
 * watcher. Returns a synchronous `stop()` that closes the watcher and releases the
-* lock — or `undefined` when another watcher already holds the lock (a standalone
-* `kizlo watch`, or a framework dev script), in which case the caller carries on
-* without watching. Shared by the standalone `kizlo watch` command and the
-* folded-in watcher of `kizlo dev`, so a single terminal covers both.
+* lock — or `undefined` when another watcher already holds the lock (a framework dev
+* script, or a second `kizlo dev`), in which case the caller carries on without
+* watching. Used by `kizlo dev`, both when it boots a local stack and when it runs
+* the watcher alone, so a single terminal covers the whole dev loop.
 */
 async function startWatcher(cwd, opts) {
 	const lock = lockPath(cwd);

package/dist/cli/index.js

@@ -12,7 +12,6 @@ runMain(defineCommand({
 	subCommands: {
 		create: () => import("./commands/create.js").then((m) => m.create),
 		init: () => import("./commands/init.js").then((m) => m.init),
-		watch: () => import("./commands/watch.js").then((m) => m.watch),
 		generate: () => import("./commands/generate.js").then((m) => m.generate),
 		dev: () => import("./commands/dev.js").then((m) => m.dev),
 		test: () => import("./commands/test.js").then((m) => m.test)

package/dist/cli/presets/template.js

@@ -5,28 +5,39 @@ import fs from "node:fs";
 
 //#region src/cli/presets/template.ts
 /**
-* The template's `template.json`. It is the single declaration of which files Kizlo lays onto a
-* project and how each is applied — the same engine drives both `create` (onto a fresh app the
-* framework CLI just bootstrapped) and `init` (onto the user's existing project). Every entry is one
-* of a small closed set — deliberately no "patch an arbitrary source file" kind, so a dangerous
-* strategy is unrepresentable:
+* The template's `template.json`. It is the single declaration of what Kizlo lays onto a project and
+* how — the same engine drives both `create` (onto a fresh app the framework CLI just bootstrapped)
+* and `init` (onto the user's existing project). Changes are grouped into three sections so a command
+* only ever applies what is safe for it:
 *
-* - `own` — a whole file Kizlo writes, adapted to the project's directories and written through the
-*   overwrite policy. `wiring`-scope files (the default) are laid down by both commands; `starter`
-*   demo files are laid down only by `create` (see {@link ownEntries}).
-* - `patch` — a partial injection into a file the framework owns (the root layout's SEO exports).
+* - `base` — applied by both commands: the Kizlo plumbing (server entry, client, routes). Every
+*   change here must be safe on an existing project, so it is limited to files Kizlo owns, which
+*   never collide with the user's pages.
+* - `create` — applied only by `create`, onto a freshly bootstrapped app it may freely overwrite:
+*   the root layout (written whole, already SEO-wired) and its styles as core wiring, plus the demo
+*   pages flagged `example`, which are written only when the user asks for example pages.
+* - `init` — applied only by `init`, onto the user's existing project. The root-layout SEO wiring
+*   lands here as a `patch` so it merges into the layout the user already owns instead of replacing it.
+*
+* Each section is a list of changes, every one a member of a small closed set — deliberately no
+* "patch an arbitrary source file" kind, so a dangerous strategy is unrepresentable:
+*
+* - `file` — a whole file Kizlo writes, adapted to the project's directories and written through the
+*   overwrite policy.
+* - `patch` — a partial injection into a file the framework owns (the root layout's SEO exports):
+*   it adds or replaces individual modules (imports/exports) inside the file, never the whole file.
 *   Both commands try a confident apply, otherwise print the payload with placement instructions.
 */
-const tokensSchema = z.object({
+const conventionsSchema = z.object({
 	kizloDir: z.string(),
 	appDir: z.string(),
 	alias: z.string()
 });
-const ownSchema = z.object({
-	kind: z.literal("own"),
+const fileSchema = z.object({
+	kind: z.literal("file"),
 	role: z.string(),
 	path: z.string(),
-	scope: z.enum(["wiring", "starter"]).optional()
+	example: z.boolean().optional()
 });
 const patchSchema = z.object({
 	kind: z.literal("patch"),
@@ -46,12 +57,15 @@ const bootstrapSchema = z.object({
 	initializer: z.string(),
 	flags: z.array(z.string()).default([])
 });
+const changeSchema = z.discriminatedUnion("kind", [fileSchema, patchSchema]);
 const manifestSchema = z.object({
 	framework: z.string(),
 	kizloVersion: z.string().optional(),
 	bootstrap: bootstrapSchema.optional(),
-	tokens: tokensSchema,
-	files: z.array(z.discriminatedUnion("kind", [ownSchema, patchSchema]))
+	conventions: conventionsSchema,
+	base: z.array(changeSchema).default([]),
+	create: z.array(changeSchema).default([]),
+	init: z.array(changeSchema).default([])
 });
 /** Role → the human label init uses in prompts and logs. */
 const ROLE_LABELS = {
@@ -62,6 +76,7 @@ const ROLE_LABELS = {
 	sitemap: "sitemap route",
 	"sitemap-redirect": "sitemap.xml redirect route",
 	manifest: "web manifest route",
+	"root-layout": "root layout",
 	"home-page": "home page",
 	"blog-post": "blog post page",
 	styles: "global styles"
@@ -73,55 +88,64 @@ function readManifest(templateDir) {
 	return manifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
 }
 /**
-* The `own` files to scaffold. By default only `wiring` files (the Kizlo plumbing) — this is what
-* `init` lays onto an existing project, so it never touches the user's own pages. With
-* `includeStarter`, demo `starter` files are added too, which is what `create` lays onto a fresh app.
+* The changes a command applies: the shared `base` set plus the command's own section. `create` gets
+* `base + create` (plumbing plus the demo pages); `init` gets `base + init` (plumbing plus any
+* init-only surgical patches). `base` is applied first so a later section can override it.
 */
-function ownEntries(manifest, opts = {}) {
-	return manifest.files.filter((file) => file.kind === "own" && (opts.includeStarter || file.scope !== "starter"));
+function changesFor(manifest, command) {
+	return [...manifest.base, ...manifest[command]];
+}
+/** The whole-file changes in a resolved change list. */
+function fileEntries(changes) {
+	return changes.filter((change) => change.kind === "file");
+}
+/** The partial-injection changes in a resolved change list. */
+function patchEntries(changes) {
+	return changes.filter((change) => change.kind === "patch");
 }
-function patchEntries(manifest) {
-	return manifest.files.filter((file) => file.kind === "patch");
+/** Whether a change is opt-in demo content — written by `create` only when example pages are requested. */
+function isExample(change) {
+	return change.kind === "file" && change.example === true;
 }
 /** The specifier the template's files use to reach the server entry, e.g. `@/lib/kizlo/server`. */
-function serverImportSpecifier(tokens) {
-	const withoutSrc = tokens.kizloDir.replace(/^src\//, "");
-	return `${tokens.alias.replace(/\/+$/, "")}/${withoutSrc}/server`;
+function serverImportSpecifier(conventions) {
+	const withoutSrc = conventions.kizloDir.replace(/^src\//, "");
+	return `${conventions.alias.replace(/\/+$/, "")}/${withoutSrc}/server`;
 }
 /**
 * Adapt a template path prefix (`src/app/...`, `src/lib/kizlo/...`) to the project's real directories.
-* Only the leading token dir is swapped; the rest of the path is preserved verbatim.
+* Only the leading convention dir is swapped; the rest of the path is preserved verbatim.
 */
-function adaptTemplatePath(relPath, tokens, ctx) {
+function adaptTemplatePath(relPath, conventions, ctx) {
 	const normalized = relPath.split(path.sep).join("/");
-	if (normalized === tokens.appDir || normalized.startsWith(`${tokens.appDir}/`)) return `${ctx.appDir}${normalized.slice(tokens.appDir.length)}`;
-	if (normalized === tokens.kizloDir || normalized.startsWith(`${tokens.kizloDir}/`)) return `${ctx.kizloDir}${normalized.slice(tokens.kizloDir.length)}`;
+	if (normalized === conventions.appDir || normalized.startsWith(`${conventions.appDir}/`)) return `${ctx.appDir}${normalized.slice(conventions.appDir.length)}`;
+	if (normalized === conventions.kizloDir || normalized.startsWith(`${conventions.kizloDir}/`)) return `${ctx.kizloDir}${normalized.slice(conventions.kizloDir.length)}`;
 	return normalized;
 }
 /**
-* Turn an `own` manifest entry into the {@link ScaffoldFile} init writes: read the template's real
+* Turn a `file` manifest entry into the {@link ScaffoldFile} init writes: read the template's real
 * file, rewrite its path prefix to the project's directories, and swap the server-entry import
 * specifier for the one resolved at the file's new location (tsconfig alias or relative). The swap is
 * surgical — it replaces the exact specifier the template uses, not a loose directory substring — so
 * an unrelated occurrence can't be corrupted. This is the job the old build-time extractor did; it
 * moves to runtime and stays as precise.
 */
-function adaptOwnFile(templateDir, entry, tokens, ctx) {
+function adaptFile(templateDir, entry, conventions, ctx) {
 	const abs = path.join(templateDir, entry.path);
 	if (!fs.existsSync(abs)) throw new Error(`Template file "${entry.path}" is listed in the manifest but does not exist in the template.`);
 	const body = fs.readFileSync(abs, "utf8");
-	const relPath = adaptTemplatePath(entry.path, tokens, ctx);
+	const relPath = adaptTemplatePath(entry.path, conventions, ctx);
 	const fromDir = path.posix.dirname(relPath);
-	const contents = body.split(serverImportSpecifier(tokens)).join(ctx.serverImport(fromDir));
+	const contents = body.split(serverImportSpecifier(conventions)).join(ctx.serverImport(fromDir));
 	return {
 		label: ROLE_LABELS[entry.role] ?? entry.role,
 		relPath,
 		contents
 	};
 }
-/** Substitute the path/import tokens for a patch against the project's real directories. */
-function resolvePatch(entry, tokens, ctx) {
-	const relPath = adaptTemplatePath(entry.path, tokens, ctx);
+/** Adapt a patch's path prefix and server-import specifier to the project's real directories. */
+function resolvePatch(entry, conventions, ctx) {
+	const relPath = adaptTemplatePath(entry.path, conventions, ctx);
 	const fromDir = path.posix.dirname(relPath);
 	const imports = entry.imports.map((imp) => ({
 		module: imp.module.replaceAll("{{serverImport}}", ctx.serverImport(fromDir)),
@@ -169,4 +193,4 @@ function rendersHtml(file) {
 }
 
 //#endregion
-export { adaptOwnFile, findRootLayout, ownEntries, patchEntries, readManifest, resolvePatch };
+export { adaptFile, changesFor, fileEntries, findRootLayout, isExample, patchEntries, readManifest, resolvePatch };

package/dist/cli/utils.js

@@ -87,7 +87,7 @@ function resolveModuleImport(cwd, targetRel, fromDirRel, alias) {
 }
 /**
 * Loads the project's `.env` files into `process.env`. The single place env
-* values come from — shared by `init --yes` and the `kizlo watch`/`generate`
+* values come from — shared by `init --yes` and the `kizlo dev`/`generate`
 * daemon so they always read the same source.
 */
 function loadEnvFiles(cwd) {

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.8.4";
+var version = "0.9.0";
 
 //#endregion
 export { version };

package/dist/router.d.ts

@@ -179,7 +179,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | undefined;
+        orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | undefined;
         searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
         slug?: string | string[] | undefined;
         taxRelation?: "AND" | "OR" | undefined;
@@ -507,7 +507,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | "menu_order" | undefined;
+        orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | "menu_order" | undefined;
         searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
         slug?: string | string[] | undefined;
         parent?: string | number | (string | number)[] | undefined;
@@ -1186,7 +1186,7 @@ declare const ROUTER_MAP: {
           include?: string | number | (string | number)[] | undefined;
           offset?: string | number | undefined;
           order?: "asc" | "desc" | undefined;
-          orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
+          orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
           searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
           slug?: string | string[] | undefined;
           taxRelation?: "AND" | "OR" | undefined;
@@ -1265,7 +1265,7 @@ declare const ROUTER_MAP: {
           include?: string | number | (string | number)[] | undefined;
           offset?: string | number | undefined;
           order?: "asc" | "desc" | undefined;
-          orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
+          orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
           searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
           slug?: string | string[] | undefined;
           taxRelation?: "AND" | "OR" | undefined;
@@ -1414,7 +1414,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "parent" | "post" | "include" | undefined;
+        orderby?: "id" | "date" | "parent" | "post" | "include" | undefined;
         parent?: string | number | (string | number)[] | undefined;
         parentExclude?: string | number | (string | number)[] | undefined;
         post?: string | number | (string | number)[] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kizlo",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "type": "module",
   "description": "A headless WordPress framework for TypeScript.",
   "keywords": [
@@ -86,6 +86,7 @@
     "citty": "^0.1.6",
     "consola": "^3.2.3",
     "cookie": "^1.0.2",
+    "get-port": "^7.2.0",
     "giget": "^3.0.0",
     "jiti": "^2.7.0",
     "magicast": "^0.5.3",

package/dist/cli/commands/watch.js

@@ -1,35 +0,0 @@
-import { getVersion } from "../utils.js";
-import { printBanner } from "../banner.js";
-import { startWatcher } from "../daemon/watch.js";
-import { defineCommand } from "citty";
-
-//#region src/cli/commands/watch.ts
-const args = { dir: {
-	type: "string",
-	description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
-} };
-async function run({ args: args$1 }) {
-	printBanner(getVersion());
-	const stop = await startWatcher(process.cwd(), { dir: args$1.dir });
-	if (!stop) return;
-	process.on("exit", stop);
-	for (const signal of [
-		"SIGINT",
-		"SIGTERM",
-		"SIGHUP"
-	]) process.on(signal, () => {
-		stop();
-		process.exit(0);
-	});
-}
-const watch = defineCommand({
-	meta: {
-		name: "watch",
-		description: "Watch your extensions and regenerate the Kizlo contract"
-	},
-	args,
-	run
-});
-
-//#endregion
-export { watch };