refactor: own the plugin-reconfiguration paragraph in one convention spoke

docs/conventions/plugin-reconfiguration/README.md

@@ -0,0 +1,59 @@
+# Plugin Reconfiguration Convention
+
+The single owned source for how a consumer changes a plugin's native `userConfig` options after
+install — the guidance every setup skill used to restate (with drift) and now cites. Setup skills
+print the short form and cite this doc; the version-verification record below lives ONLY here, so
+a re-verification against a newer Claude Code release is a one-file edit.
+
+## Boundary
+
+This doc owns the **reconfiguration routes and their caveats** for options stored in Claude Code's
+native plugin-configuration surface (`pluginConfigs`). Which options a plugin has, and what they
+mean, belong to that plugin's own README Options reference. The rule that no setup skill ever
+writes `pluginConfigs`, user settings, or the plugin cache is PLUGIN-PHILOSOPHY's (Setup is
+explicit and repeatable); this doc restates it only as the reason both routes below are
+consumer-run.
+
+## The two routes
+
+- **Interactive, any time:** `/plugin configure <plugin>@<marketplace>`.
+- **Headless:** rerun the install with the new value:
+
+  ```shell
+  claude plugin install <plugin>@<marketplace> -s <scope> --config KEY=VALUE
+  ```
+
+  (`--config` repeatable per key.) Against an already-installed plugin it prints
+  `already installed` **and still writes the value** — the short-circuit is about the install, not
+  the config write.
+
+## Verified-version record
+
+The `already installed`-still-writes claim was verified on **Claude Code 2.1.240**: a
+non-sensitive option at `user` scope — a non-default value written to an installed plugin, then
+restored. Not covered: a `sensitive` option, and `project`/`local` scope. Re-verify before relying
+on the claim outside the covered conditions, and update this section (only here) when a newer
+release is verified.
+
+## Caveats every setup skill's short form carries
+
+1. **Never uninstall to reconfigure.** Uninstalling drops the plugin's entire stored
+   `pluginConfigs` entry, resetting every option in its README Options reference to its manifest
+   default — customized values are simply gone, with nothing left to read the old values from.
+2. **Scope.** `-s` defaults to `user`; pass the scope `claude plugin list` reports for the plugin,
+   and run from that project's directory for a `project`/`local` scope, or the write lands at a
+   scope that does not load.
+3. **Observation is next-session.** The rendered `${user_config.*}` is injected at skill load and
+   each hook receives its `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at session start, so
+   a same-session `check` still reports the OLD value — that is not a failed write. Verify the
+   effective value by rerunning the plugin's setup `check` in a **fresh session**, and never claim
+   an unobserved change.
+
+## The short form setups print
+
+A setup skill states, in its own words but without restating the verified-version record: the two
+routes, the three caveats above, and a citation of this doc as the owner of the verification
+record. Canonical citation (installed plugins cannot read this repository's working tree, so cite
+the published URL):
+
+<https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-reconfiguration/README.md>

plugins/actionlint/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "actionlint",
-  "version": "0.8.21",
+  "version": "0.8.22",
   "description": "Lint GitHub Actions workflow files on edit via actionlint, surfacing findings as advisory context.",
   "author": {
     "name": "Melodic Software",

plugins/actionlint/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to the `actionlint` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.8.22]
+
+### Changed
+
+- `setup` prints the canonical short form of the plugin-reconfiguration guidance and cites the marketplace's plugin-reconfiguration convention as the owner of the verified-version record instead of restating it (#3585, customization-consistency Phase 1d).
+
 ## [0.8.21]
 
 ### Changed

plugins/actionlint/skills/setup/SKILL.md

@@ -61,28 +61,23 @@ Run `check`, then for each FAIL point at the resolution. This skill installs not
 - missing `actionlint`: platform install guidance from the README Requirements section
   (the [actionlint install guide](https://github.com/rhysd/actionlint/blob/main/docs/install.md)).
 - missing `jq` / Bash: platform install instructions from the README Requirements section.
-- toggle off: direct to `/plugin configure actionlint` (interactive, any
-  time). Headless: rerun the install with the new value,
+- toggle off: reconfigure through Claude Code's native flow, per the marketplace's
+  plugin-reconfiguration convention
+  (<https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-reconfiguration/README.md>,
+  which owns the verified-version record): interactive
+  `/plugin configure actionlint@<marketplace>` any time, or headless
   `claude plugin install actionlint@<marketplace> -s <scope> --config actionlint_enabled=true`
-  (repeatable per key). The official docs document `--config` only as a `claude plugin install`
-  flag and say nothing about an already-installed plugin, so this rests on observation, not
-  documentation: against an already-installed plugin the command prints `already installed`
-  **and still writes the value**, verified on Claude Code 2.1.240 (a non-sensitive option at
-  `user` scope: a non-default value written to an installed plugin, then restored). The
-  short-circuit is about the install, not the config write. Re-verify before relying on it
-  outside those conditions. A `sensitive` option, or `project`/`local` scope, were not covered.
-  Do **not** uninstall to reconfigure: uninstalling drops this plugin's entire stored
-  `pluginConfigs` entry, resetting every option in the README's Options reference table to its
-  manifest default. `-s` defaults to `user`, so pass the scope `claude plugin list` reports for
-  this plugin (`user`, `project`, or `local`), and run from that project's directory for a
-  `project`/`local` scope, or the write lands at a scope that does not load. This skill never
-  writes user settings or `pluginConfigs`.
-  Afterwards, keep the two claims apart. The write is issued and the stored value is what you
-  passed; the RUNNING session's behavior is not. The rendered `${user_config.*}` is injected at
-  skill load and each hook receives its `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at
-  session start, so a same-session `check` still reports the OLD value. Reporting that as a
-  failed write would be wrong. Verify the effective value by rerunning `check` in a **fresh
-  session**, and never claim an unobserved change.
+  (repeatable per key) — against an already-installed plugin it prints `already installed`
+  **and still writes the value**. Do **not** uninstall to reconfigure: that drops this plugin's
+  entire stored `pluginConfigs` entry, resetting every option in the README's Options reference
+  to its manifest default. `-s` defaults to `user`; pass the scope `claude plugin list` reports
+  for this plugin, and run from that project's directory for a `project`/`local` scope, or the
+  write lands at a scope that does not load. This skill never writes user settings or
+  `pluginConfigs`. Afterwards rerun `check` in a **fresh session** — the rendered
+  `${user_config.*}` is injected at skill load and each hook receives its
+  `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at session start, so a same-session
+  `check` still reports the OLD value; report the observed effective value, never an
+  unobserved change.
 
 After pointing at a remediation, re-run the relevant `check` probe and report its actual
 result. Never claim resolved on the reader's report that they installed something.
@@ -99,11 +94,9 @@ Re-running `apply` after everything passes changes nothing and reports "already
   the shared lib should declare it too (claude-ops set the precedent).
 - **`--config`'s post-install behavior is undocumented, so the guidance above rests on
   observation.** The official docs describe `--config` only as a `claude plugin install` flag
-  and say nothing about an already-installed plugin. This skill's `apply` route is therefore
-  stamped rather than cited: on Claude Code 2.1.240 the command printed `already installed`
-  and still wrote the value, for a non-sensitive option at `user` scope. Re-verify if the CLI's
-  plugin surface changes, and do not extend the observation to a `sensitive` option or to
-  `project`/`local` scope. Neither was covered.
+  and say nothing about an already-installed plugin. The verified-version record — which CLI
+  release the still-writes claim was observed on, and which conditions it covered — lives only
+  in the plugin-reconfiguration convention cited in `apply` above.
 - **`-shellcheck=` / `-pyflakes=` are deliberate, and the deadlock claim is a local
   observation.** The hook disables actionlint's external run-block linters primarily for
   edit-time latency; the additional "ShellCheck deadlocks on large blocks under the Windows

plugins/actionlint/skills/setup/evals/evals.json

@@ -72,12 +72,12 @@
       "id": 6,
       "name": "headless-toggle-change-reruns-install-never-uninstalls",
       "prompt": "/actionlint:setup apply — re-enable the hook headlessly by setting actionlint_enabled=true. I cannot use the interactive configure prompt from this session.",
-      "expected_output": "Routes the headless option change to a plain `claude plugin install actionlint@<marketplace> -s <scope> --config actionlint_enabled=true` rerun against the already-installed plugin, refuses the uninstall-and-reinstall route, stamps the claim with the CLI version it was verified against, and closes by re-running the relevant check probe and reporting its actual result.",
+      "expected_output": "Routes the headless option change to a plain `claude plugin install actionlint@<marketplace> -s <scope> --config actionlint_enabled=true` rerun against the already-installed plugin, refuses the uninstall-and-reinstall route, cites the plugin-reconfiguration convention as the owner of the verified-version record, and closes by re-running the relevant check probe in a fresh session and reporting its actual result.",
       "files": [],
       "expectations": [
         "Prescribes a plain `claude plugin install actionlint@<marketplace> -s <scope> --config actionlint_enabled=true` rerun, and states that against an already-installed plugin it prints `already installed` and still writes the value",
         "Never tells the user to run `claude plugin uninstall` in order to reconfigure, and gives the reason: uninstalling drops this plugin's entire stored pluginConfigs entry, resetting every option in the README Options reference table to its manifest default",
-        "Stamps the --config claim with the CLI version it was verified against — Claude Code 2.1.240, a non-sensitive option at user scope — and says the official docs describe --config only as an install-time flag, so the post-install behavior rests on observation, with a sensitive option and project/local scope not covered",
+        "Cites the marketplace's plugin-reconfiguration convention as the owner of the verified-version record for the --config-against-an-installed-plugin claim, rather than stamping a CLI version itself, and directs the operator to rerun check in a fresh session — the rendered value is injected at skill load, so a same-session check still reports the old value",
         "Tells the operator to pass the scope `claude plugin list` reports for this plugin (user, project, or local) and to run from that project's directory for a project or local scope, or the write lands at a scope that does not load",
         "Ends by re-running the relevant check probe and reporting its OBSERVED result, never claiming resolved on the reader's report that they changed the value"
       ]

plugins/ai-briefing/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "ai-briefing",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "description": "Build source-backed AI-industry briefings from official vendor publications, configured RSS/Atom feeds, GitHub releases, reputable secondary reporting, and user-supplied URLs. Deduplicate, rank, and present results as markdown or optional HTML/PPTX decks, with repository-owned profile, audience, and brand configuration. Automated X/Twitter collection is disabled; Playwright is used only for deterministic local rendering.",
   "author": {
     "name": "Melodic Software",

plugins/ai-briefing/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to the `ai-briefing` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.7.10]
+
+### Changed
+
+- `setup` prints the canonical short form of the plugin-reconfiguration guidance and cites the marketplace's plugin-reconfiguration convention as the owner of the verified-version record instead of restating it (#3585, customization-consistency Phase 1d).
+
 ## [0.7.9]
 
 ### Changed

plugins/ai-briefing/skills/setup/SKILL.md

@@ -55,24 +55,19 @@ anything.
    the configured value is wrong for this repository, also report the reconfiguration route:
    - **Interactive, any time:** `/plugin configure ai-briefing@<marketplace>`. The recommended
      route; this skill never writes `pluginConfigs`.
-   - **Headless:** rerun the install with the new value. `claude plugin install
-     ai-briefing@<marketplace> -s <scope> --config active_profile=<name>` (repeatable per key).
-     Against an already-installed plugin it prints `already installed` **and still writes the
-     value**. Verified on Claude Code 2.1.240 (a non-sensitive option at `user` scope: a
-     non-default value written to an installed plugin, then restored). The short-circuit is about
-     the install, not the config write. Re-verify before relying on it outside those conditions.
-     A `sensitive` option, or `project`/`local` scope, were not covered. Do **not** uninstall to
-     reconfigure: uninstalling drops this plugin's entire stored `pluginConfigs` entry, resetting
-     every option in the README's Options reference table to its manifest default. `-s` defaults
-     to `user`, so pass the scope `claude plugin list` reports for this plugin, and run from that
-     project's directory for a `project`/`local` scope, or the write lands at a scope that does
-     not load.
-     Afterwards, keep the two claims apart. The write is issued and the stored value is what you
-     passed; the RUNNING session's behavior is not. The rendered `${user_config.*}` is injected at
-     skill load and each hook receives its `CLAUDE_PLUGIN_OPTION_*` from an environment fixed at
-     session start, so a same-session `check` still reports the OLD value. Reporting that as a
-     failed write would be wrong. Verify the effective value by rerunning `check` in a **fresh
-     session**, and never claim an unobserved change.
+   - **Headless:** rerun the install with the new value, per the marketplace's
+     plugin-reconfiguration convention
+     (<https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/plugin-reconfiguration/README.md>,
+     which owns the verified-version record): `claude plugin install ai-briefing@<marketplace>
+     -s <scope> --config active_profile=<name>` (repeatable per key) — against an
+     already-installed plugin it prints `already installed` **and still writes the value**. Do
+     **not** uninstall to reconfigure: that drops this plugin's entire stored `pluginConfigs`
+     entry, resetting every option in the README's Options reference to its manifest default.
+     `-s` defaults to `user`; pass the scope `claude plugin list` reports for this plugin, and
+     run from that project's directory for a `project`/`local` scope, or the write lands at a
+     scope that does not load. Afterwards rerun `check` in a **fresh session** — the rendered
+     `${user_config.*}` is injected at skill load, so a same-session `check` still reports the
+     OLD value; report the observed effective value, never an unobserved change.
    - **Neither, for a one-off:** a per-run `--profile <name>` selects a different profile without
      touching stored config.
 2. **`sources.md`.** FAIL if the resolved profile has no `sources.md`: `/ai-briefing:generate`

plugins/bash-format/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "bash-format",
-  "version": "0.7.23",
+  "version": "0.7.24",
   "description": "Auto-format and lint shell scripts on edit via shfmt + ShellCheck, using the consuming repo's own .editorconfig and .shellcheckrc.",
   "author": {
     "name": "Melodic Software",

plugins/bash-format/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to the `bash-format` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.7.24]
+
+### Changed
+
+- `setup` prints the canonical short form of the plugin-reconfiguration guidance and cites the marketplace's plugin-reconfiguration convention as the owner of the verified-version record instead of restating it (#3585, customization-consistency Phase 1d).
+
 ## [0.7.23]
 
 ### Changed