universal-plugin 0.17.0 → 0.18.0

package/skills/init-universal-plugin/references/release-tools.md

@@ -0,0 +1,272 @@
+# Release tool wiring
+
+Each release tool decides the release number in its own way. The plugin still needs that number
+stamped into `plugin.json`, the vendor manifests, the catalogs, and the skill pins. The `version`
+skill owns the stamp: `plugin version` with a number the tool hands it. This file covers the wiring
+that makes a release tool call it.
+
+`plugin init` writes the changesets wiring itself (SKILL.md Phase 3). It writes nothing for the
+other tools. Their config takes several file formats, JavaScript modules among them, and it often
+carries plugins the user added. Editing it is a judgment call, so the skill makes the edit and the
+user approves it.
+
+| Tool | Config the survey finds | Wiring |
+| --- | --- | --- |
+| changesets | `.changeset/` | `plugin init` writes it (SKILL.md Phase 3) |
+| semantic-release | `.releaserc`, `.releaserc.{json,yaml,yml,js,cjs,mjs}`, `release.config.{js,cjs,mjs}`, or a `release` key in `package.json` | [below](#semantic-release) |
+| release-it | `.release-it.{json,yaml,yml,toml,js,cjs,ts}`, or a `release-it` key in `package.json` | [below](#release-it) |
+| release-please | `release-please-config.json`, `.release-please-manifest.json` | [below](#release-please) |
+
+## semantic-release
+
+semantic-release writes the version only during its own run. Two plugins carry the number into the
+plugin:
+
+- **`@semantic-release/exec`** runs the stamp in its `prepare` step:
+  `prepareCmd: "universal-plugin plugin version ${nextRelease.version}"`. semantic-release fills in
+  `${nextRelease.version}` with its lodash template. Add `--root <plugin-root>` when the plugin root
+  is not the repository root.
+- **`@semantic-release/git`** commits the stamped files back. Copilot CLI and GitHub-hosted
+  marketplaces read `plugin.json` from the repository, not from a package, so without this commit
+  those channels never see the new number (ADR-0010 §2).
+
+A `plugins` list replaces semantic-release's default list. It does not merge with it. The defaults
+are `commit-analyzer`, `release-notes-generator`, `npm`, and `github`. A config with no `plugins`
+key therefore gets the full list written out, minus whatever the case below drops.
+
+Within each step, plugins run in list order. Put `exec` after `npm` and before `git`. That way `npm`
+moves `package.json` first, `exec` stamps the plugin, and `git` commits both.
+
+### A plugin that ships to no npm package
+
+Drop `@semantic-release/npm` from the list. `npmPublish: false` does not cover this: the plugin
+still sets `package.json` `version`, and it requires a `package.json` that a git-installed plugin
+usually lacks. Without `npm`, semantic-release needs no `package.json` at all.
+
+```json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    ["@semantic-release/exec", {
+      "prepareCmd": "npx universal-plugin@0.18.0 plugin version ${nextRelease.version}"
+    }],
+    ["@semantic-release/git", {
+      "assets": [
+        "plugin.json",
+        ".claude-plugin/**",
+        ".cursor-plugin/**",
+        ".codex-plugin/**",
+        ".agents/plugins/marketplace.json",
+        ".github/plugin/**",
+        "com.github.copilot/**",
+        "skills/**",
+        ".plugin/pins.json"
+      ]
+    }],
+    "@semantic-release/github"
+  ]
+}
+```
+
+With no `package.json`, `universal-plugin` is not installed, so the command runs it through `npx`.
+Pin it to the CLI version this skill ships with, as shown. The `upgrade-plugin` skill moves that pin
+later.
+Where the repository does install `universal-plugin` as a devDependency, use the bare
+`universal-plugin` instead.
+
+### A plugin that ships on npm
+
+Keep `@semantic-release/npm` and add the other two after it:
+
+```json
+["@semantic-release/npm"],
+["@semantic-release/exec", { "prepareCmd": "universal-plugin plugin version ${nextRelease.version}" }],
+["@semantic-release/git", { "assets": ["package.json", "plugin.json", "..."] }]
+```
+
+Setting `assets` replaces the git plugin's default list, which holds `package.json`,
+`package-lock.json`, `npm-shrinkwrap.json`, and `CHANGELOG.md`. List again each of those the
+repository needs, alongside the plugin files above.
+
+### Assets
+
+`plugin version` rewrites `plugin.json` and the skill pins, and then re-derives every vendor
+manifest and repository catalog. Commit all of them, or the repository's files disagree with the
+tag. The list above covers every place the CLI writes. A glob that matches nothing adds nothing, so
+the whole list is safe to keep for a plugin that does not declare every vendor. Under a plugin root
+below the repository root, prefix the plugin's own paths with that root. The catalogs
+(`.claude-plugin/marketplace.json`, `.cursor-plugin/marketplace.json`,
+`.agents/plugins/marketplace.json`, `.github/plugin/marketplace.json`) stay at the repository root.
+Add the mcp file when the plugin declares one.
+
+The git plugin's default commit message ends in `[skip ci]`, so the commit back does not start
+another release.
+
+### Applying it
+
+1. Edit the config file the survey found, in its own format. For a JavaScript config, edit the
+   `plugins` array in place. If no config exists, write `.releaserc.json`.
+2. Keep every plugin the user already lists, and keep their order relative to each other.
+3. Show the before and after `plugins` list in the Phase 3 plan. Apply only once the user approves.
+4. Name the packages the release job must install: `@semantic-release/exec` and
+   `@semantic-release/git`. The `--no-ci` local run, and the CI job that runs semantic-release, both
+   need them. Installing them is the user's step. Do not edit the CI workflow (SKILL.md Rules).
+
+## release-it
+
+release-it runs its `after:bump` hook after it settles the new number and before its release
+commit and tag. That commit stages every tracked file the hook changed (`git add . --update`), so
+the stamp ships in the tagged commit with no extra plugin. `${version}` in a hook is the new number.
+
+### A plugin that ships to no npm package
+
+Set `"npm": false`. release-it then ignores `package.json`, needs none, and reads the current version
+from the latest git tag. Add the stamp as the `after:bump` hook:
+
+```json
+{
+  "npm": false,
+  "hooks": {
+    "after:bump": "npx universal-plugin@0.18.0 plugin version ${version}"
+  }
+}
+```
+
+With no `package.json`, `universal-plugin` is not installed, so the hook runs it through `npx`. Pin
+it to the CLI version this skill ships with, as shown. The `upgrade-plugin` skill moves that pin
+later.
+
+### A plugin that ships on npm
+
+Keep release-it's npm plugin. It bumps `package.json`, and the hook then stamps the same number into
+the plugin:
+
+```json
+{
+  "hooks": { "after:bump": "universal-plugin plugin version ${version}" }
+}
+```
+
+Use the bare `universal-plugin` when the repository installs it as a devDependency, as an
+npm-shipped plugin usually does. Otherwise use the pinned `npx` form above. Here release-it reads
+the current version from `package.json`, so the first release needs no tag.
+
+Add `--root <plugin-root>` to the hook when release-it runs from a directory other than the plugin
+root.
+
+### The first release needs a tag
+
+With `"npm": false`, release-it reads the current number from the latest tag, never from
+`plugin.json`. With no tag it starts from `0.0.0`, proposes `0.0.1`, and the stamp refuses a number
+that does not advance on the version `plugin.json` holds. The release then fails.
+
+So, when the plugin ships to no npm package, check for a tag in the Phase 3 plan:
+
+```bash
+git describe --tags --abbrev=0
+```
+
+If that finds no tag, propose tagging the current commit with the version `plugin.json` holds, and
+create the tag once the user approves:
+
+```bash
+git tag v1.2.0
+```
+
+- Use `v<version>` unless the repository already tags in another form. release-it names its next
+  tag after the latest one, so the first tag sets the form every later release keeps.
+- A lightweight tag is enough. release-it finds it with `git describe --tags`.
+- Tag the commit whose `plugin.json` holds that version, and only after the plugin's files are
+  committed. Do not move or replace an existing tag.
+- The tag is local until pushed. A release that runs in CI needs it on the remote. Pushing it is the
+  user's step, so name `git push origin v1.2.0` and run it only if the user asks.
+- If the user declines, say the first release fails until a tag on the current version exists.
+
+### Applying it
+
+1. Edit the config the survey found, in its own format: a `.release-it.*` file, or the `release-it`
+   key in `package.json`. If none exists, write `.release-it.json`.
+2. Keep every key the user already set. If an `after:bump` hook already exists, keep its command and
+   run the stamp after it: a string becomes an array of both commands. Show the hooks before and
+   after in the Phase 3 plan. Apply only once the user approves.
+3. For a plugin that ships to no npm package, set `"npm": false`, and handle the tag as above.
+4. Commit the plugin's generated files (`plugin.json`, the vendor manifests, the catalogs,
+   `.plugin/pins.json`) before the first release. The release commit stages only tracked files, so
+   a stamped file git does not track yet stays out of the tagged commit.
+5. Installing release-it is the user's step. Do not edit the CI workflow (SKILL.md Rules).
+
+`doctor` reports `release-it-no-stamp` for a release-it config that never runs `plugin version`.
+
+## release-please
+
+release-please runs no command before its release commit. Its release PR moves the number in the
+files it knows, and a workflow step on that PR then restamps the plugin. The wiring is two files the
+skill writes, and one workflow step the user adds.
+
+### A plugin that ships to no npm package
+
+`release-type: simple` keeps the number in `.release-please-manifest.json`, and `extra-files` bumps
+`plugin.json`. Write `release-please-config.json`:
+
+```json
+{
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "extra-files": [{ "type": "json", "path": "plugin.json", "jsonpath": "$.version" }]
+    }
+  }
+}
+```
+
+The restamp step runs `npx -y universal-plugin@0.18.0 plugin version --from-manifest`, which takes
+the number `plugin.json` already holds. Pin it to the CLI version this skill ships with.
+
+### A plugin that ships on npm
+
+`release-type: node` bumps `package.json`. The restamp step runs
+`universal-plugin plugin version --from-package` instead. Do not add `plugin.json` to `extra-files`
+here: the package owns the number, and `--from-package` carries it into the plugin.
+
+### The manifest holds the current version
+
+release-please reads the last release from `.release-please-manifest.json`. A package with no entry
+starts from a default version, not from the plugin's. Write the entry with the version `plugin.json`
+holds, keyed by the package path:
+
+```json
+{ ".": "1.2.0" }
+```
+
+For a plugin below the repository root, use its path as the key in both files (`"packages/my-plugin"`),
+and make `extra-files` paths relative to that package.
+
+### The workflow step
+
+The `version` skill's section *release-please with no `package.json`* has the workflow: a GitHub
+App token minted for the run, the release-please action given that token, then a checkout of the
+release PR branch with the same token, the restamp, and a commit pushed back. Show it in the plan and
+hand it to the user. Do not write or edit the workflow (SKILL.md Rules). For an npm-shipped plugin,
+the step runs `--from-package` in place of `--from-manifest`.
+
+The token matters. A push made with the default `GITHUB_TOKEN` starts no workflow run, so the
+release PR's checks never run on its head commit and a required check blocks the merge. Tell the
+user the App setup the workflow needs: an App with Contents, Pull requests and Issues set to read and
+write, installed on the repository, its client ID in the variable `RELEASE_APP_CLIENT_ID` and a
+private key in the secret `RELEASE_APP_PRIVATE_KEY`. Do not offer a `workflow_dispatch` re-run of CI
+instead: its checks do not count toward a required check.
+
+### Applying it
+
+1. If `release-please-config.json` exists, add `extra-files` to the plugin's package entry and keep
+   every other key. If it does not, write the config above.
+2. Add the plugin's entry to `.release-please-manifest.json`, or write the file. Never lower or
+   replace an entry that already exists: that is the last released version.
+3. Show both files before and after in the Phase 3 plan. Apply only once the user approves.
+4. Hand over the workflow step and the App setup.
+
+`doctor` reports `release-please-no-restamp` when `extra-files` bumps `plugin.json` and no workflow
+runs `plugin version`, and `release-please-restamp-no-ci` when the restamp is pushed with the default
+`GITHUB_TOKEN`.

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

@@ -58,7 +58,7 @@ what each build gets. A vendor listed in `vendors` with no `harnesses` entry sti
 ├── agents/<name>.md
 ├── rules/<name>.mdc         (Cursor-only guidance)
 ├── hooks/hooks.json
-├── .mcp.json
+├── mcp.json
 └── README.md
 ```
 
@@ -70,7 +70,7 @@ directories. Create the rest only when the plugin has content for them.
 | Component | Field | Directory | Reaches |
 |-----------|-------|-----------|---------|
 | Skills | `skills` | `skills/<name>/SKILL.md` | every vendor |
-| MCP servers | `mcpServers` | `.mcp.json` | every vendor |
+| MCP servers | `mcpServers` | `mcp.json` | every vendor |
 | Commands | `commands` | `commands/<name>.md` | Claude Code, Cursor, Copilot CLI |
 | Agents | `agents` | `agents/<name>.md` | Claude Code, Cursor, Copilot CLI |
 | Hooks | `hooks` | `hooks/hooks.json` | every vendor — authored PascalCase, translated per vendor by the build; handler types vary |
@@ -79,7 +79,7 @@ directories. Create the rest only when the plugin has content for them.
 | Output styles | `outputStyles` | `output-styles/` | Claude Code only |
 
 The universal minimum — reaching every runtime with no vendor manifest at all — is
-`skills/<name>/SKILL.md` plus `.mcp.json`. Reach for a narrower component only when the plugin needs
+`skills/<name>/SKILL.md` plus `mcp.json`. Reach for a narrower component only when the plugin needs
 what only that component does; the `plugin-design` reference is the authority on that choice.
 
 ## Constraints

package/skills/init-universal-plugin/references/vendors/copilot-cli.md

@@ -83,6 +83,9 @@ Do not build a delivery path for these into the plugin manifest. There is nothin
 
 ### Still open
 
+Open as of the 1.0.83 runtime examined above. Re-check against the current release before relying
+on any of these.
+
 - **Where the `unknown field (ignored)` warning surfaces.** It exists in the binary but reached no
   output on `plugin install`, `plugin list`, or `plugins list`. Likely the interactive dashboard or
   the session config-problems channel.

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

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

package/skills/marketplace/scripts/add.mjs

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

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

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

package/skills/marketplace/scripts/marketplace.mjs

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

package/skills/marketplace/scripts/update.mjs

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

package/skills/marketplace/scripts/validate.mjs

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

package/skills/migrate-plugin/SKILL.md

@@ -87,7 +87,7 @@ configuration is:
 }
 ```
 
-Retain existing package entries such as `bin`, `dist`, and `governances`.
+Retain existing package entries such as `bin`, `dist`, and `references`.
 Never replace the allowlist wholesale.
 
 ## 4. Bundle the CLI with tsdown
@@ -173,7 +173,6 @@ as a follow-up instead of doing it inside this migration.
 
 Point every version and build step at the new plugin root:
 
-- Set the manifest extension's `packagePath` to `"."`.
 - `universal-plugin plugin version --from-package --root <pkg>` reads `packagePath` from
   `<pkg>/.agents/universal-plugin.json`, not from the manifest extension. With
   no `packagePath` it reads `<pkg>/package.json`, so a package that holds its

package/skills/publish-plugin/SKILL.md

@@ -34,7 +34,8 @@ is the common case.
 
 ### 0a. Identify the marketplace repo
 
-Default to `cyberuni/cyberplace` unless the user names another one.
+Default to `cyberuni/cyberplace` unless the user names another one. The commands below call it
+`<marketplace-repo>` (`<owner>/<repo>`), and its repository name `<marketplace-repo-name>`.
 
 ### 0b. Identify which repo the cwd is
 
@@ -317,15 +318,15 @@ Otherwise, the marketplace repo is elsewhere and needs a working copy. If the us
 (org member), work directly:
 
 ```bash
-gh repo clone cyberuni/cyberplace
-cd cyberplace
+gh repo clone <marketplace-repo>
+cd <marketplace-repo-name>
 ```
 
 If a fork is needed:
 
 ```bash
-gh repo fork cyberuni/cyberplace --clone --remote
-cd cyberplace
+gh repo fork <marketplace-repo> --clone --remote
+cd <marketplace-repo-name>
 git fetch upstream && git merge upstream/main
 ```
 
@@ -354,7 +355,7 @@ git push origin add-<plugin-name>
 
 ```bash
 gh pr create \
-  --repo cyberuni/cyberplace \
+  --repo <marketplace-repo> \
   --title "Add <plugin-name> v<version>" \
   --body "$(cat <<'EOF'
 ## Plugin

package/skills/version/README.md

@@ -17,7 +17,7 @@ change without a matching bump is invisible to them.
 | Source | Call | Used by |
 |---|---|---|
 | Author bump | `plugin version minor` | Plain repositories |
-| Explicit number | `plugin version 1.4.0` | semantic-release (`@semantic-release/exec` `prepareCmd`) |
+| Explicit number | `plugin version 1.4.0` | semantic-release (`@semantic-release/exec` `prepareCmd`), release-it (`after:bump` hook) |
 | The package's `package.json` | `plugin version --from-package` | changesets, release-please |
 
 With `packagePath` declared, a release type is refused: bump the package with the release tool, then
@@ -27,8 +27,12 @@ semantic-release stamps files that exist only in the npm package unless `@semant
 commits them back. Git-sourced installs read `plugin.json` from the repository, so they need that
 commit-back.
 
-`plugin bundle` and `publish sync-version` are deprecated aliases and are removed in the next minor
-release.
+release-it with `"npm": false` reads the version from the latest git tag and needs no `package.json`.
+Its `after:bump` hook runs `plugin version ${version}` before the release commit and tag. Tag the
+current version before the first release, or release-it starts from `0.0.0`.
+
+`plugin bundle` and `publish sync-version` are deprecated aliases. They have warned since 0.14.0 and will be
+removed in a later release.
 
 ## The part that is not automatable