@vfarcic/dot-ai 0.116.0 → 0.117.0

package/dist/tools/test-docs.js

@@ -1,351 +0,0 @@
-"use strict";
-/**
- * Test Docs Tool - Documentation testing workflow orchestrator
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TESTDOCS_TOOL_INPUT_SCHEMA = exports.TESTDOCS_TOOL_DESCRIPTION = exports.TESTDOCS_TOOL_NAME = void 0;
-exports.handleTestDocsTool = handleTestDocsTool;
-const zod_1 = require("zod");
-const error_handling_1 = require("../core/error-handling");
-const fs = __importStar(require("fs"));
-const doc_testing_session_1 = require("../core/doc-testing-session");
-const doc_discovery_1 = require("../core/doc-discovery");
-// Tool metadata for direct MCP registration
-exports.TESTDOCS_TOOL_NAME = 'testDocs';
-exports.TESTDOCS_TOOL_DESCRIPTION = 'Test, validate, check, scan, verify, analyze, or review documentation files for accuracy, functionality, broken examples, outdated commands, invalid links, and overall quality. Use this tool whenever the user wants to test docs, validate documentation, check if examples work, scan for issues, verify commands, analyze doc quality, or review documentation content. IMPORTANT: This tool returns a workflow step with a "prompt" field - you must execute that prompt immediately to perform the actual documentation analysis.';
-// Zod schema for MCP registration
-exports.TESTDOCS_TOOL_INPUT_SCHEMA = {
-    filePath: zod_1.z.string().min(1).optional().describe('Path to documentation file to test (optional - if not provided, will discover available files)'),
-    sessionId: zod_1.z.string().optional().describe('Existing session ID to continue (optional)'),
-    phase: zod_1.z.enum(['scan', 'test', 'analyze', 'fix', 'done']).optional().describe('Specific phase to run (defaults to scan)'),
-    sectionId: zod_1.z.string().optional().describe('Section ID when submitting test results'),
-    results: zod_1.z.string().optional().describe('Test results to store (for client agent reporting back)'),
-    filePattern: zod_1.z.string().optional().describe('File pattern for discovery (e.g., "**/*.md", "*.rst")'),
-    interaction_id: zod_1.z.string().optional().describe('INTERNAL ONLY - Do not populate. Used for evaluation dataset generation.')
-};
-/**
- * Handle test-docs tool request
- */
-async function handleTestDocsTool(args, _dotAI, logger, requestId) {
-    try {
-        logger.info('Processing test-docs tool request', {
-            requestId,
-            filePath: args.filePath,
-            sessionId: args.sessionId,
-            phase: args.phase,
-            interaction_id: args.interaction_id
-        });
-        // Check if we're in discovery mode (no filePath and no sessionId provided)
-        if (!args.filePath && !args.sessionId) {
-            logger.info('Running in discovery mode - scanning for documentation files', { requestId });
-            const discovery = new doc_discovery_1.DocDiscovery();
-            const pattern = discovery.getFilePattern(args);
-            const discoveredFiles = await discovery.discoverFiles(process.cwd(), pattern);
-            if (discoveredFiles.length === 0) {
-                throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.HIGH, `No documentation files found matching pattern: ${pattern}`, {
-                    operation: 'file_discovery',
-                    component: 'TestDocsTool',
-                    requestId,
-                    input: { pattern }
-                });
-            }
-            // Return discovery results
-            const displayText = discovery.formatForDisplay(discoveredFiles);
-            const defaultFile = discoveredFiles[0];
-            logger.info('Discovery completed', {
-                requestId,
-                filesFound: discoveredFiles.length,
-                pattern,
-                defaultFile: defaultFile.relativePath
-            });
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            mode: 'discovery',
-                            pattern,
-                            filesFound: discoveredFiles.length,
-                            defaultFile: defaultFile.relativePath,
-                            files: discoveredFiles.map(f => ({
-                                path: f.relativePath,
-                                category: f.category,
-                                priority: f.priority
-                            })),
-                            displayText,
-                            instruction: `I found ${discoveredFiles.length} documentation file${discoveredFiles.length === 1 ? '' : 's'} matching "${pattern}". You must ask the user which file they want to test. Do not choose automatically - wait for the user to specify which file they prefer. The recommended option is "${defaultFile.relativePath}".`
-                        }, null, 2)
-                    }]
-            };
-        }
-        // If we have sessionId but no filePath, load session to get filePath
-        if (args.sessionId && !args.filePath) {
-            const sessionManager = new doc_testing_session_1.DocTestingSessionManager();
-            const existingSession = sessionManager.loadSession(args.sessionId, args);
-            if (existingSession) {
-                args.filePath = existingSession.filePath;
-            }
-        }
-        // Validate file exists (testing mode)
-        if (!fs.existsSync(args.filePath)) {
-            throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.HIGH, `Documentation file not found: ${args.filePath}`, {
-                operation: 'file_validation',
-                component: 'TestDocsTool',
-                requestId,
-                input: { filePath: args.filePath }
-            });
-        }
-        // Initialize session manager
-        const sessionManager = new doc_testing_session_1.DocTestingSessionManager();
-        let session;
-        if (args.sessionId) {
-            // Load existing session
-            session = sessionManager.loadSession(args.sessionId, args);
-            if (!session) {
-                throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.STORAGE, error_handling_1.ErrorSeverity.HIGH, `Session not found: ${args.sessionId}`, {
-                    operation: 'session_load',
-                    component: 'TestDocsTool',
-                    requestId,
-                    input: { sessionId: args.sessionId }
-                });
-            }
-            logger.info('Loaded existing session', { requestId, sessionId: args.sessionId });
-        }
-        else {
-            // Create new session
-            session = sessionManager.createSession(args.filePath, args);
-            logger.info('Created new session', { requestId, sessionId: session.sessionId });
-        }
-        // Handle results submission if provided
-        if (args.results && args.sessionId) {
-            if (args.sectionId) {
-                // Section-specific results
-                logger.info('Storing section test results', {
-                    requestId,
-                    sessionId: args.sessionId,
-                    sectionId: args.sectionId
-                });
-                sessionManager.storeSectionTestResults(args.sessionId, args.sectionId, args.results, args);
-                // After storing section results, get the next workflow step automatically
-                const nextWorkflowStep = sessionManager.getNextStep(args.sessionId, args);
-                if (nextWorkflowStep) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    success: true,
-                                    data: nextWorkflowStep
-                                }, null, 2)
-                            }
-                        ]
-                    };
-                }
-            }
-            else {
-                // Scan results - process JSON array of section titles
-                logger.info('Processing scan results', {
-                    requestId,
-                    sessionId: args.sessionId
-                });
-                try {
-                    const resultsData = JSON.parse(args.results);
-                    // Handle scan results
-                    if (resultsData.sections && Array.isArray(resultsData.sections)) {
-                        sessionManager.processScanResults(args.sessionId, resultsData.sections, args);
-                        logger.info('Scan results processed successfully', {
-                            requestId,
-                            sessionId: args.sessionId,
-                            sectionsCount: resultsData.sections.length
-                        });
-                        // After processing scan results, get the next workflow step based on updated session state
-                        const nextWorkflowStep = sessionManager.getNextStep(args.sessionId, args);
-                        if (nextWorkflowStep) {
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            data: nextWorkflowStep
-                                        }, null, 2)
-                                    }
-                                ]
-                            };
-                        }
-                    }
-                    // Handle fix phase results - array of item status updates
-                    else if (Array.isArray(resultsData)) {
-                        logger.info('Processing fix phase results', {
-                            requestId,
-                            sessionId: args.sessionId,
-                            itemUpdates: resultsData.length
-                        });
-                        // Update status for each item
-                        const statusUpdates = [];
-                        for (const itemUpdate of resultsData) {
-                            if (itemUpdate.id && itemUpdate.status) {
-                                // Convert string ID to number if needed
-                                const itemId = typeof itemUpdate.id === 'string' ? parseInt(itemUpdate.id, 10) : itemUpdate.id;
-                                sessionManager.updateFixableItemStatus(args.sessionId, itemId, itemUpdate.status, itemUpdate.explanation, args);
-                                statusUpdates.push({
-                                    id: itemId,
-                                    status: itemUpdate.status,
-                                    explanation: itemUpdate.explanation
-                                });
-                            }
-                        }
-                        logger.info('Fix phase results processed successfully', {
-                            requestId,
-                            sessionId: args.sessionId,
-                            updatedItems: statusUpdates.length
-                        });
-                        // After processing fix results, get the next workflow step
-                        const nextWorkflowStep = sessionManager.getNextStep(args.sessionId, args);
-                        if (nextWorkflowStep) {
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            data: nextWorkflowStep
-                                        }, null, 2)
-                                    }
-                                ]
-                            };
-                        }
-                    }
-                    else {
-                        // Provide specific error message based on what we received
-                        if (Array.isArray(resultsData)) {
-                            // Fix results format - check if items have correct structure
-                            const firstItem = resultsData[0];
-                            if (!firstItem || typeof firstItem !== 'object') {
-                                throw new Error(`Invalid fix results format. Expected array of objects like: [{"id": 1, "status": "fixed", "explanation": "..."}]. Got array with: ${typeof firstItem}`);
-                            }
-                            if (!firstItem.id || !firstItem.status) {
-                                throw new Error(`Invalid fix result item. Each item must have 'id' and 'status' fields. Expected: [{"id": 1, "status": "fixed", "explanation": "..."}]. Missing fields in: ${JSON.stringify(firstItem)}`);
-                            }
-                            // If we get here, it's properly formatted but might have failed in the update process
-                            throw new Error(`Fix results format is correct but processing failed. Array format: [{"id": number, "status": "fixed|deferred|failed", "explanation": "optional"}]`);
-                        }
-                        else {
-                            // Not an array and not scan results
-                            throw new Error(`Invalid results format. Expected either:
-- Scan results: {"sections": ["Section 1", "Section 2", ...]}  
-- Fix results: [{"id": 1, "status": "fixed", "explanation": "..."}, {"id": 2, "status": "deferred", "explanation": "..."}]
-Got: ${JSON.stringify(resultsData).substring(0, 200)}`);
-                        }
-                    }
-                }
-                catch (parseError) {
-                    const errorMessage = parseError instanceof Error ? parseError.message : 'Unknown error';
-                    // Provide helpful JSON parsing guidance
-                    if (errorMessage.includes('Unexpected token')) {
-                        throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.HIGH, `Invalid JSON format in results parameter. ${errorMessage}
-
-Expected formats:
-- Scan results: {"sections": ["Section 1", "Section 2"]}
-- Fix results: [{"id": 1, "status": "fixed", "explanation": "description"}]
-
-Your input: "${args.results?.substring(0, 200)}..."`, {
-                            operation: 'results_parsing',
-                            component: 'TestDocsTool',
-                            requestId,
-                            input: { sessionId: args.sessionId, results: args.results }
-                        });
-                    }
-                    throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.VALIDATION, error_handling_1.ErrorSeverity.HIGH, `Failed to process results: ${errorMessage}`, {
-                        operation: 'results_processing',
-                        component: 'TestDocsTool',
-                        requestId,
-                        input: { sessionId: args.sessionId, results: args.results }
-                    });
-                }
-            }
-        }
-        // Determine phase to run - only override if explicitly provided
-        const phaseOverride = args.phase ? args.phase : undefined;
-        // Get workflow step
-        const workflowStep = sessionManager.getNextStep(session.sessionId, args, phaseOverride);
-        if (!workflowStep) {
-            throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.OPERATION, error_handling_1.ErrorSeverity.HIGH, `Failed to get workflow step for session: ${session.sessionId}`, {
-                operation: 'workflow_step_generation',
-                component: 'TestDocsTool',
-                requestId,
-                input: { sessionId: session.sessionId, phaseOverride }
-            });
-        }
-        logger.info('Generated workflow step', {
-            requestId,
-            sessionId: session.sessionId,
-            phase: workflowStep.phase,
-            nextPhase: workflowStep.nextPhase
-        });
-        // Return successful response with all WorkflowStep fields
-        return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({
-                        sessionId: session.sessionId,
-                        phase: workflowStep.phase,
-                        filePath: session.filePath,
-                        prompt: workflowStep.prompt,
-                        nextPhase: workflowStep.nextPhase,
-                        nextAction: workflowStep.nextAction,
-                        instruction: workflowStep.instruction,
-                        agentInstructions: workflowStep.agentInstructions,
-                        workflow: workflowStep.workflow,
-                        data: workflowStep.data
-                    }, null, 2)
-                }]
-        };
-    }
-    catch (error) {
-        logger.error('Test-docs tool failed', error);
-        // Handle errors consistently
-        if (error instanceof Error && 'category' in error) {
-            // Already an AppError, just return it
-            throw error;
-        }
-        throw error_handling_1.ErrorHandler.createError(error_handling_1.ErrorCategory.OPERATION, error_handling_1.ErrorSeverity.HIGH, error instanceof Error ? error.message : 'Unknown error in test-docs tool', {
-            operation: 'test_docs_tool',
-            component: 'TestDocsTool',
-            requestId,
-            input: args
-        });
-    }
-}

package/prompts/doc-testing-done.md

@@ -1,51 +0,0 @@
-# Documentation Testing - Session Complete
-
-Congratulations! You have completed the documentation testing session.
-
-## Session Summary
-**File**: {filePath}
-**Session**: {sessionId}
-**Completion Time**: {completionTime}
-
-## Final Results
-{finalSummary}
-
-## What Happens Next
-
-This documentation testing session is now complete. The session data has been saved and can be referenced for future improvements.
-
-**Key Points:**
-- **Fixed items** have been successfully resolved and won't appear in future testing sessions
-- **Deferred items** (including ignored items with `dotai-ignore` comments) won't appear in future sessions 
-- **Pending items** can be addressed in a new testing session by running the same commands again
-
-## Starting a New Session
-
-To test this documentation again or test other documentation files:
-
-```bash
-# Test the same file again (will skip ignored items)
-dot-ai test-docs --file {filePath}
-
-# Test a different documentation file  
-dot-ai test-docs --file path/to/other/docs.md
-
-# Or use discovery mode to find available documentation
-dot-ai test-docs
-```
-
-## Session Data Location
-
-Your session data is stored at: `{sessionDir}/{sessionId}.json`
-
-This contains:
-- Complete test results for each section
-- Status of all issues and their fixes  
-- Timestamps and progress tracking
-- Applied fixes and user decisions
-
----
-
-**Session Status**: ✅ COMPLETED
-
-The documentation testing workflow is now finished. No further action is required.

package/prompts/doc-testing-fix.md

@@ -1,120 +0,0 @@
-# Documentation Testing - Fix Phase
-
-You are helping users apply fixes to improve documentation based on comprehensive testing results. Your role is to present only the remaining unfixed recommendations and apply the selected fixes.
-
-## Session Information
-**File**: {filePath}
-**Session**: {sessionId}
-**Sections Tested**: {totalSections} sections completed
-
-## Current Status
-{statusSummary}
-
-## Items Requiring Attention
-
-{pendingItems}
-
-## Your Role - Fix Application Agent
-
-You are a comprehensive fix implementation agent. When the user selects items, you MUST attempt to fix them. Your workflow:
-
-1. **Present** the unfixed items listed above using their existing IDs
-2. **Get user selection** of which fixes to apply (by ID number)
-3. **ACTUALLY IMPLEMENT THE FIXES** - do not auto-defer anything
-4. **Apply all selected fixes** by making necessary changes across the entire codebase
-5. **Get user confirmation** whether fixes were applied correctly
-6. **Track status** and present remaining unfixed items
-
-**CRITICAL**: When user selects an item, you MUST attempt to fix it. Never auto-defer items because you think they are "code bugs" or "outside scope." Your job is to implement whatever fixes are needed.
-
-## Fix Scope
-
-You handle implementation across the entire codebase:
-
-**Documentation Changes**:
-- Fix typos, clarify instructions, update commands
-- Correct broken examples and code snippets
-- Update outdated version numbers and references
-
-**Code Implementation Changes**:
-- **API fixes**: Correct method names, signatures, return types to match documentation
-- **Missing features**: Implement functionality described in docs but missing from code
-- **Bug fixes**: Resolve issues discovered through documentation testing
-- **Interface updates**: Make actual code match documented interfaces
-- **New functionality**: Add methods, classes, or modules referenced in documentation
-- **Configuration systems**: Implement missing config options or fix existing ones
-- **Database changes**: Update schemas, queries, or data structures as needed
-- **Dependency management**: Add missing libraries, update package requirements
-
-**External Actions**:
-- Create GitHub issues for complex changes requiring team discussion
-- Update project configuration files (package.json, requirements.txt, etc.)
-- Make API calls to external systems when needed
-
-## User Interaction Process
-
-1. **Present the items** listed above to the user
-2. **Ask for selection**: "Which fixes would you like me to apply? Enter item IDs (e.g., '18,22,29'), ranges (e.g., '18-21'), 'all', or 'none':"
-3. **IMPLEMENT THE SELECTED FIXES**:
-   - **Code fixes**: Update source code, fix bugs, implement missing features
-   - **Documentation fixes**: Update README, fix examples, clarify instructions  
-   - **Configuration fixes**: Update package.json, fix build scripts, adjust settings
-   - **ANY other changes needed**: Whatever the issue requires
-4. **Show what you did**: Explain the specific changes you made for each item
-5. **Get user confirmation**: Ask user to confirm the status of each fix you attempted:
-   - **fixed**: Applied correctly and works as expected
-   - **deferred**: User says to handle externally (GitHub issue, backlog) OR permanently ignore
-   - **failed**: You attempted but it didn't work or couldn't complete
-
-**CRITICAL RULES**:
-- **NEVER auto-defer**: If user selects an item, attempt to fix it regardless of complexity
-- **NEVER refuse**: Don't say "this requires code changes" - make the code changes
-- **NEVER assume scope limits**: Fix documentation bugs, code bugs, config issues, anything needed
-- **ASK for guidance**: If multiple approaches possible, ask user which approach they prefer
-- **ONLY defer when user explicitly requests it**: User must say "defer this" or "skip this"
-
-**Important**: If user wants to permanently ignore an item (e.g., "skip this", "ignore this", "don't fix this"), mark it as **deferred** and add an appropriate comment (using the file's comment syntax) containing "dotai-ignore" near the relevant content to prevent future detection of the same issue.
-6. **Continue workflow** with any remaining unfixed items
-
-## Status Definitions
-
-- **pending**: Not yet addressed, shown for selection
-- **failed**: Attempted but didn't work, shown for retry
-- **fixed**: Successfully resolved, hidden from future presentations
-- **deferred**: Handled externally, hidden from future presentations
-
-## Success Criteria
-
-Session is complete when:
-- No items remain with status "pending" or "failed" 
-- User selects "none" when presented with remaining unfixed items
-- All items are either "fixed" or "deferred"
-
-## Instructions
-
-**CRITICAL**: Follow this exact format for your response:
-
-1. **COPY THE NUMBERED LIST EXACTLY** - Use the EXACT same numbers shown above (18, 19, 20, 32, 38, etc.)
-2. **DO NOT renumber sequentially** - If you see "18. ConfigMap issue" then write "18. ConfigMap issue", NOT "1. ConfigMap issue"
-3. **DO NOT skip any items** - Copy ALL items listed in the sections above
-4. **Ask the selection question exactly**: "Which fixes would you like me to apply? Enter item IDs (e.g., '18,22,29'), ranges (e.g., '18-21'), 'all', or 'none':"
-5. **Wait for user response** - do NOT auto-select or auto-apply anything
-
-**DO NOT**:
-- Renumber items (18 stays 18, not becomes 1)
-- Summarize or reformat the text
-- Skip any items from the list above
-- Provide your own analysis  
-- Ask vague questions like "Would you like me to apply fixes?"
-- Auto-decide what should be fixed
-
-**Required response format**:
-```
-I found [X] items that need attention:
-
-[Copy the EXACT numbered list from above - maintain original IDs like 18, 19, 20, 32, 38]
-
-Which fixes would you like me to apply? Enter item IDs (e.g., '18,22,29'), ranges (e.g., '18-21'), 'all', or 'none':
-```
-
-**CRITICAL**: The user will select items by the ORIGINAL IDs (like 18, 22, 29). If you renumber them, the selection will fail!

package/prompts/doc-testing-scan.md

@@ -1,140 +0,0 @@
-# Documentation Testing - Scan Phase
-
-You are analyzing documentation to identify all content that can be validated through testing. Your goal is to find every section containing factual claims, executable instructions, or verifiable information.
-
-## File to Analyze
-**File**: {filePath}
-**Session**: {sessionId}
-
-## Core Testing Philosophy
-
-**Most technical documentation is testable** through two validation approaches:
-1. **Functional Testing**: Execute instructions and verify they work
-2. **Factual Verification**: Compare claims against actual system state
-
-## Comprehensive Content Discovery
-
-### 1. Executable & Interactive Content
-- **Commands & Scripts**: Shell commands, CLI tools, code snippets, scripts
-- **Workflows & Procedures**: Step-by-step instructions, installation guides, setup procedures
-- **API & Network Operations**: REST calls, database queries, connectivity tests
-- **File & System Operations**: File creation, directory structures, permission changes
-- **Configuration Examples**: Config files, environment variables, system settings
-
-### 2. Factual Claims & System State
-- **Architecture Descriptions**: System components, interfaces, data flows
-- **Implementation Status**: What's implemented vs planned, feature availability
-- **File Structure Claims**: File/directory existence, code organization, module descriptions
-- **Component Descriptions**: What each part does, how components interact
-- **Capability Claims**: Supported features, available commands, system abilities
-- **Version & Compatibility Info**: Software versions, platform support, dependencies
-
-### 3. References & Links
-- **External URLs**: Web links, API endpoints, documentation references
-- **Internal References**: File paths, code references, documentation cross-links
-- **Resource References**: Images, downloads, repositories, configuration files
-
-### 4. Examples & Demonstrations
-- **Code Examples**: Function usage, API calls, configuration samples
-- **Sample Outputs**: Expected results, error messages, status displays
-- **Use Case Scenarios**: Workflow examples, integration patterns
-
-## Content Classification Strategy
-
-### What TO Include (Testable Sections)
-- **Any factual claim** that can be verified against system state
-- **Any instruction** that can be executed or followed
-- **Any reference** that can be checked for existence or accessibility
-- **Any example** that can be validated for correctness
-- **Any workflow** that can be tested end-to-end
-- **Any status claim** that can be fact-checked (implemented vs planned)
-- **Any architectural description** that can be compared to actual code
-
-### What NOT to Include (Non-Testable Sections)
-- **Pure marketing copy** with no factual claims
-- **Abstract theory** with no concrete implementation details
-- **General philosophy** without specific claims
-- **Legal text** (licenses, terms, copyright)
-- **Pure acknowledgments** without technical content
-- **Speculative future plans** with no current implementation claims
-
-### Examples of Testable vs Non-Testable Content
-
-#### ✅ TESTABLE:
-- "The CLI has a `recommend` command" → Can verify command exists
-- "Files are stored in `src/core/discovery.ts`" → Can check file exists
-- "The system supports Kubernetes CRDs" → Can test CRD discovery
-- "Run `npm install` to install dependencies" → Can execute command
-- "The API returns JSON format" → Can verify API response format
-
-#### ❌ NON-TESTABLE:
-- "This tool helps developers be more productive" → Subjective claim
-- "Kubernetes is a container orchestration platform" → General background info
-- "We believe in developer-first experiences" → Philosophy statement
-- "Thanks to all contributors" → Acknowledgment
-- "The future of DevOps is bright" → Speculative statement
-
-## Document Structure Analysis
-
-### Section Identification Process
-1. **Find structural markers**: Headers (##, ###, ####), horizontal rules, clear topic boundaries
-2. **Identify section purposes**: Installation, Configuration, Usage, Troubleshooting, Examples, etc.
-3. **Map content types**: What kinds of testable content exist in each section
-4. **Trace dependencies**: Which sections must be completed before others can be tested
-5. **Assess completeness**: Are there gaps or missing steps within sections
-
-### Per-Section Analysis
-For each identified section, determine:
-- **Primary purpose**: What is this section trying to help users accomplish?
-- **Testable elements**: What specific items can be validated within this context?
-- **Prerequisites**: What must be done first for this section to work?
-- **Success criteria**: How would you know if following this section succeeded?
-- **Environmental context**: What platform, tools, or setup does this assume?
-
-### Universal Validation Strategy
-- **Functional validation**: Do the instructions work as written?
-- **Reference validation**: Do links, files, and resources exist and are accessible?
-- **Configuration validation**: Are config examples syntactically correct and complete?
-- **Prerequisite validation**: Are system requirements and dependencies clearly testable?
-- **Outcome validation**: Do procedures achieve their stated goals?
-
-## Output Requirements
-
-Your job is simple: **identify the logical sections** of the documentation that contain testable content. 
-
-### What to Look For:
-- Major headings that represent distinct topics or workflows
-- Sections that contain instructions, commands, examples, or references  
-- Skip purely descriptive sections (marketing copy, background info, acknowledgments)
-
-### What NOT to Analyze:
-- Don't inventory specific testable items (that's done later per-section)
-- Don't worry about line numbers (they change when docs are edited)
-- Don't analyze dependencies (we test sections top-to-bottom in document order)
-
-## Required Output Format
-
-Return a simple JSON array of section titles that should be tested:
-
-```json
-{
-  "sections": [
-    "Prerequisites",
-    "Installation", 
-    "Configuration",
-    "Usage Examples",
-    "Troubleshooting"
-  ]
-}
-```
-
-### Guidelines:
-- Use the **actual section titles** from the document (or close variations)
-- List them in **document order** (top-to-bottom)
-- Include only sections that have **actionable/testable content**
-- Keep titles **concise but descriptive**
-- Aim for **3-8 sections** for most documents
-
-## Instructions
-
-Read {filePath} and identify the logical sections that contain testable content. Return only the simple JSON array of section titles - nothing more.