[DOCS] Plugin marketplace docs missing ref-tracked plugin re-clone on load behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugin-marketplaces

Section/Topic

"Plugin sources" section where ref and sha fields are defined

Current Documentation

The plugin-marketplaces docs document the ref field as an optional branch/tag specifier:

"Supports ref (branch/tag) but not sha"

The distinction between ref (mutable branch/tag) and sha (pinned exact commit) is explained, but only in terms of version resolution. The docs describe plugins being "copied to a cache" (~/.claude/plugins/cache) with updates detected by version number changes.

No documentation mentions that omitting sha and using only ref changes the runtime fetch behavior to re-clone on every load.

What's Wrong or Missing?

Changelog v2.1.81: "Improved plugin freshness — ref-tracked plugins now re-clone on every load to pick up upstream changes."

This introduces a significant runtime behavior difference between ref-only plugins and sha-pinned plugins:

• ref without sha: Re-clones on every session load to pick up upstream changes
• sha pinned: Uses cached version, only updates when sha changes

Users and plugin authors need to understand this distinction to make informed decisions about pinning vs. tracking.

Suggested Improvement

Add a note to the plugin-marketplaces docs in the "Plugin sources" section where ref and sha are defined:

Note: Plugins using ref without a pinned sha ("ref-tracked plugins") re-clone from the source on every session load to ensure you always have the latest upstream changes. Plugins pinned to a specific sha use the cached version and only update when the sha value changes. Use sha pinning for stability in production environments, or ref tracking for development and frequently updated plugins.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugin-marketplaces | Plugin sources section — ref vs sha field definitions |
| https://code.claude.com/docs/en/plugins-reference | ref field in plugin manifest schema |
| https://code.claude.com/docs/en/settings | ref field in strictKnownMarketplaces / extraKnownMarketplaces |

Total scope: 3 pages affected

Source: Changelog v2.1.81 — "Improved plugin freshness — ref-tracked plugins now re-clone on every load to pick up upstream changes"