@wot-ui/cli 1.0.3 → 1.0.5-beta.1

package/dist/index.mjs

@@ -1,10 +1,1596 @@
 #!/usr/bin/env node
-import { a as findComponent, c as formatStatusLabel, d as resolveVersion, f as loadMetadataFile, i as lintProject, l as writeStderrLine, m as version, o as listComponents, p as name, r as analyzeUsage, s as formatLogMessage, t as checkForCliUpdate, u as detectVersion } from "./update-check-cp6uTpce.mjs";
+import { _ as version, a as filterComponents, d as formatStatusLabel, f as writeStderrLine, g as name, h as loadMetadataFile, i as lintProject, m as resolveVersion, o as findComponent, p as detectVersion, r as analyzeUsage, s as listComponents, t as checkForCliUpdate, u as formatLogMessage } from "./update-check-YZ9xD4u9.mjs";
 import process from "node:process";
 import { Command } from "commander";
-import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { constants, existsSync, readFileSync } from "node:fs";
+import { access, chmod, copyFile, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { isDeepStrictEqual, stripVTControlCharacters } from "node:util";
+import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+import { parse as parse$1 } from "smol-toml";
+import { LATEST_PROTOCOL_VERSION, ReadBuffer, serializeMessage } from "@modelcontextprotocol/server";
 
+//#region src/application/change-plan.ts
+async function pathExists(path) {
+	try {
+		await access(path, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readOptionalFile(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+var ChangePlanCleanupError = class extends Error {
+	applied;
+	cleanupFailures;
+	constructor(options) {
+		super(`Change plan was applied, but transaction cleanup failed for ${options.cleanupFailures.map((failure) => failure.path).join(", ")}`);
+		this.name = "ChangePlanCleanupError";
+		this.applied = options.applied;
+		this.cleanupFailures = options.cleanupFailures;
+	}
+};
+var ChangePlanApplyError = class extends Error {
+	cause;
+	applied;
+	rolledBack;
+	rollbackFailures;
+	cleanupFailures;
+	constructor(options) {
+		const causeMessage = options.cause instanceof Error ? options.cause.message : String(options.cause);
+		const rollbackMessage = options.rollbackFailures.length > 0 ? `rollback incomplete for ${options.rollbackFailures.map((failure) => failure.backupPath ? `${failure.path} (backup: ${failure.backupPath})` : failure.path).join(", ")}` : options.applied.length > 0 ? `rolled back ${options.rolledBack.length} applied change${options.rolledBack.length === 1 ? "" : "s"}` : "no files were changed";
+		const cleanupMessage = options.cleanupFailures.length > 0 ? `; cleanup incomplete for ${options.cleanupFailures.map((failure) => failure.path).join(", ")}` : "";
+		super(`Failed to apply change plan; ${rollbackMessage}${cleanupMessage}: ${causeMessage}`);
+		this.name = "ChangePlanApplyError";
+		this.cause = options.cause;
+		this.applied = options.applied;
+		this.rolledBack = options.rolledBack;
+		this.rollbackFailures = options.rollbackFailures;
+		this.cleanupFailures = options.cleanupFailures;
+	}
+};
+function isWithinRoot(root, path) {
+	const relation = relative(root, path);
+	return relation === "" || !relation.startsWith("..") && !isAbsolute(relation);
+}
+async function nearestExistingPath(path) {
+	let current = path;
+	while (true) try {
+		await lstat(current);
+		return current;
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(current);
+		if (parent === current) throw error;
+		current = parent;
+	}
+}
+async function assertPlanPath(change) {
+	const { path, allowedRoot } = change;
+	if (!path || path === "/" || path === process.env.HOME) throw new Error(`Refusing unsafe change target: ${path || "<empty>"}`);
+	if (!allowedRoot) throw new Error(`Missing allowed root for change target: ${path}`);
+	const [resolvedRoot, existingPath] = await Promise.all([realpath(allowedRoot), nearestExistingPath(path)]);
+	if (!isWithinRoot(resolvedRoot, await realpath(existingPath))) throw new Error(`Refusing change target outside allowed root: ${path}`);
+	if (existingPath === path && (await lstat(path)).isSymbolicLink()) throw new Error(`Refusing symbolic link change target: ${path}`);
+}
+async function assertUnchanged(change) {
+	await assertPlanPath(change);
+	if (await readOptionalFile(change.path) !== change.before) throw new Error(`Target changed after planning: ${change.path}`);
+}
+function transactionPath(path, transactionId, index, suffix) {
+	return `${path}.open-wot-${transactionId}-${index}.${suffix}`;
+}
+async function prepareChange(change, transactionId, index) {
+	await assertPlanPath(change);
+	if (change.type === "delete-file") return {
+		change,
+		touched: false,
+		backupCreated: false
+	};
+	await mkdir(dirname(change.path), { recursive: true });
+	const temporaryPath = transactionPath(change.path, transactionId, index, "tmp");
+	try {
+		await writeFile(temporaryPath, change.after ?? "", "utf8");
+		if (change.before !== void 0 && await pathExists(change.path)) await chmod(temporaryPath, (await stat(change.path)).mode);
+		return {
+			change,
+			temporaryPath,
+			touched: false,
+			backupCreated: false
+		};
+	} catch (error) {
+		await rm(temporaryPath, { force: true }).catch(() => {});
+		throw error;
+	}
+}
+async function commitChange(prepared, transactionId, index, hooks) {
+	const { change } = prepared;
+	await assertUnchanged(change);
+	if (change.before !== void 0) {
+		prepared.backupPath = transactionPath(change.path, transactionId, index, "rollback");
+		await hooks.beforeBackup?.(change, prepared.backupPath, index);
+		await copyFile(change.path, prepared.backupPath, constants.COPYFILE_EXCL);
+		prepared.backupCreated = true;
+	}
+	if (change.type === "write-file") {
+		await rename(prepared.temporaryPath, change.path);
+		prepared.touched = true;
+	} else {
+		await rm(change.path);
+		prepared.touched = true;
+	}
+}
+async function rollbackPreparedChange(prepared) {
+	const { change } = prepared;
+	if (!prepared.touched) return;
+	if (prepared.backupCreated && prepared.backupPath) {
+		await rm(change.path, { force: true });
+		await rename(prepared.backupPath, change.path);
+		prepared.backupCreated = false;
+		return;
+	}
+	await rm(change.path, { force: true });
+}
+async function cleanupPreparedChanges(preparedChanges, removeBackups, hooks) {
+	const failures = [];
+	await Promise.all(preparedChanges.flatMap((prepared) => {
+		const paths = [prepared.temporaryPath];
+		if (removeBackups) paths.push(prepared.backupPath);
+		return paths.filter((path) => Boolean(path)).map(async (path) => {
+			try {
+				await hooks.beforeCleanup?.(path);
+				await rm(path, { force: true });
+			} catch (error) {
+				failures.push({
+					path,
+					error: error instanceof Error ? error.message : String(error)
+				});
+			}
+		});
+	}));
+	return failures;
+}
+async function applyChangePlan(plan, hooks = {}) {
+	const transactionId = `${process.pid}-${Date.now()}-${randomUUID()}`;
+	const preparedChanges = [];
+	const applied = [];
+	try {
+		for (const change of plan.changes) await assertUnchanged(change);
+		for (const [index, change] of plan.changes.entries()) preparedChanges.push(await prepareChange(change, transactionId, index));
+		for (const [index, prepared] of preparedChanges.entries()) {
+			await hooks.beforeCommit?.(prepared.change, index);
+			await commitChange(prepared, transactionId, index, hooks);
+			applied.push(prepared);
+		}
+		const cleanupFailures = await cleanupPreparedChanges(preparedChanges, true, hooks);
+		if (cleanupFailures.length > 0) throw new ChangePlanCleanupError({
+			applied: applied.map((item) => item.change.path),
+			cleanupFailures
+		});
+		return {
+			changed: applied.length > 0,
+			applied: applied.map((item) => item.change),
+			rolledBack: false
+		};
+	} catch (error) {
+		if (error instanceof ChangePlanCleanupError) throw error;
+		const rollbackTargets = preparedChanges.filter((change) => change.touched).reverse();
+		const rolledBack = [];
+		const rollbackFailures = [];
+		for (const [index, prepared] of rollbackTargets.entries()) try {
+			await hooks.beforeRollback?.(prepared.change, index);
+			await rollbackPreparedChange(prepared);
+			rolledBack.push(prepared.change.path);
+		} catch (rollbackError) {
+			rollbackFailures.push({
+				path: prepared.change.path,
+				error: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
+				...prepared.backupCreated && prepared.backupPath ? { backupPath: prepared.backupPath } : {}
+			});
+		}
+		const cleanupFailures = await cleanupPreparedChanges(preparedChanges, rollbackFailures.length === 0, hooks);
+		throw new ChangePlanApplyError({
+			cause: error,
+			applied: applied.map((item) => item.change.path),
+			rolledBack,
+			rollbackFailures,
+			cleanupFailures
+		});
+	}
+}
+function mergeChangePlans(summary, plans) {
+	const changes = [];
+	const targets = /* @__PURE__ */ new Map();
+	for (const change of plans.flatMap((plan) => plan.changes)) {
+		const existing = targets.get(change.path);
+		if (!existing) {
+			targets.set(change.path, change);
+			changes.push(change);
+			continue;
+		}
+		if (existing.type !== change.type || existing.allowedRoot !== change.allowedRoot || existing.before !== change.before || existing.after !== change.after) throw new Error(`Conflicting planned changes for ${change.path}`);
+	}
+	return {
+		id: plans.map((plan) => plan.id).join("+") || "empty",
+		summary,
+		changes,
+		warnings: plans.flatMap((plan) => plan.warnings),
+		requiresConfirmation: plans.some((plan) => plan.requiresConfirmation)
+	};
+}
+function formatChangePlan(plan, cwd = process.cwd()) {
+	const lines = [plan.summary];
+	if (plan.changes.length === 0) lines.push("No changes required.");
+	for (const change of plan.changes) {
+		const path = relative(cwd, change.path) || change.path;
+		lines.push(`${change.type}: ${path}`, `  ${change.reason}`);
+		lines.push(...getSafePreview(change).map((line) => `  ${line}`));
+	}
+	for (const warning of plan.warnings) lines.push(`warning: ${warning}`);
+	return lines.join("\n");
+}
+function getSafePreview(change) {
+	if (change.preview?.length) return change.preview;
+	if (change.type === "delete-file" || change.after === void 0) return ["- delete file"];
+	return [change.before === void 0 ? "+ create file" : "~ update file"];
+}
+function toPublicChangePlan(plan, cwd = process.cwd()) {
+	return {
+		id: plan.id,
+		summary: plan.summary,
+		changes: plan.changes.map((change) => ({
+			type: change.type,
+			path: relative(cwd, change.path) || change.path,
+			reason: change.reason,
+			preview: getSafePreview(change)
+		})),
+		warnings: [...plan.warnings],
+		requiresConfirmation: plan.requiresConfirmation
+	};
+}
+async function confirmChangePlan(plan, options = {}) {
+	if (plan.changes.length === 0 || options.yes) return true;
+	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("Refusing to modify files in a non-interactive session without --yes. Use --dry-run to preview.");
+	const prompt = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		process.stdout.write(`${formatChangePlan(plan, options.cwd)}\n`);
+		const answer = await prompt.question(`Apply ${plan.changes.length} change${plan.changes.length === 1 ? "" : "s"}? [y/N] `);
+		return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+	} finally {
+		prompt.close();
+	}
+}
+
+//#endregion
+//#region src/utils/redaction.ts
+const SENSITIVE_KEY = String.raw`(?:api[_-]?key|access[_-]?token|auth(?:orization)?|bearer|client[_-]?secret|password|passwd|secret|token|cookie)`;
+const BEARER_PATTERN = /(authorization\s*:\s*bearer\s+)[^\s,;]+/gi;
+const ASSIGNMENT_PATTERN = new RegExp(`(["']?${SENSITIVE_KEY}["']?\\s*[:=]\\s*)(?:"[^"]*"|'[^']*'|\\S+)`, "gi");
+function redactSensitiveText(value, secretValues = []) {
+	let redacted = value.replace(BEARER_PATTERN, "$1[REDACTED]");
+	redacted = redacted.replace(ASSIGNMENT_PATTERN, "$1[REDACTED]");
+	for (const secret of secretValues) if (secret) redacted = redacted.split(secret).join("[REDACTED]");
+	return redacted;
+}
+
+//#endregion
+//#region src/mcp/clients/client-command.ts
+const TERMINATION_GRACE_MS = 500;
+async function runClientCommand(executable, args, options) {
+	const platform = options.platform ?? process.platform;
+	const useShell = platform === "win32" && /\.(?:cmd|bat)$/i.test(executable);
+	const totalTimeoutMs = Math.max(1, options.timeoutMs ?? 5e3);
+	const terminationGraceMs = Math.min(TERMINATION_GRACE_MS, Math.floor(totalTimeoutMs / 5));
+	const commandTimeoutMs = totalTimeoutMs - terminationGraceMs;
+	return new Promise((resolve$1) => {
+		const child = spawn(executable, args, {
+			cwd: options.cwd,
+			env: options.env,
+			windowsHide: true,
+			shell: useShell,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timedOut = false;
+		let timer;
+		let terminationTimer;
+		const finish = (result) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			if (terminationTimer) clearTimeout(terminationTimer);
+			resolve$1({
+				...result,
+				stdout: stdout.slice(-8e3),
+				stderr: stderr.slice(-8e3)
+			});
+		};
+		timer = setTimeout(() => {
+			timedOut = true;
+			if (platform === "win32" && child.pid) spawn("taskkill", [
+				"/pid",
+				String(child.pid),
+				"/T",
+				"/F"
+			], {
+				windowsHide: true,
+				stdio: "ignore"
+			}).once("error", () => child.kill("SIGTERM"));
+			else child.kill("SIGTERM");
+			terminationTimer = setTimeout(() => child.kill("SIGKILL"), terminationGraceMs);
+			terminationTimer.unref();
+		}, commandTimeoutMs);
+		timer.unref();
+		child.stdout.on("data", (chunk) => stdout += chunk.toString("utf8"));
+		child.stderr.on("data", (chunk) => stderr += chunk.toString("utf8"));
+		child.once("error", (error) => finish(timedOut ? {
+			timedOut: true,
+			error: `Client command timed out after ${totalTimeoutMs}ms`
+		} : {
+			timedOut: false,
+			error: error.message
+		}));
+		child.once("close", (code) => finish(timedOut ? {
+			timedOut: true,
+			error: `Client command timed out after ${totalTimeoutMs}ms`
+		} : {
+			timedOut: false,
+			...code === null ? {} : { exitCode: code }
+		}));
+	});
+}
+function clientCommandOutput(result) {
+	return redactSensitiveText(stripVTControlCharacters(`${result.stdout}\n${result.stderr}`).trim());
+}
+
+//#endregion
+//#region src/mcp/clients/detect.ts
+async function isExecutable(path, platform) {
+	try {
+		await access(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function findExecutable(names, context) {
+	const env = context.env ?? process.env;
+	const platform = context.platform ?? process.platform;
+	const pathEntries = (env.PATH ?? "").split(platform === "win32" ? ";" : ":").filter(Boolean);
+	const pathExts = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean) : [""];
+	for (const name$1 of names) {
+		const extensions = platform === "win32" && !extname(name$1) ? pathExts : [""];
+		for (const directory of pathEntries) for (const extension of extensions) {
+			const candidate = join(directory, `${name$1}${extension}`);
+			if (await isExecutable(candidate, platform)) return candidate;
+		}
+	}
+}
+
+//#endregion
+//#region src/mcp/clients/json-adapter.ts
+async function readOptional$2(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+function parseObject(content, path) {
+	const errors = [];
+	const value = parse(content, errors, {
+		allowTrailingComma: true,
+		disallowComments: false
+	});
+	if (errors.length > 0) {
+		const first = errors[0];
+		throw new Error(`Invalid JSONC in ${path}: ${printParseErrorCode(first.error)} at offset ${first.offset}`);
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Expected an object in ${path}`);
+	return value;
+}
+function isStringMap(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string");
+}
+function isServerDefinition(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const candidate = value;
+	const env = candidate.env;
+	return typeof candidate.command === "string" && Array.isArray(candidate.args) && candidate.args.every((argument) => typeof argument === "string") && (env === void 0 || isStringMap(env));
+}
+function serverMatches$1(actual, expected) {
+	return actual?.command === expected.command && JSON.stringify(actual.args) === JSON.stringify(expected.args) && JSON.stringify(actual.env ?? {}) === JSON.stringify(expected.env ?? {});
+}
+function serverPreview$1(server, serverKey) {
+	return [
+		`+ ${serverKey}.wot-ui`,
+		`  command: ${server.command}`,
+		`  args: ${server.args.join(" ")}`,
+		...Object.keys(server.env ?? {}).map((key) => `  env.${key}: [REDACTED]`)
+	];
+}
+var JsonMcpClientAdapter = class {
+	id;
+	displayName;
+	supportedScopes;
+	options;
+	constructor(options) {
+		this.options = options;
+		this.id = options.id;
+		this.displayName = options.displayName;
+		this.supportedScopes = options.supportedScopes;
+	}
+	assertScope(scope) {
+		if (!this.supportedScopes.includes(scope)) throw new Error(`${this.displayName} does not support ${scope} scope`);
+	}
+	async detect(context) {
+		const configLocations = this.supportedScopes.map((scope) => this.options.configPath(context, scope));
+		const executable = await findExecutable(this.options.executableNames, context);
+		const hasConfig = (await Promise.all(configLocations.map(async (path) => {
+			try {
+				await access(path);
+				return true;
+			} catch {
+				return false;
+			}
+		}))).some(Boolean);
+		return {
+			client: this.id,
+			displayName: this.displayName,
+			installed: Boolean(executable) || hasConfig,
+			...executable ? { executable } : {},
+			supportedScopes: this.supportedScopes,
+			configLocations,
+			preferredMethod: "config-file"
+		};
+	}
+	async inspect(context) {
+		this.assertScope(context.scope);
+		const path = this.options.configPath(context, context.scope);
+		const content = await readOptional$2(path);
+		if (content === void 0) return {
+			client: this.id,
+			displayName: this.displayName,
+			scope: context.scope,
+			path,
+			exists: false,
+			configured: false,
+			matches: false
+		};
+		try {
+			const servers = parseObject(content || "{}", path)[this.options.serverKey];
+			const entry = servers && typeof servers === "object" && !Array.isArray(servers) ? servers["wot-ui"] : void 0;
+			const server = isServerDefinition(entry) ? entry : void 0;
+			return {
+				client: this.id,
+				displayName: this.displayName,
+				scope: context.scope,
+				path,
+				exists: true,
+				configured: entry !== void 0,
+				matches: serverMatches$1(server, context.server),
+				...server ? { server } : {},
+				...!server && entry !== void 0 ? { problem: "The wot-ui entry is not a supported stdio server definition" } : {}
+			};
+		} catch (error) {
+			return {
+				client: this.id,
+				displayName: this.displayName,
+				scope: context.scope,
+				path,
+				exists: true,
+				configured: false,
+				matches: false,
+				problem: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async planInstall(context) {
+		this.assertScope(context.scope);
+		const path = this.options.configPath(context, context.scope);
+		const before = await readOptional$2(path);
+		const source = before?.trim() ? before : "{}\n";
+		parseObject(source, path);
+		const after = applyEdits(source, modify(source, [this.options.serverKey, "wot-ui"], context.server, { formattingOptions: {
+			insertSpaces: true,
+			tabSize: 2,
+			eol: source.includes("\r\n") ? "\r\n" : "\n"
+		} }));
+		const unchanged = before !== void 0 ? before === after : after === "{}\n";
+		return {
+			id: `${this.id}-${context.scope}-install`,
+			summary: `Configure wot-ui MCP for ${this.displayName}`,
+			changes: unchanged ? [] : [{
+				type: "write-file",
+				path,
+				allowedRoot: context.scope === "project" ? context.cwd : context.homeDir,
+				before,
+				after,
+				reason: `Add or update mcp server "wot-ui" under ${this.options.serverKey}`,
+				preview: serverPreview$1(context.server, this.options.serverKey)
+			}],
+			warnings: [],
+			requiresConfirmation: !unchanged
+		};
+	}
+	async planRemove(context) {
+		this.assertScope(context.scope);
+		const path = this.options.configPath(context, context.scope);
+		const before = await readOptional$2(path);
+		if (before === void 0) return {
+			id: `${this.id}-${context.scope}-remove`,
+			summary: `Remove wot-ui MCP from ${this.displayName}`,
+			changes: [],
+			warnings: [],
+			requiresConfirmation: false
+		};
+		parseObject(before || "{}", path);
+		const after = applyEdits(before, modify(before, [this.options.serverKey, "wot-ui"], void 0, { formattingOptions: {
+			insertSpaces: true,
+			tabSize: 2,
+			eol: before.includes("\r\n") ? "\r\n" : "\n"
+		} }));
+		return {
+			id: `${this.id}-${context.scope}-remove`,
+			summary: `Remove wot-ui MCP from ${this.displayName}`,
+			changes: before === after ? [] : [{
+				type: "write-file",
+				path,
+				allowedRoot: context.scope === "project" ? context.cwd : context.homeDir,
+				before,
+				after,
+				reason: "Remove only the wot-ui MCP server entry",
+				preview: [`- ${this.options.serverKey}.wot-ui`]
+			}],
+			warnings: [],
+			requiresConfirmation: before !== after
+		};
+	}
+	async print(context) {
+		this.assertScope(context.scope);
+		return JSON.stringify({ [this.options.serverKey]: { "wot-ui": context.server } }, null, 2);
+	}
+	async verifyRegistration(context, state, options) {
+		if (this.options.verifyRegistration) return this.options.verifyRegistration(context, state, options);
+		return {
+			status: "unsupported",
+			message: `${this.displayName} does not expose a stable CLI registration status check`,
+			action: `Restart ${this.displayName} and confirm wot-ui in its MCP server panel.`
+		};
+	}
+};
+
+//#endregion
+//#region src/mcp/clients/claude.ts
+const claudeAdapter = new JsonMcpClientAdapter({
+	id: "claude",
+	displayName: "Claude Code",
+	executableNames: ["claude"],
+	supportedScopes: ["project", "user"],
+	configPath: (context, scope) => scope === "project" ? resolve(context.cwd, ".mcp.json") : join(context.homeDir, ".claude.json"),
+	serverKey: "mcpServers",
+	verifyRegistration: async (context, _state, options) => {
+		const executable = await findExecutable(["claude"], context);
+		if (!executable) return {
+			status: "unknown",
+			message: "Claude Code executable was not found; registration could not be verified",
+			action: "Open Claude Code in this project and inspect /mcp."
+		};
+		const result = await runClientCommand(executable, [
+			"mcp",
+			"get",
+			"wot-ui"
+		], {
+			...context,
+			timeoutMs: options?.timeoutMs
+		});
+		const output = clientCommandOutput(result);
+		const command = `${executable} mcp get wot-ui`;
+		if (result.timedOut || result.error) return {
+			status: "failed",
+			message: result.error || "Claude Code registration check failed",
+			action: "Retry claude mcp get wot-ui and inspect the client process if it still fails.",
+			command
+		};
+		if (/pending approval|approval.*pending|untrusted|not trusted|trust (?:this )?(?:project|workspace)/i.test(output)) return {
+			status: "pending",
+			message: "Claude Code found wot-ui, but project approval is pending",
+			action: "Open Claude Code in this project and approve the wot-ui MCP server.",
+			command
+		};
+		if (/rejected|disabled/i.test(output)) return {
+			status: "failed",
+			message: "Claude Code has rejected or disabled the wot-ui MCP server",
+			action: "Open /mcp in Claude Code and enable or re-approve wot-ui.",
+			command
+		};
+		if (result.exitCode === 0 && !result.timedOut) return {
+			status: "ready",
+			message: "Claude Code recognizes the wot-ui MCP server",
+			command
+		};
+		return {
+			status: "failed",
+			message: "Claude Code did not recognize the wot-ui MCP server",
+			action: "Run claude mcp get wot-ui and inspect the configured scope.",
+			command
+		};
+	}
+});
+
+//#endregion
+//#region src/mcp/clients/types.ts
+const MCP_CLIENT_IDS = [
+	"claude",
+	"cursor",
+	"vscode",
+	"codex"
+];
+const REQUIRED_WOT_MCP_TOOLS = ["wot_status", "wot_list"];
+function isMcpClientId(value) {
+	return MCP_CLIENT_IDS.includes(value);
+}
+function isMcpScope(value) {
+	return value === "project" || value === "user";
+}
+
+//#endregion
+//#region src/mcp/clients/toml-adapter.ts
+const START = "# open-wot managed mcp server start";
+const END = "# open-wot managed mcp server end";
+const TABLE_PATTERN = /^\[mcp_servers\.(?:wot-ui|"wot-ui")\]\s*$/m;
+const CHILD_TABLE_PATTERN = /^\s*\[\[?\s*mcp_servers\s*\.\s*(?:wot-ui|"wot-ui")\s*\./m;
+async function readOptional$1(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+function quoteToml(value) {
+	return JSON.stringify(value);
+}
+function createBlock(server) {
+	const lines = [
+		START,
+		"[mcp_servers.wot-ui]",
+		`command = ${quoteToml(server.command)}`,
+		`args = [${server.args.map(quoteToml).join(", ")}]`
+	];
+	if (server.env && Object.keys(server.env).length > 0) {
+		const env = Object.entries(server.env).map(([key, value]) => `${quoteToml(key)} = ${quoteToml(value)}`).join(", ");
+		lines.push(`env = { ${env} }`);
+	}
+	lines.push(END);
+	return lines.join("\n");
+}
+function serverPreview(server) {
+	return [
+		"+ mcp_servers.wot-ui",
+		`  command: ${server.command}`,
+		`  args: ${server.args.join(" ")}`,
+		...Object.keys(server.env ?? {}).map((key) => `  env.${key}: [REDACTED]`)
+	];
+}
+function managedPattern() {
+	return /* @__PURE__ */ new RegExp(`${START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+}
+function parseTomlDocument(content, path) {
+	try {
+		return parse$1(content);
+	} catch (error) {
+		throw new Error(`Invalid TOML in ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+function isRecord$1(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function getServerEntry(config) {
+	const servers = config.mcp_servers;
+	return isRecord$1(servers) ? servers["wot-ui"] : void 0;
+}
+function optionalStringArray(value) {
+	if (value === void 0) return void 0;
+	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+}
+function parseServer(entry) {
+	if (!isRecord$1(entry) || typeof entry.command !== "string" || !Array.isArray(entry.args) || !entry.args.every((argument) => typeof argument === "string")) return void 0;
+	const env = entry.env;
+	if (env !== void 0 && (!isRecord$1(env) || !Object.values(env).every((value) => typeof value === "string"))) return void 0;
+	if (entry.enabled !== void 0 && typeof entry.enabled !== "boolean") return void 0;
+	const enabledTools = optionalStringArray(entry.enabled_tools);
+	const disabledTools = optionalStringArray(entry.disabled_tools);
+	if (enabledTools === null || disabledTools === null) return void 0;
+	return {
+		server: {
+			command: entry.command,
+			args: entry.args,
+			...env === void 0 ? {} : { env }
+		},
+		...entry.enabled === void 0 ? {} : { enabled: entry.enabled },
+		...enabledTools === void 0 ? {} : { enabledTools },
+		...disabledTools === void 0 ? {} : { disabledTools }
+	};
+}
+function serverProblem(actual) {
+	if (!actual) return "The wot-ui entry is not a supported stdio server definition";
+	if (actual.enabled === false) return "The wot-ui MCP server is disabled in Codex";
+	const missingEnabledTools = actual.enabledTools === void 0 ? [] : REQUIRED_WOT_MCP_TOOLS.filter((tool) => !actual.enabledTools.includes(tool));
+	const disabledRequiredTools = actual.disabledTools === void 0 ? [] : REQUIRED_WOT_MCP_TOOLS.filter((tool) => actual.disabledTools.includes(tool));
+	const unavailableTools = [...new Set([...missingEnabledTools, ...disabledRequiredTools])];
+	if (unavailableTools.length > 0) return `The Codex tool filters exclude required tools: ${unavailableTools.join(", ")}`;
+}
+function serverMatches(actual, expected) {
+	return !serverProblem(actual) && actual?.server.command === expected.command && JSON.stringify(actual.server.args) === JSON.stringify(expected.args) && JSON.stringify(actual.server.env ?? {}) === JSON.stringify(expected.env ?? {});
+}
+function assertNoExternalChildTables(content, path) {
+	if (CHILD_TABLE_PATTERN.test(content)) throw new Error(`Cannot safely manage nested mcp_servers.wot-ui TOML tables in ${path}; migrate them into the main server definition first`);
+}
+function assertManagedEntryOwnsServer(content, path) {
+	const managed = managedPattern().exec(content)?.[0];
+	if (!managed) return;
+	if (!isDeepStrictEqual(getServerEntry(parseTomlDocument(content, path)), getServerEntry(parseTomlDocument(managed, path)))) throw new Error(`Cannot safely manage mcp_servers.wot-ui settings outside the open-wot managed block in ${path}`);
+}
+function assertInstalledEntry(content, block, path) {
+	if (!isDeepStrictEqual(getServerEntry(parseTomlDocument(content, path)), getServerEntry(parseTomlDocument(block, path)))) throw new Error(`Cannot safely install mcp_servers.wot-ui while external settings remain in ${path}`);
+}
+function replaceServerSection(content, block) {
+	const pattern = managedPattern();
+	if (pattern.test(content)) return content.replace(pattern, () => block);
+	const tableMatch = TABLE_PATTERN.exec(content);
+	if (tableMatch) {
+		const start = tableMatch.index;
+		const remainder = content.slice(start + tableMatch[0].length);
+		const nextTable = /\n\s*\[[^\]]+\]/.exec(remainder);
+		const end = nextTable ? start + tableMatch[0].length + nextTable.index + 1 : content.length;
+		return `${content.slice(0, start)}${block}\n${content.slice(end)}`;
+	}
+	if (!content) return `${block}\n`;
+	return `${content}${content.endsWith("\n") ? "" : "\n"}${block}\n`;
+}
+function removeServerSection(content) {
+	const match = managedPattern().exec(content);
+	if (!match) return content;
+	let end = match.index + match[0].length;
+	if (content.startsWith("\r\n", end)) end += 2;
+	else if (content.startsWith("\n", end)) end += 1;
+	return `${content.slice(0, match.index)}${content.slice(end)}`;
+}
+var TomlMcpClientAdapter = class {
+	id;
+	displayName;
+	supportedScopes;
+	options;
+	constructor(options) {
+		this.options = options;
+		this.id = options.id;
+		this.displayName = options.displayName;
+		this.supportedScopes = options.supportedScopes;
+	}
+	async detect(context) {
+		const configLocations = this.supportedScopes.map((scope) => this.options.configPath(context, scope));
+		const executable = await findExecutable(this.options.executableNames, context);
+		const hasConfig = (await Promise.all(configLocations.map((path) => access(path).then(() => true).catch(() => false)))).some(Boolean);
+		return {
+			client: this.id,
+			displayName: this.displayName,
+			installed: Boolean(executable) || hasConfig,
+			...executable ? { executable } : {},
+			supportedScopes: this.supportedScopes,
+			configLocations,
+			preferredMethod: "config-file"
+		};
+	}
+	async inspect(context) {
+		const path = this.options.configPath(context, context.scope);
+		const content = await readOptional$1(path);
+		if (content === void 0) return {
+			client: this.id,
+			displayName: this.displayName,
+			scope: context.scope,
+			path,
+			exists: false,
+			configured: false,
+			matches: false
+		};
+		try {
+			const entry = getServerEntry(parseTomlDocument(content, path));
+			const parsedServer = parseServer(entry);
+			const problem = entry === void 0 ? void 0 : serverProblem(parsedServer);
+			return {
+				client: this.id,
+				displayName: this.displayName,
+				scope: context.scope,
+				path,
+				exists: true,
+				configured: entry !== void 0,
+				matches: serverMatches(parsedServer, context.server),
+				...parsedServer ? { server: parsedServer.server } : {},
+				...problem ? { problem } : {}
+			};
+		} catch (error) {
+			return {
+				client: this.id,
+				displayName: this.displayName,
+				scope: context.scope,
+				path,
+				exists: true,
+				configured: managedPattern().test(content) || TABLE_PATTERN.test(content),
+				matches: false,
+				problem: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	async planInstall(context) {
+		const path = this.options.configPath(context, context.scope);
+		const before = await readOptional$1(path);
+		parseTomlDocument(before ?? "", path);
+		assertNoExternalChildTables(before ?? "", path);
+		assertManagedEntryOwnsServer(before ?? "", path);
+		const block = createBlock(context.server);
+		const after = replaceServerSection(before ?? "", block);
+		assertInstalledEntry(after, block, path);
+		return {
+			id: `${this.id}-${context.scope}-install`,
+			summary: `Configure wot-ui MCP for ${this.displayName}`,
+			changes: before === after ? [] : [{
+				type: "write-file",
+				path,
+				allowedRoot: context.scope === "project" ? context.cwd : context.homeDir,
+				before,
+				after,
+				reason: "Add or update the managed mcp_servers.wot-ui TOML section",
+				preview: serverPreview(context.server)
+			}],
+			warnings: [],
+			requiresConfirmation: before !== after
+		};
+	}
+	async planRemove(context) {
+		const path = this.options.configPath(context, context.scope);
+		const before = await readOptional$1(path);
+		const beforeDocument = before === void 0 ? void 0 : parseTomlDocument(before, path);
+		if (before !== void 0 && managedPattern().test(before)) {
+			assertNoExternalChildTables(before, path);
+			assertManagedEntryOwnsServer(before, path);
+		}
+		const after = before === void 0 ? void 0 : removeServerSection(before);
+		if (after !== void 0) {
+			const afterDocument = parseTomlDocument(after, path);
+			if (managedPattern().test(before) && getServerEntry(afterDocument) !== void 0) throw new Error(`Cannot safely remove mcp_servers.wot-ui because external settings remain in ${path}`);
+		}
+		return {
+			id: `${this.id}-${context.scope}-remove`,
+			summary: `Remove wot-ui MCP from ${this.displayName}`,
+			changes: before === void 0 || before === after ? [] : [{
+				type: "write-file",
+				path,
+				allowedRoot: context.scope === "project" ? context.cwd : context.homeDir,
+				before,
+				after,
+				reason: "Remove only the open-wot managed TOML section",
+				preview: ["- mcp_servers.wot-ui"]
+			}],
+			warnings: beforeDocument !== void 0 && getServerEntry(beforeDocument) !== void 0 && !managedPattern().test(before) ? ["A non-managed wot-ui section was found and left unchanged."] : [],
+			requiresConfirmation: before !== void 0 && before !== after
+		};
+	}
+	async print(context) {
+		return createBlock(context.server);
+	}
+	async verifyRegistration(context, state, options) {
+		if (this.options.verifyRegistration) return this.options.verifyRegistration(context, state, options);
+		return {
+			status: "unsupported",
+			message: `${this.displayName} does not expose a stable CLI registration status check`,
+			action: `Restart ${this.displayName} and confirm wot-ui in its MCP server panel.`
+		};
+	}
+};
+
+//#endregion
+//#region src/mcp/clients/codex.ts
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+}
+const codexAdapter = new TomlMcpClientAdapter({
+	id: "codex",
+	displayName: "Codex",
+	executableNames: ["codex"],
+	supportedScopes: ["project", "user"],
+	configPath: (context, scope) => scope === "project" ? resolve(context.cwd, ".codex", "config.toml") : join(context.homeDir, ".codex", "config.toml"),
+	verifyRegistration: async (context, state, options) => {
+		const executable = await findExecutable(["codex"], context);
+		if (!executable) return {
+			status: "unknown",
+			message: "Codex executable was not found; registration could not be verified",
+			action: "Open Codex in this project and inspect MCP server settings."
+		};
+		const result = await runClientCommand(executable, [
+			"mcp",
+			"get",
+			"wot-ui",
+			"--json"
+		], {
+			...context,
+			timeoutMs: options?.timeoutMs
+		});
+		const output = clientCommandOutput(result);
+		const command = `${executable} mcp get wot-ui --json`;
+		if (result.timedOut || result.error) return {
+			status: "failed",
+			message: result.error || "Codex registration check failed",
+			action: "Retry codex mcp get wot-ui --json and inspect the client process if it still fails.",
+			command
+		};
+		if (result.exitCode === 0 && !result.timedOut) try {
+			const registration = JSON.parse(result.stdout);
+			if (!isRecord(registration) || registration.name !== "wot-ui") return {
+				status: "unknown",
+				message: "Codex returned an unreadable registration response",
+				command
+			};
+			if (registration.enabled === false) return {
+				status: "failed",
+				message: "Codex recognizes the wot-ui MCP server, but it is disabled",
+				action: "Enable the wot-ui MCP server in Codex and retry the doctor command.",
+				command
+			};
+			const enabledTools = stringArray(registration.enabled_tools);
+			const disabledTools = stringArray(registration.disabled_tools);
+			const unavailableTools = REQUIRED_WOT_MCP_TOOLS.filter((tool) => enabledTools !== void 0 && !enabledTools.includes(tool) || disabledTools?.includes(tool));
+			if (unavailableTools.length > 0) return {
+				status: "failed",
+				message: `Codex tool filters exclude required tools: ${unavailableTools.join(", ")}`,
+				action: "Update the wot-ui MCP tool filters in Codex and retry the doctor command.",
+				command
+			};
+			return {
+				status: "ready",
+				message: "Codex recognizes the wot-ui MCP server",
+				command
+			};
+		} catch {
+			return {
+				status: "unknown",
+				message: "Codex returned an unreadable registration response",
+				command
+			};
+		}
+		if (/pending approval|approval.*pending|untrusted|not trusted|trust (?:this )?(?:project|workspace)/i.test(output)) return {
+			status: "pending",
+			message: "Codex requires project trust or MCP approval",
+			action: "Trust this project in Codex, restart it, and verify the wot-ui MCP server.",
+			command
+		};
+		if (context.scope === "project" && state.matches && /no mcp server named ["']?wot-ui["']? found/i.test(output)) return {
+			status: "pending",
+			message: "Codex is not loading the project-level wot-ui MCP configuration yet",
+			action: "Trust this project by opening it in Codex, then restart Codex and retry the doctor command.",
+			command
+		};
+		return {
+			status: "failed",
+			message: "Codex did not recognize the wot-ui MCP server",
+			action: "Run codex mcp get wot-ui --json and inspect the configured scope.",
+			command
+		};
+	}
+});
+
+//#endregion
+//#region src/mcp/clients/cursor.ts
+const cursorAdapter = new JsonMcpClientAdapter({
+	id: "cursor",
+	displayName: "Cursor",
+	executableNames: ["cursor-agent", "cursor"],
+	supportedScopes: ["project", "user"],
+	configPath: (context, scope) => scope === "project" ? resolve(context.cwd, ".cursor", "mcp.json") : join(context.homeDir, ".cursor", "mcp.json"),
+	serverKey: "mcpServers"
+});
+
+//#endregion
+//#region src/mcp/clients/vscode.ts
+const vscodeAdapter = new JsonMcpClientAdapter({
+	id: "vscode",
+	displayName: "VS Code",
+	executableNames: ["code"],
+	supportedScopes: ["project"],
+	configPath: (context) => resolve(context.cwd, ".vscode", "mcp.json"),
+	serverKey: "servers"
+});
+
+//#endregion
+//#region src/mcp/clients/index.ts
+const mcpClientAdapters = [
+	claudeAdapter,
+	cursorAdapter,
+	vscodeAdapter,
+	codexAdapter
+];
+function getMcpClientAdapter(id) {
+	const adapter = mcpClientAdapters.find((candidate) => candidate.id === id);
+	if (!adapter) throw new Error(`Unsupported MCP client: ${id}`);
+	return adapter;
+}
+
+//#endregion
+//#region src/application/mcp-onboarding.ts
+function createMcpServerDefinition(pin) {
+	const version$1 = typeof pin === "string" ? pin : pin ? version : void 0;
+	return {
+		command: "npx",
+		args: [
+			"-y",
+			version$1 ? `${name}@${version$1}` : name,
+			"mcp"
+		]
+	};
+}
+function createDetectContext(options = {}) {
+	return {
+		cwd: resolve(options.cwd ?? process.cwd()),
+		homeDir: options.homeDir ?? homedir(),
+		env: options.env ?? process.env,
+		platform: options.platform ?? process.platform
+	};
+}
+function createPlanContext(options = {}) {
+	return {
+		...createDetectContext(options),
+		scope: options.scope ?? "project",
+		server: createMcpServerDefinition(options.pin)
+	};
+}
+async function detectMcpClients(options = {}) {
+	const context = createDetectContext(options);
+	return Promise.all(mcpClientAdapters.map((adapter) => adapter.detect(context)));
+}
+async function resolveMcpAdapters(client, options = {}) {
+	if (client === "all") return mcpClientAdapters.filter((adapter) => adapter.supportedScopes.includes(options.scope ?? "project"));
+	if (client !== "auto") return [getMcpClientAdapter(client)];
+	const detected = (await detectMcpClients(options)).filter((item) => item.installed && item.supportedScopes.includes(options.scope ?? "project")).map((item) => getMcpClientAdapter(item.client));
+	if (detected.length === 0) throw new Error("No supported MCP client detected. Pass --client explicitly.");
+	if (detected.length > 1) throw new Error(`Multiple MCP clients detected (${detected.map((item) => item.id).join(", ")}). Pass --client or --client all.`);
+	return detected;
+}
+async function inspectMcpClients(client, options = {}) {
+	const adapters = await resolveMcpAdapters(client, options);
+	const context = createPlanContext(options);
+	return Promise.all(adapters.map((adapter) => adapter.inspect(context)));
+}
+async function planMcpInstall(client, options = {}) {
+	const adapters = await resolveMcpAdapters(client, options);
+	const context = createPlanContext(options);
+	return Promise.all(adapters.map((adapter) => adapter.planInstall(context)));
+}
+async function planMcpRemove(client, options = {}) {
+	const adapters = await resolveMcpAdapters(client, options);
+	const context = createPlanContext(options);
+	return Promise.all(adapters.map((adapter) => adapter.planRemove(context)));
+}
+async function printMcpConfig(client, options = {}) {
+	return getMcpClientAdapter(client).print(createPlanContext(options));
+}
+function toPublicClientConfigState(state) {
+	const secretValues = Object.values(state.server?.env ?? {});
+	return {
+		...state,
+		server: void 0,
+		problem: state.problem ? redactSensitiveText(state.problem, secretValues) : void 0
+	};
+}
+
+//#endregion
+//#region src/application/agent-onboarding.ts
+const INSTRUCTIONS_START = "<!-- open-wot agent instructions start -->";
+const INSTRUCTIONS_END = "<!-- open-wot agent instructions end -->";
+function findManagedInstructionsRange(content) {
+	const start = content.indexOf(INSTRUCTIONS_START);
+	const endMarker = content.indexOf(INSTRUCTIONS_END);
+	if (start === -1 && endMarker === -1) return void 0;
+	const hasDuplicateStart = start !== -1 && content.includes(INSTRUCTIONS_START, start + 42);
+	const hasDuplicateEnd = endMarker !== -1 && content.includes(INSTRUCTIONS_END, endMarker + 40);
+	if (start === -1 || endMarker === -1 || endMarker < start || hasDuplicateStart || hasDuplicateEnd) throw new Error("Malformed open-wot Agent instructions markers; expected exactly one ordered start/end pair");
+	return {
+		start,
+		end: endMarker + 40
+	};
+}
+async function exists(path) {
+	return access(path).then(() => true).catch(() => false);
+}
+async function readOptional(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+}
+function getSkillTarget(projectDir, client) {
+	return client === "claude" ? resolve(projectDir, ".claude", "skills", "wot-ui-v2") : resolve(projectDir, ".agents", "skills", "wot-ui-v2");
+}
+function getInstructionsTarget(projectDir, client) {
+	return resolve(projectDir, client === "claude" ? "CLAUDE.md" : "AGENTS.md");
+}
+function createAgentInstructions(client) {
+	return [
+		INSTRUCTIONS_START,
+		"## Wot UI Agent Instructions",
+		"",
+		`Before generating or modifying wot-ui component code, read the project Skill at \`${client === "claude" ? ".claude/skills/wot-ui-v2/SKILL.md" : ".agents/skills/wot-ui-v2/SKILL.md"}\` and query the configured \`wot-ui\` MCP server for version-accurate APIs and examples.`,
+		"",
+		INSTRUCTIONS_END
+	].join("\n");
+}
+function updateManagedInstructions(content, block) {
+	const range = findManagedInstructionsRange(content);
+	if (range) return `${content.slice(0, range.start)}${block}${content.slice(range.end)}`;
+	if (!content) return `${block}\n`;
+	return `${content}${content.endsWith("\n\n") ? "" : content.endsWith("\n") ? "\n" : "\n\n"}${block}\n`;
+}
+function removeManagedInstructions(content) {
+	const range = findManagedInstructionsRange(content);
+	if (!range) return content;
+	return `${content.slice(0, range.start)}${content.slice(range.end)}`;
+}
+function resolveBundledWotSkill() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const found = [
+		resolve(here, "../../skills/wot-ui-v2"),
+		resolve(here, "../skills/wot-ui-v2"),
+		resolve(process.cwd(), "skills/wot-ui-v2")
+	].find((path) => existsSync(join(path, "SKILL.md")));
+	if (!found) throw new Error("Bundled wot-ui-v2 Skill not found");
+	return found;
+}
+async function listFiles(root, current = root) {
+	if (!await exists(current)) return [];
+	const entries = await readdir(current, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		if (entry.name === ".DS_Store") continue;
+		const path = join(current, entry.name);
+		if (entry.isDirectory()) files.push(...await listFiles(root, path));
+		else if (entry.isFile()) files.push(relative(root, path));
+	}
+	return files.sort();
+}
+async function planSkillInstall(projectDir, client) {
+	const source = resolveBundledWotSkill();
+	const target = getSkillTarget(projectDir, client);
+	const changes = [];
+	const warnings = [];
+	for (const file of await listFiles(source)) {
+		const sourcePath = join(source, file);
+		const targetPath = join(target, file);
+		const before = await readOptional(targetPath);
+		const after = await readFile(sourcePath, "utf8");
+		if (before !== void 0 && before !== after) {
+			warnings.push(`Modified Skill file left unchanged: ${targetPath}`);
+			continue;
+		}
+		if (before !== after) changes.push({
+			type: "write-file",
+			path: targetPath,
+			allowedRoot: projectDir,
+			before,
+			after,
+			reason: `Install bundled Skill file ${file}`,
+			preview: [before === void 0 ? "+ install bundled Skill file" : "~ refresh bundled Skill file"]
+		});
+	}
+	return {
+		id: `${client}-skill-install`,
+		summary: `Install wot-ui-v2 Skill for ${client}`,
+		changes,
+		warnings,
+		requiresConfirmation: changes.length > 0
+	};
+}
+async function planSkillRemove(projectDir, client) {
+	const source = resolveBundledWotSkill();
+	const target = getSkillTarget(projectDir, client);
+	const changes = [];
+	const warnings = [];
+	for (const file of await listFiles(source)) {
+		const path = join(target, file);
+		const before = await readOptional(path);
+		if (before === void 0) continue;
+		if (before !== await readFile(join(source, file), "utf8")) {
+			warnings.push(`Modified Skill file left unchanged: ${path}`);
+			continue;
+		}
+		changes.push({
+			type: "delete-file",
+			path,
+			allowedRoot: projectDir,
+			before,
+			reason: `Remove installed Skill file ${file}`,
+			preview: ["- remove bundled Skill file"]
+		});
+	}
+	return {
+		id: `${client}-skill-remove`,
+		summary: `Remove wot-ui-v2 Skill for ${client}`,
+		changes,
+		warnings,
+		requiresConfirmation: changes.length > 0
+	};
+}
+async function planInstructions(projectDir, client, remove) {
+	const path = getInstructionsTarget(projectDir, client);
+	const before = await readOptional(path);
+	const after = remove ? removeManagedInstructions(before ?? "") : updateManagedInstructions(before ?? "", createAgentInstructions(client));
+	return {
+		id: `${client}-instructions-${remove ? "remove" : "install"}`,
+		summary: `${remove ? "Remove" : "Install"} managed Agent instructions for ${client}`,
+		changes: (before ?? "") === after ? [] : [{
+			type: "write-file",
+			path,
+			allowedRoot: projectDir,
+			before,
+			after,
+			reason: `${remove ? "Remove" : "Update"} only the open-wot managed instructions block`,
+			preview: [remove ? "- open-wot managed instructions block" : "+ open-wot managed instructions block"]
+		}],
+		warnings: [],
+		requiresConfirmation: (before ?? "") !== after
+	};
+}
+async function planAgentInit(options) {
+	const context = createDetectContext(options);
+	const plans = [];
+	if (options.capabilities.includes("mcp")) plans.push(...await planMcpInstall(options.client, options));
+	if (options.capabilities.includes("skill")) plans.push(await planSkillInstall(context.cwd, options.client));
+	if (options.capabilities.includes("instructions")) plans.push(await planInstructions(context.cwd, options.client, false));
+	return mergeChangePlans(`Initialize wot-ui Agent integration for ${options.client}`, plans);
+}
+async function planAgentRemove(options) {
+	const context = createDetectContext(options);
+	const plans = [];
+	if (options.capabilities.includes("mcp")) plans.push(...await planMcpRemove(options.client, options));
+	if (options.capabilities.includes("skill")) plans.push(await planSkillRemove(context.cwd, options.client));
+	if (options.capabilities.includes("instructions")) plans.push(await planInstructions(context.cwd, options.client, true));
+	return mergeChangePlans(`Remove wot-ui Agent integration for ${options.client}`, plans);
+}
+async function inspectAgentSkill(projectDir, client) {
+	const source = resolveBundledWotSkill();
+	const target = getSkillTarget(projectDir, client);
+	const skillInstalled = await exists(join(target, "SKILL.md"));
+	let skillMatches = skillInstalled;
+	for (const file of await listFiles(source)) if (await readOptional(join(target, file)) !== await readFile(join(source, file), "utf8")) {
+		skillMatches = false;
+		break;
+	}
+	return {
+		installed: skillInstalled,
+		matches: skillMatches
+	};
+}
+async function inspectAgentInstructions(projectDir, client) {
+	const instructions = await readOptional(getInstructionsTarget(projectDir, client));
+	if (!instructions) return { installed: false };
+	try {
+		return { installed: Boolean(findManagedInstructionsRange(instructions)) };
+	} catch {
+		return { installed: false };
+	}
+}
+
+//#endregion
+//#region src/application/mcp-handshake.ts
+function resolveMcpSpawnCommand(command, platform) {
+	const executable = platform === "win32" && !/\.(?:exe|cmd|bat|com)$/i.test(command) ? `${command}.cmd` : command;
+	return {
+		executable,
+		useShell: platform === "win32" && /\.(?:cmd|bat)$/i.test(executable)
+	};
+}
+async function waitForChildClose(child, timeoutMs) {
+	if (child.exitCode !== null || child.signalCode !== null) return true;
+	return new Promise((resolve$1) => {
+		let timer;
+		const onClose = () => {
+			clearTimeout(timer);
+			resolve$1(true);
+		};
+		timer = setTimeout(() => {
+			child.off("close", onClose);
+			resolve$1(false);
+		}, timeoutMs);
+		timer.unref();
+		child.once("close", onClose);
+	});
+}
+async function terminate(child, platform, deadline) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	if (platform === "win32" && child.pid) spawn("taskkill", [
+		"/pid",
+		String(child.pid),
+		"/T",
+		"/F"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	}).once("error", () => child.kill("SIGTERM"));
+	else child.kill("SIGTERM");
+	if (await waitForChildClose(child, Math.min(1e3, Math.max(0, deadline - Date.now())))) return;
+	child.kill("SIGKILL");
+	const forceWaitMs = Math.min(500, Math.max(0, deadline - Date.now()));
+	if (forceWaitMs > 0) await waitForChildClose(child, forceWaitMs);
+}
+async function verifyMcpHandshake(server, options = {}) {
+	const startedAt = Date.now();
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	const deadline = startedAt + timeoutMs;
+	const platform = options.platform ?? process.platform;
+	const spawnCommand = resolveMcpSpawnCommand(server.command, platform);
+	const child = spawn(spawnCommand.executable, server.args, {
+		cwd: options.cwd ?? process.cwd(),
+		env: {
+			...process.env,
+			...options.env,
+			...server.env,
+			WOT_DISABLE_UPDATE_CHECK: "1"
+		},
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true,
+		shell: spawnCommand.useShell
+	});
+	const pending = /* @__PURE__ */ new Map();
+	const readBuffer = new ReadBuffer();
+	let stderr = "";
+	let nextId = 1;
+	const failPending = (error) => {
+		for (const request of pending.values()) request.reject(error);
+		pending.clear();
+	};
+	child.stdout.on("data", (chunk) => {
+		try {
+			readBuffer.append(chunk);
+			while (true) {
+				const message = readBuffer.readMessage();
+				if (message === null) break;
+				if ("id" in message && typeof message.id === "number") {
+					const request = pending.get(message.id);
+					if (!request) continue;
+					pending.delete(message.id);
+					if ("error" in message) request.reject(/* @__PURE__ */ new Error(`${message.error.code}: ${message.error.message}`));
+					else if ("result" in message) request.resolve(message.result);
+					else request.reject(/* @__PURE__ */ new Error("Unexpected JSON-RPC request from MCP server"));
+				}
+			}
+		} catch (error) {
+			failPending(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+	child.stderr.on("data", (chunk) => {
+		stderr = `${stderr}${chunk.toString("utf8")}`.slice(-4e3);
+	});
+	child.once("error", failPending);
+	child.stdin.once("error", failPending);
+	child.once("exit", (code, signal) => {
+		failPending(/* @__PURE__ */ new Error(`MCP server exited before verification completed (${signal ?? code ?? "unknown"})`));
+	});
+	const sendRequest = (method, params) => {
+		const id = nextId++;
+		return new Promise((resolve$1, reject) => {
+			pending.set(id, {
+				resolve: resolve$1,
+				reject
+			});
+			child.stdin.write(serializeMessage({
+				jsonrpc: "2.0",
+				id,
+				method,
+				params
+			}));
+		});
+	};
+	const timeout = new Promise((_, reject) => {
+		setTimeout(() => reject(/* @__PURE__ */ new Error(`MCP handshake timed out after ${timeoutMs}ms`)), timeoutMs).unref();
+	});
+	try {
+		const initialize = await Promise.race([sendRequest("initialize", {
+			protocolVersion: LATEST_PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: {
+				name: "open-wot-doctor",
+				version: "1.0.0"
+			}
+		}), timeout]);
+		child.stdin.write(serializeMessage({
+			jsonrpc: "2.0",
+			method: "notifications/initialized",
+			params: {}
+		}));
+		const toolResult = await Promise.race([sendRequest("tools/list", {}), timeout]);
+		const tools = Array.isArray(toolResult.tools) ? toolResult.tools.flatMap((tool) => {
+			if (!tool || typeof tool !== "object") return [];
+			const name$1 = tool.name;
+			return typeof name$1 === "string" ? [name$1] : [];
+		}) : [];
+		const serverInfo = initialize.serverInfo && typeof initialize.serverInfo === "object" ? initialize.serverInfo : {};
+		return {
+			ok: true,
+			protocolVersion: typeof initialize.protocolVersion === "string" ? initialize.protocolVersion : void 0,
+			serverName: typeof serverInfo.name === "string" ? serverInfo.name : void 0,
+			serverVersion: typeof serverInfo.version === "string" ? serverInfo.version : void 0,
+			tools,
+			durationMs: Date.now() - startedAt,
+			...stderr.trim() ? { stderr: stderr.trim() } : {}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			tools: [],
+			durationMs: Date.now() - startedAt,
+			error: error instanceof Error ? error.message : String(error),
+			...stderr.trim() ? { stderr: stderr.trim() } : {}
+		};
+	} finally {
+		failPending(/* @__PURE__ */ new Error("MCP verification finished"));
+		await terminate(child, platform, deadline);
+	}
+}
+
+//#endregion
+//#region src/application/mcp-doctor.ts
+function validateMcpHandshake(result) {
+	if (!result.ok) return {
+		status: "fail",
+		message: result.error ? redactSensitiveText(result.error) : "MCP handshake failed"
+	};
+	if (result.serverName !== "wot-ui") return {
+		status: "fail",
+		message: `Expected MCP server name "wot-ui", received "${result.serverName ?? "<missing>"}"`
+	};
+	const missingTools = REQUIRED_WOT_MCP_TOOLS.filter((tool) => !result.tools.includes(tool));
+	if (missingTools.length > 0) return {
+		status: "fail",
+		message: `MCP server is missing required tools: ${missingTools.join(", ")}`
+	};
+	return { status: "pass" };
+}
+function overallStatus(config, handshake, registration) {
+	if (config === "fail" || handshake === "fail" || registration.status === "failed") return "failed";
+	if (registration.status === "pending") return "action-required";
+	if (registration.status === "ready") return "ready";
+	return "server-ready";
+}
+async function doctorMcpClients(client, options = {}) {
+	const deadline = Date.now() + (options.timeoutMs ?? 1e4);
+	const adapters = await resolveMcpAdapters(client, options);
+	const context = createPlanContext(options);
+	const states = await Promise.all(adapters.map((adapter) => adapter.inspect(context)));
+	return Promise.all(adapters.map(async (adapter, index) => {
+		const state = states[index];
+		const configStatus = state.matches ? "pass" : "fail";
+		if (!state.matches || !state.server) return {
+			client: adapter.id,
+			displayName: adapter.displayName,
+			overall: "failed",
+			config: {
+				status: configStatus,
+				state
+			},
+			handshake: {
+				status: "skipped",
+				message: state.problem ?? "wot-ui MCP configuration is missing or differs from the expected definition"
+			},
+			clientRegistration: {
+				status: "skipped",
+				message: "Client registration was not checked because the configuration is invalid or missing"
+			}
+		};
+		const handshakeTimeoutMs = Math.max(1, deadline - Date.now());
+		const handshakeResult = await verifyMcpHandshake(state.server, {
+			cwd: context.cwd,
+			env: context.env,
+			platform: context.platform,
+			timeoutMs: handshakeTimeoutMs
+		});
+		const handshake = validateMcpHandshake(handshakeResult);
+		const registrationTimeoutMs = deadline - Date.now();
+		const registration = registrationTimeoutMs > 0 ? await getMcpClientAdapter(adapter.id).verifyRegistration(context, state, { timeoutMs: registrationTimeoutMs }) : {
+			status: "failed",
+			message: `Doctor timed out after ${options.timeoutMs ?? 1e4}ms before client registration could be verified`,
+			action: "Retry with a larger --timeout value if the MCP server needs more time to start."
+		};
+		return {
+			client: adapter.id,
+			displayName: adapter.displayName,
+			overall: overallStatus(configStatus, handshake.status, registration),
+			config: {
+				status: configStatus,
+				state
+			},
+			handshake: {
+				...handshake,
+				result: handshakeResult
+			},
+			clientRegistration: registration
+		};
+	}));
+}
+function formatMcpDoctorReport(report) {
+	const secretValues = Object.values(report.config.state.server?.env ?? {});
+	const handshakeDetail = redactSensitiveText(report.handshake.result?.ok ? `${report.handshake.result.tools.length} tools, ${report.handshake.result.durationMs}ms${report.handshake.message ? `; ${report.handshake.message}` : ""}` : report.handshake.message ?? report.handshake.result?.error ?? "not run", secretValues);
+	return [
+		`${report.overall} ${report.displayName} (${report.client})`,
+		`  ${report.config.status} config: ${report.config.state.path}`,
+		`  ${report.handshake.status} handshake: ${handshakeDetail}`,
+		`  ${report.clientRegistration.status} client: ${redactSensitiveText(report.clientRegistration.message, secretValues)}`,
+		...report.clientRegistration.action ? [`  action: ${report.clientRegistration.action}`] : []
+	].join("\n");
+}
+function mcpDoctorExitCode(reports) {
+	if (reports.some((report) => report.overall === "failed")) return 1;
+	if (reports.some((report) => report.overall === "action-required")) return 2;
+	return 0;
+}
+function toPublicMcpDoctorReport(report) {
+	const secretValues = Object.values(report.config.state.server?.env ?? {});
+	const handshakeResult = report.handshake.result ? {
+		...report.handshake.result,
+		error: report.handshake.result.error ? redactSensitiveText(report.handshake.result.error, secretValues) : void 0,
+		stderr: void 0
+	} : void 0;
+	return {
+		...report,
+		config: {
+			...report.config,
+			state: {
+				...report.config.state,
+				server: void 0,
+				problem: report.config.state.problem ? redactSensitiveText(report.config.state.problem, secretValues) : void 0
+			}
+		},
+		handshake: {
+			...report.handshake,
+			message: report.handshake.message ? redactSensitiveText(report.handshake.message, secretValues) : void 0,
+			result: handshakeResult
+		},
+		clientRegistration: {
+			...report.clientRegistration,
+			message: redactSensitiveText(report.clientRegistration.message, secretValues)
+		}
+	};
+}
+
+//#endregion
 //#region src/utils/output.ts
 function writeStdout(message) {
 	process.stdout.write(message);
@@ -37,6 +1623,12 @@ function printError(message, format) {
 	});
 	else console.error(formatLogMessage("error", message));
 }
+function parsePositiveIntegerOption(value, defaultValue, optionName) {
+	if (value === void 0) return defaultValue;
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error(`Invalid ${optionName} value "${value}". Expected a positive integer.`);
+	return parsed;
+}
 function getComponentLabel(component) {
 	return `${component.name} ${component.nameZh}`;
 }
@@ -51,6 +1643,193 @@ function formatCssVars(cssVars) {
 	}));
 }
 
+//#endregion
+//#region src/commands/agent.ts
+function parseCapabilities(value) {
+	const capabilities = (value ?? "mcp,skill,instructions").split(",").map((item) => item.trim()).filter(Boolean);
+	const supported = [
+		"mcp",
+		"skill",
+		"instructions"
+	];
+	if (capabilities.length === 0 || capabilities.some((item) => !supported.includes(item))) throw new Error("Unsupported --with value. Use mcp, skill, instructions, or a comma-separated combination.");
+	return [...new Set(capabilities)];
+}
+function parseScope$1(value) {
+	const scope = value ?? "project";
+	if (!isMcpScope(scope)) throw new Error(`Unsupported scope "${scope}". Use project or user.`);
+	return scope;
+}
+function parseClient$1(value) {
+	const client = value ?? "auto";
+	if (client === "auto" || client === "all" || isMcpClientId(client)) return client;
+	throw new Error(`Unsupported Agent client "${client}".`);
+}
+function addOptions(command, defaultClient = "auto") {
+	return command.option("--client <client>", "Agent client: auto, all, claude, cursor, vscode, codex", defaultClient).option("--scope <scope>", "MCP configuration scope: project or user", "project").option("--with <capabilities>", "capabilities: mcp,skill,instructions", "mcp,skill,instructions").option("--cwd <directory>", "project directory", process.cwd()).option("--format <format>", "output format: text or json", "text").option("--pin [version]", "pin @wot-ui/cli to the current or specified version");
+}
+async function runSafely$1(options, action) {
+	try {
+		await action();
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error), options.format === "json" ? "json" : "text");
+		process.exitCode = 1;
+	}
+}
+async function resolveClients(options) {
+	return (await resolveMcpAdapters(parseClient$1(options.client), {
+		cwd: options.cwd,
+		scope: parseScope$1(options.scope),
+		pin: options.pin
+	})).map((adapter) => adapter.id);
+}
+async function inspectCapabilities(client, capabilities, options) {
+	const projectDir = options.cwd ?? process.cwd();
+	const [mcpStates, skill, instructions] = await Promise.all([
+		capabilities.includes("mcp") ? inspectMcpClients(client, {
+			cwd: options.cwd,
+			scope: parseScope$1(options.scope),
+			pin: options.pin
+		}) : Promise.resolve([]),
+		capabilities.includes("skill") ? inspectAgentSkill(projectDir, client) : Promise.resolve(void 0),
+		capabilities.includes("instructions") ? inspectAgentInstructions(projectDir, client) : Promise.resolve(void 0)
+	]);
+	const mcp = mcpStates[0];
+	return {
+		client,
+		capabilities: {
+			mcp: capabilities.includes("mcp") ? {
+				status: mcp?.matches ? "pass" : "fail",
+				state: mcp ? toPublicClientConfigState(mcp) : void 0
+			} : { status: "skipped" },
+			skill: capabilities.includes("skill") ? {
+				status: skill?.matches ? "pass" : "fail",
+				installed: skill?.installed,
+				matches: skill?.matches
+			} : { status: "skipped" },
+			instructions: capabilities.includes("instructions") ? {
+				status: instructions?.installed ? "pass" : "fail",
+				installed: instructions?.installed
+			} : { status: "skipped" }
+		}
+	};
+}
+function reportFailed(report) {
+	return Object.values(report.capabilities).some((capability) => capability.status === "fail");
+}
+function reportNeedsAction(report) {
+	return Object.values(report.capabilities).some((capability) => capability.status === "action-required");
+}
+function reportHasWarning(report) {
+	return Object.values(report.capabilities).some((capability) => capability.status === "warning");
+}
+function formatCapabilityReport(report) {
+	const state = reportFailed(report) ? "incomplete" : reportNeedsAction(report) ? "action-required" : reportHasWarning(report) ? "warning" : "ok";
+	const capabilities = Object.entries(report.capabilities).map(([name$1, capability]) => `${name$1}=${capability.status}`).join(" ");
+	return `${state} ${report.client}: ${capabilities}`;
+}
+function registerAgentCommand(program) {
+	const agent = program.command("agent").description("Connect AI agents to wot-ui MCP and Skills");
+	addOptions(agent.command("init").description("Initialize MCP, Skill, and Agent instructions")).option("--dry-run", "preview changes without writing files").option("-y, --yes", "apply changes without prompting").action(async (options) => runSafely$1(options, async () => {
+		const clients = await resolveClients(options);
+		const capabilities = parseCapabilities(options.with);
+		const plan = mergeChangePlans("Initialize wot-ui Agent integration", await Promise.all(clients.map((client) => planAgentInit({
+			client,
+			capabilities,
+			cwd: options.cwd,
+			scope: parseScope$1(options.scope),
+			pin: options.pin
+		}))));
+		if (!options.dryRun) {
+			if (!await confirmChangePlan(plan, {
+				yes: options.yes,
+				cwd: options.cwd
+			})) {
+				writeLine("Cancelled.");
+				return;
+			}
+			await applyChangePlan(plan);
+		}
+		if (options.format === "json") writeJson({
+			dryRun: Boolean(options.dryRun),
+			plan: toPublicChangePlan(plan, options.cwd)
+		});
+		else writeLine(`${formatChangePlan(plan, options.cwd)}${options.dryRun ? "\nDry run: no files were changed." : ""}`);
+	}));
+	agent.command("list").description("List supported and detected AI clients").option("--cwd <directory>", "project directory", process.cwd()).option("--format <format>", "output format: text or json", "text").action(async (options) => runSafely$1(options, async () => {
+		const clients = await detectMcpClients({ cwd: options.cwd });
+		if (options.format === "json") writeJson({ clients });
+		else writeLine(clients.map((client) => `${client.installed ? "detected" : "not detected"} ${client.displayName} (${client.client})`).join("\n"));
+	}));
+	addOptions(agent.command("status").description("Inspect MCP, Skill, and instructions"), "all").action(async (options) => runSafely$1(options, async () => {
+		const clients = await resolveClients(options);
+		const capabilities = parseCapabilities(options.with);
+		const reports = await Promise.all(clients.map((client) => inspectCapabilities(client, capabilities, options)));
+		if (options.format === "json") writeJson({ clients: reports });
+		else writeLine(reports.map(formatCapabilityReport).join("\n"));
+		if (reports.some(reportFailed)) process.exitCode = 1;
+	}));
+	addOptions(agent.command("doctor").description("Validate Agent files and perform a real MCP handshake")).option("--timeout <milliseconds>", "total doctor timeout in milliseconds", "10000").action(async (options) => runSafely$1(options, async () => {
+		const clients = await resolveClients(options);
+		const capabilities = parseCapabilities(options.with);
+		const timeoutMs = parsePositiveIntegerOption(options.timeout, 1e4, "--timeout");
+		const deadline = Date.now() + timeoutMs;
+		const reports = [];
+		for (const client of clients) {
+			const report = await inspectCapabilities(client, capabilities, options);
+			const mcpCheck = report.capabilities.mcp;
+			if (mcpCheck.status !== "skipped") {
+				const [doctor] = await doctorMcpClients(client, {
+					cwd: options.cwd,
+					scope: parseScope$1(options.scope),
+					pin: options.pin,
+					timeoutMs: Math.max(1, deadline - Date.now())
+				});
+				const status = doctor.overall === "failed" ? "fail" : doctor.overall === "action-required" ? "action-required" : doctor.overall === "server-ready" ? "warning" : "pass";
+				report.capabilities.mcp = {
+					...mcpCheck,
+					status,
+					doctor: toPublicMcpDoctorReport(doctor)
+				};
+			}
+			reports.push(report);
+		}
+		if (options.format === "json") writeJson({ clients: reports });
+		else writeLine(reports.flatMap((report) => {
+			const doctor = report.capabilities.mcp.doctor;
+			return [formatCapabilityReport(report), ...doctor ? [formatMcpDoctorReport(doctor)] : []];
+		}).join("\n"));
+		if (reports.some(reportFailed)) process.exitCode = 1;
+		else if (reports.some(reportNeedsAction)) process.exitCode = 2;
+	}));
+	addOptions(agent.command("remove").description("Remove managed MCP, Skill, and instructions")).option("--dry-run", "preview changes without writing files").option("-y, --yes", "apply changes without prompting").action(async (options) => runSafely$1(options, async () => {
+		const clients = await resolveClients(options);
+		const capabilities = parseCapabilities(options.with);
+		const plan = mergeChangePlans("Remove wot-ui Agent integration", await Promise.all(clients.map((client) => planAgentRemove({
+			client,
+			capabilities,
+			cwd: options.cwd,
+			scope: parseScope$1(options.scope),
+			pin: options.pin
+		}))));
+		if (!options.dryRun) {
+			if (!await confirmChangePlan(plan, {
+				yes: options.yes,
+				cwd: options.cwd
+			})) {
+				writeLine("Cancelled.");
+				return;
+			}
+			await applyChangePlan(plan);
+		}
+		if (options.format === "json") writeJson({
+			dryRun: Boolean(options.dryRun),
+			plan: toPublicChangePlan(plan, options.cwd)
+		});
+		else writeLine(`${formatChangePlan(plan, options.cwd)}${options.dryRun ? "\nDry run: no files were changed." : ""}`);
+	}));
+}
+
 //#endregion
 //#region src/commands/changelog.ts
 function registerChangelogCommand(program) {
@@ -304,10 +2083,10 @@ function registerLintCommand(program) {
 //#endregion
 //#region src/commands/list.ts
 function registerListCommand(program) {
-	addQueryOptions(program.command("list").description("List available wot-ui components")).action((options) => {
+	addQueryOptions(program.command("list").argument("[keyword]", "Filter by component name, tag, category, or description").description("List available wot-ui components")).action((keyword, options) => {
 		const query = normalizeQueryOptions(options);
 		try {
-			const components = listComponents(query.version);
+			const components = filterComponents(listComponents(query.version), keyword);
 			if (query.format === "json") {
 				writeJson({ components });
 				return;
@@ -322,11 +2101,125 @@ function registerListCommand(program) {
 
 //#endregion
 //#region src/commands/mcp.ts
+function outputFormat(value) {
+	return value === "json" ? "json" : "text";
+}
+function parseClient(value, fallback = "auto") {
+	const client = value ?? fallback;
+	if (client === "auto" || client === "all" || isMcpClientId(client)) return client;
+	throw new Error(`Unsupported MCP client "${client}". Use claude, cursor, vscode, codex, auto, or all.`);
+}
+function parseScope(value) {
+	const scope = value ?? "project";
+	if (!isMcpScope(scope)) throw new Error(`Unsupported scope "${scope}". Use project or user.`);
+	return scope;
+}
+function addCommonOptions(command, defaultClient = "auto") {
+	return command.option("--client <client>", "MCP client: auto, all, claude, cursor, vscode, codex", defaultClient).option("--scope <scope>", "configuration scope: project or user", "project").option("--cwd <directory>", "project directory", process.cwd()).option("--format <format>", "output format: text or json", "text").option("--pin [version]", "pin @wot-ui/cli to the current or specified version");
+}
+async function runSafely(options, action) {
+	try {
+		await action();
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error), outputFormat(options.format));
+		process.exitCode = 1;
+	}
+}
+async function startServer() {
+	const { startMcpServer } = await import("./server-B4R7zC43.mjs");
+	await startMcpServer();
+}
 function registerMcpCommand(program) {
-	program.command("mcp").description("Start the wot-ui MCP server").action(async () => {
-		const { startMcpServer } = await import("./server-CbSmyhFy.mjs");
-		await startMcpServer();
-	});
+	const mcp = program.command("mcp").description("Start or manage the wot-ui MCP server").action(startServer);
+	mcp.command("serve").description("Start the wot-ui MCP server explicitly").action(startServer);
+	addCommonOptions(mcp.command("init").description("Configure wot-ui MCP for an AI client")).option("--dry-run", "preview changes without writing files").option("-y, --yes", "apply changes without prompting").action(async (options) => runSafely(options, async () => {
+		const client = parseClient(options.client);
+		const scope = parseScope(options.scope);
+		const plan = mergeChangePlans("Initialize wot-ui MCP integration", await planMcpInstall(client, {
+			cwd: options.cwd,
+			scope,
+			pin: options.pin
+		}));
+		if (!options.dryRun) {
+			if (!await confirmChangePlan(plan, {
+				yes: options.yes,
+				cwd: options.cwd
+			})) {
+				writeLine("Cancelled.");
+				return;
+			}
+			await applyChangePlan(plan);
+		}
+		if (outputFormat(options.format) === "json") writeJson({
+			dryRun: Boolean(options.dryRun),
+			plan: toPublicChangePlan(plan, options.cwd)
+		});
+		else writeLine(`${formatChangePlan(plan, options.cwd)}${options.dryRun ? "\nDry run: no files were changed." : ""}`);
+	}));
+	mcp.command("list").description("List supported MCP clients and detection results").option("--cwd <directory>", "project directory", process.cwd()).option("--format <format>", "output format: text or json", "text").action(async (options) => runSafely(options, async () => {
+		const detections = await detectMcpClients({ cwd: options.cwd });
+		if (outputFormat(options.format) === "json") writeJson({ clients: detections });
+		else writeLine(detections.map((item) => `${item.installed ? "detected" : "not detected"} ${item.displayName} (${item.client})\n  ${item.configLocations.join("\n  ")}`).join("\n"));
+	}));
+	addCommonOptions(mcp.command("status").description("Inspect wot-ui MCP client configuration"), "all").action(async (options) => runSafely(options, async () => {
+		const states = await inspectMcpClients(parseClient(options.client, "all"), {
+			cwd: options.cwd,
+			scope: parseScope(options.scope),
+			pin: options.pin
+		});
+		const publicStates = states.map(toPublicClientConfigState);
+		if (outputFormat(options.format) === "json") writeJson({ clients: publicStates });
+		else writeLine(publicStates.map((state) => `${state.matches ? "ok" : state.configured ? "mismatch" : "missing"} ${state.displayName}: ${state.path}${state.problem ? `\n  ${state.problem}` : ""}`).join("\n"));
+		if (states.some((state) => !state.matches)) process.exitCode = 1;
+	}));
+	addCommonOptions(mcp.command("remove").description("Remove the managed wot-ui MCP configuration")).option("--dry-run", "preview changes without writing files").option("-y, --yes", "apply changes without prompting").action(async (options) => runSafely(options, async () => {
+		const plan = mergeChangePlans("Remove wot-ui MCP integration", await planMcpRemove(parseClient(options.client), {
+			cwd: options.cwd,
+			scope: parseScope(options.scope),
+			pin: options.pin
+		}));
+		if (!options.dryRun) {
+			if (!await confirmChangePlan(plan, {
+				yes: options.yes,
+				cwd: options.cwd
+			})) {
+				writeLine("Cancelled.");
+				return;
+			}
+			await applyChangePlan(plan);
+		}
+		if (outputFormat(options.format) === "json") writeJson({
+			dryRun: Boolean(options.dryRun),
+			plan: toPublicChangePlan(plan, options.cwd)
+		});
+		else writeLine(`${formatChangePlan(plan, options.cwd)}${options.dryRun ? "\nDry run: no files were changed." : ""}`);
+	}));
+	addCommonOptions(mcp.command("doctor").description("Validate configuration and perform a real MCP handshake")).option("--timeout <milliseconds>", "total doctor timeout in milliseconds", "10000").action(async (options) => runSafely(options, async () => {
+		const reports = await doctorMcpClients(parseClient(options.client), {
+			cwd: options.cwd,
+			scope: parseScope(options.scope),
+			pin: options.pin,
+			timeoutMs: parsePositiveIntegerOption(options.timeout, 1e4, "--timeout")
+		});
+		if (outputFormat(options.format) === "json") writeJson({ clients: reports.map(toPublicMcpDoctorReport) });
+		else writeLine(reports.map(formatMcpDoctorReport).join("\n"));
+		const exitCode = mcpDoctorExitCode(reports);
+		if (exitCode > 0) process.exitCode = exitCode;
+	}));
+	addCommonOptions(mcp.command("print").description("Print the MCP configuration snippet")).action(async (options) => runSafely(options, async () => {
+		const client = parseClient(options.client);
+		if (client === "auto" || client === "all") throw new Error("mcp print requires one explicit client");
+		const config = await printMcpConfig(client, {
+			cwd: options.cwd,
+			scope: parseScope(options.scope),
+			pin: options.pin
+		});
+		if (outputFormat(options.format) === "json") writeJson({
+			client,
+			config
+		});
+		else writeLine(config);
+	}));
 }
 
 //#endregion
@@ -406,6 +2299,7 @@ function createCliProgram() {
 	registerUsageCommand(program);
 	registerLintCommand(program);
 	registerMcpCommand(program);
+	registerAgentCommand(program);
 	return program;
 }