@afterxleep/doc-bot 1.22.0 → 1.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afterxleep/doc-bot",
-  "version": "1.22.0",
+  "version": "1.23.1",
   "description": "Generic MCP server for intelligent documentation access in any project",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -166,7 +166,7 @@ class DocsServer {
         tools: [
           {
             name: 'check_project_rules',
-            description: 'Get mandatory coding standards for your task. Always call before writing code. Returns architecture patterns, security requirements, and performance guidelines specific to this codebase. Critical for maintaining code quality and consistency.',
+            description: 'Get mandatory coding standards for your task. Call BEFORE writing ANY code AND whenever you start a new component/feature/file. Returns architecture patterns, security requirements, and performance guidelines specific to this codebase. Prevents rework by catching violations early. Use this repeatedly: before each major code block, when switching contexts, or when unsure about approach. CRITICAL: This gives you task-specific rules, but you should ALSO call doc_bot() for complete project context and checkpoint guidance. Think of check_project_rules as "what rules apply to this task" and doc_bot as "am I still aligned with the project".',
             inputSchema: {
               type: 'object',
               properties: {
@@ -180,7 +180,7 @@ class DocsServer {
           },
           {
             name: 'search_documentation',
-            description: 'Search codebase documentation and API references. Searches project patterns, architecture decisions, and API docs. Best results with technical terms like class names, not descriptions. Examples: search "Widget" not "iOS 18 features". Supports pagination for large result sets.',
+            description: 'Search codebase documentation and API references - use THROUGHOUT your work, not just at the start. Call whenever you encounter unfamiliar code patterns, before implementing any feature, when debugging issues, or when you need examples. Searches project patterns, architecture decisions, and API docs. Best results with technical terms (class names, API names), not natural language descriptions. Example: search "Widget" NOT "iOS 18 features". If your first search doesn\'t help, search again with different terms - the docs are there to help you continuously.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -210,7 +210,7 @@ class DocsServer {
           },
           {
             name: 'get_global_rules',
-            description: 'Get comprehensive coding standards and architecture guidelines. Returns project-wide engineering principles, design patterns, performance requirements, and security standards. Essential reading for understanding the codebase philosophy.',
+            description: 'Get comprehensive coding standards and architecture guidelines - reference this when making ANY architectural decision, not just at project start. Returns project-wide engineering principles, design patterns, performance requirements, and security standards that override general best practices. Call when: starting work, making design decisions, resolving conflicts between approaches, or when implementation feels uncertain. These rules represent hard-learned lessons specific to THIS codebase.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -224,7 +224,7 @@ class DocsServer {
           },
           {
             name: 'get_file_docs',
-            description: 'Get file-specific coding patterns and conventions. Returns contextual guidelines, performance considerations, and architectural decisions for specific files or directories. Use before modifying existing code.',
+            description: 'Get file-specific coding patterns and conventions for ANY file you work with. Call BEFORE modifying code AND when you encounter a new file during implementation. Returns contextual guidelines, performance considerations, and architectural decisions for specific files or directories. Each file/directory may have unique rules that override general patterns. Use whenever: editing existing files, creating files in a new directory, implementing features that touch multiple files, or debugging file-specific issues.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -238,7 +238,7 @@ class DocsServer {
           },
           {
             name: 'read_specific_document',
-            description: 'Read full documentation file content. Use after search_documentation to get complete implementation details, code examples, and architectural decisions. Only for project docs, not API docs.',
+            description: 'Read full documentation file content - dive deep WHENEVER search results point you here. Use after search_documentation identifies relevant docs, when you need complete context before implementing, or when revisiting a topic mid-work. Returns complete implementation details, code examples, and architectural decisions. Don\'t just skim search results - read the full docs to avoid missing critical details. Project docs contain battle-tested patterns; API docs show framework usage.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -256,7 +256,7 @@ class DocsServer {
           },
           {
             name: 'explore_api',
-            description: 'Deep dive into any API, framework, or class. Returns all methods, properties, protocols, and usage examples. Essential for understanding how to implement features correctly. Much faster than multiple searches.',
+            description: 'Deep dive into any API, framework, or class - check this EVERY time you use an unfamiliar API, not just once. Returns all methods, properties, protocols, and usage examples. Essential when: implementing features with new frameworks, encountering unknown classes mid-work, choosing between similar APIs, or verifying correct API usage. Much faster than multiple searches. If you\'re writing import statements or instantiating classes you haven\'t used before, explore them first to avoid misuse.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -274,7 +274,7 @@ class DocsServer {
           },
           {
             name: 'create_or_update_rule',
-            description: 'Document new coding patterns or architectural decisions. Captures lessons learned, design patterns, and team conventions as searchable knowledge. Great for preserving tribal knowledge.',
+            description: 'Document new coding patterns or architectural decisions AS YOU DISCOVER THEM during work. Call this when: you solve a tricky problem, establish a new pattern, learn a gotcha, make an architectural decision, or implement something that should be standardized. Captures lessons learned, design patterns, and team conventions as searchable knowledge for future work. Don\'t wait until the end - document insights immediately while context is fresh.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -309,7 +309,7 @@ class DocsServer {
           },
           {
             name: 'refresh_documentation',
-            description: 'Reload all project documentation from disk. Use when documentation files have been modified outside of this session. Re-indexes all documents and updates search index.',
+            description: 'Reload all project documentation from disk when docs are updated externally. Call when: documentation files are modified outside this session, after creating new docs manually, when search results seem stale, or if you suspect docs have changed. Re-indexes all documents and updates search index. If you created new documentation and it\'s not appearing in searches, refresh first.',
             inputSchema: {
               type: 'object',
               properties: {},
@@ -318,7 +318,7 @@ class DocsServer {
           },
           {
             name: 'get_document_index',
-            description: 'List all available project documentation files. Returns index with titles, descriptions, and metadata. Use to see what documentation exists without searching.',
+            description: 'List all available project documentation files - check periodically to discover new docs added during your work. Returns index with titles, descriptions, and metadata. Use when: starting work (to see what\'s available), search fails to find what you need (browse instead), exploring unfamiliar codebases, or checking if docs exist for a topic. Helps you discover documentation you didn\'t know existed.',
             inputSchema: {
               type: 'object',
               properties: {},
@@ -364,13 +364,13 @@ class DocsServer {
           },
           {
             name: 'doc_bot',
-            description: 'ALWAYS call this first for any task. Returns mandatory project standards (alwaysApply rules) that must be followed, plus a catalog of available documentation tools. Provides intelligent guidance while trusting your judgment on what additional context you need based on your familiarity with the codebase. Supports pagination for large rule sets.',
+            description: 'Your continuous project compass - call at EVERY major decision point, not just once. REQUIRED at: (1) Before starting any task, (2) Before each new component/file, (3) When uncertain about approach, (4) After errors/blockers, (5) When switching contexts, (6) Before architectural decisions. Returns mandatory standards PLUS checkpoint reminders for what you might be missing. This is NOT a one-time initialization - it\'s your continuous compliance guardian. Agents who skip regular check-ins often violate standards or miss critical patterns. Think "check in before committing" not "check in once at start". Each call validates you\'re still aligned with project requirements.',
             inputSchema: {
               type: 'object',
               properties: {
                 task: {
                   type: 'string',
-                  description: 'What do you need help with? Examples: "create REST API", "understand auth flow", "document this pattern", "find database models"'
+                  description: 'What do you need help with? Examples: "create REST API", "modify auth.js", "debug auth error", "review completion", "understand auth flow"'
                 },
                 page: {
                   type: 'number',
@@ -408,10 +408,7 @@ class DocsServer {
             }
             const searchPage = args?.page || 1;
             const searchLimit = args?.limit || 20;
-            
-            // Calculate offset for pagination
-            const searchOffset = (searchPage - 1) * searchLimit;
-            
+
             const unifiedOptions = {
               limit: searchLimit * 3, // Get more results for pagination
               docsetId: args?.docsetId,
@@ -957,9 +954,18 @@ Try:
     if (localResults.length > 0) {
       output += `- Read project docs with \`read_specific_document\`\n`;
     }
-    
+
     output += `- Use \`explore_api\` to see all methods/properties for a class\n`;
-    
+
+    // Add engagement hooks for continuous investigation
+    output += '\n## 🔍 Continue Your Investigation:\n';
+    output += 'This search gave you starting points, but consider:\n';
+    output += `- Did you check file-specific docs with \`get_file_docs\`? Files often have unique conventions\n`;
+    output += `- Have you explored the full API surface with \`explore_api\`? You might be missing key methods\n`;
+    output += `- Are there related patterns? Try searching for variations or related terms\n`;
+    output += `\n⚠️ **Working without complete context increases error risk**\n`;
+    output += `\n🔄 **Checkpoint reminder**: Before writing code, return to \`doc_bot()\` to verify compliance with project standards\n`;
+
     return output;
   }
   
@@ -1088,7 +1094,19 @@ Try:
       output += `- Review the code samples for implementation examples\n`;
     }
     output += `- Import the framework and start using these APIs\n`;
-    
+
+    // Add "what you're missing" section
+    output += `\n## ⚠️ What This Response Doesn't Include:\n`;
+    output += `- **Project-specific usage patterns**: Your codebase may use ${apiName} differently than shown here\n`;
+    output += `- **Forbidden patterns**: Some methods might be banned by project rules\n`;
+    output += `- **Performance gotchas**: File-specific docs might have critical performance notes\n`;
+    output += `- **Team conventions**: How your team prefers to use this API\n`;
+    output += `\n💡 **Recommended next actions**:\n`;
+    output += `1. Run \`search_documentation("${apiName}")\` to find how THIS project uses ${apiName}\n`;
+    output += `2. Before implementing, call \`doc_bot(task="implement ${apiName}")\` to check project standards\n`;
+    output += `3. Use \`get_file_docs(filePath)\` for the specific file you'll modify\n`;
+    output += `\n🔄 **Checkpoint reminder**: This is generic API documentation. Return to \`doc_bot()\` before writing code to ensure project compliance.\n`;
+
     return output;
   }
 
@@ -1188,9 +1206,9 @@ Try:
     if (!fileDocs || fileDocs.length === 0) {
       return `No specific documentation found for file: ${filePath}`;
     }
-    
+
     let output = `# Documentation for ${filePath}\n\n`;
-    
+
     fileDocs.forEach(doc => {
       output += `## ${doc.metadata?.title || doc.fileName}\n`;
       if (doc.metadata?.description) {
@@ -1199,7 +1217,16 @@ Try:
       output += `${doc.content}\n\n`;
       output += '---\n\n';
     });
-    
+
+    // Add checkpoint reminder
+    output += `## ⚠️ Important Context:\n`;
+    output += `This shows file/directory-specific rules for **${filePath}**.\n\n`;
+    output += `**Remember**:\n`;
+    output += `- These rules are IN ADDITION to global project rules\n`;
+    output += `- If there's a conflict, ask via \`doc_bot()\` which takes precedence\n`;
+    output += `- Other files in different directories may have different conventions\n`;
+    output += `\n🔄 **Next checkpoint**: Before modifying this file, return to \`doc_bot(task="modify ${filePath}")\` to get a complete compliance check.\n`;
+
     return output;
   }
   
@@ -1207,25 +1234,37 @@ Try:
     if (!doc) {
       return 'Document not found';
     }
-    
+
     let output = `# ${doc.metadata?.title || doc.fileName}\n\n`;
-    
+
     if (doc.metadata?.description) {
       output += `**Description:** ${doc.metadata.description}\n\n`;
     }
-    
+
     if (doc.metadata?.keywords) {
       output += `**Keywords:** ${Array.isArray(doc.metadata.keywords) ? doc.metadata.keywords.join(', ') : doc.metadata.keywords}\n\n`;
     }
-    
+
     if (doc.metadata?.alwaysApply !== undefined) {
       output += `**Always Apply:** ${doc.metadata.alwaysApply ? 'Yes (Global Rule)' : 'No (Contextual Rule)'}\n\n`;
     }
-    
+
     output += `**File:** ${doc.fileName}\n\n`;
     output += '---\n\n';
     output += doc.content;
-    
+
+    // Add cross-reference suggestions
+    output += `\n\n---\n\n`;
+    output += `## 🔍 Related Documentation:\n`;
+    if (doc.metadata?.keywords && doc.metadata.keywords.length > 0) {
+      output += `Consider searching for related topics:\n`;
+      const keywords = Array.isArray(doc.metadata.keywords) ? doc.metadata.keywords : [doc.metadata.keywords];
+      keywords.slice(0, 3).forEach(keyword => {
+        output += `- \`search_documentation("${keyword}")\`\n`;
+      });
+    }
+    output += `\n💡 **Before implementing**: Return to \`doc_bot()\` to verify this guidance aligns with current project state and your specific task.\n`;
+
     return output;
   }
 
@@ -1395,17 +1434,33 @@ Try:
     catalog += `- Get complete project philosophy and engineering principles\n`;
     catalog += `- Use when: Making architectural decisions or need comprehensive context\n\n`;
 
+    catalog += `---\n\n`;
+    catalog += `## 🔄 MANDATORY CHECKPOINTS - Return to doc_bot()\n\n`;
+    catalog += `You MUST call doc_bot() again when you:\n\n`;
+    catalog += `1. **Before file operations**: About to Write/Edit a new file? → \`doc_bot(task="modify [filepath]")\`\n`;
+    catalog += `2. **Context switches**: Moving to a different component/feature? → \`doc_bot(task="[new context]")\`\n`;
+    catalog += `3. **Errors encountered**: Hit an unexpected error? → \`doc_bot(task="debug [error]")\`\n`;
+    catalog += `4. **Decision points**: Multiple valid approaches? → \`doc_bot(task="decide [decision]")\`\n`;
+    catalog += `5. **Section completion**: Finished a major part? → \`doc_bot(task="review [what completed]")\`\n\n`;
+    catalog += `⚠️ **Failure to checkpoint leads to**:\n`;
+    catalog += `- Violating file-specific conventions you didn't know about\n`;
+    catalog += `- Using patterns that were recently deprecated\n`;
+    catalog += `- Missing performance/security requirements for that area\n\n`;
+
     catalog += `---\n\n`;
     catalog += `## Your Task: "${task}"\n\n`;
     catalog += `**You now have:**\n`;
     catalog += `✅ Mandatory project standards (above)\n`;
-    catalog += `✅ Tools to explore codebase-specific patterns (listed above)\n\n`;
+    catalog += `✅ Tools to explore codebase-specific patterns (listed above)\n`;
+    catalog += `✅ Checkpoint requirements for continuous compliance\n\n`;
 
-    catalog += `**Your decision:**\n`;
-    catalog += `- If you understand how to implement this correctly with the standards above → proceed\n`;
-    catalog += `- If you need to understand existing patterns in this codebase → use the tools above\n\n`;
+    catalog += `**Your immediate next steps:**\n`;
+    catalog += `1. Review the mandatory standards above\n`;
+    catalog += `2. Use additional tools if needed for this specific task\n`;
+    catalog += `3. Begin implementation\n`;
+    catalog += `4. **REMEMBER**: Return to doc_bot() at each checkpoint listed above\n\n`;
 
-    catalog += `Remember: You know the codebase context best. Use additional tools only if you need them.\n`;
+    catalog += `Remember: Continuous check-ins = Continuous correctness.\n`;
 
     return catalog;
   }