nuxt-agent-md 0.2.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # nuxt-agent-md
 
-Generate `AGENTS.md` with Nuxt documentation for AI coding agents.
+Generate `AGENTS.md` and `CLAUDE.md` with Nuxt documentation for AI coding agents (Cursor, Copilot, Claude Code, etc.).
 
-Inspired by [Vercel's blog post](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) showing that `AGENTS.md` with a documentation index achieves 100% success rate on agent evaluations.
+Gives your AI assistant instant access to accurate Nuxt API references, reducing hallucinations and improving code quality.
 
 ## Usage
 
@@ -18,9 +18,16 @@ nuxt-agent-md
 ## What it does
 
 1. Detects your Nuxt version from `package.json`
-2. Downloads the corresponding `@nuxt/docs` documentation
-3. Generates a minified index of all documentation files
-4. Creates/updates `AGENTS.md` with the index and key Nuxt patterns
+2. Downloads the corresponding `@nuxt/docs` documentation (~1.5 MB)
+3. Generates a minified index (~20 KB) of all documentation files
+4. Creates/updates `AGENTS.md` with the index
+5. Creates `CLAUDE.md` that references `@AGENTS.md`
+
+The index format is pipe-delimited for minimal token usage:
+
+```
+CATEGORY|path/to/file.md|keyword1,keyword2,keyword3
+```
 
 ## Options
 
@@ -48,36 +55,23 @@ nuxt-agent-md --no-minify
 
 # Custom output paths
 nuxt-agent-md -d .docs -o CLAUDE.md
-
-# Preview changes without writing
-nuxt-agent-md --dry-run
 ```
 
 ## Output
 
 The tool generates:
 
-1. `.nuxt-docs/` - Directory containing raw markdown documentation
-2. `AGENTS.md` - File with minified index pointing to the docs
-
-The index format is pipe-delimited for minimal token usage:
-
-```
-CATEGORY|path/to/file.md|keyword1,keyword2,keyword3
-```
+1. `.nuxt-docs/` - Directory containing markdown documentation (auto-added to `.gitignore`)
+2. `AGENTS.md` - File with documentation index (wrapped in `<!-- BEGIN:nuxt-agent-rules -->` markers)
+3. `CLAUDE.md` - File that references `@AGENTS.md` for Claude Code/Cursor compatibility
 
-## Why this approach?
+## Why?
 
-From Vercel's research:
+AI coding agents work better when they have access to accurate documentation rather than relying on training data that may be outdated. By providing a compact index in `AGENTS.md`, the agent can quickly find and read the relevant documentation files for any Nuxt API.
 
-| Approach | Success Rate |
-|----------|--------------|
-| Baseline (no docs) | 53% |
-| Skills | 53% |
-| Skills with explicit instructions | 79% |
-| **AGENTS.md with docs index** | **100%** |
+## Credits
 
-The key insight: providing a compressed index in `AGENTS.md` that points to detailed documentation files gives agents immediate access to accurate API information without decision overhead.
+Inspired by [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) showing that documentation indexes in `AGENTS.md` significantly improve agent accuracy.
 
 ## License
 

package/dist/cli.js

@@ -38,8 +38,10 @@ function mapToDocsVersion(nuxtVersion) {
 
 // src/download.ts
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync2, mkdirSync, rmSync, renameSync } from "node:fs";
+import { existsSync as existsSync2, mkdirSync, rmSync, renameSync, readdirSync } from "node:fs";
 import { join as join2 } from "node:path";
+var CLEANUP_FILES = ["LICENSE", "README.md", "package.json", ".navigation.yml"];
+var CLEANUP_DIRS = ["bridge", "community", "migration"];
 async function downloadDocs(version, targetDir) {
   const tempDir = ".nuxt-docs-temp";
   if (existsSync2(targetDir))
@@ -63,6 +65,17 @@ async function downloadDocs(version, targetDir) {
     if (extract.status !== 0)
       throw new Error(extract.stderr);
     renameSync(join2(tempDir, "package"), targetDir);
+    for (const file of CLEANUP_FILES) {
+      const path = join2(targetDir, file);
+      if (existsSync2(path))
+        rmSync(path);
+    }
+    for (const item of readdirSync(targetDir)) {
+      const dirName = item.replace(/^\d+\./, "");
+      if (CLEANUP_DIRS.includes(dirName)) {
+        rmSync(join2(targetDir, item), { recursive: true });
+      }
+    }
   } finally {
     if (existsSync2(tempDir))
       rmSync(tempDir, { recursive: true });
@@ -70,7 +83,7 @@ async function downloadDocs(version, targetDir) {
 }
 
 // src/generate.ts
-import { readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync2, statSync } from "node:fs";
 import { join as join3, relative } from "node:path";
 async function generateIndex(docsDir) {
   const entries = [];
@@ -81,10 +94,11 @@ async function generateIndex(docsDir) {
     full: generateFullIndex(entries, docsDir)
   };
 }
+var EXCLUDED_DIRS = ["bridge", "community"];
 function walkDir(dir, baseDir, entries) {
   let items;
   try {
-    items = readdirSync(dir);
+    items = readdirSync2(dir);
   } catch {
     return;
   }
@@ -97,7 +111,8 @@ function walkDir(dir, baseDir, entries) {
       continue;
     }
     if (stat.isDirectory()) {
-      if (!item.startsWith(".") && item !== "node_modules") {
+      const dirName = item.replace(/^\d+\./, "");
+      if (!item.startsWith(".") && item !== "node_modules" && !EXCLUDED_DIRS.includes(dirName)) {
         walkDir(fullPath, baseDir, entries);
       }
     } else if (item.endsWith(".md") && !item.startsWith(".")) {
@@ -186,7 +201,7 @@ function generateMinifiedIndex(entries, docsDir) {
   });
   const lines = [];
   for (const entry of sorted) {
-    const keywords = entry.keywords.slice(0, 6).join(",");
+    const keywords = entry.keywords.slice(0, 5).join(",");
     lines.push(`${entry.category}|${docsDir}/${entry.path}|${keywords}`);
   }
   return lines.join(`
@@ -221,17 +236,23 @@ function generateFullIndex(entries, docsDir) {
 }
 
 // src/inject.ts
+import { dirname, join as join4 } from "node:path";
 import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync } from "node:fs";
-var START_MARKER = "<!-- NUXT_DOCS_START -->";
-var END_MARKER = "<!-- NUXT_DOCS_END -->";
+var START_MARKER = "<!-- BEGIN:nuxt-agent-rules -->";
+var END_MARKER = "<!-- END:nuxt-agent-rules -->";
 async function injectAgentsMd(outputPath, index, nuxtVersion, docsDir, minify) {
   let content = "";
   if (existsSync3(outputPath)) {
     content = readFileSync3(outputPath, "utf-8");
   }
   const nuxtSection = generateNuxtSection(index, nuxtVersion, docsDir, minify);
+  const oldStartMarker = "<!-- NUXT_DOCS_START -->";
+  const oldEndMarker = "<!-- NUXT_DOCS_END -->";
   if (content.includes(START_MARKER) && content.includes(END_MARKER)) {
-    const regex = new RegExp(`${START_MARKER}[\\s\\S]*${END_MARKER}`, "m");
+    const regex = new RegExp(`${escapeRegex(START_MARKER)}[\\s\\S]*${escapeRegex(END_MARKER)}`, "m");
+    content = content.replace(regex, nuxtSection);
+  } else if (content.includes(oldStartMarker) && content.includes(oldEndMarker)) {
+    const regex = new RegExp(`${escapeRegex(oldStartMarker)}[\\s\\S]*${escapeRegex(oldEndMarker)}`, "m");
     content = content.replace(regex, nuxtSection);
   } else if (content.length > 0) {
     content = content.trimEnd() + `
@@ -241,6 +262,18 @@ async function injectAgentsMd(outputPath, index, nuxtVersion, docsDir, minify) {
     content = generateFullAgentsMd(nuxtSection);
   }
   writeFileSync(outputPath, content);
+  generateClaudeMd(outputPath);
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function generateClaudeMd(agentsMdPath) {
+  const dir = dirname(agentsMdPath);
+  const claudeMdPath = join4(dir, "CLAUDE.md");
+  const agentsMdFilename = agentsMdPath.split("/").pop() || "AGENTS.md";
+  const claudeMdContent = `@${agentsMdFilename}
+`;
+  writeFileSync(claudeMdPath, claudeMdContent, "utf-8");
 }
 function generateNuxtSection(index, nuxtVersion, docsDir, minify) {
   const majorVersion = nuxtVersion.split(".")[0];
@@ -339,7 +372,8 @@ async function generateAgentsMd(options = {}) {
   if (updateGitignore(docsDir)) {
     console.log(`Added ${docsDir} to .gitignore`);
   }
-  console.log(`Generated ${outputPath}`);
+  const claudeMdPath = outputPath.replace(/[^/]+$/, "CLAUDE.md");
+  console.log(`Generated ${outputPath} and ${claudeMdPath}`);
 }
 
 // src/cli.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-agent-md",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Generate AGENTS.md with Nuxt documentation for AI coding agents",
   "type": "module",
   "bin": {