@usequark/quark-create-app 1.23.11

package/src/index.js

@@ -0,0 +1,2920 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { Command } from "commander";
+import { execa } from "execa";
+import fs from "fs-extra";
+import prompts from "prompts";
+import { findEnclosingGitRepo, formatProjectDisplayName } from "./utils.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(__dirname, "../templates");
+const pkg = await fs.readJSON(path.join(__dirname, "../package.json"));
+// db, config, and ui are always scaffolded: the base web app (layout, auth)
+// imports the ui package, so a scaffold without it is broken.
+const REQUIRED_PACKAGES = ["db", "config", "ui"];
+const SCAFFOLD_CHECK_IGNORED_FILES = new Set([".env", ".quark-link.json"]);
+
+// AI harness → directory where embedded skills are placed for auto-loading.
+const HARNESS_SKILL_DIRS = {
+	opencode: ".opencode/skills",
+	claude: ".claude/skills",
+	copilot: ".github/skills",
+};
+const DEFAULT_HARNESS = "opencode";
+
+const program = new Command();
+
+program
+	.name("quark")
+	.description("Quark CLI - scaffold, update, and deploy Quark projects")
+	.version(pkg.version);
+
+/**
+ * Generate a cryptographically secure random string
+ * @param {number} length - Length of the random string (default: 32)
+ * @returns {string} Base64 encoded random string
+ */
+function generateSecureSecret(length = 32) {
+	return crypto
+		.randomBytes(length)
+		.toString("base64")
+		.replace(/[/+=]/g, "")
+		.substring(0, length);
+}
+
+/**
+ * Generate a secure random password
+ * @param {number} length - Length of the password (default: 24)
+ * @returns {string} Alphanumeric password
+ */
+function generateSecurePassword(length = 24) {
+	const chars = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789";
+	const bytes = crypto.randomBytes(length);
+	let result = "";
+	for (let i = 0; i < length; i++) {
+		result += chars[bytes[i] % chars.length];
+	}
+	return result;
+}
+
+/**
+ * Check if a TCP port is available on localhost.
+ * Uses a connect test (not bind) to reliably detect Docker-bound ports on macOS.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function isPortAvailable(port) {
+	return new Promise((resolve) => {
+		const socket = new net.Socket();
+		socket.setTimeout(500);
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve(false); // something is listening - port is in use
+		});
+		socket.once("error", () => {
+			socket.destroy();
+			resolve(true); // ECONNREFUSED - port is free
+		});
+		socket.once("timeout", () => {
+			socket.destroy();
+			resolve(true); // no response - port is free
+		});
+		socket.connect(port, "127.0.0.1");
+	});
+}
+
+/**
+ * Find the next available port starting from a given port
+ * @param {number} startPort
+ * @param {number} [maxAttempts=20]
+ * @returns {Promise<number>}
+ */
+async function findAvailablePort(startPort, maxAttempts = 20) {
+	for (let i = 0; i < maxAttempts; i++) {
+		const port = startPort + i;
+		if (await isPortAvailable(port)) {
+			return port;
+		}
+	}
+	return startPort; // fallback to default if all checked ports are busy
+}
+
+/**
+ * Copy a template directory to the target location, with variable substitution
+ */
+async function copyTemplate(templateName, targetDir, variables = {}) {
+	const templatePath = path.join(templatesDir, templateName);
+
+	if (!(await fs.pathExists(templatePath))) {
+		throw new Error(`Template not found: ${templateName}`);
+	}
+
+	// Copy the template
+	await fs.copy(templatePath, targetDir);
+
+	// Replace variables in package.json files
+	if (Object.keys(variables).length > 0) {
+		const packageJsonPath = path.join(targetDir, "package.json");
+		if (await fs.pathExists(packageJsonPath)) {
+			let content = await fs.readFile(packageJsonPath, "utf-8");
+
+			for (const [key, value] of Object.entries(variables)) {
+				const pattern = new RegExp(
+					key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+					"g",
+				);
+				content = content.replace(pattern, value);
+			}
+
+			await fs.writeFile(packageJsonPath, content);
+		}
+	}
+}
+
+/**
+ * Resolve symlinks so paths reported by git and paths reported by the caller
+ * can be compared reliably (macOS tmpdirs are symlinked).
+ */
+function canonicalPath(dir) {
+	try {
+		return fs.realpathSync(dir);
+	} catch {
+		return path.resolve(dir);
+	}
+}
+
+/**
+ * Find the root of the git repository that contains a directory, if any.
+ * Returns null when the directory is not inside a git work tree.
+ */
+async function findEnclosingGitRoot(projectDir) {
+	try {
+		const { stdout } = await execa("git", ["rev-parse", "--show-toplevel"], {
+			cwd: projectDir,
+		});
+		const root = stdout.trim();
+		return root ? canonicalPath(root) : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Initialize a git repository and create an initial commit.
+ *
+ * When the project directory is already inside a git work tree, no nested
+ * repository is created: the enclosing repository tracks the project files.
+ * Set QUARK_FORCE_GIT_INIT=true to create a separate nested repository instead.
+ *
+ * @returns {Promise<{ initialized: boolean, existingRoot: string | null }>}
+ */
+async function initializeGit(projectDir) {
+	if (process.env.QUARK_FORCE_GIT_INIT !== "true") {
+		const existingRoot = await findEnclosingGitRoot(projectDir);
+
+		if (existingRoot) {
+			console.log(
+				chalk.dim(`    · Already inside a git repository: ${existingRoot}`),
+			);
+			if (existingRoot === canonicalPath(projectDir)) {
+				console.log(
+					chalk.dim(`      Leaving the existing repository untouched.`),
+				);
+			} else {
+				console.log(
+					chalk.dim(
+						`      Skipping nested git init - this project will be tracked by that repository.`,
+					),
+				);
+			}
+			console.log(
+				chalk.dim(
+					`      Set QUARK_FORCE_GIT_INIT=true to create a separate nested repository.`,
+				),
+			);
+			return { initialized: false, existingRoot };
+		}
+	}
+
+	try {
+		// Initialize git repo
+		await execa("git", ["init"], { cwd: projectDir });
+
+		// Add all files
+		await execa("git", ["add", "."], { cwd: projectDir });
+
+		// Create initial commit.
+		// Supply a local identity via -c to avoid failures on machines that
+		// have no global user.email / user.name configured (common on Windows).
+		await execa(
+			"git",
+			[
+				"-c",
+				"user.email=scaffold@quark.local",
+				"-c",
+				"user.name=Quark Scaffold",
+				"commit",
+				"-m",
+				"Initial commit: Quark project scaffold",
+			],
+			{
+				cwd: projectDir,
+			},
+		);
+
+		return { initialized: true, existingRoot: null };
+	} catch (error) {
+		console.warn(
+			chalk.yellow(`⚠️  Git initialization failed: ${error.message}`),
+		);
+		return { initialized: false, existingRoot: null };
+	}
+}
+
+/**
+ * Substitute __QUARK_* placeholders in a single scaffold file.
+ * Writes only when the content actually changed.
+ */
+async function substitutePlaceholders(filePath, values) {
+	let content = await fs.readFile(filePath, "utf-8");
+	const before = content;
+
+	for (const [token, value] of Object.entries(values)) {
+		// Replacer function so `$` sequences in values are treated literally.
+		content = content.replaceAll(token, () => value);
+	}
+
+	if (content !== before) {
+		await fs.writeFile(filePath, content);
+	}
+}
+
+/**
+ * Recursively substitute __QUARK_* placeholders in every Markdown file.
+ */
+async function substitutePlaceholdersInMarkdownFiles(dir, values) {
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await substitutePlaceholdersInMarkdownFiles(fullPath, values);
+		} else if (/\.md$/i.test(entry.name)) {
+			await substitutePlaceholders(fullPath, values);
+		}
+	}
+}
+
+/**
+ * Check whether a project directory has uncommitted (unstaged or staged) changes.
+ *
+ * The diff is scoped to the project directory so that a Quark project nested in
+ * a larger repository is not blocked by dirty sibling files elsewhere in that
+ * repository.
+ */
+async function hasUncommittedChanges(projectDir) {
+	try {
+		await execa("git", ["diff", "--exit-code", "--", "."], {
+			cwd: projectDir,
+		});
+		await execa("git", ["diff", "--cached", "--exit-code", "--", "."], {
+			cwd: projectDir,
+		});
+		return false;
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Update package.json name with scope
+ */
+async function updatePackageJsonName(filePath, scope) {
+	const content = await fs.readFile(filePath, "utf-8");
+	const packageJson = JSON.parse(content);
+
+	// Extract package name (e.g., "@myquark/ui" -> "ui")
+	const parts = packageJson.name.split("/");
+	const packageName = parts[parts.length - 1];
+
+	packageJson.name = `@${scope}/${packageName}`;
+
+	await fs.writeFile(filePath, `${JSON.stringify(packageJson, null, "	")}\n`);
+}
+
+function getWorkspacePackagesForFeatures(features) {
+	const packages = new Set();
+
+	for (const feature of features) {
+		const meta = FEATURE_META[feature];
+		if (meta?.skill) continue; // skill-based verticals have no workspace package
+		const packageNames = meta?.packages ?? [feature];
+
+		for (const packageName of packageNames) {
+			packages.add(packageName);
+		}
+	}
+
+	return [...packages];
+}
+
+function getPairedTemplatesForFeatures(features) {
+	const pairs = [];
+
+	for (const feature of features) {
+		const meta = FEATURE_META[feature];
+		if (!meta || meta.skill) continue; // skill-based verticals have no paired routes
+
+		for (const pair of meta.pairs) {
+			if (!pairs.includes(pair)) {
+				pairs.push(pair);
+			}
+		}
+	}
+
+	return pairs;
+}
+
+function buildFeatureRows(features) {
+	const rows = {
+		ui: "| UI package | Included | `packages/ui/README.md` |",
+		jobs: "| Jobs + worker | Included | `packages/jobs/README.md`, `apps/worker/src/handlers/` |",
+		pwa: "| PWA support | Included | `apps/web/public/sw.js`, `apps/web/src/app/manifest.js` |",
+	};
+
+	const selectedRows = features
+		.filter((feature) => rows[feature])
+		.map((feature) => rows[feature]);
+
+	if (selectedRows.length === 0) {
+		return "| Optional scaffolded features | None selected yet | Add one later with `npx @techstream/quark-create-app add <feature>` |";
+	}
+
+	return selectedRows.join("\n");
+}
+
+function buildOptionalAppLines(features) {
+	const lines = [];
+	if (features.includes("jobs")) {
+		lines.push("│   └── worker/               # BullMQ background worker\n");
+	}
+	return lines.join("");
+}
+
+function buildFirstEditLines(features) {
+	const lines = {
+		ui: "- `packages/ui/src/` - adjust primitives or add app-specific UI components",
+		jobs: "- `packages/jobs/src/definitions.js` and `apps/worker/src/handlers/` - define and process background jobs",
+		pwa: "- `apps/web/public/sw.js` - service worker caching config, `src/app/manifest.js` - app manifest (replaces the base manifest)",
+	};
+
+	const selectedLines = features
+		.filter((feature) => lines[feature])
+		.map((feature) => lines[feature]);
+
+	if (selectedLines.length === 0) {
+		return "- No optional scaffolded packages were selected yet. Add one later when the product needs it.";
+	}
+
+	return selectedLines.join("\n");
+}
+
+function buildFeatureGuideLines(features) {
+	const lines = {
+		ui: "- `packages/ui/README.md` - component catalog, import rules, and extension notes",
+		jobs: "- `packages/jobs/README.md` - queue names, worker pairing, and the job-extension workflow",
+		pwa: "- `apps/web/public/sw.js` - service worker caching strategies and offline behavior",
+	};
+
+	const selectedLines = features
+		.filter((feature) => lines[feature])
+		.map((feature) => lines[feature]);
+
+	if (selectedLines.length === 0) {
+		return "- No optional package guides are present yet. Start with `packages/db` and `apps/web`.";
+	}
+
+	return selectedLines.join("\n");
+}
+
+function normalizeScaffoldDate(scaffoldedDate) {
+	return (scaffoldedDate || new Date().toISOString()).split("T")[0];
+}
+
+function formatFeatureSummary(features) {
+	return features.length > 0 ? features.join(", ") : "none";
+}
+
+/**
+ * Registry pin for @techstream/quark-core in scaffolded apps.
+ * Mirrors sync-templates.js CORE_VERSION_PIN (major.0.0 from baked templates).
+ */
+function getCoreVersionPin() {
+	try {
+		const webPkg = fs.readJSONSync(
+			path.join(templatesDir, "base-project/apps/web/package.json"),
+		);
+		const pin = webPkg?.dependencies?.["@techstream/quark-core"];
+		if (typeof pin === "string" && pin !== "workspace:*") {
+			return pin;
+		}
+	} catch {
+		// Templates may be unavailable in some test contexts.
+	}
+	return "^2.0.0";
+}
+
+/**
+ * Replace @techstream/quark-* workspace deps with @scope/* for local packages.
+ * Also removes deps for packages that were not selected.
+ * @techstream/quark-core is a published registry package — rewrite workspace:*
+ * to the registry pin instead of deleting or rescoping it.
+ */
+function replaceDepsScope(deps, scope, selectedPackages) {
+	if (!deps) return;
+	for (const [key, value] of Object.entries(deps)) {
+		if (key.startsWith("@techstream/quark-") && value === "workspace:*") {
+			// Published registry package — keep name, pin to registry version.
+			if (key === "@techstream/quark-core") {
+				deps[key] = getCoreVersionPin();
+				continue;
+			}
+			const packageName = key.replace("@techstream/quark-", "");
+			delete deps[key];
+			// Only keep the dep if the package was selected (or is always required)
+			if (
+				packageName === "db" ||
+				packageName === "config" ||
+				packageName === "ui" ||
+				selectedPackages.includes(packageName)
+			) {
+				deps[`@${scope}/${packageName}`] = value;
+			}
+		}
+	}
+}
+
+/**
+ * Remove unselected workspace package entries from next.config.js transpilePackages.
+ * Must run AFTER replaceImportsInSourceFiles so package names are already scoped.
+ */
+async function patchNextConfig(webDir, scope, selectedPackages) {
+	const configPath = path.join(webDir, "next.config.js");
+	if (!(await fs.pathExists(configPath))) return;
+
+	let content = await fs.readFile(configPath, "utf-8");
+
+	const optionalEntries = {
+		ui: `@${scope}/ui`,
+		jobs: `@${scope}/jobs`,
+	};
+
+	for (const [feature, pkg] of Object.entries(optionalEntries)) {
+		if (!selectedPackages.includes(feature)) {
+			// Remove the line containing this package from transpilePackages.
+			// Use \r?\n so the regex matches both LF and CRLF line endings
+			// (CRLF can appear on Windows when git autocrlf=true is set).
+			content = content.replace(
+				new RegExp(`[ \\t]*"${pkg.replace("/", "\\/")}",?\\r?\\n`, "g"),
+				"",
+			);
+		}
+	}
+
+	await fs.writeFile(configPath, content);
+}
+
+/**
+ * Replace @techstream/quark-* import paths in all .js source files
+ * for workspace packages (db, jobs, ui, config) with @scope/* equivalents.
+ * Registry packages (@techstream/quark-core) are left untouched.
+ */
+async function replaceImportsInSourceFiles(dir, scope) {
+	const workspacePackages = ["db", "jobs", "ui", "config"];
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+
+		if (
+			entry.isDirectory() &&
+			entry.name !== "node_modules" &&
+			entry.name !== ".next"
+		) {
+			await replaceImportsInSourceFiles(fullPath, scope);
+		} else if (entry.isFile() && /\.(js|ts|jsx|tsx|mjs)$/.test(entry.name)) {
+			let content = await fs.readFile(fullPath, "utf-8");
+			let changed = false;
+
+			for (const pkg of workspacePackages) {
+				const pattern = new RegExp(`@techstream/quark-${pkg}`, "g");
+				if (pattern.test(content)) {
+					content = content.replace(pattern, `@${scope}/${pkg}`);
+					changed = true;
+				}
+			}
+
+			if (changed) {
+				await fs.writeFile(fullPath, content);
+			}
+		}
+	}
+}
+
+/**
+ * Validate project name to prevent path traversal and ensure safe directory creation
+ */
+function validateProjectName(name) {
+	if (!name || typeof name !== "string") {
+		throw new Error("Project name is required");
+	}
+	// Only allow safe characters: alphanumeric, hyphens, underscores, dots
+	if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+		throw new Error(
+			"Project name may only contain letters, numbers, hyphens, underscores, and dots",
+		);
+	}
+	// Block path traversal patterns
+	if (name.startsWith(".") || name.includes("..")) {
+		throw new Error("Project name must not start with '.' or contain '..'");
+	}
+
+	const resolved = path.resolve(process.cwd(), name);
+	if (!resolved.startsWith(process.cwd())) {
+		throw new Error("Project name must not escape the current directory");
+	}
+
+	return resolved;
+}
+
+function resolveSignupPreference(optionValue) {
+	if (optionValue === undefined) {
+		return undefined;
+	}
+
+	const normalized = optionValue.trim().toLowerCase();
+
+	if (["enabled", "enable", "true", "yes", "on"].includes(normalized)) {
+		return true;
+	}
+
+	if (["disabled", "disable", "false", "no", "off"].includes(normalized)) {
+		return false;
+	}
+
+	throw new Error(
+		`Invalid value for --signup: ${optionValue}. Use "enabled" or "disabled".`,
+	);
+}
+
+program
+	.argument("[project-name]", "Name of the project to create")
+	.option(
+		"--no-prompts",
+		"Skip interactive prompts and use default/provided values",
+	)
+	.option(
+		"--signup <mode>",
+		'Public self-service signup mode for the scaffolded project ("enabled" or "disabled")',
+	)
+	.option(
+		"--packages <packages>",
+		"Comma-separated list of optional packages to include (ui,jobs,pwa)",
+	)
+	.option(
+		"--prompt <prompt>",
+		"Product brief used to populate MAIN.md (AI View)",
+	)
+	.option(
+		"--harness <harness>",
+		"AI harness for embedded skills (opencode, claude, copilot)",
+	)
+	.option("--skip-install", "Skip pnpm install and Prisma generate steps")
+	.option("--skip-docker", "Skip Docker orphan-volume cleanup")
+	.action(async (projectName, options) => {
+		console.log(
+			chalk.blue.bold(
+				`\n\uD83D\uDE80 Creating your new Quark project: ${projectName}\n`,
+			),
+		);
+
+		// Verify pnpm is available before doing any work
+		if (!options.skipInstall) {
+			try {
+				await execa("pnpm", ["--version"]);
+			} catch {
+				console.error(chalk.red("\n  ✖ pnpm is required but was not found.\n"));
+				console.error(chalk.yellow("  Install it with one of:"));
+				console.error(
+					chalk.white(
+						"    corepack enable          (recommended, built into Node)",
+					),
+				);
+				console.error(chalk.white("    npm install -g pnpm"));
+				console.error(chalk.white("    brew install pnpm        (macOS)\n"));
+				console.error(chalk.gray("  Then re-run this command.\n"));
+				process.exit(1);
+			}
+		}
+
+		// If no project name provided, prompt for it (interactive only)
+		if (!projectName) {
+			if (options.prompts === false) {
+				console.error(
+					chalk.red(
+						"\n  ✖ Project name is required in non-interactive mode.\n",
+					),
+				);
+				process.exit(1);
+			}
+			const nameResponse = await prompts({
+				type: "text",
+				name: "value",
+				message: "Project name:",
+				validate: (v) => {
+					if (!v || !/^[a-zA-Z0-9._-]+$/.test(v)) {
+						return "Only letters, numbers, hyphens, underscores, and dots allowed";
+					}
+					if (v.startsWith(".") || v.includes("..")) {
+						return "Must not start with '.' or contain '..'";
+					}
+					return true;
+				},
+			});
+			if (!nameResponse.value) {
+				console.log(chalk.yellow("\n⚠️  Setup cancelled."));
+				process.exit(0);
+			}
+			projectName = nameResponse.value;
+		}
+
+		const targetDir = validateProjectName(projectName);
+		const scope = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "");
+		const appDisplayName = formatProjectDisplayName(projectName);
+		const appDescription = `${appDisplayName} application`;
+
+		// Creating a project inside an existing git work tree nests the project
+		// folder (and, if we ran `git init`, a second repository) below the repo
+		// root. pnpm workspaces, turbo and CI workflows all expect package.json
+		// at the repository root, so warn loudly and never create a nested
+		// repository.
+		const enclosingRepo = await findEnclosingGitRepo(process.cwd());
+		if (enclosingRepo) {
+			console.log(
+				chalk.yellow(
+					`\n  ⚠️  This project will be created inside an existing git repository:\n` +
+						`      repository root : ${enclosingRepo}\n` +
+						`      project folder  : ${path.relative(enclosingRepo, targetDir) || projectName}\n\n` +
+						`      pnpm, turbo and GitHub Actions expect package.json at the\n` +
+						`      repository root, so a nested project folder breaks installs\n` +
+						`      and CI. Prefer one of:\n` +
+						`        • scaffold outside this repository, then push the project\n` +
+						`          as its own repository, or\n` +
+						`        • scaffold into a temporary folder and move the files to\n` +
+						`          the repository root before the first commit.\n\n` +
+						`      Git initialization will be skipped to avoid creating a\n` +
+						`      nested repository.\n\n` +
+						`      GitHub only runs workflows stored at the repository root, so\n` +
+						`      <project>/.github/workflows/*.yml will be ignored by GitHub\n` +
+						`      Actions.\n`,
+				),
+			);
+		}
+
+		// Auto-detect interactive mode: if any config options are provided,
+		// skip prompts automatically. Only show prompts when no options given.
+		const hasConfigOptions =
+			options.packages !== undefined ||
+			options.signup !== undefined ||
+			options.prompt !== undefined ||
+			options.harness;
+		if (hasConfigOptions && options.prompts !== false) {
+			console.log(
+				chalk.dim(
+					"  ℹ Configuration options provided — skipping interactive prompts",
+				),
+			);
+			options.prompts = false;
+		}
+
+		// Deprecation warning for --no-prompts (now implicit when options are provided)
+		if (options.prompts === false && !hasConfigOptions) {
+			console.log(
+				chalk.yellow(
+					"  ⚠ --no-prompts is deprecated. Options now auto-skip prompts.",
+				),
+			);
+		}
+
+		const requestedSignupPreference = resolveSignupPreference(options.signup);
+
+		// Clean up orphaned Docker volumes from a previous project with the same name.
+		// Docker Compose names volumes as "<project>_postgres_data", "<project>_redis_data".
+		// These persist even if the project directory is manually deleted, causing
+		// authentication failures when the new project generates different credentials.
+		// We also need to stop any running containers that reference these volumes.
+		if (!options.skipDocker)
+			try {
+				const volumePrefix = `${projectName}_`;
+				const { stdout } = await execa("docker", [
+					"volume",
+					"ls",
+					"--filter",
+					`name=${volumePrefix}`,
+					"--format",
+					"{{.Name}}",
+				]);
+				const orphanedVolumes = stdout
+					.split("\n")
+					.filter((v) => v.startsWith(volumePrefix));
+				if (orphanedVolumes.length > 0) {
+					// Stop and remove any containers using these volumes first
+					const { stdout: containerOut } = await execa("docker", [
+						"ps",
+						"-a",
+						"--filter",
+						`name=${projectName}`,
+						"--format",
+						"{{.ID}}",
+					]);
+					const containers = containerOut.split("\n").filter(Boolean);
+					if (containers.length > 0) {
+						await execa("docker", ["rm", "-f", ...containers]);
+					}
+					// Remove the Docker network if it exists
+					try {
+						await execa("docker", ["network", "rm", `${projectName}_default`]);
+					} catch {
+						// Network may not exist - fine
+					}
+					// Now remove the orphaned volumes
+					for (const vol of orphanedVolumes) {
+						await execa("docker", ["volume", "rm", "-f", vol]);
+					}
+					console.log(chalk.green("  ✓ Cleaned up orphaned Docker volumes"));
+				}
+			} catch {
+				// Docker not available - fine
+			}
+
+		// Check if directory already exists
+		if (await fs.pathExists(targetDir)) {
+			if (!options.prompts) {
+				// In non-interactive mode, automatically remove existing directory
+				console.log(
+					chalk.yellow(
+						`  Directory "${projectName}" already exists. Removing... (non-interactive mode)`,
+					),
+				);
+			} else {
+				const { overwrite } = await prompts({
+					type: "confirm",
+					name: "overwrite",
+					message: `Directory "${projectName}" already exists. Remove it and recreate?`,
+					initial: false,
+				});
+
+				if (!overwrite) {
+					console.log(chalk.yellow("Aborted."));
+					process.exit(1);
+				}
+			}
+
+			// Stop any running Docker containers for this project
+			try {
+				await execa("docker", ["compose", "down"], {
+					cwd: targetDir,
+					stdio: "ignore",
+				});
+				console.log(chalk.green("  ✓ Stopped existing Docker containers"));
+			} catch {
+				// No docker-compose file or Docker not running - fine
+			}
+
+			await fs.remove(targetDir);
+		}
+
+		try {
+			// Create the base directory
+			await fs.ensureDir(targetDir);
+
+			// Step 1: Copy base project template
+			console.log(chalk.cyan("  📦 Scaffolding base project structure..."));
+			await copyTemplate("base-project", targetDir, {
+				"@myquark": `@${scope}`,
+			});
+
+			// Step 1b: Place embedded skills in the selected AI harness directory.
+			const harness = options.harness || DEFAULT_HARNESS;
+			const harnessSkillDir = HARNESS_SKILL_DIRS[harness];
+			if (harnessSkillDir) {
+				const neutralSkills = path.join(targetDir, "skills");
+				if (await fs.pathExists(neutralSkills)) {
+					const destSkills = path.join(targetDir, harnessSkillDir);
+					await fs.ensureDir(destSkills);
+					await fs.copy(neutralSkills, destSkills);
+					await fs.remove(neutralSkills);
+					console.log(
+						chalk.green(
+							`    ✓ Embedded skills → ${harnessSkillDir} (${harness})`,
+						),
+					);
+				}
+				// Point the scaffolded docs at the harness skill directory.
+				for (const doc of ["MAIN.md", "CLAUDE.md", "README.md"]) {
+					const docPath = path.join(targetDir, doc);
+					if (await fs.pathExists(docPath)) {
+						let content = await fs.readFile(docPath, "utf-8");
+						content = content.replace(/\.opencode\/skills/g, harnessSkillDir);
+						await fs.writeFile(docPath, content);
+					}
+				}
+			} else {
+				console.log(
+					chalk.yellow(
+						`    ⚠ Unknown harness "${harness}". Skills left in skills/ (no auto-load).`,
+					),
+				);
+			}
+
+			// Step 2: Create apps directory
+			await fs.ensureDir(path.join(targetDir, "apps"));
+
+			// Step 3: Create packages directory
+			await fs.ensureDir(path.join(targetDir, "packages"));
+
+			// Step 4: Copy required packages (always included)
+			console.log(chalk.cyan("\n  📦 Setting up required packages..."));
+
+			// Database and config packages are always required
+			for (const reqPkg of REQUIRED_PACKAGES) {
+				const pkgDir = path.join(targetDir, "packages", reqPkg);
+				// db is already copied from base-project; config needs to be copied from its template
+				if (!(await fs.pathExists(pkgDir))) {
+					await fs.ensureDir(pkgDir);
+					await copyTemplate(reqPkg, pkgDir);
+				}
+				const pkgJsonPath = path.join(pkgDir, "package.json");
+				// Verify copy succeeded - guards against Windows fs race conditions where a
+				// directory handle is returned before child writes are fully committed.
+				if (!(await fs.pathExists(pkgJsonPath))) {
+					throw new Error(
+						`Required package '${reqPkg}' is missing package.json after copy.\n` +
+							`  This can occur on Windows due to filesystem timing. Please re-run the scaffolder.\n` +
+							`  Expected: ${pkgJsonPath}`,
+					);
+				}
+				const pkgJson = await fs.readJSON(pkgJsonPath);
+				pkgJson.name = `@${scope}/${reqPkg}`;
+				await fs.writeFile(
+					pkgJsonPath,
+					`${JSON.stringify(pkgJson, null, "	")}\n`,
+				);
+				console.log(chalk.green(`    ✓ ${reqPkg} (required)`));
+			}
+
+			// Step 5: Determine which optional packages to scaffold
+			let features;
+			let brief = options.prompt?.trim() || `${appDisplayName} application`;
+			if (!options.prompts && options.packages !== undefined) {
+				// Parse packages from CLI flag
+				console.log(chalk.cyan("\n  🎯 Configuring optional packages..."));
+				const validFeatures = Object.keys(FEATURE_META);
+				features = options.packages
+					.split(",")
+					.map((f) => f.trim())
+					.filter((f) => f.length > 0);
+
+				// Validate features
+				const invalidFeatures = features.filter(
+					(f) => !validFeatures.includes(f),
+				);
+				if (invalidFeatures.length > 0) {
+					throw new Error(
+						`Invalid packages: ${invalidFeatures.join(", ")}. Valid options are: ${validFeatures.join(", ")}`,
+					);
+				}
+
+				// Mobile is added post-creation via `quark add mobile`
+				if (features.includes("mobile")) {
+					throw new Error(
+						'Mobile app cannot be included during project creation. Run "quark add mobile" after scaffolding.',
+					);
+				}
+
+				const requestedFeatures = [...features];
+				features = resolveFeatureSelection(features);
+				const autoIncluded = features.filter(
+					(feature) => !requestedFeatures.includes(feature),
+				);
+				if (autoIncluded.length > 0) {
+					console.log(
+						chalk.yellow(
+							`    ℹ Automatically included required packages: ${autoIncluded.join(", ")}`,
+						),
+					);
+				}
+
+				console.log(
+					chalk.green(
+						`  Selected packages: ${features.join(", ") || "none"} (non-interactive mode)`,
+					),
+				);
+			} else if (!options.prompts) {
+				// Use defaults when --no-prompts is set without --packages
+				console.log(chalk.cyan("\n  🎯 Configuring optional packages..."));
+				features = ["ui", "jobs"];
+				console.log(
+					chalk.green(
+						`  Using default packages: ${features.join(", ")} (non-interactive mode)`,
+					),
+				);
+			} else {
+				// Interactive: simple Y/n prompts
+				console.log(chalk.cyan("\n  💡 Let's set up your project...\n"));
+				const briefResponse = await prompts({
+					type: "text",
+					name: "brief",
+					message: "Describe your app in a sentence or two (seeds MAIN.md):",
+					initial: `${appDisplayName} application`,
+				});
+				brief = briefResponse.brief;
+				if (!brief) {
+					console.log(chalk.yellow("\n⚠️  Setup cancelled."));
+					await fs.remove(targetDir);
+					process.exit(0);
+				}
+				brief = brief.trim();
+
+				console.log("");
+				const jobsResponse = await prompts({
+					type: "confirm",
+					name: "value",
+					message:
+						"Include background jobs (emails, webhooks, scheduled tasks)?",
+					initial: true,
+				});
+				if (typeof jobsResponse.value !== "boolean") {
+					console.log(chalk.yellow("\n⚠️  Setup cancelled."));
+					await fs.remove(targetDir);
+					process.exit(0);
+				}
+
+				const selectedFeatures = ["ui"];
+				if (jobsResponse.value) {
+					selectedFeatures.push("jobs");
+				}
+
+				const pwaResponse = await prompts({
+					type: "confirm",
+					name: "enabled",
+					message: "Enable PWA support (offline, installable)?",
+					initial: false,
+				});
+				if (typeof pwaResponse.enabled !== "boolean") {
+					console.log(chalk.yellow("\n⚠️  Setup cancelled."));
+					await fs.remove(targetDir);
+					process.exit(0);
+				}
+				if (pwaResponse.enabled) {
+					selectedFeatures.push("pwa");
+				}
+
+				features = resolveFeatureSelection(selectedFeatures);
+
+				const requestedFeatures = [...selectedFeatures];
+				const autoIncluded = features.filter(
+					(feature) => !requestedFeatures.includes(feature),
+				);
+				if (autoIncluded.length > 0) {
+					console.log(
+						chalk.yellow(
+							`    ℹ Automatically included required packages: ${autoIncluded.join(", ")}.`,
+						),
+					);
+				}
+			}
+
+			const scaffoldPackages = getWorkspacePackagesForFeatures(features);
+			const pairedTemplates = getPairedTemplatesForFeatures(features);
+			let allowSignup;
+
+			if (requestedSignupPreference !== undefined) {
+				allowSignup = requestedSignupPreference;
+				console.log(
+					chalk.cyan(
+						`\n  🔐 Public signup: ${allowSignup ? "enabled" : "disabled"} (from flag)`,
+					),
+				);
+			} else if (!options.prompts) {
+				allowSignup = true;
+				console.log(
+					chalk.cyan(
+						"\n  🔐 Public signup: enabled (default, non-interactive mode)",
+					),
+				);
+			} else {
+				console.log(chalk.cyan("\n  🔐 Configuring authentication...\n"));
+				const authResponse = await prompts({
+					type: "confirm",
+					name: "allowSignup",
+					message: "Allow public self-service signup?",
+					initial: true,
+				});
+
+				if (typeof authResponse.allowSignup !== "boolean") {
+					console.log(chalk.yellow("\n⚠️  Setup cancelled."));
+					await fs.remove(targetDir);
+					process.exit(0);
+				}
+
+				allowSignup = authResponse.allowSignup;
+			}
+
+			const signupEnvValue = allowSignup ? "true" : "false";
+
+			// Step 6: Copy selected optional packages
+			if (scaffoldPackages.length > 0) {
+				console.log(chalk.cyan("\n  📋 Setting up optional packages..."));
+
+				for (const packageName of scaffoldPackages) {
+					const templatePath = path.join(templatesDir, packageName);
+					if (!(await fs.pathExists(templatePath))) {
+						console.log(
+							chalk.yellow(
+								`    ⚠ ${packageName} (template not yet available - skipped)`,
+							),
+						);
+						continue;
+					}
+
+					const packageDir = path.join(targetDir, "packages", packageName);
+					await fs.ensureDir(packageDir);
+					await copyTemplate(packageName, packageDir);
+
+					// Update package.json with proper scope
+					const packageJsonPath = path.join(packageDir, "package.json");
+					await updatePackageJsonName(packageJsonPath, scope);
+
+					console.log(chalk.green(`    ✓ ${packageName}`));
+				}
+
+				// If jobs selected, also scaffold apps/worker from its template
+				if (pairedTemplates.includes("worker")) {
+					const workerDir = path.join(targetDir, "apps", "worker");
+					await fs.ensureDir(workerDir);
+					await copyTemplate("worker", workerDir);
+					console.log(chalk.green(`    ✓ worker (paired with jobs)`));
+				}
+			}
+
+			// Step 6b: Copy PWA files to web app if selected
+			if (features.includes("pwa")) {
+				console.log(chalk.cyan("\n  📋 Setting up PWA support..."));
+				const pwaTemplateDir = path.join(templatesDir, "pwa");
+				const webDir = path.join(targetDir, "apps/web");
+
+				// Replace the base manifest.js. Next.js serves app/manifest.js at
+				// /manifest.webmanifest; adding a sibling app/manifest.json made the
+				// build fail with "Cannot find module for page: /manifest.webmanifest".
+				await fs.copy(
+					path.join(pwaTemplateDir, "app/manifest.js"),
+					path.join(webDir, "src/app/manifest.js"),
+				);
+
+				// Point the PWA manifest at this project's scope.
+				await substitutePlaceholders(path.join(webDir, "src/app/manifest.js"), {
+					__QUARK_SCOPE__: scope,
+				});
+
+				// Copy sw.js to public/
+				await fs.copy(
+					path.join(pwaTemplateDir, "public/sw.js"),
+					path.join(webDir, "public/sw.js"),
+				);
+
+				// Copy PWARegister client component
+				await fs.copy(
+					path.join(pwaTemplateDir, "app/_components/PWARegister.js"),
+					path.join(webDir, "src/app/_components/PWARegister.js"),
+				);
+
+				// Inject PWARegister into layout.js
+				const layoutPath = path.join(webDir, "src/app/layout.js");
+				let layout = await fs.readFile(layoutPath, "utf-8");
+
+				// Add import (after the last existing import)
+				layout = layout.replace(
+					/import UmamiWebVitals from/,
+					'import PWARegister from "./_components/PWARegister.js";\nimport UmamiWebVitals from',
+				);
+
+				// Add viewport export (before generateMetadata)
+				layout = layout.replace(
+					/export function generateMetadata/,
+					'export const viewport = {\n\tthemeColor: "#000000",\n};\n\nexport function generateMetadata',
+				);
+
+				// Add <PWARegister /> to body (before {children})
+				layout = layout.replace(/<body>/, "<body>\n\t\t\t<PWARegister />");
+
+				await fs.writeFile(layoutPath, layout);
+
+				console.log(
+					chalk.green("    ✓ PWA support enabled (manifest + service worker)"),
+				);
+			}
+
+			// Step 7: Update all package.json dependencies to use correct scope
+			console.log(chalk.cyan("\n  🔧 Updating app dependencies..."));
+
+			// Collect all package.json files that need scope replacement (apps + packages)
+			const allPkgPaths = [
+				path.join(targetDir, "apps", "web", "package.json"),
+				// Worker is only present when jobs is selected
+				...(features.includes("jobs")
+					? [path.join(targetDir, "apps", "worker", "package.json")]
+					: []),
+
+				// Also update cross-dependencies in scaffolded packages (e.g. db → config)
+				...[...REQUIRED_PACKAGES, ...scaffoldPackages].map((pkg) =>
+					path.join(targetDir, "packages", pkg, "package.json"),
+				),
+			];
+
+			for (const pkgPath of allPkgPaths) {
+				if (await fs.pathExists(pkgPath)) {
+					const pkg = await fs.readJSON(pkgPath);
+					// Rename package name if it uses @myquark/ placeholder scope
+					if (pkg.name?.startsWith("@myquark/")) {
+						const shortName = pkg.name.replace("@myquark/", "");
+						pkg.name = `@${scope}/${shortName}`;
+					}
+					replaceDepsScope(pkg.dependencies, scope, scaffoldPackages);
+					replaceDepsScope(pkg.devDependencies, scope, scaffoldPackages);
+					await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
+				}
+			}
+
+			// Also rename root package.json
+			const rootPkgPath = path.join(targetDir, "package.json");
+			if (await fs.pathExists(rootPkgPath)) {
+				const rootPkg = await fs.readJSON(rootPkgPath);
+				rootPkg.name = `@${scope}/root`;
+				await fs.writeFile(
+					rootPkgPath,
+					`${JSON.stringify(rootPkg, null, "	")}\n`,
+				);
+			}
+
+			console.log(chalk.green(`    ✓ App dependencies updated`));
+
+			// Step 7b: Replace workspace package imports in source files
+			console.log(chalk.cyan("\n  🔄 Updating import paths..."));
+			await replaceImportsInSourceFiles(targetDir, scope);
+			console.log(chalk.green(`    ✓ Import paths updated`));
+
+			// Step 7c: Patch next.config.js to remove unselected feature transpilePackages entries
+			await patchNextConfig(
+				path.join(targetDir, "apps", "web"),
+				scope,
+				scaffoldPackages,
+			);
+			console.log(chalk.green(`    ✓ next.config.js patched`));
+
+			// Step 7d: Strip jobs-related code from register route when jobs not selected
+			if (!features.includes("jobs")) {
+				const registerPath = path.join(
+					targetDir,
+					"apps",
+					"web",
+					"src",
+					"app",
+					"api",
+					"auth",
+					"register",
+					"route.js",
+				);
+				if (await fs.pathExists(registerPath)) {
+					let content = await fs.readFile(registerPath, "utf-8");
+					// Remove the jobs import line
+					content = content.replace(
+						/import\s*\{[^}]*\}\s*from\s*["']@[^/]+\/jobs["'];?\n/,
+						"",
+					);
+					// Remove createQueue from the core import if present
+					content = content.replace(/\tcreateQueue,\n/, "");
+					// Remove the @quark:start:jobs ... @quark:end:jobs block (inclusive)
+					content = content.replace(
+						/[ \t]*\/\/ @quark:start:jobs[\s\S]*?\/\/ @quark:end:jobs\n?/,
+						"",
+					);
+					await fs.writeFile(registerPath, content);
+				}
+			}
+
+			// Step 8: Create .env.example file
+			console.log(chalk.cyan("\n  📋 Creating environment configuration..."));
+			const envExampleTemplate = `# ⚠️  IMPORTANT: Copy this file to .env and fill in the values for your environment.
+# NEVER commit the .env file to version control - it contains secrets!
+# $ cp .env.example .env
+
+# --- Environment ---
+# Supported: development, test, staging, production (default: development)
+# NODE_ENV=development
+
+# --- Database Configuration ---
+# These map to the service names in docker-compose.yml
+# ⚠️  SECURITY WARNING: Change these default passwords in production!
+# Generate strong passwords with: openssl rand -base64 32
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=${scope}_user
+POSTGRES_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
+POSTGRES_DB=${scope}_dev
+# Optional: Set DATABASE_URL to override the dynamic construction above
+# DATABASE_URL="postgresql://${scope}_user:CHANGE_ME_TO_STRONG_PASSWORD@localhost:5432/${scope}_dev?schema=public"
+
+# --- Database Pool Configuration ---
+# Connection pool settings are managed automatically. Customize if needed:
+# For advanced tuning, see Prisma connection pool documentation.
+
+# --- Redis Configuration ---
+REDIS_HOST=localhost
+REDIS_PORT=6379
+# Optional: Set REDIS_URL to override the dynamic construction above
+# REDIS_URL="redis://localhost:6379"
+
+# --- Mail Configuration ---
+# Email can be sent via SMTP (local or production), Resend, or Zeptomail.
+# Choose one provider below based on your needs.
+
+# Development: Mailpit local SMTP (defaults below work with docker-compose)
+MAIL_HOST=localhost
+MAIL_SMTP_PORT=1025
+MAIL_UI_PORT=8025
+
+# Production SMTP: Set these instead of MAIL_* when using a real SMTP relay
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_SECURE=true
+# SMTP_USER=your_smtp_user
+# SMTP_PASSWORD=your_smtp_password
+
+# --- Email Provider Selection ---
+# Choose one: "smtp" (default), "resend", or "zeptomail"
+# EMAIL_PROVIDER=smtp
+# EMAIL_FROM=App Name <noreply@yourdomain.com>
+
+# Zeptomail (recommended for production)
+# Get started at: https://www.zoho.com/zeptomail/
+# Your token is shown in Zeptomail console and includes the "Zoho-enczapikey" prefix:
+# e.g. ZEPTOMAIL_TOKEN=Zoho-enczapikey <your_key_here>
+# ZEPTOMAIL_TOKEN=Zoho-enczapikey your_zeptomail_api_key
+# ZEPTOMAIL_URL=https://api.zeptomail.com  # Base URL; /v1.1/email is appended in code
+# ZEPTOMAIL_BOUNCE_EMAIL=bounce@yourdomain.com  # optional
+
+# Resend (alternative provider)
+# Get your API key at: https://resend.com/api-keys
+# RESEND_API_KEY=re_xxxxxxxxxxxxx
+
+# --- Application URL ---
+# Canonical origin for the app. Auth.js pins every sign-in redirect and the
+# client-side Auth.js base URL to this, so it must match the origin you browse
+# on exactly (scheme + host + port).
+# In development it falls back to http://localhost:PORT - set it explicitly
+# whenever you use something else (127.0.0.1, a LAN IP, a tunnel, a different
+# port), otherwise the session cookie is issued for one host and the
+# post-sign-in redirect points at another, and you land back signed out.
+# In production, set this to your real domain:
+# APP_URL=https://yourdomain.com
+
+# --- Application Identity ---
+# APP_NAME is used in metadata, emails, and page titles.
+# ⚠️  APP_DESCRIPTION affects SEO snippets - update before production.
+APP_NAME=${appDisplayName}
+APP_DESCRIPTION=${appDescription}
+
+# --- NextAuth Configuration ---
+# ⚠️  CRITICAL: Generate a secure secret with: openssl rand -base64 32
+# This secret is used to encrypt JWT tokens and session data.
+# Must be at least 32 characters or startup validation fails.
+NEXTAUTH_SECRET=CHANGE_ME_TO_A_32_CHARACTERS_OR_LONGER_SECRET
+
+# NextAuth callback URL. Normally leave this unset: it is derived from APP_URL.
+# Only set it if the auth endpoints live on a different origin, and never give
+# it a path - it must be a bare origin (scheme + host + port).
+# NEXTAUTH_URL=https://yourdomain.com
+
+# --- Authentication ---
+# Toggle during development without re-scaffolding.
+AUTH_ALLOW_SIGNUP=${signupEnvValue}
+
+# --- OAuth Providers (Not Yet Implemented) ---
+# OAuth support is planned for a future release.
+# GitHub OAuth - Get credentials at: https://github.com/settings/developers
+# GITHUB_ID=your_github_client_id
+# GITHUB_SECRET=your_github_client_secret
+
+# Google OAuth - Get credentials at: https://console.cloud.google.com/apis/credentials
+# GOOGLE_CLIENT_ID=your_google_client_id
+# GOOGLE_CLIENT_SECRET=your_google_client_secret
+
+# --- Web App Configuration ---
+PORT=3000
+
+# Development-only: allow extra hosts that can load Next.js dev endpoints
+# from LAN/VPN devices. Comma-separate additional hosts or IPs as needed.
+# NEXT_DEV_ALLOWED_ORIGINS=192.168.1.9,my-macbook.local
+# Legacy alias still recognized: ALLOWED_DEV_ORIGINS=192.168.1.9,my-macbook.local
+
+# --- Worker Configuration ---
+WORKER_CONCURRENCY=5
+
+# --- File Storage ---
+# Provider: "local" (default) or "s3" (S3-compatible: AWS S3, Cloudflare R2, MinIO)
+STORAGE_PROVIDER=local
+# Local storage directory (only when STORAGE_PROVIDER=local)
+# STORAGE_LOCAL_DIR=./uploads
+
+# S3 / Cloudflare R2 (only when STORAGE_PROVIDER=s3)
+# S3_BUCKET=your-bucket-name
+# S3_REGION=auto                  # Use "auto" for Cloudflare R2
+# S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+# S3_ACCESS_KEY_ID=your-access-key
+# S3_SECRET_ACCESS_KEY=your-secret-key
+# S3_PUBLIC_URL=https://your-public-bucket-domain.com
+
+# --- Upload Limits ---
+# UPLOAD_MAX_SIZE=10485760   # Max file size in bytes (default: 10MB)
+# UPLOAD_ALLOWED_TYPES=image/jpeg,image/png,image/gif,image/webp,image/avif,image/svg+xml,application/pdf
+
+# --- Rate Limiting & Security ---
+# RATE_LIMIT_MAX=100           # Max requests per window (default: 1000 dev, 100 prod)
+# RATE_LIMIT_WINDOW_MS=900000  # Window in ms (default: 15 minutes)
+# API_BODY_SIZE_LIMIT=2097152  # 2MB (default)
+# UPLOAD_SIZE_LIMIT=10485760   # 10MB proxy-level limit (default)
+
+# --- Logging & Cache ---
+# LOG_LEVEL=debug              # debug, info, warn, error (default: debug dev, info prod)
+# CACHE_TTL=60                 # Default cache TTL in seconds (default: 60 dev, 600 prod)
+
+# --- Database Seeding ---
+# SEED_PROFILE=dev             # Options: dev (default, includes audit logs + sample job), minimal (users only)
+`;
+			await fs.writeFile(
+				path.join(targetDir, ".env.example"),
+				envExampleTemplate,
+			);
+			console.log(chalk.green(`    ✓ .env.example`));
+
+			// Step 9: Find available ports and generate .env
+			console.log(chalk.cyan("\n  🔌 Checking port availability..."));
+			const postgresPort = await findAvailablePort(5432);
+			const redisPort = await findAvailablePort(6379);
+			const mailSmtpPort = await findAvailablePort(1025);
+			const mailUiPort = await findAvailablePort(8025);
+			const webPort = await findAvailablePort(3000);
+
+			const portChanges = [];
+			if (postgresPort !== 5432)
+				portChanges.push(`PostgreSQL: ${postgresPort}`);
+			if (redisPort !== 6379) portChanges.push(`Redis: ${redisPort}`);
+			if (mailSmtpPort !== 1025) portChanges.push(`Mail SMTP: ${mailSmtpPort}`);
+			if (mailUiPort !== 8025) portChanges.push(`Mail UI: ${mailUiPort}`);
+			if (webPort !== 3000) portChanges.push(`Web: ${webPort}`);
+
+			if (portChanges.length > 0) {
+				console.log(chalk.yellow(`    ⚡ Ports adjusted to avoid conflicts:`));
+				for (const change of portChanges) {
+					console.log(chalk.yellow(`      • ${change}`));
+				}
+			} else {
+				console.log(chalk.green(`    ✓ All default ports available`));
+			}
+
+			console.log(chalk.cyan("\n  🔑 Generating secure environment file..."));
+
+			// Generate secure random values
+			const dbPassword = generateSecurePassword(24);
+			const nextAuthSecret = generateSecureSecret(32);
+
+			// Create .env with auto-generated secure values
+			const envContent = `# --- Database Configuration ---
+POSTGRES_HOST=localhost
+POSTGRES_PORT=${postgresPort}
+POSTGRES_USER=${scope}_user
+POSTGRES_PASSWORD=${dbPassword}
+POSTGRES_DB=${scope}_dev
+
+# --- Redis Configuration ---
+REDIS_HOST=localhost
+REDIS_PORT=${redisPort}
+
+# --- Mail Configuration ---
+MAIL_HOST=localhost
+MAIL_SMTP_PORT=${mailSmtpPort}
+MAIL_UI_PORT=${mailUiPort}
+
+# --- Application Identity ---
+# APP_NAME is used in metadata, emails, and page titles.
+# ⚠️  APP_DESCRIPTION affects SEO snippets - update before production.
+APP_NAME=${appDisplayName}
+APP_DESCRIPTION=${appDescription}
+
+# --- NextAuth Configuration ---
+NEXTAUTH_SECRET=${nextAuthSecret}
+
+# --- Authentication ---
+# Toggle during development without re-scaffolding.
+AUTH_ALLOW_SIGNUP=${signupEnvValue}
+
+# --- Web App Configuration ---
+# APP_URL is derived from PORT automatically in development.
+# In production, set APP_URL explicitly in your environment.
+PORT=${webPort}
+
+# --- Worker Configuration ---
+WORKER_CONCURRENCY=5
+
+# --- File Storage ---
+STORAGE_PROVIDER=local
+
+# --- Database Seeding ---
+# SEED_PROFILE=dev             # Options: dev (default), minimal (users only - use for production initial seed)
+#`;
+			await fs.writeFile(path.join(targetDir, ".env"), envContent);
+			console.log(
+				chalk.green(`    ✓ .env (with auto-generated secure secrets)`),
+			);
+
+			// Step 11: Create .quark-link.json to track Quark version
+			const scaffoldedAt =
+				process.env.QUARK_SCAFFOLD_DATE || new Date().toISOString();
+			const quarkLinkJson = {
+				quarkVersion: process.env.QUARK_VERSION || "latest",
+				quarkSourcePath: process.env.QUARK_SOURCE_PATH || "../../quark",
+				scaffoldedDate: scaffoldedAt,
+				projectName,
+				requiredPackages: REQUIRED_PACKAGES,
+				packages: [...new Set([...REQUIRED_PACKAGES, ...features])],
+				featureVersions: {},
+				authAllowSignup: allowSignup,
+				// Track that worker is paired with jobs (not independently selectable)
+				hasWorker: features.includes("jobs"),
+				brief,
+			};
+			await fs.writeFile(
+				path.join(targetDir, ".quark-link.json"),
+				JSON.stringify(quarkLinkJson, null, "	"),
+			);
+			console.log(chalk.green(`    ✓ .quark-link.json`));
+
+			// Step 10b + 10c: Generate all AI coding tool context files
+			console.log(chalk.cyan("\n  🤖 Generating AI context files..."));
+
+			// Build shared variable map (used by SKILL.md, CLAUDE.md, .cursor/rules, copilot-instructions)
+			const scaffoldDate = normalizeScaffoldDate(scaffoldedAt);
+			const optionalLines = scaffoldPackages
+				.map((f) => {
+					const labels = {
+						ui: "Shared UI components",
+						jobs: "Job queue definitions",
+						pwa: "PWA support",
+					};
+					return `│   ├── ${f}/           # ${labels[f] || f}`;
+				})
+				.join("\n");
+			const optionalAppLines = buildOptionalAppLines(features);
+			const optionalBlock = optionalLines ? `${optionalLines}\n` : "";
+			const featureRows = buildFeatureRows(features);
+			const firstEditLines = buildFirstEditLines(features);
+			const featureGuideLines = buildFeatureGuideLines(features);
+
+			// Every __QUARK_* placeholder used by scaffolded files. Keep this map as
+			// the single source of truth so template files cannot ship with
+			// un-substituted placeholders (guarded by scaffold-output.test.js).
+			const placeholderValues = {
+				__QUARK_SCOPE__: scope,
+				__QUARK_PROJECT_NAME__: projectName,
+				__QUARK_SCAFFOLD_DATE__: scaffoldDate,
+				__QUARK_OPTIONAL_APPS__: optionalAppLines,
+				__QUARK_OPTIONAL_PACKAGES__: optionalBlock,
+				__QUARK_FEATURE_ROWS__: featureRows,
+				__QUARK_FIRST_EDITS__: firstEditLines,
+				__QUARK_FEATURE_GUIDES__: featureGuideLines,
+				__QUARK_PROJECT_BRIEF__: brief,
+			};
+
+			// Step 10b: Substitute variables in project-context SKILL.md
+			const skillPath = path.join(
+				targetDir,
+				".github",
+				"skills",
+				"project-context",
+				"SKILL.md",
+			);
+			if (await fs.pathExists(skillPath)) {
+				await substitutePlaceholders(skillPath, placeholderValues);
+				console.log(
+					chalk.green(`    ✓ .github/skills/project-context/SKILL.md`),
+				);
+			}
+
+			// Step 10c: Substitute variables in all AI coding tool context files
+			const aiContextFiles = [
+				"README.md",
+				"CLAUDE.md",
+				".cursor/rules/quark.mdc",
+				".github/copilot-instructions.md",
+				"docs/adr/README.md",
+			];
+			for (const relPath of aiContextFiles) {
+				const filePath = path.join(targetDir, relPath);
+				if (await fs.pathExists(filePath)) {
+					await substitutePlaceholders(filePath, placeholderValues);
+					console.log(chalk.green(`    ✓ ${relPath}`));
+				}
+			}
+
+			// Step 10d: Substitute variables in scaffolded docs, Railway config,
+			// and embedded skills (outside the AI-context file list above).
+			const scaffoldAssetFiles = [
+				"MAIN.md",
+				".env.railway.example",
+				".railway/railway.ts",
+			];
+			for (const relPath of scaffoldAssetFiles) {
+				const filePath = path.join(targetDir, relPath);
+				if (await fs.pathExists(filePath)) {
+					await substitutePlaceholders(filePath, placeholderValues);
+				}
+			}
+
+			const skillsPlaceholderDir = harnessSkillDir
+				? path.join(targetDir, harnessSkillDir)
+				: path.join(targetDir, "skills");
+			if (await fs.pathExists(skillsPlaceholderDir)) {
+				await substitutePlaceholdersInMarkdownFiles(
+					skillsPlaceholderDir,
+					placeholderValues,
+				);
+				console.log(
+					chalk.green(`    ✓ Embedded skill placeholders substituted`),
+				);
+			}
+
+			// Step 11: Initialize git repository
+			if (process.env.QUARK_SKIP_GIT_INIT === "true") {
+				console.log(chalk.dim("\n  · Skipping git initialization"));
+			} else if (enclosingRepo) {
+				console.log(
+					chalk.dim(
+						"\n  · Skipping git initialization (inside an existing repository)",
+					),
+				);
+			} else {
+				console.log(chalk.cyan("\n  📝 Setting up git..."));
+				const gitResult = await initializeGit(targetDir);
+				if (gitResult.initialized) {
+					console.log(chalk.green(`    ✓ Git initialized with initial commit`));
+				} else if (gitResult.existingRoot) {
+					console.log(
+						chalk.green(
+							`    ✓ Using existing git repository: ${gitResult.existingRoot}`,
+						),
+					);
+
+					// GitHub Actions only reads workflow files from the repository
+					// root, so warn when the scaffold's own workflows will be ignored.
+					if (gitResult.existingRoot !== canonicalPath(targetDir)) {
+						const relativeProjectPath = path.relative(
+							gitResult.existingRoot,
+							targetDir,
+						);
+						console.log(
+							chalk.yellow(
+								`\n    ⚠️  Nested project: GitHub only runs workflows stored at the repository root.`,
+							),
+						);
+						console.log(
+							chalk.white(
+								`       ${relativeProjectPath}/.github/workflows/*.yml will be ignored by GitHub Actions.`,
+							),
+						);
+						console.log(
+							chalk.white(
+								`       To enable CI/deploys, copy them into ${gitResult.existingRoot}/.github/workflows/`,
+							),
+						);
+						console.log(
+							chalk.white(
+								`       and set working-directory: ${relativeProjectPath} on each job's steps.\n`,
+							),
+						);
+					}
+				}
+			}
+
+			// Step 12: Run pnpm install
+			if (!options.skipInstall) {
+				console.log(chalk.cyan("\n  📦 Installing dependencies..."));
+				try {
+					await execa("pnpm", ["install"], {
+						cwd: targetDir,
+						stdio: "inherit",
+					});
+					console.log(chalk.green(`\n    ✓ Dependencies installed`));
+				} catch (installError) {
+					console.warn(
+						chalk.yellow(
+							`\n    ⚠️  pnpm install failed: ${installError.message}`,
+						),
+					);
+					console.warn(
+						chalk.yellow(
+							`    Run 'pnpm install' manually after resolving the issue.`,
+						),
+					);
+				}
+
+				// Step 13: Generate Prisma client
+				console.log(chalk.cyan("\n  🗄️  Generating Prisma client..."));
+				try {
+					await execa("pnpm", ["--filter", "db", "db:generate"], {
+						cwd: targetDir,
+						stdio: "inherit",
+					});
+					console.log(chalk.green(`    ✓ Prisma client generated`));
+				} catch (generateError) {
+					console.warn(
+						chalk.yellow(
+							`\n    ⚠️  Prisma generate failed: ${generateError.message}`,
+						),
+					);
+					console.warn(
+						chalk.yellow(`    Run 'pnpm --filter db db:generate' manually.`),
+					);
+				}
+			}
+
+			// Success message
+			console.log(
+				chalk.green.bold(
+					`\n✅ Project "${projectName}" created successfully!\n`,
+				),
+			);
+
+			console.log(chalk.white(`📂 Project location: ${targetDir}\n`));
+			console.log(chalk.cyan("Start here:"));
+			console.log(chalk.white(`  1. cd ${projectName}`));
+			console.log(chalk.white(`  2. docker compose up -d`));
+			console.log(chalk.white(`  3. pnpm db:migrate`));
+			console.log(chalk.white(`  4. pnpm db:seed`));
+			console.log(chalk.white(`  5. pnpm dev\n`));
+			console.log(
+				chalk.dim(
+					`  Toggle signup any time in development by editing AUTH_ALLOW_SIGNUP in .env\n`,
+				),
+			);
+			console.log(chalk.cyan("Build with AI:"));
+			console.log(
+				chalk.white(`  Open CLAUDE.md in your AI tool, then tell it:`),
+			);
+			console.log(
+				chalk.white(
+					`  "I'm building ${projectName} - [what it does]. Review CLAUDE.md and let's start."\n`,
+				),
+			);
+
+			console.log(
+				chalk.dim(
+					`  📖 github.com/usequark/quark  •  Updates: npx @techstream/quark-create-app update\n`,
+				),
+			);
+		} catch (error) {
+			console.error(chalk.red(`\n✗ Error creating project: ${error.message}`));
+			console.error(chalk.dim(error.stack));
+
+			// Clean up on error
+			if (await fs.pathExists(targetDir)) {
+				await fs.remove(targetDir);
+			}
+
+			process.exit(1);
+		}
+	});
+
+// ---------------------------------------------------------------------------
+// quark add <feature> - Add optional packages to an existing Quark project
+// ---------------------------------------------------------------------------
+
+/**
+ * Feature metadata: dependencies, packages, paired apps/routes, and starter.
+ *
+ * Two kinds of feature:
+ * - `package` (default): scaffolds a workspace package (and optional paired
+ *   apps/routes). e.g. ui, jobs.
+ * - `starter`: drops in a minified domain starter (generic Prisma model + CRUD
+ *   endpoint + skill) from `templates/starters/<starter>/`. No workspace
+ *   package, no paired routes.
+ */
+const FEATURE_META = {
+	ui: { requires: [], packages: ["ui"], pairs: [] },
+	jobs: { requires: [], packages: ["jobs"], pairs: ["worker"] },
+	pwa: { requires: [], packages: [], pairs: [] },
+	mobile: { requires: [], packages: [], pairs: [] },
+	// Admin dashboard and domain verticals (bookings, crm, cms, ai) are not
+	// scaffolded features. All embedded skills ship with every build and the
+	// AI builds them on demand - see the skill index in <harness>/skills/.
+};
+
+function resolveFeatureSelection(features) {
+	const resolved = [];
+	const resolvedSet = new Set();
+	const visiting = new Set();
+
+	function visit(feature) {
+		if (resolvedSet.has(feature)) return;
+		if (visiting.has(feature)) {
+			throw new Error(`Circular feature dependency detected for: ${feature}`);
+		}
+
+		const meta = FEATURE_META[feature];
+		if (!meta) return;
+
+		visiting.add(feature);
+		for (const dependency of meta.requires) {
+			visit(dependency);
+		}
+		visiting.delete(feature);
+
+		resolved.push(feature);
+		resolvedSet.add(feature);
+	}
+
+	for (const feature of features) {
+		visit(feature);
+	}
+
+	return resolved;
+}
+
+/**
+ * Detect the project scope from existing package.json files.
+ * Reads root package.json and extracts the scope from the name field.
+ * @param {string} projectDir
+ * @returns {Promise<string|null>}
+ */
+async function detectProjectScope(projectDir) {
+	const rootPkgPath = path.join(projectDir, "package.json");
+	if (!(await fs.pathExists(rootPkgPath))) return null;
+	const rootPkg = await fs.readJSON(rootPkgPath);
+	const match = rootPkg.name?.match(/^@([^/]+)\//);
+	return match ? match[1] : null;
+}
+
+/**
+ * Detect which optional features are already installed in a project.
+ * @param {string} projectDir
+ * @returns {Promise<string[]>}
+ */
+async function detectInstalledFeatures(projectDir) {
+	const installed = [];
+	// Skill-based verticals are tracked in .quark-link.json (no code is scaffolded).
+	let quarkLinkPackages = [];
+	try {
+		const quarkLink = await fs.readJSON(
+			path.join(projectDir, ".quark-link.json"),
+		);
+		quarkLinkPackages = quarkLink.packages ?? [];
+	} catch {
+		// No .quark-link.json — fall through to directory detection.
+	}
+	for (const feature of Object.keys(FEATURE_META)) {
+		const meta = FEATURE_META[feature];
+		if (meta.skill) {
+			if (quarkLinkPackages.includes(feature)) {
+				installed.push(feature);
+			}
+			continue;
+		}
+		// PWA has no workspace package — detect by PWARegister component in web app
+		if (feature === "pwa") {
+			if (
+				await fs.pathExists(
+					path.join(
+						projectDir,
+						"apps",
+						"web",
+						"src",
+						"app",
+						"_components",
+						"PWARegister.js",
+					),
+				)
+			) {
+				installed.push(feature);
+			}
+			continue;
+		}
+		const featureDir = path.join(projectDir, "packages", feature);
+		if (await fs.pathExists(featureDir)) {
+			installed.push(feature);
+		}
+	}
+	return installed;
+}
+
+async function collectRelativeFilePaths(
+	rootDir,
+	currentDir = rootDir,
+	results = [],
+) {
+	const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		if (entry.name === ".git" || entry.name === "node_modules") {
+			continue;
+		}
+
+		const fullPath = path.join(currentDir, entry.name);
+		const relativePath = path.relative(rootDir, fullPath);
+
+		if (entry.isDirectory()) {
+			await collectRelativeFilePaths(rootDir, fullPath, results);
+			continue;
+		}
+
+		if (entry.isFile() && !SCAFFOLD_CHECK_IGNORED_FILES.has(relativePath)) {
+			results.push(relativePath);
+		}
+	}
+
+	return results.sort();
+}
+
+async function compareScaffoldManagedFiles(expectedDir, projectDir) {
+	const expectedFiles = await collectRelativeFilePaths(expectedDir);
+	const changed = [];
+	const missing = [];
+
+	for (const relativePath of expectedFiles) {
+		const expectedPath = path.join(expectedDir, relativePath);
+		const projectPath = path.join(projectDir, relativePath);
+
+		if (!(await fs.pathExists(projectPath))) {
+			missing.push(relativePath);
+			continue;
+		}
+
+		const projectStat = await fs.stat(projectPath);
+		if (!projectStat.isFile()) {
+			changed.push(relativePath);
+			continue;
+		}
+
+		const [expectedContent, projectContent] = await Promise.all([
+			fs.readFile(expectedPath),
+			fs.readFile(projectPath),
+		]);
+
+		if (!expectedContent.equals(projectContent)) {
+			changed.push(relativePath);
+		}
+	}
+
+	return {
+		total: expectedFiles.length,
+		changed,
+		missing,
+	};
+}
+
+async function createReferenceScaffold(projectDir, quarkLink) {
+	const projectName = quarkLink.projectName || path.basename(projectDir);
+	const linkedFeatures = resolveFeatureSelection(
+		Array.isArray(quarkLink.packages) ? quarkLink.packages : [],
+	);
+	const detectedFeatures = resolveFeatureSelection(
+		await detectInstalledFeatures(projectDir),
+	);
+	const comparisonFeatures = resolveFeatureSelection([
+		...linkedFeatures,
+		...detectedFeatures,
+	]);
+	const allowSignup =
+		typeof quarkLink.authAllowSignup === "boolean"
+			? quarkLink.authAllowSignup
+			: true;
+	const tempRoot = await fs.mkdtemp(
+		path.join(os.tmpdir(), "quark-scaffold-check-"),
+	);
+	const args = [
+		path.join(__dirname, "index.js"),
+		projectName,
+		"--no-prompts",
+		"--skip-install",
+		"--skip-docker",
+		"--packages",
+		comparisonFeatures.join(","),
+		"--signup",
+		allowSignup ? "enabled" : "disabled",
+	];
+
+	try {
+		await execa(process.execPath, args, {
+			cwd: tempRoot,
+			env: {
+				...process.env,
+				QUARK_SCAFFOLD_DATE:
+					quarkLink.scaffoldedDate || new Date().toISOString(),
+				QUARK_SKIP_GIT_INIT: "true",
+			},
+			stdio: "pipe",
+		});
+	} catch (error) {
+		const details = error.stderr || error.stdout || error.shortMessage;
+		await fs.remove(tempRoot);
+		throw new Error(
+			details
+				? `Could not generate the reference scaffold.\n${details}`
+				: "Could not generate the reference scaffold.",
+		);
+	}
+
+	return {
+		tempRoot,
+		expectedDir: path.join(tempRoot, projectName),
+		linkedFeatures,
+		detectedFeatures,
+		comparisonFeatures,
+	};
+}
+
+async function reportScaffoldDrift(projectDir, quarkLink) {
+	console.log(chalk.yellow("Checking scaffold-managed files...\n"));
+
+	const {
+		tempRoot,
+		expectedDir,
+		linkedFeatures,
+		detectedFeatures,
+		comparisonFeatures,
+	} = await createReferenceScaffold(projectDir, quarkLink);
+
+	try {
+		const { total, changed, missing } = await compareScaffoldManagedFiles(
+			expectedDir,
+			projectDir,
+		);
+		const linkedOnly = linkedFeatures.filter(
+			(feature) => !detectedFeatures.includes(feature),
+		);
+		const detectedOnly = detectedFeatures.filter(
+			(feature) => !linkedFeatures.includes(feature),
+		);
+
+		console.log(
+			chalk.cyan(`Recorded features: ${formatFeatureSummary(linkedFeatures)}`),
+		);
+		console.log(
+			chalk.cyan(
+				`Detected features: ${formatFeatureSummary(detectedFeatures)}`,
+			),
+		);
+		console.log(
+			chalk.cyan(
+				`Compared against: ${formatFeatureSummary(comparisonFeatures)}`,
+			),
+		);
+		console.log(chalk.cyan(`Managed files:    ${total}`));
+
+		if (linkedOnly.length > 0 || detectedOnly.length > 0) {
+			console.log(
+				chalk.yellow(
+					"\n  ℹ .quark-link.json and installed feature directories differ; this report used the union.",
+				),
+			);
+		}
+
+		if (changed.length === 0 && missing.length === 0) {
+			console.log(
+				chalk.green(
+					"\n  ✓ No scaffold drift detected. This report is read-only.\n",
+				),
+			);
+			return { total, changed, missing };
+		}
+
+		console.log(
+			chalk.yellow(
+				`\n⚠️  Scaffold drift detected in ${changed.length + missing.length} file(s).\n`,
+			),
+		);
+
+		if (changed.length > 0) {
+			console.log(chalk.yellow(`Changed files (${changed.length}):`));
+			for (const relativePath of changed) {
+				console.log(chalk.white(`  - ${relativePath}`));
+			}
+		}
+
+		if (missing.length > 0) {
+			if (changed.length > 0) {
+				console.log("");
+			}
+			console.log(chalk.yellow(`Missing scaffold files (${missing.length}):`));
+			for (const relativePath of missing) {
+				console.log(chalk.white(`  - ${relativePath}`));
+			}
+		}
+
+		console.log(
+			chalk.dim(
+				"\n  This command only reports scaffold drift. It does not overwrite project files.\n",
+			),
+		);
+
+		return { total, changed, missing };
+	} finally {
+		await fs.remove(tempRoot);
+	}
+}
+
+/**
+ * Add a transpilePackages entry to next.config.js if not already present.
+ * @param {string} webDir - Path to apps/web
+ * @param {string} scopedPkg - e.g. "@myapp/admin"
+ */
+async function addTranspilePackage(webDir, scopedPkg) {
+	const configPath = path.join(webDir, "next.config.js");
+	if (!(await fs.pathExists(configPath))) return;
+
+	let content = await fs.readFile(configPath, "utf-8");
+	if (content.includes(`"${scopedPkg}"`)) return; // already present
+
+	// Insert after the last entry in transpilePackages array
+	const transpileMatch = content.match(/transpilePackages:\s*\[([^\]]*)\]/s);
+	if (!transpileMatch) return;
+
+	const existingBlock = transpileMatch[1];
+	const lastEntry = existingBlock.trimEnd();
+	// Add a trailing comma to the last entry if needed, then add new entry
+	const updatedBlock = lastEntry.endsWith(",")
+		? `${lastEntry}\n\t\t"${scopedPkg}",`
+		: `${lastEntry},\n\t\t"${scopedPkg}",`;
+
+	content = content.replace(transpileMatch[1], `${updatedBlock}\n\t`);
+	await fs.writeFile(configPath, content);
+}
+
+/**
+ * Add a workspace dependency to a package.json file.
+ * @param {string} pkgJsonPath - Path to the package.json
+ * @param {string} depName - e.g. "@myapp/admin"
+ */
+async function addWorkspaceDep(pkgJsonPath, depName) {
+	if (!(await fs.pathExists(pkgJsonPath))) return;
+	const pkg = await fs.readJSON(pkgJsonPath);
+	pkg.dependencies = pkg.dependencies || {};
+	if (pkg.dependencies[depName]) return; // already present
+	pkg.dependencies[depName] = "workspace:*";
+	await fs.writeFile(pkgJsonPath, `${JSON.stringify(pkg, null, "	")}\n`);
+}
+
+async function rewriteWorkspaceDeps(pkgJsonPath, scope, workspacePackages) {
+	if (!(await fs.pathExists(pkgJsonPath))) return;
+	const pkg = await fs.readJSON(pkgJsonPath);
+	replaceDepsScope(pkg.dependencies, scope, workspacePackages);
+	replaceDepsScope(pkg.devDependencies, scope, workspacePackages);
+	await fs.writeFile(pkgJsonPath, `${JSON.stringify(pkg, null, "	")}\n`);
+}
+
+program
+	.command("add")
+	.argument("<feature>", "Package to add (ui, jobs, pwa)")
+	.description("Add an optional package to an existing Quark project")
+	.option("--force", "Skip safety checks (uncommitted changes)")
+	.option("--skip-install", "Skip pnpm install after adding")
+	.action(async (feature, options) => {
+		console.log(chalk.blue.bold(`\n📦 Quark Add: ${feature}\n`));
+
+		// The global `--skip-install` (on the create program) shadows the add
+		// subcommand's option in commander, so also check process.argv directly.
+		const skipInstall =
+			options.skipInstall || process.argv.includes("--skip-install");
+
+		const projectDir = process.cwd();
+
+		// --- Validate: is this a Quark project? ---
+		const quarkLinkPath = path.join(projectDir, ".quark-link.json");
+		if (!(await fs.pathExists(quarkLinkPath))) {
+			console.error(
+				chalk.red(
+					"✗ .quark-link.json not found. Are you in a Quark project root?",
+				),
+			);
+			process.exit(1);
+		}
+
+		// --- Validate: is the feature valid? ---
+		const validFeatures = Object.keys(FEATURE_META);
+		if (!validFeatures.includes(feature)) {
+			console.error(
+				chalk.red(
+					`✗ Unknown feature: "${feature}". Valid options: ${validFeatures.join(", ")}`,
+				),
+			);
+			process.exit(1);
+		}
+
+		// --- Detect project state ---
+		const scope = await detectProjectScope(projectDir);
+		if (!scope) {
+			console.error(
+				chalk.red(
+					"✗ Could not detect project scope from package.json. Expected @scope/root format.",
+				),
+			);
+			process.exit(1);
+		}
+
+		const quarkLink = await fs.readJSON(quarkLinkPath);
+		const installedFeatures = await detectInstalledFeatures(projectDir);
+
+		// --- Check if already installed ---
+		if (installedFeatures.includes(feature)) {
+			console.log(
+				chalk.yellow(`⚠️  "${feature}" is already installed in this project.`),
+			);
+			process.exit(0);
+		}
+
+		// --- Safety: check for uncommitted changes (project-scoped) ---
+		if (!options.force && (await hasUncommittedChanges(projectDir))) {
+			console.log(
+				chalk.yellow(
+					"⚠️  You have uncommitted changes. Commit or stash them first.",
+				),
+			);
+			console.log(
+				chalk.white("Use --force to skip this check (not recommended).\n"),
+			);
+			process.exit(1);
+		}
+
+		// --- Resolve dependency chain ---
+		const resolvedFeatures = resolveFeatureSelection([
+			...installedFeatures,
+			feature,
+		]);
+		const toAdd = resolvedFeatures.filter(
+			(installedFeature) => !installedFeatures.includes(installedFeature),
+		);
+		const missingRequirements = toAdd.filter(
+			(installedFeature) => installedFeature !== feature,
+		);
+		if (missingRequirements.length > 0) {
+			console.log(
+				chalk.yellow(
+					`  ℹ  "${feature}" requires ${missingRequirements.join(", ")} - adding automatically.`,
+				),
+			);
+		}
+		const finalFeatures = resolvedFeatures;
+		const finalWorkspacePackages =
+			getWorkspacePackagesForFeatures(finalFeatures);
+
+		try {
+			for (const feat of toAdd) {
+				const featMeta = FEATURE_META[feat];
+				const packageNames = featMeta.packages ?? [feat];
+				console.log(chalk.cyan(`\n  📋 Adding ${feat}...`));
+
+				// 0. Skill-based vertical — the embedded skill is already scaffolded;
+				//    no starter code is added.
+				if (featMeta.skill) {
+					console.log(
+						chalk.green(
+							`    ✓ ${feat} (skill — build it with the embedded skill)`,
+						),
+					);
+					continue;
+				}
+
+				// PWA modifies the web app, not a workspace package
+				if (feat === "pwa") {
+					const pwaTemplateDir = path.join(templatesDir, "pwa");
+					const webDir = path.join(projectDir, "apps/web");
+
+					if (
+						await fs.pathExists(
+							path.join(webDir, "src/app/_components/PWARegister.js"),
+						)
+					) {
+						console.log(chalk.dim("    · PWA already configured - skipping"));
+					} else {
+						// Replace the base manifest.js - see the scaffold-time copy for
+						// why a sibling manifest.json breaks the Next.js build.
+						await fs.copy(
+							path.join(pwaTemplateDir, "app/manifest.js"),
+							path.join(webDir, "src/app/manifest.js"),
+						);
+
+						// Point the PWA manifest at this project's scope.
+						await substitutePlaceholders(
+							path.join(webDir, "src/app/manifest.js"),
+							{ __QUARK_SCOPE__: scope },
+						);
+
+						// Copy sw.js to public/
+						await fs.copy(
+							path.join(pwaTemplateDir, "public/sw.js"),
+							path.join(webDir, "public/sw.js"),
+						);
+
+						// Copy PWARegister client component
+						await fs.copy(
+							path.join(pwaTemplateDir, "app/_components/PWARegister.js"),
+							path.join(webDir, "src/app/_components/PWARegister.js"),
+						);
+
+						// Inject PWARegister into layout.js
+						const layoutPath = path.join(webDir, "src/app/layout.js");
+						let layout = await fs.readFile(layoutPath, "utf-8");
+
+						layout = layout.replace(
+							/import UmamiWebVitals from/,
+							'import PWARegister from "./_components/PWARegister.js";\nimport UmamiWebVitals from',
+						);
+
+						layout = layout.replace(
+							/export function generateMetadata/,
+							'export const viewport = {\n\tthemeColor: "#000000",\n};\n\nexport function generateMetadata',
+						);
+
+						layout = layout.replace(/<body>/, "<body>\n\t\t\t<PWARegister />");
+
+						await fs.writeFile(layoutPath, layout);
+
+						console.log(
+							chalk.green(
+								"    ✓ PWA support enabled (manifest + service worker)",
+							),
+						);
+					}
+					continue;
+				}
+
+				// Mobile app scaffolds apps/mobile from the template
+				if (feat === "mobile") {
+					const mobileTemplateDir = path.join(templatesDir, "mobile");
+					const mobileDir = path.join(projectDir, "apps/mobile");
+
+					if (await fs.pathExists(mobileDir)) {
+						console.log(
+							chalk.dim("    · apps/mobile already exists - skipping copy"),
+						);
+					} else {
+						await fs.ensureDir(mobileDir);
+						await fs.copy(mobileTemplateDir, mobileDir);
+
+						// Replace placeholder variables in template files
+						const mobileAppName = formatProjectDisplayName(
+							quarkLink.projectName,
+						);
+						const mobileFiles = ["app.json", "package.json", "README.md"];
+
+						for (const relPath of mobileFiles) {
+							const filePath = path.join(mobileDir, relPath);
+							if (await fs.pathExists(filePath)) {
+								let content = await fs.readFile(filePath, "utf-8");
+								content = content.replace(/__QUARK_APP_NAME__/g, mobileAppName);
+								content = content.replace(
+									/__QUARK_PROJECT_NAME__/g,
+									quarkLink.projectName,
+								);
+								// Replace EAS project ID with a placeholder that users
+								// fill in after running `eas init`
+								content = content.replace(
+									/__QUARK_EAS_PROJECT_ID__/g,
+									"YOUR_EAS_PROJECT_ID",
+								);
+								await fs.writeFile(filePath, content);
+							}
+						}
+
+						await updatePackageJsonName(
+							path.join(mobileDir, "package.json"),
+							scope,
+						);
+
+						// Add EXPO_PUBLIC_API_URL to .env.example
+						const envExamplePath = path.join(projectDir, ".env.example");
+						if (await fs.pathExists(envExamplePath)) {
+							let envContent = await fs.readFile(envExamplePath, "utf-8");
+							if (!envContent.includes("EXPO_PUBLIC_API_URL")) {
+								envContent +=
+									"\n# --- Mobile App ---\nEXPO_PUBLIC_API_URL=http://localhost:3000\n";
+								await fs.writeFile(envExamplePath, envContent);
+							}
+						}
+
+						// Add mobile scripts to root package.json
+						const rootPkgPath = path.join(projectDir, "package.json");
+						if (await fs.pathExists(rootPkgPath)) {
+							const rootPkg = await fs.readJSON(rootPkgPath);
+							rootPkg.scripts = rootPkg.scripts || {};
+							if (!rootPkg.scripts["dev:mobile"]) {
+								rootPkg.scripts["dev:mobile"] =
+									`pnpm --filter @${scope}/mobile start`;
+							}
+							if (!rootPkg.scripts["build:mobile"]) {
+								rootPkg.scripts["build:mobile"] =
+									`pnpm --filter @${scope}/mobile export`;
+							}
+							await fs.writeFile(
+								rootPkgPath,
+								`${JSON.stringify(rootPkg, null, "\t")}\n`,
+							);
+						}
+
+						// Add DEVICE model to Prisma schema
+						const schemaPath = path.join(
+							projectDir,
+							"packages/db/prisma/schema.prisma",
+						);
+						if (await fs.pathExists(schemaPath)) {
+							let schema = await fs.readFile(schemaPath, "utf-8");
+							if (!schema.includes("model Device")) {
+								// Insert Device model after AuditLog
+								const deviceModel = `
+
+// ─── Device Model (Mobile Push Notifications) ────────────────────────────────
+
+model Device {
+  id        String   @id @default(cuid())
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  platform  String   // "ios" | "android"
+  pushToken String
+  deviceId  String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@unique([userId, deviceId])
+  @@index([userId])
+  @@index([pushToken])
+  @@index([createdAt])
+}
+`;
+								schema = schema.replace(
+									/(\/\/ Audit Log Model[\s\S]*?^}\s)/m,
+									`$1${deviceModel}`,
+								);
+								// Add devices relation to User model
+								schema = schema.replace(
+									/(files\s+File\[\])/,
+									"$1\n  devices       Device[]",
+								);
+								await fs.writeFile(schemaPath, schema);
+							}
+						}
+
+						console.log(
+							chalk.green("    ✓ Mobile app scaffolded (apps/mobile)"),
+						);
+						console.log(
+							chalk.green("    ✓ DEVICE model added to Prisma schema"),
+						);
+						console.log(
+							chalk.green("    ✓ EXPO_PUBLIC_API_URL added to .env.example"),
+						);
+						console.log(
+							chalk.dim(
+								"    · API routes (token, refresh, device/register) already in base template",
+							),
+						);
+					}
+					continue;
+				}
+
+				// 1. Copy package template
+				for (const packageName of packageNames) {
+					const packageDir = path.join(projectDir, "packages", packageName);
+					if (await fs.pathExists(packageDir)) {
+						console.log(
+							chalk.dim(
+								`    · packages/${packageName} already exists - skipping copy`,
+							),
+						);
+					} else {
+						await copyTemplate(packageName, packageDir);
+						await updatePackageJsonName(
+							path.join(packageDir, "package.json"),
+							scope,
+						);
+						await rewriteWorkspaceDeps(
+							path.join(packageDir, "package.json"),
+							scope,
+							finalWorkspacePackages,
+						);
+						await replaceImportsInSourceFiles(packageDir, scope);
+						console.log(chalk.green(`    ✓ packages/${packageName}`));
+					}
+				}
+
+				// 2. Handle paired apps/routes
+				for (const pair of featMeta.pairs) {
+					if (pair === "worker") {
+						const workerDir = path.join(projectDir, "apps", "worker");
+						if (await fs.pathExists(workerDir)) {
+							console.log(
+								chalk.dim(`    · apps/worker already exists - skipping copy`),
+							);
+						} else {
+							await copyTemplate("worker", workerDir);
+							await updatePackageJsonName(
+								path.join(workerDir, "package.json"),
+								scope,
+							);
+							await rewriteWorkspaceDeps(
+								path.join(workerDir, "package.json"),
+								scope,
+								finalWorkspacePackages,
+							);
+							await replaceImportsInSourceFiles(workerDir, scope);
+							console.log(chalk.green(`    ✓ apps/worker (paired with jobs)`));
+						}
+					}
+				}
+
+				// 3. Add transpilePackages entries and workspace deps to apps/web/package.json
+				for (const packageName of packageNames) {
+					const scopedPkg = `@${scope}/${packageName}`;
+					await addTranspilePackage(
+						path.join(projectDir, "apps", "web"),
+						scopedPkg,
+					);
+					await addWorkspaceDep(
+						path.join(projectDir, "apps", "web", "package.json"),
+						scopedPkg,
+					);
+				}
+
+				// 5. If adding jobs, also add dep to worker
+				if (feat === "jobs") {
+					await addWorkspaceDep(
+						path.join(projectDir, "apps", "worker", "package.json"),
+						`@${scope}/jobs`,
+					);
+				}
+			}
+
+			// --- Update .quark-link.json ---
+			const allFeatures = [...new Set([...quarkLink.packages, ...toAdd])];
+			quarkLink.packages = allFeatures;
+			quarkLink.hasWorker = allFeatures.includes("jobs");
+			quarkLink.lastAddedFeature = feature;
+			quarkLink.lastModifiedDate = new Date().toISOString();
+			// Track per-feature versions for migration detection
+			if (!quarkLink.featureVersions) quarkLink.featureVersions = {};
+			for (const addedFeature of toAdd) {
+				const featurePkgPath = path.join(
+					projectDir,
+					addedFeature === "mobile" ? "apps" : "packages",
+					addedFeature,
+					"package.json",
+				);
+				if (await fs.pathExists(featurePkgPath)) {
+					const featurePkg = JSON.parse(
+						await fs.readFile(featurePkgPath, "utf-8"),
+					);
+					quarkLink.featureVersions[addedFeature] = featurePkg.version;
+				}
+			}
+			await fs.writeFile(quarkLinkPath, JSON.stringify(quarkLink, null, "	"));
+			console.log(chalk.green(`\n  ✓ .quark-link.json updated`));
+
+			// --- Run pnpm install ---
+			if (!skipInstall) {
+				console.log(chalk.cyan("\n  📦 Installing dependencies..."));
+				try {
+					await execa("pnpm", ["install"], {
+						cwd: projectDir,
+						stdio: "inherit",
+					});
+					console.log(chalk.green(`\n  ✓ Dependencies installed`));
+				} catch {
+					console.warn(
+						chalk.yellow(
+							`\n  ⚠️  pnpm install failed. Run it manually to resolve.`,
+						),
+					);
+				}
+			} else {
+				console.log(chalk.dim("\n  · Skipping pnpm install (--skip-install)"));
+			}
+
+			// --- Success ---
+			console.log(chalk.green.bold(`\n✅ Added "${feature}" successfully!\n`));
+
+			// Feature-specific next steps
+			if (feature === "jobs") {
+				console.log(chalk.cyan("Next steps:"));
+				console.log(chalk.white("  1. Define jobs in packages/jobs/src/"));
+				console.log(
+					chalk.white("  2. Add handlers in apps/worker/src/handlers/"),
+				);
+				console.log(chalk.white("  3. pnpm dev (starts web + worker)\n"));
+			} else if (feature === "ui") {
+				console.log(chalk.cyan("Next steps:"));
+				console.log(
+					chalk.white(
+						`  1. Import components: import { Button } from "@${scope}/ui"`,
+					),
+				);
+				console.log(chalk.white("  2. pnpm dev\n"));
+			} else if (feature === "pwa") {
+				console.log(chalk.cyan("Next steps:"));
+				console.log(
+					chalk.white(
+						"  1. Edit src/app/manifest.json to set your app name and theme color",
+					),
+				);
+				console.log(
+					chalk.white("  2. Replace public/quark.svg with your app icon"),
+				);
+				console.log(
+					chalk.white(
+						"  3. Customize public/sw.js caching strategies if needed",
+					),
+				);
+				console.log(
+					chalk.white("  4. pnpm build (test SW registration in production)\n"),
+				);
+			} else if (feature === "mobile") {
+				console.log(chalk.cyan("Next steps:"));
+				console.log(chalk.white("  1. pnpm install"));
+				console.log(
+					chalk.white("  2. Set EXPO_PUBLIC_API_URL in apps/mobile/.env"),
+				);
+				console.log(chalk.white("  3. pnpm dev (starts web + worker)"));
+				console.log(
+					chalk.white(
+						"  4. pnpm dev:mobile (starts Expo in a second terminal)",
+					),
+				);
+				console.log(
+					chalk.white(
+						"  5. Configure APNs/FCM env vars for push notifications\n",
+					),
+				);
+			}
+
+			console.log(
+				chalk.dim("  Run 'pnpm doctor' to check your project configuration.\n"),
+			);
+		} catch (error) {
+			console.error(
+				chalk.red(`\n✗ Failed to add "${feature}": ${error.message}`),
+			);
+			console.error(chalk.dim(error.stack));
+			process.exit(1);
+		}
+	});
+
+// ---------------------------------------------------------------------------
+// quark skill <feature> - Print an embedded skill for a feature
+// ---------------------------------------------------------------------------
+
+program
+	.command("skill")
+	.argument(
+		"<feature>",
+		"Feature to print a skill for (model, endpoint, dashboard)",
+	)
+	.description("Print an embedded skill for a feature")
+	.action(async (feature) => {
+		const skillName =
+			feature === "model"
+				? "add-model"
+				: feature === "endpoint"
+					? "add-endpoint"
+					: feature === "dashboard"
+						? "add-dashboard"
+						: feature;
+		const skillPath = path.join(
+			templatesDir,
+			"base-project",
+			"skills",
+			skillName,
+			"SKILL.md",
+		);
+
+		if (!(await fs.pathExists(skillPath))) {
+			console.error(
+				chalk.red(
+					`✗ No skill found for "${feature}". Available: model, endpoint, dashboard`,
+				),
+			);
+			process.exit(1);
+		}
+
+		const skill = await fs.readFile(skillPath, "utf-8");
+		console.log(skill);
+	});
+
+/**
+ * Read the installed version of a package from node_modules.
+ * Returns null if the package is not installed.
+ * @param {string} cwd - Project root
+ * @param {string} packageName - e.g. "@techstream/quark-core"
+ * @returns {Promise<string|null>}
+ */
+async function getInstalledVersion(cwd, packageName) {
+	try {
+		const pkgPath = path.join(
+			cwd,
+			"node_modules",
+			...packageName.split("/"),
+			"package.json",
+		);
+		const { version } = await fs.readJSON(pkgPath);
+		return version ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Fetch the latest published version of a package from the npm registry.
+ * Returns null on network failure so the caller can degrade gracefully.
+ * @param {string} packageName
+ * @returns {Promise<string|null>}
+ */
+async function getLatestNpmVersion(packageName) {
+	try {
+		const { stdout } = await execa("npm", [
+			"view",
+			packageName,
+			"version",
+			"--json",
+		]);
+		return JSON.parse(stdout);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * quark-update command
+ * Updates Quark core infrastructure in a scaffolded project
+ */
+program
+	.command("update")
+	.description("Update Quark packages in the current project")
+	.option("--check", "Check for updates without applying")
+	.option(
+		"--scaffold-check",
+		"Report drift in scaffold-managed files without applying changes",
+	)
+	.option(
+		"--fail-on-drift",
+		"Exit with status 1 when scaffold drift is detected (use with --scaffold-check)",
+	)
+	.option("--force", "Skip safety checks")
+	.action(async (options) => {
+		console.log(chalk.blue.bold(`\n🔄 Quark Package Update\n`));
+
+		if (options.failOnDrift && !options.scaffoldCheck) {
+			console.error(
+				chalk.red("✗ --fail-on-drift requires --scaffold-check.\n"),
+			);
+			process.exit(1);
+		}
+
+		// Check if .quark-link.json exists
+		const quarkLinkPath = path.join(process.cwd(), ".quark-link.json");
+		if (!(await fs.pathExists(quarkLinkPath))) {
+			console.error(
+				chalk.red("✗ .quark-link.json not found. Are you in a Quark project?"),
+			);
+			process.exit(1);
+		}
+
+		const quarkLink = await fs.readJSON(quarkLinkPath);
+
+		// The packages this command manages
+		const MANAGED_PACKAGES = [
+			"@techstream/quark-core",
+			"@techstream/quark-create-app",
+		];
+
+		// Snapshot installed versions before any update
+		const before = {};
+		for (const name of MANAGED_PACKAGES) {
+			before[name] = await getInstalledVersion(process.cwd(), name);
+		}
+
+		console.log(chalk.cyan(`Scaffolded:      ${quarkLink.scaffoldedDate}`));
+		console.log(
+			chalk.cyan(
+				`Installed core:  ${before["@techstream/quark-core"] ?? quarkLink.quarkVersion ?? "unknown"}\n`,
+			),
+		);
+
+		if (options.check) {
+			// Query npm for latest versions and report the delta
+			console.log(chalk.yellow("Checking npm registry for updates...\n"));
+			let anyUpdates = false;
+			for (const name of MANAGED_PACKAGES) {
+				const installed = before[name];
+				const latest = await getLatestNpmVersion(name);
+				if (!latest) {
+					console.log(chalk.dim(`  ${name}: registry unreachable`));
+					continue;
+				}
+				if (!installed || installed === latest) {
+					console.log(chalk.green(`  ✓ ${name} ${latest} - up to date`));
+				} else {
+					console.log(
+						chalk.yellow(`  ↑ ${name}: ${installed} → ${chalk.bold(latest)}`),
+					);
+					anyUpdates = true;
+				}
+			}
+			if (anyUpdates) {
+				console.log(chalk.white("\n  Run without --check to apply updates.\n"));
+			} else {
+				console.log(chalk.dim("\n  Nothing to update.\n"));
+			}
+		}
+
+		if (options.scaffoldCheck) {
+			const scaffoldReport = await reportScaffoldDrift(
+				process.cwd(),
+				quarkLink,
+			);
+			const hasDrift =
+				scaffoldReport.changed.length > 0 || scaffoldReport.missing.length > 0;
+			if (options.failOnDrift && hasDrift) {
+				console.error(
+					chalk.red("✗ Drift detected and --fail-on-drift was set.\n"),
+				);
+				process.exitCode = 1;
+			}
+		}
+
+		if (options.check || options.scaffoldCheck) {
+			return;
+		}
+
+		try {
+			// Guard: check for both unstaged and staged changes (project-scoped)
+			if (!options.force && (await hasUncommittedChanges(process.cwd()))) {
+				console.log(
+					chalk.yellow(
+						"⚠️  You have uncommitted changes. Commit or stash them first.",
+					),
+				);
+				console.log(
+					chalk.white("Use --force to skip this check (not recommended).\n"),
+				);
+				process.exit(1);
+			}
+
+			// Run pnpm update for all managed packages
+			console.log(chalk.cyan("📦 Updating Quark packages...\n"));
+			await execa("pnpm", ["update", ...MANAGED_PACKAGES], {
+				cwd: process.cwd(),
+				stdio: "inherit",
+			});
+
+			// Snapshot installed versions after update
+			const after = {};
+			for (const name of MANAGED_PACKAGES) {
+				after[name] = await getInstalledVersion(process.cwd(), name);
+			}
+
+			// Report the delta
+			console.log(chalk.cyan("\n📋 Update summary:\n"));
+			for (const name of MANAGED_PACKAGES) {
+				const was = before[name];
+				const now = after[name];
+				if (!now) continue;
+				if (was && was !== now) {
+					console.log(chalk.green(`  ✓ ${name}: ${was} → ${chalk.bold(now)}`));
+				} else {
+					console.log(chalk.dim(`  · ${name}: ${now} (already current)`));
+				}
+			}
+
+			// Persist the new core version - keep previous on failure, never write garbage
+			const newCoreVersion =
+				after["@techstream/quark-core"] ?? quarkLink.quarkVersion;
+			quarkLink.quarkVersion = newCoreVersion;
+			quarkLink.updatedDate = new Date().toISOString();
+			await fs.writeFile(quarkLinkPath, JSON.stringify(quarkLink, null, "	"));
+
+			// Run lint to surface any API breakage from the update
+			console.log(chalk.cyan("\n🔍 Running lint to check for breakage...\n"));
+			try {
+				await execa("pnpm", ["lint"], {
+					cwd: process.cwd(),
+					stdio: "inherit",
+				});
+				console.log(chalk.green("\n  ✓ Lint passed\n"));
+			} catch {
+				console.log(
+					chalk.yellow(
+						"\n  ⚠️  Lint reported issues - review before committing.\n",
+					),
+				);
+			}
+
+			console.log(chalk.green("✅ Quark updated successfully!\n"));
+			console.log(chalk.cyan("Next steps:"));
+			console.log(chalk.white(`  1. pnpm test`));
+			console.log(
+				chalk.white(`  2. git add . && git commit -m "chore: update Quark"\n`),
+			);
+		} catch (error) {
+			console.error(chalk.red(`\n✗ Update failed: ${error.message}\n`));
+			process.exit(1);
+		}
+	});
+
+// ---------------------------------------------------------------------------
+// quark deploy - Deploy and inspect
+// ---------------------------------------------------------------------------
+
+const deployCmd = program
+	.command("deploy")
+	.description("Deploy a Quark project to Railway");
+
+deployCmd
+	.command("railway")
+	.description("Deploy to Railway (web + worker + Postgres + Redis)")
+	.option(
+		"--project-name <name>",
+		"Railway project name (creates a new project)",
+	)
+	.option("--project-id <id>", "Existing Railway project ID to link to")
+	.option("--environment <env>", "Railway environment (default: production)")
+	.option("--no-provision", "Skip provisioning PostgreSQL and Redis plugins")
+	.option("--dry-run", "Validate configuration without deploying")
+	.action(async (options) => {
+		const { deployToRailway } = await import("./deploy/deploy.js");
+
+		if (options.dryRun) {
+			const { inspectProject } = await import("./deploy/inspect.js");
+			console.log(
+				chalk.yellow("\n⚠  Dry run - validating deployment configuration\n"),
+			);
+			await inspectProject({ cwd: process.cwd() });
+			console.log(
+				chalk.green(
+					"✔ Configuration valid. Run without --dry-run to deploy.\n",
+				),
+			);
+			return;
+		}
+
+		try {
+			await deployToRailway({
+				cwd: process.cwd(),
+				projectName: options.projectName,
+				projectId: options.projectId,
+				environment: options.environment,
+				provision: options.provision,
+			});
+		} catch (error) {
+			console.error(chalk.red(`\n✖ Deploy failed: ${error.message}\n`));
+			process.exit(1);
+		}
+	});
+
+deployCmd
+	.command("inspect")
+	.description("Inspect project deployment readiness")
+	.action(async () => {
+		const { inspectProject } = await import("./deploy/inspect.js");
+		await inspectProject({ cwd: process.cwd() });
+	});
+
+deployCmd
+	.command("status")
+	.description("Check deployed service status")
+	.action(async () => {
+		const { inspectProject } = await import("./deploy/inspect.js");
+		await inspectProject({ cwd: process.cwd() });
+	});
+
+program.parse();