docs(building-plugins): document npm plugin sources

[factory-davidgu]

Documents the new npm plugin source type for marketplace manifests in guides/building/building-plugins.mdx.

What changed

• Added a new Plugin sources subsection under Distributing plugins -> Creating a marketplace, summarizing the supported plugin source types (relative path, github, url, git-subdir, npm).
• Added a focused npm packages subsection covering:
  • Minimal, version-pinned, and private-registry examples
  • Field reference (package, version, registry)
  • Published package layout requirements (Droid + Claude Code formats both accepted; Claude format translated at install)
  • Recommended package.json files configuration
  • Install-time hardening (--ignore-scripts, scratch-scoped .npmrc)
• Added a Wrapper marketplace snippet showing how to ship a single npm-published plugin without standing up a full marketplace repo, including a CLI quick start.
• Called out that npm: is not a valid marketplace source.

Notes

• All examples use placeholder identifiers (@your-org/droid-pr-triage, your-org-plugins, https://npm.your-org.example). No real published packages are referenced.
• The companion runtime change lives in factory-mono on dgu/npm-marketplace.

[factory-droid]

Droid finished @factory-davidgu's task —— View job

---

Review summary

Solid, detailed docs for the new npm plugin source. A couple small clarifications around pinning/versioning semantics across source types will prevent readers from applying the marketplace (git commit hash) guidance to npm-based installs.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
factory	🟢 Ready	View Preview	Jun 13, 2026, 1:00 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[factory-droid]

[P1] Resolve pinning guidance ambiguity across source types

The new Plugin sources table lists per-plugin ref/sha for git-based sources, but the Version management note later says pinning a plugin requires pinning the marketplace, which is only true for relative-path plugins. This internal contradiction can mislead readers about how to pin plugins depending on the source type.

Suggested change

Each plugin entry's `source` field tells Droid where to fetch the plugin from. The default form, a relative path string like `"./plugin-one"`, points at a directory inside the marketplace repository. For plugins that live elsewhere, use a source object.

Each plugin entry's `source` field tells Droid where to fetch the plugin from. The default form, a relative path string like "./plugin-one", points at a directory inside the marketplace repository. For plugins that live elsewhere, use a source object. Pinning behavior depends on the source type: git-based sources can be pinned per-plugin (via `ref`/`sha` when supported), while relative-path plugins are pinned by pinning the marketplace source.

[factory-droid]

[P1] Clarify npm versioning vs git commit-hash note

This PR adds npm version (semver ranges and dist-tags) for plugin sources, but the Version management note later states Droid tracks plugin versions by Git commit hash, which can be read as contradicting npm-based installs. A short clarification here helps readers understand that the git commit-hash guidance applies to git-based sources, while npm sources follow npm version resolution.

Suggested change

Distribute plugins as npm packages when you already ship to a private registry (Artifactory, CodeArtifact, GitHub Packages, Verdaccio, and so on) and want to reuse that channel for your Droid plugins. Public packages on the npm registry work the same way.

Distribute plugins as npm packages when you already ship to a private registry (Artifactory, CodeArtifact, GitHub Packages, Verdaccio, and so on) and want to reuse that channel for your Droid plugins. Public packages on the npm registry work the same way. For npm sources, pinning and updates follow npm version resolution via the `version` field (the git commit-hash guidance in [Version management](#version-management) applies to git-based sources).

[factory-ain3sh]

pls address review droid feedback before merging