[DOCS] Plugin docs omit `--plugin-dir` precedence over installed marketplace plugins

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Same-name precedence between local --plugin-dir plugins and installed marketplace plugins.

Current Documentation

The local plugin testing docs currently say:

Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation.

The CLI reference says:

| --plugin-dir | Load plugins from directories for this session only (repeatable) |

The plugin reference says:

Plugins are specified in one of two ways: Through claude --plugin-dir, for the duration of a session. Through a marketplace, installed for future sessions.

The managed-settings docs separately say:

No other settings level can override them, including command line arguments.

No documentation currently explains what happens when a local plugin loaded with --plugin-dir has the same name as an installed marketplace plugin, or why managed force-enabled plugins are an exception.

What's Wrong or Missing?

Release v2.1.74 changed same-name precedence so local dev copies loaded with --plugin-dir override installed marketplace plugins for that session, unless the installed plugin is force-enabled by managed settings.

This is important behavior for plugin development, debugging, and enterprise-managed environments, but current docs do not describe it.

Suggested Improvement

Add a note under local plugin testing and CLI docs that explains:

1. Same-name --plugin-dir plugins override installed marketplace plugins for the current session.
2. This is the recommended way to shadow an installed plugin during development.
3. Managed force-enabled plugins are the exception.
4. A short example showing local development against an already-installed plugin.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugins | 278-295 | --plugin-dir local testing docs omit same-name precedence |
| https://code.claude.com/docs/en/cli-reference | 69 | Flag description says session-only, but not how conflicts are resolved |
| https://code.claude.com/docs/en/plugins-reference | 381-386 | Plugin source modes are distinguished, but same-name resolution is not documented |
| https://code.claude.com/docs/en/server-managed-settings | 90-92 | Managed settings precedence explains why force-enabled plugins are the exception |

Total scope: 4 pages affected

Source: Release v2.1.74

• Changed --plugin-dir so local dev copies now override installed marketplace plugins with the same name (unless that plugin is force-enabled by managed settings)