sfcc-dev-mcp 1.0.15 → 1.0.19

package/.github/workflows/update-docs.yml

@@ -16,7 +16,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
       with:
         # Use a token with write permissions for creating PRs
         token: ${{ secrets.GITHUB_TOKEN }}

package/AGENTS.md

@@ -45,11 +45,11 @@ Operate as a senior TypeScript / Node.js engineer with deep MCP + SFCC (OCAPI, S
 - Keep architectural diagrams & tool categories consistent with `src/core/tool-definitions.ts`
 
 ### Testing Strategy
-- Always discover real response shape with `npx aegis query` (success, empty, error variants) before writing tests
-- Unit tests: core utilities, parsing, validation, token & client logic
-- YAML tests: broad tool surface, schema/shape validation, edge cases
-- Programmatic tests: multi-step flows, stderr management, stateful sequences
-- Performance assertions: CI‑tolerant (<500ms typical, variation <50×) – functional correctness first
+- Always discover response shapes with `npx aegis query` before writing tests (see `.github/skills/mcp-yaml-testing/` for detailed workflow)
+- Unit tests (Jest): core utilities, parsing, validation, token & client logic
+- YAML tests (Aegis): broad tool surface, schema validation (see `.github/skills/mcp-yaml-testing/`)
+- Programmatic tests (Node): multi-step flows, stateful sequences (see `.github/skills/mcp-programmatic-testing/`)
+- Performance assertions: CI‑tolerant (<500ms typical) – correctness first
 
 ### Implementation Workflow
 1. Define or adjust tool schema (if new) in `core/tool-definitions.ts`
@@ -61,28 +61,6 @@ Operate as a senior TypeScript / Node.js engineer with deep MCP + SFCC (OCAPI, S
 7. Run lint + tests; address failures before further edits
 8. Commit with concise, scope-focused message
 
-### YAML Test Development (Critical Process)
-**MANDATORY for all YAML test modifications**: Before writing or modifying ANY YAML test:
-
-1. **Discovery First**: Use `npx aegis query [tool_name] '[params]' --config "[config.json]"` to discover actual response formats
-2. **Test Success & Failure**: Query both successful and failure scenarios to understand all response variations
-3. **Document Findings**: Add comments to YAML tests showing discovery commands and expected formats
-4. **Choose Correct Patterns**: Use patterns that match the actual response structure, not assumptions
-
-**Common Mistakes to Avoid**:
-- Using `arrayLength` on JSON strings instead of actual arrays
-- Complex regex patterns instead of simpler `contains` or `regex` patterns
-- Assuming response structure without verification
-- Writing tests before understanding what the tool actually returns
-
-**Example Discovery Process**:
-```bash
-# Discover actual response
-npx aegis query get_available_best_practice_guides '{}' --config "./aegis.config.docs-only.json"
-# Response: {"content": [{"type": "text", "text": "[{\"name\":\"guide1\",...}]"}], "isError": false}
-# Pattern: text: "match:contains:guide1" (not arrayLength since it's a JSON string)
-```
-
 ### Performance & Stability
 - Optimize only after measuring; instrument where ambiguity exists
 - Use caching deliberately; document invalidation triggers
@@ -116,15 +94,30 @@ sfcc-dev-mcp/
 │   ├── index.ts                  # Package exports and compatibility
 │   ├── core/                     # Core MCP server functionality
 │   │   ├── server.ts             # Main MCP server implementation
-│   │   ├── tool-definitions.ts   # MCP tool schema definitions
+│   │   ├── tool-definitions.ts   # Re-exports tool schemas from modular files
+│   │   ├── tool-schemas/         # Modular tool schema definitions
+│   │   │   ├── index.ts          # Aggregates and re-exports all tool schemas
+│   │   │   ├── shared-schemas.ts # Reusable schema components (query, pagination, etc.)
+│   │   │   ├── documentation-tools.ts # SFCC documentation tools (5 tools)
+│   │   │   ├── best-practices-tools.ts # Best practices tools (4 tools)
+│   │   │   ├── sfra-tools.ts     # SFRA documentation tools (5 tools)
+│   │   │   ├── isml-tools.ts     # ISML documentation tools (5 tools)
+│   │   │   ├── log-tools.ts      # Log + Job log tools (8 + 5 tools)
+│   │   │   ├── system-object-tools.ts # System object tools (6 tools)
+│   │   │   ├── cartridge-tools.ts # Cartridge generation tools (1 tool)
+│   │   │   └── code-version-tools.ts # Code version tools (2 tools)
 │   │   └── handlers/             # Modular tool handlers
 │   │       ├── base-handler.ts   # Abstract base handler with common functionality
+│   │       ├── abstract-client-handler.ts # Abstract handler for client-based tools
+│   │       ├── simple-client-handler.ts # Simple handler for single-client tools
 │   │       ├── client-factory.ts # Centralized client creation with dependency injection
 │   │       ├── validation-helpers.ts # Common validation utilities for handlers
 │   │       ├── docs-handler.ts   # SFCC documentation tool handler
 │   │       ├── best-practices-handler.ts # Best practices tool handler
 │   │       ├── sfra-handler.ts   # SFRA documentation tool handler
+│   │       ├── isml-handler.ts   # ISML documentation tool handler
 │   │       ├── log-handler.ts    # Log analysis tool handler
+│   │       ├── job-log-handler.ts # Job log analysis tool handler
 │   │       ├── system-object-handler.ts # System object tool handler
 │   │       ├── code-version-handler.ts # Code version tool handler
 │   │       └── cartridge-handler.ts # Cartridge generation tool handler
@@ -153,10 +146,15 @@ sfcc-dev-mcp/
 │   │   │   ├── class-name-resolver.ts # Class name normalization and resolution
 │   │   │   ├── referenced-types-extractor.ts # Type extraction from documentation content
 │   │   │   └── index.ts          # Module exports
-│   │   ├── cartridge-generation-client.ts # Cartridge structure generation client
+│   │   ├── cartridge/            # Cartridge generation system
+│   │   │   ├── cartridge-generation-client.ts # Main cartridge structure generator
+│   │   │   ├── cartridge-structure.ts # Directory structure definitions
+│   │   │   ├── cartridge-templates.ts # File content templates
+│   │   │   └── index.ts          # Module exports
 │   │   ├── log-client.ts         # Log client compatibility wrapper
 │   │   ├── docs-client.ts        # SFCC documentation client orchestrator
 │   │   ├── sfra-client.ts        # SFRA documentation client
+│   │   ├── isml-client.ts        # ISML element documentation client
 │   │   ├── ocapi-client.ts       # Main OCAPI client coordinator
 │   │   └── best-practices-client.ts # Best practices guide client
 │   ├── services/                 # Service layer with clean abstractions
@@ -166,6 +164,9 @@ sfcc-dev-mcp/
 │   ├── config/                   # Configuration management
 │   │   ├── configuration-factory.ts # Config factory for different modes
 │   │   └── dw-json-loader.ts     # dw.json configuration loader
+│   ├── constants/                # Application constants
+│   │   ├── index.ts              # Constants exports
+│   │   └── best-practices-guides.ts # Best practices guide definitions
 │   ├── tool-configs/             # Tool configuration definitions
 │   │   ├── best-practices-tool-config.ts # Best practices tools configuration
 │   │   ├── cartridge-tool-config.ts # Cartridge generation tools configuration
@@ -278,6 +279,19 @@ sfcc-dev-mcp/
 │   │   └── explain-product-pricing-methods-no-mcp.png # Demo screenshot without MCP
 │   ├── dist/                    # Built website output (Vite build)
 │   └── node_modules/            # Node.js dependencies
+├── docs-site-v2/                # VitePress documentation website
+│   ├── .vitepress/              # VitePress config and theme
+│   ├── guide/                   # Getting started and configuration
+│   ├── features/                # Feature overview
+│   ├── tools/                   # Tools catalog
+│   ├── examples/                # Prompt examples
+│   ├── script-debugger/         # Script debugger guide
+│   ├── skills/                  # Agent skills guide
+│   ├── security/                # Security and privacy notes
+│   ├── development/             # Development guide
+│   ├── troubleshooting/         # Troubleshooting guide
+│   ├── public/                  # Static assets
+│   └── package.json             # VitePress scripts and dependencies
 ├── ai-instructions/             # AI instruction files for different platforms
 │   ├── claude-desktop/          # Claude Desktop specific instructions
 │   │   └── claude_custom_instructions.md
@@ -307,18 +321,24 @@ sfcc-dev-mcp/
 - Manages configuration modes (documentation-only vs. full)
 - Provides error handling and response formatting
 - Orchestrates modular tool handlers for different functionality areas
+- Issues a one-time advisory when AGENTS.md/skills are missing, pointing clients to the installer tool
 
 #### **Tool Handler Architecture** (`core/handlers/`)
 - **BaseToolHandler** (`base-handler.ts`): Abstract base class providing common handler functionality, standardized response formatting, execution timing, and error handling patterns
+- **AbstractClientHandler** (`abstract-client-handler.ts`): Abstract handler for tools that require client instantiation
+- **SimpleClientHandler** (`simple-client-handler.ts`): Simplified handler for single-client tools with less boilerplate
 - **ClientFactory** (`client-factory.ts`): Centralized client creation with dependency injection support for testing and clean architecture
 - **ValidationHelpers** (`validation-helpers.ts`): Common validation utilities shared across all handlers
 - **DocsToolHandler** (`docs-handler.ts`): Handles SFCC documentation tools including class information, method search, and API discovery
 - **BestPracticesToolHandler** (`best-practices-handler.ts`): Manages best practice guides, security recommendations, and hook reference tables
 - **SFRAToolHandler** (`sfra-handler.ts`): Processes SFRA documentation requests with dynamic discovery and smart categorization
+- **ISMLToolHandler** (`isml-handler.ts`): Handles ISML element documentation, search, and category browsing
 - **LogToolHandler** (`log-handler.ts`): Handles real-time log analysis, error monitoring, and system health summarization
+- **JobLogToolHandler** (`job-log-handler.ts`): Handles job log analysis, debugging, and execution summaries
 - **SystemObjectToolHandler** (`system-object-handler.ts`): Manages system object definitions, custom attributes, and site preferences
 - **CodeVersionToolHandler** (`code-version-handler.ts`): Handles code version listing, activation, and deployment management
 - **CartridgeToolHandler** (`cartridge-handler.ts`): Processes cartridge generation requests with complete project setup using dependency injection
+- **AgentInstructionsToolHandler** (`agent-instructions-handler.ts`): Installs or merges bundled AGENTS.md and skills into workspaces, user home, or temp directories
 
 #### **Client Architecture**
 
@@ -352,9 +372,15 @@ sfcc-dev-mcp/
 - **DocsClient** (`docs-client.ts`): Main orchestrator for SFCC documentation processing that coordinates specialized modules for documentation scanning, content parsing, class name resolution, and type extraction across all namespaces
 - **LogClient** (`log-client.ts`): Backward compatibility wrapper that re-exports the modular log system
 - **SFRAClient** (`sfra-client.ts`): Provides comprehensive SFRA (Storefront Reference Architecture) documentation access including Server, Request, Response, QueryString, and render module documentation with method and property details
+- **ISMLClient** (`isml-client.ts`): Provides ISML element documentation, category-based browsing, and search functionality for template development
 - **OCAPIClient** (`ocapi-client.ts`): Main OCAPI coordinator that orchestrates specialized clients and provides unified interface
 - **BestPracticesClient** (`best-practices-client.ts`): Serves curated development guides including cartridge creation, ISML templates with security and performance guidelines, job framework development, LocalServiceRegistry service integrations with OAuth patterns and reusable module design, OCAPI/SCAPI hooks, SFRA controllers, SFRA models with JSON object layer design and architecture patterns, SFRA client-side JavaScript architecture (AJAX flows, validation, accessibility), custom endpoints, security recommendations, and performance optimization strategies with hook reference tables
+- **AgentInstructionsClient** (`agent-instructions-client.ts`): Plans and installs bundled AI assets (AGENTS.md + skills) into workspaces, user home, or temp directories with merge strategies and missing-only copy support
+
+##### **Cartridge Generation** (`clients/cartridge/`)
 - **CartridgeGenerationClient** (`cartridge-generation-client.ts`): Generates complete cartridge structures with clean dependency injection for file system and path operations
+- **CartridgeStructure** (`cartridge-structure.ts`): Defines standard SFCC cartridge directory structure
+- **CartridgeTemplates** (`cartridge-templates.ts`): Contains file templates for controllers, models, scripts, and configurations
 
 #### **Configuration Management** (`config/`)
 - **Configuration Factory** (`configuration-factory.ts`): Creates configurations for different modes
@@ -392,33 +418,53 @@ sfcc-dev-mcp/
    - **Category Filtering**: Explore documents by functional areas for efficient discovery
    - **Complete Coverage**: Core SFRA classes (Server, Request, Response, QueryString, render) plus comprehensive model documentation (account, cart, products, pricing, billing, shipping, store, customer management, totals, categories, content, locale, addresses, and more)
 
-4. **Cartridge Generation Tools** (1 tool)
+4. **ISML Documentation Tools** (5 tools)
+   - Complete ISML element reference and documentation
+   - Control flow elements (isif, isloop, isnext, etc.)
+   - Output formatting (isprint) and includes (isinclude, iscomponent, isslot)
+   - Scripting elements (isscript, isset) and caching (iscache)
+   - Category-based browsing and advanced search capabilities
+
+5. **Cartridge Generation Tools** (1 tool)
    - Automated cartridge structure creation with direct file generation
    - Complete project setup with all necessary configuration files
    - Proper directory organization and file structure
 
-5. **Log Analysis Tools** (8 tools)
+6. **Log Analysis Tools** (8 tools)
    - Real-time error monitoring
    - Log search and pattern matching
    - System health summarization
 
-6. **Job Log Tools** (5 tools)
+7. **Job Log Tools** (5 tools)
    - Job log analysis and debugging
    - Job execution summaries
    - Custom job step monitoring
 
-7. **System Object Tools** (6 tools)
+8. **System Object Tools** (6 tools)
    - Custom attribute discovery
    - Site preference management
    - System object schema exploration
    - Custom object attribute definitions search
 
-8. **Code Version Tools** (2 tools)
+9. **Code Version Tools** (2 tools)
    - Code version listing and management
    - Code version activation for deployment fixes
 
+10. **Agent Instruction Tools** (1 tool)
+   - Copy or merge AGENTS.md and bundled skills into the current workspace, user home, or a temp directory
+   - Supports dry-run planning, append/replace/skip strategies, and missing-only installs
+
 ### 🚀 Operating Modes
 
+#### **Configuration Discovery Priority**
+The server discovers SFCC credentials in this order (highest to lowest priority):
+
+1. **CLI parameter** (`--dw-json /path/to/dw.json`) - Explicit, highest priority
+2. **Environment variables** (`SFCC_HOSTNAME`, `SFCC_USERNAME`, `SFCC_PASSWORD`, `SFCC_CLIENT_ID`, `SFCC_CLIENT_SECRET`)
+3. **MCP workspace roots discovery** - Automatically finds `dw.json` in VS Code workspace folders after client connection
+
+> **Note**: CWD-based auto-discovery is intentionally disabled because MCP servers often start with `cwd` set to the user's home directory, not the project directory. The MCP workspace roots mechanism provides reliable project context.
+
 #### **Documentation-Only Mode**
 - No SFCC credentials required
 - Access to all documentation and best practices
@@ -429,12 +475,12 @@ sfcc-dev-mcp/
 - Complete access to logs, job logs, and system objects
 - Real-time debugging and monitoring capabilities
 
-### 🎯 Development Guidelines (Consolidated Above)
-Legacy duplication removed. See Unified Engineering Principles section for the authoritative list.
-    - Configuration options or operating modes
-    - Development workflows or best practices
-    - Tool categories or counts
-    - Installation or setup procedures
+### 🎯 Development Guidelines
+See Unified Engineering Principles section above for the authoritative guidelines covering:
+- Configuration options and operating modes
+- Development workflows and best practices
+- Tool categories and counts
+- Installation and setup procedures
 
 ### 📝 Documentation Maintenance Requirements
 
@@ -445,17 +491,18 @@ Legacy duplication removed. See Unified Engineering Principles section for the a
 Before updating any documentation with tool counts or quantitative information, **ALWAYS** verify the actual numbers using command line tools:
 
 ```bash
-# Total tool count verification
-grep -c "name: '" src/core/tool-definitions.ts
-
-# Individual section counts
-awk '/export const SFCC_DOCUMENTATION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
-awk '/export const BEST_PRACTICES_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
-awk '/export const SFRA_DOCUMENTATION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
-awk '/export const LOG_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
-awk '/export const SYSTEM_OBJECT_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
-awk '/export const CARTRIDGE_GENERATION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
-awk '/export const CODE_VERSION_TOOLS/,/^];/' src/core/tool-definitions.ts | grep -c "name: '"
+# Total tool count verification (38 tools across all categories)
+grep -c "name: '" src/core/tool-schemas/*.ts | grep -v ":0" | awk -F: '{sum+=$2} END {print "Total tools:", sum}'
+
+# Individual category counts (from modular schema files)
+echo "Documentation tools:" && grep -c "name: '" src/core/tool-schemas/documentation-tools.ts
+echo "Best practices tools:" && grep -c "name: '" src/core/tool-schemas/best-practices-tools.ts
+echo "SFRA tools:" && grep -c "name: '" src/core/tool-schemas/sfra-tools.ts
+echo "ISML tools:" && grep -c "name: '" src/core/tool-schemas/isml-tools.ts
+echo "Log + Job log tools:" && grep -c "name: '" src/core/tool-schemas/log-tools.ts
+echo "System object tools:" && grep -c "name: '" src/core/tool-schemas/system-object-tools.ts
+echo "Cartridge tools:" && grep -c "name: '" src/core/tool-schemas/cartridge-tools.ts
+echo "Code version tools:" && grep -c "name: '" src/core/tool-schemas/code-version-tools.ts
 
 # Verify file structure changes
 find src -name "*.ts" -type f | wc -l  # Count TypeScript files
@@ -515,252 +562,59 @@ find docs -name "*.md" -type f | wc -l  # Count documentation files
 
 **Remember**: These documentation files serve as the primary source of truth for understanding the project. `AGENTS.md` guides development practices and architecture, while `README.md` serves users and contributors. Keeping both current ensures consistent understanding across all stakeholders and maintains professional project standards.
 
-### 🔧 Common Development Tasks (Streamlined)
-
-- **Adding New Tools**: Define schema in `core/tool-definitions.ts`, implement handler in appropriate handler class in `core/handlers/`, or create new handler extending `BaseToolHandler`
-- **Creating New Handlers**: Extend `BaseToolHandler` class, implement `canHandle()` and `handle()` methods, register in `server.ts`
-- **Using ClientFactory**: Create clients using `ClientFactory` for centralized creation and dependency injection support
-- **Implementing Services**: Create service interfaces in `services/index.ts`, implement production versions, and provide mock implementations for testing
-- **Dependency Injection**: Use constructor injection for services, leverage `ClientFactory` for client creation with optional service injection
-- **Updating Documentation**: Modify files in `docs/` and run conversion scripts
-- **Enhancing Authentication**: Update `clients/base/oauth-token.ts` and client authentication logic
-- **Improving Caching**: Enhance `utils/cache.ts` for better performance and data freshness
-- **Adding Configuration Options**: Update `config/` modules for new configuration capabilities
-- **Adding Tests**: Create comprehensive test coverage in the `tests/` directory with proper service mocking
-- **MCP Test Execution**: Use `node --test` for individual MCP programmatic tests, NOT `npm test -- file.js` (which runs Jest)
-- **Test Types**: Jest for unit tests (`src/` directory), Node.js test runner for MCP programmatic tests (`tests/mcp/node/`), Aegis for YAML tests (`tests/mcp/yaml/`)
-- **Adding Utilities**: Extend `utils/` modules for shared functionality
-- **Handler Development**: Follow the modular handler pattern - each handler is responsible for a specific tool category with clear separation of concerns
-- **Cartridge Generation**: Use `generate_cartridge_structure` tool for automated cartridge creation with direct file generation
-- **Job Log Analysis**: Use job log tools for debugging custom job steps - `get_latest_job_log_files`, `get_job_log_entries`, `search_job_logs`, `search_job_logs_by_name`, `get_job_execution_summary`
-- **Modular Log Development**: Work with individual log modules in `clients/logs/` for specific functionality - modify `log-analyzer.ts` for analysis improvements, `log-formatter.ts` for output changes, or `log-file-reader.ts` for reading optimizations
-- **Modular Documentation Development**: Work with individual documentation modules in `clients/docs/` for specific functionality - modify `documentation-scanner.ts` for file discovery improvements, `class-content-parser.ts` for parsing enhancements, `class-name-resolver.ts` for name resolution logic, or `referenced-types-extractor.ts` for type extraction algorithms
-- **Documentation Verification**: Use verification commands (see Maintenance) before changing numeric counts or structure claims
-- **CI-Friendly Performance Testing**: When writing performance tests, use lenient timeouts (500ms+) and variation ratios (50x+) to account for GitHub Actions CI environment variability. Prioritize functional validation over strict timing requirements to prevent flaky failures due to infrastructure differences.
-
-### 🔍 Testing & Validation (Consolidated Summary)
-Detailed testing guidance lives in:
-- `tests/mcp/AGENTS.md` (umbrella & decision matrix)
-- `tests/mcp/yaml/AGENTS.md` (YAML discovery-first workflow & pattern catalog)
-- `tests/mcp/node/AGENTS.md` (programmatic multi-step, stderr management, performance tolerances)
-
-Essentials:
-- Always discover success + empty/no-result + error responses with `npx aegis query` before writing tests.
-- Prefer YAML for broad coverage; use programmatic tests for stateful or multi-step logic.
-- Keep performance assertions lenient (<500ms typical; <50× variance) unless you have empirical baselines.
-
-Cheat Sheet:
-```bash
-# List tools
-npx aegis query --config ./aegis.config.docs-only.json
-
-# Discovery examples
-npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
-npx aegis query get_sfra_document 'documentName:server' --config ./aegis.config.docs-only.json
-npx aegis query get_system_object_definitions '' --config ./aegis.config.with-dw.json
-
-# Complex dotted parameters
-npx aegis query search_system_object_attribute_definitions 'objectType:Product|searchRequest.query.match_all_query:{}' --config ./aegis.config.with-dw.json
-
-# Test suites
-npm run test:mcp:yaml        # YAML (docs-only)
-npm run test:mcp:yaml:full   # YAML (full mode)
-npm run test:mcp:node        # Programmatic
-jest                        # Unit tests
-npm test                    # Full suite
-
-# Single programmatic test
-node --test tests/mcp/node/get-latest-debug.full-mode.programmatic.test.js
-```
-
-Troubleshooting Quick Tips:
-- Mismatch schema: re-run discovery; update both test + docs.
-- Flaky stderr assertions: ensure `client.clearStderr()` in programmatic tests (see node guide).
-- Empty arrays vs objects: record actual shape before choosing regex pattern.
-
-#### **Debugging Tool Responses**
-
-When developing or debugging tools, use aegis to inspect actual response formats:
-
-```bash
-# Capture full response structure for test validation (pipe format)
-npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json | head -50
-
-# Traditional method format (still supported)
-npx aegis query --config ./aegis.config.docs-only.json --method "tools/call" --params '{"name": "[tool-name]", "arguments": [args]}' | head -50
-
-# Test error handling (pipe format)
-npx aegis query search_sfcc_classes 'query:' --config ./aegis.config.docs-only.json
-
-# Verify JSON response structure (pipe format)
-npx aegis query get_sfcc_class_info 'className:dw.catalog.Product' --config ./aegis.config.docs-only.json | jq '.'
-```
-
-#### **Development Workflow Integration**
-
-1. **Tool Development**: After implementing a new tool, immediately test with aegis before writing unit tests
-2. **Response Validation**: Use aegis to capture actual response structures when writing test assertions
-3. **Error Testing**: Verify error handling behavior with invalid parameters through aegis
-4. **Configuration Testing**: Test both docs-only and full modes to ensure proper tool availability
-5. **Integration Testing**: Validate tool interactions and data flow using aegis before automated tests
-
-#### **Critical: Response Format Discovery Before Writing Tests**
-
-**ALWAYS use aegis query to understand actual response formats before writing YAML tests.** This prevents test failures due to incorrect assumptions about response structure.
-
-##### **Essential Pre-Test Discovery Process:**
+### 🔧 Common Development Tasks
 
-1. **Query the tool with sample arguments** to see actual response format:
-   ```bash
-   npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
-   ```
+**Code Development:**
+- **Adding New Tools**: Define schema in `core/tool-schemas/[category]-tools.ts`, add to `index.ts`, implement in `core/handlers/`
+- **Creating New Handlers**: Extend `BaseToolHandler`, implement `canHandle()` and `handle()`, register in `server.ts`
+- **Using ClientFactory**: Create clients with `ClientFactory` for centralized creation and DI support
+- **Implementing Services**: Create interfaces in `services/index.ts`, implement production + mock versions
 
-2. **Test edge cases** (empty results, errors) to understand all response variations:
-   ```bash
-   npx aegis query search_sfcc_classes 'query:zzznothingfound' --config ./aegis.config.docs-only.json
-   npx aegis query search_sfcc_classes 'query:' --config ./aegis.config.docs-only.json
-   ```
+**Testing** (see `.github/skills/` for detailed guides):
+- **YAML Tests**: Use `mcp-yaml-testing` skill for declarative test creation
+- **Programmatic Tests**: Use `mcp-programmatic-testing` skill for complex workflows
+- **Unit Tests**: Jest for `tests/` directory; MCP tests use `node --test`
 
-3. **Document the actual response structure** before writing test expectations:
-   - Is it a JSON object with metadata fields like `{classes: [], totalCount: 5, searchTerm: "query"}`?
-   - Or a simple JSON array like `["dw.catalog.Product", "dw.catalog.Catalog"]`?
-   - Does it return `[]` for no results or `{classes: [], totalCount: 0}`?
+**SFCC-Specific Tasks** (see `.github/skills/` for detailed guides):
+- **Cartridge Generation**: Use `sfcc-cartridge-generation` skill for scaffolding
+- **Log Debugging**: Use `sfcc-log-debugging` skill for error investigation
 
-4. **Use the correct validation patterns** based on actual responses:
-   ```yaml
-   # For JSON array responses
-   text: "match:regex:\\[[\\s\\S]*\\]"
-   
-   # For empty array responses  
-   text: "match:regex:^\\[\\s*\\]$"
-   
-   # For JSON object responses
-   text: "match:regex:\\{[\\s\\S]*\\}"
-   
-   # For specific content validation
-   text: "match:contains:dw.catalog.Product"
-   ```
+**Modular Development:**
+- **Log Modules**: Modify `clients/logs/` files for log functionality changes
+- **Doc Modules**: Modify `clients/docs/` files for documentation parsing changes
+- **Documentation**: Use verification commands before updating counts
 
-##### **Common Testing Mistakes to Avoid:**
+### 🔍 Testing & Validation
 
-- **Assuming JSON structure without verification**: Don't expect `{classes: [], totalCount: 5}` if tool returns `["class1", "class2"]`
-- **Wrong empty result validation**: Using `match:exact:[]` instead of `match:regex:^\\[\\s*\\]$`
-- **Missing edge case testing**: Not testing empty queries, invalid parameters, or no-result scenarios
-- **Incorrect pattern syntax**: Using `contains:classes` instead of `match:contains:classes`
+**Skills Available**: For detailed testing workflows, use these Agent Skills (in `.github/skills/`):
+- `mcp-yaml-testing` - YAML test creation, patterns, discovery workflow
+- `mcp-programmatic-testing` - JavaScript tests, buffer management, multi-step workflows
 
-##### **Response Format Discovery Examples:**
+**Test Type Decision Matrix**:
+| Scenario | Recommended | Reason |
+|----------|-------------|--------|
+| Basic tool validation | YAML | Simple, declarative, CI-friendly |
+| Schema/shape testing | YAML | Pattern matching built-in |
+| Multi-step workflows | Programmatic | State management needed |
+| Complex business logic | Programmatic | Code execution required |
 
+**Essential Commands**:
 ```bash
-# Discover structure for class search (pipe format)
-npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
-# Result: ["dw.catalog.Catalog", "dw.catalog.Product", ...] (simple array)
-
-# Discover empty result format (pipe format)
-npx aegis query search_sfcc_classes 'query:zzznothingfound' --config ./aegis.config.docs-only.json
-# Result: [] (empty array)
-
-# Discover error response format (pipe format)
-npx aegis query search_sfcc_classes 'query:' --config ./aegis.config.docs-only.json
-# Result: {"content": [{"type": "text", "text": "Error: ..."}], "isError": true}
-```
-
-**Remember**: The time spent discovering actual response formats with aegis saves hours of debugging failed tests later. Always query first, then write tests based on reality, not assumptions.
-
-#### **Troubleshooting with Aegis**
-
-- **Tool Not Found**: Check configuration mode (docs-only vs full) and ensure tool is properly registered
-- **Invalid Arguments**: Use aegis to test parameter validation and see exact error messages
-- **Response Issues**: Compare aegis output with programmatic test expectations to identify format mismatches
-- **Performance Issues**: Use aegis timing information to identify slow tools
-- **Authentication Problems**: Test full-mode tools with aegis to validate OCAPI/WebDAV connections
-
-#### **Best Practices**
-
-- **CRITICAL: Always discover response formats first** - Use aegis query to understand actual response structure before writing any tests
-- **Always test new tools** with aegis before writing automated tests
-- **Use aegis output** to write accurate test assertions rather than guessing response formats  
-- **Test both success and error cases** with aegis during development
-- **Verify tool availability** in different configuration modes using aegis
-- **Debug programmatic test failures** by comparing with aegis CLI results
-- **Test parameter validation** using aegis with various input combinations
-- **Document actual response formats** in test file comments for future reference
-- **Test edge cases comprehensively** - empty results, invalid inputs, missing parameters
-- **Use correct YAML pattern syntax** - always prefix with `match:` for validation patterns
-
-#### **CI-Friendly Performance Testing Guidelines**
-
-When writing performance-related tests, especially for GitHub Actions CI environments, follow these critical guidelines:
-
-- **Use Lenient Timeouts**: Set timeout thresholds of **500ms or higher** instead of strict values (50ms-250ms). CI environments are slower and less predictable than local development machines.
-- **Account for Environment Variability**: CI runners experience resource contention, cold starts, network latency, and I/O scheduling delays that can significantly impact timing.
-- **Performance Variation Ratios**: For tests comparing min/max performance, use ratios of **50x or higher** instead of strict ratios (15x). CI environments can have extreme variations due to:
-  - Resource sharing with other processes
-  - JIT compilation and garbage collection delays  
-  - Network and file system variability
-  - Container initialization overhead
-- **Scaling Calculations**: When calculating expected performance based on result count, use generous base times (100ms+) and scaling factors (2ms+ per item) rather than tight calculations.
-- **Focus on Functional Validation**: Prioritize correctness over strict performance requirements. Performance tests should catch major regressions, not minor timing variations.
-- **Example CI-Friendly Assertions**:
-  ```javascript
-  // ❌ Too strict for CI
-  assert.ok(duration < 50, `Response time should be under 50ms`);
-  assert.ok(variationRatio < 15, `Performance variation should be under 15x`);
-  
-  // ✅ CI-friendly
-  assert.ok(duration < 500, `Response time should be under 500ms`);
-  assert.ok(variationRatio < 50, `Performance variation should be under 50x`);
-  ```
-
-**Remember**: The goal is reliable CI builds that catch real issues without flaky failures due to infrastructure timing differences.
-
-#### **Comprehensive Testing Documentation**
-
-For comprehensive MCP testing guidance, refer to the specialized AGENTS.md files in the testing directories:
-
-##### **YAML-Based Declarative Testing**
-The primary testing approach using human-readable YAML files with advanced pattern matching:
-
-- **30+ Advanced Pattern Matching**: String patterns, numeric comparisons, date validation, array operations, field extraction, cross-field validation, and pattern negation
-- **Declarative YAML Testing**: Human-readable test files with sophisticated validation patterns
-- **Interactive Tool Testing**: Quick commands for testing tools interactively with the aegis CLI
-- **Debugging Workflows**: Step-by-step approaches for troubleshooting test failures and server issues
-- **Real-World Examples**: Complete test suites for filesystem servers, multi-tool servers, and API testing scenarios
-- **Performance Testing**: Patterns for validating response times and system performance
-- **Error Handling Validation**: Comprehensive approaches to testing error scenarios and edge cases
-
-##### **Programmatic JavaScript/TypeScript Testing** 
-For complex testing scenarios requiring programmatic logic and integration with existing test suites:
-
-- **JavaScript/TypeScript API**: Full programmatic access to MCP server testing capabilities
-- **Advanced Workflows**: Multi-step testing, state management, and dynamic validation logic
-- **Framework Integration**: Jest, Mocha, and Node.js test runner integration patterns
-- **Performance Monitoring**: Built-in metrics collection and performance analysis
-- **Buffer Management**: Critical guidance on preventing test interference with proper `clearStderr()` usage
-- **Error Recovery Testing**: Comprehensive error handling and resilience validation
-- **TypeScript Support**: Full type safety for enterprise testing environments
-
-**Quick Interactive Testing Commands:**
-```bash
-# List all available tools
-aegis query --config ./aegis.config.docs-only.json
-
-# Test specific tool with arguments - Multiple formats supported:
-
-# Pipe format (recommended for CLI)
-aegis query read_file 'path:test.txt' --config ./aegis.config.docs-only.json
-aegis query calculator 'operation:add|a:5|b:3' --config ./aegis.config.docs-only.json
-
-# JSON format (complex structures)
-aegis query complex_tool '{"config": {"host": "localhost"}, "data": [1,2,3]}' --config ./aegis.config.docs-only.json
-
-# Method syntax with pipe format
-aegis query --method tools/call --params 'name:read_file|arguments.path:test.txt' --config ./aegis.config.docs-only.json
-
-# Debug with verbose output
-aegis query read_file 'path:test.txt' --config ./aegis.config.docs-only.json --verbose
+# Discovery (ALWAYS run before writing tests)
+npx aegis query [tool_name] '[params]' --config ./aegis.config.docs-only.json
+
+# Test execution
+npm run test:mcp:yaml        # YAML tests (docs-only)
+npm run test:mcp:yaml:full   # YAML tests (full mode)
+npm run test:mcp:node        # Programmatic tests
+npm test                     # Full suite (Jest + MCP)
 ```
 
-**For AI Agents**: Both AGENTS.md files are specifically designed for AI assistants to understand how to create and execute comprehensive test suites for MCP servers. Choose YAML-based testing for declarative scenarios or programmatic testing for complex logic requirements. Both approaches can be directly applied to validate this SFCC Dev MCP server's functionality.
+**Critical Rules**:
+1. Always discover response formats with `aegis query` before writing tests
+2. Use `client.clearAllBuffers()` in programmatic test `beforeEach()` hooks
+3. Never use `Promise.all()` with MCP requests (causes buffer conflicts)
+4. Use CI-friendly timeouts (500ms+) for performance assertions
 
 ### 🧱 Architecture Advantages (Consolidated)
 Unified benefits of the directory structure, handler model, dependency injection, modular log system, and modular documentation system: