[DOCS] [Plugins] `claude plugin install` should document auto-refresh and retry behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/plugins-reference#plugin-install

Section/Topic

CLI reference section for plugin install — the command description and error behavior

Current Documentation

The CLI reference for plugin install reads:

Install a plugin from available marketplaces. ``bash claude plugin install <plugin> [options] ` **Arguments:** * <plugin>: Plugin name or plugin-name@marketplace-name` for a specific marketplace

No mention of auto-refresh, retry, or error recovery behavior.

Separately, discover-plugins.md line 39 says:

If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run /plugin marketplace update claude-plugins-official to refresh it, or /plugin marketplace add anthropics/claude-plugins-official if you haven't added it before. Then retry the install.

This describes the manual workflow, which v2.1.139 now automates.

What's Wrong or Missing?

A. Missing auto-refresh documentation in CLI reference

The plugin install CLI reference does not document that the command now automatically refreshes the named marketplace and retries the install before reporting "plugin not found." Users reading the docs have no way to know this behavior exists.

B. Outdated troubleshooting guidance

discover-plugins.md still instructs users to manually run /plugin marketplace update when they see "not found." This was accurate before v2.1.139, but the install command now handles this automatically in most cases. The guidance is not wrong (manual refresh still works as a fallback), but it overstates the need for manual intervention.

Suggested Improvement

In plugins-reference.md, add a note under plugin install describing the auto-refresh behavior, for example:

If the plugin is not found, Claude Code automatically refreshes the marketplace and retries once before reporting that the plugin is not available. To manually refresh a marketplace, use claude plugin marketplace update <marketplace-name>.

In discover-plugins.md (line 39), update the troubleshooting note to reflect the new behavior:

If Claude Code reports that the plugin is not found in any marketplace after an auto-refresh, your marketplace may be missing or outdated. Run /plugin marketplace update <marketplace-name> to refresh it manually, or /plugin marketplace add <source> to add a new one.

Or remove the manual-refresh instruction entirely if the auto-refresh is expected to handle all normal cases.

Impact

Medium - Makes feature difficult to understand

Additional Context

Changelog evidence (v2.1.139):

claude plugin install <name>@<marketplace> now auto-refreshes the marketplace and retries before reporting a plugin as not found

Related changelog fixes showing this is a recurring pain point:

• v2.1.0 (changelog line 1443): "Fixed plugins showing 'not found in marketplace' errors on fresh startup by auto-refreshing after marketplace installation"
• These entries show users repeatedly encountered "not found" errors due to stale marketplace cache, and the team has been progressively improving the experience.

Affected Pages:
| Page | Issue |
|------|-------|
| https://code.claude.com/docs/en/plugins-reference | Missing auto-refresh behavior for plugin install |
| https://code.claude.com/docs/en/discover-plugins | Line 39 describes manual refresh as required, which is no longer the primary workflow |