mcp-adr-analysis-server 2.0.24 → 2.1.0

package/README.md

@@ -6,9 +6,18 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/)
 
-**AI-powered architectural analysis for intelligent development workflows.** This Model Context Protocol (MCP) server provides immediate, actionable architectural insights instead of prompts. Get real ADR suggestions, technology analysis, and security recommendations through OpenRouter.ai integration.
+> **AI-powered architectural analysis for intelligent development workflows.** Returns actual analysis results, not prompts to submit elsewhere.
 
-**Key Differentiator**: Returns actual analysis results, not prompts to submit elsewhere.
+## TL;DR
+
+**What:** MCP server that provides AI-powered architectural decision analysis and ADR management  
+**Who:** AI coding assistants (Claude, Cline, Cursor), enterprise architects, development teams  
+**Why:** Get immediate architectural insights instead of prompts, with 95% confidence scoring  
+**How:** `npm install -g mcp-adr-analysis-server` → Configure with OpenRouter API → Start analyzing
+
+**Key Features:** Tree-sitter AST analysis • Security content masking • Test-driven development • Deployment readiness validation
+
+---
 
 **Author**: [Tosin Akinosho](https://github.com/tosin2013) | **Repository**: [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server.git)
 
@@ -21,96 +30,30 @@ The Model Context Protocol enables seamless integration between AI assistants an
 🤖 **AI-Powered Analysis** - Immediate architectural insights with OpenRouter.ai integration
 🏗️ **Technology Detection** - Identify any tech stack and architectural patterns
 📋 **ADR Management** - Generate, suggest, and maintain Architectural Decision Records
+🔗 **Smart Code Linking** - AI-powered discovery of code files related to ADRs and decisions
 🛡️ **Security & Compliance** - Detect and mask sensitive content automatically
-📊 **Workflow Automation** - Todo generation, deployment tracking, and rule validation
-🧪 **TDD Integration** - Two-phase Test-Driven Development with ADR linking and validation
-🔍 **Mock Detection** - Sophisticated analysis to distinguish mock from production code
-🚀 **Deployment Readiness** - Zero-tolerance test validation with deployment history tracking and hard blocking
-
+🧪 **TDD Integration** - Two-phase Test-Driven Development with validation
+🚀 **Deployment Readiness** - Zero-tolerance test validation with hard blocking
 
+📖 **[View Full Capabilities →](docs/explanation/)**
 
-## 📦 Installation
+## 📦 Quick Installation
 
-### NPM Installation (Recommended)
 ```bash
-# Global installation
+# Global installation (recommended)
 npm install -g mcp-adr-analysis-server
 
-# Local installation
-npm install mcp-adr-analysis-server
-```
-
-### RHEL 9/10 Installation (Recommended for RHEL systems)
-```bash
-# Download and run the RHEL-specific installer
+# RHEL 9/10 systems (special installer)
 curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash
-
-# Or if you have the repository cloned:
-git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
-cd mcp-adr-analysis-server
-./scripts/install-rhel.sh
-```
-
-**Why RHEL needs special handling:**
-- RHEL 9/10 have specific npm PATH and permission issues
-- Global npm installations often fail due to SELinux policies
-- The script handles npm prefix configuration and PATH setup automatically
-
-### From Source
-```bash
-git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
-cd mcp-adr-analysis-server
-npm install
-npm run build
-npm start
 ```
 
-## 🤖 AI Execution Configuration
-
-The MCP server supports **AI-powered execution** that transforms tools from returning prompts to returning actual results. This solves the fundamental UX issue where AI agents receive prompts instead of actionable data.
-
-### Quick Setup
-
-1. **Get OpenRouter API Key**: Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
-2. **Set Environment Variables**:
-   ```bash
-   OPENROUTER_API_KEY=your_openrouter_api_key_here
-   EXECUTION_MODE=full
-   AI_MODEL=anthropic/claude-3-sonnet
-   ```
-3. **Restart MCP Server**: Tools now return actual results instead of prompts!
+📖 **[Detailed Installation Guide →](docs/tutorials/01-first-steps.md)** | **[RHEL Setup →](scripts/install-rhel.sh)**
 
-### Environment Variables
+## ⚡ Quick Setup (3 Steps)
 
-#### **AI Execution (Recommended)**
-- **`OPENROUTER_API_KEY`** (Required for AI): OpenRouter API key from https://openrouter.ai/keys
-- **`EXECUTION_MODE`** (Optional): `full` (AI execution) or `prompt-only` (legacy)
-- **`AI_MODEL`** (Optional): AI model to use (see supported models below)
-
-#### **Performance Tuning (Optional)**
-- **`AI_TEMPERATURE`** (Optional): Response consistency (0-1, default: 0.1)
-- **`AI_MAX_TOKENS`** (Optional): Response length limit (default: 4000)
-- **`AI_TIMEOUT`** (Optional): Request timeout in ms (default: 60000)
-- **`AI_CACHE_ENABLED`** (Optional): Enable response caching (default: true)
-
-#### **Project Configuration**
-- **`PROJECT_PATH`** (Required): Path to the project directory to analyze
-- **`ADR_DIRECTORY`** (Optional): Directory containing ADR files (default: `docs/adrs`)
-- **`LOG_LEVEL`** (Optional): Logging level (DEBUG, INFO, WARN, ERROR)
-
-### Supported AI Models
-
-| Model | Provider | Use Case | Input Cost | Output Cost |
-|-------|----------|----------|------------|-------------|
-| `anthropic/claude-3-sonnet` | Anthropic | Analysis, reasoning | $3.00/1K | $15.00/1K |
-| `anthropic/claude-3-haiku` | Anthropic | Quick tasks | $0.25/1K | $1.25/1K |
-| `openai/gpt-4o` | OpenAI | Versatile analysis | $5.00/1K | $15.00/1K |
-| `openai/gpt-4o-mini` | OpenAI | Cost-effective | $0.15/1K | $0.60/1K |
-
-## ⚙️ Client Configuration
-
-### Claude Desktop (Recommended Setup)
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+1. **Get API Key**: [OpenRouter.ai/keys](https://openrouter.ai/keys)
+2. **Set Environment**: `OPENROUTER_API_KEY=your_key` + `EXECUTION_MODE=full`
+3. **Configure Client**: Add to Claude Desktop, Cline, Cursor, or Windsurf
 
 ```json
 {
@@ -119,824 +62,136 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
       "command": "mcp-adr-analysis-server",
       "env": {
         "PROJECT_PATH": "/path/to/your/project",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-sonnet",
-        "EXECUTION_MODE": "full",
-        "ADR_DIRECTORY": "docs/adrs",
-        "LOG_LEVEL": "ERROR"
+        "OPENROUTER_API_KEY": "your_key_here",
+        "EXECUTION_MODE": "full"
       }
     }
   }
 }
 ```
 
-### Cline (VS Code Extension)
-Add to your `cline_mcp_settings.json`:
+📖 **[Full Configuration Guide →](docs/reference/mcp-client-config.md)** | **[Client Setup →](docs/reference/environment-config.md)**
 
-```json
-{
-  "mcpServers": {
-    "mcp-adr-analysis-server": {
-      "command": "npx",
-      "args": ["mcp-adr-analysis-server"],
-      "env": {
-        "PROJECT_PATH": "${workspaceFolder}",
-        "ADR_DIRECTORY": "docs/adrs",
-        "LOG_LEVEL": "ERROR"
-      }
-    }
-  }
-}
-```
+## 🚀 Usage Examples
 
-### Cursor
-Create `.cursor/mcp.json` in your project:
+**Ask Claude (or any MCP client):**
 
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "npx",
-      "args": ["mcp-adr-analysis-server"],
-      "env": {
-        "PROJECT_PATH": ".",
-        "ADR_DIRECTORY": "docs/adrs",
-        "LOG_LEVEL": "ERROR"
-      }
-    }
-  }
-}
-```
+> "Analyze this React project's architecture and suggest ADRs for any implicit decisions"
 
-### Windsurf
-Add to `~/.codeium/windsurf/mcp_config.json`:
+> "Generate ADRs from the PRD.md file and create a todo.md with implementation tasks"
 
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "args": [],
-      "env": {
-        "PROJECT_PATH": "/path/to/your/project",
-        "ADR_DIRECTORY": "docs/adrs",
-        "LOG_LEVEL": "ERROR"
-      }
-    }
-  }
-}
-```
+> "Check this codebase for security issues and provide masking recommendations"
 
-## 🚀 Usage Examples
+**The server returns actual analysis results** instead of prompts to submit elsewhere!
 
-### Basic Project Analysis
 ```typescript
-// Analyze any project's technology stack and architecture
+// Basic project analysis
 const analysis = await analyzeProjectEcosystem({
-  projectPath: "/path/to/project",
-  analysisType: "comprehensive"
+  projectPath: '/path/to/project',
+  analysisType: 'comprehensive',
 });
 
-// Get intelligent architectural insights
-const context = await getArchitecturalContext({
-  projectPath: "/path/to/project",
-  focusAreas: ["security", "scalability", "maintainability"]
-});
-```
-
-### ADR Generation from Requirements
-```typescript
-// Convert PRD to structured ADRs
+// Generate ADRs from requirements
 const adrs = await generateAdrsFromPrd({
-  prdPath: "docs/PRD.md",
-  outputDirectory: "docs/adrs",
-  template: "nygard"
-});
-
-// Generate actionable todos from ADRs with enhanced TDD approach
-const todos = await generateAdrTodo({
-  adrDirectory: "docs/adrs",
-  outputPath: "todo.md",
-  phase: "both",           // Two-phase TDD: test + production
-  linkAdrs: true,          // Link all ADRs for system-wide coverage
-  includeRules: true       // Include architectural rules validation
-});
-```
-
-### Enhanced TDD Workflow
-```typescript
-// Phase 1: Generate comprehensive test specifications
-const testPhase = await generateAdrTodo({
-  adrDirectory: "docs/adrs",
-  outputPath: "todo-tests.md",
-  phase: "test",           // Generate mock test specifications
-  linkAdrs: true,          // Connect all ADRs for complete test coverage
-  includeRules: true       // Validate against architectural rules
-});
-
-// Phase 2: Generate production implementation tasks
-const prodPhase = await generateAdrTodo({
-  adrDirectory: "docs/adrs", 
-  outputPath: "todo-implementation.md",
-  phase: "production",     // Generate production-ready implementation tasks
-  linkAdrs: true,          // Ensure system-wide consistency
-  includeRules: true       // Enforce architectural compliance
-});
-
-// Validate progress and detect mock vs production code
-const validation = await compareAdrProgress({
-  todoPath: "todo.md",
-  adrDirectory: "docs/adrs",
-  projectPath: "/path/to/project",
-  deepCodeAnalysis: true,     // Distinguish mock from production code
-  functionalValidation: true, // Validate code actually works
-  strictMode: true           // Reality-check against LLM overconfidence
-});
-```
-
-### Security and Compliance
-```typescript
-// Analyze and mask sensitive content
-const maskedContent = await maskContent({
-  content: "API_KEY=secret123",
-  maskingLevel: "strict"
-});
-
-// Validate architectural rules
-const validation = await validateRules({
-  projectPath: "/path/to/project",
-  ruleSet: "enterprise-security"
-});
-```
-
-### Research and Documentation
-```typescript
-// Generate context-aware research questions
-const questions = await generateResearchQuestions({
-  projectContext: analysis,
-  focusArea: "microservices-migration"
-});
-
-// Incorporate research findings
-const updatedAdrs = await incorporateResearch({
-  researchFindings: findings,
-  adrDirectory: "docs/adrs"
-});
-```
-
-### Advanced Validation & Quality Assurance
-```typescript
-// Comprehensive validation with mock detection
-const qualityCheck = await compareAdrProgress({
-  todoPath: "todo.md",
-  adrDirectory: "docs/adrs",
-  projectPath: "/path/to/project",
-  
-  // Prevent LLM deception about code completeness
-  deepCodeAnalysis: true,        // Detects mock patterns vs real implementation
-  functionalValidation: true,    // Tests if code actually works
-  strictMode: true,             // Reality-check mechanisms
-  
-  // Advanced analysis options
-  includeTestCoverage: true,     // Validate test coverage meets ADR goals
-  validateDependencies: true,    // Check cross-ADR dependencies
-  environmentValidation: true    // Test in realistic environments
-});
-
-// Generate architectural rules from ADRs and patterns
-const rules = await generateRules({
-  source: "both",               // Extract from ADRs and code patterns
-  adrDirectory: "docs/adrs",
-  projectPath: "/path/to/project",
-  outputFormat: "json"          // Machine-readable format
-});
+  prdPath: 'docs/PRD.md',
+  outputDirectory: 'docs/adrs',
+});
+
+// Smart Code Linking - Find code related to ADR decisions
+const relatedCode = await findRelatedCode(
+  'docs/adrs/001-auth-system.md',
+  'We will implement JWT authentication with Express middleware',
+  '/path/to/project',
+  {
+    useAI: true, // AI-powered keyword extraction
+    useRipgrep: true, // Fast text search
+    maxFiles: 10, // Limit results
+    includeContent: true, // Include file contents
+  }
+);
 ```
 
-### Deployment Readiness & Safety
-```typescript
-// Comprehensive deployment validation with zero tolerance
-const deploymentCheck = await deploymentReadiness({
-  operation: "full_audit",
-  projectPath: "/path/to/project",
-  targetEnvironment: "production",
-  
-  // Test validation (zero tolerance by default)
-  maxTestFailures: 0,              // Hard block on any test failures
-  requireTestCoverage: 80,         // Minimum coverage requirement
-  blockOnFailingTests: true,       // Prevent deployment with failing tests
-  
-  // Deployment history validation
-  maxRecentFailures: 2,            // Max recent deployment failures
-  deploymentSuccessThreshold: 80,  // Required success rate
-  rollbackFrequencyThreshold: 20,  // Max rollback frequency
-  
-  // Integration options
-  integrateTodoTasks: true,        // Auto-create blocking tasks
-  updateHealthScoring: true,       // Update project metrics
-  strictMode: true                 // Enable all safety checks
-});
-
-// Enhanced git push with deployment readiness
-const pushResult = await smartGitPush({
-  message: "Deploy feature X",
-  branch: "main",
-  
-  // Deployment readiness integration
-  checkDeploymentReadiness: true,     // Validate before push
-  enforceDeploymentReadiness: true,   // Hard block on issues
-  targetEnvironment: "production",    // Environment-specific checks
-  strictDeploymentMode: true          // Maximum safety
-});
-
-// Emergency override for critical fixes
-const override = await deploymentReadiness({
-  operation: "emergency_override",
-  businessJustification: "Critical security patch - CVE-2024-XXXX",
-  approvalRequired: true
-});
-```
+📖 **[Complete Usage Guide →](docs/tutorials/)** | **[API Reference →](docs/reference/)**
 
 ## 🎯 Use Cases
 
-### 👨‍💻 **AI Coding Assistants**
-*Enhance AI coding assistants like Cline, Cursor, and Claude Code*
-
-- **Test-Driven Development**: Two-phase TDD workflow with comprehensive ADR integration
-- **Intelligent Code Generation**: Generate code that follows architectural patterns and best practices
-- **Mock vs Production Detection**: Prevent AI assistants from claiming mock code is production-ready
-- **Architecture-Aware Refactoring**: Refactor code while maintaining architectural integrity
-- **Decision Documentation**: Automatically document architectural decisions as you code
-- **Pattern Recognition**: Identify and suggest architectural patterns for new features
-- **Quality Validation**: Reality-check mechanisms against overconfident AI assessments
-
-### 💬 **Conversational AI Assistants**
-*Enhance chatbots and business agents with architectural intelligence*
-
-- **Technical Documentation**: Answer questions about system architecture and design decisions
-- **Compliance Checking**: Verify that proposed changes meet architectural standards
-- **Knowledge Synthesis**: Combine information from multiple sources for comprehensive answers
-- **Decision Support**: Provide data-driven recommendations for architectural choices
-
-### 🤖 **Autonomous Development Agents**
-*Enable autonomous agents to understand and work with complex architectures*
-
-- **Automated Analysis**: Continuously analyze codebases for architectural drift
-- **Rule Enforcement**: Automatically enforce architectural rules and patterns
-- **Documentation Generation**: Generate and maintain architectural documentation
-- **Deployment Validation**: Verify deployment readiness and compliance
-
-### 🏢 **Enterprise Architecture Management**
-*Support enterprise architects and development teams*
+👨‍💻 **AI Coding Assistants** - Enhance Claude, Cline, Cursor with architectural intelligence  
+💬 **Conversational AI** - Answer architecture questions with confidence scoring  
+🤖 **Autonomous Agents** - Continuous analysis and rule enforcement  
+🏢 **Enterprise Teams** - Portfolio analysis and migration planning
 
-- **Portfolio Analysis**: Analyze multiple projects for consistency and compliance
-- **Migration Planning**: Plan and track architectural migrations and modernization
-- **Risk Assessment**: Identify architectural risks and technical debt
-- **Standards Enforcement**: Ensure compliance with enterprise architectural standards
+📖 **[Detailed Use Cases →](docs/explanation/mcp-concepts.md)**
 
 ## 🛠️ Technology Stack
 
-- **Runtime**: Node.js (>=18.0.0)
-- **Language**: TypeScript with strict configuration
-- **Core Framework**: @modelcontextprotocol/sdk
-- **Validation**: Zod schemas for all data structures
-- **Testing**: Jest with >80% coverage target
-- **Linting**: ESLint with comprehensive rules
-- **Build**: TypeScript compiler with incremental builds
-- **CI/CD**: GitHub Actions with automated testing and publishing
+**Runtime:** Node.js 18+ • **Language:** TypeScript • **Framework:** MCP SDK • **Testing:** Jest (>80% coverage)
+**Search:** ripgrep + fast-glob • **AI Integration:** OpenRouter.ai • **Code Analysis:** Smart Code Linking
 
-## � Project Structure
+📖 **[Technical Details →](docs/explanation/server-architecture.md)**
+
+## 📁 Project Structure
 
 ```
-mcp-adr-analysis-server/
-├── src/
-│   ├── index.ts              # Main MCP server entry point
-│   ├── tools/                # MCP tool implementations (23 tools)
-│   ├── resources/            # MCP resource implementations
-│   ├── prompts/              # MCP prompt implementations
-│   ├── types/                # TypeScript interfaces & schemas
-│   ├── utils/                # Utility functions and helpers
-│   └── cache/                # Intelligent caching system
-├── docs/
-│   ├── adrs/                 # Architectural Decision Records
-│   ├── research/             # Research findings and templates
-│   └── NPM_PUBLISHING.md     # NPM publishing guide
-├── tests/                    # Comprehensive test suite
-├── .github/workflows/        # CI/CD automation
-├── scripts/                  # Build and deployment scripts
-└── dist/                     # Compiled JavaScript output
+src/tools/     # 23 MCP tools for analysis
+docs/adrs/     # Architectural Decision Records
+tests/         # >80% test coverage
+.github/       # CI/CD automation
 ```
 
+📖 **[Full Structure →](docs/diataxis-index.md)**
+
 ## 🧪 Testing
 
 ```bash
-# Run all tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Run tests in watch mode
-npm run test:watch
-
-# Test MCP server functionality
-npm run test:package
+npm test              # Run all tests (>80% coverage)
+npm run test:coverage # Coverage report
 ```
 
-### Test Coverage
-- **Unit Tests**: Individual component testing with >80% coverage
-- **Integration Tests**: MCP protocol and file system testing
-- **Custom Matchers**: ADR and schema validation helpers
-- **Performance Tests**: Caching and optimization validation
+📖 **[Testing Guide →](docs/how-to-guides/troubleshooting.md)**
 
 ## 🔧 Development
 
-### Prerequisites
-- Node.js >= 18.0.0
-- npm or yarn
-- Git
-
-### Setup
 ```bash
-# Clone the repository
 git clone https://github.com/tosin2013/mcp-adr-analysis-server.git
 cd mcp-adr-analysis-server
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run tests
-npm test
-
-# Start development server
-npm run dev
-```
-
-### Available Scripts
-```bash
-npm run build         # Build TypeScript to JavaScript
-npm run dev           # Start development server with hot reload
-npm test              # Run Jest tests with coverage
-npm run lint          # Run ESLint checks
-npm run lint:fix      # Fix ESLint issues automatically
-npm run clean         # Clean build artifacts and cache
-npm run format        # Format code with Prettier
-npm run typecheck     # Run TypeScript type checking
-```
-
-### Pre-Commit Hook
-The repository includes an automated pre-commit hook that ensures code quality:
-
-```bash
-# The hook is automatically installed in .git/hooks/pre-commit
-# It runs automatically on every commit and checks:
-
-# ✅ TypeScript compilation
-# ✅ Related tests (or smoke test fallback)  
-# ✅ Code formatting (Prettier)
-# ✅ Only processes staged TypeScript/JavaScript files
-
-# If checks fail, the commit is blocked with clear error messages:
-# • TypeScript errors: Fix compilation issues
-# • Test failures: Address failing tests  
-# • Formatting issues: Run 'npm run format' to auto-fix
-
-# For comprehensive pre-release validation:
-./scripts/pre-commit-checklist.sh
-```
-
-### Code Quality Standards
-- **TypeScript**: Strict mode with comprehensive type checking
-- **ESLint**: Enforced code quality and security rules
-- **Testing**: Jest with custom matchers for ADR validation
-- **Coverage**: Minimum 80% test coverage required
-- **Security**: Content masking and secret prevention
-- **MCP Compliance**: Strict adherence to Model Context Protocol specification
-
-
-
-## 🚀 Getting Started
-
-### Quick Start (3 Steps)
-
-1. **Install**: `npm install -g mcp-adr-analysis-server`
-2. **Get API Key**: Visit [https://openrouter.ai/keys](https://openrouter.ai/keys)
-3. **Configure Claude Desktop**: Add to your configuration:
-
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/path/to/your/project",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-sonnet"
-      }
-    }
-  }
-   }
-   ```
-
-4. **Restart Claude Desktop** and start getting AI-powered architectural insights!
-
-### Example Usage
-
-Once configured, you can ask Claude:
-
-> "Analyze this React project's architecture and suggest ADRs for any implicit decisions"
-
-> "Generate ADRs from the PRD.md file and create a todo.md with implementation tasks"
-
-> "Check this codebase for security issues and provide masking recommendations"
-
-The server will now return **actual analysis results** instead of prompts to submit elsewhere!
-
-## 🚀 Complete Development Lifecycle
-
-The MCP server now provides a **complete development lifecycle assistant** with intelligent workflow guidance:
-
-### **🎯 Step 1: Get Workflow Guidance**
-```
-get_workflow_guidance
-```
-**Parameters:**
-```json
-{
-  "goal": "analyze new project and set up architectural documentation",
-  "projectContext": "new_project",
-  "availableAssets": ["codebase"],
-  "timeframe": "thorough_review"
-}
-```
-
-**Result**: Intelligent tool sequence recommendations and workflow guidance.
-
-### **🏗️ Step 2: Get Development Guidance**
-```
-get_development_guidance
-```
-**Parameters:**
-```json
-{
-  "developmentPhase": "implementation",
-  "adrsToImplement": ["ADR-001: API Design", "ADR-002: Database Schema"],
-  "technologyStack": ["TypeScript", "React", "Node.js"],
-  "teamContext": {"size": "small_team", "experienceLevel": "mixed"}
-}
+npm install && npm run build && npm test
 ```
 
-**Result**: Specific coding tasks, implementation patterns, and development roadmap.
-
-### **📊 Step 3: Execute Recommended Tools**
-Follow the workflow guidance to execute the recommended tool sequence for your specific goals.
-
-### **🔄 Complete Workflow Examples**
+**Quality Standards:** TypeScript strict mode • ESLint • >80% test coverage • Pre-commit hooks
 
-#### **New Project Setup**
-1. `get_workflow_guidance` → 2. `analyze_project_ecosystem` → 3. `get_architectural_context` → 4. `suggest_adrs` → 5. `get_development_guidance`
+📖 **[Development Guide →](docs/how-to-guides/getting-started-workflow-guidance.md)** | **[Contributing →](CONTRIBUTING.md)**
 
-#### **Existing Project Analysis**
-1. `get_workflow_guidance` → 2. `discover_existing_adrs` (initializes cache) → 3. `get_architectural_context` → 4. `generate_adr_todo` → 5. `get_development_guidance`
+## 🔧 Troubleshooting
 
-#### **Security Audit**
-1. `get_workflow_guidance` → 2. `analyze_content_security` → 3. `generate_content_masking` → 4. `validate_content_masking`
+**Common Issues:**
 
-### Configuration Examples
-
-#### Example 1: AI-Powered Project Analysis
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/Users/username/my-react-app",
-        "ADR_DIRECTORY": "docs/decisions",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-sonnet",
-        "AI_TEMPERATURE": "0.1",
-        "LOG_LEVEL": "INFO"
-      }
-    }
-  }
-}
-```
+- **RHEL Systems**: Use special installer script
+- **Tools return prompts**: Set `EXECUTION_MODE=full` + API key
+- **Module not found**: Run `npm install && npm run build`
+- **Permission denied**: Check file permissions and project path
 
-#### Example 2: Cost-Effective Setup
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/Users/username/my-project",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-haiku",
-        "AI_MAX_TOKENS": "2000",
-        "AI_TEMPERATURE": "0.05"
-      }
-    }
-  }
-}
-```
-
-#### Example 3: Prompt-Only Mode (Legacy)
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/Users/username/my-project",
-        "EXECUTION_MODE": "prompt-only",
-        "LOG_LEVEL": "INFO"
-      }
-    }
-  }
-}
-```
-
-#### Example 4: Multi-Project Setup
-```json
-{
-  "mcpServers": {
-    "adr-analysis-frontend": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/Users/username/frontend-app",
-        "ADR_DIRECTORY": "docs/adrs",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "openai/gpt-4o-mini",
-        "LOG_LEVEL": "ERROR"
-      }
-    },
-    "adr-analysis-backend": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/Users/username/backend-api",
-        "ADR_DIRECTORY": "architecture/decisions",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-sonnet",
-        "LOG_LEVEL": "DEBUG"
-      }
-    }
-  }
-}
-```
-
-#### Example 5: Development Environment
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "${workspaceFolder}",
-        "ADR_DIRECTORY": "docs/adrs",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-haiku",
-        "AI_CACHE_ENABLED": "true",
-        "AI_CACHE_TTL": "1800",
-        "LOG_LEVEL": "DEBUG"
-      }
-    }
-  }
-}
-```
+📖 **[Complete Troubleshooting Guide →](docs/troubleshooting.md)**
 
+## 🔒 Security & Performance
 
+**Security:** Automatic secret detection • Content masking • Local processing • Zero trust  
+**Performance:** Multi-level caching • Incremental analysis • Parallel processing • Memory optimization
 
-## � Troubleshooting
-
-### 🔴 **RHEL 9/10 Specific Issues**
-
-**Problem**: "Command 'mcp-adr-analysis-server' not found" on RHEL systems
-
-**Root Cause**: RHEL has specific npm global installation and PATH issues due to SELinux policies and default npm configuration.
-
-**Solution**: Use the RHEL-specific installer:
-```bash
-curl -sSL https://raw.githubusercontent.com/tosin2013/mcp-adr-analysis-server/main/scripts/install-rhel.sh | bash
-```
-
-**Manual Fix for RHEL**:
-```bash
-# Fix npm prefix for user directory
-mkdir -p ~/.npm-global
-npm config set prefix ~/.npm-global
-
-# Add to PATH
-echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
-source ~/.bashrc
-
-# Reinstall
-npm install -g mcp-adr-analysis-server
-```
-
-**RHEL MCP Configuration**:
-If the command is still not found, use the npx approach:
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "npx",
-      "args": ["mcp-adr-analysis-server"],
-      "env": {
-        "PROJECT_PATH": "/path/to/your/project",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-sonnet",
-        "ADR_DIRECTORY": "docs/adrs",
-        "LOG_LEVEL": "ERROR"
-      }
-    }
-  }
-}
-```
-
-### ⚠️ **CRITICAL**: Tools Return Prompts Instead of Results
-
-**Symptom**: When calling tools like `suggest_adrs`, you receive large detailed instructions and prompts instead of actual ADR suggestions.
-
-**Root Cause**: AI execution is not properly configured. The tool is falling back to prompt-only mode.
-
-**Solution**: Add these **required** environment variables to your MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "adr-analysis": {
-      "command": "mcp-adr-analysis-server",
-      "env": {
-        "PROJECT_PATH": "/path/to/your/project",
-        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
-        "EXECUTION_MODE": "full",
-        "AI_MODEL": "anthropic/claude-3-sonnet"
-      }
-    }
-  }
-}
-```
-
-**Verification**: After adding these variables and restarting, tools should return actual results like:
-- `suggest_adrs` → Actual ADR suggestions with titles and reasoning
-- `analyze_project_ecosystem` → Real technology analysis and recommendations
-- `generate_content_masking` → Actual masked content, not masking instructions
-
-**Quick Diagnostic**: Use the built-in diagnostic tool:
-```
-check_ai_execution_status
-```
-This will show exactly what's wrong with your configuration and provide step-by-step fix instructions.
-
-### Other AI Execution Issues
-
-**Problem**: "AI execution not available" errors
-```bash
-# Check execution mode
-echo $EXECUTION_MODE
-
-# Verify API key is set
-echo $OPENROUTER_API_KEY | head -c 10
-
-# Test AI connectivity
-curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
-     https://openrouter.ai/api/v1/models
-```
-
-**Problem**: "AI execution not available" errors
-- ✅ Verify `OPENROUTER_API_KEY` is set correctly
-- ✅ Check `EXECUTION_MODE=full` in environment
-- ✅ Ensure API key has sufficient credits
-- ✅ Verify network connectivity to OpenRouter
-
-**Problem**: Slow AI responses
-```bash
-# Reduce token limits for faster responses
-AI_MAX_TOKENS=2000
-AI_TEMPERATURE=0.05
-
-# Enable caching for repeated queries
-AI_CACHE_ENABLED=true
-AI_CACHE_TTL=3600
-```
-
-**Problem**: High API costs
-```bash
-# Use cost-effective models
-AI_MODEL=anthropic/claude-3-haiku
-# or
-AI_MODEL=openai/gpt-4o-mini
-
-# Reduce token usage
-AI_MAX_TOKENS=2000
-AI_TEMPERATURE=0.1
-```
-
-### Environment Configuration
-
-**Check current configuration:**
-```bash
-# View AI execution status
-node -e "
-const { getAIExecutionStatus } = require('./dist/utils/prompt-execution.js');
-console.log(JSON.stringify(getAIExecutionStatus(), null, 2));
-"
-```
-
-**Reset configuration:**
-```bash
-# Clear cache and restart
-rm -rf .mcp-adr-cache
-npm run build
-```
-
-### Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| "Module not found" errors | Run `npm install && npm run build` |
-| TypeScript compilation errors | Check Node.js version >= 18.0.0 |
-| Permission denied | Check file permissions and project path |
-| API rate limits | Reduce `AI_MAX_TOKENS` or increase `AI_TIMEOUT` |
-| Cache issues | Clear cache with `rm -rf .mcp-adr-cache` |
-
-## �🔒 Security Features
-
-### Content Protection
-- **Automatic Secret Detection**: Identifies API keys, passwords, and sensitive data
-- **Intelligent Masking**: Context-aware content masking with configurable levels
-- **Security Validation**: Comprehensive security checks and recommendations
-- **Compliance Tracking**: Ensure adherence to security standards and best practices
-
-### Privacy & Data Handling
-- **Local Processing**: All analysis performed locally, no data sent to external services
-- **Configurable Masking**: Customize masking rules for your organization's needs
-- **Audit Trail**: Track all security-related actions and decisions
-- **Zero Trust**: Assume all content may contain sensitive information
-
-## 📊 Performance & Scalability
-
-### Intelligent Caching
-- **Multi-level Caching**: File system, memory, and analysis result caching
-- **Cache Invalidation**: Smart cache invalidation based on file changes
-- **Performance Optimization**: Optimized for large codebases and complex projects
-- **Resource Management**: Efficient memory and CPU usage
-
-### Scalability Features
-- **Incremental Analysis**: Only analyze changed files and dependencies
-- **Parallel Processing**: Multi-threaded analysis for large projects
-- **Memory Optimization**: Efficient memory usage for large codebases
-- **Streaming Results**: Stream analysis results for real-time feedback
+📖 **[Security Guide →](docs/explanation/security-philosophy.md)** | **[Performance →](docs/explanation/performance-design.md)**
 
 ## 🤝 Contributing
 
-We welcome contributions! This project follows strict development standards to ensure quality and security.
-
-### Development Standards
-- **TypeScript**: Strict mode with comprehensive type checking
-- **Testing**: >80% code coverage with Jest
-- **Linting**: ESLint with security-focused rules
-- **Security**: All contributions must pass security validation
-- **MCP Compliance**: Strict adherence to Model Context Protocol specification
-
-### Getting Started
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes with tests
-4. The pre-commit hook will automatically validate your changes
-5. Run the full test suite: `npm test`
-6. For comprehensive validation: `./scripts/pre-commit-checklist.sh`
-7. Submit a pull request
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+We welcome contributions! Fork → Create branch → Add tests → Submit PR
 
-## 🔗 Related Resources
+**Standards:** TypeScript strict • >80% coverage • ESLint • Security validation • MCP compliance
 
-### Official Documentation
-- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
-- [MCP Server Development Guide](https://modelcontextprotocol.io/docs/concepts/servers)
-- [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+📖 **[Contributing Guide →](CONTRIBUTING.md)**
 
-### Community Resources
-- [MCP Servers Registry](https://github.com/modelcontextprotocol/servers)
-- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)
-- [MCP Community Discord](https://discord.gg/modelcontextprotocol)
+## 🔗 Resources
 
-### Project Documentation
-- [Implementation Progress](./todo.md)
-- [Architecture Decisions](./docs/adrs/)
-- [NPM Publishing Guide](./docs/NPM_PUBLISHING.md)
+**Official:** [MCP Specification](https://modelcontextprotocol.io/) • [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)  
+**Community:** [MCP Registry](https://github.com/modelcontextprotocol/servers) • [Discord](https://discord.gg/modelcontextprotocol)  
+**Project:** [ADRs](./docs/adrs/) • [Progress](./docs/release-dashboard.md) • [Publishing Guide](./docs/how-to-guides/NPM_PUBLISHING.md)
 
 ## 📄 License
 
@@ -952,4 +207,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 **Built with ❤️ by [Tosin Akinosho](https://github.com/tosin2013) for AI-driven architectural analysis**
 
-*Empowering AI assistants with deep architectural intelligence and decision-making capabilities.*
+_Empowering AI assistants with deep architectural intelligence and decision-making capabilities._