[DOCS] `--plugin-dir` docs still describe directory-only input after v2.1.128 added `.zip` plugin archives

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

--plugin-dir in the CLI flags reference, plus related --plugin-dir guidance in Headless mode and plugin development docs

Current Documentation

The docs currently say:

--plugin-dir | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: --plugin-dir A --plugin-dir B

The related pages use the same directory-only wording:

| A plugin directory | --plugin-dir <path> |

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

What's Wrong or Missing?

In v2.1.128, --plugin-dir now accepts .zip plugin archives in addition to directories, but the current documentation still describes the flag as directory-only input.

That leaves the CLI reference and supporting plugin docs outdated in two ways:

A. The accepted argument type is described too narrowly

Users are told the flag loads plugins from "a directory" and the Headless page labels it as "A plugin directory," which no longer matches the current behavior.

B. There is no .zip archive example anywhere in the related docs

The docs do not show that --plugin-dir can point to a packaged .zip plugin archive, so users have no discoverable example for the new input form.

Suggested Improvement

Update the directory-only wording anywhere --plugin-dir is described.

Before:

Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: --plugin-dir A --plugin-dir B

After:

Load plugins from a directory or .zip plugin archive for this session only. Each flag takes one path. Repeat the flag for multiple plugins, for example: --plugin-dir ./my-plugin --plugin-dir ./dist/my-plugin.zip

Also update the Headless table row from "A plugin directory" to "A plugin directory or .zip plugin archive," and add at least one plugin-doc example that shows a .zip archive path.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/cli-reference | 86 | --plugin-dir says it loads plugins from a directory and repeats for multiple directories |
| https://code.claude.com/docs/en/headless | 57 | Bare-mode flag table labels the input as "A plugin directory" |
| https://code.claude.com/docs/en/plugins | 118-121, 296-315 | Plugin testing examples only show directory paths and repeated directory flags |
| https://code.claude.com/docs/en/plugins-reference | 606-609 | Plugin loading modes mention claude --plugin-dir but do not mention .zip archives |

Total scope: 4 pages affected

The changelog entry for v2.1.128 says --plugin-dir now accepts .zip plugin archives in addition to directories, so the current directory-only wording appears outdated across the main CLI and plugin docs.