@posthog/wizard 2.65.0 → 2.67.0

package/dist/bin.js

@@ -1,28 +1,29 @@
 #!/usr/bin/env node
-import { Ct as isHeadless, L as Integration, St as headlessOption, U as POSTHOG_DOCS_URL, a as getLogFilePath, f as getUI, gt as VERSION, m as LoggingUI, mt as getSkillsBaseUrl, p as setUI, pt as WIZARD_USER_AGENT, r as debug, s as logToFile, wt as regionOption } from "./debug-Cm1hvkVy.js";
-import { a as getLocalDev, i as checkLocalServices, o as initLocalDev, r as POSTHOG_LOCAL_URL, s as localMcpSkillsNotice } from "./local-dev-BN6NKQ0B.js";
-import { n as analytics } from "./analytics-zBrIVjMV.js";
-import { r as setEntryCommand } from "./telemetry-By56gAtF.js";
-import { a as safeReadFile, o as walkProjectFiles } from "./bounded-fs-DqsVmh4r.js";
-import { n as isUsingTypeScript } from "./setup-utils-Cz0wPLsQ.js";
-import { o as handleApiError } from "./api-Wgb7AhrP.js";
-import "./wizard-session-Bn6dO1gE.js";
-import { i as wizardAbort, r as runCleanups } from "./wizard-abort-CzwID162.js";
-import { n as isNonInteractiveEnvironment } from "./environment-BhFvfkQg.js";
-import { n as runAgent, s as authenticate } from "./agent-runner-Ca-e2TOQ.js";
-import { p as writeJsonAtomic } from "./queue-tools-BREbgGSC.js";
-import { C as WIZARD_TOOL_NAMES, E as fetchSkillMenu, l as recoverOrphanedSettingsBackups, p as AgentSignals } from "./agent-interface-ORzGEFNM.js";
-import { S as SETUP_REPORT_FILE, _ as AUDIT_CHECKS_KEY, g as AUDIT_CHECKS_FILE, v as AUDIT_REPORT_FILE } from "./yara-hooks-BrisBebM.js";
-import { i as SPINNER_MESSAGE, t as FRAMEWORK_REGISTRY } from "./registry-DGJQ_8QI.js";
-import { C as scopeInstallDirToProject, D as detectFramework, E as gatherFrameworkContext, S as detectIntegrationProjects, T as resolveProjectDir, _ as HEALTH_CHECK_STEP, a as LINE_CHART_BLOCK, b as getDetectedWarehouseSources, d as isClearBlock, g as detectPostHogIntegration, h as Icons, i as FUNNEL_BLOCK, m as Colors, n as integrationRunStep, o as PRODUCT_SUITE_BLOCK, r as posthogIntegrationConfig, s as StatusPeekTrigger, u as wordWrap, v as WAREHOUSE_ABORT_CASES, x as detectWarehouseSources, y as detectWarehousePrerequisites } from "./posthog-integration-CoPvN6YZ.js";
-import { n as readApiKeyFromEnv } from "./env-api-key-CdI2XZIz.js";
+import { a as AgentSignals, c as emitWizardError, l as ErrorCodes, r as detectErrorCode } from "./errors-BHervYGs.js";
+import { Ct as isHeadless, L as Integration, St as headlessOption, U as POSTHOG_DOCS_URL, a as getLogFilePath, f as getUI, gt as VERSION, m as LoggingUI, mt as getSkillsBaseUrl, p as setUI, pt as WIZARD_USER_AGENT, r as debug, s as logToFile, wt as regionOption } from "./debug-BsHD83Vy.js";
+import { a as getLocalDev, i as checkLocalServices, o as initLocalDev, r as POSTHOG_LOCAL_URL, s as localMcpSkillsNotice } from "./local-dev-DPZiIPCK.js";
+import { n as analytics } from "./analytics-CtIYzkK4.js";
+import { r as setEntryCommand } from "./telemetry-Vi9dWddJ.js";
+import { a as safeReadFile, o as walkProjectFiles } from "./bounded-fs-BWqoFQvQ.js";
+import { n as isUsingTypeScript } from "./setup-utils-D1tv0v_R.js";
+import { o as handleApiError } from "./api-BJft9v6K.js";
+import "./wizard-session-Cex1BiXs.js";
+import { i as wizardAbort, r as runCleanups } from "./wizard-abort-CGv3lVxw.js";
+import { n as isNonInteractiveEnvironment } from "./environment-C7CKGIOE.js";
+import { n as runAgent, s as authenticate } from "./agent-runner-DD65OMkB.js";
+import { m as writeJsonAtomic } from "./queue-tools-BC9HxOV6.js";
+import { T as WIZARD_TOOL_NAMES, k as fetchSkillMenu, l as recoverOrphanedSettingsBackups } from "./agent-interface-tM_b0l__.js";
+import { S as SETUP_REPORT_FILE, _ as AUDIT_CHECKS_KEY, g as AUDIT_CHECKS_FILE, v as AUDIT_REPORT_FILE } from "./yara-hooks-DZIVzhA6.js";
+import { i as SPINNER_MESSAGE, t as FRAMEWORK_REGISTRY } from "./registry-DCAElOyj.js";
+import { C as scopeInstallDirToProject, D as detectFramework, E as gatherFrameworkContext, S as detectIntegrationProjects, T as resolveProjectDir, _ as HEALTH_CHECK_STEP, a as LINE_CHART_BLOCK, b as getDetectedWarehouseSources, d as isClearBlock, g as detectPostHogIntegration, h as Icons, i as FUNNEL_BLOCK, m as Colors, n as integrationRunStep, o as PRODUCT_SUITE_BLOCK, r as posthogIntegrationConfig, s as StatusPeekTrigger, u as wordWrap, v as WAREHOUSE_ABORT_CASES, x as detectWarehouseSources, y as detectWarehousePrerequisites } from "./posthog-integration-DFfBRGOC.js";
+import { n as readApiKeyFromEnv } from "./env-api-key-DS0ghlcO.js";
 import { satisfies } from "semver";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { existsSync, readFileSync, readdirSync, statSync } from "fs";
 import path, { join, relative } from "path";
 import * as os from "node:os";
-import * as path$1 from "node:path";
+import * as path$2 from "node:path";
 import { join as join$1 } from "node:path";
 import { spawnSync } from "node:child_process";
 import * as fs$1 from "node:fs";
@@ -132,6 +133,10 @@ var Wizard = class Wizard {
 		}).strictOptions().strictCommands().fail((msg, err) => {
 			const text = msg || err && err.message || "Invalid arguments";
 			process.stderr.write(`\n\x1b[1;91m✖ ${text}\x1b[0m\n  Run \`wizard --help\` to see available commands and options.\n\n`);
+			emitWizardError({
+				code: ErrorCodes.CliBadArgs,
+				message: text
+			});
 			process.exit(1);
 		}).help().alias("help", "h").version().alias("version", "v");
 	}
@@ -152,18 +157,30 @@ var Wizard = class Wizard {
 			const envHasCI = process.env.POSTHOG_WIZARD_CI != null && process.env.POSTHOG_WIZARD_CI !== "";
 			if (argvHasCI || envHasCI) {
 				process.stderr.write(`\n\x1b[1;91m✖ CI mode is not currently supported in published builds.\x1b[0m\n\n`);
+				emitWizardError({
+					code: ErrorCodes.CliFlagUnavailable,
+					message: "CI mode is not supported in published builds."
+				});
 				process.exit(1);
 			}
 			const argvHasOverride = args.some((a) => a === "--harness" || a.startsWith("--harness=") || a === "--sequence" || a.startsWith("--sequence=") || a === "--model" || a.startsWith("--model=") || a === "--capture-aio" || a === "--no-capture-aio" || a.startsWith("--capture-aio="));
 			const envHasOverride = process.env.POSTHOG_WIZARD_HARNESS != null && process.env.POSTHOG_WIZARD_HARNESS !== "" || process.env.POSTHOG_WIZARD_SEQUENCE != null && process.env.POSTHOG_WIZARD_SEQUENCE !== "" || process.env.POSTHOG_WIZARD_MODEL != null && process.env.POSTHOG_WIZARD_MODEL !== "" || process.env.POSTHOG_WIZARD_CAPTURE_AIO != null && process.env.POSTHOG_WIZARD_CAPTURE_AIO !== "";
 			if (argvHasOverride || envHasOverride) {
 				process.stderr.write(`\n\x1b[1;91m✖ The --harness, --sequence, --model, and --capture-aio overrides are not available in published builds.\x1b[0m\n\n`);
+				emitWizardError({
+					code: ErrorCodes.CliFlagUnavailable,
+					message: "The --harness, --sequence, --model, and --capture-aio overrides are not available in published builds."
+				});
 				process.exit(1);
 			}
 			const argvHasLocalTarget = args.some((a) => LOCAL_TARGET_FLAGS.some((f) => a === `--${f}` || a === `--no-${f}` || a.startsWith(`--${f}=`)));
 			const envHasLocalTarget = LOCAL_TARGET_ENV_VARS.some((k) => process.env[k] != null && process.env[k] !== "");
 			if (argvHasLocalTarget || envHasLocalTarget) {
 				process.stderr.write("\n\x1B[1;91m✖ The --local-dev, --local-context-mill, --local-mcp, and --local-posthog targets are not available in published builds.\x1B[0m\n  They point the wizard at development servers on localhost.\n\n");
+				emitWizardError({
+					code: ErrorCodes.CliFlagUnavailable,
+					message: "The --local-dev, --local-context-mill, --local-mcp, and --local-posthog targets are not available in published builds."
+				});
 				process.exit(1);
 			}
 		}
@@ -225,7 +242,7 @@ function runProvision(argv) {
 }
 async function provision({ email, region, name, baseUrl, jsonMode }) {
 	try {
-		const { provisionNewAccount } = await import("./provisioning-BYFSHSHY.js").then((n) => n.r);
+		const { provisionNewAccount } = await import("./provisioning-Cvy_vQHV.js").then((n) => n.r);
 		if (!jsonMode) getUI().log.info(`Provisioning account for ${email} in ${region}...`);
 		emitResult(await provisionNewAccount(email, name, region, { baseUrl }), jsonMode);
 		process.exit(0);
@@ -292,22 +309,22 @@ const basicIntegrationCommand = {
 		setEntryCommand("integrate");
 		(async () => {
 			if (isHeadless(argv)) {
-				const { runHeadlessInstall } = await import("./ci-install-D1QqmJIc.js");
+				const { runHeadlessInstall } = await import("./ci-install-BXGnVI7T.js");
 				return runHeadlessInstall(argv);
 			}
 			if (argv.ci) {
-				const { runCIInstall } = await import("./ci-install-D1QqmJIc.js");
+				const { runCIInstall } = await import("./ci-install-BXGnVI7T.js");
 				return runCIInstall(argv);
 			}
 			if (isNonInteractiveEnvironment()) {
-				const { failNonInteractive } = await import("./non-interactive-BA2L_jDT.js");
+				const { failNonInteractive } = await import("./non-interactive-Cr-chffe.js");
 				return failNonInteractive();
 			}
 			if (argv.playground) {
-				const { runPlayground } = await import("./playground-xkEke_h0.js");
+				const { runPlayground } = await import("./playground-DQ633rje.js");
 				return runPlayground();
 			}
-			const { runInteractive } = await import("./interactive-DxHFVYr2.js");
+			const { runInteractive } = await import("./interactive-DUpW84WU.js");
 			runInteractive(argv);
 		})();
 	}
@@ -592,7 +609,10 @@ function buildPrompt(session) {
 		"The wizard detected the following data warehouse sources in this project:",
 		...sources.map((s) => `- ${s.label} (kind: ${s.kind}, mode: ${s.mode}) — ${s.matchedSignal}`),
 		"",
-		"Set these up in PostHog following the skill instructions: create `in-cli` sources directly via the PostHog MCP after collecting credentials; for `deep-link` sources, provide the user the pre-filled new-source URL."
+		"Each signal names the file it came from. Trust that path — the wizard read it. To confirm a key is set, call `check_env_keys` with the key names and no `filePath`; it scans every `.env` file in the project.",
+		"",
+		"Set these up in PostHog following the skill instructions: create `in-cli` sources directly via the PostHog MCP after collecting credentials; for `deep-link` sources, provide the user the pre-filled new-source URL.",
+		"Use the `kind` string exactly as printed above for `source_type` — PostHog rejects the display label."
 	].join("\n");
 }
 const warehouseSourceConfig = {
@@ -683,6 +703,7 @@ function createSkillProgram(opts) {
 *  defined in the skill's `Abort statuses` section. */
 const AUDIT_ABORT_CASES = [{
 	match: /^no posthog sdk found$/i,
+	errorCode: ErrorCodes.DetectNoPosthogSdk,
 	message: "No PostHog SDK found",
 	body: "The audit needs an existing PostHog integration to review. No PostHog SDK appears in this project’s dependency manifests. Run the basic integration program to install PostHog first, then re-run the audit.",
 	docsUrl: "https://posthog.com/docs/getting-started/install"
@@ -1186,12 +1207,14 @@ const WEB_ANALYTICS_ABORT_CASES = [
 	},
 	{
 		match: /^insufficient permissions$/i,
+		errorCode: ErrorCodes.AuthMissingScope,
 		message: "Insufficient permissions",
 		body: "The doctor could not query your project — the authenticated token is missing query access. Re-run the wizard to sign in again, or use a key with read access to your events.",
 		docsUrl: "https://posthog.com/docs/web-analytics"
 	},
 	{
 		match: /^posthog sdk not installed$/i,
+		errorCode: ErrorCodes.DetectNoPosthogSdk,
 		message: "PostHog SDK not installed",
 		body: "The doctor could not find a PostHog SDK in this project. Install and configure PostHog first (run `npx @posthog/wizard`), then run the doctor to check your web analytics setup.",
 		docsUrl: "https://posthog.com/docs/libraries/js"
@@ -1888,6 +1911,7 @@ const GO_SDK_MODULE = "github.com/posthog/posthog-go";
 const SOURCE_MAPS_ABORT_CASES = [
 	{
 		match: /^no posthog sdk detected$/i,
+		errorCode: ErrorCodes.DetectNoPosthogSdk,
 		message: "No PostHog SDK detected",
 		body: "The agent could not find a PostHog SDK in your project. Source map upload requires the SDK to already be installed so it can report errors. Run `npx @posthog/wizard` first to install the SDK (for Go and Rust, add posthog-go / posthog-rs by hand first — the wizard cannot install the SDK for those stacks yet).",
 		docsUrl: "https://posthog.com/docs/error-tracking"
@@ -1900,6 +1924,7 @@ const SOURCE_MAPS_ABORT_CASES = [
 	},
 	{
 		match: /^bare react native not supported$/i,
+		errorCode: ErrorCodes.DetectUnsupportedPlatform,
 		message: "Bare React Native is not supported",
 		body: "Source-map upload for React Native requires Expo, and this project has no `expo` package. Bare React Native builds cannot inject the chunk IDs PostHog needs to resolve stack traces.",
 		docsUrl: "https://posthog.com/docs/error-tracking/upload-source-maps/react-native"
@@ -1976,8 +2001,12 @@ STEP 5 — Write the credentials to the env file. (skill: "Write credentials to
    Use the wizard-tools MCP server. Reuse the env file the skill tells you to
    pick — the prerequisite PostHog integration usually already wrote
    POSTHOG_* vars to one, so seed your keys alongside them.
-   - First call check_env_keys on that file (returns present/absent, never
-     values — don't read the file directly).
+   - First call check_env_keys with the key names and that file as filePath.
+     It answers { status: "present" | "missing", foundIn: [paths] } per key —
+     names and paths only, never values, so don't read the file directly.
+     "present" means a real env file sets the key; a key found only in a
+     committed template (.env.example and friends) reads as "missing",
+     because a template documents a key rather than setting it.
    - Env tool path rule: ${inSubproject ? `Tool filePaths are relative to the wizard's working directory, not the selected project directory. Treat the skill's env path as relative to the selected project and prefix it with \`${projectPath}/\` when calling the tools: for example, pass \`${projectPath}/.env\`, not \`.env\` (which would target the wizard's working directory).${variant === "rust" ? ` Cargo workspace exception: when the skill places the env file at the workspace root instead, pass the path of the ROOT manifest's directory relative to the wizard's working directory (e.g. \`rust/.env\` for a workspace root at \`rust/\`, or plain \`.env\` when the workspace root IS the working directory) — not the member path.` : ""}` : `Tool filePaths are relative to the wizard's working directory. For an env file at this project root, pass \`.env\`; never prefix it with this directory's path inside an ancestor repository.`}
    - Then call set_env_values, passing the STEP 1 secretRef as a value
      object, not a literal string:
@@ -2478,7 +2507,7 @@ const getContentBlocks$1 = (store) => pace([
 //#region src/steps/install-cli-steering/index.ts
 const dirExists = (...segments) => {
 	try {
-		return fs$1.existsSync(path$1.join(os.homedir(), ...segments));
+		return fs$1.existsSync(path$2.join(os.homedir(), ...segments));
 	} catch {
 		return false;
 	}
@@ -2487,19 +2516,19 @@ const CLI_STEERING_TARGETS = [
 	{
 		id: "claude-code",
 		name: "Claude Code",
-		instructionsPath: () => path$1.join(os.homedir(), ".claude", "CLAUDE.md"),
+		instructionsPath: () => path$2.join(os.homedir(), ".claude", "CLAUDE.md"),
 		isDetected: () => dirExists(".claude")
 	},
 	{
 		id: "codex",
 		name: "Codex",
-		instructionsPath: () => path$1.join(os.homedir(), ".codex", "AGENTS.md"),
+		instructionsPath: () => path$2.join(os.homedir(), ".codex", "AGENTS.md"),
 		isDetected: () => dirExists(".codex")
 	},
 	{
 		id: "gemini",
 		name: "Gemini CLI",
-		instructionsPath: () => path$1.join(os.homedir(), ".gemini", "GEMINI.md"),
+		instructionsPath: () => path$2.join(os.homedir(), ".gemini", "GEMINI.md"),
 		isDetected: () => dirExists(".gemini")
 	}
 ];
@@ -2844,6 +2873,7 @@ const SELF_DRIVING_ABORT_CASES = [
 	},
 	{
 		match: /^requires-interactive-mode$/i,
+		errorCode: ErrorCodes.CliInteractiveRequired,
 		message: "Interactive terminal required",
 		body: "Self-driving setup asks questions along the way (GitHub and issue trackers), so it needs an interactive terminal. Run the wizard outside CI / non-interactive mode."
 	},
@@ -3857,6 +3887,29 @@ const mcpTutorialConfig = {
 //#region src/lib/programs/mcp-analytics/index.ts
 const MCP_ANALYTICS_REPORT_FILE = "posthog-mcp-analytics-report.md";
 /**
+* `[ABORT]` reasons the mcp-analytics skill emits when the project can't be
+* instrumented. Kept in sync with the stop conditions in the skill's
+* `description.md` (context-mill `context/skills/mcp-analytics`).
+*/
+const MCP_ANALYTICS_ABORT_CASES = [
+	{
+		match: /^unsupported language for mcp analytics$/i,
+		errorCode: ErrorCodes.DetectUnsupportedPlatform,
+		message: "Unsupported language for MCP analytics",
+		body: "MCP analytics supports TypeScript/JavaScript (`@posthog/mcp`) and Python (`posthog.mcp`, shipped inside the `posthog` package). This project doesn't look like either, so there's nothing to instrument. See https://posthog.com/docs/mcp-analytics for the supported setups."
+	},
+	{
+		match: /^no mcp server found$/i,
+		message: "No MCP server found",
+		body: "This command instruments an existing MCP server with PostHog analytics, but no MCP server was found in this project. If you just want PostHog product analytics, run `npx @posthog/wizard` instead."
+	},
+	{
+		match: /^could not locate the server entry point$/i,
+		message: "Could not locate the MCP server entry point",
+		body: "This project has MCP signals, but the agent couldn't find where the server is constructed or requests are dispatched, so there's nowhere safe to add instrumentation. See https://posthog.com/docs/mcp-analytics for the supported server styles, or point the wizard at the package that defines the server if it's in a monorepo subdirectory."
+	}
+];
+/**
 * `wizard mcp-analytics` — flat skill command.
 *
 * Instruments the user's own MCP server with the `@posthog/mcp` SDK so it
@@ -3882,23 +3935,7 @@ const mcpAnalyticsConfig = createSkillProgram({
 	docsUrl: "https://posthog.com/docs/mcp-analytics",
 	spinnerMessage: "Setting up MCP analytics...",
 	estimatedDurationMinutes: 5,
-	abortCases: [
-		{
-			match: /^unsupported language for mcp analytics$/i,
-			message: "Unsupported language for MCP analytics",
-			body: "MCP analytics supports TypeScript/JavaScript (`@posthog/mcp`) and Python (`posthog.mcp`, shipped inside the `posthog` package). This project doesn't look like either, so there's nothing to instrument. See https://posthog.com/docs/mcp-analytics for the supported setups."
-		},
-		{
-			match: /^no mcp server found$/i,
-			message: "No MCP server found",
-			body: "This command instruments an existing MCP server with PostHog analytics, but no MCP server was found in this project. If you just want PostHog product analytics, run `npx @posthog/wizard` instead."
-		},
-		{
-			match: /^could not locate the server entry point$/i,
-			message: "Could not locate the MCP server entry point",
-			body: "This project has MCP signals, but the agent couldn't find where the server is constructed or requests are dispatched, so there's nowhere safe to add instrumentation. See https://posthog.com/docs/mcp-analytics for the supported server styles, or point the wizard at the package that defines the server if it's in a monorepo subdirectory."
-		}
-	]
+	abortCases: MCP_ANALYTICS_ABORT_CASES
 });
 //#endregion
 //#region src/lib/programs/replay-vision/index.ts
@@ -3936,8 +3973,10 @@ const REPLAY_VISION_SUPPORTED = new Set([
 	"flutter"
 ]);
 async function abortUnsupportedPlatform(integration) {
+	const name = FRAMEWORK_REGISTRY[integration]?.metadata.name ?? integration;
 	await wizardAbort({
-		message: `Session replay isn't available for ${FRAMEWORK_REGISTRY[integration]?.metadata.name ?? integration} projects, and Replay vision needs session recordings to watch — so there is nothing to set up here.
+		code: ErrorCodes.DetectUnsupportedPlatform,
+		message: `Session replay isn't available for ${name} projects, and Replay vision needs session recordings to watch — so there is nothing to set up here.
 
 If this repo also contains a web or mobile app, run the command from that project directory instead. See what replay supports at:
   https://posthog.com/docs/session-replay`,
@@ -4016,7 +4055,10 @@ const replayVisionConfig = {
 		await scopeInstallDirToProject(session);
 		const integration = await detectFramework(session.installDir);
 		if (!integration) {
-			await wizardAbort({ message: "Could not auto-detect your framework for this project." });
+			await wizardAbort({
+				code: ErrorCodes.DetectNoFramework,
+				message: "Could not auto-detect your framework for this project."
+			});
 			return;
 		}
 		if (!REPLAY_VISION_SUPPORTED.has(integration)) {
@@ -4275,20 +4317,30 @@ const mcpAddCommand = {
 		"api-key": {
 			describe: "PostHog personal API key (phx_xxx) for MCP authentication",
 			type: "string"
-		}
+		},
+		...headlessOption
 	},
 	handler: runMcpAdd
 };
 function runMcpAdd(argv) {
 	const features = parseFeatures(argv.features);
 	(async () => {
-		const { readApiKeyFromEnv } = await import("./env-api-key-CdI2XZIz.js").then((n) => n.t);
+		const { readApiKeyFromEnv } = await import("./env-api-key-DS0ghlcO.js").then((n) => n.t);
 		const apiKey = argv.apiKey || readApiKeyFromEnv();
 		const debug = argv.debug;
 		const localMcp = argv.local;
+		const args = {
+			local: localMcp,
+			features,
+			apiKey
+		};
+		if (isHeadless(argv)) {
+			await runHeadlessAdd(args);
+			return;
+		}
 		try {
-			const { startTUI } = await import("./start-tui-DDW9uVnD.js");
-			const { buildSession } = await import("./wizard-session-UxA_A0cA.js");
+			const { startTUI } = await import("./start-tui-B5YfmqNr.js");
+			const { buildSession } = await import("./wizard-session-DHbUcjI7.js");
 			const tui = startTUI(VERSION, Program.McpAdd);
 			tui.store.session = buildSession({
 				debug,
@@ -4299,16 +4351,16 @@ function runMcpAdd(argv) {
 			});
 		} catch (error) {
 			if (!isTUIUnavailable(error)) throw error;
-			setUI(new LoggingUI());
-			const { addMCPServerToClientsStep } = await import("./add-mcp-server-to-clients-ArtlMX9-.js").then((n) => n.r);
-			await addMCPServerToClientsStep({
-				local: localMcp,
-				features,
-				apiKey
-			});
+			await runHeadlessAdd(args);
 		}
 	})();
 }
+async function runHeadlessAdd(args) {
+	setUI(new LoggingUI());
+	const { addMCPServerToClientsStep } = await import("./add-mcp-server-to-clients-DHTRbyJX.js").then((n) => n.r);
+	const { installed, failed } = await addMCPServerToClientsStep(args);
+	if (failed.length > 0 || installed.length === 0) process.exitCode = 1;
+}
 function parseFeatures(raw) {
 	if (typeof raw !== "string") return void 0;
 	return raw.split(",").map((s) => s.trim()).filter(Boolean);
@@ -4318,20 +4370,27 @@ function parseFeatures(raw) {
 const mcpRemoveCommand = {
 	name: "remove",
 	description: "Remove PostHog MCP server from supported clients",
-	options: { local: {
-		default: false,
-		describe: "Remove local development MCP server (http://localhost:8787)",
-		type: "boolean"
-	} },
+	options: {
+		local: {
+			default: false,
+			describe: "Remove local development MCP server (http://localhost:8787)",
+			type: "boolean"
+		},
+		...headlessOption
+	},
 	handler: runMcpRemove
 };
 function runMcpRemove(argv) {
 	(async () => {
 		const debug = argv.debug;
 		const localMcp = argv.local;
+		if (isHeadless(argv)) {
+			await runHeadlessRemove(localMcp);
+			return;
+		}
 		try {
-			const { startTUI } = await import("./start-tui-DDW9uVnD.js");
-			const { buildSession } = await import("./wizard-session-UxA_A0cA.js");
+			const { startTUI } = await import("./start-tui-B5YfmqNr.js");
+			const { buildSession } = await import("./wizard-session-DHbUcjI7.js");
 			const tui = startTUI(VERSION, Program.McpRemove);
 			tui.store.session = buildSession({
 				debug,
@@ -4340,12 +4399,16 @@ function runMcpRemove(argv) {
 			});
 		} catch (error) {
 			if (!isTUIUnavailable(error)) throw error;
-			setUI(new LoggingUI());
-			const { removeMCPServerFromClientsStep } = await import("./add-mcp-server-to-clients-ArtlMX9-.js").then((n) => n.r);
-			await removeMCPServerFromClientsStep({ local: localMcp });
+			await runHeadlessRemove(localMcp);
 		}
 	})();
 }
+/** No exit code on an empty result: nothing to remove is the requested end state. */
+async function runHeadlessRemove(local) {
+	setUI(new LoggingUI());
+	const { removeMCPServerFromClientsStep } = await import("./add-mcp-server-to-clients-DHTRbyJX.js").then((n) => n.r);
+	await removeMCPServerFromClientsStep({ local });
+}
 //#endregion
 //#region src/commands/mcp/tutorial.ts
 const mcpTutorialCommand = {
@@ -4363,8 +4426,8 @@ function runMcpTutorial(argv) {
 		const debug = argv.debug;
 		const localMcp = argv.local;
 		try {
-			const { startTUI } = await import("./start-tui-DDW9uVnD.js");
-			const { buildSession } = await import("./wizard-session-UxA_A0cA.js");
+			const { startTUI } = await import("./start-tui-B5YfmqNr.js");
+			const { buildSession } = await import("./wizard-session-DHbUcjI7.js");
 			const tui = startTUI(VERSION, Program.McpTutorial);
 			tui.store.session = buildSession({
 				debug,
@@ -4374,6 +4437,10 @@ function runMcpTutorial(argv) {
 		} catch (err) {
 			setUI(new LoggingUI());
 			getUI().log.error(`The MCP tutorial requires an interactive terminal. ${err instanceof Error ? err.message : String(err)}`);
+			emitWizardError({
+				code: ErrorCodes.CliInteractiveRequired,
+				message: "The MCP tutorial requires an interactive terminal."
+			});
 			process.exit(1);
 		}
 	})();
@@ -4445,17 +4512,17 @@ function runWizard(config, options) {
 	(async () => {
 		try {
 			const installDir = options.installDir || process.cwd();
-			const { startTUI } = await import("./start-tui-DDW9uVnD.js");
-			const { buildSession, RunPhase } = await import("./wizard-session-UxA_A0cA.js");
-			const { TaskStreamPush } = await import("./task-stream-BK7JQ27G.js");
-			const { PostHogDestination } = await import("./posthog-9To56cSd.js");
+			const { startTUI } = await import("./start-tui-B5YfmqNr.js");
+			const { buildSession, RunPhase } = await import("./wizard-session-DHbUcjI7.js");
+			const { TaskStreamPush } = await import("./task-stream-DSzvwJrD.js");
+			const { PostHogDestination } = await import("./posthog-DSn9bIZc.js");
 			const local = getLocalDev();
 			const localServicesError = await checkLocalServices({
 				...local,
 				localPosthog: local.localPosthog && !options.baseUrl
 			});
 			if (localServicesError) {
-				const { wizardAbort } = await import("./wizard-abort-BlDla_Jd.js");
+				const { wizardAbort } = await import("./wizard-abort-BsNbguJt.js");
 				await wizardAbort({ message: localServicesError });
 				return;
 			}
@@ -4526,7 +4593,7 @@ function runWizard(config, options) {
 				if (shown(step)) await advanceStep(step, activeTui.store, config);
 			}
 			else if (skipAgent) {
-				const { getOrAskForProjectData } = await import("./setup-utils-Cz0wPLsQ.js").then((n) => n.r);
+				const { getOrAskForProjectData } = await import("./setup-utils-D1tv0v_R.js").then((n) => n.r);
 				const { projectApiKey, host, accessToken, projectId } = await getOrAskForProjectData({
 					signup: session.signup,
 					ci: session.ci,
@@ -4577,6 +4644,10 @@ function runWizard(config, options) {
 			} catch {}
 			console.error("Wizard run failed:", err);
 			console.error(`Full logs: ${getLogFilePath()}`);
+			emitWizardError({
+				code: ErrorCodes.InternalUnhandled,
+				message: err instanceof Error ? err.message : String(err)
+			});
 			process.exit(1);
 		}
 	})();
@@ -4599,11 +4670,19 @@ function validateNonInteractiveOptions(options, mode) {
 	if (!options.apiKey) {
 		getUI().intro("PostHog Wizard");
 		getUI().log.error(`${label} mode requires --api-key (${keyHint})`);
+		emitWizardError({
+			code: ErrorCodes.ArgsMissingApiKey,
+			message: `${label} mode requires --api-key (${keyHint})`
+		});
 		process.exit(1);
 	}
 	if (!options.installDir) {
 		getUI().intro("PostHog Wizard");
 		getUI().log.error(`${label} mode requires --install-dir (directory to install in)`);
+		emitWizardError({
+			code: ErrorCodes.ArgsMissingInstallDir,
+			message: `${label} mode requires --install-dir`
+		});
 		process.exit(1);
 	}
 }
@@ -4627,11 +4706,11 @@ function runNonInteractive(config, options, mode) {
 	analytics.setTag("build", mode);
 	(async () => {
 		const path = await import("path");
-		const { buildSession, RunPhase, OutroKind } = await import("./wizard-session-UxA_A0cA.js");
-		const { readEnvironment } = await import("./environment-BhFvfkQg.js").then((n) => n.t);
-		const { readApiKeyFromEnv } = await import("./env-api-key-CdI2XZIz.js").then((n) => n.t);
-		const { configureLogFileFromEnvironment, logToFile } = await import("./debug-CtQ13sCW.js");
-		const { wizardAbort, WizardError } = await import("./wizard-abort-BlDla_Jd.js");
+		const { buildSession, RunPhase, OutroKind } = await import("./wizard-session-DHbUcjI7.js");
+		const { readEnvironment } = await import("./environment-C7CKGIOE.js").then((n) => n.t);
+		const { readApiKeyFromEnv } = await import("./env-api-key-DS0ghlcO.js").then((n) => n.t);
+		const { configureLogFileFromEnvironment, logToFile } = await import("./debug-mO3yg4Z7.js");
+		const { wizardAbort, WizardError } = await import("./wizard-abort-BsNbguJt.js");
 		configureLogFileFromEnvironment();
 		const env = readEnvironment();
 		const apiKey = options.apiKey ?? readApiKeyFromEnv() ?? void 0;
@@ -4669,15 +4748,18 @@ function runNonInteractive(config, options, mode) {
 			localPosthog: session.baseUrl === POSTHOG_LOCAL_URL
 		});
 		if (localServicesError) {
-			await wizardAbort({ message: localServicesError });
+			await wizardAbort({
+				code: ErrorCodes.EnvLocalServicesDown,
+				message: localServicesError
+			});
 			return;
 		}
 		let store = null;
 		let taskStream = null;
 		if (mode === "headless") {
-			const { WizardStore } = await import("./store-xMkU8xAa.js").then((n) => n.n);
-			const { HeadlessUI } = await import("./headless-ui-B4FnKm11.js");
-			const { TaskStreamPush, PostHogDestination } = await import("./task-stream-BK7JQ27G.js");
+			const { WizardStore } = await import("./store-DzEgsAPN.js").then((n) => n.n);
+			const { HeadlessUI } = await import("./headless-ui-6QuByWZ_.js");
+			const { TaskStreamPush, PostHogDestination } = await import("./task-stream-DSzvwJrD.js");
 			store = new WizardStore(config.id);
 			store.session = session;
 			setUI(new HeadlessUI(store));
@@ -4713,27 +4795,54 @@ function runNonInteractive(config, options, mode) {
 					setSkillId: (skillId) => {
 						session.skillId = skillId;
 					},
-					setUnsupportedVersion: () => void 0,
+					setUnsupportedVersion: (info) => {
+						session.unsupportedVersion = info;
+					},
 					addDiscoveredFeature: () => void 0,
 					setDetectionComplete: () => void 0
 				};
 				for (const step of config.steps) if (step.onReady) await step.onReady(readyCtx);
 				const detectError = session.frameworkContext.detectError;
+				if (session.unsupportedVersion) {
+					const { current, minimum, docsUrl } = session.unsupportedVersion;
+					const message = `Detected framework version ${current} is not supported. Minimum supported version is ${minimum}.`;
+					await settleStream(RunPhase.Error, {
+						kind: OutroKind.Error,
+						message,
+						errorCode: ErrorCodes.DetectUnsupportedVersion
+					});
+					await wizardAbort({
+						code: ErrorCodes.DetectUnsupportedVersion,
+						message: `${message}\n\nSee ${docsUrl}`,
+						error: new WizardError(`${config.id} unsupported framework version`, {
+							integration: config.id,
+							current,
+							minimum
+						}, ErrorCodes.DetectUnsupportedVersion)
+					});
+				}
 				if (detectError) {
+					const code = detectErrorCode(detectError.kind);
+					const detectKind = detectError.kind;
+					const detail = { ...detectError };
 					await settleStream(RunPhase.Error, {
 						kind: OutroKind.Error,
-						message: `Prerequisites not met: ${detectError.kind}`
+						message: `Prerequisites not met: ${detectKind}`,
+						errorCode: code,
+						errorDetail: detail
 					});
 					await wizardAbort({
-						message: `Prerequisites not met: ${detectError.kind}\n\nSee ${runDef?.docsUrl ?? "https://posthog.com/docs"}`,
+						code,
+						detail,
+						message: `Prerequisites not met: ${detectKind}\n\nSee ${runDef?.docsUrl ?? "https://posthog.com/docs"}`,
 						error: new WizardError(`${config.id} prerequisites failed`, {
 							integration: config.id,
-							detect_error_kind: detectError.kind
-						})
+							detect_error_kind: detectKind
+						}, code)
 					});
 				}
 			}
-			const { runAgent } = await import("./agent-runner-Ca-e2TOQ.js").then((n) => n.t);
+			const { runAgent } = await import("./agent-runner-DD65OMkB.js").then((n) => n.t);
 			await runAgent(config, session);
 			await settleStream(RunPhase.Completed);
 		} catch (error) {
@@ -4745,14 +4854,20 @@ function runNonInteractive(config, options, mode) {
 			const docsUrl = session.frameworkConfig?.metadata.docsUrl ?? runDef?.docsUrl ?? "https://posthog.com/docs";
 			await settleStream(RunPhase.Error, {
 				kind: OutroKind.Error,
-				message: errorMessage
+				message: errorMessage,
+				errorCode: ErrorCodes.InternalUnhandled
 			});
 			await wizardAbort({
+				code: ErrorCodes.InternalUnhandled,
 				message: `Something went wrong: ${errorMessage}\n\nYou can read the documentation at ${docsUrl} to set up manually.${debugInfo}`,
 				error
 			});
 		}
-	})().catch(() => {
+	})().catch((error) => {
+		emitWizardError({
+			code: ErrorCodes.InternalUnhandled,
+			message: error instanceof Error ? error.message : String(error)
+		});
 		process.exit(1);
 	});
 }
@@ -4818,12 +4933,16 @@ function runCommandHandler(work) {
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			process.stderr.write(`\n\x1b[1;91m✖ ${msg}\x1b[0m\n\n`);
+			emitWizardError({
+				code: ErrorCodes.InternalUnhandled,
+				message: msg
+			});
 			process.exit(1);
 		}
 	})();
 }
 function dispatchProgram(config, argv) {
-	const argvRecord = argv;
+	const argvRecord = { ...argv };
 	const extras = config.mapCliOptions?.(argvRecord) ?? {};
 	const options = {
 		...argvRecord,
@@ -4929,6 +5048,10 @@ async function exitDispatchError(reason, properties, message, code = 1) {
 		await analytics.flush();
 	} catch {}
 	process.stderr.write(message);
+	emitWizardError({
+		code: ErrorCodes.CliBadArgs,
+		message: reason
+	});
 	return process.exit(code);
 }
 /**
@@ -5957,12 +6080,16 @@ async function runDoctorCI(options) {
 	if (!apiKey) {
 		getUI().intro("PostHog Wizard");
 		getUI().log.error("CI mode requires --api-key (personal API key phx_xxx)");
+		emitWizardError({
+			code: ErrorCodes.ArgsMissingApiKey,
+			message: "CI mode requires --api-key (personal API key phx_xxx)"
+		});
 		process.exit(1);
 	}
 	getUI().intro("Welcome to the PostHog setup wizard");
 	getUI().log.info("Running posthog-doctor in CI mode");
 	try {
-		const { getOrAskForProjectData } = await import("./setup-utils-Cz0wPLsQ.js").then((n) => n.r);
+		const { getOrAskForProjectData } = await import("./setup-utils-D1tv0v_R.js").then((n) => n.r);
 		const { host, accessToken, projectId } = await getOrAskForProjectData({
 			signup: false,
 			ci: true,
@@ -5980,9 +6107,13 @@ async function runDoctorCI(options) {
 		for (const issue of sorted) getUI().log.info(`  • [${issue.severity}] ${getKindMeta(issue.kind).title}`);
 		process.exit(1);
 	} catch (error) {
-		const { ApiError } = await import("./api-Wgb7AhrP.js").then((n) => n.n);
+		const { ApiError } = await import("./api-BJft9v6K.js").then((n) => n.n);
 		const message = error instanceof ApiError && error.statusCode === 401 ? "Your PostHog API key is invalid or expired." : error instanceof Error ? error.message : String(error);
 		getUI().log.error(`Doctor failed: ${message}`);
+		emitWizardError({
+			code: error instanceof ApiError && error.statusCode === 401 ? ErrorCodes.AuthInvalidOrExpired : ErrorCodes.InternalUnhandled,
+			message
+		});
 		process.exit(1);
 	}
 }
@@ -6062,8 +6193,8 @@ function runSlackConnect(argv) {
 	(async () => {
 		const debug = argv.debug;
 		try {
-			const { startTUI } = await import("./start-tui-DDW9uVnD.js");
-			const { buildSession } = await import("./wizard-session-UxA_A0cA.js");
+			const { startTUI } = await import("./start-tui-B5YfmqNr.js");
+			const { buildSession } = await import("./wizard-session-DHbUcjI7.js");
 			const tui = startTUI(VERSION, Program.SlackConnect);
 			tui.store.session = buildSession({
 				debug,
@@ -6072,6 +6203,10 @@ function runSlackConnect(argv) {
 		} catch (err) {
 			setUI(new LoggingUI());
 			getUI().log.error(`Connecting Slack requires an interactive terminal. ${err instanceof Error ? err.message : String(err)}`);
+			emitWizardError({
+				code: ErrorCodes.CliInteractiveRequired,
+				message: "Connecting Slack requires an interactive terminal."
+			});
 			process.exit(1);
 		}
 	})();
@@ -6189,6 +6324,10 @@ const skillCommand = {
 						await analytics.flush();
 					} catch {}
 					process.stderr.write("\n\x1B[1;91m✖ Couldn't reach the skill registry.\x1B[0m\n  Check your network connection and try again.\n\n");
+					emitWizardError({
+						code: ErrorCodes.SkillMenuFetchFailed,
+						message: "Couldn't reach the skill registry."
+					});
 					process.exit(1);
 				}
 				const entries = (menu.cliEntries ?? []).filter((e) => BROWSABLE_ROLES.has(e.role));
@@ -6305,7 +6444,7 @@ async function runCliAdd(argv) {
 /** Resolve which instruction files to write, from flags, detection, or a prompt. */
 async function resolveTargetFiles(argv) {
 	const ui = getUI();
-	if (typeof argv.path === "string" && argv.path.trim()) return [path$1.resolve(argv.path.trim())];
+	if (typeof argv.path === "string" && argv.path.trim()) return [path$2.resolve(argv.path.trim())];
 	if (typeof argv.agent === "string") {
 		const target = findTarget(argv.agent);
 		if (!target) {
@@ -6382,6 +6521,10 @@ if (!satisfies(process.version, NODE_VERSION_RANGE)) {
 		``,
 		`Then run the wizard again. Stuck? Email wizard@posthog.com and we'll help.`
 	].join("\n"));
+	emitWizardError({
+		code: ErrorCodes.CliNodeVersion,
+		message: `Node ${process.version} is below the required range ${NODE_VERSION_RANGE}`
+	});
 	process.exit(1);
 }
 recoverOrphanedSettingsBackups(resolveInstallDir());