[DOCS] Plugins reference does not document MCPB plugin cache invalidation and re-extraction behavior on Windows

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Plugin caching and file resolution" section, specifically the behavior of MCPB-typed plugins on Windows (the "Unrecognized fields" subsection is the only place that even names "MCPB").

Current Documentation

The "Plugin caching and file resolution" section currently says only:

For security and verification purposes, Claude Code copies marketplace plugins to the user's local plugin cache (~/.claude/plugins/cache) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files. Each installed version is a separate directory in the cache. When you update or uninstall a plugin, the previous version directory is marked as orphaned and removed automatically 7 days later. The grace period lets concurrent Claude Code sessions that already loaded the old version keep running without errors. ### Path traversal limitations Installed plugins cannot reference files outside their directory. Paths that traverse outside the plugin root (such as ../shared-utils) will not work after installation because those external files are not copied to the cache.

MCPB is only mentioned in passing, in the "Unrecognized fields" subsection, as a manifest format that the same plugin.json can double as:

This makes it practical to maintain one manifest that doubles as a VS Code or Cursor extension manifest, an npm package.json, or an MCPB/DXT bundle manifest.

The page does not describe what an MCPB bundle is, how it differs from a normal marketplace plugin in terms of caching, or what the re-extraction step does. The CLAUDE_CODE_PLUGIN_CACHE_DIR and CLAUDE_CODE_PLUGIN_SEED_DIR environment variables in env-vars.md likewise do not mention MCPB-specific behavior or Windows.

The release notes for v2.1.169 record a fix to the behavior, but the surrounding documentation never establishes the underlying Windows behavior users could have observed before the fix.

What's Wrong or Missing?

A. MCPB bundle format is undefined in the plugins reference

"MCPB" appears once in plugins-reference.md, only as an example of an unrelated manifest format. Plugin authors reading the plugins reference have no way to learn what an MCPB bundle is, how it gets installed into the plugin cache, or why a separate "extraction" step is mentioned in the changelog.

B. No description of plugin cache re-extraction on Windows

The "Plugin caching and file resolution" section describes copy-into-cache and orphan cleanup, but never explains that some plugin types (MCPB) are extracted rather than just copied, and never mentions the Windows-specific invalidation path. Users on Windows who upgraded through v2.1.168 would have seen spurious re-extraction on every session start, with no documentation that points them at the cause or the fix.

C. No platform-conditional cache behavior is documented

The section treats the plugin cache as if it behaves identically on every platform. The "Share files within a marketplace with symlinks" subsection does call out a Windows-specific mklink /D note, but only for symlinks. There is no comparable Windows note for cache invalidation or extraction, and no cross-reference between the cache section and the env-vars entries that govern the cache root.

Suggested Improvement

Add a short subsection inside "Plugin caching and file resolution" (or a new "Platform-specific cache behavior" subsection) that documents the MCPB extraction path and the prior Windows invalidation behavior, then add a v2.1.169 note that the spurious invalidation is fixed. Concretely:

Additions after the existing "Path traversal limitations" subsection:

### MCPB bundle extraction

Plugins distributed as MCPB bundles (`.mcpb` archives) are extracted into the
plugin cache on install, rather than copied as plain files. The extracted
directory is the versioned cache entry, and re-extraction happens only when
the bundle itself changes or when the cache entry is invalidated.

On Windows, prior to v2.1.169 the cache key could be invalidated on every
session start, which forced an unnecessary re-extraction step on each launch.
v2.1.169 corrects the invalidation check; Windows users who upgrade no
longer pay the re-extraction cost when the bundle is unchanged.

For the cache root and seed directory, see
`CLAUDE_CODE_PLUGIN_CACHE_DIR` and `CLAUDE_CODE_PLUGIN_SEED_DIR` in the
environment variables reference.

Suggested edit to the "Unrecognized fields" subsection (where MCPB is first named):

Before:

...or an MCPB/DXT bundle manifest.

After:

...or an MCPB/DXT bundle manifest. See [Plugin caching and file resolution](#plugin-caching-and-file-resolution) for how MCPB bundles are extracted into the cache and how Windows users were affected by the v2.1.168-era invalidation bug.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugins-reference | 459, 704-737 | "Unrecognized fields" example and "Plugin caching and file resolution" section are the only references to MCPB; the cache section omits MCPB extraction and Windows behavior |
| https://code.claude.com/docs/en/env-vars | 219, 223 | CLAUDE_CODE_PLUGIN_CACHE_DIR and CLAUDE_CODE_PLUGIN_SEED_DIR do not mention MCPB extraction or platform-specific cache invalidation |
| https://code.claude.com/docs/en/changelog | 28 | v2.1.169 fix is the only place that names the behavior |

Total scope: 3 pages affected.

Version note: v2.1.169 is the first release that stops the spurious Windows invalidation. The fix is recorded in the changelog but is not cross-referenced from the plugins reference, the env-vars reference, or any troubleshooting page, so users investigating MCPB behavior on Windows cannot trace the fix to its description.