fix: clarify userConfig option copy shown at install

[KSEGIT]

What

Rewrites the title and description for both userConfig options in .claude-plugin/plugin.json — the two prompts a user sees during /plugin install version-sentinel.

Each description now leads with its default, states what flipping it actually does, and gives a reason to change it.

Why

The old copy described internals rather than behavior, and neither option stated its default in the text:

• disable was titled "Disable blocking" and described as "all version-sentinel hooks no-op (PreToolUse block, SessionStart prereq warning, PostToolUse auto-record)". That's a parenthetical list of hook names — it reads as if it only relaxes blocking, when it in fact disables the whole plugin, auto-recording included. It also omitted that a VS_DISABLE shell variable takes precedence (scripts/lib/options.sh:6-12 only maps the plugin option when VS_DISABLE is unset, so VS_DISABLE=0 in the environment pins the guardrail on and makes the toggle a no-op).
• window_hours said only "How long a /vs-record entry stays fresh before the hook re-blocks" — it never said what re-blocking costs you (re-verifying against the registry) or how to choose a value.

Scope

Copy only. No schema key, type, default, min, or max changed — verified in the diff.

Typed as fix: rather than docs: so release-please cuts a patch release; otherwise the improved copy never reaches installed users, since the manifest only ships via a tagged release.

Verification

$ jq empty .claude-plugin/plugin.json
JSON VALID
disable: default=false title="Turn off Version Sentinel (kill switch)"
window_hours: default=24 title="How long a recorded version check stays valid (hours)"

$ bash tests/run.sh
Total: 26, Failed: 0     (plus 4/4 integration smoke)

No test asserts on these strings, so none needed updating.

Follow-up, not in this PR

Root plugin.json and .claude-plugin/plugin.json have drifted: different description, root carries an extra supply-chain-security keyword, and root has no userConfig block at all. Claude Code reads .claude-plugin/, so the options work today, but any consumer reading the root manifest sees a different plugin.

🤖 Generated with Claude Code

https://claude.ai/code/session_0118eLJLbPbqYXiPc8R9AAiJ

Summary by CodeRabbit

• Documentation
  • Clarified the disable switch’s default behavior, bypassed checks, temporary-use guidance, and override option.
  • Documented the version-check freshness window, including its default value, limits, record command behavior, expiration handling, and tradeoffs.

[coderabbitai]

📝 Walkthrough

Walkthrough

The plugin configuration descriptions now document the disable switch and version-check freshness window. The descriptions include defaults, overrides, bounds, expiration behavior, and operational tradeoffs.

Changes

Configuration Documentation

Layer / File(s)	Summary
Configuration option descriptions .claude-plugin/plugin.json	The disable option documents its default behavior, skipped guardrails, temporary use, and VS_DISABLE override. The window_hours option documents its default, bounds, validity period, expiration behavior, and lookup tradeoffs.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Poem

A rabbit read the settings bright,
The switch now tells when guards take flight.
The window shows its time and bounds,
With fresh checks hopping through the rounds.
Clearer words now guide the way.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the clarified userConfig copy shown during installation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude-plugin/plugin.json:
- Line 31: Update the description value for the disable setting to state that
only a non-empty VS_DISABLE value set in the shell overrides disable, replacing
the broader wording while preserving the rest of the description.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 24e3d77e-c7ba-48da-96fa-0cf6516d10ba

📥 Commits

Reviewing files that changed from the base of the PR and between bc19765 and fb526d8.

📒 Files selected for processing (1)

• .claude-plugin/plugin.json

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Clarify that only a non-empty VS_DISABLE value overrides disable.

scripts/lib/options.sh:6-12 treats an empty VS_DISABLE value as unset. Replace “A VS_DISABLE variable set in your shell” with “A non-empty VS_DISABLE value set in your shell” to match the actual precedence behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude-plugin/plugin.json at line 31, Update the description value for the
disable setting to state that only a non-empty VS_DISABLE value set in the shell
overrides disable, replacing the broader wording while preserving the rest of
the description.