universal-plugin 0.14.1 → 0.16.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.14.1",
+	"version": "0.16.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.14.1",
+	"version": "0.16.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "universal-plugin",
-	"version": "0.14.1",
+	"version": "0.16.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/dist/cli.mjs

@@ -5232,14 +5232,19 @@ function absoluteSource(origin, source) {
 		path: subdir
 	};
 }
-/** The source forms each runtime installs from./** The source forms each runtime installs from.
+/** The source forms each runtime installs from.
 *
 *  Every runtime takes a repository path. Beyond that they diverge, and the divergence is not
 *  cosmetic: a catalog is read at install time in someone else's terminal, so a source a runtime
 *  cannot resolve is a failure far from here. Claude Code's schema documents the full tagged set
-*  (<https://json.schemastore.org/claude-code-marketplace.json>). Codex documents npm alongside a
-*  local path. Copilot CLI and Cursor document local paths only, which is why an npm entry reaches
-*  two catalogs rather than four (`.research/local-marketplaces`, and issue #86). */
+*  (<https://json.schemastore.org/claude-code-marketplace.json>). The rest was found by running the
+*  CLIs (`.research/local-marketplaces`, "Remote entry sources"):
+*
+*  - Codex installs `npm`, `url` and `git-subdir`, and silently drops a `github` entry.
+*  - Copilot CLI installs `github` (also with `path`) and `url`, and refuses the *whole*
+*    marketplace over a single `npm` or `git-subdir` entry.
+*  - Cursor's shipped bundle resolves `github`, `url` and `git-subdir`, all by git URL, and has no
+*    `npm` source. Read from the bundle, not run. */
 const TARGET_SOURCE_KINDS = {
 	claude: [
 		"path",
@@ -5248,10 +5253,164 @@ const TARGET_SOURCE_KINDS = {
 		"url",
 		"git-subdir"
 	],
-	codex: ["path", "npm"],
-	copilot: ["path"],
-	cursor: ["path"]
+	codex: [
+		"path",
+		"npm",
+		"url",
+		"git-subdir"
+	],
+	copilot: [
+		"path",
+		"github",
+		"url"
+	],
+	cursor: [
+		"path",
+		"github",
+		"url",
+		"git-subdir"
+	]
 };
+/** The kind name used to decide whether a runtime accepts a source: a repository path, or the tag. */
+function sourceKindOf(source) {
+	if (isLocalCatalogSource(source)) return "path";
+	return typeof source === "string" ? "path" : source.source;
+}
+/** The runtimes that read `.claude-plugin/marketplace.json` when they find no catalog of their own
+*  ahead of it. Copilot CLI looks in `.github/plugin/` before `.claude-plugin/` (verified by running
+*  it against a repository carrying both). Cursor's bundle lists `.cursor-plugin/marketplace.json`
+*  first (read, not run). Codex prefers `.agents/plugins/marketplace.json` (E-CODEX-M22). So a
+*  catalog of the runtime's own shields it from whatever the Claude catalog holds. */
+const CLAUDE_CATALOG_READERS = [
+	"codex",
+	"copilot",
+	"cursor"
+];
+function pickPins(source) {
+	const pins = {};
+	if (typeof source.ref === "string") pins.ref = source.ref;
+	if (typeof source.sha === "string") pins.sha = source.sha;
+	return pins;
+}
+/** A git URL ending in `.git`, which Cursor requires of `url` and `git-subdir`. Only a GitHub URL is
+*  known to serve the same repository with the suffix, so any other host's URL is left as written. */
+function withGitSuffix(url) {
+	if (/\.git$/.test(url)) return url;
+	return GITHUB_URL.test(url) ? `${url.replace(/\/+$/, "")}.git` : void 0;
+}
+/** Turns a source into the closest one a runtime installs, or says why none exists.
+*
+*  A mapping is made only where it is lossless: `github` becomes a `url` (or, with a `path`, a
+*  `git-subdir`) on Codex, and a `git-subdir` on a GitHub URL becomes `github` + `path` on Copilot
+*  CLI. `ref` and `sha` pins cross with it. Anything else the runtime cannot install is omitted,
+*  because writing it would have the runtime drop the entry or refuse the whole catalog. */
+function adaptSource(target, source) {
+	const kind = sourceKindOf(source);
+	if (kind === "path" || typeof source === "string") return { source };
+	const supported = TARGET_SOURCE_KINDS[target].includes(kind);
+	if ((target === "codex" || target === "cursor" && typeof source.path === "string") && kind === "github" && typeof source.repo === "string") {
+		const url = `https://github.com/${source.repo}.git`;
+		return typeof source.path === "string" ? { source: {
+			source: "git-subdir",
+			url,
+			path: source.path,
+			...pickPins(source)
+		} } : { source: {
+			source: "url",
+			url,
+			...pickPins(source)
+		} };
+	}
+	if (target === "copilot" && kind === "git-subdir" && typeof source.url === "string" && typeof source.path === "string") {
+		const match = GITHUB_URL.exec(source.url.trim());
+		if (match) return { source: {
+			source: "github",
+			repo: match[1],
+			path: source.path,
+			...pickPins(source)
+		} };
+		return { omitted: "git-subdir is installable only from a GitHub URL, which is mapped to github with a path" };
+	}
+	if (!supported) return { omitted: `${kind} source is not supported by ${target}` };
+	if (target === "cursor" && (kind === "url" || kind === "git-subdir") && typeof source.url === "string") {
+		const url = withGitSuffix(source.url);
+		if (url === void 0) return { omitted: `cursor requires a ".git" URL for a ${kind} source` };
+		return { source: url === source.url ? source : {
+			...source,
+			url
+		} };
+	}
+	return { source };
+}
+/** Applies `adaptSource` to every entry of a serialized catalog: an entry is rewritten where a
+*  mapping exists and removed where none does. The content comes back untouched when nothing
+*  changed, so a catalog that needed no adapting is not reformatted. */
+function adaptCatalogContent(target, content) {
+	let parsed;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		return {
+			content,
+			omitted: []
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.plugins)) return {
+		content,
+		omitted: []
+	};
+	const catalog = parsed;
+	const omitted = [];
+	let changed = false;
+	const plugins = [];
+	for (const entry of catalog.plugins) {
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			plugins.push(entry);
+			continue;
+		}
+		const record = entry;
+		const source = record.source;
+		if (typeof source !== "string" && (typeof source !== "object" || source === null)) {
+			plugins.push(entry);
+			continue;
+		}
+		const adapted = adaptSource(target, source);
+		if ("omitted" in adapted) {
+			omitted.push({
+				name: typeof record.name === "string" ? record.name : "(unnamed)",
+				reason: adapted.omitted
+			});
+			changed = true;
+		} else if (adapted.source !== source) {
+			plugins.push({
+				...record,
+				source: adapted.source
+			});
+			changed = true;
+		} else plugins.push(entry);
+	}
+	if (!changed) return {
+		content,
+		omitted
+	};
+	return {
+		content: json({
+			...catalog,
+			plugins
+		}),
+		omitted
+	};
+}
+/** The catalog a runtime that also reads the Claude catalog should carry of its own, derived from
+*  the Claude one: the same identity and entries, each adapted to what that runtime installs. */
+function deriveSharedCatalog(target, claudeContent) {
+	const claude = parseCatalog(claudeContent, TARGET_CATALOG_PATHS.claude);
+	const metadata = existingMetadata(claude);
+	const base = JSON.parse(serializeTarget(target, metadata, [])[0]?.content ?? "{}");
+	const adapted = adaptCatalogContent(target, json({ plugins: Array.isArray(claude.plugins) ? claude.plugins : [] }));
+	base.plugins = JSON.parse(adapted.content).plugins;
+	return json(base);
+}
 /** Folds one plugin's entry into a catalog that may already exist, and returns the artifact to
 *  write. An existing catalog keeps its own top-level fields — its name, its owner, a description
 *  someone wrote — and every entry it lists for other plugins, in place. Only this plugin's entry is
@@ -5781,13 +5940,42 @@ function validateCodex(catalog) {
 	});
 	return issues;
 }
+/** What a runtime does with a source kind it cannot install: Copilot CLI refuses the whole
+*  catalog, Codex drops the entry without a word, Cursor skips it. All three leave the plugin
+*  uninstallable, so each is an issue rather than a note
+*  (`.research/local-marketplaces`, "Remote entry sources"). */
+const REJECTION = {
+	copilot: "Copilot CLI refuses the whole catalog",
+	codex: "Codex silently drops the entry",
+	cursor: "Cursor skips the entry"
+};
+/** Entries whose source `target` cannot install, one issue each. A source `adaptSource` can map is
+*  still an issue here: this checks what a catalog says, not what the generator could have written. */
+function sourceKindIssues(target, catalog) {
+	if (!isObject$1(catalog) || !Array.isArray(catalog.plugins) || target === "claude") return [];
+	const issues = [];
+	catalog.plugins.forEach((entry, index) => {
+		if (!isObject$1(entry)) return;
+		const source = entry.source;
+		if (typeof source !== "string" && !isObject$1(source)) return;
+		const adapted = adaptSource(target, source);
+		if ("source" in adapted && adapted.source === source) return;
+		const kind = sourceKindOf(source);
+		const fix = "source" in adapted ? ` — write ${JSON.stringify(adapted.source)}` : " — omit the entry";
+		issues.push({
+			path: `plugins[${index}].source`,
+			message: `${kind} source is not installable by ${target}; ${REJECTION[target]}${fix}`
+		});
+	});
+	return issues;
+}
 /** Every issue a target's runtime would raise against this catalog, empty when it loads. */
 function validateCatalog(target, catalog) {
 	if (!isObject$1(catalog)) return [{
 		path: "",
 		message: `catalog must be a JSON object, not ${typeName(catalog)}`
 	}];
-	return target === "codex" ? validateCodex(catalog) : validateClaudeShaped(catalog);
+	return [...target === "codex" ? validateCodex(catalog) : validateClaudeShaped(catalog), ...sourceKindIssues(target, catalog)];
 }
 /** The same check against a catalog still in its serialized form. Text that does not parse is one
 *  issue rather than a thrown error, so a caller checking four files reports all four. */
@@ -6920,6 +7108,82 @@ function addEntry(config, key, entry) {
 	};
 }
 //#endregion
+//#region src/compile/invisible.ts
+/** Invisible characters in compiled output (issue #190).
+*
+*  A bundler prints a dependency's `'\u{FEFF}'` as the raw character, so a committed script holds
+*  code points a reader cannot see — the ones skill checks reject because they can hide
+*  instructions. Inside a string, template or regular-expression literal the character can be
+*  written as an escape with the same meaning; anywhere else it can only be reported. */
+/** Controls, format characters (zero-width, bidirectional, BOM, soft hyphen, tags), line and paragraph
+*  separators, and default-ignorable code points such as variation selectors. Tab, line feed and
+*  carriage return are ordinary whitespace. */
+const INVISIBLE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Default_Ignorable_Code_Point}]/u;
+function isInvisible(char) {
+	return char !== "	" && char !== "\n" && char !== "\r" && INVISIBLE.test(char);
+}
+/** `\uXXXX` per UTF-16 code unit — valid in strings, templates and regular expressions, with or
+*  without the `u` flag (a surrogate pair of escapes reads as one code point under `u`). */
+function escapeChar(char) {
+	let out = "";
+	for (let i = 0; i < char.length; i++) out += `\\u${char.charCodeAt(i).toString(16).toUpperCase().padStart(4, "0")}`;
+	return out;
+}
+/** Rewrites every invisible character inside `spans` as an escape that keeps the literal's value. */
+function escapeInvisible(code, spans) {
+	const sorted = [...spans].sort((a, b) => a.start - b.start);
+	let out = "";
+	let copied = 0;
+	for (const span of sorted) {
+		if (span.start < copied) continue;
+		out += code.slice(copied, span.start);
+		out += escapeSpan(code.slice(span.start, span.end), span.kind);
+		copied = span.end;
+	}
+	return out + code.slice(copied);
+}
+function escapeSpan(text, kind) {
+	let out = "";
+	let i = 0;
+	while (i < text.length) {
+		const char = String.fromCodePoint(text.codePointAt(i));
+		if (char !== "\\") {
+			out += isInvisible(char) ? escapeChar(char) : char;
+			i += char.length;
+			continue;
+		}
+		const next = i + 1 < text.length ? String.fromCodePoint(text.codePointAt(i + 1)) : "";
+		i += 1 + next.length;
+		if (!isInvisible(next)) out += `\\${next}`;
+		else if (kind !== "regex" && (next === "\u2028" || next === "\u2029")) continue;
+		else out += escapeChar(next);
+	}
+	return out;
+}
+/** Every invisible character left in `code`, 1-based line and column, for the build to warn about. */
+function findInvisible(code) {
+	const found = [];
+	let line = 1;
+	let column = 1;
+	for (const char of code) {
+		if (char === "\n") {
+			line++;
+			column = 1;
+			continue;
+		}
+		if (isInvisible(char)) found.push({
+			line,
+			column,
+			codePoint: char.codePointAt(0)
+		});
+		column++;
+	}
+	return found;
+}
+function formatCodePoint(codePoint) {
+	return `U+${codePoint.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+//#endregion
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the
 *  library it inlines, reads it; universal-plugin depends on neither. */
@@ -6970,18 +7234,23 @@ function parseEntry(output, value) {
 		source: value
 	};
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return `scripts "${output}" must map to a source path or { source, command }`;
-	const { source, command } = value;
+	const { source, command, alias, keepNames } = value;
 	if (typeof source !== "string" || source.length === 0) return `scripts "${output}" has no source`;
 	if (command !== void 0 && (typeof command !== "string" || command.trim().length === 0)) return `scripts "${output}" has a command that is not a command path`;
-	return command === void 0 ? {
-		output: normalized,
-		source
-	} : {
+	if (alias !== void 0 && !isStringMap(alias)) return `scripts "${output}" has an alias that is not a map from import specifier to replacement`;
+	if (keepNames !== void 0 && typeof keepNames !== "boolean") return `scripts "${output}" has a keepNames that is not true or false`;
+	return {
 		output: normalized,
 		source,
-		command: command.trim().split(/\s+/).join(" ")
+		...command === void 0 ? {} : { command: command.trim().split(/\s+/).join(" ") },
+		...alias === void 0 ? {} : { alias },
+		...keepNames === void 0 ? {} : { keepNames }
 	};
 }
+function isStringMap(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	return Object.entries(value).every(([k, v]) => k.length > 0 && typeof v === "string" && v.length > 0);
+}
 /** A `/`-separated path relative to the plugin root, without `./`; `null` when it is absolute or
 *  climbs out of the root. */
 function normalizeRelative(p) {
@@ -7101,7 +7370,7 @@ async function compileScripts(root, opts, compiler) {
 				entry: entry.output,
 				commands
 			};
-			content = composeScript(await compiler.compile(sourcePath, root), entry, data);
+			content = composeScript(await compiler.compile(sourcePath, root, bundleOptions(entry)), entry, data);
 		} catch (err) {
 			warnings.push(`Failed to compile ${entry.source} → ${entry.output}: ${err instanceof Error ? err.message : String(err)}`);
 			rows.push({
@@ -7114,6 +7383,8 @@ async function compileScripts(root, opts, compiler) {
 		const bytes = Buffer.byteLength(content);
 		const overBudget = sizeWarning(entry.output, bytes, bin);
 		if (overBudget !== null) warnings.push(overBudget);
+		const hidden = findInvisible(content);
+		if (hidden.length > 0) warnings.push(invisibleWarning(entry.output, hidden));
 		const comparison = compareScript(fs$1.existsSync(outputPath) ? fs$1.readFileSync(outputPath, "utf8") : null, content);
 		if (opts.dryRun || comparison === "unchanged") {
 			rows.push({
@@ -7141,6 +7412,19 @@ async function compileScripts(root, opts, compiler) {
 		summary: summarize(rows)
 	};
 }
+/** The bundle options the entry sets, and none it does not. */
+function bundleOptions({ alias, keepNames }) {
+	return {
+		...alias === void 0 ? {} : { alias },
+		...keepNames === void 0 ? {} : { keepNames }
+	};
+}
+/** The compiler escapes invisible characters inside literals; one left elsewhere (a comment, an
+*  identifier, a tagged template) is named so the author can find it before a skill check does. */
+function invisibleWarning(output, hidden) {
+	const [first] = hidden;
+	return `${`${output}:${first?.line}:${first?.column} ${formatCodePoint(first?.codePoint ?? 0)}`}${hidden.length > 1 ? ` and ${hidden.length - 1} more` : ""}: invisible character in the compiled script that the build could not escape — skill checks reject it; write it as an escape in a string literal in the source`;
+}
 /** The `package.json` at `packagePath` (`.agents/universal-plugin.json`), which names the package and
 *  bin a script falls back to; `null` when the plugin ships to no package. Its version is never read. */
 function readPackageJson(root) {
@@ -7275,34 +7559,40 @@ function onlyEntryMain() {
 *
 *  An entry that inlines only its own source keeps readable output — in effect its types are
 *  stripped. One that inlines a dependency is minified, because that is the code the size budget is
-*  for. rolldown is loaded only when a plugin declares a script. */
-const rolldownCompiler = { async compile(sourcePath, root) {
+*  for. rolldown is loaded only when a plugin declares a script.
+*
+*  An entry's `alias` becomes `resolve.alias`, with a relative target resolved from the plugin root;
+*  its `keepNames` is passed to both outputs, so minifying keeps the names too. */
+const rolldownCompiler = { async compile(sourcePath, root, options = {}) {
 	const { rolldown } = await import("rolldown");
 	const unresolved = [];
+	const alias = resolveAlias(options, root);
+	const output = {
+		format: "esm",
+		codeSplitting: false,
+		keepNames: options.keepNames ?? false
+	};
 	const bundle = await rolldown({
 		input: sourcePath,
 		cwd: root,
 		platform: "node",
 		plugins: [onlyEntryMain()],
+		...alias === void 0 ? {} : { resolve: { alias } },
 		onLog(_level, log) {
 			if (log.code === "UNRESOLVED_IMPORT") unresolved.push(log.message);
 		}
 	});
 	try {
 		if (unresolved.length > 0) throw new Error(unresolved.join("\n"));
-		const [chunk, ...rest] = (await bundle.generate({
-			format: "esm",
-			codeSplitting: false
-		})).output;
+		const [chunk, ...rest] = (await bundle.generate(output)).output;
 		if (chunk?.type !== "chunk" || rest.some((o) => o.type === "chunk")) throw new Error("compiles to more than one file");
-		const external = [...chunk.imports, ...chunk.dynamicImports].filter((id) => !isBuiltin(id));
+		const external = [...chunk.imports, ...chunk.dynamicImports].filter((id) => !isBuiltin(id) && id !== chunk.fileName);
 		if (external.length > 0) throw new Error(`imports ${external.join(", ")}, which could not be inlined — install it where the plugin root resolves it`);
-		if (!chunk.moduleIds.some((id) => id.split(path$1.sep).includes("node_modules"))) return chunk.code;
-		return (await bundle.generate({
-			format: "esm",
-			codeSplitting: false,
+		if (!chunk.moduleIds.some((id) => id.split(path$1.sep).includes("node_modules"))) return await escapeLiterals(chunk.code);
+		return await escapeLiterals((await bundle.generate({
+			...output,
 			minify: true
-		})).output[0].code;
+		})).output[0].code);
 	} catch (error) {
 		const spec = failedExtends(error);
 		throw spec ? new Error(explainTsconfigFailure(sourcePath, root, spec), { cause: error }) : error;
@@ -7310,6 +7600,57 @@ const rolldownCompiler = { async compile(sourcePath, root) {
 		await bundle.close();
 	}
 } };
+/** The entry's alias with each relative target (`./`, `../`) made absolute from the plugin root, so it
+*  does not depend on where rolldown resolves from; `undefined` when the entry sets none. */
+function resolveAlias({ alias }, root) {
+	if (alias === void 0 || Object.keys(alias).length === 0) return void 0;
+	return Object.fromEntries(Object.entries(alias).map(([from, to]) => [from, /^\.\.?\//.test(to) ? path$1.resolve(root, to) : to]));
+}
+/** rolldown prints a dependency's escaped invisible characters raw (issue #190); this writes them back
+*  as escapes inside every string, untagged template and regular-expression literal. */
+async function escapeLiterals(code) {
+	if (![...code].some(isInvisible)) return code;
+	const { parseAst } = await import("rolldown/parseAst");
+	const spans = [];
+	collectSpans(parseAst(code), spans);
+	return escapeInvisible(code, spans);
+}
+function isNode(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function collectSpans(node, spans) {
+	if (node.type === "Literal") {
+		if (typeof node["value"] === "string") spans.push({
+			start: node.start,
+			end: node.end,
+			kind: "string"
+		});
+		else if (node["regex"] !== void 0) spans.push({
+			start: node.start,
+			end: node.end,
+			kind: "regex"
+		});
+		return;
+	}
+	if (node.type === "TaggedTemplateExpression") {
+		visit(node["tag"], spans);
+		for (const expression of node["quasi"]["expressions"]) collectSpans(expression, spans);
+		return;
+	}
+	if (node.type === "TemplateElement") {
+		spans.push({
+			start: node.start,
+			end: node.end,
+			kind: "template"
+		});
+		return;
+	}
+	for (const [key, value] of Object.entries(node)) if (key !== "parent") visit(value, spans);
+}
+function visit(value, spans) {
+	if (Array.isArray(value)) for (const item of value) visit(item, spans);
+	else if (isNode(value)) collectSpans(value, spans);
+}
 //#endregion
 //#region ../../node_modules/.pnpm/@toon-format+toon@4.1.1/node_modules/@toon-format/toon/dist/index.mjs
 const NULL_LITERAL = "null";
@@ -7897,16 +8238,17 @@ function nextStep$1(result, cwd) {
 }
 function buildCommand() {
 	const cmd = new Command("build").description("Generate vendor manifests from plugin.json");
-	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--strict-dependencies", "Fail when a refreshed catalog cannot resolve a declared dependency").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code\n").action(async (opts) => {
+	cmd.option("--vendor <id>", "Build only the named vendor").option("--dry-run", "Print what would be written without writing").option("--check", "Write nothing; exit 1 when a compiled script is missing, stale, or on another version").option("--verbose", "Print field-by-field transformation decisions").option("--clean", "Delete generated manifests before building").option("--strict-dependencies", "Fail when a refreshed catalog cannot resolve a declared dependency").option("--format <format>", "Output format: json or toon (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin plugin build --vendor claude-code\n").action(async (opts) => {
 		try {
 			const root = resolveRoot(opts.root);
+			const dryRun = opts.dryRun || opts.check;
 			const result = buildPlugin(root, {
 				vendor: opts.vendor,
-				dryRun: opts.dryRun,
+				dryRun,
 				verbose: opts.verbose,
 				clean: opts.clean
 			});
-			const scripts = await compileScripts(root, { dryRun: opts.dryRun }, rolldownCompiler);
+			const scripts = await compileScripts(root, { dryRun }, rolldownCompiler);
 			for (const warning of [...result.warnings, ...scripts.warnings]) process.stderr.write(`warn: ${warning}\n`);
 			const { built, skipped, failed, canonical } = result.summary;
 			const jsonResult = {
@@ -7941,6 +8283,11 @@ function buildCommand() {
 			});
 			process.stderr.write(nextStep$1(result, process.cwd()));
 			if (failed > 0 || scripts.summary.failed > 0) process.exitCode = 1;
+			if (opts.check && scripts.summary.behind > 0) {
+				const behind = scripts.rows.filter((r) => r.status === "missing" || r.status === "stale" || r.status === "version").map((r) => `${r.path} (${r.status})`);
+				process.stderr.write(`error: ${behind.length} compiled ${behind.length === 1 ? "script is" : "scripts are"} behind: ${behind.join(", ")} — run "universal-plugin plugin build" and commit the result (--check)\n`);
+				process.exitCode = 1;
+			}
 			if (opts.strictDependencies && result.dependencyIssues.length > 0) {
 				process.stderr.write(`error: ${result.dependencyIssues.length} declared ${result.dependencyIssues.length === 1 ? "dependency" : "dependencies"} cannot be resolved through the refreshed catalogs (--strict-dependencies)\n`);
 				process.exitCode = 1;
@@ -16413,19 +16760,64 @@ function normalizeJson(value) {
 	const record = value;
 	return Object.fromEntries(Object.keys(record).sort().map((key) => [key, normalizeJson(record[key])]));
 }
+/** The entries a runtime with no catalog of its own would have read from the Claude one, as the
+*  starting point for its catalog. Codex states an entry its own way, so those are re-shaped. */
+function sharedStart(target, claudeContent) {
+	if (claudeContent === void 0) return void 0;
+	if (target !== "codex") return claudeContent;
+	const plugins = JSON.parse(claudeContent).plugins ?? [];
+	return JSON.stringify({ plugins: plugins.map((entry) => ({
+		name: entry.name,
+		...typeof entry.version === "string" ? { version: entry.version } : {},
+		source: entry.source,
+		policy: {
+			installation: "AVAILABLE",
+			authentication: "ON_INSTALL"
+		},
+		category: "Productivity"
+	})) });
+}
 function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 	const root = path$1.resolve(rootInput);
 	const metadata = deriveMetadata(root, fs, opts);
 	const plugins = discoverPlugins(root, fs, opts.scanDirs);
-	const derived = selectedTargets$1(opts.targets).map((target) => ({
-		target,
-		artifacts: serializeTarget(target, metadata, plugins)
-	}));
-	for (const { artifacts } of derived) for (const artifact of artifacts) assertContained(root, path$1.join(root, artifact.path), fs, "selected artifact");
-	const planned = derived.map(({ target, artifacts }) => ({
-		target,
-		artifacts: artifacts.map((artifact) => mergeDiscoveredCatalog(artifact, readCatalog(fs, path$1.join(root, artifact.path))))
-	}));
+	const requested = selectedTargets$1(opts.targets);
+	const targets = requested.includes("claude") ? ["claude", ...requested.filter((t) => t !== "claude")] : requested;
+	const derived = new Map(targets.map((target) => [target, serializeTarget(target, metadata, plugins)]));
+	const readOwn = (artifact) => readCatalog(fs, path$1.join(root, artifact.path));
+	const planTarget = (target, claudeContent) => {
+		const omitted = [];
+		return {
+			target,
+			artifacts: (derived.get(target) ?? []).map((artifact) => {
+				assertContained(root, path$1.join(root, artifact.path), fs, "selected artifact");
+				const shared = CLAUDE_CATALOG_READERS.includes(target) ? sharedStart(target, claudeContent) : void 0;
+				const merged = mergeDiscoveredCatalog(artifact, readOwn(artifact) ?? shared);
+				const adapted = adaptCatalogContent(target, merged.content);
+				omitted.push(...adapted.omitted);
+				return {
+					path: merged.path,
+					content: adapted.content
+				};
+			}),
+			omitted
+		};
+	};
+	const planned = [];
+	let claudeContent;
+	for (const target of targets) {
+		const plan = planTarget(target, claudeContent);
+		if (target === "claude") claudeContent = plan.artifacts[0]?.content;
+		planned.push(plan);
+	}
+	const shielded = /* @__PURE__ */ new Set();
+	if (claudeContent !== void 0) for (const target of ["copilot", "cursor"]) {
+		if (targets.includes(target)) continue;
+		if (adaptCatalogContent(target, claudeContent).omitted.length === 0) continue;
+		derived.set(target, serializeTarget(target, metadata, plugins));
+		planned.push(planTarget(target, claudeContent));
+		shielded.add(target);
+	}
 	for (const { target, artifacts } of planned) for (const artifact of artifacts) {
 		const issues = validateCatalogContent(target, artifact.content);
 		if (issues.length > 0) throw new Error(formatCatalogIssues(artifact.path, issues));
@@ -16436,7 +16828,7 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 		if (fs.exists(output) && !sameArtifact(fs, output, artifact.content) && !opts.force) conflicts.push(artifact.path);
 	}
 	if (conflicts.length > 0) throw new Error(`error: generated artifact differs: ${conflicts.join(", ")}; rerun with --force to replace selected artifacts`);
-	const results = planned.map(({ target, artifacts }) => {
+	const results = planned.map(({ target, artifacts, omitted }) => {
 		if (plugins.length === 0) return {
 			target,
 			status: "empty",
@@ -16449,7 +16841,9 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 			target,
 			status: opts.dryRun ? "planned" : unchanged ? "unchanged" : "generated",
 			paths: artifacts.map((artifact) => artifact.path),
-			plugins: [...new Set(artifacts.flatMap((artifact) => catalogEntryNames(artifact.content)))]
+			plugins: [...new Set(artifacts.flatMap((artifact) => catalogEntryNames(artifact.content)))],
+			...omitted.length > 0 ? { omitted } : {},
+			...shielded.has(target) ? { reason: `written so ${target} does not read ${TARGET_CATALOG_PATHS.claude}, which lists entries it cannot install` } : {}
 		};
 	});
 	if (!opts.dryRun && plugins.length > 0) writeArtifacts(fs, planned.flatMap((entry) => entry.artifacts), root);
@@ -16651,11 +17045,6 @@ const ENTRY_METADATA_FIELDS = [
 	"license",
 	"keywords"
 ];
-/** The kind name used to decide whether a runtime accepts a source, from the source itself. */
-function sourceKindOf(source) {
-	if (isLocalCatalogSource(source)) return "path";
-	return typeof source === "string" ? "path" : source.source;
-}
 /** A source rendered for the result table — one short cell, not a JSON blob. */
 function describeSource(source) {
 	if (typeof source === "string") return source;
@@ -16777,27 +17166,46 @@ function addToMarketplace(rootInput, spec, opts = {}, fs = realMarketplaceFs) {
 		source: resolved.source,
 		metadata: entryMetadata(resolved.metadata, opts.metadata)
 	};
-	const kind = sourceKindOf(resolved.source);
 	const rendered = describeSource(resolved.source);
-	const planned = selectedTargets(opts.targets).map((target) => {
+	const targets = selectedTargets(opts.targets);
+	const readCatalogFile = (target) => {
+		const file = path$1.join(root, TARGET_CATALOG_PATHS[target]);
+		return fs.exists(file) ? fs.read(file) : void 0;
+	};
+	const claudeAfter = targets.includes("claude") ? mergeCatalogEntry("claude", metadata, plugin, () => readCatalogFile("claude"), { keepForeignSource: false }).content : readCatalogFile("claude");
+	const planned = targets.map((target) => {
 		const catalogPath = TARGET_CATALOG_PATHS[target];
 		const file = path$1.join(root, catalogPath);
-		const existing = fs.exists(file) ? fs.read(file) : void 0;
-		if (!TARGET_SOURCE_KINDS[target].includes(kind)) return {
-			target,
-			catalogPath,
-			file,
-			existing,
-			skipped: `${kind} source is not supported by ${target}`,
-			artifact: void 0
-		};
+		const existing = readCatalogFile(target);
+		const adapted = adaptSource(target, resolved.source);
+		if ("omitted" in adapted) {
+			const reason = `${adapted.omitted}; "${name}" is left out of ${catalogPath}`;
+			const shielded = existing === void 0 && CLAUDE_CATALOG_READERS.includes(target) && target !== "codex" && claudeAfter !== void 0 ? {
+				path: catalogPath,
+				content: deriveSharedCatalog(target, claudeAfter)
+			} : void 0;
+			return {
+				target,
+				catalogPath,
+				file,
+				existing,
+				skipped: shielded ? `${reason}; wrote the catalog without it so ${target} does not read the Claude one` : reason,
+				artifact: shielded
+			};
+		}
+		const changed = adapted.source !== resolved.source;
+		const base = existing ?? (CLAUDE_CATALOG_READERS.includes(target) && target !== "codex" && claudeAfter !== void 0 && adaptCatalogContent(target, claudeAfter).omitted.length > 0 ? deriveSharedCatalog(target, claudeAfter) : void 0);
 		return {
 			target,
 			catalogPath,
 			file,
 			existing,
 			skipped: void 0,
-			artifact: mergeCatalogEntry(target, metadata, plugin, () => existing, { keepForeignSource: false })
+			artifact: mergeCatalogEntry(target, metadata, {
+				...plugin,
+				source: adapted.source
+			}, () => base, { keepForeignSource: false }),
+			mapped: changed ? `${sourceKindOf(resolved.source)} source written as ${describeSource(adapted.source)}` : void 0
 		};
 	});
 	for (const entry of planned) {
@@ -16818,23 +17226,30 @@ function addToMarketplace(rootInput, spec, opts = {}, fs = realMarketplaceFs) {
 			source: rendered,
 			path: entry.catalogPath
 		};
-		if (entry.skipped || !entry.artifact) return {
+		if (entry.skipped) return {
 			...row,
 			status: "skipped",
-			source: rendered,
 			reason: entry.skipped
 		};
+		if (!entry.artifact) return {
+			...row,
+			status: "skipped"
+		};
+		const mapped = "mapped" in entry ? { reason: entry.mapped } : {};
 		if (entry.existing !== void 0 && sameCatalogContent(entry.existing, entry.artifact.content)) return {
 			...row,
+			...mapped,
 			status: "unchanged"
 		};
 		if (opts.dryRun) return {
 			...row,
+			...mapped,
 			status: "planned"
 		};
 		const existed = entry.existing !== void 0 && catalogEntry(entry.existing, name) !== void 0;
 		return {
 			...row,
+			...mapped,
 			status: existed ? "updated" : "added"
 		};
 	});
@@ -16931,15 +17346,30 @@ function validateMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 	]).map((target) => {
 		const relative = TARGET_CATALOG_PATHS[target];
 		const file = path$1.join(root, relative);
-		if (!fs.exists(file)) return {
-			target,
-			path: relative,
-			status: opts.required ? "invalid" : "missing",
-			issues: opts.required ? [{
-				path: "",
-				message: "no catalog at this path"
-			}] : []
-		};
+		if (!fs.exists(file)) {
+			const claudeFile = path$1.join(root, TARGET_CATALOG_PATHS.claude);
+			if (CLAUDE_CATALOG_READERS.includes(target) && fs.exists(claudeFile)) {
+				const shared = parseAndCheck(fs.read(claudeFile), (parsed) => sourceKindIssues(target, parsed)).map((issue) => ({
+					path: issue.path,
+					message: `${issue.message} (read from ${TARGET_CATALOG_PATHS.claude}; write ${relative} to shield ${target} from it)`
+				}));
+				if (shared.length > 0) return {
+					target,
+					path: TARGET_CATALOG_PATHS.claude,
+					status: "invalid",
+					issues: shared
+				};
+			}
+			return {
+				target,
+				path: relative,
+				status: opts.required ? "invalid" : "missing",
+				issues: opts.required ? [{
+					path: "",
+					message: "no catalog at this path"
+				}] : []
+			};
+		}
 		const content = fs.read(file);
 		const issues = [...validateCatalogContent(target, content), ...parseAndCheck(content, (parsed) => [...checkSources(root, fs, parsed), ...target === "claude" ? checkDependencies(root, fs, parsed, content, relative) : []])];
 		return {
@@ -17050,6 +17480,10 @@ function initCommand() {
 				})),
 				summary: `${results.length} targets`
 			});
+			for (const row of results) {
+				for (const entry of row.omitted ?? []) process.stderr.write(`warning: omitted "${entry.name}" from ${row.target}: ${entry.reason}\n`);
+				if (row.reason) process.stderr.write(`${row.target}: ${row.reason}\n`);
+			}
 			process.stderr.write("Generated repository metadata only; no marketplace publication, registration, installation, authentication, or provisioning occurred.\n");
 		} catch (err) {
 			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.14.1",
+	"version": "0.16.0",
 	"description": "Research and design toolkit for building universal AI coding agent plugins that work across Claude Code, Cursor, Codex, and GitHub Copilot CLI.",
 	"author": {
 		"name": "unional"

package/skills/adopt-upx/scripts/rewrite-upx.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/rewrite-upx.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/adopt-upx/scripts/rewrite-upx.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/adopt-upx/scripts/rewrite-upx.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 //#region src/skill-scripts/rewrite-upx.ts

package/skills/build-plugin/SKILL.md

@@ -47,7 +47,7 @@ node scripts/build.mjs --root <plugin-root>
 
 Resolve `scripts/build.mjs` against this skill's own directory. It runs the CLI the project installed
 (`pnpm exec universal-plugin`), else the CLI pinned to the version this skill shipped with
-(`npx universal-plugin@0.14.1`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
+(`npx universal-plugin@0.16.0`), so it works in a skill that was linked or copied on its own. `--root` defaults to the working directory and
 must name the directory that holds the canonical `plugin.json`.
 
 The command never prompts, so it is safe to run unattended.
@@ -58,6 +58,7 @@ The command never prompts, so it is safe to run unattended.
 | `--vendor <id>` | Build one vendor (`claude-code`, `cursor`, `codex`, `copilot-cli`), and refresh only its catalog |
 | `--verbose` | Print each field-level decision the derivation made |
 | `--strict-dependencies` | Fail when a refreshed catalog cannot resolve a declared dependency. Use in CI |
+| `--check` | Write nothing; exit 1 when a compiled script is `missing`, `stale`, or `version`. Use in CI |
 | `--format json` | The same result as JSON, for scripts |
 
 `--clean` also exists. It deletes derived manifests before rewriting them, so reach for it only

package/skills/build-plugin/scripts/build.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/build-plugin/scripts/build.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/build-plugin/scripts/build.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/doctor-universal-plugin/SKILL.md

@@ -172,7 +172,7 @@ it does not, offer to add it — ask first, because both are the user's files:
   semantic-release bot opens.
 
 Use the locked `universal-plugin` from the repository's devDependencies when it has one; otherwise
-`npx universal-plugin@0.14.1`, pinned. This check matters most where the release tool picks the
+`npx universal-plugin@0.16.0`, pinned. This check matters most where the release tool picks the
 number, because nothing else runs between that bump and publish.
 
 ## Unreleased content

package/skills/doctor-universal-plugin/scripts/doctor.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/doctor.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/doctor-universal-plugin/scripts/doctor.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/doctor-universal-plugin/scripts/doctor.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";

package/skills/init-universal-plugin/references/create.md

@@ -43,7 +43,7 @@ node scripts/init.mjs --name <plugin-name> --vendor claude-code --vendor cursor
 ```
 
 Resolve `scripts/init.mjs` against this skill's directory; it runs the project's installed CLI, else
-the pinned `npx universal-plugin@0.14.1`. Add `--npm` when an npm package ships the plugin,
+the pinned `npx universal-plugin@0.16.0`. Add `--npm` when an npm package ships the plugin,
 which also wires that `package.json`'s `files` to carry the derived manifests, copies its `version`
 into the manifest, and, in a changesets repository, wires the root `version` script to run
 `plugin version --from-package` (SKILL.md Phase 3 asks before that rewrite).

package/skills/init-universal-plugin/scripts/init.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/init-universal-plugin/scripts/init.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/init-universal-plugin/scripts/init.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/SKILL.md

@@ -56,7 +56,11 @@ disk is usually `add`.
 | Cursor | `.cursor-plugin/marketplace.json` | nothing; an admin imports the repository as a team marketplace |
 
 Three of the four read `.claude-plugin/marketplace.json`, so one file covers Claude Code, Codex, and
-Copilot CLI. The reverse does not hold: Claude Code rejects the Codex catalog for its missing
+Copilot CLI. Not every plugin in it installs everywhere: a runtime installs only the source kinds it
+supports (`references/add.md` has the table), so a catalog can list plugins a runtime cannot install.
+Copilot CLI refuses the whole catalog over one `npm` or `git-subdir` entry. The generator therefore
+writes each runtime's own catalog with only what that runtime installs, and Copilot CLI and Cursor read
+their own catalog before the Claude one, which shields them. State per runtime which plugins install. The reverse does not hold: Claude Code rejects the Codex catalog for its missing
 `owner`.
 
 ## Rules for every route

package/skills/marketplace/references/add.md

@@ -47,20 +47,32 @@ must be the full 40-character hash, which the schema requires.
 
 ## 2. Choose targets, and know what will be skipped
 
-Not every runtime installs from every source. Only a repository path reaches all four:
+Not every runtime installs from every source. Found by running the CLIs, not from the schema:
 
 | Source | Claude Code | Codex | Copilot CLI | Cursor |
 | --- | --- | --- | --- | --- |
 | path | yes | yes | yes | yes |
 | npm | yes | yes | — | — |
-| github, url, git-subdir | yes | — | — | — |
+| github | yes | written as `url` | yes (also with `path`) | yes; with `path`, written as `git-subdir` |
+| url | yes | yes | yes | yes, `.git` URL |
+| git-subdir | yes | yes | on a GitHub URL, written as `github` + `path`; otherwise — | yes, `.git` URL |
 
-A target that cannot resolve the source is reported `skipped` with the reason, and no file is
-written for it. That is deliberate: a source a runtime refuses is an install failure in someone
-else's terminal. Say which targets were skipped and why — do not report "added" and leave the user
-to discover that two catalogs have no entry.
+Cursor's row is read from its shipped bundle, not run. Where the table says "written as", the command
+rewrites the source for that catalog and keeps `ref` and `sha`; nothing is lost.
 
-With no target flags all four are selected, so the skips are the normal case for an npm package.
+A target that still cannot resolve the source is reported `skipped` with the reason, naming the entry
+and the runtime, and the entry is not written to that catalog. That is deliberate: Copilot CLI refuses
+the **whole** catalog over one `npm` or `git-subdir` entry, and Codex drops a `github` entry without a
+word. Say which targets were skipped and why — do not report "added" and leave the user to discover
+that two catalogs have no entry.
+
+Copilot CLI and Cursor also read `.claude-plugin/marketplace.json` when they have no catalog of their
+own. So a skip for either one writes its catalog anyway, derived from the Claude one without the entry:
+a catalog of its own is read first and shields it. Tell the user those two files appeared and why.
+
+With no target flags all four are selected, so skips are the normal case for an npm package.
+Plugins that only npm can deliver reach Copilot CLI and Cursor only if they are vendored into this
+repository as a `./` path, which this command does not do.
 
 ## 3. Supply the metadata
 
@@ -127,8 +139,8 @@ own git remote — which is also how `--from` resolves one. A marketplace with n
 there is no URL to rewrite against, and a bare path would name a directory this repository does not
 have.
 
-Both rewritten forms are Claude Code source types, so expect Codex, Copilot CLI, and Cursor to be
-skipped for a subdirectory plugin.
+A subdirectory plugin reaches Codex and Cursor as `git-subdir`, and Copilot CLI as `github` + `path`
+when the repository is on GitHub; on another host Copilot CLI is skipped.
 
 ## 6. Validate
 

package/skills/marketplace/references/validate.md

@@ -26,6 +26,11 @@ error: catalog ".claude-plugin/marketplace.json" does not match the marketplace
 | `invalid` | the runtime would refuse it; the issues say why |
 | `missing` | no catalog at that path, which is only a failure under `--required` |
 
+A source the runtime cannot install is an issue too: `npm` or `git-subdir` for Copilot CLI (it refuses
+the whole catalog), `github` for Codex (silently dropped), `npm` for Cursor. A runtime with no catalog
+of its own is checked against `.claude-plugin/marketplace.json`, because that is the file it reads;
+the fix is to run `init` or `add` so the runtime gets a catalog of its own.
+
 ## Fixing what it reports
 
 Fix an issue in the source it comes from, then regenerate. An entry's fields are derived, so an

package/skills/marketplace/scripts/add.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/marketplace/scripts/add.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/scripts/install-docs.mjs

@@ -1,9 +1,121 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/install-docs.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/marketplace/scripts/install-docs.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/marketplace/scripts/install-docs.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+//#region src/marketplace/marketplace.ts
+/** Whether a catalog entry's `source` names a place inside this repository — a `./`-prefixed path in
+*  the Claude-shaped catalogs, or Codex's `{ source: "local", path }`. Every other form names a
+*  plugin distributed from somewhere else: an npm package, a GitHub repository, a URL. Discovery
+*  walks directories, so it can produce the first kind and can say nothing about the second. */
+function isLocalCatalogSource(source) {
+	if (typeof source === "string") return true;
+	if (typeof source !== "object" || source === null || Array.isArray(source)) return false;
+	return source.source === "local";
+}
+const GITHUB_URL = /^(?:https?:\/\/(?:www\.)?github\.com\/|git@github\.com:)([^/]+\/[^/]+?)(?:\.git)?\/?$/;
+/** The source forms each runtime installs from.
+*
+*  Every runtime takes a repository path. Beyond that they diverge, and the divergence is not
+*  cosmetic: a catalog is read at install time in someone else's terminal, so a source a runtime
+*  cannot resolve is a failure far from here. Claude Code's schema documents the full tagged set
+*  (<https://json.schemastore.org/claude-code-marketplace.json>). The rest was found by running the
+*  CLIs (`.research/local-marketplaces`, "Remote entry sources"):
+*
+*  - Codex installs `npm`, `url` and `git-subdir`, and silently drops a `github` entry.
+*  - Copilot CLI installs `github` (also with `path`) and `url`, and refuses the *whole*
+*    marketplace over a single `npm` or `git-subdir` entry.
+*  - Cursor's shipped bundle resolves `github`, `url` and `git-subdir`, all by git URL, and has no
+*    `npm` source. Read from the bundle, not run. */
+const TARGET_SOURCE_KINDS = {
+	claude: [
+		"path",
+		"npm",
+		"github",
+		"url",
+		"git-subdir"
+	],
+	codex: [
+		"path",
+		"npm",
+		"url",
+		"git-subdir"
+	],
+	copilot: [
+		"path",
+		"github",
+		"url"
+	],
+	cursor: [
+		"path",
+		"github",
+		"url",
+		"git-subdir"
+	]
+};
+/** The kind name used to decide whether a runtime accepts a source: a repository path, or the tag. */
+function sourceKindOf(source) {
+	if (isLocalCatalogSource(source)) return "path";
+	return typeof source === "string" ? "path" : source.source;
+}
+function pickPins(source) {
+	const pins = {};
+	if (typeof source.ref === "string") pins.ref = source.ref;
+	if (typeof source.sha === "string") pins.sha = source.sha;
+	return pins;
+}
+/** A git URL ending in `.git`, which Cursor requires of `url` and `git-subdir`. Only a GitHub URL is
+*  known to serve the same repository with the suffix, so any other host's URL is left as written. */
+function withGitSuffix(url) {
+	if (/\.git$/.test(url)) return url;
+	return GITHUB_URL.test(url) ? `${url.replace(/\/+$/, "")}.git` : void 0;
+}
+/** Turns a source into the closest one a runtime installs, or says why none exists.
+*
+*  A mapping is made only where it is lossless: `github` becomes a `url` (or, with a `path`, a
+*  `git-subdir`) on Codex, and a `git-subdir` on a GitHub URL becomes `github` + `path` on Copilot
+*  CLI. `ref` and `sha` pins cross with it. Anything else the runtime cannot install is omitted,
+*  because writing it would have the runtime drop the entry or refuse the whole catalog. */
+function adaptSource(target, source) {
+	const kind = sourceKindOf(source);
+	if (kind === "path" || typeof source === "string") return { source };
+	const supported = TARGET_SOURCE_KINDS[target].includes(kind);
+	if ((target === "codex" || target === "cursor" && typeof source.path === "string") && kind === "github" && typeof source.repo === "string") {
+		const url = `https://github.com/${source.repo}.git`;
+		return typeof source.path === "string" ? { source: {
+			source: "git-subdir",
+			url,
+			path: source.path,
+			...pickPins(source)
+		} } : { source: {
+			source: "url",
+			url,
+			...pickPins(source)
+		} };
+	}
+	if (target === "copilot" && kind === "git-subdir" && typeof source.url === "string" && typeof source.path === "string") {
+		const match = GITHUB_URL.exec(source.url.trim());
+		if (match) return { source: {
+			source: "github",
+			repo: match[1],
+			path: source.path,
+			...pickPins(source)
+		} };
+		return { omitted: "git-subdir is installable only from a GitHub URL, which is mapped to github with a path" };
+	}
+	if (!supported) return { omitted: `${kind} source is not supported by ${target}` };
+	if (target === "cursor" && (kind === "url" || kind === "git-subdir") && typeof source.url === "string") {
+		const url = withGitSuffix(source.url);
+		if (url === void 0) return { omitted: `cursor requires a ".git" URL for a ${kind} source` };
+		return { source: url === source.url ? source : {
+			...source,
+			url
+		} };
+	}
+	return { source };
+}
+//#endregion
 //#region src/skill-scripts/install-docs.ts
 const argv = process.argv.slice(2);
 const rootFlag = argv.indexOf("--root");
@@ -50,6 +162,11 @@ const cursor = readJson(path.join(root, ".cursor-plugin/marketplace.json"));
 const targets = [];
 const sections = [];
 const pluginNames = (catalog) => (catalog?.plugins ?? []).map((p) => p.name).filter(Boolean);
+const installableNames = (target, catalog) => (catalog?.plugins ?? []).filter((p) => p?.name && p.source !== void 0 && !("omitted" in adaptSource(target, p.source))).map((p) => p.name);
+const notInstallable = (installed, label) => {
+	const missing = pluginNames(claude).filter((name) => !installed.includes(name));
+	return missing.length === 0 ? "" : `\n\nNot installable on ${label}: ${missing.join(", ")}.`;
+};
 if (claude) {
 	const names = pluginNames(claude);
 	const installs = (names.length > 0 ? names : ["<plugin>"]).map((n) => `/plugin install ${n}@${claude.name}`);
@@ -64,20 +181,20 @@ if (claude) {
 	].join("\n"));
 }
 if (copilot) {
-	const names = pluginNames(copilot);
+	const names = installableNames("copilot", copilot);
 	const installs = (names.length > 0 ? names : ["<plugin>"]).map((n) => `copilot plugin install ${n}@${copilot.name}`);
 	targets.push("copilot-cli");
-	sections.push([
+	sections.push([[
 		"**GitHub Copilot CLI**",
 		"",
 		"```",
 		`copilot plugin marketplace add ${repoRef}`,
 		...installs,
 		"```"
-	].join("\n"));
+	].join("\n"), notInstallable(names, "Copilot CLI")].join(""));
 }
 if (codex) {
-	const names = pluginNames(codex);
+	const names = installableNames("codex", codex);
 	const installs = (names.length > 0 ? names : ["<plugin>"]).map((n) => `codex plugin add ${n}@${codex.name}`);
 	targets.push("codex");
 	sections.push([
@@ -89,7 +206,7 @@ if (codex) {
 		"```",
 		"",
 		"Start a new session before using the plugin."
-	].join("\n"));
+	].join("\n").concat(notInstallable(names, "Codex")));
 }
 if (cursor) {
 	targets.push("cursor");

package/skills/marketplace/scripts/marketplace.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/marketplace/scripts/marketplace.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/marketplace/scripts/marketplace.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/marketplace/scripts/validate.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/marketplace/scripts/validate.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/marketplace/scripts/validate.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the

package/skills/version/SKILL.md

@@ -74,7 +74,7 @@ node scripts/version.mjs --from-package
 ```
 
 Resolve that path against this skill's own directory; it runs the project's installed CLI
-(`pnpm exec universal-plugin`), else `npx universal-plugin@0.14.1` pinned to this skill's version.
+(`pnpm exec universal-plugin`), else `npx universal-plugin@0.16.0` pinned to this skill's version.
 `universal-plugin plugin version` on the `PATH` is the fallback. The command never prompts, so it is safe to run unattended once the
 source is decided.
 

package/skills/version/scripts/version.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Compiled by `universal-plugin plugin build` from src/skill-scripts/run-cli.ts. Edit the source, not this file.
-globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.14.1","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
+globalThis.__SKILL_SCRIPT__ = {"package":"universal-plugin","bin":"universal-plugin","version":"0.16.0","entry":"skills/version/scripts/version.mjs","commands":{"marketplace add":"skills/marketplace/scripts/add.mjs","marketplace init":"skills/marketplace/scripts/marketplace.mjs","marketplace validate":"skills/marketplace/scripts/validate.mjs","plugin build":"skills/build-plugin/scripts/build.mjs","plugin init":"skills/init-universal-plugin/scripts/init.mjs","plugin version":"skills/version/scripts/version.mjs"}};
 import { spawnSync } from "node:child_process";
 //#region src/compile/scripts.ts
 /** The global the header assigns the script data to. Framework-neutral: a script's own code, or the