agent-skills-standard 2.7.1 → 2.7.3

package/dist/index.js

@@ -38,19 +38,22 @@ cross_fetch = __toESM(cross_fetch);
 let js_yaml = require("js-yaml");
 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.1",
+	version: "2.7.3",
 	description: "A CLI to manage and sync AI agent skills standard for Cursor, Claude, Copilot, Windsurf, and more.",
 	main: "dist/index.js",
 	bin: {
@@ -1433,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({
@@ -1455,10 +1463,63 @@ var SkillConfigSchema = zod.z.object({
 	mcp: McpConfigSchema.optional(),
 	telemetry: zod.z.boolean().optional()
 });
+/**
+* Known top-level runtime fields a reviewed publication may replace. Unlisted
+* (unknown/extension) root fields are always preserved verbatim.
+*/
+var REVIEWED_ROOT_FIELDS = [
+	"registry",
+	"agents",
+	"custom_overrides",
+	"workflows",
+	"prune",
+	"workflows_ref",
+	"specialists_ref",
+	"telemetry",
+	"skills_mode"
+];
+/** Known MCP fields; unknown MCP extension keys survive an MCP consent update. */
+var MCP_FIELD_KEYS = [
+	"enabled",
+	"scope",
+	"prompted",
+	"version",
+	"via",
+	"snippets"
+];
 var DEFAULT_SDLC_SUPPORT_CATEGORIES = ["quality-engineering"];
 var PRIMARY_CONFIG_FILE = ".skillsrc";
 var LEGACY_YAML_CONFIG_FILE = ".skillsrc.yaml";
 var CONFIG_CONFLICT_MESSAGE = "Configuration changed on disk since it was opened; reload before applying.";
+var RESERVED_SELECTION_KEYS = {
+	ref: "set `ref` on the category itself, e.g. `skills.<category>.ref`",
+	include: "move the allowlist under the category it applies to, e.g. `skills.<category>.include`",
+	exclude: "move the exclusion list under the category it applies to, e.g. `skills.<category>.exclude`; a global `skills.exclude` is not supported"
+};
+function isReservedSelectionKey(key) {
+	return Object.prototype.hasOwnProperty.call(RESERVED_SELECTION_KEYS, key);
+}
+function isLegacySectionKey(trimmed) {
+	if (trimmed === "workflows:") return "workflows";
+	if (trimmed === "mcp:") return "mcp";
+	if (trimmed.startsWith("custom_overrides:")) return "custom_overrides";
+	return null;
+}
+/**
+* Invalid configuration that names both the file and the logical key needing
+* repair. Callers surface the message verbatim rather than guessing a
+* migration or rewriting the user's document.
+*/
+var ConfigValidationError = class extends Error {
+	configPath;
+	logicalPath;
+	constructor(configPath, logicalPath, detail) {
+		super(`Invalid configuration at ${configPath}: "${logicalPath}" ${detail}`);
+		this.configPath = configPath;
+		this.logicalPath = logicalPath;
+		this.name = "ConfigValidationError";
+	}
+};
 /**
 * Service for managing the `.skillsrc` configuration file.
 * Handles loading, saving, and initial construction of the configuration based on project metadata.
@@ -1498,12 +1559,32 @@ var ConfigService = class {
 		if (trimmed.startsWith("- ")) return trimmed.replace(/^-\s+/, "").split(/\s+-\s+/).map((item) => item.trim()).filter(Boolean);
 		return trimmed.split(",").map((item) => item.trim()).filter(Boolean);
 	}
+	/**
+	* Parses one inline legacy value with the document YAML parser so quoted
+	* scalars and flow collections keep their YAML meaning. Shapes the
+	* line-oriented fallback cannot represent unambiguously are refused instead
+	* of being published as raw token strings.
+	*/
+	parseLegacyYamlValue(raw, configPath, logicalPath) {
+		let parsed;
+		try {
+			parsed = js_yaml.load(raw);
+		} catch (error) {
+			throw new ConfigValidationError(configPath, logicalPath, `has an inline value ("${raw}") that is not valid YAML: ${error.message}`);
+		}
+		if (raw.startsWith("{") || raw.startsWith("[")) {
+			if (!this.isRecord(parsed) && !Array.isArray(parsed)) throw new ConfigValidationError(configPath, logicalPath, `has an inline value ("${raw}") that does not parse as a YAML collection.`);
+			return parsed;
+		}
+		if (typeof parsed === "object" && parsed !== null) throw new ConfigValidationError(configPath, logicalPath, `has an inline value ("${raw}") that parses as a YAML collection without flow braces; quote it or use {..}/[..].`);
+		return parsed;
+	}
 	parseLegacyBoolean(value) {
 		const normalized = value.trim().toLowerCase();
 		if (normalized === "true") return true;
 		if (normalized === "false") return false;
 	}
-	migrateLegacyTextConfig(content) {
+	migrateLegacyTextConfig(content, configPath) {
 		const lines = content.split(/\r?\n/);
 		const registryLine = lines.find((line) => line.trim().startsWith("registry:"));
 		const agentsIndex = lines.findIndex((line) => line.trim() === "agents:");
@@ -1523,35 +1604,74 @@ var ConfigService = class {
 			agents.push(match[1].trim());
 		}
 		config.agents = agents;
-		const sectionNames = /* @__PURE__ */ new Set([
-			"custom_overrides",
-			"workflows",
-			"mcp"
-		]);
+		const skills = {};
+		config.skills = skills;
 		let currentCategory = null;
+		let currentCategoryIndent = 0;
+		let pendingList = null;
 		for (let index = skillsIndex + 1; index < lines.length; index += 1) {
-			const trimmed = lines[index].trim();
-			if (!trimmed) continue;
-			if (trimmed === "workflows:" || trimmed === "mcp:" || trimmed.startsWith("custom_overrides:")) break;
-			const categoryMatch = trimmed.match(/^([A-Za-z0-9-]+):$/);
-			if (categoryMatch && !sectionNames.has(categoryMatch[1])) {
-				currentCategory = categoryMatch[1];
-				config.skills[currentCategory] = {};
+			const line = lines[index];
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) continue;
+			const indent = line.length - line.trimStart().length;
+			const sectionKey = isLegacySectionKey(trimmed);
+			if (sectionKey) {
+				if (currentCategory && indent > currentCategoryIndent) throw new ConfigValidationError(configPath, `skills.${currentCategory}.${sectionKey}`, "is indented as a category property but names a root section; cannot infer which it is.");
+				break;
+			}
+			if (trimmed.startsWith("- ")) {
+				const item = trimmed.slice(2).trim();
+				if (!pendingList || !currentCategory) continue;
+				if (indent < pendingList.indent) throw new ConfigValidationError(configPath, `skills.${currentCategory}.${pendingList.key}`, `has a list item ("${item}") indented less than the key that opened it; cannot infer membership.`);
+				if (item) {
+					const entry = skills[currentCategory];
+					const value = this.parseLegacyYamlValue(item, configPath, `skills.${currentCategory}.${pendingList.key}`);
+					if (isReservedSelectionKey(pendingList.key) && typeof value !== "string") throw new ConfigValidationError(configPath, `skills.${currentCategory}.${pendingList.key}`, `has a non-string list item ("${item}"); selection ids must be strings.`);
+					const current = entry[pendingList.key];
+					entry[pendingList.key] = Array.isArray(current) ? [...current, value] : [value];
+				}
 				continue;
 			}
-			if (!currentCategory) continue;
-			const refMatch = trimmed.match(/^ref:\s*(.+)$/);
-			if (refMatch) {
-				config.skills[currentCategory].ref = refMatch[1].trim();
+			const keyMatch = trimmed.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+			if (!keyMatch) continue;
+			const key = keyMatch[1];
+			const inlineValue = (keyMatch[2] ?? "").trim();
+			const isNestedProperty = currentCategory !== null && indent > currentCategoryIndent;
+			if (pendingList && indent > pendingList.indent) throw new ConfigValidationError(configPath, `skills.${currentCategory}.${pendingList.key}`, "opened a block list, but a nested key appears instead; cannot infer membership.");
+			if (isReservedSelectionKey(key)) {
+				if (!currentCategory || indent < currentCategoryIndent) throw new ConfigValidationError(configPath, key, `cannot infer which category this ${key} applies to. Correction: ${RESERVED_SELECTION_KEYS[key]}.`);
+				pendingList = null;
+				const entry = skills[currentCategory];
+				if (key === "ref") {
+					if (!inlineValue) throw new ConfigValidationError(configPath, `skills.${currentCategory}.ref`, "must name a git ref.");
+					entry.ref = inlineValue;
+					continue;
+				}
+				entry[key] = inlineValue ? this.parseLegacyList(inlineValue) : [];
+				if (!inlineValue) pendingList = {
+					key,
+					indent
+				};
 				continue;
 			}
-			const excludeMatch = trimmed.match(/^exclude:\s*(.+)$/);
-			if (excludeMatch) {
-				config.skills[currentCategory].exclude = this.parseLegacyList(excludeMatch[1]);
+			if (isNestedProperty && currentCategory) {
+				pendingList = null;
+				const entry = skills[currentCategory];
+				if (inlineValue) entry[key] = this.parseLegacyYamlValue(inlineValue, configPath, `skills.${currentCategory}.${key}`);
+				else {
+					entry[key] = null;
+					pendingList = {
+						key,
+						indent
+					};
+				}
 				continue;
 			}
-			const includeMatch = trimmed.match(/^include:\s*(.+)$/);
-			if (includeMatch) config.skills[currentCategory].include = this.parseLegacyList(includeMatch[1]);
+			if (inlineValue) throw new ConfigValidationError(configPath, `skills.${key}`, `has an inline value ("${inlineValue}") where a category entry is required. Correction: write selection keys as nested mapping entries under "skills.${key}".`);
+			currentCategory = key;
+			currentCategoryIndent = indent;
+			pendingList = null;
+			skills[currentCategory] = {};
 		}
 		const overridesLine = lines.find((line) => line.trim().startsWith("custom_overrides:"));
 		if (overridesLine) {
@@ -1586,7 +1706,27 @@ var ConfigService = class {
 		}
 		return config;
 	}
-	normalizeRawConfig(rawConfig) {
+	describeValue(value) {
+		if (Array.isArray(value)) return "a list";
+		if (value === null) return "null";
+		return `a ${typeof value}`;
+	}
+	/**
+	* Rejects reserved selection keys and non-mapping category values before any
+	* registry request, naming the exact logical key. Category names themselves
+	* are never checked against a local allowlist: a project may use any category
+	* the remote registry actually publishes.
+	*/
+	assertValidSkillCategories(skills, configPath) {
+		if (skills === void 0) return;
+		if (!this.isRecord(skills)) throw new ConfigValidationError(configPath, "skills", `must be a mapping of category name to its selection, not ${this.describeValue(skills)}.`);
+		for (const [category, value] of Object.entries(skills)) {
+			if (isReservedSelectionKey(category)) throw new ConfigValidationError(configPath, `skills.${category}`, `is a reserved selection key, not a category. Correction: ${RESERVED_SELECTION_KEYS[category]}.`);
+			if (value === null || value === void 0) continue;
+			if (!this.isRecord(value)) throw new ConfigValidationError(configPath, `skills.${category}`, `must be a mapping of optional ref/include/exclude (plus extension keys), not ${this.describeValue(value)}.`);
+		}
+	}
+	normalizeRawConfig(rawConfig, configPath) {
 		if (!this.isRecord(rawConfig)) return {
 			config: {},
 			migrated: false
@@ -1607,10 +1747,11 @@ var ConfigService = class {
 			}
 			return agent;
 		});
+		this.assertValidSkillCategories(normalized.skills, configPath);
 		if (this.isRecord(normalized.skills)) {
 			const normalizedSkills = {};
 			for (const [category, value] of Object.entries(normalized.skills)) {
-				if (!this.isRecord(value)) {
+				if (value === null || value === void 0) {
 					normalizedSkills[category] = {};
 					migrated = true;
 					continue;
@@ -1648,20 +1789,29 @@ var ConfigService = class {
 		const configPath = await this.resolveConfigPath(cwd);
 		if (!configPath) return null;
 		const content = await fs_extra.default.readFile(configPath, "utf8");
+		return this.parseConfigSource(content, configPath, cwd);
+	}
+	/**
+	* Parses already-read bytes with the same parser as `readConfigSource`. Used
+	* by reviewed publication so its baseline comes from the verified file
+	* content rather than caller-held snapshot objects.
+	*/
+	parseConfigSource(content, configPath, cwd) {
 		let rawConfig;
 		let migratedFromText = false;
 		try {
 			rawConfig = js_yaml.load(content);
 		} catch (parseError) {
-			rawConfig = this.migrateLegacyTextConfig(content);
+			rawConfig = this.migrateLegacyTextConfig(content, configPath);
 			migratedFromText = rawConfig !== null;
 			if (!migratedFromText) throw parseError;
 		}
-		const { config: normalizedConfig, migrated } = this.normalizeRawConfig(rawConfig);
+		const { config: normalizedConfig, migrated } = this.normalizeRawConfig(rawConfig, configPath);
 		const parsed = SkillConfigSchema.safeParse(normalizedConfig);
 		if (!parsed.success) throw new Error(`Invalid .skillsrc format: ${parsed.error.message}`);
 		return {
 			config: parsed.data,
+			document: normalizedConfig,
 			raw: this.isRecord(rawConfig) ? { ...rawConfig } : {},
 			sourcePath: configPath,
 			fingerprint: (0, node_crypto.createHash)("sha256").update(content, "utf8").digest("hex"),
@@ -1680,10 +1830,11 @@ var ConfigService = class {
 		try {
 			const source = await this.readConfigSource(cwd);
 			if (!source) return null;
-			if (source.migratedFromText || source.migrated || source.shouldRenameLegacyYamlFile) await fs_extra.default.outputFile(this.getPrimaryConfigPath(cwd), this.dumpConfig(source.config));
+			if (source.migratedFromText || source.migrated || source.shouldRenameLegacyYamlFile) await fs_extra.default.outputFile(this.getPrimaryConfigPath(cwd), this.dumpConfig(source.document));
 			if (source.shouldRenameLegacyYamlFile) await fs_extra.default.remove(source.sourcePath);
 			return source.config;
 		} catch (error) {
+			if (error instanceof ConfigValidationError) throw error;
 			throw new Error(`Failed to load config: ${error}`, { cause: error });
 		}
 	}
@@ -1707,28 +1858,92 @@ var ConfigService = class {
 	* unrelated root values and category extension fields survive.
 	*/
 	async saveSelection(snapshot, next, cwd = process.cwd()) {
-		const parsed = SkillConfigSchema.safeParse(next);
-		if (!parsed.success) throw new Error(`Invalid .skillsrc format: ${parsed.error.message}`);
-		const validated = parsed.data;
+		return this.commitReviewedSnapshot(snapshot, next, cwd, (baseline, validated) => {
+			const raw = baseline.raw;
+			const merged = { ...raw };
+			merged.skills = this.mergeSkillEntries(raw.skills, validated.skills);
+			if (validated.skills_mode) merged.skills_mode = validated.skills_mode;
+			else delete merged.skills_mode;
+			return merged;
+		});
+	}
+	/**
+	* Publishes a complete reviewed configuration (accepted category/workflow/
+	* specialist pins and later MCP consent updates) without dropping unknown
+	* data. Changed known runtime fields are applied over the source document,
+	* skill entries merge while preserving category extensions, and unknown root
+	* fields plus unknown MCP extension fields survive.
+	*/
+	async saveReviewedConfig(snapshot, next, cwd = process.cwd()) {
+		return this.commitReviewedSnapshot(snapshot, next, cwd, (baseline, validated, configPath) => this.buildReviewedDocument(baseline.config, baseline.raw, validated, configPath));
+	}
+	/**
+	* Shared publication: validate, verify the snapshot still matches the file
+	* bytes, re-parse those bytes as the only baseline, build and validate the
+	* normalized document, then write. Any failure refuses before the filesystem
+	* is touched. `snapshot.config`/`snapshot.raw` are never used as a baseline
+	* because callers can mutate them in place.
+	*/
+	async commitReviewedSnapshot(snapshot, next, cwd, buildDocument) {
+		this.assertValidSkillCategories(next.skills, snapshot.sourcePath);
+		const parsedNext = SkillConfigSchema.safeParse(next);
+		if (!parsedNext.success) throw new Error(`Invalid .skillsrc format: ${parsedNext.error.message}`);
+		const validated = parsedNext.data;
 		if (await this.resolveConfigPath(cwd) !== snapshot.sourcePath) throw new Error(CONFIG_CONFLICT_MESSAGE);
 		const currentContent = await fs_extra.default.readFile(snapshot.sourcePath, "utf8");
 		if ((0, node_crypto.createHash)("sha256").update(currentContent, "utf8").digest("hex") !== snapshot.fingerprint) throw new Error(CONFIG_CONFLICT_MESSAGE);
-		const merged = { ...snapshot.raw };
-		merged.skills = this.mergeSkillEntries(snapshot.raw.skills, validated.skills);
-		if (validated.skills_mode) merged.skills_mode = validated.skills_mode;
-		else delete merged.skills_mode;
+		const baseline = this.parseConfigSource(currentContent, snapshot.sourcePath, cwd);
 		const primaryConfigPath = this.getPrimaryConfigPath(cwd);
+		const merged = buildDocument(baseline, validated, primaryConfigPath);
+		const { config: normalizedDocument } = this.normalizeRawConfig(merged, primaryConfigPath);
+		const persisted = SkillConfigSchema.safeParse(normalizedDocument);
+		if (!persisted.success) throw new Error(`Invalid .skillsrc format: ${persisted.error.message}`);
 		const content = this.dumpConfig(merged);
 		await fs_extra.default.outputFile(primaryConfigPath, content);
 		const legacyYamlPath = this.getLegacyYamlConfigPath(cwd);
 		if (snapshot.sourcePath === legacyYamlPath && await fs_extra.default.pathExists(legacyYamlPath)) await fs_extra.default.remove(legacyYamlPath);
 		return {
-			config: validated,
+			config: persisted.data,
 			raw: merged,
 			sourcePath: primaryConfigPath,
 			fingerprint: (0, node_crypto.createHash)("sha256").update(content, "utf8").digest("hex")
 		};
 	}
+	buildReviewedDocument(previous, raw, next, configPath) {
+		const merged = { ...raw };
+		merged.skills = this.mergeSkillEntries(raw.skills, next.skills);
+		const previousFields = previous;
+		const nextFields = next;
+		for (const field of REVIEWED_ROOT_FIELDS) {
+			if (this.valuesEqual(nextFields[field], previousFields[field])) continue;
+			if (nextFields[field] === void 0) delete merged[field];
+			else merged[field] = nextFields[field];
+		}
+		if (!this.valuesEqual(next.mcp, previous.mcp)) {
+			if (next.mcp === void 0) {
+				const unknownKeys = this.isRecord(raw.mcp) ? Object.keys(raw.mcp).filter((key) => !MCP_FIELD_KEYS.includes(key)) : [];
+				if (unknownKeys.length > 0) throw new ConfigValidationError(configPath, "mcp", `cannot be removed because it contains unrecognized extension keys (${unknownKeys.join(", ")}); remove them explicitly first.`);
+				delete merged.mcp;
+			} else {
+				const mcp = { ...this.isRecord(raw.mcp) ? raw.mcp : {} };
+				const nextMcp = next.mcp;
+				for (const key of MCP_FIELD_KEYS) if (Object.prototype.hasOwnProperty.call(nextMcp, key)) mcp[key] = nextMcp[key];
+				else delete mcp[key];
+				merged.mcp = mcp;
+			}
+		}
+		return merged;
+	}
+	valuesEqual(left, right) {
+		if (left === right) return true;
+		if (Array.isArray(left) && Array.isArray(right)) return left.length === right.length && left.every((value, index) => this.valuesEqual(value, right[index]));
+		if (this.isRecord(left) && this.isRecord(right)) {
+			const leftKeys = Object.keys(left);
+			const rightKeys = Object.keys(right);
+			return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && this.valuesEqual(left[key], right[key]));
+		}
+		return false;
+	}
 	mergeSkillEntries(rawSkills, nextSkills) {
 		const existing = this.isRecord(rawSkills) ? rawSkills : {};
 		const merged = {};
@@ -1752,6 +1967,7 @@ var ConfigService = class {
 	async saveConfig(config, cwd = process.cwd()) {
 		const primaryConfigPath = this.getPrimaryConfigPath(cwd);
 		const legacyYamlPath = this.getLegacyYamlConfigPath(cwd);
+		this.assertValidSkillCategories(config.skills, primaryConfigPath);
 		await fs_extra.default.outputFile(primaryConfigPath, this.dumpConfig(config));
 		if (legacyYamlPath !== primaryConfigPath && await fs_extra.default.pathExists(legacyYamlPath)) await fs_extra.default.remove(legacyYamlPath);
 	}
@@ -2606,8 +2822,485 @@ var HookService = class {
 	}
 };
 //#endregion
+//#region src/services/install/safePath.ts
+/**
+* Asserts that a target file path resides inside rootDir and that NO intermediate
+* directory or terminal file under rootDir is a symbolic link.
+*
+* Requirements:
+* - rootDir may itself be a symlink (or inside one); components under rootDir must NOT be.
+* - Both existing files and dangling symlinks must be detected via lstat.
+* - Fails closed if lexical containment is breached or if any component under rootDir is a symlink.
+*
+* @param rootDir The trusted root directory
+* @param targetPath The destination file/directory path to check
+*/
+async function assertNoSymlinksUnderRoot(rootDir, targetPath) {
+	const resolvedRoot = path.default.resolve(rootDir);
+	const resolvedTarget = path.default.resolve(targetPath);
+	const relative = path.default.relative(resolvedRoot, resolvedTarget);
+	if (relative === ".." || relative.startsWith(`..${path.default.sep}`) || path.default.isAbsolute(relative)) throw new Error(`Path traversal or outside target detected: "${targetPath}" is outside "${rootDir}"`);
+	const segments = relative.split(path.default.sep).filter(Boolean);
+	let current = resolvedRoot;
+	for (const segment of segments) {
+		current = path.default.join(current, segment);
+		try {
+			if ((await fs_extra.default.lstat(current)).isSymbolicLink()) throw new Error(`Symlink path component not permitted: "${current}" is a symbolic link under "${rootDir}"`);
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("Symlink path component")) throw err;
+			if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") break;
+			throw err;
+		}
+	}
+}
+var DIGEST_RE$1 = /^[0-9a-f]{64}$/;
+var GIT_BLOB_SHA1_RE$1 = /^[0-9a-f]{40}$/;
+var COMMIT_RE = /^[0-9a-f]{40}$/;
+var PACKAGE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var CATEGORY_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var ATTRIBUTION_FILE_NAME_RE$1 = /^(LICENSE|NOTICE)(?:\.(?:md|txt))?$/i;
+function isBoundedRelativePath$1(value) {
+	if (typeof value !== "string" || value.length === 0) return false;
+	if (value.includes("\0") || value.includes("\\")) return false;
+	if (node_path.default.posix.isAbsolute(value) || node_path.default.isAbsolute(value)) return false;
+	if (node_path.default.posix.normalize(value) !== value) return false;
+	return !value.split("/").includes("..");
+}
+function isBoundedAttributionFileName(value) {
+	return typeof value === "string" && ATTRIBUTION_FILE_NAME_RE$1.test(value);
+}
+function fail$1(where, message) {
+	throw new Error(`Invalid .skills-lock.json attributionCatalog: ${where} ${message}`);
+}
+function assertExactKeys(where, value, keys) {
+	const allowed = new Set(keys);
+	for (const key of Object.keys(value)) if (!allowed.has(key)) fail$1(where, `has unexpected field '${key}'`);
+}
+function assertString(where, field, value) {
+	if (typeof value !== "string" || value.length === 0) fail$1(where, `has an invalid ${field}`);
+	return value;
+}
+function assertRecord(where, value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) fail$1(where, "must be an object");
+	return value;
+}
+function assertDigest(where, field, value) {
+	if (typeof value !== "string" || !DIGEST_RE$1.test(value)) fail$1(where, `has an invalid ${field}`);
+	return value;
+}
+function assertCommit(where, field, value) {
+	if (typeof value !== "string" || !COMMIT_RE.test(value)) fail$1(where, `has an invalid ${field} (expected a resolved commit)`);
+	return value;
+}
+function assertBlobSha1(where, value) {
+	if (typeof value !== "string" || !GIT_BLOB_SHA1_RE$1.test(value)) fail$1(where, "has an invalid blobSha1 (expected a Git blob SHA-1, not a truncated SHA-256)");
+	return value;
+}
+function parseDestination(where, value) {
+	const raw = assertRecord(where, value);
+	assertExactKeys(where, raw, [
+		"agent",
+		"path",
+		"sha256"
+	]);
+	const agent = assertString(where, "destination agent", raw.agent);
+	const destinationPath = assertString(where, "destination path", raw.path);
+	if (!isBoundedRelativePath$1(destinationPath)) fail$1(where, "has an unsafe destination path");
+	return {
+		agent,
+		path: destinationPath,
+		sha256: assertDigest(where, "destination sha256", raw.sha256)
+	};
+}
+function parseFile(where, value) {
+	const raw = assertRecord(where, value);
+	assertExactKeys(where, raw, [
+		"name",
+		"sourcePath",
+		"sourceKind",
+		"requestedRef",
+		"resolvedCommit",
+		"blobSha1",
+		"sha256",
+		"basis",
+		"destinations"
+	]);
+	const name = raw.name;
+	if (!isBoundedAttributionFileName(name)) fail$1(where, "has an invalid installed filename");
+	const sourcePath = assertString(where, "sourcePath", raw.sourcePath);
+	if (!isBoundedRelativePath$1(sourcePath)) fail$1(where, "has an unsafe sourcePath");
+	if (raw.sourceKind !== "package" && raw.sourceKind !== "root") fail$1(where, "has an invalid sourceKind");
+	if (raw.basis !== "release-manifest" && raw.basis !== "commit-tree-blob") fail$1(where, "has an invalid verification basis");
+	if (!Array.isArray(raw.destinations) || raw.destinations.length === 0) fail$1(where, "has no published destinations");
+	const destinations = raw.destinations.map((binding, index) => parseDestination(`${where} destination[${index}]`, binding));
+	return {
+		name,
+		sourcePath,
+		sourceKind: raw.sourceKind,
+		requestedRef: assertString(where, "requestedRef", raw.requestedRef),
+		resolvedCommit: assertCommit(where, "resolvedCommit", raw.resolvedCommit),
+		blobSha1: assertBlobSha1(where, raw.blobSha1),
+		sha256: assertDigest(where, "sha256", raw.sha256),
+		basis: raw.basis,
+		destinations
+	};
+}
+function parsePackage(where, value) {
+	const raw = assertRecord(where, value);
+	assertExactKeys(where, raw, [
+		"registry",
+		"declaringCategory",
+		"requestedRef",
+		"resolvedCommit",
+		"files"
+	]);
+	if (typeof raw.declaringCategory !== "string" || !CATEGORY_TOKEN_RE.test(raw.declaringCategory)) fail$1(where, "has an invalid declaringCategory");
+	if (!Array.isArray(raw.files) || raw.files.length === 0) fail$1(where, "has no attribution files");
+	const fileNames = /* @__PURE__ */ new Set();
+	const files = raw.files.map((file, index) => {
+		const parsed = parseFile(`${where} files[${index}]`, file);
+		if (fileNameKey(parsed.name, fileNames)) fail$1(where, `has a duplicate installed filename '${parsed.name}'`);
+		return parsed;
+	});
+	return {
+		registry: assertString(where, "registry", raw.registry),
+		declaringCategory: raw.declaringCategory,
+		requestedRef: assertString(where, "requestedRef", raw.requestedRef),
+		resolvedCommit: assertCommit(where, "resolvedCommit", raw.resolvedCommit),
+		files
+	};
+}
+function fileNameKey(name, seen) {
+	const key = name.toLowerCase();
+	if (seen.has(key)) return true;
+	seen.add(key);
+	return false;
+}
+/**
+* Validates and narrows the optional attribution catalog. Unknown versions and
+* malformed qualified records fail closed so no caller can republish them.
+*/
+function validateAttributionCatalog(catalog) {
+	const raw = assertRecord("root", catalog);
+	assertExactKeys("root", raw, ["version", "packages"]);
+	if (raw.version !== 1) fail$1("root", `has unsupported version ${String(raw.version)} (this CLI only reads version 1)`);
+	const rawPackages = assertRecord("packages", raw.packages);
+	const packages = {};
+	for (const [packageId, record] of Object.entries(rawPackages)) {
+		if (!PACKAGE_ID_RE.test(packageId)) fail$1(`package '${packageId}'`, "is not a bounded category/skill key");
+		packages[packageId] = parsePackage(`package '${packageId}'`, record);
+	}
+	return {
+		version: 1,
+		packages
+	};
+}
+function sameOrigin(left, right) {
+	return left.sourcePath === right.sourcePath && left.sourceKind === right.sourceKind && left.requestedRef === right.requestedRef && left.resolvedCommit === right.resolvedCommit && left.blobSha1 === right.blobSha1 && left.sha256 === right.sha256 && left.basis === right.basis;
+}
+/**
+* A previous record is trustworthy only when every recorded destination
+* exists and its own bytes still match its own recorded digest. A pooled
+* digest anywhere is not evidence: one intact copy never qualifies an edited
+* or missing sibling, and digests swapped between agents never match.
+*/
+function qualifiesAgainstInstalled(previous, installed) {
+	if (!installed || installed.length === 0) return false;
+	return previous.destinations.every((recorded) => {
+		const actual = installed.find((candidate) => candidate.agent === recorded.agent && candidate.path === recorded.path);
+		return actual !== void 0 && actual.sha256 !== null && actual.sha256 === recorded.sha256;
+	});
+}
+function compareFiles(previous, planned, unqualifiedNames, originMoved) {
+	const previousByName = new Map(previous.files.map((file) => [file.name, file]));
+	const plannedByName = new Map(planned.files.map((file) => [file.name, file]));
+	const names = [.../* @__PURE__ */ new Set([...previousByName.keys(), ...plannedByName.keys()])].sort();
+	const files = [];
+	let sawAdded = false;
+	let sawRemoved = false;
+	let sawBytesChanged = false;
+	let sawOriginChanged = false;
+	for (const name of names) {
+		const oldFile = previousByName.get(name) ?? null;
+		const newFile = plannedByName.get(name) ?? null;
+		const trustworthyOld = (oldFile ? unqualifiedNames.has(name) : false) ? null : oldFile;
+		if (!oldFile && newFile) {
+			sawAdded = true;
+			files.push({
+				name,
+				status: "added",
+				previousSha256: null,
+				plannedSha256: newFile.sha256,
+				previous: null,
+				planned: newFile
+			});
+			continue;
+		}
+		if (oldFile && !newFile) {
+			sawRemoved = true;
+			files.push({
+				name,
+				status: "removed",
+				previousSha256: oldFile.sha256,
+				plannedSha256: null,
+				previous: trustworthyOld,
+				planned: null
+			});
+			continue;
+		}
+		if (oldFile && newFile) {
+			if (oldFile.sha256 !== newFile.sha256) {
+				sawBytesChanged = true;
+				files.push({
+					name,
+					status: "changed",
+					previousSha256: oldFile.sha256,
+					plannedSha256: newFile.sha256,
+					previous: trustworthyOld,
+					planned: newFile
+				});
+				continue;
+			}
+			if (!sameOrigin(oldFile, newFile) || originMoved) {
+				sawOriginChanged = true;
+				files.push({
+					name,
+					status: "origin-changed",
+					previousSha256: oldFile.sha256,
+					plannedSha256: newFile.sha256,
+					previous: trustworthyOld,
+					planned: newFile
+				});
+				continue;
+			}
+			files.push({
+				name,
+				status: "unchanged",
+				previousSha256: oldFile.sha256,
+				plannedSha256: newFile.sha256,
+				previous: trustworthyOld,
+				planned: newFile
+			});
+		}
+	}
+	return {
+		files,
+		sawAdded,
+		sawRemoved,
+		sawBytesChanged,
+		sawOriginChanged
+	};
+}
+/**
+* Pure comparison of qualified attribution metadata. No writes, no prompts:
+* the command layer owns consent, publication and exit behavior.
+*/
+function compareAttribution(input) {
+	const previousPackages = input.previousCatalog?.packages ?? {};
+	const packageIds = [.../* @__PURE__ */ new Set([...Object.keys(previousPackages), ...Object.keys(input.planned)])].sort();
+	const packages = [];
+	const legacyUnqualified = [];
+	const disclosures = [];
+	let requiresConsent = false;
+	for (const packageId of packageIds) {
+		const previous = previousPackages[packageId] ?? null;
+		const planned = input.planned[packageId] ?? null;
+		if (!input.hasExistingInstallation) {
+			if (!planned) continue;
+			packages.push({
+				packageId,
+				status: "added",
+				reason: "first-install",
+				previous: null,
+				planned,
+				files: planned.files.map((file) => ({
+					name: file.name,
+					status: "added",
+					previousSha256: null,
+					plannedSha256: file.sha256,
+					previous: null,
+					planned: file
+				})),
+				requiresConsent: false
+			});
+			disclosures.push(planned);
+			continue;
+		}
+		if (!previous) {
+			if (!planned) continue;
+			const installed = input.installed?.[packageId];
+			if (Object.values(installed ?? {}).some((bindings) => bindings.some((binding) => binding.sha256 !== null))) {
+				legacyUnqualified.push(packageId);
+				requiresConsent = true;
+				packages.push({
+					packageId,
+					status: "legacy-unqualified",
+					reason: "unqualified-origin",
+					previous: null,
+					planned,
+					files: planned.files.map((file) => ({
+						name: file.name,
+						status: "added",
+						previousSha256: null,
+						plannedSha256: file.sha256,
+						previous: null,
+						planned: file
+					})),
+					requiresConsent: true
+				});
+				continue;
+			}
+			requiresConsent = true;
+			packages.push({
+				packageId,
+				status: "added",
+				reason: "added",
+				previous: null,
+				planned,
+				files: planned.files.map((file) => ({
+					name: file.name,
+					status: "added",
+					previousSha256: null,
+					plannedSha256: file.sha256,
+					previous: null,
+					planned: file
+				})),
+				requiresConsent: true
+			});
+			continue;
+		}
+		const installed = input.installed?.[packageId];
+		const unqualifiedNames = new Set(previous.files.filter((file) => !qualifiesAgainstInstalled(file, installed?.[file.name])).map((file) => file.name));
+		if (!planned) {
+			requiresConsent = true;
+			packages.push({
+				packageId,
+				status: "removed",
+				reason: "removed",
+				previous: unqualifiedNames.size > 0 ? null : previous,
+				planned: null,
+				files: previous.files.map((file) => ({
+					name: file.name,
+					status: "removed",
+					previousSha256: file.sha256,
+					plannedSha256: null,
+					previous: unqualifiedNames.has(file.name) ? null : file,
+					planned: null
+				})),
+				requiresConsent: true
+			});
+			continue;
+		}
+		const compared = compareFiles(previous, planned, unqualifiedNames, previous.registry !== planned.registry || previous.declaringCategory !== planned.declaringCategory || previous.requestedRef !== planned.requestedRef || previous.resolvedCommit !== planned.resolvedCommit);
+		if (unqualifiedNames.size > 0) {
+			legacyUnqualified.push(packageId);
+			requiresConsent = true;
+			packages.push({
+				packageId,
+				status: "legacy-unqualified",
+				reason: installed && Object.keys(installed).length > 0 ? "installed-bytes-mismatch" : "unqualified-origin",
+				previous: null,
+				planned,
+				files: compared.files,
+				requiresConsent: true
+			});
+			continue;
+		}
+		let reason = "unchanged";
+		let status = "unchanged";
+		if (compared.sawRemoved) {
+			reason = "removed";
+			status = "changed";
+		} else if (compared.sawAdded) {
+			reason = "added";
+			status = "changed";
+		} else if (compared.sawBytesChanged) {
+			reason = "changed";
+			status = "changed";
+		} else if (compared.sawOriginChanged) {
+			reason = "origin-changed";
+			status = "origin-changed";
+		}
+		if (status !== "unchanged") requiresConsent = true;
+		packages.push({
+			packageId,
+			status,
+			reason,
+			previous,
+			planned,
+			files: compared.files,
+			requiresConsent: status !== "unchanged"
+		});
+	}
+	return {
+		firstInstall: !input.hasExistingInstallation,
+		requiresConsent,
+		packages,
+		legacyUnqualified,
+		disclosures
+	};
+}
+/**
+* Digest of an installed attribution file, or null when it cannot be read
+* inside the project root. The shared install path boundary rejects traversal
+* and any symlink component (terminal, parent, or dangling) before the bytes
+* are read, so external bytes can never qualify a record.
+*/
+async function readInstalledAttributionDigest(rootDir, relativePath) {
+	try {
+		const absPath = node_path.default.join(rootDir, relativePath);
+		await assertNoSymlinksUnderRoot(rootDir, absPath);
+		const bytes = await fs_extra.default.readFile(absPath);
+		return (0, node_crypto.createHash)("sha256").update(bytes).digest("hex");
+	} catch {
+		return null;
+	}
+}
+/**
+* Reads the bytes actually installed at every recorded destination, preserving
+* agent/path identity. A missing or unsafe destination is reported with
+* `sha256: null`, which the comparison treats as unqualified rather than as
+* agreement.
+*/
+async function collectInstalledAttributionDigests(rootDir, packages) {
+	const state = {};
+	for (const [packageId, record] of Object.entries(packages)) {
+		const perFile = {};
+		for (const file of record.files) {
+			perFile[file.name] = [];
+			for (const binding of file.destinations) perFile[file.name].push({
+				agent: binding.agent,
+				path: binding.path,
+				sha256: await readInstalledAttributionDigest(rootDir, binding.path)
+			});
+		}
+		state[packageId] = perFile;
+	}
+	return state;
+}
+function buildAttributionCatalog(packages) {
+	const sorted = {};
+	for (const packageId of Object.keys(packages).sort()) sorted[packageId] = packages[packageId];
+	return {
+		version: 1,
+		packages: sorted
+	};
+}
+//#endregion
 //#region src/services/LockfileService.ts
 var LOCKFILE_NAME = ".skills-lock.json";
+/** Top-level names this writer owns; anything else is preserved verbatim. */
+var KNOWN_LOCK_KEYS = {
+	version: true,
+	registry: true,
+	generatedAt: true,
+	sources: true,
+	entries: true,
+	generation: true,
+	disclosed: true,
+	workflowCatalog: true,
+	attributionCatalog: true
+};
 /**
 * Reserved ownership agent for the shared canonical workflow body installed at
 * `.agents/workflows/*.md`. It is not a provider and must never be added to the
@@ -2647,7 +3340,7 @@ function parseGenerationLedger(value) {
 		entries
 	};
 }
-function sha256(content) {
+function sha256$1(content) {
 	return (0, node_crypto.createHash)("sha256").update(content, Buffer.isBuffer(content) ? void 0 : "utf8").digest("hex");
 }
 /**
@@ -2687,7 +3380,8 @@ var lockV2Schema = zod.z.object({
 		sha256: zod.z.string()
 	})),
 	disclosed: zod.z.record(zod.z.string(), zod.z.array(zod.z.string())).optional(),
-	workflowCatalog: zod.z.unknown().optional()
+	workflowCatalog: zod.z.unknown().optional(),
+	attributionCatalog: zod.z.unknown().optional()
 }).passthrough();
 var lockVersionProbe = zod.z.object({ version: zod.z.unknown() });
 /**
@@ -2701,12 +3395,13 @@ function parseLockV2(raw) {
 		const where = issue?.path.length ? issue.path.join(".") : "root";
 		throw new Error(`Invalid .skills-lock.json: ${where} ${issue?.message ?? "is invalid"}`);
 	}
-	const { workflowCatalog: rawCatalog, ...rest } = parsed.data;
+	const { workflowCatalog: rawCatalog, attributionCatalog: rawAttribution, ...rest } = parsed.data;
 	const generation = parseGenerationLedger(raw.generation);
 	return {
 		...rest,
 		...generation ? { generation } : {},
-		...rawCatalog === void 0 ? {} : { workflowCatalog: validateWorkflowCatalog(rawCatalog) }
+		...rawCatalog === void 0 ? {} : { workflowCatalog: validateWorkflowCatalog(rawCatalog) },
+		...rawAttribution === void 0 ? {} : { attributionCatalog: validateAttributionCatalog(rawAttribution) }
 	};
 }
 var DIGEST_RE = /^[a-f0-9]{64}$/;
@@ -2835,21 +3530,27 @@ var LockfileService = class {
 	async write(rootDir, lock) {
 		const file = this.lockfilePath(rootDir);
 		if (lock.workflowCatalog !== void 0) validateWorkflowCatalog(lock.workflowCatalog);
+		if (lock.attributionCatalog !== void 0) validateAttributionCatalog(lock.attributionCatalog);
+		let existingRaw;
 		let existingDisclosed;
 		let existingGeneration;
+		let existingAttribution;
 		if (await fs_extra.default.pathExists(file)) {
-			let raw;
 			try {
-				raw = await readJsonStrict(file);
+				existingRaw = await readJsonStrict(file);
 			} catch {}
+			const raw = existingRaw;
 			if (raw) {
 				existingDisclosed = raw.disclosed;
-				if (raw.version === 2) existingGeneration = parseGenerationLedger(raw.generation);
-				else if (raw.generation !== void 0) throw new Error("Unsupported repository-generation lock namespace");
+				if (raw.version === 2) {
+					existingGeneration = parseGenerationLedger(raw.generation);
+					if (raw.attributionCatalog !== void 0) existingAttribution = validateAttributionCatalog(raw.attributionCatalog);
+				} else if (raw.generation !== void 0) throw new Error("Unsupported repository-generation lock namespace");
 			}
 		}
 		const generation = lock.generation === void 0 ? existingGeneration : parseGenerationLedger(lock.generation);
 		const disclosed = lock.disclosed ?? existingDisclosed;
+		const attribution = lock.attributionCatalog === void 0 ? existingAttribution : lock.attributionCatalog;
 		const sortedEntries = {};
 		for (const k of Object.keys(lock.entries).sort()) sortedEntries[k] = lock.entries[k];
 		const sortedGenerationEntries = {};
@@ -2861,10 +3562,16 @@ var LockfileService = class {
 				version: 1,
 				entries: sortedGenerationEntries
 			} } : {},
-			...disclosed ? { disclosed } : {}
+			...disclosed ? { disclosed } : {},
+			...attribution ? { attributionCatalog: attribution } : {}
 		};
 		if (!generation) delete out.generation;
 		if (!disclosed) delete out.disclosed;
+		if (!attribution) delete out.attributionCatalog;
+		for (const [key, value] of Object.entries(existingRaw ?? {})) {
+			if (KNOWN_LOCK_KEYS[key] || key in out) continue;
+			out[key] = value;
+		}
 		await this.publishAtomic(file, out);
 	}
 	/**
@@ -2894,6 +3601,7 @@ var LockfileService = class {
 		if (raw?.version === 2) parseGenerationLedger(raw.generation);
 		else if (raw?.generation !== void 0) throw new Error("Unsupported repository-generation lock namespace");
 		if (raw.workflowCatalog !== void 0) validateWorkflowCatalog(raw.workflowCatalog);
+		if (raw.attributionCatalog !== void 0) validateAttributionCatalog(raw.attributionCatalog);
 		await this.publishAtomic(file, {
 			...raw,
 			disclosed
@@ -2909,7 +3617,7 @@ var LockfileService = class {
 				missing.push(rel);
 				continue;
 			}
-			if (sha256(await fs_extra.default.readFile(absPath)) !== entry.sha256) mismatches.push(rel);
+			if (sha256$1(await fs_extra.default.readFile(absPath)) !== entry.sha256) mismatches.push(rel);
 		}
 		return {
 			ok: mismatches.length === 0 && missing.length === 0,
@@ -2927,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.0";
 /**
 * Minimum `agent-skills-standard-mcp` version required for session retrospectives.
 */
@@ -2953,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(".");
@@ -2990,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);
@@ -3025,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)) {
@@ -3059,18 +3829,111 @@ 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.0";
+		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 (ENOENT) never falls through: an installed manifest
+	* alone does not prove the command is on the client's PATH.
+	*/
+	detectGlobalVersion() {
+		const binaryVersion = this.probeGlobalBinaryVersion();
+		if (binaryVersion === GLOBAL_BINARY_MISSING) return null;
+		return binaryVersion ?? this.probeGlobalManifestVersion();
+	}
+	/** `ags-mcp --version`, or the sentinel when the command is not on PATH. */
+	probeGlobalBinaryVersion() {
+		try {
+			if (this.testGlobalVersionProbe) return this.testGlobalVersionProbe();
+			const output = (0, child_process.execFileSync)("ags-mcp", ["--version"], {
+				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;
+	}
 	getTargets() {
 		return getTargets(this.testHome ?? void 0);
 	}
@@ -3089,7 +3952,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) {
@@ -3166,12 +4032,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);
@@ -3271,7 +4170,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) {
@@ -3374,6 +4277,10 @@ function defaultDoctorDeps() {
 			rootDir,
 			agents
 		}),
+		buildMcpEntry: (cfg) => mcp.buildEntry({
+			version: cfg.mcp?.version,
+			via: cfg.mcp?.via
+		}),
 		hookStatus: (rootDir, agents) => hooks.status({
 			rootDir,
 			agents
@@ -3507,13 +4414,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.0";
+		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);
@@ -4009,10 +4951,306 @@ var InitService = class {
 		await fs_extra.default.outputFile(configPath, commentHeader + js_yaml.dump(config));
 	}
 };
-//#endregion
-//#region src/services/GithubService.ts
-/** A downloaded file failed its integrity or size check. */
-var IntegrityError = class extends Error {
+var AMBIGUOUS_ERROR_BODY_TIMEOUT_MS = 1e3;
+var RATE_LIMIT_EVIDENCE = /rate[-_ ]?limit|abuse[-_ ]?detection|too many requests/i;
+/**
+* Drops credentials, query strings, and fragments. GitHub tokens can appear in
+* query strings on some endpoints, so only origin and path are retained.
+*/
+function sanitizeEndpoint(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return url.split(/[?#]/)[0] ?? url;
+	}
+}
+function readHeader(res, name) {
+	const headers = res.headers;
+	if (!headers || typeof headers.get !== "function") return void 0;
+	const value = headers.get(name);
+	return typeof value === "string" ? value : void 0;
+}
+/** `Retry-After` in seconds. Malformed, negative, or non-integer values are ignored. */
+function parseRetryAfterSeconds(value) {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) return void 0;
+	const seconds = Number(trimmed);
+	return Number.isSafeInteger(seconds) ? seconds : void 0;
+}
+/** `x-ratelimit-reset` is epoch seconds. Malformed or implausible values are ignored. */
+function parseResetAt(value) {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) return void 0;
+	const seconds = Number(trimmed);
+	if (!Number.isSafeInteger(seconds) || seconds <= 0) return void 0;
+	const date = /* @__PURE__ */ new Date(seconds * 1e3);
+	const time = date.getTime();
+	if (Number.isNaN(time)) return void 0;
+	const year = date.getUTCFullYear();
+	if (year < 1970 || year > 2100) return void 0;
+	return date.toISOString();
+}
+function parseRemaining(value) {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) return void 0;
+	const remaining = Number(trimmed);
+	return Number.isSafeInteger(remaining) ? remaining : void 0;
+}
+function readNodeBody(stream) {
+	return new Promise((resolve) => {
+		const chunks = [];
+		let total = 0;
+		let settled = false;
+		const finish = (text) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			stream.removeListener("data", onData);
+			stream.removeListener("end", onEnd);
+			stream.removeListener("error", onError);
+			if (text === null) stream.destroy();
+			else stream.pause();
+			resolve(text);
+		};
+		const onData = (chunk) => {
+			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			total += bytes.byteLength;
+			if (total > 8192) {
+				finish(null);
+				return;
+			}
+			chunks.push(bytes);
+		};
+		const onEnd = () => finish(Buffer.concat(chunks).toString("utf8"));
+		const onError = () => finish(null);
+		const timer = setTimeout(() => finish(null), AMBIGUOUS_ERROR_BODY_TIMEOUT_MS);
+		stream.on("data", onData);
+		stream.on("end", onEnd);
+		stream.on("error", onError);
+	});
+}
+function readWebChunk(reader, timeoutMs) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			resolve("timeout");
+		}, timeoutMs);
+		reader.read().then((result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(result);
+		}, () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve("timeout");
+		});
+	});
+}
+/**
+* Abandons a WHATWG reader without waiting on `cancel()`. A cancellation
+* promise may never settle; awaiting it would extend the classification
+* deadline. The lock is released when possible, otherwise the runtime owns the
+* reader after the pending read settles.
+*/
+function abandonWebReader(reader) {
+	try {
+		reader.cancel().catch(() => void 0);
+	} catch {}
+	try {
+		reader.releaseLock();
+	} catch {}
+}
+async function readWebBody(stream) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let text = "";
+	let total = 0;
+	const deadline = Date.now() + AMBIGUOUS_ERROR_BODY_TIMEOUT_MS;
+	try {
+		for (;;) {
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) {
+				abandonWebReader(reader);
+				return null;
+			}
+			const chunk = await readWebChunk(reader, remaining);
+			if (chunk === "timeout") {
+				abandonWebReader(reader);
+				return null;
+			}
+			if (chunk.done) return text + decoder.decode();
+			total += chunk.value.byteLength;
+			if (total > 8192) {
+				abandonWebReader(reader);
+				return null;
+			}
+			text += decoder.decode(chunk.value, { stream: true });
+		}
+	} catch {
+		return null;
+	}
+}
+/**
+* Releases a response body that will never be read. Node streams are destroyed
+* synchronously; WHATWG cancellation is started with rejection handling and
+* never awaited, so a stalled cancel cannot hold up classification or latch.
+*/
+function abandonResponseBody(res) {
+	const body = res.body;
+	if (body instanceof node_stream.Readable) {
+		body.destroy();
+		return;
+	}
+	if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) try {
+		body.cancel().catch(() => void 0);
+	} catch {}
+}
+/**
+* Reads only the ambiguous 403 body, bounded in bytes and time, for both the
+* Node stream that `cross-fetch` returns and a WHATWG stream. Any timeout,
+* oversize read, or stream error releases the body and returns null.
+*/
+function readAmbiguousErrorBody(res) {
+	const body = res.body;
+	if (body instanceof node_stream.Readable) return readNodeBody(body);
+	if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream) return readWebBody(body);
+	return Promise.resolve(null);
+}
+var GithubRequestError = class GithubRequestError extends Error {
+	kind;
+	endpoint;
+	authenticated;
+	status;
+	statusText;
+	retryAfterSeconds;
+	resetAt;
+	rateLimitKind;
+	constructor(init) {
+		super(init.message, { cause: init.cause });
+		this.name = "GithubRequestError";
+		this.kind = init.kind;
+		this.endpoint = sanitizeEndpoint(init.endpoint);
+		this.authenticated = init.authenticated;
+		this.status = init.status;
+		this.statusText = init.statusText;
+		this.retryAfterSeconds = init.retryAfterSeconds;
+		this.resetAt = init.resetAt;
+		this.rateLimitKind = init.rateLimitKind;
+	}
+	/** Serialization allowlist: no token, no headers, no cause chain. */
+	toJSON() {
+		return {
+			name: "GithubRequestError",
+			kind: this.kind,
+			status: this.status ?? null,
+			endpoint: this.endpoint,
+			authenticated: this.authenticated,
+			retryAfterSeconds: this.retryAfterSeconds ?? null,
+			resetAt: this.resetAt ?? null,
+			rateLimitKind: this.rateLimitKind ?? null,
+			message: this.message
+		};
+	}
+	static isRateLimit(error) {
+		return error instanceof GithubRequestError && error.kind === "rate-limited";
+	}
+	static isAccessDenial(error) {
+		return error instanceof GithubRequestError && error.kind === "access-denied";
+	}
+};
+function buildFailure(res) {
+	const status = typeof res.status === "number" && Number.isInteger(res.status) ? res.status : 0;
+	const statusText = typeof res.statusText === "string" ? res.statusText : void 0;
+	return {
+		status,
+		statusText,
+		statusLabel: `${status || "unknown"}${statusText ? ` ${statusText}` : ""}`,
+		retryAfterSeconds: parseRetryAfterSeconds(readHeader(res, "retry-after")),
+		resetAt: parseResetAt(readHeader(res, "x-ratelimit-reset"))
+	};
+}
+function classifyGithubStatus(res, endpoint, authenticated) {
+	const { status, statusText, statusLabel, retryAfterSeconds, resetAt } = buildFailure(res);
+	const primary = parseRemaining(readHeader(res, "x-ratelimit-remaining")) === 0;
+	if (status === 404) return new GithubRequestError({
+		kind: "not-found",
+		message: `GitHub resource not found: ${statusLabel}`,
+		endpoint,
+		authenticated,
+		status,
+		statusText
+	});
+	if (status === 401) return new GithubRequestError({
+		kind: "access-denied",
+		message: `GitHub access denied: ${statusLabel}`,
+		endpoint,
+		authenticated,
+		status,
+		statusText,
+		resetAt
+	});
+	if (status === 403 || status === 429) {
+		if (primary || status === 429 || retryAfterSeconds !== void 0) {
+			const rateLimitKind = primary ? "primary" : retryAfterSeconds !== void 0 || status === 429 ? "secondary" : void 0;
+			return new GithubRequestError({
+				kind: "rate-limited",
+				message: `GitHub rate limit exceeded (${rateLimitKind ?? "unclassified"}): ${statusLabel}`,
+				endpoint,
+				authenticated,
+				status,
+				statusText,
+				retryAfterSeconds,
+				resetAt,
+				rateLimitKind
+			});
+		}
+		return "ambiguous";
+	}
+	return new GithubRequestError({
+		kind: "transport",
+		message: `GitHub API Error: ${statusLabel}`,
+		endpoint,
+		authenticated,
+		status,
+		statusText
+	});
+}
+/** Resolves an ambiguous 403 by reading a bounded body for throttle evidence. */
+async function classifyAmbiguous403(res, endpoint, authenticated) {
+	const { status, statusText, statusLabel, resetAt } = buildFailure(res);
+	const body = await readAmbiguousErrorBody(res);
+	if (body !== null && RATE_LIMIT_EVIDENCE.test(body)) return new GithubRequestError({
+		kind: "rate-limited",
+		message: `GitHub rate limit exceeded (secondary): ${statusLabel}`,
+		endpoint,
+		authenticated,
+		status,
+		statusText,
+		resetAt,
+		rateLimitKind: "secondary"
+	});
+	return new GithubRequestError({
+		kind: "access-denied",
+		message: `GitHub access denied: ${statusLabel}`,
+		endpoint,
+		authenticated,
+		status,
+		statusText,
+		resetAt
+	});
+}
+//#endregion
+//#region src/services/GithubService.ts
+/** A downloaded file failed its integrity or size check. */
+var IntegrityError = class extends Error {
 	constructor(message) {
 		super(message);
 		this.name = "IntegrityError";
@@ -4024,13 +5262,32 @@ function gitBlobSha1(content) {
 	return (0, node_crypto.createHash)("sha1").update(Buffer.concat([header, content])).digest("hex");
 }
 /**
+* Detaches a cached value from the caller that receives it. Buffers are
+* copied; plain objects are structured-cloned. The session cache therefore
+* never shares mutable state with consumers.
+*/
+function detachValue(value) {
+	if (Buffer.isBuffer(value)) return Buffer.from(value);
+	if (value !== null && typeof value === "object") return structuredClone(value);
+	return value;
+}
+/**
 * Service for interacting with the GitHub API and fetching raw file content.
 * Handles repository tree discovery, file downloads, and URL parsing.
+*
+* One instance is operation-scoped: identical requests are coalesced and
+* reused for the lifetime of the operation, the first confirmed throttling
+* response latches the whole operation, and `resetOperation()` clears both
+* when a client is reused for another command.
 */
-var GithubService = class {
+var GithubService = class GithubService {
 	token;
 	baseUrl = "https://api.github.com";
 	rawBaseUrl = "https://raw.githubusercontent.com";
+	sessionCache = /* @__PURE__ */ new Map();
+	inFlight = /* @__PURE__ */ new Map();
+	rateLimitError = null;
+	operationEpoch = 0;
 	constructor(token) {
 		this.token = token;
 	}
@@ -4039,49 +5296,155 @@ var GithubService = class {
 		if (this.token) h.Authorization = `token ${this.token}`;
 		return h;
 	}
+	/** True once this operation has observed confirmed throttling. */
+	get rateLimited() {
+		return this.rateLimitError !== null;
+	}
+	/** The first throttling failure that latched this operation, if any. */
+	get rateLimitFailure() {
+		return this.rateLimitError;
+	}
+	/**
+	* Clears session caches and the throttle latch. Call only between commands
+	* that reuse the same client. Requests already in flight settle normally,
+	* but their results are not retained.
+	*/
+	resetOperation() {
+		this.sessionCache.clear();
+		this.inFlight.clear();
+		this.rateLimitError = null;
+		this.operationEpoch += 1;
+	}
+	/**
+	* Single-flight per request identity: concurrent callers share one pending
+	* request, completed values are reused within the operation, and failures
+	* are never cached (so a recovered request can be retried).
+	*/
+	async sessionRequest(key, run) {
+		const cached = this.sessionCache.get(key);
+		if (cached !== void 0) return detachValue(cached);
+		const pending = this.inFlight.get(key);
+		if (pending) return detachValue(await pending);
+		const epoch = this.operationEpoch;
+		const promise = this.runSessionRequest(key, epoch, run);
+		this.inFlight.set(key, promise);
+		return promise;
+	}
+	async runSessionRequest(key, epoch, run) {
+		try {
+			const value = await run();
+			if (epoch === this.operationEpoch && value !== null && value !== void 0) this.sessionCache.set(key, detachValue(value));
+			return value;
+		} finally {
+			if (epoch === this.operationEpoch) this.inFlight.delete(key);
+		}
+	}
+	/**
+	* Performs one HTTP request, rejecting with a typed failure for any non-2xx
+	* response or transport error.
+	*
+	* - `authenticated` reflects the Authorization header actually attached to
+	*   this request, never a constructor assumption.
+	* - A status/header-decidable throttle latches synchronously; only an
+	*   ambiguous 403 awaits its bounded body, and that latch is guarded by the
+	*   epoch captured before the request started.
+	* - Transport messages are fixed text; the raw error (which may contain
+	*   credentials in a URL) stays internal to `cause`.
+	*/
+	async request(url, init) {
+		if (this.rateLimitError) throw this.rateLimitError;
+		const epoch = this.operationEpoch;
+		const authenticated = GithubService.hasAttachedAuthorization(init);
+		let res;
+		try {
+			res = init === void 0 ? await (0, cross_fetch.default)(url) : await (0, cross_fetch.default)(url, init);
+		} catch (error) {
+			throw new GithubRequestError({
+				kind: "transport",
+				message: "GitHub request failed before a response was received",
+				endpoint: url,
+				authenticated,
+				cause: error
+			});
+		}
+		if (!res.ok) {
+			const verdict = classifyGithubStatus(res, url, authenticated);
+			if (verdict !== "ambiguous") {
+				if (verdict.kind === "rate-limited" && epoch === this.operationEpoch && !this.rateLimitError) this.rateLimitError = verdict;
+				abandonResponseBody(res);
+				throw verdict;
+			}
+			const failure = await classifyAmbiguous403(res, url, authenticated);
+			if (failure.kind === "rate-limited" && epoch === this.operationEpoch && !this.rateLimitError) this.rateLimitError = failure;
+			throw failure;
+		}
+		return res;
+	}
+	/** True only when this request's headers actually carry an Authorization value. */
+	static hasAttachedAuthorization(init) {
+		const headers = init?.headers;
+		if (!headers) return false;
+		if (Array.isArray(headers)) return headers.some((entry) => entry[0]?.toLowerCase() === "authorization" && Boolean(entry[1]));
+		if (typeof Headers !== "undefined" && headers instanceof Headers) return Boolean(headers.get("authorization"));
+		return Object.entries(headers).some(([name, value]) => name.toLowerCase() === "authorization" && typeof value === "string" && value.length > 0);
+	}
+	/** Rate-limit and access-denial failures are actionable; never flatten them to null. */
+	static isActionable(error) {
+		return GithubRequestError.isRateLimit(error) || GithubRequestError.isAccessDenial(error);
+	}
+	static isAbsence(error) {
+		return error instanceof GithubRequestError && error.kind === "not-found";
+	}
 	/**
 	* Fetches the recursive Git tree for a repository.
 	* @param owner Repository owner
 	* @param repo Repository name
 	* @param ref Git reference (branch, tag, or commit SHA)
-	* @returns The tree data or null if not found
+	* @param options.commit Resolved commit; keys the shared tree by immutable identity
+	* @returns The tree data, or null when the object or reference does not exist
 	*/
-	async getRepoTree(owner, repo, ref) {
-		const url = `${this.baseUrl}/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`;
-		try {
-			const res = await (0, cross_fetch.default)(url, { headers: this.headers });
-			if (!res.ok) {
-				if (res.status === 404) return null;
-				throw new Error(`GitHub API Error: ${res.status} ${res.statusText}`);
+	async getRepoTree(owner, repo, ref, options) {
+		const identity = options?.commit ?? ref;
+		const key = options?.commit ? `tree-commit:${owner}/${repo}@${options.commit}` : `tree-ref:${owner}/${repo}@${ref}`;
+		const url = `${this.baseUrl}/repos/${owner}/${repo}/git/trees/${identity}?recursive=1`;
+		return this.sessionRequest(key, async () => {
+			try {
+				return await (await this.request(url, { headers: this.headers })).json();
+			} catch (error) {
+				if (GithubService.isActionable(error)) throw error;
+				if (GithubService.isAbsence(error)) return null;
+				console.error(picocolors.default.red(`Failed to fetch repo tree: ${error}`));
+				return null;
 			}
-			return await res.json();
-		} catch (error) {
-			console.error(picocolors.default.red(`Failed to fetch repo tree: ${error}`));
-			return null;
-		}
+		});
 	}
 	/**
 	* Fetches raw file bytes from GitHub and validates their Git blob identity.
 	* Text callers should use getRawFile; package callers use this byte-preserving path.
 	*/
 	async getRawFileBytes(owner, repo, ref, path, options) {
-		const url = `${this.rawBaseUrl}/${owner}/${repo}/${ref}/${path}`;
-		try {
-			const res = await (0, cross_fetch.default)(url);
-			if (!res.ok) return null;
-			const content = Buffer.from(await res.arrayBuffer());
-			const maxBytes = options?.maxBytes ?? 1048576;
-			if (content.byteLength > maxBytes) throw new IntegrityError(`${path}: ${content.byteLength} bytes exceeds the ${maxBytes}-byte limit`);
-			if (options?.expectedSha) {
-				const actualSha = gitBlobSha1(content);
-				if (actualSha !== options.expectedSha) throw new IntegrityError(`${path}: blob sha mismatch (expected ${options.expectedSha}, got ${actualSha}) — download may be corrupted or tampered with`);
+		const identity = options?.commit ?? ref;
+		const maxBytes = options?.maxBytes ?? 1048576;
+		const key = `raw:${owner}/${repo}@${identity}:${path}#${options?.expectedSha ?? ""}#${maxBytes}`;
+		const url = `${this.rawBaseUrl}/${owner}/${repo}/${identity}/${path}`;
+		return this.sessionRequest(key, async () => {
+			try {
+				const res = await this.request(url);
+				const content = Buffer.from(await res.arrayBuffer());
+				if (content.byteLength > maxBytes) throw new IntegrityError(`${path}: ${content.byteLength} bytes exceeds the ${maxBytes}-byte limit`);
+				if (options?.expectedSha) {
+					const actualSha = gitBlobSha1(content);
+					if (actualSha !== options.expectedSha) throw new IntegrityError(`${path}: blob sha mismatch (expected ${options.expectedSha}, got ${actualSha}) — download may be corrupted or tampered with`);
+				}
+				return content;
+			} catch (error) {
+				if (error instanceof IntegrityError) throw error;
+				if (GithubService.isActionable(error)) throw error;
+				if (GithubService.isAbsence(error)) return null;
+				console.error(picocolors.default.red(`Failed to fetch file ${path}: ${error}`));
+				return null;
 			}
-			return content;
-		} catch (error) {
-			if (error instanceof IntegrityError) throw error;
-			console.error(picocolors.default.red(`Failed to fetch file ${path}: ${error}`));
-			return null;
-		}
+		});
 	}
 	/**
 	* Fetches raw file content as UTF-8 for established text-only callers.
@@ -4095,14 +5458,17 @@ var GithubService = class {
 	* @param repo Repository name
 	*/
 	async getLatestReleaseTag(owner, repo) {
-		try {
-			const res = await (0, cross_fetch.default)(`${this.baseUrl}/repos/${owner}/${repo}/releases/latest`, { headers: this.headers });
-			if (!res.ok) return null;
-			return (await res.json()).tag_name;
-		} catch (error) {
-			if (process.env.DEBUG) console.warn(`[GithubService] Failed to fetch latest release: ${error}`);
-			return null;
-		}
+		const key = `latest-release:${owner}/${repo}`;
+		const url = `${this.baseUrl}/repos/${owner}/${repo}/releases/latest`;
+		return this.sessionRequest(key, async () => {
+			try {
+				return (await (await this.request(url, { headers: this.headers })).json()).tag_name;
+			} catch (error) {
+				if (GithubService.isActionable(error)) throw error;
+				if (process.env.DEBUG) console.warn(`[GithubService] Failed to fetch latest release: ${error}`);
+				return null;
+			}
+		});
 	}
 	/**
 	* Fetches basic repository information, such as the default branch.
@@ -4110,34 +5476,59 @@ var GithubService = class {
 	* @param repo Repository name
 	*/
 	async getRepoInfo(owner, repo) {
+		const key = `repo-info:${owner}/${repo}`;
 		const url = `${this.baseUrl}/repos/${owner}/${repo}`;
-		try {
-			const res = await (0, cross_fetch.default)(url, { headers: this.headers });
-			if (!res.ok) return null;
-			return await res.json();
-		} catch (error) {
-			console.error(picocolors.default.red(`Failed to fetch repo info: ${error}`));
-			return null;
-		}
+		return this.sessionRequest(key, async () => {
+			try {
+				return await (await this.request(url, { headers: this.headers })).json();
+			} catch (error) {
+				if (GithubService.isActionable(error)) throw error;
+				console.error(picocolors.default.red(`Failed to fetch repo info: ${error}`));
+				return null;
+			}
+		});
 	}
 	/**
 	* Downloads multiple text files concurrently with a limit. Existing text
 	* consumers retain UTF-8 strings; package sync uses the byte variant below.
+	*
+	* Rejects with the first known `IntegrityError` or access-denied
+	* `GithubRequestError` in input-task order after every started worker
+	* settles, unless a throttle latch owns the terminal `rateLimited` result.
 	*/
 	async downloadFilesConcurrent(tasks, concurrency = 10) {
-		return this.downloadFilesConcurrentWith(tasks, concurrency, (task) => this.getRawFile(task.owner, task.repo, task.ref, task.path, { expectedSha: task.sha }));
+		return this.downloadFilesConcurrentWith(tasks, concurrency, (task) => this.getRawFile(task.owner, task.repo, task.ref, task.path, {
+			expectedSha: task.sha,
+			commit: task.commit
+		}));
 	}
 	/**
 	* Downloads multiple files without decoding their response bytes.
+	*
+	* Same terminal-failure contract as `downloadFilesConcurrent`, so package
+	* callers cannot treat verification or authorization failure as absence.
 	*/
 	async downloadFilesConcurrentBytes(tasks, concurrency = 10) {
-		return this.downloadFilesConcurrentWith(tasks, concurrency, (task) => this.getRawFileBytes(task.owner, task.repo, task.ref, task.path, { expectedSha: task.sha }));
+		return this.downloadFilesConcurrentWith(tasks, concurrency, (task) => this.getRawFileBytes(task.owner, task.repo, task.ref, task.path, {
+			expectedSha: task.sha,
+			commit: task.commit
+		}));
 	}
+	/**
+	* Runs the batch, settles every started worker, then decides the terminal
+	* outcome:
+	* - a throttle latch keeps priority (`rateLimited` result, as before);
+	* - otherwise the first `IntegrityError` or access-denied failure in
+	*   input-task order is rethrown, so callers never mistake verification or
+	*   authorization failure for missing data;
+	* - a genuine missing file (404) stays a `failed` result.
+	*/
 	async downloadFilesConcurrentWith(tasks, concurrency, download) {
 		const outcomes = Array(tasks.length);
 		let nextIndex = 0;
 		const worker = async () => {
 			while (nextIndex < tasks.length) {
+				if (this.rateLimitError) return;
 				const index = nextIndex++;
 				const task = tasks[index];
 				if (!task) continue;
@@ -4156,7 +5547,8 @@ var GithubService = class {
 					outcomes[index] = {
 						kind: "failed",
 						path: task.path,
-						reason: error instanceof Error ? error.message : String(error)
+						reason: error instanceof Error ? error.message : String(error),
+						error
 					};
 				}
 			}
@@ -4164,16 +5556,32 @@ var GithubService = class {
 		await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length) }, worker));
 		const ok = [];
 		const failed = [];
-		for (const outcome of outcomes) {
-			if (!outcome) continue;
-			if (outcome.kind === "ok") ok.push({
+		for (let index = 0; index < tasks.length; index += 1) {
+			const outcome = outcomes[index];
+			const task = tasks[index];
+			if (outcome?.kind === "ok") ok.push({
 				path: outcome.path,
 				content: outcome.content
 			});
-			else failed.push({
+			else if (outcome?.kind === "failed") failed.push({
 				path: outcome.path,
 				reason: outcome.reason
 			});
+			else if (task && this.rateLimitError) failed.push({
+				path: task.path,
+				reason: `not attempted: ${this.rateLimitError.message}`
+			});
+		}
+		if (this.rateLimitError) return {
+			ok,
+			failed,
+			rateLimited: this.rateLimitError
+		};
+		for (let index = 0; index < outcomes.length; index += 1) {
+			const outcome = outcomes[index];
+			if (outcome?.kind !== "failed" || outcome.error === void 0) continue;
+			const error = outcome.error;
+			if (error instanceof IntegrityError || GithubRequestError.isAccessDenial(error)) throw error;
 		}
 		return {
 			ok,
@@ -4202,18 +5610,20 @@ var GithubService = class {
 	* Returns null on non-200, invalid response, or network failure.
 	*/
 	async resolveCommit(owner, repo, ref) {
+		const key = `commit:${owner}/${repo}@${ref}`;
 		const url = `${this.baseUrl}/repos/${owner}/${repo}/commits/${encodeURIComponent(ref)}`;
-		try {
-			const res = await (0, cross_fetch.default)(url, { headers: {
-				...this.headers,
-				Accept: "application/vnd.github.sha"
-			} });
-			if (!res.ok) return null;
-			const text = (await res.text()).trim();
-			return /^[0-9a-f]{40}$/i.test(text) ? text : null;
-		} catch {
-			return null;
-		}
+		return this.sessionRequest(key, async () => {
+			try {
+				const text = (await (await this.request(url, { headers: {
+					...this.headers,
+					Accept: "application/vnd.github.sha"
+				} })).text()).trim();
+				return /^[0-9a-f]{40}$/i.test(text) ? text : null;
+			} catch (error) {
+				if (GithubService.isActionable(error)) throw error;
+				return null;
+			}
+		});
 	}
 	/**
 	* Fetches and validates a release MANIFEST.json for a release tag.
@@ -4225,34 +5635,35 @@ var GithubService = class {
 	* failed verification must never look like "nothing to verify".
 	*/
 	async getReleaseManifest(owner, repo, tag) {
+		const key = `release-manifest:${owner}/${repo}@${tag}`;
 		const url = `https://github.com/${owner}/${repo}/releases/download/${tag}/MANIFEST.json`;
-		let res;
-		try {
-			res = await (0, cross_fetch.default)(url);
-		} catch (error) {
-			const detail = error instanceof Error ? error.message : String(error);
-			throw new Error(`Failed to fetch MANIFEST.json for ${tag}: ${detail}`, { cause: error });
-		}
-		if (res.status === 404) return null;
-		if (!res.ok) throw new Error(`Failed to fetch MANIFEST.json for ${tag}: HTTP ${res.status}`);
-		let data;
-		try {
-			data = await res.json();
-		} catch (error) {
-			throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: ${error instanceof Error ? error.message : String(error)}`);
-		}
-		if (typeof data !== "object" || data === null || Array.isArray(data)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: expected an object`);
-		const record = data;
-		if (record.schema_version !== 1) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: unsupported schema_version`);
-		if (record.tag !== tag) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: tag does not match`);
-		if (typeof record.commit !== "string" || !/^[0-9a-f]{40}$/i.test(record.commit)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: invalid commit`);
-		if (typeof record.files !== "object" || record.files === null || Array.isArray(record.files)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: missing files map`);
-		const files = record.files;
-		for (const [key, value] of Object.entries(files)) {
-			if (typeof key !== "string" || typeof value !== "string") throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: non-string entry ${key}`);
-			if (!/^[0-9a-f]{64}$/i.test(value)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: invalid digest for ${key}`);
-		}
-		return record;
+		return this.sessionRequest(key, async () => {
+			let res;
+			try {
+				res = await this.request(url);
+			} catch (error) {
+				if (GithubService.isAbsence(error)) return null;
+				throw error;
+			}
+			let data;
+			try {
+				data = await res.json();
+			} catch (error) {
+				throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			if (typeof data !== "object" || data === null || Array.isArray(data)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: expected an object`);
+			const record = data;
+			if (record.schema_version !== 1) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: unsupported schema_version`);
+			if (record.tag !== tag) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: tag does not match`);
+			if (typeof record.commit !== "string" || !/^[0-9a-f]{40}$/i.test(record.commit)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: invalid commit`);
+			if (typeof record.files !== "object" || record.files === null || Array.isArray(record.files)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: missing files map`);
+			const files = record.files;
+			for (const [entry, value] of Object.entries(files)) {
+				if (typeof entry !== "string" || typeof value !== "string") throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: non-string entry ${entry}`);
+				if (!/^[0-9a-f]{64}$/i.test(value)) throw new IntegrityError(`Invalid MANIFEST.json for ${tag}: invalid digest for ${entry}`);
+			}
+			return record;
+		});
 	}
 };
 //#endregion
@@ -5020,38 +6431,6 @@ async function removeEmptyParents(rootDir, dir) {
 	}
 }
 //#endregion
-//#region src/services/install/safePath.ts
-/**
-* Asserts that a target file path resides inside rootDir and that NO intermediate
-* directory or terminal file under rootDir is a symbolic link.
-*
-* Requirements:
-* - rootDir may itself be a symlink (or inside one); components under rootDir must NOT be.
-* - Both existing files and dangling symlinks must be detected via lstat.
-* - Fails closed if lexical containment is breached or if any component under rootDir is a symlink.
-*
-* @param rootDir The trusted root directory
-* @param targetPath The destination file/directory path to check
-*/
-async function assertNoSymlinksUnderRoot(rootDir, targetPath) {
-	const resolvedRoot = path.default.resolve(rootDir);
-	const resolvedTarget = path.default.resolve(targetPath);
-	const relative = path.default.relative(resolvedRoot, resolvedTarget);
-	if (relative === ".." || relative.startsWith(`..${path.default.sep}`) || path.default.isAbsolute(relative)) throw new Error(`Path traversal or outside target detected: "${targetPath}" is outside "${rootDir}"`);
-	const segments = relative.split(path.default.sep).filter(Boolean);
-	let current = resolvedRoot;
-	for (const segment of segments) {
-		current = path.default.join(current, segment);
-		try {
-			if ((await fs_extra.default.lstat(current)).isSymbolicLink()) throw new Error(`Symlink path component not permitted: "${current}" is a symbolic link under "${rootDir}"`);
-		} catch (err) {
-			if (err instanceof Error && err.message.includes("Symlink path component")) throw err;
-			if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") break;
-			throw err;
-		}
-	}
-}
-//#endregion
 //#region src/services/install/OwnershipWriter.ts
 var PassthroughWriter = class {
 	rootDir;
@@ -5085,7 +6464,7 @@ var OwnershipWriter = class {
 		await assertNoSymlinksUnderRoot(this.opts.rootDir, absPath);
 		const rel = toPosixRel(this.opts.rootDir, absPath);
 		this.touched.add(rel);
-		const incoming = sha256(content);
+		const incoming = sha256$1(content);
 		const entry = {
 			...meta,
 			sha256: incoming
@@ -5097,7 +6476,7 @@ var OwnershipWriter = class {
 			this.next[rel] = entry;
 			return;
 		}
-		const current = sha256(await fs_extra.default.readFile(absPath));
+		const current = sha256$1(await fs_extra.default.readFile(absPath));
 		if (current === incoming) {
 			this.plan.unchanged.push(rel);
 			this.next[rel] = entry;
@@ -5140,7 +6519,7 @@ var OwnershipWriter = class {
 			const abs = path.default.join(this.opts.rootDir, rel);
 			await assertNoSymlinksUnderRoot(this.opts.rootDir, abs);
 			if (!await fs_extra.default.pathExists(abs)) continue;
-			if (sha256(await fs_extra.default.readFile(abs)) !== prev.sha256) {
+			if (sha256$1(await fs_extra.default.readFile(abs)) !== prev.sha256) {
 				this.plan.keptOrphans.push(rel);
 				continue;
 			}
@@ -5170,6 +6549,8 @@ var OwnershipWriter = class {
 };
 //#endregion
 //#region src/services/SkillSyncService.ts
+var GIT_BLOB_SHA1_RE = /^[0-9a-f]{40}$/;
+var ATTRIBUTION_FAMILY_RE = /^(LICENSE|NOTICE)(?:\.(?:md|txt))?$/i;
 /**
 * A selected registry category or package could not be assembled completely.
 * Callers must not write installations or lockfiles from this partial result.
@@ -5189,6 +6570,7 @@ var SkillSyncService = class {
 	githubService;
 	failedPackagesByCategory = /* @__PURE__ */ new Map();
 	failedCategories = /* @__PURE__ */ new Set();
+	failureDetails = /* @__PURE__ */ new Map();
 	constructor(githubService) {
 		this.githubService = githubService;
 	}
@@ -5198,6 +6580,7 @@ var SkillSyncService = class {
 	async assembleSkills(categories, config, verifiers = {}, trees = {}, origins = {}, requireSkillDefinition = false) {
 		this.failedPackagesByCategory.clear();
 		this.failedCategories.clear();
+		this.failureDetails.clear();
 		const collected = [];
 		const collectedOrigins = /* @__PURE__ */ new Map();
 		const conflicts = [];
@@ -5211,21 +6594,31 @@ var SkillSyncService = class {
 			const catConfig = config.skills[category];
 			const ref = catConfig.ref || "main";
 			console.log(picocolors.default.gray(`  - Discovering ${category} (${ref})...`));
-			const treeData = trees[category] ?? await this.githubService.getRepoTree(owner, repo, ref);
+			const resolvedSource = origins[category];
+			const commit = resolvedSource?.commit && GIT_BLOB_SHA1_RE.test(resolvedSource.commit) ? resolvedSource.commit : void 0;
+			const verifier = verifiers[category];
+			if (verifier && commit) {
+				const rejection = verifier.checkSourceCommit(commit);
+				if (rejection) throw new IntegrityError(`${category}@${ref}: ${rejection}`);
+			}
+			const treeData = trees[category] ?? (commit ? await this.githubService.getRepoTree(owner, repo, ref, { commit }) : await this.githubService.getRepoTree(owner, repo, ref));
 			if (!treeData) {
 				this.failedCategories.add(category);
 				console.log(picocolors.default.red(`    ❌ Failed to fetch ${category}@${ref}.`));
 				continue;
 			}
-			const resolvedSource = origins[category];
 			const origin = resolvedSource ? {
 				category,
 				ref: resolvedSource.ref,
 				commit: resolvedSource.commit
 			} : void 0;
+			const source = commit && resolvedSource ? {
+				requestedRef: resolvedSource.ref,
+				resolvedCommit: commit
+			} : void 0;
 			const foldersToSync = resolveSkillFolders(category, catConfig, treeData.tree, requireSkillDefinition);
 			for (const absOrRelSkill of foldersToSync) {
-				const skill = await this.fetchSkill(owner, repo, ref, category, absOrRelSkill, treeData.tree, verifiers);
+				const skill = await this.fetchSkill(owner, repo, ref, category, absOrRelSkill, treeData.tree, verifiers, source);
 				if (skill) {
 					const collectedSkill = origin ? {
 						...skill,
@@ -5250,7 +6643,11 @@ var SkillSyncService = class {
 		const failures = [
 			...this.failedCategories,
 			...conflicts,
-			...Array.from(this.failedPackagesByCategory).flatMap(([category, skills]) => Array.from(skills, (skill) => `${category}/${skill}`))
+			...Array.from(this.failedPackagesByCategory).flatMap(([category, skills]) => Array.from(skills, (skill) => {
+				const key = `${category}/${skill}`;
+				const detail = this.failureDetails.get(key);
+				return detail ? `${key} (${detail})` : key;
+			}))
 		];
 		if (failures.length > 0) throw new SkillAssemblyError(failures);
 		return collected;
@@ -5260,6 +6657,7 @@ var SkillSyncService = class {
 	*/
 	async writeSkills(skills, config, agents, writer = new PassthroughWriter(process.cwd()), rootDir = process.cwd()) {
 		const overrides = config.custom_overrides || [];
+		const written = /* @__PURE__ */ new Map();
 		for (const agentId of agents) {
 			const basePath = SUPPORTED_AGENTS.find((agent) => agent.id === agentId)?.path;
 			if (!basePath) continue;
@@ -5269,9 +6667,43 @@ var SkillSyncService = class {
 			const agentDef = SUPPORTED_AGENTS.find((agent) => agent.id === agentId);
 			if (!agentDef?.path) continue;
 			const basePath = agentDef.path;
-			for (const skill of skills) await this.writeSkillForAgent(agentId, skill, overrides, basePath, writer, config, false, rootDir);
+			for (const skill of skills) {
+				const bindings = await this.writeSkillForAgent(agentId, skill, overrides, basePath, writer, config, false, rootDir);
+				for (const { name, binding } of bindings) {
+					const key = `${skill.category}/${skill.skill}\0${name}`;
+					const existing = written.get(key) ?? [];
+					if (!existing.some((current) => current.agent === binding.agent && current.path === binding.path)) existing.push(binding);
+					written.set(key, existing);
+				}
+			}
 			console.log(picocolors.default.gray(`  - Updated ${basePath}/ (${agentDef.name})`));
 		}
+		const registry = config.registry ?? "";
+		const packages = {};
+		for (const skill of skills) {
+			const origin = skill.origin;
+			if (!origin?.commit || !GIT_BLOB_SHA1_RE.test(origin.commit)) continue;
+			const files = [];
+			for (const file of skill.files) {
+				if (!file.attribution) continue;
+				const destinations = written.get(`${skill.category}/${skill.skill}\0${file.name}`);
+				if (!destinations || destinations.length === 0) continue;
+				files.push({
+					...file.attribution,
+					name: file.name,
+					destinations
+				});
+			}
+			if (files.length === 0) continue;
+			packages[`${skill.category}/${skill.skill}`] = {
+				registry,
+				declaringCategory: origin.category,
+				requestedRef: origin.ref,
+				resolvedCommit: origin.commit,
+				files
+			};
+		}
+		return packages;
 	}
 	async writeSkillForAgent(agentId, skill, overrides, basePath, writer, config, preflightOnly = false, rootDir = basePath) {
 		const isKiro = agentId === Agent.Kiro;
@@ -5297,50 +6729,136 @@ var SkillSyncService = class {
 			const content = isKiro && fileItem.name === "SKILL.md" ? this.transformSkillForKiro(fileItem.content, skill.category) : fileItem.bytes ?? fileItem.content;
 			pending.push({
 				target: targetFilePath,
-				content
+				content,
+				name: fileItem.name,
+				attributed: fileItem.attribution !== void 0
 			});
 		}
-		if (pending === null) return;
-		for (const { target, content } of pending) await writer.write(target, content, {
-			owner: "skill",
-			source,
-			agent: agentId
-		});
+		if (pending === null) return [];
+		const bindings = [];
+		for (const { target, content, name, attributed } of pending) {
+			await writer.write(target, content, {
+				owner: "skill",
+				source,
+				agent: agentId
+			});
+			if (!attributed) continue;
+			const installedDigest = await this.readInstalledDigest(target);
+			const writtenDigest = sha256$1(content);
+			if (installedDigest !== writtenDigest) continue;
+			bindings.push({
+				name,
+				binding: {
+					agent: agentId,
+					path: toPosixRel(rootDir, target),
+					sha256: writtenDigest
+				}
+			});
+		}
+		return bindings;
 	}
-	async fetchSkill(owner, repo, ref, category, absOrRelSkill, tree, verifiers = {}) {
+	/** Digest of the file as it exists on disk, or null when unreadable. */
+	async readInstalledDigest(absPath) {
+		try {
+			return sha256$1(await fs_extra.default.readFile(absPath));
+		} catch {
+			return null;
+		}
+	}
+	async fetchSkill(owner, repo, ref, category, absOrRelSkill, tree, verifiers = {}, source) {
 		const [sourceCat, skillName] = absOrRelSkill.includes("/") ? absOrRelSkill.split("/") : [category, absOrRelSkill];
 		if (!sourceCat || !skillName) return null;
 		const prefix = `skills/${sourceCat}/${skillName}/`;
 		const packageFiles = tree.filter((file) => file.type === "blob" && file.path.startsWith(prefix) && this.isPackageResource(file.path.slice(prefix.length)));
-		const rootAttributionFiles = tree.filter((file) => file.type === "blob" && this.isRootAttributionFile(file.path) && !packageFiles.some((packageFile) => packageFile.path.slice(prefix.length).toLowerCase() === file.path.toLowerCase()));
-		const downloadTasks = [...packageFiles, ...rootAttributionFiles].sort((left, right) => left.path.localeCompare(right.path)).map((file) => ({
+		const localFamilies = new Set(packageFiles.map((file) => this.attributionFamily(file.path.slice(prefix.length))).filter((family) => family !== null));
+		const rootAttributionFiles = tree.filter((file) => {
+			if (file.type !== "blob" || !this.isRootAttributionFile(file.path)) return false;
+			const family = this.attributionFamily(file.path);
+			if (!family || localFamilies.has(family)) return false;
+			return !packageFiles.some((packageFile) => packageFile.path.slice(prefix.length).toLowerCase() === file.path.toLowerCase());
+		});
+		const selectedFiles = [...packageFiles, ...rootAttributionFiles].sort((left, right) => left.path.localeCompare(right.path));
+		const downloadTasks = selectedFiles.map((file) => ({
 			owner,
 			repo,
 			ref,
 			path: file.path,
-			sha: file.sha
+			sha: file.sha,
+			...source ? { commit: source.resolvedCommit } : {}
 		}));
 		const { ok: files, failed } = await this.githubService.downloadFilesConcurrentBytes(downloadTasks);
 		const verifier = verifiers[category];
+		let integrityFailure;
 		if (verifier) for (const f of files) {
-			if (this.isRootAttributionFile(f.path)) continue;
+			if (this.isRootAttributionFile(f.path)) {
+				const rejection = verifier.checkRootAttribution(f.path, f.content);
+				if (rejection) {
+					failed.push({
+						path: f.path,
+						reason: rejection
+					});
+					integrityFailure ??= {
+						path: f.path,
+						reason: rejection
+					};
+				}
+				continue;
+			}
 			const rejection = verifier.check(f.path, f.content);
-			if (rejection) failed.push({
-				path: f.path,
-				reason: rejection
-			});
+			if (rejection) {
+				failed.push({
+					path: f.path,
+					reason: rejection
+				});
+				integrityFailure ??= {
+					path: f.path,
+					reason: rejection
+				};
+			}
 		}
 		for (const failure of failed) console.log(picocolors.default.red(`    ❌ ${sourceCat}/${skillName}: ${failure.path} — ${failure.reason}`));
-		if (!packageFiles.some((file) => file.path === `${prefix}SKILL.md`) || failed.length > 0 || files.length !== downloadTasks.length) return null;
+		if (integrityFailure) throw new IntegrityError(`Release manifest verification failed for ${sourceCat}/${skillName}: ${integrityFailure.path} — ${integrityFailure.reason}`);
+		const hasSkillDefinition = packageFiles.some((file) => file.path === `${prefix}SKILL.md`);
+		if (!hasSkillDefinition || failed.length > 0 || files.length !== downloadTasks.length) {
+			this.markPackageFailed(sourceCat, skillName, failed[0]?.reason ?? (hasSkillDefinition ? "downloaded file count mismatch" : "missing SKILL.md"));
+			return null;
+		}
+		const blobShaByPath = new Map(selectedFiles.map((file) => [file.path, file.sha]));
+		const records = /* @__PURE__ */ new Map();
+		if (source) for (const file of files) {
+			const isPackageFile = file.path.startsWith(prefix);
+			const name = isPackageFile ? file.path.slice(prefix.length) : file.path;
+			if (this.attributionFamily(name) === null) continue;
+			const blobSha1 = blobShaByPath.get(file.path);
+			if (!blobSha1 || !GIT_BLOB_SHA1_RE.test(blobSha1)) {
+				this.markPackageFailed(sourceCat, skillName, `missing Git blob identity for ${file.path}`);
+				return null;
+			}
+			const basis = verifier?.hasManifestEntry(file.path) ? "release-manifest" : "commit-tree-blob";
+			records.set(name, {
+				sourcePath: file.path,
+				sourceKind: isPackageFile ? "package" : "root",
+				requestedRef: source.requestedRef,
+				resolvedCommit: source.resolvedCommit,
+				blobSha1,
+				sha256: sha256$1(file.content),
+				basis
+			});
+		}
 		console.log(picocolors.default.gray(`    + Fetched ${sourceCat}/${skillName} (${files.length} files)`));
 		return {
 			category: sourceCat,
 			skill: skillName,
-			files: files.map((file) => ({
-				name: file.path.startsWith(prefix) ? file.path.slice(prefix.length) : file.path,
-				content: file.content.toString("utf8"),
-				bytes: file.content
-			}))
+			files: files.map((file) => {
+				const name = file.path.startsWith(prefix) ? file.path.slice(prefix.length) : file.path;
+				const attribution = records.get(name);
+				return {
+					name,
+					content: file.content.toString("utf8"),
+					bytes: file.content,
+					...attribution ? { attribution } : {}
+				};
+			})
 		};
 	}
 	/**
@@ -5386,16 +6904,24 @@ var SkillSyncService = class {
 	isPackageResource(relativePath) {
 		return relativePath === "SKILL.md" || /^(references|scripts|assets)\//.test(relativePath) || this.isRootAttributionFile(relativePath);
 	}
+	attributionFamily(filePath) {
+		if (filePath.includes("/")) return null;
+		const match = ATTRIBUTION_FAMILY_RE.exec(filePath);
+		if (!match) return null;
+		return match[1].toLowerCase() === "license" ? "license" : "notice";
+	}
 	isRootAttributionFile(filePath) {
-		return !filePath.includes("/") && /^(LICENSE|NOTICE)(?:\.(?:md|txt))?$/i.test(filePath);
+		return this.attributionFamily(filePath) !== null;
 	}
-	markPackageFailed(category, skill) {
+	markPackageFailed(category, skill, detail) {
 		let failedSkills = this.failedPackagesByCategory.get(category);
 		if (!failedSkills) {
 			failedSkills = /* @__PURE__ */ new Set();
 			this.failedPackagesByCategory.set(category, failedSkills);
 		}
 		failedSkills.add(skill);
+		const key = `${category}/${skill}`;
+		if (detail && !this.failureDetails.has(key)) this.failureDetails.set(key, detail);
 	}
 	isRecord(value) {
 		return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -6260,15 +7786,17 @@ var WorkflowSyncService = class {
 	* need the collected files; new callers must use `acquireWorkflows` so an
 	* incomplete fetch is distinguishable from a deliberate empty selection.
 	*/
-	async assembleWorkflows(config, ref = "main", verifier) {
-		return (await this.acquireWorkflows(config, ref, verifier)).workflows;
+	async assembleWorkflows(config, ref = "main", verifier, commit) {
+		return (await this.acquireWorkflows(config, ref, verifier, commit)).workflows;
 	}
 	/**
 	* Acquires the selected canonical workflows and reports whether the desired
 	* set is complete. Partial discovery/download/integrity failures are
-	* `incomplete` and never authorize absence-based pruning.
+	* `incomplete` and never authorize absence-based pruning. When `commit` is
+	* supplied, discovery and downloads use that immutable identity instead of
+	* the mutable ref string.
 	*/
-	async acquireWorkflows(config, ref = "main", verifier) {
+	async acquireWorkflows(config, ref = "main", verifier, commit) {
 		if (config.workflows === false || config.workflows === void 0) return {
 			status: "disabled",
 			workflows: [],
@@ -6289,8 +7817,12 @@ var WorkflowSyncService = class {
 			}]
 		};
 		const { owner, repo } = githubMatch;
+		if (verifier && commit) {
+			const rejection = verifier.checkSourceCommit(commit);
+			if (rejection) throw new IntegrityError(`workflows@${ref}: ${rejection}`);
+		}
 		console.log(picocolors.default.gray(`  - Discovering workflows (${ref})...`));
-		const treeData = await this.githubService.getRepoTree(owner, repo, ref);
+		const treeData = await this.githubService.getRepoTree(owner, repo, ref, commit ? { commit } : void 0);
 		if (!treeData) {
 			console.log(picocolors.default.red(`    ❌ Failed to fetch workflows@${ref}.`));
 			return {
@@ -6317,21 +7849,21 @@ var WorkflowSyncService = class {
 				failures: []
 			};
 		}
-		const { ok: files, failed } = await this.githubService.downloadFilesConcurrent(workflowFiles.map((f) => ({
+		const downloadResult = await this.githubService.downloadFilesConcurrent(workflowFiles.map((f) => ({
 			owner,
 			repo,
 			ref,
 			path: f.path,
-			sha: f.sha
+			sha: f.sha,
+			...commit ? { commit } : {}
 		})));
+		if (downloadResult.rateLimited) throw downloadResult.rateLimited;
+		const { ok: files, failed } = downloadResult;
 		const okFiles = [];
 		for (const f of files) {
 			const rejection = verifier?.check(f.path, f.content);
-			if (rejection) failed.push({
-				path: f.path,
-				reason: rejection
-			});
-			else okFiles.push(f);
+			if (rejection) throw new IntegrityError(`${f.path}: ${rejection}`);
+			okFiles.push(f);
 		}
 		for (const failure of failed) console.log(picocolors.default.red(`    ❌ ${failure.path} — ${failure.reason}`));
 		const status = failed.length > 0 ? "incomplete" : "complete";
@@ -6401,7 +7933,7 @@ var WorkflowSyncService = class {
 					source: `workflow:${workflowName}`,
 					agent: SHARED_WORKFLOW_AGENT
 				});
-				const canonicalDigest = sha256(fileItem.content);
+				const canonicalDigest = sha256$1(fileItem.content);
 				writtenDigests.set(canonicalPath, canonicalDigest);
 				result.canonical.push({
 					name: workflowName,
@@ -6433,7 +7965,7 @@ var WorkflowSyncService = class {
 						continue;
 					}
 					if (this.isOverridden(targetFilePath, overrides)) continue;
-					const outputDigest = sha256(transformed.content);
+					const outputDigest = sha256$1(transformed.content);
 					const existingDigest = writtenDigests.get(targetFilePath);
 					if (existingDigest === void 0) {
 						await writer.write(targetFilePath, transformed.content, {
@@ -6452,7 +7984,7 @@ var WorkflowSyncService = class {
 						agent: agentId,
 						path: this.normalizePath(targetFilePath),
 						outputDigest,
-						canonicalDigest: sha256(fileItem.content)
+						canonicalDigest: sha256$1(fileItem.content)
 					});
 				}
 			}
@@ -6760,33 +8292,66 @@ var SpecialistTransformer = class {
 };
 //#endregion
 //#region src/services/SpecialistSyncService.ts
-/**
-* Service responsible for syncing specialist skills from the internal registry
-* to native agent configuration directories.
-*/
 var SpecialistSyncService = class {
 	githubService;
 	constructor(githubService = new GithubService(process.env.GITHUB_TOKEN)) {
 		this.githubService = githubService;
 	}
-	async assembleSpecialists(config, ref = "main", verifier) {
+	/**
+	* Acquires every remote specialist, reporting whether the selected set is
+	* complete. Fetches are bound to `commit` when the caller resolved one, so a
+	* tag that moved after resolution cannot supply different bytes.
+	*/
+	async acquireSpecialists(config, ref = "main", verifier, commit) {
 		const githubMatch = GithubService.parseGitHubUrl(config.registry);
-		if (!githubMatch) return [];
+		if (!githubMatch) return {
+			status: "incomplete",
+			specialists: [],
+			failures: [{
+				path: "registry",
+				reason: `Unsupported registry URL '${config.registry}'.`
+			}]
+		};
 		const { owner, repo } = githubMatch;
-		const treeData = await this.githubService.getRepoTree(owner, repo, ref);
-		if (!treeData) return [];
+		const treeOptions = commit ? { commit } : void 0;
+		if (verifier && commit) {
+			const rejection = verifier.checkSourceCommit(commit);
+			if (rejection) throw new IntegrityError(`specialists@${ref}: ${rejection}`);
+		}
+		const treeData = await this.githubService.getRepoTree(owner, repo, ref, treeOptions);
+		if (!treeData) return {
+			status: "incomplete",
+			specialists: [],
+			failures: [{
+				path: "specialists",
+				reason: `Failed to fetch specialists@${ref}.`
+			}]
+		};
 		const skillFiles = treeData.tree.filter((item) => item.type === "blob" && item.path.startsWith("skills/specialists/") && item.path.endsWith("/SKILL.md"));
 		const specialists = [];
+		const failures = [];
 		for (const file of skillFiles) {
 			const specialistName = file.path.split("/")[2];
-			if (!specialistName) continue;
-			const content = await this.githubService.getRawFile(owner, repo, ref, file.path);
-			if (!content) continue;
-			const rejection = verifier?.check(file.path, content);
-			if (rejection) {
-				console.log(picocolors.default.red(`    ❌ ${file.path} — ${rejection}`));
+			if (!specialistName) {
+				failures.push({
+					path: file.path,
+					reason: "specialist directory name is missing"
+				});
+				continue;
+			}
+			const content = await this.githubService.getRawFile(owner, repo, ref, file.path, {
+				expectedSha: file.sha,
+				...commit ? { commit } : {}
+			});
+			if (!content) {
+				failures.push({
+					path: file.path,
+					reason: "download failed"
+				});
 				continue;
 			}
+			const rejection = verifier?.check(file.path, content);
+			if (rejection) throw new IntegrityError(`${file.path}: ${rejection}`);
 			specialists.push({
 				category: "specialists",
 				skill: specialistName,
@@ -6796,9 +8361,13 @@ var SpecialistSyncService = class {
 				}]
 			});
 		}
-		return specialists;
+		return {
+			status: failures.length > 0 ? "incomplete" : "complete",
+			specialists,
+			failures
+		};
 	}
-	async syncCollectedSpecialists(rootDir, agents, specialists, writer = new PassthroughWriter(rootDir)) {
+	async writeSpecialists(rootDir, agents, specialists, writer = new PassthroughWriter(rootDir)) {
 		if (specialists.length === 0) return 0;
 		for (const agentId of agents) {
 			const agentDef = SUPPORTED_AGENTS.find((a) => a.id === agentId);
@@ -6825,20 +8394,18 @@ var SpecialistSyncService = class {
 		return specialists.length;
 	}
 	/**
-	* Syncs all specialists from a source directory to active agents.
-	* @param rootDir Project root directory
-	* @param agents List of agents to sync for
-	* @param sourceDir Optional custom source directory for specialists
+	* Reads every specialist from a project-local source directory. This is a
+	* local acquisition with no network I/O; the caller publishes the result
+	* through `writeSpecialists` after the shared preflight gates.
 	*/
-	async syncSpecialists(rootDir, agents, sourceDir, writer = new PassthroughWriter(rootDir)) {
-		const specialistsDir = sourceDir || path.default.join(rootDir, "skills/specialists");
-		if (!await fs_extra.default.pathExists(specialistsDir)) return 0;
-		const specialistFolders = (await fs_extra.default.readdir(specialistsDir)).filter((f) => {
-			return fs_extra.default.statSync(path.default.join(specialistsDir, f)).isDirectory();
+	async readLocalSpecialists(sourceDir) {
+		if (!await fs_extra.default.pathExists(sourceDir)) return [];
+		const specialistFolders = (await fs_extra.default.readdir(sourceDir)).filter((f) => {
+			return fs_extra.default.statSync(path.default.join(sourceDir, f)).isDirectory();
 		});
 		const collected = [];
 		for (const folder of specialistFolders) {
-			const skillPath = path.default.join(specialistsDir, folder, "SKILL.md");
+			const skillPath = path.default.join(sourceDir, folder, "SKILL.md");
 			if (!await fs_extra.default.pathExists(skillPath)) continue;
 			const content = await fs_extra.default.readFile(skillPath, "utf8");
 			collected.push({
@@ -6850,7 +8417,7 @@ var SpecialistSyncService = class {
 				}]
 			});
 		}
-		return this.syncCollectedSpecialists(rootDir, agents, collected, writer);
+		return collected;
 	}
 };
 //#endregion
@@ -7123,22 +8690,120 @@ var BackupService = class {
 };
 //#endregion
 //#region src/services/install/ManifestVerifier.ts
+function normalizeRepoPath(repoPath) {
+	return repoPath.replace(/^(\.\/|\/)+/, "");
+}
+function sha256(content) {
+	return (0, node_crypto.createHash)("sha256").update(content, Buffer.isBuffer(content) ? void 0 : "utf8").digest("hex");
+}
+function isListed(manifest, repoPath) {
+	return Object.prototype.hasOwnProperty.call(manifest.files, repoPath);
+}
 var ManifestVerifier = class {
 	manifest;
 	constructor(manifest) {
 		this.manifest = manifest;
 	}
+	/** Resolved commit this manifest claims, or null when no manifest exists. */
+	get commit() {
+		return this.manifest?.commit ?? null;
+	}
+	/**
+	* A manifest used for selected-source verification must describe the exact
+	* resolved commit. A syntactically valid but different commit is an
+	* integrity failure, never a silently skipped verification.
+	*/
+	checkSourceCommit(expected) {
+		if (!this.manifest) return null;
+		if (this.manifest.commit === expected) return null;
+		return `release MANIFEST.json commit '${this.manifest.commit}' does not match the resolved source commit '${expected}'`;
+	}
+	/**
+	* Whether the schema-1 files map binds this exact repo path. Root LICENSE
+	* and NOTICE entries are ordinary files-map entries, not a separate
+	* namespace.
+	*/
+	hasManifestEntry(repoPath) {
+		if (!this.manifest) return false;
+		return isListed(this.manifest, normalizeRepoPath(repoPath));
+	}
 	/** Returns null when OK (or no manifest), else a rejection reason. */
 	check(repoPath, content) {
 		if (!this.manifest) return null;
-		const normalized = repoPath.replace(/^(\.\/|\/)+/, "");
-		if (!Object.prototype.hasOwnProperty.call(this.manifest.files, normalized)) return "not listed in release MANIFEST.json";
+		const normalized = normalizeRepoPath(repoPath);
+		if (!isListed(this.manifest, normalized)) return "not listed in release MANIFEST.json";
 		const expectedSha = this.manifest.files[normalized];
-		if ((0, node_crypto.createHash)("sha256").update(content, Buffer.isBuffer(content) ? void 0 : "utf8").digest("hex") !== expectedSha) return "sha256 does not match release MANIFEST.json";
+		if (sha256(content) !== expectedSha) return "sha256 does not match release MANIFEST.json";
+		return null;
+	}
+	/**
+	* Root LICENSE/NOTICE live outside every category release scope, so legacy
+	* manifests do not list them. A listed root entry is always enforced; an
+	* unlisted one leaves the caller's verified commit-tree/blob basis intact
+	* instead of inventing a manifest verification that never happened.
+	*/
+	checkRootAttribution(repoPath, content) {
+		if (!this.manifest) return null;
+		const normalized = normalizeRepoPath(repoPath);
+		if (!isListed(this.manifest, normalized)) return null;
+		if (sha256(content) !== this.manifest.files[normalized]) return "sha256 does not match release MANIFEST.json root attribution";
 		return null;
 	}
 };
 //#endregion
+//#region src/services/install/UpdatePolicy.ts
+/**
+* Automatic version-update policy for release-pinned categories, workflows,
+* and specialists.
+*
+* A newer advertised release may only replace a configured pin automatically
+* when both refs are canonical stable semantic-version refs for the same tag
+* prefix and the candidate is strictly newer. Branches, commits, custom refs,
+* prereleases, downgrades, and equal versions stay explicit: accepting them
+* would silently move a user to incomparable source.
+*/
+var STABLE_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/**
+* @param currentRef currently configured ref, if the project already pinned one
+* @param candidateRef ref advertised by the registry for the same category
+* @param tagPrefix tag prefix published for that category (may be empty)
+* @returns true only for a strictly newer comparable stable release ref
+*/
+function isAutomaticUpgrade(currentRef, candidateRef, tagPrefix) {
+	if (typeof currentRef !== "string" || typeof candidateRef !== "string") return false;
+	const current = parseStableVersion(currentRef, tagPrefix);
+	const candidate = parseStableVersion(candidateRef, tagPrefix);
+	if (!current || !candidate) return false;
+	for (let index = 0; index < 3; index += 1) {
+		const order = compareNumericStrings(current[index], candidate[index]);
+		if (order !== 0) return order < 0;
+	}
+	return false;
+}
+/**
+* Strips the category tag prefix and requires a canonical `MAJOR.MINOR.PATCH`
+* core. Numeric components are returned as digit strings so comparison stays
+* exact beyond `Number.MAX_SAFE_INTEGER`.
+*/
+function parseStableVersion(ref, tagPrefix) {
+	if (!ref.startsWith(tagPrefix)) return null;
+	const version = ref.slice(tagPrefix.length);
+	const match = STABLE_VERSION.exec(version);
+	if (!match || match[0] !== version) return null;
+	const components = [
+		match[1],
+		match[2],
+		match[3]
+	];
+	for (const component of components) if (component.length > 1 && component.startsWith("0")) return null;
+	return components;
+}
+function compareNumericStrings(left, right) {
+	if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+//#endregion
 //#region src/services/install/RefResolver.ts
 var RefResolver = class {
 	github;
@@ -7225,21 +8890,21 @@ var RefResolver = class {
 //#endregion
 //#region src/services/SyncService.ts
 var defaultExec = (cmd, args) => {
-	const { promise, resolve, reject } = Promise.withResolvers();
-	(0, node_child_process.execFile)(cmd, args, (error, _stdout, stderr) => {
-		if (error) {
-			if (error.code === "ENOENT") return reject(error);
-			return resolve({
-				code: typeof error.code === "number" ? error.code : 1,
-				stderr: stderr || error.message
+	return new Promise((resolve, reject) => {
+		(0, node_child_process.execFile)(cmd, args, (error, _stdout, stderr) => {
+			if (error) {
+				if (error.code === "ENOENT") return reject(error);
+				return resolve({
+					code: typeof error.code === "number" ? error.code : 1,
+					stderr: stderr || error.message
+				});
+			}
+			resolve({
+				code: 0,
+				stderr: stderr || ""
 			});
-		}
-		resolve({
-			code: 0,
-			stderr: stderr || ""
 		});
 	});
-	return promise;
 };
 /**
 * Rejects an incomplete or malformed repository tree. A truncated or shaped
@@ -7278,6 +8943,8 @@ function assertIncludeTargetExists(category, expression, targetCategory, targetS
 	const skillPath = `${categoryPath}/${targetSkill}/SKILL.md`;
 	if (!tree.tree.some((item) => item.type === "blob" && item.path === skillPath)) throw new SkillAssemblyError([`${category} include ${expression} (requested skill missing)`]);
 }
+/** Bounded attribution-family filename used for installed variant discovery. */
+var ATTRIBUTION_FILE_NAME_RE = /^(LICENSE|NOTICE)(?:\.(?:md|txt))?$/i;
 /**
 * Service responsible for coordinating the synchronization of agent skills and workflows.
 * It acts as a facade, delegating specialized synchronization tasks to SkillSyncService
@@ -7306,6 +8973,8 @@ var SyncService = class {
 	};
 	warnedMovedTags = /* @__PURE__ */ new Set();
 	installScope = "all";
+	/** Attribution records for the packages actually published by this run. */
+	skillAttributionPackages = null;
 	constructor(githubService = new GithubService(process.env.GITHUB_TOKEN)) {
 		this.githubService = githubService;
 		this.skillSyncService = new SkillSyncService(githubService);
@@ -7328,7 +8997,14 @@ var SyncService = class {
 	async assembleSkills(categories, config, trees, origins, requireSkillDefinition = false) {
 		await this.warnIfSyncingFromSameRepo(config);
 		const skillCategories = categories.filter((category) => category !== "specialists");
-		return this.skillSyncService.assembleSkills(skillCategories, config, this.manifestVerifiers.skills, trees, origins, requireSkillDefinition);
+		const sourceOrigins = origins ?? Object.fromEntries(skillCategories.filter((category) => this.resolvedRefs?.skills[category]).map((category) => {
+			const source = this.resolvedRefs.skills[category];
+			return [category, {
+				ref: source.ref,
+				commit: source.commit
+			}];
+		}));
+		return this.skillSyncService.assembleSkills(skillCategories, config, this.manifestVerifiers.skills, trees, sourceOrigins, requireSkillDefinition);
 	}
 	/**
 	* Prefetches only the skill sources for a scoped apply. Resolves every
@@ -7438,6 +9114,7 @@ var SyncService = class {
 		const { lock, migratedFromV1 } = await this.lockfileService.load(process.cwd(), agents);
 		this.dryRun = opts.dryRun;
 		this.previousLock = lock;
+		this.skillAttributionPackages = null;
 		this.pendingWorkflowWrites = {
 			canonical: [],
 			bindings: []
@@ -7500,11 +9177,61 @@ var SyncService = class {
 				entries
 			};
 			if (catalog) lock.workflowCatalog = catalog;
+			const attribution = await this.buildAttributionCatalog(configured, entries);
+			if (attribution) lock.attributionCatalog = attribution;
 			await this.lockfileService.write(process.cwd(), lock);
 		}
 		return plan;
 	}
 	/**
+	* Merges this run's published attribution over the previous catalog at file
+	* granularity. A previous file survives only when the declaring category is
+	* still configured, this run did not publish replacement bytes for that file,
+	* and every recorded destination still survives ownership finalization with
+	* the exact recorded bytes. Preserved overrides/untouched files therefore
+	* keep their provenance instead of reading as removals; pruned destinations,
+	* removed agents, unconfigured categories and edited copies still drop.
+	*/
+	async buildAttributionCatalog(configured, entries) {
+		const previous = this.previousLock?.attributionCatalog;
+		const written = this.skillAttributionPackages;
+		if (!written && !previous) return void 0;
+		const mergedPackages = {};
+		for (const [packageId, record] of Object.entries(previous?.packages ?? {})) {
+			if (!configured.has(record.declaringCategory)) continue;
+			const replacement = written?.[packageId];
+			const retainedFiles = [];
+			for (const file of record.files) {
+				if (replacement?.files.some((candidate) => candidate.name === file.name)) continue;
+				if (await this.attributionFileDestinationsSurvive(file, entries)) retainedFiles.push(file);
+			}
+			if (retainedFiles.length === 0) continue;
+			mergedPackages[packageId] = {
+				...replacement ?? record,
+				files: [...replacement?.files ?? [], ...retainedFiles]
+			};
+		}
+		const merged = buildAttributionCatalog({
+			...mergedPackages,
+			...written ?? {}
+		});
+		if (previous) return merged;
+		return Object.keys(merged.packages).length > 0 ? merged : void 0;
+	}
+	/**
+	* A retained file must describe only bytes that are still installed: every
+	* destination has to survive ownership finalization for the recorded agent
+	* and still hash to its recorded digest.
+	*/
+	async attributionFileDestinationsSurvive(file, entries) {
+		for (const binding of file.destinations) {
+			const entry = entries[binding.path];
+			if (!entry || entry.agent !== binding.agent) return false;
+			if (await readInstalledAttributionDigest(process.cwd(), binding.path) !== binding.sha256) return false;
+		}
+		return true;
+	}
+	/**
 	* Builds the catalog from files that survived ownership reconciliation.
 	* Canonical bodies that were kept edited/overridden and native exports whose
 	* on-disk bytes differ from the deterministic output are omitted rather than
@@ -7539,7 +9266,7 @@ var SyncService = class {
 			} catch {
 				continue;
 			}
-			const digest = sha256(canonicalBytes);
+			const digest = sha256$1(canonicalBytes);
 			if (digest !== planned.digest) continue;
 			const nativeBindings = [];
 			const nativeConflicts = [];
@@ -7550,7 +9277,7 @@ var SyncService = class {
 				try {
 					outputBytes = await fs_extra.default.readFile(outputPath);
 				} catch {}
-				if (outputBytes === null || sha256(outputBytes) !== binding.outputDigest) {
+				if (outputBytes === null || sha256$1(outputBytes) !== binding.outputDigest) {
 					nativeConflicts.push({
 						agent: binding.agent,
 						path: binding.path
@@ -7700,28 +9427,244 @@ var SyncService = class {
 	async writeSkills(skills, config) {
 		if (!this.dryRun && this.installScope !== "skills") await this.notifyLegacyAgentFolder();
 		const agents = await this.resolveTargetAgents(config);
-		await this.skillSyncService.writeSkills(skills, config, agents, this.writer);
+		this.skillAttributionPackages = await this.skillSyncService.writeSkills(skills, config, agents, this.writer);
 	}
 	async assembleWorkflows(config) {
 		const ref = this.resolvedRefs?.workflows.ref || config.workflows_ref || "main";
-		return this.workflowSyncService.assembleWorkflows(config, ref, this.manifestVerifiers.workflows);
+		return this.workflowSyncService.assembleWorkflows(config, ref, this.manifestVerifiers.workflows, this.resolvedRefs?.workflows.commit ?? void 0);
 	}
 	async acquireWorkflows(config) {
 		const ref = this.resolvedRefs?.workflows.ref || config.workflows_ref || "main";
-		return this.workflowSyncService.acquireWorkflows(config, ref, this.manifestVerifiers.workflows);
+		return this.workflowSyncService.acquireWorkflows(config, ref, this.manifestVerifiers.workflows, this.resolvedRefs?.workflows.commit ?? void 0);
 	}
 	async writeWorkflows(workflows, config) {
 		const agents = await this.resolveTargetAgents(config);
 		this.pendingWorkflowWrites = await this.workflowSyncService.writeWorkflows(workflows, config, agents, this.writer);
 	}
-	async syncSpecialists(config) {
-		const agents = await this.resolveTargetAgents(config);
-		if (agents.length === 0) return true;
+	/**
+	* Acquires every desired specialist before any managed publication. A local
+	* `skills/specialists` directory is the project's own source and is complete
+	* by construction; otherwise the pinned remote source is acquired and its
+	* completeness is reported explicitly.
+	*/
+	async acquireSpecialists(config) {
 		const localRegistrySource = path.default.join(process.cwd(), "skills/specialists");
-		if (await fs_extra.default.pathExists(localRegistrySource)) return await this.specialistSyncService.syncSpecialists(process.cwd(), agents, localRegistrySource, this.writer) > 0;
+		if (await fs_extra.default.pathExists(localRegistrySource)) return {
+			status: "complete",
+			specialists: await this.specialistSyncService.readLocalSpecialists(localRegistrySource),
+			failures: []
+		};
 		const ref = this.resolvedRefs?.specialists.ref || config.specialists_ref || "main";
-		const specialists = await this.specialistSyncService.assembleSpecialists(config, ref, this.manifestVerifiers.specialists);
-		return await this.specialistSyncService.syncCollectedSpecialists(process.cwd(), agents, specialists, this.writer) > 0;
+		return this.specialistSyncService.acquireSpecialists(config, ref, this.manifestVerifiers.specialists, this.resolvedRefs?.specialists.commit ?? void 0);
+	}
+	/**
+	* Publishes the specialists acquired during preflight. Returns whether any
+	* specialist is desired, which is the only evidence that authorizes pruning
+	* previously installed specialist exports.
+	*/
+	async writeSpecialists(acquisition, config) {
+		const agents = await this.resolveTargetAgents(config);
+		if (agents.length === 0) return true;
+		await this.specialistSyncService.writeSpecialists(process.cwd(), agents, acquisition.specialists, this.writer);
+		return acquisition.specialists.length > 0;
+	}
+	/** The typed throttle failure, if this operation latched one. */
+	get rateLimitFailure() {
+		return this.githubService.rateLimitFailure;
+	}
+	/**
+	* Builds the attribution plan for the acquired (unpublished) skills and
+	* compares it with the qualified state of the current installation. Nothing
+	* is written: the command layer owns consent and publication.
+	*
+	* Destination bindings are derived from the same agent layout the ownership
+	* writer will use, so the collector reads the bytes a previous run would
+	* have installed at exactly those paths. The candidate digest recorded here
+	* is the source digest; publication re-derives the installed digest from the
+	* actual written bytes.
+	*/
+	async planAttribution(skills, config) {
+		const agents = await this.resolveTargetAgents(config);
+		const overrides = config.custom_overrides ?? [];
+		const registry = config.registry ?? "";
+		const previousCatalog = this.previousLock?.attributionCatalog;
+		const planned = {};
+		/** `<packageId>\0<fileName>` -> effective destination paths. */
+		const publishedPaths = /* @__PURE__ */ new Set();
+		const agentDir = (agentId, skill) => {
+			const basePath = SUPPORTED_AGENTS.find((agent) => agent.id === agentId)?.path;
+			if (!basePath) return null;
+			return agentId === Agent.Kiro ? path.default.join(basePath, `${skill.category}-${skill.skill}`) : path.default.join(basePath, skill.category, skill.skill);
+		};
+		for (const skill of skills) {
+			const origin = skill.origin;
+			const packageId = `${skill.category}/${skill.skill}`;
+			const files = [];
+			for (const file of skill.files) {
+				if (!file.attribution) continue;
+				const destinations = [];
+				for (const agentId of agents) {
+					const dir = agentDir(agentId, skill);
+					if (!dir) continue;
+					const relative = toPosixRel(process.cwd(), path.default.join(dir, file.name));
+					if (isOverriddenRel(relative, overrides)) continue;
+					publishedPaths.add(`${packageId}\0${file.name}\0${relative}`);
+					destinations.push({
+						agent: agentId,
+						path: relative,
+						sha256: file.attribution.sha256
+					});
+				}
+				if (destinations.length === 0) continue;
+				files.push({
+					...file.attribution,
+					name: file.name,
+					destinations
+				});
+			}
+			const previous = previousCatalog?.packages[packageId];
+			const preserved = this.preservedAttributionFiles(packageId, previous, publishedPaths, overrides, config.prune !== false);
+			if (files.length === 0) {
+				if (previous && preserved.length === previous.files.length) planned[packageId] = {
+					...previous,
+					files: preserved
+				};
+				continue;
+			}
+			if (!origin?.commit || !/^[0-9a-f]{40}$/.test(origin.commit)) continue;
+			for (const file of preserved) if (!files.some((candidate) => candidate.name === file.name)) files.push(file);
+			planned[packageId] = {
+				registry,
+				declaringCategory: origin.category,
+				requestedRef: origin.ref,
+				resolvedCommit: origin.commit,
+				files
+			};
+		}
+		for (const [packageId, record] of Object.entries(previousCatalog?.packages ?? {})) {
+			if (planned[packageId]) continue;
+			const preserved = this.preservedAttributionFiles(packageId, record, publishedPaths, overrides, config.prune !== false);
+			if (preserved.length !== record.files.length) continue;
+			planned[packageId] = {
+				...record,
+				files: preserved
+			};
+		}
+		const installedOnly = await this.discoverInstalledAttributionVariants(skills, planned, previousCatalog?.packages ?? {}, agents, overrides, publishedPaths);
+		const installed = await collectInstalledAttributionDigests(process.cwd(), this.mergeAttributionDestinations(planned, previousCatalog?.packages ?? {}));
+		const hasInstalledBytes = installedOnly.some((variant) => variant.sha256 !== null) || Object.values(installed).some((perFile) => Object.values(perFile).some((bindings) => bindings.some((binding) => binding.sha256 !== null)));
+		return {
+			planned,
+			installed,
+			installedOnly,
+			comparison: compareAttribution({
+				planned,
+				previousCatalog,
+				hasExistingInstallation: Object.keys(this.previousLock?.entries ?? {}).length > 0 || hasInstalledBytes,
+				installed
+			})
+		};
+	}
+	/**
+	* Previous records whose bytes this run will not touch: every recorded
+	* destination is either a configured override or (when pruning is disabled)
+	* a destination the ownership finalizer keeps. The record is returned
+	* verbatim so the comparison sees preserved bytes, not a removal.
+	*/
+	preservedAttributionFiles(packageId, previous, publishedPaths, overrides, prune) {
+		if (!previous) return [];
+		const preserved = [];
+		for (const file of previous.files) if (file.destinations.every((destination) => {
+			if (publishedPaths.has(`${packageId}\0${file.name}\0${destination.path}`)) return false;
+			return isOverriddenRel(destination.path, overrides) || !prune;
+		})) preserved.push({ ...file });
+		return preserved;
+	}
+	/**
+	* Bounded discovery of attribution-family files that exist in installed
+	* package directories but appear in neither the candidate nor the catalog.
+	* Only effective package directories are read — candidate packages plus
+	* directories referenced by previous destinations — only top-level
+	* LICENSE/NOTICE variants are considered, and the actual installed digest is
+	* reported with no invented origin.
+	*/
+	async discoverInstalledAttributionVariants(skills, planned, previous, agents, overrides, publishedPaths) {
+		const knownPaths = /* @__PURE__ */ new Set();
+		for (const record of [...Object.values(planned), ...Object.values(previous)]) for (const file of record.files) for (const destination of file.destinations) knownPaths.add(destination.path);
+		const scan = /* @__PURE__ */ new Map();
+		for (const skill of skills) {
+			const packageId = `${skill.category}/${skill.skill}`;
+			for (const agentId of agents) {
+				const basePath = SUPPORTED_AGENTS.find((agent) => agent.id === agentId)?.path;
+				if (!basePath) continue;
+				const dir = agentId === Agent.Kiro ? path.default.join(basePath, `${skill.category}-${skill.skill}`) : path.default.join(basePath, skill.category, skill.skill);
+				scan.set(dir, {
+					packageId,
+					agent: agentId,
+					dir
+				});
+			}
+		}
+		for (const [packageId, record] of Object.entries(previous)) for (const file of record.files) for (const destination of file.destinations) {
+			const dir = path.default.dirname(path.default.join(process.cwd(), destination.path));
+			scan.set(dir, {
+				packageId,
+				agent: destination.agent,
+				dir
+			});
+		}
+		const variants = /* @__PURE__ */ new Map();
+		for (const { packageId, agent, dir } of scan.values()) {
+			let entries;
+			try {
+				entries = await fs_extra.default.readdir(dir);
+			} catch {
+				continue;
+			}
+			for (const entry of entries) {
+				if (!ATTRIBUTION_FILE_NAME_RE.test(entry)) continue;
+				const relative = toPosixRel(process.cwd(), path.default.join(dir, entry));
+				if (knownPaths.has(relative) || publishedPaths.has(`${packageId}\0${entry}\0${relative}`) || isOverriddenRel(relative, overrides)) continue;
+				variants.set(relative, {
+					packageId,
+					name: entry,
+					agent,
+					path: relative,
+					sha256: await readInstalledAttributionDigest(process.cwd(), relative)
+				});
+			}
+		}
+		return [...variants.values()].sort((left, right) => left.path.localeCompare(right.path));
+	}
+	/**
+	* Unions the planned and previously recorded destination sets per package
+	* and filename so the installed-state read covers both sides of the
+	* comparison. Extra bindings never qualify a record; they only let the
+	* comparison see the real bytes at every path it may judge.
+	*/
+	mergeAttributionDestinations(planned, previous) {
+		const merged = { ...planned };
+		for (const [packageId, record] of Object.entries(previous)) {
+			const base = merged[packageId];
+			if (!base) {
+				merged[packageId] = record;
+				continue;
+			}
+			const files = base.files.map((file) => ({ ...file }));
+			for (const priorFile of record.files) {
+				const existing = files.find((file) => file.name === priorFile.name);
+				if (!existing) {
+					files.push({ ...priorFile });
+					continue;
+				}
+				for (const destination of priorFile.destinations) if (!existing.destinations.some((current) => current.agent === destination.agent && current.path === destination.path)) existing.destinations.push(destination);
+			}
+			merged[packageId] = {
+				...base,
+				files
+			};
+		}
+		return merged;
 	}
 	async applyIndices(config, targetAgents, localMetadata, desiredSkillIds, options) {
 		const agents = targetAgents || await this.resolveTargetAgents(config);
@@ -7796,22 +9739,25 @@ var SyncService = class {
 		for (const [cat, catConfig] of Object.entries(config.skills)) {
 			const remoteMetaCat = remoteMeta.categories?.[cat];
 			if (!remoteMetaCat?.version) continue;
-			const latestRef = `${remoteMetaCat.tag_prefix || ""}${remoteMetaCat.version}`;
-			if (catConfig.ref !== latestRef) candidates.push({
+			const prefix = remoteMetaCat.tag_prefix || "";
+			const latestRef = `${prefix}${remoteMetaCat.version}`;
+			if (catConfig.ref === void 0 || isAutomaticUpgrade(catConfig.ref, latestRef, prefix)) candidates.push({
 				key: cat,
 				ref: latestRef
 			});
 		}
 		if (remoteMeta.releases?.workflows?.version) {
-			const latestWorkflowsRef = `${remoteMeta.releases.workflows.tag_prefix || ""}${remoteMeta.releases.workflows.version}`;
-			if (config.workflows_ref && config.workflows_ref !== latestWorkflowsRef) candidates.push({
+			const prefix = remoteMeta.releases.workflows.tag_prefix || "";
+			const latestWorkflowsRef = `${prefix}${remoteMeta.releases.workflows.version}`;
+			if (config.workflows_ref && isAutomaticUpgrade(config.workflows_ref, latestWorkflowsRef, prefix)) candidates.push({
 				key: "workflows",
 				ref: latestWorkflowsRef
 			});
 		}
 		if (remoteMeta.categories?.specialists?.version) {
-			const latestSpecialistsRef = `${remoteMeta.categories.specialists.tag_prefix || ""}${remoteMeta.categories.specialists.version}`;
-			if (config.specialists_ref && config.specialists_ref !== latestSpecialistsRef) candidates.push({
+			const prefix = remoteMeta.categories.specialists.tag_prefix || "";
+			const latestSpecialistsRef = `${prefix}${remoteMeta.categories.specialists.version}`;
+			if (config.specialists_ref && isAutomaticUpgrade(config.specialists_ref, latestSpecialistsRef, prefix)) candidates.push({
 				key: "specialists",
 				ref: latestSpecialistsRef
 			});
@@ -8624,26 +10570,66 @@ 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/
+*
+* `--install-global` (on enable) installs `agent-skills-standard-mcp@<pin>`
+* globally, then verifies the installed binary reports the pin.
 */
 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;
+	}
 	async run(action, options = {}) {
 		const config = await this.configService.loadConfig();
 		if (!config) {
@@ -8654,13 +10640,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) {
@@ -8673,20 +10660,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.0";
+		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:"));
@@ -8697,12 +10714,38 @@ 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) {
+	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;
 		}
+		if (options.installGlobal) {
+			const pin = mcp.version ?? "0.8.0";
+			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;
+			}
+			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}.`));
+				console.log(picocolors.default.gray(`   Run manually: npm i -g ${spec}`));
+				process.exitCode = 1;
+				return;
+			}
+			console.log(picocolors.default.green(`✅ Global ags-mcp ${pin} installed and verified.`));
+		}
 		config.mcp = {
 			...mcp,
 			enabled: true,
@@ -8710,8 +10753,37 @@ var McpCommand = class {
 		};
 		await this.configService.saveConfig(config);
 		console.log(picocolors.default.green("✅ MCP enabled."));
+		if (viaOverride) {
+			const report = await this.mcpService.install({
+				rootDir: cwd,
+				agents,
+				mcp: {
+					...config.mcp,
+					via: viaOverride
+				}
+			});
+			console.log(picocolors.default.gray(`   Installed configs using launch mode "${viaOverride}".`));
+			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 --install-global`."));
+		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(),
@@ -8745,6 +10817,12 @@ 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;
@@ -8764,7 +10842,8 @@ var McpCommand = class {
 			mcp: {
 				...mcp,
 				enabled: true,
-				scope: effectiveScope
+				scope: effectiveScope,
+				...viaOverride ? { via: viaOverride } : {}
 			},
 			userScopePrompt: userPrompt
 		});
@@ -8792,15 +10871,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) {
@@ -8899,12 +10985,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.0";
 	}
 	exit(code) {
 		process.exitCode = code;
@@ -8933,8 +11021,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;
 		}
@@ -8953,7 +11041,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
@@ -8983,9 +11072,25 @@ var RetrospectiveCommand = class {
 };
 //#endregion
 //#region src/commands/sync.ts
+/** A classified command failure; `cancelled` marks a declined required consent. */
+var SyncFailureError = class extends Error {
+	failure;
+	cancelled;
+	constructor(failure, cancelled = false) {
+		super(failure.message);
+		this.failure = failure;
+		this.cancelled = cancelled;
+		this.name = "SyncFailureError";
+	}
+};
 /**
 * Command for synchronizing skills and workflows from the remote registry to the local workspace.
-* It handles configuration re-detection, fetching files, writing to disk, and updating indices.
+*
+* Publication order is preflight-first: configuration and pins are reconciled
+* in memory, every selected source is resolved and acquired, and the
+* attribution plan is computed before any managed file, lock entry, or saved
+* ref is written. A preflight failure therefore preserves the installed bytes,
+* the lock, and the saved refs.
 */
 var SyncCommand = class {
 	configService;
@@ -9001,118 +11106,385 @@ var SyncCommand = class {
 		this.hookService = hookService || new HookService();
 	}
 	/**
-	* Executes the synchronization flow.
-	* Reconciles dependencies, fetches skills and workflows from the registry, and updates AGENTS.md.
+	* Executes the synchronization flow and returns a discriminated outcome.
+	* The CLI boundary owns `process.exitCode`; services never exit the process.
 	*/
 	async run(options = {}) {
+		const restoreOutput = options.json ? this.redirectProgressToStderr() : () => {};
 		try {
-			const config = await this.configService.loadConfig();
-			if (!config) {
-				console.log(picocolors.default.red("❌ Error: .skillsrc not found. Run `init` first."));
-				return;
-			}
-			const projectDeps = await this.detectionService.getProjectDeps();
-			const skillsChanged = await this.syncService.reconcileConfig(config, projectDeps);
-			const workflowsChanged = await this.syncService.reconcileWorkflows(config);
-			if (!options.dryRun && (skillsChanged || workflowsChanged)) await this.configService.saveConfig(config);
-			const resolvedRefs = await this.syncService.resolvePins(config);
-			if (Object.entries(resolvedRefs.newPins).length > 0) {
-				const pinnedList = [resolvedRefs.newPins.workflows_ref, resolvedRefs.newPins.specialists_ref].filter(Boolean).join(", ");
-				if (!options.dryRun) {
-					if (resolvedRefs.newPins.workflows_ref) config.workflows_ref = resolvedRefs.newPins.workflows_ref;
-					if (resolvedRefs.newPins.specialists_ref) config.specialists_ref = resolvedRefs.newPins.specialists_ref;
-					await this.configService.saveConfig(config);
-					console.log(picocolors.default.green(`📌 Pinned ${pinnedList} in .skillsrc`));
-				} else console.log(picocolors.default.gray(`  (dry-run) would pin ${pinnedList} in .skillsrc`));
-			}
-			for (const warning of resolvedRefs.warnings) console.log(picocolors.default.yellow(warning));
-			const updates = await this.syncService.checkForUpdates(config);
-			let refsChanged = false;
-			if (updates && Object.keys(updates).length > 0) {
-				if (options.dryRun) {
-					if (!options.json) for (const [cat, ref] of Object.entries(updates)) console.log(picocolors.default.gray(`  (dry-run) would offer: ${cat} -> ${ref}`));
-				} else {
-					console.log(picocolors.default.yellow("\n🚀 New skill versions detected:"));
-					for (const [cat, ref] of Object.entries(updates)) {
-						const currentRef = cat === "workflows" ? config.workflows_ref : cat === "specialists" ? config.specialists_ref : config.skills[cat]?.ref;
-						console.log(picocolors.default.gray(`  - ${cat}: ${currentRef} -> ${ref}`));
-					}
-					let update = options.yes;
-					if (update === void 0) {
-						if (!process.stdin.isTTY) {
-							console.log(picocolors.default.cyan("ℹ️  Non-interactive environment detected. Skipping version updates. Use --yes to auto-confirm."));
-							update = false;
-						} else update = (await inquirer.default.prompt([{
-							type: "confirm",
-							name: "update",
-							message: "Do you want to update .skillsrc with these versions?",
-							default: true
-						}])).update;
-					}
-					if (update) {
-						for (const [cat, ref] of Object.entries(updates)) if (cat === "workflows") {
-							config.workflows_ref = ref;
-							refsChanged = true;
-						} else if (cat === "specialists") {
-							config.specialists_ref = ref;
-							refsChanged = true;
-						} else if (config.skills[cat]) {
-							config.skills[cat].ref = ref;
-							refsChanged = true;
-						}
-						await this.configService.saveConfig(config);
-						console.log(picocolors.default.green("✅ .skillsrc updated."));
-					} else console.log(picocolors.default.cyan("ℹ️  Skipping version updates, staying on pinned refs."));
+			return await this.execute(options);
+		} catch (error) {
+			const failure = this.classify(error);
+			const cancelled = error instanceof SyncFailureError && error.cancelled;
+			this.reportFailure(failure, options, cancelled);
+			return cancelled ? {
+				status: "cancelled",
+				failure
+			} : {
+				status: "failure",
+				failure
+			};
+		} finally {
+			restoreOutput();
+		}
+	}
+	async execute(options) {
+		const snapshot = await this.configService.readSnapshot();
+		if (!snapshot) throw new SyncFailureError({
+			code: "config-invalid",
+			message: "❌ Error: .skillsrc not found. Run `init` first."
+		});
+		const config = structuredClone(snapshot.config);
+		const projectDeps = await this.detectionService.getProjectDeps();
+		const skillsChanged = await this.syncService.reconcileConfig(config, projectDeps);
+		const workflowsChanged = await this.syncService.reconcileWorkflows(config);
+		let configChanged = skillsChanged || workflowsChanged;
+		const resolvedRefs = await this.syncService.resolvePins(config);
+		if (Object.entries(resolvedRefs.newPins).length > 0) {
+			const pinnedList = [resolvedRefs.newPins.workflows_ref, resolvedRefs.newPins.specialists_ref].filter(Boolean).join(", ");
+			if (!options.dryRun) {
+				if (resolvedRefs.newPins.workflows_ref) config.workflows_ref = resolvedRefs.newPins.workflows_ref;
+				if (resolvedRefs.newPins.specialists_ref) config.specialists_ref = resolvedRefs.newPins.specialists_ref;
+				configChanged = true;
+				console.log(picocolors.default.green(`📌 Pinned ${pinnedList} in .skillsrc`));
+			} else console.log(picocolors.default.gray(`  (dry-run) would pin ${pinnedList} in .skillsrc`));
+		}
+		for (const warning of resolvedRefs.warnings) console.log(picocolors.default.yellow(warning));
+		const updates = await this.syncService.checkForUpdates(config);
+		let refsChanged = false;
+		if (updates && Object.keys(updates).length > 0) {
+			if (options.dryRun) {
+				if (!options.json) for (const [cat, ref] of Object.entries(updates)) console.log(picocolors.default.gray(`  (dry-run) would offer: ${cat} -> ${ref}`));
+			} else {
+				console.log(picocolors.default.yellow("\n🚀 New skill versions detected:"));
+				for (const [cat, ref] of Object.entries(updates)) {
+					const currentRef = cat === "workflows" ? config.workflows_ref : cat === "specialists" ? config.specialists_ref : config.skills[cat]?.ref;
+					console.log(picocolors.default.gray(`  - ${cat}: ${currentRef} -> ${ref}`));
 				}
+				let update = options.yes;
+				if (update === void 0) {
+					if (options.json || !process.stdin.isTTY) {
+						console.log(picocolors.default.cyan("ℹ️  Non-interactive environment detected. Skipping version updates. Use --yes to auto-confirm."));
+						update = false;
+					} else update = (await inquirer.default.prompt([{
+						type: "confirm",
+						name: "update",
+						message: "Do you want to update .skillsrc with these versions?",
+						default: true
+					}])).update;
+				}
+				if (update) {
+					for (const [cat, ref] of Object.entries(updates)) if (cat === "workflows") {
+						config.workflows_ref = ref;
+						refsChanged = true;
+					} else if (cat === "specialists") {
+						config.specialists_ref = ref;
+						refsChanged = true;
+					} else if (config.skills[cat]) {
+						config.skills[cat].ref = ref;
+						refsChanged = true;
+					}
+					configChanged = true;
+					console.log(picocolors.default.green("✅ .skillsrc updated."));
+				} else console.log(picocolors.default.cyan("ℹ️  Skipping version updates, staying on pinned refs."));
 			}
-			if (refsChanged) await this.syncService.resolvePins(config);
-			if (!options.json) console.log(picocolors.default.cyan(`🚀 Syncing skills from ${config.registry}...`));
-			await this.syncService.beginInstall(config, {
-				dryRun: Boolean(options.dryRun),
-				force: options.force ?? []
-			});
-			const skillCategories = Object.keys(config.skills).filter((category) => category !== "specialists");
-			const skills = await this.syncService.assembleSkills(skillCategories, config);
-			const workflowAcquisition = await this.syncService.acquireWorkflows(config);
-			const workflows = workflowAcquisition.workflows;
-			if (workflowAcquisition.status === "incomplete") {
-				console.error(picocolors.default.red("❌ Workflow acquisition incomplete; existing workflows were preserved and no success is claimed."));
-				for (const failure of workflowAcquisition.failures) console.error(picocolors.default.red(`   ❌ ${failure.path} — ${failure.reason}`));
-			}
-			await this.syncService.writeSkills(skills, config);
-			await this.syncService.writeWorkflows(workflows, config);
-			const specialistsOk = await this.syncService.syncSpecialists(config);
-			const plan = await this.syncService.completeInstall(config, {
-				skills,
-				workflows,
-				specialistsOk,
-				refreshIndices: true,
-				completedSkillCategories: skillCategories,
-				workflowAcquisition
+		}
+		if (refsChanged) await this.syncService.resolvePins(config);
+		if (!options.json) console.log(picocolors.default.cyan(`🚀 Syncing skills from ${config.registry}...`));
+		await this.syncService.beginInstall(config, {
+			dryRun: Boolean(options.dryRun),
+			force: options.force ?? []
+		});
+		const skillCategories = Object.keys(config.skills).filter((category) => category !== "specialists");
+		const skills = await this.syncService.assembleSkills(skillCategories, config);
+		const workflowAcquisition = await this.syncService.acquireWorkflows(config);
+		if (workflowAcquisition.status === "incomplete") throw new SyncFailureError({
+			code: "sync-failed",
+			message: "Workflow acquisition incomplete; existing files, lock and saved refs were preserved.",
+			details: { workflowFailures: workflowAcquisition.failures }
+		});
+		const workflows = workflowAcquisition.workflows;
+		const specialistAcquisition = await this.syncService.acquireSpecialists(config);
+		if (specialistAcquisition.status === "incomplete") throw new SyncFailureError({
+			code: "sync-failed",
+			message: "Specialist acquisition incomplete; existing files, lock and saved refs were preserved.",
+			details: { specialistFailures: specialistAcquisition.failures }
+		});
+		const latched = this.syncService.rateLimitFailure;
+		if (latched) throw latched;
+		let attribution = null;
+		let attributionRequiresConsent = false;
+		if (!options.dryRun) {
+			const plan = await this.syncService.planAttribution(skills, config);
+			attribution = plan.comparison;
+			attributionRequiresConsent = plan.comparison.requiresConsent || plan.installedOnly.length > 0;
+			this.printAttributionPreview(plan);
+			await this.ensureAttributionConsent(plan, options);
+		}
+		let publishedSnapshot = snapshot;
+		if (!options.dryRun) publishedSnapshot = configChanged ? await this.configService.saveReviewedConfig(snapshot, config) : await this.assertSnapshotUnchanged(snapshot);
+		await this.syncService.writeSkills(skills, config);
+		await this.syncService.writeWorkflows(workflows, config);
+		const specialistsOk = await this.syncService.writeSpecialists(specialistAcquisition, config);
+		const plan = await this.syncService.completeInstall(config, {
+			skills,
+			workflows,
+			specialistsOk,
+			refreshIndices: true,
+			completedSkillCategories: skillCategories,
+			workflowAcquisition
+		});
+		if (options.dryRun) {
+			if (options.json) this.writeJson({
+				schema_version: 1,
+				kind: "sync.plan",
+				data: plan
 			});
-			if (options.dryRun) {
-				if (options.json) console.log(JSON.stringify({
-					schema_version: 1,
-					kind: "sync.plan",
-					data: plan
-				}));
-				else {
-					console.log(picocolors.default.cyan("🔍 Dry run — no files written"));
-					this.printPlanCounts(plan);
-					if (options.verbose) this.printVerbosePlan(plan);
-					console.log(picocolors.default.gray("  (dry-run) skipped: MCP registration, hooks, capability notes"));
+			else {
+				console.log(picocolors.default.cyan("🔍 Dry run — no files written"));
+				this.printPlanCounts(plan);
+				if (options.verbose) this.printVerbosePlan(plan);
+				console.log(picocolors.default.gray("  (dry-run) skipped: MCP registration, hooks, capability notes"));
+			}
+			return {
+				status: "dry-run",
+				plan
+			};
+		}
+		this.printSummary(plan);
+		await this.syncService.discloseCapabilities(config);
+		console.log(picocolors.default.green("✅ All skills synced successfully!"));
+		await this.runMcpPhase(config, options, publishedSnapshot);
+		await this.runHookPhase(config, options);
+		if (options.json) this.writeJson({
+			schema_version: 1,
+			kind: "sync.result",
+			data: {
+				status: "success",
+				added: plan.added.length,
+				updated: plan.updated.length,
+				unchanged: plan.unchanged.length,
+				kept: plan.kept.length,
+				unknown: plan.unknown.length,
+				pruned: plan.pruned.length,
+				keptOrphans: plan.keptOrphans.length,
+				attribution: attribution ? {
+					required: attributionRequiresConsent,
+					changes: attribution.packages.filter((change) => change.requiresConsent).length
+				} : null
+			}
+		});
+		return {
+			status: "success",
+			plan
+		};
+	}
+	/**
+	* Confirms the configuration on disk is still the snapshot read at preflight
+	* without writing anything. Runs immediately before the first managed write.
+	*/
+	async assertSnapshotUnchanged(snapshot) {
+		const current = await this.configService.readSnapshot();
+		if (!current || current.sourcePath !== snapshot.sourcePath || current.fingerprint !== snapshot.fingerprint) throw new SyncFailureError({
+			code: "config-invalid",
+			message: "❌ .skillsrc changed after preflight; nothing was published. Re-run `ags sync`."
+		});
+		return snapshot;
+	}
+	/**
+	* In JSON mode stdout carries exactly one envelope. Every progress line,
+	* including service-level logging, is redirected to stderr for the run.
+	*/
+	redirectProgressToStderr() {
+		const originalLog = console.log;
+		const originalInfo = console.info;
+		console.log = (...args) => console.error(...args);
+		console.info = (...args) => console.error(...args);
+		return () => {
+			console.log = originalLog;
+			console.info = originalInfo;
+		};
+	}
+	writeJson(value) {
+		process.stdout.write(`${JSON.stringify(value)}\n`);
+	}
+	/** Maps a thrown value to a stable, caller-visible failure contract. */
+	classify(error) {
+		if (error instanceof SyncFailureError) return error.failure;
+		const latched = this.syncService.rateLimitFailure;
+		if (latched) return this.githubError(latched);
+		if (error instanceof GithubRequestError) return this.githubError(error);
+		if (error instanceof ConfigValidationError) return {
+			code: "config-invalid",
+			message: `❌ Invalid .skillsrc: ${error.message}`,
+			details: {
+				configPath: error.configPath,
+				logicalPath: error.logicalPath
+			}
+		};
+		if (error instanceof IntegrityError) return {
+			code: "integrity",
+			message: error.message
+		};
+		if (error instanceof Error) return {
+			code: "sync-failed",
+			message: error.message
+		};
+		return {
+			code: "sync-failed",
+			message: String(error)
+		};
+	}
+	githubError(error) {
+		const auth = error.authenticated ? "a GitHub token was sent" : "no GitHub token was sent";
+		const code = error.kind === "rate-limited" || error.kind === "access-denied" ? error.kind : error.kind === "integrity" ? "integrity" : "sync-failed";
+		let hint;
+		if (error.kind === "rate-limited") {
+			const timing = error.resetAt ? ` It resets at ${error.resetAt}.` : error.retryAfterSeconds !== void 0 ? ` Retry after ${error.retryAfterSeconds}s.` : "";
+			hint = `GitHub ${error.rateLimitKind ?? "primary"} rate limit reached; no further requests were scheduled.${timing} ${auth}; set GITHUB_TOKEN for a higher limit.`;
+		} else if (error.kind === "access-denied") hint = `GitHub denied access to ${error.endpoint}. ${auth}; verify repository access or set GITHUB_TOKEN.`;
+		else if (error.kind === "integrity") hint = "A downloaded source failed integrity verification; nothing was published.";
+		else hint = `GitHub request failed at ${error.endpoint}. ${auth}; retry when the network or the reference is available.`;
+		return {
+			code,
+			message: error.message,
+			hint,
+			github: error.toJSON()
+		};
+	}
+	reportFailure(failure, options, cancelled) {
+		if (options.json) {
+			this.writeJson({
+				schema_version: 1,
+				kind: "sync.error",
+				data: {
+					code: failure.code,
+					message: failure.message,
+					...failure.hint ? { hint: failure.hint } : {},
+					...failure.github ? { github: failure.github } : {},
+					...failure.details ? { details: failure.details } : {},
+					...cancelled ? { cancelled: true } : {}
 				}
-				return;
+			});
+			return;
+		}
+		console.error(picocolors.default.red("❌ Sync failed:"), failure.message);
+		if (failure.hint) console.error(picocolors.default.yellow(`   ${failure.hint}`));
+		const acquisitionFailures = failure.details?.workflowFailures ?? failure.details?.specialistFailures;
+		if (Array.isArray(acquisitionFailures)) for (const item of acquisitionFailures) console.error(picocolors.default.red(`   ❌ ${String(item.path)} — ${String(item.reason)}`));
+	}
+	/**
+	* Discloses a first installation and previews every transition with both
+	* origins, the installed digest, explicitly unknown old origins, and
+	* installed-only attribution files that no candidate/catalog record covers.
+	*/
+	printAttributionPreview(plan) {
+		const { comparison, installed, installedOnly } = plan;
+		if (comparison.firstInstall && installedOnly.length === 0) {
+			for (const record of comparison.disclosures) {
+				const files = record.files.map((file) => `${file.name} (${file.basis}, ${file.resolvedCommit.slice(0, 12)})`).join(", ");
+				console.error(picocolors.default.gray(`  ℹ️  First install — attribution disclosed from ${record.registry}@${record.requestedRef}: ${files}`));
 			}
-			this.printSummary(plan);
-			await this.syncService.discloseCapabilities(config);
-			if (workflowAcquisition.status !== "incomplete") console.log(picocolors.default.green("✅ All skills synced successfully!"));
-			await this.runMcpPhase(config, options);
-			await this.runHookPhase(config, options);
-		} catch (error) {
-			if (error instanceof Error) console.error(picocolors.default.red("❌ Sync failed:"), error.message);
-			else console.error(picocolors.default.red("❌ Sync failed:"), String(error));
+			return;
 		}
+		const relevant = comparison.packages.filter((change) => change.status !== "unchanged" || change.requiresConsent || change.files.some((file) => file.previous === null));
+		if (relevant.length === 0 && installedOnly.length === 0) return;
+		console.error(picocolors.default.yellow("\n⚠️  Attribution changes require consent:"));
+		for (const change of relevant) {
+			console.error(picocolors.default.yellow(`  ${change.status} ${change.packageId} (${change.reason})`));
+			for (const file of change.files.slice(0, 12)) {
+				const installedNow = installed[change.packageId]?.[file.name] ?? [];
+				const installedDigest = installedNow.find((binding) => binding.sha256 !== null)?.sha256 ?? null;
+				console.error(picocolors.default.gray(`    ${file.status} ${file.name}`));
+				console.error(picocolors.default.gray(`      old: ${this.describeAttributionOrigin(file.previous, file.previousSha256 ?? installedDigest, "old")}`));
+				console.error(picocolors.default.gray(`      new: ${this.describeAttributionOrigin(file.planned, file.plannedSha256, "new")}`));
+				console.error(picocolors.default.gray(`      installed: ${installedNow.length === 0 ? "not recorded" : installedNow.map((binding) => `${binding.agent}:${binding.path} sha256=${binding.sha256 ? binding.sha256.slice(0, 12) : "unreadable"}`).join("; ")}`));
+			}
+			if (change.files.length > 12) console.error(picocolors.default.gray(`    … +${change.files.length - 12} more files`));
+		}
+		for (const variant of installedOnly.slice(0, 12)) console.error(picocolors.default.yellow(`  installed-only ${variant.name} @ ${variant.path} (${variant.agent}): origin unknown, installed sha256 ${variant.sha256 ? variant.sha256.slice(0, 12) : "unreadable"}`));
+		if (installedOnly.length > 12) console.error(picocolors.default.gray(`  … +${installedOnly.length - 12} more installed-only files`));
+	}
+	describeAttributionOrigin(record, digest, kind) {
+		if (record) return `${record.sourcePath}@${record.requestedRef}/${record.resolvedCommit.slice(0, 12)} basis=${record.basis} sha256=${record.sha256.slice(0, 12)}`;
+		if (digest) return `unknown origin (qualified record unavailable) sha256=${digest.slice(0, 12)}`;
+		return kind === "new" ? "not shipped by the selected source" : "none";
+	}
+	/**
+	* Requires separate attribution consent for any computed transition or any
+	* installed attribution file that cannot be qualified. Ordinary `--yes` is
+	* not consent; a non-interactive run without the flag fails preflight, and an
+	* interactive decline cancels the run, both before any publication.
+	*/
+	async ensureAttributionConsent(plan, options) {
+		const { comparison, installed, installedOnly } = plan;
+		if (!(comparison.requiresConsent || installedOnly.length > 0)) return;
+		const details = {
+			legacyUnqualified: comparison.legacyUnqualified,
+			installedOnly: installedOnly.map((variant) => ({
+				packageId: variant.packageId,
+				name: variant.name,
+				agent: variant.agent,
+				path: variant.path,
+				sha256: variant.sha256
+			})),
+			packages: comparison.packages.filter((change) => change.requiresConsent || installedOnly.some((variant) => variant.packageId === change.packageId)).map((change) => ({
+				packageId: change.packageId,
+				status: change.status,
+				reason: change.reason,
+				files: change.files.map((file) => ({
+					name: file.name,
+					status: file.status,
+					previousSha256: file.previousSha256,
+					plannedSha256: file.plannedSha256,
+					previous: file.previous ? {
+						sourcePath: file.previous.sourcePath,
+						sourceKind: file.previous.sourceKind,
+						requestedRef: file.previous.requestedRef,
+						resolvedCommit: file.previous.resolvedCommit,
+						blobSha1: file.previous.blobSha1,
+						basis: file.previous.basis,
+						sha256: file.previous.sha256
+					} : null,
+					planned: file.planned ? {
+						sourcePath: file.planned.sourcePath,
+						sourceKind: file.planned.sourceKind,
+						requestedRef: file.planned.requestedRef,
+						resolvedCommit: file.planned.resolvedCommit,
+						blobSha1: file.planned.blobSha1,
+						basis: file.planned.basis,
+						sha256: file.planned.sha256
+					} : null,
+					installed: (installed[change.packageId]?.[file.name] ?? []).map((binding) => ({
+						agent: binding.agent,
+						path: binding.path,
+						sha256: binding.sha256
+					}))
+				}))
+			}))
+		};
+		if (options.acceptAttributionChanges) return;
+		const message = "Attribution changes require explicit consent; re-run with --accept-attribution-changes (ordinary --yes does not authorize attribution changes).";
+		if (options.json || !process.stdin.isTTY) throw new SyncFailureError({
+			code: "attribution-consent-required",
+			message,
+			hint: "Review the preview above, then re-run with --accept-attribution-changes.",
+			details
+		});
+		await this.promptAttributionConsent(details);
+	}
+	async promptAttributionConsent(details) {
+		if ((await inquirer.default.prompt([{
+			type: "confirm",
+			name: "accept",
+			message: "Apply these attribution changes to the installed files?",
+			default: false
+		}])).accept) return;
+		throw new SyncFailureError({
+			code: "attribution-consent-required",
+			message: "Attribution changes were declined; nothing was published.",
+			details
+		}, true);
 	}
 	/**
 	* Phase 7 — MCP integration. Three paths:
@@ -9123,7 +11495,7 @@ var SyncCommand = class {
 	* In non-interactive mode (no TTY) and never-prompted: skip with a hint, do
 	* not assume consent. Users can opt in later via `ags mcp enable`.
 	*/
-	async runMcpPhase(config, options) {
+	async runMcpPhase(config, options, snapshot) {
 		const mcp = config.mcp ? { ...config.mcp } : defaultMcpConfig();
 		const agents = config.agents ?? [];
 		const snippetOnlyOverride = options.snippets === true && (!mcp.enabled || mcp.scope === "disabled");
@@ -9133,17 +11505,19 @@ var SyncCommand = class {
 			mcp.snippets = true;
 		} else if (options.snippets !== void 0) mcp.snippets = options.snippets;
 		if (!snippetOnlyOverride && (!mcp.prompted || !mcp.enabled && mcp.prompted)) {
-			if (!process.stdin.isTTY && !options.yes) {
+			if ((options.json || !process.stdin.isTTY) && !options.yes) {
 				if (!mcp.prompted) console.log(picocolors.default.gray("\nℹ️  MCP integration not yet configured. Run `ags mcp enable` (or `ags mcp scope project`) when ready."));
 				return;
 			}
 			const decided = await this.promptMcpConsent(options, mcp.prompted && !mcp.enabled);
-			config.mcp = {
+			const reviewed = structuredClone(config);
+			reviewed.mcp = {
 				enabled: decided.enabled,
 				scope: decided.enabled ? decided.scope : "disabled",
 				prompted: true
 			};
-			await this.configService.saveConfig(config);
+			config.mcp = reviewed.mcp;
+			await this.configService.saveReviewedConfig(snapshot, reviewed);
 		}
 		const finalMcp = config.mcp ? { ...config.mcp } : defaultMcpConfig();
 		if (snippetOnlyOverride) {
@@ -9153,6 +11527,10 @@ var SyncCommand = class {
 		} else if (options.snippets !== void 0) finalMcp.snippets = options.snippets;
 		if (!finalMcp.enabled || finalMcp.scope === "disabled") return;
 		const userScopePrompt = options.yes ? async () => true : async (agent, file) => {
+			if (options.json || !process.stdin.isTTY) {
+				console.log(picocolors.default.gray(`  ℹ️  Skipping user-scope MCP config for ${agent} (${file}); re-run interactively or with --yes to authorize.`));
+				return false;
+			}
 			const { ok } = await inquirer.default.prompt([{
 				type: "confirm",
 				name: "ok",
@@ -9233,7 +11611,7 @@ var SyncCommand = class {
 			return;
 		}
 		const promptPermission = options.yes ? async () => true : async (agent) => {
-			if (!process.stdin.isTTY) {
+			if (options.json || !process.stdin.isTTY) {
 				console.log(picocolors.default.gray(`\nℹ️  Skipping MCP permission grant for ${agent} (non-interactive; use --yes to auto-confirm).`));
 				return false;
 			}
@@ -9343,7 +11721,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.
@@ -9388,6 +11770,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) {
@@ -9439,6 +11822,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";
@@ -10251,7 +12640,7 @@ var UninstallService = class {
 				missing.push(rel);
 				continue;
 			}
-			if (sha256(await fs_extra.default.readFile(absPath)) === entry.sha256) remove.push(rel);
+			if (sha256$1(await fs_extra.default.readFile(absPath)) === entry.sha256) remove.push(rel);
 			else keepEdited.push(rel);
 		}
 		const removedAgents = hasAgents ? [...selection.agents] : [];
@@ -10266,7 +12655,7 @@ var UninstallService = class {
 			}
 			const entry = lock.entries[rel];
 			const content = await fs_extra.default.readFile(absPath);
-			if (entry && sha256(content) === entry.sha256) remove.push(rel);
+			if (entry && sha256$1(content) === entry.sha256) remove.push(rel);
 			else keepEdited.push(rel);
 		}
 		return {
@@ -11376,7 +13765,7 @@ var PolicyCommand = class {
 };
 //#endregion
 //#region src/index.ts
-dotenv.default.config();
+dotenv.default.config({ quiet: true });
 var _agsExecPath = process.argv[1] ?? "";
 if (_agsExecPath.includes("/pnpm/") && _agsExecPath.includes("/node_modules/agent-skills-standard/") && !_agsExecPath.includes(`agent-skills-standard@${package_default.version}`)) process.stderr.write(`\n${picocolors.default.yellow("⚠️  ags is running from a stale global shim — reported version will be wrong.")}\n   ${picocolors.default.cyan("Quickfix:")} ${picocolors.default.bold("npx agent-skills-standard@latest upgrade")} ` + picocolors.default.gray("(auto-detects & removes the stale shim)") + "\n\n");
 var program = new commander.Command();
@@ -11384,8 +13773,9 @@ program.name("agent-skills-standard").description("A CLI to manage and sync AI a
 program.command("init").description("Initialize a .skillsrc configuration file interactively").action(async () => {
 	await new InitCommand().run();
 });
-program.command("sync").description("Sync skills to AI Agent skill directories").option("-y, --yes", "Automatically confirm interactive prompts (e.g. update versions)").option("--snippets", "Generate JSON config snippets in ./mcp-config-snippets/; if MCP is disabled, run snippet-only mode").option("--dry-run", "Show what sync would change without writing anything").option("--force <paths...>", "Overwrite these files even if you edited them (backed up first)").option("--verbose", "With --dry-run: list every path").option("--json", "With --dry-run: print the plan as JSON (sync.plan)").action(async (options) => {
-	await new SyncCommand().run(options);
+program.command("sync").description("Sync skills to AI Agent skill directories").option("-y, --yes", "Automatically confirm interactive prompts (e.g. update versions)").option("--snippets", "Generate JSON config snippets in ./mcp-config-snippets/; if MCP is disabled, run snippet-only mode").option("--dry-run", "Show what sync would change without writing anything").option("--force <paths...>", "Overwrite these files even if you edited them (backed up first)").option("--verbose", "With --dry-run: list every path").option("--json", "Emit one versioned JSON envelope on stdout (sync.plan for --dry-run, sync.result/sync.error otherwise)").option("--accept-attribution-changes", "Consent to the previewed attribution changes for this run only (ordinary --yes is not consent)").action(async (options) => {
+	const outcome = await new SyncCommand().run(options);
+	process.exitCode = outcome.status === "success" || outcome.status === "dry-run" ? 0 : 1;
 });
 program.command("verify").description("Check installed files against .skills-lock.json (catches tampering, partial writes, or manual drift)").option("--agent <agent>", "Which agent skill directory to verify (default: first configured agent)").option("--strict", "Fail if any locked ref has moved (resolves to a different commit)").option("--attestation", "Verify build-provenance attestations using the GitHub CLI (gh)").action(async (options) => {
 	await new VerifyCommand().run(options);
@@ -11414,9 +13804,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").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 = {}) => {