@numbered/docs-to-context 0.1.3 → 0.1.5

package/README.md

@@ -12,7 +12,7 @@ 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
@@ -20,6 +20,24 @@ bunx @numbered/docs-to-context [project_root] [options]
 --output path               Custom output directory
 ```
 
+### Output
+
+```
+  @numbered/docs-to-context
+  ─────────────────────
+
+  Extract
+  ● Platform: nextjs
+  ✓ Extracted 74 components
+    /path/to/project/docs/components
+
+  Inject
+  ● Found 14 core doc(s)
+  ✓ Injected index into CLAUDE.md
+
+  Done.
+```
+
 ## What it does
 
 1. **Extracts** component APIs from source files into per-component MDX docs at `docs/components/`
@@ -29,11 +47,13 @@ bunx @numbered/docs-to-context [project_root] [options]
 
 ### Injected format
 
-Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
+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}
 [Component Index]|root: ./docs/components
@@ -43,9 +63,16 @@ Follows the [Vercel compressed folder path convention](https://vercel.com/blog/a
 |[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 -->
 ```
 
+Three sections:
+
+- **Frontend** — design tokens, grid/layout (read before styling)
+- **Components** — per-component MDX with props, variants, defaults
+- **Entities** — content architecture (read before schema/data work)
+
 ## Supported platforms
 
 ### Next.js
@@ -69,17 +96,28 @@ Scans `snippets/*.liquid` and extracts:
 
 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 |
+| 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 `docs/components/` is gitignored, agents on a fresh clone will see:
+
+```
+|If ./docs/components is missing, run: bunx @numbered/docs-to-context
+```
+
+No plugin install, no auth — just `bun` and the public npm package.
+
 ## Publishing
 
 ```bash
-cd packages/project-docs
+cd packages/docs-to-context
 npm login --scope=@numbered
-bun run publish:dry     # preview
-bun run publish:npm     # publish to npm (public)
+bun run publish:dry       # preview
+bun run publish:patch     # bump patch + publish
+bun run publish:minor     # bump minor + publish
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@numbered/docs-to-context",
-	"version": "0.1.3",
+	"version": "0.1.5",
 	"description": "Generate project docs (component APIs, design system, architecture) and inject index into CLAUDE.md",
 	"bin": {
 		"docs-to-context": "scripts/generate.ts"

package/scripts/inject.ts

@@ -124,11 +124,15 @@ function injectIntoClaudeMd(claudeMdPath: string, block: string) {
 
 	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
+	// Single-pass: replacer callback tracks whether a match occurred
+	let matched = false
+	const replaced = content.replace(MARKER_PATTERN, () => {
+		matched = true
+		return block
+	})
+	const newContent = matched
+		? replaced
+		: content.trimEnd() + '\n\n' + block + '\n'
 
 	writeFileSync(claudeMdPath, newContent, 'utf-8')
 	log.success('Injected index into CLAUDE.md')

package/scripts/log.ts

@@ -19,7 +19,7 @@ export const log = {
 	banner: () => {
 		console.log()
 		console.log(`  ${bold('@numbered/docs-to-context')}`)
-		console.log(`  ${dim('─────────────────────')}`)
+		console.log(`  ${dim('─────────────────────────')}`)
 	},
 
 	done: () => {