Convention-based Docs Discovery
Track: convention-based-discovery-20260409
Type: refactor
Overview
The CLI currently requires every library to be manually curated into the
central registry (ask-registry.pages.dev) before ask docs add can fetch
its documentation. This is the root cause of the recent production hang
(Nuxt Content + D1 subrequest-limit deadlock) and a hard ceiling on how
fast the project can grow its library coverage.
Most OSS libraries already place their docs under a small set of
conventional paths — docs/, website/docs/, apps/docs/,
src/content/docs/, dist/docs/, etc. If the CLI scans those paths
first, the vast majority of popular packages resolve automatically with
no registry entry. At the same time, TanStack Intent-compatible packages
(package.json.keywords contains tanstack-intent + skills/**/SKILL.md)
get discovered via @tanstack/intent's programmatic API and wired
through Intent's native installation model, so ask docs add and
bunx @tanstack/intent install produce identical AGENTS.md results
and remain interchangeable.
The central registry is not removed — its role narrows from "source of
truth for every library" to "override layer for libraries with
non-conventional layouts or alias mappings". This unblocks growth
without another deploy-time D1 sync.
Scope
In scope
Discovery pipeline (packages/cli/src/discovery/)
New adapter layer. Each adapter is independently testable and can be
swapped without touching the CLI dispatcher.
Adapters (ordered, first non-null wins):
- Local ASK self-declare — reads
package.json.ask.docsPath from
the installed package. Lets library authors opt in without a registry
entry and without following a convention.
- Local TanStack Intent — wraps
@tanstack/intent's scanLibrary,
findSkillFiles, and parseFrontmatter to discover Intent-shaped
packages. Only read-path APIs are used; no Intent writing APIs.
- Local convention scan — checks
node_modules/<pkg>/ for
dist/docs/, docs/, and README.md in that order.
- Central registry lookup — the existing
resolveFromRegistry
path, now demoted to "fallback when no local signal".
Convention-based Docs Discovery
Overview
The CLI currently requires every library to be manually curated into the
central registry (
ask-registry.pages.dev) beforeask docs addcan fetchits documentation. This is the root cause of the recent production hang
(Nuxt Content + D1 subrequest-limit deadlock) and a hard ceiling on how
fast the project can grow its library coverage.
Most OSS libraries already place their docs under a small set of
conventional paths —
docs/,website/docs/,apps/docs/,src/content/docs/,dist/docs/, etc. If the CLI scans those pathsfirst, the vast majority of popular packages resolve automatically with
no registry entry. At the same time, TanStack Intent-compatible packages
(
package.json.keywordscontainstanstack-intent+skills/**/SKILL.md)get discovered via
@tanstack/intent's programmatic API and wiredthrough Intent's native installation model, so
ask docs addandbunx @tanstack/intent installproduce identicalAGENTS.mdresultsand remain interchangeable.
The central registry is not removed — its role narrows from "source of
truth for every library" to "override layer for libraries with
non-conventional layouts or alias mappings". This unblocks growth
without another deploy-time D1 sync.
Scope
In scope
Discovery pipeline (
packages/cli/src/discovery/)New adapter layer. Each adapter is independently testable and can be
swapped without touching the CLI dispatcher.
Adapters (ordered, first non-null wins):
package.json.ask.docsPathfromthe installed package. Lets library authors opt in without a registry
entry and without following a convention.
@tanstack/intent'sscanLibrary,findSkillFiles, andparseFrontmatterto discover Intent-shapedpackages. Only read-path APIs are used; no Intent writing APIs.
node_modules/<pkg>/fordist/docs/,docs/, andREADME.mdin that order.resolveFromRegistrypath, now demoted to "fallback when no local signal".