docs(versioning): a release is not live until the marketplace entry moves

AGENTS.md

@@ -160,4 +160,4 @@ Use feature branches and pull requests. Validation runs on every push/PR.
 - **Don't duplicate the `sdd` plugin.** This plugin owns prose and content; requirements, RFC-2119 specifications, ADRs, and traceability belong to `sdd`. When extending, resist adding a spec-authoring or traceability skill that competes.
 - **`claude plugin <unknown-subcommand>` prints the general help and exits 0.** It does not error, so a non-existent command reads as working in a script or a doc review. `claude plugin add` does not exist and never did — the real subcommands are `details disable enable eval init install list marketplace prune tag uninstall update validate`. Verify a CLI invocation by running it and checking behaviour, not just the exit code.
 - **There is no local-path *install*.** `claude --plugin-dir <path>` loads a working copy for **one session** (repeatable; also takes a `.zip`), and is the dogfooding path. `claude plugin install` resolves names from a configured marketplace, and `claude plugin marketplace add <path>` needs a `.claude-plugin/marketplace.json`, which a single-plugin repo does not have. A persistent install therefore goes through the marketplace.
-- **Register in the marketplace separately.** Public availability requires an entry in the `cadasto` marketplace (`cadasto/plugin-marketplace`); the plugin is registered there independently of this repo.
+- **Register in the marketplace separately — and repin it on every release.** Public availability requires an entry in the `cadasto` marketplace, maintained in `Cadasto/plugin-marketplace`. That entry is pinned to a release tag, so tagging here ships nothing until the entry's `version` and `source.ref` are bumped; see [docs/versioning.md](docs/versioning.md#marketplace).

CHANGELOG.md

@@ -7,6 +7,11 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 - Keep a Changelog: https://keepachangelog.com/en/1.1.0/
 - Semantic Versioning: https://semver.org/spec/v2.0.0.html
 
+## [Unreleased]
+
+### Changed
+- Docs: `docs/versioning.md`, `AGENTS.md` — the `cadasto` catalog pins each entry to a release tag, so a tag here ships nothing until the entry's `version` and `source.ref` move. Repinning is now release step 8.
+
 ## [0.2.0] - 2026-08-25
 
 Tightens the plugin to a single prose linter and makes its always-on surface cheap: markdownlint is gone, the agents are honestly described as report-only, and every skill description is rewritten for the skill-listing budget.

docs/versioning.md

@@ -19,11 +19,26 @@ While on the `0.x` line, treat the plugin as pre-stable: a breaking change may s
 5. Sync the docs surface (AGENTS.md, README.md) with what shipped. The router body and `hooks/session-start.sh` are checked mechanically by the validator, so a missed component fails CI rather than shipping quietly.
 6. Commit (`chore(release): vX.Y.Z`) and tag: `git tag -a vX.Y.Z -m "docs-editing-plugin vX.Y.Z"`.
 7. Push commits and the tag: `git push origin main --follow-tags`.
+8. **Update the marketplace entry** — the release is not live until this lands. See below.
 
 ## Coupling to external tooling
 
 The reference linter config (`references/vale.ini`) pins no tool version, but it does name **style packages** (`Google`, `write-good`, `alex`, `proselint`) whose rule sets change upstream. When a package renames or removes a rule the config disables or escalates, the config breaks silently — `vale` warns but exits 0 for an unknown rule name. Re-check the named rules when bumping a package, and treat a rule rename as a **patch** fix.
 
-## No MCP or marketplace coupling
+## No MCP coupling
 
-This plugin has **no companion MCP server**, so there is no server-compatibility version to align. It is listed in the **Cadasto marketplace** (`cadasto/plugin-marketplace`); the marketplace tracks the repo's default branch, so update that entry only when `name`, `description`, or `repository` changes — there is no version pin to bump there.
+This plugin has **no companion MCP server**, so there is no server-compatibility version to align.
+
+## Marketplace
+
+Public install is via the [Cadasto marketplace](https://github.com/Cadasto/plugin-marketplace) as `docs-editing@cadasto`. The catalog **pins every entry to a release tag**, so tagging and pushing a release here does not ship it — users see nothing until the marketplace entry moves.
+
+After step 7, update the entry in `Cadasto/plugin-marketplace`:
+
+1. Bump that entry's `version` to `X.Y.Z` and `source.ref` to `vX.Y.Z` together (validation there rejects a mismatch).
+2. Bump the catalog's own `metadata.version` — a plugin minor/major is a catalog **minor**, a plugin patch is a catalog **patch**.
+3. Add a dated `## [X.Y.Z] - YYYY-MM-DD` section in the catalog `CHANGELOG.md`, then run `python3 scripts/validate.py --fix`.
+
+See the catalog's [docs/versioning.md](https://github.com/Cadasto/plugin-marketplace/blob/main/docs/versioning.md).
+
+The catalog copies `description`, `version`, and `keywords` verbatim from `.claude-plugin/plugin.json`. Fix those in this repo and copy them into the catalog when the next release is pinned.