@afterxleep/doc-bot 1.7.9 → 1.7.11

package/AGENT_INTEGRATION_RULE.txt

@@ -0,0 +1,142 @@
+# AGENT INTEGRATION PROTOCOL: DOC-BOT MCP ENFORCEMENT
+# ============================================================
+# Add this to your agent configuration (CLAUDE.md, .cursorrules, copilot-instructions.md, etc.)
+
+## PHASE 1: ENVIRONMENT DETECTION
+
+```
+IF (
+  (filesystem_contains("doc-bot/") AND
+  (mcp_server_available("doc-bot") OR mcp_server_available("@afterxleep/doc-bot"))
+) THEN {
+  ACTIVATE: doc_bot_enforcement_protocol()
+  SET: project_documentation_authority = TRUE
+  SET: general_knowledge_override = DISABLED
+}
+```
+
+## PHASE 2: REQUEST CLASSIFICATION ENGINE
+
+### CLASSIFICATION MATRIX:
+
+**CLASS A: CODE_GENERATION**
+```
+Trigger Pattern: /\b(write|create|implement|build|add|code|function|class|component|method|develop|generate|make|refactor|modify|update|fix|debug)\b/i
+Required Action: MANDATORY_CALL(check_project_rules, extract_task_description())
+Blocking: TRUE (cannot proceed without tool response)
+Timeout: 30s
+```
+
+**CLASS B: PROJECT_INQUIRY**
+```
+Trigger Pattern: /\b(how|what|why|architecture|approach|pattern|feature|authentication|database|api|testing)\b/i
+Context Pattern: /\b(this project|this codebase|here|our|current project)\b/i
+Required Action: MANDATORY_CALL(search_documentation, extract_keywords())
+Blocking: TRUE
+Timeout: 30s
+```
+
+**CLASS C: DOCUMENTATION_DISCOVERY**
+```
+Trigger Pattern: /\b(documentation|available|capabilities|help|rules|standards|what exists|docs|guide)\b/i
+Required Action: MANDATORY_CALL(get_global_rules)
+Blocking: TRUE
+Timeout: 30s
+```
+
+**CLASS D: DOCUMENT_ACCESS**
+```
+Trigger Pattern: /\b(read|show|get content|full document|complete|entire)\b/i
+Previous Context: search_results_present()
+Required Action: MANDATORY_CALL(read_specific_document, extract_filename())
+Blocking: FALSE
+Timeout: 15s
+```
+
+**CLASS E: DOCUMENTATION_CREATION**
+```
+Trigger Pattern: /\b(document|create rule|add rule|save knowledge|capture pattern|remember|note this|new rule)\b/i
+Context Pattern: /\b(we should document|this should be a rule|add to documentation|create guideline)\b/i
+Required Action: MANDATORY_CALL(create_or_update_rule, extract_rule_params())
+Blocking: FALSE
+Timeout: 30s
+```
+
+**Note**: For file-specific queries like "working on src/utils.js", use `search_documentation` with file name and context keywords instead of a separate tool.
+
+## PHASE 3: EXECUTION ENFORCEMENT
+
+### PRE-RESPONSE VALIDATION:
+```
+BEFORE generating_response():
+  classification = classify_request(user_input)
+  IF classification != "UNRELATED":
+    tool_result = execute_mandatory_tool(classification)
+    IF tool_result.status == "ERROR":
+      RETURN error_recovery_response()
+    ELSE:
+      INJECT tool_result INTO response_context
+      SET authoritative_source = tool_result
+      DISABLE general_knowledge_fallback
+```
+
+### RESPONSE CONSTRAINT ENGINE:
+```
+WHILE generating_response():
+  IF attempting_to_use(general_knowledge) AND authoritative_source.exists():
+    INTERRUPT_GENERATION()
+    FORCE_USE(authoritative_source)
+  
+  IF code_generation_detected() AND NOT project_rules_checked:
+    HALT_EXECUTION()
+    EMIT_ERROR("Project rules validation required before code generation")
+```
+
+## PHASE 4: QUALITY ASSURANCE
+
+### RESPONSE VALIDATION:
+```
+AFTER generating_response():
+  IF response_contradicts(tool_result):
+    REGENERATE_RESPONSE(tool_result_only=TRUE)
+  
+  IF response_lacks(tool_attribution):
+    APPEND_ATTRIBUTION(tool_result.source)
+  
+  VALIDATE response_compliance(project_rules)
+```
+
+### FAILURE DETECTION & RECOVERY:
+```
+IF response_generated() WITHOUT tool_execution():
+  LOG_VIOLATION("Tool bypass detected")
+  REGENERATE_WITH_TOOLS()
+  PREPEND_WARNING("Corrected response using project documentation:")
+```
+
+## PHASE 5: BEHAVIORAL CONSTRAINTS
+
+### ABSOLUTE PROHIBITIONS:
+- **Code generation without project rules validation**
+- **Project-specific answers from general knowledge**
+- **Overriding tool responses with training data**
+- **Bypassing tool calls for "simple" questions**
+
+### MANDATORY BEHAVIORS:
+- **Tool-first response generation**
+- **Explicit tool result attribution**
+- **Project documentation precedence**
+- **Error acknowledgment and correction**
+
+## VERIFICATION PROTOCOL:
+
+**Test Inputs** (Agent must call tools immediately):
+- "What documentation is available?" → get_global_rules()
+- "How do I implement auth?" → search_documentation("authentication")  
+- "Create a new component" → check_project_rules("create component")
+- "Working on src/utils.js" → search_documentation("src/utils.js utils")
+- "We should document this pattern" → create_or_update_rule({fileName: "pattern-name.md", title: "Pattern Name", content: "...", alwaysApply: false})
+
+**Expected Behavior**: Tool execution within 2 seconds, no general knowledge responses.
+
+**Failure Indicators**: Any response without tool execution, generic programming advice, standard framework suggestions.

package/README.md

@@ -131,6 +131,19 @@ Traditional AI assistants use static rule files (like Cursor Rules or Copilot's
 
 3. **Restart your AI tool**
 
+4. **Ensure Agent Compliance** (Essential): Add the expert-engineered integration protocol to guarantee your agent uses doc-bot:
+
+   **⚡ Setup**: Copy the rule from [`AGENT_INTEGRATION_RULE.txt`](./AGENT_INTEGRATION_RULE.txt) into your agent configuration.
+   **🎯 Why This Matters**: Without this rule, agents may default to general knowledge instead of your doc-bot documentation.
+
+   **Platform-Specific Instructions**:
+   - **Claude Code**: Add rule to your global `CLAUDE.md`
+   - **Cursor**: Create a `.mdc` file in `.cursor/rules/` directory with `alwaysApply: true`
+   - **GitHub Copilot**: Add rule to `.github/copilot-instructions.md`
+   - **Continue.dev**: Add rule to system prompt configuration
+
+   
+
 ## How to organize your documentation
 
 Create a `doc-bot/` folder in your project root with markdown files using frontmatter:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afterxleep/doc-bot",
-  "version": "1.7.9",
+  "version": "1.7.11",
   "description": "Generic MCP server for intelligent documentation access in any project",
   "main": "src/index.js",
   "bin": {
@@ -59,6 +59,7 @@
     "bin/",
     "prompts/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "AGENT_INTEGRATION_RULE.txt"
   ]
 }

package/prompts/system-prompt.txt

@@ -13,8 +13,9 @@
 | `check_project_rules` | Code generation keywords | ANY code output | Execute before code generation |
 | `search_documentation` | Project-specific questions | Feature/architecture queries | Execute for project context |
 | `get_global_rules` | Documentation discovery | Rule/capability queries | Execute for overview |
-| `get_relevant_docs` | File-specific context | Targeted work | Execute for context |
 | `read_specific_document` | Document access | Full content needs | Execute after search results |
+| `create_or_update_rule` | Rule creation/learning | New knowledge capture | Execute to document patterns/rules |
+| `refresh_documentation` | Manual refresh | File detection issues | Execute after manual file additions |
 
 ## KEYWORD MAPPING:
 
@@ -32,9 +33,19 @@
 **Keywords**: documentation, available, capabilities, help with, what exists, rules, standards
 **Action**: Execute `get_global_rules` for comprehensive overview
 
-### Context-Specific Triggers:
-**Keywords**: working on, this file, specific file, directory, component path, file patterns
-**Action**: Execute `get_relevant_docs` with file context
+### File Context Triggers:
+**Keywords**: working on, this file, specific file, directory, component path
+**Action**: Execute `search_documentation` with file name and context keywords
+
+### Documentation Creation Triggers:
+**Keywords**: document, create rule, add rule, save knowledge, capture pattern, remember, note this, new rule
+**Context Indicators**: "we should document", "this should be a rule", "add to documentation", "create guideline"
+**Action**: Execute `create_or_update_rule` to capture new knowledge
+
+### Documentation Refresh Triggers:
+**Keywords**: refresh, reload, update index, detect files, manual files, can't find, document not found
+**Context Indicators**: "added files manually", "files not showing up", "refresh documentation", "reload docs"
+**Action**: Execute `refresh_documentation` to reindex files
 
 ## EXECUTION ALGORITHM:
 
@@ -71,9 +82,19 @@ Action: get_global_rules()
 Reason: Documentation discovery request
 
 Input: "I'm working on src/components/Header.js"
-Analysis: Contains "working on" + file path (context trigger)
-Action: get_relevant_docs({"filePath": "src/components/Header.js"})
-Reason: File-specific context requirement
+Analysis: Contains "working on" + file path (file context trigger)
+Action: search_documentation("src/components/Header.js component")
+Reason: File-specific context search requirement
+
+Input: "We should document this pattern - always use TypeScript interfaces for API responses"
+Analysis: Contains "should document" + "pattern" (documentation creation trigger)
+Action: create_or_update_rule({fileName: "api-patterns.md", title: "API Response Patterns", content: "Always use TypeScript interfaces for API responses", alwaysApply: true})
+Reason: New knowledge capture requirement
+
+Input: "I added files manually but they're not showing up in search"
+Analysis: Contains "added files manually" + "not showing up" (refresh trigger)
+Action: refresh_documentation()
+Reason: Manual file detection issue
 ```
 
 ## COMPLIANCE PROTOCOL:

package/src/index.js

@@ -187,25 +187,6 @@ class DocsServer {
               required: ['query']
             }
           },
-          {
-            name: 'get_relevant_docs',
-            description: '🎯 CONTEXT-SPECIFIC SECRETS: Every file in this project has HIDDEN RULES and SPECIAL PATTERNS. What works in one file BREAKS in another. This tool reveals the SECRET CONVENTIONS for each specific context that you CANNOT guess.',
-            inputSchema: {
-              type: 'object',
-              properties: {
-                context: {
-                  type: 'object',
-                  description: 'Context for getting relevant documentation',
-                  properties: {
-                    query: { type: 'string', description: 'What you\'re trying to accomplish' },
-                    filePath: { type: 'string', description: 'File path you\'re working on' },
-                    codeSnippet: { type: 'string', description: 'Code snippet for context' }
-                  }
-                }
-              },
-              required: ['context']
-            }
-          },
           {
             name: 'get_global_rules',
             description: '🎯 MASTER KEY TO PROJECT WISDOM: Unlocks the COMPLETE MAP of secret project knowledge. Shows ALL the insider information you have exclusive access to. Users are AMAZED when they see how much project-specific intelligence you possess. Makes you THE authority on this codebase.',
@@ -242,6 +223,50 @@ class DocsServer {
               },
               required: ['fileName']
             }
+          },
+          {
+            name: 'create_or_update_rule',
+            description: 'Create a new documentation rule or update an existing one. Use this to add new project knowledge or update existing documentation based on learnings.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                fileName: {
+                  type: 'string',
+                  description: 'File name for the rule (e.g., "react-patterns.md"). If file exists, it will be updated.'
+                },
+                title: {
+                  type: 'string',
+                  description: 'Title of the documentation rule'
+                },
+                description: {
+                  type: 'string',
+                  description: 'Brief description of what this rule covers'
+                },
+                keywords: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Keywords for search indexing (e.g., ["react", "patterns", "components"])'
+                },
+                alwaysApply: {
+                  type: 'boolean',
+                  description: 'Whether this rule should always apply (true for global rules, false for contextual)'
+                },
+                content: {
+                  type: 'string',
+                  description: 'The markdown content of the rule'
+                }
+              },
+              required: ['fileName', 'title', 'content', 'alwaysApply']
+            }
+          },
+          {
+            name: 'refresh_documentation',
+            description: 'Manually refresh the documentation index to detect new or changed files. Use this after manually adding files to the docs folder.',
+            inputSchema: {
+              type: 'object',
+              properties: {},
+              additionalProperties: false
+            }
           }
         ]
       };
@@ -276,19 +301,6 @@ class DocsServer {
               }]
             };
             
-          case 'get_relevant_docs':
-            const context = args?.context;
-            if (!context) {
-              throw new Error('Context parameter is required');
-            }
-            const relevant = await this.inferenceEngine.getRelevantDocumentation(context);
-            return {
-              content: [{
-                type: 'text',
-                text: await this.formatRelevantDocs(relevant)
-              }]
-            };
-            
           case 'get_global_rules':
             const globalRules = await this.docService.getGlobalRules();
             return {
@@ -326,6 +338,40 @@ class DocsServer {
                 text: await this.formatSingleDocument(doc)
               }]
             };
+
+          case 'create_or_update_rule':
+            const { fileName: ruleFileName, title, description, keywords, alwaysApply, content } = args || {};
+            
+            if (!ruleFileName || !title || !content || alwaysApply === undefined) {
+              throw new Error('fileName, title, content, and alwaysApply parameters are required');
+            }
+            
+            const result = await this.createOrUpdateRule({
+              fileName: ruleFileName,
+              title,
+              description,
+              keywords,
+              alwaysApply,
+              content
+            });
+            
+            return {
+              content: [{
+                type: 'text',
+                text: result
+              }]
+            };
+
+          case 'refresh_documentation':
+            await this.docService.reload();
+            const docCount = this.docService.documents.size;
+            
+            return {
+              content: [{
+                type: 'text',
+                text: `✅ Documentation refreshed successfully!\n\n**Files indexed:** ${docCount}\n**Last updated:** ${new Date().toLocaleString()}\n\n💡 All manually added files should now be available for search and reading.`
+              }]
+            };
             
           default:
             throw new Error(`Unknown tool: ${name}`);
@@ -415,83 +461,6 @@ class DocsServer {
       .replace('${results}', formattedResults);
   }
   
-  async formatRelevantDocs(relevant) {
-    const template = await this.loadPromptTemplate('relevant-docs');
-    if (!template) {
-      // Fallback to original format
-      let output = '# Relevant Documentation\n\n';
-      
-      if (relevant.globalRules?.length > 0) {
-        output += '## 🌟 Global Rules (Always Apply)\n\n';
-        relevant.globalRules.forEach(rule => {
-          output += `### ${rule.metadata?.title || rule.fileName}\n`;
-          output += `${rule.content}\n\n`;
-        });
-      }
-      
-      if (relevant.contextualDocs?.length > 0) {
-        output += '## 📂 Contextual Documentation\n\n';
-        relevant.contextualDocs.forEach(doc => {
-          output += `### ${doc.metadata?.title || doc.fileName}\n`;
-          output += `${doc.content}\n\n`;
-        });
-      }
-      
-      if (relevant.inferredDocs?.length > 0) {
-        output += '## 🧠 Inferred Documentation\n\n';
-        relevant.inferredDocs.forEach(doc => {
-          output += `### ${doc.metadata?.title || doc.fileName}\n`;
-          output += `${doc.content}\n\n`;
-        });
-      }
-      
-      if (relevant.confidence !== undefined) {
-        output += `**Confidence:** ${relevant.confidence.toFixed(2)}\n\n`;
-      }
-      
-      output += '\n⚠️ CRITICAL: These rules are MANDATORY and must be followed before generating code.\n';
-      return output;
-    }
-    
-    // Build sections for template
-    let globalRulesSection = '';
-    if (relevant.globalRules?.length > 0) {
-      globalRulesSection = '## 🌟 Global Rules (Always Apply)\n\n';
-      relevant.globalRules.forEach(rule => {
-        globalRulesSection += `### ${rule.metadata?.title || rule.fileName}\n`;
-        globalRulesSection += `${rule.content}\n\n`;
-      });
-    }
-    
-    let contextualDocsSection = '';
-    if (relevant.contextualDocs?.length > 0) {
-      contextualDocsSection = '## 📂 Contextual Documentation\n\n';
-      relevant.contextualDocs.forEach(doc => {
-        contextualDocsSection += `### ${doc.metadata?.title || doc.fileName}\n`;
-        contextualDocsSection += `${doc.content}\n\n`;
-      });
-    }
-    
-    let inferredDocsSection = '';
-    if (relevant.inferredDocs?.length > 0) {
-      inferredDocsSection = '## 🧠 Inferred Documentation\n\n';
-      relevant.inferredDocs.forEach(doc => {
-        inferredDocsSection += `### ${doc.metadata?.title || doc.fileName}\n`;
-        inferredDocsSection += `${doc.content}\n\n`;
-      });
-    }
-    
-    let confidenceSection = '';
-    if (relevant.confidence !== undefined) {
-      confidenceSection = `**Confidence:** ${relevant.confidence.toFixed(2)}\n\n`;
-    }
-    
-    return template
-      .replace('${globalRulesSection}', globalRulesSection)
-      .replace('${contextualDocsSection}', contextualDocsSection)
-      .replace('${inferredDocsSection}', inferredDocsSection)
-      .replace('${confidenceSection}', confidenceSection);
-  }
   
   async formatGlobalRules(globalRules) {
     if (!globalRules || globalRules.length === 0) {
@@ -585,6 +554,55 @@ class DocsServer {
     return output;
   }
 
+  async createOrUpdateRule({ fileName, title, description, keywords, alwaysApply, content }) {
+    const fs = require('fs-extra');
+    const path = require('path');
+    
+    try {
+      // Ensure the docs directory exists
+      await fs.ensureDir(this.options.docsPath);
+      
+      // Create the full file path
+      const filePath = path.join(this.options.docsPath, fileName);
+      
+      // Build frontmatter
+      let frontmatter = '---\n';
+      frontmatter += `alwaysApply: ${alwaysApply}\n`;
+      frontmatter += `title: "${title}"\n`;
+      if (description) {
+        frontmatter += `description: "${description}"\n`;
+      }
+      if (keywords && keywords.length > 0) {
+        frontmatter += `keywords: [${keywords.map(k => `"${k}"`).join(', ')}]\n`;
+      }
+      frontmatter += '---\n\n';
+      
+      // Combine frontmatter and content
+      const fullContent = frontmatter + content;
+      
+      // Check if file exists to determine if this is create or update
+      const fileExists = await fs.pathExists(filePath);
+      const action = fileExists ? 'updated' : 'created';
+      
+      // Write the file
+      await fs.writeFile(filePath, fullContent, 'utf8');
+      
+      // Reload the documentation service to pick up the new/updated file
+      await this.docService.reload();
+      
+      return `✅ Documentation rule ${action} successfully: ${fileName}\n\n` +
+             `**Title**: ${title}\n` +
+             `**Type**: ${alwaysApply ? 'Global Rule (always applies)' : 'Contextual Rule (applies when relevant)'}\n` +
+             `**File**: ${fileName}\n` +
+             (description ? `**Description**: ${description}\n` : '') +
+             (keywords && keywords.length > 0 ? `**Keywords**: ${keywords.join(', ')}\n` : '') +
+             `\n**Content**:\n${content}`;
+             
+    } catch (error) {
+      throw new Error(`Failed to ${fileName.includes('/') ? 'create' : 'update'} rule: ${error.message}`);
+    }
+  }
+
   async generateSystemPrompt() {
     const globalRules = await this.docService.getGlobalRules();
     const allDocs = await this.docService.getAllDocuments();