kizlo 0.9.1 → 0.11.0

package/README.md

@@ -23,16 +23,16 @@ Kizlo is an open-source framework for building content-driven applications with
 
 ## Quick start
 
-Set up Kizlo in your project:
+Scaffold a new project with Kizlo already wired:
 
 ```bash
-npx kizlo@latest init
+npx kizlo@latest create
 ```
 
-Start the local WordPress stack:
+Or add Kizlo to an existing project:
 
 ```bash
-npx kizlo dev
+npx kizlo@latest init
 ```
 
 See the [docs](https://kizlo.io/docs) for the full guide.

package/dist/cli/commands/_setup.js

@@ -1,11 +1,13 @@
-import { composeStop, createStack } from "../wp/docker.js";
-import { ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
+import { LOCAL_DIR_REL } from "../wp/constants.js";
+import { composeStop, createStack, dockerHint, dockerStatus } from "../wp/docker.js";
+import { DEFAULT_ENV_KEYS, ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
 import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName } from "../daemon/config.js";
 import { createAdminAppPassword } from "../wp/bootstrap.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { removeProjectContainers } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
+import { isPluginVersionSupported, pluginUpdateMessage } from "@kizlo/shared";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
@@ -14,51 +16,76 @@ 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. */
-const PROD_WP_ENV_KEYS = [
-	"KIZLO_SITE_SECRET",
-	"KIZLO_WORDPRESS_URL",
-	"KIZLO_WORDPRESS_USERNAME",
-	"KIZLO_WORDPRESS_APPLICATION_PASSWORD"
-];
 /**
-* The `.env` keys setup manages and the values to write, branched on the connection mode. A local
-* dev stack writes the `KIZLO_DEV_WORDPRESS_*` / `KIZLO_DEV_SITE_SECRET` set plus `KIZLO_TARGET=dev`, so it
-* never touches the production keys (a user can point those at a real site). A remote site writes the
-* bare production keys exactly as before — no `KIZLO_TARGET`, since `"production"` is the default target.
+* The resolved `.env` key names the scaffold writes: the template's declared `env` when it has one,
+* else the preset's built-in `envKeys` (the generic `base` preset), else the {@link DEFAULT_ENV_KEYS}
+* fallback for an in-repo template before the first stamped release. Threaded into `managedEnv`,
+* `writeEnv`, and `collectConnectionFromEnv` so the scaffold writes the names the pinned runtime reads.
 */
-function managedEnv(preset, conn) {
-	if (conn.mode === "local") return {
+function resolveEnvKeys(preset, manifest) {
+	return manifest?.env ?? preset.envKeys ?? DEFAULT_ENV_KEYS;
+}
+/** Remote connection keys — what a real deploy needs, and what `.env.example` always lists. */
+function remoteKeys(envKeys) {
+	return [
+		envKeys.remote.siteSecret,
+		envKeys.remote.wpUrl,
+		envKeys.remote.wpUsername,
+		envKeys.remote.wpPassword
+	];
+}
+/**
+* The `.env` keys setup manages and the values to write, branched on the connection mode. Local
+* WordPress writes the `KIZLO_LOCAL_WP_*` / `KIZLO_LOCAL_WP_SECRET` set plus `KIZLO_CONNECT=local`,
+* so it never touches the remote keys (a user can point those at a real site). A remote site writes
+* the bare remote keys exactly as before — no `KIZLO_CONNECT`, since `"remote"` is the default.
+*/
+function managedEnv(envKeys, conn) {
+	if (conn.mode === "local") {
+		const { connect, siteSecret: siteSecret$1, wpUrl: wpUrl$1, wpUsername: wpUsername$1, wpPassword: wpPassword$1 } = envKeys.local;
+		return {
+			keys: [
+				envKeys.baseUrl,
+				connect,
+				siteSecret$1,
+				wpUrl$1,
+				wpUsername$1,
+				wpPassword$1
+			],
+			values: {
+				[envKeys.baseUrl]: conn.baseUrl,
+				[connect]: "local",
+				[siteSecret$1]: conn.siteSecret,
+				[wpUrl$1]: conn.wpUrl,
+				[wpUsername$1]: conn.wpUsername,
+				[wpPassword$1]: conn.wpPassword
+			}
+		};
+	}
+	const { siteSecret, wpUrl, wpUsername, wpPassword } = envKeys.remote;
+	return {
 		keys: [
-			preset.baseUrlEnvKey,
-			"KIZLO_TARGET",
-			"KIZLO_DEV_SITE_SECRET",
-			"KIZLO_DEV_WORDPRESS_URL",
-			"KIZLO_DEV_WORDPRESS_USERNAME",
-			"KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD"
+			envKeys.baseUrl,
+			siteSecret,
+			wpUrl,
+			wpUsername,
+			wpPassword
 		],
 		values: {
-			[preset.baseUrlEnvKey]: conn.baseUrl,
-			KIZLO_TARGET: "dev",
-			KIZLO_DEV_SITE_SECRET: conn.siteSecret,
-			KIZLO_DEV_WORDPRESS_URL: conn.wpUrl,
-			KIZLO_DEV_WORDPRESS_USERNAME: conn.wpUsername,
-			KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD: conn.wpPassword
-		}
-	};
-	return {
-		keys: [preset.baseUrlEnvKey, ...PROD_WP_ENV_KEYS],
-		values: {
-			[preset.baseUrlEnvKey]: conn.baseUrl,
-			KIZLO_SITE_SECRET: conn.siteSecret,
-			KIZLO_WORDPRESS_URL: conn.wpUrl,
-			KIZLO_WORDPRESS_USERNAME: conn.wpUsername,
-			KIZLO_WORDPRESS_APPLICATION_PASSWORD: conn.wpPassword
+			[envKeys.baseUrl]: conn.baseUrl,
+			[siteSecret]: conn.siteSecret,
+			[wpUrl]: conn.wpUrl,
+			[wpUsername]: conn.wpUsername,
+			[wpPassword]: conn.wpPassword
 		}
 	};
 }
 const requiredString = z.string().trim().min(1, "Required");
-const urlString = requiredString.pipe(z.url("Must be a valid URL (e.g. https://example.com)"));
+const urlString = requiredString.pipe(z.url({
+	protocol: /^https?$/,
+	hostname: /^(localhost|(\d{1,3}\.){3}\d{1,3}|([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,})$/,
+	error: "Must be a valid http(s) URL with a real host (e.g. https://example.com)"
+}));
 const dirPath = requiredString.refine((value) => !value.endsWith(".ts"), "Enter a directory, not a file");
 function validate(schema) {
 	return (value) => {
@@ -149,18 +176,24 @@ async function collectConnectionInteractively(preset, opts = {}) {
 		initialValue: "local",
 		options: [{
 			value: "local",
-			label: "Set up a local dev environment",
-			hint: "runs WordPress in Docker"
+			label: "Set up local WordPress",
+			hint: "runs in Docker, for dev and test"
 		}, {
 			value: "remote",
 			label: "Use my own WordPress",
-			hint: "connect to an existing site"
+			hint: "connect to your existing WordPress"
 		}]
 	}));
+	if (mode === "local") {
+		const status = await dockerStatus();
+		if (status !== "running") {
+			p.cancel(dockerHint(status));
+			process.exit(1);
+		}
+	}
 	let wpUrl = "";
 	let wpUsername = "";
 	let wpPassword = "";
-	let devPath;
 	if (mode === "remote") {
 		wpUrl = orCancel(await p.text({
 			message: "WordPress URL",
@@ -175,11 +208,7 @@ async function collectConnectionInteractively(preset, opts = {}) {
 			message: "WordPress application password",
 			validate: validate(requiredString)
 		}));
-	} else devPath = orCancel(await p.text({
-		message: "Local WordPress folder",
-		initialValue: "wordpress",
-		validate: validate(dirPath)
-	}));
+	}
 	return {
 		mode,
 		baseUrl,
@@ -187,27 +216,26 @@ async function collectConnectionInteractively(preset, opts = {}) {
 		siteSecret,
 		wpUrl,
 		wpUsername,
-		wpPassword,
-		devPath
+		wpPassword
 	};
 }
 /**
 * Non-interactive connection: skip prompts and use env values where present. Missing ones are
 * left empty for the user to fill in later. Never fails — always yields a fillable project.
 */
-function collectConnectionFromEnv(preset) {
+function collectConnectionFromEnv(envKeys) {
 	return {
 		mode: "remote",
-		baseUrl: process.env[preset.baseUrlEnvKey]?.trim() ?? "",
-		siteSecret: process.env.KIZLO_SITE_SECRET?.trim() || randomBytes(32).toString("hex"),
-		wpUrl: process.env.KIZLO_WORDPRESS_URL?.trim() ?? "",
-		wpUsername: process.env.KIZLO_WORDPRESS_USERNAME?.trim() ?? "",
-		wpPassword: process.env.KIZLO_WORDPRESS_APPLICATION_PASSWORD?.trim() ?? ""
+		baseUrl: process.env[envKeys.baseUrl]?.trim() ?? "",
+		siteSecret: process.env[envKeys.remote.siteSecret]?.trim() || randomBytes(32).toString("hex"),
+		wpUrl: process.env[envKeys.remote.wpUrl]?.trim() ?? "",
+		wpUsername: process.env[envKeys.remote.wpUsername]?.trim() ?? "",
+		wpPassword: process.env[envKeys.remote.wpPassword]?.trim() ?? ""
 	};
 }
-/** Build a {@link ResolvedDevConfig} from the chosen install folder, matching `resolveDevConfig`'s
+/** Build a {@link ResolvedDevConfig} for the fixed `.kizlo/local` install, matching `resolveDevConfig`'s
 * defaults — built directly so setup never has to round-trip through the config file it's writing. */
-function devConfigFor(cwd, devPath) {
+function devConfigFor(cwd) {
 	return {
 		configDir: cwd,
 		project: `${resolveStackName(cwd)}-dev`,
@@ -216,15 +244,15 @@ function devConfigFor(cwd, devPath) {
 		dbPort: DEFAULT_DEV_DB_PORT,
 		dbPortExplicit: false,
 		fixtures: [],
-		wordpressPath: devPath,
-		wordpressDir: path.resolve(cwd, devPath)
+		wordpressPath: LOCAL_DIR_REL,
+		wordpressDir: path.resolve(cwd, LOCAL_DIR_REL)
 	};
 }
 /**
-* Boot the local dev stack once to produce working credentials, then stop it (volumes
-* persist, so a later `kizlo dev` resumes instantly). The dev stack mints no application
-* password — that's a test-stack concern — so we create one here for REST auth in `.env`.
-* While the stack is still up, push the dev site settings (`siteSecret` plus the Kizlo server's
+* Boot local WordPress once to produce working credentials, then stop it (volumes
+* persist, so a later `kizlo dev` resumes instantly). Local WordPress mints no application
+* password — that's a test concern — so we create one here for REST auth in `.env`.
+* While it's still up, push the site settings (`siteSecret` plus the Kizlo server's
 * `url`/`backend_url`, derived from `baseUrl`) into the plugin so webhook signing and event delivery
 * work.
 */
@@ -266,23 +294,24 @@ async function provisionLocalStack(cfg, siteSecret, baseUrl) {
 	};
 }
 /**
-* Provision the local WordPress dev stack and fill the connection's WP credentials from it, then
-* report the outcome. Mutates `conn` in place (wpUrl / wpUsername / wpPassword). Exits on failure,
-* matching the previous inline behavior. No-op for a remote connection.
+* Provision local WordPress and fill the connection's WP credentials from it, then report the
+* outcome. Mutates `conn` in place (wpUrl / wpUsername / wpPassword). Writing the `local` flags into
+* `kizlo.config.ts` is the caller's job (the generated config for `create`/`init`). Exits on failure.
+* No-op for a remote connection.
 */
 async function setupLocalWordPress(cwd, conn) {
-	if (conn.mode !== "local" || !conn.devPath) return;
-	ensureGitignored(cwd, conn.devPath);
+	if (conn.mode !== "local") return;
+	ensureGitignored(cwd, ".kizlo/");
 	const s = p.spinner();
 	s.start("Setting up local WordPress (first run downloads images, this can take a while)");
 	try {
-		const local = await provisionLocalStack(devConfigFor(cwd, conn.devPath), conn.siteSecret, conn.baseUrl);
+		const local = await provisionLocalStack(devConfigFor(cwd), conn.siteSecret, conn.baseUrl);
 		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})`);
+		if (local.secretSyncError) p.log.warn(`Could not sync KIZLO_LOCAL_WP_SECRET to the local plugin (${local.secretSyncError})`);
 	} catch (error) {
 		s.stop("Local WordPress setup failed");
 		p.cancel(error instanceof Error ? error.message : String(error));
@@ -290,12 +319,34 @@ async function setupLocalWordPress(cwd, conn) {
 	}
 }
 /**
+* The template's own `.env.example`, when it ships one. Templates own the framework-specific key names
+* (e.g. `NEXT_PUBLIC_KIZLO_API_URL`) and the shared section layout, so their file is the source of the
+* scaffold's `.env.example` — see {@link writeEnv}. Undefined for the base preset (no template dir).
+*/
+function readEnvExample(templateDir) {
+	const file = path.join(templateDir, ".env.example");
+	return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : void 0;
+}
+/**
+* The `.env.example` body for the base preset, which ships no template file. Lists the API URL and the
+* remote connection keys, then the commented `KIZLO_CONNECT=local` toggle for the local-dev path. Real
+* templates carry their own `.env.example` (passed to {@link writeEnv}) so its structure and comments
+* stay consistent with the `.env` the scaffold writes.
+*/
+function generatedEnvExample(envKeys) {
+	const exampleKeys = [envKeys.baseUrl, ...remoteKeys(envKeys)];
+	const { content } = mergeEnv("", Object.fromEntries(exampleKeys.map((key) => [key, ""])), new Set(exampleKeys), envGroups(envKeys));
+	return `${content}\n# Point the app at local WordPress (managed by \`kizlo dev\`) instead of the keys above:\n# ${envKeys.local.connect}=local\n`;
+}
+/**
 * Write (or update) `.env` and `.env.example` for the managed keys and report the outcome.
 * Existing conflicting `.env` values are preserved unless `force`; interactively the user is asked,
-* and under `--yes` they are kept. `.env.example` is only written when absent.
+* and under `--yes` they are kept. `.env.example` is only written when absent, and is sourced from the
+* template's own file (`opts.exampleTemplate`) so it matches the `.env` structure, falling back to a
+* generated block for the base preset.
 */
-async function writeEnv(cwd, preset, conn, opts) {
-	const { keys, values: envValues } = managedEnv(preset, conn);
+async function writeEnv(cwd, envKeys, conn, opts) {
+	const { keys, values: envValues } = managedEnv(envKeys, conn);
 	const envPath = path.join(cwd, ".env");
 	const envExisted = fs.existsSync(envPath);
 	const existingEnv = envExisted ? fs.readFileSync(envPath, "utf8") : "";
@@ -311,11 +362,9 @@ async function writeEnv(cwd, preset, conn, opts) {
 			initialValue: true
 		}))) overwriteKeys = /* @__PURE__ */ new Set();
 	}
-	const merge = mergeEnv(existingEnv, envValues, overwriteKeys, envGroups(preset.baseUrlEnvKey));
+	const merge = mergeEnv(existingEnv, envValues, overwriteKeys, envGroups(envKeys));
 	fs.writeFileSync(envPath, merge.content);
-	const exampleKeys = [preset.baseUrlEnvKey, ...PROD_WP_ENV_KEYS];
-	const { content: exampleEnv } = mergeEnv("", Object.fromEntries(exampleKeys.map((key) => [key, ""])), new Set(exampleKeys), envGroups(preset.baseUrlEnvKey));
-	const exampleBody = `${exampleEnv}\n# Point the app at a local dev stack (managed by \`kizlo dev\`) instead of the keys above:\n# KIZLO_TARGET=dev\n`;
+	const exampleBody = opts.exampleTemplate ?? generatedEnvExample(envKeys);
 	const exampleCreated = writeFileIfAbsent(path.join(cwd, ".env.example"), exampleBody);
 	if (!envExisted) p.log.success("Created .env");
 	else if (merge.updated.length || merge.added.length) p.log.success("Updated .env");
@@ -338,7 +387,11 @@ async function syncRemote(conn) {
 		siteUrl: conn.siteUrl,
 		backendUrl: conn.baseUrl
 	});
-	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.`);
+	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.`);
+		return;
+	}
+	if (!isPluginVersionSupported(sync.pluginVersion)) p.log.warn(pluginUpdateMessage(sync.pluginVersion));
 }
 /** The "Next steps" lines. `kizlo dev` is the single entry point for development. */
 function nextStepsLines(conn, prefix = "") {
@@ -359,4 +412,4 @@ function nextStepsNote(conn, prefix = "") {
 }
 
 //#endregion
-export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, pickAppPort, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };
+export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };

package/dist/cli/commands/_wiring.js

@@ -8,13 +8,14 @@ import fs from "node:fs";
 import * as p from "@clack/prompts";
 
 //#region src/cli/commands/_wiring.ts
-/** The kizlo.config.ts a scaffolded project gets: the Kizlo directory, optional import alias, and —
-*  for a local dev setup — the WordPress install folder so `kizlo dev` knows where it lives. */
-function kizloConfigTemplate(dir, alias, devPath) {
+/** The kizlo.config.ts a scaffolded project gets: the Kizlo directory, an optional import alias, and —
+*  when local WordPress is chosen — `dev.local` + `test.local` so `kizlo dev` and `kizlo test` boot the
+*  fixed `.kizlo/local` install. */
+function kizloConfigTemplate(dir, alias, localWordPress = false) {
 	return `import { defineConfig } from "kizlo/config"
 
 export default defineConfig({
-	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}${devPath ? `\n\tdev: { path: "${devPath}" },` : ""}
+	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}${localWordPress ? `\n\tdev: { local: true },\n\ttest: { local: true },` : ""}
 })
 `;
 }

package/dist/cli/commands/create.js

@@ -1,9 +1,8 @@
-import { dockerAvailable } from "../wp/docker.js";
-import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, getVersion, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
+import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
 import { getPreset } from "../presets/index.js";
 import { fetchTemplate } from "../presets/source.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 { adaptFile, changesFor, fileEntries, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.js";
+import { collectConnectionInteractively, nextStepsLines, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, 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";
@@ -29,16 +28,23 @@ const PACKAGE_MANAGERS = [
 	"bun"
 ];
 /**
-* Pin the `kizlo` dependency in the freshly bootstrapped `package.json`. The template is
-* authoritative for the version (`kizloVersion` in its manifest, stamped at release), falling back to
-* the running CLI's version in-repo before the first stamp. The dependency is only recorded, not
-* installed — the getting-started note tells the user to run install.
+* Pin Kizlo's dependencies in the freshly bootstrapped `package.json`. The template is authoritative
+* for the versions (its manifest's `dependencies`/`devDependencies`, stamped at release), falling back
+* to the running CLI's version for `kizlo` in-repo before the first stamp. The deps are only recorded,
+* not installed — the getting-started note tells the user to run install.
 */
-function recordKizloDependency(dir, manifest) {
+function recordDependencies(dir, manifest) {
 	const pkgPath = path.join(dir, "package.json");
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-	pkg.dependencies ??= {};
-	pkg.dependencies.kizlo = manifest.kizloVersion ?? `^${getVersion()}`;
+	const { dependencies, devDependencies } = resolveDependencies(manifest);
+	pkg.dependencies = {
+		...pkg.dependencies,
+		...dependencies
+	};
+	if (Object.keys(devDependencies).length) pkg.devDependencies = {
+		...pkg.devDependencies,
+		...devDependencies
+	};
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
 }
 /**
@@ -57,9 +63,9 @@ 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 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`
+* `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's files (core wiring from `base`
+* and `create` always, the `example`-flagged demo pages only when `includeExamples`),
+* seed the generated contract, and ignore `.env` and the `.kizlo/` working dir (which holds the local WordPress install). 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
@@ -73,12 +79,12 @@ async function applyManifestWiring(dir, templateDir, manifest, opts) {
 		alias,
 		clientUrl: void 0
 	});
-	recordKizloDependency(dir, manifest);
-	const changes = changesFor(manifest, "create").filter((change) => opts.includeExamples || !isExample(change));
+	recordDependencies(dir, manifest);
+	const changes = changesFor(manifest, "create", { includeExamples: opts.includeExamples });
 	const files = [{
 		label: "Kizlo config",
 		relPath: "kizlo.config.ts",
-		contents: kizloConfigTemplate(kizloDir, alias, opts.devPath)
+		contents: kizloConfigTemplate(kizloDir, alias, opts.localDev)
 	}, ...fileEntries(changes).map((entry) => adaptFile(templateDir, entry, manifest.conventions, scaffold))];
 	for (const file of files) reportScaffold(file, await scaffoldFile(dir, file, {
 		force: true,
@@ -86,6 +92,7 @@ async function applyManifestWiring(dir, templateDir, manifest, opts) {
 	}), false);
 	writeGeneratedContract(dir, path.join(kizloDir, "server"));
 	ensureGitignored(dir, ".env");
+	ensureGitignored(dir, ".kizlo/");
 	applyLayoutPatches(dir, patchEntries(changes), manifest.conventions, scaffold);
 }
 const create = defineCommand({
@@ -156,16 +163,12 @@ const create = defineCommand({
 			})),
 			initialValue: defaultPm
 		}));
+		const conn = await collectConnectionInteractively(preset, { baseUrl: `http://localhost:${await pickAppPort()}` });
+		if (preset.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, preset.apiPath);
 		const includeExamples = orCancel(await p.confirm({
-			message: "Add example pages?",
+			message: "Add examples?",
 			initialValue: true
 		}));
-		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”.");
-			process.exit(1);
-		}
 		const fetched = await fetchTemplate(template);
 		const fail = (message) => {
 			fetched.cleanup();
@@ -173,6 +176,8 @@ const create = defineCommand({
 			process.exit(1);
 		};
 		const manifest = readManifest(fetched.dir);
+		const minErr = minCliError(manifest);
+		if (minErr) fail(minErr);
 		const bootstrap = bootstrapArgs(manifest, pm, name);
 		if (!bootstrap) {
 			fetched.cleanup();
@@ -187,10 +192,11 @@ const create = defineCommand({
 			if (scaffold.output) p.log.error(scaffold.output);
 			fail(`${preset.label} setup failed — see the output above and try again.`);
 		}
+		const exampleTemplate = readEnvExample(fetched.dir);
 		try {
 			await applyManifestWiring(dir, fetched.dir, manifest, {
-				devPath: conn.devPath,
-				includeExamples
+				includeExamples,
+				localDev: conn.mode === "local"
 			});
 		} catch (error) {
 			fail(error instanceof Error ? error.message : String(error));
@@ -208,9 +214,10 @@ const create = defineCommand({
 			if (!depsInstalled) p.log.warn(`Install them yourself: cd ${name} && ${installArgs(pm).join(" ")}`);
 		}
 		await setupLocalWordPress(dir, conn);
-		await writeEnv(dir, preset, conn, {
+		await writeEnv(dir, resolveEnvKeys(preset, manifest), conn, {
 			force: true,
-			yes: false
+			yes: false,
+			exampleTemplate
 		});
 		await syncRemote(conn);
 		p.note([