[DOCS] Plugin marketplace docs omit automatic `renames` handling

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Marketplace file schema, plugin updates, and renamed plugins.

Current Documentation

The plugin marketplace guide currently introduces marketplace files as:

Create .claude-plugin/marketplace.json in your repository root. This file defines your marketplace's name, owner information, and a list of plugins with their sources.

The settings page describes marketplace refresh behavior:

Each marketplace entry also accepts an optional autoUpdate Boolean. Set "autoUpdate": true alongside source to make Claude Code refresh that marketplace and update its installed plugins at startup.

The discover page explains how users install from a marketplace:

To install a plugin from the official marketplace, use /plugin install <name>@claude-plugins-official.

What's Wrong or Missing?

Claude Code v2.1.193 improved plugin auto-rename behavior so marketplace renames maps are followed automatically and user settings are updated to the new plugin name.

The current docs do not mention:

• a renames field in marketplace.json
• the expected source and target format for rename entries
• how installed plugin IDs in enabledPlugins are updated
• what happens when a marketplace renames a plugin that users have installed
• how marketplace maintainers should publish a rename without breaking users

This leaves both marketplace authors and users without guidance for a supported migration path.

Suggested Improvement

Document the marketplace renames map in the marketplace schema/reference.

Suggested minimum addition:

Marketplaces can include a renames map to move users from an old plugin name to a new plugin name. During marketplace refresh/update, Claude Code follows the rename and updates settings entries such as enabledPlugins from the old <plugin>@<marketplace> ID to the new one.

Include a small JSON example and note whether rename targets can cross marketplaces or only point to another plugin in the same marketplace.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugin-marketplaces | Marketplace schema and update guidance omit renames |
| https://code.claude.com/docs/en/discover-plugins | User-facing install/update docs do not explain renamed installed plugins |
| https://code.claude.com/docs/en/settings | Plugin settings describe enabledPlugins IDs but not automatic migration when a marketplace rename is followed |

Total scope: 3 pages affected

Version context: Claude Code v2.1.193 release note: "Improved plugin auto-rename: marketplace renames maps are now followed automatically, updating your settings to the new name."