@numbered/docs-to-context

Extract component APIs, design system docs, best practices, and architecture specs into structured references and inject a compact index into CLAUDE.md — so AI agents always know what's available without hallucinating.

Usage

bunx @numbered/docs-to-context

Run from the project root. Auto-detects platform (Next.js or Shopify).

Options

bunx @numbered/docs-to-context [project_root] [options]

--platform nextjs|shopify   Force platform detection
--dirs dir1 dir2            Custom scan directories (Next.js only)
--output path               Custom output directory

Output

  @numbered/docs-to-context
  ─────────────────────

  Extract
  ● Platform: nextjs
  ✓ Extracted 74 components
    /path/to/project/.context/components

  Inject
  ✓ Copied 1 best practice doc(s)
  ● Found 15 core doc(s)
  ✓ Injected index into CLAUDE.md

  Done.

What it does

1. Extracts component APIs from source files into per-component docs at .context/components/
2. Copies platform-specific best practice docs to .context/best-practices/
3. Discovers core docs if present (design system, grid system, architecture specs)
4. Injects a compact index between <!-- PROJECT_DOCS_START --> / <!-- PROJECT_DOCS_END --> markers in CLAUDE.md
5. Adds .context/ to .gitignore

Injected format

Follows the Vercel compressed folder path convention. Files are grouped by directory to minimize token usage:

<!-- PROJECT_DOCS_START -->

## Project Docs

|[Frontend]|root: ./docs
|frontend:{design-system.md,grid-system.md}
|[Best Practices]|root: ./.context
|best-practices:{react-rules.md}
|IMPORTANT: Read best practice docs before writing code
[Component Index]|root: ./.context/components
|IMPORTANT: Read component docs before using any component
|components:{Button.md,Carousel.md,Container.md}
|If ./.context/components is missing, run: bunx @numbered/docs-to-context
|[Entities]|root: ./docs
|specs/architecture:{README.md,entities.md,entity-relationship-diagram.md}
|specs/architecture/entities:{about.md,journal.md,happening.md}

<!-- PROJECT_DOCS_END -->

Four sections:

• Frontend — design tokens, grid/layout (read before styling)
• Best Practices — platform-specific coding rules (read before writing code)
• Components — per-component docs with props, variants, defaults
• Entities — content architecture (read before schema/data work)

Best practices

The package bundles best-practice docs per platform:

| Platform | Folder | Source | Contents | | -------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | Next.js | docs/react/ | vercel-labs/agent-skills + custom rules | React rules (re-renders, effects, etc.) | | Shopify | docs/liquid/ | internal | Liquid rules (performance, Alpine.js) |

These are copied to .context/best-practices/ at generation time. More docs can be added to each folder.

To update from upstream: bun run sync react-best-practices (see scripts/sync.d/).

Supported platforms

Next.js

Scans packages/ui/components/**/*.tsx and extracts:

• Component name, Props interface/type, JSDoc
• Default values, tv() variants (tailwind-variants)
• 'use client' directive, forwardRef usage
• Sub-exports, local dependencies

Shopify

Scans snippets/*.liquid and extracts:

• {% doc %}...{% enddoc %} blocks
• @param tags (type, required/optional, defaults)
• @example usage blocks

Core docs discovery

The following files are automatically included in the index when present:

| Section | Path | Purpose | | -------- | --------------------------------- | ----------------------------------------- | | Frontend | docs/design-system.md | Design tokens, typography, colors | | Frontend | docs/grid-system.md | Grid system, breakpoints, fluid utilities | | Entities | docs/specs/architecture/**/*.md | Document types, ER diagrams, entity specs |

Fresh clone

Since .context/ is gitignored, agents on a fresh clone will see:

|If ./.context/components is missing, run: bunx @numbered/docs-to-context

No plugin install, no auth — just bun and the public npm package.

Publishing

cd packages/docs-to-context
npm login --scope=@numbered
bun run publish:dry       # preview
bun run publish:patch     # bump patch + publish
bun run publish:minor     # bump minor + publish