universal-plugin 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-plugin",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Universal AI agent plugin build tool",
   "keywords": [
     "agent-plugin",
@@ -39,6 +39,7 @@
     "agents"
   ],
   "dependencies": {
+    "@repobuddy/upx": "^0.1.0",
     "@toon-format/toon": "^4.1.1",
     "commander": "^14.0.3",
     "semver": "^7.8.1"
@@ -62,12 +63,13 @@
   },
   "scripts": {
     "build": "tsdown",
+    "check:governances": "tsx src/cli.ts plugin build --check --root .",
     "dev": "tsx src/cli.ts",
     "knip": "knip",
     "lint": "biome check .",
     "test": "pnpm build && vitest run src",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "verify": "pnpm typecheck && pnpm lint && pnpm test"
+    "verify": "pnpm typecheck && pnpm lint && pnpm test && pnpm check:governances"
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "universal-plugin",
-	"version": "0.7.0",
+	"version": "0.9.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/readme.md

@@ -120,21 +120,28 @@ npx universal-plugin self-update <version>            # update the version pin i
 
 ## upx, the fast package runner
 
-`npm i -g universal-plugin` puts a second bin, `upx`, on PATH.
+`upx` now ships as its own package, [`@repobuddy/upx`](https://www.npmjs.com/package/@repobuddy/upx).
 
 `upx <pkg>@^<major>` looks for an already-installed version satisfying the range, checking local
 `node_modules` first and then global. It spawns that binary directly, skipping the resolve step that
-costs `npx` roughly 1s per call. When nothing installed matches, it falls back to `npx`.
+costs `npx` a registry round-trip on every call. When nothing installed matches, it falls back to
+`npx`. See [its measurements](https://repobuddy.github.io/upx/concepts/measurements/) for what that
+is worth on current npm.
 
 ```sh
-npm i -g universal-plugin
+npm i -g @repobuddy/upx
 upx cyber-skills@^2 audit validate
 ```
 
 Use a caret range on the major rather than an exact pin, so one global install serves every caller.
+`plugin bundle --runner upx` emits references in this form.
 
-`upx` only works once `universal-plugin` is installed globally. `npx` ships with npm, so keep `npx`
-as the default anywhere you cannot guarantee that install.
+`upx` only works once it is installed globally. `npx` ships with npm, so keep `npx` as the default
+anywhere you cannot guarantee that install.
+
+> **Deprecated:** `universal-plugin` still installs a `upx` bin that re-exports `@repobuddy/upx`, so
+> existing global installs keep working. It will be removed in the next major — install
+> `@repobuddy/upx` directly.
 
 ## Related
 

package/schema/extension.schema.json

@@ -1,8 +1,8 @@
 {
 	"$schema": "https://json-schema.org/draft/2020-12/schema",
 	"title": "universal-plugin extension namespace",
-	"description": "universal-plugin build configuration: the build-target list, per-harness manifest overrides, the plugins depended on, the npm package tracked, and the canonical component input paths the build derives per harness. This is the body of extensions[\"org.cyberuni.universal-plugin\"] in an Agent Plugins Specification v1.0.0 manifest, and nothing else — apply it to the namespace object, not to the manifest.",
-	"$comment": "The manifest envelope around this object belongs to the Agent Plugins Specification and is validated by https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. That specification assigns no semantics to a namespace object's contents (§8), so this schema supplies them for the one namespace universal-plugin owns. It carries no $id: the fields it describes version with the universal-plugin package that ships it.",
+	"description": "universal-plugin build configuration: the build-target list, per-harness manifest overrides, the plugins depended on, and the canonical component input paths the build derives per harness. This is the body of extensions[\"org.cyberuni.universal-plugin\"] in an Agent Plugins Specification v1.0.0 manifest, and nothing else — apply it to the namespace object, not to the manifest.",
+	"$comment": "The manifest envelope around this object belongs to the Agent Plugins Specification and is validated by https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. That specification assigns no semantics to a namespace object's contents (§8), so this schema supplies them for the one namespace universal-plugin owns. packagePath is not here: it is repository release config, read from .agents/universal-plugin.json beside plugin.json and resolved from the plugin root (ADR-0010 §2). It carries no $id: the fields it describes version with the universal-plugin package that ships it.",
 	"type": "object",
 	"additionalProperties": false,
 	"properties": {
@@ -22,10 +22,6 @@
 			"$ref": "#/$defs/dependencies",
 			"description": "Plugins this plugin needs. Delivered to the harnesses that read a dependency and dropped with a build warning for the rest — only Claude Code reads one (ADR-0013)."
 		},
-		"packagePath": {
-			"type": "string",
-			"description": "Relative path (from repo root) to the npm package folder whose version this plugin tracks."
-		},
 		"skills": {
 			"$ref": "#/$defs/pathValue",
 			"description": "Skill directories. Default: ./skills/. Each subdirectory must contain SKILL.md."

package/skills/adopt-upx/README.md

@@ -6,13 +6,13 @@ Rewrites `npx <pkg>@<version>` references in `SKILL.md` files to a caret range o
 
 ## When to use
 
-When you want a project's skills to call CLIs via `upx` instead of `npx`, for the ~10× speed win
-on repeated invocations (local-first resolution vs. `npx`'s ~1s registry+spawn cost per call, even
+When you want a project's skills to call CLIs via `upx` instead of `npx`, for the speed win
+on repeated invocations (local-first resolution vs. `npx`'s registry+spawn cost per call, even
 cached).
 
 ## What it does
 
-1. Confirms `upx` is installed (`npm i -g universal-plugin`) and on PATH.
+1. Confirms `upx` is installed (`npm i -g @repobuddy/upx`) and on PATH.
 2. Rewrites `npx <pkg>@<concrete-semver>` → `upx <pkg>@^<major>` (or `^0.<minor>` for a 0.x pin)
    across a chosen scope:
    - one specific skill (a path)
@@ -29,7 +29,7 @@ cached).
 ## Tradeoff
 
 A rewritten skill depends on `upx` being on PATH. `npx` ships with every npm install; `upx` only
-exists after `npm i -g universal-plugin`. This is an opt-in migration, not a safe default.
+exists after `npm i -g @repobuddy/upx`. This is an opt-in migration, not a safe default.
 
 ## Install
 

package/skills/adopt-upx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adopt-upx
-description: Use this skill when the user wants to make their skills use upx — the fast local-first package runner shipped by universal-plugin. Trigger on phrases like "make my skills use upx", "adopt the upx runner", "speed up npx calls", "switch to upx", or "rewrite npx pins to upx". Rewrites `npx <pkg>@<version>` references to a caret range on `upx` (`^<major>`, or `^0.<minor>` for a 0.x pin) across one skill, a named set, or every skill in the project.
+description: Use this skill when the user wants to make their skills use upx — the fast local-first package runner shipped as @repobuddy/upx. Trigger on phrases like "make my skills use upx", "adopt the upx runner", "speed up npx calls", "switch to upx", or "rewrite npx pins to upx". Rewrites `npx <pkg>@<version>` references to a caret range on `upx` (`^<major>`, or `^0.<minor>` for a 0.x pin) across one skill, a named set, or every skill in the project.
 ---
 
 # Adopt upx
@@ -11,7 +11,7 @@ fast local-first runner shipped by `universal-plugin` (see the package
 
 ## When to use
 
-The user wants their project's skills to shell out via `upx` instead of `npx`, for the ~10× speed
+The user wants their project's skills to shell out via `upx` instead of `npx`, for the speed
 win on repeated calls. This is an opt-in migration, not a default — see Tradeoff below before
 running it broadly.
 
@@ -20,7 +20,7 @@ running it broadly.
 Install the runner:
 
 ```bash
-npm i -g universal-plugin
+npm i -g @repobuddy/upx
 ```
 
 This puts the `upx` bin on PATH. Verify:
@@ -94,7 +94,7 @@ a no-op (there's no `npx` left to match), so it's safe to run again after adding
 
 A skill rewritten to `upx` now depends on the `upx` bin being on that environment's PATH.
 `npx` always ships with npm — every Node environment has it. `upx` does not — it only exists after
-`npm i -g universal-plugin`. So this is a deliberate opt-in for environments where
+`npm i -g @repobuddy/upx`. So this is a deliberate opt-in for environments where
 `universal-plugin` is installed globally, not a safe-by-default swap.
 
 Mitigating factor: `upx` itself falls back to plain `npx` on a miss (no local/global install

package/skills/{doctor → doctor-universal-plugin}/README.md

@@ -1,4 +1,4 @@
-# doctor skill
+# doctor-universal-plugin skill
 
 Diagnose a universal agent plugin: what the canonical `plugin.json` declares, and whether what is on
 disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
@@ -16,7 +16,7 @@ The skill supplies the judgment around it: which finding matters, and which skil
 
 ## It never repairs
 
-Every finding names the skill that fixes it — `init` for anything that rewrites the manifest,
+Every finding names the skill that fixes it — `init-universal-plugin` for anything that rewrites the manifest,
 `version` for the release number, `remove-plugin` for artifacts. A repair can overwrite a manifest
 the user maintains, and that judgment belongs to the skill that owns the write.
 
@@ -29,9 +29,8 @@ The checks are deterministic: same tree, same findings. The one check that is no
 definitive staleness test — rebuild on a clean tree and read the diff — because it writes. The skill
 reports that one as a repair for the user to run.
 
-Manifest validation is chartered as a CLI capability (`plugin validate`, specified but not yet
-shipped). This script stays a thin composition on purpose, so it folds into that command rather than
-competing with it.
+Manifest validation is a CLI capability (`plugin validate`). This script stays a thin composition
+on purpose, so it folds into that command rather than competing with it.
 
 ## Boundaries
 

package/skills/{doctor → doctor-universal-plugin}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: doctor
+name: doctor-universal-plugin
 description: Use this skill to diagnose a universal agent plugin — when `plugin build` reports "built 0" or "nothing to build", when it warns "No vendors declared in harnesses", when a repository still carries `.plugin/plugin.json` or a top-level `vendorExtensions` block after upgrading universal-plugin across a major, when a released version never reached the vendor manifests, when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, or when checking whether what the canonical plugin.json declares still matches what is on disk for Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "is my plugin set up right", "why isn't my plugin loading", "the build says built 0", "why did nothing get built", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
 ---
 
@@ -21,6 +21,9 @@ node scripts/doctor.mjs
 
 Resolve that path against this skill's own directory. It runs the CLI that shipped beside it against
 the current working directory, so nothing is downloaded; add `--root <path>` to diagnose elsewhere.
+Add `--marketplace-root <path>` (repeatable) to also check a **separately-cloned** shared marketplace
+repository (e.g. a local clone of `cyberuni/marketplace`) — see
+[Catalogs are checked at the repository root](#catalogs-are-checked-at-the-repository-root).
 It never prompts and never writes, so it is safe to run unattended.
 
 Stdout is one JSON object — that is the contract to read, not the CLI's own terminal output:
@@ -67,24 +70,27 @@ Each `code` below is what the script emits.
 
 | Finding | What it means | Repair |
 | --- | --- | --- |
-| `no-manifest` | no root `plugin.json` — this is not a plugin yet | `/universal-plugin:init` |
-| `legacy-manifest` | root `plugin.json` with neither `$schema` nor `extensions` — a single-vendor manifest on the canonical path | `/universal-plugin:init`, adopt route |
-| `vendor-only` | a vendor manifest with no canonical manifest above it | `/universal-plugin:init`, adopt route |
+| `no-manifest` | no root `plugin.json` — this is not a plugin yet | `/universal-plugin:init-universal-plugin` |
+| `legacy-manifest` | root `plugin.json` with neither `$schema` nor `extensions` — a single-vendor manifest on the canonical path | `/universal-plugin:init-universal-plugin`, adopt route |
+| `vendor-only` | a vendor manifest with no canonical manifest above it | `/universal-plugin:init-universal-plugin`, adopt route |
 | `unbuilt` | a declared vendor whose output path holds no file — that runtime sees no plugin | `universal-plugin plugin build` |
 | `stale` | a derived manifest older than `plugin.json` | `universal-plugin plugin build` |
 | `hand-edited` | a derived manifest that `build` would rewrite — the edit is already lost, it just has not been overwritten yet | move the field to the canonical manifest or to `harnesses.<vendor>`, then rebuild |
 | `unknown-vendor` | a `vendors` entry no build target matches; reported as `skipped` plus a warning | fix the id in `plugin.json` |
-| `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init`, update route — move them to a vendor that has a derived manifest, or drop them |
+| `undeliverable-override` | `harnesses["copilot-cli"]` sets fields that reach nothing | `/universal-plugin:init-universal-plugin`, update route — move them to a vendor that has a derived manifest, or drop them |
 | `codex-fields-missing` | Codex is targeted without `version` or `description`; the build fails and writes **nothing at all**, including for the other vendors | add both to the canonical top level |
 | `version-drift` | the `packagePath` `package.json` and the canonical manifest carry different versions | `/universal-plugin:version` |
 | `unreleased-content` | shipped content was committed after the commit that set the current version — a consumer keyed on that version never re-extracts it | `/universal-plugin:version` |
 | `copilot-root-components` | agents, commands, rules, hooks, or LSP servers sit at the plugin root with no copy under `com.github.copilot/` — Copilot CLI reads them only from there in spec mode, so it loads none of them, silently | `universal-plugin plugin build` |
 | `stale-github-plugin` | a leftover `.github/plugin/plugin.json` from an older build — shadowed by root and no longer generated | `/universal-plugin:remove-plugin` |
 | `shadowing-manifest` | a `.plugin/plugin.json` exists — it outranks root in Copilot CLI's search order and silently shadows the canonical manifest | `/universal-plugin:remove-plugin` |
-| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. On a repository still on the pre-0.6 layout the build stops rather than reporting an empty result, and the detail says so — read it beside `legacy-manifest` and `shadowing-manifest`, which name the signals | `/universal-plugin:init`, adopt route on the pre-0.6 layout, else update route |
+| `no-vendors` | no vendor is declared, so the build writes nothing and no runtime reads the plugin. On a repository still on the pre-0.6 layout the build stops rather than reporting an empty result, and the detail says so — read it beside `legacy-manifest` and `shadowing-manifest`, which name the signals | `/universal-plugin:init-universal-plugin`, adopt route on the pre-0.6 layout, else update route |
 | `package-path-missing` | `packagePath` names a directory with no readable `package.json` | fix `packagePath`, or create the package |
+| `package-path-unknown` | the CLI could not report `packagePath` (a version too old to read it), so `version-drift` and `unreleased-content` were skipped rather than guessed | upgrade universal-plugin |
+| `misplaced-package-path` | `plugin.json` declares `packagePath` under `extensions["org.cyberuni.universal-plugin"]`, where the CLI never reads it — the plugin is silently treated as not shipping to npm | move it to `.agents/universal-plugin.json`, relative to the plugin root |
 | `unparsable-manifest` | root `plugin.json` is not valid JSON | fix the syntax error |
-| `invalid-catalog` | a marketplace catalog at the repository root is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` |
+| `invalid-catalog` | a marketplace catalog — at the repository root, or at a `--marketplace-root` clone — is not a shape its runtime loads — it is found, read, and refused at install time, in the user's terminal | `/universal-plugin:marketplace` |
+| `marketplace-root-missing` | a `--marketplace-root` path does not exist, so it could not be checked at all | clone the marketplace repository, or fix the path |
 
 ## Catalogs are checked at the repository root
 
@@ -96,6 +102,20 @@ The detail names the key at fault, so hand it to `/universal-plugin:marketplace`
 entry's fields are derived from the plugin's `plugin.json`, and the catalog's own `name` and `owner`
 are authored in the catalog — which half is at fault decides where the repair goes.
 
+A **shared** marketplace repository (e.g. `cyberuni/marketplace`) is a repository of its own — a bad
+entry that reached it by another path (a hand-edited entry, a PR from a different tool, a curator
+edit) is invisible to a `doctor` run inside any plugin's own repo, because that run never sees the
+shared repository at all. Clone it separately and name the clone explicitly:
+
+```bash
+node scripts/doctor.mjs --marketplace-root ../marketplace
+```
+
+Pass `--marketplace-root` once per clone to check more than one. Each invalid entry it finds is still
+reported as `invalid-catalog`, with the clone's path in the detail so it reads apart from the plugin
+repo's own catalogs; a path that does not exist is `marketplace-root-missing` rather than a silent
+skip.
+
 ## Checking staleness properly
 
 The `stale` finding is an mtime comparison, which catches the common case and nothing more. It cannot
@@ -116,8 +136,8 @@ user can run, or ask before running it yourself.
 
 ## Version drift
 
-Two files carry an authored version: the canonical `plugin.json`, and the `package.json` at
-`extensions["org.cyberuni.universal-plugin"].packagePath` when one is declared. The script compares
+Two files carry an authored version: the canonical `plugin.json`, and the `package.json` at the
+`packagePath` the CLI reports (`config get --key packagePath`), resolved from the plugin root. The script compares
 them and emits `version-drift`.
 
 They diverge when someone ran `npm version`, or when changesets released a number that never flowed
@@ -158,7 +178,7 @@ is meant to ship — content that is still being worked on is not a finding to a
 
 | Task | Skill |
 |------|-------|
-| Create, adopt, or change what the plugin declares | `init` |
+| Create, adopt, or change what the plugin declares | `init-universal-plugin` |
 | Move the plugin's version | `version` |
 | Remove derived manifests, or the plugin itself | `remove-plugin` |
 | Generate the repository's own marketplace catalogs | `marketplace` |

package/skills/{doctor → doctor-universal-plugin}/scripts/doctor.mjs

@@ -15,6 +15,9 @@ const argv = process.argv.slice(2)
 const verbose = argv.includes('--verbose')
 const rootFlag = argv.indexOf('--root')
 const root = path.resolve(rootFlag === -1 ? process.cwd() : (argv[rootFlag + 1] ?? process.cwd()))
+// A shared marketplace repository (e.g. cyberuni/marketplace) is cloned separately from any plugin
+// repo, so it is named explicitly rather than discovered — repeatable, one clone per flag.
+const marketplaceRoots = argv.flatMap((arg, i) => (arg === '--marketplace-root' ? [argv[i + 1]] : [])).filter(Boolean)
 
 const findings = []
 const add = (code, severity, detail, repair) => findings.push({ code, severity, detail, repair })
@@ -42,27 +45,56 @@ if (manifest === null) {
 			'vendor-only',
 			'high',
 			`vendor manifests with no canonical manifest: ${orphans.join(', ')}`,
-			'/universal-plugin:init, adopt route',
+			'/universal-plugin:init-universal-plugin, adopt route',
 		)
 	} else {
-		add('no-manifest', 'high', 'no root plugin.json — this is not a plugin yet', '/universal-plugin:init')
+		add(
+			'no-manifest',
+			'high',
+			'no root plugin.json — this is not a plugin yet',
+			'/universal-plugin:init-universal-plugin',
+		)
 	}
 	report({ vendors: [] })
 }
 
 const ext = manifest.extensions?.[UP_NAMESPACE] ?? null
 
-// `packagePath` is the CLI's own config, and the CLI reads it from `.agents/universal-plugin.json`
-// (src/version/fs.ts). It is read here from the same file, so a plugin the CLI treats as npm-shipping
-// is one this script treats the same way. The manifest extension is accepted as a fallback for a
-// repository that put it there.
+// The shipped CLI, preferring the one this skill ships with. Every question the CLI can answer is asked
+// of it rather than re-derived here, so this script cannot drift from the commands it diagnoses.
+const bin = path.join(packageRoot, 'bin', 'universal-plugin.mjs')
+const runCli = (...args) =>
+	fs.existsSync(bin)
+		? spawnSync(process.execPath, [bin, ...args], { encoding: 'utf8' })
+		: spawnSync('npx', ['universal-plugin', ...args], { encoding: 'utf8' })
+
+// `packagePath` is the CLI's own config. It is asked of the CLI (`config get --key packagePath`), the
+// same reader `plugin version` and `publish sync-version` use, so a plugin the CLI treats as
+// npm-shipping is one this script treats the same way (issue #79). `undefined` means the CLI could not
+// answer — too old to read the key — and every check that depends on it is skipped rather than guessed.
 const packagePath = readPackagePath()
+if (packagePath === undefined) {
+	add(
+		'package-path-unknown',
+		'low',
+		'the CLI could not report packagePath, so version-drift and unreleased-content were not checked',
+		'upgrade universal-plugin',
+	)
+}
+if (ext !== null && Object.hasOwn(ext, 'packagePath')) {
+	add(
+		'misplaced-package-path',
+		'high',
+		`plugin.json declares extensions["${UP_NAMESPACE}"].packagePath, which the CLI never reads${packagePath === null ? ' — this plugin is treated as not shipping to npm' : ''}`,
+		'move packagePath to .agents/universal-plugin.json, relative to the plugin root',
+	)
+}
 if (!manifest.$schema?.includes('agent-plugins.org') || ext === null) {
 	add(
 		'legacy-manifest',
 		'high',
 		'root plugin.json carries no $schema on agent-plugins.org or no extensions block',
-		'/universal-plugin:init, adopt route',
+		'/universal-plugin:init-universal-plugin, adopt route',
 	)
 }
 
@@ -136,14 +168,7 @@ if (declaredTargets.includes('copilot-cli')) {
 }
 
 // Ask the shipped CLI what it would write, without writing it.
-const bin = path.join(packageRoot, 'bin', 'universal-plugin.mjs')
-const cli = fs.existsSync(bin)
-	? spawnSync(process.execPath, [bin, 'plugin', 'build', '--dry-run', '--format', 'json', '--root', root], {
-			encoding: 'utf8',
-		})
-	: spawnSync('npx', ['universal-plugin', 'plugin', 'build', '--dry-run', '--format', 'json', '--root', root], {
-			encoding: 'utf8',
-		})
+const cli = runCli('plugin', 'build', '--dry-run', '--format', 'json', '--root', root)
 
 const vendors = []
 const build = readJson_stdout(cli.stdout)
@@ -166,7 +191,7 @@ if (build === null) {
 			'no-vendors',
 			'medium',
 			'no vendor is declared — the project is on the pre-0.6 layout, so the build derives nothing and no runtime reads this plugin',
-			'/universal-plugin:init, adopt route',
+			'/universal-plugin:init-universal-plugin, adopt route',
 		)
 	} else {
 		add(
@@ -199,13 +224,13 @@ if (build === null) {
 	}
 	for (const warning of build.warnings ?? []) {
 		if (/not delivered/.test(warning)) {
-			add('undeliverable-override', 'medium', warning, '/universal-plugin:init, update route')
+			add('undeliverable-override', 'medium', warning, '/universal-plugin:init-universal-plugin, update route')
 		} else if (/No vendors declared/.test(warning)) {
 			add(
 				'no-vendors',
 				'medium',
 				'no vendor is declared — the build writes nothing, so no runtime reads this plugin',
-				'/universal-plugin:init, update route',
+				'/universal-plugin:init-universal-plugin, update route',
 			)
 		} else if (/^Unknown vendor/.test(warning)) {
 			add('unknown-vendor', 'medium', warning, 'fix the vendor id in plugin.json')
@@ -216,7 +241,7 @@ if (build === null) {
 }
 
 // Version drift between the two authored numbers.
-if (packagePath !== null) {
+if (typeof packagePath === 'string') {
 	const pkgPath = path.join(root, packagePath, 'package.json')
 	const pkg = readJson(pkgPath)
 	if (pkg === null) {
@@ -264,31 +289,45 @@ if (manifest.version !== undefined && packagePath === null) {
 // The marketplace catalogs a user installs from. They sit at the *repository* root, above a plugin in
 // a monorepo, and each is read by its runtime at install time — a catalog whose shape that runtime
 // refuses fails in the user's terminal, not here. The shipped CLI owns the rules; this only asks.
-for (const row of invalidCatalogs()) {
+// A shared marketplace repository (--marketplace-root) is a separate clone this plugin's repo root
+// cannot see, so it is checked the same way but reported with the clone's path attached.
+const missingMarketplaceRoots = marketplaceRoots.filter((r) => !fs.existsSync(path.resolve(r)))
+for (const r of missingMarketplaceRoots) {
+	add(
+		'marketplace-root-missing',
+		'high',
+		`--marketplace-root ${r} does not exist`,
+		'clone the marketplace repository, or fix the path',
+	)
+}
+const existingMarketplaceRoots = marketplaceRoots.filter((r) => fs.existsSync(path.resolve(r)))
+
+for (const row of invalidCatalogs(existingMarketplaceRoots)) {
+	const label = row.own ? row.path : `${row.catalogRoot}/${row.path}`
 	add(
 		'invalid-catalog',
 		'high',
-		`${row.path} is not a shape its runtime loads: ${row.issues.map((issue) => `${issue.path} ${issue.message}`).join('; ')}`,
+		`${label} is not a shape its runtime loads: ${row.issues.map((issue) => `${issue.path} ${issue.message}`).join('; ')}`,
 		'/universal-plugin:marketplace',
 	)
 }
 
 report({ vendors })
 
-/** Every catalog the repository carries that its runtime would refuse. Empty when there is nothing to
- *  read, when the CLI is too old to answer, or when every catalog is fine — a missing catalog is not a
- *  fault, and this reports no opinion on which ones a repository ought to carry. */
-function invalidCatalogs() {
+/** Every catalog the repository — and any explicitly named marketplace clone — carries that its
+ *  runtime would refuse. Empty when there is nothing to read, when the CLI is too old to answer, or
+ *  when every catalog is fine — a missing catalog is not a fault, and this reports no opinion on
+ *  which ones a repository ought to carry. */
+function invalidCatalogs(extraRoots) {
 	const catalogRoot = git('rev-parse', '--show-toplevel') ?? root
-	const result = fs.existsSync(bin)
-		? spawnSync(process.execPath, [bin, 'marketplace', 'validate', '--format', 'json', '--root', catalogRoot], {
-				encoding: 'utf8',
-			})
-		: spawnSync('npx', ['universal-plugin', 'marketplace', 'validate', '--format', 'json', '--root', catalogRoot], {
-				encoding: 'utf8',
-			})
-	const rows = readJson_stdout(result.stdout)
-	return Array.isArray(rows) ? rows.filter((row) => row.status === 'invalid') : []
+	const targets = [{ catalogRoot, own: true }, ...extraRoots.map((r) => ({ catalogRoot: path.resolve(r), own: false }))]
+	return targets.flatMap(({ catalogRoot, own }) => {
+		const result = runCli('marketplace', 'validate', '--format', 'json', '--root', catalogRoot)
+		const rows = readJson_stdout(result.stdout)
+		return Array.isArray(rows)
+			? rows.filter((row) => row.status === 'invalid').map((row) => ({ ...row, catalogRoot, own }))
+			: []
+	})
 }
 
 /** Runs git inside `root`, returning its stdout or `null` — a non-zero status, a missing git, and a
@@ -355,9 +394,16 @@ function report({ vendors }) {
 	process.exit(0)
 }
 
-/** Where the npm package that ships this plugin lives, or `null` when the plugin ships to no
- *  package. `null` is the author-picks release model of ADR-0010 §2. */
+/** Where the npm package that ships this plugin lives, relative to the plugin root, as the CLI reads
+ *  it; `null` when the plugin ships to no package (the author-picks release model of ADR-0010 §2);
+ *  `undefined` when the CLI could not answer. */
 function readPackagePath() {
-	const declared = readJson(path.join(root, '.agents', 'universal-plugin.json'))?.packagePath ?? ext?.packagePath
-	return typeof declared === 'string' && declared.length > 0 ? declared : null
+	const result = runCli('config', 'get', '--key', 'packagePath', '--format', 'json', '--root', root)
+	if (result.status !== 0) return undefined
+	try {
+		const declared = JSON.parse(result.stdout)
+		return typeof declared === 'string' || declared === null ? declared : undefined
+	} catch {
+		return undefined
+	}
 }

package/skills/{init → init-universal-plugin}/README.md

@@ -1,4 +1,4 @@
-# init skill
+# init-universal-plugin skill
 
 Give a project one canonical `plugin.json` on the [Agent Plugins
 Specification](https://agent-plugins.org), then derive the manifest each runtime expects — Claude

package/skills/{init → init-universal-plugin}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: init
+name: init-universal-plugin
 description: Use this skill to create or change a universal agent plugin — scaffold a new one, adopt an existing vendor-specific plugin or already-shipped skills onto the open Agent Plugins Specification, or add and remove vendors and components on the canonical plugin.json that drives Claude Code, Cursor, Codex, and GitHub Copilot CLI. Trigger on "init a plugin here", "make my Claude Code plugin work in Cursor", "convert this to the open plugin standard", "turn these skills into a plugin", "add Codex support", or "add a hooks component".
 argument-hint: '[--name <name>] [--vendor <id>] [--scaffold] [--npm] [--no-marketplace] [--force]'
 ---
@@ -48,7 +48,7 @@ It is the authoritative source for which component to reach for and which anti-p
 
 ## Arguments
 
-An invocation may carry the CLI's own flags: `/universal-plugin:init --name my-plugin --scaffold --npm`.
+An invocation may carry the CLI's own flags: `/universal-plugin:init-universal-plugin --name my-plugin --scaffold --npm`.
 
 Read them from the invocation itself rather than from a placeholder. Claude Code appends what the
 caller typed as `ARGUMENTS: <value>`, and Codex substitutes nothing at all, so on every runtime the
@@ -161,7 +161,7 @@ and read back any line it printed on stderr — a repository with no author, no
 remote gets no catalog, because every runtime requires an owner. `--no-marketplace` skips the step.
 
 The catalog is named after the repository, `<owner>-<repo>-local`, not after the plugin: it lists
-every plugin the repository develops. Re-running `init` folds the entry back in and leaves the
+every plugin the repository develops. Re-running `init-universal-plugin` folds the entry back in and leaves the
 marketplace name, the owner, and every other entry alone, so it is safe over a catalog someone
 edited. Generating catalogs for a repository that already holds several plugins, and writing the
 README install section, is the `marketplace` skill's job.

package/skills/{init → init-universal-plugin}/references/standard.md

@@ -36,10 +36,14 @@ lives under one namespaced key, `extensions["org.cyberuni.universal-plugin"]`:
 | --- | --- |
 | `vendors` | the build targets. When absent, the `harnesses` keys are the targets |
 | `harnesses` | per-vendor overrides, keyed by vendor id. `{}` opts in with no overrides |
-| `packagePath` | the npm package whose `package.json` carries the same version |
 | component paths (`skills`, `commands`, `agents`, `hooks`, …) | where each component lives |
 | `dependencies` | the plugins this plugin needs. Only Claude Code reads them; see [`vendors/claude-code.md`](./vendors/claude-code.md) |
 
+`packagePath` does not belong here. The npm package whose `package.json` carries the same version is
+named in `.agents/universal-plugin.json` beside `plugin.json`, as a path relative to the plugin root
+(for example `"packagePath": "."`, or `"../../packages/<name>"` in a monorepo). It is release config
+for the repository, not part of the manifest.
+
 `vendors` and `harnesses` are separate on purpose: `vendors` says what to build, `harnesses` says
 what each build gets. A vendor listed in `vendors` with no `harnesses` entry still builds; a
 `harnesses` entry with no `vendors` list builds only while `vendors` is absent.

package/skills/{init → init-universal-plugin}/references/vendors/claude-code.md

@@ -10,7 +10,7 @@ npx universal-plugin plugin build --vendor claude-code
 
 The shared metadata from the canonical top level, plus the component paths, plus whatever
 `extensions["org.cyberuni.universal-plugin"].harnesses["claude-code"]` sets. `$schema`, `extensions`,
-`vendors`, `packagePath`, and `harnesses` are universal-plugin's own orchestration — they never
+`vendors`, and `harnesses` are universal-plugin's own orchestration — they never
 appear in a vendor manifest.
 
 An empty `"claude-code": {}` is the normal case: it opts into the build with no overrides.

package/skills/marketplace/SKILL.md

@@ -195,7 +195,7 @@ a version the plugin does not have.
 
 | Task | Skill |
 |------|-------|
-| Create or change the plugin being listed | `init` |
+| Create or change the plugin being listed | `init-universal-plugin` |
 | Check that the plugin's own manifests are current | `doctor` |
 | Move the version users will install | `version` |
 | Submit to the shared marketplace repository instead | `publish-plugin` |