track: npm-tarball-docs-20260408

[amondnet]

---

product_spec_domain: cli/sources

npm tarball docs (dist/docs) utilization

Track: npm-tarball-docs-20260408

Overview

Some npm packages (ai, @mastra/core, @mastra/memory, etc.) ship dist/docs/ inside their tarball. This source is preferable to GitHub because it (1) matches the installed version 1:1, (2) is already present in node_modules for instant offline reads, and (3) was deliberately curated by the author for agent consumption. However, there is no standard field/path convention, so reliable CLI auto-detection is not feasible.

This track solves the problem with a 2-tier strategy:

• Tier 1 (Fast Path): Explicitly register an npm strategy with docsPath in the ASK Registry. CLI executes deterministically.
• Tier 2 (Discovery Path): For packages not in the Registry, the generated *-docs skill includes a fallback guide instructing the agent (LLM) to walk node_modules at runtime and read docs.

Additionally, the CLI's npm source is improved to prefer the local node_modules over a tarball download. A telemetry-driven Registry auto-promotion mechanism is left as a design document only (implementation deferred to a follow-up track). Reference prior art: https://github.com/vercel-labs/skills/blob/main/src/telemetry.ts

Requirements

Functional Requirements

• FR-1: Extend the Registry strategy union in apps/registry/content.config.ts with an npm type that supports a docsPath field (e.g. { type: 'npm', docsPath: 'dist/docs' }).
• FR-2: Add seed Registry entries: vercel/ai, mastra-ai/mastra (with @mastra/core, @mastra/memory aliases).
• FR-3: packages/cli/src/sources/npm.ts MUST first probe node_modules/<pkg>/package.json of the current project; when the version matches and <docsPath> exists, read locally and return.
• FR-4: Fall back to tarball download only on local miss, applying the same docsPath rule.
• FR-5: In packages/cli/src/resolvers/npm.ts, when the Registry specifies an npm strategy, do NOT delegate to GitHub — invoke the npm source directly.
• FR-6: The SKILL.md template generated by packages/cli/src/skill.ts MUST include a "When the docs cannot be found" fallback section guiding the agent to walk node_modules/<pkg>/{dist/docs,docs,*.md}.
• FR-7: When the Tier 2 fallback discovers usable docs, it MUST suggest formal registration via ask docs add npm:<pkg>.
• FR-8: Document the telemetry-driven Registry auto-promotion design (opt-in model, collected fields, aggregation flow, privacy considerations) in design/telemetry.md. Reference and analyze https://github.com/vercel-labs/skills/blob/main/src/telemetry.ts. Code changes are out of scope.

Non-functional Requirements

• NFR-1: The local node_modules read path MUST return the same FetchResult { files, resolvedVersion } shape as the tarball path (output pipeline compatibility).
• NFR-2: The local-preferred path MUST NOT make any network calls (offline / CI friendly).
• NFR-3: Tier 1 and Tier 2 MUST NOT break existing ask docs add UX and MUST NOT introduce new required flags.

Acceptance Criteria

• AC-1: A vercel/ai Registry entry exists with the npm strategy (docsPath: 'dist/docs'), and ask docs add npm:ai collects docs from npm tarball / node_modules dist/docs rather than GitHub.
• AC-2: When the project already has ai installed, running ask docs add npm:ai makes no HTTP call to the npm registry.
• AC-3: The same flow succeeds for @mastra/core and @mastra/memory (scoped packages with monorepo subpaths).
• AC-4: For an arbitrary package not in the Registry, the generated *-docs skill contains a fallback section that clearly tells the agent how to walk node_modules.
• AC-5: design/telemetry.md exists and covers the opt-in activation model, the collected fields (package name, version, docsPath, success flag), the aggregation and promotion flow, and privacy / rate-limit considerations, plus an analysis of the vercel-labs/skills reference.
• AC-6: Existing Registry entries that use the GitHub source path keep working with no regression.

Out of Scope

• Telemetry collection server / endpoint implementation (separate track).