# @numbered/docs-to-context

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

Normalizes legacy agent instruction files (`CLAUDE.md`, `GEMINI.md`) into the canonical `AGENTS.md`, replacing originals with symlinks.

## Usage

```bash
bunx @numbered/docs-to-context@latest
```

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
  ────────────────────────

  Normalize
  ✓ Renamed CLAUDE.md → AGENTS.md
  ✓ CLAUDE.md → AGENTS.md (symlink)

  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 AGENTS.md

  Done.
```

## What it does

1. **Extracts** component APIs from source files into per-component docs at `.context/components/`, plus a `README.md` index (conventions + one-line description per component)
2. **Copies** platform-specific best practice docs to `.context/best-practices/`
3. **Discovers** core docs if present (design system, grid system, architecture specs)
4. **Normalizes** `CLAUDE.md` / `GEMINI.md` → `AGENTS.md` (content migrated, originals become symlinks)
5. **Injects** a compact index between `<!-- PROJECT_DOCS_START -->` / `<!-- PROJECT_DOCS_END -->` markers in `AGENTS.md`
6. **Adds** `.context/` to `.gitignore`

### Injected format

Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals). Files are grouped by directory to minimize token usage:

```markdown
<!-- 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
|74 component docs — ./.context/components/README.md indexes each with a one-line description
|IMPORTANT: find the component in README.md, then read its .md before using it
|[Entities]|root: ./docs
|specs/architecture:{README.md,entities.md,external-entities.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. The index emits just a pointer to `.context/components/README.md` (conventions + a one-line description per component), read on demand — keeping the always-loaded `AGENTS.md` compact regardless of component count.
- **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](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices) + 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` | Entities index, per-entity props, relationships ER |

## Fresh clone

Since `.context/` is gitignored, regenerate it on a fresh clone with `bunx @numbered/docs-to-context`. No plugin install, no auth — just `bun` and the public npm package.

## Publishing

```bash
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
```