create-kubojs 0.2.1 → 0.3.0

package/dist/{src-CvkZZND8.mjs → src-9z53Xnti.mjs}

@@ -11,15 +11,16 @@ import path from "node:path";
 import envPaths from "env-paths";
 import fs from "fs-extra";
 import { fileURLToPath } from "node:url";
-import { desktopWebFrontends as desktopWebFrontends$3, getPaymentCompatibilityIssue, normalizePayments } from "@kubojs/types";
-import { EMBEDDED_TEMPLATES, EMBEDDED_TEMPLATES as EMBEDDED_TEMPLATES$1, GeneratorError, GeneratorError as GeneratorError$1, TEMPLATE_COUNT, VirtualFileSystem, VirtualFileSystem as VirtualFileSystem$1, dependencyVersionMap, generate, generate as generate$1, generateReproducibleCommand, processAddonTemplates, processAddonsDeps, processEnvVariables, processPackageConfigs, processTemplateString, processTurboConfig, processVitePlusConfig } from "@kubojs/template-generator";
+import { ADDON_COMPATIBILITY, COMMUNICATION_PRODUCT_NAMES, CONVEX_BETTER_AUTH_INCOMPATIBLE_FRONTENDS, CONVEX_BETTER_AUTH_SUPPORTED_FRONTENDS, FRONTEND_VALUES, KUBO_CLI_TITLE, KUBO_TITLE_COLORS, KuboConfigFileSchema, KubojsConfigFileSchema, WEB_FRONTENDS_REQUIRING_ORPC, backendAllowsAiExample, backendAllowsApi, backendAllowsOnlyNoneApi, evaluate, getCommunicationCompatibilityIssue, getPaymentCompatibilityIssue, isCommunicationProvider, isWebFrontend, normalizeCommunication, normalizeCommunication as normalizeCommunication$2, normalizeLegacyKuboConfig, normalizeObservability, normalizePayments } from "@kubojs/types";
+import { EMBEDDED_TEMPLATES, EMBEDDED_TEMPLATES as EMBEDDED_TEMPLATES$1, GeneratorError, GeneratorError as GeneratorError$1, KUBO_CONFIG_FILE, TEMPLATE_COUNT, VirtualFileSystem, VirtualFileSystem as VirtualFileSystem$1, applyAddonCatalog, dependencyVersionMap, generate, generate as generate$1, generateReproducibleCommand, getWebAppPath, isBinaryFile, processEnvVariables, processPackageConfigs, processTemplateString, resolveLayout, serializeKuboConfigFile } from "@kubojs/template-generator";
 import { consola, createConsola } from "consola";
 import { AsyncLocalStorage } from "node:async_hooks";
 import gradient from "gradient-string";
 import { $, execa } from "execa";
-import { writeTree } from "@kubojs/template-generator/fs-writer";
+import { writeSelected, writeTree } from "@kubojs/template-generator/fs-writer";
 import { ConfirmPrompt, GroupMultiSelectPrompt, MultiSelectPrompt, SelectPrompt, TextPrompt, isCancel as isCancel$1, isCancel as isCancel$2 } from "@clack/core";
-import { applyEdits, modify, parse } from "jsonc-parser";
+import { createJiti } from "jiti";
+import { parse } from "jsonc-parser";
 import os from "node:os";
 import { format } from "oxfmt";
 import { Generator, configSchema } from "@tanstack/router-generator";
@@ -30,9 +31,30 @@ const KUBO_COLORS = {
 	orange: "#e08a2e",
 	cream: "#f2ede0"
 };
-const supportsTrueColor = process.env.NO_COLOR === void 0 && process.env.FORCE_COLOR !== "0" && (process.env.FORCE_COLOR !== void 0 || process.stdout.isTTY === true);
+const TRUECOLOR_COLORTERM = new Set(["24bit", "truecolor"]);
+function parseForceColor(forceColor) {
+	if (forceColor === void 0 || forceColor === "") return void 0;
+	if (forceColor === "true") return 1;
+	const parsed = Number.parseInt(forceColor, 10);
+	return Number.isNaN(parsed) ? 1 : parsed;
+}
+function supportsAnsiColor(env = process.env, terminal = process.stdout) {
+	if (env.NO_COLOR !== void 0) return false;
+	const forceColor = parseForceColor(env.FORCE_COLOR);
+	if (forceColor === 0) return false;
+	if (forceColor !== void 0) return true;
+	return terminal.isTTY === true;
+}
+function supportsTrueColor(env = process.env, terminal = process.stdout) {
+	if (!supportsAnsiColor(env, terminal)) return false;
+	const forceColor = parseForceColor(env.FORCE_COLOR);
+	if (forceColor !== void 0) return forceColor >= 3;
+	const colorTerm = env.COLORTERM?.toLowerCase();
+	if (colorTerm !== void 0 && TRUECOLOR_COLORTERM.has(colorTerm)) return true;
+	return env.TERM?.toLowerCase().includes("direct") === true;
+}
 function createColor(hex, fallback) {
-	if (!supportsTrueColor) return fallback;
+	if (!supportsTrueColor()) return fallback;
 	const red = Number.parseInt(hex.slice(1, 3), 16);
 	const green = Number.parseInt(hex.slice(3, 5), 16);
 	const blue = Number.parseInt(hex.slice(5, 7), 16);
@@ -66,7 +88,7 @@ const DEFAULT_CONFIG_BASE = {
 	auth: "better-auth",
 	payments: [],
 	observability: ["getmonitor"],
-	communication: "none",
+	communication: ["arara"],
 	addons: ["turborepo"],
 	examples: [],
 	testing: [],
@@ -93,27 +115,6 @@ function getDefaultConfig() {
 	};
 }
 const DEFAULT_CONFIG = getDefaultConfig();
-const ADDON_COMPATIBILITY = {
-	pwa: [
-		"tanstack-router",
-		"react-router",
-		"solid",
-		"next"
-	],
-	tauri: desktopWebFrontends$3,
-	electrobun: desktopWebFrontends$3,
-	biome: [],
-	husky: [],
-	lefthook: [],
-	turborepo: [],
-	"vite-plus": [],
-	mcp: [],
-	oxlint: [],
-	opentui: [],
-	skills: [],
-	"s3-storage": [],
-	none: []
-};
 //#endregion
 //#region src/utils/context.ts
 const cliStorage = new AsyncLocalStorage();
@@ -283,6 +284,14 @@ var AddonSetupError = class extends TaggedError("AddonSetupError")() {
 	}
 };
 /**
+* Invalid kubo.config.ts / kubojs.jsonrc content or failed config module load
+*/
+var KuboConfigInvalidError = class extends TaggedError("KuboConfigInvalidError")() {
+	constructor(args) {
+		super(args);
+	}
+};
+/**
 * Create a user cancelled error Result
 */
 function userCancelled(message) {
@@ -440,34 +449,16 @@ async function clearHistory() {
 }
 //#endregion
 //#region src/utils/render-title.ts
-const TITLE_TEXT = `
-██╗  ██╗██╗   ██╗██████╗  ██████╗
-██║ ██╔╝██║   ██║██╔══██╗██╔═══██╗
-█████╔╝ ██║   ██║██████╔╝██║   ██║
-██╔═██╗ ██║   ██║██╔══██╗██║   ██║
-██║  ██╗╚██████╔╝██████╔╝╚██████╔╝
-╚═╝  ╚═╝ ╚═════╝ ╚═════╝  ╚═════╝
-`;
-const KUBO_TITLE_COLORS = [
-	"#D6A72B",
-	"#F5D76E",
-	"#E0B43E",
-	"#E08A2E",
-	"#E0B43E",
-	"#E8A43A",
-	"#E08A2E",
-	"#E08A2E",
-	"#C49314",
-	"#E8C978",
-	"#E5D3A5"
-];
+const TITLE_TEXT = KUBO_CLI_TITLE;
 const renderTitle = () => {
 	const terminalWidth = process.stdout.columns || 80;
 	const titleLines = TITLE_TEXT.split("\n");
-	if (terminalWidth < Math.max(...titleLines.map((line) => line.length))) {
-		const simplifiedTitle = `Kubo`;
-		console.log(gradient([...KUBO_TITLE_COLORS]).multiline(simplifiedTitle));
-	} else console.log(gradient([...KUBO_TITLE_COLORS]).multiline(TITLE_TEXT));
+	const title = terminalWidth < Math.max(...titleLines.map((line) => line.length)) ? "Kubo" : TITLE_TEXT;
+	if (supportsTrueColor()) {
+		console.log(gradient([...KUBO_TITLE_COLORS]).multiline(title));
+		return;
+	}
+	console.log(pc.yellow(title));
 };
 //#endregion
 //#region src/commands/history.ts
@@ -566,24 +557,224 @@ import * as import__kubojs_types from "@kubojs/types";
 __reExport(types_exports, import__kubojs_types);
 //#endregion
 //#region src/utils/compatibility.ts
-const WEB_FRAMEWORKS = [
-	"tanstack-router",
-	"react-router",
-	"tanstack-start",
-	"next",
-	"nuxt",
-	"svelte",
-	"solid",
-	"astro"
-];
+const WEB_FRAMEWORKS = FRONTEND_VALUES.filter(isWebFrontend);
+//#endregion
+//#region src/utils/compatibility-adapter.ts
+const NESTJS_MESSAGES = {
+	"backend-api": "NestJS currently supports no API layer yet. Please use '--api none'.",
+	"backend-auth": "NestJS backend currently supports Better Auth or no authentication. Please use '--auth better-auth' or '--auth none'.",
+	"backend-database": "NestJS backend currently supports PostgreSQL as its database. Please use '--database postgres'.",
+	"backend-orm": "NestJS backend currently supports Prisma as its ORM. Please use '--orm prisma'.",
+	"example-ai-backend": "The 'ai' example is not supported with NestJS yet. Please remove 'ai' from --examples.",
+	payment: "Payment integrations are not supported with NestJS yet. Please remove payment providers."
+};
+const FIELD_FLAGS = {
+	runtime: "--runtime",
+	database: "--database",
+	orm: "--orm",
+	api: "--api",
+	auth: "--auth",
+	dbSetup: "--db-setup",
+	serverDeploy: "--server-deploy",
+	communication: "--communication",
+	payments: "--payments"
+};
+function validationErr(message, compatibilityCode) {
+	return Result.err(new ValidationError({
+		message,
+		compatibilityCode
+	}));
+}
+function normalizeCompatibilityInput(config) {
+	return config.payments === "none" ? {
+		...config,
+		payments: []
+	} : config;
+}
+function firstIncompatibleFrontend(frontends) {
+	return [
+		"nuxt",
+		"svelte",
+		"solid",
+		"astro"
+	].find((frontend) => frontends.includes(frontend));
+}
+function getBackendOwnedMessage(issue, config) {
+	const field = issue.fields[0];
+	const flag = FIELD_FLAGS[field] ?? field;
+	const backend = config.backend;
+	if (backend === "convex") return `Convex backend requires '${flag} none'. Please remove the ${flag} flag or set it to 'none'.`;
+	if (backend === "none") return `Backend 'none' requires '${flag} none'. Please remove the ${flag} flag or set it to 'none'.`;
+	return `${backend ?? "This backend"} owns ${field}; choose a compatible value.`;
+}
+function getDatabaseMessage(config) {
+	if (config.orm === "mongoose") return "Mongoose ORM requires MongoDB database. Please use '--database mongodb' or choose a different ORM.";
+	if (config.orm === "drizzle" && config.database === "mongodb") return "Drizzle ORM does not support MongoDB. Please use '--orm mongoose' or '--orm prisma' or choose a different database.";
+	if (config.database && config.database !== "none" && config.orm === "none") return "Database selection requires an ORM. Please choose '--orm drizzle', '--orm prisma', or '--orm mongoose'.";
+	return "ORM selection requires a database. Please choose a database or set '--orm none'.";
+}
+function getDatabaseSetupMessage(config) {
+	if (!config.database || config.database === "none") return "Database setup requires a database. Please choose a database or set '--db-setup none'.";
+	switch (config.dbSetup) {
+		case "turso": return "Turso setup requires SQLite database. Please use '--database sqlite' or choose a different setup.";
+		case "neon": return "Neon setup requires PostgreSQL database. Please use '--database postgres' or choose a different setup.";
+		case "prisma-postgres": return "Prisma PostgreSQL setup requires PostgreSQL database. Please use '--database postgres' or choose a different setup.";
+		case "planetscale": return "PlanetScale setup requires PostgreSQL or MySQL database. Please use '--database postgres' or '--database mysql' or choose a different setup.";
+		case "mongodb-atlas": return "MongoDB Atlas setup requires MongoDB database. Please use '--database mongodb' or choose a different setup.";
+		case "supabase": return "Supabase setup requires PostgreSQL database. Please use '--database postgres' or choose a different setup.";
+		case "d1": return "Cloudflare D1 setup requires SQLite database.";
+		case "docker":
+			if (config.database === "sqlite") return "Docker setup is not compatible with SQLite database. SQLite is file-based and doesn't require Docker. Please use '--database postgres', '--database mysql', '--database mongodb', or choose a different setup.";
+			return "Docker setup is not compatible with Cloudflare Workers runtime. Workers runtime uses serverless databases (D1) and doesn't support local Docker containers. Please use '--db-setup d1' for SQLite or choose a different runtime.";
+		default: return "Database setup is not compatible with the selected database.";
+	}
+}
+function getServerDeployMessage(config) {
+	const serverDeploy = config.serverDeploy;
+	if (!config.backend || config.backend === "none") return "'--server-deploy' requires a backend. Please select a backend or set '--server-deploy none'.";
+	if (serverDeploy === "cloudflare") {
+		if (config.runtime !== "workers") return `Server deployment '${serverDeploy}' requires '--runtime workers'. Please use '--runtime workers' or choose a different server deployment.`;
+		return "Cloudflare server deployment requires the Hono backend. Please use '--backend hono' or choose a different server deployment.";
+	}
+	if (serverDeploy === "none" && config.runtime === "workers") return "Cloudflare Workers runtime requires a server deployment. Please choose 'cloudflare' for --server-deploy.";
+	if (config.backend === "convex" || config.backend === "self") return `'--server-deploy ${serverDeploy}' requires a separate server backend (hono, express, fastify, elysia, nestjs). For a fullstack 'self' backend, use '--web-deploy ${serverDeploy}' instead.`;
+	return `'--server-deploy ${serverDeploy}' is not compatible with '--runtime workers'. Use '--runtime bun' or '--runtime node', or choose '--server-deploy cloudflare'.`;
+}
+function getExampleMessage(config, issue) {
+	if (issue.code === "example-ai-backend" && config.backend === "none") return "The 'ai' example requires a backend.";
+	if (issue.code === "example-ai-backend" && config.backend === "nestjs") return NESTJS_MESSAGES[issue.code] ?? "The selected backend does not support this example.";
+	if (issue.code === "example-ai-frontend") {
+		const incompatible = firstIncompatibleFrontend(config.frontend ?? []);
+		if (config.backend === "convex" && (incompatible === "nuxt" || incompatible === "svelte")) return "The 'ai' example with Convex backend only supports React-based frontends (Next.js, TanStack Router, TanStack Start, React Router). Svelte and Nuxt are not supported with Convex AI.";
+		return `The 'ai' example is not compatible with the ${incompatible ? incompatible.charAt(0).toUpperCase() + incompatible.slice(1) : "selected"} frontend.`;
+	}
+	if (issue.code === "example-todo-database") return "The 'todo' example requires a database. Cannot use --examples todo when database is 'none'.";
+	if (issue.code === "example-todo-api") return "Cannot use '--examples todo' when '--api' is set to 'none'.";
+	return "The selected example is not compatible with this project configuration.";
+}
+function getAddonMessage(issue, config) {
+	if (issue.code === "addon-task-runner") return "Cannot combine 'turborepo' and 'vite-plus' addons. Choose one task runner.";
+	if (issue.code === "addon-linter") return "Cannot combine 'biome' and 'oxlint' addons. Choose one code-quality linter.";
+	const addon = issue.values?.[0] ?? "selected";
+	if (issue.code === "addon-backend") return `${addon} addon requires a separate backend or no backend because backend 'self' emits server routes that cannot be bundled as static desktop assets.`;
+	if (issue.code === "addon-auth") {
+		if (config.auth === "clerk" && config.frontend?.includes("react-router")) return `${addon} addon forces React Router into a static export, but Clerk on React Router requires SSR middleware. Remove the addon or use a different auth/frontend.`;
+		return `${addon} addon is not compatible with Convex Better Auth on Next.js or TanStack Start because those templates use server auth bootstrap and cannot be exported as static desktop assets.`;
+	}
+	return `${addon} addon requires one of these frontends: ${(isAddon(addon) ? ADDON_COMPATIBILITY[addon] : []).join(", ")}`;
+}
+function isAddon(value) {
+	return Object.hasOwn(ADDON_COMPATIBILITY, value);
+}
+function getCompatibilityMessage(issue, config, options) {
+	if (issue.code.startsWith("backend-none-") || issue.code.startsWith("backend-convex-")) {
+		if (issue.code === "backend-convex-frontend") return `The following frontends are not compatible with '--backend convex': ${(config.frontend ?? []).filter((frontend) => frontend === "solid" || frontend === "astro").join(", ")}. Please choose a different frontend or backend.`;
+		if (issue.code === "backend-convex-better-auth-frontend") {
+			const incompatible = (config.frontend ?? []).filter((frontend) => includesValue(CONVEX_BETTER_AUTH_INCOMPATIBLE_FRONTENDS, frontend));
+			if (incompatible.length > 0) return `Better Auth with '--backend convex' is not compatible with the following frontends: ${incompatible.join(", ")}. Please use a React-based web frontend (next, tanstack-start, tanstack-router, react-router), a supported native frontend, or choose a different auth provider.`;
+			return `Better Auth with '--backend convex' requires a supported frontend (${CONVEX_BETTER_AUTH_SUPPORTED_FRONTENDS.join(", ")}).`;
+		}
+		return getBackendOwnedMessage(issue, config);
+	}
+	if (issue.code === "backend-self-frontend") return "Backend 'self' (fullstack) currently only supports Next.js, TanStack Start, Nuxt, SvelteKit, and Astro frontends. Please use --frontend next, --frontend tanstack-start, --frontend nuxt, --frontend svelte, or --frontend astro.";
+	if (issue.code === "backend-self-runtime") return "Backend 'self' (fullstack) requires '--runtime none'. Please remove the --runtime flag or set it to 'none'.";
+	if (issue.code === "frontend-web-cardinality") return "Cannot select multiple web frameworks. Choose only one of: tanstack-router, tanstack-start, react-router, next, nuxt, svelte, solid, astro";
+	if (issue.code === "frontend-native-cardinality") return "Cannot select multiple native frameworks. Choose only one of: native-bare, native-uniwind, native-unistyles";
+	if (issue.code === "backend-workers") {
+		if (options?.runtime === "workers") return `Cloudflare Workers runtime (--runtime workers) is only supported with Hono backend (--backend hono). Current backend: ${config.backend}. Please use '--backend hono' or choose a different runtime.`;
+		return `Backend '${config.backend}' is not compatible with Cloudflare Workers runtime. Cloudflare Workers runtime is only supported with Hono backend. Please use '--backend hono' or choose a different runtime.`;
+	}
+	if (issue.code === "backend-workers-database") {
+		if (options?.runtime === "workers") return "Cloudflare Workers runtime (--runtime workers) is not compatible with MongoDB database. MongoDB requires Prisma or Mongoose ORM, but Workers runtime only supports Drizzle or Prisma ORM. Please use a different database or runtime.";
+		return "MongoDB database is not compatible with Cloudflare Workers runtime. MongoDB requires Prisma or Mongoose ORM, but Workers runtime only supports Drizzle or Prisma ORM. Please use a different database or runtime.";
+	}
+	if (issue.code === "runtime-required") return "'--runtime none' is only supported with '--backend convex', '--backend none', or '--backend self'. Please choose 'bun', 'node', or remove the --runtime flag.";
+	if (issue.code === "backend-api" || issue.code === "backend-auth" || issue.code === "backend-database" || issue.code === "backend-orm") {
+		if (config.backend === "nestjs") return NESTJS_MESSAGES[issue.code] ?? "The selected backend does not support this value.";
+		if (issue.code === "backend-api" && config.api === "orval") return "Orval API requires the Hono backend. Please use '--backend hono' or choose tRPC/oRPC.";
+	}
+	if (issue.code === "api-frontend") {
+		const frontend = firstIncompatibleFrontend(config.frontend ?? []);
+		return `tRPC API is not supported with '${frontend}' frontend. Please use --api orpc or --api none or remove '${frontend}' from --frontend.`;
+	}
+	if (issue.code === "database-orm") return getDatabaseMessage(config);
+	if (issue.code === "database-setup" || issue.code === "database-setup-target") {
+		if (issue.code === "database-setup-target") return "Cloudflare D1 setup requires SQLite database and either Cloudflare Workers runtime with server deployment or backend 'self' with Cloudflare web deployment.";
+		return getDatabaseSetupMessage(config);
+	}
+	if (issue.code === "web-deploy-frontend") return "'--web-deploy' requires a web frontend. Please select a web frontend or set '--web-deploy none'.";
+	if (issue.code === "server-deploy-backend" || issue.code === "server-deploy-runtime" || issue.code === "server-deploy-cloudflare") return getServerDeployMessage(config);
+	if (issue.code === "auth-backend") return "Clerk exige backend Convex, Hono, Express, Fastify, Elysia ou Next.js/TanStack Start fullstack";
+	if (issue.code === "auth-frontend") return "Clerk authentication is not compatible with the selected frontend. Please choose a different frontend or auth provider.";
+	if (issue.code === "addon-task-runner" || issue.code === "addon-linter" || issue.code === "addon-frontend" || issue.code === "addon-backend" || issue.code === "addon-auth") return getAddonMessage(issue, config);
+	if (issue.code === "testing-frontend") return "playwright testing requires a web frontend";
+	if (issue.code === "example-todo-database" || issue.code === "example-todo-api" || issue.code === "example-todo-orval" || issue.code === "example-ai-frontend" || issue.code === "example-ai-backend") {
+		if (issue.code === "example-todo-orval") return "The Orval API layer does not support the generated todo example yet. Please remove 'todo' from --examples or choose tRPC/oRPC.";
+		return getExampleMessage(config, issue);
+	}
+	if (issue.code === "communication") {
+		const failingProvider = normalizeCommunication(config.communication ?? []).find((candidate) => {
+			if (!isCommunicationProvider(candidate)) return false;
+			return getCommunicationCompatibilityIssue({
+				provider: candidate,
+				backend: config.backend,
+				runtime: config.runtime,
+				serverDeploy: config.serverDeploy
+			});
+		});
+		if (!failingProvider || !isCommunicationProvider(failingProvider)) return "Communication is incompatible with the selected configuration.";
+		return getCommunicationCompatibilityIssue({
+			provider: failingProvider,
+			backend: config.backend,
+			runtime: config.runtime,
+			serverDeploy: config.serverDeploy
+		}) === "workers-unsupported" ? "AraraHQ requires the official Node SDK and is not compatible with Edge/Workers runtimes. Use a Node/Bun server deployment or Convex Node Action." : `${COMMUNICATION_PRODUCT_NAMES[failingProvider]} communication requires a server backend. Please choose a backend or use '--communication none'.`;
+	}
+	if (issue.code === "payment") {
+		const paymentValues = config.payments;
+		const provider = (Array.isArray(paymentValues) ? paymentValues : typeof paymentValues === "string" ? [paymentValues] : []).find((candidate) => getPaymentCompatibilityIssue({
+			provider: candidate,
+			backend: config.backend,
+			frontends: config.frontend,
+			database: config.database,
+			orm: config.orm
+		}));
+		if (config.backend === "nestjs") return NESTJS_MESSAGES.payment;
+		const paymentIssue = provider ? getPaymentCompatibilityIssue({
+			provider,
+			backend: config.backend,
+			frontends: config.frontend,
+			database: config.database,
+			orm: config.orm
+		}) : null;
+		const label = provider === "stripe" ? "Stripe" : "AbacatePay";
+		if (paymentIssue === "convex-unsupported") return `${label} payments is not compatible with '--backend convex'. Please use a server backend or backend 'self'.`;
+		if (paymentIssue === "requires-web-frontend") return `${label} payments requires a web frontend. Please choose next, tanstack-start, tanstack-router, react-router, nuxt, svelte, solid, or astro.`;
+		if (paymentIssue === "native-only-unsupported") return `${label} payments is not compatible with native-only frontends. Please add a supported web frontend or leave payments unselected.`;
+		if (paymentIssue === "sql-database-required") return "AbacatePay payments v1 requires a SQL database with Drizzle or Prisma. MongoDB and Mongoose are not supported.";
+		return `${label} payments is not compatible with the selected project configuration.`;
+	}
+	return "The selected project configuration is not compatible.";
+}
+function validateWithCompatibilityEvaluator(config, options, preferredCodes = []) {
+	const normalizedConfig = normalizeCompatibilityInput(config);
+	const issues = evaluate(normalizedConfig).issues;
+	const firstIssue = preferredCodes.map((code) => issues.find((candidate) => candidate.code === code)).find((candidate) => candidate !== void 0) ?? issues[0];
+	return firstIssue ? validationErr(getCompatibilityMessage(firstIssue, normalizedConfig, options), firstIssue.code) : Result.ok(void 0);
+}
+function getCompatibilityValidationMessage(issue, config, options) {
+	return getCompatibilityMessage(issue, config, options);
+}
+function includesValue(values, value) {
+	return values.some((candidate) => candidate === value);
+}
 //#endregion
 //#region src/utils/compatibility-rules.ts
 const TASK_RUNNER_ADDONS$1 = ["turborepo", "vite-plus"];
 /** Mutually exclusive code-quality linters (one slot). */
 const LINTER_ADDONS = ["biome", "oxlint"];
-const STATIC_DESKTOP_ADDONS = ["tauri", "electrobun"];
 function isLinterAddon(addon) {
-	return LINTER_ADDONS.includes(addon);
+	return LINTER_ADDONS.some((value) => value === addon);
 }
 /**
 * When adding a code-quality linter, drop sibling linters so only one remains.
@@ -604,203 +795,96 @@ function mergeAddonsExclusive(existingAddons, addonsToAdd) {
 		removedAddons: [...removed]
 	};
 }
-const TAURI_STATIC_EXPORT_FRONTENDS = ["next", "tanstack-start"];
-const CONVEX_BETTER_AUTH_INCOMPATIBLE_FRONTENDS = [
-	"nuxt",
-	"svelte",
-	"solid",
-	"astro"
-];
-const CONVEX_BETTER_AUTH_SUPPORTED_FRONTENDS = [
-	"tanstack-router",
-	"react-router",
-	"tanstack-start",
-	"next",
-	"native-bare",
-	"native-uniwind",
-	"native-unistyles"
-];
-function validationErr$1(message) {
-	return Result.err(new ValidationError({ message }));
-}
-function isWebFrontend(value) {
+function isWebFrontend$1(value) {
 	return WEB_FRAMEWORKS.includes(value);
 }
 function isPlaywrightAllowed(frontends = []) {
-	return frontends.some((frontend) => isWebFrontend(frontend));
+	return frontends.some((frontend) => isWebFrontend$1(frontend));
 }
 function validateTestingAgainstFrontends(testing = [], frontends = []) {
-	if (testing.includes("playwright") && !isPlaywrightAllowed(frontends)) return validationErr$1("playwright testing requires a web frontend");
-	return Result.ok(void 0);
-}
-function splitFrontends(values = []) {
-	return {
-		web: values.filter((f) => isWebFrontend(f)),
-		native: values.filter((f) => f === "native-bare" || f === "native-uniwind" || f === "native-unistyles")
-	};
-}
-function ensureSingleWebAndNative(frontends) {
-	const { web, native } = splitFrontends(frontends);
-	if (web.length > 1) return validationErr$1("Cannot select multiple web frameworks. Choose only one of: tanstack-router, tanstack-start, react-router, next, nuxt, svelte, solid, astro");
-	if (native.length > 1) return validationErr$1("Cannot select multiple native frameworks. Choose only one of: native-bare, native-uniwind, native-unistyles");
-	return Result.ok(void 0);
-}
-const FULLSTACK_FRONTENDS$1 = [
-	"next",
-	"tanstack-start",
-	"nuxt",
-	"svelte",
-	"astro"
-];
-function validateSelfBackendCompatibility(providedFlags, options, config) {
-	const backend = config.backend || options.backend;
-	const frontends = config.frontend || options.frontend || [];
-	if (backend === "self") {
-		const { web, native } = splitFrontends(frontends);
-		if (!(web.length === 1 && FULLSTACK_FRONTENDS$1.includes(web[0]))) return validationErr$1("Backend 'self' (fullstack) currently only supports Next.js, TanStack Start, Nuxt, SvelteKit, and Astro frontends. Please use --frontend next, --frontend tanstack-start, --frontend nuxt, --frontend svelte, or --frontend astro.");
-		if (native.length > 1) return validationErr$1("Cannot select multiple native frameworks. Choose only one of: native-bare, native-uniwind, native-unistyles");
-	}
-	const hasFullstackFrontend = frontends.some((f) => FULLSTACK_FRONTENDS$1.includes(f));
-	if (providedFlags.has("backend") && !hasFullstackFrontend && backend === "self") return validationErr$1("Backend 'self' (fullstack) currently only supports Next.js, TanStack Start, Nuxt, SvelteKit, and Astro frontends. Please use --frontend next, --frontend tanstack-start, --frontend nuxt, --frontend svelte, --frontend astro, or choose a different backend.");
-	return Result.ok(void 0);
-}
-function validateWorkersCompatibility(providedFlags, options, config) {
-	if (providedFlags.has("runtime") && options.runtime === "workers" && config.backend && config.backend !== "hono") return validationErr$1(`Cloudflare Workers runtime (--runtime workers) is only supported with Hono backend (--backend hono). Current backend: ${config.backend}. Please use '--backend hono' or choose a different runtime.`);
-	if (providedFlags.has("backend") && config.backend && config.backend !== "hono" && config.runtime === "workers") return validationErr$1(`Backend '${config.backend}' is not compatible with Cloudflare Workers runtime. Cloudflare Workers runtime is only supported with Hono backend. Please use '--backend hono' or choose a different runtime.`);
-	if (providedFlags.has("runtime") && options.runtime === "workers" && config.database === "mongodb") return validationErr$1("Cloudflare Workers runtime (--runtime workers) is not compatible with MongoDB database. MongoDB requires Prisma or Mongoose ORM, but Workers runtime only supports Drizzle or Prisma ORM. Please use a different database or runtime.");
-	if (providedFlags.has("database") && config.database === "mongodb" && config.runtime === "workers") return validationErr$1("MongoDB database is not compatible with Cloudflare Workers runtime. MongoDB requires Prisma or Mongoose ORM, but Workers runtime only supports Drizzle or Prisma ORM. Please use a different database or runtime.");
-	return Result.ok(void 0);
+	return validateWithCompatibilityEvaluator({
+		testing,
+		frontend: frontends
+	}, void 0, ["testing-frontend"]);
 }
 function validateApiFrontendCompatibility(api, frontends = []) {
-	const includesNuxt = frontends.includes("nuxt");
-	const includesSvelte = frontends.includes("svelte");
-	const includesSolid = frontends.includes("solid");
-	const includesAstro = frontends.includes("astro");
-	if ((includesNuxt || includesSvelte || includesSolid || includesAstro) && api === "trpc") return validationErr$1(`tRPC API is not supported with '${includesNuxt ? "nuxt" : includesSvelte ? "svelte" : includesSolid ? "solid" : "astro"}' frontend. Please use --api orpc or --api none or remove '${includesNuxt ? "nuxt" : includesSvelte ? "svelte" : includesSolid ? "solid" : "astro"}' from --frontend.`);
-	return Result.ok(void 0);
+	return validateWithCompatibilityEvaluator({
+		api,
+		frontend: frontends
+	}, void 0, ["api-frontend"]);
 }
 function isFrontendAllowedWithBackend(frontend, backend, auth) {
-	if (backend === "convex") {
-		if (auth === "better-auth" && CONVEX_BETTER_AUTH_INCOMPATIBLE_FRONTENDS.includes(frontend)) return false;
-		if (frontend === "solid" || frontend === "astro") return false;
-	}
-	if (auth === "clerk") {
-		if ([
-			"nuxt",
-			"svelte",
-			"solid",
-			"astro"
-		].includes(frontend)) return false;
-	}
-	return true;
+	return !evaluate({
+		backend,
+		auth,
+		frontend: [frontend]
+	}).issues.map(({ code }) => code).some((code) => [
+		"backend-convex-frontend",
+		"backend-convex-better-auth-frontend",
+		"backend-self-frontend",
+		"auth-frontend"
+	].includes(code));
 }
 function supportsConvexBetterAuth(frontends = []) {
-	return frontends.some((frontend) => CONVEX_BETTER_AUTH_SUPPORTED_FRONTENDS.includes(frontend));
+	return frontends.some((frontend) => CONVEX_BETTER_AUTH_SUPPORTED_FRONTENDS.some((supported) => supported === frontend));
 }
 function allowedApisForFrontends(frontends = [], backend) {
-	const includesNuxt = frontends.includes("nuxt");
-	const includesSvelte = frontends.includes("svelte");
-	const includesSolid = frontends.includes("solid");
-	const includesAstro = frontends.includes("astro");
-	const base = [
+	if (backendAllowsOnlyNoneApi(backend)) return ["none"];
+	const supportsTrpc = !frontends.some((frontend) => WEB_FRONTENDS_REQUIRING_ORPC.includes(frontend));
+	return [
 		"trpc",
-		"orpc",
-		"none"
-	];
-	if (backend === "hono") base.splice(2, 0, "orval");
-	if (includesNuxt || includesSvelte || includesSolid || includesAstro) return backend === "hono" ? [
 		"orpc",
 		"orval",
 		"none"
-	] : ["orpc", "none"];
-	return base;
+	].filter((api) => (api !== "trpc" || supportsTrpc) && isApiCompatibleWithBackend(api, backend));
 }
 function isApiCompatibleWithBackend(api, backend) {
-	return api !== "orval" || backend === "hono";
+	return api !== "orval" || backendAllowsApi(backend, "orval");
 }
 function isExampleTodoAllowed(backend, database, api) {
-	if (backend === "convex") return true;
-	if (database === "none" || api === "none") return false;
-	return true;
+	return !evaluate({
+		backend,
+		database,
+		api,
+		examples: ["todo"]
+	}).issues.some(({ code }) => [
+		"example-todo-database",
+		"example-todo-api",
+		"example-todo-orval"
+	].includes(code));
+}
+function isExampleAIAllowedForBackend(backend, example) {
+	return example !== "ai" || backendAllowsAiExample(backend);
 }
 function isExampleAIAllowed(backend, frontends = []) {
-	if (backend === "none") return false;
-	const includesSolid = frontends.includes("solid");
-	const includesAstro = frontends.includes("astro");
-	if (includesSolid || includesAstro) return false;
-	if (backend === "convex") {
-		const includesNuxt = frontends.includes("nuxt");
-		const includesSvelte = frontends.includes("svelte");
-		if (includesNuxt || includesSvelte) return false;
-	}
-	return true;
-}
-function validateWebDeployRequiresWebFrontend(webDeploy, hasWebFrontendFlag) {
-	if (webDeploy && webDeploy !== "none" && !hasWebFrontendFlag) return validationErr$1("'--web-deploy' requires a web frontend. Please select a web frontend or set '--web-deploy none'.");
-	return Result.ok(void 0);
-}
-function validateServerDeployRequiresBackend(serverDeploy, backend) {
-	if (serverDeploy && serverDeploy !== "none" && (!backend || backend === "none")) return validationErr$1("'--server-deploy' requires a backend. Please select a backend or set '--server-deploy none'.");
-	return Result.ok(void 0);
-}
-function validateDockerServerDeploy(serverDeploy, backend, runtime) {
-	if (serverDeploy !== "docker") return Result.ok(void 0);
-	if (backend === "convex" || backend === "self") return validationErr$1("'--server-deploy docker' requires a separate server backend (hono, express, fastify, elysia). For a fullstack 'self' backend, use '--web-deploy docker' instead.");
-	if (runtime === "workers") return validationErr$1("'--server-deploy docker' is not compatible with '--runtime workers'. Use '--runtime bun' or '--runtime node', or choose '--server-deploy cloudflare'.");
-	return Result.ok(void 0);
-}
-function validateVercelServerDeploy(serverDeploy, backend, runtime) {
-	if (serverDeploy !== "vercel") return Result.ok(void 0);
-	if (backend === "convex" || backend === "self") return validationErr$1("'--server-deploy vercel' requires a separate server backend (hono, express, fastify, elysia). For a fullstack 'self' backend, use '--web-deploy vercel' instead.");
-	if (runtime === "workers") return validationErr$1("'--server-deploy vercel' is not compatible with '--runtime workers'. Use '--runtime bun' or '--runtime node', or choose '--server-deploy cloudflare'.");
-	return Result.ok(void 0);
-}
-function validateGuaraCloudServerDeploy(serverDeploy, backend, runtime) {
-	if (serverDeploy !== "guaracloud") return Result.ok(void 0);
-	if (backend === "convex" || backend === "self") return validationErr$1("'--server-deploy guaracloud' requires a separate server backend (hono, express, fastify, elysia). For a fullstack 'self' backend, use '--web-deploy guaracloud' instead.");
-	if (runtime === "workers") return validationErr$1("'--server-deploy guaracloud' is not compatible with '--runtime workers'. Use '--runtime bun' or '--runtime node', or choose '--server-deploy cloudflare'.");
-	return Result.ok(void 0);
-}
-const DOCKER_SERVER_OUTPUT_FRONTENDS = [
-	"next",
-	"svelte",
-	"astro",
-	"react-router"
-];
-function validateDockerWebDeployDesktopAddons(webDeploy, addons, frontend, backend, auth) {
-	if (webDeploy !== "docker" || !addons || !frontend) return Result.ok(void 0);
-	const desktopAddons = addons.filter((addon) => STATIC_DESKTOP_ADDONS.includes(addon));
-	if (desktopAddons.length === 0) return Result.ok(void 0);
-	const affected = frontend.find((f) => DOCKER_SERVER_OUTPUT_FRONTENDS.includes(f));
-	if (!affected) return Result.ok(void 0);
-	if (affected === "next" && !desktopAddons.includes("tauri") && backend === "convex" && auth === "better-auth") return Result.ok(void 0);
-	return validationErr$1(`'--web-deploy docker' is not compatible with the ${desktopAddons.join(", ")} addon on '${affected}' because desktop addons switch the web build to a static export, which the docker image cannot serve. Remove the addon or use a static-serving frontend (tanstack-router, solid).`);
-}
-function validateAddonCompatibility(addon, frontend, auth, backend, runtime) {
-	if (STATIC_DESKTOP_ADDONS.includes(addon) && auth === "clerk" && frontend.includes("react-router")) return {
-		isCompatible: false,
-		reason: `${addon} addon forces React Router into a static export, but Clerk on React Router requires SSR middleware. Remove the addon or use a different auth/frontend.`
-	};
-	if (backend === "self" && STATIC_DESKTOP_ADDONS.includes(addon)) return {
-		isCompatible: false,
-		reason: `${addon} addon requires a separate backend or no backend because backend 'self' emits server routes that cannot be bundled as static desktop assets.`
-	};
-	if (addon === "tauri" && backend === "convex" && auth === "better-auth" && frontend.some((f) => TAURI_STATIC_EXPORT_FRONTENDS.includes(f))) return {
-		isCompatible: false,
-		reason: "tauri addon is not compatible with Convex Better Auth on Next.js or TanStack Start because those templates use server auth bootstrap and cannot be exported as static desktop assets."
-	};
-	if (!(addon in ADDON_COMPATIBILITY)) return {
+	return !evaluate({
+		backend,
+		frontend: frontends,
+		examples: ["ai"]
+	}).issues.some(({ code }) => ["example-ai-frontend", "example-ai-backend"].includes(code));
+}
+function validateAddonCompatibility(addon, frontend, auth, backend, _runtime) {
+	const issue = evaluate({
+		addons: [addon],
+		frontend,
+		auth,
+		backend
+	}).issues.find(({ code }) => [
+		"addon-task-runner",
+		"addon-linter",
+		"addon-frontend",
+		"addon-backend",
+		"addon-auth"
+	].includes(code));
+	return issue ? {
 		isCompatible: false,
-		reason: `${addon} is not a supported addon`
-	};
-	const compatibleFrontends = ADDON_COMPATIBILITY[addon];
-	if (compatibleFrontends.length > 0) {
-		if (!frontend.some((f) => compatibleFrontends.some((compatibleFrontend) => compatibleFrontend === f))) return {
-			isCompatible: false,
-			reason: `${addon} addon requires one of these frontends: ${compatibleFrontends.join(", ")}`
-		};
-	}
-	return { isCompatible: true };
+		reason: getCompatibilityValidationMessage(issue, {
+			addons: [addon],
+			frontend,
+			auth,
+			backend
+		})
+	} : { isCompatible: true };
 }
 function getCompatibleAddons(allAddons, frontend, existingAddons = [], auth, backend, runtime) {
 	return allAddons.filter((addon) => {
@@ -812,64 +896,23 @@ function getCompatibleAddons(allAddons, frontend, existingAddons = [], auth, bac
 	});
 }
 function validateAddonsAgainstFrontends(addons = [], frontends = [], auth, backend, runtime) {
-	if (addons.filter((addon) => TASK_RUNNER_ADDONS$1.includes(addon)).length > 1) return validationErr$1("Cannot combine 'turborepo' and 'vite-plus' addons. Choose one task runner.");
-	if ([...new Set(addons.filter((addon) => LINTER_ADDONS.includes(addon)))].length > 1) return validationErr$1("Cannot combine 'biome' and 'oxlint' addons. Choose one code-quality linter.");
-	for (const addon of addons) {
-		if (addon === "none") continue;
-		const { isCompatible, reason } = validateAddonCompatibility(addon, frontends, auth, backend, runtime);
-		if (!isCompatible) return validationErr$1(`Incompatible addon/frontend combination: ${reason}`);
-	}
-	return Result.ok(void 0);
+	return validateWithCompatibilityEvaluator({
+		addons,
+		frontend: frontends,
+		auth,
+		backend,
+		runtime
+	}, void 0, [
+		"addon-task-runner",
+		"addon-linter",
+		"addon-frontend",
+		"addon-backend",
+		"addon-auth"
+	]);
 }
 function validateAddonsAgainstConfig(addons = [], config) {
 	return validateAddonsAgainstFrontends(addons, config.frontend ?? [], config.auth, config.backend, config.runtime);
 }
-function validateCommunicationCompatibility(communication, backend) {
-	if (!communication || communication === "none") return Result.ok(void 0);
-	if ((communication === "resend" || communication === "notifique" || communication === "arara") && backend === "none") return validationErr$1(`${communication === "notifique" ? "Notifique" : communication === "arara" ? "AraraHQ" : "Resend"} communication requires a server backend. Please choose a backend or use '--communication none'.`);
-	return Result.ok(void 0);
-}
-function validateAraraRuntimeCompatibility(communication, backend, runtime, serverDeploy) {
-	if (communication !== "arara" || backend === "convex") return Result.ok(void 0);
-	if (runtime === "workers" || serverDeploy === "cloudflare") return validationErr$1("AraraHQ requires the official Node SDK and is not compatible with Edge/Workers runtimes. Use a Node/Bun server deployment or Convex Node Action.");
-	return Result.ok(void 0);
-}
-function validatePaymentsCompatibility(payments, auth, backend, frontends = [], orm, database) {
-	if (!payments || payments.length === 0) return Result.ok(void 0);
-	for (const provider of payments) {
-		const issue = getPaymentCompatibilityIssue({
-			provider,
-			backend,
-			frontends,
-			database,
-			orm
-		});
-		const label = provider === "stripe" ? "Stripe" : "AbacatePay";
-		if (issue === "convex-unsupported") return validationErr$1(`${label} payments is not compatible with '--backend convex'. Please use a server backend or backend 'self'.`);
-		if (issue === "requires-web-frontend") return validationErr$1(`${label} payments requires a web frontend. Please choose next, tanstack-start, tanstack-router, react-router, nuxt, svelte, solid, or astro.`);
-		if (issue === "native-only-unsupported") return validationErr$1(`${label} payments is not compatible with native-only frontends. Please add a supported web frontend or leave payments unselected.`);
-		if (issue === "sql-database-required") return validationErr$1("AbacatePay payments v1 requires a SQL database with Drizzle or Prisma. MongoDB and Mongoose are not supported.");
-	}
-	return Result.ok(void 0);
-}
-function validateExamplesCompatibility(examples, backend, database, frontend, api) {
-	const examplesArr = examples ?? [];
-	if (examplesArr.length === 0 || examplesArr.includes("none")) return Result.ok(void 0);
-	if (examplesArr.includes("todo") && backend !== "convex") {
-		if (database === "none") return validationErr$1("The 'todo' example requires a database. Cannot use --examples todo when database is 'none'.");
-		if (api === "none") return validationErr$1("The 'todo' example requires an API layer (tRPC or oRPC). Cannot use --examples todo when api is 'none'.");
-	}
-	if (examplesArr.includes("ai") && (frontend ?? []).includes("solid")) return validationErr$1("The 'ai' example is not compatible with the Solid frontend.");
-	if (examplesArr.includes("ai") && (frontend ?? []).includes("astro")) return validationErr$1("The 'ai' example is not compatible with the Astro frontend.");
-	if (examplesArr.includes("ai") && backend === "none") return validationErr$1("The 'ai' example requires a backend.");
-	if (examplesArr.includes("ai") && backend === "convex") {
-		const frontendArr = frontend ?? [];
-		const includesNuxt = frontendArr.includes("nuxt");
-		const includesSvelte = frontendArr.includes("svelte");
-		if (includesNuxt || includesSvelte) return validationErr$1("The 'ai' example with Convex backend only supports React-based frontends (Next.js, TanStack Router, TanStack Start, React Router). Svelte and Nuxt are not supported with Convex AI.");
-	}
-	return Result.ok(void 0);
-}
 //#endregion
 //#region src/utils/navigation.ts
 const GO_BACK_SYMBOL = Symbol("clack:goBack");
@@ -917,6 +960,12 @@ function getMultiHint() {
 function normalizeValidationMessage(validationMessage) {
 	return validationMessage instanceof Error ? validationMessage.message : validationMessage;
 }
+function formatKeycap(key) {
+	return pc.bold(`<${key}>`);
+}
+function getRequiredMultiselectMessage() {
+	return `Please select at least one option.\n${pc.dim(`Press ${formatKeycap("space")} to select, ${formatKeycap("enter")} to submit`)}`;
+}
 async function runWithNavigation(prompt) {
 	let goBack = false;
 	prompt.on("key", (char) => {
@@ -974,7 +1023,7 @@ async function navigableMultiselect(opts) {
 		initialValues: opts.initialValues,
 		required,
 		validate(selected) {
-			if (required && (selected === void 0 || selected.length === 0)) return `Please select at least one option.\n${pc.reset(pc.dim(`Press ${pc.gray(pc.bgWhite(pc.inverse(" space ")))} to select, ${pc.gray(pc.bgWhite(pc.inverse(" enter ")))} to submit`))}`;
+			if (required && (selected === void 0 || selected.length === 0)) return getRequiredMultiselectMessage();
 			return normalizeValidationMessage(opts.validate?.(selected));
 		},
 		render() {
@@ -1058,7 +1107,7 @@ async function navigableGroupMultiselect(opts) {
 		required,
 		selectableGroups: true,
 		validate(selected) {
-			if (required && (selected === void 0 || selected.length === 0)) return `Please select at least one option.\n${pc.reset(pc.dim(`Press ${pc.gray(pc.bgWhite(pc.inverse(" space ")))} to select, ${pc.gray(pc.bgWhite(pc.inverse(" enter ")))} to submit`))}`;
+			if (required && (selected === void 0 || selected.length === 0)) return getRequiredMultiselectMessage();
 			return normalizeValidationMessage(opts.validate?.(selected));
 		},
 		render() {
@@ -1269,6 +1318,66 @@ async function getAddonsToAdd(config) {
 	return response;
 }
 //#endregion
+//#region src/utils/config-processing.ts
+function processArrayOption(options) {
+	if (!options || options.length === 0) return [];
+	if (options.includes("none")) return [];
+	return options.filter((item) => item !== "none");
+}
+function deriveProjectName(projectName, projectDirectory) {
+	if (projectName) return projectName;
+	if (projectDirectory) return path.basename(path.resolve(process.cwd(), projectDirectory));
+	return "";
+}
+function processFlags(options, projectName) {
+	const config = {};
+	if (options.api) config.api = options.api;
+	if (options.addonOptions) config.addonOptions = options.addonOptions;
+	if (options.dbSetupOptions) config.dbSetupOptions = options.dbSetupOptions;
+	if (options.backend) config.backend = options.backend;
+	if (options.database) config.database = options.database;
+	if (options.orm) config.orm = options.orm;
+	if (options.auth !== void 0) config.auth = options.auth;
+	if (options.payments !== void 0) config.payments = normalizePayments(options.payments);
+	if (options.observability !== void 0) config.observability = normalizeObservability(options.observability);
+	if (options.disableObservability) config.observability = [];
+	if (options.communication !== void 0) config.communication = normalizeCommunication$2(options.communication);
+	if (options.git !== void 0) config.git = options.git;
+	if (options.install !== void 0) config.install = options.install;
+	if (options.runtime) config.runtime = options.runtime;
+	if (options.dbSetup) config.dbSetup = options.dbSetup;
+	if (options.packageManager) config.packageManager = options.packageManager;
+	if (options.webDeploy) config.webDeploy = options.webDeploy;
+	if (options.serverDeploy) config.serverDeploy = options.serverDeploy;
+	const derivedName = deriveProjectName(projectName, options.projectDirectory);
+	if (derivedName) config.projectName = projectName || derivedName;
+	if (options.frontend && options.frontend.length > 0) config.frontend = processArrayOption(options.frontend);
+	if (options.addons && options.addons.length > 0) config.addons = processArrayOption(options.addons);
+	if (options.examples && options.examples.length > 0) config.examples = processArrayOption(options.examples);
+	if (options.testing && options.testing.length > 0) config.testing = processArrayOption(options.testing);
+	return config;
+}
+function getProvidedFlags(options) {
+	return new Set(Object.keys(options).filter((key) => options[key] !== void 0));
+}
+function validateNoneExclusivity(options, optionName) {
+	if (!options || options.length === 0) return Result.ok(void 0);
+	if (options.includes("none") && options.length > 1) return Result.err(new ValidationError({ message: `Cannot combine 'none' with other ${optionName}.` }));
+	return Result.ok(void 0);
+}
+function validateArrayOptions(options) {
+	if (options.disableObservability && options.observability !== void 0) return Result.err(new ValidationError({ message: "Cannot combine '--disable-observability' with '--observability'." }));
+	const frontendResult = validateNoneExclusivity(options.frontend, "frontend options");
+	if (frontendResult.isErr()) return frontendResult;
+	const addonsResult = validateNoneExclusivity(options.addons, "addons");
+	if (addonsResult.isErr()) return addonsResult;
+	const examplesResult = validateNoneExclusivity(options.examples, "examples");
+	if (examplesResult.isErr()) return examplesResult;
+	const testingResult = validateNoneExclusivity(options.testing, "testing");
+	if (testingResult.isErr()) return testingResult;
+	return Result.ok(void 0);
+}
+//#endregion
 //#region src/utils/input-hardening.ts
 function hasControlCharacters(value) {
 	for (const char of value) {
@@ -1289,34 +1398,83 @@ function validateAgentSafePathInput(value, field) {
 	return Result.ok(void 0);
 }
 //#endregion
-//#region src/utils/kubojs-config.ts
-const KUBOJS_CONFIG_FILE = "kubojs.jsonrc";
-/**
-* Reads the kubojs configuration file from the project directory.
-*/
-async function readKubojsConfig(projectDir) {
-	try {
-		const configPath = path.join(projectDir, KUBOJS_CONFIG_FILE);
-		if (!await fs.pathExists(configPath)) return null;
-		return parse(await fs.readFile(configPath, "utf-8"));
-	} catch {
-		return null;
+//#region src/utils/kubo-config.ts
+const LEGACY_CONFIG_FILE = "kubojs.jsonrc";
+const CONFIG_CANDIDATES = [
+	"kubo.config.ts",
+	"kubo.config.mts",
+	"kubo.config.js",
+	"kubo.config.mjs"
+];
+async function findConfigFile(projectDir) {
+	for (const candidate of CONFIG_CANDIDATES) {
+		const absolute = path.join(projectDir, candidate);
+		if (await fs.pathExists(absolute)) return absolute;
 	}
+	return null;
 }
-/**
-* Updates specific fields in the kubojs configuration file.
-*/
-async function updateKubojsConfig(projectDir, updates) {
-	try {
-		const configPath = path.join(projectDir, KUBOJS_CONFIG_FILE);
-		if (!await fs.pathExists(configPath)) return;
-		let content = await fs.readFile(configPath, "utf-8");
-		for (const [key, value] of Object.entries(updates)) {
-			const edits = modify(content, [key], value, { formattingOptions: { tabSize: 2 } });
-			content = applyEdits(content, edits);
-		}
-		await fs.writeFile(configPath, content, "utf-8");
-	} catch {}
+function configInvalid(file, detail, cause) {
+	return Result.err(new KuboConfigInvalidError({
+		file,
+		message: `Invalid ${file}: ${detail}`,
+		cause
+	}));
+}
+async function loadTypeScriptConfig(projectDir) {
+	const configPath = await findConfigFile(projectDir);
+	if (!configPath) return Result.ok(null);
+	const fileName = path.basename(configPath);
+	const jiti = createJiti(import.meta.url, {
+		interopDefault: true,
+		moduleCache: false
+	});
+	const importResult = await Result.tryPromise({
+		try: () => jiti.import(configPath),
+		catch: (e) => new KuboConfigInvalidError({
+			file: fileName,
+			message: `Invalid ${fileName}: ${e instanceof Error ? e.message : String(e)}`,
+			cause: e
+		})
+	});
+	if (importResult.isErr()) return Result.err(importResult.error);
+	const loaded = importResult.value;
+	const exported = loaded.default ?? loaded;
+	const parsed = KuboConfigFileSchema.safeParse(exported);
+	if (!parsed.success) return configInvalid(fileName, parsed.error.issues.map((issue) => issue.message).join("; "));
+	return Result.ok(normalizeLegacyKuboConfig(parsed.data));
+}
+async function loadLegacyJsonConfig(projectDir) {
+	const configPath = path.join(projectDir, LEGACY_CONFIG_FILE);
+	if (!await fs.pathExists(configPath)) return Result.ok(null);
+	const raw = parse(await fs.readFile(configPath, "utf-8"));
+	const parsed = KubojsConfigFileSchema.safeParse(raw);
+	if (!parsed.success) return configInvalid(LEGACY_CONFIG_FILE, parsed.error.issues.map((issue) => issue.message).join("; "));
+	return Result.ok(normalizeLegacyKuboConfig(parsed.data));
+}
+async function loadProjectKuboConfig(projectDir) {
+	const tsResult = await loadTypeScriptConfig(projectDir);
+	if (tsResult.isErr()) return tsResult;
+	if (tsResult.value) return tsResult;
+	return loadLegacyJsonConfig(projectDir);
+}
+async function readKubojsConfig(projectDir) {
+	return loadProjectKuboConfig(projectDir);
+}
+async function updateProjectKuboConfig(projectDir, updates) {
+	const existingResult = await loadProjectKuboConfig(projectDir);
+	if (existingResult.isErr()) return Result.err(existingResult.error);
+	const existing = existingResult.value;
+	if (!existing) return Result.ok(void 0);
+	const merged = {
+		...existing,
+		...updates,
+		addonOptions: updates.addonOptions ?? existing.addonOptions,
+		dbSetupOptions: updates.dbSetupOptions ?? existing.dbSetupOptions
+	};
+	const configPath = await findConfigFile(projectDir) ?? path.join(projectDir, KUBO_CONFIG_FILE);
+	const content = serializeKuboConfigFile(merged);
+	await fs.writeFile(configPath, content, "utf-8");
+	return Result.ok(void 0);
 }
 //#endregion
 //#region src/utils/add-package-deps.ts
@@ -2040,31 +2198,82 @@ function hasReactBasedFrontend(frontend) {
 function hasNativeFrontend(frontend) {
 	return frontend.includes("native-bare") || frontend.includes("native-uniwind") || frontend.includes("native-unistyles");
 }
+const RECOMMENDED_SOURCE_RULES = {
+	reactBasedFrontend: {
+		when: ({ frontend }) => hasReactBasedFrontend(frontend),
+		sources: ["vercel-labs/agent-skills", "shadcn/ui"]
+	},
+	vercelDeployment: {
+		when: ({ webDeploy, serverDeploy }) => webDeploy === "vercel" || serverDeploy === "vercel",
+		sources: ["vercel-labs/agent-skills"]
+	},
+	nextFrontend: {
+		when: ({ frontend }) => frontend.includes("next"),
+		sources: ["vercel-labs/next-skills"]
+	},
+	nuxtFrontend: {
+		when: ({ frontend }) => frontend.includes("nuxt"),
+		sources: ["nuxt/ui"]
+	},
+	nativeUniwindFrontend: {
+		when: ({ frontend }) => frontend.includes("native-uniwind"),
+		sources: ["heroui-inc/heroui"]
+	},
+	nativeFrontend: {
+		when: ({ frontend }) => hasNativeFrontend(frontend),
+		sources: ["expo/skills"]
+	},
+	betterAuth: {
+		when: ({ auth }) => auth === "better-auth",
+		sources: ["better-auth/skills"]
+	},
+	clerk: {
+		when: ({ auth }) => auth === "clerk",
+		sources: ["clerk/skills"]
+	},
+	neonDatabase: {
+		when: ({ dbSetup }) => dbSetup === "neon",
+		sources: ["neondatabase/agent-skills"]
+	},
+	supabaseDatabase: {
+		when: ({ dbSetup }) => dbSetup === "supabase",
+		sources: ["supabase/agent-skills"]
+	},
+	planetscaleDatabase: {
+		when: ({ dbSetup }) => dbSetup === "planetscale",
+		sources: ["planetscale/database-skills"]
+	},
+	prismaDatabase: {
+		when: ({ orm, dbSetup }) => orm === "prisma" || dbSetup === "prisma-postgres",
+		sources: ["prisma/skills"]
+	},
+	aiExample: {
+		when: ({ examples }) => examples.includes("ai"),
+		sources: ["vercel/ai"]
+	},
+	turborepoAddon: {
+		when: ({ addons }) => addons.includes("turborepo"),
+		sources: ["vercel/turborepo"]
+	},
+	honoBackend: {
+		when: ({ backend }) => backend === "hono",
+		sources: ["yusukebe/hono-skill"]
+	},
+	elysiaBackend: {
+		when: ({ backend }) => backend === "elysia",
+		sources: ["elysiajs/skills"]
+	},
+	convexBackend: {
+		when: ({ backend }) => backend === "convex",
+		sources: ["waynesutton/convexskills"]
+	},
+	opentuiAddon: {
+		when: ({ addons }) => addons.includes("opentui"),
+		sources: ["msmps/opentui-skill"]
+	}
+};
 function getRecommendedSourceKeys(config) {
-	const sources = [];
-	const { frontend, backend, dbSetup, auth, examples, addons, orm, webDeploy, serverDeploy } = config;
-	if (hasReactBasedFrontend(frontend)) {
-		sources.push("vercel-labs/agent-skills");
-		sources.push("shadcn/ui");
-	}
-	if ((webDeploy === "vercel" || serverDeploy === "vercel") && !sources.includes("vercel-labs/agent-skills")) sources.push("vercel-labs/agent-skills");
-	if (frontend.includes("next")) sources.push("vercel-labs/next-skills");
-	if (frontend.includes("nuxt")) sources.push("nuxt/ui");
-	if (frontend.includes("native-uniwind")) sources.push("heroui-inc/heroui");
-	if (hasNativeFrontend(frontend)) sources.push("expo/skills");
-	if (auth === "better-auth") sources.push("better-auth/skills");
-	if (auth === "clerk") sources.push("clerk/skills");
-	if (dbSetup === "neon") sources.push("neondatabase/agent-skills");
-	if (dbSetup === "supabase") sources.push("supabase/agent-skills");
-	if (dbSetup === "planetscale") sources.push("planetscale/database-skills");
-	if (orm === "prisma" || dbSetup === "prisma-postgres") sources.push("prisma/skills");
-	if (examples.includes("ai")) sources.push("vercel/ai");
-	if (addons.includes("turborepo")) sources.push("vercel/turborepo");
-	if (backend === "hono") sources.push("yusukebe/hono-skill");
-	if (backend === "elysia") sources.push("elysiajs/skills");
-	if (backend === "convex") sources.push("waynesutton/convexskills");
-	if (addons.includes("opentui")) sources.push("msmps/opentui-skill");
-	return sources;
+	return uniqueValues(Object.values(RECOMMENDED_SOURCE_RULES).flatMap(({ when, sources }) => when(config) ? sources : []));
 }
 const CURATED_SKILLS_BY_SOURCE = {
 	"vercel-labs/agent-skills": (config) => {
@@ -2144,7 +2353,12 @@ function uniqueValues(values) {
 async function setupSkills(config) {
 	if (shouldSkipExternalCommands()) return Result.ok(void 0);
 	const { packageManager, projectDir } = config;
-	const kubojsConfig = await readKubojsConfig(projectDir);
+	const kubojsConfigResult = await readKubojsConfig(projectDir);
+	if (kubojsConfigResult.isErr()) return Result.err(new CLIError({
+		message: kubojsConfigResult.error.message,
+		cause: kubojsConfigResult.error
+	}));
+	const kubojsConfig = kubojsConfigResult.value;
 	const fullConfig = kubojsConfig ? {
 		...config,
 		addons: kubojsConfig.addons ?? config.addons,
@@ -2589,103 +2803,36 @@ async function installPlaywrightBrowsers(projectDir, packageManager) {
 	}
 }
 //#endregion
-//#region src/utils/config-processing.ts
-function processArrayOption(options) {
-	if (!options || options.length === 0) return [];
-	if (options.includes("none")) return [];
-	return options.filter((item) => item !== "none");
-}
-function deriveProjectName(projectName, projectDirectory) {
-	if (projectName) return projectName;
-	if (projectDirectory) return path.basename(path.resolve(process.cwd(), projectDirectory));
-	return "";
-}
-function processFlags(options, projectName) {
-	const config = {};
-	if (options.api) config.api = options.api;
-	if (options.addonOptions) config.addonOptions = options.addonOptions;
-	if (options.dbSetupOptions) config.dbSetupOptions = options.dbSetupOptions;
-	if (options.backend) config.backend = options.backend;
-	if (options.database) config.database = options.database;
-	if (options.orm) config.orm = options.orm;
-	if (options.auth !== void 0) config.auth = options.auth;
-	if (options.payments !== void 0) config.payments = normalizePayments(options.payments);
-	if (options.observability !== void 0) config.observability = normalizeObservability(options.observability);
-	if (options.disableObservability) config.observability = [];
-	if (options.communication !== void 0) config.communication = options.communication;
-	if (options.git !== void 0) config.git = options.git;
-	if (options.install !== void 0) config.install = options.install;
-	if (options.runtime) config.runtime = options.runtime;
-	if (options.dbSetup) config.dbSetup = options.dbSetup;
-	if (options.packageManager) config.packageManager = options.packageManager;
-	if (options.webDeploy) config.webDeploy = options.webDeploy;
-	if (options.serverDeploy) config.serverDeploy = options.serverDeploy;
-	const derivedName = deriveProjectName(projectName, options.projectDirectory);
-	if (derivedName) config.projectName = projectName || derivedName;
-	if (options.frontend && options.frontend.length > 0) config.frontend = processArrayOption(options.frontend);
-	if (options.addons && options.addons.length > 0) config.addons = processArrayOption(options.addons);
-	if (options.examples && options.examples.length > 0) config.examples = processArrayOption(options.examples);
-	if (options.testing && options.testing.length > 0) config.testing = processArrayOption(options.testing);
-	return config;
-}
-function normalizeObservability(value) {
-	if (value === "none" || value === void 0) return [];
-	return [...new Set((Array.isArray(value) ? value : [value]).filter((item) => item === "getmonitor" || item === "himetrica"))];
-}
-function getProvidedFlags(options) {
-	return new Set(Object.keys(options).filter((key) => options[key] !== void 0));
-}
-function validateNoneExclusivity(options, optionName) {
-	if (!options || options.length === 0) return Result.ok(void 0);
-	if (options.includes("none") && options.length > 1) return Result.err(new ValidationError({ message: `Cannot combine 'none' with other ${optionName}.` }));
-	return Result.ok(void 0);
-}
-function validateArrayOptions(options) {
-	if (options.disableObservability && options.observability !== void 0) return Result.err(new ValidationError({ message: "Cannot combine '--disable-observability' with '--observability'." }));
-	const frontendResult = validateNoneExclusivity(options.frontend, "frontend options");
-	if (frontendResult.isErr()) return frontendResult;
-	const addonsResult = validateNoneExclusivity(options.addons, "addons");
-	if (addonsResult.isErr()) return addonsResult;
-	const examplesResult = validateNoneExclusivity(options.examples, "examples");
-	if (examplesResult.isErr()) return examplesResult;
-	const testingResult = validateNoneExclusivity(options.testing, "testing");
-	if (testingResult.isErr()) return testingResult;
-	return Result.ok(void 0);
-}
-//#endregion
 //#region src/helpers/core/detect-project-config.ts
 async function detectProjectConfig(projectDir) {
-	const result = await Result.tryPromise({
-		try: async () => {
-			const kubojsConfig = await readKubojsConfig(projectDir);
-			if (kubojsConfig) return {
-				projectDir,
-				projectName: path.basename(projectDir),
-				addonOptions: kubojsConfig.addonOptions,
-				dbSetupOptions: kubojsConfig.dbSetupOptions,
-				database: kubojsConfig.database,
-				orm: kubojsConfig.orm,
-				backend: kubojsConfig.backend,
-				runtime: kubojsConfig.runtime,
-				frontend: kubojsConfig.frontend,
-				addons: kubojsConfig.addons,
-				examples: kubojsConfig.examples,
-				testing: kubojsConfig.testing,
-				auth: kubojsConfig.auth,
-				payments: kubojsConfig.payments,
-				observability: normalizeObservability(kubojsConfig.observability),
-				communication: kubojsConfig.communication ?? "none",
-				packageManager: kubojsConfig.packageManager,
-				dbSetup: kubojsConfig.dbSetup,
-				api: kubojsConfig.api,
-				webDeploy: kubojsConfig.webDeploy,
-				serverDeploy: kubojsConfig.serverDeploy
-			};
-			return null;
-		},
-		catch: () => null
+	const loadResult = await readKubojsConfig(projectDir);
+	if (loadResult.isErr()) return Result.err(loadResult.error);
+	const kubojsConfig = loadResult.value;
+	if (!kubojsConfig) return Result.ok(null);
+	return Result.ok({
+		projectDir,
+		projectName: path.basename(projectDir),
+		layout: kubojsConfig.layout,
+		addonOptions: kubojsConfig.addonOptions,
+		dbSetupOptions: kubojsConfig.dbSetupOptions,
+		database: kubojsConfig.database,
+		orm: kubojsConfig.orm,
+		backend: kubojsConfig.backend,
+		runtime: kubojsConfig.runtime,
+		frontend: kubojsConfig.frontend,
+		addons: kubojsConfig.addons,
+		examples: kubojsConfig.examples,
+		testing: kubojsConfig.testing,
+		auth: kubojsConfig.auth,
+		payments: kubojsConfig.payments,
+		observability: normalizeObservability(kubojsConfig.observability),
+		communication: normalizeCommunication$2(kubojsConfig.communication ?? []),
+		packageManager: kubojsConfig.packageManager,
+		dbSetup: kubojsConfig.dbSetup,
+		api: kubojsConfig.api,
+		webDeploy: kubojsConfig.webDeploy,
+		serverDeploy: kubojsConfig.serverDeploy
 	});
-	return result.isOk() ? result.value : null;
 }
 //#endregion
 //#region src/helpers/core/install-dependencies.ts
@@ -2711,32 +2858,56 @@ async function installDependencies({ projectDir, packageManager }) {
 	return result;
 }
 //#endregion
+//#region src/helpers/core/project-vfs.ts
+const IGNORED_DIRECTORY_NAMES = new Set([
+	".git",
+	".next",
+	".nuxt",
+	".output",
+	".svelte-kit",
+	".turbo",
+	"artifacts",
+	"build",
+	"coverage",
+	"dist",
+	"node_modules"
+]);
+/**
+* Imports the editable text surface of an existing project into the VFS.
+* Generated/dependency directories and binary files remain owned by the filesystem.
+*/
+async function loadProjectTextFiles(vfs, projectDir) {
+	await loadDirectory(vfs, projectDir, projectDir);
+}
+async function loadDirectory(vfs, projectDir, currentDir) {
+	const entries = await fs.readdir(currentDir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (entry.isSymbolicLink()) continue;
+		const absolutePath = path.join(currentDir, entry.name);
+		if (entry.isDirectory()) {
+			if (IGNORED_DIRECTORY_NAMES.has(entry.name)) continue;
+			await loadDirectory(vfs, projectDir, absolutePath);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		const relativePath = path.relative(projectDir, absolutePath);
+		if (isBinaryFile(relativePath)) continue;
+		const content = await fs.readFile(absolutePath);
+		if (isBinaryContent(content)) continue;
+		vfs.loadFile(relativePath, content.toString("utf-8"));
+	}
+}
+function isBinaryContent(content) {
+	if (content.includes(0)) return true;
+	try {
+		new TextDecoder("utf-8", { fatal: true }).decode(content);
+		return false;
+	} catch {
+		return true;
+	}
+}
+//#endregion
 //#region src/helpers/core/add-handler.ts
-const ADD_PACKAGE_JSON_PATHS = [
-	"package.json",
-	"apps/server/package.json",
-	"apps/web/package.json",
-	"apps/native/package.json",
-	"apps/desktop/package.json",
-	"apps/docs/package.json",
-	"apps/api/package.json",
-	"packages/db/package.json",
-	"packages/auth/package.json",
-	"packages/backend/package.json",
-	"packages/config/package.json",
-	"packages/env/package.json",
-	"packages/infra/package.json",
-	"packages/ui/package.json"
-];
-const ADD_TEXT_FILE_PATHS = ["apps/web/vite.config.ts", "lefthook.yml"];
-const ADD_ENV_FILE_PATHS = [
-	".env",
-	"apps/web/.env",
-	"apps/server/.env",
-	"apps/native/.env",
-	"packages/backend/.env.local",
-	"packages/infra/.env"
-];
 const HOOK_ADDONS = ["husky", "lefthook"];
 const HOOK_LINTER_ADDONS = [
 	"biome",
@@ -2803,8 +2974,9 @@ async function cleanupRemovedLinters(projectDir, removedAddons) {
 		}
 	}
 }
-function updateViteConfigImportsForVitePlus(vfs) {
-	for (const viteConfigPath of ["apps/web/vite.config.ts"]) {
+function updateViteConfigImportsForVitePlus(vfs, webPath) {
+	const viteConfigPaths = [`${webPath}/vite.config.ts`];
+	for (const viteConfigPath of viteConfigPaths) {
 		const content = vfs.readFile(viteConfigPath);
 		if (!content) continue;
 		const updatedContent = content.replaceAll("from \"vite\";", "from \"vite-plus\";").replaceAll("from 'vite';", "from 'vite-plus';");
@@ -2847,8 +3019,13 @@ async function addHandlerInternal(input) {
 		renderTitle();
 		intro(cliColors.signal("Add addons to your kubojs project"));
 	}
-	const existingConfig = await detectProjectConfig(projectDir);
-	if (!existingConfig) return Result.err(new CLIError({ message: `No kubojs project found in ${projectDir}. Make sure kubojs.jsonrc exists.` }));
+	const detectResult = await detectProjectConfig(projectDir);
+	if (detectResult.isErr()) return Result.err(new CLIError({
+		message: detectResult.error.message,
+		cause: detectResult.error
+	}));
+	const existingConfig = detectResult.value;
+	if (!existingConfig) return Result.err(new CLIError({ message: `No kubojs project found in ${projectDir}. Make sure kubo.config.ts exists.` }));
 	if (!isSilent()) log.info(pc.dim(`Detected project: ${existingConfig.projectName}`));
 	let addonsToAdd;
 	if (input.addons && input.addons.length > 0) {
@@ -2897,10 +3074,20 @@ async function addHandlerInternal(input) {
 		if (removedAddons.length > 0) log.info(pc.dim(`Replacing exclusive addons: ${removedAddons.join(", ")}`));
 	}
 	const mergedAddonOptions = mergeAddonOptions(existingConfig.addonOptions, input.addonOptions);
+	const layout = existingConfig.layout ?? { preset: "standard" };
+	const layoutResult = resolveLayout(layout, projectDir, {
+		backend: existingConfig.backend,
+		addonsToAdd
+	});
+	if (layoutResult.isErr()) return Result.err(new CLIError({
+		message: layoutResult.error.message,
+		cause: layoutResult.error
+	}));
 	const config = {
 		projectName: existingConfig.projectName,
 		projectDir,
 		relativePath: ".",
+		layout,
 		addonOptions: mergedAddonOptions,
 		database: existingConfig.database,
 		orm: existingConfig.orm,
@@ -2912,7 +3099,7 @@ async function addHandlerInternal(input) {
 		auth: existingConfig.auth,
 		payments: existingConfig.payments,
 		observability: existingConfig.observability,
-		communication: existingConfig.communication ?? "none",
+		communication: normalizeCommunication$2(existingConfig.communication ?? []),
 		testing: updatedTesting,
 		git: false,
 		packageManager: input.packageManager || existingConfig.packageManager,
@@ -2928,45 +3115,27 @@ async function addHandlerInternal(input) {
 	};
 	if (!isSilent()) log.info(pc.dim("Installing addon files..."));
 	const vfs = new VirtualFileSystem();
-	for (const pkgPath of ADD_PACKAGE_JSON_PATHS) {
-		const fullPath = path.join(projectDir, pkgPath);
-		if (await fs.pathExists(fullPath)) {
-			const content = await fs.readFile(fullPath, "utf-8");
-			vfs.writeFile(pkgPath, content);
-		}
-	}
-	for (const filePath of ADD_TEXT_FILE_PATHS) {
-		const fullPath = path.join(projectDir, filePath);
-		if (await fs.pathExists(fullPath)) {
-			const content = await fs.readFile(fullPath, "utf-8");
-			vfs.writeFile(filePath, content);
-		}
-	}
-	for (const filePath of ADD_ENV_FILE_PATHS) {
-		const fullPath = path.join(projectDir, filePath);
-		if (await fs.pathExists(fullPath)) {
-			const content = await fs.readFile(fullPath, "utf-8");
-			vfs.writeFile(filePath, content);
-		}
-	}
-	await processAddonTemplates(vfs, EMBEDDED_TEMPLATES, config);
-	processAddonsDeps(vfs, config);
+	await loadProjectTextFiles(vfs, projectDir);
+	await applyAddonCatalog(vfs, EMBEDDED_TEMPLATES, updatedConfig, {
+		templateConfig: config,
+		refreshTaskRunner: addonsToAdd.includes("turborepo"),
+		refreshVitePlus: addonsToAdd.includes("vite-plus")
+	});
 	processEnvVariables(vfs, updatedConfig);
-	if (addonsToAdd.includes("turborepo")) processTurboConfig(vfs, updatedConfig);
-	if (addonsToAdd.includes("vite-plus")) processVitePlusConfig(vfs, updatedConfig);
 	if (updatedAddons.some((addon) => TASK_RUNNER_ADDONS.includes(addon))) processPackageConfigs(vfs, updatedConfig);
-	if (updatedAddons.includes("vite-plus")) updateViteConfigImportsForVitePlus(vfs);
+	if (updatedAddons.includes("vite-plus")) updateViteConfigImportsForVitePlus(vfs, getWebAppPath(updatedConfig));
 	if (shouldRefreshLefthook(addonsToAdd, updatedAddons)) refreshLefthookTemplate(vfs, updatedConfig);
+	const changedFiles = new Set(vfs.getChangedFiles());
 	const tree = {
 		root: vfs.toTree(""),
-		fileCount: vfs.getFileCount(),
+		fileCount: changedFiles.size,
 		directoryCount: vfs.getDirectoryCount(),
 		config: updatedConfig
 	};
 	if (input.dryRun) {
 		if (!isSilent()) {
 			log.success(pc.green("Dry run validation passed. No addon files were written."));
-			log.info(pc.dim(`Planned addon files: ${vfs.getFileCount()}`));
+			log.info(pc.dim(`Planned addon files: ${changedFiles.size}`));
 			outro(cliColors.signal("Dry run complete."));
 		}
 		return Result.ok({
@@ -2977,9 +3146,9 @@ async function addHandlerInternal(input) {
 			plannedFileCount: vfs.getFileCount()
 		});
 	}
-	const writeResult = await writeTree(tree, projectDir);
+	const writeResult = await writeSelected(tree, projectDir, (filePath) => changedFiles.has(filePath));
 	if (writeResult.isErr()) return Result.err(new CLIError({ message: `Failed to write addon files: ${writeResult.error.message}` }));
-	if (vfs.getFileCount() > 0 && !isSilent()) log.info(pc.dim(`Wrote ${vfs.getFileCount()} addon files`));
+	if (changedFiles.size > 0 && !isSilent()) log.info(pc.dim(`Wrote ${changedFiles.size} addon files`));
 	await cleanupRemovedLinters(projectDir, removedAddons);
 	const setupResult = await Result.tryPromise({
 		try: () => setupAddons({
@@ -3003,11 +3172,16 @@ async function addHandlerInternal(input) {
 		})
 	});
 	if (testingSetupResult.isErr()) return Result.err(testingSetupResult.error);
-	await updateKubojsConfig(projectDir, {
+	const configUpdateResult = await updateProjectKuboConfig(projectDir, {
 		addons: updatedAddons,
 		addonOptions: updatedConfig.addonOptions,
-		testing: updatedTesting
+		testing: updatedTesting,
+		layout
 	});
+	if (configUpdateResult.isErr()) return Result.err(new CLIError({
+		message: configUpdateResult.error.message,
+		cause: configUpdateResult.error
+	}));
 	if (input.install) {
 		if (!isSilent()) log.info(pc.dim("Installing dependencies..."));
 		await installDependencies({
@@ -3149,6 +3323,10 @@ async function getBackendFrameworkChoice(backendFramework, frontends, previousVa
 		value: "elysia",
 		label: "Elysia",
 		hint: "Ergonomic web framework for building backend servers"
+	}, {
+		value: "nestjs",
+		label: "NestJS",
+		hint: "Opinionated TypeScript framework for scalable server applications"
 	});
 	if (!hasIncompatibleFrontend) backendOptions.push({
 		value: "convex",
@@ -3170,35 +3348,31 @@ async function getBackendFrameworkChoice(backendFramework, frontends, previousVa
 }
 //#endregion
 //#region src/prompts/communication.ts
+const options$1 = [
+	{
+		value: "arara",
+		label: "AraraHQ",
+		hint: "Recommended — WhatsApp messaging via the official Node SDK"
+	},
+	{
+		value: "resend",
+		label: "Resend",
+		hint: "Transactional email for developers"
+	},
+	{
+		value: "notifique",
+		label: "Notifique",
+		hint: "Omnichannel BR messaging API"
+	}
+];
 async function getCommunicationChoice(communication, backend, previousValue) {
-	if (communication !== void 0) return communication;
-	if (backend === "none") return "none";
-	const options = [
-		{
-			value: "none",
-			label: "None",
-			hint: "No email/communication provider"
-		},
-		{
-			value: "resend",
-			label: "Resend",
-			hint: "Transactional email for developers"
-		},
-		{
-			value: "notifique",
-			label: "Notifique",
-			hint: "Omnichannel BR messaging API"
-		},
-		{
-			value: "arara",
-			label: "AraraHQ",
-			hint: "WhatsApp messaging via the official Node SDK"
-		}
-	];
-	const response = await navigableSelect({
-		message: "Select communication provider",
-		options,
-		initialValue: preferValidInitial(options, previousValue, DEFAULT_CONFIG.communication)
+	if (communication !== void 0) return normalizeCommunication$2(communication);
+	if (backend === "none") return [];
+	const response = await navigableMultiselect({
+		message: "Select communication providers",
+		options: options$1,
+		required: false,
+		initialValues: previousValue ?? DEFAULT_CONFIG.communication
 	});
 	if (isCancel$2(response)) throw new UserCancelledError({ message: "Operation cancelled" });
 	return response;
@@ -3354,7 +3528,7 @@ async function getExamplesChoice(examples, database, frontends, backend, api, pr
 		label: "Todo App",
 		hint: "A simple CRUD example app"
 	});
-	if (isExampleAIAllowed(backend, frontends ?? [])) options.push({
+	if (isExampleAIAllowed(backend, frontends ?? []) && isExampleAIAllowedForBackend(backend, "ai")) options.push({
 		value: "ai",
 		label: "AI Chat",
 		hint: "A simple AI chat interface using AI SDK"
@@ -3545,219 +3719,21 @@ async function getObservabilityChoice(observability, previousValue) {
 }
 //#endregion
 //#region src/utils/config-validation.ts
-function validationErr(message) {
-	return Result.err(new ValidationError({ message }));
-}
-function hasResolvedWorkersD1Target(config) {
-	return config.backend === "hono" && config.runtime === "workers" && config.serverDeploy === "cloudflare";
-}
-function hasResolvedSelfCloudflareD1Target(config) {
-	return config.backend === "self" && config.runtime === "none" && config.webDeploy === "cloudflare";
-}
-function canResolveWorkersD1Target(config) {
-	return (config.backend === void 0 || config.backend === "hono") && (config.runtime === void 0 || config.runtime === "workers") && (config.serverDeploy === void 0 || config.serverDeploy === "cloudflare");
-}
-function canResolveSelfCloudflareD1Target(config) {
-	return (config.backend === void 0 || config.backend === "self") && (config.runtime === void 0 || config.runtime === "none") && (config.webDeploy === void 0 || config.webDeploy === "cloudflare");
-}
 /**
-* Pure ORM + database compatibility check. Used by the flag-path
-* validator below and by the orm prompt directly (for flag+prompt
-* combos where one value came from a flag and the other from a
-* prompt).
+* Keeps the prompt-level API stable while compatibility facts live in the
+* shared evaluator.
 */
 function validateOrmDatabaseCompat(orm, database) {
-	if (orm === "mongoose" && database && database !== "mongodb") return validationErr("Mongoose ORM requires MongoDB database. Please use '--database mongodb' or choose a different ORM.");
-	if (orm === "drizzle" && database === "mongodb") return validationErr("Drizzle ORM does not support MongoDB. Please use '--orm mongoose' or '--orm prisma' or choose a different database.");
-	if (database === "mongodb" && orm && orm !== "mongoose" && orm !== "prisma" && orm !== "none") return validationErr("MongoDB database requires Mongoose or Prisma ORM. Please use '--orm mongoose' or '--orm prisma' or choose a different database.");
-	if (database && database !== "none" && orm === "none") return validationErr("Database selection requires an ORM. Please choose '--orm drizzle', '--orm prisma', or '--orm mongoose'.");
-	if (orm && orm !== "none" && database === "none") return validationErr("ORM selection requires a database. Please choose a database or set '--orm none'.");
-	return Result.ok(void 0);
-}
-function validateDatabaseOrmAuth(cfg, flags) {
-	const has = (k) => flags ? flags.has(k) : true;
-	if (!has("orm") || !has("database")) return Result.ok(void 0);
-	return validateOrmDatabaseCompat(cfg.orm, cfg.database);
-}
-function validateDatabaseSetup(config, providedFlags) {
-	const { dbSetup, database, runtime } = config;
-	if (providedFlags.has("dbSetup") && providedFlags.has("database") && dbSetup && dbSetup !== "none" && database === "none") return validationErr("Database setup requires a database. Please choose a database or set '--db-setup none'.");
-	const setupValidations = {
-		turso: {
-			database: "sqlite",
-			errorMessage: "Turso setup requires SQLite database. Please use '--database sqlite' or choose a different setup."
-		},
-		neon: {
-			database: "postgres",
-			errorMessage: "Neon setup requires PostgreSQL database. Please use '--database postgres' or choose a different setup."
-		},
-		"prisma-postgres": {
-			database: "postgres",
-			errorMessage: "Prisma PostgreSQL setup requires PostgreSQL database. Please use '--database postgres' or choose a different setup."
-		},
-		planetscale: { errorMessage: "PlanetScale setup requires PostgreSQL or MySQL database. Please use '--database postgres' or '--database mysql' or choose a different setup." },
-		"mongodb-atlas": {
-			database: "mongodb",
-			errorMessage: "MongoDB Atlas setup requires MongoDB database. Please use '--database mongodb' or choose a different setup."
-		},
-		supabase: {
-			database: "postgres",
-			errorMessage: "Supabase setup requires PostgreSQL database. Please use '--database postgres' or choose a different setup."
-		},
-		d1: {
-			database: "sqlite",
-			errorMessage: "Cloudflare D1 setup requires SQLite database."
-		},
-		docker: { errorMessage: "Docker setup is not compatible with SQLite database or Cloudflare Workers runtime." },
-		none: { errorMessage: "" }
-	};
-	if (dbSetup && dbSetup !== "none") {
-		const validation = setupValidations[dbSetup];
-		if (dbSetup === "planetscale") {
-			if (database !== "postgres" && database !== "mysql") return validationErr(validation.errorMessage);
-		} else if (validation.database && database !== validation.database) return validationErr(validation.errorMessage);
-		if (validation.runtime && runtime !== validation.runtime) return validationErr(validation.errorMessage);
-		if (dbSetup === "d1") {
-			const isWorkersTarget = hasResolvedWorkersD1Target(config);
-			const isSelfCloudflareTarget = hasResolvedSelfCloudflareD1Target(config);
-			const canResolveWorkersTarget = canResolveWorkersD1Target(config);
-			const canResolveSelfCloudflareTarget = canResolveSelfCloudflareD1Target(config);
-			if (!isWorkersTarget && !isSelfCloudflareTarget && !canResolveWorkersTarget && !canResolveSelfCloudflareTarget) return validationErr("Cloudflare D1 setup requires SQLite database and either Cloudflare Workers runtime with server deployment or backend 'self' with Cloudflare web deployment.");
-		}
-		if (dbSetup === "docker") {
-			if (database === "sqlite") return validationErr("Docker setup is not compatible with SQLite database. SQLite is file-based and doesn't require Docker. Please use '--database postgres', '--database mysql', '--database mongodb', or choose a different setup.");
-			if (runtime === "workers") return validationErr("Docker setup is not compatible with Cloudflare Workers runtime. Workers runtime uses serverless databases (D1) and doesn't support local Docker containers. Please use '--db-setup d1' for SQLite or choose a different runtime.");
-		}
-	}
-	return Result.ok(void 0);
-}
-function validateConvexConstraints(config, providedFlags) {
-	const { backend } = config;
-	if (backend !== "convex") return Result.ok(void 0);
-	const has = (k) => providedFlags.has(k);
-	if (has("runtime") && config.runtime !== "none") return validationErr("Convex backend requires '--runtime none'. Please remove the --runtime flag or set it to 'none'.");
-	if (has("database") && config.database !== "none") return validationErr("Convex backend requires '--database none'. Please remove the --database flag or set it to 'none'.");
-	if (has("orm") && config.orm !== "none") return validationErr("Convex backend requires '--orm none'. Please remove the --orm flag or set it to 'none'.");
-	if (has("api") && config.api !== "none") return validationErr("Convex backend requires '--api none'. Please remove the --api flag or set it to 'none'.");
-	if (has("dbSetup") && config.dbSetup !== "none") return validationErr("Convex backend requires '--db-setup none'. Please remove the --db-setup flag or set it to 'none'.");
-	if (has("serverDeploy") && config.serverDeploy !== "none") return validationErr("Convex backend requires '--server-deploy none'. Please remove the --server-deploy flag or set it to 'none'.");
-	if (has("auth") && config.auth === "better-auth") {
-		const incompatibleFrontends = config.frontend?.filter((f) => CONVEX_BETTER_AUTH_INCOMPATIBLE_FRONTENDS.includes(f)) ?? [];
-		const hasSupportedFrontend = supportsConvexBetterAuth(config.frontend);
-		if (incompatibleFrontends.length > 0) return validationErr(`Better Auth with '--backend convex' is not compatible with the following frontends: ${incompatibleFrontends.join(", ")}. Please use a React-based web frontend (next, tanstack-start, tanstack-router, react-router), a supported native frontend, or choose a different auth provider.`);
-		if (!hasSupportedFrontend) return validationErr(`Better Auth with '--backend convex' requires a supported frontend (${CONVEX_BETTER_AUTH_SUPPORTED_FRONTENDS.join(", ")}).`);
-	}
-	return Result.ok(void 0);
-}
-function validateBackendNoneConstraints(config, providedFlags) {
-	const { backend } = config;
-	if (backend !== "none") return Result.ok(void 0);
-	const has = (k) => providedFlags.has(k);
-	if (has("runtime") && config.runtime !== "none") return validationErr("Backend 'none' requires '--runtime none'. Please remove the --runtime flag or set it to 'none'.");
-	if (has("database") && config.database !== "none") return validationErr("Backend 'none' requires '--database none'. Please remove the --database flag or set it to 'none'.");
-	if (has("orm") && config.orm !== "none") return validationErr("Backend 'none' requires '--orm none'. Please remove the --orm flag or set it to 'none'.");
-	if (has("api") && config.api !== "none") return validationErr("Backend 'none' requires '--api none'. Please remove the --api flag or set it to 'none'.");
-	if (has("auth") && config.auth !== "none") return validationErr("Backend 'none' requires '--auth none'. Please remove the --auth flag or set it to 'none'.");
-	if (has("payments") && (config.payments?.length ?? 0) > 0) return validationErr("Backend 'none' requires '--payments none'. Please remove the --payments flag or set it to 'none'.");
-	if (has("communication") && config.communication !== "none") return validationErr("Backend 'none' requires '--communication none'. Please remove the --communication flag or set it to 'none'.");
-	if (has("dbSetup") && config.dbSetup !== "none") return validationErr("Backend 'none' requires '--db-setup none'. Please remove the --db-setup flag or set it to 'none'.");
-	if (has("serverDeploy") && config.serverDeploy !== "none") return validationErr("Backend 'none' requires '--server-deploy none'. Please remove the --server-deploy flag or set it to 'none'.");
-	return Result.ok(void 0);
-}
-function validateSelfBackendConstraints(config, providedFlags) {
-	const { backend } = config;
-	if (backend !== "self") return Result.ok(void 0);
-	const has = (k) => providedFlags.has(k);
-	if (has("runtime") && config.runtime !== "none") return validationErr("Backend 'self' (fullstack) requires '--runtime none'. Please remove the --runtime flag or set it to 'none'.");
-	return Result.ok(void 0);
-}
-function validateBackendConstraints(config, providedFlags, options) {
-	const { backend } = config;
-	if (config.auth === "clerk" && config.frontend) {
-		const incompatibleFrontends = config.frontend.filter((f) => [
-			"nuxt",
-			"svelte",
-			"solid",
-			"astro"
-		].includes(f));
-		if (incompatibleFrontends.length > 0) return validationErr(`Clerk authentication is not compatible with the following frontends: ${incompatibleFrontends.join(", ")}. Please choose a different frontend or auth provider.`);
-	}
-	if (providedFlags.has("backend") && backend && backend !== "convex" && backend !== "none" && backend !== "self") {
-		if (providedFlags.has("runtime") && options.runtime === "none") return validationErr("'--runtime none' is only supported with '--backend convex', '--backend none', or '--backend self'. Please choose 'bun', 'node', or remove the --runtime flag.");
-	}
-	if (backend === "convex" && providedFlags.has("frontend") && options.frontend) {
-		const incompatibleFrontends = options.frontend.filter((f) => f === "solid" || f === "astro");
-		if (incompatibleFrontends.length > 0) return validationErr(`The following frontends are not compatible with '--backend convex': ${incompatibleFrontends.join(", ")}. Please choose a different frontend or backend.`);
-	}
-	return Result.ok(void 0);
-}
-function validateFrontendConstraints(config, providedFlags) {
-	const { frontend } = config;
-	if (frontend && frontend.length > 0) {
-		const singleWebNativeResult = ensureSingleWebAndNative(frontend);
-		if (singleWebNativeResult.isErr()) return singleWebNativeResult;
-		if (providedFlags.has("api") && providedFlags.has("frontend") && config.api) {
-			const apiResult = validateApiFrontendCompatibility(config.api, frontend);
-			if (apiResult.isErr()) return apiResult;
-		}
-	}
-	const hasWebFrontendFlag = (frontend ?? []).some((f) => isWebFrontend(f));
-	const webDeployResult = validateWebDeployRequiresWebFrontend(config.webDeploy, hasWebFrontendFlag);
-	if (webDeployResult.isErr()) return webDeployResult;
-	return Result.ok(void 0);
-}
-function validateApiConstraints(config, options) {
-	if (!isApiCompatibleWithBackend(config.api, config.backend)) return validationErr("Orval API requires the Hono backend in this version. Please use '--backend hono' or choose tRPC/oRPC.");
-	if (config.api === "orval" && options.examples?.includes("todo")) return validationErr("The Orval API layer does not support the generated todo example yet. Please remove 'todo' from --examples or choose tRPC/oRPC.");
-	if (config.api === "none") {
-		if (options.examples?.includes("todo") && options.backend !== "convex" && options.backend !== "none") return validationErr("Cannot use '--examples todo' when '--api' is set to 'none'. The todo example requires an API layer. Please remove 'todo' from --examples or choose an API type.");
-	}
-	return Result.ok(void 0);
-}
-function validateFullConfig(config, providedFlags, options) {
-	return Result.gen(function* () {
-		yield* validateDatabaseOrmAuth(config, providedFlags);
-		yield* validateDatabaseSetup(config, providedFlags);
-		yield* validateConvexConstraints(config, providedFlags);
-		yield* validateBackendNoneConstraints(config, providedFlags);
-		yield* validateSelfBackendConstraints(config, providedFlags);
-		yield* validateBackendConstraints(config, providedFlags, options);
-		yield* validateFrontendConstraints(config, providedFlags);
-		yield* validateTestingAgainstFrontends(config.testing ?? [], config.frontend ?? []);
-		yield* validateApiConstraints(config, options);
-		yield* validateServerDeployRequiresBackend(config.serverDeploy, config.backend);
-		yield* validateDockerServerDeploy(config.serverDeploy, config.backend, config.runtime);
-		yield* validateVercelServerDeploy(config.serverDeploy, config.backend, config.runtime);
-		yield* validateGuaraCloudServerDeploy(config.serverDeploy, config.backend, config.runtime);
-		yield* validateDockerWebDeployDesktopAddons(config.webDeploy, config.addons, config.frontend, config.backend, config.auth);
-		yield* validateSelfBackendCompatibility(providedFlags, options, config);
-		yield* validateWorkersCompatibility(providedFlags, options, config);
-		if (config.runtime === "workers" && config.serverDeploy === "none") yield* validationErr("Cloudflare Workers runtime requires a server deployment. Please choose 'cloudflare' for --server-deploy.");
-		if (providedFlags.has("serverDeploy") && config.serverDeploy === "cloudflare" && config.runtime !== "workers") yield* validationErr(`Server deployment '${config.serverDeploy}' requires '--runtime workers'. Please use '--runtime workers' or choose a different server deployment.`);
-		if (config.addons && config.addons.length > 0) {
-			yield* validateAddonsAgainstFrontends(config.addons, config.frontend, config.auth, config.backend, config.runtime);
-			config.addons = [...new Set(config.addons)];
-		}
-		yield* validateExamplesCompatibility(config.examples ?? [], config.backend, config.database, config.frontend ?? [], config.api);
-		yield* validatePaymentsCompatibility(config.payments, config.auth, config.backend, config.frontend ?? [], config.orm, config.database);
-		yield* validateCommunicationCompatibility(config.communication, config.backend);
-		yield* validateAraraRuntimeCompatibility(config.communication, config.backend, config.runtime, config.serverDeploy);
-		return Result.ok(void 0);
+	return validateWithCompatibilityEvaluator({
+		orm,
+		database
 	});
 }
+function validateFullConfig(config, _providedFlags, options) {
+	return validateWithCompatibilityEvaluator(config, options);
+}
 function validateConfigForProgrammaticUse(config) {
-	return Result.gen(function* () {
-		yield* validateDatabaseOrmAuth(config);
-		if (config.frontend && config.frontend.length > 0) yield* ensureSingleWebAndNative(config.frontend);
-		yield* validateApiFrontendCompatibility(config.api, config.frontend);
-		yield* validateTestingAgainstFrontends(config.testing ?? [], config.frontend ?? []);
-		yield* validatePaymentsCompatibility(config.payments, config.auth, config.backend, config.frontend, config.orm, config.database);
-		yield* validateCommunicationCompatibility(config.communication, config.backend);
-		yield* validateAraraRuntimeCompatibility(config.communication, config.backend, config.runtime, config.serverDeploy);
-		if (config.addons && config.addons.length > 0) yield* validateAddonsAgainstFrontends(config.addons, config.frontend, config.auth, config.backend, config.runtime);
-		yield* validateExamplesCompatibility(config.examples ?? [], config.backend, config.database, config.frontend ?? [], config.api);
-		return Result.ok(void 0);
-	});
+	return validateWithCompatibilityEvaluator(config);
 }
 //#endregion
 //#region src/prompts/orm.ts
@@ -3898,26 +3874,33 @@ const SERVER_APP_BACKENDS = [
 	"hono",
 	"express",
 	"fastify",
-	"elysia"
+	"elysia",
+	"nestjs"
 ];
-function getDeploymentDisplay$1(deployment) {
-	if (deployment === "cloudflare") return {
+const DEPLOYMENT_DISPLAYS$1 = {
+	cloudflare: {
 		label: "Cloudflare",
 		hint: "Deploy to Cloudflare Workers using Alchemy"
-	};
-	if (deployment === "docker") return {
+	},
+	docker: {
 		label: "Docker",
 		hint: "Self-host with a Dockerfile and docker-compose.yml"
-	};
-	if (deployment === "vercel") return {
+	},
+	vercel: {
 		label: "Vercel",
 		hint: "Deploy to Vercel with Services"
-	};
-	if (deployment === "guaracloud") return {
+	},
+	railway: {
+		label: "Railway",
+		hint: "Deploy with Railpack and railway.json"
+	},
+	guaracloud: {
 		label: "Guara Cloud",
 		hint: "Deploy containers on Guara Cloud via GitHub or Docker image"
-	};
-	return {
+	}
+};
+function getDeploymentDisplay$1(deployment) {
+	return DEPLOYMENT_DISPLAYS$1[deployment] ?? {
 		label: deployment,
 		hint: `Add ${deployment} deployment`
 	};
@@ -3930,6 +3913,8 @@ async function getServerDeploymentChoice(deployment, runtime, backend, _webDeplo
 	const options = [
 		"docker",
 		"vercel",
+		"railway",
+		"guaracloud",
 		"none"
 	].map((deploy) => {
 		const { label, hint } = deploy === "none" ? {
@@ -3978,24 +3963,30 @@ async function getTestingChoice(testing, frontends, previousValue) {
 function hasWebFrontend(frontends) {
 	return frontends.some((f) => WEB_FRAMEWORKS.includes(f));
 }
-function getDeploymentDisplay(deployment) {
-	if (deployment === "cloudflare") return {
+const DEPLOYMENT_DISPLAYS = {
+	cloudflare: {
 		label: "Cloudflare",
 		hint: "Deploy to Cloudflare Workers using Alchemy"
-	};
-	if (deployment === "docker") return {
+	},
+	docker: {
 		label: "Docker",
 		hint: "Self-host with a Dockerfile and docker-compose.yml"
-	};
-	if (deployment === "vercel") return {
+	},
+	vercel: {
 		label: "Vercel",
 		hint: "Deploy to Vercel with Services"
-	};
-	if (deployment === "guaracloud") return {
+	},
+	railway: {
+		label: "Railway",
+		hint: "Deploy with Railpack and railway.json"
+	},
+	guaracloud: {
 		label: "Guara Cloud",
 		hint: "Deploy containers on Guara Cloud via GitHub or Docker image"
-	};
-	return {
+	}
+};
+function getDeploymentDisplay(deployment) {
+	return DEPLOYMENT_DISPLAYS[deployment] ?? {
 		label: deployment,
 		hint: `Add ${deployment} deployment`
 	};
@@ -4008,6 +3999,7 @@ async function getDeploymentChoice(deployment, _runtime, backend, frontend = [],
 		"cloudflare",
 		"docker",
 		"vercel",
+		"railway",
 		"guaracloud",
 		"none"
 	].map((deploy) => {
@@ -4043,7 +4035,7 @@ async function gatherConfig(flags, projectName, projectDir, relativePath) {
 		auth: flags.auth ?? DEFAULT_CONFIG.auth,
 		payments: flags.payments ?? DEFAULT_CONFIG.payments,
 		observability: flags.observability ?? DEFAULT_CONFIG.observability,
-		communication: flags.communication ?? DEFAULT_CONFIG.communication,
+		communication: normalizeCommunication$2(flags.communication ?? DEFAULT_CONFIG.communication),
 		addons: flags.addons ?? [...DEFAULT_CONFIG.addons],
 		examples: flags.examples ?? [...DEFAULT_CONFIG.examples],
 		testing: flags.testing ?? [...DEFAULT_CONFIG.testing],
@@ -4118,7 +4110,7 @@ function kuboText(options) {
 		initialValue: options.initialValue,
 		render() {
 			const title = `${cliColors.signal(S_BAR)}\n${cliColors.bright(S_STEP_ACTIVE)}  ${options.message}\n`;
-			const placeholder = options.placeholder ? pc.inverse(options.placeholder[0]) + pc.dim(options.placeholder.slice(1)) : pc.inverse(pc.hidden("_"));
+			const placeholder = options.placeholder ? pc.dim(options.placeholder) : pc.dim("_");
 			const input = this.userInput ? this.userInputWithCursor : placeholder;
 			const value = this.value ?? "";
 			switch (this.state) {
@@ -4200,10 +4192,25 @@ function isTelemetryEnabled() {
 async function sendConvexEvent(payload) {}
 async function trackProjectCreation(config, disableAnalytics = false) {
 	if (!isTelemetryEnabled() || disableAnalytics) return;
-	const { projectName: _projectName, projectDir: _projectDir, relativePath: _relativePath, ...safeConfig } = config;
+	const { database, orm, backend, runtime, frontend, addons, examples, auth, payments, git, packageManager, install, dbSetup, api, webDeploy, serverDeploy } = config;
 	await Result.tryPromise({
 		try: () => sendConvexEvent({
-			...safeConfig,
+			database,
+			orm,
+			backend,
+			runtime,
+			frontend,
+			addons,
+			examples,
+			auth,
+			payments,
+			git,
+			packageManager,
+			install,
+			dbSetup,
+			api,
+			webDeploy,
+			serverDeploy,
 			cli_version: getLatestCLIVersion(),
 			node_version: typeof process !== "undefined" ? process.version : "",
 			platform: typeof process !== "undefined" ? process.platform : ""
@@ -4228,7 +4235,10 @@ function displayConfig(config) {
 	if (config.orm !== void 0) configDisplay.push(`${cliColors.signal("ORM:")} ${String(config.orm)}`);
 	if (config.auth !== void 0) configDisplay.push(`${cliColors.signal("Auth:")} ${String(config.auth)}`);
 	if (config.payments !== void 0) configDisplay.push(`${cliColors.signal("Payments:")} ${config.payments.join(", ") || "none"}`);
-	if (config.communication !== void 0) configDisplay.push(`${cliColors.signal("Communication:")} ${String(config.communication)}`);
+	if (config.communication !== void 0) {
+		const communication = normalizeCommunication$2(config.communication);
+		configDisplay.push(`${cliColors.signal("Communication:")} ${communication.join(", ") || "none"}`);
+	}
 	if (config.observability !== void 0) configDisplay.push(`${cliColors.signal("Observability:")} ${config.observability.join(", ") || "none"}`);
 	if (config.addons !== void 0) {
 		const addons = Array.isArray(config.addons) ? config.addons : [config.addons];
@@ -4388,7 +4398,7 @@ const TEMPLATE_PRESETS = {
 		auth: "better-auth",
 		payments: [],
 		observability: ["getmonitor"],
-		communication: "none",
+		communication: [],
 		addons: ["turborepo"],
 		examples: ["todo"],
 		dbSetup: "mongodb-atlas",
@@ -4405,7 +4415,7 @@ const TEMPLATE_PRESETS = {
 		auth: "better-auth",
 		payments: [],
 		observability: ["getmonitor"],
-		communication: "none",
+		communication: [],
 		addons: ["turborepo"],
 		examples: ["todo"],
 		dbSetup: "none",
@@ -4422,7 +4432,7 @@ const TEMPLATE_PRESETS = {
 		auth: "better-auth",
 		payments: [],
 		observability: ["getmonitor"],
-		communication: "none",
+		communication: [],
 		addons: ["biome", "turborepo"],
 		examples: ["none"],
 		dbSetup: "none",
@@ -4439,7 +4449,7 @@ const TEMPLATE_PRESETS = {
 		auth: "none",
 		payments: [],
 		observability: [],
-		communication: "none",
+		communication: [],
 		addons: ["none"],
 		examples: ["none"],
 		dbSetup: "none",
@@ -4535,6 +4545,7 @@ const formatOptions = {
 /** Files that must not be rewritten by post-scaffold formatters. */
 const SKIP_FILE_NAMES = new Set([
 	"kubojs.jsonrc",
+	"kubo.config.ts",
 	"package-lock.json",
 	"pnpm-lock.yaml",
 	"yarn.lock",
@@ -6117,7 +6128,8 @@ function getDesktopStaticBuildNote(frontend) {
 	return `${pc$1.yellow("NOTE:")} Desktop builds package static web assets.\n   ${staticBuildFrontends.get(staticBuildFrontend)} needs a static/export web build before desktop packaging will work.`;
 }
 async function displayPostInstallInstructions(config) {
-	const { api, database, relativePath, packageManager, depsInstalled, orm, addons, testing, runtime, frontend, backend, dbSetup, webDeploy, serverDeploy, observability, communication } = config;
+	const { api, database, relativePath, packageManager, depsInstalled, orm, addons, testing, runtime, frontend, backend, dbSetup, webDeploy, serverDeploy, observability, communication: rawCommunication } = config;
+	const communication = normalizeCommunication$2(rawCommunication ?? []);
 	const isConvex = backend === "convex";
 	const isBackendSelf = backend === "self";
 	const runCmd = packageManager === "npm" ? "npm run" : packageManager === "pnpm" ? "pnpm run" : "bun run";
@@ -6140,9 +6152,9 @@ async function displayPostInstallInstructions(config) {
 	const clerkInstructions = config.auth === "clerk" ? getClerkInstructions(frontend || [], backend, api) : "";
 	const alchemyDeployInstructions = getAlchemyDeployInstructions(runCmd, webDeploy, serverDeploy, backend);
 	const getMonitorInstructions = observability.includes("getmonitor") ? getGetMonitorInstructions() : "";
-	const resendInstructions = communication === "resend" ? getResendInstructions() : "";
-	const notifiqueInstructions = communication === "notifique" ? getNotifiqueInstructions() : "";
-	const araraInstructions = communication === "arara" ? getAraraInstructions(backend) : "";
+	const resendInstructions = communication.includes("resend") ? getResendInstructions() : "";
+	const notifiqueInstructions = communication.includes("notifique") ? getNotifiqueInstructions() : "";
+	const araraInstructions = communication.includes("arara") ? getAraraInstructions(backend) : "";
 	const hasWeb = frontend?.some((f) => types_exports.desktopWebFrontends.includes(f));
 	const hasNative = frontend?.includes("native-bare") || frontend?.includes("native-uniwind") || frontend?.includes("native-unistyles");
 	const webPort = (0, types_exports.getWebPort)(frontend ?? []);
@@ -6540,7 +6552,7 @@ function createEmptyResult(timeScaffolded, elapsedTimeMs, error) {
 			auth: "none",
 			payments: [],
 			observability: [],
-			communication: "none",
+			communication: [],
 			git: false,
 			packageManager: "npm",
 			install: false,
@@ -7074,7 +7086,7 @@ async function createVirtual(options) {
 		auth: options.auth || "none",
 		payments: rawPayments === "none" ? [] : Array.isArray(rawPayments) ? rawPayments : rawPayments ? [rawPayments] : [],
 		observability: options.disableObservability ? [] : rawObservability === "none" ? [] : Array.isArray(rawObservability) ? rawObservability : rawObservability ? [rawObservability] : [],
-		communication: options.communication || "none",
+		communication: options.communication ? (0, types_exports.normalizeCommunication)(options.communication) : [],
 		git: options.git ?? false,
 		packageManager: options.packageManager || "bun",
 		install: false,
@@ -7105,6 +7117,7 @@ async function createVirtual(options) {
 	if (validationResult.isErr()) return Result.err(new GeneratorError({
 		message: validationResult.error.message,
 		phase: "validation",
+		compatibilityCode: validationResult.error.compatibilityCode,
 		cause: validationResult.error
 	}));
 	return generate({