maxsimcli 3.11.0 → 4.0.0

package/dist/cli.cjs

@@ -31,10 +31,9 @@ let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
 let node_path = require("node:path");
 node_path = __toESM(node_path);
+let node_child_process = require("node:child_process");
 let node_os = require("node:os");
 node_os = __toESM(node_os);
-let node_child_process = require("node:child_process");
-let node_module = require("node:module");
 let node_buffer = require("node:buffer");
 let child_process = require("child_process");
 let node_events = require("node:events");
@@ -42,8 +41,22 @@ let node_process = require("node:process");
 node_process = __toESM(node_process);
 let node_tty = require("node:tty");
 node_tty = __toESM(node_tty);
+let node_module = require("node:module");
 
 //#region src/core/types.ts
+function cmdOk(result, rawValue) {
+	return {
+		ok: true,
+		result,
+		rawValue
+	};
+}
+function cmdErr(error) {
+	return {
+		ok: false,
+		error
+	};
+}
 const PLANNING_CONFIG_DEFAULTS = {
 	model_profile: "balanced",
 	commit_docs: true,
@@ -53,9 +66,8 @@ const PLANNING_CONFIG_DEFAULTS = {
 	milestone_branch_template: "maxsim/{milestone}-{slug}",
 	workflow: {
 		research: true,
-		plan_check: true,
-		verifier: true,
-		nyquist_validation: false
+		plan_checker: true,
+		verifier: true
 	},
 	parallelization: true,
 	brave_search: false
@@ -594,7 +606,7 @@ var require_has_flag = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 //#endregion
 //#region ../../node_modules/supports-color/index.js
 var require_supports_color = /* @__PURE__ */ __commonJSMin(((exports, module) => {
-	const os$4 = require("os");
+	const os$5 = require("os");
 	const tty$2 = require("tty");
 	const hasFlag = require_has_flag();
 	const { env } = process;
@@ -621,7 +633,7 @@ var require_supports_color = /* @__PURE__ */ __commonJSMin(((exports, module) =>
 		const min = forceColor || 0;
 		if (env.TERM === "dumb") return min;
 		if (process.platform === "win32") {
-			const osRelease = os$4.release().split(".");
+			const osRelease = os$5.release().split(".");
 			if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) return Number(osRelease[2]) >= 14931 ? 3 : 2;
 			return 1;
 		}
@@ -4711,21 +4723,47 @@ const MODEL_PROFILES = {
 		tokenburner: "opus"
 	}
 };
+/** Thrown by output() to signal successful command completion. */
+var CliOutput = class {
+	result;
+	raw;
+	rawValue;
+	constructor(result, raw, rawValue) {
+		this.result = result;
+		this.raw = raw ?? false;
+		this.rawValue = rawValue;
+	}
+};
+/** Thrown by error() to signal a command error. */
+var CliError = class {
+	message;
+	constructor(message) {
+		this.message = message;
+	}
+};
 function output(result, raw, rawValue) {
-	if (raw && rawValue !== void 0) process.stdout.write(String(rawValue));
+	throw new CliOutput(result, raw, rawValue);
+}
+function error(message) {
+	throw new CliError(message);
+}
+/** Re-throw CliOutput/CliError signals so catch blocks don't intercept them */
+function rethrowCliSignals(e) {
+	if (e instanceof CliOutput || e instanceof CliError) throw e;
+}
+/**
+* Handle a CliOutput by writing to stdout. Extracted so cli.ts can use it.
+*/
+function writeOutput(out) {
+	if (out.raw && out.rawValue !== void 0) process.stdout.write(String(out.rawValue));
 	else {
-		const json = JSON.stringify(result, null, 2);
+		const json = JSON.stringify(out.result, null, 2);
 		if (json.length > 5e4) {
 			const tmpPath = node_path.default.join(node_os.default.tmpdir(), `maxsim-${Date.now()}.json`);
 			node_fs.default.writeFileSync(tmpPath, json, "utf-8");
 			process.stdout.write("@file:" + tmpPath);
 		} else process.stdout.write(json);
 	}
-	process.exit(0);
-}
-function error(message) {
-	process.stderr.write("Error: " + message + "\n");
-	process.exit(1);
 }
 /** Today's date as YYYY-MM-DD. */
 function todayISO() {
@@ -4758,9 +4796,28 @@ function listSubDirs(dir, sortByPhase = false) {
 	const dirs = node_fs.default.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
 	return sortByPhase ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs;
 }
-/** Log only when MAXSIM_DEBUG is set. */
-function debugLog(e) {
-	if (process.env.MAXSIM_DEBUG) console.error(e);
+/** Async version of listSubDirs using fs.promises. */
+async function listSubDirsAsync(dir, sortByPhase = false) {
+	const dirs = (await node_fs.promises.readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+	return sortByPhase ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs;
+}
+/** Async version of safeReadFile using fs.promises. */
+async function safeReadFileAsync(filePath) {
+	try {
+		return await node_fs.promises.readFile(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+/** Extract a human-readable message from an unknown thrown value. */
+function errorMsg(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+/** Log only when MAXSIM_DEBUG is set. Accepts an optional context label. */
+function debugLog(contextOrError, error) {
+	if (!process.env.MAXSIM_DEBUG) return;
+	if (error !== void 0) console.error(`[maxsim:${contextOrError}]`, error);
+	else console.error(contextOrError);
 }
 /** Escape a phase number for use in regex. */
 function escapePhaseNum(phase) {
@@ -4833,6 +4890,9 @@ function loadConfig(cwd) {
 				field: "research"
 			}) ?? defaults.research,
 			plan_checker: get("plan_checker", {
+				section: "workflow",
+				field: "plan_checker"
+			}) ?? get("plan_checker", {
 				section: "workflow",
 				field: "plan_check"
 			}) ?? defaults.plan_checker,
@@ -4849,7 +4909,11 @@ function loadConfig(cwd) {
 			config: result
 		};
 		return result;
-	} catch {
+	} catch (e) {
+		if (node_fs.default.existsSync(cfgPath)) {
+			console.warn(`[maxsim] Warning: config.json exists but could not be parsed — using defaults.`);
+			debugLog("config-load-failed", e);
+		}
 		_configCache = {
 			cwd,
 			config: defaults
@@ -4872,10 +4936,15 @@ async function execGit(cwd, args) {
 			stderr: ""
 		};
 	} catch (thrown) {
+		const message = thrown instanceof Error ? thrown.message : String(thrown);
+		debugLog("exec-git-failed", {
+			args,
+			error: message
+		});
 		return {
 			exitCode: 1,
 			stdout: "",
-			stderr: thrown.message ?? ""
+			stderr: message
 		};
 	}
 }
@@ -4950,7 +5019,12 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
 			has_context: hasContext,
 			has_verification: hasVerification
 		};
-	} catch {
+	} catch (e) {
+		debugLog("search-phase-in-dir-failed", {
+			dir: baseDir,
+			phase: normalized,
+			error: errorMsg(e)
+		});
 		return null;
 	}
 }
@@ -4979,7 +5053,7 @@ function findPhaseInternal(cwd, phase) {
 			}
 		}
 	} catch (e) {
-		debugLog(e);
+		debugLog("find-phase-milestone-search-failed", e);
 	}
 	return null;
 }
@@ -5002,7 +5076,7 @@ function getArchivedPhaseDirs(cwd) {
 			});
 		}
 	} catch (e) {
-		debugLog(e);
+		debugLog("get-archived-phase-dirs-failed", e);
 	}
 	return results;
 }
@@ -5028,7 +5102,11 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
 			goal,
 			section
 		};
-	} catch {
+	} catch (e) {
+		debugLog("get-roadmap-phase-failed", {
+			phase: phaseNum,
+			error: errorMsg(e)
+		});
 		return null;
 	}
 }
@@ -11804,39 +11882,30 @@ const FRONTMATTER_SCHEMAS = {
 		"score"
 	] }
 };
-function cmdFrontmatterGet(cwd, filePath, field, raw) {
-	if (!filePath) error("file path required");
+function cmdFrontmatterGet(cwd, filePath, field) {
+	if (!filePath) return cmdErr("file path required");
 	const content = safeReadFile(node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(cwd, filePath));
-	if (!content) {
-		output({
-			error: "File not found",
-			path: filePath
-		}, raw);
-		return;
-	}
+	if (!content) return cmdOk({
+		error: "File not found",
+		path: filePath
+	});
 	const fm = extractFrontmatter(content);
 	if (field) {
 		const value = fm[field];
-		if (value === void 0) {
-			output({
-				error: "Field not found",
-				field
-			}, raw);
-			return;
-		}
-		output({ [field]: value }, raw, JSON.stringify(value));
-	} else output(fm, raw);
+		if (value === void 0) return cmdOk({
+			error: "Field not found",
+			field
+		});
+		return cmdOk({ [field]: value }, JSON.stringify(value));
+	} else return cmdOk(fm);
 }
-function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
-	if (!filePath || !field || value === void 0) error("file, field, and value required");
+function cmdFrontmatterSet(cwd, filePath, field, value) {
+	if (!filePath || !field || value === void 0) return cmdErr("file, field, and value required");
 	const fullPath = node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(cwd, filePath);
-	if (!node_fs.default.existsSync(fullPath)) {
-		output({
-			error: "File not found",
-			path: filePath
-		}, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(fullPath)) return cmdOk({
+		error: "File not found",
+		path: filePath
+	});
 	const content = node_fs.default.readFileSync(fullPath, "utf-8");
 	const fm = extractFrontmatter(content);
 	let parsedValue;
@@ -11848,60 +11917,53 @@ function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
 	fm[field] = parsedValue;
 	const newContent = spliceFrontmatter(content, fm);
 	node_fs.default.writeFileSync(fullPath, newContent, "utf-8");
-	output({
+	return cmdOk({
 		updated: true,
 		field,
 		value: parsedValue
-	}, raw, "true");
+	}, "true");
 }
-function cmdFrontmatterMerge(cwd, filePath, data, raw) {
-	if (!filePath || !data) error("file and data required");
+function cmdFrontmatterMerge(cwd, filePath, data) {
+	if (!filePath || !data) return cmdErr("file and data required");
 	const fullPath = node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(cwd, filePath);
-	if (!node_fs.default.existsSync(fullPath)) {
-		output({
-			error: "File not found",
-			path: filePath
-		}, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(fullPath)) return cmdOk({
+		error: "File not found",
+		path: filePath
+	});
 	const content = node_fs.default.readFileSync(fullPath, "utf-8");
 	const fm = extractFrontmatter(content);
 	let mergeData;
 	try {
 		mergeData = JSON.parse(data);
 	} catch {
-		error("Invalid JSON for --data");
-		return;
+		return cmdErr("Invalid JSON for --data");
 	}
 	Object.assign(fm, mergeData);
 	const newContent = spliceFrontmatter(content, fm);
 	node_fs.default.writeFileSync(fullPath, newContent, "utf-8");
-	output({
+	return cmdOk({
 		merged: true,
 		fields: Object.keys(mergeData)
-	}, raw, "true");
+	}, "true");
 }
-function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
-	if (!filePath || !schemaName) error("file and schema required");
+function cmdFrontmatterValidate(cwd, filePath, schemaName) {
+	if (!filePath || !schemaName) return cmdErr("file and schema required");
 	const schema = FRONTMATTER_SCHEMAS[schemaName];
-	if (!schema) error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(", ")}`);
+	if (!schema) return cmdErr(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(", ")}`);
 	const content = safeReadFile(node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(cwd, filePath));
-	if (!content) {
-		output({
-			error: "File not found",
-			path: filePath
-		}, raw);
-		return;
-	}
+	if (!content) return cmdOk({
+		error: "File not found",
+		path: filePath
+	});
 	const fm = extractFrontmatter(content);
 	const missing = schema.required.filter((f) => fm[f] === void 0);
 	const present = schema.required.filter((f) => fm[f] !== void 0);
-	output({
+	return cmdOk({
 		valid: missing.length === 0,
 		missing,
 		present,
 		schema: schemaName
-	}, raw, missing.length === 0 ? "valid" : "invalid");
+	}, missing.length === 0 ? "valid" : "invalid");
 }
 
 //#endregion
@@ -11917,15 +11979,12 @@ function cmdConfigEnsureSection(cwd, raw) {
 	try {
 		if (!node_fs.default.existsSync(planningDir)) node_fs.default.mkdirSync(planningDir, { recursive: true });
 	} catch (err) {
-		error("Failed to create .planning directory: " + err.message);
-	}
-	if (node_fs.default.existsSync(configPath)) {
-		output({
-			created: false,
-			reason: "already_exists"
-		}, raw, "exists");
-		return;
+		return cmdErr("Failed to create .planning directory: " + err.message);
 	}
+	if (node_fs.default.existsSync(configPath)) return cmdOk({
+		created: false,
+		reason: "already_exists"
+	}, raw ? "exists" : void 0);
 	const homedir = node_os.default.homedir();
 	const braveKeyFile = node_path.default.join(homedir, ".maxsim", "brave_api_key");
 	const hasBraveSearch = !!(process.env.BRAVE_API_KEY || node_fs.default.existsSync(braveKeyFile));
@@ -11948,17 +12007,17 @@ function cmdConfigEnsureSection(cwd, raw) {
 	};
 	try {
 		node_fs.default.writeFileSync(configPath, JSON.stringify(defaults, null, 2), "utf-8");
-		output({
+		return cmdOk({
 			created: true,
 			path: ".planning/config.json"
-		}, raw, "created");
+		}, raw ? "created" : void 0);
 	} catch (err) {
-		error("Failed to create config.json: " + err.message);
+		return cmdErr("Failed to create config.json: " + err.message);
 	}
 }
 function cmdConfigSet(cwd, keyPath, value, raw) {
 	const configPath = node_path.default.join(cwd, ".planning", "config.json");
-	if (!keyPath) error("Usage: config-set <key.path> <value>");
+	if (!keyPath) return cmdErr("Usage: config-set <key.path> <value>");
 	let parsedValue = value;
 	if (value === "true") parsedValue = true;
 	else if (value === "false") parsedValue = false;
@@ -11967,7 +12026,7 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
 	try {
 		if (node_fs.default.existsSync(configPath)) config = JSON.parse(node_fs.default.readFileSync(configPath, "utf-8"));
 	} catch (err) {
-		error("Failed to read config.json: " + err.message);
+		return cmdErr("Failed to read config.json: " + err.message);
 	}
 	const keys = keyPath.split(".");
 	let current = config;
@@ -11979,34 +12038,33 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
 	current[keys[keys.length - 1]] = parsedValue;
 	try {
 		node_fs.default.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
-		output({
+		return cmdOk({
 			updated: true,
 			key: keyPath,
 			value: parsedValue
-		}, raw, `${keyPath}=${parsedValue}`);
+		}, raw ? `${keyPath}=${parsedValue}` : void 0);
 	} catch (err) {
-		error("Failed to write config.json: " + err.message);
+		return cmdErr("Failed to write config.json: " + err.message);
 	}
 }
 function cmdConfigGet(cwd, keyPath, raw) {
 	const configPath = node_path.default.join(cwd, ".planning", "config.json");
-	if (!keyPath) error("Usage: config-get <key.path>");
+	if (!keyPath) return cmdErr("Usage: config-get <key.path>");
 	let config = {};
 	try {
 		if (node_fs.default.existsSync(configPath)) config = JSON.parse(node_fs.default.readFileSync(configPath, "utf-8"));
-		else error("No config.json found at " + configPath);
+		else return cmdErr("No config.json found at " + configPath);
 	} catch (err) {
-		if (err.message.startsWith("No config.json")) throw err;
-		error("Failed to read config.json: " + err.message);
+		return cmdErr("Failed to read config.json: " + err.message);
 	}
 	const keys = keyPath.split(".");
 	let current = config;
 	for (const key of keys) {
-		if (current === void 0 || current === null || typeof current !== "object") error(`Key not found: ${keyPath}`);
+		if (current === void 0 || current === null || typeof current !== "object") return cmdErr(`Key not found: ${keyPath}`);
 		current = current[key];
 	}
-	if (current === void 0) error(`Key not found: ${keyPath}`);
-	output(current, raw, String(current));
+	if (current === void 0) return cmdErr(`Key not found: ${keyPath}`);
+	return cmdOk(current, raw ? String(current) : void 0);
 }
 
 //#endregion
@@ -12023,16 +12081,31 @@ function escapeStringRegexp(string) {
 *
 * Ported from maxsim/bin/lib/state.cjs
 */
+/**
+* Parse a markdown table row into cells, handling escaped pipes (`\|`) within cell content.
+* Strips leading/trailing pipe characters and trims each cell.
+*/
+function parseTableRow(row) {
+	const placeholder = "\0PIPE\0";
+	return row.replace(/\\\|/g, placeholder).split("|").map((c) => c.replaceAll(placeholder, "|").trim()).filter(Boolean);
+}
 function stateExtractField(content, fieldName) {
-	const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, "i");
-	const match = content.match(pattern);
-	return match ? match[1].trim() : null;
+	const escaped = escapeStringRegexp(fieldName);
+	const boldPattern = new RegExp(`\\*\\*\\s*${escaped}\\s*:\\s*\\*\\*\\s*(.+)`, "i");
+	const boldMatch = content.match(boldPattern);
+	if (boldMatch) return boldMatch[1].trim();
+	const plainPattern = new RegExp(`^\\s*${escaped}\\s*:\\s*(.+)`, "im");
+	const plainMatch = content.match(plainPattern);
+	return plainMatch ? plainMatch[1].trim() : null;
 }
 function stateReplaceField(content, fieldName, newValue) {
 	const escaped = escapeStringRegexp(fieldName);
-	const pattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, "i");
-	if (pattern.test(content)) return content.replace(pattern, (_match, prefix) => `${prefix}${newValue}`);
-	return null;
+	const boldPattern = new RegExp(`(\\*\\*\\s*${escaped}\\s*:\\s*\\*\\*\\s*)(.*)`, "i");
+	let replaced = content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+	if (replaced !== content) return replaced;
+	const plainPattern = new RegExp(`(^[ \\t]*${escaped}\\s*:\\s*)(.*)`, "im");
+	replaced = content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
+	return replaced !== content ? replaced : null;
 }
 function readTextArgOrFile(cwd, value, filePath, label) {
 	if (!filePath) return value;
@@ -12059,16 +12132,14 @@ function appendToStateSection(content, sectionPattern, entry, placeholderPattern
 	sectionBody = sectionBody.trimEnd() + "\n" + entry + "\n";
 	return content.replace(sectionPattern, (_m, header) => `${header}${sectionBody}`);
 }
-function cmdStateLoad(cwd, raw) {
+async function cmdStateLoad(cwd, raw) {
 	const config = loadConfig(cwd);
-	let stateRaw = "";
-	try {
-		stateRaw = node_fs.default.readFileSync(statePath(cwd), "utf-8");
-	} catch (e) {
-		debugLog(e);
-	}
-	const configExists = node_fs.default.existsSync(configPath(cwd));
-	const roadmapExists = node_fs.default.existsSync(roadmapPath(cwd));
+	const [stateContent, configExists, roadmapExists] = await Promise.all([
+		safeReadFileAsync(statePath(cwd)),
+		node_fs.default.promises.access(configPath(cwd)).then(() => true, () => false),
+		node_fs.default.promises.access(roadmapPath(cwd)).then(() => true, () => false)
+	]);
+	const stateRaw = stateContent ?? "";
 	const stateExists = stateRaw.length > 0;
 	const result = {
 		config,
@@ -12079,7 +12150,7 @@ function cmdStateLoad(cwd, raw) {
 	};
 	if (raw) {
 		const c = config;
-		const lines = [
+		return cmdOk(result, [
 			`model_profile=${c.model_profile}`,
 			`commit_docs=${c.commit_docs}`,
 			`branching_strategy=${c.branching_strategy}`,
@@ -12092,36 +12163,25 @@ function cmdStateLoad(cwd, raw) {
 			`config_exists=${configExists}`,
 			`roadmap_exists=${roadmapExists}`,
 			`state_exists=${stateExists}`
-		];
-		process.stdout.write(lines.join("\n"));
-		process.exit(0);
+		].join("\n"));
 	}
-	output(result);
+	return cmdOk(result);
 }
 function cmdStateGet(cwd, section, raw) {
 	const statePath$2 = statePath(cwd);
 	try {
 		const content = node_fs.default.readFileSync(statePath$2, "utf-8");
-		if (!section) {
-			output({ content }, raw, content);
-			return;
-		}
+		if (!section) return cmdOk({ content }, raw ? content : void 0);
+		const fieldValue = stateExtractField(content, section);
+		if (fieldValue !== null) return cmdOk({ [section]: fieldValue }, raw ? fieldValue : void 0);
 		const fieldEscaped = escapeStringRegexp(section);
-		const fieldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, "i");
-		const fieldMatch = content.match(fieldPattern);
-		if (fieldMatch) {
-			output({ [section]: fieldMatch[1].trim() }, raw, fieldMatch[1].trim());
-			return;
-		}
-		const sectionPattern = new RegExp(`##\\s*${fieldEscaped}\\s*\n([\\s\\S]*?)(?=\\n##|$)`, "i");
+		const sectionPattern = new RegExp(`#{2,3}\\s*${fieldEscaped}\\s*\\n\\s*\\n?([\\s\\S]*?)(?=\\n#{2,3}\\s|$)`, "i");
 		const sectionMatch = content.match(sectionPattern);
-		if (sectionMatch) {
-			output({ [section]: sectionMatch[1].trim() }, raw, sectionMatch[1].trim());
-			return;
-		}
-		output({ error: `Section or field "${section}" not found` }, raw, "");
-	} catch {
-		error("STATE.md not found");
+		if (sectionMatch) return cmdOk({ [section]: sectionMatch[1].trim() }, raw ? sectionMatch[1].trim() : void 0);
+		return cmdOk({ error: `Section or field "${section}" not found` }, raw ? "" : void 0);
+	} catch (e) {
+		rethrowCliSignals(e);
+		return cmdErr("STATE.md not found");
 	}
 }
 function cmdStatePatch(cwd, patches, raw) {
@@ -12133,36 +12193,34 @@ function cmdStatePatch(cwd, patches, raw) {
 			failed: []
 		};
 		for (const [field, value] of Object.entries(patches)) {
-			const fieldEscaped = escapeStringRegexp(field);
-			const pattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, "i");
-			if (pattern.test(content)) {
-				content = content.replace(pattern, (_match, prefix) => `${prefix}${value}`);
+			const result = stateReplaceField(content, field, value);
+			if (result) {
+				content = result;
 				results.updated.push(field);
 			} else results.failed.push(field);
 		}
 		if (results.updated.length > 0) node_fs.default.writeFileSync(statePath$3, content, "utf-8");
-		output(results, raw, results.updated.length > 0 ? "true" : "false");
-	} catch {
-		error("STATE.md not found");
+		return cmdOk(results, raw ? results.updated.length > 0 ? "true" : "false" : void 0);
+	} catch (e) {
+		rethrowCliSignals(e);
+		return cmdErr("STATE.md not found");
 	}
 }
 function cmdStateUpdate(cwd, field, value) {
-	if (!field || value === void 0) error("field and value required for state update");
+	if (!field || value === void 0) return cmdErr("field and value required for state update");
 	const statePath$4 = statePath(cwd);
 	try {
-		let content = node_fs.default.readFileSync(statePath$4, "utf-8");
-		const fieldEscaped = escapeStringRegexp(field);
-		const pattern = new RegExp(`(\\*\\*${fieldEscaped}:\\*\\*\\s*)(.*)`, "i");
-		if (pattern.test(content)) {
-			content = content.replace(pattern, (_match, prefix) => `${prefix}${value}`);
-			node_fs.default.writeFileSync(statePath$4, content, "utf-8");
-			output({ updated: true });
-		} else output({
+		const result = stateReplaceField(node_fs.default.readFileSync(statePath$4, "utf-8"), field, value);
+		if (result) {
+			node_fs.default.writeFileSync(statePath$4, result, "utf-8");
+			return cmdOk({ updated: true });
+		} else return cmdOk({
 			updated: false,
 			reason: `Field "${field}" not found in STATE.md`
 		});
-	} catch {
-		output({
+	} catch (e) {
+		rethrowCliSignals(e);
+		return cmdOk({
 			updated: false,
 			reason: "STATE.md not found"
 		});
@@ -12170,56 +12228,44 @@ function cmdStateUpdate(cwd, field, value) {
 }
 function cmdStateAdvancePlan(cwd, raw) {
 	const statePath$5 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$5)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$5)) return cmdOk({ error: "STATE.md not found" });
 	let content = node_fs.default.readFileSync(statePath$5, "utf-8");
 	const currentPlan = parseInt(stateExtractField(content, "Current Plan") ?? "", 10);
 	const totalPlans = parseInt(stateExtractField(content, "Total Plans in Phase") ?? "", 10);
 	const today = todayISO();
-	if (isNaN(currentPlan) || isNaN(totalPlans)) {
-		output({ error: "Cannot parse Current Plan or Total Plans in Phase from STATE.md" }, raw);
-		return;
-	}
+	if (isNaN(currentPlan) || isNaN(totalPlans)) return cmdOk({ error: "Cannot parse Current Plan or Total Plans in Phase from STATE.md" });
 	if (currentPlan >= totalPlans) {
 		content = stateReplaceField(content, "Status", "Phase complete — ready for verification") || content;
 		content = stateReplaceField(content, "Last Activity", today) || content;
 		node_fs.default.writeFileSync(statePath$5, content, "utf-8");
-		output({
+		return cmdOk({
 			advanced: false,
 			reason: "last_plan",
 			current_plan: currentPlan,
 			total_plans: totalPlans,
 			status: "ready_for_verification"
-		}, raw, "false");
+		}, raw ? "false" : void 0);
 	} else {
 		const newPlan = currentPlan + 1;
 		content = stateReplaceField(content, "Current Plan", String(newPlan)) || content;
 		content = stateReplaceField(content, "Status", "Ready to execute") || content;
 		content = stateReplaceField(content, "Last Activity", today) || content;
 		node_fs.default.writeFileSync(statePath$5, content, "utf-8");
-		output({
+		return cmdOk({
 			advanced: true,
 			previous_plan: currentPlan,
 			current_plan: newPlan,
 			total_plans: totalPlans
-		}, raw, "true");
+		}, raw ? "true" : void 0);
 	}
 }
 function cmdStateRecordMetric(cwd, options, raw) {
 	const statePath$6 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$6)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$6)) return cmdOk({ error: "STATE.md not found" });
 	let content = node_fs.default.readFileSync(statePath$6, "utf-8");
 	const { phase, plan, duration, tasks, files } = options;
-	if (!phase || !plan || !duration) {
-		output({ error: "phase, plan, and duration required" }, raw);
-		return;
-	}
-	const metricsPattern = /(##\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n)([\s\S]*?)(?=\n##|\n$|$)/i;
+	if (!phase || !plan || !duration) return cmdOk({ error: "phase, plan, and duration required" });
+	const metricsPattern = /(#{2,3}\s*Performance Metrics[\s\S]*?\n\|[^\n]+\n\|[\s:|\-]+\n)([\s\S]*?)(?=\n#{2,3}\s|\n$|$)/i;
 	const metricsMatch = content.match(metricsPattern);
 	if (metricsMatch) {
 		let tableBody = metricsMatch[2].trimEnd();
@@ -12228,23 +12274,20 @@ function cmdStateRecordMetric(cwd, options, raw) {
 		else tableBody = tableBody + "\n" + newRow;
 		content = content.replace(metricsPattern, (_match, header) => `${header}${tableBody}\n`);
 		node_fs.default.writeFileSync(statePath$6, content, "utf-8");
-		output({
+		return cmdOk({
 			recorded: true,
 			phase,
 			plan,
 			duration
-		}, raw, "true");
-	} else output({
+		}, raw ? "true" : void 0);
+	} else return cmdOk({
 		recorded: false,
 		reason: "Performance Metrics section not found in STATE.md"
-	}, raw, "false");
+	}, raw ? "false" : void 0);
 }
 function cmdStateUpdateProgress(cwd, raw) {
 	const statePath$7 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$7)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$7)) return cmdOk({ error: "STATE.md not found" });
 	let content = node_fs.default.readFileSync(statePath$7, "utf-8");
 	const phasesDir = phasesPath(cwd);
 	let totalPlans = 0;
@@ -12261,28 +12304,24 @@ function cmdStateUpdateProgress(cwd, raw) {
 	const barWidth = 10;
 	const filled = Math.round(percent / 100 * barWidth);
 	const progressStr = `[${"█".repeat(filled) + "░".repeat(barWidth - filled)}] ${percent}%`;
-	const progressPattern = /(\*\*Progress:\*\*\s*).*/i;
-	if (progressPattern.test(content)) {
-		content = content.replace(progressPattern, (_match, prefix) => `${prefix}${progressStr}`);
-		node_fs.default.writeFileSync(statePath$7, content, "utf-8");
-		output({
+	const result = stateReplaceField(content, "Progress", progressStr);
+	if (result) {
+		node_fs.default.writeFileSync(statePath$7, result, "utf-8");
+		return cmdOk({
 			updated: true,
 			percent,
 			completed: totalSummaries,
 			total: totalPlans,
 			bar: progressStr
-		}, raw, progressStr);
-	} else output({
+		}, raw ? progressStr : void 0);
+	} else return cmdOk({
 		updated: false,
 		reason: "Progress field not found in STATE.md"
-	}, raw, "false");
+	}, raw ? "false" : void 0);
 }
 function cmdStateAddDecision(cwd, options, raw) {
 	const statePath$8 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$8)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$8)) return cmdOk({ error: "STATE.md not found" });
 	const { phase, summary, summary_file, rationale, rationale_file } = options;
 	let summaryText;
 	let rationaleText = "";
@@ -12290,99 +12329,79 @@ function cmdStateAddDecision(cwd, options, raw) {
 		summaryText = readTextArgOrFile(cwd, summary, summary_file, "summary");
 		rationaleText = readTextArgOrFile(cwd, rationale || "", rationale_file, "rationale") || "";
 	} catch (thrown) {
-		output({
+		return cmdOk({
 			added: false,
 			reason: thrown.message
-		}, raw, "false");
-		return;
-	}
-	if (!summaryText) {
-		output({ error: "summary required" }, raw);
-		return;
+		}, raw ? "false" : void 0);
 	}
+	if (!summaryText) return cmdOk({ error: "summary required" });
 	const content = node_fs.default.readFileSync(statePath$8, "utf-8");
 	const entry = `- [Phase ${phase || "?"}]: ${summaryText}${rationaleText ? ` — ${rationaleText}` : ""}`;
 	const updated = appendToStateSection(content, /(###?\s*(?:Decisions|Decisions Made|Accumulated.*Decisions)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i, entry, [/None yet\.?\s*\n?/gi, /No decisions yet\.?\s*\n?/gi]);
 	if (updated) {
 		node_fs.default.writeFileSync(statePath$8, updated, "utf-8");
-		output({
+		return cmdOk({
 			added: true,
 			decision: entry
-		}, raw, "true");
-	} else output({
+		}, raw ? "true" : void 0);
+	} else return cmdOk({
 		added: false,
 		reason: "Decisions section not found in STATE.md"
-	}, raw, "false");
+	}, raw ? "false" : void 0);
 }
 function cmdStateAddBlocker(cwd, text, raw) {
 	const statePath$9 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$9)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$9)) return cmdOk({ error: "STATE.md not found" });
 	const blockerOptions = typeof text === "object" && text !== null ? text : { text };
 	let blockerText;
 	try {
 		blockerText = readTextArgOrFile(cwd, blockerOptions.text, blockerOptions.text_file, "blocker");
 	} catch (thrown) {
-		output({
+		return cmdOk({
 			added: false,
 			reason: thrown.message
-		}, raw, "false");
-		return;
-	}
-	if (!blockerText) {
-		output({ error: "text required" }, raw);
-		return;
+		}, raw ? "false" : void 0);
 	}
+	if (!blockerText) return cmdOk({ error: "text required" });
 	const updated = appendToStateSection(node_fs.default.readFileSync(statePath$9, "utf-8"), /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i, `- ${blockerText}`, [/None\.?\s*\n?/gi, /None yet\.?\s*\n?/gi]);
 	if (updated) {
 		node_fs.default.writeFileSync(statePath$9, updated, "utf-8");
-		output({
+		return cmdOk({
 			added: true,
 			blocker: blockerText
-		}, raw, "true");
-	} else output({
+		}, raw ? "true" : void 0);
+	} else return cmdOk({
 		added: false,
 		reason: "Blockers section not found in STATE.md"
-	}, raw, "false");
+	}, raw ? "false" : void 0);
 }
 function cmdStateResolveBlocker(cwd, text, raw) {
 	const statePath$10 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$10)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
-	if (!text) {
-		output({ error: "text required" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$10)) return cmdOk({ error: "STATE.md not found" });
+	if (!text) return cmdOk({ error: "text required" });
 	let content = node_fs.default.readFileSync(statePath$10, "utf-8");
-	const sectionPattern = /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i;
+	const sectionPattern = /(#{2,3}\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n\s*\n?)([\s\S]*?)(?=\n#{2,3}\s|$)/i;
 	const match = content.match(sectionPattern);
 	if (match) {
 		let newBody = match[2].split("\n").filter((line) => {
-			if (!line.startsWith("- ")) return true;
+			if (!/^\s*[-*]\s+/.test(line)) return true;
 			return !line.toLowerCase().includes(text.toLowerCase());
 		}).join("\n");
-		if (!newBody.trim() || !newBody.includes("- ")) newBody = "None\n";
+		if (!newBody.trim() || !/^\s*[-*]\s+/m.test(newBody)) newBody = "None\n";
 		content = content.replace(sectionPattern, (_match, header) => `${header}${newBody}`);
 		node_fs.default.writeFileSync(statePath$10, content, "utf-8");
-		output({
+		return cmdOk({
 			resolved: true,
 			blocker: text
-		}, raw, "true");
-	} else output({
+		}, raw ? "true" : void 0);
+	} else return cmdOk({
 		resolved: false,
 		reason: "Blockers section not found in STATE.md"
-	}, raw, "false");
+	}, raw ? "false" : void 0);
 }
 function cmdStateRecordSession(cwd, options, raw) {
 	const statePath$11 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$11)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$11)) return cmdOk({ error: "STATE.md not found" });
 	let content = node_fs.default.readFileSync(statePath$11, "utf-8");
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const updated = [];
@@ -12413,27 +12432,20 @@ function cmdStateRecordSession(cwd, options, raw) {
 	}
 	if (updated.length > 0) {
 		node_fs.default.writeFileSync(statePath$11, content, "utf-8");
-		output({
+		return cmdOk({
 			recorded: true,
 			updated
-		}, raw, "true");
-	} else output({
+		}, raw ? "true" : void 0);
+	} else return cmdOk({
 		recorded: false,
 		reason: "No session fields found in STATE.md"
-	}, raw, "false");
+	}, raw ? "false" : void 0);
 }
 function cmdStateSnapshot(cwd, raw) {
 	const statePath$12 = statePath(cwd);
-	if (!node_fs.default.existsSync(statePath$12)) {
-		output({ error: "STATE.md not found" }, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(statePath$12)) return cmdOk({ error: "STATE.md not found" });
 	const content = node_fs.default.readFileSync(statePath$12, "utf-8");
-	const extractField = (fieldName) => {
-		const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, "i");
-		const match = content.match(pattern);
-		return match ? match[1].trim() : null;
-	};
+	const extractField = (fieldName) => stateExtractField(content, fieldName);
 	const currentPhase = extractField("Current Phase");
 	const currentPhaseName = extractField("Current Phase Name");
 	const totalPhasesRaw = extractField("Total Phases");
@@ -12448,11 +12460,12 @@ function cmdStateSnapshot(cwd, raw) {
 	const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
 	const progressPercent = progressRaw ? parseInt(progressRaw.replace("%", ""), 10) : null;
 	const decisions = [];
-	const decisionsMatch = content.match(/##\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[-|\s]+\n([\s\S]*?)(?=\n##|\n$|$)/i);
+	const decisionsMatch = content.match(/#{2,3}\s*Decisions Made[\s\S]*?\n\|[^\n]+\n\|[\s:|\-]+\n([\s\S]*?)(?=\n#{2,3}\s|\n$|$)/i);
 	if (decisionsMatch) {
-		const rows = decisionsMatch[1].trim().split("\n").filter((r) => r.includes("|"));
+		const rows = decisionsMatch[1].trim().split("\n").filter((r) => r.includes("|") && !r.match(/^\s*$/));
 		for (const row of rows) {
-			const cells = row.split("|").map((c) => c.trim()).filter(Boolean);
+			if (/^\s*\|[\s:\-|]+\|\s*$/.test(row)) continue;
+			const cells = parseTableRow(row);
 			if (cells.length >= 3) decisions.push({
 				phase: cells[0],
 				summary: cells[1],
@@ -12461,27 +12474,24 @@ function cmdStateSnapshot(cwd, raw) {
 		}
 	}
 	const blockers = [];
-	const blockersMatch = content.match(/##\s*Blockers\s*\n([\s\S]*?)(?=\n##|$)/i);
+	const blockersMatch = content.match(/#{2,3}\s*Blockers\s*\n([\s\S]*?)(?=\n#{2,3}\s|$)/i);
 	if (blockersMatch) {
-		const items = blockersMatch[1].match(/^-\s+(.+)$/gm) || [];
-		for (const item of items) blockers.push(item.replace(/^-\s+/, "").trim());
+		const items = blockersMatch[1].match(/^\s*[-*]\s+(.+)$/gm) || [];
+		for (const item of items) blockers.push(item.replace(/^\s*[-*]\s+/, "").trim());
 	}
 	const session = {
 		last_date: null,
 		stopped_at: null,
 		resume_file: null
 	};
-	const sessionMatch = content.match(/##\s*Session\s*\n([\s\S]*?)(?=\n##|$)/i);
+	const sessionMatch = content.match(/#{2,3}\s*Session\s*\n\s*\n?([\s\S]*?)(?=\n#{2,3}\s|$)/i);
 	if (sessionMatch) {
 		const sessionSection = sessionMatch[1];
-		const lastDateMatch = sessionSection.match(/\*\*Last Date:\*\*\s*(.+)/i);
-		const stoppedAtMatch = sessionSection.match(/\*\*Stopped At:\*\*\s*(.+)/i);
-		const resumeFileMatch = sessionSection.match(/\*\*Resume File:\*\*\s*(.+)/i);
-		if (lastDateMatch) session.last_date = lastDateMatch[1].trim();
-		if (stoppedAtMatch) session.stopped_at = stoppedAtMatch[1].trim();
-		if (resumeFileMatch) session.resume_file = resumeFileMatch[1].trim();
+		session.last_date = stateExtractField(sessionSection, "Last Date");
+		session.stopped_at = stateExtractField(sessionSection, "Stopped At") || stateExtractField(sessionSection, "Stopped at");
+		session.resume_file = stateExtractField(sessionSection, "Resume File") || stateExtractField(sessionSection, "Resume file");
 	}
-	output({
+	return cmdOk({
 		current_phase: currentPhase,
 		current_phase_name: currentPhaseName,
 		total_phases: totalPhases,
@@ -12495,7 +12505,7 @@ function cmdStateSnapshot(cwd, raw) {
 		blockers,
 		paused_at: pausedAt,
 		session
-	}, raw);
+	});
 }
 
 //#endregion
@@ -12505,15 +12515,12 @@ function cmdStateSnapshot(cwd, raw) {
 *
 * Ported from maxsim/bin/lib/roadmap.cjs
 */
-function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
+function cmdRoadmapGetPhase(cwd, phaseNum) {
 	const rmPath = roadmapPath(cwd);
-	if (!node_fs.default.existsSync(rmPath)) {
-		output({
-			found: false,
-			error: "ROADMAP.md not found"
-		}, raw, "");
-		return;
-	}
+	if (!node_fs.default.existsSync(rmPath)) return cmdOk({
+		found: false,
+		error: "ROADMAP.md not found"
+	}, "");
 	try {
 		const content = node_fs.default.readFileSync(rmPath, "utf-8");
 		const escapedPhase = phaseNum.replace(/\./g, "\\.");
@@ -12522,21 +12529,17 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
 		if (!headerMatch) {
 			const checklistPattern = new RegExp(`-\\s*\\[[ x]\\]\\s*\\*\\*Phase\\s+${escapedPhase}:\\s*([^*]+)\\*\\*`, "i");
 			const checklistMatch = content.match(checklistPattern);
-			if (checklistMatch) {
-				output({
-					found: false,
-					phase_number: phaseNum,
-					phase_name: checklistMatch[1].trim(),
-					error: "malformed_roadmap",
-					message: `Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.`
-				}, raw, "");
-				return;
-			}
-			output({
+			if (checklistMatch) return cmdOk({
+				found: false,
+				phase_number: phaseNum,
+				phase_name: checklistMatch[1].trim(),
+				error: "malformed_roadmap",
+				message: `Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.`
+			}, "");
+			return cmdOk({
 				found: false,
 				phase_number: phaseNum
-			}, raw, "");
-			return;
+			}, "");
 		}
 		const phaseName = headerMatch[1].trim();
 		const headerIndex = headerMatch.index;
@@ -12546,33 +12549,29 @@ function cmdRoadmapGetPhase(cwd, phaseNum, raw) {
 		const goalMatch = section.match(/\*\*Goal(?::\*\*|\*\*:)\s*([^\n]+)/i);
 		const goal = goalMatch ? goalMatch[1].trim() : null;
 		const criteriaMatch = section.match(/\*\*Success Criteria\*\*[^\n]*:\s*\n((?:\s*\d+\.\s*[^\n]+\n?)+)/i);
-		output({
+		return cmdOk({
 			found: true,
 			phase_number: phaseNum,
 			phase_name: phaseName,
 			goal,
 			success_criteria: criteriaMatch ? criteriaMatch[1].trim().split("\n").map((line) => line.replace(/^\s*\d+\.\s*/, "").trim()).filter(Boolean) : [],
 			section
-		}, raw, section);
+		}, section);
 	} catch (e) {
-		error("Failed to read ROADMAP.md: " + e.message);
+		return cmdErr("Failed to read ROADMAP.md: " + e.message);
 	}
 }
-function cmdRoadmapAnalyze(cwd, raw) {
-	const rmPath = roadmapPath(cwd);
-	if (!node_fs.default.existsSync(rmPath)) {
-		output({
-			error: "ROADMAP.md not found",
-			milestones: [],
-			phases: [],
-			current_phase: null
-		}, raw);
-		return;
-	}
-	const content = node_fs.default.readFileSync(rmPath, "utf-8");
+async function cmdRoadmapAnalyze(cwd) {
+	const content = await safeReadFileAsync(roadmapPath(cwd));
+	if (!content) return cmdOk({
+		error: "ROADMAP.md not found",
+		milestones: [],
+		phases: [],
+		current_phase: null
+	});
 	const phasesDir = phasesPath(cwd);
 	const phasePattern = getPhasePattern();
-	const phases = [];
+	const parsedPhases = [];
 	let match;
 	while ((match = phasePattern.exec(content)) !== null) {
 		const phaseNum = match[1];
@@ -12585,16 +12584,29 @@ function cmdRoadmapAnalyze(cwd, raw) {
 		const goal = goalMatch ? goalMatch[1].trim() : null;
 		const dependsMatch = section.match(/\*\*Depends on:\*\*\s*([^\n]+)/i);
 		const depends_on = dependsMatch ? dependsMatch[1].trim() : null;
-		const normalized = normalizePhaseName(phaseNum);
+		parsedPhases.push({
+			phaseNum,
+			phaseName,
+			goal,
+			depends_on,
+			normalized: normalizePhaseName(phaseNum),
+			checkboxPattern: new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseNum.replace(".", "\\.")}`, "i")
+		});
+	}
+	let allDirs = [];
+	try {
+		allDirs = await listSubDirsAsync(phasesDir);
+	} catch {}
+	const phases = await Promise.all(parsedPhases.map(async (p) => {
 		let diskStatus = "no_directory";
 		let planCount = 0;
 		let summaryCount = 0;
 		let hasContext = false;
 		let hasResearch = false;
 		try {
-			const dirMatch = listSubDirs(phasesDir).find((d) => d.startsWith(normalized + "-") || d === normalized);
+			const dirMatch = allDirs.find((d) => d.startsWith(p.normalized + "-") || d === p.normalized);
 			if (dirMatch) {
-				const phaseFiles = node_fs.default.readdirSync(node_path.default.join(phasesDir, dirMatch));
+				const phaseFiles = await node_fs.default.promises.readdir(node_path.default.join(phasesDir, dirMatch));
 				planCount = phaseFiles.filter((f) => isPlanFile(f)).length;
 				summaryCount = phaseFiles.filter((f) => isSummaryFile(f)).length;
 				hasContext = phaseFiles.some((f) => f.endsWith("-CONTEXT.md") || f === "CONTEXT.md");
@@ -12609,22 +12621,21 @@ function cmdRoadmapAnalyze(cwd, raw) {
 		} catch (e) {
 			debugLog(e);
 		}
-		const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseNum.replace(".", "\\.")}`, "i");
-		const checkboxMatch = content.match(checkboxPattern);
+		const checkboxMatch = content.match(p.checkboxPattern);
 		const roadmapComplete = checkboxMatch ? checkboxMatch[1] === "x" : false;
-		phases.push({
-			number: phaseNum,
-			name: phaseName,
-			goal,
-			depends_on,
+		return {
+			number: p.phaseNum,
+			name: p.phaseName,
+			goal: p.goal,
+			depends_on: p.depends_on,
 			plan_count: planCount,
 			summary_count: summaryCount,
 			has_context: hasContext,
 			has_research: hasResearch,
 			disk_status: diskStatus,
 			roadmap_complete: roadmapComplete
-		});
-	}
+		};
+	}));
 	const milestones = [];
 	const milestonePattern = /##\s*(.*v(\d+\.\d+)[^(\n]*)/gi;
 	let mMatch;
@@ -12643,7 +12654,7 @@ function cmdRoadmapAnalyze(cwd, raw) {
 	while ((checklistMatch = checklistPattern.exec(content)) !== null) checklistPhases.add(checklistMatch[1]);
 	const detailPhases = new Set(phases.map((p) => p.number));
 	const missingDetails = [...checklistPhases].filter((p) => !detailPhases.has(p));
-	output({
+	return cmdOk({
 		milestones,
 		phases,
 		phase_count: phases.length,
@@ -12654,57 +12665,46 @@ function cmdRoadmapAnalyze(cwd, raw) {
 		current_phase: currentPhase ? currentPhase.number : null,
 		next_phase: nextPhase ? nextPhase.number : null,
 		missing_phase_details: missingDetails.length > 0 ? missingDetails : null
-	}, raw);
+	});
 }
-function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
-	if (!phaseNum) error("phase number required for roadmap update-plan-progress");
+function cmdRoadmapUpdatePlanProgress(cwd, phaseNum) {
+	if (!phaseNum) return cmdErr("phase number required for roadmap update-plan-progress");
 	const rmPath = roadmapPath(cwd);
 	const phaseInfo = findPhaseInternal(cwd, phaseNum);
-	if (!phaseInfo) error(`Phase ${phaseNum} not found`);
+	if (!phaseInfo) return cmdErr(`Phase ${phaseNum} not found`);
 	const planCount = phaseInfo.plans.length;
 	const summaryCount = phaseInfo.summaries.length;
-	if (planCount === 0) {
-		output({
-			updated: false,
-			reason: "No plans found",
-			plan_count: 0,
-			summary_count: 0
-		}, raw, "no plans");
-		return;
-	}
+	if (planCount === 0) return cmdOk({
+		updated: false,
+		reason: "No plans found",
+		plan_count: 0,
+		summary_count: 0
+	}, "no plans");
 	const isComplete = summaryCount >= planCount;
 	const status = isComplete ? "Complete" : summaryCount > 0 ? "In Progress" : "Planned";
 	const today = todayISO();
-	if (!node_fs.default.existsSync(rmPath)) {
-		output({
-			updated: false,
-			reason: "ROADMAP.md not found",
-			plan_count: planCount,
-			summary_count: summaryCount
-		}, raw, "no roadmap");
-		return;
-	}
+	if (!node_fs.default.existsSync(rmPath)) return cmdOk({
+		updated: false,
+		reason: "ROADMAP.md not found",
+		plan_count: planCount,
+		summary_count: summaryCount
+	}, "no roadmap");
 	let roadmapContent = node_fs.default.readFileSync(rmPath, "utf-8");
 	const phaseEscaped = phaseNum.replace(".", "\\.");
-	const tablePattern = new RegExp(`(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`, "i");
 	const dateField = isComplete ? ` ${today} ` : "  ";
-	roadmapContent = roadmapContent.replace(tablePattern, `$1 ${summaryCount}/${planCount} $2 ${status.padEnd(11)}$3${dateField}$4`);
-	const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, "i");
+	roadmapContent = roadmapContent.replace(new RegExp(`(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`, "i"), `$1 ${summaryCount}/${planCount} $2 ${status.padEnd(11)}$3${dateField}$4`);
 	const planCountText = isComplete ? `${summaryCount}/${planCount} plans complete` : `${summaryCount}/${planCount} plans executed`;
-	roadmapContent = roadmapContent.replace(planCountPattern, `$1${planCountText}`);
-	if (isComplete) {
-		const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`, "i");
-		roadmapContent = roadmapContent.replace(checkboxPattern, `$1x$2 (completed ${today})`);
-	}
+	roadmapContent = roadmapContent.replace(new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, "i"), `$1${planCountText}`);
+	if (isComplete) roadmapContent = roadmapContent.replace(new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phaseEscaped}[:\\s][^\\n]*)`, "i"), `$1x$2 (completed ${today})`);
 	node_fs.default.writeFileSync(rmPath, roadmapContent, "utf-8");
-	output({
+	return cmdOk({
 		updated: true,
 		phase: phaseNum,
 		plan_count: planCount,
 		summary_count: summaryCount,
 		status,
 		complete: isComplete
-	}, raw, `${summaryCount}/${planCount} ${status}`);
+	}, `${summaryCount}/${planCount} ${status}`);
 }
 
 //#endregion
@@ -12714,19 +12714,16 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
 *
 * Ported from maxsim/bin/lib/milestone.cjs
 */
-function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
-	if (!reqIdsRaw || reqIdsRaw.length === 0) error("requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02");
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw) {
+	if (!reqIdsRaw || reqIdsRaw.length === 0) return cmdErr("requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02");
 	const reqIds = reqIdsRaw.join(" ").replace(/[\[\]]/g, "").split(/[,\s]+/).map((r) => r.trim()).filter(Boolean);
-	if (reqIds.length === 0) error("no valid requirement IDs found");
+	if (reqIds.length === 0) return cmdErr("no valid requirement IDs found");
 	const reqPath = planningPath(cwd, "REQUIREMENTS.md");
-	if (!node_fs.default.existsSync(reqPath)) {
-		output({
-			updated: false,
-			reason: "REQUIREMENTS.md not found",
-			ids: reqIds
-		}, raw, "no requirements file");
-		return;
-	}
+	if (!node_fs.default.existsSync(reqPath)) return cmdOk({
+		updated: false,
+		reason: "REQUIREMENTS.md not found",
+		ids: reqIds
+	}, "no requirements file");
 	let reqContent = node_fs.default.readFileSync(reqPath, "utf-8");
 	const updated = [];
 	const notFound = [];
@@ -12745,15 +12742,15 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
 		else notFound.push(reqId);
 	}
 	if (updated.length > 0) node_fs.default.writeFileSync(reqPath, reqContent, "utf-8");
-	output({
+	return cmdOk({
 		updated: updated.length > 0,
 		marked_complete: updated,
 		not_found: notFound,
 		total: reqIds.length
-	}, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+	}, `${updated.length}/${reqIds.length} requirements marked complete`);
 }
-function cmdMilestoneComplete(cwd, version, options, raw) {
-	if (!version) error("version required for milestone complete (e.g., v1.0)");
+function cmdMilestoneComplete(cwd, version, options) {
+	if (!version) return cmdErr("version required for milestone complete (e.g., v1.0)");
 	const roadmapPath$1 = roadmapPath(cwd);
 	const reqPath = planningPath(cwd, "REQUIREMENTS.md");
 	const statePath$1 = statePath(cwd);
@@ -12822,7 +12819,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		version,
 		name: milestoneName,
 		date: today,
@@ -12838,7 +12835,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
 		},
 		milestones_updated: true,
 		state_updated: node_fs.default.existsSync(statePath$1)
-	}, raw);
+	});
 }
 
 //#endregion
@@ -13267,12 +13264,12 @@ function parseTodoFrontmatter(content) {
 	};
 }
 function cmdGenerateSlug(text, raw) {
-	if (!text) error("text required for slug generation");
+	if (!text) return cmdErr("text required for slug generation");
 	const slug = (0, import_slugify.default)(text, {
 		lower: true,
 		strict: true
 	});
-	output({ slug }, raw, slug);
+	return cmdOk({ slug }, raw ? slug : void 0);
 }
 function cmdCurrentTimestamp(format, raw) {
 	const now = /* @__PURE__ */ new Date();
@@ -13288,7 +13285,7 @@ function cmdCurrentTimestamp(format, raw) {
 			result = now.toISOString();
 			break;
 	}
-	output({ timestamp: result }, raw, result);
+	return cmdOk({ timestamp: result }, raw ? result : void 0);
 }
 function cmdListTodos(cwd, area, raw) {
 	const pendingDir = planningPath(cwd, "todos", "pending");
@@ -13313,25 +13310,26 @@ function cmdListTodos(cwd, area, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		count,
 		todos
-	}, raw, count.toString());
+	}, raw ? count.toString() : void 0);
 }
 function cmdVerifyPathExists(cwd, targetPath, raw) {
-	if (!targetPath) error("path required for verification");
+	if (!targetPath) return cmdErr("path required for verification");
 	const fullPath = node_path.default.isAbsolute(targetPath) ? targetPath : node_path.default.join(cwd, targetPath);
 	try {
 		const stats = node_fs.default.statSync(fullPath);
-		output({
+		return cmdOk({
 			exists: true,
 			type: stats.isDirectory() ? "directory" : stats.isFile() ? "file" : "other"
-		}, raw, "true");
-	} catch {
-		output({
+		}, raw ? "true" : void 0);
+	} catch (e) {
+		rethrowCliSignals(e);
+		return cmdOk({
 			exists: false,
 			type: null
-		}, raw, "false");
+		}, raw ? "false" : void 0);
 	}
 }
 function cmdHistoryDigest(cwd, raw) {
@@ -13358,14 +13356,11 @@ function cmdHistoryDigest(cwd, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	if (allPhaseDirs.length === 0) {
-		output({
-			phases: {},
-			decisions: [],
-			tech_stack: []
-		}, raw);
-		return;
-	}
+	if (allPhaseDirs.length === 0) return cmdOk({
+		phases: {},
+		decisions: [],
+		tech_stack: []
+	});
 	try {
 		for (const { name: dir, fullPath: dirPath } of allPhaseDirs) {
 			const summaries = node_fs.default.readdirSync(dirPath).filter((f) => isSummaryFile(f));
@@ -13406,48 +13401,40 @@ function cmdHistoryDigest(cwd, raw) {
 			affects: [...data.affects],
 			patterns: [...data.patterns]
 		};
-		output(outputDigest, raw);
+		return cmdOk(outputDigest);
 	} catch (e) {
-		error("Failed to generate history digest: " + e.message);
+		rethrowCliSignals(e);
+		return cmdErr("Failed to generate history digest: " + e.message);
 	}
 }
 function cmdResolveModel(cwd, agentType, raw) {
-	if (!agentType) error("agent-type required");
+	if (!agentType) return cmdErr("agent-type required");
 	const profile = loadConfig(cwd).model_profile || "balanced";
 	const agentModels = MODEL_PROFILES[agentType];
-	if (!agentModels) {
-		output({
-			model: "sonnet",
-			profile,
-			unknown_agent: true
-		}, raw, "sonnet");
-		return;
-	}
+	if (!agentModels) return cmdOk({
+		model: "sonnet",
+		profile,
+		unknown_agent: true
+	}, raw ? "sonnet" : void 0);
 	const resolved = agentModels[profile] || agentModels["balanced"] || "sonnet";
 	const model = resolved === "opus" ? "inherit" : resolved;
-	output({
+	return cmdOk({
 		model,
 		profile
-	}, raw, model);
+	}, raw ? model : void 0);
 }
 async function cmdCommit(cwd, message, files, raw, amend) {
-	if (!message && !amend) error("commit message required");
-	if (!loadConfig(cwd).commit_docs) {
-		output({
-			committed: false,
-			hash: null,
-			reason: "skipped_commit_docs_false"
-		}, raw, "skipped");
-		return;
-	}
-	if (await isGitIgnored(cwd, ".planning")) {
-		output({
-			committed: false,
-			hash: null,
-			reason: "skipped_gitignored"
-		}, raw, "skipped");
-		return;
-	}
+	if (!message && !amend) return cmdErr("commit message required");
+	if (!loadConfig(cwd).commit_docs) return cmdOk({
+		committed: false,
+		hash: null,
+		reason: "skipped_commit_docs_false"
+	}, raw ? "skipped" : void 0);
+	if (await isGitIgnored(cwd, ".planning")) return cmdOk({
+		committed: false,
+		hash: null,
+		reason: "skipped_gitignored"
+	}, raw ? "skipped" : void 0);
 	const filesToStage = files && files.length > 0 ? files : [".planning/"];
 	for (const file of filesToStage) await execGit(cwd, ["add", file]);
 	const commitResult = await execGit(cwd, amend ? [
@@ -13460,21 +13447,17 @@ async function cmdCommit(cwd, message, files, raw, amend) {
 		message
 	]);
 	if (commitResult.exitCode !== 0) {
-		if (commitResult.stdout.includes("nothing to commit") || commitResult.stderr.includes("nothing to commit")) {
-			output({
-				committed: false,
-				hash: null,
-				reason: "nothing_to_commit"
-			}, raw, "nothing");
-			return;
-		}
-		output({
+		if (commitResult.stdout.includes("nothing to commit") || commitResult.stderr.includes("nothing to commit")) return cmdOk({
+			committed: false,
+			hash: null,
+			reason: "nothing_to_commit"
+		}, raw ? "nothing" : void 0);
+		return cmdOk({
 			committed: false,
 			hash: null,
 			reason: "nothing_to_commit",
 			error: commitResult.stderr
-		}, raw, "nothing");
-		return;
+		}, raw ? "nothing" : void 0);
 	}
 	const hashResult = await execGit(cwd, [
 		"rev-parse",
@@ -13482,22 +13465,19 @@ async function cmdCommit(cwd, message, files, raw, amend) {
 		"HEAD"
 	]);
 	const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
-	output({
+	return cmdOk({
 		committed: true,
 		hash,
 		reason: "committed"
-	}, raw, hash || "committed");
+	}, raw ? hash || "committed" : void 0);
 }
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
-	if (!summaryPath) error("summary-path required for summary-extract");
+	if (!summaryPath) return cmdErr("summary-path required for summary-extract");
 	const fullPath = node_path.default.join(cwd, summaryPath);
-	if (!node_fs.default.existsSync(fullPath)) {
-		output({
-			error: "File not found",
-			path: summaryPath
-		}, raw);
-		return;
-	}
+	if (!node_fs.default.existsSync(fullPath)) return cmdOk({
+		error: "File not found",
+		path: summaryPath
+	});
 	const fm = extractFrontmatter(node_fs.default.readFileSync(fullPath, "utf-8"));
 	const parseDecisions = (decisionsList) => {
 		if (!decisionsList || !Array.isArray(decisionsList)) return [];
@@ -13526,27 +13506,20 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
 	if (fields && fields.length > 0) {
 		const filtered = { path: summaryPath };
 		for (const field of fields) if (fullResult[field] !== void 0) filtered[field] = fullResult[field];
-		output(filtered, raw);
-		return;
+		return cmdOk(filtered);
 	}
-	output(fullResult, raw);
+	return cmdOk(fullResult);
 }
 async function cmdWebsearch(query, options, raw) {
 	const apiKey = process.env.BRAVE_API_KEY;
-	if (!apiKey) {
-		output({
-			available: false,
-			reason: "BRAVE_API_KEY not set"
-		}, raw, "");
-		return;
-	}
-	if (!query) {
-		output({
-			available: false,
-			error: "Query required"
-		}, raw, "");
-		return;
-	}
+	if (!apiKey) return cmdOk({
+		available: false,
+		reason: "BRAVE_API_KEY not set"
+	}, raw ? "" : void 0);
+	if (!query) return cmdOk({
+		available: false,
+		error: "Query required"
+	}, raw ? "" : void 0);
 	const params = new URLSearchParams({
 		q: query,
 		count: String(options.limit || 10),
@@ -13560,30 +13533,28 @@ async function cmdWebsearch(query, options, raw) {
 			Accept: "application/json",
 			"X-Subscription-Token": apiKey
 		} });
-		if (!response.ok) {
-			output({
-				available: false,
-				error: `API error: ${response.status}`
-			}, raw, "");
-			return;
-		}
+		if (!response.ok) return cmdOk({
+			available: false,
+			error: `API error: ${response.status}`
+		}, raw ? "" : void 0);
 		const results = ((await response.json()).web?.results || []).map((r) => ({
 			title: r.title,
 			url: r.url,
 			description: r.description,
 			age: r.age || null
 		}));
-		output({
+		return cmdOk({
 			available: true,
 			query,
 			count: results.length,
 			results
-		}, raw, results.map((r) => `${r.title}\n${r.url}\n${r.description}`).join("\n\n"));
+		}, raw ? results.map((r) => `${r.title}\n${r.url}\n${r.description}`).join("\n\n") : void 0);
 	} catch (err) {
-		output({
+		rethrowCliSignals(err);
+		return cmdOk({
 			available: false,
 			error: err.message
-		}, raw, "");
+		}, raw ? "" : void 0);
 	}
 }
 function cmdProgressRender(cwd, format, raw) {
@@ -13631,17 +13602,17 @@ function cmdProgressRender(cwd, format, raw) {
 		out += `| Phase | Name | Plans | Status |\n`;
 		out += `|-------|------|-------|--------|\n`;
 		for (const p of phases) out += `| ${p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${p.status} |\n`;
-		output({ rendered: out }, raw, out);
+		return cmdOk({ rendered: out }, raw ? out : void 0);
 	} else if (format === "bar") {
 		const barWidth = 20;
 		const filled = Math.round(percent / 100 * barWidth);
 		const text = `[${"█".repeat(filled) + "░".repeat(barWidth - filled)}] ${totalSummaries}/${totalPlans} plans (${percent}%)`;
-		output({
+		return cmdOk({
 			bar: text,
 			percent,
 			completed: totalSummaries,
 			total: totalPlans
-		}, raw, text);
+		}, raw ? text : void 0);
 	} else if (format === "phase-bars") {
 		const doneCount = phases.filter((p) => p.status === "Complete").length;
 		const inProgressCount = phases.filter((p) => p.status === "In Progress").length;
@@ -13661,39 +13632,39 @@ function cmdProgressRender(cwd, format, raw) {
 			lines.push(line);
 		}
 		const rendered = lines.join("\n");
-		output({
+		return cmdOk({
 			rendered,
 			done: doneCount,
 			in_progress: inProgressCount,
 			total: totalCount,
 			percent
-		}, raw, rendered);
-	} else output({
+		}, raw ? rendered : void 0);
+	} else return cmdOk({
 		milestone_version: milestone.version,
 		milestone_name: milestone.name,
 		phases,
 		total_plans: totalPlans,
 		total_summaries: totalSummaries,
 		percent
-	}, raw);
+	});
 }
 function cmdTodoComplete(cwd, filename, raw) {
-	if (!filename) error("filename required for todo complete");
+	if (!filename) return cmdErr("filename required for todo complete");
 	const pendingDir = planningPath(cwd, "todos", "pending");
 	const completedDir = planningPath(cwd, "todos", "completed");
 	const sourcePath = node_path.default.join(pendingDir, filename);
-	if (!node_fs.default.existsSync(sourcePath)) error(`Todo not found: ${filename}`);
+	if (!node_fs.default.existsSync(sourcePath)) return cmdErr(`Todo not found: ${filename}`);
 	node_fs.default.mkdirSync(completedDir, { recursive: true });
 	let content = node_fs.default.readFileSync(sourcePath, "utf-8");
 	const today = todayISO();
 	content = `completed: ${today}\n` + content;
 	node_fs.default.writeFileSync(node_path.default.join(completedDir, filename), content, "utf-8");
 	node_fs.default.unlinkSync(sourcePath);
-	output({
+	return cmdOk({
 		completed: true,
 		file: filename,
 		date: today
-	}, raw, "completed");
+	}, raw ? "completed" : void 0);
 }
 function cmdScaffold(cwd, type, options, raw) {
 	const { phase, name } = options;
@@ -13701,7 +13672,7 @@ function cmdScaffold(cwd, type, options, raw) {
 	const today = todayISO();
 	const phaseInfo = phase ? findPhaseInternal(cwd, phase) : null;
 	const phaseDir = phaseInfo ? node_path.default.join(cwd, phaseInfo.directory) : null;
-	if (phase && !phaseDir && type !== "phase-dir") error(`Phase ${phase} directory not found`);
+	if (phase && !phaseDir && type !== "phase-dir") return cmdErr(`Phase ${phase} directory not found`);
 	let filePath;
 	let content;
 	switch (type) {
@@ -13718,37 +13689,31 @@ function cmdScaffold(cwd, type, options, raw) {
 			content = `---\nphase: "${padded}"\nname: "${name || phaseInfo?.phase_name || "Unnamed"}"\ncreated: ${today}\nstatus: pending\n---\n\n# Phase ${phase}: ${name || phaseInfo?.phase_name || "Unnamed"} — Verification\n\n## Goal-Backward Verification\n\n**Phase Goal:** [From ROADMAP.md]\n\n## Checks\n\n| # | Requirement | Status | Evidence |\n|---|------------|--------|----------|\n\n## Result\n\n_Pending verification_\n`;
 			break;
 		case "phase-dir": {
-			if (!phase || !name) error("phase and name required for phase-dir scaffold");
+			if (!phase || !name) return cmdErr("phase and name required for phase-dir scaffold");
 			const dirName = `${padded}-${generateSlugInternal(name)}`;
 			const phasesParent = phasesPath(cwd);
 			node_fs.default.mkdirSync(phasesParent, { recursive: true });
 			const dirPath = node_path.default.join(phasesParent, dirName);
 			node_fs.default.mkdirSync(dirPath, { recursive: true });
-			output({
+			return cmdOk({
 				created: true,
 				directory: `.planning/phases/${dirName}`,
 				path: dirPath
-			}, raw, dirPath);
-			return;
+			}, raw ? dirPath : void 0);
 		}
-		default:
-			error(`Unknown scaffold type: ${type}. Available: context, uat, verification, phase-dir`);
-			return;
-	}
-	if (node_fs.default.existsSync(filePath)) {
-		output({
-			created: false,
-			reason: "already_exists",
-			path: filePath
-		}, raw, "exists");
-		return;
+		default: return cmdErr(`Unknown scaffold type: ${type}. Available: context, uat, verification, phase-dir`);
 	}
+	if (node_fs.default.existsSync(filePath)) return cmdOk({
+		created: false,
+		reason: "already_exists",
+		path: filePath
+	}, raw ? "exists" : void 0);
 	node_fs.default.writeFileSync(filePath, content, "utf-8");
 	const relPath = node_path.default.relative(cwd, filePath);
-	output({
+	return cmdOk({
 		created: true,
 		path: relPath
-	}, raw, relPath);
+	}, raw ? relPath : void 0);
 }
 
 //#endregion
@@ -13758,27 +13723,24 @@ function cmdScaffold(cwd, type, options, raw) {
 *
 * Ported from maxsim/bin/lib/verify.cjs
 */
-async function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
-	if (!summaryPath) error("summary-path required");
+async function cmdVerifySummary(cwd, summaryPath, checkFileCount) {
+	if (!summaryPath) return cmdErr("summary-path required");
 	const fullPath = node_path.default.join(cwd, summaryPath);
 	const checkCount = checkFileCount || 2;
-	if (!node_fs.default.existsSync(fullPath)) {
-		output({
-			passed: false,
-			checks: {
-				summary_exists: false,
-				files_created: {
-					checked: 0,
-					found: 0,
-					missing: []
-				},
-				commits_exist: false,
-				self_check: "not_found"
+	if (!node_fs.default.existsSync(fullPath)) return cmdOk({
+		passed: false,
+		checks: {
+			summary_exists: false,
+			files_created: {
+				checked: 0,
+				found: 0,
+				missing: []
 			},
-			errors: ["SUMMARY.md not found"]
-		}, raw, "failed");
-		return;
-	}
+			commits_exist: false,
+			self_check: "not_found"
+		},
+		errors: ["SUMMARY.md not found"]
+	}, "failed");
 	const content = node_fs.default.readFileSync(fullPath, "utf-8");
 	const errors = [];
 	const mentionedFiles = /* @__PURE__ */ new Set();
@@ -13828,22 +13790,19 @@ async function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
 		self_check: selfCheck
 	};
 	const passed = missing.length === 0 && selfCheck !== "failed";
-	output({
+	return cmdOk({
 		passed,
 		checks,
 		errors
-	}, raw, passed ? "passed" : "failed");
+	}, passed ? "passed" : "failed");
 }
-function cmdVerifyPlanStructure(cwd, filePath, raw) {
-	if (!filePath) error("file path required");
+function cmdVerifyPlanStructure(cwd, filePath) {
+	if (!filePath) return cmdErr("file path required");
 	const content = safeReadFile(node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(cwd, filePath));
-	if (!content) {
-		output({
-			error: "File not found",
-			path: filePath
-		}, raw);
-		return;
-	}
+	if (!content) return cmdOk({
+		error: "File not found",
+		path: filePath
+	});
 	const fm = extractFrontmatter(content);
 	const errors = [];
 	const warnings = [];
@@ -13884,25 +13843,22 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
 	if (tasks.length === 0) warnings.push("No <task> elements found");
 	if (fm.wave && parseInt(String(fm.wave)) > 1 && (!fm.depends_on || Array.isArray(fm.depends_on) && fm.depends_on.length === 0)) warnings.push("Wave > 1 but depends_on is empty");
 	if (/<task\s+type=["']?checkpoint/.test(content) && fm.autonomous !== "false" && fm.autonomous !== false) errors.push("Has checkpoint tasks but autonomous is not false");
-	output({
+	return cmdOk({
 		valid: errors.length === 0,
 		errors,
 		warnings,
 		task_count: tasks.length,
 		tasks,
 		frontmatter_fields: Object.keys(fm)
-	}, raw, errors.length === 0 ? "valid" : "invalid");
+	}, errors.length === 0 ? "valid" : "invalid");
 }
-function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
-	if (!phase) error("phase required");
+function cmdVerifyPhaseCompleteness(cwd, phase) {
+	if (!phase) return cmdErr("phase required");
 	const phaseInfo = findPhaseInternal(cwd, phase);
-	if (!phaseInfo) {
-		output({
-			error: "Phase not found",
-			phase
-		}, raw);
-		return;
-	}
+	if (!phaseInfo) return cmdOk({
+		error: "Phase not found",
+		phase
+	});
 	const errors = [];
 	const warnings = [];
 	const phaseDir = node_path.default.join(cwd, phaseInfo.directory);
@@ -13910,8 +13866,7 @@ function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
 	try {
 		files = node_fs.default.readdirSync(phaseDir);
 	} catch {
-		output({ error: "Cannot read phase directory" }, raw);
-		return;
+		return cmdOk({ error: "Cannot read phase directory" });
 	}
 	const plans = files.filter((f) => isPlanFile(f));
 	const summaries = files.filter((f) => isSummaryFile(f));
@@ -13921,7 +13876,7 @@ function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
 	if (incompletePlans.length > 0) errors.push(`Plans without summaries: ${incompletePlans.join(", ")}`);
 	const orphanSummaries = [...summaryIds].filter((id) => !planIds.has(id));
 	if (orphanSummaries.length > 0) warnings.push(`Summaries without plans: ${orphanSummaries.join(", ")}`);
-	output({
+	return cmdOk({
 		complete: errors.length === 0,
 		phase: phaseInfo.phase_number,
 		plan_count: plans.length,
@@ -13930,18 +13885,15 @@ function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
 		orphan_summaries: orphanSummaries,
 		errors,
 		warnings
-	}, raw, errors.length === 0 ? "complete" : "incomplete");
+	}, errors.length === 0 ? "complete" : "incomplete");
 }
-function cmdVerifyReferences(cwd, filePath, raw) {
-	if (!filePath) error("file path required");
+function cmdVerifyReferences(cwd, filePath) {
+	if (!filePath) return cmdErr("file path required");
 	const content = safeReadFile(node_path.default.isAbsolute(filePath) ? filePath : node_path.default.join(cwd, filePath));
-	if (!content) {
-		output({
-			error: "File not found",
-			path: filePath
-		}, raw);
-		return;
-	}
+	if (!content) return cmdOk({
+		error: "File not found",
+		path: filePath
+	});
 	const found = [];
 	const missing = [];
 	const atRefs = content.match(/@([^\s\n,)]+\/[^\s\n,)]+)/g) || [];
@@ -13960,15 +13912,15 @@ function cmdVerifyReferences(cwd, filePath, raw) {
 		if (node_fs.default.existsSync(resolved)) found.push(cleanRef);
 		else missing.push(cleanRef);
 	}
-	output({
+	return cmdOk({
 		valid: missing.length === 0,
 		found: found.length,
 		missing,
 		total: found.length + missing.length
-	}, raw, missing.length === 0 ? "valid" : "invalid");
+	}, missing.length === 0 ? "valid" : "invalid");
 }
-async function cmdVerifyCommits(cwd, hashes, raw) {
-	if (!hashes || hashes.length === 0) error("At least one commit hash required");
+async function cmdVerifyCommits(cwd, hashes) {
+	if (!hashes || hashes.length === 0) return cmdErr("At least one commit hash required");
 	const valid = [];
 	const invalid = [];
 	for (const hash of hashes) {
@@ -13980,31 +13932,25 @@ async function cmdVerifyCommits(cwd, hashes, raw) {
 		if (result.exitCode === 0 && result.stdout.trim() === "commit") valid.push(hash);
 		else invalid.push(hash);
 	}
-	output({
+	return cmdOk({
 		all_valid: invalid.length === 0,
 		valid,
 		invalid,
 		total: hashes.length
-	}, raw, invalid.length === 0 ? "valid" : "invalid");
+	}, invalid.length === 0 ? "valid" : "invalid");
 }
-function cmdVerifyArtifacts(cwd, planFilePath, raw) {
-	if (!planFilePath) error("plan file path required");
+function cmdVerifyArtifacts(cwd, planFilePath) {
+	if (!planFilePath) return cmdErr("plan file path required");
 	const content = safeReadFile(node_path.default.isAbsolute(planFilePath) ? planFilePath : node_path.default.join(cwd, planFilePath));
-	if (!content) {
-		output({
-			error: "File not found",
-			path: planFilePath
-		}, raw);
-		return;
-	}
+	if (!content) return cmdOk({
+		error: "File not found",
+		path: planFilePath
+	});
 	const artifacts = parseMustHavesBlock(content, "artifacts");
-	if (artifacts.length === 0) {
-		output({
-			error: "No must_haves.artifacts found in frontmatter",
-			path: planFilePath
-		}, raw);
-		return;
-	}
+	if (artifacts.length === 0) return cmdOk({
+		error: "No must_haves.artifacts found in frontmatter",
+		path: planFilePath
+	});
 	const results = [];
 	for (const artifact of artifacts) {
 		if (typeof artifact === "string") continue;
@@ -14033,31 +13979,25 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
 		results.push(check);
 	}
 	const passed = results.filter((r) => r.passed).length;
-	output({
+	return cmdOk({
 		all_passed: passed === results.length,
 		passed,
 		total: results.length,
 		artifacts: results
-	}, raw, passed === results.length ? "valid" : "invalid");
+	}, passed === results.length ? "valid" : "invalid");
 }
-function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
-	if (!planFilePath) error("plan file path required");
+function cmdVerifyKeyLinks(cwd, planFilePath) {
+	if (!planFilePath) return cmdErr("plan file path required");
 	const content = safeReadFile(node_path.default.isAbsolute(planFilePath) ? planFilePath : node_path.default.join(cwd, planFilePath));
-	if (!content) {
-		output({
-			error: "File not found",
-			path: planFilePath
-		}, raw);
-		return;
-	}
+	if (!content) return cmdOk({
+		error: "File not found",
+		path: planFilePath
+	});
 	const keyLinks = parseMustHavesBlock(content, "key_links");
-	if (keyLinks.length === 0) {
-		output({
-			error: "No must_haves.key_links found in frontmatter",
-			path: planFilePath
-		}, raw);
-		return;
-	}
+	if (keyLinks.length === 0) return cmdOk({
+		error: "No must_haves.key_links found in frontmatter",
+		path: planFilePath
+	});
 	const results = [];
 	for (const link of keyLinks) {
 		if (typeof link === "string") continue;
@@ -14093,26 +14033,25 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
 		results.push(check);
 	}
 	const verified = results.filter((r) => r.verified).length;
-	output({
+	return cmdOk({
 		all_verified: verified === results.length,
 		verified,
 		total: results.length,
 		links: results
-	}, raw, verified === results.length ? "valid" : "invalid");
+	}, verified === results.length ? "valid" : "invalid");
 }
-function cmdValidateConsistency(cwd, raw) {
+function cmdValidateConsistency(cwd) {
 	const rmPath = roadmapPath(cwd);
 	const phasesDir = phasesPath(cwd);
 	const errors = [];
 	const warnings = [];
 	if (!node_fs.default.existsSync(rmPath)) {
 		errors.push("ROADMAP.md not found");
-		output({
+		return cmdOk({
 			passed: false,
 			errors,
 			warnings
-		}, raw, "failed");
-		return;
+		}, "failed");
 	}
 	const roadmapContent = node_fs.default.readFileSync(rmPath, "utf-8");
 	const roadmapPhases = /* @__PURE__ */ new Set();
@@ -14164,14 +14103,14 @@ function cmdValidateConsistency(cwd, raw) {
 		debugLog(e);
 	}
 	const passed = errors.length === 0;
-	output({
+	return cmdOk({
 		passed,
 		errors,
 		warnings,
 		warning_count: warnings.length
-	}, raw, passed ? "passed" : "failed");
+	}, passed ? "passed" : "failed");
 }
-function cmdValidateHealth(cwd, options, raw) {
+function cmdValidateHealth(cwd, options) {
 	const planningDir = planningPath(cwd);
 	const projectPath = planningPath(cwd, "PROJECT.md");
 	const rmPath = roadmapPath(cwd);
@@ -14195,14 +14134,13 @@ function cmdValidateHealth(cwd, options, raw) {
 	};
 	if (!node_fs.default.existsSync(planningDir)) {
 		addIssue("error", "E001", ".planning/ directory not found", "Run /maxsim:new-project to initialize");
-		output({
+		return cmdOk({
 			status: "broken",
 			errors,
 			warnings,
 			info,
 			repairable_count: 0
-		}, raw);
-		return;
+		});
 	}
 	if (!node_fs.default.existsSync(projectPath)) addIssue("error", "E002", "PROJECT.md not found", "Run /maxsim:new-project to create");
 	else {
@@ -14362,14 +14300,14 @@ function cmdValidateHealth(cwd, options, raw) {
 	else if (warnings.length > 0) status = "degraded";
 	else status = "healthy";
 	const repairableCount = errors.filter((e) => e.repairable).length + warnings.filter((w) => w.repairable).length;
-	output({
+	return cmdOk({
 		status,
 		errors,
 		warnings,
 		info,
 		repairable_count: repairableCount,
 		repairs_performed: repairActions.length > 0 ? repairActions : void 0
-	}, raw);
+	});
 }
 
 //#endregion
@@ -14435,7 +14373,7 @@ function phaseInsertCore(cwd, afterPhase, description, options) {
 			if (dm) existingDecimals.push(parseInt(dm[1], 10));
 		}
 	} catch (e) {
-		debugLog(e);
+		debugLog("phase-insert-decimal-scan-failed", e);
 	}
 	const decimalPhase = `${normalizedBase}.${existingDecimals.length === 0 ? 1 : Math.max(...existingDecimals) + 1}`;
 	const dirName = `${decimalPhase}-${slug}`;
@@ -14481,7 +14419,9 @@ function phaseCompleteCore(cwd, phaseNum) {
 		roadmapContent = roadmapContent.replace(tablePattern, `$1 Complete    $2 ${today} $3`);
 		const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?\\*\\*Plans:\\*\\*\\s*)[^\\n]+`, "i");
 		roadmapContent = roadmapContent.replace(planCountPattern, `$1${summaryCount}/${planCount} plans complete`);
+		debugLog("phase-complete-write", `writing ROADMAP.md for phase ${phaseNum}`);
 		node_fs.default.writeFileSync(rmPath, roadmapContent, "utf-8");
+		debugLog("phase-complete-write", `ROADMAP.md updated for phase ${phaseNum}`);
 		const reqPath = planningPath(cwd, "REQUIREMENTS.md");
 		if (node_fs.default.existsSync(reqPath)) {
 			const reqMatch = roadmapContent.match(new RegExp(`Phase\\s+${escapePhaseNum(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, "i"));
@@ -14492,7 +14432,9 @@ function phaseCompleteCore(cwd, phaseNum) {
 					reqContent = reqContent.replace(new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqId}\\*\\*)`, "gi"), "$1x$2");
 					reqContent = reqContent.replace(new RegExp(`(\\|\\s*${reqId}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, "gi"), "$1 Complete $2");
 				}
+				debugLog("phase-complete-write", `writing REQUIREMENTS.md for phase ${phaseNum}`);
 				node_fs.default.writeFileSync(reqPath, reqContent, "utf-8");
+				debugLog("phase-complete-write", `REQUIREMENTS.md updated for phase ${phaseNum}`);
 				requirementsUpdated = true;
 			}
 		}
@@ -14514,7 +14456,7 @@ function phaseCompleteCore(cwd, phaseNum) {
 			}
 		}
 	} catch (e) {
-		debugLog(e);
+		debugLog("phase-complete-next-phase-scan-failed", e);
 	}
 	if (node_fs.default.existsSync(stPath)) {
 		let stateContent = node_fs.default.readFileSync(stPath, "utf-8");
@@ -14524,7 +14466,9 @@ function phaseCompleteCore(cwd, phaseNum) {
 		stateContent = stateContent.replace(/(\*\*Current Plan:\*\*\s*).*/, `$1Not started`);
 		stateContent = stateContent.replace(/(\*\*Last Activity:\*\*\s*).*/, `$1${today}`);
 		stateContent = stateContent.replace(/(\*\*Last Activity Description:\*\*\s*).*/, `$1Phase ${phaseNum} complete${nextPhaseNum ? `, transitioned to Phase ${nextPhaseNum}` : ""}`);
+		debugLog("phase-complete-write", `writing STATE.md for phase ${phaseNum}`);
 		node_fs.default.writeFileSync(stPath, stateContent, "utf-8");
+		debugLog("phase-complete-write", `STATE.md updated for phase ${phaseNum}`);
 	}
 	return {
 		completed_phase: phaseNum,
@@ -14539,22 +14483,21 @@ function phaseCompleteCore(cwd, phaseNum) {
 		requirements_updated: requirementsUpdated
 	};
 }
-function cmdPhasesList(cwd, options, raw) {
+async function cmdPhasesList(cwd, options) {
 	const phasesDirPath = phasesPath(cwd);
-	const { type, phase, includeArchived } = options;
-	if (!node_fs.default.existsSync(phasesDirPath)) {
-		if (type) output({
-			files: [],
-			count: 0
-		}, raw, "");
-		else output({
-			directories: [],
-			count: 0
-		}, raw, "");
-		return;
-	}
+	const { type, phase, includeArchived, offset, limit } = options;
+	if (!node_fs.default.existsSync(phasesDirPath)) if (type) return cmdOk({
+		files: [],
+		count: 0,
+		total: 0
+	}, "");
+	else return cmdOk({
+		directories: [],
+		count: 0,
+		total: 0
+	}, "");
 	try {
-		let dirs = listSubDirs(phasesDirPath);
+		let dirs = await listSubDirsAsync(phasesDirPath);
 		if (includeArchived) {
 			const archived = getArchivedPhaseDirs(cwd);
 			for (const a of archived) dirs.push(`${a.name} [${a.milestone}]`);
@@ -14563,55 +14506,53 @@ function cmdPhasesList(cwd, options, raw) {
 		if (phase) {
 			const normalized = normalizePhaseName(phase);
 			const match = dirs.find((d) => d.startsWith(normalized));
-			if (!match) {
-				output({
-					files: [],
-					count: 0,
-					phase_dir: null,
-					error: "Phase not found"
-				}, raw, "");
-				return;
-			}
+			if (!match) return cmdOk({
+				files: [],
+				count: 0,
+				total: 0,
+				phase_dir: null,
+				error: "Phase not found"
+			}, "");
 			dirs = [match];
 		}
 		if (type) {
-			const files = [];
-			for (const dir of dirs) {
+			const files = (await Promise.all(dirs.map(async (dir) => {
 				const dirPath = node_path.default.join(phasesDirPath, dir);
-				const dirFiles = node_fs.default.readdirSync(dirPath);
+				const dirFiles = await node_fs.default.promises.readdir(dirPath);
 				let filtered;
 				if (type === "plans") filtered = dirFiles.filter(isPlanFile);
 				else if (type === "summaries") filtered = dirFiles.filter(isSummaryFile);
 				else filtered = dirFiles;
-				files.push(...filtered.sort());
-			}
-			output({
+				return filtered.sort();
+			}))).flat();
+			return cmdOk({
 				files,
 				count: files.length,
+				total: files.length,
 				phase_dir: phase ? dirs[0].replace(/^\d+(?:\.\d+)?-?/, "") : null
-			}, raw, files.join("\n"));
-			return;
-		}
-		output({
-			directories: dirs,
-			count: dirs.length
-		}, raw, dirs.join("\n"));
+			}, files.join("\n"));
+		}
+		const total = dirs.length;
+		const start = offset ?? 0;
+		const paginated = limit !== void 0 ? dirs.slice(start, start + limit) : dirs.slice(start);
+		return cmdOk({
+			directories: paginated,
+			count: paginated.length,
+			total
+		}, paginated.join("\n"));
 	} catch (e) {
-		error("Failed to list phases: " + e.message);
+		return cmdErr("Failed to list phases: " + e.message);
 	}
 }
-function cmdPhaseNextDecimal(cwd, basePhase, raw) {
+function cmdPhaseNextDecimal(cwd, basePhase) {
 	const phasesDirPath = phasesPath(cwd);
 	const normalized = normalizePhaseName(basePhase);
-	if (!node_fs.default.existsSync(phasesDirPath)) {
-		output({
-			found: false,
-			base_phase: normalized,
-			next: `${normalized}.1`,
-			existing: []
-		}, raw, `${normalized}.1`);
-		return;
-	}
+	if (!node_fs.default.existsSync(phasesDirPath)) return cmdOk({
+		found: false,
+		base_phase: normalized,
+		next: `${normalized}.1`,
+		existing: []
+	}, `${normalized}.1`);
 	try {
 		const dirs = listSubDirs(phasesDirPath);
 		const baseExists = dirs.some((d) => d.startsWith(normalized + "-") || d === normalized);
@@ -14630,18 +14571,18 @@ function cmdPhaseNextDecimal(cwd, basePhase, raw) {
 			const lastDecimal = existingDecimals[existingDecimals.length - 1];
 			nextDecimal = `${normalized}.${parseInt(lastDecimal.split(".")[1], 10) + 1}`;
 		}
-		output({
+		return cmdOk({
 			found: baseExists,
 			base_phase: normalized,
 			next: nextDecimal,
 			existing: existingDecimals
-		}, raw, nextDecimal);
+		}, nextDecimal);
 	} catch (e) {
-		error("Failed to calculate next decimal phase: " + e.message);
+		return cmdErr("Failed to calculate next decimal phase: " + e.message);
 	}
 }
-function cmdFindPhase(cwd, phase, raw) {
-	if (!phase) error("phase identifier required");
+function cmdFindPhase(cwd, phase) {
+	if (!phase) return cmdErr("phase identifier required");
 	const phasesDirPath = phasesPath(cwd);
 	const normalized = normalizePhaseName(phase);
 	const notFound = {
@@ -14654,10 +14595,7 @@ function cmdFindPhase(cwd, phase, raw) {
 	};
 	try {
 		const match = listSubDirs(phasesDirPath, true).find((d) => d.startsWith(normalized));
-		if (!match) {
-			output(notFound, raw, "");
-			return;
-		}
+		if (!match) return cmdOk(notFound, "");
 		const dirMatch = match.match(/^(\d+[A-Z]?(?:\.\d+)?)-?(.*)/i);
 		const phaseNumber = dirMatch ? dirMatch[1] : normalized;
 		const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
@@ -14673,13 +14611,13 @@ function cmdFindPhase(cwd, phase, raw) {
 			plans,
 			summaries
 		};
-		output(result, raw, result.directory);
-	} catch {
-		output(notFound, raw, "");
+		return cmdOk(result, result.directory);
+	} catch (e) {
+		return cmdOk(notFound, "");
 	}
 }
-function cmdPhasePlanIndex(cwd, phase, raw) {
-	if (!phase) error("phase required for phase-plan-index");
+function cmdPhasePlanIndex(cwd, phase) {
+	if (!phase) return cmdErr("phase required for phase-plan-index");
 	const phasesDirPath = phasesPath(cwd);
 	const normalized = normalizePhaseName(phase);
 	let phaseDir = null;
@@ -14687,19 +14625,16 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
 		const match = listSubDirs(phasesDirPath, true).find((d) => d.startsWith(normalized));
 		if (match) phaseDir = node_path.default.join(phasesDirPath, match);
 	} catch (e) {
-		debugLog(e);
-	}
-	if (!phaseDir) {
-		output({
-			phase: normalized,
-			error: "Phase not found",
-			plans: [],
-			waves: {},
-			incomplete: [],
-			has_checkpoints: false
-		}, raw);
-		return;
+		debugLog("phase-plan-index-failed", e);
 	}
+	if (!phaseDir) return cmdOk({
+		phase: normalized,
+		error: "Phase not found",
+		plans: [],
+		waves: {},
+		incomplete: [],
+		has_checkpoints: false
+	});
 	const phaseFiles = node_fs.default.readdirSync(phaseDir);
 	const planFiles = phaseFiles.filter(isPlanFile).sort();
 	const summaryFiles = phaseFiles.filter(isSummaryFile);
@@ -14736,62 +14671,62 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
 		if (!waves[waveKey]) waves[waveKey] = [];
 		waves[waveKey].push(id);
 	}
-	output({
+	return cmdOk({
 		phase: normalized,
 		plans,
 		waves,
 		incomplete,
 		has_checkpoints: hasCheckpoints
-	}, raw);
+	});
 }
-function cmdPhaseAdd(cwd, description, raw) {
-	if (!description) error("description required for phase add");
+function cmdPhaseAdd(cwd, description) {
+	if (!description) return cmdErr("description required for phase add");
 	try {
 		const result = phaseAddCore(cwd, description, { includeStubs: false });
-		output({
+		return cmdOk({
 			phase_number: result.phase_number,
 			padded: result.padded,
 			name: result.description,
 			slug: result.slug,
 			directory: result.directory
-		}, raw, result.padded);
+		}, result.padded);
 	} catch (e) {
-		error(e.message);
+		return cmdErr(e.message);
 	}
 }
-function cmdPhaseInsert(cwd, afterPhase, description, raw) {
-	if (!afterPhase || !description) error("after-phase and description required for phase insert");
+function cmdPhaseInsert(cwd, afterPhase, description) {
+	if (!afterPhase || !description) return cmdErr("after-phase and description required for phase insert");
 	try {
 		const result = phaseInsertCore(cwd, afterPhase, description, { includeStubs: false });
-		output({
+		return cmdOk({
 			phase_number: result.phase_number,
 			after_phase: result.after_phase,
 			name: result.description,
 			slug: result.slug,
 			directory: result.directory
-		}, raw, result.phase_number);
+		}, result.phase_number);
 	} catch (e) {
-		error(e.message);
+		return cmdErr(e.message);
 	}
 }
-function cmdPhaseRemove(cwd, targetPhase, options, raw) {
-	if (!targetPhase) error("phase number required for phase remove");
+function cmdPhaseRemove(cwd, targetPhase, options) {
+	if (!targetPhase) return cmdErr("phase number required for phase remove");
 	const rmPath = roadmapPath(cwd);
 	const phasesDirPath = phasesPath(cwd);
 	const force = options.force || false;
-	if (!node_fs.default.existsSync(rmPath)) error("ROADMAP.md not found");
+	if (!node_fs.default.existsSync(rmPath)) return cmdErr("ROADMAP.md not found");
 	const normalized = normalizePhaseName(targetPhase);
 	const isDecimal = targetPhase.includes(".");
 	let targetDir = null;
 	try {
 		targetDir = listSubDirs(phasesDirPath, true).find((d) => d.startsWith(normalized + "-") || d === normalized) || null;
 	} catch (e) {
-		debugLog(e);
+		debugLog("phase-remove-find-target-failed", e);
 	}
 	if (targetDir && !force) {
 		const targetPath = node_path.default.join(phasesDirPath, targetDir);
 		const summaries = node_fs.default.readdirSync(targetPath).filter(isSummaryFile);
-		if (summaries.length > 0) error(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
+		if (summaries.length > 0) return cmdErr(`Phase ${targetPhase} has ${summaries.length} executed plan(s). Use --force to remove anyway.`);
 	}
 	if (targetDir) node_fs.default.rmSync(node_path.default.join(phasesDirPath, targetDir), {
 		recursive: true,
@@ -14837,7 +14772,10 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
 				}
 			}
 		} catch (e) {
-			debugLog(e);
+			debugLog("phase-remove-decimal-rename-failed", {
+				phase: targetPhase,
+				error: errorMsg(e)
+			});
 		}
 	} else {
 		const removedInt = parseInt(normalized, 10);
@@ -14885,7 +14823,10 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
 				}
 			}
 		} catch (e) {
-			debugLog(e);
+			debugLog("phase-remove-int-rename-failed", {
+				phase: targetPhase,
+				error: errorMsg(e)
+			});
 		}
 	}
 	let roadmapContent = node_fs.default.readFileSync(rmPath, "utf-8");
@@ -14929,20 +14870,20 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
 		}
 		node_fs.default.writeFileSync(stPath, stateContent, "utf-8");
 	}
-	output({
+	return cmdOk({
 		removed: targetPhase,
 		directory_deleted: targetDir || null,
 		renamed_directories: renamedDirs,
 		renamed_files: renamedFiles,
 		roadmap_updated: true,
 		state_updated: node_fs.default.existsSync(stPath)
-	}, raw);
+	});
 }
-function cmdPhaseComplete(cwd, phaseNum, raw) {
-	if (!phaseNum) error("phase number required for phase complete");
+function cmdPhaseComplete(cwd, phaseNum) {
+	if (!phaseNum) return cmdErr("phase number required for phase complete");
 	try {
 		const result = phaseCompleteCore(cwd, phaseNum);
-		output({
+		return cmdOk({
 			completed_phase: result.completed_phase,
 			phase_name: result.phase_name,
 			plans_executed: result.plans_executed,
@@ -14952,9 +14893,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
 			date: result.date,
 			roadmap_updated: result.roadmap_updated,
 			state_updated: result.state_updated
-		}, raw);
+		});
 	} catch (e) {
-		error(e.message);
+		return cmdErr(e.message);
 	}
 }
 
@@ -14965,8 +14906,8 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
 *
 * Ported from maxsim/bin/lib/template.cjs
 */
-function cmdTemplateSelect(cwd, planPath, raw) {
-	if (!planPath) error("plan-path required");
+function cmdTemplateSelect(cwd, planPath) {
+	if (!planPath) return cmdErr("plan-path required");
 	try {
 		const fullPath = node_path.default.join(cwd, planPath);
 		const content = node_fs.default.readFileSync(fullPath, "utf-8");
@@ -14986,32 +14927,29 @@ function cmdTemplateSelect(cwd, planPath, raw) {
 			template = "templates/summary-complex.md";
 			type = "complex";
 		}
-		output({
+		return cmdOk({
 			template,
 			type,
 			taskCount,
 			fileCount,
 			hasDecisions
-		}, raw, template);
+		}, template);
 	} catch (thrown) {
-		output({
+		return cmdOk({
 			template: "templates/summary-standard.md",
 			type: "standard",
 			error: thrown.message
-		}, raw, "templates/summary-standard.md");
+		}, "templates/summary-standard.md");
 	}
 }
-function cmdTemplateFill(cwd, templateType, options, raw) {
-	if (!templateType) error("template type required: summary, plan, or verification");
-	if (!options.phase) error("--phase required");
+function cmdTemplateFill(cwd, templateType, options) {
+	if (!templateType) return cmdErr("template type required: summary, plan, or verification");
+	if (!options.phase) return cmdErr("--phase required");
 	const phaseInfo = findPhaseInternal(cwd, options.phase);
-	if (!phaseInfo) {
-		output({
-			error: "Phase not found",
-			phase: options.phase
-		}, raw);
-		return;
-	}
+	if (!phaseInfo) return cmdOk({
+		error: "Phase not found",
+		phase: options.phase
+	});
 	const padded = normalizePhaseName(options.phase);
 	const today = todayISO();
 	const phaseName = options.name || phaseInfo.phase_name || "Unnamed";
@@ -15157,26 +15095,633 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
 			].join("\n");
 			fileName = `${padded}-VERIFICATION.md`;
 			break;
-		default:
-			error(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
-			return;
+		default: return cmdErr(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
 	}
 	const fullContent = `---\n${reconstructFrontmatter(frontmatter)}\n---\n\n${body}\n`;
 	const outPath = node_path.default.join(cwd, phaseInfo.directory, fileName);
-	if (node_fs.default.existsSync(outPath)) {
-		output({
-			error: "File already exists",
-			path: node_path.default.relative(cwd, outPath)
-		}, raw);
-		return;
-	}
+	if (node_fs.default.existsSync(outPath)) return cmdOk({
+		error: "File already exists",
+		path: node_path.default.relative(cwd, outPath)
+	});
 	node_fs.default.writeFileSync(outPath, fullContent, "utf-8");
 	const relPath = node_path.default.relative(cwd, outPath);
-	output({
+	return cmdOk({
 		created: true,
 		path: relPath,
 		template: templateType
-	}, raw, relPath);
+	}, relPath);
+}
+
+//#endregion
+//#region src/core/artefakte.ts
+/**
+* Artefakte — CRUD operations for project-level artefakte files
+*
+* Manages DECISIONS.md, ACCEPTANCE-CRITERIA.md, and NO-GOS.md
+* at both project level (.planning/) and phase level (.planning/phases/<phase>/).
+*/
+const ARTEFAKT_FILES = {
+	"decisions": "DECISIONS.md",
+	"acceptance-criteria": "ACCEPTANCE-CRITERIA.md",
+	"no-gos": "NO-GOS.md"
+};
+function isValidType(type) {
+	return !!type && type in ARTEFAKT_FILES;
+}
+function resolveArtefaktPath(cwd, type, phase) {
+	const filename = ARTEFAKT_FILES[type];
+	if (phase) {
+		const phaseInfo = findPhaseInternal(cwd, phase);
+		if (!phaseInfo?.directory) return null;
+		return node_path.default.join(cwd, phaseInfo.directory, filename);
+	}
+	return planningPath(cwd, filename);
+}
+function getTemplate(type) {
+	const today = todayISO();
+	switch (type) {
+		case "decisions": return `# Decisions\n\n> Architectural and design decisions for this project.\n\n**Created:** ${today}\n\n## Decision Log\n\n| # | Decision | Rationale | Date | Phase |\n|---|----------|-----------|------|-------|\n`;
+		case "acceptance-criteria": return `# Acceptance Criteria\n\n> Conditions that must be met for deliverables to be accepted.\n\n**Created:** ${today}\n\n## Criteria\n\n| # | Criterion | Status | Verified |\n|---|-----------|--------|----------|\n`;
+		case "no-gos": return `# No-Gos\n\n> Things explicitly out of scope or forbidden.\n\n**Created:** ${today}\n\n## Boundaries\n\n- _No entries yet._\n`;
+	}
+}
+function cmdArtefakteRead(cwd, type, phase, raw) {
+	if (!isValidType(type)) return cmdErr(`Invalid artefakt type: ${type}. Available: ${Object.keys(ARTEFAKT_FILES).join(", ")}`);
+	const filePath = resolveArtefaktPath(cwd, type, phase);
+	if (!filePath) return cmdErr(`Phase ${phase} not found`);
+	const content = safeReadFile(filePath);
+	if (content === null) return cmdOk({
+		exists: false,
+		type,
+		phase: phase ?? null,
+		content: null
+	}, raw ? "" : void 0);
+	return cmdOk({
+		exists: true,
+		type,
+		phase: phase ?? null,
+		content
+	}, raw ? content : void 0);
+}
+function cmdArtefakteWrite(cwd, type, content, phase, raw) {
+	if (!isValidType(type)) return cmdErr(`Invalid artefakt type: ${type}. Available: ${Object.keys(ARTEFAKT_FILES).join(", ")}`);
+	const fileContent = content ?? getTemplate(type);
+	const filePath = resolveArtefaktPath(cwd, type, phase);
+	if (!filePath) return cmdErr(`Phase ${phase} not found`);
+	node_fs.default.mkdirSync(node_path.default.dirname(filePath), { recursive: true });
+	node_fs.default.writeFileSync(filePath, fileContent, "utf-8");
+	const relPath = node_path.default.relative(cwd, filePath);
+	return cmdOk({
+		written: true,
+		type,
+		phase: phase ?? null,
+		path: relPath
+	}, raw ? relPath : void 0);
+}
+function cmdArtefakteAppend(cwd, type, entry, phase, raw) {
+	if (!entry) return cmdErr("entry required for artefakte append");
+	if (!isValidType(type)) return cmdErr(`Invalid artefakt type: ${type}. Available: ${Object.keys(ARTEFAKT_FILES).join(", ")}`);
+	const filePath = resolveArtefaktPath(cwd, type, phase);
+	if (!filePath) return cmdErr(`Phase ${phase} not found`);
+	let fileContent = safeReadFile(filePath);
+	if (fileContent === null) fileContent = getTemplate(type);
+	fileContent = fileContent.replace(/^-\s*_No entries yet\._\s*$/m, "");
+	const today = todayISO();
+	let appendLine;
+	if (type === "decisions") appendLine = `| ${(fileContent.match(/^\|\s*\d+/gm) || []).length + 1} | ${entry} | - | ${today} | - |`;
+	else if (type === "acceptance-criteria") appendLine = `| ${(fileContent.match(/^\|\s*\d+/gm) || []).length + 1} | ${entry} | pending | - |`;
+	else appendLine = `- ${entry}`;
+	fileContent = fileContent.trimEnd() + "\n" + appendLine + "\n";
+	node_fs.default.writeFileSync(filePath, fileContent, "utf-8");
+	const relPath = node_path.default.relative(cwd, filePath);
+	return cmdOk({
+		appended: true,
+		type,
+		phase: phase ?? null,
+		entry: appendLine,
+		path: relPath
+	}, raw ? "true" : void 0);
+}
+function cmdArtefakteList(cwd, phase, raw) {
+	const results = [];
+	for (const [type, filename] of Object.entries(ARTEFAKT_FILES)) {
+		let filePath;
+		if (phase) {
+			const phaseInfo = findPhaseInternal(cwd, phase);
+			if (!phaseInfo?.directory) return cmdOk({ error: `Phase ${phase} not found` });
+			filePath = node_path.default.join(cwd, phaseInfo.directory, filename);
+		} else filePath = planningPath(cwd, filename);
+		results.push({
+			type,
+			exists: node_fs.default.existsSync(filePath),
+			path: node_path.default.relative(cwd, filePath)
+		});
+	}
+	return cmdOk({
+		phase: phase ?? null,
+		artefakte: results
+	});
+}
+
+//#endregion
+//#region src/core/context-loader.ts
+/**
+* Context Loader — Intelligent file selection for workflow context assembly
+*
+* Selects relevant planning files based on the current task/phase domain,
+* preventing context overload by loading only what matters.
+*/
+function fileEntry(cwd, relPath, role) {
+	const fullPath = node_path.default.join(cwd, relPath);
+	try {
+		return {
+			path: relPath,
+			role,
+			size: node_fs.default.statSync(fullPath).size
+		};
+	} catch {
+		return null;
+	}
+}
+function addIfExists(files, cwd, relPath, role) {
+	const entry = fileEntry(cwd, relPath, role);
+	if (entry) files.push(entry);
+}
+function loadProjectContext(cwd) {
+	const files = [];
+	addIfExists(files, cwd, ".planning/PROJECT.md", "project-vision");
+	addIfExists(files, cwd, ".planning/REQUIREMENTS.md", "requirements");
+	addIfExists(files, cwd, ".planning/STATE.md", "state");
+	addIfExists(files, cwd, ".planning/config.json", "config");
+	return files;
+}
+function loadRoadmapContext(cwd) {
+	const files = [];
+	addIfExists(files, cwd, ".planning/ROADMAP.md", "roadmap");
+	return files;
+}
+function loadPhaseContext(cwd, phase) {
+	const files = [];
+	const phaseInfo = findPhaseInternal(cwd, phase);
+	if (!phaseInfo?.directory) return files;
+	const phaseDir = phaseInfo.directory;
+	try {
+		const phaseFiles = node_fs.default.readdirSync(node_path.default.join(cwd, phaseDir));
+		for (const f of phaseFiles) {
+			const relPath = node_path.default.join(phaseDir, f);
+			if (f.endsWith("-CONTEXT.md") || f === "CONTEXT.md") addIfExists(files, cwd, relPath, "phase-context");
+			else if (f.endsWith("-RESEARCH.md") || f === "RESEARCH.md") addIfExists(files, cwd, relPath, "phase-research");
+			else if (f.endsWith("-PLAN.md")) addIfExists(files, cwd, relPath, "phase-plan");
+			else if (f.endsWith("-SUMMARY.md")) addIfExists(files, cwd, relPath, "phase-summary");
+			else if (f.endsWith("-VERIFICATION.md") || f === "VERIFICATION.md") addIfExists(files, cwd, relPath, "phase-verification");
+		}
+	} catch (e) {
+		debugLog("context-loader-phase-files-failed", e);
+	}
+	return files;
+}
+function loadArtefakteContext(cwd, phase) {
+	const files = [];
+	for (const filename of [
+		"DECISIONS.md",
+		"ACCEPTANCE-CRITERIA.md",
+		"NO-GOS.md"
+	]) {
+		if (phase) {
+			const phaseInfo = findPhaseInternal(cwd, phase);
+			if (phaseInfo?.directory) addIfExists(files, cwd, node_path.default.join(phaseInfo.directory, filename), `artefakt-${filename.toLowerCase()}`);
+		}
+		addIfExists(files, cwd, `.planning/${filename}`, `artefakt-${filename.toLowerCase()}`);
+	}
+	return files;
+}
+function loadHistoryContext(cwd, currentPhase) {
+	const files = [];
+	const pd = phasesPath(cwd);
+	try {
+		const dirs = listSubDirs(pd, true);
+		for (const dir of dirs) {
+			if (currentPhase) {
+				if (dir.match(/^(\d+[A-Z]?(?:\.\d+)?)/i)?.[1] === currentPhase) continue;
+			}
+			const dirPath = node_path.default.join(pd, dir);
+			const summaries = node_fs.default.readdirSync(dirPath).filter((f) => isSummaryFile(f));
+			for (const s of summaries) addIfExists(files, cwd, node_path.default.join(".planning", "phases", dir, s), "history-summary");
+		}
+	} catch (e) {
+		debugLog("context-loader-history-failed", e);
+	}
+	return files;
+}
+function cmdContextLoad(cwd, phase, topic, includeHistory) {
+	const allFiles = [];
+	allFiles.push(...loadProjectContext(cwd));
+	allFiles.push(...loadRoadmapContext(cwd));
+	allFiles.push(...loadArtefakteContext(cwd, phase));
+	if (phase) allFiles.push(...loadPhaseContext(cwd, phase));
+	if (includeHistory) allFiles.push(...loadHistoryContext(cwd, phase));
+	const seen = /* @__PURE__ */ new Set();
+	const deduped = allFiles.filter((f) => {
+		if (seen.has(f.path)) return false;
+		seen.add(f.path);
+		return true;
+	});
+	return cmdOk({
+		files: deduped,
+		total_size: deduped.reduce((sum, f) => sum + f.size, 0),
+		phase: phase ?? null,
+		topic: topic ?? null
+	});
+}
+
+//#endregion
+//#region src/core/skills.ts
+/**
+* Skills — List, install, and update skill templates
+*
+* Skills are installed to `.claude/skills/<name>/SKILL.md`.
+* Source templates live in `templates/skills/<name>/SKILL.md`.
+*/
+/**
+* Resolve the installed skills directory for the current project.
+* Skills live at `.claude/skills/` relative to cwd.
+*/
+function skillsDir(cwd) {
+	return node_path.default.join(cwd, ".claude", "skills");
+}
+/**
+* Resolve the templates source directory for skills.
+* At runtime (from dist/cli.cjs), templates are bundled at dist/assets/templates/skills/.
+*/
+function skillsTemplateDir() {
+	return node_path.default.resolve(__dirname, "assets", "templates", "skills");
+}
+/**
+* Read a single skill's metadata from its SKILL.md frontmatter.
+*/
+function readSkillInfo(skillDir, dirName) {
+	const content = safeReadFile(node_path.default.join(skillDir, "SKILL.md"));
+	if (!content) return null;
+	const fm = extractFrontmatter(content);
+	return {
+		name: fm.name ?? dirName,
+		description: fm.description ?? "",
+		directory: dirName
+	};
+}
+/**
+* List all installed skills from `.claude/skills/`.
+*/
+function cmdSkillList(cwd, raw) {
+	const dir = skillsDir(cwd);
+	if (!node_fs.default.existsSync(dir)) output({
+		skills: [],
+		count: 0
+	}, raw, "No skills installed.");
+	const entries = node_fs.default.readdirSync(dir, { withFileTypes: true });
+	const skills = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const info = readSkillInfo(node_path.default.join(dir, entry.name), entry.name);
+		if (info) skills.push(info);
+	}
+	output({
+		skills,
+		count: skills.length
+	}, raw, skills.map((s) => `${s.name}: ${s.description}`).join("\n"));
+}
+/**
+* Install a specific skill from the templates directory.
+*/
+function cmdSkillInstall(cwd, skillName, raw) {
+	if (!skillName) error("skill name required. Usage: skill-install <name>");
+	const srcFile = node_path.default.join(skillsTemplateDir(), skillName, "SKILL.md");
+	if (!node_fs.default.existsSync(srcFile)) error(`Skill "${skillName}" not found in templates. Available: ${listAvailableTemplates().join(", ")}`);
+	const destDir = node_path.default.join(skillsDir(cwd), skillName);
+	const destFile = node_path.default.join(destDir, "SKILL.md");
+	node_fs.default.mkdirSync(destDir, { recursive: true });
+	node_fs.default.copyFileSync(srcFile, destFile);
+	output({
+		installed: true,
+		skill: skillName,
+		path: node_path.default.relative(cwd, destFile)
+	}, raw, `Installed skill: ${skillName}`);
+}
+/**
+* Update one or all installed skills from the templates source.
+*/
+function cmdSkillUpdate(cwd, skillName, raw) {
+	const dir = skillsDir(cwd);
+	const templateDir = skillsTemplateDir();
+	if (skillName) {
+		const srcFile = node_path.default.join(templateDir, skillName, "SKILL.md");
+		if (!node_fs.default.existsSync(srcFile)) error(`Skill template "${skillName}" not found.`);
+		const destDir = node_path.default.join(dir, skillName);
+		if (!node_fs.default.existsSync(destDir)) error(`Skill "${skillName}" is not installed. Use skill-install first.`);
+		const destFile = node_path.default.join(destDir, "SKILL.md");
+		node_fs.default.copyFileSync(srcFile, destFile);
+		output({
+			updated: [skillName],
+			skipped: [],
+			not_found: []
+		}, raw, `Updated skill: ${skillName}`);
+		return;
+	}
+	if (!node_fs.default.existsSync(dir)) {
+		output({
+			updated: [],
+			skipped: [],
+			not_found: []
+		}, raw, "No skills installed.");
+		return;
+	}
+	const entries = node_fs.default.readdirSync(dir, { withFileTypes: true });
+	const updated = [];
+	const skipped = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const name = entry.name;
+		const srcFile = node_path.default.join(templateDir, name, "SKILL.md");
+		if (!node_fs.default.existsSync(srcFile)) {
+			skipped.push(name);
+			continue;
+		}
+		const destFile = node_path.default.join(dir, name, "SKILL.md");
+		node_fs.default.copyFileSync(srcFile, destFile);
+		updated.push(name);
+	}
+	const summary = updated.length > 0 ? `Updated ${updated.length} skill(s): ${updated.join(", ")}` : "No skills updated.";
+	output({
+		updated,
+		skipped
+	}, raw, summary);
+}
+function listAvailableTemplates() {
+	const dir = skillsTemplateDir();
+	if (!node_fs.default.existsSync(dir)) return [];
+	return node_fs.default.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+//#endregion
+//#region src/core/dashboard-launcher.ts
+/**
+* Dashboard Launcher — Shared dashboard lifecycle utilities
+*
+* Used by both cli.ts (tool-router) and install.ts (npx entry point).
+*/
+const DEFAULT_PORT = 3333;
+const PORT_RANGE_END = 3343;
+const HEALTH_TIMEOUT_MS = 1e4;
+/**
+* Check if a dashboard health endpoint is responding on the given port.
+*/
+async function checkHealth(port, timeoutMs = HEALTH_TIMEOUT_MS) {
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const res = await fetch(`http://localhost:${port}/api/health`, { signal: controller.signal });
+		clearTimeout(timer);
+		if (res.ok) return (await res.json()).status === "ok";
+		return false;
+	} catch (e) {
+		debugLog("health-check-failed", {
+			port,
+			error: errorMsg(e)
+		});
+		return false;
+	}
+}
+/**
+* Scan the port range for a running dashboard instance.
+* Returns the port number if found, null otherwise.
+*/
+async function findRunningDashboard(timeoutMs = HEALTH_TIMEOUT_MS) {
+	for (let port = DEFAULT_PORT; port <= PORT_RANGE_END; port++) if (await checkHealth(port, timeoutMs)) return port;
+	return null;
+}
+/**
+* Kill processes listening on the given port. Cross-platform.
+*/
+function killProcessOnPort(port) {
+	if (process.platform === "win32") try {
+		const lines = (0, node_child_process.execSync)(`netstat -ano | findstr :${port} | findstr LISTENING`, { encoding: "utf-8" }).trim().split("\n");
+		const pids = /* @__PURE__ */ new Set();
+		for (const line of lines) {
+			const parts = line.trim().split(/\s+/);
+			const pid = parts[parts.length - 1];
+			if (pid && pid !== "0") pids.add(pid);
+		}
+		for (const pid of pids) try {
+			(0, node_child_process.execSync)(`taskkill /PID ${pid} /F`, { stdio: "ignore" });
+		} catch (e) {
+			debugLog("kill-process-on-port-taskkill-failed", {
+				port,
+				pid,
+				error: errorMsg(e)
+			});
+		}
+	} catch (e) {
+		debugLog("kill-process-on-port-netstat-failed", {
+			port,
+			platform: "win32",
+			error: errorMsg(e)
+		});
+	}
+	else try {
+		(0, node_child_process.execSync)(`lsof -i :${port} -t | xargs kill -SIGTERM 2>/dev/null`, { stdio: "ignore" });
+	} catch (e) {
+		debugLog("kill-process-on-port-lsof-failed", {
+			port,
+			platform: process.platform,
+			error: errorMsg(e)
+		});
+	}
+}
+/**
+* Resolve the dashboard server entry point path.
+* Tries: local project install, global install, @maxsim/dashboard package, monorepo walk.
+*/
+function resolveDashboardServer() {
+	const localDashboard = node_path.default.join(process.cwd(), ".claude", "dashboard", "server.js");
+	if (node_fs.default.existsSync(localDashboard)) return localDashboard;
+	const globalDashboard = node_path.default.join(node_os.default.homedir(), ".claude", "dashboard", "server.js");
+	if (node_fs.default.existsSync(globalDashboard)) return globalDashboard;
+	try {
+		const pkgPath = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href).resolve("@maxsim/dashboard/package.json");
+		const pkgDir = node_path.default.dirname(pkgPath);
+		const serverJs = node_path.default.join(pkgDir, "server.js");
+		if (node_fs.default.existsSync(serverJs)) return serverJs;
+		const serverTs = node_path.default.join(pkgDir, "server.ts");
+		if (node_fs.default.existsSync(serverTs)) return serverTs;
+	} catch (e) {
+		debugLog("resolve-dashboard-strategy1-failed", {
+			strategy: "@maxsim/dashboard package",
+			error: errorMsg(e)
+		});
+	}
+	try {
+		let dir = node_path.default.dirname(new URL(require("url").pathToFileURL(__filename).href).pathname);
+		if (process.platform === "win32" && dir.startsWith("/")) dir = dir.slice(1);
+		for (let i = 0; i < 5; i++) {
+			const candidate = node_path.default.join(dir, "packages", "dashboard", "server.ts");
+			if (node_fs.default.existsSync(candidate)) return candidate;
+			const candidateJs = node_path.default.join(dir, "packages", "dashboard", "server.js");
+			if (node_fs.default.existsSync(candidateJs)) return candidateJs;
+			dir = node_path.default.dirname(dir);
+		}
+	} catch (e) {
+		debugLog("resolve-dashboard-strategy2-failed", {
+			strategy: "monorepo walk",
+			error: errorMsg(e)
+		});
+	}
+	return null;
+}
+/**
+* Ensure node-pty is installed in the dashboard directory.
+* Returns true if node-pty is available after this call.
+*/
+function ensureNodePty(serverDir) {
+	const ptyModulePath = node_path.default.join(serverDir, "node_modules", "node-pty");
+	if (node_fs.default.existsSync(ptyModulePath)) return true;
+	const dashPkgPath = node_path.default.join(serverDir, "package.json");
+	if (!node_fs.default.existsSync(dashPkgPath)) node_fs.default.writeFileSync(dashPkgPath, "{\"private\":true}\n");
+	try {
+		(0, node_child_process.execSync)("npm install node-pty --save-optional --no-audit --no-fund --loglevel=error", {
+			cwd: serverDir,
+			stdio: "inherit",
+			timeout: 12e4
+		});
+		return true;
+	} catch (e) {
+		debugLog("ensure-node-pty-install-failed", {
+			serverDir,
+			error: errorMsg(e)
+		});
+		return false;
+	}
+}
+/**
+* Read dashboard.json config from the parent directory of the dashboard dir.
+*/
+function readDashboardConfig(serverPath) {
+	const dashboardDir = node_path.default.dirname(serverPath);
+	const dashboardConfigPath = node_path.default.join(node_path.default.dirname(dashboardDir), "dashboard.json");
+	let projectCwd = process.cwd();
+	let networkMode = false;
+	if (node_fs.default.existsSync(dashboardConfigPath)) try {
+		const config = JSON.parse(node_fs.default.readFileSync(dashboardConfigPath, "utf8"));
+		if (config.projectCwd) projectCwd = config.projectCwd;
+		networkMode = config.networkMode ?? false;
+	} catch (e) {
+		debugLog("read-dashboard-config-failed", {
+			path: dashboardConfigPath,
+			error: errorMsg(e)
+		});
+	}
+	return {
+		projectCwd,
+		networkMode
+	};
+}
+/**
+* Spawn the dashboard server as a detached background process.
+* Returns the child process PID, or null if spawn failed.
+*/
+function spawnDashboard(options) {
+	const { serverPath, projectCwd, networkMode = false, nodeEnv = "production" } = options;
+	const serverDir = node_path.default.dirname(serverPath);
+	const isTsFile = serverPath.endsWith(".ts");
+	const child = (0, node_child_process.spawn)("node", isTsFile ? [
+		"--import",
+		"tsx",
+		serverPath
+	] : [serverPath], {
+		cwd: serverDir,
+		detached: true,
+		stdio: "ignore",
+		env: {
+			...process.env,
+			MAXSIM_PROJECT_CWD: projectCwd,
+			MAXSIM_NETWORK_MODE: networkMode ? "1" : "0",
+			NODE_ENV: isTsFile ? "development" : nodeEnv
+		},
+		...process.platform === "win32" ? { shell: true } : {}
+	});
+	child.unref();
+	return child.pid ?? null;
+}
+/**
+* Poll the port range until a dashboard health endpoint responds.
+* Returns the URL if found within the timeout, null otherwise.
+*/
+async function waitForDashboard(pollIntervalMs = 500, pollTimeoutMs = 2e4, healthTimeoutMs = 1e3) {
+	const deadline = Date.now() + pollTimeoutMs;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, pollIntervalMs));
+		for (let p = DEFAULT_PORT; p <= PORT_RANGE_END; p++) if (await checkHealth(p, healthTimeoutMs)) return `http://localhost:${p}`;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/core/start.ts
+/**
+* Start — Orchestrates Dashboard launch + browser open
+*
+* Provides a unified `maxsimcli start` entry point that:
+* 1. Checks for a running dashboard
+* 2. Starts the dashboard if needed
+* 3. Opens the browser
+* 4. Reports status
+*/
+function openBrowser(url) {
+	(0, node_child_process.exec)(process.platform === "win32" ? `start "" "${url}"` : process.platform === "darwin" ? `open "${url}"` : `xdg-open "${url}"`, (err) => {
+		if (err) debugLog("open-browser-failed", err);
+	});
+}
+async function cmdStart(cwd, options) {
+	const existingPort = await findRunningDashboard();
+	if (existingPort) {
+		const url = `http://localhost:${existingPort}`;
+		if (!options.noBrowser) openBrowser(url);
+		return cmdOk({
+			started: true,
+			url,
+			already_running: true,
+			port: existingPort
+		}, url);
+	}
+	const serverPath = resolveDashboardServer();
+	if (!serverPath) return cmdErr("Dashboard server not found. Run `npx maxsimcli` to install first.");
+	const serverDir = node_path.default.dirname(serverPath);
+	const dashConfig = readDashboardConfig(serverPath);
+	ensureNodePty(serverDir);
+	const pid = spawnDashboard({
+		serverPath,
+		projectCwd: dashConfig.projectCwd,
+		networkMode: options.networkMode
+	});
+	if (!pid) return cmdErr("Failed to spawn dashboard process.");
+	const url = await waitForDashboard();
+	if (url) {
+		if (!options.noBrowser) openBrowser(url);
+		return cmdOk({
+			started: true,
+			url,
+			already_running: false,
+			pid
+		}, url);
+	} else {
+		const fallbackUrl = `http://localhost:${DEFAULT_PORT}`;
+		return cmdOk({
+			started: true,
+			url: fallbackUrl,
+			already_running: false,
+			pid,
+			warning: "Dashboard spawned but health check timed out. It may still be starting."
+		}, fallbackUrl);
+	}
 }
 
 //#endregion
@@ -15209,13 +15754,47 @@ function scanPhaseArtifacts(cwd, phaseDirectory) {
 	}
 	return result;
 }
-function cmdInitExecutePhase(cwd, phase, raw) {
-	if (!phase) error("phase required for init execute-phase");
+const CODE_EXTENSIONS = new Set([
+	".ts",
+	".js",
+	".py",
+	".go",
+	".rs",
+	".swift",
+	".java"
+]);
+const EXCLUDED_DIRS = new Set(["node_modules", ".git"]);
+function findCodeFiles(dir, maxDepth = 3, limit = 5) {
+	const results = [];
+	function walk(currentDir, depth) {
+		if (depth > maxDepth || results.length >= limit) return;
+		let entries;
+		try {
+			entries = node_fs.default.readdirSync(currentDir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (results.length >= limit) return;
+			if (EXCLUDED_DIRS.has(entry.name)) continue;
+			const fullPath = node_path.default.join(currentDir, entry.name);
+			if (entry.isDirectory()) walk(fullPath, depth + 1);
+			else if (entry.isFile()) {
+				const ext = node_path.default.extname(entry.name).toLowerCase();
+				if (CODE_EXTENSIONS.has(ext)) results.push(fullPath);
+			}
+		}
+	}
+	walk(dir, 1);
+	return results;
+}
+function cmdInitExecutePhase(cwd, phase) {
+	if (!phase) return cmdErr("phase required for init execute-phase");
 	const config = loadConfig(cwd);
 	const phaseInfo = findPhaseInternal(cwd, phase);
 	const milestone = getMilestoneInfo(cwd);
 	const phase_req_ids = extractReqIds(cwd, phase);
-	output({
+	return cmdOk({
 		executor_model: resolveModelInternal(cwd, "maxsim-executor"),
 		verifier_model: resolveModelInternal(cwd, "maxsim-verifier"),
 		commit_docs: config.commit_docs,
@@ -15245,10 +15824,10 @@ function cmdInitExecutePhase(cwd, phase, raw) {
 		state_path: ".planning/STATE.md",
 		roadmap_path: ".planning/ROADMAP.md",
 		config_path: ".planning/config.json"
-	}, raw);
+	});
 }
-function cmdInitPlanPhase(cwd, phase, raw) {
-	if (!phase) error("phase required for init plan-phase");
+function cmdInitPlanPhase(cwd, phase) {
+	if (!phase) return cmdErr("phase required for init plan-phase");
 	const config = loadConfig(cwd);
 	const phaseInfo = findPhaseInternal(cwd, phase);
 	const phase_req_ids = extractReqIds(cwd, phase);
@@ -15258,7 +15837,6 @@ function cmdInitPlanPhase(cwd, phase, raw) {
 		checker_model: resolveModelInternal(cwd, "maxsim-plan-checker"),
 		research_enabled: config.research,
 		plan_checker_enabled: config.plan_checker,
-		nyquist_validation_enabled: false,
 		commit_docs: config.commit_docs,
 		phase_found: !!phaseInfo,
 		phase_dir: phaseInfo?.directory ?? null,
@@ -15284,30 +15862,16 @@ function cmdInitPlanPhase(cwd, phase, raw) {
 		if (artifacts.verification_path) result.verification_path = artifacts.verification_path;
 		if (artifacts.uat_path) result.uat_path = artifacts.uat_path;
 	}
-	output(result, raw);
+	return cmdOk(result);
 }
-function cmdInitNewProject(cwd, raw) {
+function cmdInitNewProject(cwd) {
 	const config = loadConfig(cwd);
 	const homedir = node_os.default.homedir();
 	const braveKeyFile = node_path.default.join(homedir, ".maxsim", "brave_api_key");
 	const hasBraveSearch = !!(process.env.BRAVE_API_KEY || node_fs.default.existsSync(braveKeyFile));
-	let hasCode = false;
-	let hasPackageFile = false;
-	try {
-		hasCode = (0, node_child_process.execSync)("find . -maxdepth 3 \\( -name \"*.ts\" -o -name \"*.js\" -o -name \"*.py\" -o -name \"*.go\" -o -name \"*.rs\" -o -name \"*.swift\" -o -name \"*.java\" \\) 2>/dev/null | grep -v node_modules | grep -v .git | head -5", {
-			cwd,
-			encoding: "utf-8",
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			]
-		}).trim().length > 0;
-	} catch (e) {
-		debugLog(e);
-	}
-	hasPackageFile = pathExistsInternal(cwd, "package.json") || pathExistsInternal(cwd, "requirements.txt") || pathExistsInternal(cwd, "Cargo.toml") || pathExistsInternal(cwd, "go.mod") || pathExistsInternal(cwd, "Package.swift");
-	output({
+	const hasCode = findCodeFiles(cwd).length > 0;
+	const hasPackageFile = pathExistsInternal(cwd, "package.json") || pathExistsInternal(cwd, "requirements.txt") || pathExistsInternal(cwd, "Cargo.toml") || pathExistsInternal(cwd, "go.mod") || pathExistsInternal(cwd, "Package.swift");
+	return cmdOk({
 		researcher_model: resolveModelInternal(cwd, "maxsim-project-researcher"),
 		synthesizer_model: resolveModelInternal(cwd, "maxsim-research-synthesizer"),
 		roadmapper_model: resolveModelInternal(cwd, "maxsim-roadmapper"),
@@ -15322,12 +15886,12 @@ function cmdInitNewProject(cwd, raw) {
 		has_git: pathExistsInternal(cwd, ".git"),
 		brave_search_available: hasBraveSearch,
 		project_path: ".planning/PROJECT.md"
-	}, raw);
+	});
 }
-function cmdInitNewMilestone(cwd, raw) {
+function cmdInitNewMilestone(cwd) {
 	const config = loadConfig(cwd);
 	const milestone = getMilestoneInfo(cwd);
-	output({
+	return cmdOk({
 		researcher_model: resolveModelInternal(cwd, "maxsim-project-researcher"),
 		synthesizer_model: resolveModelInternal(cwd, "maxsim-research-synthesizer"),
 		roadmapper_model: resolveModelInternal(cwd, "maxsim-roadmapper"),
@@ -15341,9 +15905,9 @@ function cmdInitNewMilestone(cwd, raw) {
 		project_path: ".planning/PROJECT.md",
 		roadmap_path: ".planning/ROADMAP.md",
 		state_path: ".planning/STATE.md"
-	}, raw);
+	});
 }
-function cmdInitQuick(cwd, description, raw) {
+function cmdInitQuick(cwd, description) {
 	const config = loadConfig(cwd);
 	const now = /* @__PURE__ */ new Date();
 	const slug = description ? generateSlugInternal(description)?.substring(0, 40) ?? null : null;
@@ -15355,7 +15919,7 @@ function cmdInitQuick(cwd, description, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		planner_model: resolveModelInternal(cwd, "maxsim-planner"),
 		executor_model: resolveModelInternal(cwd, "maxsim-executor"),
 		checker_model: resolveModelInternal(cwd, "maxsim-plan-checker"),
@@ -15370,9 +15934,9 @@ function cmdInitQuick(cwd, description, raw) {
 		task_dir: slug ? `.planning/quick/${nextNum}-${slug}` : null,
 		roadmap_exists: pathExistsInternal(cwd, ".planning/ROADMAP.md"),
 		planning_exists: pathExistsInternal(cwd, ".planning")
-	}, raw);
+	});
 }
-function cmdInitResume(cwd, raw) {
+function cmdInitResume(cwd) {
 	const config = loadConfig(cwd);
 	let interruptedAgentId = null;
 	try {
@@ -15380,7 +15944,7 @@ function cmdInitResume(cwd, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		state_exists: pathExistsInternal(cwd, ".planning/STATE.md"),
 		roadmap_exists: pathExistsInternal(cwd, ".planning/ROADMAP.md"),
 		project_exists: pathExistsInternal(cwd, ".planning/PROJECT.md"),
@@ -15391,13 +15955,13 @@ function cmdInitResume(cwd, raw) {
 		has_interrupted_agent: !!interruptedAgentId,
 		interrupted_agent_id: interruptedAgentId,
 		commit_docs: config.commit_docs
-	}, raw);
+	});
 }
-function cmdInitVerifyWork(cwd, phase, raw) {
-	if (!phase) error("phase required for init verify-work");
+function cmdInitVerifyWork(cwd, phase) {
+	if (!phase) return cmdErr("phase required for init verify-work");
 	const config = loadConfig(cwd);
 	const phaseInfo = findPhaseInternal(cwd, phase);
-	output({
+	return cmdOk({
 		planner_model: resolveModelInternal(cwd, "maxsim-planner"),
 		checker_model: resolveModelInternal(cwd, "maxsim-plan-checker"),
 		commit_docs: config.commit_docs,
@@ -15406,9 +15970,9 @@ function cmdInitVerifyWork(cwd, phase, raw) {
 		phase_number: phaseInfo?.phase_number ?? null,
 		phase_name: phaseInfo?.phase_name ?? null,
 		has_verification: phaseInfo?.has_verification ?? false
-	}, raw);
+	});
 }
-function cmdInitPhaseOp(cwd, phase, raw) {
+function cmdInitPhaseOp(cwd, phase) {
 	const config = loadConfig(cwd);
 	let phaseInfo = findPhaseInternal(cwd, phase ?? "");
 	if (!phaseInfo) {
@@ -15457,9 +16021,9 @@ function cmdInitPhaseOp(cwd, phase, raw) {
 		if (artifacts.verification_path) result.verification_path = artifacts.verification_path;
 		if (artifacts.uat_path) result.uat_path = artifacts.uat_path;
 	}
-	output(result, raw);
+	return cmdOk(result);
 }
-function cmdInitTodos(cwd, area, raw) {
+function cmdInitTodos(cwd, area) {
 	const config = loadConfig(cwd);
 	const now = /* @__PURE__ */ new Date();
 	const pendingDir = planningPath(cwd, "todos", "pending");
@@ -15488,7 +16052,7 @@ function cmdInitTodos(cwd, area, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		commit_docs: config.commit_docs,
 		date: todayISO(),
 		timestamp: now.toISOString(),
@@ -15500,9 +16064,9 @@ function cmdInitTodos(cwd, area, raw) {
 		planning_exists: pathExistsInternal(cwd, ".planning"),
 		todos_dir_exists: pathExistsInternal(cwd, ".planning/todos"),
 		pending_dir_exists: pathExistsInternal(cwd, ".planning/todos/pending")
-	}, raw);
+	});
 }
-function cmdInitMilestoneOp(cwd, raw) {
+function cmdInitMilestoneOp(cwd) {
 	const config = loadConfig(cwd);
 	const milestone = getMilestoneInfo(cwd);
 	let phaseCount = 0;
@@ -15526,7 +16090,7 @@ function cmdInitMilestoneOp(cwd, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		commit_docs: config.commit_docs,
 		milestone_version: milestone.version,
 		milestone_name: milestone.name,
@@ -15541,9 +16105,9 @@ function cmdInitMilestoneOp(cwd, raw) {
 		state_exists: pathExistsInternal(cwd, ".planning/STATE.md"),
 		archive_exists: pathExistsInternal(cwd, ".planning/archive"),
 		phases_dir_exists: pathExistsInternal(cwd, ".planning/phases")
-	}, raw);
+	});
 }
-function cmdInitMapCodebase(cwd, raw) {
+function cmdInitMapCodebase(cwd) {
 	const config = loadConfig(cwd);
 	const codebaseDir = planningPath(cwd, "codebase");
 	let existingMaps = [];
@@ -15552,7 +16116,7 @@ function cmdInitMapCodebase(cwd, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		mapper_model: resolveModelInternal(cwd, "maxsim-codebase-mapper"),
 		commit_docs: config.commit_docs,
 		search_gitignored: config.search_gitignored,
@@ -15562,29 +16126,15 @@ function cmdInitMapCodebase(cwd, raw) {
 		has_maps: existingMaps.length > 0,
 		planning_exists: pathExistsInternal(cwd, ".planning"),
 		codebase_dir_exists: pathExistsInternal(cwd, ".planning/codebase")
-	}, raw);
+	});
 }
-function cmdInitExisting(cwd, raw) {
+function cmdInitExisting(cwd) {
 	const config = loadConfig(cwd);
 	const homedir = node_os.default.homedir();
 	const braveKeyFile = node_path.default.join(homedir, ".maxsim", "brave_api_key");
 	const hasBraveSearch = !!(process.env.BRAVE_API_KEY || node_fs.default.existsSync(braveKeyFile));
-	let hasCode = false;
-	let hasPackageFile = false;
-	try {
-		hasCode = (0, node_child_process.execSync)("find . -maxdepth 3 \\( -name \"*.ts\" -o -name \"*.js\" -o -name \"*.py\" -o -name \"*.go\" -o -name \"*.rs\" -o -name \"*.swift\" -o -name \"*.java\" \\) 2>/dev/null | grep -v node_modules | grep -v .git | head -5", {
-			cwd,
-			encoding: "utf-8",
-			stdio: [
-				"pipe",
-				"pipe",
-				"pipe"
-			]
-		}).trim().length > 0;
-	} catch (e) {
-		debugLog(e);
-	}
-	hasPackageFile = pathExistsInternal(cwd, "package.json") || pathExistsInternal(cwd, "requirements.txt") || pathExistsInternal(cwd, "Cargo.toml") || pathExistsInternal(cwd, "go.mod") || pathExistsInternal(cwd, "Package.swift");
+	const hasCode = findCodeFiles(cwd).length > 0;
+	const hasPackageFile = pathExistsInternal(cwd, "package.json") || pathExistsInternal(cwd, "requirements.txt") || pathExistsInternal(cwd, "Cargo.toml") || pathExistsInternal(cwd, "go.mod") || pathExistsInternal(cwd, "Package.swift");
 	let planningFiles = [];
 	try {
 		const planDir = planningPath(cwd);
@@ -15592,7 +16142,7 @@ function cmdInitExisting(cwd, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		researcher_model: resolveModelInternal(cwd, "maxsim-project-researcher"),
 		synthesizer_model: resolveModelInternal(cwd, "maxsim-research-synthesizer"),
 		roadmapper_model: resolveModelInternal(cwd, "maxsim-roadmapper"),
@@ -15612,9 +16162,9 @@ function cmdInitExisting(cwd, raw) {
 		parallelization: config.parallelization,
 		project_path: ".planning/PROJECT.md",
 		codebase_dir: ".planning/codebase"
-	}, raw);
+	});
 }
-function cmdInitProgress(cwd, raw) {
+function cmdInitProgress(cwd) {
 	const config = loadConfig(cwd);
 	const milestone = getMilestoneInfo(cwd);
 	const progressPhasesDir = phasesPath(cwd);
@@ -15629,22 +16179,22 @@ function cmdInitProgress(cwd, raw) {
 			const phaseName = match && match[2] ? match[2] : null;
 			const phaseDirPath = node_path.default.join(progressPhasesDir, dir);
 			const phaseFiles = node_fs.default.readdirSync(phaseDirPath);
-			const plans = phaseFiles.filter((f) => isPlanFile(f));
+			const plansList = phaseFiles.filter((f) => isPlanFile(f));
 			const summaries = phaseFiles.filter((f) => isSummaryFile(f));
 			const hasResearch = phaseFiles.some((f) => f.endsWith("-RESEARCH.md") || f === "RESEARCH.md");
-			const status = summaries.length >= plans.length && plans.length > 0 ? "complete" : plans.length > 0 ? "in_progress" : hasResearch ? "researched" : "pending";
-			const phaseInfo = {
+			const status = summaries.length >= plansList.length && plansList.length > 0 ? "complete" : plansList.length > 0 ? "in_progress" : hasResearch ? "researched" : "pending";
+			const phaseInfoItem = {
 				number: phaseNumber,
 				name: phaseName,
 				directory: node_path.default.join(".planning", "phases", dir),
 				status,
-				plan_count: plans.length,
+				plan_count: plansList.length,
 				summary_count: summaries.length,
 				has_research: hasResearch
 			};
-			phases.push(phaseInfo);
-			if (!currentPhase && (status === "in_progress" || status === "researched")) currentPhase = phaseInfo;
-			if (!nextPhase && status === "pending") nextPhase = phaseInfo;
+			phases.push(phaseInfoItem);
+			if (!currentPhase && (status === "in_progress" || status === "researched")) currentPhase = phaseInfoItem;
+			if (!nextPhase && status === "pending") nextPhase = phaseInfoItem;
 		}
 	} catch (e) {
 		debugLog(e);
@@ -15656,7 +16206,7 @@ function cmdInitProgress(cwd, raw) {
 	} catch (e) {
 		debugLog(e);
 	}
-	output({
+	return cmdOk({
 		executor_model: resolveModelInternal(cwd, "maxsim-executor"),
 		planner_model: resolveModelInternal(cwd, "maxsim-planner"),
 		commit_docs: config.commit_docs,
@@ -15677,7 +16227,7 @@ function cmdInitProgress(cwd, raw) {
 		roadmap_path: ".planning/ROADMAP.md",
 		project_path: ".planning/PROJECT.md",
 		config_path: ".planning/config.json"
-	}, raw);
+	});
 }
 
 //#endregion
@@ -15705,7 +16255,12 @@ function getFlags(args, ...flags) {
 function hasFlag(args, flag) {
 	return args.includes(`--${flag}`);
 }
-const handleState = (args, cwd, raw) => {
+/** Convert a CmdResult into the appropriate output()/error() call. */
+function handleResult(r, raw) {
+	if (r.ok) output(r.result, raw, r.rawValue);
+	else error(r.error);
+}
+const handleState = async (args, cwd, raw) => {
 	const sub = args[1];
 	const handler = sub ? {
 		"update": () => cmdStateUpdate(cwd, args[2], args[3]),
@@ -15717,12 +16272,12 @@ const handleState = (args, cwd, raw) => {
 				const value = args[i + 1];
 				if (key && value !== void 0) patches[key] = value;
 			}
-			cmdStatePatch(cwd, patches, raw);
+			return cmdStatePatch(cwd, patches, raw);
 		},
 		"advance-plan": () => cmdStateAdvancePlan(cwd, raw),
 		"record-metric": () => {
 			const f = getFlags(args, "phase", "plan", "duration", "tasks", "files");
-			cmdStateRecordMetric(cwd, {
+			return cmdStateRecordMetric(cwd, {
 				phase: f.phase ?? "",
 				plan: f.plan ?? "",
 				duration: f.duration ?? "",
@@ -15733,7 +16288,7 @@ const handleState = (args, cwd, raw) => {
 		"update-progress": () => cmdStateUpdateProgress(cwd, raw),
 		"add-decision": () => {
 			const f = getFlags(args, "phase", "summary", "summary-file", "rationale", "rationale-file");
-			cmdStateAddDecision(cwd, {
+			return cmdStateAddDecision(cwd, {
 				phase: f.phase ?? void 0,
 				summary: f.summary ?? void 0,
 				summary_file: f["summary-file"] ?? void 0,
@@ -15743,7 +16298,7 @@ const handleState = (args, cwd, raw) => {
 		},
 		"add-blocker": () => {
 			const f = getFlags(args, "text", "text-file");
-			cmdStateAddBlocker(cwd, {
+			return cmdStateAddBlocker(cwd, {
 				text: f.text ?? void 0,
 				text_file: f["text-file"] ?? void 0
 			}, raw);
@@ -15751,38 +16306,38 @@ const handleState = (args, cwd, raw) => {
 		"resolve-blocker": () => cmdStateResolveBlocker(cwd, getFlag(args, "--text"), raw),
 		"record-session": () => {
 			const f = getFlags(args, "stopped-at", "resume-file");
-			cmdStateRecordSession(cwd, {
+			return cmdStateRecordSession(cwd, {
 				stopped_at: f["stopped-at"] ?? void 0,
 				resume_file: f["resume-file"] ?? "None"
 			}, raw);
 		}
 	}[sub] : void 0;
-	if (handler) return handler();
-	cmdStateLoad(cwd, raw);
+	if (handler) return handleResult(await handler(), raw);
+	return handleResult(await cmdStateLoad(cwd, raw), raw);
 };
 const handleTemplate = (args, cwd, raw) => {
 	const sub = args[1];
-	if (sub === "select") cmdTemplateSelect(cwd, args[2], raw);
+	if (sub === "select") handleResult(cmdTemplateSelect(cwd, args[2]), raw);
 	else if (sub === "fill") {
 		const f = getFlags(args, "phase", "plan", "name", "type", "wave", "fields");
-		cmdTemplateFill(cwd, args[2], {
+		handleResult(cmdTemplateFill(cwd, args[2], {
 			phase: f.phase ?? "",
 			plan: f.plan ?? void 0,
 			name: f.name ?? void 0,
 			type: f.type ?? "execute",
 			wave: f.wave ?? "1",
 			fields: f.fields ? JSON.parse(f.fields) : {}
-		}, raw);
+		}), raw);
 	} else error("Unknown template subcommand. Available: select, fill");
 };
 const handleFrontmatter = (args, cwd, raw) => {
 	const sub = args[1];
 	const file = args[2];
 	const handler = sub ? {
-		"get": () => cmdFrontmatterGet(cwd, file, getFlag(args, "--field"), raw),
-		"set": () => cmdFrontmatterSet(cwd, file, getFlag(args, "--field"), getFlag(args, "--value") ?? void 0, raw),
-		"merge": () => cmdFrontmatterMerge(cwd, file, getFlag(args, "--data"), raw),
-		"validate": () => cmdFrontmatterValidate(cwd, file, getFlag(args, "--schema"), raw)
+		"get": () => handleResult(cmdFrontmatterGet(cwd, file, getFlag(args, "--field")), raw),
+		"set": () => handleResult(cmdFrontmatterSet(cwd, file, getFlag(args, "--field"), getFlag(args, "--value") ?? void 0), raw),
+		"merge": () => handleResult(cmdFrontmatterMerge(cwd, file, getFlag(args, "--data")), raw),
+		"validate": () => handleResult(cmdFrontmatterValidate(cwd, file, getFlag(args, "--schema")), raw)
 	}[sub] : void 0;
 	if (handler) return handler();
 	error("Unknown frontmatter subcommand. Available: get, set, merge, validate");
@@ -15790,46 +16345,48 @@ const handleFrontmatter = (args, cwd, raw) => {
 const handleVerify = async (args, cwd, raw) => {
 	const sub = args[1];
 	const handler = sub ? {
-		"plan-structure": () => cmdVerifyPlanStructure(cwd, args[2], raw),
-		"phase-completeness": () => cmdVerifyPhaseCompleteness(cwd, args[2], raw),
-		"references": () => cmdVerifyReferences(cwd, args[2], raw),
-		"commits": () => cmdVerifyCommits(cwd, args.slice(2), raw),
-		"artifacts": () => cmdVerifyArtifacts(cwd, args[2], raw),
-		"key-links": () => cmdVerifyKeyLinks(cwd, args[2], raw)
+		"plan-structure": () => handleResult(cmdVerifyPlanStructure(cwd, args[2]), raw),
+		"phase-completeness": () => handleResult(cmdVerifyPhaseCompleteness(cwd, args[2]), raw),
+		"references": () => handleResult(cmdVerifyReferences(cwd, args[2]), raw),
+		"commits": async () => handleResult(await cmdVerifyCommits(cwd, args.slice(2)), raw),
+		"artifacts": () => handleResult(cmdVerifyArtifacts(cwd, args[2]), raw),
+		"key-links": () => handleResult(cmdVerifyKeyLinks(cwd, args[2]), raw)
 	}[sub] : void 0;
 	if (handler) return handler();
 	error("Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links");
 };
-const handlePhases = (args, cwd, raw) => {
+const handlePhases = async (args, cwd, raw) => {
 	if (args[1] === "list") {
-		const f = getFlags(args, "type", "phase");
-		cmdPhasesList(cwd, {
+		const f = getFlags(args, "type", "phase", "offset", "limit");
+		handleResult(await cmdPhasesList(cwd, {
 			type: f.type,
 			phase: f.phase,
-			includeArchived: hasFlag(args, "include-archived")
-		}, raw);
+			includeArchived: hasFlag(args, "include-archived"),
+			offset: f.offset !== null ? parseInt(f.offset, 10) : void 0,
+			limit: f.limit !== null ? parseInt(f.limit, 10) : void 0
+		}), raw);
 	} else error("Unknown phases subcommand. Available: list");
 };
-const handleRoadmap = (args, cwd, raw) => {
+const handleRoadmap = async (args, cwd, raw) => {
 	const sub = args[1];
 	const handler = sub ? {
-		"get-phase": () => cmdRoadmapGetPhase(cwd, args[2], raw),
-		"analyze": () => cmdRoadmapAnalyze(cwd, raw),
-		"update-plan-progress": () => cmdRoadmapUpdatePlanProgress(cwd, args[2], raw)
+		"get-phase": () => cmdRoadmapGetPhase(cwd, args[2]),
+		"analyze": () => cmdRoadmapAnalyze(cwd),
+		"update-plan-progress": () => cmdRoadmapUpdatePlanProgress(cwd, args[2])
 	}[sub] : void 0;
-	if (handler) return handler();
+	if (handler) return handleResult(await handler(), raw);
 	error("Unknown roadmap subcommand. Available: get-phase, analyze, update-plan-progress");
 };
 const handlePhase = (args, cwd, raw) => {
 	const sub = args[1];
 	const handler = sub ? {
-		"next-decimal": () => cmdPhaseNextDecimal(cwd, args[2], raw),
-		"add": () => cmdPhaseAdd(cwd, args.slice(2).join(" "), raw),
-		"insert": () => cmdPhaseInsert(cwd, args[2], args.slice(3).join(" "), raw),
-		"remove": () => cmdPhaseRemove(cwd, args[2], { force: hasFlag(args, "force") }, raw),
-		"complete": () => cmdPhaseComplete(cwd, args[2], raw)
+		"next-decimal": () => cmdPhaseNextDecimal(cwd, args[2]),
+		"add": () => cmdPhaseAdd(cwd, args.slice(2).join(" ")),
+		"insert": () => cmdPhaseInsert(cwd, args[2], args.slice(3).join(" ")),
+		"remove": () => cmdPhaseRemove(cwd, args[2], { force: hasFlag(args, "force") }),
+		"complete": () => cmdPhaseComplete(cwd, args[2])
 	}[sub] : void 0;
-	if (handler) return handler();
+	if (handler) return handleResult(handler(), raw);
 	error("Unknown phase subcommand. Available: next-decimal, add, insert, remove, complete");
 };
 const handleMilestone = (args, cwd, raw) => {
@@ -15844,17 +16401,17 @@ const handleMilestone = (args, cwd, raw) => {
 			}
 			milestoneName = nameArgs.join(" ") || null;
 		}
-		cmdMilestoneComplete(cwd, args[2], {
+		handleResult(cmdMilestoneComplete(cwd, args[2], {
 			name: milestoneName ?? void 0,
 			archivePhases: hasFlag(args, "archive-phases")
-		}, raw);
+		}), raw);
 	} else error("Unknown milestone subcommand. Available: complete");
 };
 const handleValidate = (args, cwd, raw) => {
 	const sub = args[1];
 	const handler = sub ? {
-		"consistency": () => cmdValidateConsistency(cwd, raw),
-		"health": () => cmdValidateHealth(cwd, { repair: hasFlag(args, "repair") }, raw)
+		"consistency": () => handleResult(cmdValidateConsistency(cwd), raw),
+		"health": () => handleResult(cmdValidateHealth(cwd, { repair: hasFlag(args, "repair") }), raw)
 	}[sub] : void 0;
 	if (handler) return handler();
 	error("Unknown validate subcommand. Available: consistency, health");
@@ -15862,83 +16419,95 @@ const handleValidate = (args, cwd, raw) => {
 const handleInit = (args, cwd, raw) => {
 	const workflow = args[1];
 	const handler = workflow ? {
-		"execute-phase": () => cmdInitExecutePhase(cwd, args[2], raw),
-		"plan-phase": () => cmdInitPlanPhase(cwd, args[2], raw),
-		"new-project": () => cmdInitNewProject(cwd, raw),
-		"new-milestone": () => cmdInitNewMilestone(cwd, raw),
-		"quick": () => cmdInitQuick(cwd, args.slice(2).join(" "), raw),
-		"resume": () => cmdInitResume(cwd, raw),
-		"verify-work": () => cmdInitVerifyWork(cwd, args[2], raw),
-		"phase-op": () => cmdInitPhaseOp(cwd, args[2], raw),
-		"todos": () => cmdInitTodos(cwd, args[2], raw),
-		"milestone-op": () => cmdInitMilestoneOp(cwd, raw),
-		"map-codebase": () => cmdInitMapCodebase(cwd, raw),
-		"init-existing": () => cmdInitExisting(cwd, raw),
-		"progress": () => cmdInitProgress(cwd, raw)
+		"execute-phase": () => cmdInitExecutePhase(cwd, args[2]),
+		"plan-phase": () => cmdInitPlanPhase(cwd, args[2]),
+		"new-project": () => cmdInitNewProject(cwd),
+		"new-milestone": () => cmdInitNewMilestone(cwd),
+		"quick": () => cmdInitQuick(cwd, args.slice(2).join(" ")),
+		"resume": () => cmdInitResume(cwd),
+		"verify-work": () => cmdInitVerifyWork(cwd, args[2]),
+		"phase-op": () => cmdInitPhaseOp(cwd, args[2]),
+		"todos": () => cmdInitTodos(cwd, args[2]),
+		"milestone-op": () => cmdInitMilestoneOp(cwd),
+		"map-codebase": () => cmdInitMapCodebase(cwd),
+		"init-existing": () => cmdInitExisting(cwd),
+		"progress": () => cmdInitProgress(cwd)
 	}[workflow] : void 0;
-	if (handler) return handler();
+	if (handler) return handleResult(handler(), raw);
 	error(`Unknown init workflow: ${workflow}\nAvailable: execute-phase, plan-phase, new-project, new-milestone, quick, resume, verify-work, phase-op, todos, milestone-op, map-codebase, init-existing, progress`);
 };
 const COMMANDS = {
 	"state": handleState,
-	"resolve-model": (args, cwd, raw) => cmdResolveModel(cwd, args[1], raw),
-	"find-phase": (args, cwd, raw) => cmdFindPhase(cwd, args[1], raw),
+	"resolve-model": (args, cwd, raw) => handleResult(cmdResolveModel(cwd, args[1], raw), raw),
+	"find-phase": (args, cwd, raw) => handleResult(cmdFindPhase(cwd, args[1]), raw),
 	"commit": async (args, cwd, raw) => {
 		const files = args.indexOf("--files") !== -1 ? args.slice(args.indexOf("--files") + 1).filter((a) => !a.startsWith("--")) : [];
-		await cmdCommit(cwd, args[1], files, raw, hasFlag(args, "amend"));
+		handleResult(await cmdCommit(cwd, args[1], files, raw, hasFlag(args, "amend")), raw);
 	},
 	"verify-summary": async (args, cwd, raw) => {
 		const countIndex = args.indexOf("--check-count");
 		const checkCount = countIndex !== -1 ? parseInt(args[countIndex + 1], 10) : 2;
-		await cmdVerifySummary(cwd, args[1], checkCount, raw);
+		handleResult(await cmdVerifySummary(cwd, args[1], checkCount), raw);
 	},
 	"template": handleTemplate,
 	"frontmatter": handleFrontmatter,
 	"verify": handleVerify,
-	"generate-slug": (args, _cwd, raw) => cmdGenerateSlug(args[1], raw),
-	"current-timestamp": (args, _cwd, raw) => cmdCurrentTimestamp(args[1] || "full", raw),
-	"list-todos": (args, cwd, raw) => cmdListTodos(cwd, args[1], raw),
-	"verify-path-exists": (args, cwd, raw) => cmdVerifyPathExists(cwd, args[1], raw),
-	"config-ensure-section": (_args, cwd, raw) => cmdConfigEnsureSection(cwd, raw),
-	"config-set": (args, cwd, raw) => cmdConfigSet(cwd, args[1], args[2], raw),
-	"config-get": (args, cwd, raw) => cmdConfigGet(cwd, args[1], raw),
-	"history-digest": (_args, cwd, raw) => cmdHistoryDigest(cwd, raw),
+	"generate-slug": (args, _cwd, raw) => handleResult(cmdGenerateSlug(args[1], raw), raw),
+	"current-timestamp": (args, _cwd, raw) => handleResult(cmdCurrentTimestamp(args[1] || "full", raw), raw),
+	"list-todos": (args, cwd, raw) => handleResult(cmdListTodos(cwd, args[1], raw), raw),
+	"verify-path-exists": (args, cwd, raw) => handleResult(cmdVerifyPathExists(cwd, args[1], raw), raw),
+	"config-ensure-section": (_args, cwd, raw) => handleResult(cmdConfigEnsureSection(cwd, raw), raw),
+	"config-set": (args, cwd, raw) => handleResult(cmdConfigSet(cwd, args[1], args[2], raw), raw),
+	"config-get": (args, cwd, raw) => handleResult(cmdConfigGet(cwd, args[1], raw), raw),
+	"history-digest": (_args, cwd, raw) => handleResult(cmdHistoryDigest(cwd, raw), raw),
 	"phases": handlePhases,
 	"roadmap": handleRoadmap,
 	"requirements": (args, cwd, raw) => {
-		if (args[1] === "mark-complete") cmdRequirementsMarkComplete(cwd, args.slice(2), raw);
+		if (args[1] === "mark-complete") handleResult(cmdRequirementsMarkComplete(cwd, args.slice(2)), raw);
 		else error("Unknown requirements subcommand. Available: mark-complete");
 	},
 	"phase": handlePhase,
 	"milestone": handleMilestone,
 	"validate": handleValidate,
-	"progress": (args, cwd, raw) => cmdProgressRender(cwd, args[1] || "json", raw),
+	"progress": (args, cwd, raw) => handleResult(cmdProgressRender(cwd, args[1] || "json", raw), raw),
 	"todo": (args, cwd, raw) => {
-		if (args[1] === "complete") cmdTodoComplete(cwd, args[2], raw);
+		if (args[1] === "complete") handleResult(cmdTodoComplete(cwd, args[2], raw), raw);
 		else error("Unknown todo subcommand. Available: complete");
 	},
 	"scaffold": (args, cwd, raw) => {
 		const f = getFlags(args, "phase", "name");
-		cmdScaffold(cwd, args[1], {
+		handleResult(cmdScaffold(cwd, args[1], {
 			phase: f.phase,
 			name: f.name ? args.slice(args.indexOf("--name") + 1).join(" ") : null
-		}, raw);
+		}, raw), raw);
 	},
 	"init": handleInit,
-	"phase-plan-index": (args, cwd, raw) => cmdPhasePlanIndex(cwd, args[1], raw),
-	"state-snapshot": (_args, cwd, raw) => cmdStateSnapshot(cwd, raw),
+	"phase-plan-index": (args, cwd, raw) => handleResult(cmdPhasePlanIndex(cwd, args[1]), raw),
+	"state-snapshot": (_args, cwd, raw) => handleResult(cmdStateSnapshot(cwd, raw), raw),
 	"summary-extract": (args, cwd, raw) => {
 		const fieldsIndex = args.indexOf("--fields");
 		const fields = fieldsIndex !== -1 ? args[fieldsIndex + 1].split(",") : null;
-		cmdSummaryExtract(cwd, args[1], fields, raw);
+		handleResult(cmdSummaryExtract(cwd, args[1], fields, raw), raw);
 	},
 	"websearch": async (args, _cwd, raw) => {
 		const f = getFlags(args, "limit", "freshness");
-		await cmdWebsearch(args[1], {
+		handleResult(await cmdWebsearch(args[1], {
 			limit: f.limit ? parseInt(f.limit, 10) : 10,
 			freshness: f.freshness ?? void 0
-		}, raw);
+		}, raw), raw);
 	},
+	"artefakte-read": (args, cwd, raw) => handleResult(cmdArtefakteRead(cwd, args[1], getFlag(args, "--phase") ?? void 0, raw), raw),
+	"artefakte-write": (args, cwd, raw) => handleResult(cmdArtefakteWrite(cwd, args[1], getFlag(args, "--content") ?? void 0, getFlag(args, "--phase") ?? void 0, raw), raw),
+	"artefakte-append": (args, cwd, raw) => handleResult(cmdArtefakteAppend(cwd, args[1], getFlag(args, "--entry") ?? void 0, getFlag(args, "--phase") ?? void 0, raw), raw),
+	"artefakte-list": (args, cwd, raw) => handleResult(cmdArtefakteList(cwd, getFlag(args, "--phase") ?? void 0, raw), raw),
+	"context-load": (args, cwd, raw) => handleResult(cmdContextLoad(cwd, getFlag(args, "--phase") ?? void 0, getFlag(args, "--topic") ?? void 0, hasFlag(args, "include-history")), raw),
+	"skill-list": (_args, cwd, raw) => cmdSkillList(cwd, raw),
+	"skill-install": (args, cwd, raw) => cmdSkillInstall(cwd, args[1], raw),
+	"skill-update": (args, cwd, raw) => cmdSkillUpdate(cwd, args[1], raw),
+	"start": async (args, cwd, raw) => handleResult(await cmdStart(cwd, {
+		noBrowser: hasFlag(args, "no-browser"),
+		networkMode: hasFlag(args, "network")
+	}), raw),
 	"dashboard": (args) => handleDashboard(args.slice(1)),
 	"start-server": async () => {
 		const serverPath = node_path.join(__dirname, "mcp-server.cjs");
@@ -15946,30 +16515,42 @@ const COMMANDS = {
 	}
 };
 async function main() {
-	const args = process.argv.slice(2);
-	let cwd = process.cwd();
-	const cwdEqArg = args.find((arg) => arg.startsWith("--cwd="));
-	const cwdIdx = args.indexOf("--cwd");
-	if (cwdEqArg) {
-		const value = cwdEqArg.slice(6).trim();
-		if (!value) error("Missing value for --cwd");
-		args.splice(args.indexOf(cwdEqArg), 1);
-		cwd = node_path.resolve(value);
-	} else if (cwdIdx !== -1) {
-		const value = args[cwdIdx + 1];
-		if (!value || value.startsWith("--")) error("Missing value for --cwd");
-		args.splice(cwdIdx, 2);
-		cwd = node_path.resolve(value);
-	}
-	if (!node_fs.existsSync(cwd) || !node_fs.statSync(cwd).isDirectory()) error(`Invalid --cwd: ${cwd}`);
-	const rawIndex = args.indexOf("--raw");
-	const raw = rawIndex !== -1;
-	if (rawIndex !== -1) args.splice(rawIndex, 1);
-	const command = args[0];
-	if (!command) error(`Usage: maxsim-tools <command> [args] [--raw] [--cwd <path>]\nCommands: ${Object.keys(COMMANDS).join(", ")}`);
-	const handler = COMMANDS[command];
-	if (!handler) error(`Unknown command: ${command}`);
-	await handler(args, cwd, raw);
+	try {
+		const args = process.argv.slice(2);
+		let cwd = process.cwd();
+		const cwdEqArg = args.find((arg) => arg.startsWith("--cwd="));
+		const cwdIdx = args.indexOf("--cwd");
+		if (cwdEqArg) {
+			const value = cwdEqArg.slice(6).trim();
+			if (!value) error("Missing value for --cwd");
+			args.splice(args.indexOf(cwdEqArg), 1);
+			cwd = node_path.resolve(value);
+		} else if (cwdIdx !== -1) {
+			const value = args[cwdIdx + 1];
+			if (!value || value.startsWith("--")) error("Missing value for --cwd");
+			args.splice(cwdIdx, 2);
+			cwd = node_path.resolve(value);
+		}
+		if (!node_fs.existsSync(cwd) || !node_fs.statSync(cwd).isDirectory()) error(`Invalid --cwd: ${cwd}`);
+		const rawIndex = args.indexOf("--raw");
+		const raw = rawIndex !== -1;
+		if (rawIndex !== -1) args.splice(rawIndex, 1);
+		const command = args[0];
+		if (!command) error(`Usage: maxsim-tools <command> [args] [--raw] [--cwd <path>]\nCommands: ${Object.keys(COMMANDS).join(", ")}`);
+		const handler = COMMANDS[command];
+		if (!handler) error(`Unknown command: ${command}`);
+		await handler(args, cwd, raw);
+	} catch (thrown) {
+		if (thrown instanceof CliOutput) {
+			writeOutput(thrown);
+			process.exit(0);
+		}
+		if (thrown instanceof CliError) {
+			process.stderr.write("Error: " + thrown.message + "\n");
+			process.exit(1);
+		}
+		throw thrown;
+	}
 }
 /**
 * Dashboard launch command.
@@ -15979,40 +16560,20 @@ async function main() {
 * Supports --stop to kill a running instance.
 */
 async function handleDashboard(args) {
-	const DEFAULT_PORT = 3333;
-	const PORT_RANGE_END = 3343;
-	const HEALTH_TIMEOUT_MS = 1500;
 	const networkMode = args.includes("--network");
 	if (args.includes("--stop")) {
-		for (let port = DEFAULT_PORT; port <= PORT_RANGE_END; port++) if (await checkHealth(port, HEALTH_TIMEOUT_MS)) {
-			console.log(`Dashboard found on port ${port} — sending shutdown...`);
-			console.log(`Dashboard at http://localhost:${port} is running.`);
-			console.log(`To stop it, close the browser tab or kill the process on port ${port}.`);
-			try {
-				if (process.platform === "win32") {
-					const lines = (0, node_child_process.execSync)(`netstat -ano | findstr :${port} | findstr LISTENING`, { encoding: "utf-8" }).trim().split("\n");
-					const pids = /* @__PURE__ */ new Set();
-					for (const line of lines) {
-						const parts = line.trim().split(/\s+/);
-						const pid = parts[parts.length - 1];
-						if (pid && pid !== "0") pids.add(pid);
-					}
-					for (const pid of pids) try {
-						(0, node_child_process.execSync)(`taskkill /PID ${pid} /F`, { stdio: "ignore" });
-						console.log(`Killed process ${pid}`);
-					} catch {}
-				} else (0, node_child_process.execSync)(`lsof -i :${port} -t | xargs kill -SIGTERM 2>/dev/null`, { stdio: "ignore" });
-				console.log("Dashboard stopped.");
-			} catch {
-				console.log("Could not automatically stop the dashboard. Kill the process manually.");
-			}
+		for (let port = DEFAULT_PORT; port <= PORT_RANGE_END; port++) if (await checkHealth(port)) {
+			console.log(`Dashboard found on port ${port} — stopping...`);
+			killProcessOnPort(port);
+			console.log("Dashboard stopped.");
 			return;
 		}
 		console.log("No running dashboard found.");
 		return;
 	}
-	for (let port = DEFAULT_PORT; port <= PORT_RANGE_END; port++) if (await checkHealth(port, HEALTH_TIMEOUT_MS)) {
-		console.log(`Dashboard already running at http://localhost:${port}`);
+	const runningPort = await findRunningDashboard();
+	if (runningPort) {
+		console.log(`Dashboard already running at http://localhost:${runningPort}`);
 		return;
 	}
 	const serverPath = resolveDashboardServer();
@@ -16021,100 +16582,25 @@ async function handleDashboard(args) {
 		console.error("Ensure @maxsim/dashboard is installed and built.");
 		process.exit(1);
 	}
-	const isTsFile = serverPath.endsWith(".ts");
-	const runner = "node";
-	const runnerArgs = isTsFile ? [
-		"--import",
-		"tsx",
-		serverPath
-	] : [serverPath];
 	const serverDir = node_path.dirname(serverPath);
-	let projectCwd = process.cwd();
-	const dashboardConfigPath = node_path.join(node_path.dirname(serverDir), "dashboard.json");
-	if (node_fs.existsSync(dashboardConfigPath)) try {
-		const config = JSON.parse(node_fs.readFileSync(dashboardConfigPath, "utf8"));
-		if (config.projectCwd) projectCwd = config.projectCwd;
-	} catch {}
-	const ptyModulePath = node_path.join(serverDir, "node_modules", "node-pty");
-	if (!node_fs.existsSync(ptyModulePath)) {
-		console.log("Installing node-pty for terminal support...");
-		try {
-			(0, node_child_process.execSync)("npm install node-pty --save-optional --no-audit --no-fund --loglevel=error", {
-				cwd: serverDir,
-				stdio: "inherit",
-				timeout: 12e4
-			});
-		} catch {
-			console.warn("node-pty installation failed — terminal will be unavailable.");
-		}
-	}
+	const dashConfig = readDashboardConfig(serverPath);
+	console.log("Installing node-pty for terminal support...");
+	if (!ensureNodePty(serverDir)) console.warn("node-pty installation failed — terminal will be unavailable.");
 	console.log("Dashboard starting...");
-	const child = (0, node_child_process.spawn)(runner, runnerArgs, {
-		cwd: serverDir,
-		detached: true,
-		stdio: "ignore",
-		env: {
-			...process.env,
-			MAXSIM_PROJECT_CWD: projectCwd,
-			NODE_ENV: isTsFile ? "development" : "production",
-			...networkMode ? { MAXSIM_NETWORK_MODE: "1" } : {}
-		},
-		...process.platform === "win32" ? { shell: true } : {}
+	const pid = spawnDashboard({
+		serverPath,
+		projectCwd: dashConfig.projectCwd,
+		networkMode
 	});
-	child.unref();
 	await new Promise((resolve) => setTimeout(resolve, 3e3));
-	for (let port = DEFAULT_PORT; port <= PORT_RANGE_END; port++) if (await checkHealth(port, HEALTH_TIMEOUT_MS)) {
-		console.log(`Dashboard ready at http://localhost:${port}`);
+	const readyPort = await findRunningDashboard();
+	if (readyPort) {
+		console.log(`Dashboard ready at http://localhost:${readyPort}`);
 		return;
 	}
-	console.log(`Dashboard spawned (PID ${child.pid}). It may take a moment to start.`);
+	console.log(`Dashboard spawned (PID ${pid}). It may take a moment to start.`);
 	console.log(`Check http://localhost:${DEFAULT_PORT} once ready.`);
 }
-/**
-* Check if a dashboard health endpoint is responding on the given port.
-*/
-async function checkHealth(port, timeoutMs) {
-	try {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), timeoutMs);
-		const res = await fetch(`http://localhost:${port}/api/health`, { signal: controller.signal });
-		clearTimeout(timer);
-		if (res.ok) return (await res.json()).status === "ok";
-		return false;
-	} catch {
-		return false;
-	}
-}
-/**
-* Resolve the dashboard server entry point path.
-* Tries: built server.js first, then source server.ts for dev mode.
-*/
-function resolveDashboardServer() {
-	const localDashboard = node_path.join(process.cwd(), ".claude", "dashboard", "server.js");
-	if (node_fs.existsSync(localDashboard)) return localDashboard;
-	const globalDashboard = node_path.join(node_os.homedir(), ".claude", "dashboard", "server.js");
-	if (node_fs.existsSync(globalDashboard)) return globalDashboard;
-	try {
-		const pkgPath = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href).resolve("@maxsim/dashboard/package.json");
-		const pkgDir = node_path.dirname(pkgPath);
-		const serverJs = node_path.join(pkgDir, "server.js");
-		if (node_fs.existsSync(serverJs)) return serverJs;
-		const serverTs = node_path.join(pkgDir, "server.ts");
-		if (node_fs.existsSync(serverTs)) return serverTs;
-	} catch {}
-	try {
-		let dir = node_path.dirname(new URL(require("url").pathToFileURL(__filename).href).pathname);
-		if (process.platform === "win32" && dir.startsWith("/")) dir = dir.slice(1);
-		for (let i = 0; i < 5; i++) {
-			const candidate = node_path.join(dir, "packages", "dashboard", "server.ts");
-			if (node_fs.existsSync(candidate)) return candidate;
-			const candidateJs = node_path.join(dir, "packages", "dashboard", "server.js");
-			if (node_fs.existsSync(candidateJs)) return candidateJs;
-			dir = node_path.dirname(dir);
-		}
-	} catch {}
-	return null;
-}
 main();
 
 //#endregion