ai-readme-mcp 0.3.3 → 0.4.1

package/dist/index.js

@@ -296,6 +296,8 @@ async function getContextForFile(input) {
   const index = await scanner.scan();
   const router = new ContextRouter(index);
   const contexts = await router.getContextForFile(filePath, includeRoot);
+  const hasEmptyReadmes = contexts.some((ctx) => !ctx.content || ctx.content.trim().length === 0);
+  const hasNoReadmes = contexts.length === 0;
   const formattedContexts = contexts.map((ctx) => ({
     path: ctx.path,
     relevance: ctx.relevance,
@@ -305,33 +307,39 @@ async function getContextForFile(input) {
   let promptText = `## \u{1F4DA} Project Context for: ${filePath}
 
 `;
-  if (contexts.length === 0) {
-    promptText += `\u26A0\uFE0F **No AI_README.md files found in this project.**
+  if (hasNoReadmes || hasEmptyReadmes) {
+    promptText += `\u26A0\uFE0F **Empty or missing AI_README files detected.**
 
 `;
-    promptText += `To get the most out of AI assistance, consider creating an AI_README.md file to document:
-`;
-    promptText += `- Project architecture and conventions
+    promptText += `**Recommended Action:** Use the \`init_ai_readme\` tool to automatically populate AI_README files.
+
 `;
-    promptText += `- Coding standards and best practices
+    promptText += `\`\`\`
 `;
-    promptText += `- Testing requirements
+    promptText += `init_ai_readme({ projectRoot: "${projectRoot.replace(/\\/g, "/")}" })
 `;
-    promptText += `- Common patterns to follow
+    promptText += `\`\`\`
 
 `;
-    promptText += `**Quick Start:**
+    promptText += `This tool will:
 `;
-    promptText += `Use the \`init_ai_readme\` tool to create a template:
+    promptText += `- Scan the project for empty AI_README files
 `;
-    promptText += `- Creates AI_README.md from a customizable template
+    promptText += `- Guide you through populating them with conventions
 `;
-    promptText += `- Helps maintain consistency across your team
+    promptText += `- Ensure consistent documentation across your project
+
 `;
-    promptText += `- Improves AI output quality
+    promptText += `\u{1F4A1} Alternatively, you can manually create and populate AI_README.md files, then call this tool again.
+
+`;
+    promptText += `---
+
 `;
-  } else {
-    for (const ctx of formattedContexts) {
+  }
+  const nonEmptyContexts = contexts.filter((ctx) => ctx.content && ctx.content.trim().length > 0);
+  if (nonEmptyContexts.length > 0) {
+    for (const ctx of nonEmptyContexts) {
       if (ctx.relevance === "root") {
         promptText += `### Root Conventions (${ctx.path})
 
@@ -385,14 +393,10 @@ var ReadmeUpdater = class {
    */
   async update(readmePath, operations) {
     try {
-      if (!existsSync(readmePath)) {
-        return {
-          success: false,
-          error: `File not found: ${readmePath}`,
-          changes: []
-        };
+      let content = "";
+      if (existsSync(readmePath)) {
+        content = await readFile3(readmePath, "utf-8");
       }
-      const content = await readFile3(readmePath, "utf-8");
       let updatedContent = content;
       const changes = [];
       for (const operation of operations) {
@@ -916,353 +920,180 @@ async function validateAIReadmes(input) {
 
 // src/tools/init.ts
 import { z as z5 } from "zod";
-import { readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
-import { join as join5, dirname as dirname4, relative } from "path";
-import { existsSync as existsSync4 } from "fs";
-import { fileURLToPath } from "url";
-
-// src/core/detector.ts
-import { readFile as readFile5, readdir, stat } from "fs/promises";
+import { writeFile as writeFile2 } from "fs/promises";
 import { join as join4 } from "path";
 import { existsSync as existsSync3 } from "fs";
-var ProjectDetector = class {
-  constructor(targetPath) {
-    this.targetPath = targetPath;
-  }
-  /**
-   * Detect project information by analyzing files and structure
-   */
-  async detect() {
-    const info = {
-      projectName: "Project",
-      projectType: "unknown",
-      language: "JavaScript",
-      hasTests: false,
-      mainDirs: []
-    };
-    const packageJsonPath = join4(this.targetPath, "package.json");
-    if (existsSync3(packageJsonPath)) {
-      await this.analyzePackageJson(packageJsonPath, info);
-    }
-    if (existsSync3(join4(this.targetPath, "requirements.txt")) || existsSync3(join4(this.targetPath, "setup.py")) || existsSync3(join4(this.targetPath, "pyproject.toml"))) {
-      info.language = "Python";
-    }
-    if (existsSync3(join4(this.targetPath, "go.mod"))) {
-      info.language = "Go";
-    }
-    if (existsSync3(join4(this.targetPath, "Cargo.toml"))) {
-      info.language = "Rust";
-    }
-    if (existsSync3(join4(this.targetPath, "pom.xml")) || existsSync3(join4(this.targetPath, "build.gradle"))) {
-      info.language = "Java";
-    }
-    await this.analyzeStructure(info);
-    return info;
-  }
-  /**
-   * Analyze package.json to extract project information
-   */
-  async analyzePackageJson(path, info) {
-    try {
-      const content = await readFile5(path, "utf-8");
-      const pkg = JSON.parse(content);
-      if (pkg.name) {
-        info.projectName = pkg.name;
-      }
-      if (pkg.devDependencies?.typescript || pkg.dependencies?.typescript) {
-        info.language = "TypeScript";
-      }
-      if (pkg.dependencies?.react || pkg.devDependencies?.react) {
-        info.framework = "React";
-      } else if (pkg.dependencies?.vue || pkg.devDependencies?.vue) {
-        info.framework = "Vue";
-      } else if (pkg.dependencies?.["@angular/core"]) {
-        info.framework = "Angular";
-      } else if (pkg.dependencies?.next) {
-        info.framework = "Next.js";
-      } else if (pkg.dependencies?.express) {
-        info.framework = "Express";
-      } else if (pkg.dependencies?.nestjs || pkg.dependencies?.["@nestjs/core"]) {
-        info.framework = "NestJS";
-      }
-      const lockFiles = await readdir(this.targetPath);
-      if (lockFiles.includes("pnpm-lock.yaml")) {
-        info.packageManager = "pnpm";
-      } else if (lockFiles.includes("yarn.lock")) {
-        info.packageManager = "yarn";
-      } else if (lockFiles.includes("bun.lockb")) {
-        info.packageManager = "bun";
-      } else if (lockFiles.includes("package-lock.json")) {
-        info.packageManager = "npm";
-      }
-      if (pkg.workspaces || existsSync3(join4(this.targetPath, "pnpm-workspace.yaml"))) {
-        info.projectType = "monorepo";
-      }
-      if (!info.projectType || info.projectType === "unknown") {
-        if (pkg.main || pkg.exports) {
-          info.projectType = "library";
-        } else {
-          info.projectType = "application";
-        }
-      }
-      if (pkg.dependencies) {
-        info.dependencies = Object.keys(pkg.dependencies).slice(0, 5);
-      }
-    } catch (error) {
-    }
-  }
-  /**
-   * Analyze directory structure
-   */
-  async analyzeStructure(info) {
-    try {
-      const entries = await readdir(this.targetPath);
-      const dirs = [];
-      for (const entry of entries) {
-        try {
-          const entryPath = join4(this.targetPath, entry);
-          const stats = await stat(entryPath);
-          if (stats.isDirectory()) {
-            if (["src", "lib", "app", "pages", "components", "api", "server", "client"].includes(entry)) {
-              dirs.push(entry);
-            }
-            if (["test", "tests", "__tests__", "spec"].includes(entry)) {
-              info.hasTests = true;
-            }
-            if (["apps", "packages", "modules"].includes(entry)) {
-              info.projectType = "monorepo";
-              dirs.push(entry);
-            }
-          }
-        } catch {
-        }
-      }
-      info.mainDirs = dirs;
-    } catch (error) {
-    }
-  }
-};
-
-// src/tools/init.ts
 var initSchema = z5.object({
-  targetPath: z5.string().describe("Directory where AI_README.md will be created"),
-  projectName: z5.string().optional().describe("Project name to use in the template (optional)"),
-  overwrite: z5.boolean().optional().describe("Whether to overwrite existing AI_README.md (default: false)"),
-  smart: z5.boolean().optional().describe("Enable smart content generation based on project analysis (default: true)")
+  projectRoot: z5.string().describe("The root directory of the project"),
+  excludePatterns: z5.array(z5.string()).optional().describe("Glob patterns to exclude when scanning"),
+  targetPath: z5.string().optional().describe("Specific directory to initialize (optional, defaults to scanning entire project)")
 });
 async function initAIReadme(input) {
-  const { targetPath, projectName, overwrite = false } = input;
-  const smart = input.smart !== false;
-  console.error(`[DEBUG] init_ai_readme: smart=${smart}, input.smart=${input.smart}`);
-  try {
-    if (!existsSync4(targetPath)) {
-      return {
-        success: false,
-        error: `Target directory does not exist: ${targetPath}`,
-        message: `Failed to create AI_README.md: Directory not found`
-      };
-    }
-    const readmePath = join5(targetPath, "AI_README.md");
-    const fileExists = existsSync4(readmePath);
-    let isEmpty = false;
-    if (fileExists) {
-      const existingContent = await readFile6(readmePath, "utf-8");
-      isEmpty = existingContent.trim().length < 50;
-      if (!isEmpty && !overwrite) {
-        return {
-          success: false,
-          error: "AI_README.md already exists with content",
-          message: `AI_README.md already exists at ${readmePath}. Use overwrite: true to replace it.`,
-          existingPath: readmePath
-        };
-      }
+  const { projectRoot, excludePatterns, targetPath } = input;
+  const scanner = new AIReadmeScanner(projectRoot, {
+    excludePatterns,
+    cacheContent: true
+  });
+  const index = await scanner.scan();
+  const emptyReadmes = [];
+  for (const readme of index.readmes) {
+    if (!readme.content || readme.content.trim().length === 0) {
+      emptyReadmes.push({
+        path: readme.path,
+        dirPath: readme.path.replace(/[\/\\]AI_README\.md$/, ""),
+        needsCreation: false
+      });
     }
-    let content;
-    let detectedInfo = {};
-    if (smart) {
-      const detector = new ProjectDetector(targetPath);
-      const projectInfo = await detector.detect();
-      detectedInfo = projectInfo;
-      const parentReadme = await findParentReadme(targetPath);
-      const isSubdirectory = parentReadme !== null;
-      content = await generateSmartContent(projectInfo, targetPath, isSubdirectory, parentReadme);
-    } else {
-      const __filename2 = fileURLToPath(import.meta.url);
-      const __dirname2 = dirname4(__filename2);
-      const templatePath = join5(__dirname2, "..", "..", "docs", "templates", "basic.md");
-      if (!existsSync4(templatePath)) {
-        return {
-          success: false,
-          error: `Template file not found: ${templatePath}`,
-          message: "Template file is missing. Please check installation."
-        };
-      }
-      content = await readFile6(templatePath, "utf-8");
-      const finalProjectName = projectName || "Project Name";
-      content = content.replace(/\{\{PROJECT_NAME\}\}/g, finalProjectName);
+  }
+  if (index.readmes.length === 0) {
+    const rootReadmePath = join4(projectRoot, "AI_README.md");
+    if (!existsSync3(rootReadmePath)) {
+      await writeFile2(rootReadmePath, "", "utf-8");
     }
-    await writeFile2(readmePath, content, "utf-8");
-    const action = fileExists ? isEmpty ? "filled" : "overwritten" : "created";
+    emptyReadmes.push({
+      path: rootReadmePath,
+      dirPath: projectRoot,
+      needsCreation: true
+    });
+  }
+  let targetReadmes = emptyReadmes;
+  if (targetPath) {
+    const normalizedTarget = targetPath.replace(/\\/g, "/");
+    targetReadmes = emptyReadmes.filter(
+      (r) => r.dirPath.replace(/\\/g, "/").includes(normalizedTarget)
+    );
+  }
+  if (targetReadmes.length === 0) {
     return {
       success: true,
-      readmePath,
-      action,
-      projectInfo: smart ? detectedInfo : void 0,
-      message: `Successfully ${action} AI_README.md at ${readmePath}. ${smart ? "Content generated based on project analysis." : "Edit the file to customize it for your project."}`
-    };
-  } catch (error) {
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error),
-      message: `Failed to create AI_README.md: ${error instanceof Error ? error.message : String(error)}`
+      message: "\u2705 All AI_README files are already populated!",
+      initialized: []
     };
   }
-}
-async function findParentReadme(targetPath) {
-  let currentPath = dirname4(targetPath);
-  const root = "/";
-  while (currentPath !== root) {
-    const readmePath = join5(currentPath, "AI_README.md");
-    if (existsSync4(readmePath)) {
-      const content = await readFile6(readmePath, "utf-8");
-      if (content.trim().length > 50) {
-        return currentPath;
-      }
+  let promptText = `# \u{1F680} AI_README Initialization
+
+`;
+  promptText += `Found ${targetReadmes.length} AI_README file(s) that need population.
+
+`;
+  if (targetReadmes.some((r) => r.needsCreation)) {
+    promptText += `\u2705 Created empty AI_README file(s) at:
+`;
+    for (const readme of targetReadmes.filter((r) => r.needsCreation)) {
+      promptText += `- ${readme.path.replace(/\\/g, "/")}
+`;
     }
-    const parentPath = dirname4(currentPath);
-    if (parentPath === currentPath) break;
-    currentPath = parentPath;
+    promptText += `
+`;
   }
-  return null;
-}
-async function generateSmartContent(projectInfo, targetPath, isSubdirectory, parentPath) {
-  let content = `# ${projectInfo.projectName}
+  promptText += `## \u{1F4CB} Required Actions
 
 `;
-  if (isSubdirectory && parentPath) {
-    const relativePath = relative(parentPath, targetPath);
-    content += `> This README extends the root AI_README.md with ${relativePath}-specific conventions.
+  promptText += `You must populate the following AI_README files by analyzing their respective directories:
 
 `;
-  }
-  content += `## Architecture
+  for (let i = 0; i < targetReadmes.length; i++) {
+    const readme = targetReadmes[i];
+    const readmePath = readme.path.replace(/\\/g, "/");
+    const dirPath = readme.dirPath.replace(/\\/g, "/");
+    promptText += `### ${i + 1}. ${readmePath}
 
 `;
-  content += `- **Type:** ${projectInfo.projectType}
+    promptText += `**Directory to analyze:** \`${dirPath}\`
+
 `;
-  content += `- **Language:** ${projectInfo.language}
+    promptText += `**Steps:**
+
 `;
-  if (projectInfo.framework) {
-    content += `- **Framework:** ${projectInfo.framework}
+    promptText += `1. **Scan directory contents:**
 `;
-  }
-  content += `
+    promptText += `   \`\`\`
+`;
+    promptText += `   Use Glob: pattern="**/*", path="${dirPath}"
 `;
-  if (projectInfo.mainDirs && projectInfo.mainDirs.length > 0) {
-    content += `## Directory Structure
+    promptText += `   \`\`\`
 
 `;
-    for (const dir of projectInfo.mainDirs) {
-      content += `- ${dir}/ - [Add description]
+    promptText += `2. **Read key source files** (pick 2-5 representative files):
 `;
-    }
-    content += `
+    promptText += `   - Configuration files (package.json, tsconfig.json, etc.)
 `;
-  }
-  content += `## Coding Conventions
+    promptText += `   - Main source files
+`;
+    promptText += `   - Important modules/components
 
 `;
-  content += `### File Naming
+    promptText += `3. **Analyze and identify:**
 `;
-  content += `- [Add your file naming conventions here]
-
+    promptText += `   - \u{1F4E6} **Tech Stack**: Frameworks, libraries, languages, tools
 `;
-  content += `### Code Style
+    promptText += `   - \u{1F3D7}\uFE0F **Architecture**: Project structure, design patterns
 `;
-  if (projectInfo.language === "TypeScript") {
-    content += `- Use TypeScript strict mode
+    promptText += `   - \u{1F4DD} **Coding Conventions**: Naming, formatting, patterns
 `;
-    content += `- Prefer interfaces over types for object shapes
+    promptText += `   - \u{1F5C2}\uFE0F **File Structure**: Directory organization, module boundaries
+
 `;
-  } else if (projectInfo.language === "Python") {
-    content += `- Follow PEP 8 style guide
+    promptText += `4. **Populate AI_README:**
 `;
-    content += `- Use type hints
+    promptText += `   \`\`\`
 `;
-  }
-  content += `- [Add more style guidelines]
-
+    promptText += `   Use update_ai_readme:
 `;
-  if (projectInfo.framework) {
-    content += `### ${projectInfo.framework} Conventions
+    promptText += `   {
 `;
-    if (projectInfo.framework === "React") {
-      content += `- Component naming: PascalCase
+    promptText += `     readmePath: "${readmePath}",
 `;
-      content += `- Hooks naming: use prefix 'use'
+    promptText += `     operations: [{
 `;
-      content += `- Prefer functional components
+    promptText += `       type: "append",
 `;
-    } else if (projectInfo.framework === "Vue") {
-      content += `- Component naming: PascalCase or kebab-case
+    promptText += `       content: "<your analysis in markdown format>"
 `;
-      content += `- Use Composition API
+    promptText += `     }]
 `;
-    }
-    content += `
+    promptText += `   }
 `;
-  }
-  content += `## Testing
+    promptText += `   \`\`\`
 
 `;
-  if (projectInfo.hasTests) {
-    content += `- Tests are located in test directories
+    promptText += `   **Include these sections:**
 `;
-  }
-  if (projectInfo.packageManager) {
-    content += `- Run: \`${projectInfo.packageManager} test\`
+    promptText += `   - \`## Tech Stack\` - List frameworks, libraries, tools
 `;
-  } else {
-    content += `- Run: [Add test command]
+    promptText += `   - \`## Architecture Patterns\` - Design patterns, project structure
 `;
-  }
-  content += `- Coverage target: [Add target or "not enforced"]
-
+    promptText += `   - \`## Coding Conventions\` - Naming, formatting, best practices
 `;
-  if (projectInfo.dependencies && projectInfo.dependencies.length > 0) {
-    content += `## Key Dependencies
+    promptText += `   - \`## File Structure\` - Directory organization (brief)
 
 `;
-    for (const dep of projectInfo.dependencies) {
-      content += `- ${dep} - [Add purpose]
-`;
-    }
-    content += `
+    promptText += `   **Keep it concise:** AI_READMEs should be <400 tokens. Focus on actionable conventions.
+
 `;
   }
-  content += `## Development
+  promptText += `---
 
 `;
-  if (projectInfo.packageManager) {
-    content += `- Install: \`${projectInfo.packageManager} install\`
+  promptText += `\u{1F4A1} **Tips:**
 `;
-    content += `- Dev: \`${projectInfo.packageManager} run dev\`
+  promptText += `- Work through each README sequentially
 `;
-    content += `- Build: \`${projectInfo.packageManager} run build\`
+  promptText += `- Be concise - every token counts!
 `;
-  }
-  content += `
+  promptText += `- Focus on conventions that help generate better code
 `;
-  content += `## Important Notes
+  promptText += `- After completing all, you can verify with \`validate_ai_readmes\`
 
 `;
-  content += `- [Add critical information that AI should know]
+  promptText += `**Start with the first AI_README now!**
 `;
-  content += `- [Security considerations]
-`;
-  content += `- [Performance considerations]
-`;
-  return content;
+  return {
+    success: true,
+    message: `Found ${targetReadmes.length} AI_README file(s) to initialize`,
+    readmesToInitialize: targetReadmes.map((r) => r.path.replace(/\\/g, "/")),
+    instructions: promptText
+  };
 }
 
 // src/index.ts
@@ -1287,30 +1118,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "get_context_for_file",
-        description: '\u26A0\uFE0F REQUIRED: Call this tool BEFORE creating or editing ANY file to get project conventions.\n\nGets relevant AI_README context for a specific file path. Returns formatted guidelines that MUST be followed when writing code.\n\n**When to call this tool:**\n- BEFORE using Write tool (creating new files)\n- BEFORE using Edit tool (modifying existing files)\n- AFTER updating AI_README (to get fresh context)\n- Works even if the target file does not exist yet\n\n**Recommended workflow:**\n1. Establishing NEW conventions: update_ai_readme \u2192 get_context_for_file \u2192 Write/Edit\n2. Following existing conventions: get_context_for_file \u2192 Write/Edit\n3. Documenting discovered patterns: Write/Edit \u2192 update_ai_readme\n\n**Example:** Before creating Button.tsx, call get_context_for_file with filePath="src/components/Button.tsx" to learn styling preferences (CSS Modules vs Tailwind), naming conventions, component patterns, etc.',
+        description: '\u26A0\uFE0F REQUIRED: Call this tool BEFORE creating or editing ANY file to get project conventions.\n\nGets relevant AI_README context for a specific file path. Returns formatted guidelines that MUST be followed when writing code.\n\n**When to call:**\n- BEFORE using Write tool (creating new files)\n- BEFORE using Edit tool (modifying existing files)\n- AFTER updating AI_README (to get fresh context)\n- Works even if the target file does not exist yet\n\n**Workflows:**\n1. Following conventions: get_context_for_file \u2192 Write/Edit\n2. Establishing NEW conventions: update_ai_readme \u2192 get_context_for_file \u2192 Write/Edit\n3. Empty AI_README detected: Use `init_ai_readme` tool (tool will suggest this)\n4. Document discovered patterns: Write/Edit \u2192 update_ai_readme\n\n**Example:** Before creating Button.tsx, call get_context_for_file with filePath="src/components/Button.tsx" to learn styling preferences (CSS Modules vs Tailwind), naming conventions, component patterns, etc.',
         inputSchema: zodToJsonSchema(getContextSchema)
       },
       {
         name: "update_ai_readme",
-        description: `Update an AI_README.md file to document conventions, patterns, or architectural decisions. Supports append, prepend, replace, insert-after, insert-before operations. Auto-validates after update.
-
-**When to use this tool:**
-1. BEFORE code changes: When establishing NEW conventions
-   - User requests a style/approach change (e.g., "use CSS Modules instead of Tailwind")
-   - Choosing between multiple approaches (e.g., state management libraries)
-   - Setting up new architectural patterns or folder structures
-   - Workflow: update_ai_readme \u2192 get_context_for_file \u2192 Write/Edit
-
-2. AFTER code changes: When documenting discovered patterns
-   - Found consistent patterns in existing code
-   - Identified team conventions from code review
-   - Workflow: Write/Edit \u2192 update_ai_readme
-
-**Example scenarios:**
-- User: "Use CSS Modules instead of Tailwind" \u2192 Update AI_README first, then modify code
-- User: "Add error handling to API calls" \u2192 Code first, document pattern after if it's new
-
-Note: Only update when documenting NEW conventions - avoid duplicates.`,
+        description: 'Update an AI_README.md file to document conventions, patterns, or architectural decisions. Supports append, prepend, replace, insert-after, insert-before operations.\n\n**CRITICAL: Token Efficiency Rules**\n- Keep content EXTREMELY concise (< 400 tokens ideal, < 600 warning, > 1000 error)\n- Only document ACTIONABLE conventions that affect code generation\n- NO explanations, NO examples, NO verbose descriptions\n- Use bullet points, avoid complete sentences when possible\n- Focus on: tech stack, naming rules, patterns, architectural decisions\n- AVOID: project background, how-to guides, documentation, obvious practices\n\n**When to use:**\n1. BEFORE code changes: Establishing NEW conventions\n   - User requests style/approach change (e.g., "use CSS Modules")\n   - Choosing between approaches (e.g., state management)\n   - Setting up new architectural patterns\n   - Workflow: update_ai_readme \u2192 get_context_for_file \u2192 Write/Edit\n\n2. AFTER code changes: Documenting discovered patterns\n   - Found consistent patterns in existing code\n   - Workflow: Write/Edit \u2192 update_ai_readme\n\n**Quality checklist before updating:**\nIs this a CONVENTION or PATTERN (not documentation)?\nWill this help AI generate better code?\nIs it concise (<3 words per bullet)?\nDoes it avoid obvious/general practices?\nReject: project descriptions, tutorials, general best practices\n\n**Example (GOOD):**\n- Use CSS Modules\n- Components in PascalCase\n- Test coverage: 80%+\n\n**Example (BAD - too verbose):**\n- We use CSS Modules for styling because it provides better type safety and scoping compared to Tailwind...',
         inputSchema: zodToJsonSchema(updateSchema)
       },
       {
@@ -1320,7 +1133,7 @@ Note: Only update when documenting NEW conventions - avoid duplicates.`,
       },
       {
         name: "init_ai_readme",
-        description: "Initialize or fill an AI_README.md file with smart content based on project analysis. Auto-detects project type, language, and framework. Use this to create new READMEs or fill empty ones.",
+        description: '\u{1F680} Initialize and populate empty AI_README files in your project.\n\nScans the project for empty or missing AI_README files and guides you through populating them with project conventions.\n\n**When to use:**\n- First time setting up AI_README in a project\n- When get_context_for_file detects empty AI_README files\n- After creating new empty AI_README.md files manually\n- To populate multiple AI_README files at once\n\n**What it does:**\n1. Scans project for empty AI_README files\n2. Creates root-level AI_README if none exist\n3. Provides step-by-step instructions to populate each file\n4. Guides analysis of tech stack, patterns, and conventions\n\n**Workflow:**\n1. Call init_ai_readme\n2. Follow the instructions to explore directories\n3. Use update_ai_readme to populate each file\n4. Call get_context_for_file to verify and use conventions\n\n**Example:** `init_ai_readme({ projectRoot: "/path/to/project" })`',
         inputSchema: zodToJsonSchema(initSchema)
       }
     ]
@@ -1384,7 +1197,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         content: [
           {
             type: "text",
-            text: JSON.stringify(result, null, 2)
+            text: result.instructions || JSON.stringify(result, null, 2)
           }
         ]
       };