[DOCS] Plugin reference does not document that project `pluginConfigs` are ignored

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The userConfig section that explains where non-sensitive plugin option values are stored, plus the plugin rename migration guidance.

Current Documentation

The plugin reference currently says:

“Non-sensitive values are stored in settings.json under pluginConfigs[<plugin-id>].options.”

The plugin marketplace guide also says that a rename:

“rewrites the old key to the new key in the user, project, and local settings scopes for both enabledPlugins and pluginConfigs”

What's Wrong or Missing?

Claude Code v2.1.207 changed plugin option loading so pluginConfigs values are no longer read from project-level .claude/settings.json. Only user settings, the --settings layer, and managed settings are honored.

The current reference presents settings.json as if any settings scope can provide plugin option values, and the rename guidance lists project settings as an active pluginConfigs scope without explaining the new restriction. A team that commits plugin options to .claude/settings.json can therefore believe the plugin is configured when Claude Code silently ignores those values.

Suggested Improvement

Document the exact supported scopes in the userConfig section: user settings, inline --settings, and managed settings. Explicitly state that project-level .claude/settings.json is not a supported source for pluginConfigs values as of Claude Code v2.1.207, and explain the security or trust rationale if applicable.

Update the rename section so it distinguishes key migration from runtime loading: if project and local keys are still rewritten for compatibility, say that clearly and explain which rewritten scopes are actually read. Add a short migration example showing where a user or administrator should move existing plugin option values.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | Storage statement for pluginConfigs[<plugin-id>].options does not identify supported scopes |
| https://code.claude.com/docs/en/plugin-marketplaces | Plugin rename guidance lists project pluginConfigs as an active scope without the v2.1.207 restriction |
| https://code.claude.com/docs/en/settings | Plugin configuration overview does not explain the supported pluginConfigs scope policy |

Total scope: 3 pages affected

Source: Claude Code v2.1.207

Plugin option values (pluginConfigs) are no longer read from project-level .claude/settings.json; only user, --settings, and managed settings are honored