fix(setup): unstamped `--config` claim prescribes a destructive reinstall across 18 setup skills

[kyle-sexton]

Problem

scripts/sync-plugin-options-docs.py:93 generates route 2 as "Headless, at install time", and 18 setup skills carry a stronger, load-bearing form of the same premise:

Headless: --config only applies on a fresh install (ignored once installed), so reconfigure via claude plugin uninstall <p> -s <scope> then claude plugin install <p>@<mkt> -s <scope> --config KEY=VALUE

That premise does not hold on Claude Code 2.1.240. Verified by writing an arbitrary non-default value to an already-installed plugin and restoring it:

BEFORE  {"options":{"settings_write_ask_enabled":true}}
$ claude plugin install context-budget@melodic-software -s user --config settings_write_ask_enabled=false
  ✔ Plugin "context-budget@melodic-software" is already installed (scope: user)
        {"options":{"settings_write_ask_enabled":false}}
$ claude plugin install context-budget@melodic-software -s user --config settings_write_ask_enabled=true
AFTER   {"options":{"settings_write_ask_enabled":true}}

This rules out both "it only worked because the value equalled the manifest default" and "it only worked because the key was absent".

Why it matters

The prescribed uninstall drops the entire pluginConfigs entry. Following that guidance resets 34 options on source-control, 20 on guardrails, 14 on claude-ops. The claude-ops setup skill documents that hazard at length — a hazard the working route makes unnecessary.

Framing

The claim landed 2026-07-18 in fe28ffa70 ("adopt the uniform setup contract across 17 shape-B plugins", #360) via template sweep, carrying no version stamp. CC 2.1.221 changed install-activation behaviour in this area, so "always false" and "true when written, fixed since" are not distinguishable from available evidence — and need not be.

The defect is: an unversioned harness claim, propagated by template to 18 skills, prescribing a destructive path for a case where the safe route demonstrably works. Remediation is to correct and stamp, matching the house style already used in plugins/claude-ops/skills/plugins/context/scope-semantics.md ("Empirically verified on Claude Code 2.1.228").

Also in scope

• Coverage rule — declares userConfig ⇒ ships a setup skill. Three violations: context-budget, repo-hygiene, visualization.
• Verify-it-landed — the setup contract's apply should read back the effective value after routing a reconfiguration rather than claiming an unobserved change. 34 setup skills reference pluginConfigs already, but none asserts post-write.

Motivating incident: three consecutive /plugin configure context-budget@melodic-software attempts on 2.1.240 returned No configuration changes., (no content), Configuration cancelled. and persisted nothing, with no error surfaced. Related upstream issues (anthropics/claude-code#51538, #52724, #46477) are all closed, and #52724's one named user-side cause — a custom ~/.claude/keybindings.json — did not apply.

Related

No linked issue.

[kyle-sexton]

Correction to this issue's provenance claim — the origin commit I cited is wrong.

This issue attributes the "--config only applies on a fresh install" claim to fe28ffa70 (2026-07-18, #360, "adopt the uniform setup contract across 17 shape-B plugins"). A fresh-context verifier working #3139 found that is where the claim spread, not where it originated, and I re-derived it independently:

$ git log -1 --format='%h %ad %s' --date=short eefcbb1a2
eefcbb1a2 2026-07-11 docs(playbook): codify extensibility contract v2.1 and record smoke tests (#81)

$ git show eefcbb1a2:docs/extensibility-contract-smoke-tests.md | grep -n 'fresh install'
21:`--config` is applied only on a fresh install (Test C), so uninstall before each run and read the
110:  flow"). It applies **only on a fresh install** — `--config` is ignored once the plugin is already

$ for rev in eefcbb1a2 fe28ffa70~1 fe28ffa70 origin/main; do
    git grep -l "fresh install" $rev -- 'plugins/*/skills/setup/SKILL.md' | wc -l; done
eefcbb1a2    0
fe28ffa70~1  9
fe28ffa70   14
origin/main 24

So the actual history is: the claim was born in docs/ at eefcbb1a2 (#81, 2026-07-11) as an inference from Test C, reached zero setup skills at that point, then propagated into setup skills — 9 already carried it before fe28ffa70, which took it to 14. It stands at 24 on main today, across 48 setup skills.

Two things follow:

1. The unstamped-claim framing gets stronger, not weaker. The claim did not start as boilerplate in a template sweep; it started as a documented inference from a real smoke test, and then propagated outward into skills over two weeks. That is precisely why fix(docs): setup-contract drift — unstamped --config claim in three docs, no SSOT for the contract, stale PR-section config #3127 item 2 — the setup contract having no single source of truth — is the load-bearing fix rather than a tidy-up. The docs were the origin.
2. Do not reuse the number 25 for feat: adopt the uniform setup contract across 17 shape-B plugins #360's scope. 25 is the scope of the correction campaign (fix(setup): unstamped --config claim prescribes a destructive reinstall across 18 setup skills #3111 / fix(plugins): correct the unstamped --config reconfiguration claim (#3111) #3115). The feat: adopt the uniform setup contract across 17 shape-B plugins #360 figure is 14 (from 9), and fe28ffa70 touches 17 setup SKILL.md files, matching its own subject line. The two numbers were conflated once already in fix(docs): correct setup-contract drift in docs and tracked PR config #3139 and caught by its verifier.

Nothing else in this issue changes — the empirical result on 2.1.240, the reset-hazard severity, and the remediation shape are unaffected.