universal-plugin 0.8.0 → 0.10.0

package/dist/cli.mjs

@@ -3779,12 +3779,6 @@ function output(data, view) {
 	if (isJsonOutput()) printJson(data);
 	else console.log(encode(view ?? data));
 }
-/** Print a result whose default rendering is a document body rather than a record.
-* `--format json` still emits the structured payload. */
-function outputText(data, text) {
-	if (isJsonOutput()) printJson(data);
-	else text();
-}
 //#endregion
 //#region ../../node_modules/.pnpm/semver@7.8.1/node_modules/semver/internal/constants.js
 var require_constants = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -5413,6 +5407,23 @@ function claudeArtifact(metadata, plugins) {
 		})
 	};
 }
+/** 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";
+}
+/** Codex states a source as an object either way: a repository path is tagged `local`, and a source
+*  that already carries its own tag passes through as it stands. */
+function codexSource(source) {
+	return typeof source === "string" ? {
+		source: "local",
+		path: source
+	} : source;
+}
 function codexArtifact(metadata, plugins) {
 	return {
 		path: TARGET_CATALOG_PATHS.codex,
@@ -5422,10 +5433,7 @@ function codexArtifact(metadata, plugins) {
 			plugins: plugins.map((plugin) => ({
 				name: plugin.name,
 				version: plugin.metadata.version,
-				source: {
-					source: "local",
-					path: plugin.source
-				},
+				source: codexSource(plugin.source),
 				policy: {
 					installation: "AVAILABLE",
 					authentication: "ON_INSTALL"
@@ -5474,6 +5482,72 @@ const VENDOR_TARGETS = {
 	codex: "codex",
 	"copilot-cli": "copilot"
 };
+const GITHUB_URL = /^(?:https?:\/\/(?:www\.)?github\.com\/|git@github\.com:)([^/]+\/[^/]+?)(?:\.git)?\/?$/;
+/** A git URL read as an origin, recognizing a GitHub one so an entry at the repository root can use
+*  the tidier `github` form. */
+function originFromUrl(url) {
+	const match = GITHUB_URL.exec(url.trim());
+	return match ? {
+		url,
+		repo: match[1]
+	} : { url };
+}
+/** An `owner/repo` slug as an origin. */
+function originFromRepo(repo) {
+	return {
+		url: `https://github.com/${repo}.git`,
+		repo
+	};
+}
+/** The path part of a local source, `./` stripped, empty at the marketplace root. */
+function localSourcePath(source) {
+	const raw = typeof source === "string" ? source : source.path;
+	if (typeof raw !== "string") return void 0;
+	return raw.replace(/^\.\/?/, "").replace(/\/+$/, "");
+}
+/** Rewrites a source that is local to *another* marketplace into one that resolves from anywhere.
+*
+*  A copied entry's `./plugins/aced` is relative to the marketplace it came from, so carrying it
+*  across unchanged would point at a directory this repository does not have. The path is not
+*  useless, though — it is a location inside a repository whose URL is known, which is exactly what
+*  `git-subdir` states. An entry at that repository's root needs no subdirectory and takes the
+*  plainer `github` or `url` form. */
+function absoluteSource(origin, source) {
+	const subdir = localSourcePath(source);
+	if (subdir === void 0) return void 0;
+	if (subdir === "" || subdir === ".") return origin.repo ? {
+		source: "github",
+		repo: origin.repo
+	} : {
+		source: "url",
+		url: origin.url
+	};
+	return {
+		source: "git-subdir",
+		url: origin.url,
+		path: subdir
+	};
+}
+/** 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). */
+const TARGET_SOURCE_KINDS = {
+	claude: [
+		"path",
+		"npm",
+		"github",
+		"url",
+		"git-subdir"
+	],
+	codex: ["path", "npm"],
+	copilot: ["path"],
+	cursor: ["path"]
+};
 /** 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
@@ -5482,7 +5556,7 @@ const VENDOR_TARGETS = {
 *  `version` is derived, never authored (ADR-0010 §3): the entry carries whatever the canonical
 *  manifest carries, and a version left behind on an entry whose manifest declares none is removed
 *  rather than kept. */
-function mergeCatalogEntry(target, metadata, plugin, readExisting) {
+function mergeCatalogEntry(target, metadata, plugin, readExisting, { keepForeignSource = true } = {}) {
 	const artifact = serializeTarget(target, metadata, [plugin])[0];
 	const existing = readExisting(artifact.path);
 	if (existing === void 0) return artifact;
@@ -5491,7 +5565,7 @@ function mergeCatalogEntry(target, metadata, plugin, readExisting) {
 	const entry = generated.plugins[0];
 	const merged = { ...previous };
 	for (const [key, value] of Object.entries(generated)) if (!(key in merged)) merged[key] = value;
-	merged.plugins = mergeEntries(previous, entry);
+	merged.plugins = mergeEntries(previous, entry, { keepForeignSource });
 	return {
 		path: artifact.path,
 		content: json(merged)
@@ -5507,18 +5581,78 @@ function parseCatalog(content, path) {
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`error: existing catalog "${path}" is not a JSON object`);
 	return parsed;
 }
-function mergeEntries(previous, entry) {
+function mergeEntries(previous, entry, { keepForeignSource = false } = {}) {
 	const entries = Array.isArray(previous.plugins) ? [...previous.plugins] : [];
 	const index = entries.findIndex((candidate) => typeof candidate === "object" && candidate !== null && candidate.name === entry.name);
 	if (index === -1) return [...entries, entry];
+	const existing = entries[index];
 	const merged = {
-		...entries[index],
+		...existing,
 		...entry
 	};
 	if (!("version" in entry)) delete merged.version;
+	if (keepForeignSource && !isLocalCatalogSource(existing.source)) merged.source = existing.source;
 	entries[index] = merged;
 	return entries;
 }
+/** Re-derives a whole catalog from discovery while keeping the entries discovery cannot see.
+*
+*  A repository may list plugins that live somewhere else — an npm package, a GitHub repository —
+*  put there by `marketplace add`. Nothing on disk produces those, so a regeneration that trusted
+*  discovery alone would report every one of them as a deletion, and `--force` would carry it out.
+*  Two things survive instead: an entry whose source is not local stays even though discovery never
+*  saw it, and a discovered plugin whose existing entry names a non-local source keeps that source
+*  with only its derived metadata refreshed.
+*
+*  That second case is the loss in issue #86 — a plugin shipped through npm, whose repository path
+*  holds only gitignored build output, rewritten to that path on every regeneration.
+*
+*  What discovery owns, it still owns: a local-path entry it no longer finds is dropped, so the
+*  catalog keeps mirroring the repository for the part of the repository it describes. */
+function mergeDiscoveredCatalog(generated, existing) {
+	if (existing === void 0) return generated;
+	let previous;
+	try {
+		previous = parseCatalog(existing, generated.path);
+	} catch {
+		return generated;
+	}
+	const foreign = /* @__PURE__ */ new Map();
+	for (const candidate of Array.isArray(previous.plugins) ? previous.plugins : []) {
+		if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) continue;
+		const entry = candidate;
+		if (typeof entry.name !== "string" || isLocalCatalogSource(entry.source)) continue;
+		foreign.set(entry.name, entry);
+	}
+	if (foreign.size === 0) return generated;
+	const catalog = JSON.parse(generated.content);
+	const discovered = catalog.plugins ?? [];
+	const merged = discovered.map((entry) => {
+		const kept = typeof entry.name === "string" ? foreign.get(entry.name) : void 0;
+		return kept === void 0 ? entry : {
+			...entry,
+			source: kept.source
+		};
+	});
+	const discoveredNames = new Set(discovered.map((entry) => entry.name));
+	for (const [name, entry] of foreign) if (!discoveredNames.has(name)) merged.push(entry);
+	catalog.plugins = merged;
+	return {
+		path: generated.path,
+		content: json(catalog)
+	};
+}
+/** The plugin names a catalog lists, so a result row can report what the file ends up saying rather
+*  than only what discovery contributed to it. */
+function catalogEntryNames(content) {
+	try {
+		const parsed = JSON.parse(content);
+		if (!Array.isArray(parsed.plugins)) return [];
+		return parsed.plugins.map((entry) => typeof entry === "object" && entry !== null ? entry.name : void 0).filter((name) => typeof name === "string");
+	} catch {
+		return [];
+	}
+}
 /** The catalog's own top-level identity, read back from the file the repository already carries, so
 *  a refresh re-derives one entry without proposing a name or an owner of its own. */
 function existingMetadata(previous) {
@@ -5545,7 +5679,7 @@ function refreshCatalogEntry(target, plugin, existing) {
 		path: catalogPath,
 		content: json({
 			...previous,
-			plugins: mergeEntries(previous, entry)
+			plugins: mergeEntries(previous, entry, { keepForeignSource: true })
 		})
 	};
 }
@@ -5632,6 +5766,79 @@ function gatherCatalogRepo(root) {
 		catalogs
 	};
 }
+/** Where Claude Code records the marketplaces a user has added, and clones each one.
+*
+*  This is read, never written. It is the one place on the machine that already knows what
+*  `<plugin>@<marketplace>` refers to, so resolving through it asks the user for nothing and reaches
+*  no network. A marketplace they have not added is simply not found, and `--from` names it instead. */
+function claudePluginsHome(home = os.homedir()) {
+	return path.join(home, ".claude", "plugins");
+}
+/** The origin the runtime recorded for a marketplace, in the vocabulary it records it in: a
+*  `github` repo slug, or a `git`/`url` clone URL. */
+function registryOrigin(source) {
+	if (typeof source !== "object" || source === null || Array.isArray(source)) return void 0;
+	const record = source;
+	if (record.source === "github" && typeof record.repo === "string") return originFromRepo(record.repo);
+	if ((record.source === "git" || record.source === "url") && typeof record.url === "string") return originFromUrl(record.url);
+}
+/** The URL a checkout was cloned from, which is the origin for a marketplace the registry does not
+*  describe — one reached through `--from`, or added before the runtime recorded a source. */
+function gitRemoteUrl(dir) {
+	try {
+		const url = execFileSync("git", [
+			"-C",
+			dir,
+			"remote",
+			"get-url",
+			"origin"
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		return url === "" ? void 0 : url;
+	} catch {
+		return;
+	}
+}
+/** The marketplace a name refers to, or `undefined` when the user has not added it. */
+function resolveKnownMarketplace(name, marketplaceFs = realMarketplaceFs, home = os.homedir()) {
+	const pluginsHome = claudePluginsHome(home);
+	const registry = path.join(pluginsHome, "known_marketplaces.json");
+	if (marketplaceFs.exists(registry)) {
+		let parsed;
+		try {
+			parsed = JSON.parse(marketplaceFs.read(registry));
+		} catch {
+			parsed = void 0;
+		}
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+			const entry = parsed[name];
+			if (typeof entry === "object" && entry !== null) {
+				const record = entry;
+				const location = record.installLocation;
+				if (typeof location === "string" && marketplaceFs.exists(location)) return {
+					dir: location,
+					origin: registryOrigin(record.source)
+				};
+			}
+		}
+	}
+	const conventional = path.join(pluginsHome, "marketplaces", name);
+	return marketplaceFs.exists(conventional) ? { dir: conventional } : void 0;
+}
+/** The catalog a marketplace directory carries, tried in the order the runtimes agree on: the Claude
+*  path first, because three of the four read it. */
+function readMarketplaceCatalog(dir, marketplaceFs = realMarketplaceFs) {
+	for (const relative of Object.values(TARGET_CATALOG_PATHS)) {
+		const file = path.join(dir, relative);
+		if (marketplaceFs.exists(file)) return marketplaceFs.read(file);
+	}
+}
 //#endregion
 //#region src/marketplace/validation.ts
 function isObject$1(value) {
@@ -6241,7 +6448,7 @@ function buildPlugin(root, opts = {}) {
 	}
 	if (vendors.length === 0) {
 		const signals = legacyLayoutSignals(manifest, fs.existsSync(path.join(root, SHADOWING_MANIFEST)));
-		if (signals.length > 0) throw new Error(`Nothing was derived, and this project is still on the pre-0.6 manifest layout:\n${signals.map((s) => `  - ${s}`).join("\n")}\nRun /universal-plugin:doctor for the full diagnosis and the skill that owns each repair.`);
+		if (signals.length > 0) throw new Error(`Nothing was derived, and this project is still on the pre-0.6 manifest layout:\n${signals.map((s) => `  - ${s}`).join("\n")}\nRun /universal-plugin:doctor-universal-plugin for the full diagnosis and the skill that owns each repair.`);
 		warnings.push("No vendors declared in harnesses — nothing to build");
 		return {
 			vendors: [],
@@ -6681,8 +6888,8 @@ function formatMcpNote(note) {
 }
 //#endregion
 //#region src/build/cli.ts
-const NEXT_STEP_NOTHING_BUILT = "→ /universal-plugin:doctor — diagnose why nothing is declared\n";
-const NEXT_STEP_BUILT = "→ /universal-plugin:doctor — check the built manifests against plugin.json\n";
+const NEXT_STEP_NOTHING_BUILT = "→ /universal-plugin:doctor-universal-plugin — diagnose why nothing is declared\n";
+const NEXT_STEP_BUILT = "→ /universal-plugin:doctor-universal-plugin — check the built manifests against plugin.json\n";
 /** Every hint names a command that exists today: an agent that follows a hint into
 *  `unknown command` is at a dead end (issue #80). A refreshed catalog is checked by
 *  `marketplace validate`, pointed at the repository the catalog lives in. */
@@ -7094,7 +7301,7 @@ const realConfigFs = {
 function assertNotReserved(key) {
 	if (isReservedKey(key)) throw new Error(`error: "${key}" is a reserved key (universal-plugin's own config) — not a plugin-registered array; edit .agents/universal-plugin.json directly`);
 }
-function addCommand(fs) {
+function addCommand$1(fs) {
 	return new Command("add").description("Register (append or replace-by-name) an entry in the array at a config key").requiredOption("--key <key>", "The config key whose array to write").requiredOption("--entry <json>", "The entry object as JSON (must include a \"name\" field)").option("--format <format>", "Output format: json or toon (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin config add --key sdd-plugins --entry '{\"name\":\"aces\",\"handles\":[\"agent evaluation\"]}'\n").action((opts) => {
 		try {
 			assertNotReserved(opts.key);
@@ -7153,148 +7360,35 @@ function getCommand(fs) {
 	});
 }
 function configCommand(fs = realConfigFs) {
-	return new Command("config").description("Read and write plugin-registered config in .agents/universal-plugin.json").addCommand(addCommand(fs)).addCommand(getCommand(fs));
+	return new Command("config").description("Read and write plugin-registered config in .agents/universal-plugin.json").addCommand(addCommand$1(fs)).addCommand(getCommand(fs));
 }
 //#endregion
-//#region src/governance/fs.ts
-const realGovernanceFs = {
-	exists: (p) => fs.existsSync(p),
-	read: (p) => fs.readFileSync(p, "utf8"),
-	list: (dir) => {
-		if (!fs.existsSync(dir)) return [];
-		return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.slice(0, -3));
-	}
-};
-//#endregion
-//#region src/governance/governance.ts
-function getManagedDir() {
-	if (process.platform === "darwin") return "/Library/Application Support/UniPlugin/governances";
-	if (process.platform === "win32") return path.join(process.env["ProgramData"] ?? "C:\\ProgramData", "UniPlugin", "governances");
-	return "/etc/universal-plugin/governances";
-}
-function getUserDir() {
-	return path.join(os.homedir(), ".agents", "governances");
-}
-function getProjectDir(root) {
-	return path.join(root, "governances");
-}
-function getLocalDir(root) {
-	return path.join(root, ".agents", "governances");
-}
-function getPackageDir() {
-	const thisFile = fileURLToPath(import.meta.url);
-	return path.join(path.dirname(thisFile), "..", "governances");
-}
-function getScopedPaths(root) {
-	return [
-		{
-			scope: "managed",
-			dir: getManagedDir()
-		},
-		{
-			scope: "project",
-			dir: getProjectDir(root)
-		},
-		{
-			scope: "local",
-			dir: getLocalDir(root)
-		},
-		{
-			scope: "user",
-			dir: getUserDir()
-		},
-		{
-			scope: "package",
-			dir: getPackageDir()
-		}
-	];
+//#region src/governance/cli.ts
+const RETIRED = "universal-plugin governance is retired; buddy-agent-harness reference reads the same documents.\n";
+const IN_A_SKILL = "In a skill, load a document with the load-reference skill in the buddy-agent-harness plugin.\n";
+function retire(replacement) {
+	process.stderr.write(`${RETIRED}${IN_A_SKILL}→ ${replacement}\n`);
+	process.exit(1);
 }
-function showGovernance(name, root, govFs, storeOpts) {
-	const slashIdx = name.indexOf("/");
-	if (slashIdx !== -1 && storeOpts) {
-		const pluginName = name.slice(0, slashIdx);
-		const assetName = name.slice(slashIdx + 1);
-		for (const scope of [
-			"managed",
-			"project",
-			"user"
-		]) {
-			let dir;
-			if (scope === "managed") dir = getManagedDir();
-			else if (scope === "project") dir = getProjectDir(root);
-			else dir = getUserDir();
-			const filePath = path.join(dir, pluginName, `${assetName}.md`);
-			if (govFs.exists(filePath)) return {
-				content: govFs.read(filePath),
-				scope
-			};
-		}
-		const entry = storeOpts.state.assets[pluginName];
-		if (!entry) return null;
-		const segment = path.join(entry.source, `${pluginName}@${entry.version}`);
-		const storePath = path.join(storeOpts.globalStorePath, segment, "governances", `${assetName}.md`);
-		if (govFs.exists(storePath)) return {
-			content: govFs.read(storePath),
-			scope: "store"
-		};
-		return null;
-	}
-	for (const { scope, dir } of getScopedPaths(root)) {
-		const filePath = path.join(dir, `${name}.md`);
-		if (govFs.exists(filePath)) return {
-			content: govFs.read(filePath),
-			scope
-		};
+/** The flags `governance show` took that carried a value, so the value is not read as the name. */
+const VALUE_FLAGS = new Set(["--root", "--format"]);
+function documentName(args) {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (VALUE_FLAGS.has(arg)) i++;
+		else if (!arg.startsWith("-")) return arg;
 	}
-	return null;
+	return "<name>";
 }
-function listGovernances(root, govFs) {
-	const seen = /* @__PURE__ */ new Set();
-	const entries = [];
-	for (const { scope, dir } of getScopedPaths(root)) for (const name of govFs.list(dir)) if (!seen.has(name)) {
-		seen.add(name);
-		entries.push({
-			name,
-			scope
-		});
-	}
-	return entries.sort((a, b) => a.name.localeCompare(b.name));
-}
-//#endregion
-//#region src/governance/cli.ts
-function readGlobalState() {
-	const p = path.join(os.homedir(), ".agents", "universal-plugin.json");
-	try {
-		return mergeSafeState(JSON.parse(fs.readFileSync(p, "utf8")));
-	} catch {
-		return emptyState();
-	}
+/** Takes any argument or flag, so a caller still passing `--root` or `--format json` is told where
+*  to go instead of what it typed wrong. */
+function retiredCommand(name) {
+	return new Command(name).allowUnknownOption().allowExcessArguments().helpOption(false);
 }
 function governanceCommand() {
-	const cmd = new Command("governance").description("Manage plugin governances").helpCommand(false);
-	cmd.command("show <name>").description("Show a governance by name").option("--format <format>", "Output format: json or text (default: text)").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((name, opts) => {
-		const result = showGovernance(name, resolveRoot(opts.root), realGovernanceFs, {
-			state: readGlobalState(),
-			globalStorePath: globalStorePath()
-		});
-		if (!result) {
-			process.stderr.write(`Governance "${name}" not found\n`);
-			process.exit(1);
-		}
-		outputText(result, () => {
-			process.stdout.write(result.content);
-		});
-	});
-	cmd.command("list").description("List available governances").option("--format <format>", "Output format: json or text (default: text)").addOption(ROOT_OPTION).addOption(new Option("--json").hideHelp()).action((opts) => {
-		const entries = listGovernances(resolveRoot(opts.root), realGovernanceFs);
-		output(entries, {
-			governances: entries.map((e) => ({
-				name: e.name,
-				scope: e.scope
-			})),
-			summary: `${entries.length} governances across ${new Set(entries.map((e) => e.scope)).size} scopes`
-		});
-	});
+	const cmd = retiredCommand("governance").description("Retired: use buddy-agent-harness reference").helpOption("-h, --help", "Show help").helpCommand(false).addHelpText("after", "\nThis command is retired. buddy-agent-harness reference show|list|search reads the same documents.\nExample:\n  $ buddy-agent-harness reference show plugin-design\n").action(() => retire("buddy-agent-harness reference list"));
+	cmd.addCommand(retiredCommand("show").action((_opts, command) => retire(`buddy-agent-harness reference show ${documentName(command.args)}`)));
+	cmd.addCommand(retiredCommand("list").action(() => retire("buddy-agent-harness reference list")));
 	return cmd;
 }
 //#endregion
@@ -7984,6 +8078,9 @@ function manifestOwner(manifest) {
 		return owner;
 	}
 }
+/** The catalog's own identity: its name and its owner, from the root manifest unless overridden.
+*  Exported because `marketplace add` creates a catalog in a repository that has no plugins of its
+*  own to discover, and the two commands must name that catalog the same way. */
 function deriveMetadata(root, fs, opts) {
 	const rootManifest = path.join(root, "plugin.json");
 	if (fs.exists(rootManifest)) assertContained(root, rootManifest, fs, "root plugin.json");
@@ -8044,7 +8141,7 @@ function writeArtifacts(fs, artifacts, root) {
 	const changed = artifacts.filter((artifact) => !sameArtifact(fs, path.join(root, artifact.path), artifact.content));
 	for (const artifact of changed) fs.writeAtomically(path.join(root, artifact.path), artifact.content);
 }
-function selectedTargets(targets) {
+function selectedTargets$1(targets) {
 	return targets && targets.length > 0 ? [...new Set(targets)] : [
 		"claude",
 		"codex",
@@ -8052,6 +8149,9 @@ function selectedTargets(targets) {
 		"cursor"
 	];
 }
+function readCatalog(fs, file) {
+	return fs.exists(file) ? fs.read(file) : void 0;
+}
 function sameArtifact(fs, file, content) {
 	if (!fs.exists(file)) return false;
 	const existing = fs.read(file);
@@ -8073,12 +8173,16 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 	const root = path.resolve(rootInput);
 	const metadata = deriveMetadata(root, fs, opts);
 	const plugins = discoverPlugins(root, fs, opts.scanDirs);
-	const planned = selectedTargets(opts.targets).map((target) => ({
+	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.join(root, artifact.path), fs, "selected artifact");
+	const planned = derived.map(({ target, artifacts }) => ({
+		target,
+		artifacts: artifacts.map((artifact) => mergeDiscoveredCatalog(artifact, readCatalog(fs, path.join(root, artifact.path))))
+	}));
 	for (const { target, artifacts } of planned) for (const artifact of artifacts) {
-		assertContained(root, path.join(root, artifact.path), fs, "selected artifact");
 		const issues = validateCatalogContent(target, artifact.content);
 		if (issues.length > 0) throw new Error(formatCatalogIssues(artifact.path, issues));
 	}
@@ -8101,13 +8205,403 @@ function initializeMarketplace(rootInput, opts = {}, fs = realMarketplaceFs) {
 			target,
 			status: opts.dryRun ? "planned" : unchanged ? "unchanged" : "generated",
 			paths: artifacts.map((artifact) => artifact.path),
-			plugins: plugins.map((plugin) => plugin.name)
+			plugins: [...new Set(artifacts.flatMap((artifact) => catalogEntryNames(artifact.content)))]
 		};
 	});
 	if (!opts.dryRun && plugins.length > 0) writeArtifacts(fs, planned.flatMap((entry) => entry.artifacts), root);
 	return results;
 }
 //#endregion
+//#region src/marketplace/spec.ts
+/** What a user names on the command line when they ask for a plugin to be listed, reduced to the
+*  source a catalog entry states. Pure: every rule here is a decision about the string itself, so
+*  nothing consults the filesystem, the network, or the runtime's configuration. */
+const GITHUB_REPO = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const NPM_PACKAGE = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** The last meaningful segment of a path or URL, with a `.git` suffix removed. */
+function basename(value) {
+	const segments = value.replace(/[/\\]+$/, "").split(/[/\\]/);
+	return (segments[segments.length - 1] ?? value).replace(/\.git$/, "");
+}
+/** An npm package's entry name is the package name without its scope: `@cyberuni/upx` lists as
+*  `upx`, which is what a user installs and what every other source form yields. */
+function packageEntryName(pkg) {
+	return pkg.startsWith("@") ? pkg.split("/")[1] ?? pkg : pkg;
+}
+function pathSpec(value) {
+	const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
+	const source = normalized.startsWith("./") || normalized.startsWith("../") ? normalized : `./${normalized}`;
+	return {
+		kind: "path",
+		name: basename(normalized),
+		source
+	};
+}
+function npmSpec(pkg) {
+	return {
+		kind: "npm",
+		name: packageEntryName(pkg),
+		source: {
+			source: "npm",
+			package: pkg
+		}
+	};
+}
+function githubSpec(repo) {
+	return {
+		kind: "github",
+		name: basename(repo),
+		source: {
+			source: "github",
+			repo
+		}
+	};
+}
+function urlSpec(url) {
+	return {
+		kind: "url",
+		name: basename(url),
+		source: {
+			source: "url",
+			url
+		}
+	};
+}
+/** Splits `<plugin>@<marketplace>` at the separator that is not a scope marker, so a scoped package
+*  name keeps its leading `@`. */
+function splitMarketplace(value) {
+	const at = value.indexOf("@", value.startsWith("@") ? 1 : 0);
+	if (at <= 0) return void 0;
+	const plugin = value.slice(0, at);
+	const marketplace = value.slice(at + 1);
+	if (plugin === "" || marketplace === "" || marketplace.includes("/")) return void 0;
+	return {
+		plugin,
+		marketplace
+	};
+}
+function marketplaceSpec(value) {
+	const split = splitMarketplace(value);
+	if (!split) throw new Error(`error: "${value}" is not <plugin>@<marketplace>`);
+	return {
+		kind: "marketplace",
+		name: packageEntryName(split.plugin),
+		...split
+	};
+}
+const SHA = /^[a-f0-9]{40}$/;
+/** A subdirectory as `git-subdir` states it: no leading `./`, no trailing slash. */
+function normalizeSubdir(subdir) {
+	const path = subdir.trim().replace(/\\/g, "/").replace(/^\.\/?/, "").replace(/\/+$/, "");
+	if (path === "") throw new Error("error: --subdir must name a directory inside the repository");
+	if (path.startsWith("/")) throw new Error(`error: --subdir "${subdir}" must be relative to the repository root`);
+	return path;
+}
+/** The git URL a spec's source points at, for the two kinds that name a whole repository. */
+function repositoryUrl(spec) {
+	if (typeof spec.source !== "object") return void 0;
+	if (spec.source.source === "github") return originFromRepo(spec.source.repo).url;
+	if (spec.source.source === "url") return spec.source.url;
+}
+/** Narrows a whole-repository source to the one directory inside it that is the plugin.
+*
+*  A monorepo publishes several plugins from one repository, and neither `github` nor `url` can say
+*  which directory. `git-subdir` is the form that can, so `--subdir` turns the source into one —
+*  and the entry takes its name from that directory rather than from the repository. */
+function withSubdir(spec, subdir) {
+	const url = repositoryUrl(spec);
+	if (url === void 0) throw new Error(`error: --subdir applies to a repository source, not to a ${spec.kind} one`);
+	const path = normalizeSubdir(subdir);
+	return {
+		kind: spec.kind,
+		name: basename(path),
+		source: {
+			source: "git-subdir",
+			url,
+			path
+		}
+	};
+}
+/** Pins a source to a branch, tag, or commit. Only the git-backed forms carry one; an npm package is
+*  pinned by version and a path is whatever is on disk. */
+function withPin(spec, ref, sha) {
+	if (ref === void 0 && sha === void 0) return spec;
+	const source = spec.source;
+	if (typeof source !== "object" || ![
+		"url",
+		"github",
+		"git-subdir"
+	].includes(source.source)) throw new Error(`error: --ref and --sha apply to a git source, not to a ${spec.kind} one`);
+	if (sha !== void 0 && !SHA.test(sha)) throw new Error(`error: --sha "${sha}" must be a full 40-character commit hash`);
+	return {
+		...spec,
+		source: {
+			...source,
+			...ref === void 0 ? {} : { ref },
+			...sha === void 0 ? {} : { sha }
+		}
+	};
+}
+function looksLikeUrl(value) {
+	return value.includes("://") || value.startsWith("git@");
+}
+function looksLikePath(value) {
+	return value.startsWith("./") || value.startsWith("../") || value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value);
+}
+/** Applies the kind the user named, so every guess below has an override. */
+function explicitSpec(value, kind) {
+	switch (kind) {
+		case "path": return pathSpec(value);
+		case "npm": return npmSpec(value.replace(/^npm:/, ""));
+		case "github": return githubSpec(value);
+		case "url": return urlSpec(value);
+		case "marketplace": return marketplaceSpec(value);
+	}
+}
+/** Reads a spec string as the source it names.
+*
+*  The order below is the disambiguation, and every step of it is overridable with an explicit kind:
+*
+*  1. an `npm:` prefix, which is how a bare name that looks like anything else is forced to a package
+*  2. a URL scheme or an `scp`-style `git@host:path`
+*  3. a path, which has to say so with `./`, `../`, or a leading slash
+*  4. `<plugin>@<marketplace>`, splitting after a leading scope `@` so `@scope/pkg` is not one
+*  5. `owner/repo`
+*  6. anything else left, which is an npm package name
+*
+*  Step 3 is why `plugins/alpha` reads as a GitHub repository rather than a directory: both are
+*  `a/b`, and a guess that reached for the filesystem would answer differently depending on where
+*  the command was run. `./plugins/alpha` or `--path` says it plainly. */
+function parsePluginSpec(value, opts = {}) {
+	const { kind, subdir, ref, sha } = opts;
+	const spec = value.trim();
+	if (spec === "") throw new Error("error: a plugin spec is required");
+	const shape = (base) => withPin(subdir === void 0 ? base : withSubdir(base, subdir), ref, sha);
+	if (kind) return shape(explicitSpec(spec, kind));
+	if (spec.startsWith("npm:")) {
+		const pkg = spec.slice(4);
+		if (!NPM_PACKAGE.test(pkg)) throw new Error(`error: "${pkg}" is not an npm package name`);
+		return shape(npmSpec(pkg));
+	}
+	if (looksLikeUrl(spec)) return shape(urlSpec(spec));
+	if (looksLikePath(spec)) return shape(pathSpec(spec));
+	const split = splitMarketplace(spec);
+	if (split) return shape({
+		kind: "marketplace",
+		name: packageEntryName(split.plugin),
+		...split
+	});
+	if (GITHUB_REPO.test(spec)) return shape(githubSpec(spec));
+	if (NPM_PACKAGE.test(spec)) return shape(npmSpec(spec));
+	throw new Error(`error: cannot tell what "${spec}" names; pass --path, --npm, --github, --url, or --from-marketplace`);
+}
+//#endregion
+//#region src/marketplace/add.ts
+/** The manifest fields a catalog entry carries. Exactly the set the catalog already derives from a
+*  discovered plugin, so an added entry and a discovered one say the same kinds of things. */
+const ENTRY_METADATA_FIELDS = [
+	"description",
+	"version",
+	"homepage",
+	"repository",
+	"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;
+	const detail = source.package ?? source.repo ?? source.url ?? source.path;
+	return typeof detail === "string" ? `${source.source}:${detail}` : String(source.source);
+}
+function readJsonFile(fs, file) {
+	if (!fs.exists(file)) return void 0;
+	try {
+		const parsed = JSON.parse(fs.read(file));
+		return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Metadata already on this machine for the plugin being listed.
+*
+*  A local path carries its own manifest, and an npm package that happens to be installed carries a
+*  `package.json`. Neither is fetched: what is here is read, what is not here is left to the
+*  metadata flags. An entry missing an optional field still installs. */
+function localMetadata(root, spec, fs) {
+	if (spec.kind === "path" && typeof spec.source === "string") return readJsonFile(fs, path.join(root, spec.source, "plugin.json")) ?? {};
+	if (spec.kind === "npm" && typeof spec.source === "object") {
+		const pkg = spec.source.package;
+		if (typeof pkg !== "string") return {};
+		return readJsonFile(fs, path.join(root, "node_modules", pkg, "package.json")) ?? {};
+	}
+	return {};
+}
+/** The entry another marketplace already publishes for this plugin, copied rather than invented.
+*
+*  The catalog schema has no "from another marketplace" source, so there is nothing to write until
+*  that marketplace has been read. Its entry already names a source every runtime can resolve — that
+*  is what makes it publishable — so the whole entry comes across. */
+function resolveFromMarketplace(spec, opts, fs) {
+	const marketplace = spec.marketplace;
+	const known = opts.from === void 0 ? resolveKnownMarketplace(marketplace, fs) : { dir: opts.from };
+	if (known === void 0) throw new Error(`error: marketplace "${marketplace}" is not installed; add it in the runtime first, or pass --from <path>`);
+	const dir = known.dir;
+	const content = readMarketplaceCatalog(dir, fs);
+	if (content === void 0) throw new Error(`error: no marketplace.json found under "${dir}"`);
+	let catalog;
+	try {
+		catalog = JSON.parse(content);
+	} catch {
+		throw new Error(`error: the catalog in "${dir}" is not valid JSON`);
+	}
+	const found = (typeof catalog === "object" && catalog !== null && Array.isArray(catalog.plugins) ? catalog.plugins : []).find((entry) => typeof entry === "object" && entry !== null && entry.name === spec.plugin);
+	if (!found) throw new Error(`error: marketplace "${marketplace}" lists no plugin "${spec.plugin}"`);
+	const source = found.source;
+	if (source === void 0) throw new Error(`error: the "${spec.plugin}" entry in "${marketplace}" names no source`);
+	if (!isLocalCatalogSource(source)) return {
+		source,
+		metadata: found
+	};
+	const remote = gitRemoteUrl(dir);
+	const origin = known.origin ?? (remote === void 0 ? void 0 : originFromUrl(remote));
+	if (origin === void 0) throw new Error(`error: "${spec.plugin}" is local to marketplace "${marketplace}", and that marketplace has no remote to rewrite its source against`);
+	const rewritten = absoluteSource(origin, source);
+	if (rewritten === void 0) throw new Error(`error: the "${spec.plugin}" entry in "${marketplace}" names a source this command cannot read`);
+	return {
+		source: rewritten,
+		metadata: found
+	};
+}
+function selectedTargets(targets) {
+	return targets && targets.length > 0 ? [...new Set(targets)] : [
+		"claude",
+		"codex",
+		"copilot",
+		"cursor"
+	];
+}
+function entryMetadata(discovered, supplied = {}) {
+	const metadata = {};
+	for (const field of ENTRY_METADATA_FIELDS) {
+		const value = supplied[field] ?? discovered[field];
+		if (value !== void 0) metadata[field] = value;
+	}
+	return metadata;
+}
+function catalogEntry(content, name) {
+	try {
+		const parsed = JSON.parse(content);
+		if (!Array.isArray(parsed.plugins)) return void 0;
+		return parsed.plugins.find((entry) => typeof entry === "object" && entry !== null && entry.name === name);
+	} catch {
+		return;
+	}
+}
+/** Lists a plugin that lives somewhere else in this repository's catalogs.
+*
+*  Where `marketplace init` derives a catalog from the plugins a repository holds, this adds one it
+*  does not: an npm package, a GitHub repository, an entry another marketplace already publishes.
+*  Together they let one repository be both — a plugin's own home and a curated list.
+*
+*  Nothing is fetched and nothing is published. The command reads this repository, and at most a
+*  marketplace already installed on this machine, and writes catalog files. */
+function addToMarketplace(rootInput, spec, opts = {}, fs = realMarketplaceFs) {
+	const root = path.resolve(rootInput);
+	const parsed = parsePluginSpec(spec, {
+		kind: opts.kind,
+		subdir: opts.subdir,
+		ref: opts.ref,
+		sha: opts.sha
+	});
+	const name = opts.name ?? parsed.name;
+	assertMarketplaceName(name, "plugin name");
+	const resolved = parsed.kind === "marketplace" ? resolveFromMarketplace(parsed, opts, fs) : {
+		source: parsed.source,
+		metadata: localMetadata(root, parsed, fs)
+	};
+	const metadata = deriveMetadata(root, fs, {
+		name: opts.marketplaceName,
+		owner: opts.owner
+	});
+	const plugin = {
+		name,
+		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 catalogPath = TARGET_CATALOG_PATHS[target];
+		const file = path.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
+		};
+		return {
+			target,
+			catalogPath,
+			file,
+			existing,
+			skipped: void 0,
+			artifact: mergeCatalogEntry(target, metadata, plugin, () => existing, { keepForeignSource: false })
+		};
+	});
+	for (const entry of planned) {
+		if (!entry.artifact) continue;
+		const issues = validateCatalogContent(entry.target, entry.artifact.content);
+		if (issues.length > 0) throw new Error(formatCatalogIssues(entry.catalogPath, issues));
+	}
+	const conflicts = planned.filter((entry) => {
+		if (!entry.artifact || entry.existing === void 0 || opts.force) return false;
+		if (catalogEntry(entry.existing, name) === void 0) return false;
+		return !sameCatalogContent(entry.existing, entry.artifact.content);
+	}).map((entry) => entry.catalogPath);
+	if (conflicts.length > 0) throw new Error(`error: "${name}" is already listed differently in ${conflicts.join(", ")}; rerun with --force to replace it`);
+	const results = planned.map((entry) => {
+		const row = {
+			target: entry.target,
+			entry: name,
+			source: rendered,
+			path: entry.catalogPath
+		};
+		if (entry.skipped || !entry.artifact) return {
+			...row,
+			status: "skipped",
+			source: rendered,
+			reason: entry.skipped
+		};
+		if (entry.existing !== void 0 && sameCatalogContent(entry.existing, entry.artifact.content)) return {
+			...row,
+			status: "unchanged"
+		};
+		if (opts.dryRun) return {
+			...row,
+			status: "planned"
+		};
+		const existed = entry.existing !== void 0 && catalogEntry(entry.existing, name) !== void 0;
+		return {
+			...row,
+			status: existed ? "updated" : "added"
+		};
+	});
+	if (!opts.dryRun) for (const entry of planned) {
+		if (!entry.artifact) continue;
+		if (entry.existing !== void 0 && sameCatalogContent(entry.existing, entry.artifact.content)) continue;
+		fs.writeAtomically(entry.file, entry.artifact.content);
+	}
+	return results;
+}
+//#endregion
 //#region src/marketplace/validate.ts
 /** A `./`-prefixed source names a directory inside the repository, and Claude Code resolves it
 *  against the directory holding `.claude-plugin/`. A source pointing nowhere passes every schema
@@ -8178,6 +8672,65 @@ function targetsFromOptions(opts) {
 	].filter((target) => opts[target]);
 	return targets.length > 0 ? targets : void 0;
 }
+/** The kind flags, as one map, so a second one is an error rather than a silent precedence rule. */
+const KIND_FLAGS = {
+	path: "path",
+	npm: "npm",
+	github: "github",
+	url: "url",
+	fromMarketplace: "marketplace"
+};
+function kindFromOptions(opts) {
+	const named = Object.keys(KIND_FLAGS).filter((flag) => opts[flag]);
+	if (named.length > 1) throw new Error(`error: pass one source kind, not ${named.length}`);
+	return named.length === 1 ? KIND_FLAGS[named[0]] : void 0;
+}
+function metadataFromOptions(opts) {
+	const metadata = {};
+	for (const field of ENTRY_METADATA_FIELDS) {
+		const value = opts[field];
+		if (typeof value !== "string") continue;
+		metadata[field] = field === "keywords" ? value.split(",").map((keyword) => keyword.trim()).filter((keyword) => keyword !== "") : value;
+	}
+	return metadata;
+}
+function addCommand() {
+	return new Command("add").description("List a plugin that lives elsewhere in this repository's marketplace catalogs").argument("<spec>", "What to list: ./path, owner/repo, a git URL, an npm package (npm:<pkg>), or <plugin>@<marketplace>").option("--claude", "Write the Claude marketplace catalog").option("--codex", "Write the Codex marketplace catalog").option("--copilot", "Write the Copilot marketplace catalog").option("--cursor", "Write the Cursor marketplace catalog").option("--path", "Read the spec as a repository-relative path").option("--npm", "Read the spec as an npm package name").option("--github", "Read the spec as an owner/repo GitHub repository").option("--url", "Read the spec as a git or https URL").option("--from-marketplace", "Read the spec as <plugin>@<marketplace>").option("--from <dir>", "Directory holding the marketplace to copy an entry from").option("--subdir <path>", "The plugin's directory inside the repository, for a monorepo").option("--ref <ref>", "Branch or tag to pin a git source to").option("--sha <sha>", "Commit to pin a git source to (full 40-character hash)").option("--name <name>", "Entry name, when it differs from the one the spec implies").option("--description <text>", "Entry description").option("--version <version>", "Entry version").option("--homepage <url>", "Entry homepage").option("--repository <url>", "Entry repository URL").option("--license <id>", "Entry license").option("--keywords <list>", "Entry keywords, comma-separated").option("--marketplace-name <name>", "Name for the catalog, when this command has to create one").option("--owner <name>", "Owner for the catalog, when this command has to create one").option("--dry-run", "Preview the entry without writing it").option("--force", "Replace an entry of this name that is already listed differently").option("--format <format>", "Output format: toon or json (default: toon)").addOption(ROOT_OPTION).addHelpText("after", "\nExamples:\n  $ universal-plugin marketplace add npm:repobuddy\n  $ universal-plugin marketplace add cyberuni/universal-plugin\n  $ universal-plugin marketplace add cyberuni/cyber-sdd --subdir plugins/aced\n  $ universal-plugin marketplace add repobuddy@cyberplace --dry-run\n").action((spec, opts) => {
+		try {
+			if (opts.format !== void 0 && opts.format !== "toon" && opts.format !== "json") throw new Error("error: --format must be \"toon\" or \"json\"");
+			const results = addToMarketplace(resolveRoot(opts.root), spec, {
+				targets: targetsFromOptions(opts),
+				kind: kindFromOptions(opts),
+				name: opts.name,
+				from: opts.from,
+				subdir: opts.subdir,
+				ref: opts.ref,
+				sha: opts.sha,
+				metadata: metadataFromOptions(opts),
+				marketplaceName: opts.marketplaceName,
+				owner: opts.owner,
+				dryRun: opts.dryRun,
+				force: opts.force
+			});
+			output(results, {
+				targets: results.map((row) => ({
+					target: row.target,
+					status: row.status,
+					entry: row.entry,
+					source: row.source,
+					path: row.path,
+					reason: row.reason ?? "-"
+				})),
+				summary: `${results.filter((row) => row.status === "skipped").length} skipped of ${results.length}`
+			});
+			for (const row of results.filter((row) => row.status === "skipped")) process.stderr.write(`skipped ${row.target}: ${row.reason}\n`);
+			process.stderr.write(`${opts.dryRun ? "Planned" : "Wrote"} 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`);
+			process.exitCode = 1;
+		}
+	});
+}
 function initCommand() {
 	return new Command("init").description("Generate local marketplace metadata without publishing or provisioning").option("--claude", "Generate the Claude marketplace catalog").option("--codex", "Generate the Codex marketplace catalog").option("--copilot", "Generate the Copilot marketplace catalog").option("--cursor", "Generate the Cursor marketplace catalog").option("--plugin-scan-dir <dir>", "Directory beneath --root to scan for root-level plugin.json files (repeatable)", (value, previous = []) => [...previous, value]).option("--name <name>", "Override the marketplace name").option("--owner <name>", "Override the marketplace owner").option("--dry-run", "Preview artifacts without writing them").option("--force", "Replace differing artifacts for selected targets").option("--format <format>", "Output format: toon or json (default: toon)").addOption(new Option("--json").hideHelp()).addOption(ROOT_OPTION).addHelpText("after", "\nExample:\n  $ universal-plugin marketplace init --root .\n").action((opts) => {
 		try {
@@ -8235,7 +8788,7 @@ function validateCommand$1() {
 	});
 }
 function marketplaceCommand() {
-	return new Command("marketplace").description("Generate repository-local marketplace metadata").addCommand(initCommand()).addCommand(validateCommand$1());
+	return new Command("marketplace").description("Generate repository-local marketplace metadata").addCommand(addCommand()).addCommand(initCommand()).addCommand(validateCommand$1());
 }
 //#endregion
 //#region src/prepare/fs.ts
@@ -8490,7 +9043,7 @@ const realSyncVersionFs = realJsonIo;
 //#endregion
 //#region src/publish/sync-version.ts
 /** The changesets-driven direction of the version flow: the number is decided by
-*  `changeset version` in `<packagePath>/package.json`, and this copies it into the canonical
+*  `changeset version` in `<packagePath>/package.json` (the plugin root's when none is declared), and this copies it into the canonical
 *  manifest. `plugin version` is the other direction — the number decided here, flowing out to
 *  `package.json`. The two differ **only** in where the version comes from, so they share
 *  `applyVersionPlan` and cannot drift; `package.json` is the source here, never rewritten. */
@@ -8498,11 +9051,11 @@ function syncVersion(root, syncFs) {
 	const manifestPath = path.join(root, "plugin.json");
 	if (!syncFs.exists(manifestPath)) throw new Error(`No plugin.json found at ${root}`);
 	const agentsConfigPath = path.join(root, ".agents", "universal-plugin.json");
-	const packagePath = getPackagePath(syncFs.exists(agentsConfigPath) ? JSON.parse(syncFs.read(agentsConfigPath)) : {});
-	if (packagePath === null) throw new Error("packagePath is required in .agents/universal-plugin.json");
+	const declared = getPackagePath(syncFs.exists(agentsConfigPath) ? JSON.parse(syncFs.read(agentsConfigPath)) : {});
+	const packagePath = declared ?? ".";
 	const manifest = JSON.parse(syncFs.read(manifestPath));
 	const pkgJsonPath = path.join(root, packagePath, "package.json");
-	if (!syncFs.exists(pkgJsonPath)) throw new Error(`No package.json found at ${packagePath}`);
+	if (!syncFs.exists(pkgJsonPath)) throw new Error(declared === null ? "No package.json to sync from: packagePath is not set in .agents/universal-plugin.json and the plugin root has no package.json" : `No package.json found at ${packagePath}`);
 	const version = JSON.parse(syncFs.read(pkgJsonPath))["version"];
 	if (!version || typeof version !== "string") throw new Error(`No version found in ${packagePath}/package.json`);
 	const current = manifest["version"];
@@ -8529,7 +9082,7 @@ function syncVersion(root, syncFs) {
 //#region src/publish/cli.ts
 function publishCommand() {
 	const cmd = new Command("publish").description("Prepare plugin for publishing").helpCommand(false);
-	cmd.command("sync-version").description("Sync version from packagePath/package.json into plugin.json").addOption(ROOT_OPTION).action((opts) => {
+	cmd.command("sync-version").description("Sync version from packagePath/package.json (default: the plugin root) into plugin.json").addOption(ROOT_OPTION).action((opts) => {
 		try {
 			const result = syncVersion(resolveRoot(opts.root), realSyncVersionFs);
 			output(result, {