Deploy from GitHub Actions: Mon Feb 23 10:09:33 UTC 2026

Commit: eab2d1232405e9e1c2bfa46ba5b72e966865f8ce
Run: https://github.com/TalkShopClub/morpheus/actions/runs/22301563869

.dockerignore

@@ -0,0 +1,32 @@
+# Ignore all node_modules everywhere
+**/node_modules
+**/.turbo
+**/.next
+**/dist
+**/build
+**/.bun
+**/__pycache__
+
+# Ignore VCS + metadata
+.git
+.gitignore
+.vscode
+.DS_Store
+
+
+
+# Docker-specific junk
+docker-compose*.yml
+Dockerfile
+**/Dockerfile
+
+# Ignore environment files
+.env
+.env.*
+!.env.example
+
+# Logs + temp
+*.log
+tmp
+coverage
+data

.gitattributes

@@ -0,0 +1 @@
+*.{icns,png,jpg,zip,bin,model,pt} filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,64 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+
+# Claude
+CLAUDE.md
+.claude/
+
+*.pdf
+
+
+.nx/cache
+.nx/workspace-data
+.cursor/rules/nx-rules.mdc
+.github/instructions/nx.instructions.md
+
+**/*.log*
+**/files/*
+
+/scripts/*
+/docs/*
+!/docs/od-architecture
+/docs/od-architecture/implementation
+!/docs/chaos
+morpheus-data
+/packages/controlmart/ui/docs
+packages/controlmart/test_ods.sh
+bun.lock
+packages/controlmart/ui/bun.lock
+.postman/
+postman/
+packages/controlmart/scripts/test-index-sync.sh
+/packages/controlmart/src/docs/plans

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "Start ControlMart Dev Server",
+			"type": "shell",
+			"command": "bun run dev",
+			"group": "build",
+			"isBackground": true,
+			"problemMatcher": []
+		}
+	]
+}

Dockerfile

@@ -1 +1,43 @@
-FROM public.ecr.aws/w3z5w3s0/skyfall/morpheus:latest
+FROM oven/bun:latest AS builder
+
+WORKDIR /app
+
+COPY package.json bun.lock ./
+COPY packages/controlmart/package.json ./packages/controlmart/
+COPY packages/controlmart/ui/package.json ./packages/controlmart/ui/
+
+
+RUN bun install
+
+COPY . .
+
+WORKDIR /app/packages/controlmart/ui
+RUN bun install
+RUN bun run build
+
+WORKDIR /app/packages/controlmart
+
+RUN bun run build:binary
+
+FROM mongo:7
+
+RUN apt-get update && apt-get install -y \
+    curl \
+    ca-certificates \
+    netcat-openbsd \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=builder /app/packages/controlmart/morpheus-server ./morpheus-server
+COPY --from=builder /app/packages/controlmart/dist/ui ./ui
+COPY --from=builder /app/start-hf.sh ./start-hf.sh
+RUN chmod +x start-hf.sh
+
+ENV NODE_ENV=production
+ENV PORT=7860
+ENV HOST=0.0.0.0
+ENV MONGO_URI=mongodb://localhost:27017
+ENV DB_NAME=morpheus
+EXPOSE 7860
+CMD ["./start-hf.sh"]

deploy-public-hf.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+set -e
+
+ECR_REGISTRY="public.ecr.aws/w3z5w3s0/skyfall"
+IMAGE_NAME="morpheus"
+IMAGE_TAG="latest"
+FULL_IMAGE_URI="$ECR_REGISTRY/$IMAGE_NAME:$IMAGE_TAG"
+
+
+PUBLIC_REPO_DIR="../morpheus_public"
+SOURCE_README="README.md"
+DEST_README="$PUBLIC_REPO_DIR/README.md"
+
+echo "==============================================="
+echo "   Morpheus Public Deployment Script"
+echo "==============================================="
+
+echo "[1/3] Building and Publishing to ECR..."
+echo "Target: $FULL_IMAGE_URI"
+
+echo "Note: Ensure you are logged into ECR Public."
+
+echo "Building image..."
+docker build --platform linux/amd64 -f Dockerfile.hf -t "$FULL_IMAGE_URI" .
+
+echo "Pushing image..."
+docker push "$FULL_IMAGE_URI"
+echo "ECR Publish Complete."
+
+echo "[2/3] Syncing Documentation..."
+if [ -f "$SOURCE_README" ]; then
+    cp "$SOURCE_README" "$DEST_README"
+    echo "Copied $SOURCE_README to $DEST_README"
+else
+    echo "Warning: $SOURCE_README not found in current directory."
+fi
+
+echo "[3/3] Updating Public Repository..."
+
+if [ ! -d "$PUBLIC_REPO_DIR" ]; then
+    echo "Error: Directory $PUBLIC_REPO_DIR does not exist."
+    echo "Please clone the Hugging Face repository to $PUBLIC_REPO_DIR first."
+    exit 1
+fi
+
+cd "$PUBLIC_REPO_DIR" || exit
+
+if [[ -n $(git status -s) ]]; then
+    echo "Changes detected. Committing and pushing..."
+    git add .
+    git commit -m "Deploy update: $(date)"
+    git push
+    echo "Public Repo Updated."
+else
+    echo "No changes to public repo files."
+fi
+
+echo "==============================================="
+echo "   Deployment Complete!"
+echo "==============================================="

docs/chaos/README.md

@@ -0,0 +1,104 @@
+# Chaos Engineering & Management
+
+## Overview
+
+This directory contains documentation for Morpheus's chaos engineering system - a comprehensive framework for injecting realistic failures into workflows to test AI agent resilience.
+
+## The Problem
+
+Currently, chaos configuration is scattered across 14+ files with:
+- Hardcoded probabilities in builders (0.0 to 0.8)
+- Step-level inline configs with inconsistent values
+- No central configuration or master kill-switch
+- No environment-specific profiles
+- Same workflow having different chaos in different places
+
+## The Solution
+
+A comprehensive chaos management system with:
+- **Centralized Configuration**: Preset library with reusable chaos configurations
+- **Environment Control**: Master kill-switch and environment-specific profiles
+- **Multi-Level Configuration**: World → Capability → OD → Step cascade
+- **Reproducibility**: Seeded randomness for deterministic chaos
+- **Integration**: Seamlessly integrated with OD architecture
+
+## Documentation
+
+### [Chaos Management](./chaos-management.md)
+Complete chaos management system design:
+- Current problems and gaps
+- Proposed architecture with priority cascade
+- Centralized preset library (light, moderate, aggressive, realistic)
+- Environment variables and master kill-switch
+- World, capability, and OD-level configuration
+- API endpoints for chaos control
+- Migration strategy from scattered configs
+- Best practices for researchers
+
+## Current Chaos Capabilities
+
+### 11 Chaos Scenario Types
+
+1. **data_corruption** - Corrupt field values (null, wrong type, invalid format, random value)
+2. **missing_data** - Remove fields or records
+3. **stale_data** - Age timestamps (simulate eventual consistency)
+4. **format_change** - Schema evolution (rename fields, change types)
+5. **permission_denied** - Authorization errors
+6. **rate_limit** - API throttling with delays
+7. **partial_data** - Return subset of results (pagination issues)
+8. **duplicate_data** - Inject duplicate records
+9. **invalid_state** - Set records to invalid states (deleted, suspended)
+10. **dependency_failure** - Downstream service unavailability
+11. **timing_issue** - Future timestamps (clock skew)
+
+## Quick Start
+
+### Using Presets
+
+```yaml
+world:
+  chaos:
+    preset: "moderate"  # Options: light, moderate, aggressive, realistic
+    seed: "reproducible-123"
+```
+
+### Custom Configuration
+
+```yaml
+world:
+  chaos:
+    globalPolicy:
+      enabled: true
+      probability: 0.15
+      scenarios:
+        - type: stale_data
+          weight: 10
+        - type: rate_limit
+          weight: 5
+```
+
+### Master Kill-Switch
+
+```bash
+# Disable all chaos globally
+export CHAOS_ENABLED=false
+```
+
+## Related Documentation
+
+- [Current Chaos Implementation](../03-chaos-engineering.md) - Existing chaos engine details
+- [OD Architecture](../od-architecture/) - How chaos integrates with OD system
+- [World Configuration](../od-architecture/05-sampling-world-config.md) - Configuring chaos per world
+
+## Status
+
+**Phase**: Design & Planning
+**Last Updated**: 2025-11-14
+
+## Next Steps
+
+1. Review chaos management design
+2. Implement centralized registry and presets
+3. Add environment variable controls
+4. Migrate scattered chaos configs
+5. Build chaos configuration API

docs/chaos/chaos-management.md

@@ -0,0 +1,808 @@
+# 07. Chaos Management
+
+## Overview
+
+Chaos engineering in Morpheus allows researchers to inject realistic failures into workflows to test AI agent resilience. However, the current chaos configuration is scattered across 14+ files, making it unmanageable. This document proposes a comprehensive chaos management system integrated with the broader OD architecture.
+
+## Current Problems
+
+### 1. Scattered Configuration
+
+**Hardcoded Probabilities**:
+```typescript
+// In different files:
+GenericODBuilder: chaosProbability: 0.0
+EDI builder: chaosProbability: 0.1
+ERP builder: chaosProbability: 0.05
+CRM builder: chaosProbability: 0.05
+WMS builder: chaosProbability: 0.05
+```
+
+**Step-Level Inline Configs**:
+```typescript
+// od-builders.edi.util.ts
+EDI 850 generation: probability: 0.0
+Invoice generation: probability: 0.05
+Advanced ship notice: probability: 0.1
+
+// od-builders-refactored.edi.util.ts
+Refactored EDI 850: probability: 0.2  // Different value!
+Invoice step: probability: 0.1
+ASN step: probability: 0.1
+```
+
+**Demo/Test Specific**:
+```typescript
+// chaos-edi-demo.ts
+probability: 0.8  // Very aggressive for demo
+scenarios: 7 different chaos types
+
+// simple-edi-demo.ts
+chaosProbability: 0.0  // Disabled
+```
+
+### 2. No Central Configuration
+
+- No single source of truth
+- Same workflow has different chaos in different files
+- No reusable scenario library
+- Must edit code to change chaos
+
+### 3. No Environment Awareness
+
+- Same chaos runs in all environments
+- No way to disable in production
+- No environment-specific profiles (dev/staging/prod)
+
+### 4. No Master Kill-Switch
+
+- Can't globally disable chaos
+- Must manually set probability to 0 everywhere
+- Risk of leaving chaos enabled accidentally
+
+### 5. Inconsistent Behavior
+
+- Duplication: Similar scenarios defined multiple times
+- Variation: Same operation has different chaos values
+- Maintenance: Changing chaos requires editing multiple files
+
+## Chaos in the OD Architecture
+
+### Chaos as a Cross-Cutting Concern
+
+Chaos configuration exists at multiple levels:
+
+```
+┌─────────────────────────────────┐
+│  WORLD                          │  Global chaos policy
+│  ├─ Global Chaos Policy         │  (affects all capabilities in world)
+│  └─ Chaos Presets               │
+└──────────────┬──────────────────┘
+               │
+               ↓
+┌─────────────────────────────────┐
+│  CAPABILITY                     │  Capability-level overrides
+│  └─ Chaos Override (optional)   │  (e.g., Order Fulfillment always has 0.3 chaos)
+└──────────────┬──────────────────┘
+               │
+               ↓
+┌─────────────────────────────────┐
+│  OD (Workflow)                  │  OD-level chaos config
+│  ├─ Global OD Chaos Policy      │  (applies to all steps in OD)
+│  └─ Step-Level Overrides        │
+└──────────────┬──────────────────┘
+               │
+               ↓
+┌─────────────────────────────────┐
+│  STEP                           │  Step-level chaos override
+│  └─ Step Chaos Override         │  (most specific, highest priority)
+└─────────────────────────────────┘
+```
+
+**Priority (highest to lowest)**:
+1. Step-level override
+2. OD-level policy
+3. Capability-level override
+4. World-level global policy
+5. System defaults
+
+**Master Kill-Switch**: Environment variable overrides everything
+
+## Proposed Architecture
+
+### 1. Environment Variables (Master Control)
+
+```bash
+# Master kill-switch
+CHAOS_ENABLED=true|false          # Override all chaos config
+
+# Global settings
+CHAOS_ENV=development|staging|production
+CHAOS_GLOBAL_PROBABILITY=0.1      # Default probability if not specified
+CHAOS_GLOBAL_SEED=seed-123        # For reproducibility
+
+# Preset selection
+CHAOS_PRESET=light|moderate|aggressive|custom
+CHAOS_PRESET_FILE=/path/to/custom-preset.json
+
+# Telemetry
+CHAOS_TELEMETRY_LEVEL=basic|detailed|verbose
+```
+
+**Priority**: Environment variables override all file-based configuration.
+
+### 2. Centralized Preset Library
+
+#### File Structure
+```
+/config/
+  /chaos-presets/
+    default.json              # System default
+    light.json                # Low probability, common scenarios
+    moderate.json             # Medium probability, diverse scenarios
+    aggressive.json           # High probability, all scenarios
+    realistic.json            # Real-world distribution
+    /domain/
+      fulfillment.json        # Fulfillment-specific chaos
+      inventory.json          # Inventory-specific chaos
+      transportation.json     # Transportation-specific chaos
+```
+
+#### Preset Format
+
+**Example: `light.json`**
+```json
+{
+  "id": "light",
+  "name": "Light Chaos",
+  "description": "Low probability chaos for basic resilience testing",
+  "globalProbability": 0.05,
+  "scenarios": [
+    {
+      "type": "stale_data",
+      "weight": 10,
+      "description": "Simulate eventual consistency delays",
+      "config": {
+        "staleDataAge": 30
+      }
+    },
+    {
+      "type": "rate_limit",
+      "weight": 5,
+      "description": "API throttling",
+      "config": {
+        "rateLimitDelay": 1000,
+        "rateLimitMessage": "Rate limit exceeded"
+      }
+    },
+    {
+      "type": "missing_data",
+      "weight": 3,
+      "description": "Occasional missing records",
+      "config": {
+        "missingRecords": true
+      }
+    }
+  ]
+}
+```
+
+**Example: `aggressive.json`**
+```json
+{
+  "id": "aggressive",
+  "name": "Aggressive Chaos",
+  "description": "High probability chaos with all scenario types",
+  "globalProbability": 0.3,
+  "scenarios": [
+    {
+      "type": "data_corruption",
+      "weight": 8,
+      "config": {
+        "corruptFields": ["*"],
+        "corruptionType": "random"
+      }
+    },
+    {
+      "type": "missing_data",
+      "weight": 7,
+      "config": {
+        "missingFields": ["*"],
+        "missingRecords": true
+      }
+    },
+    {
+      "type": "stale_data",
+      "weight": 6,
+      "config": {
+        "staleDataAge": 120
+      }
+    },
+    {
+      "type": "format_change",
+      "weight": 5,
+      "config": {
+        "changeType": "all"
+      }
+    },
+    {
+      "type": "permission_denied",
+      "weight": 4,
+      "config": {}
+    },
+    {
+      "type": "rate_limit",
+      "weight": 7,
+      "config": {
+        "rateLimitDelay": 3000
+      }
+    },
+    {
+      "type": "partial_data",
+      "weight": 6,
+      "config": {
+        "returnCount": 5
+      }
+    },
+    {
+      "type": "duplicate_data",
+      "weight": 5,
+      "config": {
+        "duplicateCount": 3
+      }
+    },
+    {
+      "type": "invalid_state",
+      "weight": 4,
+      "config": {
+        "invalidStates": ["deleted", "suspended"]
+      }
+    },
+    {
+      "type": "dependency_failure",
+      "weight": 3,
+      "config": {}
+    },
+    {
+      "type": "timing_issue",
+      "weight": 2,
+      "config": {
+        "timeSkewMinutes": 30
+      }
+    }
+  ]
+}
+```
+
+**Example: `realistic.json`** (based on real-world failure rates)
+```json
+{
+  "id": "realistic",
+  "name": "Realistic Chaos",
+  "description": "Chaos distribution matching real-world failure rates",
+  "globalProbability": 0.08,
+  "scenarios": [
+    {
+      "type": "stale_data",
+      "weight": 40,
+      "description": "Most common: eventual consistency"
+    },
+    {
+      "type": "rate_limit",
+      "weight": 20,
+      "description": "Common: API throttling"
+    },
+    {
+      "type": "timeout",
+      "weight": 15,
+      "description": "Common: network delays"
+    },
+    {
+      "type": "partial_data",
+      "weight": 10,
+      "description": "Occasional: pagination issues"
+    },
+    {
+      "type": "data_corruption",
+      "weight": 7,
+      "description": "Rare: data quality issues"
+    },
+    {
+      "type": "missing_data",
+      "weight": 5,
+      "description": "Rare: data loss"
+    },
+    {
+      "type": "permission_denied",
+      "weight": 2,
+      "description": "Very rare: auth failures"
+    },
+    {
+      "type": "dependency_failure",
+      "weight": 1,
+      "description": "Very rare: service outages"
+    }
+  ]
+}
+```
+
+### 3. Chaos Configuration Registry
+
+**TypeScript Service**:
+```typescript
+// src/config/chaos-config.registry.ts
+
+interface ChaosConfigRegistry {
+  // Presets
+  loadPreset(presetId: string): ChaosPolicy;
+  listPresets(): PresetMetadata[];
+  createPreset(preset: ChaosPreset): void;
+
+  // World-level
+  getWorldChaosPolicy(worldId: string): ChaosPolicy;
+  setWorldChaosPolicy(worldId: string, policy: ChaosPolicy): void;
+
+  // Capability-level
+  getCapabilityChaos(capabilityId: string): ChaosPolicy | null;
+  setCapabilityChaos(capabilityId: string, policy: ChaosPolicy): void;
+
+  // OD-level (runtime overrides)
+  getODChaos(odId: string): ChaosPolicy | null;
+  setODChaos(odId: string, policy: ChaosPolicy): void;
+
+  // Resolution (apply priority rules)
+  resolveChaosPolicy(context: ChaosContext): ChaosPolicy;
+
+  // Master switch
+  isChaosEnabled(): boolean;
+}
+
+interface ChaosContext {
+  worldId: string;
+  capabilityId?: string;
+  odId: string;
+  stepId: string;
+  service?: string;
+  tool?: string;
+}
+
+class ChaosConfigRegistryImpl implements ChaosConfigRegistry {
+  private presets: Map<string, ChaosPreset> = new Map();
+  private worldPolicies: Map<string, ChaosPolicy> = new Map();
+  private capabilityOverrides: Map<string, ChaosPolicy> = new Map();
+  private odOverrides: Map<string, ChaosPolicy> = new Map();
+
+  constructor() {
+    this.loadPresetsFromDisk();
+  }
+
+  resolveChaosPolicy(context: ChaosContext): ChaosPolicy {
+    // 0. Check master kill-switch
+    if (!this.isChaosEnabled()) {
+      return { enabled: false, probability: 0, scenarios: [] };
+    }
+
+    // Priority cascade (highest to lowest)
+    const policies = [
+      // 1. Step-level (from OD definition)
+      this.getStepChaos(context.odId, context.stepId),
+
+      // 2. OD-level
+      this.odOverrides.get(context.odId),
+
+      // 3. Capability-level
+      context.capabilityId ? this.capabilityOverrides.get(context.capabilityId) : null,
+
+      // 4. World-level
+      this.worldPolicies.get(context.worldId),
+
+      // 5. Global preset (from env or default)
+      this.getGlobalPreset(),
+    ];
+
+    // Return first non-null policy
+    return policies.find(p => p !== null) || this.getDefaultPolicy();
+  }
+
+  isChaosEnabled(): boolean {
+    const envFlag = process.env.CHAOS_ENABLED;
+    if (envFlag !== undefined) {
+      return envFlag.toLowerCase() === 'true';
+    }
+    return true; // Default: enabled
+  }
+}
+```
+
+### 4. World Configuration Integration
+
+**World Chaos Config**:
+```yaml
+world:
+  id: "warehouse-research-001"
+  name: "Warehouse Automation Research"
+
+  chaos:
+    # Option 1: Use preset
+    preset: "moderate"
+
+    # Option 2: Custom global policy
+    globalPolicy:
+      enabled: true
+      probability: 0.15
+      seed: "reproducible-seed-123"
+      scenarios:
+        - type: stale_data
+          weight: 10
+        - type: rate_limit
+          weight: 5
+
+    # Option 3: Per-capability overrides
+    capabilityOverrides:
+      order-fulfillment:
+        probability: 0.3  # Higher chaos for this capability
+        scenarios:
+          - type: missing_data
+            weight: 10
+
+      inventory-check:
+        probability: 0.0  # No chaos for this capability
+
+    # Option 4: Per-OD overrides (runtime)
+    odOverrides:
+      order-fulfillment-v1:
+        probability: 0.25
+```
+
+### 5. API Endpoints
+
+```typescript
+// Presets
+GET    /api/chaos/presets                    # List all presets
+GET    /api/chaos/presets/:presetId          # Get preset details
+POST   /api/chaos/presets                    # Create custom preset
+PUT    /api/chaos/presets/:presetId          # Update preset
+DELETE /api/chaos/presets/:presetId          # Delete preset
+
+// World-level chaos
+GET    /api/worlds/:worldId/chaos            # Get world chaos config
+PUT    /api/worlds/:worldId/chaos            # Update world chaos
+POST   /api/worlds/:worldId/chaos/preset/:presetId  # Apply preset to world
+
+// Capability-level chaos
+GET    /api/capabilities/:capId/chaos        # Get capability chaos override
+PUT    /api/capabilities/:capId/chaos        # Set capability chaos override
+DELETE /api/capabilities/:capId/chaos        # Remove override
+
+// Runtime OD chaos
+GET    /api/ods/:odId/chaos                  # Get OD chaos config
+PUT    /api/ods/:odId/chaos                  # Set OD chaos override (runtime)
+DELETE /api/ods/:odId/chaos                  # Remove override
+
+// Chaos status and testing
+GET    /api/chaos/status                     # Is chaos enabled? Global settings
+POST   /api/chaos/test                       # Test chaos injection (dry run)
+GET    /api/chaos/scenarios                  # List all scenario types
+```
+
+### 6. Migration Strategy
+
+#### Phase 1: Add Central Registry (No Breaking Changes)
+1. Create `ChaosConfigRegistry` service
+2. Load presets from JSON files
+3. Add environment variable support
+4. Keep existing inline configs working (backward compatible)
+
+#### Phase 2: Update Chaos Engine
+1. Modify `chaos-engine.od.ts` to use registry
+2. Implement priority cascade logic
+3. Add master kill-switch check
+4. Log which chaos policy was applied
+
+#### Phase 3: Migrate Existing Configs
+1. Extract inline chaos configs to presets
+2. Remove hardcoded probabilities from builders
+3. Update tests to use registry
+4. Add deprecation warnings for old patterns
+
+#### Phase 4: Cleanup
+1. Remove old builder chaos parameters
+2. Delete duplicate scenario definitions
+3. Document new patterns
+4. Provide migration guide
+
+## Example Usage Patterns
+
+### Pattern 1: Default Chaos (Preset)
+
+**Environment**:
+```bash
+CHAOS_ENABLED=true
+CHAOS_PRESET=moderate
+```
+
+**Result**: All worlds use "moderate" preset unless overridden.
+
+---
+
+### Pattern 2: Per-World Customization
+
+**World Config**:
+```yaml
+world:
+  name: "High Chaos Test"
+  chaos:
+    preset: "aggressive"
+```
+
+**Result**: This world has aggressive chaos, others use default.
+
+---
+
+### Pattern 3: Capability-Specific Chaos
+
+**Capability Override**:
+```typescript
+chaosRegistry.setCapabilityChaos('order-fulfillment', {
+  enabled: true,
+  probability: 0.3,
+  scenarios: [
+    { type: 'missing_data', weight: 10, config: { missingRecords: true } },
+    { type: 'stale_data', weight: 8, config: { staleDataAge: 60 } },
+  ]
+});
+```
+
+**Result**: Order fulfillment always has 30% chaos, other capabilities use world default.
+
+---
+
+### Pattern 4: Environment-Based Profiles
+
+**Environment Variables**:
+```bash
+# Development
+CHAOS_ENABLED=true
+CHAOS_PRESET=aggressive
+CHAOS_GLOBAL_PROBABILITY=0.3
+
+# Staging
+CHAOS_ENABLED=true
+CHAOS_PRESET=moderate
+CHAOS_GLOBAL_PROBABILITY=0.1
+
+# Production
+CHAOS_ENABLED=false
+```
+
+**Result**: Chaos automatically adjusts based on environment.
+
+---
+
+### Pattern 5: Reproducible Experiments
+
+**Configuration**:
+```yaml
+world:
+  chaos:
+    preset: "moderate"
+    seed: "experiment-001-seed"
+```
+
+**Result**: Same seed produces identical chaos injections across runs.
+
+---
+
+### Pattern 6: Emergency Disable
+
+**Command**:
+```bash
+# Set environment variable and restart
+export CHAOS_ENABLED=false
+
+# Or via API (if running)
+curl -X PUT /api/chaos/status -d '{"enabled": false}'
+```
+
+**Result**: All chaos immediately disabled without code changes.
+
+## Chaos Telemetry & Observability
+
+### Chaos Injection Logging
+
+**Enhanced Logging**:
+```typescript
+{
+  timestamp: "2025-11-14T10:30:45Z",
+  level: "info",
+  service: "ODFlow",
+  msg: "Chaos injected",
+  chaos: {
+    worldId: "world-123",
+    capabilityId: "order-fulfillment",
+    odId: "order-fulfillment-v1",
+    stepId: "step-2",
+    scenarioType: "stale_data",
+    configSource: "capability-override",  // where policy came from
+    probability: 0.3,
+    seed: "experiment-001-seed",
+    modifications: {
+      staleDataAge: 60,
+      fieldsAffected: ["timestamp", "lastUpdated"]
+    }
+  }
+}
+```
+
+### Chaos Metrics
+
+**Track**:
+- Total chaos injections per world/capability/OD
+- Injection rate over time
+- Scenario type distribution
+- Success/failure correlation with chaos
+- Mean time between chaos events
+
+**API**:
+```typescript
+GET /api/chaos/metrics?worldId=world-123
+{
+  totalInjections: 150,
+  injectionRate: 0.12,  // actual vs configured
+  scenarioDistribution: {
+    stale_data: 60,
+    missing_data: 45,
+    rate_limit: 30,
+    ...
+  },
+  impactAnalysis: {
+    odSuccessRate: 0.75,  // with chaos enabled
+    odSuccessRateWithoutChaos: 0.95,  // estimated baseline
+    meanRecoveryTimeMs: 1500
+  }
+}
+```
+
+## Best Practices for Researchers
+
+### 1. Start with Presets
+```yaml
+# Begin with pre-defined presets
+chaos:
+  preset: "light"  # Start simple
+
+# Progress to more chaos
+chaos:
+  preset: "moderate"
+
+# Advanced testing
+chaos:
+  preset: "aggressive"
+```
+
+### 2. Use Reproducible Seeds
+```yaml
+# Always specify seed for reproducibility
+chaos:
+  preset: "moderate"
+  seed: "experiment-20251114-001"
+```
+
+### 3. Override Selectively
+```yaml
+# Use presets as baseline, override specific capabilities
+chaos:
+  preset: "moderate"
+  capabilityOverrides:
+    critical-capability:
+      probability: 0.0  # No chaos for critical path
+```
+
+### 4. Document Chaos Configuration
+```yaml
+world:
+  name: "Experiment: Agent Resilience Test"
+  description: "Testing AI agent with realistic failure rates"
+  chaos:
+    preset: "realistic"
+    seed: "resilience-test-001"
+  # Document why this chaos config
+  chaosRationale: "Using realistic preset to match production failure rates"
+```
+
+### 5. Compare With and Without Chaos
+```typescript
+// Run baseline (no chaos)
+const baselineWorld = {
+  chaos: { enabled: false }
+};
+
+// Run with chaos
+const chaosWorld = {
+  chaos: { preset: "moderate", seed: "compare-001" }
+};
+
+// Compare results
+const impact = compareChaosImpact(baselineResults, chaosResults);
+```
+
+## Implementation Checklist
+
+### Phase 1: Foundation (Week 1-2)
+- [ ] Create `ChaosConfigRegistry` service
+- [ ] Define preset JSON schema
+- [ ] Create 5 standard presets (light, moderate, aggressive, realistic, custom)
+- [ ] Add environment variable support
+- [ ] Implement master kill-switch
+
+### Phase 2: Integration (Week 3-4)
+- [ ] Update `chaos-engine.od.ts` to use registry
+- [ ] Implement priority cascade logic
+- [ ] Add world-level chaos configuration
+- [ ] Add capability-level overrides
+- [ ] Enhance chaos telemetry logging
+
+### Phase 3: API (Week 5)
+- [ ] Build chaos configuration API endpoints
+- [ ] Add preset management endpoints
+- [ ] Add chaos status/testing endpoints
+- [ ] Create metrics aggregation endpoint
+
+### Phase 4: Migration (Week 6-7)
+- [ ] Extract inline chaos to presets
+- [ ] Update all builders to use registry
+- [ ] Migrate test files
+- [ ] Add backward compatibility layer
+- [ ] Add deprecation warnings
+
+### Phase 5: Documentation (Week 8)
+- [ ] Write chaos configuration guide
+- [ ] Create preset cookbook
+- [ ] Document migration path
+- [ ] Add API documentation
+- [ ] Create tutorial videos/examples
+
+## Open Questions
+
+### Q1: Preset Versioning
+**Question**: Should presets be versioned?
+
+**Options**:
+- A. No versioning (mutable presets)
+- B. Semantic versioning (e.g., `moderate-v1.2.0`)
+- C. Immutable presets (new ID for changes)
+
+**Impact**: Reproducibility, backward compatibility
+
+---
+
+### Q2: Custom Scenario Creation
+**Question**: Can researchers create custom chaos scenarios (new types)?
+
+**Options**:
+- A. No - limited to 11 existing types
+- B. Yes - via preprocessInput/postprocessOutput hooks
+- C. Yes - full extension API for new scenario types
+
+**Impact**: Flexibility vs complexity
+
+---
+
+### Q3: Chaos Scheduling
+**Question**: Should chaos be time-based or event-based?
+
+**Options**:
+- A. Probabilistic only (current approach)
+- B. Add temporal patterns (increase chaos over time, specific time windows)
+- C. Event-driven (inject chaos after N successful operations)
+
+**Impact**: Research sophistication, implementation complexity
+
+---
+
+## Related Documents
+
+- [02. Conceptual Model](./02-conceptual-model.md) - OD architecture
+- [05. Sampling & World Config](./05-sampling-world-config.md) - World configuration
+- [06. Open Questions](./06-open-questions.md) - Unresolved decisions
+- Main docs: [03-chaos-engineering.md](../03-chaos-engineering.md) - Current chaos implementation

docs/od-architecture/01-current-state.md

@@ -0,0 +1,516 @@
+# 01. Current State Analysis
+
+## System Inventory
+
+### Services & Tools
+
+Morpheus currently simulates 4 main enterprise services with approximately **162 tools/APIs**:
+
+| Service | Tool Count | Purpose |
+|---------|-----------|---------|
+| **WMS** (Warehouse Management) | 64 | Inventory, receiving, picking, packing, putaway, cycle counting |
+| **ERP** (Enterprise Resource Planning) | 34 | Orders, products, customers, pricing, purchase orders |
+| **TMS** (Transportation Management) | 33 | Shipments, carriers, routes, tracking |
+| **EDI** (Electronic Data Interchange) | 15 | Document generation (850, 810, 856), parsing, acknowledgments |
+| **Logs** | 5 | Log querying and analysis |
+| **OD Management** | 4 | OD execution and status |
+| **World/Registry** | 7 | World management, service registration |
+
+**Service Registration**: `/packages/controlmart/src/routes/registry.route.ts`
+- Routes mounted by domain: `/:worldId/wms`, `/:worldId/tms`, `/:worldId/edi`
+- Services exposed as REST endpoints (not pure MCP servers yet)
+
+### Example Service Tools
+
+**WMS Sample Tools:**
+```
+- inventory/get-all
+- inventory/get-by-id
+- inventory/update-quantity
+- receiving/create-appointment
+- receiving/process-receipt
+- picking/create-wave
+- picking/assign-picker
+- putaway/create-task
+- cycle-count/initiate
+```
+
+**ERP Sample Tools:**
+```
+- companies/create-company
+- companies/get-by-id
+- companies/get-mpc-company
+- companies/bulk-upsert
+- products/create-product  
+- products/get-by-sku
+- products/get-random
+- products/bulk-upsert
+- orders/create-order
+- orders/get-by-po-number
+- orders/update-status
+- orders/delete-order
+- invoices/create-invoice
+- invoices/get-by-number
+- invoices/update-status
+- shipments/create-shipment
+- shipments/update-tracking
+- shipments/add-event
+- shipments/add-document
+- payments/create-payment
+- payments/apply-allocations
+- payments/update-status
+```
+
+**TMS Sample Tools:**
+```
+- shipments/create
+- shipments/track
+- carriers/assign
+- routes/optimize
+- deliveries/schedule
+```
+
+## Current OD Patterns
+
+### Existing Operational Descriptors
+
+ODs are currently defined programmatically using builder patterns. Here are representative examples:
+
+#### 1. Inbound Receiving Workflow
+**Location**: `/packages/controlmart/src/examples/simple-wms-od.ts`
+
+**Purpose**: Complete inbound receiving process from shipment to putaway
+
+**Flow**:
+```
+TMS: Shipment Tender
+  ↓
+TMS: In-Transit Tracking
+  ↓
+WMS: Dock Appointment
+  ↓
+WMS: Receiving
+  ↓
+WMS: Putaway
+```
+
+**Characteristics**:
+- Multi-service orchestration (TMS → WMS)
+- Sequential steps with dependencies
+- Data flows between services
+- ~5-7 steps total
+
+#### 2. Purchase Order EDI Processing
+**Location**: `/packages/controlmart/src/utils/edi/od-builders-refactored.edi.util.ts`
+
+**Purpose**: Process EDI 850 purchase order documents
+
+**Flow**:
+```
+Generate PO Data
+  ↓
+Generate EDI 850 Document
+  ↓
+Send EDI Acknowledgment (997)
+  ↓
+Generate Invoice (EDI 810)
+```
+
+**Characteristics**:
+- Data transformation heavy
+- Multi-format handling (JSON → EDI)
+- Document validation
+- ~4-6 steps
+
+#### 3. Generic WMS Workflows
+**Location**: `/packages/controlmart/src/utils/wms/od-builder.wms.util.ts`
+
+**Purpose**: Template-based WMS operations
+
+**Workflow Types**:
+- `inbound`: Receiving and putaway
+- `outbound`: Picking and shipping
+- `cycle_count`: Inventory auditing
+- `replenishment`: Stock transfer
+
+**Characteristics**:
+- Builder pattern with fluent API
+- Configurable chaos injection
+- Service-specific (WMS only)
+
+#### 4. Business Rules Triggered OD
+**Location**: `/packages/controlmart/src/business-rules/actions/trigger-od.action.ts`
+
+**Purpose**: Execute OD when business rule fires
+
+**Example**: Auto-allocate inventory when new order created
+
+**Characteristics**:
+- Event-driven
+- Connects business rules → OD execution
+- Async execution
+
+### OD Structure & Components
+
+**Core Files**:
+- `/packages/controlmart/src/operational-descriptor/executor.od.ts` - Main executor
+- `/packages/controlmart/src/operational-descriptor/run-step.od.ts` - Step execution logic
+- `/packages/controlmart/src/operational-descriptor/generic-builder.od.ts` - Builder pattern
+- `/packages/controlmart/src/operational-descriptor/schema.od.ts` - JSON schema validation
+- `/packages/controlmart/src/operational-descriptor/chaos-engine.od.ts` - Chaos injection
+
+**Step Types**:
+1. **MCP Step**: Call service tool (most common)
+2. **Map Step**: Parallel iteration over arrays
+3. **Script Step**: Execute JavaScript code
+4. **Noop Step**: No-op placeholder
+
+**OD Properties**:
+```typescript
+{
+  id: string,
+  name: string,
+  version: string,
+  description?: string,
+
+  // Global chaos config
+  chaos?: ChaosPolicy,
+
+  // Workflow steps
+  steps: Step[],
+
+  // Success criteria
+  assertions?: Assertion[],
+
+  // Metadata
+  tags?: string[],
+  metadata?: Record<string, any>
+}
+```
+
+**Step Properties**:
+```typescript
+{
+  id: string,
+  type: "mcp" | "map" | "script" | "noop",
+
+  // For MCP steps
+  service?: string,
+  tool?: string,
+  input?: InputBinding,
+  output?: OutputBinding,
+
+  // Resilience
+  retry?: RetryPolicy,
+  chaos?: ChaosPolicy,  // Step-level override
+
+  // Conditional execution
+  condition?: string,
+
+  // Validation
+  assertions?: Assertion[]
+}
+```
+
+## Current Organization Patterns
+
+### 1. By Service (Primary)
+
+ODs and tools are primarily organized by which service they interact with:
+
+```
+/packages/controlmart/src/
+  /routes/
+    wms.route.ts        # All WMS endpoints
+    erp.routes.ts       # All ERP endpoints
+    tms.route.ts        # All TMS endpoints
+    edi.route.ts        # All EDI endpoints
+  /utils/
+    /wms/
+      service-tools.wms.util.ts
+      od-builder.wms.util.ts
+    /edi/
+      service-tools.edi.util.ts
+      od-builders.edi.util.ts
+      od-builders-refactored.edi.util.ts
+    /tms/
+      service-tools.tms.util.ts
+```
+
+**Pros**:
+- Clear ownership
+- Easy to find service-specific logic
+- Modular structure
+
+**Cons**:
+- Cross-service workflows scattered
+- No semantic grouping
+- Hard to discover "what can I do?"
+
+### 2. By Workflow Type (Secondary)
+
+Some OD builders organize by workflow category:
+
+**WmsODBuilderFactory** workflows:
+- `inbound`: Receiving operations
+- `outbound`: Fulfillment operations
+- `cycle_count`: Audit operations
+- `replenishment`: Transfer operations
+
+**GenericODBuilderFactory** services:
+- `edi`: EDI document processing
+- `erp`: Order management
+- `wms`: Warehouse operations
+- `tms`: Transportation operations
+- `multi-service`: Cross-service workflows
+
+**Pros**:
+- Some semantic meaning
+- Groups related operations
+
+**Cons**:
+- Limited vocabulary
+- Inconsistent across services
+- Not extensible
+
+### 3. By Business Domain (Emerging)
+
+Business rules show domain-based organization:
+
+**Domains**: `WMS`, `ERP`, `TMS`, `EDI`
+
+**Target Collections**:
+- WMS: `Inventory`, `Order`, `Receiving`, `Picking`
+- ERP: `Order`, `Product`, `Customer`, `PurchaseOrder`
+- TMS: `Shipment`, `Carrier`, `Route`
+
+**Pros**:
+- Aligns with business concepts
+- Clear data ownership
+
+**Cons**:
+- Only used in business rules
+- Not extended to ODs
+- No cross-domain taxonomy
+
+## Critical Gaps
+
+### 1. No Persona Model
+
+**Current State**:
+- No formal persona or role system
+- Some role attributes scattered in models:
+  - `personality` field in customer/employee types
+  - `role` field in WMS labor user model
+  - Hardcoded "Skyfall Automation Bot" reference
+
+**Missing**:
+- Persona definitions (Store Manager, Warehouse Worker, etc.)
+- Capability matrix (who can do what)
+- Access control model
+- Persona-based OD filtering
+
+**Impact**:
+- Can't answer: "What can a store manager do?"
+- No way to configure worlds by persona
+- Unclear authorization model
+
+### 2. No OD Registry/Catalog
+
+**Current State**:
+- ODs scattered across builder files
+- No central inventory
+- Must read code to discover ODs
+- No metadata or discoverability
+
+**Missing**:
+- Centralized OD registry
+- Searchable catalog
+- Metadata (tags, description, inputs, outputs)
+- Version management
+
+**Impact**:
+- Can't answer: "What ODs exist?"
+- Researchers must know code structure
+- No programmatic discovery
+- Hard to share/reuse ODs
+
+### 3. No Capability Mapping
+
+**Current State**:
+- Tools exist but not semantically organized
+- ODs exist but not categorized by function
+- No mapping of tool → capability → persona
+
+**Missing**:
+- Capability taxonomy
+- Tool-to-capability mapping
+- Capability-to-persona mapping
+- Dependency analysis
+
+**Impact**:
+- Can't answer: "What capabilities exist?"
+- Can't suggest ODs based on available tools
+- No validation of OD feasibility
+- Manual OD creation only
+
+### 4. No Semantic Organization
+
+**Current State**:
+- Organization by service/workflow type only
+- No domain taxonomy (procurement, fulfillment, etc.)
+- No complexity classification
+- No tags or metadata
+
+**Missing**:
+- Multi-dimensional taxonomy
+- Tag system
+- Filtering/search capabilities
+- Hierarchical organization
+
+**Impact**:
+- Hard to browse/discover
+- No researcher-friendly navigation
+- Can't filter by domain, complexity, etc.
+- Overwhelming for newcomers
+
+### 5. Chaos Configuration Scattered
+
+**Current State**:
+- Hardcoded probabilities in 14+ files
+- Different values for similar workflows
+- No central configuration
+- No master kill-switch
+
+**Specific Issues**:
+- EDI builder: `chaosProbability: 0.1`
+- ERP builder: `chaosProbability: 0.05`
+- EDI 850 step: `probability: 0.0`
+- Refactored EDI 850: `probability: 0.2`
+- Chaos demo: `probability: 0.8` with 7 scenarios
+
+**Missing**:
+- Centralized chaos presets
+- Environment-based configuration
+- Global master switch
+- Reusable scenario library
+
+**Impact**:
+- Chaos management unmanageable (original problem!)
+- Inconsistent behavior
+- Hard to reproduce experiments
+- Must edit code to change chaos
+
+### 6. No World Configuration System
+
+**Current State**:
+- Worlds have all services/tools available
+- No way to limit scope
+- No sampling mechanism
+- All-or-nothing approach
+
+**Missing**:
+- Capability filtering
+- OD sampling strategies
+- Domain-specific worlds
+- Complexity-based filtering
+
+**Impact**:
+- Can't create specialized worlds (warehouse-only, retail-only)
+- Can't simplify for experiments
+- No way to control scope
+- Overwhelming for simple tests
+
+### 7. No Experiment Tracking
+
+**Current State**:
+- OD execution results returned via API
+- No persistent run history
+- Manual metrics tracking in demo scripts
+- No configuration snapshots
+
+**Missing**:
+- Run history database
+- Configuration versioning
+- Result comparison tools
+- Reproducibility support
+
+**Impact**:
+- Can't compare experiments
+- Hard to reproduce issues
+- No learning from past runs
+- Manual data collection required
+
+## Technology Stack
+
+**Language**: TypeScript/Node.js
+
+**Framework**: Express.js
+
+**Database**: MongoDB (Mongoose ODM)
+
+**Validation**: JSON Schema, Zod (partial), JMESPath, JSONata, CEL
+
+**Logging**: Pino (structured logging)
+
+**Architecture**: Monorepo (packages/controlmart)
+
+## Key Codebase Locations
+
+### Type Definitions
+- `/packages/controlmart/src/types/od.type.ts` - OD types, chaos types, step types
+- `/packages/controlmart/src/types/service-tools.type.ts` - Service tool definitions
+
+### Core OD System
+- `/packages/controlmart/src/operational-descriptor/executor.od.ts` - Main executor
+- `/packages/controlmart/src/operational-descriptor/run-step.od.ts` - Step runner
+- `/packages/controlmart/src/operational-descriptor/chaos-engine.od.ts` - Chaos injection
+- `/packages/controlmart/src/operational-descriptor/generic-builder.od.ts` - Builder API
+- `/packages/controlmart/src/operational-descriptor/schema.od.ts` - Schema validation
+
+### Service Implementations
+- `/packages/controlmart/src/routes/wms.route.ts` - WMS REST API
+- `/packages/controlmart/src/routes/erp.routes.ts` - ERP REST API
+- `/packages/controlmart/src/routes/tms.route.ts` - TMS REST API
+- `/packages/controlmart/src/routes/edi.route.ts` - EDI REST API
+
+### Service Tools
+- `/packages/controlmart/src/utils/wms/service-tools.wms.util.ts` - WMS operations
+- `/packages/controlmart/src/utils/edi/service-tools.edi.util.ts` - EDI operations
+- `/packages/controlmart/src/utils/tms/service-tools.tms.util.ts` - TMS operations
+
+### OD Builders
+- `/packages/controlmart/src/utils/wms/od-builder.wms.util.ts` - WMS OD builder
+- `/packages/controlmart/src/utils/edi/od-builders.edi.util.ts` - EDI OD builders
+- `/packages/controlmart/src/utils/edi/od-builders-refactored.edi.util.ts` - Refactored EDI builders
+
+### Business Rules
+- `/packages/controlmart/src/business-rules/rule-engine.ts` - Rule execution engine
+- `/packages/controlmart/src/business-rules/rules/wms-rules.ts` - WMS-specific rules
+- `/packages/controlmart/src/business-rules/actions/trigger-od.action.ts` - OD triggering
+
+### Examples & Tests
+- `/packages/controlmart/src/examples/simple-wms-od.ts` - Simple WMS example
+- `/packages/controlmart/src/examples/generic-builder-examples.ts` - Generic builder examples
+- `/packages/controlmart/src/edi-demos/chaos-edi-demo.ts` - Chaos demo
+- `/packages/controlmart/tests/generic-builder.test.ts` - Builder tests
+- `/packages/controlmart/tests/chaos.od.test.ts` - Chaos tests
+
+## Summary
+
+**Strengths**:
+- Robust OD execution engine
+- Sophisticated chaos injection framework
+- Multiple services with realistic operations
+- Business rules integration
+- Comprehensive logging
+
+**Weaknesses**:
+- No persona model or capability mapping
+- ODs scattered with no central registry
+- No semantic organization or taxonomy
+- Chaos configuration unmanageable
+- No world configuration/sampling
+- No experiment tracking
+
+**Next Steps**: Define conceptual model to address these gaps (see [02-conceptual-model.md](./02-conceptual-model.md))

docs/od-architecture/02-conceptual-model.md

@@ -0,0 +1,553 @@
+# 02. Conceptual Model
+
+## Overview
+
+This document proposes a conceptual model for organizing Operational Descriptors (ODs) around **capabilities** and **personas**, rather than just services and workflows.
+
+## Proposed Architecture Layers
+
+```
+┌─────────────────────────────────────────┐
+│         PERSONA                         │  Who performs actions
+│  (Store Manager, Warehouse Worker)      │
+└──────────────────┬──────────────────────┘
+                   │ has access to
+                   ↓
+┌─────────────────────────────────────────┐
+│         CAPABILITY                      │  What can be done
+│  (Order Fulfillment, Inventory Mgmt)    │
+└──────────────────┬──────────────────────┘
+                   │ implemented by
+                   ↓
+┌─────────────────────────────────────────┐
+│  OPERATIONAL DESCRIPTOR (OD)            │  How it's done
+│  (Workflow definition)                  │
+└──────────────────┬──────────────────────┘
+                   │ composed of
+                   ↓
+┌─────────────────────────────────────────┐
+│         TOOL / API                      │  Atomic operations
+│  (getOrder, updateInventory)            │
+└──────────────────┬──────────────────────┘
+                   │ exposed by
+                   ↓
+┌─────────────────────────────────────────┐
+│         SERVICE                         │  System boundaries
+│  (ERP, WMS, TMS, EDI)                   │
+└─────────────────────────────────────────┘
+```
+
+## Layer Definitions
+
+### 1. Service Layer
+
+**Definition**: A simulated enterprise system that provides tools/APIs.
+
+**Examples**:
+- ERP (Enterprise Resource Planning)
+- WMS (Warehouse Management System)
+- TMS (Transportation Management System)
+- EDI (Electronic Data Interchange)
+
+**Responsibilities**:
+- Data storage (MongoDB collections)
+- Business logic enforcement
+- API exposure
+- State management
+
+**Current Implementation**: ✅ Well-defined
+- Each service has its own routes, models, and utilities
+- ~162 tools across 4 main services
+
+### 2. Tool Layer
+
+**Definition**: An atomic API operation that reads or modifies data in a single service.
+
+**Examples**:
+- WMS: `inventory/update-quantity`
+- ERP: `orders/create`
+- TMS: `shipments/track`
+- EDI: `generate-850-document`
+
+**Characteristics**:
+- Single responsibility
+- Service-scoped
+- Stateless operation
+- Input/output contract
+
+**Current Implementation**: ✅ Well-defined
+- Exposed as REST endpoints
+- Clear input/output schemas
+- Comprehensive coverage
+
+### 3. Operational Descriptor (OD) Layer
+
+**Definition**: A declarative workflow that orchestrates multiple tools to accomplish an end-to-end business process.
+
+**Examples**:
+- "Inbound Receiving Workflow" (TMS shipment → WMS receiving → WMS putaway)
+- "Order Fulfillment" (ERP order → WMS picking → WMS packing → TMS shipping)
+- "EDI 850 Processing" (Generate PO → Create EDI doc → Send ACK → Create invoice)
+
+**Characteristics**:
+- Multi-tool orchestration
+- Can span multiple services
+- Contains steps, assertions, retry logic, chaos config
+- Declarative (can be serialized to JSON/YAML)
+
+**Current Implementation**: ⚠️ Partially defined
+- Strong execution engine
+- Builder patterns for construction
+- **Missing**: Central registry, versioning, metadata
+
+### 4. Capability Layer
+
+**Definition**: A semantic business function or process that has meaning to domain experts and end users.
+
+**Examples**:
+- "Order Fulfillment"
+- "Inventory Management"
+- "Shipment Tracking"
+- "Purchase Order Processing"
+- "Cycle Counting"
+
+**Characteristics**:
+- Business-oriented naming
+- Domain-specific
+- May have multiple implementations (simple vs complex)
+- Discoverable and browsable
+
+**Relationship to ODs**:
+- **Option A (1:1)**: Each capability has exactly one canonical OD
+- **Option B (1:N)**: One capability can have multiple OD variants
+  - Example: "Order Fulfillment" could have:
+    - `order-fulfillment-standard` (5 steps, 2 services)
+    - `order-fulfillment-express` (3 steps, aggressive SLAs)
+    - `order-fulfillment-with-validation` (8 steps, extensive checks)
+- **Option C (N:M)**: Capabilities can share ODs or be composed
+
+**Current Implementation**: ❌ Not defined
+- Capabilities are implicit in OD names
+- No formal capability model
+- No metadata or taxonomy
+
+### 5. Persona Layer
+
+**Definition**: A role or actor in the system that has access to specific capabilities.
+
+**Examples**:
+- **Store Manager**: Order management, inventory oversight, staff coordination
+- **Warehouse Worker**: Receiving, picking, packing, putaway
+- **Logistics Coordinator**: Shipment planning, carrier management, route optimization
+- **Purchasing Agent**: Purchase order creation, supplier management
+- **Inventory Auditor**: Cycle counting, variance resolution
+
+**Characteristics**:
+- Represents real-world roles
+- Has capability permissions
+- Can be used for access control
+- Enables persona-based world configuration
+
+**Relationship to Capabilities**:
+- Personas have many capabilities
+- Capabilities can be shared across personas
+- Permission matrix: `Persona × Capability → Boolean`
+
+**Current Implementation**: ❌ Not defined
+- No persona model
+- Some role attributes scattered in data models
+- No permission system
+
+## Key Relationships
+
+### Persona ↔ Capability
+
+**Relationship Type**: Many-to-Many
+
+**Examples**:
+```
+Store Manager has:
+  - Order Fulfillment ✓
+  - Inventory Management ✓
+  - Staff Coordination ✓
+  - Warehouse Receiving ✗
+
+Warehouse Worker has:
+  - Warehouse Receiving ✓
+  - Picking & Packing ✓
+  - Putaway ✓
+  - Order Fulfillment ✗ (limited scope)
+```
+
+**Implementation Options**:
+- **Static**: Hardcoded in configuration files
+- **Dynamic**: Stored in database, configurable via API
+- **Hybrid**: Default mappings with override capability
+
+### Capability ↔ OD
+
+**Relationship Type**: TBD (see options above)
+
+**Option A: 1:1 Mapping**
+```
+Capability "Order Fulfillment" → OD "order-fulfillment-v1"
+```
+
+**Pros**:
+- Simple
+- Clear ownership
+- Easy to reason about
+
+**Cons**:
+- Inflexible
+- Can't have variants
+- Complexity hidden inside OD
+
+**Option B: 1:N Mapping (Variants)**
+```
+Capability "Order Fulfillment" → [
+  OD "order-fulfillment-standard",
+  OD "order-fulfillment-express",
+  OD "order-fulfillment-international"
+]
+```
+
+**Pros**:
+- Flexible
+- Can optimize for different scenarios
+- Clear trade-offs between variants
+
+**Cons**:
+- More complex
+- Need selection logic
+- Versioning challenges
+
+**Option C: N:M Mapping (Composition)**
+```
+Capability "Order Fulfillment" → OD "order-fulfillment"
+Capability "Inventory Check" → OD "inventory-check"
+
+OD "order-fulfillment" uses OD "inventory-check" as sub-workflow
+```
+
+**Pros**:
+- Maximum reusability
+- Modular design
+- Hierarchical composition
+
+**Cons**:
+- Most complex
+- Circular dependency risk
+- Harder to reason about
+
+### OD ↔ Tool
+
+**Relationship Type**: Many-to-Many
+
+**Characteristics**:
+- ODs reference tools in steps
+- Same tool can be used in multiple ODs
+- Tools can appear multiple times in same OD
+
+**Current Implementation**: ✅ Well-defined
+```typescript
+{
+  step: {
+    type: "mcp",
+    service: "wms",
+    tool: "inventory/update-quantity",
+    input: { ... }
+  }
+}
+```
+
+### Tool ↔ Service
+
+**Relationship Type**: Many-to-One
+
+**Characteristics**:
+- Each tool belongs to exactly one service
+- Services expose many tools
+- Clear boundary
+
+**Current Implementation**: ✅ Well-defined
+
+## Data Entities & Dependencies
+
+### Data Flow
+
+Tools produce and consume **data entities**:
+
+**Common Entities**:
+- Order
+- Product
+- Inventory
+- Shipment
+- Customer
+- Location
+- Document (EDI)
+
+**Dependencies**:
+```
+Tool "orders/create" produces: Order
+Tool "inventory/allocate" requires: Order, Product
+Tool "picking/create-wave" requires: Order, Inventory
+Tool "shipments/create" requires: Order, Location
+```
+
+**Use Case**: Knowledge graph can validate OD feasibility
+- Can we execute this OD with available tools?
+- What data is needed to start this workflow?
+- What data will be produced?
+
+## Metadata & Attributes
+
+### Capability Metadata
+
+**Proposed Schema**:
+```typescript
+{
+  id: string,                    // "order-fulfillment"
+  name: string,                  // "Order Fulfillment"
+  description: string,           // "Process customer orders..."
+  domain: string,                // "fulfillment"
+  complexity: "simple" | "medium" | "complex",
+  tags: string[],                // ["retail", "b2c", "warehouse"]
+  personas: string[],            // ["store-manager", "fulfillment-specialist"]
+  ods: string[],                 // ["order-fulfillment-v1", ...]
+  requiredServices: string[],    // ["erp", "wms", "tms"]
+  estimatedDuration: number,     // milliseconds
+  version: string                // "1.0.0"
+}
+```
+
+### OD Metadata
+
+**Current Schema** (from od.type.ts):
+```typescript
+{
+  id: string,
+  name: string,
+  version: string,
+  description?: string,
+  steps: Step[],
+  chaos?: ChaosPolicy,
+  assertions?: Assertion[],
+  metadata?: Record<string, any>
+}
+```
+
+**Proposed Additions**:
+```typescript
+{
+  // ... existing fields ...
+
+  // New metadata
+  capability?: string,           // "order-fulfillment"
+  domain?: string,               // "fulfillment"
+  complexity?: "simple" | "medium" | "complex",
+  tags?: string[],               // ["retail", "standard-shipping"]
+  requiredServices?: string[],   // ["erp", "wms"]
+  personas?: string[],           // ["store-manager"]
+  estimatedDuration?: number,    // milliseconds
+  author?: string,               // "system" or researcher name
+  createdAt?: Date,
+  updatedAt?: Date
+}
+```
+
+### Persona Metadata
+
+**Proposed Schema**:
+```typescript
+{
+  id: string,                    // "store-manager"
+  name: string,                  // "Store Manager"
+  description: string,           // "Manages store operations..."
+  department: string,            // "retail"
+  capabilities: string[],        // ["order-fulfillment", ...]
+  accessLevel: "basic" | "advanced" | "admin",
+  tags: string[]                 // ["management", "retail"]
+}
+```
+
+## Design Questions
+
+### 1. Capability Definition
+
+**Question**: What exactly is a capability?
+
+**Options**:
+- **A. Business Function**: High-level processes ("Order Management")
+- **B. User Story**: Goal-oriented tasks ("Fulfill a customer order")
+- **C. Domain Process**: Technical workflows ("Inbound Receiving Flow")
+
+**Trade-offs**:
+- A: Too broad, may contain multiple workflows
+- B: Very specific, may explode in count
+- C: Technical, less accessible to non-engineers
+
+**Recommendation Needed**: Which resonates with your target users (AI researchers)?
+
+### 2. Capability ↔ OD Mapping
+
+**Question**: Can one capability have multiple OD implementations?
+
+**Scenarios**:
+- Simple vs complex variants
+- Different optimization targets (speed vs accuracy)
+- Evolution over time (v1, v2, v3)
+
+**Options**:
+- **A. 1:1**: One capability = one canonical OD
+- **B. 1:N**: One capability = multiple OD variants (with selection logic)
+- **C. N:M**: Capabilities compose and share ODs
+
+**Recommendation Needed**: Which provides the right flexibility vs complexity?
+
+### 3. Persona Granularity
+
+**Question**: How detailed should personas be?
+
+**Options**:
+- **A. Broad** (5-10 personas): Manager, Worker, Coordinator, Analyst
+- **B. Detailed** (20-50 personas): Store Manager, DC Manager, Warehouse Manager, etc.
+- **C. Functional** (50+ personas): Receiving Clerk, Picking Specialist, QA Inspector
+
+**Trade-offs**:
+- A: Simple, easy to configure, coarse-grained permissions
+- B: Balance of specificity and manageability
+- C: Highly realistic, but complex to manage
+
+**Recommendation Needed**: What level of detail is useful for research?
+
+### 4. Static vs Dynamic Configuration
+
+**Question**: Should persona ↔ capability mappings be configurable?
+
+**Options**:
+- **A. Static**: Hardcoded in config files, version controlled
+- **B. Dynamic**: Stored in database, editable via API
+- **C. Hybrid**: Defaults in config, overridable per world
+
+**Use Cases**:
+- Researcher wants custom persona for experiment
+- Need to restrict capabilities for specific test
+- Want to evolve personas without code changes
+
+**Recommendation Needed**: How much runtime configurability is needed?
+
+### 5. Hierarchy & Composition
+
+**Question**: Should capabilities have hierarchies or compositions?
+
+**Examples**:
+```
+Parent: "Order Management"
+  Children:
+    - "Create Order"
+    - "Fulfill Order"
+    - "Cancel Order"
+    - "Track Order"
+```
+
+or
+
+```
+Capability: "Fulfill Order"
+  Requires:
+    - "Check Inventory" (sub-capability)
+    - "Create Shipment" (sub-capability)
+```
+
+**Trade-offs**:
+- Hierarchies: Better organization, but more complex
+- Flat: Simpler, but harder to browse
+- Composition: Enables reuse, but adds dependencies
+
+**Recommendation Needed**: Is flat structure sufficient, or do we need hierarchies?
+
+## Example: Order Fulfillment
+
+Let's walk through a concrete example:
+
+### Personas
+```
+Store Manager:
+  - Can execute order fulfillment
+  - Can view inventory
+  - Can manage staff
+
+Warehouse Worker:
+  - Can pick orders
+  - Can pack shipments
+  - Cannot create orders
+```
+
+### Capability
+```
+ID: order-fulfillment
+Name: Order Fulfillment
+Description: Process a customer order from creation to shipment
+Domain: fulfillment
+Complexity: medium
+Tags: [retail, standard-shipping]
+Personas: [store-manager]
+```
+
+### ODs (Variant Approach)
+```
+OD: order-fulfillment-standard
+  Steps:
+    1. ERP: Create order
+    2. WMS: Allocate inventory
+    3. WMS: Create pick wave
+    4. WMS: Assign picker
+    5. WMS: Create shipment
+    6. TMS: Assign carrier
+    7. TMS: Generate shipping label
+
+OD: order-fulfillment-express
+  Steps:
+    1. ERP: Create order (skip validation)
+    2. WMS: Auto-allocate
+    3. WMS: Create priority shipment
+    4. TMS: Assign premium carrier
+```
+
+### Tools Used
+```
+- erp/companies/create-company
+- erp/orders/create-order
+- erp/invoices/create-invoice  
+- erp/shipments/create-shipment
+- erp/payments/create-payment
+- wms/inventory/allocate
+- wms/picking/create-wave
+- wms/picking/assign-picker
+- wms/shipments/create
+- tms/carriers/assign
+- tms/labels/generate
+```
+
+### Services Required
+```
+- ERP
+- WMS
+- TMS
+```
+
+## Next Steps
+
+1. **Answer design questions** (see above)
+2. **Define capability taxonomy** (see [04-taxonomy-organization.md](./04-taxonomy-organization.md))
+3. **Design knowledge graph** (see [03-knowledge-graph.md](./03-knowledge-graph.md))
+4. **Create persona catalog** (define 10-20 personas)
+5. **Map existing ODs** to capabilities
+
+## Related Documents
+
+- [01. Current State](./01-current-state.md) - What exists today
+- [03. Knowledge Graph](./03-knowledge-graph.md) - Relationship modeling
+- [04. Taxonomy & Organization](./04-taxonomy-organization.md) - Categorization strategy
+- [06. Open Questions](./06-open-questions.md) - Unresolved decisions

docs/od-architecture/03-knowledge-graph.md

@@ -0,0 +1,689 @@
+# 03. Knowledge Graph
+
+## Overview
+
+A **knowledge graph** can model relationships between services, tools, data entities, ODs, capabilities, and personas. This enables intelligent features like:
+- Auto-discovery of valid OD compositions
+- Validation of OD feasibility
+- Suggestion of capabilities based on available tools
+- Dependency analysis
+
+## Graph Structure
+
+### Node Types
+
+```
+┌─────────────┐
+│   PERSONA   │  Role/actor (e.g., Store Manager)
+└─────────────┘
+       │
+       │ can_perform
+       ↓
+┌─────────────┐
+│ CAPABILITY  │  Business function (e.g., Order Fulfillment)
+└─────────────┘
+       │
+       │ implemented_by
+       ↓
+┌─────────────┐
+│     OD      │  Workflow definition
+└─────────────┘
+       │
+       │ uses
+       ↓
+┌─────────────┐
+│    TOOL     │  API operation (e.g., createOrder)
+└─────────────┘
+       │
+       │ exposed_by
+       ↓
+┌─────────────┐
+│   SERVICE   │  System boundary (e.g., ERP, WMS)
+└─────────────┘
+       │
+       │ manages
+       ↓
+┌─────────────┐
+│   ENTITY    │  Data object (e.g., Order, Product)
+└─────────────┘
+```
+
+### Node Definitions
+
+#### 1. Persona Node
+```typescript
+{
+  type: "persona",
+  id: "store-manager",
+  name: "Store Manager",
+  description: "Manages store operations",
+  department: "retail",
+  accessLevel: "advanced"
+}
+```
+
+#### 2. Capability Node
+```typescript
+{
+  type: "capability",
+  id: "order-fulfillment",
+  name: "Order Fulfillment",
+  description: "Process customer orders end-to-end",
+  domain: "fulfillment",
+  complexity: "medium"
+}
+```
+
+#### 3. OD Node
+```typescript
+{
+  type: "od",
+  id: "order-fulfillment-standard-v1",
+  name: "Standard Order Fulfillment",
+  version: "1.0.0",
+  complexity: "medium",
+  estimatedDuration: 5000  // ms
+}
+```
+
+#### 4. Tool Node
+```typescript
+{
+  type: "tool",
+  id: "wms:inventory:allocate",
+  name: "Allocate Inventory",
+  service: "wms",
+  endpoint: "/inventory/allocate",
+  inputSchema: { ... },
+  outputSchema: { ... }
+}
+```
+
+#### 5. Service Node
+```typescript
+{
+  type: "service",
+  id: "wms",
+  name: "Warehouse Management System",
+  baseUrl: "/:worldId/wms"
+}
+```
+
+#### 6. Entity Node
+```typescript
+{
+  type: "entity",
+  id: "order",
+  name: "Order",
+  collection: "orders",
+  schema: { ... }
+}
+```
+
+### Edge Types
+
+#### Persona → Capability
+```typescript
+{
+  source: "store-manager",
+  target: "order-fulfillment",
+  type: "can_perform",
+  permission: "execute"  // or "read", "write"
+}
+```
+
+#### Capability → OD
+```typescript
+{
+  source: "order-fulfillment",
+  target: "order-fulfillment-standard-v1",
+  type: "implemented_by",
+  variant: "standard"  // or "express", "international"
+}
+```
+
+#### OD → Tool
+```typescript
+{
+  source: "order-fulfillment-standard-v1",
+  target: "wms:inventory:allocate",
+  type: "uses",
+  stepIndex: 2,
+  required: true
+}
+```
+
+#### Tool → Service
+```typescript
+{
+  source: "wms:inventory:allocate",
+  target: "wms",
+  type: "exposed_by"
+}
+```
+
+#### Service → Entity
+```typescript
+{
+  source: "wms",
+  target: "inventory",
+  type: "manages"
+}
+```
+
+#### Tool → Entity (Data Flow)
+
+**Produces**:
+```typescript
+{
+  source: "erp:orders:create",
+  target: "order",
+  type: "produces"
+}
+```
+
+**Requires**:
+```typescript
+{
+  source: "wms:inventory:allocate",
+  target: "order",
+  type: "requires"
+}
+```
+
+**Modifies**:
+```typescript
+{
+  source: "wms:inventory:update-quantity",
+  target: "inventory",
+  type: "modifies"
+}
+```
+
+#### Tool → Tool (Sequencing)
+
+**Prerequisite**:
+```typescript
+{
+  source: "erp:orders:create",
+  target: "wms:inventory:allocate",
+  type: "prerequisite",
+  reason: "Order must exist before allocation"
+}
+```
+
+**Conflicts With**:
+```typescript
+{
+  source: "wms:inventory:allocate",
+  target: "wms:inventory:deallocate",
+  type: "conflicts_with",
+  reason: "Cannot allocate and deallocate simultaneously"
+}
+```
+
+#### Entity → Entity (Data Relationships)
+
+**Contains**:
+```typescript
+{
+  source: "order",
+  target: "order-line",
+  type: "contains",
+  cardinality: "one-to-many"
+}
+```
+
+**References**:
+```typescript
+{
+  source: "order",
+  target: "customer",
+  type: "references",
+  cardinality: "many-to-one"
+}
+```
+
+## Use Cases
+
+### 1. OD Discovery: "What ODs can I create?"
+
+**Scenario**: Given available tools, suggest possible ODs.
+
+**Query**:
+```
+Given tools: [erp:orders:create, wms:inventory:allocate, tms:shipments:create]
+Find: Valid OD sequences
+```
+
+**Graph Traversal**:
+1. Start with tools
+2. Find entities they produce/require
+3. Identify valid tool chains (where outputs match inputs)
+4. Suggest OD templates
+
+**Example Result**:
+```
+Suggested OD: "Simple Order Fulfillment"
+  Steps:
+    1. erp:orders:create (produces: Order)
+    2. wms:inventory:allocate (requires: Order, produces: Allocation)
+    3. tms:shipments:create (requires: Order, Allocation)
+```
+
+### 2. OD Validation: "Is this OD valid?"
+
+**Scenario**: Validate that an OD can actually execute.
+
+**Checks**:
+1. **Tool Availability**: Do all referenced tools exist?
+2. **Service Dependencies**: Are required services available?
+3. **Data Flow**: Does each step have required input data?
+4. **Sequencing**: Are there any conflicting operations?
+
+**Example Validation**:
+```
+OD: "order-fulfillment-v1"
+  Step 1: erp:orders:create ✓
+    - Produces: Order
+  Step 2: wms:inventory:allocate ✓
+    - Requires: Order ✓ (produced by step 1)
+    - Produces: Allocation
+  Step 3: wms:inventory:deallocate ✗
+    - Conflicts with: wms:inventory:allocate (step 2)
+
+Result: INVALID - Conflicting operations
+```
+
+### 3. Capability Suggestion: "What capabilities are possible?"
+
+**Scenario**: Given available services, suggest capabilities.
+
+**Query**:
+```
+Given services: [wms, tms]
+Find: Capabilities that only need these services
+```
+
+**Graph Traversal**:
+1. Find all tools from these services
+2. Find all ODs that only use these tools
+3. Find all capabilities implemented by these ODs
+
+**Example Result**:
+```
+Possible Capabilities:
+  - Inbound Receiving (WMS only)
+  - Warehouse Transfer (WMS only)
+  - Shipment Tracking (TMS only)
+  - Outbound Shipping (WMS + TMS)
+
+Not Possible:
+  - Order Fulfillment (requires ERP)
+  - EDI Processing (requires EDI service)
+```
+
+### 4. Dependency Analysis: "What does this OD need?"
+
+**Scenario**: Understand prerequisites for an OD.
+
+**Query**:
+```
+For OD: "order-fulfillment-standard-v1"
+Find: All dependencies
+```
+
+**Graph Traversal**:
+1. Find all tools used by OD
+2. Find all services hosting those tools
+3. Find all entities required by tools
+4. Find all prerequisite data
+
+**Example Result**:
+```
+OD: "order-fulfillment-standard-v1"
+
+Required Services:
+  - ERP
+  - WMS
+  - TMS
+
+Required Entities (Input):
+  - Customer (must pre-exist)
+  - Product (must pre-exist)
+  - Inventory (must have stock)
+
+Produced Entities (Output):
+  - Order
+  - Allocation
+  - Shipment
+```
+
+### 5. Impact Analysis: "What breaks if I change this?"
+
+**Scenario**: Understand impact of removing/changing a tool or service.
+
+**Query**:
+```
+If we remove tool: "wms:inventory:allocate"
+What is affected?
+```
+
+**Graph Traversal**:
+1. Find all ODs using this tool
+2. Find all capabilities implemented by those ODs
+3. Find all personas with access to those capabilities
+
+**Example Result**:
+```
+Removing "wms:inventory:allocate" affects:
+
+ODs (3):
+  - order-fulfillment-standard-v1 (step 2)
+  - order-fulfillment-express-v1 (step 2)
+  - inventory-reservation-v1 (step 1)
+
+Capabilities (2):
+  - Order Fulfillment
+  - Inventory Reservation
+
+Personas (3):
+  - Store Manager
+  - Fulfillment Specialist
+  - Inventory Manager
+
+Recommendation: High impact - find alternative or create substitute
+```
+
+### 6. Path Finding: "How do I get from A to B?"
+
+**Scenario**: Find tool sequences to transform one entity into another.
+
+**Query**:
+```
+Start: Customer (exists)
+Goal: Shipment (with tracking number)
+Find: Shortest tool path
+```
+
+**Graph Traversal**:
+1. Start with Customer entity
+2. Find tools that require Customer (produces Order)
+3. Continue until Shipment is produced
+4. Return shortest path
+
+**Example Result**:
+```
+Path:
+  Customer → [erp:orders:create] → Order
+  Order → [wms:inventory:allocate] → Allocation
+  Order + Allocation → [wms:shipments:create] → Shipment
+  Shipment → [tms:carriers:assign] → Shipment (with carrier)
+  Shipment → [tms:labels:generate] → Shipment (with tracking)
+
+Suggested OD: 5 steps, 3 services (ERP, WMS, TMS)
+```
+
+## Implementation Approaches
+
+### Option A: Static Analysis (Build Time)
+
+**How**: Analyze code/config files to build graph.
+
+**Process**:
+1. Parse TypeScript types and service tool definitions
+2. Extract input/output schemas from tools
+3. Build graph from static information
+4. Generate graph file (JSON/GraphML)
+
+**Pros**:
+- No runtime overhead
+- Version controlled
+- Can be part of CI/CD
+
+**Cons**:
+- Doesn't capture runtime behavior
+- Misses dynamic relationships
+- Requires manual annotation for data flow
+
+**Tools**:
+- TypeScript compiler API
+- JSON schema analysis
+- Custom AST traversal
+
+### Option B: Dynamic Learning (Runtime)
+
+**How**: Learn relationships from actual OD executions.
+
+**Process**:
+1. Start with basic graph (services, tools)
+2. Monitor OD executions
+3. Record which tools are called together
+4. Infer data flow from step outputs → inputs
+5. Update graph weights based on frequency
+
+**Pros**:
+- Discovers actual usage patterns
+- Adapts over time
+- Captures implicit dependencies
+
+**Cons**:
+- Requires execution history
+- Slow to bootstrap
+- May learn anti-patterns
+
+**Data Sources**:
+- OD execution logs
+- Step input/output traces
+- Success/failure rates
+
+### Option C: Hybrid (Static + Runtime)
+
+**How**: Start with static analysis, refine with runtime data.
+
+**Process**:
+1. Build initial graph from code (static)
+2. Annotate tools with produces/requires/modifies (manual or inferred)
+3. Validate and refine during execution (runtime)
+4. Update edge weights based on usage
+
+**Pros**:
+- Best of both worlds
+- Quick bootstrap
+- Improves over time
+
+**Cons**:
+- More complex
+- Need to reconcile conflicts
+- Schema evolution challenges
+
+**Recommendation**: Start with static, add runtime as phase 2.
+
+## Graph Technology Options
+
+### Option 1: In-Memory Graph (JavaScript)
+
+**Libraries**:
+- `graphlib` (lightweight, simple)
+- `cytoscape.js` (visualization support)
+- Custom adjacency list
+
+**Pros**:
+- Simple
+- Fast for small graphs
+- No external dependencies
+
+**Cons**:
+- Not persistent
+- Limited query capabilities
+- Rebuild on every startup
+
+### Option 2: Graph Database (Neo4j, ArangoDB)
+
+**Pros**:
+- Purpose-built for graphs
+- Powerful query language (Cypher, AQL)
+- Scales to large graphs
+- Persistent
+
+**Cons**:
+- Additional infrastructure
+- Complexity
+- Overkill for initial version
+
+### Option 3: MongoDB (Document + Relationships)
+
+**Pros**:
+- Already using MongoDB
+- Can store nodes and edges as documents
+- Familiar query language
+- Good for hybrid approach
+
+**Cons**:
+- Not optimized for graph traversal
+- Complex queries for deep traversals
+- Manual relationship management
+
+**Recommendation**: Start with in-memory (Option 1), migrate to MongoDB (Option 3) when persistence needed.
+
+## Practical Example: Order Fulfillment Graph
+
+### Nodes
+```javascript
+// Persona
+{ type: "persona", id: "store-manager", name: "Store Manager" }
+
+// Capability
+{ type: "capability", id: "order-fulfillment", name: "Order Fulfillment" }
+
+// OD
+{ type: "od", id: "order-fulfillment-v1", name: "Standard Order Fulfillment" }
+
+// Tools
+{ type: "tool", id: "erp:orders:create", service: "erp" }
+{ type: "tool", id: "wms:inventory:allocate", service: "wms" }
+{ type: "tool", id: "tms:shipments:create", service: "tms" }
+
+// Services
+{ type: "service", id: "erp", name: "ERP" }
+{ type: "service", id: "wms", name: "WMS" }
+{ type: "service", id: "tms", name: "TMS" }
+
+// Entities
+{ type: "entity", id: "order", collection: "orders" }
+{ type: "entity", id: "inventory", collection: "inventory" }
+{ type: "entity", id: "shipment", collection: "shipments" }
+```
+
+### Edges
+```javascript
+// Persona → Capability
+{ from: "store-manager", to: "order-fulfillment", type: "can_perform" }
+
+// Capability → OD
+{ from: "order-fulfillment", to: "order-fulfillment-v1", type: "implemented_by" }
+
+// OD → Tools
+{ from: "order-fulfillment-v1", to: "erp:orders:create", type: "uses", step: 1 }
+{ from: "order-fulfillment-v1", to: "wms:inventory:allocate", type: "uses", step: 2 }
+{ from: "order-fulfillment-v1", to: "tms:shipments:create", type: "uses", step: 3 }
+
+// Tools → Services
+{ from: "erp:orders:create", to: "erp", type: "exposed_by" }
+{ from: "wms:inventory:allocate", to: "wms", type: "exposed_by" }
+{ from: "tms:shipments:create", to: "tms", type: "exposed_by" }
+
+// Tools → Entities (Data Flow)
+{ from: "erp:orders:create", to: "order", type: "produces" }
+{ from: "wms:inventory:allocate", to: "order", type: "requires" }
+{ from: "wms:inventory:allocate", to: "inventory", type: "modifies" }
+{ from: "tms:shipments:create", to: "order", type: "requires" }
+{ from: "tms:shipments:create", to: "shipment", type: "produces" }
+```
+
+### Queries
+
+**Query 1: What can a store manager do?**
+```javascript
+// Traverse: Persona → Capability
+getOutgoingEdges("store-manager", "can_perform")
+// Result: ["order-fulfillment", "inventory-management", ...]
+```
+
+**Query 2: How is order fulfillment implemented?**
+```javascript
+// Traverse: Capability → OD → Tool
+getOutgoingEdges("order-fulfillment", "implemented_by")  // ODs
+  .flatMap(od => getOutgoingEdges(od, "uses"))  // Tools
+// Result: ["erp:orders:create", "wms:inventory:allocate", "tms:shipments:create"]
+```
+
+**Query 3: What entities does order fulfillment require?**
+```javascript
+// Get OD's tools, then find entities they require
+const tools = getOutgoingEdges("order-fulfillment-v1", "uses")
+const requiredEntities = tools
+  .flatMap(tool => getOutgoingEdges(tool, "requires"))
+  .filter(node => node.type === "entity")
+// Result: ["order", "inventory"]
+```
+
+## Open Questions
+
+### 1. Graph Granularity
+
+**Question**: How detailed should the graph be?
+
+**Options**:
+- **Coarse**: Just services, capabilities, personas
+- **Medium**: + tools, entities
+- **Fine**: + tool parameters, entity fields, step-level details
+
+**Trade-off**: Detail vs maintainability
+
+### 2. Data Flow Inference
+
+**Question**: How do we know which entities a tool produces/requires?
+
+**Options**:
+- **Manual Annotation**: Developers specify in code comments or metadata
+- **Schema Analysis**: Infer from input/output TypeScript types
+- **Runtime Learning**: Monitor actual executions
+
+**Recommendation Needed**: Feasibility of each approach?
+
+### 3. Graph Updates
+
+**Question**: When does the graph get updated?
+
+**Options**:
+- **Build Time**: Regenerated on every deployment
+- **Startup**: Built when service starts
+- **Runtime**: Updated as ODs execute
+
+**Recommendation Needed**: What's the update frequency requirement?
+
+### 4. Query Performance
+
+**Question**: Do we need to optimize for specific query patterns?
+
+**Common Queries**:
+- "What can persona X do?" (1-hop traversal)
+- "What ODs use tool Y?" (reverse lookup)
+- "Find path from A to B" (shortest path, can be expensive)
+
+**Recommendation Needed**: Which queries are most critical?
+
+## Next Steps
+
+1. **Choose implementation approach** (static/dynamic/hybrid)
+2. **Select graph technology** (in-memory/Neo4j/MongoDB)
+3. **Define annotation format** for manual metadata
+4. **Build proof-of-concept** for one use case (e.g., OD validation)
+5. **Evaluate query performance** on realistic graph size
+
+## Related Documents
+
+- [02. Conceptual Model](./02-conceptual-model.md) - Defines nodes (Persona, Capability, OD)
+- [04. Taxonomy & Organization](./04-taxonomy-organization.md) - How to categorize nodes
+- [06. Open Questions](./06-open-questions.md) - Unresolved decisions

docs/od-architecture/04-taxonomy-organization.md

@@ -0,0 +1,619 @@
+# 04. Taxonomy & Organization
+
+## Overview
+
+This document proposes taxonomies for organizing capabilities and ODs so that researchers can easily browse, filter, and discover what they need.
+
+## Taxonomy Dimensions
+
+### 1. Domain-Based Organization
+
+Organize by **business domain** or functional area.
+
+#### Proposed Domains
+
+```
+Supply Chain Management
+├── Procurement
+│   ├── Supplier Management
+│   ├── Purchase Order Creation
+│   ├── RFQ Processing
+│   └── Vendor Evaluation
+│
+├── Inventory Management
+│   ├── Stock Control
+│   ├── Cycle Counting
+│   ├── Replenishment
+│   └── Allocation
+│
+├── Fulfillment
+│   ├── Order Processing
+│   ├── Picking & Packing
+│   ├── Wave Management
+│   └── Returns Processing
+│
+├── Warehousing
+│   ├── Inbound Receiving
+│   ├── Putaway
+│   ├── Transfers
+│   └── Labor Management
+│
+├── Transportation
+│   ├── Shipment Planning
+│   ├── Carrier Management
+│   ├── Route Optimization
+│   └── Delivery Tracking
+│
+├── Data Exchange
+│   ├── EDI Document Processing
+│   ├── API Integration
+│   ├── File Import/Export
+│   └── Format Transformation
+│
+└── Analytics & Reporting
+    ├── KPI Dashboards
+    ├── Exception Monitoring
+    ├── Audit Trails
+    └── Performance Analysis
+```
+
+**Pros**:
+- Aligned with business language
+- Easy for domain experts to navigate
+- Clear ownership
+
+**Cons**:
+- Cross-domain capabilities hard to categorize
+- May not match researcher mental models
+- Requires domain knowledge
+
+#### Example Mapping
+```
+Domain: Fulfillment
+  Capabilities:
+    - Order Fulfillment
+    - Express Order Fulfillment
+    - Drop Ship Fulfillment
+    - Pick & Pack
+    - Order Cancellation
+```
+
+### 2. Persona-Based Organization
+
+Organize by **who** performs the capability.
+
+#### Proposed Personas
+
+```
+Management Roles
+├── Store Manager
+│   └── Capabilities: Order oversight, inventory review, staff coordination
+├── Warehouse Manager
+│   └── Capabilities: Resource planning, performance monitoring
+├── Logistics Manager
+│   └── Capabilities: Route planning, carrier negotiation
+└── Operations Director
+    └── Capabilities: Multi-site coordination, strategic planning
+
+Operational Roles
+├── Warehouse Worker
+│   └── Capabilities: Receiving, picking, packing, putaway
+├── Inventory Specialist
+│   └── Capabilities: Cycle counting, adjustments, audits
+├── Shipping Clerk
+│   └── Capabilities: Label generation, manifest creation
+└── Receiving Clerk
+    └── Capabilities: Appointment scheduling, unloading, inspection
+
+Analytical Roles
+├── Demand Planner
+│   └── Capabilities: Forecast analysis, replenishment planning
+├── Business Analyst
+│   └── Capabilities: Report generation, exception analysis
+└── Data Engineer
+    └── Capabilities: Data integration, pipeline management
+
+System Roles
+├── EDI Operator
+│   └── Capabilities: EDI mapping, document transmission
+├── Integration Specialist
+│   └── Capabilities: API configuration, webhook setup
+└── Automation Bot
+    └── Capabilities: Scheduled workflows, event-driven processes
+```
+
+**Pros**:
+- Intuitive for role-based access
+- Clear permission model
+- Enables persona-specific worlds
+
+**Cons**:
+- Capabilities may span multiple personas
+- Persona definitions may vary by organization
+- Maintenance overhead
+
+#### Example Mapping
+```
+Persona: Store Manager
+  Capabilities:
+    - Order Fulfillment
+    - Inventory Management
+    - Staff Scheduling
+    - Exception Handling
+
+  Cannot Access:
+    - Warehouse Physical Operations (worker-level tasks)
+    - System Configuration (admin tasks)
+```
+
+### 3. Complexity-Based Organization
+
+Organize by **complexity** level.
+
+#### Complexity Metrics
+
+**Quantitative Factors**:
+- Number of steps (1-3: simple, 4-7: medium, 8+: complex)
+- Number of services involved (1: simple, 2-3: medium, 4+: complex)
+- Number of decision points (conditionals, branches)
+- Average execution time
+- Error rate / retry frequency
+
+**Qualitative Factors**:
+- Requires domain expertise?
+- Has edge cases?
+- Needs manual intervention?
+- High business impact?
+
+#### Complexity Tiers
+
+```
+SIMPLE (Tier 1)
+├── Definition: 1-3 steps, single service, no branching
+├── Examples:
+│   ├── Check Inventory Level
+│   ├── Create Purchase Order
+│   ├── Update Product Price
+│   └── Generate Report
+└── Use Case: Learning, testing, debugging
+
+MEDIUM (Tier 2)
+├── Definition: 4-7 steps, 2-3 services, some branching
+├── Examples:
+│   ├── Process Customer Order
+│   ├── Receive Shipment
+│   ├── Allocate Inventory
+│   └── Generate EDI 850
+└── Use Case: Standard operations, automation
+
+COMPLEX (Tier 3)
+├── Definition: 8+ steps, multi-service, extensive branching
+├── Examples:
+│   ├── End-to-End Order Fulfillment
+│   ├── Cross-Dock Transfer
+│   ├── Returns Processing with Restocking
+│   └── Multi-Leg Shipment Orchestration
+└── Use Case: Advanced scenarios, research experiments
+```
+
+**Pros**:
+- Easy to assess difficulty
+- Good for progressive learning
+- Helps with sampling strategies
+
+**Cons**:
+- Subjective boundaries
+- May not reflect actual difficulty
+- Changes as system evolves
+
+#### Example Mapping
+```
+Capability: Order Fulfillment
+
+Simple Variant:
+  - Steps: 3 (Create order, allocate inventory, create shipment)
+  - Services: 2 (ERP, WMS)
+  - Estimated Duration: 2 seconds
+
+Medium Variant:
+  - Steps: 7 (Add validation, picking, packing, carrier assignment)
+  - Services: 3 (ERP, WMS, TMS)
+  - Estimated Duration: 5 seconds
+
+Complex Variant:
+  - Steps: 12 (Add fraud check, inventory reservation, multi-location, split shipments)
+  - Services: 4 (ERP, WMS, TMS, External Payment Gateway)
+  - Estimated Duration: 10 seconds
+```
+
+### 4. Service-Based Organization (Current)
+
+Organize by **which service(s)** are involved.
+
+```
+Single Service
+├── ERP-Only
+│   ├── Customer Management
+│   ├── Product Catalog
+│   └── Order Entry
+├── WMS-Only
+│   ├── Cycle Counting
+│   ├── Putaway
+│   └── Inventory Adjustment
+└── TMS-Only
+    ├── Carrier Rate Lookup
+    ├── Shipment Tracking
+    └── Route Planning
+
+Multi-Service
+├── ERP + WMS
+│   ├── Order Fulfillment (partial)
+│   └── Inventory Synchronization
+├── WMS + TMS
+│   ├── Outbound Shipping
+│   └── Inbound Receiving
+├── ERP + EDI
+│   ├── EDI 850 Processing
+│   └── Invoice Generation
+└── ERP + WMS + TMS
+    ├── End-to-End Order Fulfillment
+    └── Drop Ship Workflow
+```
+
+**Pros**:
+- Matches current architecture
+- Clear technical dependencies
+- Easy to implement
+
+**Cons**:
+- Not user-friendly
+- Technical rather than semantic
+- Doesn't help discovery
+
+### 5. Workflow Pattern Organization
+
+Organize by **common workflow patterns**.
+
+```
+Sequential Workflows
+├── Linear Pipeline (A → B → C)
+├── Example: Inbound Receiving (Appointment → Unload → Inspect → Putaway)
+
+Parallel Workflows
+├── Fork-Join (A → [B, C, D] → E)
+├── Example: Multi-Location Picking (Split order → Pick at each DC → Consolidate)
+
+Conditional Workflows
+├── If-Then-Else (A → Decision → B or C)
+├── Example: Order Routing (Check inventory → Ship from DC or Store)
+
+Event-Driven Workflows
+├── Trigger-Action (Event → OD)
+├── Example: Low Stock Alert → Auto-Replenishment
+
+Iterative Workflows
+├── Loop Until Condition (Repeat A until B)
+├── Example: Cycle Count (Check location → Adjust → Next location)
+
+Compensating Workflows
+├── Try-Catch-Rollback (A → B fails → Undo A)
+├── Example: Order Cancellation (Release inventory, refund payment, notify customer)
+```
+
+**Pros**:
+- Educational for learning workflow patterns
+- Useful for OD design
+- Technical but accessible
+
+**Cons**:
+- Multiple patterns may apply
+- Orthogonal to business meaning
+- Complex to categorize
+
+## Multi-Dimensional Tagging
+
+Rather than forcing a single taxonomy, use **tags** to support multiple views.
+
+### Tag Schema
+
+```typescript
+{
+  // Core Tags
+  domain: string[],              // ["fulfillment", "inventory"]
+  persona: string[],             // ["store-manager", "warehouse-worker"]
+  complexity: "simple" | "medium" | "complex",
+
+  // Service Tags
+  services: string[],            // ["erp", "wms", "tms"]
+  serviceCount: number,          // 3
+
+  // Pattern Tags
+  pattern: string[],             // ["sequential", "conditional"]
+
+  // Functional Tags
+  category: string[],            // ["order-processing", "shipping"]
+
+  // Technical Tags
+  stepCount: number,             // 7
+  estimatedDuration: number,     // 5000 (ms)
+  hasExternalDeps: boolean,      // false
+
+  // Business Tags
+  businessImpact: "low" | "medium" | "high",
+  frequency: "rare" | "occasional" | "frequent",
+
+  // Meta Tags
+  version: string,               // "1.0.0"
+  author: string,                // "system" | researcher name
+  status: "draft" | "stable" | "deprecated"
+}
+```
+
+### Tag-Based Filtering
+
+Researchers can filter by any combination:
+
+**Example Queries**:
+```
+# Simple warehouse operations
+domain: "warehousing"
+complexity: "simple"
+services: ["wms"]
+
+# Store manager capabilities (medium complexity)
+persona: "store-manager"
+complexity: ["medium", "complex"]
+
+# High-frequency fulfillment workflows
+domain: "fulfillment"
+frequency: "frequent"
+businessImpact: ["medium", "high"]
+
+# Cross-service workflows
+serviceCount: >= 2
+pattern: "sequential"
+```
+
+## Browsing & Discovery UI Concepts
+
+### Concept 1: Hierarchical Tree View
+
+```
+📁 Supply Chain Management
+  📁 Fulfillment
+    📄 Order Fulfillment (medium, store-manager)
+    📄 Express Fulfillment (simple, store-manager)
+    📄 Drop Ship (complex, logistics-manager)
+  📁 Inventory Management
+    📄 Cycle Count (simple, inventory-specialist)
+    📄 Replenishment (medium, warehouse-manager)
+```
+
+### Concept 2: Persona-Centric View
+
+```
+👤 Store Manager
+  📋 My Capabilities (12)
+    ✓ Order Fulfillment
+    ✓ Inventory Management
+    ✓ Exception Handling
+  📊 By Complexity
+    Simple: 4 capabilities
+    Medium: 6 capabilities
+    Complex: 2 capabilities
+```
+
+### Concept 3: Tag Cloud / Faceted Search
+
+```
+🏷️ Tags:
+  Domain: [Fulfillment (8)] [Inventory (12)] [Transportation (6)]
+  Complexity: [Simple (15)] [Medium (20)] [Complex (8)]
+  Persona: [Store Manager (10)] [Warehouse Worker (18)]
+
+🔍 Search: "order"
+  Results (3):
+    - Order Fulfillment (fulfillment, medium, store-manager)
+    - Order Cancellation (fulfillment, simple, store-manager)
+    - Purchase Order Creation (procurement, simple, purchasing-agent)
+```
+
+### Concept 4: Capability Matrix
+
+```
+               │ Simple │ Medium │ Complex │
+───────────────┼────────┼────────┼─────────┤
+Fulfillment    │   4    │   8    │    3    │
+Inventory      │   6    │   5    │    1    │
+Transportation │   3    │   4    │    2    │
+Warehousing    │   5    │   6    │    4    │
+```
+
+## Practical Examples
+
+### Example 1: Order Fulfillment Taxonomy
+
+```yaml
+capability:
+  id: order-fulfillment
+  name: Order Fulfillment
+
+  tags:
+    domain: [fulfillment, order-processing]
+    persona: [store-manager, fulfillment-specialist]
+    complexity: medium
+    services: [erp, wms, tms]
+    serviceCount: 3
+    pattern: [sequential, conditional]
+    category: [order-processing, shipping]
+    businessImpact: high
+    frequency: frequent
+
+  variants:
+    - id: order-fulfillment-standard
+      complexity: medium
+      stepCount: 7
+      estimatedDuration: 5000
+
+    - id: order-fulfillment-express
+      complexity: simple
+      stepCount: 4
+      estimatedDuration: 3000
+      tags: [expedited]
+
+    - id: order-fulfillment-international
+      complexity: complex
+      stepCount: 12
+      estimatedDuration: 10000
+      tags: [customs, international]
+```
+
+### Example 2: Warehouse Operations Taxonomy
+
+```yaml
+domain:
+  id: warehousing
+  name: Warehouse Operations
+
+  capabilities:
+    - name: Inbound Receiving
+      complexity: medium
+      personas: [receiving-clerk, warehouse-worker]
+
+    - name: Putaway
+      complexity: simple
+      personas: [warehouse-worker]
+
+    - name: Cycle Counting
+      complexity: simple
+      personas: [inventory-specialist]
+
+    - name: Wave Picking
+      complexity: medium
+      personas: [warehouse-worker, picking-specialist]
+
+    - name: Cross-Dock Transfer
+      complexity: complex
+      personas: [warehouse-manager]
+```
+
+## Recommended Approach
+
+### Phase 1: Multi-Dimensional Tagging (Immediate)
+
+Implement comprehensive tagging on all capabilities and ODs:
+- Domain, persona, complexity (required)
+- Service, pattern, category (optional)
+- Business metadata (impact, frequency)
+
+**Benefits**:
+- Maximum flexibility
+- Supports all browsing patterns
+- Easy to extend
+
+### Phase 2: Default Views (Short-term)
+
+Create 3 primary views:
+1. **Domain View** (default for business users)
+2. **Persona View** (for role-based access)
+3. **Complexity View** (for learning/sampling)
+
+**Benefits**:
+- Guided discovery
+- Reduces cognitive load
+- Meets different user needs
+
+### Phase 3: Smart Search (Medium-term)
+
+Add search with:
+- Full-text search on names/descriptions
+- Tag-based filtering
+- Similarity search ("find capabilities like this one")
+
+**Benefits**:
+- Powerful for expert users
+- Handles edge cases
+- Scales to large catalogs
+
+### Phase 4: Personalized Recommendations (Long-term)
+
+Use knowledge graph + usage data to suggest:
+- "Researchers working on X also used Y"
+- "Based on your world config, you might need Z"
+- "This capability requires these prerequisites"
+
+**Benefits**:
+- Contextual
+- Reduces trial-and-error
+- Learns from community
+
+## Open Questions
+
+### 1. Primary Organization
+
+**Question**: What should be the default/primary taxonomy?
+
+**Options**:
+- Domain-based (business-oriented)
+- Persona-based (role-oriented)
+- Complexity-based (learning-oriented)
+- Multi-dimensional tags (no primary)
+
+**Recommendation Needed**: What's most intuitive for AI researchers?
+
+### 2. Tag Vocabulary
+
+**Question**: Should tag values be freeform or controlled?
+
+**Options**:
+- **Freeform**: Authors can add any tags
+- **Controlled**: Pre-defined tag vocabulary
+- **Hybrid**: Core tags controlled, custom tags allowed
+
+**Trade-offs**:
+- Freeform: Flexible but inconsistent
+- Controlled: Consistent but rigid
+
+**Recommendation Needed**: How important is consistency?
+
+### 3. Maintenance Strategy
+
+**Question**: Who maintains the taxonomy?
+
+**Options**:
+- **System**: Auto-generated from code
+- **Manual**: Curated by team
+- **Community**: Researchers contribute tags
+- **Hybrid**: System baseline + manual refinement
+
+**Recommendation Needed**: What's sustainable long-term?
+
+### 4. Granularity
+
+**Question**: How detailed should categories be?
+
+**Example**:
+- Coarse: "Fulfillment" (20 capabilities)
+- Medium: "Order Processing", "Picking & Packing", "Returns" (5-8 each)
+- Fine: "Standard Picking", "Batch Picking", "Zone Picking" (1-3 each)
+
+**Trade-offs**:
+- Coarse: Simple but less precise
+- Fine: Precise but overwhelming
+
+**Recommendation Needed**: What level of detail is useful?
+
+## Next Steps
+
+1. **Choose primary taxonomy** (domain/persona/complexity/tags)
+2. **Define tag schema** and controlled vocabulary
+3. **Tag existing ODs** in codebase
+4. **Build browsing UI** (or API endpoints for CLI)
+5. **Test with users** and iterate
+
+## Related Documents
+
+- [02. Conceptual Model](./02-conceptual-model.md) - Capability and persona definitions
+- [03. Knowledge Graph](./03-knowledge-graph.md) - Relationship modeling
+- [05. Sampling & World Config](./05-sampling-world-config.md) - Using taxonomy for filtering
+- [06. Open Questions](./06-open-questions.md) - Unresolved decisions

docs/od-architecture/05-sampling-world-config.md

@@ -0,0 +1,754 @@
+# 05. Sampling & World Configuration
+
+## Overview
+
+Researchers need the ability to configure "worlds" with specific subsets of capabilities, rather than always having all 100+ capabilities available. This document explores sampling strategies and world configuration patterns.
+
+## Problem Statement
+
+**Current State**:
+- Every world has all services and tools available
+- All ODs are accessible to all users
+- No way to create focused, specialized environments
+
+**User Needs**:
+- "Give me only warehouse operations" (domain filtering)
+- "Sample 10 random capabilities for testing" (random sampling)
+- "Progressive complexity: start simple, add complexity" (staged learning)
+- "Retail-only world for store management research" (persona filtering)
+
+## Use Cases
+
+### Use Case 1: Domain-Specific Research
+
+**Scenario**: Researcher studying warehouse automation
+
+**Need**: World with only warehouse-related capabilities
+
+**Configuration**:
+```yaml
+world:
+  name: "Warehouse Automation Study"
+  filter:
+    domains: [warehousing, inventory]
+    services: [wms]
+
+result:
+  capabilities: 25 (out of 100)
+  - Inbound Receiving
+  - Putaway
+  - Cycle Counting
+  - Picking & Packing
+  - Replenishment
+  - Warehouse Transfers
+  - Labor Management
+  ...
+
+  excluded:
+  - Order Fulfillment (requires ERP)
+  - Shipment Tracking (requires TMS)
+  - EDI Processing (requires EDI)
+```
+
+### Use Case 2: Persona-Based World
+
+**Scenario**: Training AI agent as "Store Manager"
+
+**Need**: World with only store manager capabilities
+
+**Configuration**:
+```yaml
+world:
+  name: "Store Manager Training"
+  filter:
+    personas: [store-manager]
+
+result:
+  capabilities: 15
+  - Order Fulfillment
+  - Inventory Management
+  - Exception Handling
+  - Staff Coordination
+  - Customer Service Escalation
+  ...
+
+  excluded:
+  - Warehouse Physical Tasks (worker-level)
+  - System Administration (admin-level)
+  - Data Engineering (technical roles)
+```
+
+### Use Case 3: Progressive Complexity
+
+**Scenario**: Learning path from simple to complex
+
+**Need**: Start with simple capabilities, gradually add complexity
+
+**Configuration**:
+```yaml
+world:
+  name: "Progressive Learning Path"
+  stages:
+    - stage: 1
+      complexity: [simple]
+      count: 10
+
+    - stage: 2
+      complexity: [simple, medium]
+      count: 20
+
+    - stage: 3
+      complexity: [simple, medium, complex]
+      count: all
+
+result:
+  stage1: 10 simple capabilities
+  stage2: + 10 medium capabilities
+  stage3: + all remaining capabilities
+```
+
+### Use Case 4: Random Sampling for Generalization
+
+**Scenario**: Testing AI agent on diverse, random tasks
+
+**Need**: Randomly sample N capabilities
+
+**Configuration**:
+```yaml
+world:
+  name: "Random Capability Test"
+  sampling:
+    strategy: random
+    count: 20
+    seed: "reproducible-123"
+
+result:
+  capabilities: 20 randomly selected
+  - Mix of domains, complexities, services
+  - Reproducible with same seed
+```
+
+### Use Case 5: Weighted Sampling by Frequency
+
+**Scenario**: Realistic distribution of common vs rare operations
+
+**Need**: Sample based on real-world frequency
+
+**Configuration**:
+```yaml
+world:
+  name: "Realistic Operations Mix"
+  sampling:
+    strategy: weighted
+    weights:
+      frequency: 0.7    # 70% weight on frequency
+      complexity: 0.2   # 20% weight on complexity
+      businessImpact: 0.1  # 10% weight on impact
+    count: 30
+
+result:
+  capabilities: 30 selected
+  - 60% frequent operations (order processing, inventory checks)
+  - 30% occasional operations (cycle counts, transfers)
+  - 10% rare operations (exceptions, reversals)
+```
+
+### Use Case 6: Capability Prerequisites
+
+**Scenario**: Ensure dependent capabilities are included
+
+**Need**: Auto-include prerequisites when selecting capabilities
+
+**Configuration**:
+```yaml
+world:
+  name: "Fulfillment with Dependencies"
+  capabilities:
+    - order-fulfillment  # explicitly selected
+
+  autoIncludeDependencies: true
+
+result:
+  included:
+    - order-fulfillment (explicit)
+    - inventory-check (prerequisite)
+    - create-shipment (prerequisite)
+    - carrier-assignment (prerequisite)
+```
+
+## Sampling Strategies
+
+### 1. Filter-Based Selection
+
+**Method**: Boolean filtering on tags
+
+**Criteria**:
+- Domain(s)
+- Persona(s)
+- Complexity level(s)
+- Service(s)
+- Pattern(s)
+- Business impact
+- Frequency
+
+**Algorithm**:
+```typescript
+function filterCapabilities(
+  allCapabilities: Capability[],
+  filters: Filters
+): Capability[] {
+  return allCapabilities.filter(cap => {
+    if (filters.domains && !filters.domains.includes(cap.domain)) return false;
+    if (filters.personas && !cap.personas.some(p => filters.personas.includes(p))) return false;
+    if (filters.complexity && cap.complexity !== filters.complexity) return false;
+    if (filters.services && !cap.services.every(s => filters.services.includes(s))) return false;
+    // ... more filters
+    return true;
+  });
+}
+```
+
+**Pros**:
+- Deterministic
+- Intuitive
+- Easy to explain
+
+**Cons**:
+- May return too many or too few results
+- No control over count
+
+### 2. Random Sampling
+
+**Method**: Randomly select N capabilities
+
+**Variants**:
+- **Uniform Random**: All capabilities equally likely
+- **Stratified Random**: Sample from each category proportionally
+
+**Algorithm**:
+```typescript
+function randomSample(
+  capabilities: Capability[],
+  count: number,
+  seed?: string
+): Capability[] {
+  const rng = seed ? seededRandom(seed) : Math.random;
+  const shuffled = shuffle(capabilities, rng);
+  return shuffled.slice(0, count);
+}
+
+function stratifiedSample(
+  capabilities: Capability[],
+  count: number,
+  stratifyBy: 'domain' | 'complexity' | 'persona'
+): Capability[] {
+  const groups = groupBy(capabilities, stratifyBy);
+  const perGroup = Math.ceil(count / groups.length);
+  return groups.flatMap(group => randomSample(group, perGroup)).slice(0, count);
+}
+```
+
+**Pros**:
+- Good for generalization testing
+- Reproducible with seed
+- Unbiased
+
+**Cons**:
+- May not match researcher intent
+- May include unrelated capabilities
+- No semantic coherence
+
+### 3. Weighted Sampling
+
+**Method**: Sample based on attribute weights
+
+**Weights**:
+- **Frequency**: How often used in real world
+- **Business Impact**: High-impact operations more likely
+- **Complexity**: Prefer simpler or more complex
+- **Recency**: Recently added capabilities
+- **Popularity**: Most-used by other researchers
+
+**Algorithm**:
+```typescript
+function weightedSample(
+  capabilities: Capability[],
+  count: number,
+  weights: WeightConfig
+): Capability[] {
+  // Calculate composite score for each capability
+  const scored = capabilities.map(cap => ({
+    capability: cap,
+    score:
+      cap.frequency * weights.frequency +
+      cap.businessImpact * weights.businessImpact +
+      (1 / cap.complexity) * weights.simplicity
+  }));
+
+  // Sort by score and take top N
+  return scored
+    .sort((a, b) => b.score - a.score)
+    .slice(0, count)
+    .map(s => s.capability);
+}
+```
+
+**Pros**:
+- Realistic distributions
+- Tunable via weights
+- Can match real-world scenarios
+
+**Cons**:
+- Requires metadata (frequency, impact)
+- More complex to configure
+- Less predictable
+
+### 4. Hierarchical Sampling
+
+**Method**: Sample from capability hierarchy
+
+**Approach**:
+- Start with high-level domains
+- Drill down to sub-capabilities
+- Ensure coverage across hierarchy
+
+**Algorithm**:
+```typescript
+function hierarchicalSample(
+  capabilityTree: CapabilityTree,
+  countPerLevel: number[]
+): Capability[] {
+  const selected: Capability[] = [];
+
+  // Level 0: Domains
+  const domains = randomSample(capabilityTree.domains, countPerLevel[0]);
+
+  domains.forEach(domain => {
+    // Level 1: Categories within domain
+    const categories = randomSample(domain.categories, countPerLevel[1]);
+
+    categories.forEach(category => {
+      // Level 2: Capabilities within category
+      selected.push(...randomSample(category.capabilities, countPerLevel[2]));
+    });
+  });
+
+  return selected;
+}
+```
+
+**Pros**:
+- Ensures diversity
+- Covers different areas
+- Good for broad testing
+
+**Cons**:
+- Requires hierarchical structure
+- May not match real workflows
+- Complex configuration
+
+### 5. Graph-Based Sampling
+
+**Method**: Use knowledge graph to ensure coherence
+
+**Approach**:
+- Select seed capability
+- Include connected capabilities (prerequisites, dependents)
+- Expand by graph distance
+
+**Algorithm**:
+```typescript
+function graphSample(
+  graph: KnowledgeGraph,
+  seedCapability: string,
+  maxDistance: number,
+  maxCount: number
+): Capability[] {
+  const visited = new Set<string>();
+  const queue: [string, number][] = [[seedCapability, 0]];
+  const selected: Capability[] = [];
+
+  while (queue.length > 0 && selected.length < maxCount) {
+    const [capId, distance] = queue.shift()!;
+
+    if (visited.has(capId) || distance > maxDistance) continue;
+    visited.add(capId);
+
+    const capability = graph.getNode(capId);
+    selected.push(capability);
+
+    // Add neighbors
+    const neighbors = graph.getNeighbors(capId, ['prerequisite', 'related_to']);
+    neighbors.forEach(neighbor => {
+      queue.push([neighbor, distance + 1]);
+    });
+  }
+
+  return selected;
+}
+```
+
+**Pros**:
+- Semantically coherent
+- Includes dependencies
+- Useful for focused research
+
+**Cons**:
+- Requires knowledge graph
+- May create echo chambers
+- Complex to reason about
+
+## World Configuration Schema
+
+### Proposed Configuration Format
+
+```yaml
+world:
+  # Metadata
+  id: string
+  name: string
+  description: string
+  author: string
+  tags: string[]
+
+  # Capability Selection
+  capabilities:
+    # Option 1: Explicit list
+    explicit:
+      - order-fulfillment
+      - inventory-management
+      - cycle-counting
+
+    # Option 2: Filter-based
+    filters:
+      domains: [fulfillment, warehousing]
+      personas: [store-manager]
+      complexity: [simple, medium]
+      services: [erp, wms]
+
+    # Option 3: Sampling
+    sampling:
+      strategy: random | weighted | stratified | hierarchical | graph
+      count: 20
+      seed: "reproducible-123"
+      weights:
+        frequency: 0.5
+        complexity: 0.3
+        businessImpact: 0.2
+
+    # Dependency handling
+    autoIncludeDependencies: true
+    autoExcludeBlocked: true
+
+  # Chaos Configuration (per-world)
+  chaos:
+    enabled: true
+    globalProbability: 0.1
+    presets: [light-chaos]
+    overrides:
+      # Per-capability overrides
+      order-fulfillment:
+        probability: 0.3
+
+  # Resource Limits
+  limits:
+    maxConcurrentODs: 10
+    maxStepsPerOD: 50
+    timeoutMs: 30000
+
+  # Data Seeding
+  seed:
+    companies: 10
+    products: 100
+    initialOrders: 50
+    customSeed: "data-seed-123"
+```
+
+### Example Configurations
+
+#### Example 1: Warehouse-Only World
+```yaml
+world:
+  name: "Warehouse Automation Research"
+  capabilities:
+    filters:
+      domains: [warehousing, inventory]
+      services: [wms]
+    autoIncludeDependencies: false
+
+  chaos:
+    enabled: true
+    globalProbability: 0.2
+
+  seed:
+    companies: 5
+    products: 50
+```
+
+#### Example 2: Progressive Learning World
+```yaml
+world:
+  name: "AI Agent Training - Progressive"
+  capabilities:
+    filters:
+      complexity: [simple]  # Start with simple only
+      personas: [warehouse-worker]
+    # Later stages can be added dynamically
+
+  chaos:
+    enabled: false  # No chaos during learning
+
+  seed:
+    companies: 3
+    products: 20
+```
+
+#### Example 3: Realistic Mix World
+```yaml
+world:
+  name: "Realistic Operations Simulation"
+  capabilities:
+    sampling:
+      strategy: weighted
+      count: 30
+      weights:
+        frequency: 0.7
+        businessImpact: 0.2
+        complexity: 0.1
+
+  chaos:
+    enabled: true
+    globalProbability: 0.05  # Light chaos
+    presets: [realistic-failures]
+
+  seed:
+    companies: 20
+    products: 200
+    initialOrders: 100
+```
+
+#### Example 4: Domain Exploration World
+```yaml
+world:
+  name: "Cross-Domain Integration Test"
+  capabilities:
+    sampling:
+      strategy: stratified
+      count: 25
+      stratifyBy: domain  # Equal representation from each domain
+
+  chaos:
+    enabled: true
+    globalProbability: 0.15
+
+  seed:
+    companies: 10
+    products: 100
+```
+
+## Implementation Considerations
+
+### 1. Capability Registry
+
+Need a central registry that supports:
+- Querying by tags/filters
+- Counting capabilities matching criteria
+- Sampling with various strategies
+- Dependency resolution
+
+**API Example**:
+```typescript
+interface CapabilityRegistry {
+  // Query
+  find(filters: Filters): Capability[];
+  count(filters: Filters): number;
+
+  // Sampling
+  sample(strategy: SamplingStrategy, config: SamplingConfig): Capability[];
+
+  // Dependencies
+  resolveDependencies(capabilities: Capability[]): Capability[];
+  validateDependencies(capabilities: Capability[]): ValidationResult;
+}
+```
+
+### 2. World Lifecycle
+
+**Creation**:
+```
+1. Parse world configuration
+2. Resolve capability selection (filters/sampling)
+3. Resolve dependencies
+4. Validate configuration
+5. Create world in database
+6. Seed initial data
+7. Return world ID
+```
+
+**Updates**:
+```
+1. Add/remove capabilities dynamically
+2. Update chaos configuration
+3. Adjust limits
+4. Cannot change after ODs have executed (immutability)
+```
+
+**Deletion**:
+```
+1. Archive logs and results
+2. Delete world data
+3. Update registry
+```
+
+### 3. Configuration Validation
+
+**Checks**:
+- At least 1 capability selected
+- All referenced capabilities exist
+- Dependencies are satisfiable
+- No circular dependencies
+- Services required by capabilities are available
+- Sampling count ≤ total available capabilities
+
+**Validation API**:
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  resolvedCapabilities: Capability[];
+  dependencyGraph: DependencyGraph;
+}
+```
+
+### 4. Presets & Templates
+
+Provide pre-configured world templates:
+
+```yaml
+presets:
+  - id: warehouse-basic
+    name: "Basic Warehouse Operations"
+    capabilities:
+      filters:
+        domains: [warehousing]
+        complexity: [simple]
+
+  - id: full-supply-chain
+    name: "End-to-End Supply Chain"
+    capabilities:
+      filters:
+        domains: [procurement, inventory, fulfillment, transportation]
+
+  - id: ai-training-starter
+    name: "AI Agent Training Starter Pack"
+    capabilities:
+      explicit:
+        - order-fulfillment-simple
+        - inventory-check
+        - shipment-tracking
+```
+
+## API Endpoints
+
+### World Configuration API
+
+```
+POST   /api/worlds                    # Create world with config
+GET    /api/worlds/:worldId           # Get world details
+PUT    /api/worlds/:worldId           # Update world config
+DELETE /api/worlds/:worldId           # Delete world
+
+GET    /api/worlds/:worldId/capabilities  # List capabilities in this world
+POST   /api/worlds/:worldId/capabilities  # Add capability to world
+DELETE /api/worlds/:worldId/capabilities/:capId  # Remove capability
+
+POST   /api/worlds/:worldId/sample   # Resample capabilities
+POST   /api/worlds/:worldId/validate # Validate configuration
+```
+
+### Sampling API
+
+```
+POST   /api/capabilities/sample       # Sample capabilities (without creating world)
+POST   /api/capabilities/filter       # Filter capabilities
+GET    /api/capabilities/count        # Count capabilities matching criteria
+```
+
+### Preset API
+
+```
+GET    /api/world-presets             # List presets
+GET    /api/world-presets/:presetId   # Get preset config
+POST   /api/world-presets/:presetId/instantiate  # Create world from preset
+```
+
+## Open Questions
+
+### 1. Static vs Dynamic Configuration
+
+**Question**: Can world capabilities change after creation?
+
+**Options**:
+- **Static**: Configuration locked at creation (immutable)
+- **Dynamic**: Capabilities can be added/removed during experiments
+- **Staged**: Pre-defined stages that unlock over time
+
+**Trade-offs**:
+- Static: Reproducible, simple, but inflexible
+- Dynamic: Flexible, but hard to reproduce
+- Staged: Good for learning paths, but complex
+
+**Recommendation Needed**: What's the priority—reproducibility or flexibility?
+
+### 2. Default Behavior
+
+**Question**: If no capabilities specified, what happens?
+
+**Options**:
+- **All**: Include all capabilities (current behavior)
+- **Error**: Require explicit configuration
+- **Smart Default**: Sample 20 common capabilities
+
+**Recommendation Needed**: What's the safest default?
+
+### 3. Dependency Auto-Resolution
+
+**Question**: Should dependencies be automatically included?
+
+**Scenario**: Researcher selects "Order Fulfillment" but not "Inventory Check" (prerequisite)
+
+**Options**:
+- **Auto-Include**: Silently add dependencies (convenient but surprising)
+- **Warn**: Show warning but allow (flexible but risky)
+- **Error**: Reject invalid configuration (strict but safe)
+
+**Recommendation Needed**: What behavior is least surprising?
+
+### 4. Sampling Determinism
+
+**Question**: Should sampling be deterministic?
+
+**Options**:
+- **Always Seeded**: Require seed for reproducibility
+- **Optional Seed**: Allow non-deterministic sampling
+- **Hybrid**: Default seed + override option
+
+**Recommendation Needed**: How important is experiment reproducibility?
+
+## Next Steps
+
+1. **Choose default sampling strategy** for most common use cases
+2. **Define world configuration schema** formally (JSON Schema/Zod)
+3. **Build capability registry** with filtering and sampling
+4. **Implement dependency resolution** using knowledge graph
+5. **Create 5-10 world presets** for common scenarios
+6. **Build world configuration API** endpoints
+7. **Test with realistic scenarios** and iterate
+
+## Related Documents
+
+- [02. Conceptual Model](./02-conceptual-model.md) - Capability definitions
+- [03. Knowledge Graph](./03-knowledge-graph.md) - Dependency modeling
+- [04. Taxonomy & Organization](./04-taxonomy-organization.md) - Filtering strategies
+- [06. Open Questions](./06-open-questions.md) - Unresolved decisions

docs/od-architecture/06-open-questions.md

@@ -0,0 +1,539 @@
+# 06. Open Questions & Decisions
+
+## Overview
+
+This document consolidates all design questions from the OD architecture discussion, tracking both decisions made and questions still pending.
+
+**Last Updated**: 2025-11-14
+
+## Decision Summary
+
+| ID | Question | Status | Decision |
+|----|----------|--------|----------|
+| **Priority 1: Critical** |
+| Q1.1 | Capability Definition | ✅ **DECIDED** | Semantic Grouping / Domain Process (~50 capabilities) |
+| Q1.2 | Capability ↔ OD Relationship | ✅ **DECIDED** | 1:N Variants |
+| Q1.3 | Knowledge Graph Approach | ✅ **DECIDED** | Hybrid (Manual → Static → Runtime, phased) |
+| Q1.4 | Primary Taxonomy | ✅ **DECIDED** | Multi-dimensional tags, domain-based default |
+| **Priority 2: Important** |
+| Q2.1 | Persona Granularity | ✅ **DECIDED** | Detailed (20-50 personas) |
+| Q2.2 | Persona-Capability Config | ✅ **DECIDED** | Hybrid (defaults + world overrides) |
+| Q2.3 | Hierarchy vs Flat | ✅ **DECIDED** | Flat with tags (add hierarchy later if needed) |
+| Q2.4 | Data Flow Inference | ✅ **DECIDED** | Manual annotations + runtime validation |
+| Q2.5 | Graph Technology | ✅ **DECIDED** | In-memory (graphlib) + MongoDB persistence |
+| **Priority 3: Nice-to-Have** |
+| Q3.1 | Tag Vocabulary | 💡 RECOMMENDED | Hybrid (core controlled + custom allowed) |
+| Q3.2 | Taxonomy Maintenance | 💡 RECOMMENDED | Hybrid (system baseline + manual curation) |
+| Q3.3 | Graph Update Frequency | 💡 RECOMMENDED | Startup + manual refresh |
+| Q3.4 | World Mutability | 💡 RECOMMENDED | Static (locked at creation for reproducibility) |
+| Q3.5 | Default World Behavior | 💡 RECOMMENDED | Error (require explicit configuration) |
+| Q3.6 | Dependency Auto-Resolution | 💡 RECOMMENDED | Warn (show warning but allow) |
+| Q3.7 | Sampling Determinism | 💡 RECOMMENDED | Hybrid (default seed + override) |
+
+## Priority 1: Critical Decisions (Block Implementation)
+
+These questions must be answered first, as they fundamentally shape the architecture.
+
+### Q1.1: Capability Definition
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option D + C**: Semantic Grouping with Domain Process characteristics (~50 capabilities)
+> **Rationale**: Capabilities should be actionable business processes that AI agents can perform end-to-end. Not too broad ("Order Management" contains too many distinct workflows), not too granular ("Click button to create order" is too atomic). Examples: "Fulfill Customer Order", "Receive Inbound Shipment", "Cycle Count Inventory".
+> **Implementation**: Start with ~30-40 capabilities, grow to 50-60 as needed. Each capability maps to 1-N OD variants.
+
+**Question**: What exactly is a capability?
+
+**Context**: Need clear definition to design the entire system.
+
+**Options**:
+- **A. Business Function**: High-level processes ("Order Management", "Inventory Control")
+- **B. User Story**: Goal-oriented tasks ("As a store manager, I want to fulfill an order")
+- **C. Domain Process**: Technical workflows ("Inbound Receiving Flow", "Pick-Pack-Ship Process")
+- **D. Semantic Grouping**: Logical grouping of related ODs
+
+**Trade-offs**:
+| Option | Granularity | User-Friendly | Technical Clarity | Count |
+|--------|-------------|---------------|-------------------|-------|
+| A | Coarse | High | Low | ~20 |
+| B | Fine | Very High | Medium | ~100+ |
+| C | Medium | Medium | High | ~50 |
+| D | Variable | Medium | Medium | ~30-60 |
+
+**Impact**: Affects taxonomy, knowledge graph, UI design, and tagging strategy.
+
+**Recommendation Needed**: Which best serves AI researchers?
+
+---
+
+### Q1.2: Capability ↔ OD Relationship
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option B**: 1:N Mapping (Variants)
+> **Rationale**: One capability can have multiple OD implementations (variants) for different scenarios. Examples: "Order Fulfillment - Standard", "Order Fulfillment - Express", "Order Fulfillment - International". This provides flexibility for researchers to choose complexity level and optimization targets (speed vs accuracy). Also enables low-chaos vs high-chaos variants of the same capability. Can add N:M composition in future if needed.
+> **Implementation**: Capability → OD[] mapping in registry. Variant selection via tags (complexity, speed, chaos-level).
+
+**Question**: Can one capability have multiple OD implementations?
+
+**Context**: Determines flexibility vs simplicity trade-off.
+
+**Options**:
+- **A. 1:1 Mapping**: One capability = exactly one OD
+- **B. 1:N Mapping (Variants)**: One capability = multiple OD variants (standard, express, complex)
+- **C. N:M Mapping (Composition)**: Capabilities can share ODs, ODs can compose
+
+**Examples**:
+```
+Option A (1:1):
+  Capability "Order Fulfillment" → OD "order-fulfillment-v1"
+
+Option B (1:N):
+  Capability "Order Fulfillment" → [
+    OD "order-fulfillment-standard",
+    OD "order-fulfillment-express",
+    OD "order-fulfillment-international"
+  ]
+
+Option C (N:M):
+  Capability "Order Fulfillment" → OD "order-fulfillment"
+  Capability "Inventory Check" → OD "inventory-check"
+  OD "order-fulfillment" uses OD "inventory-check" (sub-workflow)
+```
+
+**Trade-offs**:
+- A: Simplest, but inflexible
+- B: Good balance, clear variants
+- C: Most flexible, but most complex
+
+**Impact**: Registry design, variant selection logic, OD composition patterns.
+
+**Recommendation Needed**: What level of flexibility is required?
+
+---
+
+### Q1.3: Knowledge Graph Implementation Approach
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Hybrid - Phased Approach**: Start with Option D (Manual), evolve to Option C (Hybrid)
+> **Rationale**:
+> - **Phase 1 (MVP)**: Manual annotations in tool definitions (`@produces Order`, `@requires Customer, Product`) - Fast to implement, high quality
+> - **Phase 2**: Static analysis to extract and validate annotations using TypeScript compiler API
+> - **Phase 3**: Runtime learning to refine edge weights and discover implicit patterns
+> **Implementation**: Build graph structure now, populate incrementally. Start with manual annotations for critical tools, expand coverage over time.
+
+**Question**: How should the knowledge graph be built?
+
+**Context**: Affects development timeline and capabilities.
+
+**Options**:
+- **A. Static Analysis** (Build time): Parse code, generate graph from types/schemas
+- **B. Dynamic Learning** (Runtime): Learn from OD executions, infer relationships
+- **C. Hybrid**: Static baseline + runtime refinement
+- **D. Manual Annotation**: Developers explicitly specify relationships
+
+**Trade-offs**:
+| Option | Effort | Accuracy | Maintenance | Bootstrap Time |
+|--------|--------|----------|-------------|----------------|
+| A | Medium | Medium | Low | Fast |
+| B | High | High | Low | Slow |
+| C | High | Very High | Medium | Medium |
+| D | Low | High | High | Fast |
+
+**Impact**: Development time, graph quality, maintenance burden.
+
+**Recommendation Needed**: What's feasible for initial version?
+
+---
+
+### Q1.4: Primary Taxonomy
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option D**: Multi-Dimensional Tags with **Domain-Based Default View**
+> **Rationale**: Different researchers have different mental models. Tags support all browsing patterns without forcing a single hierarchy. Default to domain-based view (Fulfillment, Inventory, Transportation) as it matches business language, but also offer persona view and complexity view.
+> **Implementation**: Every capability gets comprehensive tags: `{domain: [], persona: [], complexity: "", services: [], pattern: []}`. API supports filtering by any tag combination. UI offers 3 primary views: Domain (default), Persona, Complexity.
+> **Example**: `/api/capabilities?domain=fulfillment`, `/api/capabilities?persona=store-manager`, `/api/capabilities?complexity=simple`
+
+**Question**: What should be the default organization scheme?
+
+**Context**: Determines how researchers browse and discover capabilities.
+
+**Options**:
+- **A. Domain-Based**: Organize by business domain (Fulfillment, Inventory, Transportation)
+- **B. Persona-Based**: Organize by role (Store Manager, Warehouse Worker)
+- **C. Complexity-Based**: Organize by difficulty (Simple, Medium, Complex)
+- **D. Multi-Dimensional Tags**: No primary taxonomy, support all views
+
+**Trade-offs**:
+| Option | Intuitive | Flexible | Maintenance | Use Case |
+|--------|-----------|----------|-------------|----------|
+| A | High | Low | Low | Business-oriented research |
+| B | Medium | Medium | Medium | Role-based training |
+| C | Medium | Low | Low | Progressive learning |
+| D | Low | Very High | High | Expert users |
+
+**Impact**: UI design, browsing patterns, filtering logic.
+
+**Recommendation Needed**: What's most intuitive for AI researchers?
+
+---
+
+## Priority 2: Important Design Choices
+
+These affect implementation details but can be iterated on.
+
+### Q2.1: Persona Granularity
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option B**: Detailed (20-50 personas)
+> **Rationale**: Broad personas (5-10) are too coarse - "Manager" doesn't convey specific responsibilities. Functional personas (50+) are overkill and hard to maintain. Sweet spot: Role-specific but not task-specific. Examples: Store Manager, Warehouse Manager, DC Manager (different management roles); Receiving Clerk, Shipping Clerk, Inventory Specialist (different operational functions).
+> **Implementation**: Start with 15-20 core personas, expand to 30-40 as use cases emerge. Not: "Morning Shift Receiving Clerk" (too granular).
+
+**Question**: How detailed should personas be?
+
+**Options**:
+- **A. Broad** (5-10 personas): Manager, Worker, Coordinator, Analyst, Bot
+- **B. Detailed** (20-50 personas): Store Manager, DC Manager, Warehouse Manager, Receiving Clerk, etc.
+- **C. Functional** (50+ personas): Very specific roles for each function
+
+**Trade-offs**:
+- A: Simple to manage, coarse permissions
+- B: Balance of specificity and manageability
+- C: Highly realistic, complex to maintain
+
+**Impact**: Permission model, world configuration complexity.
+
+**Recommendation Needed**: What level matches research needs?
+
+---
+
+### Q2.2: Persona ↔ Capability Configuration
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option C**: Hybrid (Defaults in config, overridable per world)
+> **Rationale**: Standard persona-capability mappings should be in version-controlled config (stable, predictable). But researchers need ability to create custom personas or restrict capabilities for experiments. Solution: Default mappings work out-of-box, but worlds can override with custom personas.
+> **Implementation**: Default mappings in `config/personas.json`. World config can add `personaOverrides: { "custom-agent": { capabilities: [...] } }`.
+
+**Question**: Should persona-capability mappings be configurable?
+
+**Options**:
+- **A. Static**: Hardcoded in config files, version controlled
+- **B. Dynamic**: Stored in database, editable via API
+- **C. Hybrid**: Defaults in config, overridable per world
+
+**Use Cases**:
+- Custom personas for specific experiments
+- Restrict capabilities for testing
+- Evolve personas without code changes
+
+**Impact**: Flexibility, complexity, reproducibility.
+
+**Recommendation Needed**: How important is runtime configurability?
+
+---
+
+### Q2.3: Hierarchy vs Flat Capabilities
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Flat with tags** (add hierarchy later if needed)
+> **Rationale**: With ~50 capabilities, flat structure is manageable. Tags provide "virtual hierarchy": filtering by `domain:fulfillment` shows all fulfillment capabilities. Simpler to implement and reason about. Can add optional parent/child relationships later if catalog grows to 100+ capabilities.
+> **Implementation**: No parent/child fields. Use tags for grouping: `tags: { domain: ["fulfillment"], category: ["order-processing"] }`.
+
+**Question**: Should capabilities have hierarchical structure?
+
+**Examples**:
+```
+Hierarchical:
+  Order Management (parent)
+    ├── Create Order
+    ├── Fulfill Order
+    ├── Cancel Order
+    └── Track Order
+
+Flat:
+  - Create Order
+  - Fulfill Order
+  - Cancel Order
+  - Track Order
+```
+
+**Trade-offs**:
+- Hierarchical: Better organization, more complex
+- Flat: Simpler, but harder to navigate large catalogs
+
+**Impact**: UI complexity, filtering logic, tagging strategy.
+
+**Recommendation Needed**: Is flat sufficient or do we need hierarchy?
+
+---
+
+### Q2.4: Data Flow Inference Method
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option D**: Hybrid (Manual annotations + runtime validation)
+> **Rationale**: Phase 1: Add manual annotations to tool definitions (`produces: ["Order"], requires: ["Customer", "Product"]`). Fast to implement, high quality. Phase 2: Runtime tracking validates annotations and discovers edge cases. Best of both worlds.
+> **Implementation**: Add metadata fields to service tool definitions. Start with critical tools, expand coverage incrementally. Runtime logs can validate/suggest annotations.
+
+**Question**: How do we determine which entities a tool produces/requires?
+
+**Context**: Needed for knowledge graph and OD validation.
+
+**Options**:
+- **A. Manual Annotation**: Developers add metadata (e.g., `@produces Order`)
+- **B. Schema Analysis**: Infer from TypeScript types and input/output schemas
+- **C. Runtime Learning**: Monitor executions, track data flow
+- **D. Hybrid**: Start with annotations, refine with runtime data
+
+**Feasibility**:
+- A: Immediate, but manual effort
+- B: Possible with TypeScript compiler API, may be incomplete
+- C: Accurate but slow to bootstrap
+- D: Best of both worlds, more complex
+
+**Impact**: Graph quality, validation accuracy, developer burden.
+
+**Recommendation Needed**: What's most practical?
+
+---
+
+### Q2.5: Graph Technology Choice
+
+> **✅ DECISION** (2025-11-14)
+> **Chosen**: **Option D**: In-memory (graphlib) + MongoDB persistence
+> **Rationale**: Use in-memory graph library (graphlib) for fast queries. Persist graph structure to MongoDB (already in stack). Load graph on startup. No new infrastructure (Neo4j). Can migrate to dedicated graph DB later if query complexity demands it.
+> **Implementation**: `Graph` class using graphlib. Store nodes/edges in MongoDB collections. Load on service startup: `graph.loadFromMongoDB()`. Update and persist as needed.
+
+**Question**: What technology should power the knowledge graph?
+
+**Options**:
+- **A. In-Memory (graphlib, cytoscape.js)**: Simple, fast, not persistent
+- **B. Graph Database (Neo4j, ArangoDB)**: Purpose-built, powerful queries, infrastructure
+- **C. MongoDB**: Already using it, not optimized for graphs
+- **D. Hybrid**: In-memory + MongoDB persistence
+
+**Trade-offs**:
+| Option | Setup | Performance | Persistence | Query Power |
+|--------|-------|-------------|-------------|-------------|
+| A | Easy | Fast | No | Basic |
+| B | Hard | Fast | Yes | Excellent |
+| C | Easy | Slow | Yes | Limited |
+| D | Medium | Fast | Yes | Medium |
+
+**Impact**: Infrastructure complexity, query capabilities, scalability.
+
+**Recommendation Needed**: What fits the architecture best?
+
+---
+
+## Priority 3: Nice-to-Have Features
+
+These can be deferred to later phases. **RECOMMENDED** options provided below can be finalized during implementation.
+
+### Q3.1: Tag Vocabulary Control
+
+> **💡 RECOMMENDED**: **Option C**: Hybrid (Core tags controlled, custom tags allowed)
+> Core tags (domain, persona, complexity, services) use controlled vocabulary. Custom tags allowed for experimental/research-specific categorization.
+
+**Question**: Should tag values be freeform or controlled?
+
+**Options**:
+- **A. Freeform**: Authors can add any tags (flexible, inconsistent)
+- **B. Controlled**: Pre-defined tag vocabulary (consistent, rigid)
+- **C. Hybrid**: Core tags controlled, custom tags allowed
+
+**Impact**: Tag consistency, search quality, maintenance.
+
+---
+
+### Q3.2: Taxonomy Maintenance
+
+> **💡 RECOMMENDED**: **Option D**: Hybrid (System baseline + manual curation)
+> System generates initial tags from code structure. Team manually curates and refines. Sustainable long-term.
+
+**Question**: Who maintains the taxonomy and tags?
+
+**Options**:
+- **A. System**: Auto-generated from code
+- **B. Manual**: Curated by team
+- **C. Community**: Researchers contribute
+- **D. Hybrid**: System baseline + manual curation
+
+**Impact**: Accuracy, freshness, maintenance burden.
+
+---
+
+### Q3.3: Graph Update Frequency
+
+> **💡 RECOMMENDED**: **Option B**: Startup (+ manual refresh capability)
+> Load graph on service startup. Provide manual refresh endpoint for updates without restart.
+
+**Question**: When does the knowledge graph get updated?
+
+**Options**:
+- **A. Build Time**: Regenerated on deployment
+- **B. Startup**: Built when service starts
+- **C. Runtime**: Updated as ODs execute
+- **D. Manual**: Explicit refresh command
+
+**Impact**: Graph freshness, performance, complexity.
+
+---
+
+### Q3.4: World Configuration Mutability
+
+> **💡 RECOMMENDED**: **Option A**: Static (locked at creation)
+> World configuration locked at creation for reproducibility. Create new world for different configuration.
+
+**Question**: Can world capabilities change after creation?
+
+**Options**:
+- **A. Static**: Configuration locked at creation (reproducible, inflexible)
+- **B. Dynamic**: Capabilities can be added/removed (flexible, hard to reproduce)
+- **C. Staged**: Pre-defined stages that unlock over time (good for learning, complex)
+
+**Impact**: Reproducibility, flexibility, complexity.
+
+---
+
+### Q3.5: Default World Behavior
+
+> **💡 RECOMMENDED**: **Option B**: Error (require explicit configuration)
+> Fail fast if no capabilities specified. Forces researchers to think about world configuration.
+
+**Question**: If no capabilities specified, what happens?
+
+**Options**:
+- **A. All**: Include all capabilities (current behavior)
+- **B. Error**: Require explicit configuration (safe, strict)
+- **C. Smart Default**: Sample 20 common capabilities (convenient, opinionated)
+
+**Impact**: User experience, safety, defaults.
+
+---
+
+### Q3.6: Dependency Auto-Resolution
+
+> **💡 RECOMMENDED**: **Option B**: Warn (show warning but allow)
+> Show clear warning message listing missing dependencies, but allow configuration. Researcher makes informed choice.
+
+**Question**: Should dependencies be automatically included?
+
+**Scenario**: Researcher selects "Order Fulfillment" but not "Inventory Check" (prerequisite)
+
+**Options**:
+- **A. Auto-Include**: Silently add dependencies (convenient, surprising)
+- **B. Warn**: Show warning but allow (flexible, risky)
+- **C. Error**: Reject invalid configuration (strict, safe)
+
+**Impact**: User experience, safety, complexity.
+
+---
+
+### Q3.7: Sampling Determinism
+
+> **💡 RECOMMENDED**: **Option C**: Hybrid (default seed + override)
+> Auto-generate seed (timestamp-based) for reproducibility. Allow explicit seed override for exact replication.
+
+**Question**: Should sampling always be deterministic?
+
+**Options**:
+- **A. Always Seeded**: Require seed for reproducibility (reproducible, less convenient)
+- **B. Optional Seed**: Allow non-deterministic sampling (flexible, hard to reproduce)
+- **C. Hybrid**: Default seed + override option (balanced)
+
+**Impact**: Experiment reproducibility, user experience.
+
+---
+
+## Decision-Making Framework
+
+### How to Prioritize
+
+**Criteria**:
+1. **Blocking**: Does this block other work?
+2. **Impact**: How many components are affected?
+3. **Reversibility**: Can we change this decision later?
+4. **Effort**: How much work to implement each option?
+
+**Suggested Process**:
+1. Answer all Priority 1 questions first
+2. Build proof-of-concept based on Priority 1 answers
+3. Test POC with realistic scenarios
+4. Answer Priority 2 questions based on learnings
+5. Defer Priority 3 questions to later phases
+
+### Decision Log Template
+
+For each question, document:
+```markdown
+## Decision: [Question Number]
+
+**Date**: YYYY-MM-DD
+**Decided By**: [Name/Team]
+**Chosen Option**: [A/B/C/D]
+
+**Rationale**:
+- Why this option was chosen
+- Key trade-offs considered
+- Alternative options rejected and why
+
+**Impact**:
+- What changes in implementation
+- Dependencies on other decisions
+- Timeline impact
+
+**Revisit Date**: YYYY-MM-DD (if needed)
+```
+
+## Next Steps
+
+✅ **Completed**:
+1. All Priority 1 (critical) questions decided
+2. All Priority 2 (important) questions decided
+3. Priority 3 (nice-to-have) recommendations provided
+
+**Now Ready For**:
+1. **Create implementation roadmap** based on decisions
+2. **Build proof-of-concept** for:
+   - Capability registry with multi-dimensional tags
+   - Knowledge graph (in-memory + MongoDB)
+   - OD variant system (1:N mapping)
+   - Manual tool annotations (produces/requires)
+3. **Define initial capability catalog** (~30-40 capabilities)
+4. **Define persona catalog** (~15-20 personas)
+5. **Start Phase 1 implementation** (see implementation plan TBD)
+
+## Related Documents
+
+- [02. Conceptual Model](./02-conceptual-model.md) - Questions about capability/persona/OD definitions
+- [03. Knowledge Graph](./03-knowledge-graph.md) - Questions about graph implementation
+- [04. Taxonomy & Organization](./04-taxonomy-organization.md) - Questions about categorization
+- [05. Sampling & World Config](./05-sampling-world-config.md) - Questions about world configuration
+
+---
+
+## Summary
+
+**Status**: ✅ All critical and important questions decided (2025-11-14)
+
+**Priority 1 (Critical)**: 4/4 **DECIDED** ✅
+- Capability definition → Semantic Grouping / Domain Process (~50 capabilities)
+- Capability ↔ OD relationship → 1:N Variants
+- Knowledge graph approach → Hybrid (Manual → Static → Runtime phased)
+- Primary taxonomy → Multi-dimensional tags, domain-based default
+
+**Priority 2 (Important)**: 5/5 **DECIDED** ✅
+- Persona granularity → Detailed (20-50 personas)
+- Persona-capability configuration → Hybrid (defaults + world overrides)
+- Hierarchy vs flat → Flat with tags
+- Data flow inference → Manual annotations + runtime validation
+- Graph technology → In-memory (graphlib) + MongoDB
+
+**Priority 3 (Nice-to-Have)**: 7/7 **RECOMMENDED** 💡
+- Tag vocabulary → Hybrid (core controlled + custom allowed)
+- Taxonomy maintenance → Hybrid (system baseline + manual curation)
+- Graph update frequency → Startup + manual refresh
+- World configuration mutability → Static (locked at creation)
+- Default world behavior → Error (require explicit config)
+- Dependency auto-resolution → Warn (show warning but allow)
+- Sampling determinism → Hybrid (default seed + override)
+
+**Next Step**: Create implementation roadmap and build proof-of-concept.

docs/od-architecture/07-chaos-integration.md

@@ -0,0 +1,535 @@
+# 07. Chaos Integration
+
+## Overview
+
+This document explains how the chaos management system integrates with the OD architecture. Chaos is a **cross-cutting concern** that affects capability execution at multiple levels.
+
+For complete chaos management details, see [Chaos Management Documentation](../chaos/).
+
+**Last Updated**: 2025-11-14
+
+## Chaos in the Architecture
+
+### Architectural Position
+
+```
+┌─────────────────────────────────────┐
+│  PERSONA                            │
+│  (Store Manager)                    │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│  CAPABILITY                         │  ← Chaos override possible
+│  (Order Fulfillment)                │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│  OPERATIONAL DESCRIPTOR (OD)        │  ← Chaos policy defined
+│  (Workflow with chaos config)       │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│  STEP                               │  ← Chaos injected here
+│  (Tool execution + chaos)           │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│  TOOL                               │
+│  (Actual service call)              │
+└─────────────────────────────────────┘
+```
+
+**Chaos is injected**: After tool execution, before storing output (in the Step layer)
+
+**Chaos is configured**: At World, Capability, OD, and Step levels
+
+## Configuration Cascade
+
+Chaos configuration follows a **priority cascade** (highest to lowest):
+
+```
+1. MASTER KILL-SWITCH (environment variable)
+   ↓ if enabled
+2. Step-level chaos override (in OD definition)
+   ↓ if not specified
+3. OD-level chaos policy (global OD chaos)
+   ↓ if not specified
+4. Capability-level override (per-capability config)
+   ↓ if not specified
+5. World-level chaos policy (world config)
+   ↓ if not specified
+6. System default chaos preset
+```
+
+### Example Cascade
+
+**Environment**: `CHAOS_ENABLED=true`
+
+**World Config**:
+```yaml
+world:
+  id: "research-001"
+  chaos:
+    preset: "moderate"  # Global: 0.15 probability
+```
+
+**Capability Override**:
+```yaml
+capability:
+  id: "order-fulfillment"
+  chaosOverride:
+    probability: 0.3  # Higher for this capability
+```
+
+**OD Definition**:
+```yaml
+od:
+  id: "order-fulfillment-standard"
+  chaos:
+    probability: 0.25  # OD-level setting
+  steps:
+    - id: "check-inventory"
+      chaos:
+        probability: 0.0  # This step: no chaos!
+```
+
+**Result**:
+- `check-inventory` step: **0.0** (step override)
+- Other steps in OD: **0.25** (OD-level)
+- Other capabilities in world: **0.15** (world preset)
+
+## Integration Points
+
+### 1. World Configuration
+
+Chaos is configured when creating a world:
+
+```yaml
+POST /api/worlds
+{
+  "name": "Chaos Research World",
+  "capabilities": {
+    "filters": { "domain": ["fulfillment"] }
+  },
+  "chaos": {
+    "preset": "aggressive",
+    "seed": "repro-123"
+  }
+}
+```
+
+**What Happens**:
+- World uses "aggressive" preset (0.3 probability)
+- All capabilities in this world inherit this chaos
+- Seed ensures reproducibility
+
+### 2. Capability-Level Overrides
+
+Fine-grained control per capability:
+
+```yaml
+world:
+  chaos:
+    preset: "moderate"
+    capabilityOverrides:
+      order-fulfillment:
+        probability: 0.5  # Critical capability: more chaos
+      inventory-check:
+        probability: 0.0  # Critical path: no chaos
+```
+
+**Use Case**: Test resilience of critical capabilities with higher chaos.
+
+### 3. OD Execution
+
+Chaos is injected during OD execution:
+
+```
+1. Researcher executes capability
+2. Capability maps to OD
+3. OD executor runs steps
+4. For each step:
+   a. Execute tool (service call)
+   b. Resolve chaos policy (use cascade)
+   c. Maybe inject chaos (based on probability)
+   d. Store result (potentially modified by chaos)
+5. Return execution result
+```
+
+**Chaos Transparency**:
+- Chaos injections are logged
+- Chaos modifications tracked in telemetry
+- Researchers can see what chaos was applied
+
+### 4. OD Variants with Chaos
+
+Capabilities can have chaos-specific variants:
+
+```yaml
+capability:
+  id: "order-fulfillment"
+  variants:
+    - id: "order-fulfillment-no-chaos"
+      chaos: { enabled: false }
+      odId: "order-fulfillment-v1"
+
+    - id: "order-fulfillment-light-chaos"
+      chaos: { preset: "light" }
+      odId: "order-fulfillment-v1"
+
+    - id: "order-fulfillment-aggressive-chaos"
+      chaos: { preset: "aggressive" }
+      odId: "order-fulfillment-v1"
+```
+
+**Benefit**: Same workflow, different chaos levels for A/B testing.
+
+## Chaos Presets
+
+### Standard Presets
+
+Defined in `config/chaos-presets/`:
+
+**light.json** (0.05 probability):
+- Stale data (eventual consistency)
+- Rate limits (throttling)
+- Missing data (occasional)
+
+**moderate.json** (0.15 probability):
+- All light scenarios
+- Data corruption
+- Partial data
+- Permission denied
+
+**aggressive.json** (0.3 probability):
+- All scenarios
+- Higher weights
+- More severe configurations
+
+**realistic.json** (0.08 probability):
+- Real-world failure distribution
+- Stale data: 40% weight
+- Rate limits: 20% weight
+- Rare failures: < 5% weight
+
+### Custom Presets
+
+Researchers can create custom presets:
+
+```json
+// config/chaos-presets/custom-fulfillment.json
+{
+  "id": "custom-fulfillment",
+  "name": "Order Fulfillment Focused Chaos",
+  "globalProbability": 0.2,
+  "scenarios": [
+    {
+      "type": "missing_data",
+      "weight": 10,
+      "description": "Missing inventory records",
+      "config": { "missingRecords": true }
+    },
+    {
+      "type": "stale_data",
+      "weight": 8,
+      "description": "Stale order status",
+      "config": { "staleDataAge": 120 }
+    }
+  ]
+}
+```
+
+## Master Kill-Switch
+
+### Environment Variables
+
+```bash
+# Disable all chaos globally
+CHAOS_ENABLED=false
+
+# Use specific preset
+CHAOS_PRESET=moderate
+
+# Override global probability
+CHAOS_GLOBAL_PROBABILITY=0.2
+
+# Set global seed
+CHAOS_GLOBAL_SEED=experiment-001
+```
+
+**Priority**: Environment variables override ALL file-based configuration.
+
+### Runtime Control
+
+```bash
+# Via API (if implemented)
+PUT /api/chaos/status
+{
+  "enabled": false
+}
+```
+
+**Use Case**: Emergency disable without restarting service.
+
+## Chaos Telemetry
+
+### What's Logged
+
+Every chaos injection logs:
+
+```json
+{
+  "timestamp": "2025-11-14T10:30:45Z",
+  "level": "info",
+  "msg": "Chaos injected",
+  "chaos": {
+    "worldId": "research-001",
+    "capabilityId": "order-fulfillment",
+    "odId": "order-fulfillment-standard-v1",
+    "stepId": "check-inventory",
+    "scenarioType": "stale_data",
+    "configSource": "world-preset",
+    "probability": 0.15,
+    "seed": "repro-123",
+    "modifications": {
+      "staleDataAge": 60,
+      "fieldsAffected": ["timestamp", "lastUpdated"]
+    }
+  }
+}
+```
+
+### Chaos Metrics
+
+Track chaos impact:
+
+```
+GET /api/chaos/metrics?worldId=research-001
+{
+  "totalInjections": 150,
+  "injectionRate": 0.14,
+  "scenarioDistribution": {
+    "stale_data": 60,
+    "missing_data": 45,
+    "rate_limit": 30
+  },
+  "impactAnalysis": {
+    "odSuccessRate": 0.75,
+    "odSuccessRateWithoutChaos": 0.95,
+    "chaosImpact": -20%
+  }
+}
+```
+
+## Integration with Knowledge Graph
+
+### Chaos-Aware Validation
+
+Knowledge graph can validate chaos feasibility:
+
+```typescript
+// Can this OD handle this chaos scenario?
+graph.validateChaos(odId, chaosScenario);
+
+// Which scenarios are safe for this capability?
+graph.suggestSafeChaos(capabilityId);
+```
+
+### Chaos Dependencies
+
+Some chaos scenarios require specific data:
+
+```
+Scenario: "data_corruption"
+  Requires: Fields to corrupt
+  Validates: OD produces structured data (not just primitives)
+
+Scenario: "missing_data"
+  Requires: Optional fields in schema
+  Validates: OD can handle missing data gracefully
+```
+
+**Future**: Graph validates chaos applicability before injection.
+
+## Researcher Workflows
+
+### Workflow 1: Standard Chaos Testing
+
+```yaml
+# Create world with moderate chaos
+world:
+  name: "Resilience Test"
+  chaos:
+    preset: "moderate"
+    seed: "test-001"
+
+# Execute capabilities
+# Observe failures
+# Analyze chaos impact
+```
+
+### Workflow 2: Progressive Chaos
+
+```yaml
+# Phase 1: No chaos
+world1:
+  chaos: { enabled: false }
+
+# Phase 2: Light chaos
+world2:
+  chaos: { preset: "light" }
+
+# Phase 3: Aggressive chaos
+world3:
+  chaos: { preset: "aggressive" }
+
+# Compare results across phases
+```
+
+### Workflow 3: Targeted Chaos
+
+```yaml
+# Most capabilities: no chaos
+world:
+  chaos: { enabled: false }
+
+  # Except one critical capability
+  capabilityOverrides:
+    order-fulfillment:
+      chaos:
+        preset: "aggressive"
+        scenarios: [
+          { type: "missing_data", weight: 10 }
+        ]
+```
+
+### Workflow 4: A/B Testing
+
+```yaml
+# Control group: no chaos variant
+capability: "order-fulfillment-no-chaos"
+
+# Treatment group: chaos variant
+capability: "order-fulfillment-light-chaos"
+
+# Compare AI agent performance
+```
+
+## Best Practices
+
+### 1. Start with Presets
+
+Don't configure chaos manually from scratch:
+
+```yaml
+# ✅ Good: Use preset
+chaos:
+  preset: "moderate"
+
+# ❌ Avoid: Manual config (error-prone)
+chaos:
+  probability: 0.15
+  scenarios: [ ... 20 lines of config ... ]
+```
+
+### 2. Always Use Seeds for Reproducibility
+
+```yaml
+# ✅ Good: Reproducible
+chaos:
+  preset: "moderate"
+  seed: "experiment-20251114-001"
+
+# ❌ Avoid: Non-deterministic
+chaos:
+  preset: "moderate"
+  # no seed = different chaos each run
+```
+
+### 3. Override Selectively
+
+```yaml
+# ✅ Good: Preset + targeted override
+chaos:
+  preset: "moderate"
+  capabilityOverrides:
+    critical-capability:
+      probability: 0.0  # No chaos for critical path
+
+# ❌ Avoid: Everything manual
+capabilityOverrides:
+  cap1: { ... }
+  cap2: { ... }
+  cap3: { ... }
+  # Too much manual config
+```
+
+### 4. Document Chaos Rationale
+
+```yaml
+world:
+  name: "Agent Resilience Test"
+  description: "Testing AI agent with realistic failure rates"
+  chaos:
+    preset: "realistic"
+    seed: "resilience-001"
+  chaosRationale: "Using realistic preset to match production failure distribution"
+```
+
+## Implementation Phases
+
+Chaos management is built incrementally alongside OD architecture:
+
+### Phase 1 (Core Capability System)
+- **Deliverable**: Chaos preset files
+- **Deliverable**: Environment variable support (CHAOS_ENABLED)
+- **Deliverable**: ChaosConfigRegistry service
+- Researchers can use presets
+
+### Phase 2 (World Configuration)
+- **Deliverable**: World-level chaos config
+- **Deliverable**: Apply presets to worlds
+- **Deliverable**: Seed support for reproducibility
+- Researchers configure chaos per world
+
+### Phase 4 (Advanced Features)
+- **Deliverable**: Capability-level overrides
+- **Deliverable**: OD-level runtime config
+- **Deliverable**: Chaos telemetry and metrics
+- Researchers have fine-grained control
+
+### Phase 5 (Polish & Scale)
+- **Deliverable**: Chaos configuration API
+- **Deliverable**: Impact analysis tools
+- **Deliverable**: Migration from scattered configs
+- Production-ready chaos management
+
+## Related Documents
+
+- **[Chaos Management](../chaos/chaos-management.md)** - Complete chaos system design
+- **[Chaos Presets](../chaos/)** - Preset library and details
+- **[02. Conceptual Model](./02-conceptual-model.md)** - Where chaos fits in architecture
+- **[08. Implementation Roadmap](./08-implementation-roadmap.md)** - Chaos implementation timeline
+- **[05. World Configuration](./05-sampling-world-config.md)** - World-level chaos config
+
+## Summary
+
+**Key Points**:
+1. Chaos is a **cross-cutting concern** affecting OD execution
+2. Configuration **cascades** from World → Capability → OD → Step
+3. **Master kill-switch** via environment variables
+4. **Presets** provide standardized chaos configurations
+5. **Telemetry** tracks all chaos injections
+6. **Reproducible** via seeded randomness
+7. Integrated with **OD architecture** from Phase 1
+
+**For Researchers**:
+- Start with presets (light, moderate, aggressive, realistic)
+- Configure at world level
+- Override for specific capabilities as needed
+- Always use seeds for reproducibility
+- Monitor chaos impact via telemetry

docs/od-architecture/08-implementation-roadmap.md

@@ -0,0 +1,819 @@
+# 08. Implementation Roadmap
+
+## Overview
+
+This roadmap outlines a **value-driven, incremental approach** to implementing the OD management system. Each phase delivers usable features to researchers, not just infrastructure.
+
+**Last Updated**: 2025-11-14
+
+## Why NOT Bottom-Up?
+
+**Bottom-up approach (❌ Don't do this)**:
+```
+Phase 1: Build complete database schema
+Phase 2: Build knowledge graph infrastructure
+Phase 3: Build capability registry
+Phase 4: Build persona system
+Phase 5: Finally, let researchers use it
+```
+
+**Problems**:
+- No researcher value until Phase 5
+- High risk if requirements change
+- Over-engineering for features we might not need
+- Long feedback loop - don't learn if design works until the end
+
+## Our Approach: Value-Driven Vertical Slices
+
+**Incremental approach (✅ We do this)**:
+```
+Phase 0: Walking skeleton - 5 hardcoded capabilities researchers can execute
+Phase 1: Browse and filter ~30 capabilities
+Phase 2: Create custom worlds with capability sampling
+Phase 3: Validate dependencies (basic knowledge graph)
+Phase 4: Add personas and chaos integration
+Phase 5: Polish and scale
+```
+
+**Benefits**:
+- Researcher value from Phase 0
+- Fast feedback - learn if approach works early
+- Can pivot based on learnings
+- Lower risk - small increments
+- Infrastructure built when needed, not speculatively
+
+## Guiding Principles
+
+1. **Deliver Value Every Phase**: Each phase = something researchers can use
+2. **Walking Skeleton First**: Get minimal end-to-end working, then expand
+3. **Defer Decisions**: Don't implement everything designed; implement what's needed
+4. **Evolutionary Architecture**: Allow for changes based on learnings
+5. **Vertical Slices**: Build features end-to-end, not layers horizontally
+
+---
+
+## Phase 0: Walking Skeleton (2-3 weeks)
+
+### Goal
+Prove the concept works end-to-end with minimal implementation.
+
+### What Researchers Can Do
+- List available capabilities (5 hardcoded examples)
+- View capability details (name, description, tags)
+- Execute a capability (maps to existing OD)
+
+### Deliverables
+
+**1. Hardcoded Capability Catalog** (~5 capabilities)
+```typescript
+// src/capabilities/catalog.ts
+export const CAPABILITIES = [
+  {
+    id: "order-fulfillment-simple",
+    name: "Order Fulfillment (Simple)",
+    description: "Process customer order with basic workflow",
+    tags: {
+      domain: ["fulfillment"],
+      complexity: "simple",
+      services: ["erp", "wms"]
+    },
+    odId: "order-fulfillment-standard-v1"  // Links to existing OD
+  },
+  // ... 4 more
+];
+```
+
+**2. Simple REST API**
+```
+GET  /api/capabilities           # List all capabilities
+GET  /api/capabilities/:id       # Get capability details
+POST /api/capabilities/:id/execute  # Execute (runs linked OD)
+```
+
+**3. Execution Logic**
+- Map capability ID → existing OD
+- Execute OD using current executor
+- Return results
+
+### What We're NOT Building Yet
+- ❌ Database persistence
+- ❌ Knowledge graph
+- ❌ Complex filtering
+- ❌ World configuration
+- ❌ Persona system
+- ❌ Dynamic capability creation
+
+### Success Criteria
+- ✅ Researcher can GET /api/capabilities and see 5 options
+- ✅ Researcher can execute a capability and get results
+- ✅ End-to-end flow works without errors
+- ✅ Team agrees this approach is promising
+
+### Decision Point
+**After Phase 0**: Does this approach provide value? Should we continue?
+
+**Effort**: 2-3 weeks (1 developer)
+
+---
+
+## Phase 1: Core Capability System (3-4 weeks)
+
+### Goal
+Expand to ~30 capabilities with browsing, filtering, and tagging.
+
+### What Researchers Can Do
+- Browse ~30 capabilities across domains
+- Filter by domain, complexity, services
+- Search by name/description
+- Execute any capability
+- **Use chaos presets** (light, moderate, aggressive)
+
+### Deliverables
+
+**1. Capability Registry Service**
+```typescript
+// src/services/capability-registry.service.ts
+class CapabilityRegistry {
+  private capabilities: Map<string, Capability>;
+
+  find(filters: CapabilityFilters): Capability[];
+  get(capabilityId: string): Capability | null;
+  search(query: string): Capability[];
+}
+```
+
+**2. Capability Definitions** (~30 capabilities)
+- File-based storage: `config/capabilities/`
+- YAML or JSON format
+- Comprehensive tags for each
+
+**3. Enhanced API**
+```
+GET /api/capabilities?domain=fulfillment
+GET /api/capabilities?complexity=simple
+GET /api/capabilities?services=wms,erp
+GET /api/capabilities/search?q=order
+```
+
+**4. Map Capabilities to Existing ODs**
+- Use current OD builders
+- No need to refactor existing ODs yet
+
+**5. Chaos Management Foundation**
+```typescript
+// src/config/chaos-config.registry.ts
+class ChaosConfigRegistry {
+  loadPreset(presetId: string): ChaosPolicy;
+  listPresets(): PresetMetadata[];
+  isChaosEnabled(): boolean;  // Check CHAOS_ENABLED env var
+}
+```
+
+**6. Chaos Preset Files**
+```
+config/chaos-presets/
+├── light.json        # 0.05 probability
+├── moderate.json     # 0.15 probability
+├── aggressive.json   # 0.3 probability
+└── realistic.json    # 0.08 probability (real-world distribution)
+```
+
+**7. Environment Variable Support**
+```bash
+CHAOS_ENABLED=true|false      # Master kill-switch
+CHAOS_PRESET=moderate         # Default preset
+CHAOS_GLOBAL_PROBABILITY=0.1  # Override probability
+```
+
+### What We're NOT Building Yet
+- ❌ MongoDB persistence (file-based is fine)
+- ❌ Knowledge graph
+- ❌ World configuration
+- ❌ Persona mapping
+- ❌ OD variants (just 1:1 mapping for now)
+
+### Success Criteria
+- ✅ 30 capabilities defined and discoverable
+- ✅ Filtering works correctly
+- ✅ All capabilities executable
+- ✅ Researchers can find what they need
+- ✅ **Chaos presets work with env var control**
+- ✅ **CHAOS_ENABLED=false disables all chaos**
+
+### Decision Point
+**After Phase 1**: Are 30 capabilities enough? Is tagging working? Do we need hierarchy? **Are chaos presets sufficient?**
+
+**Effort**: 3-4 weeks (1-2 developers)
+- Define 30 capabilities: 1 week
+- Build registry service: 1 week
+- API endpoints: 1 week
+- **Chaos presets & registry: 3 days**
+- Testing & docs: 1 week
+
+---
+
+## Phase 2: World Configuration (2-3 weeks)
+
+### Goal
+Enable researchers to create custom worlds with capability sampling.
+
+### What Researchers Can Do
+- Create world with specific capabilities (filter-based selection)
+- Sample capabilities randomly or by criteria
+- Execute capabilities within configured world
+- World configuration is immutable after creation
+- **Configure chaos at world level** (preset-based)
+- **Reproducible chaos** with seeds
+
+### Deliverables
+
+**1. World Configuration Schema**
+```yaml
+world:
+  id: "research-001"
+  name: "Warehouse Operations Study"
+  capabilities:
+    filters:
+      domains: [warehousing, inventory]
+      complexity: [simple, medium]
+  chaos:
+    preset: "moderate"       # Use preset
+    seed: "repro-123"        # Reproducible chaos
+```
+
+**2. World Configuration API**
+```
+POST   /api/worlds                # Create world with config
+GET    /api/worlds/:worldId       # Get world details
+GET    /api/worlds/:worldId/capabilities  # List capabilities in world
+POST   /api/worlds/:worldId/capabilities/:capId/execute  # Execute in world context
+```
+
+**3. Sampling Strategies** (start simple)
+- Filter-based selection (domain, complexity, etc.)
+- Random sampling with count
+- Seed support for reproducibility
+
+**4. World-Scoped Execution**
+- Execute ODs in world context
+- Isolated data per world (already supported)
+
+**5. World-Level Chaos Configuration**
+```typescript
+// Update ChaosConfigRegistry
+class ChaosConfigRegistry {
+  // Add world-level chaos resolution
+  getWorldChaosPolicy(worldId: string): ChaosPolicy;
+  setWorldChaosPolicy(worldId: string, policy: ChaosPolicy): void;
+
+  // Resolve chaos with world context
+  resolveChaosPolicy(context: ChaosContext): ChaosPolicy;
+}
+```
+- Apply preset to world
+- Support chaos seed for reproducibility
+- Chaos inherits to all capabilities in world
+
+### What We're NOT Building Yet
+- ❌ MongoDB persistence (in-memory registry is fine)
+- ❌ Dependency validation
+- ❌ Persona-based filtering
+- ❌ Complex sampling (weighted, hierarchical, graph-based)
+- ❌ World mutation after creation
+- ❌ **Capability-level chaos overrides** (comes in Phase 4)
+
+### Success Criteria
+- ✅ Researcher can create world with filtered capabilities
+- ✅ World shows only selected capabilities
+- ✅ Capabilities execute correctly in world context
+- ✅ Sampling is reproducible with seed
+- ✅ **Chaos configured at world level**
+- ✅ **Same seed produces identical chaos across runs**
+
+### Decision Point
+**After Phase 2**: Are filter-based and random sampling sufficient? Do we need weighted/hierarchical? **Is world-level chaos enough or need capability-level?**
+
+**Effort**: 2-3 weeks (1 developer)
+- World config schema: 3 days
+- Sampling logic: 1 week
+- API endpoints: 3 days
+- **World chaos integration: 2 days**
+- Testing: 3 days
+
+---
+
+## Phase 3: Knowledge Graph Basics (3-4 weeks)
+
+### Goal
+Add dependency validation and basic capability suggestions using a simple knowledge graph.
+
+### What Researchers Can Do
+- Validate that a capability is executable (has all dependencies)
+- Get warned about missing prerequisites
+- See "related capabilities" suggestions
+- Validate OD feasibility before execution
+
+### Deliverables
+
+**1. Manual Tool Annotations**
+```typescript
+// Add to existing service tool definitions
+{
+  tool: "createOrder",
+  produces: ["Order"],
+  requires: ["Customer", "Product"],
+  service: "erp"
+}
+```
+
+**2. In-Memory Knowledge Graph**
+```typescript
+// src/services/knowledge-graph.service.ts
+class KnowledgeGraph {
+  // Nodes: Services, Tools, Entities, Capabilities
+  // Edges: uses, produces, requires, exposed_by
+
+  validateOD(odId: string): ValidationResult;
+  findCapabilities(filters: any): Capability[];
+  suggestRelated(capabilityId: string): Capability[];
+}
+```
+
+**3. Dependency Validation**
+- Check if OD has all required tools
+- Check if tools have required data
+- Warn if dependencies missing
+
+**4. Enhanced API**
+```
+GET /api/capabilities/:id/validate      # Validate capability is executable
+GET /api/capabilities/:id/dependencies  # List dependencies
+GET /api/capabilities/:id/related       # Suggest related capabilities
+```
+
+### What We're NOT Building Yet
+- ❌ MongoDB persistence for graph (rebuild on startup is fine)
+- ❌ Runtime learning
+- ❌ Static analysis of code
+- ❌ Complex graph queries
+- ❌ OD discovery/suggestion (just validation)
+
+### Success Criteria
+- ✅ Can validate if capability is executable
+- ✅ Warnings shown for missing dependencies
+- ✅ Related capabilities suggested accurately
+- ✅ Graph loads quickly on startup
+
+### Decision Point
+**After Phase 3**: Is manual annotation sustainable? Do we need static analysis? Is validation useful?
+
+**Effort**: 3-4 weeks (1-2 developers)
+- Annotate tools: 1 week (15-20 critical tools)
+- Build graph structure: 1 week
+- Validation logic: 1 week
+- API & testing: 1 week
+
+---
+
+## Phase 4: Advanced Features (3-4 weeks)
+
+### Goal
+Add persona system and advanced chaos integration.
+
+### What Researchers Can Do
+- Filter capabilities by persona
+- Create worlds with persona-based access
+- Configure chaos at world/capability level with full priority cascade
+- Analyze chaos impact through detailed telemetry
+
+### Deliverables
+
+**1. Persona System** (~15-20 personas)
+```yaml
+# config/personas.yaml
+personas:
+  - id: store-manager
+    name: Store Manager
+    description: Manages store operations
+    capabilities:
+      - order-fulfillment
+      - inventory-management
+      - exception-handling
+```
+
+**2. Persona-Based Filtering**
+```
+GET /api/capabilities?persona=store-manager
+GET /api/personas                  # List all personas
+GET /api/personas/:id/capabilities # Capabilities for persona
+```
+
+**3. Advanced Chaos Features**
+```yaml
+world:
+  chaos:
+    preset: "moderate"
+    # Capability-level overrides
+    capabilityOverrides:
+      order-fulfillment:
+        probability: 0.3
+        scenarios:
+          - type: missing_data
+            weight: 10
+      inventory-check:
+        probability: 0.0  # No chaos for critical path
+```
+
+**Chaos Configuration Priority Cascade**:
+```typescript
+// Implement full priority cascade
+class ChaosConfigRegistry {
+  resolveChaosPolicy(context: ChaosContext): ChaosPolicy {
+    // 1. Check master kill-switch (CHAOS_ENABLED)
+    // 2. Step-level override (from OD)
+    // 3. OD-level policy
+    // 4. Capability-level override
+    // 5. World-level policy
+    // 6. System default
+  }
+}
+```
+
+**Chaos Telemetry**:
+```typescript
+// Enhanced logging for chaos injections
+{
+  chaosInjected: true,
+  scenarioType: "stale_data",
+  configSource: "capability-override",
+  probability: 0.3,
+  seed: "repro-123"
+}
+```
+
+**4. World Persona Overrides**
+```yaml
+world:
+  personaOverrides:
+    custom-agent:
+      capabilities: [order-fulfillment, inventory-check]
+```
+
+### What We're NOT Building Yet
+- ❌ MongoDB persistence (still file-based)
+- ❌ Complex persona hierarchies
+- ❌ Dynamic persona creation UI
+- ❌ OD Variants (deferred to Phase 6)
+
+### Success Criteria
+- ✅ Personas defined and queryable
+- ✅ Can filter capabilities by persona
+- ✅ **Capability-level chaos overrides functional**
+- ✅ **Chaos priority cascade implemented correctly**
+- ✅ **Chaos telemetry logs all injections**
+- ✅ Custom personas can be created per world
+
+### Decision Point
+**After Phase 4**: Are personas granular enough? **Is chaos telemetry providing useful insights?**
+
+**Effort**: 3-4 weeks (2 developers)
+- Define personas: 1 week
+- Persona filtering: 1 week
+- **Advanced chaos features**: 1 week
+  - Capability-level overrides
+  - Priority cascade implementation
+  - Enhanced telemetry
+- Testing & docs: 1 week
+
+---
+
+## Phase 5: Polish & Scale (Ongoing)
+
+### Goal
+Production-ready system with performance, persistence, and documentation.
+
+### What Researchers Can Do
+- Use system at scale (100+ capabilities, 50+ personas)
+- Advanced sampling strategies
+- Comprehensive documentation
+- Performance monitoring
+
+### Deliverables
+
+**1. MongoDB Persistence**
+- Capabilities collection
+- Personas collection
+- Worlds collection
+- Knowledge graph nodes/edges
+
+**2. Performance Optimization**
+- Caching for capability queries
+- Efficient graph queries
+- Pagination for large result sets
+
+**3. Advanced Sampling**
+- Weighted sampling
+- Hierarchical sampling
+- Graph-based sampling
+
+**4. Comprehensive Documentation**
+- API reference
+- Researcher guide
+- Capability cookbook
+- Migration guide from old system
+
+**5. Monitoring & Telemetry**
+- Usage metrics
+- Performance metrics
+- Error tracking
+
+**6. Chaos Management API & Tools**
+```
+# Chaos configuration endpoints
+GET    /api/chaos/presets                    # List presets
+GET    /api/chaos/presets/:id                # Get preset
+POST   /api/chaos/presets                    # Create custom preset
+PUT    /api/worlds/:worldId/chaos            # Update world chaos
+GET    /api/chaos/metrics?worldId=...        # Chaos impact metrics
+POST   /api/chaos/test                       # Test chaos (dry run)
+```
+
+**7. Chaos Impact Analysis**
+- Chaos metrics aggregation (injection counts, scenario distribution)
+- Success rate correlation (with vs without chaos)
+- Chaos impact reports
+- A/B testing tools (compare chaos variants)
+
+**8. Migration from Scattered Chaos Configs**
+- Extract chaos from 14+ existing files
+- Convert to centralized presets
+- Update builders to use ChaosConfigRegistry
+- Deprecation warnings for inline chaos
+
+### Success Criteria
+- ✅ System handles 100+ capabilities
+- ✅ Query performance < 100ms
+- ✅ Complete documentation
+- ✅ Migration plan for existing ODs
+- ✅ **Chaos configuration API fully functional**
+- ✅ **All scattered chaos configs migrated to presets**
+- ✅ **Chaos impact analysis provides actionable insights**
+
+**Effort**: Ongoing (2+ developers)
+
+---
+
+## Migration Strategy
+
+### Backward Compatibility
+
+**Phase 0-2**: New system runs alongside old
+- Existing OD builders continue working
+- New capability API available but optional
+- No breaking changes
+
+**Phase 3-4**: Encourage migration
+- Document migration path
+- Create capabilities for common ODs
+- Deprecation warnings for old patterns
+
+**Phase 5**: Complete migration
+- All ODs accessible via capabilities
+- Old builders deprecated but still functional
+- Migration tooling to convert old → new
+
+### Coexistence Pattern
+
+```typescript
+// Old way (still works)
+const od = new GenericODBuilder()
+  .addStep(...)
+  .build();
+
+// New way (recommended)
+const capability = await capabilityRegistry.get("order-fulfillment");
+await capability.execute(worldId, inputs);
+```
+
+---
+
+## Phase 6: OD Variants (Future)
+
+### Goal
+Support multiple implementation approaches for the same capability through OD variants.
+
+### What Researchers Can Do
+- Choose OD variants (simple vs complex implementations)
+- Select complexity-based variants for capabilities
+- Use chaos-focused variants with different chaos presets
+- Execute capabilities with variant-specific configurations
+
+### Deliverables
+
+**1. OD Variant Type System**
+```typescript
+// Capability can have multiple OD implementation variants
+capability:
+  id: order-fulfillment
+  variants:
+    # Complexity variants
+    - id: order-fulfillment-simple
+      complexity: simple
+      odId: "order-fulfillment-simple-v1"
+    - id: order-fulfillment-standard
+      complexity: medium
+      odId: "order-fulfillment-standard-v1"
+    - id: order-fulfillment-complex
+      complexity: complex
+      odId: "order-fulfillment-complex-v1"
+```
+
+**2. Complexity Variants**
+- Convert 3-5 high-value capabilities to variant model
+- Each capability has 2-3 variants (simple/medium/complex)
+- Different OD implementations for different complexity levels
+
+**3. Chaos Variants**
+```yaml
+# Same workflow, different chaos configurations
+capability:
+  variants:
+    - id: inventory-check-no-chaos
+      chaos: { enabled: false }
+      odId: "inventory-check-standard-v1"
+    - id: inventory-check-light
+      chaos: { preset: "light" }
+      odId: "inventory-check-standard-v1"
+    - id: inventory-check-aggressive
+      chaos: { preset: "aggressive" }
+      odId: "inventory-check-standard-v1"
+```
+
+**4. Variant Selection API**
+```
+GET  /capabilities/:id/variants        # List all variants
+POST /capabilities/:id/execute
+{
+  "worldId": "...",
+  "inputs": {...},
+  "options": {
+    "variantId": "order-fulfillment-complex"  // or
+    "complexity": "medium"
+  }
+}
+```
+
+### What We're NOT Building Yet
+- ❌ N:M composition (multiple ODs combined)
+- ❌ Dynamic variant generation
+- ❌ Variant recommendations
+
+### Success Criteria
+- ✅ 3-5 capabilities with complexity variants
+- ✅ Variant selection working (by ID and complexity)
+- ✅ Chaos variants functional
+- ✅ All variant tests passing
+- ✅ API documentation complete
+
+### Decision Point
+**After Phase 6**: Is 1:N variant mapping sufficient? Do we need N:M composition?
+
+**Effort**: 1-2 weeks (1 developer)
+- Variant type system: 1 day
+- Complexity variants (3-5 capabilities): 2-3 days
+- Capability executor updates: 1 day
+- Variant selection API: 1 day
+- Chaos variants: 1 day
+- Testing & docs: 1-2 days
+
+**Note**: This phase is deprioritized and will be scheduled based on research needs after Phase 5 is complete.
+
+---
+
+## Risk Mitigation
+
+### Major Risks
+
+**1. Scope Creep**
+- **Mitigation**: Each phase has clear "NOT building" list. Defer aggressively.
+
+**2. Over-Engineering**
+- **Mitigation**: Start simple, add complexity only when needed.
+
+**3. Changing Requirements**
+- **Mitigation**: Decision points after each phase. Can pivot based on learnings.
+
+**4. Adoption**
+- **Mitigation**: Backward compatibility. Researchers can adopt incrementally.
+
+**5. Performance**
+- **Mitigation**: Deferred to Phase 5. Measure early, optimize when needed.
+
+### Flexibility Points
+
+**Can Easily Change**:
+- Number of capabilities (30 → 50 → 100)
+- Sampling strategies
+- Tag vocabulary
+- Persona definitions
+
+**Hard to Change Later**:
+- Capability ↔ OD relationship (1:1 vs 1:N vs N:M)
+- Knowledge graph structure
+- API design
+
+**Strategy**: Lock hard-to-change early, keep easy-to-change flexible.
+
+---
+
+## Decision Points & Metrics
+
+### After Each Phase
+
+**Questions to Answer**:
+1. Did we deliver value to researchers?
+2. Were our assumptions correct?
+3. What surprised us?
+4. What should we adjust?
+
+**Metrics to Track**:
+- API usage (which endpoints are popular?)
+- Capability execution counts (which are used most?)
+- Error rates (where do things fail?)
+- Researcher feedback (qualitative)
+
+### Go/No-Go Criteria
+
+**Continue to next phase if**:
+- ✅ Current phase delivered promised value
+- ✅ Researchers are using the features
+- ✅ No major architectural issues discovered
+
+**Pivot or adjust if**:
+- ❌ Low adoption
+- ❌ Fundamental design flaw found
+- ❌ Requirements changed significantly
+
+---
+
+## Effort Summary
+
+| Phase | Duration | Team Size | Focus |
+|-------|----------|-----------|-------|
+| Phase 0: Walking Skeleton | 2-3 weeks | 1 dev | Proof of concept |
+| Phase 1: Core System | 3-4 weeks | 1-2 devs | Capability browsing |
+| Phase 2: World Config | 2-3 weeks | 1 dev | Customization |
+| Phase 3: Knowledge Graph | 3-4 weeks | 1-2 devs | Validation |
+| Phase 4: Advanced Features | 3-4 weeks | 2 devs | Personas & chaos |
+| Phase 5: Polish & Scale | Ongoing | 2+ devs | Production-ready |
+| Phase 6: OD Variants | 1-2 weeks | 1 dev | Variant system (Future) |
+
+**Total to MVP (Phase 0-2)**: 7-10 weeks
+**Total to Full Feature Set (Phase 0-4)**: 13-17 weeks (~3-4 months)
+**Total with OD Variants (Phase 0-6)**: 14-19 weeks (~3.5-5 months)
+
+---
+
+## Success Metrics
+
+### Phase 0 Success
+- Concept validated
+- Team aligned on approach
+
+### Phase 1-2 Success
+- 10+ researchers using capability API
+- 50+ capability executions per week
+
+### Phase 3-4 Success
+- Dependency validation prevents 80% of execution errors
+- Personas used in 50% of world configurations
+
+### Phase 5 Success
+- 100+ capabilities defined
+- < 100ms query performance
+- Migration complete for 80% of existing ODs
+
+---
+
+## Related Documents
+
+- [02. Conceptual Model](./02-conceptual-model.md) - Architecture we're implementing
+- [06. Open Questions & Decisions](./06-open-questions.md) - Decisions guiding this roadmap
+- [07. Chaos Integration](./07-chaos-integration.md) - How chaos integrates with OD architecture
+- [04. Taxonomy & Organization](./04-taxonomy-organization.md) - How capabilities are organized
+- [05. Sampling & World Config](./05-sampling-world-config.md) - World configuration details
+- [Chaos Management](../chaos/chaos-management.md) - Complete chaos system design
+
+---
+
+## Next Steps
+
+1. **Review roadmap** with team and stakeholders
+2. **Get approval** for Phase 0 start
+3. **Create Phase 0 task breakdown** (detailed stories)
+4. **Assign developer(s)** to Phase 0
+5. **Set up** project tracking (GitHub issues, board, etc.)
+6. **Start Phase 0 implementation**
+7. **Review progress weekly**, adjust as needed
+
+**First Milestone**: Complete Phase 0 in 2-3 weeks, validate approach.

docs/od-architecture/09-implementation-tasks.md

@@ -0,0 +1,1548 @@
+# 09. Implementation Tasks Tracker
+
+## Overview
+
+This document serves as a master index for all implementation tasks across phases. Detailed task specifications are maintained in phase-specific files within the `implementation/` directory.
+
+**Last Updated**: 2025-11-21
+
+**How to Use**:
+1. Navigate to the appropriate phase folder: `implementation/phaseN/`
+2. Open `tasks.md` for detailed tickets
+3. Pick a ticket with status 📝 TODO
+4. Update status to 🚧 IN PROGRESS
+5. Complete the work according to acceptance criteria
+6. Update status to ✅ DONE
+
+**Status Key**:
+- 📝 **TODO**: Not started
+- 🚧 **IN PROGRESS**: Currently being worked on
+- ✅ **DONE**: Completed and tested
+- ❌ **BLOCKED**: Waiting on dependencies
+- ⏸️ **ON HOLD**: Paused, will resume later
+
+---
+
+## Phase Index
+
+### Phase 0: Walking Skeleton (2-3 weeks)
+
+**Epic**: MORPH-100 - Walking Skeleton
+
+**Goal**: Prove the concept works end-to-end with minimal implementation
+
+**Status**: ✅ **COMPLETED**
+
+**Documents**:
+- [Tasks](./implementation/phase0/tasks.md) - Detailed 12 tickets
+- [Demo Script](./implementation/phase0/demo.md) - Walkthrough
+- [Test Results](./implementation/phase0/test-results.md) - Test execution results
+
+**Summary**:
+- 12 tickets, ~21 story points
+- 5 capabilities implemented
+- API endpoints functional
+- End-to-end flow validated
+
+---
+
+### Phase 1: Core Capability System (3-4 weeks)
+
+**Epic**: MORPH-200 - Core Capability System
+
+**Goal**: Expand to 4 working capabilities with real OD execution, filtering, and chaos support
+
+**Status**: ✅ **COMPLETED**
+
+**Documents**:
+- [Tasks](./implementation/phase1/tasks.md) - Detailed 20 tickets
+- [Demo Script](./implementation/phase1/demo-script.md) - Walkthrough
+- [Test Results](./implementation/phase1/test-results.md) - Test execution results
+- [Retrospective](./implementation/phase1/retrospective.md) - Lessons learned
+
+**Summary**:
+- 20 tickets, ~57 story points
+- 4 working capabilities: inventory-check, shipment-tracking, equipment-availability-check, dock-appointment-scheduling
+- Real OD execution with chaos engineering
+- Search/filtering APIs functional
+- Performance baselines established
+- **Decision**: ✅ Proceed to Phase 2 (World Configuration)
+
+---
+
+### Phase 2: World Configuration (2.5-3 weeks)
+
+**Epic**: MORPH-300 - World Configuration
+
+**Goal**: Enable researchers to create custom worlds with capability sampling and chaos configuration
+
+**Status**: 📝 **TODO** (Ready to Start)
+
+**Documents**:
+- [Tasks](./implementation/phase2/tasks.md) - Detailed 10 tickets (REVISED)
+
+**Summary**:
+- 10 tickets, 22 story points (revised from 30 - **27% effort reduction**)
+- Extends existing World model (leverages 40% existing infrastructure)
+- Sampling strategies: filter, random, seeded
+- World-level chaos configuration with API endpoints
+- Capability-level chaos overrides
+- **Critical bug fix**: Capability executor chaos integration
+- Reproducibility via seeds for sampling and chaos
+
+---
+
+### Phase 3-5: Future Phases
+
+**Status**: 🔒 **LOCKED** (will be created after Phase 2 completion)
+
+See [08. Implementation Roadmap](./08-implementation-roadmap.md) for high-level phase definitions.
+
+---
+
+## Quick Navigation
+
+| Phase | Status | Tasks | Demo | Tests | Retro |
+|-------|--------|-------|------|-------|-------|
+| Phase 0 | ✅ DONE | [tasks](./implementation/phase0/tasks.md) | [demo](./implementation/phase0/demo.md) | [tests](./implementation/phase0/test-results.md) | - |
+| Phase 1 | ✅ DONE | [tasks](./implementation/phase1/tasks.md) | [demo](./implementation/phase1/demo-script.md) | [tests](./implementation/phase1/test-results.md) | [retro](./implementation/phase1/retrospective.md) |
+| Phase 2 | 📝 TODO | [tasks](./implementation/phase2/tasks.md) | - | - | - |
+| Phase 3+ | 🔒 LOCKED | - | - | - | - |
+
+---
+
+## Historical Detail (Archived)
+
+The content below has been moved to phase-specific `tasks.md` files. This section is kept for reference only.
+
+<details>
+<summary>Phase 0 Tickets (ARCHIVED - See implementation/phase0/tasks.md)</summary>
+
+### MORPH-101: Project Setup & Type Definitions
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 2 points (1 day)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Set up project structure and create TypeScript type definitions for capabilities.
+
+**Acceptance Criteria**:
+- [  ] Folder structure created: `src/capabilities/`
+- [  ] Type definitions file created: `src/types/capability.type.ts`
+- [  ] Core types defined: `Capability`, `CapabilityMetadata`, `CapabilityTags`
+- [  ] Types compile without errors
+- [  ] Types exported properly
+
+**Technical Details**:
+```typescript
+// src/types/capability.type.ts
+export interface Capability {
+  id: string;
+  name: string;
+  description: string;
+  tags: CapabilityTags;
+  odId: string;  // Maps to existing OD
+  version: string;
+  metadata?: CapabilityMetadata;
+}
+
+export interface CapabilityTags {
+  domain: string[];
+  complexity: 'simple' | 'medium' | 'complex';
+  services: string[];
+  personas?: string[];
+}
+
+export interface CapabilityMetadata {
+  author?: string;
+  createdAt?: Date;
+  estimatedDuration?: number;
+}
+```
+
+**Dependencies**: None
+
+**Testing**:
+- Types compile successfully
+- Can import types in other files
+
+---
+
+### MORPH-102: Create 5 Hardcoded Capabilities
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 3 points (1 day)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Create a hardcoded catalog of 5 example capabilities spanning different domains and complexity levels.
+
+**Acceptance Criteria**:
+- [  ] File created: `src/capabilities/catalog.ts`
+- [  ] 5 capabilities defined with complete metadata
+- [  ] Covers at least 3 different domains
+- [  ] Mix of simple, medium, complex
+- [  ] Each capability maps to an existing OD
+- [  ] Data exported as constant array
+
+**Technical Details**:
+```typescript
+// src/capabilities/catalog.ts
+import { Capability } from '../types/capability.type';
+
+export const INITIAL_CAPABILITIES: Capability[] = [
+  {
+    id: 'order-fulfillment-simple',
+    name: 'Order Fulfillment (Simple)',
+    description: 'Process customer order with basic workflow',
+    tags: {
+      domain: ['fulfillment', 'order-processing'],
+      complexity: 'simple',
+      services: ['erp', 'wms']
+    },
+    odId: 'order-fulfillment-standard-v1',  // Existing OD
+    version: '1.0.0'
+  },
+  // ... 4 more
+];
+```
+
+**Capabilities to Create**:
+1. **order-fulfillment-simple** (Fulfillment, Simple, ERP+WMS)
+2. **inventory-check** (Inventory, Simple, WMS)
+3. **inbound-receiving** (Warehousing, Medium, TMS+WMS)
+4. **edi-850-generation** (EDI, Medium, EDI+ERP)
+5. **shipment-tracking** (Transportation, Simple, TMS)
+
+**Dependencies**: MORPH-101
+
+**Testing**:
+- Catalog imports successfully
+- All 5 capabilities have required fields
+- OD IDs reference existing ODs
+
+---
+
+### MORPH-103: Build Capability Catalog Service
+
+**Type**: Story
+**Priority**: High
+**Estimate**: 3 points (1.5 days)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Create an in-memory capability catalog service with basic query methods.
+
+**Acceptance Criteria**:
+- [  ] File created: `src/services/capability-catalog.service.ts`
+- [  ] `CapabilityCatalog` class implemented
+- [  ] Method: `getAll()` returns all capabilities
+- [  ] Method: `getById(id)` returns single capability or null
+- [  ] Method: `filter(tags)` returns filtered capabilities
+- [  ] Service is a singleton
+- [  ] Loads from hardcoded catalog on initialization
+
+**Technical Details**:
+```typescript
+// src/services/capability-catalog.service.ts
+import { Capability, CapabilityTags } from '../types/capability.type';
+import { INITIAL_CAPABILITIES } from '../capabilities/catalog';
+
+class CapabilityCatalog {
+  private capabilities: Map<string, Capability>;
+
+  constructor() {
+    this.capabilities = new Map();
+    this.loadCapabilities();
+  }
+
+  private loadCapabilities(): void {
+    INITIAL_CAPABILITIES.forEach(cap => {
+      this.capabilities.set(cap.id, cap);
+    });
+  }
+
+  getAll(): Capability[] {
+    return Array.from(this.capabilities.values());
+  }
+
+  getById(id: string): Capability | null {
+    return this.capabilities.get(id) || null;
+  }
+
+  filter(filters: Partial<CapabilityTags>): Capability[] {
+    return this.getAll().filter(cap => {
+      if (filters.domain && !filters.domain.some(d => cap.tags.domain.includes(d))) {
+        return false;
+      }
+      if (filters.complexity && cap.tags.complexity !== filters.complexity) {
+        return false;
+      }
+      if (filters.services && !filters.services.every(s => cap.tags.services.includes(s))) {
+        return false;
+      }
+      return true;
+    });
+  }
+}
+
+// Singleton
+export const capabilityCatalog = new CapabilityCatalog();
+```
+
+**Dependencies**: MORPH-101, MORPH-102
+
+**Testing**:
+- `getAll()` returns 5 capabilities
+- `getById('order-fulfillment-simple')` returns correct capability
+- `filter({ domain: ['fulfillment'] })` returns matching capabilities
+- `filter({ complexity: 'simple' })` returns 3 simple capabilities
+
+---
+
+### MORPH-104: Create GET /api/capabilities Endpoint
+
+**Type**: Story
+**Priority**: High
+**Estimate**: 2 points (1 day)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Create REST API endpoint to list all capabilities with optional filtering.
+
+**Acceptance Criteria**:
+- [  ] Route created: `src/routes/capabilities.route.ts`
+- [  ] `GET /api/capabilities` returns all capabilities
+- [  ] Query params supported: `domain`, `complexity`, `services`
+- [  ] Returns JSON array of capabilities
+- [  ] Proper HTTP status codes (200, 400)
+- [  ] Route registered in main app
+
+**Technical Details**:
+```typescript
+// src/routes/capabilities.route.ts
+import { Router } from 'express';
+import { capabilityCatalog } from '../services/capability-catalog.service';
+
+const router = Router();
+
+router.get('/', (req, res) => {
+  try {
+    const { domain, complexity, services } = req.query;
+
+    const filters: any = {};
+    if (domain) filters.domain = Array.isArray(domain) ? domain : [domain];
+    if (complexity) filters.complexity = complexity;
+    if (services) filters.services = Array.isArray(services) ? services : [services];
+
+    const capabilities = Object.keys(filters).length > 0
+      ? capabilityCatalog.filter(filters)
+      : capabilityCatalog.getAll();
+
+    res.json(capabilities);
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+export default router;
+```
+
+**API Examples**:
+```bash
+# Get all capabilities
+GET /api/capabilities
+→ Returns: [5 capabilities]
+
+# Filter by domain
+GET /api/capabilities?domain=fulfillment
+→ Returns: [1-2 capabilities]
+
+# Filter by complexity
+GET /api/capabilities?complexity=simple
+→ Returns: [3 capabilities]
+
+# Multiple filters
+GET /api/capabilities?domain=fulfillment&complexity=simple
+→ Returns: [1 capability]
+```
+
+**Dependencies**: MORPH-103
+
+**Testing**:
+- Manual curl/Postman tests
+- Returns correct number of capabilities
+- Filtering works correctly
+- Invalid filters return 400
+
+---
+
+### MORPH-105: Create GET /api/capabilities/:id Endpoint
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 1 point (0.5 days)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Create REST API endpoint to get details of a single capability.
+
+**Acceptance Criteria**:
+- [  ] `GET /api/capabilities/:id` returns capability details
+- [  ] Returns 404 if capability not found
+- [  ] Returns 200 with capability JSON if found
+- [  ] Includes all capability metadata
+
+**Technical Details**:
+```typescript
+// Add to src/routes/capabilities.route.ts
+router.get('/:id', (req, res) => {
+  const { id } = req.params;
+  const capability = capabilityCatalog.getById(id);
+
+  if (!capability) {
+    return res.status(404).json({ error: 'Capability not found' });
+  }
+
+  res.json(capability);
+});
+```
+
+**API Examples**:
+```bash
+# Get capability details
+GET /api/capabilities/order-fulfillment-simple
+→ Returns: { id: "order-fulfillment-simple", ... }
+
+# Not found
+GET /api/capabilities/non-existent
+→ Returns 404: { error: "Capability not found" }
+```
+
+**Dependencies**: MORPH-104
+
+**Testing**:
+- Valid ID returns capability
+- Invalid ID returns 404
+- Response includes all fields
+
+---
+
+### MORPH-106: Build Capability → OD Mapper Service
+
+**Type**: Story
+**Priority**: High
+**Estimate**: 2 points (1 day)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Create service that maps capability IDs to existing OD builders and executes them.
+
+**Acceptance Criteria**:
+- [  ] File created: `src/services/capability-executor.service.ts`
+- [  ] `CapabilityExecutor` class implemented
+- [  ] Method: `execute(capabilityId, inputs)` runs OD
+- [  ] Uses existing OD builders (no refactoring)
+- [  ] Returns OD execution results
+- [  ] Handles errors gracefully
+
+**Technical Details**:
+```typescript
+// src/services/capability-executor.service.ts
+import { capabilityCatalog } from './capability-catalog.service';
+import { executeOD } from '../operational-descriptor/executor.od';
+
+export class CapabilityExecutor {
+  async execute(
+    capabilityId: string,
+    worldId: string,
+    inputs: any
+  ): Promise<any> {
+    // 1. Get capability
+    const capability = capabilityCatalog.getById(capabilityId);
+    if (!capability) {
+      throw new Error(`Capability not found: ${capabilityId}`);
+    }
+
+    // 2. Get OD (for now, assume OD exists in registry)
+    const odId = capability.odId;
+
+    // 3. Execute OD using existing executor
+    const result = await executeOD(odId, worldId, inputs);
+
+    return {
+      capabilityId,
+      odId,
+      worldId,
+      result,
+      executedAt: new Date()
+    };
+  }
+}
+
+export const capabilityExecutor = new CapabilityExecutor();
+```
+
+**Dependencies**: MORPH-103
+
+**Testing**:
+- Can execute order-fulfillment-simple
+- Returns proper result structure
+- Throws error for non-existent capability
+- OD execution works correctly
+
+---
+
+### MORPH-107: Create POST /api/capabilities/:id/execute Endpoint
+
+**Type**: Story
+**Priority**: High
+**Estimate**: 2 points (1 day)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Create REST API endpoint to execute a capability.
+
+**Acceptance Criteria**:
+- [  ] `POST /api/capabilities/:id/execute` endpoint created
+- [  ] Accepts `worldId` and `inputs` in request body
+- [  ] Executes capability via CapabilityExecutor
+- [  ] Returns execution results
+- [  ] Proper error handling (404, 400, 500)
+- [  ] Request validation
+
+**Technical Details**:
+```typescript
+// Add to src/routes/capabilities.route.ts
+router.post('/:id/execute', async (req, res) => {
+  try {
+    const { id } = req.params;
+    const { worldId, inputs } = req.body;
+
+    // Validation
+    if (!worldId) {
+      return res.status(400).json({ error: 'worldId is required' });
+    }
+
+    // Execute
+    const result = await capabilityExecutor.execute(id, worldId, inputs);
+
+    res.json(result);
+  } catch (error) {
+    if (error.message.includes('not found')) {
+      return res.status(404).json({ error: error.message });
+    }
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+**API Examples**:
+```bash
+# Execute capability
+POST /api/capabilities/order-fulfillment-simple/execute
+Body: {
+  "worldId": "world-123",
+  "inputs": {
+    "orderId": "ORD-001"
+  }
+}
+→ Returns: {
+  "capabilityId": "order-fulfillment-simple",
+  "odId": "order-fulfillment-standard-v1",
+  "result": { ... },
+  "executedAt": "2025-11-14T10:30:00Z"
+}
+```
+
+**Dependencies**: MORPH-106
+
+**Testing**:
+- Successful execution returns results
+- Missing worldId returns 400
+- Invalid capability ID returns 404
+- OD execution errors return 500
+
+---
+
+### MORPH-108: Register Capability Routes in App
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 1 point (0.5 days)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Register the new capability routes in the main Express app.
+
+**Acceptance Criteria**:
+- [  ] Capability routes mounted in main app
+- [  ] Routes accessible via `/api/capabilities`
+- [  ] Routes work in development environment
+- [  ] No breaking changes to existing routes
+
+**Technical Details**:
+```typescript
+// In main app file (e.g., src/app.ts or src/index.ts)
+import capabilitiesRouter from './routes/capabilities.route';
+
+// Register routes
+app.use('/api/capabilities', capabilitiesRouter);
+```
+
+**Dependencies**: MORPH-107
+
+**Testing**:
+- All capability endpoints accessible
+- Existing routes still work
+- Server starts without errors
+
+---
+
+### MORPH-109: Integration Testing
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: ⏸️ ON HOLD
+**Note**: Requires MongoDB setup - will complete after environment setup
+
+**Description**:
+Create integration tests for the end-to-end capability flow.
+
+**Acceptance Criteria**:
+- [  ] Test file created: `tests/capabilities.integration.test.ts`
+- [  ] Test: List all capabilities
+- [  ] Test: Get capability by ID
+- [  ] Test: Filter capabilities
+- [  ] Test: Execute capability end-to-end
+- [  ] All tests pass
+
+**Technical Details**:
+```typescript
+// tests/capabilities.integration.test.ts
+describe('Capabilities API', () => {
+  describe('GET /api/capabilities', () => {
+    it('should return all 5 capabilities', async () => {
+      const res = await request(app).get('/api/capabilities');
+      expect(res.status).toBe(200);
+      expect(res.body).toHaveLength(5);
+    });
+
+    it('should filter by domain', async () => {
+      const res = await request(app)
+        .get('/api/capabilities?domain=fulfillment');
+      expect(res.status).toBe(200);
+      expect(res.body.every(c => c.tags.domain.includes('fulfillment'))).toBe(true);
+    });
+  });
+
+  describe('GET /api/capabilities/:id', () => {
+    it('should return capability details', async () => {
+      const res = await request(app)
+        .get('/api/capabilities/order-fulfillment-simple');
+      expect(res.status).toBe(200);
+      expect(res.body.id).toBe('order-fulfillment-simple');
+    });
+
+    it('should return 404 for invalid ID', async () => {
+      const res = await request(app)
+        .get('/api/capabilities/invalid');
+      expect(res.status).toBe(404);
+    });
+  });
+
+  describe('POST /api/capabilities/:id/execute', () => {
+    it('should execute capability', async () => {
+      const res = await request(app)
+        .post('/api/capabilities/order-fulfillment-simple/execute')
+        .send({
+          worldId: 'test-world',
+          inputs: { orderId: 'TEST-001' }
+        });
+      expect(res.status).toBe(200);
+      expect(res.body.capabilityId).toBe('order-fulfillment-simple');
+      expect(res.body.result).toBeDefined();
+    });
+  });
+});
+```
+
+**Dependencies**: MORPH-108
+
+**Testing**:
+- Run tests: `npm test`
+- All tests pass
+- Coverage > 80%
+
+---
+
+### MORPH-110: API Documentation
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Document the new capability API endpoints.
+
+**Acceptance Criteria**:
+- [  ] Document created: `docs/api/capabilities.md`
+- [  ] All 3 endpoints documented
+- [  ] Request/response examples provided
+- [  ] Error codes documented
+- [  ] Example curl commands included
+
+**Technical Details**:
+```markdown
+# Capabilities API
+
+## Endpoints
+
+### GET /api/capabilities
+List all capabilities with optional filtering.
+
+**Query Parameters**:
+- `domain` (string[]): Filter by domain
+- `complexity` (string): Filter by complexity
+- `services` (string[]): Filter by services
+
+**Example**:
+curl http://localhost:3000/api/capabilities?domain=fulfillment
+
+### GET /api/capabilities/:id
+Get details of a single capability.
+
+**Example**:
+curl http://localhost:3000/api/capabilities/order-fulfillment-simple
+
+### POST /api/capabilities/:id/execute
+Execute a capability.
+
+**Body**:
+{
+  "worldId": "string",
+  "inputs": object
+}
+
+**Example**:
+curl -X POST http://localhost:3000/api/capabilities/order-fulfillment-simple/execute \
+  -H "Content-Type: application/json" \
+  -d '{"worldId":"world-123","inputs":{"orderId":"ORD-001"}}'
+```
+
+**Dependencies**: MORPH-109
+
+**Testing**:
+- Documentation is clear
+- Examples work
+- Covers all endpoints
+
+---
+
+### MORPH-111: Phase 0 Demo Preparation
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 1 point (0.5 days)
+**Status**: ✅ DONE
+**Completed**: 2025-11-19
+
+**Description**:
+Prepare demo script and materials for Phase 0 review.
+
+**Acceptance Criteria**:
+- [  ] Demo script created
+- [  ] Example requests prepared (Postman/curl)
+- [  ] Can demonstrate end-to-end flow
+- [  ] Demo shows all 3 endpoints working
+- [  ] Demo execution is successful
+
+**Demo Script**:
+```bash
+# 1. List all capabilities
+curl http://localhost:3000/api/capabilities
+
+# 2. Filter by domain
+curl http://localhost:3000/api/capabilities?domain=fulfillment
+
+# 3. Get capability details
+curl http://localhost:3000/api/capabilities/order-fulfillment-simple
+
+# 4. Execute capability
+curl -X POST http://localhost:3000/api/capabilities/order-fulfillment-simple/execute \
+  -H "Content-Type: application/json" \
+  -d '{"worldId":"demo-world","inputs":{"orderId":"DEMO-001"}}'
+
+# 5. Show execution result
+```
+
+**Dependencies**: MORPH-110
+
+**Testing**:
+- Demo runs successfully
+- All endpoints work
+- Results are as expected
+
+---
+
+### MORPH-112: Phase 0 Retrospective & Decision
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 1 point (0.5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Conduct Phase 0 retrospective and make go/no-go decision for Phase 1.
+
+**Acceptance Criteria**:
+- [  ] Team demo completed
+- [  ] Feedback collected
+- [  ] Decision documented: Continue to Phase 1 or Pivot
+- [  ] Learnings documented for Phase 1 planning
+
+**Discussion Points**:
+1. Does this approach provide value to researchers?
+2. Is the API intuitive?
+3. Are we on the right track?
+4. What should we adjust for Phase 1?
+
+**Deliverables**:
+- Meeting notes
+- Decision: GO / NO-GO / PIVOT
+- Feedback incorporated into Phase 1 planning
+
+**Dependencies**: MORPH-111
+
+**Testing**:
+- Decision is clear
+- Feedback is actionable
+
+---
+
+## Phase 0 Summary
+
+**Total Tickets**: 12
+**Total Story Points**: 21 points (~2-3 weeks with 1 developer)
+
+**Ticket Breakdown**:
+- Setup & Foundation: 3 tickets (8 points)
+- Capability System: 4 tickets (8 points)
+- API Endpoints: 3 tickets (3 points)
+- Testing & Documentation: 2 tickets (2 points)
+
+**Critical Path**:
+MORPH-101 → MORPH-102 → MORPH-103 → MORPH-104 → MORPH-106 → MORPH-107 → MORPH-108 → MORPH-109
+
+**Parallelizable**:
+- MORPH-105 can be done alongside MORPH-106
+- MORPH-110 can be done alongside MORPH-109
+
+---
+
+</details>
+
+<details>
+<summary>Phase 1 Tickets (ARCHIVED - See implementation/phase1/tasks.md)</summary>
+
+### MORPH-201: Create OD Registry Service
+
+**Type**: Story
+**Priority**: High
+**Estimate**: 5 points (2-3 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Create a centralized OD Registry that maps capability IDs to actual OD builder functions. This registry will be used by the CapabilityExecutor to instantiate and build ODs for execution.
+
+**Acceptance Criteria**:
+- [ ] File created: `src/services/od-registry.service.ts`
+- [ ] `ODRegistry` class implemented with builder registration
+- [ ] Method: `registerBuilder(odId, builderFactory)` to register OD builders
+- [ ] Method: `getBuilder(odId)` returns builder factory or null
+- [ ] Method: `buildOD(odId, config)` builds and returns OD instance
+- [ ] Registry supports all existing OD builders (WMS, EDI, TMS)
+- [ ] Singleton pattern for global access
+- [ ] Initial registration for 5 Phase 0 ODs
+
+**Dependencies**: None (foundational)
+
+**Testing**:
+- Can register builder without error
+- Can retrieve registered builder
+- `buildOD()` returns valid OperationalDescriptor
+- Throws error for non-existent OD ID
+
+---
+
+### MORPH-202: Integrate Real OD Execution in CapabilityExecutor
+
+**Type**: Story
+**Priority**: High
+**Estimate**: 5 points (2-3 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Replace stub implementation in CapabilityExecutor with real OD execution using the OD Registry, world initialization, and existing OD executor.
+
+**Acceptance Criteria**:
+- [ ] Update `capability-executor.service.ts` to use real execution
+- [ ] Initialize world context using `initOperationalDescriptor()`
+- [ ] Build OD from registry using capability's `odId`
+- [ ] Execute OD using `executeOperationalDescriptor()`
+- [ ] Return properly formatted execution results
+- [ ] Handle errors gracefully with proper status codes
+- [ ] Include logger from capability execution context
+- [ ] Pass chaos policy from capability to OD
+
+**Dependencies**: MORPH-201
+
+**Testing**:
+- Execute order-fulfillment-simple returns real results
+- World context initialized correctly
+- OD executes with proper steps
+- Errors handled and returned with 'failed' status
+
+---
+
+### MORPH-203: Build 15 Additional OD Builders
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 8 points (4-5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Create 15 new OD builders to expand from 5 to 20 total capabilities. Focus on common supply chain workflows across WMS, EDI, TMS, and ERP domains.
+
+**Acceptance Criteria**:
+- [ ] 15 new OD builder functions created
+- [ ] Each builder registered in OD Registry
+- [ ] Mix of simple (5), medium (7), complex (3) workflows
+- [ ] Cover all major domains: fulfillment, inventory, warehousing, EDI, transportation
+- [ ] Use GenericODBuilder for consistent structure
+- [ ] Include appropriate chaos scenarios for each
+- [ ] All builders tested and working
+
+**OD Builders to Create**:
+1. inventory-adjustment-simple-v1 (Simple, WMS)
+2. shipment-status-check-v1 (Simple, TMS)
+3. edi-856-asn-generation-v1 (Simple, EDI)
+4. order-cancellation-simple-v1 (Simple, ERP)
+5. dock-schedule-query-v1 (Simple, WMS)
+6. cycle-count-workflow-v1 (Medium, WMS)
+7. outbound-picking-v1 (Medium, WMS)
+8. edi-810-invoice-v1 (Medium, EDI+ERP)
+9. cross-dock-workflow-v1 (Medium, WMS+TMS)
+10. replenishment-workflow-v1 (Medium, WMS)
+11. edi-855-po-ack-v1 (Medium, EDI)
+12. load-planning-v1 (Medium, TMS)
+13. returns-processing-v1 (Complex, ERP+WMS+TMS)
+14. wave-picking-v1 (Complex, WMS)
+15. multi-location-transfer-v1 (Complex, WMS+TMS)
+
+**Dependencies**: MORPH-201
+
+**Testing**:
+- Each OD builds successfully
+- ODs execute without errors (with mock data)
+- Step structure is valid
+
+---
+
+### MORPH-204: Expand Capability Catalog to 20 Capabilities
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 3 points (1.5-2 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Add 15 new capability definitions to the catalog, mapping to the new OD builders. Ensure comprehensive metadata, tags, and descriptions.
+
+**Acceptance Criteria**:
+- [ ] Add 15 new capabilities to `catalog.ts`
+- [ ] Each capability maps to an OD from MORPH-203
+- [ ] Complete metadata: description, tags, personas, patterns
+- [ ] Estimated durations realistic
+- [ ] Exported as `EXPANDED_CAPABILITIES` array
+- [ ] Update CapabilityCatalog to load expanded set
+
+**Dependencies**: MORPH-203
+
+**Testing**:
+- Catalog loads 20 capabilities
+- All capabilities have valid `odId` references
+- Filtering by tags works correctly
+- No duplicate capability IDs
+
+---
+
+### MORPH-205: Create Chaos Preset Configuration Files
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Create JSON configuration files for chaos presets (light, moderate, aggressive, realistic) that can be applied to capabilities and worlds.
+
+**Acceptance Criteria**:
+- [ ] Directory created: `config/chaos-presets/`
+- [ ] 4 preset files created: `light.json`, `moderate.json`, `aggressive.json`, `realistic.json`
+- [ ] Each preset defines probability and scenario weights
+- [ ] Presets cover all chaos scenario types
+- [ ] README documenting preset usage
+
+**Dependencies**: None
+
+**Testing**:
+- All JSON files valid
+- Probabilities sum correctly
+- Scenario weights reasonable
+
+---
+
+### MORPH-206: Build Chaos Config Registry Service
+
+**Type**: Story
+**Priority**: Medium
+**Estimate**: 4 points (2 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Create a Chaos Config Registry that loads presets, manages chaos configuration, and provides chaos resolution based on environment variables and context.
+
+**Acceptance Criteria**:
+- [ ] File created: `src/services/chaos-config.registry.ts`
+- [ ] Loads presets from JSON files on initialization
+- [ ] Method: `loadPreset(presetId)` returns ChaosPolicy
+- [ ] Method: `listPresets()` returns available presets
+- [ ] Method: `isChaosEnabled()` checks CHAOS_ENABLED env var
+- [ ] Method: `resolveChaosPolicy(context)` applies priority cascade
+- [ ] Respects environment variable overrides
+- [ ] Singleton pattern
+
+**Dependencies**: MORPH-205
+
+**Testing**:
+- Loads all 4 presets on initialization
+- `isChaosEnabled()` respects env var
+- `resolveChaosPolicy()` follows priority cascade
+- CHAOS_ENABLED=false disables all chaos
+
+---
+
+### MORPH-207: Integrate Chaos Registry with Capability Executor
+
+**Type**: Story
+**Priority**: Medium
+**Estimate**: 3 points (1.5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Integrate ChaosConfigRegistry into CapabilityExecutor so chaos policies are resolved and applied during OD execution.
+
+**Acceptance Criteria**:
+- [ ] CapabilityExecutor uses ChaosConfigRegistry
+- [ ] Resolves chaos policy before building OD
+- [ ] Passes resolved chaos to OD builder
+- [ ] Capability-level chaos in catalog respected
+- [ ] Environment variables control chaos behavior
+- [ ] Chaos telemetry logged in execution results
+
+**Dependencies**: MORPH-206, MORPH-202
+
+**Testing**:
+- Chaos disabled when CHAOS_ENABLED=false
+- Capability-level chaos overrides default
+- Resolved chaos passed to OD builder
+- Chaos telemetry in execution results
+
+---
+
+### MORPH-208: Add Chaos Support to Capability Type
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 1 point (0.5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Extend Capability type definition to support chaos configuration at capability level.
+
+**Acceptance Criteria**:
+- [ ] Add optional `chaos` field to Capability type
+- [ ] Update catalog with chaos configs for select capabilities
+- [ ] Type supports both preset reference and inline policy
+- [ ] Backward compatible (chaos optional)
+
+**Dependencies**: MORPH-204
+
+**Testing**:
+- Types compile correctly
+- Catalog capabilities with chaos load properly
+- Preset references resolve correctly
+
+---
+
+### MORPH-209: Enhanced Filtering with Search
+
+**Type**: Story
+**Priority**: Medium
+**Estimate**: 3 points (1.5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Add full-text search and enhanced filtering capabilities to CapabilityCatalog for better discoverability.
+
+**Acceptance Criteria**:
+- [ ] Method: `search(query)` performs full-text search
+- [ ] Search across name, description, tags
+- [ ] Filter by multiple tags simultaneously
+- [ ] Filter by persona
+- [ ] Filter by pattern
+- [ ] Case-insensitive search
+- [ ] Returns ranked results (most relevant first)
+
+**Dependencies**: MORPH-204
+
+**Testing**:
+- Search for 'inventory' returns relevant capabilities
+- Multiple filters work together (AND logic)
+- Empty query returns all
+
+---
+
+### MORPH-210: Update GET /api/capabilities with Search
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Update the capabilities API endpoint to support full-text search and enhanced filtering.
+
+**Acceptance Criteria**:
+- [ ] Add `q` query parameter for search
+- [ ] Add `persona` query parameter
+- [ ] Add `pattern` query parameter
+- [ ] Update to use `filterEnhanced()` method
+- [ ] Return count metadata
+- [ ] Backward compatible with existing filters
+
+**Dependencies**: MORPH-209
+
+**Testing**:
+- Search queries return relevant results
+- Multiple filters work correctly
+- Response includes count metadata
+
+---
+
+### MORPH-211: Add GET /api/chaos/presets Endpoint
+
+**Type**: Task
+**Priority**: Low
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Create API endpoints for chaos preset management and inspection.
+
+**Acceptance Criteria**:
+- [ ] `GET /api/chaos/presets` lists all presets
+- [ ] `GET /api/chaos/presets/:id` returns preset details
+- [ ] `GET /api/chaos/status` returns chaos configuration status
+- [ ] Returns preset metadata and configuration
+- [ ] Documents chaos environment variables
+
+**Dependencies**: MORPH-206
+
+**Testing**:
+- Lists all 4 presets
+- Returns 404 for invalid preset ID
+- Status endpoint shows env vars
+
+---
+
+### MORPH-212: Service Tools Enhancement for New ODs
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 5 points (2-3 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Add new service tool methods to support the 15 new OD builders. Enhance existing WMS, EDI, and TMS service tools.
+
+**Acceptance Criteria**:
+- [ ] Add 10-15 new tool methods across WMS, EDI, TMS
+- [ ] Tools support new capability workflows
+- [ ] Tools follow existing patterns (repositories, logging)
+- [ ] Mock implementations for missing backend
+- [ ] Proper error handling
+
+**New Tools Needed**:
+- WMS: selectCycleCountLocations, performCycleCount, reconcileInventory, performReplenishment, createPickTask
+- EDI: generate856ASN, generate855POAck, generate810Invoice, validateEDIDocument
+- TMS: planLoad, optimizeRoute, trackMultipleShipments
+
+**Dependencies**: MORPH-203
+
+**Testing**:
+- Each new tool callable without errors
+- Returns expected data structure
+- Handles invalid inputs gracefully
+
+---
+
+### MORPH-213: Update API Documentation
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Update API documentation to reflect Phase 1 enhancements: search, filtering, chaos endpoints.
+
+**Acceptance Criteria**:
+- [ ] Update `docs/api/capabilities.md` with new query params
+- [ ] Document search functionality with examples
+- [ ] Document chaos endpoints
+- [ ] Add filtering examples
+- [ ] Update Swagger/OpenAPI spec if exists
+- [ ] Include chaos configuration guide
+
+**Dependencies**: MORPH-210, MORPH-211
+
+**Testing**:
+- Documentation accurate
+- Examples work as shown
+- All new features documented
+
+---
+
+### MORPH-214: Integration Testing for Phase 1
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 5 points (2-3 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Create comprehensive integration tests for Phase 1 features: real OD execution, filtering, search, chaos.
+
+**Acceptance Criteria**:
+- [ ] Test file: `tests/phase1-integration.test.ts`
+- [ ] Test: Execute all 20 capabilities successfully
+- [ ] Test: Search and filtering combinations
+- [ ] Test: Chaos disabled with CHAOS_ENABLED=false
+- [ ] Test: Different chaos presets produce different results
+- [ ] Test: OD execution returns proper RunResult
+- [ ] All tests pass
+- [ ] Coverage > 80%
+
+**Dependencies**: MORPH-202, MORPH-210, MORPH-211
+
+**Testing**:
+- All test suites pass
+- Tests cover happy path and error cases
+- Tests run in CI/CD pipeline
+
+---
+
+### MORPH-215: Performance Baseline Metrics
+
+**Type**: Task
+**Priority**: Low
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Establish performance baselines for Phase 1 to track improvements in later phases.
+
+**Acceptance Criteria**:
+- [ ] Measure capability list endpoint performance
+- [ ] Measure capability execution time (per complexity)
+- [ ] Measure search and filter performance
+- [ ] Document baseline metrics
+- [ ] Set up basic performance monitoring
+
+**Baseline Targets**:
+- List 20 capabilities: < 50ms
+- Search capabilities: < 100ms
+- Execute simple capability: < 5s
+- Execute medium capability: < 15s
+
+**Dependencies**: MORPH-214
+
+**Testing**:
+- Performance tests run successfully
+- Baselines documented
+
+---
+
+### MORPH-216: Add 10 More Capabilities (30 Total)
+
+**Type**: Task
+**Priority**: Low
+**Estimate**: 5 points (2-3 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Expand capability catalog from 20 to 30 capabilities for more comprehensive coverage. Optional based on Phase 1 decision point.
+
+**Acceptance Criteria**:
+- [ ] 10 additional OD builders created
+- [ ] 10 additional capabilities defined
+- [ ] Mix of all complexity levels
+- [ ] Cover edge cases and variants
+- [ ] All tested and working
+
+**Additional Capabilities**:
+1. multi-order-fulfillment-v1
+2. emergency-stock-transfer-v1
+3. quality-hold-workflow-v1
+4. edi-940-warehouse-order-v1
+5. carrier-appointment-v1
+6. labor-planning-v1
+7. exception-resolution-v1
+8. returns-authorization-v1
+9. kitting-assembly-v1
+10. bulk-location-update-v1
+
+**Dependencies**: MORPH-203, MORPH-204
+
+**Testing**:
+- All 30 capabilities execute successfully
+- Coverage across all domains
+
+---
+
+### MORPH-217: Phase 1 Demo Preparation
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Prepare demo materials and script for Phase 1 review and decision point.
+
+**Acceptance Criteria**:
+- [ ] Demo script created showing all Phase 1 features
+- [ ] Postman collection with example requests
+- [ ] Demo data setup script
+- [ ] Slides or presentation materials
+- [ ] Comparison with Phase 0 stub
+
+**Dependencies**: All Phase 1 tickets
+
+**Testing**:
+- Demo runs successfully
+- All features demonstrated
+- Clear value proposition shown
+
+---
+
+### MORPH-218: Phase 1 Retrospective & Decision
+
+**Type**: Task
+**Priority**: High
+**Estimate**: 1 point (0.5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Conduct Phase 1 retrospective and make go/no-go decision for Phase 2.
+
+**Acceptance Criteria**:
+- [ ] Team demo completed
+- [ ] Feedback collected from researchers
+- [ ] Performance metrics reviewed
+- [ ] Decision documented: Continue to Phase 2 or Pivot
+- [ ] Learnings documented for Phase 2 planning
+
+**Discussion Points**:
+1. Are 20-30 capabilities enough for meaningful research?
+2. Is real OD execution meeting needs?
+3. Are chaos presets providing value?
+4. What should we add/change for Phase 2?
+
+**Dependencies**: MORPH-217
+
+**Testing**:
+- Decision is clear and documented
+- Feedback is actionable
+
+---
+
+### MORPH-219: Update README and Getting Started Guide
+
+**Type**: Task
+**Priority**: Medium
+**Estimate**: 2 points (1 day)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Update project README and getting started documentation to reflect Phase 1 capabilities.
+
+**Acceptance Criteria**:
+- [ ] README updated with Phase 1 features
+- [ ] Getting started guide includes search examples
+- [ ] Chaos configuration documented
+- [ ] Environment variables documented
+- [ ] Migration notes from Phase 0
+
+**Dependencies**: MORPH-217
+
+**Testing**:
+- Documentation accurate
+- Examples work
+- Links valid
+
+---
+
+### MORPH-220: Code Cleanup and Refactoring
+
+**Type**: Task
+**Priority**: Low
+**Estimate**: 3 points (1.5 days)
+**Status**: 📝 TODO
+**Assignee**: _Unassigned_
+
+**Description**:
+Clean up code, remove Phase 0 stubs, improve code quality and consistency.
+
+**Acceptance Criteria**:
+- [ ] Remove stub implementation comments
+- [ ] Consistent error handling across services
+- [ ] Add JSDoc comments to all public methods
+- [ ] Extract common patterns to utilities
+- [ ] Lint and format all code
+- [ ] Update TypeScript strict mode compliance
+
+**Dependencies**: All Phase 1 tickets
+
+**Testing**:
+- All tests still pass
+- No regressions
+- Linting passes
+
+---
+
+## Phase 1 Summary
+
+**Total Tickets**: 20
+**Total Story Points**: 57 points (~3-4 weeks with 2 developers)
+
+**Ticket Breakdown by Type**:
+- Foundation (Registry & Execution): 2 tickets (10 points)
+- Capability Expansion: 3 tickets (16 points)
+- Chaos Management: 4 tickets (10 points)
+- Search & Filtering: 2 tickets (5 points)
+- API & Documentation: 3 tickets (6 points)
+- Testing & Quality: 3 tickets (12 points)
+- Cleanup & Polish: 3 tickets (8 points)
+
+**Critical Path**:
+MORPH-201 → MORPH-202 → MORPH-203 → MORPH-204 → MORPH-214 → MORPH-217 → MORPH-218
+
+**Parallelizable Work**:
+- MORPH-205, MORPH-206, MORPH-207 (Chaos stream)
+- MORPH-209, MORPH-210 (Search stream)
+- MORPH-212 (Service tools - parallel to OD builders)
+- MORPH-213, MORPH-219 (Documentation - parallel to development)
+
+**Priority Tiers**:
+- **High Priority (Must Have)**: MORPH-201, 202, 203, 204, 214, 217, 218
+- **Medium Priority (Should Have)**: MORPH-205, 206, 207, 209, 210, 212, 213, 219
+- **Low Priority (Nice to Have)**: MORPH-208, 211, 215, 216, 220
+
+**Estimated Velocity**:
+- Week 1: 12-15 points (Foundation + Core ODs)
+- Week 2: 15-18 points (Chaos + Filtering + Service Tools)
+- Week 3: 12-15 points (Testing + Documentation)
+- Week 4: 8-10 points (Polish + Demo + Retrospective)
+
+</details>
+
+---
+
+## Tracking Metrics
+
+### Overall Progress
+
+| Phase | Story Points | Status | Completion |
+|-------|--------------|--------|------------|
+| Phase 0 | 21 | ✅ DONE | 100% |
+| Phase 1 | 57 | ✅ DONE | 100% |
+| Phase 2 | 22 | 📝 TODO | 0% |
+| Phase 3+ | TBD | 🔒 LOCKED | - |
+
+**Total Completed**: 78 story points
+**Next Phase**: Phase 2 (22 points, 2.5-3 weeks)
+
+---
+
+## Related Documents
+
+- [README](./README.md) - Architecture overview and navigation
+- [08. Implementation Roadmap](./08-implementation-roadmap.md) - High-level phases
+- [06. Open Questions & Decisions](./06-open-questions.md) - Architectural decisions
+- [02. Conceptual Model](./02-conceptual-model.md) - System architecture
+
+---
+
+## Definition of Done
+
+**For Each Ticket**:
+- All acceptance criteria met
+- Code reviewed
+- Tests passing
+- Documentation updated
+- No regressions
+
+**For Each Phase**:
+- All tickets completed
+- Demo executed successfully
+- Test results documented
+- Retrospective conducted
+- Go/no-go decision made

docs/od-architecture/README.md

@@ -0,0 +1,181 @@
+# Operational Descriptor (OD) Architecture
+
+## Overview
+
+This directory contains architectural documentation for the OD Management System redesign. The goal is to transform Morpheus from a collection of scattered operational descriptors into a well-organized, capability-based system that AI researchers can easily configure and use.
+
+## The Problem
+
+Currently, Morpheus has:
+- **162 tools** across 4 main services (WMS: 64, ERP: 34, TMS: 33, EDI: 15)
+- **Scattered ODs** across multiple builder files with no central registry
+- **No persona model** - unclear who can execute what
+- **No capability mapping** - can't answer "what can a store manager do?"
+- **Unmanageable chaos configuration** - hardcoded in 14+ files
+- **No way to sample/configure** - researchers can't easily customize worlds
+
+## The Vision
+
+Transform the system to support:
+
+1. **Capability-Based Organization**: ODs organized by business capabilities, not just services
+2. **Persona Model**: Clear mapping of which personas can perform which capabilities
+3. **Knowledge Graph**: Intelligent discovery of valid OD compositions from available tools
+4. **World Configuration**: Researchers can sample capabilities and configure worlds
+5. **Centralized Management**: OD registry, versioning, and customization
+
+## Implementation Files
+
+### Phase-Specific Documentation
+
+All phase-specific implementation details are organized in the `implementation/` directory:
+
+```
+implementation/
+├── phase0/           # Walking Skeleton
+│   ├── tasks.md      # 12 tickets, 21 story points
+│   ├── demo.md       # Demo walkthrough
+│   └── test-results.md
+├── phase1/           # Core Capability System
+│   ├── tasks.md      # 20 tickets, 57 story points
+│   ├── demo-script.md
+│   ├── test-results.md
+│   └── retrospective.md
+└── phase2/           # World Configuration
+    └── tasks.md      # 10 tickets, 22 story points (REVISED)
+```
+
+See [09. Implementation Tasks](./09-implementation-tasks.md) for quick navigation links.
+
+---
+
+## Architecture Documents
+
+### [01. Current State](./01-current-state.md)
+Complete inventory of the existing system:
+- Services and tools catalog
+- Existing OD patterns
+- Current organization
+- Critical gaps
+
+### [02. Conceptual Model](./02-conceptual-model.md)
+Proposed architectural model:
+- Persona → Capability → OD → Tool → Service layering
+- Definitions and relationships
+- Design questions to resolve
+
+### [03. Knowledge Graph](./03-knowledge-graph.md)
+Graph-based capability discovery:
+- Graph structure (nodes, edges)
+- Use cases (OD discovery, validation, suggestions)
+- Implementation approaches
+
+### [04. Taxonomy & Organization](./04-taxonomy-organization.md)
+How to categorize and organize ODs:
+- Taxonomy options (domain, persona, complexity)
+- Tagging and filtering strategies
+- Discovery patterns
+
+### [05. Sampling & World Configuration](./05-sampling-world-config.md)
+Enabling researcher customization:
+- World configuration scenarios
+- Sampling strategies
+- Use cases and workflows
+
+### [06. Open Questions & Decisions](./06-open-questions.md)
+Architectural decisions made:
+- ✅ All critical and important questions decided
+- Decision rationale and implementation notes
+- Priority 3 recommendations for later phases
+
+### [07. Chaos Integration](./07-chaos-integration.md)
+How chaos management integrates with OD architecture:
+- Chaos configuration cascade (World → Capability → OD → Step)
+- Integration points and workflows
+- Chaos presets and telemetry
+- Best practices for researchers
+
+### [08. Implementation Roadmap](./08-implementation-roadmap.md)
+Value-driven implementation plan:
+- Incremental phases delivering researcher value
+- Phase 0: Walking skeleton (2-3 weeks)
+- Phase 1-4: Core features (14-20 weeks)
+- Migration strategy and risk mitigation
+
+### [09. Implementation Tasks](./09-implementation-tasks.md)
+Master index for all implementation tasks:
+- Phase 0: ✅ COMPLETED (12 tickets, 21 story points)
+- Phase 1: ✅ COMPLETED (20 tickets, 57 story points)
+- Phase 2: 📝 TODO - Ready to Start (12 tickets, 30 story points)
+- Detailed tasks in `implementation/phaseN/` folders
+- Quick navigation table with links to all phase documents
+
+## Key Concepts
+
+### Service
+A simulated enterprise system (ERP, WMS, TMS, EDI) that exposes tools/APIs.
+
+### Tool
+An API endpoint that performs a specific action (e.g., `getOrder`, `updateInventory`, `scheduleShipment`).
+
+### Operational Descriptor (OD)
+A declarative workflow that orchestrates multiple tools to accomplish an end-to-end business process. Contains steps, input bindings, assertions, retry policies, and chaos configuration.
+
+### Capability
+A semantic business function or process (e.g., "Order Fulfillment", "Inventory Management", "Shipment Tracking"). Capabilities are implemented by one or more ODs.
+
+### Persona
+A role or actor in the system (e.g., Store Manager, Warehouse Worker, Logistics Coordinator). Personas have access to specific capabilities.
+
+### Knowledge Graph
+A graph representation of relationships between services, tools, data entities, ODs, capabilities, and personas. Used for discovery, validation, and intelligent suggestions.
+
+## Status
+
+**Phase**: Phase 2 Implementation (World Configuration)
+**Last Updated**: 2025-11-21
+**Contributors**: System Architects, AI Research Team
+
+**Completed**:
+- ✅ Architecture designed (Persona → Capability → OD → Tool → Service)
+- ✅ All critical decisions made (9/9 questions)
+- ✅ Implementation roadmap created (value-driven, 6 phases)
+- ✅ Phase 0: Walking Skeleton (12 tickets, 21 points) - DONE
+- ✅ Phase 1: Core Capability System (20 tickets, 57 points) - DONE
+  - 4 working capabilities with real OD execution
+  - Chaos engineering integrated
+  - Search/filtering APIs functional
+
+**Current**: Phase 2 - World Configuration (10 tickets, 22 points)
+- Extends existing World model (27% effort reduction)
+- Capability sampling: filter, random, seeded
+- World-level chaos configuration with CRUD API
+- Capability-level chaos overrides
+- Critical bug fix: capability executor chaos integration
+- Reproducibility via seeds
+
+## Next Steps
+
+1. ✅ ~~Review and discuss each architecture document~~ **DONE**
+2. ✅ ~~Answer open questions and make design decisions~~ **DONE**
+3. ✅ ~~Create implementation plan~~ **DONE**
+4. ✅ ~~Complete Phase 0 - Walking Skeleton~~ **DONE**
+5. ✅ ~~Complete Phase 1 - Core Capability System~~ **DONE**
+6. **NOW**: Start Phase 2 - World Configuration (3-4 weeks)
+   - Implement world configuration schema
+   - Build sampling strategies (filter, random, seeded)
+   - Add world-level chaos with seed support
+   - Create world management API endpoints
+7. **NEXT**: Continue through remaining phases based on learnings
+
+## Related Documentation
+
+- [Main Architecture](../01-architecture.md) - Overall system architecture
+- [Operational Descriptors](../02-operational-descriptors.md) - Current OD implementation
+- [Chaos Engineering](../03-chaos-engineering.md) - Chaos injection framework
+- [Chaos Management](../chaos/) - Chaos configuration and management system
+- [Business Rules](../business-rules/) - Business rules system
+
+## Feedback
+
+This is a living document. If you have questions, suggestions, or concerns about the proposed architecture, please discuss in the team channels or create an issue.

morpheus.local.pwd.yaml

@@ -0,0 +1,26 @@
+services:
+  mongodb:
+    image: mongo:7
+    ports:
+      - 27017:27017
+    volumes:
+      - ./morpheus-data/mongodb:/data/db
+    restart: unless-stopped
+
+  controlmart:
+    env_file:
+      - packages/controlmart/.env
+    build:
+      context: .
+      dockerfile: packages/controlmart/Dockerfile
+    image: controlmart-local
+    environment:
+      MONGO_URI: mongodb://mongodb:27017
+    ports:
+      - "8282:8282"
+    restart: unless-stopped
+    depends_on:
+      - mongodb
+
+volumes:
+  mongodb-data:

morpheus.pwd.yaml

@@ -0,0 +1,61 @@
+version: "3.8"
+
+services:
+  mongodb:
+    image: mongo:7
+    ports:
+      - 27017:27017
+    volumes:
+      - /mnt/morpheus-data:/data/db
+    restart: unless-stopped
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+
+  controlmart:
+    image: 129875285541.dkr.ecr.us-east-1.amazonaws.com/skyfall/morpheus:latest
+    labels:
+      - "com.centurylinklabs.watchtower.enable=true"
+    environment:
+      NODE_ENV: production
+      PORT: 8282
+      MONGO_URI: mongodb://mongodb:27017
+      DB_NAME: controlmart
+      LOG_LEVEL: debug
+      ENABLE_CORS: true
+    ports:
+      - "8282:8282"
+    restart: unless-stopped
+    depends_on:
+      - mongodb
+
+  watchtower:
+    image: containrrr/watchtower
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /home/ubuntu/.docker:/config:ro
+    environment:
+      DOCKER_CONFIG: /config
+      WATCHTOWER_CLEANUP: "true"
+      WATCHTOWER_POLL_INTERVAL: 60
+      WATCHTOWER_DEBUG: "true"
+    restart: unless-stopped
+
+  nginx:
+    image: nginx:1.25
+    container_name: nginx-proxy
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /mnt/morpheus-data/morpheus/nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
+      - /mnt/morpheus-data/morpheus/nginx/certs:/etc/ssl:ro
+    depends_on:
+      - controlmart
+    restart: unless-stopped
+
+volumes:
+  mongodb-data:

nginx/nginx.conf

@@ -0,0 +1,25 @@
+server {
+    listen 80;
+    server_name _;
+
+    proxy_buffering off;
+    proxy_request_buffering off;
+    proxy_http_version 1.1;
+    proxy_set_header Accept-Encoding "";
+
+    proxy_connect_timeout 60s;
+    proxy_send_timeout 60s;
+    proxy_read_timeout 60s;
+
+    location / {
+        proxy_pass http://controlmart:8282;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_redirect off;
+    }
+
+    access_log /var/log/nginx/access.log;
+    error_log /var/log/nginx/error.log;
+}

package.json

@@ -0,0 +1,18 @@
+{
+  "name": "morpheus",
+  "module": "index.ts",
+  "type": "module",
+  "private": true,
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "workspaces": [
+    "packages/controlmart"
+  ],
+  "dependencies": {
+    "axios": "^1.12.2"
+  }
+}

packages/controlmart/.dockerignore

@@ -0,0 +1,33 @@
+# Node / Bun deps
+node_modules
+bun.lockb.bak
+*.log
+
+# Bun cache
+.bun
+.cache
+.vscode
+
+# Git / version control
+.git
+.gitignore
+
+# Docker junk
+Dockerfile*
+docker-compose*
+.dockerignore
+
+# OS + editor noise
+.DS_Store
+Thumbs.db
+
+# Build output
+dist
+build
+tmp
+coverage
+
+# Environment and secrets
+.env
+.env.*
+!.env.example

packages/controlmart/.gitignore

@@ -0,0 +1,37 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+build-dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+
+tests/implementation-tests

packages/controlmart/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+build
+bun.lockb
+coverage
+.env

packages/controlmart/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "proseWrap": "preserve",
+  "embeddedLanguageFormatting": "auto",
+  "singleAttributePerLine": false
+}

packages/controlmart/Dockerfile

@@ -0,0 +1,23 @@
+FROM oven/bun:latest
+
+WORKDIR /app
+
+COPY bun.lock package.json ./
+
+COPY packages/controlmart/package.json packages/controlmart/
+
+RUN bun install
+
+COPY . .
+
+WORKDIR /app/packages/controlmart
+RUN bun run build:ui
+
+WORKDIR /app/packages/controlmart
+
+ENV NODE_ENV=production
+ENV PORT=8282
+
+EXPOSE ${PORT}
+
+CMD ["bun", "run", "start"]

packages/controlmart/README.md

@@ -0,0 +1,148 @@
+# ControlMart - Capability Orchestration Engine
+
+ControlMart is Morpheus's capability orchestration engine that provides a semantic layer over Operational Descriptors (ODs) for executing business capabilities with chaos engineering support.
+
+## Features
+
+- **4 Phase 1 Capabilities**: Inventory Check, Shipment Tracking, Equipment Availability, Dock Appointment Scheduling
+- **Semantic Discovery**: Search and filter capabilities by domain, complexity, services, personas, and patterns
+- **Chaos Engineering**: Built-in resilience testing with configurable chaos scenarios and presets
+- **World Isolation**: Execute capabilities in isolated world contexts with independent data and business rules
+- **RESTful API**: Simple HTTP endpoints for capability discovery and execution
+
+## Quick Start
+
+### Prerequisites
+
+- Bun v1.2.15+
+- MongoDB running on localhost:27017
+
+### Installation
+
+```bash
+bun install
+```
+
+### Running the Server
+
+```bash
+# Development mode
+bun run index.ts
+
+# With environment variables
+MONGO_URI="mongodb://localhost:27017" DB_NAME="morpheus-test" PORT=4000 bun run index.ts
+
+# With chaos enabled
+CHAOS_ENABLED=true CHAOS_PRESET=realistic bun run index.ts
+```
+
+### Basic Usage
+
+```bash
+# List all capabilities
+curl http://localhost:4000/capabilities
+
+# Search for capabilities
+curl "http://localhost:4000/capabilities?q=inventory"
+
+# Get capability details
+curl http://localhost:4000/capabilities/inventory-check
+
+# Execute a capability
+curl -X POST http://localhost:4000/capabilities/inventory-check/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "worldId": "your-world-id",
+    "inputs": {
+      "sku": "SKU-001",
+      "locationId": "WH-01"
+    }
+  }'
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MONGO_URI` | MongoDB connection string | `mongodb://localhost:27017` |
+| `DB_NAME` | Database name | `morpheus-test` |
+| `PORT` | Server port | `4000` |
+| `CHAOS_ENABLED` | Enable chaos injection | `false` |
+| `CHAOS_PRESET` | Chaos preset (`light`/`moderate`/`realistic`/`aggressive`) | `realistic` |
+
+## Available Capabilities
+
+### 1. Inventory Check
+Check current inventory levels for SKUs across warehouse locations.
+
+**Inputs**: `sku` (required), `locationId` (optional)
+
+### 2. Shipment Tracking
+Track shipment status and location through the transportation network.
+
+**Inputs**: `shipmentId` (required)
+
+### 3. Equipment Availability Check
+Check available warehouse equipment (forklifts, pallet jacks, etc.) by type and zone.
+
+**Inputs**: `equipmentType` (required), `zoneId` (optional)
+
+### 4. Dock Appointment Scheduling
+Find available dock appointment time slots and view current schedule.
+
+**Inputs**: `date` (required), `dockDoorId` (required), `appointmentType` (optional)
+
+## Chaos Engineering
+
+ControlMart includes built-in chaos engineering for resilience testing:
+
+```bash
+# Check chaos status
+curl http://localhost:4000/chaos/status
+
+# List available presets
+curl http://localhost:4000/chaos/presets
+
+# Run with aggressive chaos
+CHAOS_PRESET=aggressive bun run index.ts
+```
+
+**Chaos Presets:**
+- `light` (5%): Minimal chaos for production-like testing
+- `moderate` (15%): Balanced chaos for resilience testing
+- `realistic` (10%): Production-realistic failure rates
+- `aggressive` (30%): High chaos for stress testing
+
+## Performance Measurement
+
+Measure baseline performance for all capabilities:
+
+```bash
+bun run scripts/measure-performance.ts
+```
+
+Results are saved to `config/performance-baselines.json`.
+
+## Documentation
+
+- **API Reference**: [docs/api/capabilities-api.md](docs/api/capabilities-api.md)
+- **Architecture**: [../../docs/od-architecture/](../../docs/od-architecture/)
+
+## Project Structure
+
+```
+src/
+├── capabilities/          # Capability catalog
+├── ods/                   # Operational Descriptor builders
+├── routes/                # API routes (capabilities, chaos)
+├── services/              # Core services (executor, catalog, chaos)
+├── types/                 # TypeScript type definitions
+scripts/
+├── measure-performance.ts # Performance measurement tool
+docs/
+└── api/                   # API documentation
+```
+
+## Development
+
+Built with [Bun](https://bun.sh) - a fast all-in-one JavaScript runtime.

packages/controlmart/bootstrap.ts

@@ -0,0 +1,22 @@
+import { existsSync } from "fs";
+import path from "path";
+
+// Bootstrap
+(async () => {
+  // Check for environment file relative to executable
+  const execDir = path.dirname(process.execPath);
+  const localEnvPath = path.join(execDir, ".env");
+  const devEnvPath = path.resolve(execDir, "../../..", ".env"); // For dev/source runs
+
+  const envPath = existsSync(localEnvPath) ? localEnvPath : devEnvPath;
+
+  if (!existsSync(envPath)) {
+    console.log(`[bootstrap] No .env file found at ${envPath}. Launching Setup Mode...`);
+    const { startSetup } = await import("./src/application/setup.app");
+    await startSetup();
+  } else {
+    // Launch Main Application
+    console.log("[bootstrap] Environment found. Starting Application...");
+    await import("./main");
+  }
+})();

packages/controlmart/config/chaos-presets/aggressive.json

@@ -0,0 +1,109 @@
+{
+  "id": "aggressive",
+  "name": "Aggressive Chaos",
+  "description": "High probability chaos with all scenario types. Tests extreme resilience under heavy failure conditions.",
+  "globalProbability": 0.3,
+  "scenarios": [
+    {
+      "type": "data_corruption",
+      "weight": 10,
+      "description": "Severe data corruption",
+      "config": {
+        "corruptFields": ["*"],
+        "corruptionType": "random_value"
+      }
+    },
+    {
+      "type": "missing_data",
+      "weight": 9,
+      "description": "Frequent missing records",
+      "config": {
+        "missingRecords": true,
+        "throwError": true
+      }
+    },
+    {
+      "type": "stale_data",
+      "weight": 8,
+      "description": "Very stale data",
+      "config": {
+        "staleDataAge": 120
+      }
+    },
+    {
+      "type": "rate_limit",
+      "weight": 8,
+      "description": "Aggressive rate limiting",
+      "config": {
+        "rateLimitDelay": 3000,
+        "rateLimitMessage": "Rate limit exceeded - too many requests"
+      }
+    },
+    {
+      "type": "format_change",
+      "weight": 7,
+      "description": "Breaking schema changes",
+      "config": {
+        "schemaChanges": [
+          {
+            "field": "id",
+            "change": "rename",
+            "newName": "order_id"
+          },
+          {
+            "field": "status",
+            "change": "change_type",
+            "newType": "number"
+          }
+        ]
+      }
+    },
+    {
+      "type": "partial_data",
+      "weight": 7,
+      "description": "Heavily incomplete data",
+      "config": {
+        "partialResults": {
+          "percentage": 50,
+          "randomize": true
+        }
+      }
+    },
+    {
+      "type": "permission_denied",
+      "weight": 6,
+      "description": "Frequent authorization failures",
+      "config": {
+        "permissionError": "Access denied - chaos injection"
+      }
+    },
+    {
+      "type": "duplicate_data",
+      "weight": 6,
+      "description": "Heavy duplicate records",
+      "config": {}
+    },
+    {
+      "type": "invalid_state",
+      "weight": 5,
+      "description": "Records in invalid states",
+      "config": {
+        "invalidStates": ["deleted", "suspended", "inactive", "pending_deletion"]
+      }
+    },
+    {
+      "type": "dependency_failure",
+      "weight": 4,
+      "description": "Service dependency failures",
+      "config": {
+        "dependencyService": "downstream-service"
+      }
+    },
+    {
+      "type": "timing_issue",
+      "weight": 3,
+      "description": "Timestamp inconsistencies",
+      "config": {}
+    }
+  ]
+}

packages/controlmart/config/chaos-presets/infra.json

@@ -0,0 +1,33 @@
+{
+    "id": "infra",
+    "name": "Infrastructure Chaos",
+    "description": "System-level faults: rate limits, timeouts, dependency failures. NO data corruption.",
+    "globalProbability": 0.1,
+    "scenarios": [
+        {
+            "type": "rate_limit",
+            "weight": 50,
+            "description": "API throttling (429 Too Many Requests)",
+            "config": {
+                "rateLimitDelay": 1500,
+                "rateLimitMessage": "Rate limit exceeded"
+            }
+        },
+        {
+            "type": "dependency_failure",
+            "weight": 30,
+            "description": "Dependency service outage (502/503)",
+            "config": {
+                "dependencyService": "database-shard-01"
+            }
+        },
+        {
+            "type": "permission_denied",
+            "weight": 20,
+            "description": "Authorization failures (403 Forbidden)",
+            "config": {
+                "permissionError": "Insufficient permissions"
+            }
+        }
+    ]
+}

packages/controlmart/config/chaos-presets/light.json

@@ -0,0 +1,45 @@
+{
+  "id": "light",
+  "name": "Light Chaos",
+  "description": "Low probability chaos for basic resilience testing. Simulates common, low-impact scenarios like eventual consistency and rate limiting.",
+  "globalProbability": 0.05,
+  "scenarios": [
+    {
+      "type": "stale_data",
+      "weight": 10,
+      "description": "Simulate eventual consistency delays - most common in distributed systems",
+      "config": {
+        "staleDataAge": 30
+      }
+    },
+    {
+      "type": "rate_limit",
+      "weight": 5,
+      "description": "API throttling and rate limiting",
+      "config": {
+        "rateLimitDelay": 1000,
+        "rateLimitMessage": "Rate limit exceeded - please retry"
+      }
+    },
+    {
+      "type": "missing_data",
+      "weight": 3,
+      "description": "Occasional missing records or null results",
+      "config": {
+        "missingRecords": true,
+        "throwError": false
+      }
+    },
+    {
+      "type": "partial_data",
+      "weight": 2,
+      "description": "Incomplete data sets returned",
+      "config": {
+        "partialResults": {
+          "percentage": 80,
+          "randomize": false
+        }
+      }
+    }
+  ]
+}

packages/controlmart/config/chaos-presets/moderate.json

@@ -0,0 +1,68 @@
+{
+  "id": "moderate",
+  "name": "Moderate Chaos",
+  "description": "Medium probability chaos with diverse scenario types. Good balance for resilience testing without overwhelming the system.",
+  "globalProbability": 0.15,
+  "scenarios": [
+    {
+      "type": "stale_data",
+      "weight": 12,
+      "description": "Eventual consistency delays",
+      "config": {
+        "staleDataAge": 60
+      }
+    },
+    {
+      "type": "data_corruption",
+      "weight": 8,
+      "description": "Data quality issues and field corruption",
+      "config": {
+        "corruptFields": ["email", "status", "timestamp"],
+        "corruptionType": "wrong_type"
+      }
+    },
+    {
+      "type": "rate_limit",
+      "weight": 7,
+      "description": "API throttling",
+      "config": {
+        "rateLimitDelay": 2000,
+        "rateLimitMessage": "Rate limit exceeded"
+      }
+    },
+    {
+      "type": "partial_data",
+      "weight": 6,
+      "description": "Incomplete result sets",
+      "config": {
+        "partialResults": {
+          "percentage": 70,
+          "randomize": true
+        }
+      }
+    },
+    {
+      "type": "missing_data",
+      "weight": 5,
+      "description": "Missing records and fields",
+      "config": {
+        "missingRecords": true,
+        "throwError": false
+      }
+    },
+    {
+      "type": "permission_denied",
+      "weight": 3,
+      "description": "Authorization failures",
+      "config": {
+        "permissionError": "Access denied - insufficient permissions"
+      }
+    },
+    {
+      "type": "duplicate_data",
+      "weight": 4,
+      "description": "Duplicate records in results",
+      "config": {}
+    }
+  ]
+}

packages/controlmart/config/chaos-presets/process.json

@@ -0,0 +1,72 @@
+{
+    "id": "process",
+    "name": "Process Chaos",
+    "description": "Business logic and data integrity failures only. No infrastructure or system faults.",
+    "globalProbability": 0.1,
+    "scenarios": [
+        {
+            "type": "stale_data",
+            "weight": 30,
+            "description": "Eventual consistency delays (e.g. order not found immediately after creation)",
+            "config": {
+                "staleDataAge": 45
+            }
+        },
+        {
+            "type": "partial_data",
+            "weight": 20,
+            "description": "Pagination and partial results (e.g. search returns subset)",
+            "config": {
+                "partialResults": {
+                    "percentage": 75,
+                    "randomize": false
+                }
+            }
+        },
+        {
+            "type": "data_corruption",
+            "weight": 20,
+            "description": "Data quality issues (invalid enums, wrong formats)",
+            "config": {
+                "corruptFields": [
+                    "orderStatus",
+                    "orderPriority",
+                    "warehouseId",
+                    "customerId"
+                ],
+                "corruptionType": "invalid_format"
+            }
+        },
+        {
+            "type": "missing_data",
+            "weight": 15,
+            "description": "Missing required or optional fields",
+            "config": {
+                "missingFields": [
+                    "customerName",
+                    "shipToAddress",
+                    "lines"
+                ],
+                "throwError": false
+            }
+        },
+        {
+            "type": "duplicate_data",
+            "weight": 10,
+            "description": "Duplicate records in list responses",
+            "config": {}
+        },
+        {
+            "type": "invalid_state",
+            "weight": 5,
+            "description": "Records in logic-breaking states",
+            "config": {
+                "invalidStates": [
+                    "SUSPENDED",
+                    "ARCHIVED",
+                    "UNKNOWN"
+                ]
+            }
+        }
+    ]
+}

packages/controlmart/config/chaos-presets/realistic.json

@@ -0,0 +1,76 @@
+{
+  "id": "realistic",
+  "name": "Realistic Chaos",
+  "description": "Chaos distribution matching real-world production failure rates. Based on observability data from distributed systems.",
+  "globalProbability": 0.08,
+  "scenarios": [
+    {
+      "type": "stale_data",
+      "weight": 40,
+      "description": "Most common: eventual consistency delays",
+      "config": {
+        "staleDataAge": 45
+      }
+    },
+    {
+      "type": "rate_limit",
+      "weight": 20,
+      "description": "Common: API throttling",
+      "config": {
+        "rateLimitDelay": 1500,
+        "rateLimitMessage": "Rate limit exceeded"
+      }
+    },
+    {
+      "type": "partial_data",
+      "weight": 15,
+      "description": "Common: pagination and partial results",
+      "config": {
+        "partialResults": {
+          "percentage": 75,
+          "randomize": false
+        }
+      }
+    },
+    {
+      "type": "data_corruption",
+      "weight": 10,
+      "description": "Occasional: data quality issues",
+      "config": {
+        "corruptFields": ["email", "phoneNumber"],
+        "corruptionType": "invalid_format"
+      }
+    },
+    {
+      "type": "missing_data",
+      "weight": 7,
+      "description": "Occasional: missing optional fields",
+      "config": {
+        "missingFields": ["metadata", "description"],
+        "throwError": false
+      }
+    },
+    {
+      "type": "duplicate_data",
+      "weight": 4,
+      "description": "Rare: duplicate records",
+      "config": {}
+    },
+    {
+      "type": "permission_denied",
+      "weight": 3,
+      "description": "Rare: authorization failures",
+      "config": {
+        "permissionError": "Insufficient permissions"
+      }
+    },
+    {
+      "type": "dependency_failure",
+      "weight": 1,
+      "description": "Very rare: complete service outages",
+      "config": {
+        "dependencyService": "external-service"
+      }
+    }
+  ]
+}

packages/controlmart/docs/api/capabilities-api.md

@@ -0,0 +1,484 @@
+# Capabilities API Documentation
+
+## Overview
+
+The Capabilities API provides endpoints for discovering and executing business capabilities in the Morpheus platform.
+
+## Base URL
+
+```
+http://localhost:4000
+```
+
+## Endpoints
+
+### 1. List All Capabilities
+
+**GET** `/capabilities`
+
+Returns all available capabilities with optional filtering and search.
+
+**Query Parameters:**
+- `q` (string, optional): Full-text search across name, description, and tags
+- `domain` (string[], optional): Filter by domain(s)
+- `complexity` (string, optional): Filter by complexity level (`simple`, `medium`, `complex`)
+- `services` (string[], optional): Filter by service(s) used
+- `personas` (string[], optional): Filter by persona(s)
+- `patterns` (string[], optional): Filter by workflow pattern(s)
+
+**Example Requests:**
+
+```bash
+# Get all capabilities
+curl http://localhost:4000/capabilities
+
+# Search for inventory-related capabilities
+curl "http://localhost:4000/capabilities?q=inventory"
+
+# Filter by domain
+curl "http://localhost:4000/capabilities?domain=inventory&domain=warehousing"
+
+# Filter by complexity
+curl "http://localhost:4000/capabilities?complexity=simple"
+
+# Combined search and filter
+curl "http://localhost:4000/capabilities?q=check&complexity=simple"
+```
+
+**Response:**
+
+```json
+[
+  {
+    "id": "inventory-check",
+    "name": "Inventory Check",
+    "description": "Check current inventory levels for one or more SKUs...",
+    "tags": {
+      "domain": ["inventory", "warehousing"],
+      "complexity": "simple",
+      "services": ["wms"],
+      "personas": ["warehouse-worker", "store-manager"],
+      "patterns": ["sequential"]
+    },
+    "odId": "inventory-check-standard-v1",
+    "version": "1.0.0",
+    "metadata": {
+      "author": "morpheus-team",
+      "estimatedDuration": 2000
+    },
+    "chaos": {
+      "enabled": true,
+      "probability": 0.1,
+      "scenarios": [...]
+    }
+  }
+]
+```
+
+### 2. Get Capability by ID
+
+**GET** `/capabilities/:id`
+
+Returns a single capability by its ID.
+
+**Example:**
+
+```bash
+curl http://localhost:4000/capabilities/inventory-check
+```
+
+### 3. Execute Capability
+
+**POST** `/capabilities/:id/execute`
+
+Executes a capability within a world context.
+
+**Request Body:**
+
+```json
+{
+  "worldId": "world-id-here",
+  "inputs": {
+    "sku": "SKU-001",
+    "locationId": "WH-01"
+  }
+}
+```
+
+**Example:**
+
+```bash
+curl -X POST http://localhost:4000/capabilities/inventory-check/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "worldId": "673d9a8f1234567890abcdef",
+    "inputs": {
+      "sku": "SKU-001",
+      "locationId": "WH-01"
+    }
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "capabilityId": "inventory-check",
+  "odId": "inventory-check-standard-v1",
+  "worldId": "673d9a8f1234567890abcdef",
+  "result": {
+    "runId": "inventory-check-standard-v1",
+    "worldId": "673d9a8f1234567890abcdef",
+    "descriptorId": "inventory-check-standard-v1",
+    "descriptorVersion": "1.0.0",
+    "status": "success",
+    "startTime": "2025-11-20T13:00:00.000Z",
+    "endTime": "2025-11-20T13:00:01.245Z",
+    "durationMs": 1245,
+    "stepResults": [...],
+    "totalSteps": 3,
+    "successfulSteps": 3,
+    "failedSteps": 0,
+    "skippedSteps": 0
+  },
+  "executedAt": "2025-11-20T13:00:00.000Z",
+  "durationMs": 1245,
+  "status": "success",
+  "capabilityInWorld": true,
+  "chaosMetadata": {
+    "enabled": true,
+    "injectionCount": 1,
+    "injections": [
+      {
+        "stepId": "fetch-inventory",
+        "stepName": "Fetch Inventory Records",
+        "scenarioType": "missing_data",
+        "scenarioDescription": "Records not found or empty results",
+        "configSource": "world",
+        "probability": 0.2,
+        "seed": "test-seed-123",
+        "timestamp": "2025-11-20T13:00:00.500Z",
+        "modifications": [
+          "Returned empty result set",
+          "Original had 5 records"
+        ],
+        "config": {
+          "missingRecords": true,
+          "throwError": false
+        }
+      }
+    ],
+    "cascadeResolution": {
+      "finalSource": "world"
+    },
+    "probability": 0.2,
+    "seed": "test-seed-123"
+  }
+}
+```
+
+**Note:** The `chaosMetadata` field is only present when chaos engineering is enabled. See the [Chaos Telemetry](#chaos-telemetry) section below for details.
+
+## Chaos Telemetry
+
+When chaos engineering is enabled, capability execution responses include comprehensive telemetry about chaos injections that occurred during execution. This telemetry helps you understand exactly what chaos was injected, when, and from which configuration level.
+
+### ChaosTelemetry Schema
+
+```typescript
+{
+  enabled: boolean;              // Whether chaos was enabled for this execution
+  injectionCount: number;        // Total number of chaos injections that occurred
+  injections: ChaosInjectionMetadata[]; // Details of each injection
+  cascadeResolution: {
+    finalSource: string;         // Which config level provided the chaos policy
+                                 // Values: "env" | "step" | "od" | "capability" | "world" | "global"
+  };
+  probability: number;           // Probability that was used (0.0 to 1.0)
+  seed?: string;                 // Seed used for reproducible chaos (if any)
+}
+```
+
+### ChaosInjectionMetadata Schema
+
+Each injection in the `injections` array contains:
+
+```typescript
+{
+  stepId: string;                // OD step ID where chaos was injected
+  stepName: string;              // Human-readable step name
+  scenarioType: string;          // Type of chaos scenario (e.g., "missing_data", "data_corruption")
+  scenarioDescription: string;   // Human-readable description
+  configSource: string;          // Config level that provided the chaos scenario
+                                 // Values: "step" | "od" | "capability" | "world" | "global" | "env"
+  probability: number;           // Probability setting at time of injection
+  seed?: string;                 // Seed if used for this injection
+  timestamp: string;             // ISO 8601 timestamp of injection
+  modifications: string[];       // List of modifications made to the data
+  config?: object;               // Scenario-specific configuration used
+}
+```
+
+### Example: No Chaos Injected
+
+When chaos is enabled but no injections occurred (due to probability):
+
+```json
+{
+  "capabilityId": "inventory-check",
+  "status": "success",
+  "chaosMetadata": {
+    "enabled": true,
+    "injectionCount": 0,
+    "injections": [],
+    "cascadeResolution": {
+      "finalSource": "world"
+    },
+    "probability": 0.1,
+    "seed": null
+  }
+}
+```
+
+### Example: Multiple Chaos Injections
+
+When multiple steps experience chaos:
+
+```json
+{
+  "capabilityId": "order-fulfillment",
+  "status": "partial",
+  "chaosMetadata": {
+    "enabled": true,
+    "injectionCount": 2,
+    "injections": [
+      {
+        "stepId": "fetch-order",
+        "stepName": "Fetch Order Details",
+        "scenarioType": "stale_data",
+        "scenarioDescription": "Return outdated data",
+        "configSource": "world",
+        "probability": 0.25,
+        "timestamp": "2025-11-20T14:30:00.100Z",
+        "modifications": [
+          "Made data appear 60 minutes old",
+          "Updated timestamp to 2025-11-20T13:30:00.000Z"
+        ],
+        "config": {
+          "staleDataAge": 60
+        }
+      },
+      {
+        "stepId": "check-inventory",
+        "stepName": "Check Inventory Availability",
+        "scenarioType": "partial_data",
+        "scenarioDescription": "Return incomplete results",
+        "configSource": "world",
+        "probability": 0.25,
+        "timestamp": "2025-11-20T14:30:00.500Z",
+        "modifications": [
+          "Returned 3 out of 6 SKUs",
+          "Missing SKUs: SKU-004, SKU-005, SKU-006"
+        ],
+        "config": {
+          "partialResults": {
+            "percentage": 50,
+            "randomize": true
+          }
+        }
+      }
+    ],
+    "cascadeResolution": {
+      "finalSource": "world"
+    },
+    "probability": 0.25,
+    "seed": "test-123"
+  }
+}
+```
+
+### Using Chaos Telemetry
+
+**1. Debugging Test Failures**
+
+When a test fails unexpectedly, check if chaos was injected:
+
+```bash
+curl -X POST http://localhost:4000/capabilities/inventory-check/execute \
+  -H "Content-Type: application/json" \
+  -d '{"worldId": "..."}' | jq '.chaosMetadata'
+```
+
+**2. Analyzing Chaos Impact**
+
+Track which scenarios are triggered most frequently:
+
+```bash
+# Execute capability multiple times
+for i in {1..100}; do
+  curl -X POST http://localhost:4000/capabilities/inventory-check/execute \
+    -H "Content-Type: application/json" \
+    -d '{"worldId": "..."}' >> chaos-results.json
+done
+
+# Analyze results
+cat chaos-results.json | jq '.chaosMetadata.injections[].scenarioType' | sort | uniq -c
+```
+
+**3. Reproducing Specific Failures**
+
+Use the seed from a failed execution to reproduce the exact same chaos:
+
+```bash
+# First execution - note the seed from response
+RESPONSE=$(curl -X POST http://localhost:4000/capabilities/inventory-check/execute \
+  -H "Content-Type: application/json" \
+  -d '{"worldId": "..."}')
+
+SEED=$(echo $RESPONSE | jq -r '.chaosMetadata.seed')
+
+# Configure world with the same seed to reproduce
+curl -X PUT "http://localhost:4000/world/$WORLD_ID/chaos" \
+  -H "Content-Type: application/json" \
+  -d "{\"enabled\": true, \"probability\": 0.5, \"seed\": \"$SEED\", ...}"
+```
+
+**4. Understanding Config Source**
+
+The `configSource` field in each injection tells you which configuration level provided the chaos scenario:
+
+- `"env"` - From `CHAOS_PRESET` environment variable
+- `"world"` - From world-specific chaos configuration
+- `"capability"` - From capability-level override
+- `"od"` - From operational descriptor definition
+- `"step"` - From step-level chaos policy
+- `"global"` - From global preset loaded at startup
+
+This helps you understand the chaos configuration hierarchy and debug unexpected behavior.
+
+For comprehensive chaos engineering documentation, including all chaos endpoints and configuration options, see the [Chaos Engineering API documentation](./chaos-api.md).
+
+## Chaos Engineering API
+
+### 1. List Chaos Presets
+
+**GET** `/chaos/presets`
+
+Returns all available chaos presets.
+
+**Example:**
+
+```bash
+curl http://localhost:4000/chaos/presets
+```
+
+**Response:**
+
+```json
+[
+  {
+    "id": "light",
+    "name": "Light Chaos",
+    "description": "Minimal chaos for production-like testing",
+    "probability": 0.05,
+    "scenarios": 4
+  },
+  {
+    "id": "moderate",
+    "name": "Moderate Chaos",
+    "description": "Balanced chaos for resilience testing",
+    "probability": 0.15,
+    "scenarios": 7
+  }
+]
+```
+
+### 2. Get Chaos Preset Details
+
+**GET** `/chaos/presets/:id`
+
+Returns detailed configuration for a specific chaos preset.
+
+**Example:**
+
+```bash
+curl http://localhost:4000/chaos/presets/aggressive
+```
+
+### 3. Get Chaos Status
+
+**GET** `/chaos/status`
+
+Returns the current chaos system status.
+
+**Example:**
+
+```bash
+curl http://localhost:4000/chaos/status
+```
+
+**Response:**
+
+```json
+{
+  "enabled": true,
+  "globalPreset": "realistic",
+  "availablePresets": ["light", "moderate", "realistic", "aggressive"],
+  "env": {
+    "CHAOS_ENABLED": "true",
+    "CHAOS_PRESET": "realistic"
+  }
+}
+```
+
+## Capability Input Reference
+
+### Inventory Check
+
+```json
+{
+  "sku": "SKU-001",
+  "locationId": "WH-01"  // optional
+}
+```
+
+### Shipment Tracking
+
+```json
+{
+  "shipmentId": "SHIP-001"
+}
+```
+
+### Equipment Availability Check
+
+```json
+{
+  "equipmentType": "forklift",
+  "zoneId": "ZONE-A"  // optional
+}
+```
+
+### Dock Appointment Scheduling
+
+```json
+{
+  "date": "2025-11-21",
+  "dockDoorId": "DOCK-01",
+  "appointmentType": "inbound"  // optional: "inbound" or "outbound"
+}
+```
+
+## Environment Variables
+
+- `CHAOS_ENABLED`: Enable/disable chaos injection (`true`/`false`)
+- `CHAOS_PRESET`: Global chaos preset (`light`/`moderate`/`realistic`/`aggressive`)
+- `MONGO_URI`: MongoDB connection string
+- `DB_NAME`: Database name
+- `PORT`: Server port (default: 4000)
+
+## Related APIs
+
+- [Persona API](./persona-api.md) - Discover personas and their capabilities
+- [Chaos Engineering API](./chaos-api.md) - Configure chaos injection policies
+- [World API](./world-api.md) - Manage world contexts for capability execution

packages/controlmart/docs/api/chaos-api.md

@@ -0,0 +1,628 @@
+# Chaos Engineering API Documentation
+
+## Overview
+
+The Chaos Engineering API provides endpoints for managing chaos injection configuration in the Morpheus platform. Chaos engineering helps test system resilience by intentionally injecting failures, data corruption, and other anomalies during capability execution.
+
+## Base URL
+
+```
+http://localhost:4000
+```
+
+## Chaos Priority Cascade
+
+The Morpheus platform uses a priority cascade for chaos configuration resolution:
+
+1. **ENV** - Environment variables (`CHAOS_ENABLED`, `CHAOS_PRESET`)
+2. **Step** - Step-level chaos policy (in OD definition)
+3. **OD** - Operational Descriptor-level chaos policy
+4. **Capability** - Capability-level chaos override
+5. **World** - World-level chaos policy
+6. **Global** - Global preset loaded at startup
+
+Higher priority levels override lower levels. This allows fine-grained control over chaos injection at different granularities.
+
+## Global Chaos Endpoints
+
+### 1. List All Chaos Presets
+
+**GET** `/chaos/presets`
+
+Returns all available chaos presets with metadata. Presets are pre-configured chaos policies that can be applied at any level.
+
+**Example:**
+
+```bash
+curl http://localhost:4000/chaos/presets
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "count": 4,
+  "data": [
+    {
+      "id": "light",
+      "name": "Light Chaos",
+      "description": "Minimal chaos for production-like testing",
+      "probability": 0.05,
+      "scenarioCount": 4
+    },
+    {
+      "id": "moderate",
+      "name": "Moderate Chaos",
+      "description": "Balanced chaos for resilience testing",
+      "probability": 0.15,
+      "scenarioCount": 7
+    },
+    {
+      "id": "realistic",
+      "name": "Realistic Chaos",
+      "description": "Real-world failure patterns for comprehensive testing",
+      "probability": 0.25,
+      "scenarioCount": 11
+    },
+    {
+      "id": "aggressive",
+      "name": "Aggressive Chaos",
+      "description": "High-frequency chaos for stress testing",
+      "probability": 0.40,
+      "scenarioCount": 11
+    }
+  ]
+}
+```
+
+### 2. Get Chaos Preset Details
+
+**GET** `/chaos/presets/:id`
+
+Returns the full chaos policy configuration for a specific preset, including all scenarios and their configurations.
+
+**Path Parameters:**
+- `id` (string, required): Preset ID (e.g., "light", "moderate", "realistic", "aggressive")
+
+**Example:**
+
+```bash
+curl http://localhost:4000/chaos/presets/realistic
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "enabled": true,
+    "probability": 0.25,
+    "scenarios": [
+      {
+        "type": "missing_data",
+        "weight": 20,
+        "description": "Records not found or empty results",
+        "config": {
+          "missingRecords": true,
+          "throwError": true
+        }
+      },
+      {
+        "type": "data_corruption",
+        "weight": 15,
+        "description": "Corrupt critical fields in responses",
+        "config": {
+          "corruptFields": ["id", "status"],
+          "corruptionType": "null"
+        }
+      },
+      {
+        "type": "stale_data",
+        "weight": 15,
+        "description": "Return outdated data",
+        "config": {
+          "staleDataAge": 60
+        }
+      },
+      {
+        "type": "partial_data",
+        "weight": 15,
+        "description": "Return incomplete results",
+        "config": {
+          "partialResults": {
+            "percentage": 50,
+            "randomize": true
+          }
+        }
+      }
+    ],
+    "seed": undefined
+  }
+}
+```
+
+### 3. Get Chaos System Status
+
+**GET** `/chaos/status`
+
+Returns the current global chaos system configuration and statistics.
+
+**Example:**
+
+```bash
+curl http://localhost:4000/chaos/status
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "enabled": true,
+    "activePreset": "realistic",
+    "stats": {
+      "presetCount": 4,
+      "worldPolicyCount": 2,
+      "capabilityOverrideCount": 0,
+      "odOverrideCount": 0
+    }
+  }
+}
+```
+
+**Status Fields:**
+- `enabled`: Whether chaos is globally enabled (from `CHAOS_ENABLED` env var)
+- `activePreset`: Current global preset name (from `CHAOS_PRESET` env var)
+- `stats.presetCount`: Number of available chaos presets
+- `stats.worldPolicyCount`: Number of worlds with custom chaos policies
+- `stats.capabilityOverrideCount`: Number of capabilities with chaos overrides
+- `stats.odOverrideCount`: Number of ODs with chaos policies
+
+## World-Specific Chaos Endpoints
+
+Worlds can have their own chaos policies that override the global configuration for all capabilities executed in that world context.
+
+### 4. Get World Chaos Configuration
+
+**GET** `/world/:worldId/chaos`
+
+Returns the chaos policy configured for a specific world.
+
+**Path Parameters:**
+- `worldId` (string, required): World ID (MongoDB ObjectId)
+
+**Example:**
+
+```bash
+curl http://localhost:4000/world/673d9a8f1234567890abcdef/chaos
+```
+
+**Response:**
+
+```json
+{
+  "worldId": "673d9a8f1234567890abcdef",
+  "worldName": "chaos-test-world",
+  "chaos": {
+    "enabled": true,
+    "probability": 0.3,
+    "scenarios": [
+      {
+        "type": "missing_data",
+        "weight": 50,
+        "description": "Simulate missing inventory records",
+        "config": {
+          "missingRecords": true,
+          "throwError": false
+        }
+      },
+      {
+        "type": "data_corruption",
+        "weight": 30,
+        "description": "Corrupt quantity fields",
+        "config": {
+          "corruptFields": ["quantity", "available"],
+          "corruptionType": "wrong_type"
+        }
+      },
+      {
+        "type": "rate_limit",
+        "weight": 20,
+        "description": "Simulate API rate limiting",
+        "config": {
+          "rateLimitDelay": 2000,
+          "rateLimitMessage": "Rate limit exceeded"
+        }
+      }
+    ],
+    "seed": "test-seed-123"
+  }
+}
+```
+
+**Default Response (No Chaos Configured):**
+
+```json
+{
+  "worldId": "673d9a8f1234567890abcdef",
+  "worldName": "normal-world",
+  "chaos": {
+    "enabled": false,
+    "probability": 0.0,
+    "scenarios": []
+  }
+}
+```
+
+### 5. Update World Chaos Configuration
+
+**PUT** `/world/:worldId/chaos`
+
+Sets or updates the chaos policy for a specific world. This configuration will apply to all capabilities executed in this world.
+
+**Path Parameters:**
+- `worldId` (string, required): World ID (MongoDB ObjectId)
+
+**Request Body:**
+
+```json
+{
+  "enabled": true,
+  "probability": 0.2,
+  "scenarios": [
+    {
+      "type": "missing_data",
+      "weight": 60,
+      "description": "Simulate missing records",
+      "config": {
+        "missingRecords": true,
+        "throwError": true
+      }
+    },
+    {
+      "type": "stale_data",
+      "weight": 40,
+      "description": "Return outdated data",
+      "config": {
+        "staleDataAge": 30
+      }
+    }
+  ],
+  "seed": "reproducible-chaos-seed"
+}
+```
+
+**Example:**
+
+```bash
+curl -X PUT http://localhost:4000/world/673d9a8f1234567890abcdef/chaos \
+  -H "Content-Type: application/json" \
+  -d '{
+    "enabled": true,
+    "probability": 0.2,
+    "scenarios": [
+      {
+        "type": "missing_data",
+        "weight": 60,
+        "description": "Simulate missing records",
+        "config": {
+          "missingRecords": true,
+          "throwError": true
+        }
+      }
+    ]
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "worldId": "673d9a8f1234567890abcdef",
+  "chaos": {
+    "enabled": true,
+    "probability": 0.2,
+    "scenarios": [...]
+  },
+  "message": "World chaos configuration updated successfully"
+}
+```
+
+### 6. Delete World Chaos Configuration
+
+**DELETE** `/world/:worldId/chaos`
+
+Removes the custom chaos policy from a world, causing it to fall back to the global chaos configuration.
+
+**Path Parameters:**
+- `worldId` (string, required): World ID (MongoDB ObjectId)
+
+**Example:**
+
+```bash
+curl -X DELETE http://localhost:4000/world/673d9a8f1234567890abcdef/chaos
+```
+
+**Response:**
+
+```json
+{
+  "worldId": "673d9a8f1234567890abcdef",
+  "message": "World chaos configuration removed successfully"
+}
+```
+
+## Chaos Policy Schema
+
+### ChaosPolicy Object
+
+```typescript
+{
+  enabled: boolean;          // Whether chaos injection is enabled
+  probability: number;       // 0.0 to 1.0 - overall chance chaos occurs
+  scenarios: ChaosScenario[]; // Array of possible chaos scenarios
+  seed?: string;             // Optional seed for reproducible chaos
+}
+```
+
+### ChaosScenario Object
+
+```typescript
+{
+  type: string;              // Scenario type (see Chaos Scenario Types below)
+  weight: number;            // Relative probability weight (higher = more likely)
+  description: string;       // Human-readable description
+  config: ChaosConfig;       // Scenario-specific configuration
+}
+```
+
+## Chaos Scenario Types
+
+### 1. missing_data
+Simulates missing records or empty results from data sources.
+
+**Config:**
+```json
+{
+  "missingRecords": true,      // Return empty results
+  "missingFields": ["field1"], // Remove specific fields (optional)
+  "throwError": true           // Throw error vs return empty (default: true)
+}
+```
+
+### 2. data_corruption
+Corrupts fields in response data with null, wrong types, or invalid values.
+
+**Config:**
+```json
+{
+  "corruptFields": ["id", "status"],
+  "corruptionType": "null" | "wrong_type" | "invalid_format" | "random_value"
+}
+```
+
+### 3. stale_data
+Returns outdated data to simulate caching issues or sync delays.
+
+**Config:**
+```json
+{
+  "staleDataAge": 60  // Age in minutes
+}
+```
+
+### 4. format_change
+Simulates breaking schema changes in data structures.
+
+**Config:**
+```json
+{
+  "schemaChanges": [
+    {
+      "field": "oldField",
+      "change": "rename",
+      "newName": "newField"
+    }
+  ]
+}
+```
+
+### 5. permission_denied
+Simulates access control failures.
+
+**Config:**
+```json
+{
+  "permissionError": "Access denied: insufficient permissions"
+}
+```
+
+### 6. rate_limit
+Simulates API rate limiting with delays.
+
+**Config:**
+```json
+{
+  "rateLimitDelay": 2000,  // Delay in ms
+  "rateLimitMessage": "Rate limit exceeded, please retry"
+}
+```
+
+### 7. partial_data
+Returns incomplete data sets.
+
+**Config:**
+```json
+{
+  "partialResults": {
+    "percentage": 50,      // Percentage of data to return (0-100)
+    "randomize": true      // Random subset vs first N items
+  }
+}
+```
+
+### 8. duplicate_data
+Injects duplicate records in results.
+
+**Config:**
+```json
+{
+  "duplicateCount": 2  // Number of duplicates to create
+}
+```
+
+### 9. invalid_state
+Returns records in invalid or conflicting states.
+
+**Config:**
+```json
+{
+  "invalidStates": ["CANCELLED_BUT_ACTIVE", "SHIPPED_NO_TRACKING"]
+}
+```
+
+### 10. dependency_failure
+Simulates downstream service failures.
+
+**Config:**
+```json
+{
+  "dependencyService": "inventory-service",
+  "cascadeFailure": true  // Propagate failure to other steps
+}
+```
+
+### 11. timing_issue
+Introduces timing-related problems like race conditions or delays.
+
+**Config:**
+```json
+{
+  "delay": 5000,  // Delay in ms
+  "timeout": true // Simulate timeout
+}
+```
+
+## Chaos Telemetry
+
+When chaos is enabled, capability execution responses include detailed telemetry about which chaos scenarios were injected. See the [Capabilities API documentation](./capabilities-api.md#chaos-telemetry) for details.
+
+## Environment Variables
+
+- `CHAOS_ENABLED`: Enable/disable chaos injection globally (`"true"`/`"false"`)
+- `CHAOS_PRESET`: Global chaos preset to load at startup (`"light"`, `"moderate"`, `"realistic"`, `"aggressive"`)
+- `CHAOS_SEED`: Global seed for reproducible chaos (optional)
+
+## Use Cases
+
+### 1. Testing System Resilience
+
+Enable chaos to test how your system handles various failure modes:
+
+```bash
+# Set aggressive chaos for stress testing
+export CHAOS_ENABLED=true
+export CHAOS_PRESET=aggressive
+
+# Run tests and observe behavior
+```
+
+### 2. World-Specific Testing
+
+Create worlds with different chaos levels for controlled testing:
+
+```bash
+# Create a chaos test world
+WORLD_ID=$(curl -X POST http://localhost:4000/world \
+  -H "Content-Type: application/json" \
+  -d '{"name": "chaos-test"}' | jq -r '.worldId')
+
+# Configure aggressive chaos for this world only
+curl -X PUT "http://localhost:4000/world/$WORLD_ID/chaos" \
+  -H "Content-Type: application/json" \
+  -d @realistic-chaos.json
+
+# Execute capabilities in this world - they will experience chaos
+curl -X POST http://localhost:4000/capabilities/inventory-check/execute \
+  -H "Content-Type: application/json" \
+  -d "{\"worldId\": \"$WORLD_ID\", \"inputs\": {}}"
+```
+
+### 3. Reproducible Chaos Testing
+
+Use seeds for deterministic chaos injection:
+
+```bash
+# Configure chaos with a seed
+curl -X PUT "http://localhost:4000/world/$WORLD_ID/chaos" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "enabled": true,
+    "probability": 0.5,
+    "seed": "test-run-1",
+    "scenarios": [...]
+  }'
+
+# Run the same test multiple times - chaos will be identical each time
+```
+
+### 4. Gradual Chaos Introduction
+
+Start with light chaos and gradually increase:
+
+```bash
+# Week 1: Light chaos
+export CHAOS_PRESET=light
+
+# Week 2: Moderate chaos
+export CHAOS_PRESET=moderate
+
+# Week 3: Realistic chaos
+export CHAOS_PRESET=realistic
+
+# Observe application behavior at each level
+```
+
+## Error Responses
+
+### 400 Bad Request
+
+```json
+{
+  "success": false,
+  "error": "worldId is required"
+}
+```
+
+### 404 Not Found
+
+```json
+{
+  "success": false,
+  "error": "Chaos preset not found: invalid-preset"
+}
+```
+
+```json
+{
+  "success": false,
+  "error": "World not found"
+}
+```
+
+### 500 Internal Server Error
+
+```json
+{
+  "success": false,
+  "error": "Failed to update world chaos"
+}
+```
+
+## Related APIs
+
+- [Capabilities API](./capabilities-api.md) - Execute capabilities and view chaos telemetry
+- [World API](./world-api.md) - Manage worlds and their configurations

packages/controlmart/docs/api/persona-api.md

@@ -0,0 +1,265 @@
+# Persona API Documentation
+
+## Overview
+
+The Persona API provides endpoints for discovering personas (user roles) and their associated capabilities in the Morpheus platform. Personas represent different types of users in a supply chain environment (e.g., warehouse workers, store managers, logistics coordinators).
+
+## Base URL
+
+```
+http://localhost:4000
+```
+
+## Endpoints
+
+### 1. List All Personas
+
+**GET** `/personas`
+
+Returns all available personas with optional filtering by role, department, access level, or tags.
+
+**Query Parameters:**
+- `role` (string, optional): Filter by role (e.g., "operations", "management", "specialist")
+- `department` (string, optional): Filter by department (e.g., "warehouse", "store", "logistics")
+- `accessLevel` (string, optional): Filter by access level (e.g., "operational", "supervisory", "executive")
+- `tags` (string, optional): Comma-separated list of tags to filter by
+
+**Example Requests:**
+
+```bash
+# Get all personas
+curl http://localhost:4000/personas
+
+# Filter by role
+curl "http://localhost:4000/personas?role=operations"
+
+# Filter by department
+curl "http://localhost:4000/personas?department=warehouse"
+
+# Filter by access level
+curl "http://localhost:4000/personas?accessLevel=operational"
+
+# Filter by multiple tags
+curl "http://localhost:4000/personas?tags=frontline,operational"
+
+# Combined filters
+curl "http://localhost:4000/personas?role=operations&department=warehouse"
+```
+
+**Response:**
+
+```json
+{
+  "count": 5,
+  "personas": [
+    {
+      "id": "warehouse-worker",
+      "name": "Warehouse Worker",
+      "description": "Frontline warehouse operations staff",
+      "role": "operations",
+      "department": "warehouse",
+      "accessLevel": "operational",
+      "capabilityIds": [
+        "inventory-check",
+        "shipment-tracking",
+        "equipment-availability"
+      ],
+      "tags": ["frontline", "operational", "warehouse"]
+    },
+    {
+      "id": "store-manager",
+      "name": "Store Manager",
+      "description": "Retail store manager overseeing operations",
+      "role": "management",
+      "department": "store",
+      "accessLevel": "supervisory",
+      "capabilityIds": [
+        "inventory-check",
+        "order-fulfillment-status"
+      ],
+      "tags": ["management", "retail", "supervisory"]
+    }
+  ]
+}
+```
+
+### 2. Get Persona by ID
+
+**GET** `/personas/:personaId`
+
+Returns a single persona by its ID.
+
+**Path Parameters:**
+- `personaId` (string, required): Unique identifier for the persona
+
+**Example:**
+
+```bash
+curl http://localhost:4000/personas/warehouse-worker
+```
+
+**Response:**
+
+```json
+{
+  "id": "warehouse-worker",
+  "name": "Warehouse Worker",
+  "description": "Frontline warehouse operations staff performing daily tasks like receiving, putaway, picking, and shipping",
+  "role": "operations",
+  "department": "warehouse",
+  "accessLevel": "operational",
+  "capabilityIds": [
+    "inventory-check",
+    "shipment-tracking",
+    "equipment-availability",
+    "dock-appointment-check"
+  ],
+  "tags": ["frontline", "operational", "warehouse", "physical-work"]
+}
+```
+
+### 3. Get Capabilities for a Persona
+
+**GET** `/personas/:personaId/capabilities`
+
+Returns all capabilities associated with a specific persona, including full capability details.
+
+**Path Parameters:**
+- `personaId` (string, required): Unique identifier for the persona
+
+**Example:**
+
+```bash
+curl http://localhost:4000/personas/warehouse-worker/capabilities
+```
+
+**Response:**
+
+```json
+{
+  "personaId": "warehouse-worker",
+  "personaName": "Warehouse Worker",
+  "capabilityCount": 4,
+  "capabilities": [
+    {
+      "id": "inventory-check",
+      "name": "Inventory Check",
+      "description": "Check current inventory levels for one or more SKUs",
+      "tags": {
+        "domain": ["inventory", "warehousing"],
+        "complexity": "simple",
+        "services": ["wms"],
+        "personas": ["warehouse-worker", "store-manager"],
+        "patterns": ["sequential"]
+      },
+      "odId": "inventory-check-standard-v1",
+      "version": "1.0.0",
+      "metadata": {
+        "author": "morpheus-team",
+        "estimatedDuration": 2000
+      }
+    },
+    {
+      "id": "shipment-tracking",
+      "name": "Shipment Tracking",
+      "description": "Track a shipment and retrieve its status and location",
+      "tags": {
+        "domain": ["transportation", "logistics"],
+        "complexity": "simple",
+        "services": ["tms"],
+        "personas": ["warehouse-worker", "logistics-coordinator"],
+        "patterns": ["sequential"]
+      },
+      "odId": "shipment-tracking-standard-v1",
+      "version": "1.0.0"
+    }
+  ]
+}
+```
+
+## Persona Schema
+
+### Persona Object
+
+```typescript
+{
+  id: string;              // Unique identifier (e.g., "warehouse-worker")
+  name: string;            // Display name (e.g., "Warehouse Worker")
+  description: string;     // Detailed description of the persona
+  role: string;            // Role category (operations, management, specialist)
+  department: string;      // Department (warehouse, store, logistics, etc.)
+  accessLevel: string;     // Access level (operational, supervisory, executive)
+  capabilityIds: string[]; // Array of capability IDs this persona can execute
+  tags: string[];          // Additional tags for filtering and categorization
+}
+```
+
+## Use Cases
+
+### 1. Building Role-Based UIs
+
+Use the persona API to build role-specific interfaces that only show capabilities relevant to the current user's role:
+
+```bash
+# Get all capabilities for warehouse workers
+curl http://localhost:4000/personas/warehouse-worker/capabilities
+
+# Use the response to build a UI that shows only these capabilities
+```
+
+### 2. Capability Discovery
+
+Find which personas can perform a specific capability:
+
+```bash
+# Get all personas
+curl http://localhost:4000/personas
+
+# Filter the response to find which personas include a specific capabilityId
+```
+
+### 3. Access Control
+
+Validate whether a persona should have access to a capability:
+
+```bash
+# Get persona details
+curl http://localhost:4000/personas/warehouse-worker
+
+# Check if the desired capabilityId is in the persona's capabilityIds array
+```
+
+## Common Personas
+
+The Morpheus platform includes these standard personas:
+
+| Persona ID | Name | Department | Role | Typical Capabilities |
+|------------|------|------------|------|---------------------|
+| `warehouse-worker` | Warehouse Worker | Warehouse | Operations | Inventory check, shipment tracking, equipment availability |
+| `store-manager` | Store Manager | Store | Management | Inventory check, order fulfillment status |
+| `logistics-coordinator` | Logistics Coordinator | Logistics | Specialist | Shipment tracking, route optimization, carrier rate lookup |
+| `supply-chain-manager` | Supply Chain Manager | Supply Chain | Management | Advanced analytics, network optimization |
+| `inventory-analyst` | Inventory Analyst | Inventory | Specialist | Inventory analytics, forecasting, replenishment |
+
+## Error Responses
+
+### 404 Not Found
+
+```json
+{
+  "error": "Persona 'invalid-persona' not found"
+}
+```
+
+### 500 Internal Server Error
+
+```json
+{
+  "error": "Error message describing what went wrong"
+}
+```
+
+## Related APIs
+
+- [Capabilities API](./capabilities-api.md) - Execute and discover capabilities
+- [World API](./world-api.md) - Manage world contexts for capability execution

packages/controlmart/driver-service-mesh.ts

@@ -0,0 +1,27 @@
+
+import { ServiceMesh } from './src/utils/service-mesh.util';
+
+console.log('--- Service Mesh Driver & Test ---');
+
+// 1. Inspect Registry Structure
+const registry = ServiceMesh.getRegistry();
+const registeredServices = Object.keys(registry);
+console.log(`[INFO] Registered Services (${registeredServices.length}):`, registeredServices.join(', '));
+
+// 2. Check for System Service Docs
+console.log('\n--- Checking System Docs ---');
+const systemEndpoints = ServiceMesh.findEndpoints('system');
+console.log(`[INFO] Found ${systemEndpoints.length} System endpoints.`);
+
+if (systemEndpoints.length > 0) {
+    systemEndpoints.forEach(ep => console.log(`   -> [${ep.method.toUpperCase()}] ${ep.path}`));
+    console.log('\n--- Sample formatted doc for /docs/mesh ---');
+    const meshEp = systemEndpoints.find(ep => ep.path === '/docs/mesh');
+    if (meshEp) {
+        console.log(ServiceMesh.getFormattedEndpointDocs(meshEp));
+    }
+} else {
+    console.error("[FAIL] No System endpoints found. Check docs.app.ts parsing.");
+}
+
+console.log('\n--- Driver Complete ---');

packages/controlmart/eslint.config.js

@@ -0,0 +1,54 @@
+import tsParser from "@typescript-eslint/parser";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import importPlugin from "eslint-plugin-import";
+import unusedImports from "eslint-plugin-unused-imports";
+import prettierConfig from "eslint-config-prettier";
+
+export default [
+  prettierConfig,
+
+  {
+    files: ["**/*.ts"],
+    ignores: ["dist", "build", "node_modules"],
+
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: process.cwd(),
+      },
+      sourceType: "module",
+      ecmaVersion: "latest",
+    },
+
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+      import: importPlugin,
+      "unused-imports": unusedImports,
+    },
+
+    rules: {
+      "unused-imports/no-unused-imports": "error",
+
+      "unused-imports/no-unused-vars": [
+        "warn",
+        {
+          vars: "all",
+          varsIgnorePattern: "^_",
+          args: "after-used",
+          argsIgnorePattern: "^_",
+        },
+      ],
+
+      "@typescript-eslint/no-unused-vars": "off",
+
+      "import/order": [
+        "warn",
+        {
+          groups: ["builtin", "external", "internal", ["parent", "sibling"], "index"],
+          "newlines-between": "always",
+        },
+      ],
+    },
+  },
+];

packages/controlmart/index.ts

@@ -0,0 +1,17 @@
+import { existsSync } from "fs";
+import path from "path";
+
+// Development Entry Point
+// This bypasses the Setup UI and directly launches the main application.
+// It assumes the developer has a .env file or environment variables set.
+
+(async () => {
+  const envPath = path.join(process.cwd(), ".env");
+
+  if (!existsSync(envPath)) {
+    console.warn(`[dev] ⚠️  No .env file found at ${envPath}. Application may fail if variables are missing.`);
+  }
+
+  // Import the main application logic (migrations, seeding, server start)
+  await import("./main");
+})();

packages/controlmart/main.ts

@@ -0,0 +1,242 @@
+import { createApplication } from "./src/application/application.app";
+import { World } from "./src/models/world.model";
+import { WorldLog } from "./src/models/logs.model";
+import {
+  createAppLogger,
+  createHttpLogger,
+} from "./src/utils/logger.util";
+import { getErrorMessage } from "./src/utils/error.util";
+// Research branch imports
+import { loadEnv } from "./src/utils/env.util";
+import { registerTicketingJob } from "./src/jobs/ticketing.job";
+import { registerDeleteLogQueueJob } from "./src/jobs/delete-logqueue.job";
+import { startScheduler, stopScheduler } from "./src/services/scheduler.service";
+import { initializeODScheduling } from "./src/operational-descriptor/schedule.od";
+import { createCollectionsIfNotExist, connectMongo, syncModelIndexes } from "./src/services/mongo.service";
+import { auditLogger } from "./src/services/audit-logger.service";
+// od-arch branch imports
+// import { seedBusinessRules } from "./src/business-rules/seed-rules"; // Temporarily disabled
+import { initializeODRegistry } from "./src/ods/index";
+import { WorldRepository } from "./src/repository";
+import { ChaosConfigRegistry } from "./src/services/chaos-config.registry";
+import { capabilityCatalog } from './src/services/capability-catalog.service';
+import { personaRegistry } from './src/services/persona-registry.service';
+import { autoSeedIfEmpty } from './src/services/auto-seed.service';
+
+const envValues = loadEnv();
+
+// Parse CLI arguments
+const forceSeed = process.argv.includes('--force-seed');
+
+export const logger = createAppLogger({});
+
+// Timeout wrapper for startup operations to prevent indefinite hangs
+const withTimeout = <T>(
+  promise: Promise<T>,
+  ms: number,
+  operation: string
+): Promise<T> => {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`${operation} timed out after ${ms}ms`)),
+        ms
+      )
+    ),
+  ]);
+};
+
+
+export const httpLogger = createHttpLogger(logger);
+export const mongoLogger = auditLogger;
+
+
+try {
+  // 1. Validate Critical Configuration
+  if (!envValues.MONGO_URI || !envValues.OPENAI_API_KEY) {
+    logger.warn("[startup] Missing critical configuration (MONGO_URI or OPENAI_API_KEY). Launching Setup Mode...");
+    const { startSetup } = await import("./src/application/setup.app");
+    await startSetup();
+    // Keep process alive for setup server
+    await new Promise(() => { });
+  }
+
+  // 2. Run Boot Check (Database Connection)
+  try {
+    await withTimeout(
+      connectMongo({
+        uri: envValues.MONGO_URI,
+        dbName: envValues.DB_NAME,
+        log: true,
+      }),
+      30000,
+      'connectMongo'
+    );
+  } catch (err) {
+    logger.error({ error: getErrorMessage(err) }, "[startup] Database connection failed. Launching Setup Mode...");
+    const { startSetup } = await import("./src/application/setup.app");
+    await startSetup();
+    // Keep process alive for setup server
+    await new Promise(() => { });
+  }
+  await withTimeout(
+    createCollectionsIfNotExist({
+      models: [World, WorldLog],
+      collectionNames: ["schedules"],
+      log: true,
+    }),
+    30000,
+    'createCollectionsIfNotExist'
+  );
+
+  // Seed business rules on startup
+  // await seedBusinessRules();
+
+  await withTimeout(startScheduler(), 30000, 'startScheduler');
+  initializeODScheduling();
+
+  // Register Ticketing Job
+  await withTimeout(registerTicketingJob(), 30000, 'registerTicketingJob');
+
+  // Register Log Cleanup Job
+  await withTimeout(registerDeleteLogQueueJob(), 30000, 'registerDeleteLogQueueJob');
+
+  // Initialize OD Registry with all available OD builders
+  initializeODRegistry();
+  logger.info('OD Registry initialized');
+
+  // Auto-seed database if collections are empty (or force mode)
+  if (forceSeed) {
+    logger.info('[startup] Force seed mode enabled via --force-seed');
+  }
+  const seedResult = await withTimeout(
+    autoSeedIfEmpty(logger, { force: forceSeed }),
+    120000,
+    'autoSeedIfEmpty'
+  );
+  if (seedResult.capabilities.seeded || seedResult.personas.seeded || seedResult.knowledgeGraph.seeded) {
+    logger.info({ seedResult }, 'Auto-seeding completed');
+  }
+
+  // Initialize capability and persona services from MongoDB
+  const initializedServices: string[] = [];
+
+  // 1. Initialize Capability Catalog
+  try {
+    await withTimeout(capabilityCatalog.initialize(), 60000, 'capabilityCatalog.initialize');
+    initializedServices.push(`CapabilityCatalog (${capabilityCatalog.count()} capabilities)`);
+  } catch (error) {
+    const errorMsg = getErrorMessage(error);
+    if (errorMsg.includes('CapabilityCatalog not initialized')) {
+      logger.warn('Capability catalog database is empty. Run migration script: bun run scripts/migrate-capabilities.ts');
+    } else {
+      logger.error({ error: errorMsg }, 'Failed to initialize capability catalog');
+    }
+  }
+
+  // 2. Initialize Persona Registry
+  try {
+    await withTimeout(personaRegistry.initialize(), 60000, 'personaRegistry.initialize');
+    initializedServices.push(`PersonaRegistry (${personaRegistry.getCount()} personas)`);
+  } catch (error) {
+    const errorMsg = getErrorMessage(error);
+    if (errorMsg.includes('PersonaRegistry not initialized')) {
+      logger.warn('Persona registry database is empty. Run migration script: bun run scripts/migrate-personas.ts');
+    } else {
+      logger.error({ error: errorMsg }, 'Failed to initialize persona registry');
+    }
+  }
+
+  // 3. Initialize Knowledge Graph
+  try {
+    const { knowledgeGraph } = await import('./src/services/knowledge-graph.service');
+    await withTimeout(knowledgeGraph.initialize(), 60000, 'knowledgeGraph.initialize');
+    initializedServices.push('KnowledgeGraph');
+  } catch (error) {
+    const errorMsg = getErrorMessage(error);
+    if (errorMsg.includes('Knowledge graph database is empty')) {
+      logger.warn('Knowledge graph database is empty. Run migration script: bun run scripts/migrate-knowledge-graph.ts');
+    } else {
+      logger.error({ error: errorMsg }, 'Failed to initialize knowledge graph');
+    }
+  }
+
+  // Log summary of initialized services
+  if (initializedServices.length > 0) {
+    logger.info({ services: initializedServices }, 'Initialized services');
+  } else {
+    logger.warn('No services initialized - database appears empty. Application will start but some features may be unavailable.');
+  }
+
+  // Load persisted world chaos configurations into registry
+  // Load persisted world chaos configurations into registry
+  try {
+    const worldsResult = await withTimeout(
+      WorldRepository.getAllWorlds(),
+      60000,
+      'WorldRepository.getAllWorlds'
+    );
+    // Handle both cursor pagination (items) and offset pagination (data) return types
+    const worldsList = 'items' in worldsResult ? worldsResult.items : worldsResult.data;
+    let chaosCount = 0;
+    for (const world of worldsList) {
+      if (world.chaos) {
+        const worldId = (world as any)._id?.toString() || '';
+        if (worldId) {
+          ChaosConfigRegistry.setWorldChaosConfiguration(worldId, world.chaos);
+          chaosCount++;
+        }
+      }
+    }
+    logger.info(
+      { count: chaosCount },
+      'Loaded world chaos configurations'
+    );
+  } catch (error) {
+    logger.error({ error: getErrorMessage(error) }, 'Failed to load chaos configs');
+  }
+
+  createApplication({
+    port: envValues.PORT,
+    host: process.env.HOST,
+    env: envValues.NODE_ENV,
+    logger,
+    httpLogger,
+  });
+
+  // Open Browser
+  // Defaults to opening unless disabled via flag or env var
+  const noBrowserFlag = process.argv.includes("--no-browser");
+  const noBrowserEnv = process.env.NO_BROWSER === "true";
+
+  if (!noBrowserFlag && !noBrowserEnv) {
+    logger.info(`[app] Opening browser at http://localhost:${envValues.PORT}/admin`);
+    Bun.spawn(["open", `http://localhost:${envValues.PORT}/admin`]);
+  }
+
+
+  syncModelIndexes({ log: true })
+    .then(() => logger.info('Index sync completed successfully'))
+    .catch((err) => logger.error({ error: getErrorMessage(err) }, 'Index sync failed'));
+
+  process.on("SIGTERM", async () => {
+    logger.info("SIGTERM received, shutting down gracefully");
+    await stopScheduler();
+    process.exit(0);
+  });
+
+  process.on("SIGINT", async () => {
+    logger.info("SIGINT received, shutting down gracefully");
+    await stopScheduler();
+    process.exit(0);
+  });
+} catch (err) {
+  logger.error(
+    {
+      error: getErrorMessage(err),
+    },
+    "[app] Application failed to start:",
+  );
+  process.exit(1);
+}

packages/controlmart/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "controlmart",
+  "module": "index.ts",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start": "bun run src/application/bootcheck.app.ts && bun run index.ts",
+    "run:local": "bun run build:ui && bun run dev",
+    "run:hf": "bun run start --no-browser",
+    "validate:annotations": "bun run src/scripts/validate-tool-annotations.ts",
+    "prebuild": "bun run validate:annotations",
+    "build": "tsc -p tsconfig.json ",
+    "dev": "bun run src/application/bootcheck.app.ts && bun run --watch index.ts",
+    "generate": "bun run index.ts",
+    "seed-dev": "bun run scripts/seed-dev-data.ts",
+    "lint": "bunx eslint . --ext .ts",
+    "lint:fix": "bunx eslint . --ext .ts --fix",
+    "fmt:fix": "bunx prettier --write .",
+    "fmt": "bunx prettier --check .",
+    "build:ui": "cd ui && bun install && bun run build",
+    "dev:ui": "cd ui && bun run dev",
+    "dev:full": "bun run build:ui && bun run dev --no-browser",
+    "build:binary": "bun build ./bootstrap.ts --compile --outfile morpheus-server",
+    "build:app": "bun run scripts/build-macos-app.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/compression": "^1.8.1",
+    "@types/cors": "^2.8.19",
+    "@types/graphlib": "^2.1.12",
+    "@types/morgan": "^1.9.10",
+    "@types/seedrandom": "^3.0.8",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "prettier": "^3.6.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^10.0.0",
+    "@hokify/agenda": "^6.3.0",
+    "@scalar/express-api-reference": "^0.8.22",
+    "@types/express": "^5.0.3",
+    "@types/jmespath": "^0.15.2",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
+    "ajv": "^8.17.1",
+    "compression": "^1.8.1",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^5.1.0",
+    "graphlib": "^2.1.8",
+    "helmet": "^8.1.0",
+    "jmespath": "^0.16.0",
+    "mongoose": "^8.19.0",
+    "morgan": "^1.10.1",
+    "openai": "^6.10.0",
+    "pino": "^10.0.0",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.1",
+    "seedrandom": "^3.0.5",
+    "slugify": "^1.6.6",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
+    "uuid": "^13.0.0",
+    "zod": "^4.1.11"
+  }
+}

packages/controlmart/scripts/build-macos-app.ts

@@ -0,0 +1,176 @@
+import { mkdirSync, chmodSync } from "node:fs";
+import { $ } from "bun";
+
+const APP_NAME = "Skyfall - Morpheus";
+const BUILD_DIR = "build-dist";
+const APP_BUNDLE = `${BUILD_DIR}/${APP_NAME}.app`;
+const CONTENTS_DIR = `${APP_BUNDLE}/Contents`;
+const MACOS_DIR = `${CONTENTS_DIR}/MacOS`;
+const RESOURCES_DIR = `${CONTENTS_DIR}/Resources`;
+
+console.log("Cleaning build directory...");
+await $`rm -rf ${BUILD_DIR}`;
+
+console.log("Building binary...");
+try {
+    // Build the standalone executable from the bootstrap script
+    await $`bun build ./bootstrap.ts --compile --outfile morpheus-server`;
+} catch (e) {
+    console.error("Build failed:", e);
+    process.exit(1);
+}
+
+console.log("Creating App Bundle structure...");
+// Create directories
+mkdirSync(MACOS_DIR, { recursive: true });
+mkdirSync(RESOURCES_DIR, { recursive: true });
+
+console.log("Moving binary...");
+// Move the built binary to the App Bundle
+// Move the built binary to the App Bundle
+await $`mv morpheus-server ${MACOS_DIR}/`;
+
+console.log("Copying UI assets...");
+// Copy dist/ui to Contents/MacOS/ui so the binary encounters it at ./ui
+try {
+    const uiSource = "dist/ui";
+    if (Bun.file(uiSource).size > 0 || (await $`ls ${uiSource}`.quiet()).exitCode === 0) {
+        await $`cp -R ${uiSource} ${MACOS_DIR}/ui`;
+    } else {
+        console.warn("Warning: dist/ui not found. UI will be missing.");
+    }
+} catch (e) {
+    console.warn("Failed to copy UI assets:", e);
+}
+
+console.log("Copying .env file...");
+try {
+    const envSource = ".env";
+    if (Bun.file(envSource).size > 0) {
+        await $`cp ${envSource} ${MACOS_DIR}/.env`;
+    } else {
+        console.warn("Warning: .env not found. App will launch in Setup Mode.");
+    }
+} catch (e) {
+    console.warn("Failed to copy .env:", e);
+}
+
+console.log("Copying App Icon...");
+try {
+    const iconSource = "assets/icon.icns";
+    if (Bun.file(iconSource).size > 0) {
+        await $`cp ${iconSource} ${RESOURCES_DIR}/AppIcon.icns`;
+    } else {
+        console.warn("Warning: assets/icon.icns not found. App will have default icon.");
+    }
+} catch (e) {
+    console.warn("Failed to copy icon:", e);
+}
+
+console.log("Creating Info.plist...");
+const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleName</key>
+    <string>${APP_NAME}</string>
+    <key>CFBundleDisplayName</key>
+    <string>Morpheus ControlMart</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.talkshopclub.morpheus</string>
+    <key>CFBundleVersion</key>
+    <string>1.0.0</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0.0</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleExecutable</key>
+    <string>MorpheusLauncher</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>11.0</string>
+    <key>LSUIElement</key>
+    <false/>
+</dict>
+</plist>`;
+await Bun.write(`${CONTENTS_DIR}/Info.plist`, plist);
+
+console.log("Creating Launcher script...");
+const launcher = `#!/bin/bash
+DIR=$(cd "$(dirname "$0")"; pwd)
+# Change CWD to the folder containing the .app bundle so .env is stored there
+cd "$DIR/../../.."
+LOG_FILE="/tmp/morpheus_app.log"
+
+# Kill any existing instances to prevent EADDRINUSE
+pkill -f "morpheus-server" || true
+
+export MORPHEUS_LAUNCHER=true
+
+while true; do
+    echo "$(date): Starting Morpheus..." >> "$LOG_FILE"
+    
+    # Run the server in background to allow signal trapping
+    "$DIR/morpheus-server" >> "$LOG_FILE" 2>&1 &
+    PID=$!
+    
+    # helper to kill server on exit
+    cleanup() {
+        echo "Stopping Morpheus..." >> "$LOG_FILE"
+        kill $PID
+        exit 0
+    }
+    trap cleanup SIGINT SIGTERM
+    
+    # Wait for the process to finish
+    wait $PID
+    EXIT_CODE=$?
+    
+    # Remove trap for normal exit handling
+    trap - SIGINT SIGTERM
+    
+    # Check for restart request (Exit Code 100)
+    if [ $EXIT_CODE -eq 100 ]; then
+        echo "Restart requested..." >> "$LOG_FILE"
+        sleep 1
+        continue
+    fi
+
+    if [ $EXIT_CODE -ne 0 ]; then
+        echo "Morpheus exited with code $EXIT_CODE" >> "$LOG_FILE"
+        
+        # Write error msg to temp file for safe reading
+        ERROR_FILE="/tmp/morpheus_error.txt"
+        tail -n 15 "$LOG_FILE" > "$ERROR_FILE"
+        
+        # Show native alert dialog reading from file
+        osascript -e "display dialog (read POSIX file \\"$ERROR_FILE\\") with title \\"Morpheus Error\\" buttons {\\"OK\\"} default button \\"OK\\" icon stop"
+    fi
+    
+    # Break loop for normal exit or error
+    break
+done
+
+exit $EXIT_CODE
+`;
+
+const launcherPath = `${MACOS_DIR}/MorpheusLauncher`;
+await Bun.write(launcherPath, launcher);
+
+// Make executable
+chmodSync(launcherPath, "755");
+chmodSync(`${MACOS_DIR}/morpheus-server`, "755");
+
+console.log("Signing app bundle (ad-hoc)...");
+try {
+    await $`codesign --force --deep --sign - ${APP_BUNDLE}`;
+} catch (e) {
+    console.warn("Warning: Ad-hoc signing failed. App strictly requires xattr -cr to run on other machines.");
+}
+
+console.log("Creating distribution zip...");
+await $`cd ${BUILD_DIR} && zip -r "${APP_NAME}.zip" "${APP_NAME}.app"`;
+
+console.log(`Successfully created ${APP_BUNDLE}`);
+console.log(`Distribution zip ready: ${BUILD_DIR}/${APP_NAME}.zip`);

packages/controlmart/scripts/measure-performance.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+
+/**
+ * Performance Baseline Measurement Script
+ *
+ * Measures execution time for all Phase 1 capabilities to establish baseline performance metrics.
+ * Run with: bun run scripts/measure-performance.ts
+ */
+
+import { connectMongo, disconnectMongo } from '../src/services/mongo.service';
+import { CapabilityExecutor } from '../src/services/capability-executor.service';
+import { WorldRepository } from '../src/repository/world.repository';
+import { capabilityCatalog } from '../src/services/capability-catalog.service';
+import { initializeODRegistry } from '../src/ods';
+
+interface PerformanceResult {
+  capabilityId: string;
+  capabilityName: string;
+  runs: number;
+  avgDurationMs: number;
+  minDurationMs: number;
+  maxDurationMs: number;
+  stdDeviation: number;
+  successRate: number;
+}
+
+async function measureCapabilityPerformance(
+  executor: CapabilityExecutor,
+  capabilityId: string,
+  worldId: string,
+  inputs: any,
+  runs: number = 10
+): Promise<PerformanceResult> {
+  const capability = capabilityCatalog.getById(capabilityId);
+  if (!capability) {
+    throw new Error(`Capability not found: ${capabilityId}`);
+  }
+
+  const durations: number[] = [];
+  let successCount = 0;
+
+  console.log(`\n📊 Measuring ${capability.name} (${runs} runs)...`);
+
+  for (let i = 0; i < runs; i++) {
+    try {
+      const result = await executor.execute({
+        capabilityId,
+        worldId,
+        inputs,
+      });
+
+      if (result.status === 'success' && result.durationMs) {
+        durations.push(result.durationMs);
+        successCount++;
+      }
+
+      process.stdout.write('.');
+    } catch (error) {
+      process.stdout.write('x');
+    }
+  }
+
+  console.log(' Done!');
+
+  // Calculate statistics
+  const avgDuration = durations.reduce((a, b) => a + b, 0) / durations.length;
+  const minDuration = Math.min(...durations);
+  const maxDuration = Math.max(...durations);
+
+  // Calculate standard deviation
+  const variance =
+    durations.reduce((sum, d) => sum + Math.pow(d - avgDuration, 2), 0) /
+    durations.length;
+  const stdDeviation = Math.sqrt(variance);
+
+  const successRate = (successCount / runs) * 100;
+
+  return {
+    capabilityId,
+    capabilityName: capability.name,
+    runs,
+    avgDurationMs: Math.round(avgDuration),
+    minDurationMs: Math.round(minDuration),
+    maxDurationMs: Math.round(maxDuration),
+    stdDeviation: Math.round(stdDeviation),
+    successRate: Math.round(successRate),
+  };
+}
+
+async function main() {
+  console.log('🚀 Performance Baseline Measurement');
+  console.log('==================================\n');
+
+  // Connect to database
+  console.log('📦 Connecting to database...');
+  const mongoUri = process.env.MONGO_URI || 'mongodb://localhost:27017';
+  const dbName = process.env.DB_NAME || 'morpheus-test';
+  await connectMongo({ uri: mongoUri, dbName });
+
+  // Initialize OD Registry
+  console.log('🔧 Initializing OD Registry...');
+  initializeODRegistry();
+
+  // Create test world
+  console.log('🌍 Creating test world...');
+  const world = await WorldRepository.createWorld({
+    name: `perf-test-${Date.now()}`,
+    description: 'Performance testing world',
+    status: 'active',
+  });
+  console.log(`✅ World created: ${world._id}`);
+
+  const executor = new CapabilityExecutor();
+  const results: PerformanceResult[] = [];
+
+  // Disable chaos for baseline measurements
+  process.env.CHAOS_ENABLED = 'false';
+
+  // Test each capability
+  const capabilities = [
+    {
+      id: 'inventory-check',
+      inputs: { sku: 'SKU-001', locationId: 'WH-01' },
+    },
+    {
+      id: 'shipment-tracking',
+      inputs: { shipmentId: 'SHIP-001' },
+    },
+    {
+      id: 'equipment-availability-check',
+      inputs: { equipmentType: 'forklift', zoneId: 'ZONE-A' },
+    },
+    {
+      id: 'dock-appointment-scheduling',
+      inputs: {
+        date: '2025-11-21',
+        dockDoorId: 'DOCK-01',
+        appointmentType: 'inbound',
+      },
+    },
+  ];
+
+  for (const cap of capabilities) {
+    const result = await measureCapabilityPerformance(
+      executor,
+      cap.id,
+      world._id.toString(),
+      cap.inputs,
+      10
+    );
+    results.push(result);
+  }
+
+  // Print results
+  console.log('\n\n📈 Performance Baseline Results');
+  console.log('================================\n');
+
+  console.table(
+    results.map((r) => ({
+      Capability: r.capabilityName,
+      'Avg (ms)': r.avgDurationMs,
+      'Min (ms)': r.minDurationMs,
+      'Max (ms)': r.maxDurationMs,
+      'Std Dev': r.stdDeviation,
+      'Success Rate': `${r.successRate}%`,
+    }))
+  );
+
+  // Overall statistics
+  const totalAvg =
+    results.reduce((sum, r) => sum + r.avgDurationMs, 0) / results.length;
+  console.log(`\n📊 Overall Average: ${Math.round(totalAvg)}ms`);
+
+  // Save results to file
+  const timestamp = new Date().toISOString();
+  const report = {
+    timestamp,
+    environment: {
+      nodeVersion: process.version,
+      platform: process.platform,
+      chaosEnabled: false,
+    },
+    results,
+    summary: {
+      totalCapabilities: results.length,
+      overallAvgMs: Math.round(totalAvg),
+    },
+  };
+
+  await Bun.write(
+    'config/performance-baselines.json',
+    JSON.stringify(report, null, 2)
+  );
+  console.log('\n💾 Results saved to config/performance-baselines.json');
+
+  // Cleanup
+  console.log('\n🧹 Cleaning up...');
+  await WorldRepository.deleteWorld(world._id.toString());
+  await disconnectMongo();
+
+  console.log('✅ Done!\n');
+}
+
+main().catch((error) => {
+  console.error('❌ Error:', error);
+  process.exit(1);
+});

packages/controlmart/scripts/migrate-capabilities-to-db.ts

@@ -0,0 +1,163 @@
+/**
+ * Capability Migration Script
+ *
+ * Migrates capabilities from src/capabilities/catalog.ts to MongoDB.
+ * Idempotent - safe to run multiple times.
+ *
+ * Usage:
+ *   bun run scripts/migrate-capabilities-to-db.ts [--dry-run] [--force] [--clear-first]
+ *
+ * Options:
+ *   --dry-run      Preview changes without writing to database
+ *   --force        Update existing capabilities instead of skipping
+ *   --clear-first  Delete all existing capabilities before migration
+ */
+
+import { connectMongo, createCollectionsIfNotExist } from "../src/services/mongo.service";
+import { Capability } from "../src/models/capability.model";
+import { CapabilityRepository } from "../src/repository/capability.repository";
+import { INITIAL_CAPABILITIES } from "../src/capabilities/catalog";
+import { getErrorMessage } from "../src/utils/error.util";
+import { loadEnv } from "../src/utils/env.util";
+
+interface MigrateOptions {
+  dryRun?: boolean;
+  force?: boolean;
+  clearFirst?: boolean;
+}
+
+interface MigrationStats {
+  created: number;
+  updated: number;
+  skipped: number;
+  errors: number;
+}
+
+async function migrate(options: MigrateOptions = {}): Promise<void> {
+  console.log("[migrate-capabilities] Starting migration...");
+  console.log(`[migrate-capabilities] Options:`, {
+    dryRun: options.dryRun || false,
+    force: options.force || false,
+    clearFirst: options.clearFirst || false,
+  });
+
+  // Load environment variables
+  const env = loadEnv();
+
+  // Connect to MongoDB
+  await connectMongo({
+    uri: env.MONGO_URI,
+    dbName: env.DB_NAME,
+    log: true,
+  });
+
+  // Ensure collection exists with indexes
+  await createCollectionsIfNotExist({
+    models: [Capability],
+    log: true,
+  });
+
+  // Clear existing capabilities if requested
+  if (options.clearFirst) {
+    if (options.dryRun) {
+      console.log("[DRY-RUN] Would clear all existing capabilities");
+    } else {
+      console.log("[migrate-capabilities] Clearing existing capabilities...");
+      await (Capability as any).deleteMany({}).exec();
+      console.log("[migrate-capabilities] Cleared all capabilities");
+    }
+  }
+
+  // Migrate capabilities
+  console.log(`\n[migrate-capabilities] Migrating ${INITIAL_CAPABILITIES.length} capabilities...\n`);
+
+  const stats: MigrationStats = {
+    created: 0,
+    updated: 0,
+    skipped: 0,
+    errors: 0,
+  };
+
+  for (const capability of INITIAL_CAPABILITIES) {
+    try {
+      if (options.dryRun) {
+        console.log(`[DRY-RUN] Would create/update: ${capability.id} (${capability.name})`);
+        stats.created++;
+      } else {
+        // Check if capability already exists
+        const existing = await CapabilityRepository.findById(capability.id);
+
+        if (existing && !options.force) {
+          console.log(`⏭️  Skipping existing: ${capability.id} (${capability.name})`);
+          stats.skipped++;
+        } else if (existing && options.force) {
+          // Update existing capability
+          await CapabilityRepository.update(capability.id, capability);
+          console.log(`✏️  Updated: ${capability.id} (${capability.name})`);
+          stats.updated++;
+        } else {
+          // Create new capability
+          await CapabilityRepository.create(capability);
+          console.log(`✅ Created: ${capability.id} (${capability.name})`);
+          stats.created++;
+        }
+      }
+    } catch (error) {
+      console.error(`❌ Error migrating ${capability.id}:`, getErrorMessage(error));
+      stats.errors++;
+    }
+  }
+
+  // Print summary
+  console.log(`\n${"=".repeat(60)}`);
+  console.log("[migrate-capabilities] Migration complete");
+  console.log(`${"=".repeat(60)}`);
+  console.log(`  Created:        ${stats.created}`);
+  console.log(`  Updated:        ${stats.updated}`);
+  console.log(`  Skipped:        ${stats.skipped}`);
+  console.log(`  Errors:         ${stats.errors}`);
+  console.log(`  Total:          ${INITIAL_CAPABILITIES.length}`);
+  console.log(`${"=".repeat(60)}\n`);
+
+  if (options.dryRun) {
+    console.log("💡 This was a dry-run. No changes were made to the database.");
+    console.log("   Run without --dry-run to apply changes.\n");
+  }
+
+  // Exit with appropriate code
+  if (stats.errors > 0) {
+    console.error("[migrate-capabilities] Migration completed with errors");
+    process.exit(1);
+  } else {
+    console.log("[migrate-capabilities] Migration successful");
+    process.exit(0);
+  }
+}
+
+// Main execution
+async function main() {
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  const options: MigrateOptions = {
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    clearFirst: args.includes('--clear-first'),
+  };
+
+  // Validate conflicting options
+  if (options.clearFirst && options.force) {
+    console.warn("[migrate-capabilities] Warning: --clear-first and --force both specified.");
+    console.warn("   --clear-first will delete all capabilities before migration.");
+    console.warn("   Continuing in 3 seconds... (Ctrl+C to cancel)");
+    await new Promise(resolve => setTimeout(resolve, 3000));
+  }
+
+  // Run migration
+  await migrate(options);
+}
+
+// Execute main function
+main().catch((err) => {
+  console.error("[migrate-capabilities] Fatal error:", getErrorMessage(err));
+  process.exit(1);
+});

packages/controlmart/scripts/migrate-knowledge-graph-to-db.ts

@@ -0,0 +1,245 @@
+/**
+ * Knowledge Graph Migration Script
+ *
+ * Builds knowledge graph from code annotations (ODs, capabilities, personas, tools)
+ * and persists it to MongoDB.
+ *
+ * Usage:
+ *   bun run scripts/migrate-knowledge-graph-to-db.ts [--dry-run] [--clear-first]
+ *
+ * Options:
+ *   --dry-run      Preview graph build without writing to database
+ *   --clear-first  Delete existing graph before migration
+ *
+ * Dependencies:
+ *   - Capabilities must be migrated first (run migrate-capabilities-to-db.ts)
+ *   - Personas must be migrated first (run migrate-personas-to-db.ts)
+ */
+
+import { connectMongo, createCollectionsIfNotExist } from "../src/services/mongo.service";
+import { KnowledgeGraphNode } from "../src/models/knowledge-graph-node.model";
+import { KnowledgeGraphEdge } from "../src/models/knowledge-graph-edge.model";
+import { knowledgeGraph } from "../src/services/knowledge-graph.service";
+import { capabilityCatalog } from "../src/services/capability-catalog.service";
+import { personaRegistry } from "../src/services/persona-registry.service";
+import { initializeODRegistry } from "../src/ods/index";
+import { getErrorMessage } from "../src/utils/error.util";
+import { loadEnv } from "../src/utils/env.util";
+
+interface MigrateOptions {
+  dryRun?: boolean;
+  clearFirst?: boolean;
+}
+
+interface MigrationResult {
+  nodeCount: number;
+  edgeCount: number;
+  source: string;
+  status: 'success' | 'error';
+}
+
+/**
+ * Verify that dependencies (capabilities and personas) are already migrated
+ */
+async function verifyDependencies(): Promise<void> {
+  console.log("[migrate-knowledge-graph] Verifying dependencies...\n");
+
+  // Initialize capability catalog
+  try {
+    await capabilityCatalog.initialize();
+    const capCount = capabilityCatalog.count();
+    if (capCount === 0) {
+      console.error("❌ Error: No capabilities found in database");
+      console.error("   Run: bun run scripts/migrate-capabilities-to-db.ts\n");
+      process.exit(1);
+    }
+    console.log(`  ✅ Capabilities: ${capCount} loaded`);
+  } catch (error) {
+    console.error("❌ Error: Failed to load capabilities");
+    console.error(`   ${getErrorMessage(error)}`);
+    console.error("   Run: bun run scripts/migrate-capabilities-to-db.ts\n");
+    process.exit(1);
+  }
+
+  // Initialize persona registry
+  try {
+    await personaRegistry.initialize();
+    const personaCount = personaRegistry.getCount();
+    if (personaCount === 0) {
+      console.error("❌ Error: No personas found in database");
+      console.error("   Run: bun run scripts/migrate-personas-to-db.ts\n");
+      process.exit(1);
+    }
+    console.log(`  ✅ Personas: ${personaCount} loaded`);
+  } catch (error) {
+    console.error("❌ Error: Failed to load personas");
+    console.error(`   ${getErrorMessage(error)}`);
+    console.error("   Run: bun run scripts/migrate-personas-to-db.ts\n");
+    process.exit(1);
+  }
+
+  // Initialize OD Registry
+  try {
+    initializeODRegistry();
+    console.log(`  ✅ OD Registry initialized`);
+  } catch (error) {
+    console.error("❌ Error: Failed to initialize OD Registry");
+    console.error(`   ${getErrorMessage(error)}\n`);
+    process.exit(1);
+  }
+
+  console.log("");
+}
+
+/**
+ * Clear existing knowledge graph from database
+ */
+async function clearGraph(): Promise<void> {
+  console.log("[migrate-knowledge-graph] Clearing existing graph...");
+  await (KnowledgeGraphNode as any).deleteMany({}).exec();
+  await (KnowledgeGraphEdge as any).deleteMany({}).exec();
+  console.log("[migrate-knowledge-graph] Cleared all nodes and edges\n");
+}
+
+/**
+ * Main migration function
+ */
+async function migrate(options: MigrateOptions = {}): Promise<MigrationResult> {
+  console.log("[migrate-knowledge-graph] Starting migration...");
+  console.log(`[migrate-knowledge-graph] Options:`, {
+    dryRun: options.dryRun || false,
+    clearFirst: options.clearFirst || false,
+  });
+  console.log("");
+
+  // Load environment variables
+  const env = loadEnv();
+
+  // Connect to MongoDB
+  await connectMongo({
+    uri: env.MONGO_URI,
+    dbName: env.DB_NAME,
+    log: true,
+  });
+
+  // Ensure collections exist with indexes
+  await createCollectionsIfNotExist({
+    models: [KnowledgeGraphNode, KnowledgeGraphEdge],
+    log: true,
+  });
+
+  console.log("");
+
+  // Verify dependencies (capabilities, personas, ODs)
+  await verifyDependencies();
+
+  // Clear existing graph if requested
+  if (options.clearFirst && !options.dryRun) {
+    await clearGraph();
+  } else if (options.clearFirst && options.dryRun) {
+    console.log("[DRY-RUN] Would clear existing graph\n");
+  }
+
+  // Build knowledge graph from annotations
+  console.log("[migrate-knowledge-graph] Building knowledge graph from annotations...\n");
+
+  try {
+    if (options.dryRun) {
+      // In dry-run, build graph but don't save
+      console.log("[DRY-RUN] Building graph (will not save to database)...");
+      knowledgeGraph.buildGraphFromAnnotations();
+
+      const nodeCount = (knowledgeGraph as any).graph.nodeCount();
+      const edgeCount = (knowledgeGraph as any).graph.edgeCount();
+
+      console.log(`[DRY-RUN] Would save: ${nodeCount} nodes, ${edgeCount} edges\n`);
+
+      return {
+        nodeCount,
+        edgeCount,
+        source: 'annotations',
+        status: 'success',
+      };
+    } else {
+      // Build graph from annotations
+      knowledgeGraph.buildGraphFromAnnotations();
+
+      const nodeCount = (knowledgeGraph as any).graph.nodeCount();
+      const edgeCount = (knowledgeGraph as any).graph.edgeCount();
+
+      console.log(`[KnowledgeGraphService] Built graph: ${nodeCount} nodes, ${edgeCount} edges\n`);
+
+      // Save to MongoDB
+      console.log("[migrate-knowledge-graph] Saving to MongoDB...");
+      await knowledgeGraph.saveToDB();
+      console.log("[migrate-knowledge-graph] Successfully saved graph to database\n");
+
+      return {
+        nodeCount,
+        edgeCount,
+        source: 'annotations',
+        status: 'success',
+      };
+    }
+  } catch (error) {
+    console.error("❌ Error building or saving knowledge graph:");
+    console.error(`   ${getErrorMessage(error)}\n`);
+    return {
+      nodeCount: 0,
+      edgeCount: 0,
+      source: 'annotations',
+      status: 'error',
+    };
+  }
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  const options: MigrateOptions = {
+    dryRun: args.includes('--dry-run'),
+    clearFirst: args.includes('--clear-first'),
+  };
+
+  // Run migration
+  const result = await migrate(options);
+
+  // Print summary
+  console.log(`${"=".repeat(60)}`);
+  console.log("[migrate-knowledge-graph] Migration complete");
+  console.log(`${"=".repeat(60)}`);
+  console.log(`  Nodes:          ${result.nodeCount}`);
+  console.log(`  Edges:          ${result.edgeCount}`);
+  console.log(`  Source:         ${result.source}`);
+  console.log(`  Status:         ${result.status}`);
+  console.log(`${"=".repeat(60)}\n`);
+
+  if (options.dryRun) {
+    console.log("💡 This was a dry-run. No changes were made to the database.");
+    console.log("   Run without --dry-run to apply changes.\n");
+  }
+
+  if (result.status === 'error') {
+    console.error("[migrate-knowledge-graph] Migration failed");
+    process.exit(1);
+  } else {
+    console.log("[migrate-knowledge-graph] Migration successful");
+
+    if (!options.dryRun) {
+      console.log("\n💡 Next steps:");
+      console.log("   - Restart your application to load the knowledge graph from MongoDB");
+      console.log("   - The graph will be loaded via knowledgeGraph.initialize()\n");
+    }
+
+    process.exit(0);
+  }
+}
+
+// Execute main function
+main().catch((err) => {
+  console.error("[migrate-knowledge-graph] Fatal error:", getErrorMessage(err));
+  process.exit(1);
+});

packages/controlmart/scripts/migrate-personas-to-db.ts

@@ -0,0 +1,163 @@
+/**
+ * Persona Migration Script
+ *
+ * Migrates personas from src/personas/catalog.ts to MongoDB.
+ * Idempotent - safe to run multiple times.
+ *
+ * Usage:
+ *   bun run scripts/migrate-personas-to-db.ts [--dry-run] [--force] [--clear-first]
+ *
+ * Options:
+ *   --dry-run      Preview changes without writing to database
+ *   --force        Update existing personas instead of skipping
+ *   --clear-first  Delete all existing personas before migration
+ */
+
+import { connectMongo, createCollectionsIfNotExist } from "../src/services/mongo.service";
+import { Persona } from "../src/models/persona.model";
+import { PersonaRepository } from "../src/repository/persona.repository";
+import { personaCatalog } from "../src/personas/catalog";
+import { getErrorMessage } from "../src/utils/error.util";
+import { loadEnv } from "../src/utils/env.util";
+
+interface MigrateOptions {
+  dryRun?: boolean;
+  force?: boolean;
+  clearFirst?: boolean;
+}
+
+interface MigrationStats {
+  created: number;
+  updated: number;
+  skipped: number;
+  errors: number;
+}
+
+async function migrate(options: MigrateOptions = {}): Promise<void> {
+  console.log("[migrate-personas] Starting migration...");
+  console.log(`[migrate-personas] Options:`, {
+    dryRun: options.dryRun || false,
+    force: options.force || false,
+    clearFirst: options.clearFirst || false,
+  });
+
+  // Load environment variables
+  const env = loadEnv();
+
+  // Connect to MongoDB
+  await connectMongo({
+    uri: env.MONGO_URI,
+    dbName: env.DB_NAME,
+    log: true,
+  });
+
+  // Ensure collection exists with indexes
+  await createCollectionsIfNotExist({
+    models: [Persona],
+    log: true,
+  });
+
+  // Clear existing personas if requested
+  if (options.clearFirst) {
+    if (options.dryRun) {
+      console.log("[DRY-RUN] Would clear all existing personas");
+    } else {
+      console.log("[migrate-personas] Clearing existing personas...");
+      await (Persona as any).deleteMany({}).exec();
+      console.log("[migrate-personas] Cleared all personas");
+    }
+  }
+
+  // Migrate personas
+  console.log(`\n[migrate-personas] Migrating ${personaCatalog.length} personas...\n`);
+
+  const stats: MigrationStats = {
+    created: 0,
+    updated: 0,
+    skipped: 0,
+    errors: 0,
+  };
+
+  for (const persona of personaCatalog) {
+    try {
+      if (options.dryRun) {
+        console.log(`[DRY-RUN] Would create/update: ${persona.id} (${persona.name}) - ${persona.capabilityIds.length} capabilities`);
+        stats.created++;
+      } else {
+        // Check if persona already exists
+        const existing = await PersonaRepository.findById(persona.id);
+
+        if (existing && !options.force) {
+          console.log(`⏭️  Skipping existing: ${persona.id} (${persona.name})`);
+          stats.skipped++;
+        } else if (existing && options.force) {
+          // Update existing persona
+          await PersonaRepository.update(persona.id, persona);
+          console.log(`✏️  Updated: ${persona.id} (${persona.name}) - ${persona.capabilityIds.length} capabilities`);
+          stats.updated++;
+        } else {
+          // Create new persona
+          await PersonaRepository.create(persona);
+          console.log(`✅ Created: ${persona.id} (${persona.name}) - ${persona.capabilityIds.length} capabilities`);
+          stats.created++;
+        }
+      }
+    } catch (error) {
+      console.error(`❌ Error migrating ${persona.id}:`, getErrorMessage(error));
+      stats.errors++;
+    }
+  }
+
+  // Print summary
+  console.log(`\n${"=".repeat(60)}`);
+  console.log("[migrate-personas] Migration complete");
+  console.log(`${"=".repeat(60)}`);
+  console.log(`  Created:        ${stats.created}`);
+  console.log(`  Updated:        ${stats.updated}`);
+  console.log(`  Skipped:        ${stats.skipped}`);
+  console.log(`  Errors:         ${stats.errors}`);
+  console.log(`  Total:          ${personaCatalog.length}`);
+  console.log(`${"=".repeat(60)}\n`);
+
+  if (options.dryRun) {
+    console.log("💡 This was a dry-run. No changes were made to the database.");
+    console.log("   Run without --dry-run to apply changes.\n");
+  }
+
+  // Exit with appropriate code
+  if (stats.errors > 0) {
+    console.error("[migrate-personas] Migration completed with errors");
+    process.exit(1);
+  } else {
+    console.log("[migrate-personas] Migration successful");
+    process.exit(0);
+  }
+}
+
+// Main execution
+async function main() {
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  const options: MigrateOptions = {
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    clearFirst: args.includes('--clear-first'),
+  };
+
+  // Validate conflicting options
+  if (options.clearFirst && options.force) {
+    console.warn("[migrate-personas] Warning: --clear-first and --force both specified.");
+    console.warn("   --clear-first will delete all personas before migration.");
+    console.warn("   Continuing in 3 seconds... (Ctrl+C to cancel)");
+    await new Promise(resolve => setTimeout(resolve, 3000));
+  }
+
+  // Run migration
+  await migrate(options);
+}
+
+// Execute main function
+main().catch((err) => {
+  console.error("[migrate-personas] Fatal error:", getErrorMessage(err));
+  process.exit(1);
+});

packages/controlmart/scripts/seed-dev-data.ts

@@ -0,0 +1,436 @@
+/**
+ * Seed Development Data Script
+ *
+ * One-command solution to seed MongoDB with all development data:
+ * - Capabilities (4)
+ * - Personas (5)
+ * - Knowledge Graph (63 nodes, 80 edges)
+ * - Sample Worlds (5 with diverse sampling strategies)
+ *
+ * Usage:
+ *   bun run seed-dev                    # Interactive with confirmation
+ *   bun run seed-dev --no-confirm       # Skip confirmation
+ *   bun run seed-dev --skip-worlds      # Skip world creation
+ *
+ * Note: This script orchestrates other migration scripts
+ */
+
+import { spawn } from 'child_process';
+import * as readline from 'readline';
+import * as crypto from 'crypto';
+import { connectMongo, createCollectionsIfNotExist } from "../src/services/mongo.service";
+import { World } from "../src/models/world.model";
+import { Capability } from "../src/models/capability.model";
+import { Persona } from "../src/models/persona.model";
+import { KnowledgeGraphNode } from "../src/models/knowledge-graph-node.model";
+import { KnowledgeGraphEdge } from "../src/models/knowledge-graph-edge.model";
+import { WorldRepository } from "../src/repository/world.repository";
+import { capabilitySamplingService } from "../src/services/capability-sampling.service";
+import { capabilityCatalog } from "../src/services/capability-catalog.service";
+import { getErrorMessage } from "../src/utils/error.util";
+import { loadEnv } from "../src/utils/env.util";
+import type { TWorldInput, SamplingStrategy, PersonaConfig } from "../src/models/world.model.type";
+
+interface SeedOptions {
+  noConfirm?: boolean;
+  skipWorlds?: boolean;
+}
+
+interface SeedResult {
+  capabilities: number;
+  personas: number;
+  knowledgeGraphNodes: number;
+  knowledgeGraphEdges: number;
+  worlds: number;
+  worldDetails: Array<{ name: string; capabilityCount: number }>;
+  duration: number;
+}
+
+interface WorldSpec {
+  name: string;
+  url: string;
+  description: string;
+  samplingStrategy: SamplingStrategy;
+  personas?: PersonaConfig;
+  mpcCompany?: string;
+}
+
+/**
+ * Sample world specifications demonstrating different sampling strategies
+ */
+const SAMPLE_WORLD_SPECS: WorldSpec[] = [
+  {
+    name: 'development-local',
+    url: 'http://localhost:3000',
+    description: 'Full capability access for local development',
+    samplingStrategy: { type: 'all' },
+    personas: {
+      allowedPersonas: ['warehouse-manager', 'system-administrator']
+    },
+    mpcCompany: 'Morpheus Labs'
+  },
+  {
+    name: 'staging-integration',
+    url: 'https://staging.example.com',
+    description: 'Inventory-focused staging environment',
+    samplingStrategy: {
+      type: 'filter',
+      filter: { domain: ['inventory', 'warehousing'] }
+    },
+    personas: {
+      allowedPersonas: ['warehouse-manager', 'warehouse-worker', 'store-manager']
+    },
+    mpcCompany: 'Morpheus Staging'
+  },
+  {
+    name: 'demo-showcase',
+    url: 'https://demo.example.com',
+    description: 'Reproducible demo with seeded capabilities',
+    samplingStrategy: {
+      type: 'seeded',
+      count: 3,
+      seed: 12345
+    },
+    personas: {
+      allowedPersonas: ['store-manager', 'customer-service-rep']
+    },
+    mpcCompany: 'Morpheus Demo'
+  },
+  {
+    name: 'test-automation',
+    url: 'http://test.example.com',
+    description: 'Random capability subset for testing',
+    samplingStrategy: {
+      type: 'random',
+      count: 2
+    },
+    personas: {
+      allowedPersonas: ['warehouse-worker', 'store-manager'],
+      personaOverrides: {
+        'warehouse-worker': {
+          capabilityIds: ['inventory-check']
+        }
+      }
+    },
+    mpcCompany: 'Morpheus Test'
+  },
+  {
+    name: 'performance-load',
+    url: 'http://perf.example.com',
+    description: 'Simple capabilities for load testing',
+    samplingStrategy: {
+      type: 'filter',
+      filter: { complexity: 'simple' }
+    },
+    mpcCompany: 'Morpheus Performance'
+  }
+];
+
+/**
+ * Prompt user for confirmation
+ */
+async function promptConfirmation(env: ReturnType<typeof loadEnv>): Promise<boolean> {
+  console.log('\n⚠️  This will clear ALL existing data and reseed the database.');
+  console.log(`   Database: ${env.DB_NAME} (${env.MONGO_URI})\n`);
+  console.log('   This will:');
+  console.log('   - Delete all capabilities, personas, knowledge graph, and worlds');
+  console.log('   - Migrate 4 capabilities');
+  console.log('   - Migrate 5 personas');
+  console.log('   - Build and save knowledge graph (63 nodes, 80 edges)');
+  console.log('   - Create 5 sample worlds with sampling strategies\n');
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Continue? (y/N): ', (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Run a migration script
+ */
+async function runScript(scriptPath: string, args: string[] = []): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('bun', ['run', scriptPath, ...args], {
+      stdio: 'inherit',
+      cwd: process.cwd()
+    });
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Script ${scriptPath} exited with code ${code}`));
+      }
+    });
+
+    proc.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Clear all collections
+ */
+async function clearAllData(): Promise<void> {
+  console.log('\n[seed-dev] Clearing existing data...');
+
+  await (KnowledgeGraphNode as any).deleteMany({}).exec();
+  await (KnowledgeGraphEdge as any).deleteMany({}).exec();
+  console.log('  ✓ Cleared knowledge graph');
+
+  await (Persona as any).deleteMany({}).exec();
+  console.log('  ✓ Cleared personas');
+
+  await (Capability as any).deleteMany({}).exec();
+  console.log('  ✓ Cleared capabilities');
+
+  await (World as any).deleteMany({}).exec();
+  console.log('  ✓ Cleared worlds');
+
+  console.log('[seed-dev] All data cleared\n');
+}
+
+/**
+ * Generate API credentials
+ */
+function generateApiKey(): string {
+  return `api_${crypto.randomBytes(16).toString('hex')}`;
+}
+
+function generateApiSecret(): string {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Create sample worlds with sampling strategies
+ */
+async function createSampleWorlds(): Promise<Array<{ name: string; capabilityCount: number }>> {
+  console.log('\n[seed-dev] Creating sample worlds with sampling strategies...\n');
+
+  // Initialize capability catalog (needed for sampling)
+  await capabilityCatalog.initialize();
+
+  const worldDetails: Array<{ name: string; capabilityCount: number }> = [];
+
+  for (const spec of SAMPLE_WORLD_SPECS) {
+    try {
+      // Apply sampling strategy to get capability IDs
+      const capabilityIds = capabilitySamplingService.applySamplingStrategy(
+        spec.samplingStrategy,
+        spec.personas
+      );
+
+      // Create world with sampled capabilities
+      const worldInput: TWorldInput = {
+        name: spec.name,
+        url: spec.url,
+        apiKey: generateApiKey(),
+        apiSecret: generateApiSecret(),
+        description: spec.description,
+        mpcCompany: spec.mpcCompany,
+        samplingStrategy: spec.samplingStrategy,
+        capabilityIds,
+        personas: spec.personas
+      };
+
+      const world = await WorldRepository.createWorld(worldInput);
+
+      const strategyDesc =
+        spec.samplingStrategy.type === 'all' ? 'ALL' :
+        spec.samplingStrategy.type === 'filter' ? 'FILTERED' :
+        spec.samplingStrategy.type === 'seeded' ? 'SEEDED' :
+        'RANDOM';
+
+      console.log(`  ✓ Created: ${world.name}`);
+      console.log(`     Strategy: ${strategyDesc} (${capabilityIds.length} capabilities)`);
+
+      worldDetails.push({
+        name: world.name,
+        capabilityCount: capabilityIds.length
+      });
+    } catch (error) {
+      console.error(`  ✗ Failed to create world: ${spec.name}`);
+      console.error(`     Error: ${getErrorMessage(error)}`);
+      throw error;
+    }
+  }
+
+  console.log('');
+  return worldDetails;
+}
+
+/**
+ * Validate seeded data
+ */
+async function validateData(skipWorlds: boolean): Promise<{
+  capabilities: number;
+  personas: number;
+  nodes: number;
+  edges: number;
+  worlds: number;
+}> {
+  console.log('[seed-dev] Validating seeded data...\n');
+
+  const capCount = await (Capability as any).countDocuments().exec();
+  const personaCount = await (Persona as any).countDocuments().exec();
+  const nodeCount = await (KnowledgeGraphNode as any).countDocuments().exec();
+  const edgeCount = await (KnowledgeGraphEdge as any).countDocuments().exec();
+  const worldCount = await (World as any).countDocuments().exec();
+
+  console.log(`  Capabilities:      ${capCount} ${capCount === 4 ? '✓' : '✗'}`);
+  console.log(`  Personas:          ${personaCount} ${personaCount === 5 ? '✓' : '✗'}`);
+  console.log(`  KG Nodes:          ${nodeCount} ${nodeCount > 0 ? '✓' : '✗'}`);
+  console.log(`  KG Edges:          ${edgeCount} ${edgeCount > 0 ? '✓' : '✗'}`);
+  console.log(`  Worlds:            ${worldCount} ${skipWorlds || worldCount === 5 ? '✓' : '✗'}`);
+  console.log('');
+
+  if (capCount !== 4 || personaCount !== 5 || nodeCount === 0 || edgeCount === 0) {
+    throw new Error('Validation failed: Data counts do not match expected values');
+  }
+
+  if (!skipWorlds && worldCount !== 5) {
+    throw new Error('Validation failed: Expected 5 worlds but found ' + worldCount);
+  }
+
+  return {
+    capabilities: capCount,
+    personas: personaCount,
+    nodes: nodeCount,
+    edges: edgeCount,
+    worlds: worldCount
+  };
+}
+
+/**
+ * Main seeding function
+ */
+async function seedDevData(options: SeedOptions): Promise<SeedResult> {
+  const startTime = Date.now();
+
+  console.log('[seed-dev] Starting development data seeding...\n');
+
+  // Load environment
+  const env = loadEnv();
+
+  // Confirmation prompt (unless --no-confirm)
+  if (!options.noConfirm) {
+    const confirmed = await promptConfirmation(env);
+    if (!confirmed) {
+      console.log('\n[seed-dev] Seeding cancelled by user\n');
+      process.exit(0);
+    }
+  }
+
+  // Connect to MongoDB
+  await connectMongo({
+    uri: env.MONGO_URI,
+    dbName: env.DB_NAME,
+    log: false
+  });
+
+  // Ensure collections exist
+  await createCollectionsIfNotExist({
+    models: [World, Capability, Persona, KnowledgeGraphNode, KnowledgeGraphEdge],
+    log: false
+  });
+
+  // Clear existing data
+  await clearAllData();
+
+  // Run capability migration
+  console.log('[seed-dev] Running capability migration...');
+  await runScript('scripts/migrate-capabilities-to-db.ts', ['--clear-first']);
+
+  // Run persona migration
+  console.log('\n[seed-dev] Running persona migration...');
+  await runScript('scripts/migrate-personas-to-db.ts', ['--clear-first']);
+
+  // Create sample worlds (unless --skip-worlds)
+  let worldDetails: Array<{ name: string; capabilityCount: number }> = [];
+  if (!options.skipWorlds) {
+    worldDetails = await createSampleWorlds();
+  } else {
+    console.log('\n[seed-dev] Skipping world creation (--skip-worlds)\n');
+  }
+
+  // Run knowledge graph migration
+  console.log('[seed-dev] Running knowledge graph migration...');
+  await runScript('scripts/migrate-knowledge-graph-to-db.ts', ['--clear-first']);
+
+  // Validate data
+  const counts = await validateData(options.skipWorlds || false);
+
+  const duration = (Date.now() - startTime) / 1000;
+
+  return {
+    capabilities: counts.capabilities,
+    personas: counts.personas,
+    knowledgeGraphNodes: counts.nodes,
+    knowledgeGraphEdges: counts.edges,
+    worlds: counts.worlds,
+    worldDetails,
+    duration
+  };
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  // Parse command line arguments
+  const args = process.argv.slice(2);
+  const options: SeedOptions = {
+    noConfirm: args.includes('--no-confirm'),
+    skipWorlds: args.includes('--skip-worlds')
+  };
+
+  try {
+    const result = await seedDevData(options);
+
+    // Print summary
+    console.log(`${"=".repeat(60)}`);
+    console.log('Development Data Seeding Complete');
+    console.log(`${"=".repeat(60)}`);
+    console.log(`  Capabilities:    ${result.capabilities} migrated`);
+    console.log(`  Personas:        ${result.personas} migrated`);
+    console.log(`  Knowledge Graph: ${result.knowledgeGraphNodes} nodes, ${result.knowledgeGraphEdges} edges`);
+    console.log(`  Worlds:          ${result.worlds} created`);
+
+    if (result.worldDetails.length > 0) {
+      result.worldDetails.forEach(w => {
+        const strategyType = SAMPLE_WORLD_SPECS.find(s => s.name === w.name)?.samplingStrategy.type || 'unknown';
+        const label = strategyType.toUpperCase();
+        console.log(`    - ${w.name.padEnd(22)} ${label.padEnd(10)} (${w.capabilityCount} caps)`);
+      });
+    }
+
+    console.log(`  Duration:        ${result.duration.toFixed(1)}s`);
+    console.log(`  Status:          ✅ SUCCESS`);
+    console.log(`${"=".repeat(60)}\n`);
+
+    if (result.worldDetails.length > 0) {
+      console.log('💡 Sample worlds demonstrate different sampling strategies:');
+      console.log('   - Use \'development-local\' for full access testing');
+      console.log('   - Use \'demo-showcase\' for reproducible demos (seeded)');
+      console.log('   - Use \'test-automation\' for integration tests\n');
+    }
+
+    console.log('[seed-dev] ✅ Development environment ready!\n');
+    process.exit(0);
+  } catch (error) {
+    console.error('\n[seed-dev] ✗ Seeding failed:');
+    console.error(`   ${getErrorMessage(error)}\n`);
+    process.exit(1);
+  }
+}
+
+// Execute main function
+main();

packages/controlmart/scripts/validate-seed-data.ts

@@ -0,0 +1,76 @@
+/**
+ * Quick validation script to check seeded data
+ */
+
+import { connectMongo } from "../src/services/mongo.service";
+import { Capability } from "../src/models/capability.model";
+import { Persona } from "../src/models/persona.model";
+import { KnowledgeGraphNode } from "../src/models/knowledge-graph-node.model";
+import { KnowledgeGraphEdge } from "../src/models/knowledge-graph-edge.model";
+import { World } from "../src/models/world.model";
+import { loadEnv } from "../src/utils/env.util";
+
+async function validate() {
+  const env = loadEnv();
+
+  await connectMongo({
+    uri: env.MONGO_URI,
+    dbName: env.DB_NAME,
+    log: false
+  });
+
+  console.log("=== Test 1 Validation ===\n");
+
+  const capCount = await (Capability as any).countDocuments().exec();
+  const personaCount = await (Persona as any).countDocuments().exec();
+  const nodeCount = await (KnowledgeGraphNode as any).countDocuments().exec();
+  const edgeCount = await (KnowledgeGraphEdge as any).countDocuments().exec();
+  const worldCount = await (World as any).countDocuments().exec();
+
+  console.log(`Capabilities: ${capCount} ${capCount === 4 ? '✓' : '✗'}`);
+  console.log(`Personas: ${personaCount} ${personaCount === 5 ? '✓' : '✗'}`);
+  console.log(`KG Nodes: ${nodeCount} ${nodeCount === 63 ? '✓' : '✗'}`);
+  console.log(`KG Edges: ${edgeCount} ${edgeCount === 80 ? '✓' : '✗'}`);
+  console.log(`Worlds: ${worldCount} ${worldCount === 0 ? '✓' : '✗'}`);
+
+  console.log("\n=== Sample Capability ===");
+  const sampleCap = await (Capability as any).findOne({}).select('id name domain').lean().exec();
+  console.log(JSON.stringify(sampleCap, null, 2));
+
+  console.log("\n=== Sample Persona ===");
+  const samplePersona = await (Persona as any).findOne({}).select('id name capabilityIds').lean().exec();
+  console.log(JSON.stringify(samplePersona, null, 2));
+
+  console.log("\n=== KG Node Types ===");
+  const nodeTypes = await (KnowledgeGraphNode as any).aggregate([
+    { $group: { _id: '$type', count: { $sum: 1 } } },
+    { $sort: { _id: 1 } }
+  ]).exec();
+  console.log(JSON.stringify(nodeTypes, null, 2));
+
+  // Validate worlds if they exist
+  if (worldCount > 0) {
+    console.log("\n=== World Details ===");
+    const worlds = await (World as any)
+      .find({})
+      .select('name capabilityIds samplingStrategy personas.allowedPersonas apiKey mpcCompany')
+      .lean()
+      .exec();
+
+    for (const world of worlds) {
+      console.log(`\n${world.name}:`);
+      console.log(`  Company: ${world.mpcCompany || 'N/A'}`);
+      console.log(`  Strategy: ${world.samplingStrategy?.type?.toUpperCase() || 'N/A'}`);
+      console.log(`  Capabilities: ${world.capabilityIds?.length || 0} - [${(world.capabilityIds || []).join(', ')}]`);
+      console.log(`  Personas: ${world.personas?.allowedPersonas?.length || 0} - [${(world.personas?.allowedPersonas || []).join(', ')}]`);
+      console.log(`  API Key: ${world.apiKey ? '✓ Set' : '✗ Missing'}`);
+    }
+  }
+
+  process.exit(0);
+}
+
+validate().catch(err => {
+  console.error("Validation error:", err);
+  process.exit(1);
+});