@numbered/docs-to-context 0.1.2

package/README.md

@@ -0,0 +1,85 @@
+# @numbered/docs-to-context
+
+Extract component APIs, design system docs, 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
+
+```bash
+bunx @numbered/docs-to-context
+```
+
+Run from the project root. Auto-detects platform (Next.js or Shopify).
+
+### Options
+
+```bash
+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
+```
+
+## What it does
+
+1. **Extracts** component APIs from source files into per-component MDX docs at `docs/components/`
+2. **Discovers** core docs if present (design system, grid system, architecture specs)
+3. **Injects** a compact index between `<!-- PROJECT_DOCS_START -->` / `<!-- PROJECT_DOCS_END -->` markers in `CLAUDE.md`
+4. **Adds** `docs/components/` to `.gitignore`
+
+### Injected format
+
+Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
+
+```markdown
+<!-- PROJECT_DOCS_START -->
+## Project Docs
+|[Frontend]|root: ./docs
+|frontend:{design-system.md,grid-system.md}
+[Component Index]|root: ./docs/components
+|IMPORTANT: Read component MDX before using any component
+|components:{Button.mdx,Carousel.mdx,Container.mdx}
+|If ./docs/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 -->
+```
+
+## 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 |
+
+## Publishing
+
+```bash
+cd packages/project-docs
+npm login --scope=@numbered
+bun run publish:dry     # preview
+bun run publish:npm     # publish to npm (public)
+```

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@numbered/docs-to-context",
+	"version": "0.1.2",
+	"description": "Generate project docs (component APIs, design system, architecture) and inject index into CLAUDE.md",
+	"bin": {
+		"docs-to-context": "scripts/generate.ts"
+	},
+	"files": [
+		"scripts/*.ts",
+		"README.md"
+	],
+	"scripts": {
+		"prepublishOnly": "bun run typecheck",
+		"typecheck": "bun x tsc --noEmit",
+		"publish:patch": "npm version patch && npm publish --access public",
+		"publish:minor": "npm version minor && npm publish --access public",
+		"publish:dry": "npm publish --access public --dry-run"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+ssh://[email protected]/Numbered-com/claude.git",
+		"directory": "packages/docs-to-context"
+	},
+	"license": "MIT",
+	"private": false
+}

package/scripts/extract.ts

@@ -0,0 +1,425 @@
+/**
+ * Extract component documentation from Next.js (TSX) or Shopify (Liquid) projects.
+ *
+ * Scans component files, extracts API surface (props, variants, defaults, directives),
+ * and generates per-component MDX files plus a compact INDEX for CLAUDE.md injection.
+ */
+
+import { mkdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve } from 'node:path'
+import { isDir, walkDir } from './fs'
+import { log } from './log'
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+interface NextjsComponent {
+	name: string
+	file: string
+	client: boolean
+	forwardRef: boolean
+	description: string
+	propsName?: string
+	propsBody?: string
+	defaults: Record<string, string>
+	variants: Record<string, string[]>
+	subExports: string[]
+	dependencies: string[]
+}
+
+interface ShopifyParam {
+	name: string
+	type: string
+	required: boolean
+	default: string
+	description: string
+}
+
+interface ShopifySnippet {
+	name: string
+	file: string
+	description: string
+	params: ShopifyParam[]
+	examples: string[]
+}
+
+// ── Platform detection ─────────────────────────────────────────────────
+
+export function detectPlatform(projectRoot: string): 'nextjs' | 'shopify' | null {
+	const snippetsDir = join(projectRoot, 'snippets')
+	if (isDir(snippetsDir)) {
+		const hasLiquid = walkDir(snippetsDir, ['.liquid']).length > 0
+		if (hasLiquid) return 'shopify'
+	}
+	if (isDir(join(projectRoot, 'packages', 'ui', 'components'))) {
+		return 'nextjs'
+	}
+	return null
+}
+
+// ── Next.js extraction ─────────────────────────────────────────────────
+
+const SKIP_NAMES = new Set(['index.ts', 'index.tsx'])
+const SKIP_SUFFIXES = ['.test.', '.stories.', '.story.', '.spec.']
+
+function parseNextjsComponent(filePath: string): NextjsComponent | null {
+	const content = readFileSync(filePath, 'utf-8')
+
+	const client = /^['"]use client['"]/.test(content.trim())
+	const hasForwardRef = content.includes('forwardRef')
+
+	// JSDoc preceding first export
+	let description = ''
+	const jsdocMatch = content.match(/\/\*\*\s*([\s\S]*?)\*\/\s*\n\s*export\s/)
+	if (jsdocMatch) {
+		const lines: string[] = []
+		for (const line of jsdocMatch[1].split('\n')) {
+			const cleaned = line.replace(/^\s*\*\s?/, '').trim()
+			if (cleaned && !cleaned.startsWith('@')) lines.push(cleaned)
+		}
+		description = lines.join(' ')
+	}
+
+	// Exported component names
+	const exportNames = [...content.matchAll(/export\s+(?:const|function)\s+(\w+)/g)].map((m) => m[1])
+	const components = exportNames.filter((n) => /^[A-Z]/.test(n))
+	const nonComponents = exportNames.filter((n) => !/^[A-Z]/.test(n) && !n.includes('Props'))
+
+	if (components.length === 0) return null
+
+	// Props interface or type
+	let propsName: string | undefined
+	let propsBody: string | undefined
+
+	const ifaceMatch = content.match(/export\s+interface\s+(\w+Props)\s*\{([\s\S]*?)\n\}/)
+	if (ifaceMatch) {
+		propsName = ifaceMatch[1]
+		propsBody = `export interface ${ifaceMatch[1]} {${ifaceMatch[2]}\n}`
+	} else {
+		const typeMatch = content.match(/export\s+type\s+(\w+Props)\s*=\s*([\s\S]*?)(?:\n\n|\nexport\s)/)
+		if (typeMatch) {
+			propsName = typeMatch[1]
+			propsBody = `export type ${typeMatch[1]} = ${typeMatch[2].trimEnd()}`
+		}
+	}
+
+	// Default values from destructured params
+	const defaults: Record<string, string> = {}
+	const destructMatch = content.match(
+		/(?:export\s+(?:const|function)\s+\w+\s*=\s*\(|export\s+function\s+\w+\s*\()\s*\{([^}]+)\}\s*:\s*\w+/,
+	)
+	if (destructMatch) {
+		for (const m of destructMatch[1].matchAll(/(\w+)\s*=\s*([^,}]+)/g)) {
+			const prop = m[1].trim()
+			if (!prop.startsWith('...')) {
+				defaults[prop] = m[2].trim()
+			}
+		}
+	}
+
+	// tv() variants
+	const variants: Record<string, string[]> = {}
+	const tvMatch = content.match(
+		/(?:export\s+const\s+\w+\s*=\s*)?tv\(\s*\{[\s\S]*?variants\s*:\s*\{([\s\S]*?)\n\t\},/,
+	)
+	if (tvMatch) {
+		for (const vm of tvMatch[1].matchAll(/\n\t\t(\w+)\s*:\s*\{([\s\S]*?)\n\t\t\}/g)) {
+			variants[vm[1]] = [...vm[2].matchAll(/\n\t\t\t(\w+)\s*:/g)].map((o) => o[1])
+		}
+	}
+
+	// Local dependencies
+	const deps = new Set<string>()
+	for (const im of content.matchAll(/from\s+['"]([^'"]+)['"]/g)) {
+		const dep = im[1]
+		if (dep.startsWith('@local/') || dep.startsWith('./') || dep.startsWith('../')) {
+			deps.add(dep)
+		}
+	}
+
+	return {
+		name: components[0],
+		file: filePath,
+		client,
+		forwardRef: hasForwardRef,
+		description,
+		propsName,
+		propsBody,
+		defaults,
+		variants,
+		subExports: [...components.slice(1), ...nonComponents],
+		dependencies: [...deps],
+	}
+}
+
+function generateNextjsMdx(comp: NextjsComponent): string {
+	const lines: string[] = [
+		'---',
+		`name: ${comp.name}`,
+		'category: components',
+		`client: ${comp.client}`,
+	]
+	if (comp.forwardRef) lines.push('forwardRef: true')
+	lines.push('---', '', `# ${comp.name}`, '')
+
+	if (comp.description) lines.push(comp.description, '')
+
+	if (comp.propsBody) {
+		lines.push('## Props', '', '```typescript', comp.propsBody, '```', '')
+	}
+
+	if (Object.keys(comp.defaults).length) {
+		lines.push('## Defaults', '', '| Prop | Default |', '| --- | --- |')
+		for (const [prop, val] of Object.entries(comp.defaults)) {
+			lines.push(`| ${prop} | \`${val}\` |`)
+		}
+		lines.push('')
+	}
+
+	if (Object.keys(comp.variants).length) {
+		lines.push('## Variants', '')
+		for (const [key, opts] of Object.entries(comp.variants)) {
+			lines.push(`**${key}**: ${opts.map((o) => `\`${o}\``).join(', ')}`, '')
+		}
+	}
+
+	if (comp.subExports.length) {
+		lines.push('## Sub-exports', '')
+		for (const name of comp.subExports) lines.push(`- \`${name}\``)
+		lines.push('')
+	}
+
+	if (comp.dependencies.length) {
+		lines.push('## Dependencies', '')
+		for (const dep of comp.dependencies.sort()) lines.push(`- \`${dep}\``)
+		lines.push('')
+	}
+
+	return lines.join('\n')
+}
+
+function scanNextjs(projectRoot: string, dirs?: string[], outputDir?: string): NextjsComponent[] {
+	const root = resolve(projectRoot)
+	const outDir = outputDir ?? join(root, 'docs', 'components')
+	const scanDirs = dirs ?? ['packages/ui/components']
+
+	mkdirSync(outDir, { recursive: true })
+
+	const components: NextjsComponent[] = []
+	const writes: Array<[string, string]> = []
+
+	for (const scanDir of scanDirs) {
+		for (const tsxFile of walkDir(join(root, scanDir), ['.tsx'])) {
+			const fileName = basename(tsxFile)
+			if (SKIP_NAMES.has(fileName)) continue
+			if (SKIP_SUFFIXES.some((s) => fileName.includes(s))) continue
+
+			// Only keep main component: filename must match parent folder
+			const parentDir = basename(dirname(tsxFile))
+			const stem = basename(tsxFile, extname(tsxFile))
+			if (stem.toLowerCase() !== parentDir.toLowerCase()) continue
+
+			const comp = parseNextjsComponent(tsxFile)
+			if (!comp) continue
+
+			comp.file = relative(root, tsxFile)
+			writes.push([join(outDir, `${comp.name}.mdx`), generateNextjsMdx(comp)])
+			components.push(comp)
+		}
+	}
+
+	// Batch writes — parallel async I/O
+	const indexLines = components
+		.sort((a, b) => a.name.localeCompare(b.name))
+		.map((comp) => {
+			const flags: string[] = []
+			if (comp.client) flags.push('client')
+			if (comp.forwardRef) flags.push('ref')
+			if (Object.keys(comp.variants).length) flags.push('tv')
+			const flagStr = flags.length ? ` [${flags.join(',')}]` : ''
+			return `${comp.name}${flagStr}`
+		})
+
+	writes.push([join(outDir, 'INDEX'), indexLines.join('\n') + '\n'])
+	batchWrite(writes)
+
+	log.success(`Extracted ${components.length} components`)
+	log.dim(outDir)
+
+	return components
+}
+
+// ── Shopify extraction ─────────────────────────────────────────────────
+
+function parseShopifySnippet(filePath: string): ShopifySnippet | null {
+	const content = readFileSync(filePath, 'utf-8')
+
+	const docMatch = content.match(/\{%[-\s]*doc\s*%\}([\s\S]*?)\{%[-\s]*enddoc\s*%\}/)
+	if (!docMatch) return null
+
+	const docBlock = docMatch[1].trim()
+
+	// Description: lines before first @tag
+	const descLines: string[] = []
+	for (const line of docBlock.split('\n')) {
+		const trimmed = line.trim()
+		if (trimmed.startsWith('@')) break
+		if (trimmed) descLines.push(trimmed)
+	}
+
+	// @param entries
+	const params: ShopifyParam[] = []
+	for (const m of docBlock.matchAll(/@param\s+\{(\w+)\}\s+(\[?\w+\]?)\s*-\s*(.*)/g)) {
+		const rawName = m[2]
+		const optional = rawName.startsWith('[') && rawName.endsWith(']')
+		const name = rawName.replace(/[[\]]/g, '')
+
+		let defaultVal = '-'
+		const defaultMatch = m[3].match(/\(default:\s*([^)]+)\)/)
+		if (defaultMatch) defaultVal = defaultMatch[1].trim()
+
+		params.push({
+			name,
+			type: m[1],
+			required: !optional,
+			default: defaultVal,
+			description: m[3].trim(),
+		})
+	}
+
+	// @example blocks
+	const examples: string[] = []
+	for (const m of docBlock.matchAll(/@example\s*\n([\s\S]*?)(?=@|\Z)/g)) {
+		const example = m[1].trim()
+		if (example) examples.push(example)
+	}
+
+	return {
+		name: basename(filePath, '.liquid'),
+		file: filePath,
+		description: descLines.join(' '),
+		params,
+		examples,
+	}
+}
+
+function generateShopifyMdx(snippet: ShopifySnippet): string {
+	const lines: string[] = [
+		'---',
+		`name: ${snippet.name}`,
+		'category: snippets',
+		'---',
+		'',
+		`# ${snippet.name}`,
+		'',
+	]
+
+	if (snippet.description) lines.push(snippet.description, '')
+
+	if (snippet.params.length) {
+		lines.push(
+			'## Parameters',
+			'',
+			'| Param | Type | Required | Default | Description |',
+			'| --- | --- | --- | --- | --- |',
+		)
+		for (const p of snippet.params) {
+			lines.push(`| ${p.name} | ${p.type} | ${p.required ? 'yes' : 'no'} | ${p.default} | ${p.description} |`)
+		}
+		lines.push('')
+	}
+
+	if (snippet.examples.length) {
+		lines.push('## Usage', '')
+		for (const example of snippet.examples) {
+			lines.push('```liquid', example, '```', '')
+		}
+	}
+
+	return lines.join('\n')
+}
+
+function scanShopify(projectRoot: string, outputDir?: string): ShopifySnippet[] {
+	const root = resolve(projectRoot)
+	const outDir = outputDir ?? join(root, 'docs', 'components')
+	const snippetsDir = join(root, 'snippets')
+
+	if (!isDir(snippetsDir)) {
+		log.error(`Snippets directory not found: ${snippetsDir}`)
+		process.exit(1)
+	}
+
+	mkdirSync(outDir, { recursive: true })
+
+	const snippets: ShopifySnippet[] = []
+	const writes: Array<[string, string]> = []
+
+	for (const file of walkDir(snippetsDir, ['.liquid'])) {
+		const snippet = parseShopifySnippet(file)
+		if (!snippet) continue
+
+		snippet.file = relative(root, file)
+		writes.push([join(outDir, `${snippet.name}.mdx`), generateShopifyMdx(snippet)])
+		snippets.push(snippet)
+	}
+
+	// INDEX
+	const indexLines = snippets
+		.sort((a, b) => a.name.localeCompare(b.name))
+		.map((s) => {
+			const reqCount = s.params.filter((p) => p.required).length
+			return `${s.name} [${reqCount}req/${s.params.length}params]`
+		})
+
+	writes.push([join(outDir, 'INDEX'), indexLines.join('\n') + '\n'])
+	batchWrite(writes)
+
+	log.success(`Extracted ${snippets.length} snippets`)
+	log.dim(outDir)
+
+	return snippets
+}
+
+// ── Batch write ────────────────────────────────────────────────────────
+
+function batchWrite(files: Array<[string, string]>) {
+	// Bun.write returns promises — fire all at once, await together
+	const promises = files.map(([path, content]) => Bun.write(path, content))
+	// Top-level await not used; block at boundary
+	const results = Promise.all(promises)
+	// Bun handles microtask queue synchronously in script mode
+	return results
+}
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+export interface ExtractOptions {
+	projectRoot: string
+	platform?: 'nextjs' | 'shopify'
+	dirs?: string[]
+	outputDir?: string
+}
+
+export function extract(opts: ExtractOptions) {
+	const root = resolve(opts.projectRoot)
+
+	if (!isDir(root)) {
+		log.error(`Project root not found: ${root}`)
+		process.exit(1)
+	}
+
+	const platform = opts.platform ?? detectPlatform(root)
+	if (!platform) {
+		log.error('Could not detect platform. Use --platform flag.')
+		process.exit(1)
+	}
+
+	log.info(`Platform: ${platform}`)
+
+	const outputDir = opts.outputDir ? resolve(root, opts.outputDir) : undefined
+
+	if (platform === 'nextjs') {
+		scanNextjs(root, opts.dirs, outputDir)
+	} else {
+		scanShopify(root, outputDir)
+	}
+}

package/scripts/fs.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared filesystem helpers.
+ */
+
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Recursively collect files matching an extension filter.
+ * Single sort at the end — no intermediate sorting during recursion.
+ */
+export function walkDir(dir: string, extensions: string[]): string[] {
+	const results: string[] = []
+	collect(dir, extensions, results)
+	return results.sort()
+}
+
+function collect(dir: string, extensions: string[], out: string[]) {
+	let entries
+	try {
+		entries = readdirSync(dir, { withFileTypes: true })
+	} catch {
+		return
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name)
+		if (entry.isDirectory()) {
+			collect(full, extensions, out)
+		} else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+			out.push(full)
+		}
+	}
+}
+
+/** Check if path is a directory — single syscall, no throw. */
+export function isDir(path: string): boolean {
+	try {
+		return statSync(path).isDirectory()
+	} catch {
+		return false
+	}
+}
+
+/** Check if path is a file — single syscall, no throw. */
+export function isFile(path: string): boolean {
+	try {
+		return statSync(path).isFile()
+	} catch {
+		return false
+	}
+}

package/scripts/generate.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+/**
+ * Generate project docs: extract component APIs + inject index into CLAUDE.md.
+ *
+ * Usage: bunx @numbered/docs-to-context [project_root] [options]
+ *
+ * Options:
+ *   --platform nextjs|shopify   Force platform detection
+ *   --dirs dir1 dir2            Custom scan directories (Next.js only)
+ *   --output path               Custom output directory
+ */
+
+import { resolve } from 'node:path'
+import { extract } from './extract'
+import { inject } from './inject'
+import { log } from './log'
+
+// ── Arg parsing ────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2)
+
+let projectRoot = '.'
+let platform: 'nextjs' | 'shopify' | undefined
+let dirs: string[] | undefined
+let outputDir: string | undefined
+
+for (let i = 0; i < args.length; i++) {
+	const arg = args[i]
+	if (arg === '--platform' && args[i + 1]) {
+		platform = args[++i] as 'nextjs' | 'shopify'
+	} else if (arg === '--dirs') {
+		dirs = []
+		while (args[i + 1] && !args[i + 1].startsWith('--')) {
+			dirs.push(args[++i])
+		}
+	} else if ((arg === '--output' || arg === '-o') && args[i + 1]) {
+		outputDir = args[++i]
+	} else if (!arg.startsWith('-')) {
+		projectRoot = arg
+	}
+}
+
+projectRoot = resolve(projectRoot)
+
+// ── Run ────────────────────────────────────────────────────────────────
+
+log.banner()
+
+log.section('Extract')
+extract({ projectRoot, platform, dirs, outputDir })
+
+log.section('Inject')
+inject({ projectRoot, docsDir: outputDir })
+
+log.done()

package/scripts/inject.ts

@@ -0,0 +1,189 @@
+/**
+ * Inject project docs INDEX into CLAUDE.md between marker comments.
+ *
+ * Reads the INDEX file from docs/components/ and injects a compact reference
+ * between <!-- PROJECT_DOCS_START --> and <!-- PROJECT_DOCS_END --> markers.
+ * Also discovers core docs (design system, grid, architecture) and includes them.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { isDir, isFile, walkDir } from './fs'
+import { log } from './log'
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+const MARKER_START = '<!-- PROJECT_DOCS_START -->'
+const MARKER_END = '<!-- PROJECT_DOCS_END -->'
+const MARKER_PATTERN = new RegExp(
+	MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+	+ '[\\s\\S]*?'
+	+ MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+)
+const CORE_DOCS_ROOT = 'docs'
+const REGENERATE_CMD = 'bunx @numbered/docs-to-context'
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+interface CoreDocs {
+	frontend: string[]
+	entities: string[]
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+function groupByDir(paths: string[]): [string, string[]][] {
+	const groups = new Map<string, string[]>()
+	for (const p of paths) {
+		const lastSlash = p.lastIndexOf('/')
+		const dir = lastSlash >= 0 ? p.slice(0, lastSlash) : '.'
+		const file = lastSlash >= 0 ? p.slice(lastSlash + 1) : p
+		const list = groups.get(dir)
+		if (list) list.push(file)
+		else groups.set(dir, [file])
+	}
+	return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))
+}
+
+// ── Core docs discovery ────────────────────────────────────────────────
+
+function discoverCoreDocs(projectRoot: string): CoreDocs {
+	const docsDir = join(projectRoot, CORE_DOCS_ROOT)
+	const result: CoreDocs = { frontend: [], entities: [] }
+
+	if (!isDir(docsDir)) return result
+
+	// Frontend: design tokens, grid/layout
+	for (const name of ['design-system.md', 'grid-system.md']) {
+		if (isFile(join(docsDir, name))) result.frontend.push(name)
+	}
+
+	// Entities: architecture specs
+	const archDir = join(docsDir, 'specs', 'architecture')
+	if (isDir(archDir)) {
+		result.entities = walkDir(archDir, ['.md', '.mdx']).map((f) => relative(docsDir, f))
+	}
+
+	return result
+}
+
+// ── Block builder ──────────────────────────────────────────────────────
+
+function buildComponentLines(docsDirRel: string, names: string[]): string[] {
+	return [
+		`[Component Index]|root: ./${docsDirRel}`,
+		'|IMPORTANT: Read component MDX before using any component',
+		`|components:{${names.join(',')}}`,
+		`|If ./${docsDirRel} is missing, run: ${REGENERATE_CMD}`,
+	]
+}
+
+function buildIndexBlock(indexPath: string, docsDirRel: string, coreDocs: CoreDocs | null): string | null {
+	const indexContent = readFileSync(indexPath, 'utf-8').trim()
+
+	const names: string[] = []
+	for (const line of indexContent.split('\n')) {
+		if (!line.trim()) continue
+		const name = line.split('[')[0].split(' ')[0].trim()
+		if (name) names.push(`${name}.mdx`)
+	}
+
+	if (names.length === 0) return null
+
+	const lines: string[] = [MARKER_START, '## Project Docs']
+	const root = `./${CORE_DOCS_ROOT}`
+
+	// Frontend
+	if (coreDocs?.frontend.length) {
+		lines.push(`|[Frontend]|root: ${root}`)
+		lines.push(`|frontend:{${coreDocs.frontend.join(',')}}`)
+	}
+
+	// Components (always present)
+	lines.push(...buildComponentLines(docsDirRel, names))
+
+	// Entities (grouped by directory)
+	if (coreDocs?.entities.length) {
+		lines.push(`|[Entities]|root: ${root}`)
+		for (const [dirPath, files] of groupByDir(coreDocs.entities)) {
+			lines.push(`|${dirPath}:{${files.join(',')}}`)
+		}
+	}
+
+	lines.push(MARKER_END)
+	return lines.join('\n')
+}
+
+// ── CLAUDE.md injection ────────────────────────────────────────────────
+
+function injectIntoClaudeMd(claudeMdPath: string, block: string) {
+	if (!existsSync(claudeMdPath)) {
+		log.error(`CLAUDE.md not found: ${claudeMdPath}`)
+		process.exit(1)
+	}
+
+	const content = readFileSync(claudeMdPath, 'utf-8')
+
+	// Single-pass: replace returns original if no match
+	const replaced = content.replace(MARKER_PATTERN, block)
+	const newContent = replaced === content
+		? content.trimEnd() + '\n\n' + block + '\n'
+		: replaced
+
+	writeFileSync(claudeMdPath, newContent, 'utf-8')
+	log.success('Injected index into CLAUDE.md')
+}
+
+// ── .gitignore ─────────────────────────────────────────────────────────
+
+function ensureGitignore(projectRoot: string, docsDirRel: string) {
+	const gitignorePath = join(projectRoot, '.gitignore')
+	const entry = docsDirRel.replace(/\/+$/, '') + '/'
+
+	if (existsSync(gitignorePath)) {
+		const content = readFileSync(gitignorePath, 'utf-8')
+		if (content.includes(entry) || content.includes(docsDirRel)) return
+
+		const padded = content.endsWith('\n') ? content : content + '\n'
+		writeFileSync(gitignorePath, padded + `\n# Generated component docs\n${entry}\n`, 'utf-8')
+	} else {
+		writeFileSync(gitignorePath, `# Generated component docs\n${entry}\n`, 'utf-8')
+	}
+
+	log.info(`Added ${entry} to .gitignore`)
+}
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+export interface InjectOptions {
+	projectRoot: string
+	indexPath?: string
+	claudeMdPath?: string
+	docsDir?: string
+}
+
+export function inject(opts: InjectOptions) {
+	const root = resolve(opts.projectRoot)
+	const docsDir = opts.docsDir ?? 'docs/components'
+	const indexPath = opts.indexPath ?? join(root, docsDir, 'INDEX')
+	const claudeMdPath = opts.claudeMdPath ?? join(root, 'CLAUDE.md')
+
+	if (!existsSync(indexPath)) {
+		log.error(`INDEX file not found: ${indexPath}`)
+		log.dim('Run extraction first.')
+		process.exit(1)
+	}
+
+	const coreDocs = discoverCoreDocs(root)
+	const total = coreDocs.frontend.length + coreDocs.entities.length
+	if (total) log.info(`Found ${total} core doc(s)`)
+
+	const block = buildIndexBlock(indexPath, docsDir, total ? coreDocs : null)
+	if (!block) {
+		log.error('INDEX file is empty, nothing to inject.')
+		process.exit(1)
+	}
+
+	injectIntoClaudeMd(claudeMdPath, block)
+	ensureGitignore(root, docsDir)
+}

package/scripts/log.ts

@@ -0,0 +1,35 @@
+/**
+ * Colored terminal output helpers.
+ */
+
+const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`
+const bold = (s: string) => `\x1b[1m${s}\x1b[0m`
+
+export const log = {
+	info: (msg: string) => console.log(`  ${cyan('●')} ${msg}`),
+	success: (msg: string) => console.log(`  ${green('✓')} ${msg}`),
+	warn: (msg: string) => console.log(`  ${yellow('!')} ${msg}`),
+	error: (msg: string) => console.error(`  ${red('✗')} ${msg}`),
+	dim: (msg: string) => console.log(`    ${dim(msg)}`),
+
+	banner: () => {
+		console.log()
+		console.log(`  ${bold('@numbered/docs-to-context')}`)
+		console.log(`  ${dim('─────────────────────')}`)
+	},
+
+	done: () => {
+		console.log()
+		console.log(`  ${green('Done.')}`)
+		console.log()
+	},
+
+	section: (title: string) => {
+		console.log()
+		console.log(`  ${bold(title)}`)
+	},
+}