universal-plugin 0.5.0 → 0.7.0

package/skills/doctor/README.md

@@ -8,7 +8,9 @@ disk still matches it for Claude Code, Cursor, Codex, and GitHub Copilot CLI.
 `scripts/doctor.mjs` composes the shipped CLI's `plugin build --dry-run --format json` with the
 filesystem facts that build cannot see — whether each derived manifest exists, whether it predates
 the canonical manifest, whether a stale or shadowing manifest is lying around, whether the two
-authored version numbers still agree, and whether shipped content has moved since the version did. It emits one JSON object: `vendors`, `findings`, `ok`.
+authored version numbers still agree, whether shipped content has moved since the version did, and
+whether every marketplace catalog at the repository root is a shape its runtime loads. It emits one
+JSON object: `vendors`, `findings`, `ok`.
 
 The skill supplies the judgment around it: which finding matters, and which skill owns its repair.
 

package/skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor
-description: Use this skill to diagnose a universal agent plugin — when a runtime loads none of the plugin's skills, when a vendor manifest is missing or looks out of date after a pull, when a build prints warnings nobody has read, 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", "check the plugin", "are the vendor manifests current", or "what does this plugin declare".
+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".
 ---
 
 # Plugin Doctor
@@ -43,13 +43,20 @@ Read `vendors[].status` literally:
 
 | Status | Means |
 | --- | --- |
-| `built` | the build writes this vendor's manifest |
+| `built` | the build writes this vendor's output. For `copilot-cli` that output is the `com.github.copilot/` component tree, not a manifest |
 | `canonical` | the vendor reads root `plugin.json`; **no file is written, and that is correct** |
 | `skipped` | an unknown vendor id — a typo in `vendors` |
 | `failed` | the write itself failed; the finding names why |
 
-`copilot-cli` reporting `canonical` with `exists: false` is a healthy plugin, not a missing build.
-Never report it as a fault.
+`copilot-cli` reporting `canonical` is a healthy plugin, not a missing build — root `plugin.json`
+serves it, and a plugin declaring no agents, commands, rules, hooks, or LSP servers has nothing else
+to derive. Never report it as a fault.
+
+A plugin that **does** declare those reports `copilot-cli` as `built` at `com.github.copilot/`
+instead. Declaring the canonical `$schema` moves them there: Copilot CLI stops reading them from the
+plugin root entirely, so a root-only layout loads none of them and says nothing
+([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)). That is what
+`copilot-root-components` reports.
 
 If `node` is unavailable, read `scripts/doctor.mjs` and apply the same checks by hand: it composes
 `universal-plugin plugin build --dry-run --format json` with filesystem facts that build cannot see.
@@ -71,11 +78,23 @@ Each `code` below is what the script emits.
 | `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 | `/universal-plugin:init`, 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`, 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 |
 | `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` |
+
+## Catalogs are checked at the repository root
+
+The marketplace catalogs sit above the plugin in a monorepo, so the catalog check runs against the
+repository root rather than `--root`. It reports only a catalog that would be **refused**: a missing
+one is not a fault, and nothing here has an opinion on which catalogs a repository ought to carry.
+
+The detail names the key at fault, so hand it to `/universal-plugin:marketplace` as it stands. An
+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.
 
 ## Checking staleness properly
 
@@ -129,7 +148,9 @@ is meant to ship — content that is still being worked on is not a finding to a
 - **Never repair.** Report the finding and name the skill that owns it.
 - **Never hand-edit a derived manifest to make a finding go away.** The next build overwrites it and
   the finding comes back.
-- Do not report `copilot-cli` writing no file as a fault. It reads the canonical manifest directly.
+- Do not report `copilot-cli` writing no **manifest** as a fault. It reads the canonical manifest
+  directly. Its **components** are a separate question — a `copilot-root-components` finding is a real
+  fault, and `canonical` is only healthy for a plugin that declares none of the moved kinds.
 - Do not treat repo-private agent configuration (`.claude/skills/`, `.agents/skills/`) as part of the
   plugin. Diagnosing a repository's own skill wiring is `buddy-agent-harness:doctor`.
 

package/skills/doctor/scripts/doctor.mjs

@@ -84,6 +84,57 @@ if (fs.existsSync(path.join(root, '.github/plugin/plugin.json'))) {
 	)
 }
 
+// Copilot CLI's spec mode reads its native components ONLY under com.github.copilot/ — declaring the
+// canonical $schema moves them out of the plugin root (ADR-0015). A plugin that ships them at the
+// root and has no namespace copy loads none of them on Copilot CLI, and nothing at runtime says so.
+// Checked from the filesystem rather than from the build result, so it still fires on a repository
+// whose build cannot run.
+const COPILOT_NAMESPACE = 'com.github.copilot'
+const declaredTargets = ext?.vendors ?? Object.keys(ext?.harnesses ?? {})
+if (declaredTargets.includes('copilot-cli')) {
+	const nsDir = path.join(root, COPILOT_NAMESPACE)
+	const declaredPaths = (value, fallback) => {
+		if (value === undefined) return fallback === null ? [] : [fallback]
+		if (typeof value === 'string') return [value]
+		if (Array.isArray(value)) return value.filter((entry) => typeof entry === 'string')
+		if (value && Array.isArray(value.paths)) return value.paths.filter((entry) => typeof entry === 'string')
+		return []
+	}
+	const hasContent = (rel) => {
+		const abs = path.join(root, rel)
+		return fs.existsSync(abs) && fs.statSync(abs).isDirectory() && fs.readdirSync(abs).length > 0
+	}
+	const missing = []
+	// The same defaults the build derives from. Passing null here would make the check fire only for a
+	// manifest that names the path — and the manifest that names none is the common one.
+	for (const [kind, defaultPath] of [
+		['agents', './agents/'],
+		['commands', './commands/'],
+		['rules', './rules/'],
+	]) {
+		const roots = declaredPaths(ext?.[kind], defaultPath)
+		if (roots.some(hasContent) && !hasContent(path.join(COPILOT_NAMESPACE, kind))) missing.push(kind)
+	}
+	// hooks is a single file, declared as a path or inline in the manifest, and carries a default the
+	// manifest need not declare at all.
+	const inlineHooks = ext?.hooks !== null && typeof ext?.hooks === 'object' && 'hooks' in ext.hooks
+	const hookSources = inlineHooks ? [] : declaredPaths(ext?.hooks, './hooks/hooks.json')
+	const hasHooks = inlineHooks || hookSources.some((rel) => fs.existsSync(path.join(root, rel)))
+	if (hasHooks && !fs.existsSync(path.join(nsDir, 'hooks', 'hooks.json'))) missing.push('hooks')
+	const lspSources = declaredPaths(ext?.lspServers, null)
+	if (lspSources.some((rel) => fs.existsSync(path.join(root, rel))) && !fs.existsSync(path.join(nsDir, 'lsp.json'))) {
+		missing.push('lspServers')
+	}
+	if (missing.length > 0) {
+		add(
+			'copilot-root-components',
+			'high',
+			`${missing.join(', ')} sit at the plugin root with no copy under ${COPILOT_NAMESPACE}/ — Copilot CLI reads them only from there once the canonical $schema is declared, so it loads none of them`,
+			'universal-plugin plugin build',
+		)
+	}
+}
+
 // 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)
@@ -106,6 +157,17 @@ if (build === null) {
 			'codex is targeted without version or description — the build writes nothing at all, for any vendor',
 			'add both to the canonical top level',
 		)
+	} else if (findings.some((f) => f.code === 'legacy-manifest' || f.code === 'shadowing-manifest')) {
+		// The build stops rather than reporting a definitive empty state when the layout explains the
+		// empty result (issue #61). That is still the no-vendors diagnosis — the layout findings above
+		// name the signals, and this names the consequence. Keyed on those findings rather than on the
+		// build's message, so the two never have to agree on wording.
+		add(
+			'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',
+		)
 	} else {
 		add(
 			'build-failed',
@@ -199,8 +261,36 @@ 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()) {
+	add(
+		'invalid-catalog',
+		'high',
+		`${row.path} 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() {
+	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') : []
+}
+
 /** Runs git inside `root`, returning its stdout or `null` — a non-zero status, a missing git, and a
  *  directory outside any repository are all the same answer here: no history to read. */
 function git(...args) {

package/skills/init/README.md

@@ -53,5 +53,8 @@ touch CI, repository settings, or unrelated project files.
 ## References
 
 - [Spec](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md)
-- [Schema](https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json)
+- [Manifest schema (Agent Plugins Specification v1.0.0)](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)
+- [Extension schema](https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/schema/extension.schema.json)
+  — the body of `extensions["org.cyberuni.universal-plugin"]`, also shipped in the package at
+  `schema/extension.schema.json`
 - [Examples](https://github.com/cyberuni/universal-plugin/tree/main/examples)

package/skills/init/SKILL.md

@@ -10,10 +10,18 @@ Give a project one canonical plugin manifest — a root `plugin.json` on the Age
 Specification — and derive from it the manifest each runtime expects.
 
 Most of the manifest is shared. The divergence is small and asymmetric: Copilot CLI reads the
-canonical `plugin.json` directly and gets no derived file at all, while Claude Code, Cursor, and
+canonical `plugin.json` directly and gets no derived *manifest*, while Claude Code, Cursor, and
 Codex each read their own path. Keep that asymmetry in mind — this is a consolidation job, not a
 copy-everywhere job.
 
+That asymmetry does not extend to components. Declaring the canonical `$schema` puts a plugin in
+Open Plugin Spec mode, and Copilot CLI then reads its **native** components — agents, commands,
+rules, hooks, LSP servers — from a `com.github.copilot/` directory rather than the plugin root.
+Authoring still happens at the canonical locations: `plugin build` derives that directory
+([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)), so do not tell
+an author to move `agents/` into it — the root copy is what the other three vendors derive from. See
+[`references/vendors/copilot-cli.md`](./references/vendors/copilot-cli.md).
+
 `references/standard.md` defines the baseline every plugin gets. Read the vendor file for each
 runtime you are enabling, and only those.
 
@@ -22,7 +30,7 @@ runtime you are enabling, and only those.
 | Claude Code | `.claude-plugin/plugin.json` | none | `references/vendors/claude-code.md` |
 | Cursor | `.cursor-plugin/plugin.json` | none | `references/vendors/cursor.md` |
 | Codex | `.codex-plugin/plugin.json` | `version`, `description` | `references/vendors/codex.md` |
-| GitHub Copilot CLI | none — reads root `plugin.json` | none | `references/vendors/copilot-cli.md` |
+| GitHub Copilot CLI | none — reads root `plugin.json` | native components derived under `com.github.copilot/` ([ADR-0015](../../.agents/spec/design/decisions/0015-copilot-spec-mode-namespace.md)) | `references/vendors/copilot-cli.md` |
 
 This skill owns the **authoring** side: the plugin a project ships. Setting a repository up to
 *consume* skills — the `.agents/skills/` layout, `AGENTS.md`, per-harness bridges — is
@@ -78,9 +86,12 @@ Sort each finding into exactly one bucket:
 - **adoptable** — a hand-written vendor manifest with no canonical manifest above it, a legacy root
   `plugin.json` carrying neither `$schema` nor `extensions`, or publicly-shipped skills with no
   manifest at all. These become canonical content in Phase 4.
-- **undeliverable** — a vendor-specific field with no delivery path, most often a
-  `harnesses["copilot-cli"]` override: the canonical schema is closed, so the field cannot ride
-  along in root and the build warns about it. Report; do not invent a home for it.
+- **undeliverable** — a vendor-specific field with no delivery path, because Copilot CLI reads the
+  canonical manifest directly and has no derived file of its own. Two shapes reach this bucket: a
+  `harnesses["copilot-cli"]` override, which the build warns about; and a non-spec field on a
+  **legacy root `plugin.json`** — `category`, `tags` — which nothing warns about at all, because the
+  correct adoption never writes a `harnesses` entry for it. Report every one by name; do not invent
+  a home for it.
 - **not a plugin** — repo-private agent configuration (`.claude/skills/`, `.agents/skills/`,
   `.cursor/rules/`). It is this project's own tooling, not something it distributes. Say nothing
   about packaging it.
@@ -95,6 +106,11 @@ hand-written vendor manifests become generated artifacts, which vendors will be
 canonical metadata will say (show `name`, `version`, and `description` verbatim), and what is being
 left alone and why.
 
+An adoption also presents **every non-spec field it is about to drop, by name and value** — the
+undeliverable bucket from Phase 2. Nothing downstream warns about those, so this is the only notice
+the user gets. [`references/adopt.md`](./references/adopt.md) Step 2 has the command that enumerates
+them.
+
 Get explicit approval before any step that deletes, replaces, or rewrites a user-authored file —
 adoption always crosses that line, because it turns manifests the user maintains into build output.
 Creating a missing `plugin.json`, a missing component directory, or a missing skill scaffold needs
@@ -167,11 +183,16 @@ override both surface there and both are silent capability loss if ignored.
 When the work was an adoption, the proof is the diff:
 
 ```bash
-git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
+git diff -- plugin.json .claude-plugin .cursor-plugin .codex-plugin .github/plugin
 ```
 
-Expect only formatting and key-order churn. Any field that disappeared is a regression, not a
-cleanup — trace it back to the shared metadata or to that vendor's `harnesses` entry before shipping.
+From the four derived paths, expect only formatting and key-order churn. Root `plugin.json` is
+different and is in the list on purpose: it shows real hunks — the `$schema`/`extensions` rewrite —
+and under the legacy layout it *was* Copilot CLI's manifest, so it is the one file where a field can
+vanish unnoticed. Read those hunks rather than skimming them.
+
+Any field that disappeared is a regression, not a cleanup — trace it back to the shared metadata, to
+that vendor's `harnesses` entry, or to the drop list you reported in Phase 3, before shipping.
 
 Audit each skill the plugin ships, per [`references/create.md`](./references/create.md) Step 6.
 Report what was created, adopted, derived, and left alone. For a fuller read of the plugin's state
@@ -186,7 +207,9 @@ This skill is not a formatter. If the project has one, run it over the written f
 - **Never hand-edit a `version` field.** Two authored files and every derived artifact fall out of
   sync. The `version` skill owns that move.
 - **Adoption is lossless by contract.** Every vendor that worked before must still work after, and
-  the Phase 5 diff is the check that proves it.
+  the Phase 5 diff — root `plugin.json` included — is the check that proves it. Where a field
+  genuinely cannot be carried, losing it is a decision the user makes, not one the adoption makes
+  quietly: name it first.
 - **Do not package repo-private agent configuration.** A `.claude/skills/` directory is the project's
   own tooling; offering to publish it is wrong.
 - **Do not convert vendor settings without a documented mapping.** Hooks have one: author them in
@@ -215,5 +238,7 @@ This skill is not a formatter. If the project has one, run it over the written f
 
 - Governance: `npx universal-plugin governance show plugin-design`
 - Spec: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/.agents/spec/spec.md
-- Schema: https://raw.githubusercontent.com/cyberuni/universal-plugin/refs/heads/main/schema/v1.json
+- Manifest schema (Agent Plugins Specification v1.0.0): https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
+- Extension schema (the body of `extensions["org.cyberuni.universal-plugin"]`), shipped in the package at
+  `schema/extension.schema.json`: https://github.com/cyberuni/universal-plugin/blob/main/packages/universal-plugin/schema/extension.schema.json
 - Examples: https://github.com/cyberuni/universal-plugin/tree/main/examples

package/skills/init/references/adopt.md

@@ -41,19 +41,94 @@ canonical manifest (has `$schema` pointing at `agent-plugins.org` and an `extens
 which case there is nothing to adopt; route to `update.md`, or hand off to `doctor`, instead), or a legacy
 Copilot CLI manifest that now collides with the canonical path and must be folded in.
 
-## Step 2 — Sort every field into shared vs vendor-specific
+## Step 2 — Sort every field into shared, vendor-specific, and undeliverable
 
-Build two buckets from the manifests you inventoried:
+Build three buckets from the manifests you inventoried:
 
-- **Shared metadata** — `name`, `version`, `description`, `author`, `homepage`, `repository`,
-  `license`, `keywords`, and the component paths. These go at the canonical top level.
+- **Shared metadata** — the canonical top level is a **closed** set of exactly ten fields:
+  `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`,
+  `keywords`, `extensions`. A field in that list stays at the top level. That set is the upstream
+  spec's, not this project's — see
+  [the published schema](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json).
 - **Vendor-specific** — anything only one runtime understands (Cursor's `publisher`/`category`/
-  `tags`, Codex's `interface`, Copilot's `category`/`tags`). These go under
-  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`.
+  `tags`, Codex's `interface`). These go under
+  `extensions["org.cyberuni.universal-plugin"].harnesses.<vendor>`. The component paths
+  (`skills`, `commands`, `agents`, `hooks`, `mcpServers`, `rules`, `lspServers`, `outputStyles`)
+  are not top-level either — they go under that same extension namespace, one level up from
+  `harnesses`.
+- **Undeliverable** — a field whose only consumer is Copilot CLI. Copilot CLI reads the canonical
+  root manifest directly and gets no derived file, so such a field has no home on either side: the
+  closed schema rejects it at the top level, and a `harnesses["copilot-cli"]` entry is never
+  written anywhere. Before dropping one, check
+  [`vendors/copilot-cli.md`](./vendors/copilot-cli.md) — the two fields that actually turn up here,
+  `category` and `tags`, have a spec-conformant home (`keywords`) and are not a loss.
 
 Where two vendor manifests disagree on a shared field, **ask the user** which value is canonical
 rather than picking one. A silent choice here is a silent behavior change for one of their runtimes.
 
+### Name every field you are about to drop
+
+A legacy root `plugin.json` is what makes the third bucket real. Before 0.6 the build wrote
+Copilot CLI's output *to root*, so root carries whatever Copilot-specific fields the project set —
+`category` and `tags` are the ones seen in the wild. After adoption root is the canonical manifest
+and those fields have nowhere to go.
+
+Nothing warns about this. The build's `undeliverable-override` warning and `doctor`'s matching
+finding fire only on a `harnesses["copilot-cli"]` entry — which is what someone doing it *wrong*
+writes. An adoption done correctly never creates one, so it gets silence. Enumerate the fields
+yourself, from the pre-adoption root manifest, before you overwrite it:
+
+```bash
+node -e '
+  const spec = ["$schema", "name", "version", "description", "author",
+                "homepage", "repository", "license", "keywords", "extensions"]
+  const root = JSON.parse(require("node:fs").readFileSync("plugin.json", "utf8"))
+  for (const k of Object.keys(root)) {
+    if (!spec.includes(k)) console.log(k, "=", JSON.stringify(root[k]))
+  }
+'
+```
+
+Every name it prints is a field the canonical top level cannot hold. Sort each one:
+
+| The field | Where it goes |
+| --- | --- |
+| `vendorExtensions` — the whole pre-0.6 block | `extensions["org.cyberuni.universal-plugin"].harnesses` — **renamed, not dropped** |
+| a component path (`skills`, `commands`, `agents`, …) | `extensions["org.cyberuni.universal-plugin"].<name>` — carried |
+| a field a vendor with a *derived* manifest understands | that vendor's `harnesses` entry — carried |
+| `category` / `tags` from the legacy Copilot output | fold into **`keywords`** — see below |
+| anything left | **dropped** |
+
+`vendorExtensions` is the row that catches people out, because the snippet prints it alongside the
+genuinely undeliverable fields and it looks like one of them. It is not: it is the old name for
+`harnesses`, and dropping it discards every per-harness override the project had. Carry the block
+across, then sort the `copilot-cli` entry inside it by the rule above — that entry is the one whose
+contents have no delivery path.
+
+`plugin build` will not let this one pass quietly: a root manifest still carrying `vendorExtensions`
+now exits 1 rather than reporting `built 0`, naming the signal and routing to `doctor`. If Step 5
+fails that way, the block did not get carried across.
+
+`category` and `tags` have their own row because they are the fields this whole step exists for, and
+they are **not** simply dropped. Copilot CLI has no `plugin.json` handling for either — its manifest
+validator knows `keywords` and treats these two as unknown-and-ignored — while `keywords` is both a
+spec field and the one Copilot actually parses. So fold the values in rather than deleting them:
+
+```
+category: "productivity" + tags: ["workflow", "planning", "verification"]
+  → keywords: ["productivity", "workflow", "planning", "verification"]
+```
+
+If the project also ships a `marketplace.json` catalog, `category` and `tags` are real fields on a
+catalog entry and belong there as well — with the right types, because a wrong one is a fatal browse
+error rather than a warning. [`vendors/copilot-cli.md`](./vendors/copilot-cli.md) has the evidence
+and the exact validator messages.
+
+**Report anything genuinely dropped to the user by name, with the value each held, before Step 3
+writes anything.** That report is the only notice they get, and it is the difference between an informed
+decision and a field that evaporates. Say what the field was for if you know; if a field looks load-
+bearing and the user wants it kept, stop rather than shipping the adoption around it.
+
 ## Step 3 — Write the canonical manifest
 
 Scaffold it, naming exactly the vendors you found in Step 1:
@@ -85,8 +160,8 @@ regenerated rather than edited.
 - Tell the user they are generated from here on, and that hand-edits will be overwritten by
   `plugin build`.
 - If the project has a legacy root `plugin.json` for Copilot CLI, that path is now the canonical
-  manifest — its derived Copilot output moves elsewhere. Check the vendor output table in
-  [`create.md`](./create.md) Step 2 for the current path.
+  manifest. Copilot CLI gets no replacement file: it reads root directly, so the canonical manifest
+  *is* its manifest from here on. See the vendor output table in [`create.md`](./create.md) Step 2.
 
 ## Step 5 — Build
 
@@ -99,14 +174,27 @@ npx universal-plugin plugin build
 This is the point of the whole procedure.
 
 ```bash
-git diff -- .claude-plugin .cursor-plugin .codex-plugin .github/plugin
+git diff -- plugin.json .claude-plugin .cursor-plugin .codex-plugin .github/plugin
 ```
 
-Read every line of that diff. Expect only formatting and key-order churn.
+Root `plugin.json` is in that list on purpose, and it is the one path that behaves differently from
+the other four.
+
+- For `.claude-plugin`, `.cursor-plugin`, `.codex-plugin`, and `.github/plugin`, expect only
+  formatting and key-order churn. A hunk that changes a value is a finding.
+- For root `plugin.json`, **expect real hunks** — the `$schema` line and the `extensions` object are
+  new, and the component paths moved under them. That is the rewrite working. Because the diff is
+  large by design it is the easy one to skim, and under the legacy layout root *was* a vendor
+  manifest — Copilot CLI's — so it is also the only file where a field can go missing without any
+  other check noticing. Read it, do not skim it.
+
+Account for **every key that leaves root**. Each one must land in exactly one of three places: at the
+canonical top level, under `extensions`, or on the dropped list you enumerated and reported in
+Step 2. A key that left root and is on none of those three is a regression.
 
-**Any field that disappeared is a regression**, not a cleanup. Trace it back: either it belongs in
-the shared metadata, or it belongs in that vendor's `harnesses` entry, or it is a field the build
-does not yet support — in which case stop and tell the user rather than shipping a quiet
+**Any field that disappeared unannounced is a regression**, not a cleanup. Trace it back: either it
+belongs in the shared metadata, or it belongs in that vendor's `harnesses` entry, or it is a field
+the build does not yet support — in which case stop and tell the user rather than shipping a quiet
 capability loss.
 
 Then confirm the plugin still loads. See [`create.md`](./create.md) Step 8 for local install.

package/skills/init/references/detection.md

@@ -15,13 +15,19 @@ ls .mcp.json .lsp.json hooks/ commands/ agents/ rules/ output-styles/ 2>/dev/nul
 | `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/` manifest **below** a canonical root | build output | derived |
 | a vendor manifest with **no** canonical root `plugin.json` | a vendor-specific plugin | adoptable |
 | root `plugin.json` with neither `$schema` nor `extensions` | a legacy single-vendor manifest now sitting on the canonical path | adoptable |
+| a top-level `vendorExtensions` block | the pre-0.6 name for `harnesses`; `plugin build` exits 1 on it | adoptable — carry the block, do not drop it |
 | publicly-shipped skills and no manifest of any kind | skills shipped without a plugin | adoptable |
 | `harnesses["copilot-cli"]` carrying fields | no delivery path — the canonical schema is closed | undeliverable |
+| a non-spec field on a legacy root `plugin.json` (`category`, `tags`, …) | it was Copilot CLI's, and Copilot CLI has no derived manifest to move it to | undeliverable — and **nothing warns**; name it in Phase 3 |
 | `.claude/skills/`, `.agents/skills/`, `.cursor/rules/` | the project's own tooling | not a plugin |
 | `.github/plugin/plugin.json` | a path older builds wrote; shadowed by root and no longer generated | stale, safe to delete |
 
-For every vendor manifest found, record its path and **every field it sets**. Adoption reproduces
-all of it, and the Phase 5 diff is checked field by field.
+For every vendor manifest found, record its path and **every field it sets** — root `plugin.json`
+included, when it is the legacy kind. Adoption reproduces all of it, and the Phase 5 diff is checked
+field by field. The canonical top level accepts exactly ten fields (`$schema`, `name`, `version`,
+`description`, `author`, `homepage`, `repository`, `license`, `keywords`, `extensions`); everything
+else either moves under `extensions` or is dropped, and
+[`adopt.md`](./adopt.md) Step 2 is where you sort out which.
 
 ## Which skills count as public