[DOCS] plugin-marketplaces.md doesn't document the extraKnownMarketplaces source schema (git/hostPattern/file types missing, "url"/"github" mean something different there)

Start with the plugin-marketplaces documentation page and compare its plugin-entry source table with the extraKnownMarketplaces schema at schemastore.org/claude-code-settings.json. Add a clearly separated table for the six extraKnownMarketplaces source types, including their fields and differing meanings. Done means the page documents git, hostPattern, and file and explicitly distinguishes overlapping url and github types.

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Marketplace sources vs plugin sources / the extraKnownMarketplaces setting

Current Documentation

The page's source-types table and surrounding prose only describe the schema for a plugin entry's source field inside marketplace.json:

"The git-based source types below are github, url, and git-subdir."

url | string | Required. Full git repository URL (https:// or git@)

This table is presented right next to the page's own "Marketplace source vs plugin source" callout, which links extraKnownMarketplaces directly beside it — making it read as if this table is also the reference for extraKnownMarketplaces in settings.json.

What's Wrong or Missing?

extraKnownMarketplaces actually uses a different, undocumented schema from the one on this page. Pulled directly from the current published schema (https://www.schemastore.org/claude-code-settings.json), the real extraKnownMarketplaces source union is:

• url — direct HTTP(S) URL to a marketplace.json file (format: uri, no git involved)
• git — full git-clone of a repo (git@/SSH and https:// remotes both work here)
• github — owner/repo shorthand (different field shape than the plugin-entry github type)
• hostPattern — trust a git host pattern
• npm — package containing marketplace.json
• file — local path to marketplace.json

None of git, hostPattern, or file appear anywhere on the docs page. Worse, url and github do appear, but with different meaning and shape than the plugin-entry version of those same names — url here is a plain file fetch, not a git-based source at all, despite sitting directly under a section titled "the git-based source types."

This tripped me up in practice: I had "source": "git" with a git@host:path.git SSH URL in extraKnownMarketplaces, which works correctly, but it looked wrong against this page since "git" isn't listed as a valid type anywhere. Meanwhile "url" looked like it should accept the same SSH syntax per its description here — but url under extraKnownMarketplaces can't clone a repo at all, it only fetches a static file over HTTP(S).

Suggested Improvement

Add a clearly-separated section (or its own page) documenting the extraKnownMarketplaces source schema on its own terms, distinct from the plugin-entry source table — ideally with its own table:

And note explicitly that this schema is not the same as the plugin-entry source schema documented above it, even though some type names overlap.

Impact

Medium - Makes feature difficult to understand

Additional Context

Related: #77315 (same extraKnownMarketplaces → git source schema area, different specific defect — a stale .git$ suffix pattern requirement, confirmed by a maintainer as a stale-schema issue rather than a doc issue). Not a duplicate, just adjacent.