mcp-souschef 3.0.0__tar.gz → 3.5.1__tar.gz

{mcp_souschef-3.0.0 → mcp_souschef-3.5.1}/PKG-INFO

@@ -1,34 +1,40 @@
 Metadata-Version: 2.4
 Name: mcp-souschef
-Version: 3.0.0
+Version: 3.5.1
 Summary: AI-powered MCP server for Chef to Ansible conversion
 License: MIT
 License-File: LICENSE
 Keywords: chef,ansible,migration,infrastructure,automation,mcp,ai,conversion
 Author: SousChef Contributors
-Requires-Python: >=3.13,<4.0
+Requires-Python: >=3.10,<4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
+Provides-Extra: ai
+Provides-Extra: all
 Provides-Extra: ui
-Requires-Dist: anthropic (>=0.75.0)
+Requires-Dist: anthropic (>=0.75.0) ; extra == "ai" or extra == "all"
 Requires-Dist: click (>=8.1.0)
 Requires-Dist: mcp (>=1.25.0)
-Requires-Dist: openai (>=1.0.0)
-Requires-Dist: pandas (>=2.0.0) ; extra == "ui"
-Requires-Dist: plotly (>=5.0.0)
+Requires-Dist: openai (>=1.0.0) ; extra == "ai" or extra == "all"
+Requires-Dist: pandas (>=2.0.0) ; extra == "ui" or extra == "all"
+Requires-Dist: plotly (>=5.17.0,<7.0) ; extra == "ui" or extra == "all"
+Requires-Dist: pydantic (>=2.0.0)
 Requires-Dist: python-dotenv (>=1.2.1)
 Requires-Dist: pyyaml (>=6.0.0)
-Requires-Dist: streamlit (>=1.28.0)
-Requires-Dist: zod (>=0.8.0)
+Requires-Dist: requests (>=2.31.0)
+Requires-Dist: streamlit (>=1.28.0) ; extra == "ui" or extra == "all"
 Project-URL: Documentation, https://kpeacocke.github.io/souschef/
 Project-URL: Homepage, https://github.com/kpeacocke/souschef
 Project-URL: Repository, https://github.com/kpeacocke/souschef
@@ -41,7 +47,7 @@ An AI-powered MCP (Model Context Protocol) server that provides comprehensive Ch
 [![GitHub release](https://img.shields.io/github/v/release/kpeacocke/souschef)](https://github.com/kpeacocke/souschef/releases)
 [![Python Version](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Test Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)](htmlcov/index.html)
+[![Test Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](htmlcov/index.html)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)
@@ -50,17 +56,17 @@ An AI-powered MCP (Model Context Protocol) server that provides comprehensive Ch
 
 ## Overview - Chef to Ansible features
 
-SousChef is a complete enterprise-grade migration platform with **32 primary MCP tools** organised across **10 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments and CI/CD pipeline generation, SousChef provides everything needed for a successful infrastructure automation migration.
+SousChef is a complete enterprise-grade migration platform with **35 primary MCP tools** organised across **11 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments, Chef Server integration, and CI/CD pipeline generation, SousChef provides everything needed for a successful infrastructure automation migration.
 
 ### About Tool Counts
 
-**Why 32 tools in the documentation but more in the server?**
+**Why 35 tools in the documentation but more in the server?**
 
-The MCP server provides **37 total tools** (35 public + 2 internal). This documentation focuses on the **32 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations and helper utilities used internally by the main tools.
+The MCP server provides **38 total tools**. This documentation focuses on the **35 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations used internally by the main tools.
 
-As a user, you'll primarily interact with the 27 documented tools. Your AI assistant may use the additional tools automatically when needed, but you don't need to know about them for successful migrations.
+As a user, you'll primarily interact with the documented tools. Your AI assistant may use the additional tools automatically when needed, but you don't need to know about them for successful migrations.
 
-> **For developers:** See `souschef/server.py` for the complete list of all 37 registered tools.
+> **For developers:** See `souschef/server.py` for the complete list of all 38 registered tools.
 
 ## Model Agnostic - Works with Any AI Model
 
@@ -73,7 +79,7 @@ As a user, you'll primarily interact with the 27 documented tools. Your AI assis
 - **Local Models** (Ollama, llama.cpp, etc.)
 - **Custom Enterprise Models**
 
-**How it works:** You choose your AI model provider in your MCP client. SousChef provides the Chef/Ansible expertise through 27 specialized tools. The model calls these tools to help with your migration.
+**How it works:** You choose your AI model provider in your MCP client. SousChef provides the Chef/Ansible expertise through 35 specialized tools. The model calls these tools to help with your migration.
 
 > See [config/CONFIGURATION.md](config/CONFIGURATION.md) for configuration examples with different model providers.
 
@@ -84,6 +90,28 @@ As a user, you'll primarily interact with the 27 documented tools. Your AI assis
 - **[API Reference](docs/api-reference/)** - Detailed tool documentation
 - **[Migration Guide](docs/migration-guide/)** - Step-by-step migration process
 
+## What's New in v3.4.0-beta
+
+**Chef Server Integration & AI-Enhanced Template Conversion** - New tools for dynamic inventory and intelligent template conversion:
+
+- **Chef Server Connectivity**: Validate Chef Server connections and query nodes with `validate_chef_server_connection` and `get_chef_nodes`
+- **AI-Enhanced Templates**: Convert ERB to Jinja2 with AI validation using `convert_template_with_ai` for complex Ruby logic
+- **CLI Commands**: New commands `validate-chef-server`, `query-chef-nodes`, and `convert-template-ai` for command-line access
+- **Streamlit UI**: Chef Server Settings page for managing server configuration and validation
+
+## What's New in v3.3.0
+
+**AI-Assisted Effort Estimation** - SousChef now displays realistic migration effort comparisons directly in the Streamlit UI:
+
+- **Manual Migration Estimates**: Full effort without AI assistance
+- **SousChef-Assisted Estimates**: 50% time reduction through automated boilerplate conversion
+- **Time Savings Display**: Instant visual comparison showing hours saved and efficiency gains
+- **Interactive Metrics**: Summary and per-cookbook effort comparisons with clear deltas
+
+Example: A cookbook estimated at 40 hours of manual work shows SousChef-assisted time as 20 hours, saving 20 hours (50%) and reducing team needs from 2 developers to 1.
+
+See the [Assessment Guide](docs/migration-guide/assessment.md#effort-estimation-model) for details on the effort estimation model.
+
 ## Installation
 
 ```bash
@@ -101,6 +129,7 @@ poetry install
 ## Core Capabilities
 
 ### 1. Chef Cookbook Analysis & Parsing
+
 Complete cookbook introspection and analysis tools:
 
 - **parse_template** - Parse ERB templates with Jinja2 conversion and variable extraction
@@ -113,6 +142,7 @@ Complete cookbook introspection and analysis tools:
 - **list_cookbook_structure** - Display complete cookbook directory hierarchy
 
 ### 2. Chef-to-Ansible Conversion Engine
+
 Advanced resource-to-task conversion with intelligent module selection:
 
 - **convert_resource_to_task** - Transform individual Chef resources to Ansible tasks
@@ -125,6 +155,7 @@ Advanced resource-to-task conversion with intelligent module selection:
   - Platform checks, node attributes, file/directory existence, and command execution
 
 ### 3. Chef Search & Inventory Integration
+
 Convert Chef search patterns to dynamic Ansible inventory:
 
 - **convert_chef_search_to_inventory** - Transform Chef search queries to Ansible inventory groups
@@ -132,6 +163,7 @@ Convert Chef search patterns to dynamic Ansible inventory:
 - **analyse_chef_search_patterns** - Discover and analyse search usage in cookbooks
 
 ### 4. InSpec Integration & Validation
+
 Complete InSpec-to-Ansible testing pipeline:
 
 - **parse_inspec_profile** - Parse InSpec profiles and extract controls
@@ -139,6 +171,7 @@ Complete InSpec-to-Ansible testing pipeline:
 - **generate_inspec_from_recipe** - Auto-generate InSpec validation from Chef recipes
 
 ### 5. Data Bags & Secrets Management
+
 Chef data bags to Ansible vars/vault conversion:
 
 - **convert_chef_databag_to_vars** - Transform data bags to Ansible variable files
@@ -146,6 +179,7 @@ Chef data bags to Ansible vars/vault conversion:
 - **analyse_chef_databag_usage** - Analyse data bag usage patterns in cookbooks
 
 ### 6. Environment & Configuration Management
+
 Chef environments to Ansible inventory groups:
 
 - **convert_chef_environment_to_inventory_group** - Transform Chef environments to inventory
@@ -153,6 +187,7 @@ Chef environments to Ansible inventory groups:
 - **analyse_chef_environment_usage** - Analyse environment usage in cookbooks
 
 ### 7. AWX/Ansible Automation Platform Integration
+
 Enterprise AWX/AAP configuration generation:
 
 - **generate_awx_job_template_from_cookbook** - Create AWX job templates from cookbooks
@@ -161,6 +196,7 @@ Enterprise AWX/AAP configuration generation:
 - **generate_awx_inventory_source_from_chef** - Create dynamic inventory sources from Chef server
 
 ### 8. Chef Habitat to Container Conversion
+
 Modernize Habitat applications to containerized deployments:
 
 - **parse_habitat_plan** - Parse Chef Habitat plan files (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration
@@ -168,6 +204,7 @@ Modernize Habitat applications to containerized deployments:
 - **generate_compose_from_habitat** - Generate docker-compose.yml from multiple Habitat plans for multi-service deployments
 
 ### 9. Advanced Deployment Patterns & Migration Assessment
+
 Modern deployment strategies and migration planning:
 
 - **convert_chef_deployment_to_ansible_strategy** - Convert deployment recipes to Ansible strategies
@@ -175,6 +212,7 @@ Modern deployment strategies and migration planning:
 - **generate_canary_deployment_strategy** - Generate canary deployment configurations
 
 ### 10. CI/CD Pipeline Generation
+
 Generate Jenkins, GitLab CI, and GitHub Actions workflows from Chef cookbook CI patterns:
 
 - **generate_jenkinsfile_from_chef** - Generate Jenkinsfile (Declarative or Scripted) from Chef cookbook CI/CD patterns
@@ -182,6 +220,7 @@ Generate Jenkins, GitLab CI, and GitHub Actions workflows from Chef cookbook CI
 - **generate_github_workflow_from_chef** - Generate GitHub Actions workflow from Chef cookbook CI/CD patterns
 
 Automatically detects and converts:
+
 - **Test Kitchen** configurations (.kitchen.yml) → Integration test stages
 - **ChefSpec** tests (spec/) → Unit test stages
 - **Cookstyle/Foodcritic** → Lint stages
@@ -207,7 +246,10 @@ souschef generate-gitlab-ci ./mycookbook --no-cache --no-artifacts
 souschef generate-github-workflow ./mycookbook --workflow-name "My CI" --no-cache
 ```
 
+#### Command Line Usage
+
 **MCP Tool Usage:**
+
 ```python
 # From an AI assistant with SousChef MCP
 
@@ -235,6 +277,7 @@ generate_github_workflow_from_chef(
 ```
 
 ### 11. Conversion Validation Framework
+
 Comprehensive validation of Chef-to-Ansible conversions:
 
 - **validate_conversion** - Validate conversions across multiple dimensions
@@ -245,18 +288,20 @@ Comprehensive validation of Chef-to-Ansible conversions:
   - **Performance Recommendations**: Efficiency suggestions and optimizations
 
 #### Validation Levels
+
 - **ERROR**: Critical issues that will prevent execution
 - **WARNING**: Potential problems or anti-patterns that may cause issues
 - **INFO**: Suggestions for improvements and best practices
 
 #### Validation Categories
+
 - **Syntax**: Code structure and syntax correctness
 - **Semantic**: Logical equivalence and meaning preservation
 - **Best Practice**: Ansible community standards and patterns
 - **Security**: Security considerations and recommendations
 - **Performance**: Efficiency and optimization suggestions
 
-#### Example Usage
+#### Validation Examples
 
 ```python
 # Validate a resource conversion
@@ -272,6 +317,7 @@ validate_conversion(
 ```
 
 Output formats:
+
 - **text**: Detailed report with all findings grouped by severity
 - **json**: Structured JSON for programmatic processing
 - **summary**: Quick overview with counts only
@@ -282,9 +328,58 @@ Output formats:
 - **analyse_cookbook_dependencies** - Analyse dependencies and migration order
 - **generate_migration_report** - Generate executive and technical migration reports
 
+### 12. Chef Server Integration & Dynamic Inventory
+
+Dynamic inventory generation and Chef Server connectivity for hybrid environments:
+
+- **validate_chef_server_connection** - Test Chef Server REST API connectivity and authentication
+- **get_chef_nodes** - Query Chef Server for nodes matching search criteria, extracting roles, environment, platform, and IP information
+- **convert_template_with_ai** - Convert ERB templates to Jinja2 with AI-based validation for complex Ruby logic
+
+#### Chef Server Features
+
+- **Connection Validation**: Test Chef Server connectivity before migrations
+- **Dynamic Node Queries**: Search Chef Server by role, environment, or custom attributes
+- **Node Metadata Extraction**: Retrieve IP addresses, FQDNs, platforms, and roles for inventory
+- **AI-Enhanced Conversion**: Intelligent ERB→Jinja2 conversion with validation for complex Ruby constructs
+- **Fallback Handling**: Graceful degradation when Chef Server is unavailable
+
+#### Usage Examples
+
+```bash
+# Validate Chef Server connection
+souschef validate-chef-server --server-url https://chef.example.com --node-name admin
+
+# Query Chef Server for nodes
+souschef query-chef-nodes --search-query "role:web_server" --json
+
+# Convert template with AI assistance
+souschef convert-template-ai /path/to/template.erb --ai --output /path/to/output.j2
+```
+
+#### MCP Tool Usage
+
+```python
+# Validate Chef Server from AI assistant
+validate_chef_server_connection(
+    server_url="https://chef.example.com",
+    node_name="admin"
+)
+
+# Query nodes for dynamic inventory
+get_chef_nodes(search_query="role:web_server AND environment:production")
+
+# Convert template with AI validation
+convert_template_with_ai(
+    erb_path="/path/to/template.erb",
+    use_ai_enhancement=True
+)
+```
+
 ## Migration Workflow
 
 ### Phase 1: Discovery & Assessment
+
 ```bash
 # Assess migration complexity
 assess_chef_migration_complexity /path/to/cookbooks
@@ -297,6 +392,7 @@ generate_migration_plan '{\"cookbooks\": [\"/path/to/cookbook1\", \"/path/to/coo
 ```
 
 ### Phase 2: Content Conversion
+
 ```bash
 # Convert recipes to playbooks
 generate_playbook_from_recipe /path/to/recipe.rb
@@ -309,6 +405,7 @@ generate_inventory_from_chef_environments /path/to/environments
 ```
 
 ### Phase 3: AWX/AAP Integration
+
 ```bash
 # Generate AWX job templates
 generate_awx_job_template_from_cookbook /path/to/cookbook cookbook_name
@@ -321,6 +418,7 @@ generate_awx_inventory_source_from_chef https://chef.example.com production web_
 ```
 
 ### Phase 4: Habitat to Container Migration
+
 ```bash
 # Parse Habitat plan
 parse_habitat_plan /path/to/plan.sh
@@ -333,6 +431,7 @@ generate_compose_from_habitat "/path/to/plan1.sh,/path/to/plan2.sh" my_network
 ```
 
 ### Phase 5: Validation & Testing
+
 ```bash
 # Generate InSpec validation
 generate_inspec_from_recipe /path/to/recipe.rb
@@ -342,6 +441,7 @@ convert_inspec_to_test /path/to/inspec_profile testinfra
 ```
 
 ### Performance Profiling & Optimization
+
 Profile cookbook parsing performance to identify bottlenecks and optimize large-scale migrations:
 
 ```bash
@@ -362,15 +462,22 @@ profile_parsing_operation recipe /path/to/recipe.rb --detailed
 ```
 
 ### 10. Visual Migration Planning Interface
+
 Interactive web-based interface for Chef-to-Ansible migration planning and visualization:
 
 - **Cookbook Analysis Dashboard**: Interactive directory scanning with metadata parsing and complexity assessment
-- **Migration Planning Wizard**: Step-by-step migration planning with effort estimation and risk analysis
+- **AI-Assisted Effort Estimation** (v3.3.0+):
+  - **Manual Migration Estimate**: Full effort without AI assistance
+  - **SousChef-Assisted Estimate**: 50% time reduction through automated boilerplate conversion
+  - **Time Savings Display**: Clear comparison showing hours saved and efficiency percentage
+  - **Visual Metrics**: Side-by-side metric cards for instant visual comparison
+- **Migration Planning Wizard**: Step-by-step migration planning with dual effort scenarios and risk analysis
 - **Dependency Mapping**: Visual dependency graphs showing cookbook relationships and migration ordering
 - **Validation Reports**: Conversion validation results with syntax checking and best practice compliance
 - **Progress Tracking**: Real-time migration progress with completion metrics and bottleneck identification
 
 **Launch the UI:**
+
 ```bash
 # Using Poetry (development)
 poetry run souschef ui
@@ -383,6 +490,7 @@ souschef ui --port 8080
 ```
 
 **Run in Docker:**
+
 ```bash
 # Build the image
 docker build -t souschef-ui .
@@ -394,6 +502,51 @@ docker run -p 9999:9999 souschef-ui
 docker-compose up
 ```
 
+**Run Published Image from GitHub Container Registry:**
+
+SousChef images are automatically published to GitHub Container Registry (GHCR) on each release:
+
+```bash
+# Pull the latest released image
+docker pull ghcr.io/mcp-souschef:latest
+
+# Or pull a specific version
+docker pull ghcr.io/mcp-souschef:3.2.0
+
+# Run the image with your .env file
+docker run -p 9999:9999 \
+  --env-file .env \
+  ghcr.io/mcp-souschef:latest
+
+# Or with docker-compose
+cat > docker-compose.override.yml << 'EOF'
+version: '3.8'
+services:
+  souschef-ui:
+    image: ghcr.io/mcp-souschef:latest
+    build: ~
+EOF
+docker-compose up
+```
+
+**Container Images:**
+
+- **Registry**: GitHub Container Registry (GHCR)
+- **Image Name**: `mcp-souschef`
+- **Full URL**: `ghcr.io/mcp-souschef`
+- **Available Tags**:
+  - `latest` - Most recent release
+  - `3.2.0` - Specific version (semver)
+  - `3.2` - Latest patch of a minor version
+  - `3` - Latest patch of a major version
+
+**Why use GHCR?**
+
+- Integrated with GitHub releases and CI/CD
+- Faster pulls for users in GitHub ecosystem
+- Security scanning and SBOM included
+- Multi-platform support (amd64, arm64)
+
 **Docker Environment Configuration:**
 
 SousChef supports AI configuration via environment variables in Docker containers. Create a `.env` file in your project root:
@@ -407,6 +560,7 @@ nano .env
 ```
 
 **Example .env file:**
+
 ```dotenv
 # AI Configuration
 SOUSCHEF_AI_PROVIDER=Anthropic (Claude)
@@ -416,6 +570,7 @@ SOUSCHEF_AI_BASE_URL=
 SOUSCHEF_AI_PROJECT_ID=
 SOUSCHEF_AI_TEMPERATURE=0.7
 SOUSCHEF_AI_MAX_TOKENS=4000
+SOUSCHEF_ALLOWED_HOSTNAMES=api.example.com,*.example.org
 
 # Streamlit Configuration (optional)
 STREAMLIT_SERVER_PORT=9999
@@ -423,12 +578,14 @@ STREAMLIT_SERVER_HEADLESS=true
 ```
 
 **Supported AI Providers:**
+
 - `Anthropic (Claude)` - Anthropic Claude models
 - `OpenAI (GPT)` - OpenAI GPT models
 - `IBM Watsonx` - IBM Watsonx AI models
 - `Red Hat Lightspeed` - Red Hat Lightspeed models
 
 **Environment Variables:**
+
 - `SOUSCHEF_AI_PROVIDER` - AI provider name (required)
 - `SOUSCHEF_AI_MODEL` - Model name (required)
 - `SOUSCHEF_AI_API_KEY` - API key for authentication (required)
@@ -436,8 +593,10 @@ STREAMLIT_SERVER_HEADLESS=true
 - `SOUSCHEF_AI_PROJECT_ID` - Project ID for Watsonx (optional)
 - `SOUSCHEF_AI_TEMPERATURE` - Model temperature 0.0-2.0 (optional, default: 0.7)
 - `SOUSCHEF_AI_MAX_TOKENS` - Maximum tokens to generate (optional, default: 4000)
+- `SOUSCHEF_ALLOWED_HOSTNAMES` - Comma-separated list of allowed hostnames for outbound API requests (optional)
 
 **Docker Compose (recommended for development):**
+
 ```yaml
 version: '3.8'
 services:
@@ -456,6 +615,7 @@ services:
 ```
 
 **Features:**
+
 - Clean, professional design matching documentation standards
 - Real-time cookbook analysis with progress indicators
 - **Interactive dependency visualization** with Plotly graphs and NetworkX analysis
@@ -468,15 +628,17 @@ services:
 ### Advanced UI Features
 
 #### Interactive Dependency Visualization
+
 The UI includes sophisticated dependency graph visualization powered by NetworkX and Plotly:
 
 - **Graph Analysis**: Automatic detection of cookbook dependencies, circular references, and migration ordering
 - **Interactive Exploration**: Zoom, pan, and hover over nodes to explore complex dependency relationships
 - **Color Coding**: Visual distinction between cookbooks, dependencies, community cookbooks, and circular dependencies
 - **Static Export**: Matplotlib-based static graphs for reports and documentation
-- **Large Graph Support**: Optimized layouts for complex cookbook ecosystems
+- **Large Graph Support**: Optimised layouts for complex cookbook ecosystems
 
 #### Real-Time Progress Tracking
+
 All analysis operations include comprehensive progress feedback:
 
 - **Progress Bars**: Visual progress indicators for long-running operations
@@ -485,18 +647,21 @@ All analysis operations include comprehensive progress feedback:
 - **Error Handling**: Graceful error display with recovery suggestions
 
 #### Enhanced User Experience
+
 - **Responsive Design**: Clean, professional interface that works across different screen sizes
 - **Export Options**: Download analysis results, graphs, and migration plans
 - **Session Persistence**: Maintain analysis state across page refreshes
 - **Quick Actions**: One-click access to common migration tasks
 
 ### Migration Assessment & Reporting
+
 - **Complexity Analysis**: Automated assessment of migration effort and risk factors
 - **Dependency Mapping**: Complete cookbook dependency analysis with migration ordering
 - **Impact Analysis**: Resource usage patterns and conversion recommendations
 - **Executive Reports**: Stakeholder-ready migration reports with timelines and costs
 
 ### Modern Deployment Patterns
+
 - **Blue/Green Deployments**: Zero-downtime deployment strategies
 - **Canary Releases**: Gradual rollout configurations
 - **Application Patterns**: Modern containerized and cloud-native deployment patterns
@@ -504,6 +669,7 @@ All analysis operations include comprehensive progress feedback:
 - **Habitat to Container**: Convert Chef Habitat plans to Docker and Docker Compose configurations
 
 ### Enterprise Integration
+
 - **AWX/AAP Ready**: Native Ansible Automation Platform integration
 - **Dynamic Inventory**: Chef server integration for hybrid environments
 - **Secrets Management**: Secure data bag to Vault conversion
@@ -512,6 +678,7 @@ All analysis operations include comprehensive progress feedback:
 ## Installation & Setup
 
 ### Prerequisites
+
 - Python 3.14+
 - [Poetry](https://python-poetry.org/) for dependency management
 - MCP-compatible client (Claude Desktop, VS Code 1.102+ with GitHub Copilot, etc.)
@@ -519,6 +686,7 @@ All analysis operations include comprehensive progress feedback:
 ### Quick Start
 
 1. **Install SousChef**:
+
    ```bash
    pip install mcp-souschef
    ```
@@ -528,12 +696,14 @@ All analysis operations include comprehensive progress feedback:
    Use the pre-configured files in the `config/` directory for quick setup with Claude Desktop, VS Code Copilot, or other MCP clients.
 
    **Claude Desktop** (macOS):
+
    ```bash
    cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
    # Restart Claude Desktop
    ```
 
    **VS Code + GitHub Copilot** (requires VS Code 1.102+):
+
    ```bash
    # macOS/Linux
    cp config/vscode-copilot.json ~/.config/Code/User/mcp.json
@@ -544,7 +714,7 @@ All analysis operations include comprehensive progress feedback:
    # Reload VS Code window, then trust the server when prompted
    ```
 
-   ** See [config/CONFIGURATION.md](config/CONFIGURATION.md) for:**
+   **See [config/CONFIGURATION.md](config/CONFIGURATION.md) for:**
    - Platform-specific setup (macOS/Linux/Windows)
    - Model provider configurations (Red Hat AI, OpenAI, local models)
    - Development setup
@@ -574,6 +744,7 @@ souschef-cli inspec-convert controls.rb --format testinfra
 ```
 
 **Available Commands:**
+
 - `recipe` - Parse Chef recipe files and extract resources
 - `template` - Convert ERB templates to Jinja2 with variable extraction
 - `resource` - Parse custom resources and LWRPs
@@ -629,15 +800,17 @@ poetry update              # All packages
 ```
 
 **Automated Systems:**
--  Pre-commit hooks auto-update `poetry.lock` when `pyproject.toml` changes
--  CI validates lock file on every PR
--  Dependabot sends weekly dependency updates
+
+- Pre-commit hooks auto-update `poetry.lock` when `pyproject.toml` changes
+- CI validates lock file on every PR
+- Dependabot sends weekly dependency updates
 
 See [CONTRIBUTING.md](CONTRIBUTING.md#-managing-dependencies) for detailed dependency management guide.
 
 ## Architecture & Design
 
 ### MCP Protocol Integration
+
 SousChef leverages the Model Context Protocol (MCP) to provide seamless integration with AI assistants and development environments:
 
 - **38 Specialized Tools**: Each migration capability exposed as dedicated MCP tool
@@ -646,6 +819,7 @@ SousChef leverages the Model Context Protocol (MCP) to provide seamless integrat
 - **Streaming Support**: Efficient handling of large cookbook conversions
 
 ### Testing Strategy
+
 Following enterprise-grade testing standards with comprehensive test coverage:
 
 - **Unit Tests**: Mock-based testing for individual functions (test_server.py, test_cli.py, test_mcp.py)
@@ -654,9 +828,10 @@ Following enterprise-grade testing standards with comprehensive test coverage:
 - **Specialized Tests**: Enhanced guards (test_enhanced_guards.py), error handling (test_error_paths.py, test_error_recovery.py), real-world fixtures (test_real_world_fixtures.py)
 - **Performance Tests**: Benchmarking and optimization validation (test_performance.py)
 - **Snapshot Tests**: Regression testing for output stability (test_snapshots.py)
-- **92% Coverage**: Comprehensive test coverage exceeding the 90% target for production readiness
+- **83% Coverage**: Comprehensive test coverage approaching the 90% target for production readiness
 
 ### Quality Assurance
+
 - **Zero Warnings Policy**: All code passes linting without disabling checks
 - **Type Safety**: Complete type annotations throughout the codebase
 - **Automated Testing**: CI/CD pipeline with comprehensive test suites
@@ -665,7 +840,9 @@ Following enterprise-grade testing standards with comprehensive test coverage:
 ## Documentation
 
 ### Tool Reference
+
 Each MCP tool includes comprehensive documentation:
+
 - Purpose and use cases
 - Parameter descriptions and types
 - Return value specifications
@@ -673,73 +850,12 @@ Each MCP tool includes comprehensive documentation:
 - Error handling behaviors
 
 ### Migration Guides
+
 - **[Enterprise Migration Guide](docs/enterprise-migration.md)** - Complete methodology for large-scale migrations
 - **[AWX Integration Guide](docs/awx-integration.md)** - Step-by-step AWX/AAP setup and configuration
 - **[Testing Strategy Guide](docs/testing-strategy.md)** - Validation and testing approaches
 - **[Best Practices](docs/best-practices.md)** - Recommended patterns and approaches
 
-## Contributing
-
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
-- Development setup and workflow
-- Code style and testing requirements
-- Pull request process
-- Issue reporting guidelines
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Roadmap
-
-### Completed
--  Complete Chef cookbook parsing (recipes, attributes, metadata, templates)
--  InSpec profile parsing and conversion to Testinfra/Ansible tests
--  Chef resource to Ansible task conversion with module mapping
--  Data bags to Ansible Vault conversion
--  Chef environments to Ansible inventory conversion
--  Chef search patterns to dynamic inventory conversion
--  AWX/AAP job templates, workflows, and project generation
--  Blue/green and canary deployment pattern generation
--  Migration complexity assessment and planning tools
--  Comprehensive testing suite (unit, integration, property-based)
--  Command-line interface (CLI) for standalone usage
--  Enhanced Chef guard handling (arrays, lambda syntax, complex nested conditions)
--  Advanced attribute precedence resolution (6 levels with conflict detection)
--  Automated release management with Release Please
--  Automated branch cleanup for release PRs
--  Automated conversion validation and testing framework
--  Chef Habitat to containerized deployment conversion (parse_habitat_plan, convert_habitat_to_dockerfile, generate_compose_from_habitat)
--  Enhanced error handling with custom exceptions and actionable recovery suggestions
--  Technical debt reduction - ALL PHASES COMPLETE: 16 functions refactored (15 C-grade eliminated, 70+ helpers extracted, average 77% complexity reduction, zero C-grade functions remaining)
--  Performance profiling and optimization for large cookbooks (profiling module, CLI commands, MCP tools)
--  Code duplication elimination (InSpec functions refactored: 55 duplicate lines removed, improved architecture)
--  Documentation website with MkDocs + Material theme (charcoal + teal colour scheme, 16 pages)
--  Comprehensive documentation content (Getting Started, Tool Reference, Migration Guide, API docs, Examples)
--  Integration with additional test frameworks (ServerSpec, Goss) - InSpec conversion now supports 4 output formats
--  Jenkins/GitLab CI pipeline generation from Chef cookbook CI patterns (Test Kitchen, ChefSpec, Cookstyle)
--  Visual migration planning interface with Streamlit-based web UI for interactive cookbook analysis and migration planning
--  **Interactive dependency mapping and visualization** with Plotly graphs and NetworkX analysis
--  **Real-time progress tracking** for all analysis operations with Streamlit progress bars
--  **Static graph visualization** with matplotlib for reports and documentation
--  **Automated ERB to Jinja2 template conversion** - Converts Chef ERB templates to Ansible Jinja2 templates during cookbook conversion
-   -  Converts ERB syntax to Jinja2: `<%= var %>` → `{{ var }}`, `<% if %>` → `{% if %}`
-   -  Extracts template variables for validation and documentation
-   -  Includes converted templates in downloadable playbook archives
-   -  UI displays converted templates with variable lists and preview
-
-### Planned
-- 📅 Enhanced graph layout algorithms for large dependency networks (force-directed, hierarchical)
-- 📅 Export functionality for graphs (PNG, SVG, PDF formats)
-- 📅 UI configuration options and themes
-- 📅 Performance caching for expensive analysis operations
-- 📅 Mobile-responsive design improvements
-- 📅 Accessibility enhancements (ARIA labels, keyboard navigation)
-- 📅 Integration testing for UI components
-- 📅 Advanced filtering and search in dependency graphs
-- 📅 Migration templates and presets
-- 📅 Terraform provider for infrastructure state management
-
 ## Support & Community
 
 - **Issues**: [GitHub Issues](https://github.com/kpeacocke/souschef/issues)
@@ -748,326 +864,23 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**SousChef** - *Transforming infrastructure automation, one recipe at a time.*
-  desc 'Ensure package nginx is properly configured'
-  impact 1.0
-
-  describe package('nginx') do
-    it { should be_installed }
-  end
-end
-
-control 'service-nginx' do
-  title 'Verify service nginx'
-  desc 'Ensure service nginx is properly configured'
-  impact 1.0
-
-  describe service('nginx') do
-    it { should be_running }
-    it { should be_enabled }
-  end
-end
-
-control 'template--etc-nginx-nginx.conf' do
-  title 'Verify template /etc/nginx/nginx.conf'
-  desc 'Ensure template /etc/nginx/nginx.conf is properly configured'
-  impact 1.0
-
-  describe file('/etc/nginx/nginx.conf') do
-    it { should exist }
-    its('mode') { should cmp '0644' }
-    its('owner') { should eq 'root' }
-    its('group') { should eq 'root' }
-  end
-end
-```
-
-#### Testinfra Integration
-
-Convert to Python tests for CI/CD pipelines:
-
-```bash
-souschef-cli inspec-convert validation-controls.rb --format testinfra
-```
-
-```python
-import pytest
-
-def test_package_nginx(host):
-    """Ensure package nginx is properly configured"""
-    pkg = host.package("nginx")
-    assert pkg.is_installed
-
-def test_service_nginx(host):
-    """Ensure service nginx is properly configured"""
-    svc = host.service("nginx")
-    assert svc.is_running
-    assert svc.is_enabled
-
-def test_template_etc_nginx_nginx_conf(host):
-    """Ensure template /etc/nginx/nginx.conf is properly configured"""
-    f = host.file("/etc/nginx/nginx.conf")
-    assert f.exists
-    assert oct(f.mode) == "0644"
-    assert f.user == "root"
-    assert f.group == "root"
-```
+## SousChef
 
-#### Ansible Assert Integration
-
-For Ansible playbook validation:
-
-```bash
-souschef-cli inspec-convert validation-controls.rb --format ansible_assert
-```
-
-```yaml
----
-# Validation tasks converted from InSpec
-
-- name: Verify package nginx
-  ansible.builtin.assert:
-    that:
-      - ansible_facts.packages['nginx'] is defined
-    fail_msg: "Ensure package nginx is properly configured validation failed"
-
-- name: Verify service nginx
-  ansible.builtin.assert:
-    that:
-      - services['nginx'].state == 'running'
-      - services['nginx'].status == 'enabled'
-    fail_msg: "Ensure service nginx is properly configured validation failed"
-```
-
-#### Benefits
-
-- **Consistency Validation** - Ensure Chef and Ansible produce identical infrastructure state
-- **AI Context Enhancement** - InSpec profiles help AI understand infrastructure intent
-- **Automated Testing** - Generate tests automatically from Chef recipes
-- **Multiple Test Formats** - Support for InSpec, Testinfra, and Ansible assert
-- **CI/CD Integration** - Easy integration with existing test pipelines
-
-### As an MCP Server
-
-SousChef is designed to be used as an MCP server with AI assistants that support the Model Context Protocol.
-
-#### Configure with Claude Desktop
-
-Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "souschef": {
-      "command": "poetry",
-      "args": [
-        "-C",
-        "/path/to/souschef",
-        "run",
-        "souschef"
-      ]
-    }
-  }
-}
-```
-
-### Available Tools
-
-#### `list_directory(path: str)`
-List the contents of a directory.
-
-**Example:**
-```python
-list_directory("/path/to/cookbooks")
-# Returns: ['nginx', 'apache2', 'mysql']
-```
-
-#### `read_file(path: str)`
-Read the contents of a file.
-
-**Example:**
-```python
-read_file("/path/to/cookbook/recipes/default.rb")
-# Returns: file contents as string
-```
-
-#### `read_cookbook_metadata(path: str)`
-Parse Chef cookbook metadata.rb file.
-
-**Example:**
-```python
-read_cookbook_metadata("/path/to/cookbook/metadata.rb")
-# Returns:
-# name: nginx
-# maintainer: Chef Software, Inc.
-# version: 8.0.0
-# depends: logrotate, iptables
-```
-
-#### `parse_recipe(path: str)`
-Parse a Chef recipe file and extract resources.
-
-**Example:**
-```python
-parse_recipe("/path/to/cookbook/recipes/default.rb")
-# Returns:
-# Resource 1:
-#   Type: package
-#   Name: nginx
-#   Action: install
-```
-
-#### `parse_attributes(path: str, resolve_precedence: bool = True)`
-Parse a Chef attributes file and extract attribute definitions with precedence analysis.
-
-**Chef Attribute Precedence** (lowest to highest):
-1. `default` - Normal default value
-2. `force_default` - Forced default, higher than regular default
-3. `normal` - Normal attribute set by cookbook
-4. `override` - Override values
-5. `force_override` - Forced override, cannot be overridden
-6. `automatic` - Automatically detected by Ohai (highest precedence)
-
-When multiple attributes with the same path exist at different precedence levels, the highest precedence wins. The tool automatically resolves conflicts and reports which values were overridden.
-
-**Parameters:**
-- `path`: Path to the attributes (.rb) file
-- `resolve_precedence`: If True (default), resolves conflicts and shows only winning values. If False, shows all attributes.
-
-**Example:**
-```python
-# With precedence resolution (default)
-parse_attributes("/path/to/cookbook/attributes/default.rb")
-# Returns:
-# Resolved Attributes (with precedence):
-# ==================================================
-#
-# Attribute: nginx.port
-#   Value: 443
-#   Precedence: force_override (level 5)
-#     Overridden values: default=80, normal=8080
-#
-# Attribute: nginx.ssl_port
-#   Value: 443
-#   Precedence: default (level 1)
-#
-# ==================================================
-# Total attributes: 2
-# Attributes with precedence conflicts: 1
-
-# Without precedence resolution (show all)
-parse_attributes("/path/to/cookbook/attributes/default.rb", resolve_precedence=False)
-# Returns:
-# default[nginx.port] = 80
-# normal[nginx.port] = 8080
-# force_override[nginx.port] = 443
-# default[nginx.ssl_port] = 443
-```
-
-**Use Cases:**
-- Understanding attribute conflicts in complex cookbooks
-- Debugging which attributes will actually be applied
-- Planning attribute migrations to Ansible variables
-- Identifying force_override attributes that need special handling
-
-#### `list_cookbook_structure(path: str)`
-List the structure of a Chef cookbook directory.
-
-**Example:**
-```python
-list_cookbook_structure("/path/to/cookbook")
-# Returns:
-# recipes/
-#   default.rb
-#   install.rb
-# attributes/
-#   default.rb
-# metadata/
-#   metadata.rb
-```
-
-#### `parse_template(path: str)`
-Parse a Chef ERB template file and convert it to Jinja2 format.
-
-**Example:**
-```python
-parse_template("/path/to/cookbook/templates/default/nginx.conf.erb")
-# Returns JSON with:
-# {
-#   "original_file": "/path/to/cookbook/templates/default/nginx.conf.erb",
-#   "variables": [
-#     "nginx']['port",
-#     "nginx']['server_name",
-#     "nginx']['ssl_enabled"
-#   ],
-#   "jinja2_template": "server {\n  listen {{ nginx']['port }};\n  {% if nginx']['ssl_enabled %}\n  ssl on;\n  {% endif %}\n}"
-# }
-```
-
-**ERB to Jinja2 Conversion:**
-- Variable output: `<%= var %>` → `{{ var }}`
-- Instance variables: `<%= @var %>` → `{{ var }}`
-- Node attributes: `<%= node['attr'] %>` → `{{ attr }}`
-- Conditionals: `<% if cond %>` → `{% if cond %}`
-- Unless: `<% unless cond %>` → `{% if not cond %}`
-- Elsif: `<% elsif cond %>` → `{% elif cond %}`
-- Else: `<% else %>` → `{% else %}`
-- Loops: `<% arr.each do |item| %>` → `{% for item in arr %}`
-- End blocks: `<% end %>` → `{% endif %}` or `{% endfor %}`
-
-#### `parse_custom_resource(path: str)`
-Parse a Chef custom resource or LWRP file and extract properties, attributes, and actions.
-
-**Example:**
-```python
-parse_custom_resource("/path/to/cookbook/resources/app_config.rb")
-# Returns JSON with:
-# {
-#   "resource_file": "/path/to/cookbook/resources/app_config.rb",
-#   "resource_name": "app_config",
-#   "resource_type": "custom_resource",  # or "lwrp"
-#   "properties": [
-#     {
-#       "name": "config_name",
-#       "type": "String",
-#       "name_property": true
-#     },
-#     {
-#       "name": "port",
-#       "type": "Integer",
-#       "default": "8080"
-#     },
-#     {
-#       "name": "ssl_enabled",
-#       "type": "[true, false]",
-#       "default": "false"
-#     }
-#   ],
-#   "actions": ["create", "delete"],
-#   "default_action": "create"
-# }
-```
-
-**Detected Resource Types:**
-- **Custom Resource** (modern) - Uses `property` keyword
-- **LWRP** (legacy) - Uses `attribute` keyword with `kind_of:`
-
-**Property/Attribute Fields:**
-- `name` - Property/attribute name
-- `type` - Type constraint (String, Integer, Boolean, Array, Hash, etc.)
-- `name_property` - Whether this is the resource's name property (true/false)
 - `default` - Default value if specified
 - `required` - Whether the property is required (true/false)
 
 **Action Extraction:**
+
 - Modern format: `action :name do ... end`
 - LWRP format: `actions :create, :delete, :update`
 - Supports both formats and mixed declarations
 
-#### `convert_resource_to_task(resource_type: str, resource_name: str, action: str = "create", properties: str = "")`
+### `convert_resource_to_task(resource_type: str, resource_name: str, action: str = "create", properties: str = "")`
+
 Convert a Chef resource to an Ansible task.
 
 **Example:**
+
 ```python
 convert_resource_to_task("package", "nginx", "install")
 # Returns:
@@ -1094,6 +907,7 @@ convert_resource_to_task("template", "/etc/nginx/nginx.conf.erb", "create")
 ```
 
 **Supported Resource Types:**
+
 - `package` → `ansible.builtin.package`
 - `service` → `ansible.builtin.service`
 - `template` → `ansible.builtin.template`
@@ -1106,9 +920,11 @@ convert_resource_to_task("template", "/etc/nginx/nginx.conf.erb", "create")
 - And more...
 
 #### `parse_habitat_plan(plan_path: str)`
+
 Parse a Chef Habitat plan file (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration.
 
 **Example:**
+
 ```python
 parse_habitat_plan("/path/to/habitat/plan.sh")
 # Returns JSON with:
@@ -1144,6 +960,7 @@ parse_habitat_plan("/path/to/habitat/plan.sh")
 ```
 
 **Extracted Information:**
+
 - **Package metadata**: name, origin, version, maintainer, description
 - **Dependencies**: Build-time and runtime package dependencies
 - **Ports**: Exported port configurations for service discovery
@@ -1152,15 +969,18 @@ parse_habitat_plan("/path/to/habitat/plan.sh")
 - **Build callbacks**: do_build, do_install, do_init, and other lifecycle hooks
 
 **Use Cases:**
+
 - Understanding Habitat application structure before containerization
 - Extracting dependencies for Docker base image selection
 - Planning port mappings for docker-compose configurations
 - Analyzing service dependencies and orchestration needs
 
 #### `convert_habitat_to_dockerfile(plan_path: str, base_image: str = "ubuntu:22.04")`
+
 Convert a Chef Habitat plan to a production-ready Dockerfile with security validation.
 
 **Example:**
+
 ```python
 convert_habitat_to_dockerfile("/path/to/habitat/plan.sh", "ubuntu:22.04")
 # Returns:
@@ -1202,10 +1022,12 @@ convert_habitat_to_dockerfile("/path/to/habitat/plan.sh", "ubuntu:22.04")
 ```
 
 **Parameters:**
+
 - `plan_path`: Path to the Habitat plan.sh file
 - `base_image`: Docker base image (default: ubuntu:22.04). Validated for security
 
 **Features:**
+
 - **Dependency mapping**: Converts Habitat dependencies to apt packages
 - **Build optimization**: Multi-stage builds when applicable
 - **Security scanning**: Detects dangerous patterns (curl|sh, eval, etc.)
@@ -1217,9 +1039,11 @@ convert_habitat_to_dockerfile("/path/to/habitat/plan.sh", "ubuntu:22.04")
 The tool processes shell commands from Habitat plans and includes them in the Dockerfile. Only use with trusted Habitat plans from known sources. Review generated Dockerfiles before building images.
 
 #### `generate_compose_from_habitat(plan_paths: str, network_name: str = "habitat_net")`
+
 Generate docker-compose.yml from multiple Habitat plans for multi-service deployments.
 
 **Example:**
+
 ```python
 # Single service
 generate_compose_from_habitat("/path/to/nginx/plan.sh", "myapp_network")
@@ -1289,10 +1113,12 @@ generate_compose_from_habitat(
 ```
 
 **Parameters:**
+
 - `plan_paths`: Comma-separated paths to plan.sh files for multiple services
 - `network_name`: Docker network name for service communication (default: habitat_net)
 
 **Features:**
+
 - **Multi-service orchestration**: Combines multiple Habitat plans into one compose file
 - **Automatic dependencies**: Creates depends_on from Habitat service binds
 - **Volume detection**: Identifies services needing persistent storage from do_init callbacks
@@ -1301,6 +1127,7 @@ generate_compose_from_habitat(
 - **Environment variables**: Generates environment configuration from port definitions
 
 **Use Cases:**
+
 - Converting multi-service Habitat applications to Docker Compose
 - Creating development environments from production Habitat plans
 - Simplifying container orchestration for local testing
@@ -1310,7 +1137,7 @@ generate_compose_from_habitat(
 
 ### Project Structure
 
-```
+```text
 souschef/
 ├── souschef/
 │   ├── __init__.py
@@ -1330,12 +1157,14 @@ souschef/
 SousChef uses a modern Python toolchain for code quality:
 
 - **Ruff**: Primary linter and formatter (replaces Black, isort, flake8)
+
   ```bash
   poetry run ruff check .    # Lint code
   poetry run ruff format .   # Format code
   ```
 
 - **mypy**: Static type checking for CI/CD
+
   ```bash
   poetry run mypy souschef   # Type check source code
   ```
@@ -1345,11 +1174,13 @@ SousChef uses a modern Python toolchain for code quality:
   - Provides immediate feedback during development
 
 - **pytest**: Testing framework with coverage reporting
+
   ```bash
   poetry run pytest --cov=souschef --cov-report=term-missing
   ```
 
 **Quality Requirements:**
+
 - Zero warnings from all tools (Ruff, mypy, Pylance)
 - Type hints required for all functions
 - Google-style docstrings
@@ -1367,18 +1198,18 @@ poetry run pytest
 poetry run pytest --cov=souschef --cov-report=term-missing --cov-report=html
 
 # Run specific test suites
-poetry run pytest tests/test_server.py              # Core unit tests
-poetry run pytest tests/test_cli.py                 # CLI tests
-poetry run pytest tests/test_mcp.py                 # MCP protocol tests
-poetry run pytest tests/test_integration.py         # Integration tests
-poetry run pytest tests/test_integration_accuracy.py # Accuracy validation
-poetry run pytest tests/test_enhanced_guards.py     # Guard conversion tests
-poetry run pytest tests/test_error_paths.py         # Error handling
-poetry run pytest tests/test_error_recovery.py      # Error recovery
-poetry run pytest tests/test_real_world_fixtures.py # Real-world cookbooks
-poetry run pytest tests/test_property_based.py      # Hypothesis fuzz tests
-poetry run pytest tests/test_performance.py         # Performance benchmarks
-poetry run pytest tests/test_snapshots.py           # Snapshot regression tests
+poetry run pytest tests/unit/test_server.py              # Core unit tests
+poetry run pytest tests/unit/test_cli.py                 # CLI tests
+poetry run pytest tests/e2e/test_mcp.py                  # MCP protocol tests
+poetry run pytest tests/integration/test_integration.py         # Integration tests
+poetry run pytest tests/integration/test_integration_accuracy.py # Accuracy validation
+poetry run pytest tests/unit/test_enhanced_guards.py     # Guard conversion tests
+poetry run pytest tests/unit/test_error_paths.py         # Error handling
+poetry run pytest tests/unit/test_error_recovery.py      # Error recovery
+poetry run pytest tests/integration/test_real_world_fixtures.py # Real-world cookbooks
+poetry run pytest tests/unit/test_property_based.py      # Hypothesis fuzz tests
+poetry run pytest tests/integration/test_performance.py         # Performance benchmarks
+poetry run pytest tests/unit/test_snapshots.py           # Snapshot regression tests
 
 # Run with benchmarks
 poetry run pytest --benchmark-only
@@ -1418,7 +1249,7 @@ The project includes comprehensive test coverage across multiple dimensions:
    - **Snapshots** (`test_snapshots.py`): Regression testing for output stability
 
 5. **Test Fixtures**
-   - Sample Chef cookbooks in `tests/fixtures/`
+  - Sample Chef cookbooks in `tests/integration/fixtures/`
    - Multiple cookbook types: apache2, docker, mysql, nodejs, legacy Chef 12, Habitat plans
    - Real-world metadata, recipes, attributes, and resources
    - Used across integration and accuracy testing
@@ -1444,6 +1275,7 @@ poetry run mutmut results
 ### VS Code Tasks
 
 The project includes several VS Code tasks:
+
 - **Run Tests** - Execute test suite
 - **Run Tests with Coverage** - Generate coverage reports
 - **Lint (Ruff)** - Check code quality
@@ -1457,6 +1289,7 @@ Thank you for your interest in contributing to SousChef!
 **Before you start**, please read the [**Architecture Guide**](docs/ARCHITECTURE.md) to understand where different code belongs and why. This is essential for understanding how to structure your contributions.
 
 For complete contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md), which includes:
+
 - Development setup instructions
 - Code standards and quality tools
 - Testing requirements and patterns
@@ -1464,6 +1297,7 @@ For complete contributing guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md), wh
 - Release procedures
 
 **Quick Checklist for Contributions:**
+
 1. Read [**docs/ARCHITECTURE.md**](docs/ARCHITECTURE.md) to understand module structure
 2. Ensure all tests pass: `poetry run pytest`
 3. Code passes linting: `poetry run ruff check .`
@@ -1481,5 +1315,3 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**SousChef** - *Ansible automation, one recipe at a time.*
-