agent-skills-standard 2.7.2 → 2.7.4

package/dist/index.js

@@ -40,20 +40,20 @@ js_yaml = __toESM(js_yaml);
 let zod = require("zod");
 let node_path = require("node:path");
 node_path = __toESM(node_path);
+let child_process = require("child_process");
 let os = require("os");
 os = __toESM(os);
 let node_stream = require("node:stream");
 let node_child_process = require("node:child_process");
 let node_os = require("node:os");
 node_os = __toESM(node_os);
-let child_process = require("child_process");
 let fs = require("fs");
 fs = __toESM(fs);
 let crypto = require("crypto");
 crypto = __toESM(crypto);
 var package_default = {
 	name: "agent-skills-standard",
-	version: "2.7.2",
+	version: "2.7.4",
 	description: "A CLI to manage and sync AI agent skills standard for Cursor, Claude, Copilot, Windsurf, and more.",
 	main: "dist/index.js",
 	bin: {
@@ -1436,6 +1436,11 @@ var McpConfigSchema = zod.z.object({
 	scope: McpScopeSchema,
 	prompted: zod.z.boolean(),
 	version: zod.z.string().optional(),
+	via: zod.z.enum([
+		"auto",
+		"npx",
+		"global"
+	]).optional(),
 	snippets: zod.z.boolean().optional()
 });
 var SkillConfigSchema = zod.z.object({
@@ -1479,6 +1484,7 @@ var MCP_FIELD_KEYS = [
 	"scope",
 	"prompted",
 	"version",
+	"via",
 	"snippets"
 ];
 var DEFAULT_SDLC_SUPPORT_CATEGORIES = ["quality-engineering"];
@@ -3629,11 +3635,10 @@ var LockfileService = class {
 * agent-skills-standard-mcp`, which would silently pull whatever is latest
 * on npm at the moment the agent starts.
 *
-* Bump this alongside mcp/package.json's version when releasing — there is
-* no automated sync between the two (mirrors how skills/metadata.json
-* category versions are maintained today).
+* Bumped automatically by `scripts/release-mcp.ts` when the MCP package is
+* released and gated in CI, so this pin always matches `mcp/package.json`.
 */
-var MCP_COMPATIBLE_VERSION = "0.6.1";
+var MCP_COMPATIBLE_VERSION = "0.8.1";
 /**
 * Minimum `agent-skills-standard-mcp` version required for session retrospectives.
 */
@@ -3655,6 +3660,10 @@ function escapeTomlString(value) {
 }
 //#endregion
 //#region src/services/utils/codexTomlMcp.ts
+/** Structural equality for the server entry we generate and re-read. */
+function sameMcpEntry(a, b) {
+	return a.command === b.command && a.args.length === b.args.length && a.args.every((arg, index) => arg === b.args[index]);
+}
 var HEADER_RE = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/;
 function normalizeKey(raw) {
 	return raw.split(".").map((s) => s.trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1")).join(".");
@@ -3692,6 +3701,61 @@ function renderTomlMcpServer(name, entry) {
 function hasTomlMcpServer(content, name) {
 	return findOurRanges(content.split("\n"), name).length > 0;
 }
+function parseTomlStringLiteral(raw) {
+	const value = raw.trim();
+	if (value.length < 2) return null;
+	if (value.startsWith("\"") && value.endsWith("\"")) return value.slice(1, -1).replace(/\\(["\\])/g, "$1");
+	if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+	return null;
+}
+var STRING_TOKEN_RE = /("(?:\\.|[^"\\])*"|'[^']*')/g;
+/**
+* Reads the `[mcp_servers.<name>]` table emitted by `renderTomlMcpServer`.
+* Returns null when the table is absent or either `command` / `args` is
+* missing or malformed. Only the exact table block is inspected, so
+* unrelated tables (and subtables) are ignored.
+*/
+function readTomlMcpServer(content, name) {
+	const lines = content.split("\n");
+	const base = `mcp_servers.${name}`;
+	let start = -1;
+	for (let i = 0; i < lines.length; i += 1) {
+		const m = HEADER_RE.exec(lines[i]);
+		if (m && normalizeKey(m[1]) === base) {
+			start = i;
+			break;
+		}
+	}
+	if (start === -1) return null;
+	let command = null;
+	let args = null;
+	for (let i = start + 1; i < lines.length; i += 1) {
+		const line = lines[i];
+		if (HEADER_RE.test(line)) break;
+		const commandMatch = /^\s*command\s*=\s*((?:"(?:\\.|[^"\\])*")|(?:'[^']*'))\s*(?:#.*)?$/.exec(line);
+		if (commandMatch) {
+			command = parseTomlStringLiteral(commandMatch[1]);
+			continue;
+		}
+		const argsMatch = /^\s*args\s*=\s*\[(.*)\]\s*(?:#.*)?$/.exec(line);
+		if (argsMatch) {
+			const tokens = argsMatch[1].match(STRING_TOKEN_RE) ?? [];
+			if (argsMatch[1].replace(STRING_TOKEN_RE, "").replace(/[\s,]/g, "").length > 0) return null;
+			const parsed = [];
+			for (const token of tokens) {
+				const value = parseTomlStringLiteral(token);
+				if (value === null) return null;
+				parsed.push(value);
+			}
+			args = parsed;
+		}
+	}
+	if (command === null || args === null) return null;
+	return {
+		command,
+		args
+	};
+}
 function removeTomlMcpServer(content, name) {
 	const lines = content.split("\n");
 	const ranges = findOurRanges(lines, name);
@@ -3727,6 +3791,10 @@ function upsertTomlMcpServer(content, name, entry) {
 //#region src/services/McpConfigService.ts
 var SERVER_NAME = "agent-skills-standard";
 var PACKAGE = "agent-skills-standard-mcp";
+/** Sentinel: the `ags-mcp` command is not on PATH (no manifest fallback allowed). */
+var GLOBAL_BINARY_MISSING = Symbol("ags-mcp-missing");
+var SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+var SEMVER_EXACT = /^\d+\.\d+\.\d+$/;
 var getTargets = (home = os.default.homedir(), platform = process.platform) => {
 	const out = {};
 	for (const agent of Object.values(Agent)) {
@@ -3749,6 +3817,27 @@ var getTargets = (home = os.default.homedir(), platform = process.platform) => {
 	return out;
 };
 /**
+* Command used to run `ags-mcp --version`.
+*
+* On Windows npm exposes the binary as a `.cmd` shim, which `execFileSync`
+* cannot spawn directly (ENOENT), so the probe goes through `cmd /c` — the
+* same shape the generated global launch entry uses. POSIX keeps the bare
+* binary with no shell.
+*/
+function globalVersionProbeCommand(platform = process.platform) {
+	return platform === "win32" ? {
+		command: "cmd",
+		args: [
+			"/c",
+			"ags-mcp",
+			"--version"
+		]
+	} : {
+		command: "ags-mcp",
+		args: ["--version"]
+	};
+}
+/**
 * Owns all MCP-config writes. Pure logic — never prompts the user directly.
 * The caller (sync command, mcp subcommand) supplies a `userScopePrompt`
 * callback that is invoked ONLY when the user has chosen `scope: 'user'` AND
@@ -3761,18 +3850,143 @@ var McpConfigService = class {
 	* <package>`, which would otherwise pull whatever is latest on npm the
 	* moment the agent starts — an unpinned update-drift surface (AST07).
 	* Pass an explicit `version` (from `mcp.version` in .skillsrc) to override.
+	*
+	* `via` selects the launch strategy (default `auto`). A global install
+	* avoids the ~0.6s npx resolution overhead on every client spawn, but a
+	* stale global must never be silently preferred over the pin.
 	*/
-	buildEntry(version) {
+	buildEntry(opts = {}) {
+		const version = opts.version || "0.8.1";
+		const via = opts.via ?? "auto";
+		const platform = this.testPlatform ?? process.platform;
+		if (via === "global" || via === "auto" && platform !== "win32" && this.detectGlobalVersion() === version) return platform === "win32" ? {
+			command: "cmd",
+			args: ["/c", "ags-mcp"]
+		} : {
+			command: "ags-mcp",
+			args: []
+		};
 		return {
 			command: "npx",
-			args: ["-y", `${PACKAGE}@${version || "0.6.1"}`]
+			args: [
+				"-y",
+				"--prefer-offline",
+				`${PACKAGE}@${version}`
+			]
 		};
 	}
+	/**
+	* Version reported by a globally installed `ags-mcp`, or `null` when the
+	* binary is missing/unusable.
+	*
+	* Two probes, in order:
+	*  1. `ags-mcp --version` — authoritative and install-manager agnostic.
+	*  2. the manifest under `npm root -g` — required for servers published
+	*     before `--version` existed, where probe 1 either prints nothing or
+	*     times out because the stdio server starts normally instead.
+	* A missing binary never falls through: an installed manifest alone does
+	* not prove the command is on the client's PATH. POSIX surfaces that as
+	* ENOENT; win32 (which probes through `cmd /c`) proves it with
+	* `where.exe ags-mcp` before allowing the legacy manifest fallback.
+	*/
+	detectGlobalVersion() {
+		const binaryVersion = this.probeGlobalBinaryVersion();
+		if (binaryVersion === GLOBAL_BINARY_MISSING) return null;
+		if (binaryVersion) return binaryVersion;
+		if (!this.probeGlobalBinaryOnPath()) return null;
+		return this.probeGlobalManifestVersion();
+	}
+	/**
+	* Whether `ags-mcp` resolves on PATH. POSIX misses already surface as
+	* ENOENT in the version probe, so only win32 needs the explicit check.
+	*/
+	probeGlobalBinaryOnPath() {
+		if ((this.testPlatform ?? process.platform) !== "win32") return true;
+		if (this.testGlobalPathProbe) return this.testGlobalPathProbe();
+		try {
+			const output = (0, child_process.execFileSync)("where.exe", ["ags-mcp"], {
+				encoding: "utf8",
+				timeout: 2e3,
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			});
+			return String(output).trim().length > 0;
+		} catch {
+			return false;
+		}
+	}
+	/** `ags-mcp --version`, or the sentinel when the command is not on PATH. */
+	probeGlobalBinaryVersion() {
+		try {
+			if (this.testGlobalVersionProbe) return this.testGlobalVersionProbe();
+			const { command, args } = globalVersionProbeCommand(this.testPlatform ?? process.platform);
+			const output = (0, child_process.execFileSync)(command, args, {
+				encoding: "utf8",
+				timeout: 2e3,
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			});
+			const firstLine = String(output).split("\n")[0].trim();
+			return SEMVER_PREFIX.test(firstLine) ? firstLine : null;
+		} catch (err) {
+			return err.code === "ENOENT" ? GLOBAL_BINARY_MISSING : null;
+		}
+	}
+	/** Version field of the globally installed manifest, purely from disk. */
+	probeGlobalManifestVersion() {
+		if (this.testGlobalManifestProbe) return this.testGlobalManifestProbe();
+		const isWindows = (this.testPlatform ?? process.platform) === "win32";
+		try {
+			const globalRoot = String((0, child_process.execFileSync)(isWindows ? "npm.cmd" : "npm", ["root", "-g"], {
+				encoding: "utf8",
+				timeout: 5e3,
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				],
+				...isWindows ? { shell: true } : {}
+			})).trim();
+			if (!globalRoot) return null;
+			const manifestPath = path.default.join(globalRoot, PACKAGE, "package.json");
+			if (!fs_extra.default.pathExistsSync(manifestPath)) return null;
+			const manifest = fs_extra.default.readJsonSync(manifestPath);
+			return typeof manifest.version === "string" && SEMVER_EXACT.test(manifest.version) ? manifest.version : null;
+		} catch {
+			return null;
+		}
+	}
 	/** For testing: allows overriding the home directory. */
 	testHome = null;
 	setHomeForTesting(home) {
 		this.testHome = home;
 	}
+	/** For testing: allows overriding the detected platform. */
+	testPlatform = null;
+	setPlatformForTesting(platform) {
+		this.testPlatform = platform;
+	}
+	/** For testing: allows overriding the global-version probe. */
+	testGlobalVersionProbe = null;
+	setGlobalVersionProbeForTesting(fn) {
+		this.testGlobalVersionProbe = fn;
+	}
+	/** For testing: allows overriding the `npm root -g` manifest probe. */
+	testGlobalManifestProbe = null;
+	setGlobalManifestProbeForTesting(fn) {
+		this.testGlobalManifestProbe = fn;
+	}
+	/** For testing: allows overriding the win32 PATH-resolution probe. */
+	testGlobalPathProbe = null;
+	setGlobalPathProbeForTesting(fn) {
+		this.testGlobalPathProbe = fn;
+	}
 	getTargets() {
 		return getTargets(this.testHome ?? void 0);
 	}
@@ -3791,7 +4005,10 @@ var McpConfigService = class {
 		const { rootDir, agents, mcp } = opts;
 		if (mcp.scope === "disabled" || !mcp.enabled) return report;
 		const TARGETS = this.getTargets();
-		const entry = this.buildEntry(mcp.version);
+		const entry = this.buildEntry({
+			version: mcp.version,
+			via: mcp.via
+		});
 		if (mcp.scope === "snippets-only" || mcp.snippets) await this.generateSnippets(rootDir, agents, entry, report);
 		if (mcp.scope === "snippets-only") return report;
 		for (const agent of agents) {
@@ -3868,12 +4085,45 @@ var McpConfigService = class {
 			const target = TARGETS[agent];
 			if (!target) continue;
 			const row = { agent };
-			if (target.projectFile) row.project = await this.hasOurEntry(path.default.join(opts.rootDir, target.projectFile), target);
-			if (target.userFile) row.user = await this.hasOurEntry(target.userFile, target);
+			if (target.projectFile) {
+				const abs = path.default.join(opts.rootDir, target.projectFile);
+				row.project = await this.hasOurEntry(abs, target);
+				row.projectEntry = await this.readEntry(abs, target);
+			}
+			if (target.userFile) {
+				row.user = await this.hasOurEntry(target.userFile, target);
+				row.userEntry = await this.readEntry(target.userFile, target);
+			}
 			out.push(row);
 		}
 		return out;
 	}
+	/** Parse the entry this service wrote for `SERVER_NAME`, if present. */
+	async readEntry(abs, target) {
+		if (!await fs_extra.default.pathExists(abs)) return null;
+		if (target.format === "toml") return readTomlMcpServer(await fs_extra.default.readFile(abs, "utf8"), SERVER_NAME);
+		const data = await fs_extra.default.readJson(abs).catch(() => null);
+		if (!data) return null;
+		const container = this.getNestedValue(data, target.key);
+		if (!container) return null;
+		if (target.shape === "map") {
+			if (typeof container !== "object" || Array.isArray(container)) return null;
+			return this.normalizeEntry(container[SERVER_NAME]);
+		}
+		if (!Array.isArray(container)) return null;
+		const item = container.find((entry) => entry.name === SERVER_NAME);
+		return this.normalizeEntry(item?.transport);
+	}
+	normalizeEntry(value) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+		const record = value;
+		if (typeof record.command !== "string") return null;
+		const args = Array.isArray(record.args) ? record.args.map((arg) => String(arg)) : [];
+		return {
+			command: record.command,
+			args
+		};
+	}
 	async generateSnippets(rootDir, agents, entry, report) {
 		const dir = path.default.join(rootDir, "mcp-config-snippets");
 		await fs_extra.default.ensureDir(dir);
@@ -3973,7 +4223,11 @@ var McpConfigService = class {
 		if (!data) return false;
 		const container = this.getNestedValue(data, target.key);
 		if (!container) return false;
-		if (target.shape === "map") return Boolean(container[SERVER_NAME]);
+		if (target.shape === "map") {
+			if (typeof container !== "object" || Array.isArray(container)) return false;
+			return Boolean(container[SERVER_NAME]);
+		}
+		if (!Array.isArray(container)) return false;
 		return container.some((item) => item.name === SERVER_NAME);
 	}
 	buildFreshDoc(target, entry) {
@@ -4076,6 +4330,10 @@ function defaultDoctorDeps() {
 			rootDir,
 			agents
 		}),
+		buildMcpEntry: (cfg) => mcp.buildEntry({
+			version: cfg.mcp?.version,
+			via: cfg.mcp?.via
+		}),
 		hookStatus: (rootDir, agents) => hooks.status({
 			rootDir,
 			agents
@@ -4209,13 +4467,48 @@ var DoctorService = class {
 		if (!config.mcp?.enabled || scope !== "project" && scope !== "user") return check("mcp", "skip", "MCP disabled in .skillsrc");
 		const rows = await this.deps.mcpStatus(rootDir, agents);
 		const missing = rows.filter((r) => scope === "project" ? !r.project : !(r.project || r.user)).map((r) => r.agent);
-		if (missing.length === 0) return check("mcp", "ok", `registered for ${rows.map((r) => r.agent).join(", ") || "no MCP-capable agents"}`);
-		return check("mcp", "fail", `MCP server not registered for: ${missing.join(", ")}`, {
+		if (missing.length > 0) return check("mcp", "fail", `MCP server not registered for: ${missing.join(", ")}`, {
 			description: `register MCP for ${missing.join(", ")}`,
 			apply: async () => {
 				for (const agent of missing) await this.deps.installMcp(rootDir, agent, config);
 			}
 		});
+		const expected = this.deps.buildMcpEntry ? this.deps.buildMcpEntry(config) : new McpConfigService().buildEntry({
+			version: config.mcp.version,
+			via: config.mcp.via
+		});
+		const pin = config.mcp.version ?? "0.8.1";
+		const drifted = [];
+		for (const row of rows) {
+			if (scope === "project") {
+				if (row.project && row.projectEntry && !sameMcpEntry(row.projectEntry, expected)) drifted.push({
+					agent: row.agent,
+					scope: "project",
+					entry: row.projectEntry
+				});
+				continue;
+			}
+			if (row.project && row.projectEntry && !sameMcpEntry(row.projectEntry, expected)) drifted.push({
+				agent: row.agent,
+				scope: "project",
+				entry: row.projectEntry
+			});
+			if (row.user && row.userEntry && !sameMcpEntry(row.userEntry, expected)) drifted.push({
+				agent: row.agent,
+				scope: "user",
+				entry: row.userEntry
+			});
+		}
+		if (drifted.length > 0) {
+			const driftedAgents = [...new Set(drifted.map((item) => item.agent))];
+			return check("mcp", "warn", `MCP pin drift: ${drifted.map((item) => `${item.agent} ${item.scope} pins ${item.entry.command}${item.entry.args.length ? ` ${item.entry.args.join(" ")}` : ""} but this CLI expects agent-skills-standard-mcp@${pin}`).join("; ")}`, {
+				description: `refresh MCP entry for ${driftedAgents.join(", ")}`,
+				apply: async () => {
+					for (const agent of driftedAgents) await this.deps.installMcp(rootDir, agent, config);
+				}
+			});
+		}
+		return check("mcp", "ok", `registered for ${rows.map((r) => r.agent).join(", ") || "no MCP-capable agents"}`);
 	}
 	async hooksCheck(rootDir, agents) {
 		const rows = await this.deps.hookStatus(rootDir, agents);
@@ -10330,26 +10623,94 @@ var VALID_SCOPES = [
 	"snippets-only",
 	"disabled"
 ];
+var VALID_VIAS = [
+	"auto",
+	"npx",
+	"global"
+];
+function parseVia(value) {
+	return typeof value === "string" && VALID_VIAS.includes(value) ? value : null;
+}
+function defaultGlobalInstaller(spec) {
+	if (process.platform === "win32") {
+		(0, child_process.execFileSync)("npm.cmd", [
+			"i",
+			"-g",
+			spec
+		], {
+			stdio: "inherit",
+			shell: true
+		});
+		return;
+	}
+	(0, child_process.execFileSync)("npm", [
+		"i",
+		"-g",
+		spec
+	], { stdio: "inherit" });
+}
+function formatEntry(entry) {
+	if (!entry) return "(none)";
+	return entry.args.length ? `${entry.command} ${entry.args.join(" ")}` : entry.command;
+}
 /**
 * `ags mcp <action>` — manage the optional MCP server integration without
 * editing `.skillsrc` by hand.
 *
 * Sub-actions:
-*   status                 Show current scope, enabled state, and which configs are wired
-*   enable                 Set mcp.enabled=true; install configs at the configured scope
+*   status                 Show scope, launch mode, resolved command, and installed configs
+*   enable [--via=...]     Set mcp.enabled=true; optionally install configs at the configured scope
 *   disable                Set mcp.enabled=false; existing configs are NOT removed
 *   scope <scope>          Change scope: project | user | snippets-only | disabled
-*   install [--scope=...]  One-shot install at the given (or configured) scope
+*   via <auto|npx|global>  Change launch mode (default: auto)
+*   install [--scope=...] [--via=...]
+*                          One-shot install at the given (or configured) scope/mode
 *   uninstall [--from=...] Remove our entry from configs (project | user | all)
-*   snippets               Generate fresh snippet files in ./mcp-config-snippets/
+*   snippets [--via=...]   Generate fresh snippet files in ./mcp-config-snippets/
+*
+* `enable` also installs `agent-skills-standard-mcp@<pin>` globally and
+* verifies the reported version whenever the effective launch mode is
+* `global` (saved mode or `--via global`) — no extra flag required.
+* `--install-global` remains as an explicit trigger for the same install.
 */
 var McpCommand = class {
 	configService;
 	mcpService;
+	globalInstaller = defaultGlobalInstaller;
 	constructor(configService, mcpService) {
 		this.configService = configService ?? new ConfigService();
 		this.mcpService = mcpService ?? new McpConfigService();
 	}
+	/** For testing: replace the global npm installer (never run real npm in unit tests). */
+	setGlobalInstallerForTesting(fn) {
+		this.globalInstaller = fn ?? defaultGlobalInstaller;
+	}
+	/**
+	* Install the pinned package globally and prove the installed binary
+	* reports that exact pin. Returns false (with exit code 1) when either
+	* step fails so callers can abort before persisting or writing configs.
+	*/
+	ensureGlobalPin(pin) {
+		const spec = `${PACKAGE}@${pin}`;
+		try {
+			this.globalInstaller(spec);
+		} catch {
+			console.log(picocolors.default.red(`❌ Global install failed. Run manually:`));
+			console.log(picocolors.default.gray(`   npm i -g ${spec}`));
+			process.exitCode = 1;
+			return false;
+		}
+		const detected = this.mcpService.detectGlobalVersion();
+		if (detected !== pin) {
+			console.log(picocolors.default.red(`❌ Global ags-mcp reports ${detected ?? "no version"} but the CLI pin is ${pin}.`));
+			if (!detected) console.log(picocolors.default.gray("   Probe found no usable version: check that npm's global bin directory is on PATH and that `ags-mcp --version` prints the expected pin."));
+			console.log(picocolors.default.gray(`   Run manually: npm i -g ${spec}`));
+			process.exitCode = 1;
+			return false;
+		}
+		console.log(picocolors.default.green(`✅ Global ags-mcp ${pin} installed and verified.`));
+		return true;
+	}
 	async run(action, options = {}) {
 		const config = await this.configService.loadConfig();
 		if (!config) {
@@ -10360,13 +10721,14 @@ var McpCommand = class {
 		const agents = config.agents ?? [];
 		switch (action) {
 			case "status": return this.actionStatus(config, cwd);
-			case "enable": return this.actionEnable(config);
+			case "enable": return this.actionEnable(config, agents, cwd, options);
 			case "disable": return this.actionDisable(config);
 			case "scope": return this.actionScope(config, options);
+			case "via": return this.actionVia(config, options);
 			case "install": return this.actionInstall(config, agents, cwd, options);
 			case "uninstall": return this.actionUninstall(config, agents, cwd, options);
-			case "snippets": return this.actionSnippets(config, agents, cwd);
-			default: console.log(picocolors.default.red(`Unknown action: ${action}`), "\nValid actions: status, enable, disable, scope, install, uninstall, snippets");
+			case "snippets": return this.actionSnippets(config, agents, cwd, options);
+			default: console.log(picocolors.default.red(`Unknown action: ${action}`), "\nValid actions: status, enable, disable, scope, via, install, uninstall, snippets");
 		}
 	}
 	async actionStatus(config, cwd) {
@@ -10379,20 +10741,50 @@ var McpCommand = class {
 		console.log(picocolors.default.bold("\n🔌 MCP integration status\n"));
 		console.log(`  enabled : ${mcp.enabled ? picocolors.default.green("yes") : picocolors.default.gray("no")}`);
 		console.log(`  scope   : ${picocolors.default.cyan(mcp.scope)}`);
+		console.log(`  via     : ${picocolors.default.cyan(mcp.via ?? "auto")}`);
 		console.log(`  prompted: ${mcp.prompted ? "yes" : "no"}`);
 		if (mcp.version) console.log(`  version : ${mcp.version}`);
+		const pin = mcp.version ?? "0.8.1";
+		const entry = this.mcpService.buildEntry({
+			version: mcp.version,
+			via: mcp.via
+		});
+		const launch = entry.args.length ? `${entry.command} ${entry.args.join(" ")}` : entry.command;
+		console.log(`  launch  : ${picocolors.default.gray(launch)}`);
+		console.log(`  pin     : ${pin}`);
+		const detected = this.mcpService.detectGlobalVersion();
+		console.log(`  global  : ${detected ? picocolors.default.green(detected) : picocolors.default.gray("not found")}`);
+		if (detected && detected !== pin) {
+			console.log(picocolors.default.yellow(`\n⚠️  Global ags-mcp is ${detected} but the CLI pin is ${pin}; "auto" will use npx until they match.`));
+			console.log(picocolors.default.gray(`   Update with: npm i -g ${PACKAGE}@${pin}`));
+		}
 		if (rows.length === 0) {
 			console.log(picocolors.default.gray("\n  (no agents configured)"));
 			return;
 		}
 		console.log("\n  Per-agent installation state:");
 		let installedAnywhere = false;
+		const drift = [];
 		for (const row of rows) {
-			const project = row.project === void 0 ? "—" : row.project ? picocolors.default.green("✓") : picocolors.default.gray("✗");
-			const user = row.user === void 0 ? "—" : row.user ? picocolors.default.green("✓") : picocolors.default.gray("✗");
+			const project = row.project === void 0 ? "—" : `${row.project ? picocolors.default.green("✓") : picocolors.default.gray("✗")} ${formatEntry(row.projectEntry)}`;
+			const user = row.user === void 0 ? "—" : `${row.user ? picocolors.default.green("✓") : picocolors.default.gray("✗")} ${formatEntry(row.userEntry)}`;
 			if (row.project === true || row.user === true) installedAnywhere = true;
+			if (row.project === true && row.projectEntry && !sameMcpEntry(row.projectEntry, entry)) drift.push({
+				agent: row.agent,
+				scope: "project",
+				configured: row.projectEntry
+			});
+			if (row.user === true && row.userEntry && !sameMcpEntry(row.userEntry, entry)) drift.push({
+				agent: row.agent,
+				scope: "user",
+				configured: row.userEntry
+			});
 			console.log(`    ${row.agent.padEnd(12)} project: ${project}   user: ${user}`);
 		}
+		if (drift.length > 0) {
+			for (const item of drift) console.log(picocolors.default.yellow(`\n⚠️  MCP pin drift: ${item.agent} ${item.scope} pins ${formatEntry(item.configured)} but this CLI expects ${launch}.`));
+			console.log(picocolors.default.gray("   Run `ags sync` (or `ags mcp install`) to refresh; existing agents pick it up on their next MCP start."));
+		}
 		if (!mcp.enabled && installedAnywhere) {
 			console.log(picocolors.default.yellow("\n⚠️  Mismatch detected: .skillsrc says mcp.enabled=false, but the MCP entry IS present in at least one runtime config."));
 			console.log(picocolors.default.gray("   The MCP will work, but `sync` will not keep its config in step. Consider one of:"));
@@ -10403,12 +10795,36 @@ var McpCommand = class {
 			console.log(picocolors.default.gray("   Run `ags mcp install` to write the entries, or `ags mcp disable` to clear the consent flag."));
 		}
 	}
-	async actionEnable(config) {
+	/**
+	* Per-file consent for user-home MCP configs. Shared by every install path
+	* so `enable` (including global mode) cannot drift from `actionInstall`.
+	*/
+	async promptUserScopeWrite(agent, file) {
+		const { ok } = await inquirer.default.prompt([{
+			type: "confirm",
+			name: "ok",
+			message: `Write user-scope MCP config for ${picocolors.default.cyan(agent)} at ${picocolors.default.gray(file)}?`,
+			default: false
+		}]);
+		return ok;
+	}
+	async actionEnable(config, agents, cwd, options) {
 		const mcp = config.mcp ?? defaultMcpConfig();
+		const viaOverrideRaw = options.via;
+		const viaOverride = viaOverrideRaw ? parseVia(viaOverrideRaw) : void 0;
+		if (viaOverrideRaw && !viaOverride) {
+			console.log(picocolors.default.red(`Invalid --via value. Valid: ${VALID_VIAS.join(" | ")}`));
+			return;
+		}
 		if (mcp.scope === "disabled") {
 			console.log(picocolors.default.yellow("⚠️  scope is currently \"disabled\". Set a real scope first: `ags mcp scope project`"));
 			return;
 		}
+		const effectiveVia = viaOverride ?? mcp.via ?? "auto";
+		if (Boolean(options.installGlobal) || effectiveVia === "global") {
+			const pin = mcp.version ?? "0.8.1";
+			if (!this.ensureGlobalPin(pin)) return;
+		}
 		config.mcp = {
 			...mcp,
 			enabled: true,
@@ -10416,8 +10832,39 @@ var McpCommand = class {
 		};
 		await this.configService.saveConfig(config);
 		console.log(picocolors.default.green("✅ MCP enabled."));
+		if (viaOverride || effectiveVia === "global") {
+			const installVia = viaOverride ?? "global";
+			const report = await this.mcpService.install({
+				rootDir: cwd,
+				agents,
+				mcp: {
+					...config.mcp,
+					via: installVia
+				},
+				userScopePrompt: (agent, file) => this.promptUserScopeWrite(agent, file)
+			});
+			console.log(picocolors.default.gray(`   Installed configs using launch mode "${installVia}".`));
+			this.printReport(report, cwd);
+			return;
+		}
 		console.log(picocolors.default.gray("   Run `ags mcp install` to write configs now, or it happens on next `sync`."));
 	}
+	async actionVia(config, options) {
+		const via = options.via ?? options._?.[0];
+		if (!parseVia(via)) {
+			console.log(picocolors.default.red(`Invalid via. Valid: ${VALID_VIAS.join(" | ")}`));
+			return;
+		}
+		config.mcp = {
+			...config.mcp ?? defaultMcpConfig(),
+			via,
+			prompted: true
+		};
+		await this.configService.saveConfig(config);
+		console.log(picocolors.default.green(`✅ MCP launch mode set to "${via}".`));
+		if (via === "global") console.log(picocolors.default.yellow("⚠️  \"global\" requires a matching global install: `ags mcp enable` installs and verifies it automatically."));
+		else if (via === "auto") console.log(picocolors.default.gray("   \"auto\" uses a version-matched global ags-mcp when present, otherwise npx."));
+	}
 	async actionDisable(config) {
 		config.mcp = {
 			...config.mcp ?? defaultMcpConfig(),
@@ -10451,28 +10898,26 @@ var McpCommand = class {
 			console.log(picocolors.default.red(`Invalid --scope value. Valid: ${VALID_SCOPES.join(" | ")}`));
 			return;
 		}
+		const viaOverrideRaw = options.via;
+		const viaOverride = viaOverrideRaw ? parseVia(viaOverrideRaw) : void 0;
+		if (viaOverrideRaw && !viaOverride) {
+			console.log(picocolors.default.red(`Invalid --via value. Valid: ${VALID_VIAS.join(" | ")}`));
+			return;
+		}
 		if (effectiveScope === "disabled") {
 			console.log(picocolors.default.yellow("Scope is \"disabled\" — nothing to install."));
 			return;
 		}
-		const userPrompt = async (agent, file) => {
-			const { ok } = await inquirer.default.prompt([{
-				type: "confirm",
-				name: "ok",
-				message: `Write user-scope MCP config for ${picocolors.default.cyan(agent)} at ${picocolors.default.gray(file)}?`,
-				default: false
-			}]);
-			return ok;
-		};
 		const report = await this.mcpService.install({
 			rootDir: cwd,
 			agents,
 			mcp: {
 				...mcp,
 				enabled: true,
-				scope: effectiveScope
+				scope: effectiveScope,
+				...viaOverride ? { via: viaOverride } : {}
 			},
-			userScopePrompt: userPrompt
+			userScopePrompt: (agent, file) => this.promptUserScopeWrite(agent, file)
 		});
 		this.printReport(report, cwd);
 	}
@@ -10498,15 +10943,22 @@ var McpCommand = class {
 		console.log(picocolors.default.green(`✅ Removed agent-skills MCP entry from:`));
 		for (const r of removed) console.log(`   - ${picocolors.default.cyan(r.agent)} → ${picocolors.default.gray(r.file)}`);
 	}
-	async actionSnippets(config, agents, cwd) {
+	async actionSnippets(config, agents, cwd, options) {
 		const mcp = config.mcp ?? defaultMcpConfig();
+		const viaOverrideRaw = options.via;
+		const viaOverride = viaOverrideRaw ? parseVia(viaOverrideRaw) : void 0;
+		if (viaOverrideRaw && !viaOverride) {
+			console.log(picocolors.default.red(`Invalid --via value. Valid: ${VALID_VIAS.join(" | ")}`));
+			return;
+		}
 		const report = await this.mcpService.install({
 			rootDir: cwd,
 			agents,
 			mcp: {
 				...mcp,
 				enabled: true,
-				scope: "snippets-only"
+				scope: "snippets-only",
+				...viaOverride ? { via: viaOverride } : {}
 			}
 		});
 		if (report.snippets.length === 0) {
@@ -10605,12 +11057,14 @@ var RetrospectiveCommand = class {
 	env;
 	customExit;
 	log;
+	mcpVersion;
 	constructor(deps = {}) {
 		this.spawnFn = deps.spawnFn ?? defaultSpawn;
 		this.platform = deps.platform ?? process.platform;
 		this.env = deps.env ?? process.env;
 		this.customExit = deps.exit;
 		this.log = deps.log ?? console.log;
+		this.mcpVersion = deps.mcpVersion ?? "0.8.1";
 	}
 	exit(code) {
 		process.exitCode = code;
@@ -10639,8 +11093,8 @@ var RetrospectiveCommand = class {
 			}
 		}
 		const envSpec = this.env.AGS_MCP_PACKAGE_SPEC;
-		if (!(typeof envSpec === "string" && envSpec.trim() !== "") && !isVersionAtLeast("0.6.1", "0.8.0")) {
-			this.log(`Session retrospectives need agent-skills-standard-mcp ${RETROSPECTIVE_MIN_MCP_VERSION} or newer, but this ags is pinned to ${MCP_COMPATIBLE_VERSION}. Upgrade ags (ags upgrade), or set AGS_MCP_PACKAGE_SPEC to a newer package for testing.`);
+		if (!(typeof envSpec === "string" && envSpec.trim() !== "") && !isVersionAtLeast(this.mcpVersion, "0.8.0")) {
+			this.log(`Session retrospectives need agent-skills-standard-mcp ${RETROSPECTIVE_MIN_MCP_VERSION} or newer, but this ags is pinned to ${this.mcpVersion}. Upgrade ags (ags upgrade), or set AGS_MCP_PACKAGE_SPEC to a newer package for testing.`);
 			this.exit(1);
 			return;
 		}
@@ -10659,7 +11113,8 @@ var RetrospectiveCommand = class {
 		}
 		const argsToSpawn = [
 			"-y",
-			typeof envSpec === "string" && envSpec.trim() !== "" ? envSpec : `${PACKAGE}@${MCP_COMPATIBLE_VERSION}`,
+			"--prefer-offline",
+			typeof envSpec === "string" && envSpec.trim() !== "" ? envSpec : `${PACKAGE}@${this.mcpVersion}`,
 			"retrospective",
 			mappedAction,
 			...forwarded
@@ -11338,7 +11793,11 @@ var AuditCommand = class {
 * It checks the latest version on npm and performs the upgrade using the detected package manager.
 */
 var UpgradeCommand = class {
+	deps;
 	currentVersion = package_default.version;
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
 	/**
 	* Executes the upgrade flow.
 	* @param options Command options, including `dryRun` to check for updates without installing.
@@ -11383,6 +11842,7 @@ var UpgradeCommand = class {
 				const fallbackCmd = this.getUpgradeCommand(pm, "latest");
 				(0, child_process.execSync)(fallbackCmd, { stdio: "inherit" });
 			}
+			await this.printMcpRefreshHint();
 			if (pm === "pnpm") {
 				const installedVersion = this.getInstalledVersionFromPnpm(latestVersion);
 				if (installedVersion !== latestVersion) {
@@ -11434,6 +11894,12 @@ var UpgradeCommand = class {
 			this.printManualInstructions(pm, latestVersion);
 		}
 	}
+	async printMcpRefreshHint() {
+		try {
+			if (!(this.deps.loadMcpEnabled ? await this.deps.loadMcpEnabled() : (await new ConfigService().loadConfig())?.mcp?.enabled ?? false)) return;
+			console.log(picocolors.default.gray(`MCP configs are not rewritten by upgrade — run \`ags sync\` (or \`ags mcp install\`) to move them to ${MCP_COMPATIBLE_VERSION}.`));
+		} catch {}
+	}
 	detectPackageManager() {
 		const execPath = process.argv[1] || "";
 		if (execPath.includes("pnpm") || (process.env.npm_config_user_agent || "").includes("pnpm")) return "pnpm";
@@ -13410,9 +13876,12 @@ program.command("feedback").description("Report skill improvement opportunities
 program.command("upgrade").description("Upgrade the CLI to the latest version").option("--dry-run", "Check for updates without installing").action(async (options) => {
 	await new UpgradeCommand().run(options);
 });
-program.command("mcp <action> [scope]").description("Manage the optional MCP server integration. Actions: status | enable | disable | scope <project|user|snippets-only|disabled> | install | uninstall | snippets").option("--scope <scope>", "Override scope for install (project|user|snippets-only|disabled)").option("--from <from>", "For uninstall: project | user | all (default: project)").action(async (action, positional, opts) => {
+program.command("mcp <action> [scope]").description("Manage the optional MCP server integration. Actions: status | enable | disable | scope <project|user|snippets-only|disabled> | via <auto|npx|global> | install | uninstall | snippets").option("--scope <scope>", "Override scope for install (project|user|snippets-only|disabled)").option("--via <via>", "Override launch mode for this run (auto|npx|global)").option("--install-global", "On enable: install agent-skills-standard-mcp@<pin> globally, then verify its version (automatic when launch mode is global)").option("--from <from>", "For uninstall: project | user | all (default: project)").action(async (action, positional, opts) => {
 	const merged = { ...opts };
-	if (positional) merged.scope = opts.scope ?? positional;
+	if (positional) {
+		if (action === "via") merged.via = opts.via ?? positional;
+		else merged.scope = opts.scope ?? positional;
+	}
 	await new McpCommand().run(action, merged);
 });
 program.command("retrospective <action> [args...]").description("Enable, disable or inspect local session retrospectives (consent and the cross-session index). Runs the pinned agent-skills-standard-mcp package. Actions: enable | disable | status | index").allowUnknownOption(true).option("--store-root <path>", "Store root directory").option("--source-root <path>", "Additional source root for transcripts (repeatable)", (val, prev) => prev ? [...prev, val] : [val]).option("--since <YYYY-MM-DD>", "Index sessions since date").option("--until <YYYY-MM-DD>", "Index sessions until date").option("--folder <name>", "Index sessions from folder").action(async (action, args = [], options = {}) => {