Merge pull request 'development' (#240) from development into main

Reviewed-on: #240

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "4.1.0"
+    "version": "5.1.0"
   },
   "plugins": [
     {
@@ -75,8 +75,8 @@
     },
     {
       "name": "cmdb-assistant",
-      "version": "1.0.0",
-      "description": "NetBox CMDB integration for infrastructure management",
+      "version": "1.1.0",
+      "description": "NetBox CMDB integration with data quality validation and machine registration",
       "source": "./plugins/cmdb-assistant",
       "author": {
         "name": "Leo Miranda",
@@ -86,7 +86,7 @@
       "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
       "mcpServers": ["./.mcp.json"],
       "category": "infrastructure",
-      "tags": ["cmdb", "netbox", "dcim", "ipam"],
+      "tags": ["cmdb", "netbox", "dcim", "ipam", "data-quality", "validation"],
       "license": "MIT"
     },
     {
@@ -165,6 +165,38 @@
       "category": "data",
       "tags": ["pandas", "postgresql", "postgis", "dbt", "data-engineering", "etl"],
       "license": "MIT"
+    },
+    {
+      "name": "viz-platform",
+      "version": "1.0.0",
+      "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
+      "source": "./plugins/viz-platform",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/viz-platform/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "mcpServers": ["./.mcp.json"],
+      "category": "visualization",
+      "tags": ["dash", "plotly", "mantine", "charts", "dashboards", "theming", "dmc"],
+      "license": "MIT"
+    },
+    {
+      "name": "contract-validator",
+      "version": "1.0.0",
+      "description": "Cross-plugin compatibility validation and Claude.md agent verification",
+      "source": "./plugins/contract-validator",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "mcpServers": ["./.mcp.json"],
+      "category": "development",
+      "tags": ["validation", "contracts", "compatibility", "agents", "interfaces", "cross-plugin"],
+      "license": "MIT"
     }
   ]
 }

.gitignore

@@ -31,6 +31,8 @@ venv/
 ENV/
 env/
 .venv/
+.venv
+**/.venv
 
 # PyCharm
 .idea/

CHANGELOG.md

@@ -6,6 +6,112 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Added
+
+#### Sprint 3: Hooks (V5.2.0 Plugin Enhancements)
+Implementation of 6 foundational hooks across 4 plugins.
+
+**git-flow v1.1.0:**
+- **Commit message enforcement hook** - PreToolUse hook validates conventional commit format on all `git commit` commands (not just `/commit`). Blocks invalid commits with format guidance.
+- **Branch name validation hook** - PreToolUse hook validates branch naming on `git checkout -b` and `git switch -c`. Enforces `type/description` format, lowercase, max 50 chars.
+
+**clarity-assist v1.1.0:**
+- **Vagueness detection hook** - UserPromptSubmit hook detects vague prompts and suggests `/clarify` when ambiguity, missing context, or unclear scope detected.
+
+**data-platform v1.1.0:**
+- **Schema diff detection hook** - PostToolUse hook monitors edits to schema files (dbt models, SQL migrations). Warns on breaking changes (column removal, type narrowing, constraint addition).
+
+**contract-validator v1.1.0:**
+- **SessionStart auto-validate hook** - Smart validation that only runs when plugin files changed since last check. Detects interface compatibility issues at session start.
+- **Breaking change detection hook** - PostToolUse hook monitors plugin interface files (README.md, plugin.json). Warns when changes would break consumers.
+
+**Sprint Completed:**
+- Milestone: Sprint 3 - Hooks (closed 2026-01-28)
+- Issues: #225, #226, #227, #228, #229, #230
+- Wiki: [Change V5.2.0: Plugin Enhancements Proposal](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0:-Plugin-Enhancements-Proposal)
+- Lessons: Background agent permissions, agent runaway detection, MCP branch detection bug
+
+### Known Issues
+- **MCP Bug #231:** Branch detection in Gitea MCP runs from installed plugin directory, not user's project directory. Workaround: close issues via Gitea web UI.
+
+---
+
+#### Gitea MCP Server - create_pull_request Tool
+- **`create_pull_request`**: Create new pull requests via MCP
+  - Parameters: title, body, head (source branch), base (target branch), labels
+  - Branch-aware security: only allowed on development/feature branches
+  - Completes the PR lifecycle (was previously missing - only had list/get/review/comment)
+
+#### cmdb-assistant v1.1.0 - Data Quality Validation
+- **SessionStart Hook**: Tests NetBox API connectivity at session start
+  - Warns if VMs exist without site assignment
+  - Warns if devices exist without platform
+  - Non-blocking: displays warning, doesn't prevent work
+- **PreToolUse Hook**: Validates input parameters before VM/device operations
+  - Warns about missing site, tenant, platform
+  - Non-blocking: suggests best practices without blocking
+- **`/cmdb-audit` Command**: Comprehensive data quality analysis
+  - Scopes: all, vms, devices, naming, roles
+  - Identifies Critical/High/Medium/Low issues
+  - Provides prioritized remediation recommendations
+- **`/cmdb-register` Command**: Register current machine into NetBox
+  - Discovers system info: hostname, platform, hardware, network interfaces
+  - Discovers running apps: Docker containers, systemd services
+  - Creates device with interfaces, IPs, and sets primary IP
+  - Creates cluster and VMs for Docker containers
+- **`/cmdb-sync` Command**: Sync machine state with NetBox
+  - Compares current state with NetBox record
+  - Shows diff of changes (interfaces, IPs, containers)
+  - Updates with user confirmation
+  - Supports --full and --dry-run flags
+- **NetBox Best Practices Skill**: Reference documentation
+  - Dependency order for object creation
+  - Naming conventions (`{role}-{site}-{number}`, `{env}-{app}-{number}`)
+  - Role consolidation guidance
+  - Site/tenant/platform assignment requirements
+- **Agent Enhancement**: Updated cmdb-assistant agent with validation requirements
+  - Proactive suggestions for missing fields
+  - Naming convention checks
+  - Dependency order enforcement
+  - Duplicate prevention
+
+---
+
+## [5.0.0] - 2026-01-26
+
+### Added
+
+#### Sprint 1: viz-platform Plugin ✅ Completed
+- **viz-platform** v1.0.0 - Visualization tools with Dash Mantine Components validation and theming
+  - **DMC Tools** (3 tools): `list_components`, `get_component_props`, `validate_component`
+    - Version-locked component registry prevents Claude from hallucinating invalid props
+    - Static JSON registry approach for fast, deterministic validation
+  - **Chart Tools** (2 tools): `chart_create`, `chart_configure_interaction`
+    - Plotly-based visualization with theme token support
+  - **Layout Tools** (5 tools): `layout_create`, `layout_add_filter`, `layout_set_grid`, `layout_get`, `layout_add_section`
+    - Dashboard composition with responsive grid system
+  - **Theme Tools** (6 tools): `theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`, `theme_list`, `theme_activate`
+    - Design token-based theming system
+    - Dual storage: user-level (`~/.config/claude/themes/`) and project-level
+  - **Page Tools** (5 tools): `page_create`, `page_add_navbar`, `page_set_auth`, `page_list`, `page_get_app_config`
+    - Multi-page Dash app structure generation
+  - **Commands**: `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/initial-setup`
+  - **Agents**: `theme-setup`, `layout-builder`, `component-check`
+  - **SessionStart Hook**: DMC version check (non-blocking)
+  - **Tests**: 94 tests passing
+    - config.py: 82% coverage
+    - component_registry.py: 92% coverage
+    - dmc_tools.py: 88% coverage
+    - chart_tools.py: 68% coverage
+    - theme_tools.py: 99% coverage
+
+**Sprint Completed:**
+- Milestone: Sprint 1 - viz-platform Plugin (closed 2026-01-26)
+- Issues: #170-#182 (13/13 closed)
+- Wiki: [Sprint-1-viz-platform-Implementation-Plan](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Sprint-1-viz-platform-Implementation-Plan)
+- Lessons: [sprint-1---viz-platform-plugin-implementation](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/lessons/sprints/sprint-1---viz-platform-plugin-implementation)
+- Reference: `docs/changes/CHANGE_V04_0_0_PROPOSAL_ORIGINAL.md` (Phases 4-5)
+
 ---
 
 ## [4.1.0] - 2026-01-26

CLAUDE.md

@@ -50,14 +50,14 @@ See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
 ## Project Overview
 
 **Repository:** leo-claude-mktplace
-**Version:** 4.0.0
+**Version:** 5.1.0
 **Status:** Production Ready
 
 A plugin marketplace for Claude Code containing:
 
 | Plugin | Description | Version |
 |--------|-------------|---------|
-| `projman` | Sprint planning and project management with Gitea integration | 3.1.0 |
+| `projman` | Sprint planning and project management with Gitea integration | 3.2.0 |
 | `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 |
 | `pr-review` | Multi-agent PR review with confidence scoring | 1.0.0 |
 | `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
@@ -66,6 +66,8 @@ A plugin marketplace for Claude Code containing:
 | `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
 | `cmdb-assistant` | NetBox CMDB integration for infrastructure management | 1.0.0 |
 | `data-platform` | pandas, PostgreSQL, and dbt integration for data engineering | 1.0.0 |
+| `viz-platform` | DMC validation, Plotly charts, and theming for dashboards | 1.0.0 |
+| `contract-validator` | Cross-plugin compatibility validation and agent verification | 1.0.0 |
 | `project-hygiene` | Post-task cleanup automation via hooks | 0.1.0 |
 
 ## Quick Start
@@ -91,6 +93,8 @@ A plugin marketplace for Claude Code containing:
 | **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
 | **Config** | `/config-analyze`, `/config-optimize` |
 | **Data** | `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run` |
+| **Visualization** | `/component`, `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css` |
+| **Validation** | `/validate-contracts`, `/check-agent`, `/list-interfaces` |
 | **Debug** | `/debug-report`, `/debug-review` |
 
 ## Repository Structure
@@ -101,7 +105,9 @@ leo-claude-mktplace/
 │   └── marketplace.json          # Marketplace manifest
 ├── mcp-servers/                  # SHARED MCP servers (v3.0.0+)
 │   ├── gitea/                    # Gitea MCP (issues, PRs, wiki)
-│   └── netbox/                   # NetBox MCP (CMDB)
+│   ├── netbox/                   # NetBox MCP (CMDB)
+│   ├── data-platform/            # pandas, PostgreSQL, dbt
+│   └── viz-platform/             # DMC validation, charts, themes
 ├── plugins/
 │   ├── projman/                  # Sprint management
 │   │   ├── .claude-plugin/plugin.json
@@ -133,6 +139,13 @@ leo-claude-mktplace/
 │   │   ├── commands/             # 7 commands
 │   │   ├── hooks/                # SessionStart PostgreSQL check
 │   │   └── agents/               # 2 agents
+│   ├── viz-platform/             # Visualization (NEW v4.0.0)
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/          # viz-platform MCP
+│   │   ├── commands/             # 7 commands
+│   │   ├── hooks/                # SessionStart DMC check
+│   │   └── agents/               # 3 agents
 │   ├── doc-guardian/             # Documentation drift detection
 │   ├── code-sentinel/            # Security scanning & refactoring
 │   ├── claude-config-maintainer/

README.md

@@ -1,4 +1,4 @@
-# Leo Claude Marketplace - v4.1.0
+# Leo Claude Marketplace - v5.1.0
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
@@ -19,7 +19,7 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp
 - Branch-aware security (development/staging/production)
 - Pre-sprint-close code quality review and test verification
 
-**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`
+**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`, `/debug-report`, `/debug-review`, `/suggest-version`, `/proposal-status`
 
 #### [git-flow](./plugins/git-flow/README.md) *NEW in v3.0.0*
 **Git Workflow Automation**
@@ -53,6 +53,19 @@ Analyze, optimize, and create CLAUDE.md configuration files for Claude Code proj
 
 **Commands:** `/config-analyze`, `/config-optimize`, `/config-init`
 
+#### [contract-validator](./plugins/contract-validator/README.md) *NEW in v5.0.0*
+**Cross-Plugin Compatibility Validation**
+
+Validate plugin marketplaces for command conflicts, tool overlaps, and broken agent references.
+
+- Interface parsing from plugin README.md files
+- Agent extraction from CLAUDE.md definitions
+- Pairwise compatibility checks between all plugins
+- Data flow validation for agent sequences
+- Markdown or JSON reports with actionable suggestions
+
+**Commands:** `/validate-contracts`, `/check-agent`, `/list-interfaces`, `/initial-setup`
+
 ### Productivity
 
 #### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0*
@@ -94,11 +107,11 @@ Security vulnerability detection and code refactoring tools.
 
 Full CRUD operations for network infrastructure management directly from Claude Code.
 
-**Commands:** `/initial-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`
+**Commands:** `/initial-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`, `/cmdb-audit`, `/cmdb-register`, `/cmdb-sync`
 
 ### Data Engineering
 
-#### [data-platform](./plugins/data-platform/README.md) *NEW*
+#### [data-platform](./plugins/data-platform/README.md) *NEW in v4.0.0*
 **pandas, PostgreSQL/PostGIS, and dbt Integration**
 
 Comprehensive data engineering toolkit with persistent DataFrame storage.
@@ -111,6 +124,22 @@ Comprehensive data engineering toolkit with persistent DataFrame storage.
 
 **Commands:** `/ingest`, `/profile`, `/schema`, `/explain`, `/lineage`, `/run`
 
+### Visualization
+
+#### [viz-platform](./plugins/viz-platform/README.md) *NEW in v4.0.0*
+**Dash Mantine Components Validation and Theming**
+
+Visualization toolkit with version-locked component validation and design token theming.
+
+- 3 DMC tools with static JSON registry (prevents prop hallucination)
+- 2 Chart tools with Plotly and theme integration
+- 5 Layout tools for dashboard composition
+- 6 Theme tools with design token system
+- 5 Page tools for multi-page app structure
+- Dual theme storage: user-level and project-level
+
+**Commands:** `/chart`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/initial-setup`
+
 ## MCP Servers
 
 MCP servers are **shared at repository root** with **symlinks** from plugins that use them.
@@ -141,7 +170,7 @@ Comprehensive NetBox REST API integration for infrastructure management.
 | Virtualization | Clusters, VMs, Interfaces |
 | Extras | Tags, Custom Fields, Audit Log |
 
-### Data Platform MCP Server (shared) *NEW*
+### Data Platform MCP Server (shared) *NEW in v4.0.0*
 
 pandas, PostgreSQL/PostGIS, and dbt integration for data engineering.
 
@@ -152,6 +181,28 @@ pandas, PostgreSQL/PostGIS, and dbt integration for data engineering.
 | PostGIS | `st_tables`, `st_geometry_type`, `st_srid`, `st_extent` |
 | dbt | `dbt_parse`, `dbt_run`, `dbt_test`, `dbt_build`, `dbt_compile`, `dbt_ls`, `dbt_docs_generate`, `dbt_lineage` |
 
+### Viz Platform MCP Server (shared) *NEW in v4.0.0*
+
+Dash Mantine Components validation and visualization tools.
+
+| Category | Tools |
+|----------|-------|
+| DMC | `list_components`, `get_component_props`, `validate_component` |
+| Chart | `chart_create`, `chart_configure_interaction` |
+| Layout | `layout_create`, `layout_add_filter`, `layout_set_grid`, `layout_get`, `layout_add_section` |
+| Theme | `theme_create`, `theme_extend`, `theme_validate`, `theme_export_css`, `theme_list`, `theme_activate` |
+| Page | `page_create`, `page_add_navbar`, `page_set_auth`, `page_list`, `page_get_app_config` |
+
+### Contract Validator MCP Server (shared) *NEW in v5.0.0*
+
+Cross-plugin compatibility validation tools.
+
+| Category | Tools |
+|----------|-------|
+| Parse | `parse_plugin_interface`, `parse_claude_md_agents` |
+| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` |
+| Report | `generate_compatibility_report`, `list_issues` |
+
 ## Installation
 
 ### Prerequisites
@@ -249,6 +300,8 @@ After installing plugins, the `/plugin` command may show `(no content)` - this i
 | claude-config-maintainer | `/claude-config-maintainer:config-analyze` |
 | cmdb-assistant | `/cmdb-assistant:cmdb-search` |
 | data-platform | `/data-platform:ingest` |
+| viz-platform | `/viz-platform:chart` |
+| contract-validator | `/contract-validator:validate-contracts` |
 
 ## Repository Structure
 
@@ -259,13 +312,17 @@ leo-claude-mktplace/
 ├── mcp-servers/                   # SHARED MCP servers (v3.0.0+)
 │   ├── gitea/                     # Gitea MCP (issues, PRs, wiki)
 │   ├── netbox/                    # NetBox MCP (CMDB)
-│   └── data-platform/             # Data engineering (pandas, PostgreSQL, dbt)
+│   ├── data-platform/             # Data engineering (pandas, PostgreSQL, dbt)
+│   ├── viz-platform/              # Visualization (DMC, Plotly, theming)
+│   └── contract-validator/        # Cross-plugin validation (v5.0.0)
 ├── plugins/                       # All plugins
 │   ├── projman/                   # Sprint management
 │   ├── git-flow/                  # Git workflow automation
 │   ├── pr-review/                 # PR review
 │   ├── clarity-assist/            # Prompt optimization
-│   ├── data-platform/             # Data engineering (NEW)
+│   ├── data-platform/             # Data engineering
+│   ├── viz-platform/              # Visualization
+│   ├── contract-validator/        # Cross-plugin validation (NEW)
 │   ├── claude-config-maintainer/  # CLAUDE.md optimization
 │   ├── cmdb-assistant/            # NetBox CMDB integration
 │   ├── doc-guardian/              # Documentation drift detection

docs/CANONICAL-PATHS.md

@@ -2,7 +2,7 @@
 
 **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
 
-Last Updated: 2026-01-23 (v3.1.2)
+Last Updated: 2026-01-27 (v5.1.0)
 
 ---
 
@@ -37,8 +37,40 @@ leo-claude-mktplace/
 │   │   │       └── pull_requests.py  # NEW in v3.0.0
 │   │   ├── requirements.txt
 │   │   └── .venv/
-│   └── netbox/                 # NetBox MCP server
+│   ├── netbox/                 # NetBox MCP server
+│   │   ├── mcp_server/
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   ├── data-platform/          # Data engineering MCP (NEW v4.0.0)
+│   │   ├── mcp_server/
+│   │   │   ├── server.py
+│   │   │   ├── pandas_tools.py
+│   │   │   ├── postgres_tools.py
+│   │   │   └── dbt_tools.py
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   ├── contract-validator/     # Contract validation MCP (NEW v5.0.0)
+│   │   ├── mcp_server/
+│   │   │   ├── server.py
+│   │   │   ├── parse_tools.py
+│   │   │   ├── validation_tools.py
+│   │   │   └── report_tools.py
+│   │   ├── tests/
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   └── viz-platform/           # Visualization MCP (NEW v4.1.0)
 │       ├── mcp_server/
+│       │   ├── server.py
+│       │   ├── config.py
+│       │   ├── component_registry.py
+│       │   ├── dmc_tools.py
+│       │   ├── chart_tools.py
+│       │   ├── layout_tools.py
+│       │   ├── theme_tools.py
+│       │   ├── theme_store.py
+│       │   └── page_tools.py
+│       ├── registry/           # DMC component JSON registries
+│       ├── tests/              # 94 tests
 │       ├── requirements.txt
 │       └── .venv/
 ├── plugins/                    # ALL plugins
@@ -94,20 +126,50 @@ leo-claude-mktplace/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   └── pr-review/              # NEW in v3.0.0
+│   ├── pr-review/              # NEW in v3.0.0
+│   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── data-platform/          # NEW in v4.0.0
+│   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── data-platform -> ../../../mcp-servers/data-platform  # SYMLINK
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── hooks/
+│   │   └── claude-md-integration.md
+│   ├── contract-validator/     # NEW in v5.0.0
+│   │   ├── .claude-plugin/
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/
+│   │   │   └── contract-validator -> ../../../mcp-servers/contract-validator  # SYMLINK
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   └── claude-md-integration.md
+│   └── viz-platform/           # NEW in v4.1.0
 │       ├── .claude-plugin/
 │       ├── .mcp.json
 │       ├── mcp-servers/
-│       │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│       │   └── viz-platform -> ../../../mcp-servers/viz-platform  # SYMLINK
 │       ├── commands/
 │       ├── agents/
-│       ├── skills/
+│       ├── hooks/
 │       └── claude-md-integration.md
 ├── scripts/                    # Setup and maintenance scripts
 │   ├── setup.sh                # Initial setup (create venvs, config templates)
 │   ├── post-update.sh          # Post-update (rebuild venvs, verify symlinks)
 │   ├── check-venv.sh           # Check if venvs exist (for hooks)
-│   └── validate-marketplace.sh # Marketplace compliance validation
+│   ├── validate-marketplace.sh # Marketplace compliance validation
+│   ├── verify-hooks.sh         # Verify all hooks use correct event types
+│   ├── setup-venvs.sh          # Setup/repair MCP server venvs
+│   ├── venv-repair.sh          # Repair broken venv symlinks
+│   └── release.sh              # Release automation with version bumping
 ├── CLAUDE.md
 ├── README.md
 ├── LICENSE
@@ -226,6 +288,9 @@ MCP servers are now **shared at repository root** with **symlinks** from plugins
 plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
 plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
 plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
+plugins/data-platform/mcp-servers/data-platform -> ../../../mcp-servers/data-platform
+plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platform
+plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-servers/contract-validator
 ```
 
 ---
@@ -234,6 +299,9 @@ plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
 
 | Date | Change | By |
 |------|--------|-----|
+| 2026-01-26 | v5.0.0: Added contract-validator plugin and MCP server | Claude Code |
+| 2026-01-26 | v4.1.0: Added viz-platform plugin and MCP server | Claude Code |
+| 2026-01-25 | v4.0.0: Added data-platform plugin and MCP server | Claude Code |
 | 2026-01-20 | v3.0.0: MCP servers moved to root with symlinks | Claude Code |
 | 2026-01-20 | v3.0.0: Added clarity-assist, git-flow, pr-review plugins | Claude Code |
 | 2026-01-20 | v3.0.0: Added docs/CONFIGURATION.md | Claude Code |

docs/COMMANDS-CHEATSHEET.md

@@ -23,6 +23,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
 | **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
 | **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
+| **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
 | **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message |
 | **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation |
 | **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch |
@@ -55,6 +56,9 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
 | **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes |
 | **cmdb-assistant** | `/cmdb-site` | | X | Manage sites, locations, racks, and regions |
+| **cmdb-assistant** | `/cmdb-audit` | | X | Data quality analysis (VMs, devices, naming, roles) |
+| **cmdb-assistant** | `/cmdb-register` | | X | Register current machine into NetBox with running apps |
+| **cmdb-assistant** | `/cmdb-sync` | | X | Sync machine state with NetBox (detect drift, update) |
 | **project-hygiene** | *PostToolUse hook* | X | | Removes temp files, warns about unexpected root files |
 | **data-platform** | `/ingest` | | X | Load data from CSV, Parquet, JSON into DataFrame |
 | **data-platform** | `/profile` | | X | Generate data profiling report with statistics |
@@ -64,6 +68,14 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **data-platform** | `/run` | | X | Run dbt models with validation |
 | **data-platform** | `/initial-setup` | | X | Setup wizard for data-platform MCP servers |
 | **data-platform** | *SessionStart hook* | X | | Checks PostgreSQL connection (non-blocking warning) |
+| **viz-platform** | `/initial-setup` | | X | Setup wizard for viz-platform MCP server |
+| **viz-platform** | `/chart` | | X | Create Plotly charts with theme integration |
+| **viz-platform** | `/dashboard` | | X | Create dashboard layouts with filters and grids |
+| **viz-platform** | `/theme` | | X | Apply existing theme to visualizations |
+| **viz-platform** | `/theme-new` | | X | Create new custom theme with design tokens |
+| **viz-platform** | `/theme-css` | | X | Export theme as CSS custom properties |
+| **viz-platform** | `/component` | | X | Inspect DMC component props and validation |
+| **viz-platform** | *SessionStart hook* | X | | Checks DMC version (non-blocking warning) |
 
 ---
 
@@ -78,6 +90,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **Git Operations** | git-flow | Commits, branches, workflow automation |
 | **Infrastructure** | cmdb-assistant | NetBox CMDB management |
 | **Data Engineering** | data-platform | pandas, PostgreSQL, dbt operations |
+| **Visualization** | viz-platform | DMC validation, Plotly charts, theming |
 | **Maintenance** | project-hygiene | Automatic cleanup |
 
 ---
@@ -92,6 +105,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
 | **code-sentinel** | PreToolUse (Write/Edit) | Scans for security issues; blocks critical vulnerabilities |
 | **project-hygiene** | PostToolUse (Write/Edit) | Cleans temp files, warns about misplaced files |
 | **data-platform** | SessionStart | Checks PostgreSQL connection; non-blocking warning if unavailable |
+| **viz-platform** | SessionStart | Checks DMC version; non-blocking warning if mismatch detected |
 
 ---
 
@@ -234,9 +248,10 @@ Some plugins require MCP server connectivity:
 | pr-review | Gitea | PR operations and reviews |
 | cmdb-assistant | NetBox | Infrastructure CMDB |
 | data-platform | pandas, PostgreSQL, dbt | DataFrames, database queries, dbt builds |
+| viz-platform | viz-platform | DMC validation, charts, layouts, themes, pages |
 
 Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/claude/netbox.env`, or `~/.config/claude/postgres.env`.
 
 ---
 
-*Last Updated: 2026-01-25*
+*Last Updated: 2026-01-26*

docs/CONFIGURATION.md

@@ -393,6 +393,8 @@ PR_REVIEW_AUTO_SUBMIT=false
 | **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
 | **clarity-assist** | None | None | None needed |
 | **cmdb-assistant** | netbox.env | None | `/initial-setup` |
+| **data-platform** | postgres.env | .env (optional) | `/initial-setup` |
+| **viz-platform** | None | .env (optional DMC_VERSION) | `/initial-setup` |
 | **doc-guardian** | None | None | None needed |
 | **code-sentinel** | None | None | None needed |
 | **project-hygiene** | None | None | None needed |

mcp-servers/contract-validator/mcp_server/__init__.py

@@ -0,0 +1,3 @@
+"""Contract Validator MCP Server - Cross-plugin compatibility validation."""
+
+__version__ = "1.0.0"

mcp-servers/contract-validator/mcp_server/parse_tools.py

@@ -0,0 +1,415 @@
+"""
+Parse tools for extracting interfaces from plugin documentation.
+
+Provides structured extraction of:
+- Plugin interfaces from README.md (commands, agents, tools)
+- Agent definitions from CLAUDE.md (tool sequences, workflows)
+"""
+import re
+import os
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel
+
+
+class ToolInfo(BaseModel):
+    """Information about a single tool"""
+    name: str
+    category: Optional[str] = None
+    description: Optional[str] = None
+
+
+class CommandInfo(BaseModel):
+    """Information about a plugin command"""
+    name: str
+    description: Optional[str] = None
+
+
+class AgentInfo(BaseModel):
+    """Information about a plugin agent"""
+    name: str
+    description: Optional[str] = None
+    tools: list[str] = []
+
+
+class PluginInterface(BaseModel):
+    """Structured plugin interface extracted from README"""
+    plugin_name: str
+    description: Optional[str] = None
+    commands: list[CommandInfo] = []
+    agents: list[AgentInfo] = []
+    tools: list[ToolInfo] = []
+    tool_categories: dict[str, list[str]] = {}
+    features: list[str] = []
+
+
+class ClaudeMdAgent(BaseModel):
+    """Agent definition extracted from CLAUDE.md"""
+    name: str
+    personality: Optional[str] = None
+    responsibilities: list[str] = []
+    tool_refs: list[str] = []
+    workflow_steps: list[str] = []
+
+
+class ParseTools:
+    """Tools for parsing plugin documentation"""
+
+    async def parse_plugin_interface(self, plugin_path: str) -> dict:
+        """
+        Parse plugin README.md to extract interface declarations.
+
+        Args:
+            plugin_path: Path to plugin directory or README.md file
+
+        Returns:
+            Structured interface with commands, agents, tools, etc.
+        """
+        # Resolve path to README
+        path = Path(plugin_path)
+        if path.is_dir():
+            readme_path = path / "README.md"
+        else:
+            readme_path = path
+
+        if not readme_path.exists():
+            return {
+                "error": f"README.md not found at {readme_path}",
+                "plugin_path": plugin_path
+            }
+
+        content = readme_path.read_text()
+        plugin_name = self._extract_plugin_name(content, path)
+
+        interface = PluginInterface(
+            plugin_name=plugin_name,
+            description=self._extract_description(content),
+            commands=self._extract_commands(content),
+            agents=self._extract_agents_from_readme(content),
+            tools=self._extract_tools(content),
+            tool_categories=self._extract_tool_categories(content),
+            features=self._extract_features(content)
+        )
+
+        return interface.model_dump()
+
+    async def parse_claude_md_agents(self, claude_md_path: str) -> dict:
+        """
+        Parse CLAUDE.md to extract agent definitions and tool sequences.
+
+        Args:
+            claude_md_path: Path to CLAUDE.md file
+
+        Returns:
+            List of agents with their tool sequences
+        """
+        path = Path(claude_md_path)
+
+        if not path.exists():
+            return {
+                "error": f"CLAUDE.md not found at {path}",
+                "claude_md_path": claude_md_path
+            }
+
+        content = path.read_text()
+        agents = self._extract_agents_from_claude_md(content)
+
+        return {
+            "file": str(path),
+            "agents": [a.model_dump() for a in agents],
+            "agent_count": len(agents)
+        }
+
+    def _extract_plugin_name(self, content: str, path: Path) -> str:
+        """Extract plugin name from content or path"""
+        # Try to get from H1 header
+        match = re.search(r'^#\s+(.+?)(?:\s+Plugin|\s*$)', content, re.MULTILINE)
+        if match:
+            name = match.group(1).strip()
+            # Handle cases like "# data-platform Plugin"
+            name = re.sub(r'\s*Plugin\s*$', '', name, flags=re.IGNORECASE)
+            return name
+
+        # Fall back to directory name
+        if path.is_dir():
+            return path.name
+        return path.parent.name
+
+    def _extract_description(self, content: str) -> Optional[str]:
+        """Extract plugin description from first paragraph after title"""
+        # Get content after H1, before first H2
+        match = re.search(r'^#\s+.+?\n\n(.+?)(?=\n##|\n\n##|\Z)', content, re.MULTILINE | re.DOTALL)
+        if match:
+            desc = match.group(1).strip()
+            # Take first paragraph only
+            desc = desc.split('\n\n')[0].strip()
+            return desc
+        return None
+
+    def _extract_commands(self, content: str) -> list[CommandInfo]:
+        """Extract commands from Commands section"""
+        commands = []
+
+        # Find Commands section
+        commands_section = self._extract_section(content, "Commands")
+        if not commands_section:
+            return commands
+
+        # Parse table format: | Command | Description |
+        # Only match actual command names (start with / or alphanumeric)
+        table_pattern = r'\|\s*`?(/[a-z][-a-z0-9]*)`?\s*\|\s*([^|]+)\s*\|'
+        for match in re.finditer(table_pattern, commands_section):
+            cmd_name = match.group(1).strip()
+            desc = match.group(2).strip()
+
+            # Skip header row and separators
+            if cmd_name.lower() in ('command', 'commands') or cmd_name.startswith('-'):
+                continue
+
+            commands.append(CommandInfo(
+                name=cmd_name,
+                description=desc
+            ))
+
+        # Also look for ### `/command-name` format (with backticks)
+        cmd_header_pattern = r'^###\s+`(/[a-z][-a-z0-9]*)`\s*\n(.+?)(?=\n###|\n##|\Z)'
+        for match in re.finditer(cmd_header_pattern, commands_section, re.MULTILINE | re.DOTALL):
+            cmd_name = match.group(1).strip()
+            desc_block = match.group(2).strip()
+            # Get first line or paragraph as description
+            desc = desc_block.split('\n')[0].strip()
+
+            # Don't duplicate if already found in table
+            if not any(c.name == cmd_name for c in commands):
+                commands.append(CommandInfo(name=cmd_name, description=desc))
+
+        # Also look for ### /command-name format (without backticks)
+        cmd_header_pattern2 = r'^###\s+(/[a-z][-a-z0-9]*)\s*\n(.+?)(?=\n###|\n##|\Z)'
+        for match in re.finditer(cmd_header_pattern2, commands_section, re.MULTILINE | re.DOTALL):
+            cmd_name = match.group(1).strip()
+            desc_block = match.group(2).strip()
+            # Get first line or paragraph as description
+            desc = desc_block.split('\n')[0].strip()
+
+            # Don't duplicate if already found in table
+            if not any(c.name == cmd_name for c in commands):
+                commands.append(CommandInfo(name=cmd_name, description=desc))
+
+        return commands
+
+    def _extract_agents_from_readme(self, content: str) -> list[AgentInfo]:
+        """Extract agents from Agents section in README"""
+        agents = []
+
+        # Find Agents section
+        agents_section = self._extract_section(content, "Agents")
+        if not agents_section:
+            return agents
+
+        # Parse table format: | Agent | Description |
+        # Only match actual agent names (alphanumeric with dashes/underscores)
+        table_pattern = r'\|\s*`?([a-z][-a-z0-9_]*)`?\s*\|\s*([^|]+)\s*\|'
+        for match in re.finditer(table_pattern, agents_section):
+            agent_name = match.group(1).strip()
+            desc = match.group(2).strip()
+
+            # Skip header row and separators
+            if agent_name.lower() in ('agent', 'agents') or agent_name.startswith('-'):
+                continue
+
+            agents.append(AgentInfo(name=agent_name, description=desc))
+
+        return agents
+
+    def _extract_tools(self, content: str) -> list[ToolInfo]:
+        """Extract tool list from Tools Summary or similar section"""
+        tools = []
+
+        # Find Tools Summary section
+        tools_section = self._extract_section(content, "Tools Summary")
+        if not tools_section:
+            tools_section = self._extract_section(content, "Tools")
+        if not tools_section:
+            tools_section = self._extract_section(content, "MCP Server Tools")
+
+        if not tools_section:
+            return tools
+
+        # Parse category headers: ### category (N tools)
+        category_pattern = r'###\s*(.+?)\s*(?:\((\d+)\s*tools?\))?\s*\n([^#]+)'
+        for match in re.finditer(category_pattern, tools_section):
+            category = match.group(1).strip()
+            tool_list_text = match.group(3).strip()
+
+            # Extract tool names from backtick lists
+            tool_names = re.findall(r'`([a-z_]+)`', tool_list_text)
+            for name in tool_names:
+                tools.append(ToolInfo(name=name, category=category))
+
+        # Also look for inline tool lists without categories
+        inline_pattern = r'`([a-z_]+)`'
+        all_tool_names = set(t.name for t in tools)
+        for match in re.finditer(inline_pattern, tools_section):
+            name = match.group(1)
+            if name not in all_tool_names:
+                tools.append(ToolInfo(name=name))
+                all_tool_names.add(name)
+
+        return tools
+
+    def _extract_tool_categories(self, content: str) -> dict[str, list[str]]:
+        """Extract tool categories with their tool lists"""
+        categories = {}
+
+        tools_section = self._extract_section(content, "Tools Summary")
+        if not tools_section:
+            tools_section = self._extract_section(content, "Tools")
+        if not tools_section:
+            return categories
+
+        # Parse category headers: ### category (N tools)
+        category_pattern = r'###\s*(.+?)\s*(?:\((\d+)\s*tools?\))?\s*\n([^#]+)'
+        for match in re.finditer(category_pattern, tools_section):
+            category = match.group(1).strip()
+            tool_list_text = match.group(3).strip()
+
+            # Extract tool names from backtick lists
+            tool_names = re.findall(r'`([a-z_]+)`', tool_list_text)
+            if tool_names:
+                categories[category] = tool_names
+
+        return categories
+
+    def _extract_features(self, content: str) -> list[str]:
+        """Extract features from Features section"""
+        features = []
+
+        features_section = self._extract_section(content, "Features")
+        if not features_section:
+            return features
+
+        # Parse bullet points
+        bullet_pattern = r'^[-*]\s+\*\*(.+?)\*\*'
+        for match in re.finditer(bullet_pattern, features_section, re.MULTILINE):
+            features.append(match.group(1).strip())
+
+        return features
+
+    def _extract_section(self, content: str, section_name: str) -> Optional[str]:
+        """Extract content of a markdown section by header name"""
+        # Match ## Section Name - include all content until next ## (same level or higher)
+        pattern = rf'^##\s+{re.escape(section_name)}(?:\s*\([^)]*\))?\s*\n(.*?)(?=\n##[^#]|\Z)'
+        match = re.search(pattern, content, re.MULTILINE | re.DOTALL | re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+
+        # Try ### level - include content until next ## or ###
+        pattern = rf'^###\s+{re.escape(section_name)}(?:\s*\([^)]*\))?\s*\n(.*?)(?=\n##|\n###[^#]|\Z)'
+        match = re.search(pattern, content, re.MULTILINE | re.DOTALL | re.IGNORECASE)
+        if match:
+            return match.group(1).strip()
+
+        return None
+
+    def _extract_agents_from_claude_md(self, content: str) -> list[ClaudeMdAgent]:
+        """Extract agent definitions from CLAUDE.md"""
+        agents = []
+
+        # Look for Four-Agent Model section specifically
+        # Match section headers like "### Four-Agent Model (projman)" or "## Four-Agent Model"
+        agent_model_match = re.search(
+            r'^##[#]?\s+Four-Agent Model.*?\n(.*?)(?=\n##[^#]|\Z)',
+            content, re.MULTILINE | re.DOTALL
+        )
+        agent_model_section = agent_model_match.group(1) if agent_model_match else None
+
+        if agent_model_section:
+            # Parse agent table within this section
+            # | **Planner** | Thoughtful, methodical | Sprint planning, ... |
+            # Match rows where first cell starts with ** (bold) and contains a capitalized word
+            agent_table_pattern = r'\|\s*\*\*([A-Z][a-zA-Z\s]+?)\*\*\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|'
+
+            for match in re.finditer(agent_table_pattern, agent_model_section):
+                agent_name = match.group(1).strip()
+                personality = match.group(2).strip()
+                responsibilities = match.group(3).strip()
+
+                # Skip header rows and separator rows
+                if agent_name.lower() in ('agent', 'agents', '---', '-', ''):
+                    continue
+                if 'personality' in personality.lower() or '---' in personality:
+                    continue
+
+                # Skip if personality looks like tool names (contains backticks)
+                if '`' in personality:
+                    continue
+
+                # Extract tool references from responsibilities
+                tool_refs = re.findall(r'`([a-z_]+)`', responsibilities)
+
+                # Split responsibilities by comma
+                resp_list = [r.strip() for r in responsibilities.split(',')]
+
+                agents.append(ClaudeMdAgent(
+                    name=agent_name,
+                    personality=personality,
+                    responsibilities=resp_list,
+                    tool_refs=tool_refs
+                ))
+
+        # Also look for agents table in ## Agents section
+        agents_section = self._extract_section(content, "Agents")
+        if agents_section:
+            # Parse table: | Agent | Description |
+            table_pattern = r'\|\s*`?([a-z][-a-z0-9_]+)`?\s*\|\s*([^|]+)\s*\|'
+            for match in re.finditer(table_pattern, agents_section):
+                agent_name = match.group(1).strip()
+                desc = match.group(2).strip()
+
+                # Skip header rows
+                if agent_name.lower() in ('agent', 'agents', '---', '-'):
+                    continue
+
+                # Check if agent already exists
+                if not any(a.name.lower() == agent_name.lower() for a in agents):
+                    agents.append(ClaudeMdAgent(
+                        name=agent_name,
+                        responsibilities=[desc] if desc else []
+                    ))
+
+        # Look for workflow sections to enrich agent data
+        workflow_section = self._extract_section(content, "Workflow")
+        if workflow_section:
+            # Parse numbered steps
+            step_pattern = r'^\d+\.\s+(.+?)$'
+            workflow_steps = re.findall(step_pattern, workflow_section, re.MULTILINE)
+
+            # Associate workflow steps with agents mentioned
+            for agent in agents:
+                for step in workflow_steps:
+                    if agent.name.lower() in step.lower():
+                        agent.workflow_steps.append(step)
+                        # Extract any tool references in the step
+                        step_tools = re.findall(r'`([a-z_]+)`', step)
+                        agent.tool_refs.extend(t for t in step_tools if t not in agent.tool_refs)
+
+        # Look for agent-specific sections (### Planner Agent)
+        agent_section_pattern = r'^###?\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)?)\s+Agent\s*\n(.*?)(?=\n##|\n###|\Z)'
+        for match in re.finditer(agent_section_pattern, content, re.MULTILINE | re.DOTALL):
+            agent_name = match.group(1).strip()
+            section_content = match.group(2).strip()
+
+            # Check if agent already exists
+            existing = next((a for a in agents if a.name.lower() == agent_name.lower()), None)
+            if existing:
+                # Add tool refs from this section
+                tool_refs = re.findall(r'`([a-z_]+)`', section_content)
+                existing.tool_refs.extend(t for t in tool_refs if t not in existing.tool_refs)
+            else:
+                tool_refs = re.findall(r'`([a-z_]+)`', section_content)
+                agents.append(ClaudeMdAgent(
+                    name=agent_name,
+                    tool_refs=tool_refs
+                ))
+
+        return agents

mcp-servers/contract-validator/mcp_server/report_tools.py

@@ -0,0 +1,337 @@
+"""
+Report tools for generating compatibility reports and listing issues.
+
+Provides:
+- generate_compatibility_report: Full marketplace validation report
+- list_issues: Filtered issue listing
+"""
+import os
+from pathlib import Path
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel
+
+from .parse_tools import ParseTools
+from .validation_tools import ValidationTools, IssueSeverity, IssueType, ValidationIssue
+
+
+class ReportSummary(BaseModel):
+    """Summary statistics for a report"""
+    total_plugins: int = 0
+    total_commands: int = 0
+    total_agents: int = 0
+    total_tools: int = 0
+    total_issues: int = 0
+    errors: int = 0
+    warnings: int = 0
+    info: int = 0
+
+
+class ReportTools:
+    """Tools for generating reports and listing issues"""
+
+    def __init__(self):
+        self.parse_tools = ParseTools()
+        self.validation_tools = ValidationTools()
+
+    async def generate_compatibility_report(
+        self,
+        marketplace_path: str,
+        format: str = "markdown"
+    ) -> dict:
+        """
+        Generate a comprehensive compatibility report for all plugins.
+
+        Args:
+            marketplace_path: Path to marketplace root directory
+            format: Output format ("markdown" or "json")
+
+        Returns:
+            Full compatibility report with all findings
+        """
+        marketplace = Path(marketplace_path)
+        plugins_dir = marketplace / "plugins"
+
+        if not plugins_dir.exists():
+            return {
+                "error": f"Plugins directory not found at {plugins_dir}",
+                "marketplace_path": marketplace_path
+            }
+
+        # Discover all plugins
+        plugins = []
+        for item in plugins_dir.iterdir():
+            if item.is_dir() and (item / ".claude-plugin").exists():
+                plugins.append(item)
+
+        if not plugins:
+            return {
+                "error": "No plugins found in marketplace",
+                "marketplace_path": marketplace_path
+            }
+
+        # Parse all plugin interfaces
+        interfaces = {}
+        all_issues = []
+        summary = ReportSummary(total_plugins=len(plugins))
+
+        for plugin_path in plugins:
+            interface = await self.parse_tools.parse_plugin_interface(str(plugin_path))
+            if "error" not in interface:
+                interfaces[interface["plugin_name"]] = interface
+                summary.total_commands += len(interface.get("commands", []))
+                summary.total_agents += len(interface.get("agents", []))
+                summary.total_tools += len(interface.get("tools", []))
+
+        # Run pairwise compatibility checks
+        plugin_names = list(interfaces.keys())
+        compatibility_results = []
+
+        for i, name_a in enumerate(plugin_names):
+            for name_b in plugin_names[i+1:]:
+                path_a = plugins_dir / self._find_plugin_dir(plugins_dir, name_a)
+                path_b = plugins_dir / self._find_plugin_dir(plugins_dir, name_b)
+
+                result = await self.validation_tools.validate_compatibility(
+                    str(path_a), str(path_b)
+                )
+
+                if "error" not in result:
+                    compatibility_results.append(result)
+                    all_issues.extend(result.get("issues", []))
+
+        # Parse CLAUDE.md if exists
+        claude_md = marketplace / "CLAUDE.md"
+        agents_from_claude = []
+        if claude_md.exists():
+            agents_result = await self.parse_tools.parse_claude_md_agents(str(claude_md))
+            if "error" not in agents_result:
+                agents_from_claude = agents_result.get("agents", [])
+
+                # Validate each agent
+                for agent in agents_from_claude:
+                    agent_result = await self.validation_tools.validate_agent_refs(
+                        agent["name"],
+                        str(claude_md),
+                        [str(p) for p in plugins]
+                    )
+                    if "error" not in agent_result:
+                        all_issues.extend(agent_result.get("issues", []))
+
+        # Count issues by severity
+        for issue in all_issues:
+            severity = issue.get("severity", "info")
+            if isinstance(severity, str):
+                severity_str = severity.lower()
+            else:
+                severity_str = severity.value if hasattr(severity, 'value') else str(severity).lower()
+
+            if "error" in severity_str:
+                summary.errors += 1
+            elif "warning" in severity_str:
+                summary.warnings += 1
+            else:
+                summary.info += 1
+
+        summary.total_issues = len(all_issues)
+
+        # Generate report
+        if format == "json":
+            return {
+                "generated_at": datetime.now().isoformat(),
+                "marketplace_path": marketplace_path,
+                "summary": summary.model_dump(),
+                "plugins": interfaces,
+                "compatibility_checks": compatibility_results,
+                "claude_md_agents": agents_from_claude,
+                "all_issues": all_issues
+            }
+        else:
+            # Generate markdown report
+            report = self._generate_markdown_report(
+                marketplace_path,
+                summary,
+                interfaces,
+                compatibility_results,
+                agents_from_claude,
+                all_issues
+            )
+            return {
+                "generated_at": datetime.now().isoformat(),
+                "marketplace_path": marketplace_path,
+                "summary": summary.model_dump(),
+                "report": report
+            }
+
+    def _find_plugin_dir(self, plugins_dir: Path, plugin_name: str) -> str:
+        """Find plugin directory by name (handles naming variations)"""
+        # Try exact match first
+        for item in plugins_dir.iterdir():
+            if item.is_dir():
+                if item.name.lower() == plugin_name.lower():
+                    return item.name
+                # Check plugin.json for name
+                plugin_json = item / ".claude-plugin" / "plugin.json"
+                if plugin_json.exists():
+                    import json
+                    try:
+                        data = json.loads(plugin_json.read_text())
+                        if data.get("name", "").lower() == plugin_name.lower():
+                            return item.name
+                    except:
+                        pass
+        return plugin_name
+
+    def _generate_markdown_report(
+        self,
+        marketplace_path: str,
+        summary: ReportSummary,
+        interfaces: dict,
+        compatibility_results: list,
+        agents: list,
+        issues: list
+    ) -> str:
+        """Generate markdown formatted report"""
+        lines = [
+            "# Contract Validation Report",
+            "",
+            f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
+            f"**Marketplace:** `{marketplace_path}`",
+            "",
+            "## Summary",
+            "",
+            f"| Metric | Count |",
+            f"|--------|-------|",
+            f"| Plugins | {summary.total_plugins} |",
+            f"| Commands | {summary.total_commands} |",
+            f"| Agents | {summary.total_agents} |",
+            f"| Tools | {summary.total_tools} |",
+            f"| **Issues** | **{summary.total_issues}** |",
+            f"| - Errors | {summary.errors} |",
+            f"| - Warnings | {summary.warnings} |",
+            f"| - Info | {summary.info} |",
+            "",
+        ]
+
+        # Plugin details
+        lines.extend([
+            "## Plugins",
+            "",
+        ])
+
+        for name, interface in interfaces.items():
+            cmds = len(interface.get("commands", []))
+            agents_count = len(interface.get("agents", []))
+            tools = len(interface.get("tools", []))
+            lines.append(f"### {name}")
+            lines.append("")
+            lines.append(f"- Commands: {cmds}")
+            lines.append(f"- Agents: {agents_count}")
+            lines.append(f"- Tools: {tools}")
+            lines.append("")
+
+        # Compatibility results
+        if compatibility_results:
+            lines.extend([
+                "## Compatibility Checks",
+                "",
+            ])
+
+            for result in compatibility_results:
+                status = "✓" if result.get("compatible", True) else "✗"
+                lines.append(f"### {result['plugin_a']} ↔ {result['plugin_b']} {status}")
+                lines.append("")
+
+                if result.get("shared_tools"):
+                    lines.append(f"- Shared tools: `{', '.join(result['shared_tools'])}`")
+                if result.get("issues"):
+                    for issue in result["issues"]:
+                        sev = issue.get("severity", "info")
+                        if hasattr(sev, 'value'):
+                            sev = sev.value
+                        lines.append(f"- [{sev.upper()}] {issue['message']}")
+                lines.append("")
+
+        # Issues section
+        if issues:
+            lines.extend([
+                "## All Issues",
+                "",
+                "| Severity | Type | Message |",
+                "|----------|------|---------|",
+            ])
+
+            for issue in issues:
+                sev = issue.get("severity", "info")
+                itype = issue.get("issue_type", "unknown")
+                msg = issue.get("message", "")
+
+                if hasattr(sev, 'value'):
+                    sev = sev.value
+                if hasattr(itype, 'value'):
+                    itype = itype.value
+
+                # Truncate message for table
+                msg_short = msg[:60] + "..." if len(msg) > 60 else msg
+                lines.append(f"| {sev} | {itype} | {msg_short} |")
+
+            lines.append("")
+
+        return "\n".join(lines)
+
+    async def list_issues(
+        self,
+        marketplace_path: str,
+        severity: str = "all",
+        issue_type: str = "all"
+    ) -> dict:
+        """
+        List validation issues with optional filtering.
+
+        Args:
+            marketplace_path: Path to marketplace root directory
+            severity: Filter by severity ("error", "warning", "info", "all")
+            issue_type: Filter by type ("missing_tool", "interface_mismatch", etc., "all")
+
+        Returns:
+            Filtered list of issues
+        """
+        # Generate full report first
+        report = await self.generate_compatibility_report(marketplace_path, format="json")
+
+        if "error" in report:
+            return report
+
+        all_issues = report.get("all_issues", [])
+
+        # Filter by severity
+        if severity != "all":
+            filtered = []
+            for issue in all_issues:
+                issue_sev = issue.get("severity", "info")
+                if hasattr(issue_sev, 'value'):
+                    issue_sev = issue_sev.value
+                if isinstance(issue_sev, str) and severity.lower() in issue_sev.lower():
+                    filtered.append(issue)
+            all_issues = filtered
+
+        # Filter by type
+        if issue_type != "all":
+            filtered = []
+            for issue in all_issues:
+                itype = issue.get("issue_type", "unknown")
+                if hasattr(itype, 'value'):
+                    itype = itype.value
+                if isinstance(itype, str) and issue_type.lower() in itype.lower():
+                    filtered.append(issue)
+            all_issues = filtered
+
+        return {
+            "marketplace_path": marketplace_path,
+            "filters": {
+                "severity": severity,
+                "issue_type": issue_type
+            },
+            "total_issues": len(all_issues),
+            "issues": all_issues
+        }

mcp-servers/contract-validator/mcp_server/server.py

@@ -0,0 +1,274 @@
+"""
+MCP Server entry point for Contract Validator.
+
+Provides cross-plugin compatibility validation and Claude.md agent verification
+tools to Claude Code via JSON-RPC 2.0 over stdio.
+"""
+import asyncio
+import logging
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .parse_tools import ParseTools
+from .validation_tools import ValidationTools
+from .report_tools import ReportTools
+
+# Suppress noisy MCP validation warnings on stderr
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("root").setLevel(logging.ERROR)
+logging.getLogger("mcp").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+class ContractValidatorMCPServer:
+    """MCP Server for cross-plugin compatibility validation"""
+
+    def __init__(self):
+        self.server = Server("contract-validator-mcp")
+        self.parse_tools = ParseTools()
+        self.validation_tools = ValidationTools()
+        self.report_tools = ReportTools()
+
+    async def initialize(self):
+        """Initialize server."""
+        logger.info("Contract Validator MCP Server initialized")
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            tools = [
+                # Parse tools (to be implemented in #186)
+                Tool(
+                    name="parse_plugin_interface",
+                    description="Parse plugin README.md to extract interface declarations (inputs, outputs, tools)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "plugin_path": {
+                                "type": "string",
+                                "description": "Path to plugin directory or README.md"
+                            }
+                        },
+                        "required": ["plugin_path"]
+                    }
+                ),
+                Tool(
+                    name="parse_claude_md_agents",
+                    description="Parse Claude.md to extract agent definitions and their tool sequences",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "claude_md_path": {
+                                "type": "string",
+                                "description": "Path to CLAUDE.md file"
+                            }
+                        },
+                        "required": ["claude_md_path"]
+                    }
+                ),
+                # Validation tools (to be implemented in #187)
+                Tool(
+                    name="validate_compatibility",
+                    description="Validate compatibility between two plugin interfaces",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "plugin_a": {
+                                "type": "string",
+                                "description": "Path to first plugin"
+                            },
+                            "plugin_b": {
+                                "type": "string",
+                                "description": "Path to second plugin"
+                            }
+                        },
+                        "required": ["plugin_a", "plugin_b"]
+                    }
+                ),
+                Tool(
+                    name="validate_agent_refs",
+                    description="Validate that all tool references in an agent definition exist",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "agent_name": {
+                                "type": "string",
+                                "description": "Name of agent to validate"
+                            },
+                            "claude_md_path": {
+                                "type": "string",
+                                "description": "Path to CLAUDE.md containing agent"
+                            },
+                            "plugin_paths": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Paths to available plugins"
+                            }
+                        },
+                        "required": ["agent_name", "claude_md_path"]
+                    }
+                ),
+                Tool(
+                    name="validate_data_flow",
+                    description="Validate data flow through an agent's tool sequence",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "agent_name": {
+                                "type": "string",
+                                "description": "Name of agent to validate"
+                            },
+                            "claude_md_path": {
+                                "type": "string",
+                                "description": "Path to CLAUDE.md containing agent"
+                            }
+                        },
+                        "required": ["agent_name", "claude_md_path"]
+                    }
+                ),
+                # Report tools (to be implemented in #188)
+                Tool(
+                    name="generate_compatibility_report",
+                    description="Generate a comprehensive compatibility report for all plugins",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "marketplace_path": {
+                                "type": "string",
+                                "description": "Path to marketplace root directory"
+                            },
+                            "format": {
+                                "type": "string",
+                                "enum": ["markdown", "json"],
+                                "default": "markdown",
+                                "description": "Output format"
+                            }
+                        },
+                        "required": ["marketplace_path"]
+                    }
+                ),
+                Tool(
+                    name="list_issues",
+                    description="List validation issues with optional filtering",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "marketplace_path": {
+                                "type": "string",
+                                "description": "Path to marketplace root directory"
+                            },
+                            "severity": {
+                                "type": "string",
+                                "enum": ["error", "warning", "info", "all"],
+                                "default": "all",
+                                "description": "Filter by severity"
+                            },
+                            "issue_type": {
+                                "type": "string",
+                                "enum": ["missing_tool", "interface_mismatch", "optional_dependency", "undeclared_output", "all"],
+                                "default": "all",
+                                "description": "Filter by issue type"
+                            }
+                        },
+                        "required": ["marketplace_path"]
+                    }
+                )
+            ]
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation."""
+            try:
+                # All tools return placeholder responses for now
+                # Actual implementation will be added in issues #186, #187, #188
+
+                if name == "parse_plugin_interface":
+                    result = await self._parse_plugin_interface(**arguments)
+                elif name == "parse_claude_md_agents":
+                    result = await self._parse_claude_md_agents(**arguments)
+                elif name == "validate_compatibility":
+                    result = await self._validate_compatibility(**arguments)
+                elif name == "validate_agent_refs":
+                    result = await self._validate_agent_refs(**arguments)
+                elif name == "validate_data_flow":
+                    result = await self._validate_data_flow(**arguments)
+                elif name == "generate_compatibility_report":
+                    result = await self._generate_compatibility_report(**arguments)
+                elif name == "list_issues":
+                    result = await self._list_issues(**arguments)
+                else:
+                    raise ValueError(f"Unknown tool: {name}")
+
+                return [TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str)
+                )]
+
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({"error": str(e)}, indent=2)
+                )]
+
+    # Parse tool implementations (Issue #186)
+
+    async def _parse_plugin_interface(self, plugin_path: str) -> dict:
+        """Parse plugin interface from README.md"""
+        return await self.parse_tools.parse_plugin_interface(plugin_path)
+
+    async def _parse_claude_md_agents(self, claude_md_path: str) -> dict:
+        """Parse agents from CLAUDE.md"""
+        return await self.parse_tools.parse_claude_md_agents(claude_md_path)
+
+    # Validation tool implementations (Issue #187)
+
+    async def _validate_compatibility(self, plugin_a: str, plugin_b: str) -> dict:
+        """Validate compatibility between plugins"""
+        return await self.validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    async def _validate_agent_refs(self, agent_name: str, claude_md_path: str, plugin_paths: list = None) -> dict:
+        """Validate agent tool references"""
+        return await self.validation_tools.validate_agent_refs(agent_name, claude_md_path, plugin_paths)
+
+    async def _validate_data_flow(self, agent_name: str, claude_md_path: str) -> dict:
+        """Validate agent data flow"""
+        return await self.validation_tools.validate_data_flow(agent_name, claude_md_path)
+
+    # Report tool implementations (Issue #188)
+
+    async def _generate_compatibility_report(self, marketplace_path: str, format: str = "markdown") -> dict:
+        """Generate comprehensive compatibility report"""
+        return await self.report_tools.generate_compatibility_report(marketplace_path, format)
+
+    async def _list_issues(self, marketplace_path: str, severity: str = "all", issue_type: str = "all") -> dict:
+        """List validation issues with filtering"""
+        return await self.report_tools.list_issues(marketplace_path, severity, issue_type)
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = ContractValidatorMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp-servers/contract-validator/mcp_server/validation_tools.py

@@ -0,0 +1,338 @@
+"""
+Validation tools for checking cross-plugin compatibility and agent references.
+
+Provides:
+- validate_compatibility: Compare two plugin interfaces
+- validate_agent_refs: Check agent tool references exist
+- validate_data_flow: Verify data flow through agent sequences
+"""
+from pathlib import Path
+from typing import Optional
+from pydantic import BaseModel
+from enum import Enum
+
+from .parse_tools import ParseTools, PluginInterface, ClaudeMdAgent
+
+
+class IssueSeverity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class IssueType(str, Enum):
+    MISSING_TOOL = "missing_tool"
+    INTERFACE_MISMATCH = "interface_mismatch"
+    OPTIONAL_DEPENDENCY = "optional_dependency"
+    UNDECLARED_OUTPUT = "undeclared_output"
+    INVALID_SEQUENCE = "invalid_sequence"
+
+
+class ValidationIssue(BaseModel):
+    """A single validation issue"""
+    severity: IssueSeverity
+    issue_type: IssueType
+    message: str
+    location: Optional[str] = None
+    suggestion: Optional[str] = None
+
+
+class CompatibilityResult(BaseModel):
+    """Result of compatibility check between two plugins"""
+    plugin_a: str
+    plugin_b: str
+    compatible: bool
+    shared_tools: list[str] = []
+    a_only_tools: list[str] = []
+    b_only_tools: list[str] = []
+    issues: list[ValidationIssue] = []
+
+
+class AgentValidationResult(BaseModel):
+    """Result of agent reference validation"""
+    agent_name: str
+    valid: bool
+    tool_refs_found: list[str] = []
+    tool_refs_missing: list[str] = []
+    issues: list[ValidationIssue] = []
+
+
+class DataFlowResult(BaseModel):
+    """Result of data flow validation"""
+    agent_name: str
+    valid: bool
+    flow_steps: list[str] = []
+    issues: list[ValidationIssue] = []
+
+
+class ValidationTools:
+    """Tools for validating plugin compatibility and agent references"""
+
+    def __init__(self):
+        self.parse_tools = ParseTools()
+
+    async def validate_compatibility(self, plugin_a: str, plugin_b: str) -> dict:
+        """
+        Validate compatibility between two plugin interfaces.
+
+        Compares tools, commands, and agents to identify overlaps and gaps.
+
+        Args:
+            plugin_a: Path to first plugin directory
+            plugin_b: Path to second plugin directory
+
+        Returns:
+            Compatibility report with shared tools, unique tools, and issues
+        """
+        # Parse both plugins
+        interface_a = await self.parse_tools.parse_plugin_interface(plugin_a)
+        interface_b = await self.parse_tools.parse_plugin_interface(plugin_b)
+
+        # Check for parse errors
+        if "error" in interface_a:
+            return {
+                "error": f"Failed to parse plugin A: {interface_a['error']}",
+                "plugin_a": plugin_a,
+                "plugin_b": plugin_b
+            }
+        if "error" in interface_b:
+            return {
+                "error": f"Failed to parse plugin B: {interface_b['error']}",
+                "plugin_a": plugin_a,
+                "plugin_b": plugin_b
+            }
+
+        # Extract tool names
+        tools_a = set(t["name"] for t in interface_a.get("tools", []))
+        tools_b = set(t["name"] for t in interface_b.get("tools", []))
+
+        # Find overlaps and differences
+        shared = tools_a & tools_b
+        a_only = tools_a - tools_b
+        b_only = tools_b - tools_a
+
+        issues = []
+
+        # Check for potential naming conflicts
+        if shared:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.WARNING,
+                issue_type=IssueType.INTERFACE_MISMATCH,
+                message=f"Both plugins define tools with same names: {list(shared)}",
+                location=f"{interface_a['plugin_name']} and {interface_b['plugin_name']}",
+                suggestion="Ensure tools with same names have compatible interfaces"
+            ))
+
+        # Check command overlaps
+        cmds_a = set(c["name"] for c in interface_a.get("commands", []))
+        cmds_b = set(c["name"] for c in interface_b.get("commands", []))
+        shared_cmds = cmds_a & cmds_b
+
+        if shared_cmds:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.ERROR,
+                issue_type=IssueType.INTERFACE_MISMATCH,
+                message=f"Command name conflict: {list(shared_cmds)}",
+                location=f"{interface_a['plugin_name']} and {interface_b['plugin_name']}",
+                suggestion="Rename conflicting commands to avoid ambiguity"
+            ))
+
+        result = CompatibilityResult(
+            plugin_a=interface_a["plugin_name"],
+            plugin_b=interface_b["plugin_name"],
+            compatible=len([i for i in issues if i.severity == IssueSeverity.ERROR]) == 0,
+            shared_tools=list(shared),
+            a_only_tools=list(a_only),
+            b_only_tools=list(b_only),
+            issues=issues
+        )
+
+        return result.model_dump()
+
+    async def validate_agent_refs(
+        self,
+        agent_name: str,
+        claude_md_path: str,
+        plugin_paths: list[str] = None
+    ) -> dict:
+        """
+        Validate that all tool references in an agent definition exist.
+
+        Args:
+            agent_name: Name of the agent to validate
+            claude_md_path: Path to CLAUDE.md containing the agent
+            plugin_paths: Optional list of plugin paths to check for tools
+
+        Returns:
+            Validation result with found/missing tools and issues
+        """
+        # Parse CLAUDE.md for agents
+        agents_result = await self.parse_tools.parse_claude_md_agents(claude_md_path)
+
+        if "error" in agents_result:
+            return {
+                "error": agents_result["error"],
+                "agent_name": agent_name
+            }
+
+        # Find the specific agent
+        agent = None
+        for a in agents_result.get("agents", []):
+            if a["name"].lower() == agent_name.lower():
+                agent = a
+                break
+
+        if not agent:
+            return {
+                "error": f"Agent '{agent_name}' not found in {claude_md_path}",
+                "agent_name": agent_name,
+                "available_agents": [a["name"] for a in agents_result.get("agents", [])]
+            }
+
+        # Collect all available tools from plugins
+        available_tools = set()
+        if plugin_paths:
+            for plugin_path in plugin_paths:
+                interface = await self.parse_tools.parse_plugin_interface(plugin_path)
+                if "error" not in interface:
+                    for tool in interface.get("tools", []):
+                        available_tools.add(tool["name"])
+
+        # Check agent tool references
+        tool_refs = set(agent.get("tool_refs", []))
+        found = tool_refs & available_tools if available_tools else tool_refs
+        missing = tool_refs - available_tools if available_tools else set()
+
+        issues = []
+
+        # Report missing tools
+        for tool in missing:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.ERROR,
+                issue_type=IssueType.MISSING_TOOL,
+                message=f"Agent '{agent_name}' references tool '{tool}' which is not found",
+                location=claude_md_path,
+                suggestion=f"Check if tool '{tool}' exists or fix the reference"
+            ))
+
+        # Check if agent has no tool refs (might be incomplete)
+        if not tool_refs:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.INFO,
+                issue_type=IssueType.UNDECLARED_OUTPUT,
+                message=f"Agent '{agent_name}' has no documented tool references",
+                location=claude_md_path,
+                suggestion="Consider documenting which tools this agent uses"
+            ))
+
+        result = AgentValidationResult(
+            agent_name=agent_name,
+            valid=len([i for i in issues if i.severity == IssueSeverity.ERROR]) == 0,
+            tool_refs_found=list(found),
+            tool_refs_missing=list(missing),
+            issues=issues
+        )
+
+        return result.model_dump()
+
+    async def validate_data_flow(self, agent_name: str, claude_md_path: str) -> dict:
+        """
+        Validate data flow through an agent's tool sequence.
+
+        Checks that each step's expected output can be used by the next step.
+
+        Args:
+            agent_name: Name of the agent to validate
+            claude_md_path: Path to CLAUDE.md containing the agent
+
+        Returns:
+            Data flow validation result with steps and issues
+        """
+        # Parse CLAUDE.md for agents
+        agents_result = await self.parse_tools.parse_claude_md_agents(claude_md_path)
+
+        if "error" in agents_result:
+            return {
+                "error": agents_result["error"],
+                "agent_name": agent_name
+            }
+
+        # Find the specific agent
+        agent = None
+        for a in agents_result.get("agents", []):
+            if a["name"].lower() == agent_name.lower():
+                agent = a
+                break
+
+        if not agent:
+            return {
+                "error": f"Agent '{agent_name}' not found in {claude_md_path}",
+                "agent_name": agent_name,
+                "available_agents": [a["name"] for a in agents_result.get("agents", [])]
+            }
+
+        issues = []
+        flow_steps = []
+
+        # Extract workflow steps
+        workflow_steps = agent.get("workflow_steps", [])
+        responsibilities = agent.get("responsibilities", [])
+
+        # Build flow from workflow steps or responsibilities
+        steps = workflow_steps if workflow_steps else responsibilities
+
+        for i, step in enumerate(steps):
+            flow_steps.append(f"Step {i+1}: {step}")
+
+        # Check for data flow patterns
+        tool_refs = agent.get("tool_refs", [])
+
+        # Known data flow patterns
+        # e.g., data-platform produces data_ref, viz-platform consumes it
+        known_producers = {
+            "read_csv": "data_ref",
+            "read_parquet": "data_ref",
+            "pg_query": "data_ref",
+            "filter": "data_ref",
+            "groupby": "data_ref",
+        }
+
+        known_consumers = {
+            "describe": "data_ref",
+            "head": "data_ref",
+            "tail": "data_ref",
+            "to_csv": "data_ref",
+            "to_parquet": "data_ref",
+        }
+
+        # Check if agent uses tools that require data_ref
+        has_producer = any(t in known_producers for t in tool_refs)
+        has_consumer = any(t in known_consumers for t in tool_refs)
+
+        if has_consumer and not has_producer:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.WARNING,
+                issue_type=IssueType.INTERFACE_MISMATCH,
+                message=f"Agent '{agent_name}' uses tools that consume data_ref but no producer found",
+                location=claude_md_path,
+                suggestion="Ensure a data loading tool (read_csv, pg_query, etc.) is used before data consumers"
+            ))
+
+        # Check for empty workflow
+        if not steps and not tool_refs:
+            issues.append(ValidationIssue(
+                severity=IssueSeverity.INFO,
+                issue_type=IssueType.UNDECLARED_OUTPUT,
+                message=f"Agent '{agent_name}' has no documented workflow or tool sequence",
+                location=claude_md_path,
+                suggestion="Consider documenting the agent's workflow steps"
+            ))
+
+        result = DataFlowResult(
+            agent_name=agent_name,
+            valid=len([i for i in issues if i.severity == IssueSeverity.ERROR]) == 0,
+            flow_steps=flow_steps,
+            issues=issues
+        )
+
+        return result.model_dump()

mcp-servers/contract-validator/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contract-validator-mcp"
+version = "1.0.0"
+description = "MCP Server for cross-plugin compatibility validation and agent verification"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Leo Miranda"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=0.9.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp-servers/contract-validator/requirements.txt

@@ -0,0 +1,9 @@
+# MCP SDK
+mcp>=0.9.0
+
+# Utilities
+pydantic>=2.5.0
+
+# Testing
+pytest>=7.4.3
+pytest-asyncio>=0.23.0

mcp-servers/contract-validator/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/contract-validator/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/contract-validator/tests/__init__.py

@@ -0,0 +1 @@
+# Tests for contract-validator MCP server

mcp-servers/contract-validator/tests/test_parse_tools.py

@@ -0,0 +1,193 @@
+"""
+Unit tests for parse tools.
+"""
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def parse_tools():
+    """Create ParseTools instance"""
+    from mcp_server.parse_tools import ParseTools
+    return ParseTools()
+
+
+@pytest.fixture
+def sample_readme(tmp_path):
+    """Create a sample README.md for testing"""
+    readme = tmp_path / "README.md"
+    readme.write_text("""# Test Plugin
+
+A test plugin for validation.
+
+## Features
+
+- **Feature One**: Does something
+- **Feature Two**: Does something else
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/test-cmd` | Test command |
+| `/another-cmd` | Another test command |
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `test-agent` | A test agent |
+
+## Tools Summary
+
+### Category A (3 tools)
+`tool_a`, `tool_b`, `tool_c`
+
+### Category B (2 tools)
+`tool_d`, `tool_e`
+""")
+    return str(tmp_path)
+
+
+@pytest.fixture
+def sample_claude_md(tmp_path):
+    """Create a sample CLAUDE.md for testing"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+## Project Overview
+
+### Four-Agent Model (test)
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **Planner** | Thoughtful | Planning via `create_issue`, `search_lessons` |
+| **Executor** | Focused | Implementation via `write`, `edit` |
+
+## Workflow
+
+1. Planner creates issues
+2. Executor implements code
+""")
+    return str(claude_md)
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_basic(parse_tools, sample_readme):
+    """Test basic plugin interface parsing"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    assert "error" not in result
+    # Plugin name extraction strips "Plugin" suffix
+    assert result["plugin_name"] == "Test"
+    assert "A test plugin" in result["description"]
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_commands(parse_tools, sample_readme):
+    """Test command extraction from README"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    commands = result["commands"]
+    assert len(commands) == 2
+    assert commands[0]["name"] == "/test-cmd"
+    assert commands[1]["name"] == "/another-cmd"
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_agents(parse_tools, sample_readme):
+    """Test agent extraction from README"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    agents = result["agents"]
+    assert len(agents) == 1
+    assert agents[0]["name"] == "test-agent"
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_tools(parse_tools, sample_readme):
+    """Test tool extraction from README"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    tools = result["tools"]
+    tool_names = [t["name"] for t in tools]
+    assert "tool_a" in tool_names
+    assert "tool_b" in tool_names
+    assert "tool_e" in tool_names
+    assert len(tools) >= 5
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_categories(parse_tools, sample_readme):
+    """Test tool category extraction"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    categories = result["tool_categories"]
+    assert "Category A" in categories
+    assert "Category B" in categories
+    assert "tool_a" in categories["Category A"]
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_features(parse_tools, sample_readme):
+    """Test feature extraction"""
+    result = await parse_tools.parse_plugin_interface(sample_readme)
+
+    features = result["features"]
+    assert "Feature One" in features
+    assert "Feature Two" in features
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_interface_not_found(parse_tools, tmp_path):
+    """Test error when README not found"""
+    result = await parse_tools.parse_plugin_interface(str(tmp_path / "nonexistent"))
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_parse_claude_md_agents(parse_tools, sample_claude_md):
+    """Test agent extraction from CLAUDE.md"""
+    result = await parse_tools.parse_claude_md_agents(sample_claude_md)
+
+    assert "error" not in result
+    assert result["agent_count"] == 2
+
+    agents = result["agents"]
+    agent_names = [a["name"] for a in agents]
+    assert "Planner" in agent_names
+    assert "Executor" in agent_names
+
+
+@pytest.mark.asyncio
+async def test_parse_claude_md_tool_refs(parse_tools, sample_claude_md):
+    """Test tool reference extraction from agents"""
+    result = await parse_tools.parse_claude_md_agents(sample_claude_md)
+
+    agents = {a["name"]: a for a in result["agents"]}
+    planner = agents["Planner"]
+
+    assert "create_issue" in planner["tool_refs"]
+    assert "search_lessons" in planner["tool_refs"]
+
+
+@pytest.mark.asyncio
+async def test_parse_claude_md_not_found(parse_tools, tmp_path):
+    """Test error when CLAUDE.md not found"""
+    result = await parse_tools.parse_claude_md_agents(str(tmp_path / "CLAUDE.md"))
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_parse_plugin_with_direct_file(parse_tools, sample_readme):
+    """Test parsing with direct file path instead of directory"""
+    readme_path = Path(sample_readme) / "README.md"
+    result = await parse_tools.parse_plugin_interface(str(readme_path))
+
+    assert "error" not in result
+    # Plugin name extraction strips "Plugin" suffix
+    assert result["plugin_name"] == "Test"

mcp-servers/contract-validator/tests/test_report_tools.py

@@ -0,0 +1,261 @@
+"""
+Unit tests for report tools.
+"""
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def report_tools():
+    """Create ReportTools instance"""
+    from mcp_server.report_tools import ReportTools
+    return ReportTools()
+
+
+@pytest.fixture
+def sample_marketplace(tmp_path):
+    """Create a sample marketplace structure"""
+    import json
+
+    plugins_dir = tmp_path / "plugins"
+    plugins_dir.mkdir()
+
+    # Plugin 1
+    plugin1 = plugins_dir / "plugin-one"
+    plugin1.mkdir()
+    plugin1_meta = plugin1 / ".claude-plugin"
+    plugin1_meta.mkdir()
+    (plugin1_meta / "plugin.json").write_text(json.dumps({"name": "plugin-one"}))
+    (plugin1 / "README.md").write_text("""# plugin-one
+
+First test plugin.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmd-one` | Command one |
+
+## Tools Summary
+
+### Tools (2 tools)
+`tool_a`, `tool_b`
+""")
+
+    # Plugin 2
+    plugin2 = plugins_dir / "plugin-two"
+    plugin2.mkdir()
+    plugin2_meta = plugin2 / ".claude-plugin"
+    plugin2_meta.mkdir()
+    (plugin2_meta / "plugin.json").write_text(json.dumps({"name": "plugin-two"}))
+    (plugin2 / "README.md").write_text("""# plugin-two
+
+Second test plugin.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmd-two` | Command two |
+
+## Tools Summary
+
+### Tools (2 tools)
+`tool_c`, `tool_d`
+""")
+
+    # Plugin 3 (with conflict)
+    plugin3 = plugins_dir / "plugin-three"
+    plugin3.mkdir()
+    plugin3_meta = plugin3 / ".claude-plugin"
+    plugin3_meta.mkdir()
+    (plugin3_meta / "plugin.json").write_text(json.dumps({"name": "plugin-three"}))
+    (plugin3 / "README.md").write_text("""# plugin-three
+
+Third test plugin with conflict.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/cmd-one` | Conflicting command |
+
+## Tools Summary
+
+### Tools (1 tool)
+`tool_e`
+""")
+
+    return str(tmp_path)
+
+
+@pytest.fixture
+def marketplace_no_plugins(tmp_path):
+    """Create marketplace with no plugins"""
+    plugins_dir = tmp_path / "plugins"
+    plugins_dir.mkdir()
+    return str(tmp_path)
+
+
+@pytest.fixture
+def marketplace_no_dir(tmp_path):
+    """Create path without plugins directory"""
+    return str(tmp_path)
+
+
+@pytest.mark.asyncio
+async def test_generate_report_json_format(report_tools, sample_marketplace):
+    """Test JSON format report generation"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    assert "error" not in result
+    assert "generated_at" in result
+    assert "summary" in result
+    assert "plugins" in result
+    assert result["summary"]["total_plugins"] == 3
+
+
+@pytest.mark.asyncio
+async def test_generate_report_markdown_format(report_tools, sample_marketplace):
+    """Test markdown format report generation"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "markdown"
+    )
+
+    assert "error" not in result
+    assert "report" in result
+    assert "# Contract Validation Report" in result["report"]
+    assert "## Summary" in result["report"]
+
+
+@pytest.mark.asyncio
+async def test_generate_report_finds_conflicts(report_tools, sample_marketplace):
+    """Test that report finds command conflicts"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    assert "error" not in result
+    assert result["summary"]["errors"] > 0
+    assert result["summary"]["total_issues"] > 0
+
+
+@pytest.mark.asyncio
+async def test_generate_report_counts_correctly(report_tools, sample_marketplace):
+    """Test summary counts are correct"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    summary = result["summary"]
+    assert summary["total_plugins"] == 3
+    assert summary["total_commands"] == 3  # 3 commands total
+    assert summary["total_tools"] == 5  # a, b, c, d, e
+
+
+@pytest.mark.asyncio
+async def test_generate_report_no_plugins(report_tools, marketplace_no_plugins):
+    """Test error when no plugins found"""
+    result = await report_tools.generate_compatibility_report(
+        marketplace_no_plugins, "json"
+    )
+
+    assert "error" in result
+    assert "no plugins" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_generate_report_no_plugins_dir(report_tools, marketplace_no_dir):
+    """Test error when plugins directory doesn't exist"""
+    result = await report_tools.generate_compatibility_report(
+        marketplace_no_dir, "json"
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_list_issues_all(report_tools, sample_marketplace):
+    """Test listing all issues"""
+    result = await report_tools.list_issues(sample_marketplace, "all", "all")
+
+    assert "error" not in result
+    assert "issues" in result
+    assert result["total_issues"] > 0
+
+
+@pytest.mark.asyncio
+async def test_list_issues_filter_by_severity(report_tools, sample_marketplace):
+    """Test filtering issues by severity"""
+    all_result = await report_tools.list_issues(sample_marketplace, "all", "all")
+    error_result = await report_tools.list_issues(sample_marketplace, "error", "all")
+
+    # Error count should be less than or equal to all
+    assert error_result["total_issues"] <= all_result["total_issues"]
+
+    # All issues should have error severity
+    for issue in error_result["issues"]:
+        sev = issue.get("severity", "")
+        if hasattr(sev, 'value'):
+            sev = sev.value
+        assert "error" in str(sev).lower()
+
+
+@pytest.mark.asyncio
+async def test_list_issues_filter_by_type(report_tools, sample_marketplace):
+    """Test filtering issues by type"""
+    result = await report_tools.list_issues(
+        sample_marketplace, "all", "interface_mismatch"
+    )
+
+    # All issues should have matching type
+    for issue in result["issues"]:
+        itype = issue.get("issue_type", "")
+        if hasattr(itype, 'value'):
+            itype = itype.value
+        assert "interface_mismatch" in str(itype).lower()
+
+
+@pytest.mark.asyncio
+async def test_list_issues_combined_filters(report_tools, sample_marketplace):
+    """Test combined severity and type filters"""
+    result = await report_tools.list_issues(
+        sample_marketplace, "error", "interface_mismatch"
+    )
+
+    assert "error" not in result
+    # Should have command conflict errors
+    assert result["total_issues"] > 0
+
+
+@pytest.mark.asyncio
+async def test_report_markdown_has_all_sections(report_tools, sample_marketplace):
+    """Test markdown report contains all expected sections"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "markdown"
+    )
+
+    report = result["report"]
+    assert "## Summary" in report
+    assert "## Plugins" in report
+    # Compatibility section only if there are checks
+    assert "Plugin One" in report or "plugin-one" in report.lower()
+
+
+@pytest.mark.asyncio
+async def test_report_includes_suggestions(report_tools, sample_marketplace):
+    """Test that issues include suggestions"""
+    result = await report_tools.generate_compatibility_report(
+        sample_marketplace, "json"
+    )
+
+    issues = result.get("all_issues", [])
+    # Find an issue with a suggestion
+    issues_with_suggestions = [
+        i for i in issues
+        if i.get("suggestion")
+    ]
+    assert len(issues_with_suggestions) > 0

mcp-servers/contract-validator/tests/test_validation_tools.py

@@ -0,0 +1,256 @@
+"""
+Unit tests for validation tools.
+"""
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def validation_tools():
+    """Create ValidationTools instance"""
+    from mcp_server.validation_tools import ValidationTools
+    return ValidationTools()
+
+
+@pytest.fixture
+def plugin_a(tmp_path):
+    """Create first test plugin"""
+    plugin_dir = tmp_path / "plugin-a"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("""# Plugin A
+
+Test plugin A.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/setup-a` | Setup A |
+| `/shared-cmd` | Shared command |
+
+## Tools Summary
+
+### Core (2 tools)
+`tool_one`, `tool_two`
+""")
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def plugin_b(tmp_path):
+    """Create second test plugin"""
+    plugin_dir = tmp_path / "plugin-b"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("""# Plugin B
+
+Test plugin B.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/setup-b` | Setup B |
+| `/shared-cmd` | Shared command (conflict!) |
+
+## Tools Summary
+
+### Core (2 tools)
+`tool_two`, `tool_three`
+""")
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def plugin_no_conflict(tmp_path):
+    """Create plugin with no conflicts"""
+    plugin_dir = tmp_path / "plugin-c"
+    plugin_dir.mkdir()
+    (plugin_dir / ".claude-plugin").mkdir()
+
+    readme = plugin_dir / "README.md"
+    readme.write_text("""# Plugin C
+
+Test plugin C.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unique-cmd` | Unique command |
+
+## Tools Summary
+
+### Core (1 tool)
+`unique_tool`
+""")
+    return str(plugin_dir)
+
+
+@pytest.fixture
+def claude_md_with_agents(tmp_path):
+    """Create CLAUDE.md with agent definitions"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **TestAgent** | Careful | Uses `tool_one`, `tool_two`, `missing_tool` |
+| **ValidAgent** | Thorough | Uses `tool_one` only |
+| **EmptyAgent** | Unknown | General tasks |
+""")
+    return str(claude_md)
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_command_conflict(validation_tools, plugin_a, plugin_b):
+    """Test detection of command name conflicts"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    assert "error" not in result
+    assert result["compatible"] is False
+
+    # Find the command conflict issue
+    error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
+    assert len(error_issues) > 0
+    assert any("/shared-cmd" in str(i["message"]) for i in error_issues)
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_tool_overlap(validation_tools, plugin_a, plugin_b):
+    """Test detection of tool name overlaps"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    assert "tool_two" in result["shared_tools"]
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_unique_tools(validation_tools, plugin_a, plugin_b):
+    """Test identification of unique tools per plugin"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_b)
+
+    assert "tool_one" in result["a_only_tools"]
+    assert "tool_three" in result["b_only_tools"]
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_no_conflict(validation_tools, plugin_a, plugin_no_conflict):
+    """Test compatible plugins"""
+    result = await validation_tools.validate_compatibility(plugin_a, plugin_no_conflict)
+
+    assert "error" not in result
+    assert result["compatible"] is True
+
+
+@pytest.mark.asyncio
+async def test_validate_compatibility_missing_plugin(validation_tools, plugin_a, tmp_path):
+    """Test error when plugin not found"""
+    result = await validation_tools.validate_compatibility(
+        plugin_a,
+        str(tmp_path / "nonexistent")
+    )
+
+    assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_with_missing_tools(validation_tools, claude_md_with_agents, plugin_a):
+    """Test detection of missing tool references"""
+    result = await validation_tools.validate_agent_refs(
+        "TestAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" not in result
+    assert result["valid"] is False
+    assert "missing_tool" in result["tool_refs_missing"]
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_valid_agent(validation_tools, claude_md_with_agents, plugin_a):
+    """Test valid agent with all tools found"""
+    result = await validation_tools.validate_agent_refs(
+        "ValidAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" not in result
+    assert result["valid"] is True
+    assert "tool_one" in result["tool_refs_found"]
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_empty_agent(validation_tools, claude_md_with_agents, plugin_a):
+    """Test agent with no tool references"""
+    result = await validation_tools.validate_agent_refs(
+        "EmptyAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" not in result
+    # Should have info issue about undocumented references
+    info_issues = [i for i in result["issues"] if i["severity"].value == "info"]
+    assert len(info_issues) > 0
+
+
+@pytest.mark.asyncio
+async def test_validate_agent_refs_agent_not_found(validation_tools, claude_md_with_agents, plugin_a):
+    """Test error when agent not found"""
+    result = await validation_tools.validate_agent_refs(
+        "NonexistentAgent",
+        claude_md_with_agents,
+        [plugin_a]
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_validate_data_flow_valid(validation_tools, tmp_path):
+    """Test data flow validation with valid flow"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **DataAgent** | Analytical | Load with `read_csv`, analyze with `describe`, export with `to_csv` |
+""")
+
+    result = await validation_tools.validate_data_flow("DataAgent", str(claude_md))
+
+    assert "error" not in result
+    assert result["valid"] is True
+
+
+@pytest.mark.asyncio
+async def test_validate_data_flow_missing_producer(validation_tools, tmp_path):
+    """Test data flow with consumer but no producer"""
+    claude_md = tmp_path / "CLAUDE.md"
+    claude_md.write_text("""# CLAUDE.md
+
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **BadAgent** | Careless | Just runs `describe`, `head`, `tail` without loading |
+""")
+
+    result = await validation_tools.validate_data_flow("BadAgent", str(claude_md))
+
+    assert "error" not in result
+    # Should have warning about missing producer
+    warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
+    assert len(warning_issues) > 0

mcp-servers/data-platform/mcp_server/pandas_tools.py

@@ -330,7 +330,7 @@ class PandasTools:
             return {'error': f'DataFrame not found: {data_ref}'}
 
         try:
-            filtered = df.query(condition)
+            filtered = df.query(condition).reset_index(drop=True)
             result_name = name or f"{data_ref}_filtered"
             return self._check_and_store(
                 filtered,

mcp-servers/data-platform/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/data-platform/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/gitea/mcp_server/gitea_client.py

@@ -239,8 +239,11 @@ class GiteaClient:
         repo: Optional[str] = None
     ) -> Dict:
         """Get a specific wiki page by name."""
+        from urllib.parse import quote
         owner, target_repo = self._parse_repo(repo)
-        url = f"{self.base_url}/repos/{owner}/{target_repo}/wiki/page/{page_name}"
+        # URL-encode the page_name to handle special characters like ':'
+        encoded_page_name = quote(page_name, safe='')
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/wiki/page/{encoded_page_name}"
         logger.info(f"Getting wiki page '{page_name}' from {owner}/{target_repo}")
         response = self.session.get(url)
         response.raise_for_status()
@@ -271,9 +274,13 @@ class GiteaClient:
         repo: Optional[str] = None
     ) -> Dict:
         """Update an existing wiki page."""
+        from urllib.parse import quote
         owner, target_repo = self._parse_repo(repo)
-        url = f"{self.base_url}/repos/{owner}/{target_repo}/wiki/page/{page_name}"
+        # URL-encode the page_name to handle special characters like ':'
+        encoded_page_name = quote(page_name, safe='')
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/wiki/page/{encoded_page_name}"
         data = {
+            'title': page_name,  # CRITICAL: include title to preserve page name
             'content_base64': self._encode_base64(content)
         }
         logger.info(f"Updating wiki page '{page_name}' in {owner}/{target_repo}")
@@ -287,8 +294,11 @@ class GiteaClient:
         repo: Optional[str] = None
     ) -> bool:
         """Delete a wiki page."""
+        from urllib.parse import quote
         owner, target_repo = self._parse_repo(repo)
-        url = f"{self.base_url}/repos/{owner}/{target_repo}/wiki/page/{page_name}"
+        # URL-encode the page_name to handle special characters like ':'
+        encoded_page_name = quote(page_name, safe='')
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/wiki/page/{encoded_page_name}"
         logger.info(f"Deleting wiki page '{page_name}' from {owner}/{target_repo}")
         response = self.session.delete(url)
         response.raise_for_status()
@@ -777,3 +787,42 @@ class GiteaClient:
         response = self.session.post(url, json=data)
         response.raise_for_status()
         return response.json()
+
+    def create_pull_request(
+        self,
+        title: str,
+        body: str,
+        head: str,
+        base: str,
+        labels: Optional[List[str]] = None,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """
+        Create a new pull request.
+
+        Args:
+            title: PR title
+            body: PR description/body
+            head: Source branch name (the branch with changes)
+            base: Target branch name (the branch to merge into)
+            labels: Optional list of label names
+            repo: Repository in 'owner/repo' format
+
+        Returns:
+            Created pull request dictionary
+        """
+        owner, target_repo = self._parse_repo(repo)
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/pulls"
+        data = {
+            'title': title,
+            'body': body,
+            'head': head,
+            'base': base
+        }
+        if labels:
+            label_ids = self._resolve_label_ids(labels, owner, target_repo)
+            data['labels'] = label_ids
+        logger.info(f"Creating PR '{title}' in {owner}/{target_repo}: {head} -> {base}")
+        response = self.session.post(url, json=data)
+        response.raise_for_status()
+        return response.json()

mcp-servers/gitea/mcp_server/server.py

@@ -844,6 +844,41 @@ class GiteaMCPServer:
                         },
                         "required": ["pr_number", "body"]
                     }
+                ),
+                Tool(
+                    name="create_pull_request",
+                    description="Create a new pull request",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "title": {
+                                "type": "string",
+                                "description": "PR title"
+                            },
+                            "body": {
+                                "type": "string",
+                                "description": "PR description/body"
+                            },
+                            "head": {
+                                "type": "string",
+                                "description": "Source branch name (the branch with changes)"
+                            },
+                            "base": {
+                                "type": "string",
+                                "description": "Target branch name (the branch to merge into)"
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Optional list of label names"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        },
+                        "required": ["title", "body", "head", "base"]
+                    }
                 )
             ]
 
@@ -959,6 +994,8 @@ class GiteaMCPServer:
                     result = await self.pr_tools.create_pr_review(**arguments)
                 elif name == "add_pr_comment":
                     result = await self.pr_tools.add_pr_comment(**arguments)
+                elif name == "create_pull_request":
+                    result = await self.pr_tools.create_pull_request(**arguments)
                 else:
                     raise ValueError(f"Unknown tool: {name}")
 

mcp-servers/gitea/mcp_server/tools/issues.py

@@ -7,6 +7,7 @@ Provides async wrappers for issue CRUD operations with:
 - Comprehensive error handling
 """
 import asyncio
+import os
 import subprocess
 import logging
 from typing import List, Dict, Optional
@@ -27,19 +28,34 @@ class IssueTools:
         """
         self.gitea = gitea_client
 
+    def _get_project_directory(self) -> Optional[str]:
+        """
+        Get the user's project directory from environment.
+
+        Returns:
+            Project directory path or None if not set
+        """
+        return os.environ.get('CLAUDE_PROJECT_DIR')
+
     def _get_current_branch(self) -> str:
         """
-        Get current git branch.
+        Get current git branch from user's project directory.
+
+        Uses CLAUDE_PROJECT_DIR environment variable to determine the correct
+        directory for git operations, avoiding the bug where git runs from
+        the installed plugin directory instead of the user's project.
 
         Returns:
             Current branch name or 'unknown' if not in a git repo
         """
         try:
+            project_dir = self._get_project_directory()
             result = subprocess.run(
                 ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
                 capture_output=True,
                 text=True,
-                check=True
+                check=True,
+                cwd=project_dir  # Run git in project directory, not plugin directory
             )
             return result.stdout.strip()
         except subprocess.CalledProcessError:
@@ -66,7 +82,13 @@ class IssueTools:
             return operation in ['list_issues', 'get_issue', 'get_labels', 'create_issue']
 
         # Development branches (full access)
-        if branch in ['development', 'develop'] or branch.startswith(('feat/', 'feature/', 'dev/')):
+        # Include all common feature/fix branch patterns
+        dev_prefixes = (
+            'feat/', 'feature/', 'dev/',
+            'fix/', 'bugfix/', 'hotfix/',
+            'chore/', 'refactor/', 'docs/', 'test/'
+        )
+        if branch in ['development', 'develop'] or branch.startswith(dev_prefixes):
             return True
 
         # Unknown branch - be restrictive

mcp-servers/gitea/mcp_server/tools/pull_requests.py

@@ -7,6 +7,7 @@ Provides async wrappers for PR operations with:
 - Comprehensive error handling
 """
 import asyncio
+import os
 import subprocess
 import logging
 from typing import List, Dict, Optional
@@ -27,19 +28,34 @@ class PullRequestTools:
         """
         self.gitea = gitea_client
 
+    def _get_project_directory(self) -> Optional[str]:
+        """
+        Get the user's project directory from environment.
+
+        Returns:
+            Project directory path or None if not set
+        """
+        return os.environ.get('CLAUDE_PROJECT_DIR')
+
     def _get_current_branch(self) -> str:
         """
-        Get current git branch.
+        Get current git branch from user's project directory.
+
+        Uses CLAUDE_PROJECT_DIR environment variable to determine the correct
+        directory for git operations, avoiding the bug where git runs from
+        the installed plugin directory instead of the user's project.
 
         Returns:
             Current branch name or 'unknown' if not in a git repo
         """
         try:
+            project_dir = self._get_project_directory()
             result = subprocess.run(
                 ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
                 capture_output=True,
                 text=True,
-                check=True
+                check=True,
+                cwd=project_dir  # Run git in project directory, not plugin directory
             )
             return result.stdout.strip()
         except subprocess.CalledProcessError:
@@ -69,7 +85,13 @@ class PullRequestTools:
             return operation in read_ops + ['add_pr_comment']
 
         # Development branches (full access)
-        if branch in ['development', 'develop'] or branch.startswith(('feat/', 'feature/', 'dev/')):
+        # Include all common feature/fix branch patterns
+        dev_prefixes = (
+            'feat/', 'feature/', 'dev/',
+            'fix/', 'bugfix/', 'hotfix/',
+            'chore/', 'refactor/', 'docs/', 'test/'
+        )
+        if branch in ['development', 'develop'] or branch.startswith(dev_prefixes):
             return True
 
         # Unknown branch - be restrictive
@@ -272,3 +294,42 @@ class PullRequestTools:
             None,
             lambda: self.gitea.add_pr_comment(pr_number, body, repo)
         )
+
+    async def create_pull_request(
+        self,
+        title: str,
+        body: str,
+        head: str,
+        base: str,
+        labels: Optional[List[str]] = None,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """
+        Create a new pull request (async wrapper with branch check).
+
+        Args:
+            title: PR title
+            body: PR description/body
+            head: Source branch name (the branch with changes)
+            base: Target branch name (the branch to merge into)
+            labels: Optional list of label names
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            Created pull request dictionary
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('create_pull_request'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot create PR on branch '{branch}'. "
+                f"Switch to a development or feature branch to create PRs."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.create_pull_request(title, body, head, base, labels, repo)
+        )

mcp-servers/gitea/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/gitea/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/netbox/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/netbox/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/viz-platform/README.md

@@ -0,0 +1,115 @@
+# viz-platform MCP Server
+
+Model Context Protocol (MCP) server for Dash Mantine Components validation and visualization tools.
+
+## Overview
+
+This MCP server provides 21 tools for:
+- **DMC Validation**: Version-locked component registry prevents Claude from hallucinating invalid props
+- **Chart Creation**: Plotly-based visualization with theme integration
+- **Layout Composition**: Dashboard layouts with responsive grids
+- **Theme Management**: Design token-based theming system
+- **Page Structure**: Multi-page Dash app generation
+
+## Tools
+
+### DMC Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List available DMC components by category |
+| `get_component_props` | Get valid props, types, and defaults for a component |
+| `validate_component` | Validate component definition before use |
+
+### Chart Tools (2)
+
+| Tool | Description |
+|------|-------------|
+| `chart_create` | Create Plotly chart (line, bar, scatter, pie, histogram, area, heatmap) |
+| `chart_configure_interaction` | Configure chart interactions (zoom, pan, hover) |
+
+### Layout Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `layout_create` | Create dashboard layout structure |
+| `layout_add_filter` | Add filter components to layout |
+| `layout_set_grid` | Configure responsive grid settings |
+| `layout_get` | Retrieve layout configuration |
+| `layout_add_section` | Add sections to layout |
+
+### Theme Tools (6)
+
+| Tool | Description |
+|------|-------------|
+| `theme_create` | Create new theme with design tokens |
+| `theme_extend` | Extend existing theme with overrides |
+| `theme_validate` | Validate theme completeness |
+| `theme_export_css` | Export theme as CSS custom properties |
+| `theme_list` | List available themes |
+| `theme_activate` | Set active theme for visualizations |
+
+### Page Tools (5)
+
+| Tool | Description |
+|------|-------------|
+| `page_create` | Create new page structure |
+| `page_add_navbar` | Add navigation bar to page |
+| `page_set_auth` | Configure page authentication |
+| `page_list` | List available pages |
+| `page_get_app_config` | Get full app configuration |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DMC_VERSION` | No | Dash Mantine Components version (auto-detected if installed) |
+| `VIZ_DEFAULT_THEME` | No | Default theme name |
+| `CLAUDE_PROJECT_DIR` | No | Project directory for theme storage |
+
+### Theme Storage
+
+Themes can be stored at two levels:
+- **User-level**: `~/.config/claude/themes/`
+- **Project-level**: `{project}/.viz-platform/themes/`
+
+Project-level themes take precedence.
+
+## Component Registry
+
+The server uses a static JSON registry for DMC component validation:
+- Pre-generated from DMC source code
+- Version-tagged (e.g., `dmc_2_5.json`)
+- Prevents hallucination of non-existent props
+- Fast, deterministic validation
+
+Registry files are stored in `registry/` directory.
+
+## Tests
+
+94 tests with coverage:
+- `test_config.py`: 82% coverage
+- `test_component_registry.py`: 92% coverage
+- `test_dmc_tools.py`: 88% coverage
+- `test_chart_tools.py`: 68% coverage
+- `test_theme_tools.py`: 99% coverage
+
+Run tests:
+```bash
+cd mcp-servers/viz-platform
+source .venv/bin/activate
+pytest tests/ -v
+```
+
+## Dependencies
+
+- Python 3.10+
+- FastMCP
+- plotly
+- dash-mantine-components (optional, for version detection)
+
+## Usage
+
+This MCP server is used by the `viz-platform` plugin. See [plugins/viz-platform/README.md](../../plugins/viz-platform/README.md) for usage instructions.

mcp-servers/viz-platform/mcp_server/__init__.py

@@ -0,0 +1,7 @@
+"""
+viz-platform MCP Server package.
+
+Provides Dash Mantine Components validation and visualization tools to Claude Code.
+"""
+
+__version__ = "1.0.0"

mcp-servers/viz-platform/mcp_server/chart_tools.py

@@ -0,0 +1,397 @@
+"""
+Chart creation tools using Plotly.
+
+Provides tools for creating data visualizations with automatic theme integration.
+"""
+import logging
+from typing import Dict, List, Optional, Any, Union
+
+logger = logging.getLogger(__name__)
+
+
+# Default color palette based on Mantine theme
+DEFAULT_COLORS = [
+    "#228be6",  # blue
+    "#40c057",  # green
+    "#fa5252",  # red
+    "#fab005",  # yellow
+    "#7950f2",  # violet
+    "#fd7e14",  # orange
+    "#20c997",  # teal
+    "#f783ac",  # pink
+    "#868e96",  # gray
+    "#15aabf",  # cyan
+]
+
+
+class ChartTools:
+    """
+    Plotly-based chart creation tools.
+
+    Creates charts that integrate with DMC theming system.
+    """
+
+    def __init__(self, theme_store=None):
+        """
+        Initialize chart tools.
+
+        Args:
+            theme_store: Optional ThemeStore for theme token resolution
+        """
+        self.theme_store = theme_store
+        self._active_theme = None
+
+    def set_theme(self, theme: Dict[str, Any]) -> None:
+        """Set the active theme for chart styling."""
+        self._active_theme = theme
+
+    def _get_color_palette(self) -> List[str]:
+        """Get color palette from theme or defaults."""
+        if self._active_theme and 'colors' in self._active_theme:
+            colors = self._active_theme['colors']
+            # Extract primary colors from theme
+            palette = []
+            for key in ['primary', 'secondary', 'success', 'warning', 'error']:
+                if key in colors:
+                    palette.append(colors[key])
+            if palette:
+                return palette + DEFAULT_COLORS[len(palette):]
+        return DEFAULT_COLORS
+
+    def _resolve_color(self, color: Optional[str]) -> str:
+        """Resolve a color token to actual color value."""
+        if not color:
+            return self._get_color_palette()[0]
+
+        # Check if it's a theme token
+        if self._active_theme and 'colors' in self._active_theme:
+            colors = self._active_theme['colors']
+            if color in colors:
+                return colors[color]
+
+        # Check if it's already a valid color
+        if color.startswith('#') or color.startswith('rgb'):
+            return color
+
+        # Map common color names to palette
+        color_map = {
+            'blue': DEFAULT_COLORS[0],
+            'green': DEFAULT_COLORS[1],
+            'red': DEFAULT_COLORS[2],
+            'yellow': DEFAULT_COLORS[3],
+            'violet': DEFAULT_COLORS[4],
+            'orange': DEFAULT_COLORS[5],
+            'teal': DEFAULT_COLORS[6],
+            'pink': DEFAULT_COLORS[7],
+            'gray': DEFAULT_COLORS[8],
+            'cyan': DEFAULT_COLORS[9],
+        }
+        return color_map.get(color, color)
+
+    async def chart_create(
+        self,
+        chart_type: str,
+        data: Dict[str, Any],
+        options: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a Plotly chart.
+
+        Args:
+            chart_type: Type of chart (line, bar, scatter, pie, heatmap, histogram, area)
+            data: Data specification with x, y values or labels/values for pie
+            options: Optional chart options (title, color, layout settings)
+
+        Returns:
+            Dict with:
+                - figure: Plotly figure JSON
+                - chart_type: Type of chart created
+                - error: Error message if creation failed
+        """
+        options = options or {}
+
+        # Validate chart type
+        valid_types = ['line', 'bar', 'scatter', 'pie', 'heatmap', 'histogram', 'area']
+        if chart_type not in valid_types:
+            return {
+                "error": f"Invalid chart_type '{chart_type}'. Must be one of: {valid_types}",
+                "chart_type": chart_type,
+                "figure": None
+            }
+
+        try:
+            # Build trace based on chart type
+            trace = self._build_trace(chart_type, data, options)
+            if 'error' in trace:
+                return trace
+
+            # Build layout
+            layout = self._build_layout(options)
+
+            # Create figure structure
+            figure = {
+                "data": [trace],
+                "layout": layout
+            }
+
+            return {
+                "figure": figure,
+                "chart_type": chart_type,
+                "trace_count": 1
+            }
+
+        except Exception as e:
+            logger.error(f"Chart creation failed: {e}")
+            return {
+                "error": str(e),
+                "chart_type": chart_type,
+                "figure": None
+            }
+
+    def _build_trace(
+        self,
+        chart_type: str,
+        data: Dict[str, Any],
+        options: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Build Plotly trace for the chart type."""
+        color = self._resolve_color(options.get('color'))
+        palette = self._get_color_palette()
+
+        # Common trace properties
+        trace: Dict[str, Any] = {}
+
+        if chart_type == 'line':
+            trace = {
+                "type": "scatter",
+                "mode": "lines+markers",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "line": {"color": color},
+                "marker": {"color": color}
+            }
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        elif chart_type == 'bar':
+            trace = {
+                "type": "bar",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "marker": {"color": color}
+            }
+            if options.get('horizontal'):
+                trace['orientation'] = 'h'
+                trace['x'], trace['y'] = trace['y'], trace['x']
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        elif chart_type == 'scatter':
+            trace = {
+                "type": "scatter",
+                "mode": "markers",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "marker": {
+                    "color": color,
+                    "size": options.get('marker_size', 10)
+                }
+            }
+            if 'size' in data:
+                trace['marker']['size'] = data['size']
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        elif chart_type == 'pie':
+            labels = data.get('labels', data.get('x', []))
+            values = data.get('values', data.get('y', []))
+            trace = {
+                "type": "pie",
+                "labels": labels,
+                "values": values,
+                "marker": {"colors": palette[:len(labels)]}
+            }
+            if options.get('donut'):
+                trace['hole'] = options.get('hole', 0.4)
+
+        elif chart_type == 'heatmap':
+            trace = {
+                "type": "heatmap",
+                "z": data.get('z', data.get('values', [])),
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "colorscale": options.get('colorscale', 'Blues')
+            }
+
+        elif chart_type == 'histogram':
+            trace = {
+                "type": "histogram",
+                "x": data.get('x', data.get('values', [])),
+                "marker": {"color": color}
+            }
+            if 'nbins' in options:
+                trace['nbinsx'] = options['nbins']
+
+        elif chart_type == 'area':
+            trace = {
+                "type": "scatter",
+                "mode": "lines",
+                "x": data.get('x', []),
+                "y": data.get('y', []),
+                "fill": "tozeroy",
+                "line": {"color": color},
+                "fillcolor": color.replace(')', ', 0.3)').replace('rgb', 'rgba') if color.startswith('rgb') else color + '4D'
+            }
+            if 'name' in data:
+                trace['name'] = data['name']
+
+        else:
+            return {"error": f"Unsupported chart type: {chart_type}"}
+
+        return trace
+
+    def _build_layout(self, options: Dict[str, Any]) -> Dict[str, Any]:
+        """Build Plotly layout from options."""
+        layout: Dict[str, Any] = {
+            "autosize": True,
+            "margin": {"l": 50, "r": 30, "t": 50, "b": 50}
+        }
+
+        # Title
+        if 'title' in options:
+            layout['title'] = {
+                "text": options['title'],
+                "x": 0.5,
+                "xanchor": "center"
+            }
+
+        # Axis labels
+        if 'x_label' in options:
+            layout['xaxis'] = layout.get('xaxis', {})
+            layout['xaxis']['title'] = options['x_label']
+
+        if 'y_label' in options:
+            layout['yaxis'] = layout.get('yaxis', {})
+            layout['yaxis']['title'] = options['y_label']
+
+        # Theme-based styling
+        if self._active_theme:
+            colors = self._active_theme.get('colors', {})
+            bg = colors.get('background', {})
+
+            if isinstance(bg, dict):
+                layout['paper_bgcolor'] = bg.get('base', '#ffffff')
+                layout['plot_bgcolor'] = bg.get('subtle', '#f8f9fa')
+            elif isinstance(bg, str):
+                layout['paper_bgcolor'] = bg
+                layout['plot_bgcolor'] = bg
+
+            text_color = colors.get('text', {})
+            if isinstance(text_color, dict):
+                layout['font'] = {'color': text_color.get('primary', '#212529')}
+            elif isinstance(text_color, str):
+                layout['font'] = {'color': text_color}
+
+        # Additional layout options
+        if 'showlegend' in options:
+            layout['showlegend'] = options['showlegend']
+
+        if 'height' in options:
+            layout['height'] = options['height']
+
+        if 'width' in options:
+            layout['width'] = options['width']
+
+        return layout
+
+    async def chart_configure_interaction(
+        self,
+        figure: Dict[str, Any],
+        interactions: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Configure interactions for a chart.
+
+        Args:
+            figure: Plotly figure JSON to modify
+            interactions: Interaction configuration:
+                - hover_template: Custom hover text template
+                - click_data: Enable click data capture
+                - selection: Enable selection (box, lasso)
+                - zoom: Enable/disable zoom
+
+        Returns:
+            Dict with:
+                - figure: Updated figure JSON
+                - interactions_added: List of interactions configured
+                - error: Error message if configuration failed
+        """
+        if not figure or 'data' not in figure:
+            return {
+                "error": "Invalid figure: must contain 'data' key",
+                "figure": figure,
+                "interactions_added": []
+            }
+
+        try:
+            interactions_added = []
+
+            # Process each trace
+            for i, trace in enumerate(figure['data']):
+                # Hover template
+                if 'hover_template' in interactions:
+                    trace['hovertemplate'] = interactions['hover_template']
+                    if i == 0:
+                        interactions_added.append('hover_template')
+
+                # Custom hover info
+                if 'hover_info' in interactions:
+                    trace['hoverinfo'] = interactions['hover_info']
+                    if i == 0:
+                        interactions_added.append('hover_info')
+
+            # Layout-level interactions
+            layout = figure.get('layout', {})
+
+            # Click data (Dash callback integration)
+            if interactions.get('click_data', False):
+                layout['clickmode'] = 'event+select'
+                interactions_added.append('click_data')
+
+            # Selection mode
+            if 'selection' in interactions:
+                sel_mode = interactions['selection']
+                if sel_mode in ['box', 'lasso', 'box+lasso']:
+                    layout['dragmode'] = 'select' if sel_mode == 'box' else sel_mode
+                    interactions_added.append(f'selection:{sel_mode}')
+
+            # Zoom configuration
+            if 'zoom' in interactions:
+                if not interactions['zoom']:
+                    layout['xaxis'] = layout.get('xaxis', {})
+                    layout['yaxis'] = layout.get('yaxis', {})
+                    layout['xaxis']['fixedrange'] = True
+                    layout['yaxis']['fixedrange'] = True
+                    interactions_added.append('zoom:disabled')
+                else:
+                    interactions_added.append('zoom:enabled')
+
+            # Modebar configuration
+            if 'modebar' in interactions:
+                layout['modebar'] = interactions['modebar']
+                interactions_added.append('modebar')
+
+            figure['layout'] = layout
+
+            return {
+                "figure": figure,
+                "interactions_added": interactions_added
+            }
+
+        except Exception as e:
+            logger.error(f"Interaction configuration failed: {e}")
+            return {
+                "error": str(e),
+                "figure": figure,
+                "interactions_added": []
+            }

mcp-servers/viz-platform/mcp_server/component_registry.py

@@ -0,0 +1,301 @@
+"""
+DMC Component Registry for viz-platform.
+
+Provides version-locked component definitions to prevent Claude from
+hallucinating invalid props. Uses static JSON registries pre-generated
+from DMC source.
+"""
+import json
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+
+class ComponentRegistry:
+    """
+    Version-locked registry of Dash Mantine Components.
+
+    Loads component definitions from static JSON files and provides
+    lookup methods for validation tools.
+    """
+
+    def __init__(self, dmc_version: Optional[str] = None):
+        """
+        Initialize the component registry.
+
+        Args:
+            dmc_version: Installed DMC version (e.g., "0.14.7").
+                        If None, will try to detect or use fallback.
+        """
+        self.dmc_version = dmc_version
+        self.registry_dir = Path(__file__).parent.parent / 'registry'
+        self.components: Dict[str, Dict[str, Any]] = {}
+        self.categories: Dict[str, List[str]] = {}
+        self.loaded_version: Optional[str] = None
+
+    def load(self) -> bool:
+        """
+        Load the component registry for the configured DMC version.
+
+        Returns:
+            True if registry loaded successfully, False otherwise
+        """
+        registry_file = self._find_registry_file()
+
+        if not registry_file:
+            logger.warning(
+                f"No registry found for DMC {self.dmc_version}. "
+                "Component validation will be limited."
+            )
+            return False
+
+        try:
+            with open(registry_file, 'r') as f:
+                data = json.load(f)
+
+            self.loaded_version = data.get('version')
+            self.components = data.get('components', {})
+            self.categories = data.get('categories', {})
+
+            logger.info(
+                f"Loaded component registry v{self.loaded_version} "
+                f"with {len(self.components)} components"
+            )
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to load registry: {e}")
+            return False
+
+    def _find_registry_file(self) -> Optional[Path]:
+        """
+        Find the best matching registry file for the DMC version.
+
+        Strategy:
+        1. Exact major.minor match (e.g., dmc_0_14.json for 0.14.7)
+        2. Fallback to latest available registry
+
+        Returns:
+            Path to registry file, or None if not found
+        """
+        if not self.registry_dir.exists():
+            logger.warning(f"Registry directory not found: {self.registry_dir}")
+            return None
+
+        # Try exact major.minor match
+        if self.dmc_version:
+            parts = self.dmc_version.split('.')
+            if len(parts) >= 2:
+                major_minor = f"{parts[0]}_{parts[1]}"
+                exact_match = self.registry_dir / f"dmc_{major_minor}.json"
+                if exact_match.exists():
+                    return exact_match
+
+        # Fallback: find latest registry
+        registry_files = list(self.registry_dir.glob("dmc_*.json"))
+        if registry_files:
+            # Sort by version and return latest
+            registry_files.sort(reverse=True)
+            fallback = registry_files[0]
+            if self.dmc_version:
+                logger.warning(
+                    f"No exact match for DMC {self.dmc_version}, "
+                    f"using fallback: {fallback.name}"
+                )
+            return fallback
+
+        return None
+
+    def get_component(self, name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get component definition by name.
+
+        Args:
+            name: Component name (e.g., "Button", "TextInput")
+
+        Returns:
+            Component definition dict, or None if not found
+        """
+        return self.components.get(name)
+
+    def get_component_props(self, name: str) -> Optional[Dict[str, Any]]:
+        """
+        Get props schema for a component.
+
+        Args:
+            name: Component name
+
+        Returns:
+            Props dict with type info, or None if component not found
+        """
+        component = self.get_component(name)
+        if component:
+            return component.get('props', {})
+        return None
+
+    def list_components(self, category: Optional[str] = None) -> Dict[str, List[str]]:
+        """
+        List available components, optionally filtered by category.
+
+        Args:
+            category: Optional category filter (e.g., "inputs", "buttons")
+
+        Returns:
+            Dict of category -> component names
+        """
+        if category:
+            if category in self.categories:
+                return {category: self.categories[category]}
+            return {}
+        return self.categories
+
+    def get_categories(self) -> List[str]:
+        """
+        Get list of available component categories.
+
+        Returns:
+            List of category names
+        """
+        return list(self.categories.keys())
+
+    def validate_prop(
+        self,
+        component: str,
+        prop_name: str,
+        prop_value: Any
+    ) -> Dict[str, Any]:
+        """
+        Validate a single prop value against the registry.
+
+        Args:
+            component: Component name
+            prop_name: Prop name
+            prop_value: Value to validate
+
+        Returns:
+            Dict with valid: bool, error: Optional[str]
+        """
+        props = self.get_component_props(component)
+        if props is None:
+            return {
+                'valid': False,
+                'error': f"Unknown component: {component}"
+            }
+
+        if prop_name not in props:
+            # Check for similar prop names (typo detection)
+            similar = self._find_similar_props(prop_name, props.keys())
+            if similar:
+                return {
+                    'valid': False,
+                    'error': f"Unknown prop '{prop_name}' for {component}. Did you mean '{similar}'?"
+                }
+            return {
+                'valid': False,
+                'error': f"Unknown prop '{prop_name}' for {component}"
+            }
+
+        prop_schema = props[prop_name]
+        return self._validate_value(prop_value, prop_schema, prop_name)
+
+    def _validate_value(
+        self,
+        value: Any,
+        schema: Dict[str, Any],
+        prop_name: str
+    ) -> Dict[str, Any]:
+        """
+        Validate a value against a prop schema.
+
+        Args:
+            value: Value to validate
+            schema: Prop schema from registry
+            prop_name: Prop name (for error messages)
+
+        Returns:
+            Dict with valid: bool, error: Optional[str]
+        """
+        prop_type = schema.get('type', 'any')
+
+        # Any type always valid
+        if prop_type == 'any':
+            return {'valid': True}
+
+        # Check enum values
+        if 'enum' in schema:
+            if value not in schema['enum']:
+                return {
+                    'valid': False,
+                    'error': f"Prop '{prop_name}' expects one of {schema['enum']}, got '{value}'"
+                }
+            return {'valid': True}
+
+        # Type checking
+        type_checks = {
+            'string': lambda v: isinstance(v, str),
+            'number': lambda v: isinstance(v, (int, float)),
+            'integer': lambda v: isinstance(v, int),
+            'boolean': lambda v: isinstance(v, bool),
+            'array': lambda v: isinstance(v, list),
+            'object': lambda v: isinstance(v, dict),
+        }
+
+        checker = type_checks.get(prop_type)
+        if checker and not checker(value):
+            return {
+                'valid': False,
+                'error': f"Prop '{prop_name}' expects type '{prop_type}', got '{type(value).__name__}'"
+            }
+
+        return {'valid': True}
+
+    def _find_similar_props(
+        self,
+        prop_name: str,
+        available_props: List[str]
+    ) -> Optional[str]:
+        """
+        Find a similar prop name for typo suggestions.
+
+        Uses simple edit distance heuristic.
+
+        Args:
+            prop_name: The (possibly misspelled) prop name
+            available_props: List of valid prop names
+
+        Returns:
+            Most similar prop name, or None if no close match
+        """
+        prop_lower = prop_name.lower()
+
+        for prop in available_props:
+            # Exact match after lowercase
+            if prop.lower() == prop_lower:
+                return prop
+            # Common typos: extra/missing letter
+            if abs(len(prop) - len(prop_name)) == 1:
+                if prop_lower.startswith(prop.lower()[:3]):
+                    return prop
+
+        return None
+
+    def is_loaded(self) -> bool:
+        """Check if registry is loaded."""
+        return len(self.components) > 0
+
+
+def load_registry(dmc_version: Optional[str] = None) -> ComponentRegistry:
+    """
+    Convenience function to load and return a component registry.
+
+    Args:
+        dmc_version: Optional DMC version string
+
+    Returns:
+        Loaded ComponentRegistry instance
+    """
+    registry = ComponentRegistry(dmc_version)
+    registry.load()
+    return registry

mcp-servers/viz-platform/mcp_server/config.py

@@ -0,0 +1,172 @@
+"""
+Configuration loader for viz-platform MCP Server.
+
+Implements hybrid configuration system:
+- System-level: ~/.config/claude/viz-platform.env (theme preferences)
+- Project-level: .env (DMC version overrides)
+- Auto-detection: DMC package version from installed package
+"""
+from pathlib import Path
+from dotenv import load_dotenv
+import os
+import logging
+from typing import Dict, Optional
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class VizPlatformConfig:
+    """Hybrid configuration loader for viz-platform tools"""
+
+    def __init__(self):
+        self.dmc_version: Optional[str] = None
+        self.theme_dir_user: Path = Path.home() / '.config' / 'claude' / 'themes'
+        self.theme_dir_project: Optional[Path] = None
+        self.default_theme: Optional[str] = None
+
+    def load(self) -> Dict[str, any]:
+        """
+        Load configuration from system and project levels.
+
+        Returns:
+            Dict containing dmc_version, theme directories, and availability flags
+        """
+        # Load system config
+        system_config = Path.home() / '.config' / 'claude' / 'viz-platform.env'
+        if system_config.exists():
+            load_dotenv(system_config)
+            logger.info(f"Loaded system configuration from {system_config}")
+
+        # Find project directory
+        project_dir = self._find_project_directory()
+
+        # Load project config (overrides system)
+        if project_dir:
+            project_config = project_dir / '.env'
+            if project_config.exists():
+                load_dotenv(project_config, override=True)
+                logger.info(f"Loaded project configuration from {project_config}")
+
+            # Set project theme directory
+            self.theme_dir_project = project_dir / '.viz-platform' / 'themes'
+
+        # Get DMC version (from env or auto-detect)
+        self.dmc_version = os.getenv('DMC_VERSION') or self._detect_dmc_version()
+        self.default_theme = os.getenv('VIZ_DEFAULT_THEME')
+
+        # Ensure user theme directory exists
+        self.theme_dir_user.mkdir(parents=True, exist_ok=True)
+
+        return {
+            'dmc_version': self.dmc_version,
+            'dmc_available': self.dmc_version is not None,
+            'theme_dir_user': str(self.theme_dir_user),
+            'theme_dir_project': str(self.theme_dir_project) if self.theme_dir_project else None,
+            'default_theme': self.default_theme,
+            'project_dir': str(project_dir) if project_dir else None
+        }
+
+    def _detect_dmc_version(self) -> Optional[str]:
+        """
+        Auto-detect installed Dash Mantine Components version.
+
+        Returns:
+            Version string (e.g., "0.14.7") or None if not installed
+        """
+        try:
+            from importlib.metadata import version
+            dmc_version = version('dash-mantine-components')
+            logger.info(f"Detected DMC version: {dmc_version}")
+            return dmc_version
+        except ImportError:
+            logger.warning("dash-mantine-components not installed - using registry fallback")
+            return None
+        except Exception as e:
+            logger.warning(f"Could not detect DMC version: {e}")
+            return None
+
+    def _find_project_directory(self) -> Optional[Path]:
+        """
+        Find the user's project directory.
+
+        Returns:
+            Path to project directory, or None if not found
+        """
+        # Strategy 1: Check CLAUDE_PROJECT_DIR environment variable
+        project_dir = os.getenv('CLAUDE_PROJECT_DIR')
+        if project_dir:
+            path = Path(project_dir)
+            if path.exists():
+                logger.info(f"Found project directory from CLAUDE_PROJECT_DIR: {path}")
+                return path
+
+        # Strategy 2: Check PWD
+        pwd = os.getenv('PWD')
+        if pwd:
+            path = Path(pwd)
+            if path.exists() and (
+                (path / '.git').exists() or
+                (path / '.env').exists() or
+                (path / '.viz-platform').exists()
+            ):
+                logger.info(f"Found project directory from PWD: {path}")
+                return path
+
+        # Strategy 3: Check current working directory
+        cwd = Path.cwd()
+        if (cwd / '.git').exists() or (cwd / '.env').exists() or (cwd / '.viz-platform').exists():
+            logger.info(f"Found project directory from cwd: {cwd}")
+            return cwd
+
+        logger.debug("Could not determine project directory")
+        return None
+
+
+def load_config() -> Dict[str, any]:
+    """
+    Convenience function to load configuration.
+
+    Returns:
+        Configuration dictionary
+    """
+    config = VizPlatformConfig()
+    return config.load()
+
+
+def check_dmc_version() -> Dict[str, any]:
+    """
+    Check DMC installation status for SessionStart hook.
+
+    Returns:
+        Dict with installation status and version info
+    """
+    config = load_config()
+
+    if not config.get('dmc_available'):
+        return {
+            'installed': False,
+            'message': 'dash-mantine-components not installed. Run: pip install dash-mantine-components'
+        }
+
+    version = config.get('dmc_version', 'unknown')
+
+    # Check for registry compatibility
+    registry_path = Path(__file__).parent.parent / 'registry'
+    major_minor = '.'.join(version.split('.')[:2]) if version else None
+    registry_file = registry_path / f'dmc_{major_minor.replace(".", "_")}.json' if major_minor else None
+
+    if registry_file and registry_file.exists():
+        return {
+            'installed': True,
+            'version': version,
+            'registry_available': True,
+            'message': f'DMC {version} ready with component registry'
+        }
+    else:
+        return {
+            'installed': True,
+            'version': version,
+            'registry_available': False,
+            'message': f'DMC {version} installed but no matching registry. Validation may be limited.'
+        }

mcp-servers/viz-platform/mcp_server/dmc_tools.py

@@ -0,0 +1,306 @@
+"""
+DMC (Dash Mantine Components) validation tools.
+
+Provides component constraint layer to prevent Claude from hallucinating invalid props.
+"""
+import logging
+from typing import Dict, List, Optional, Any
+
+from .component_registry import ComponentRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class DMCTools:
+    """
+    DMC component validation tools.
+
+    These tools provide the "constraint layer" that validates component usage
+    against a version-locked registry of DMC components.
+    """
+
+    def __init__(self, registry: Optional[ComponentRegistry] = None):
+        """
+        Initialize DMC tools with component registry.
+
+        Args:
+            registry: ComponentRegistry instance. If None, creates one.
+        """
+        self.registry = registry
+        self._initialized = False
+
+    def initialize(self, dmc_version: Optional[str] = None) -> bool:
+        """
+        Initialize the registry if not already provided.
+
+        Args:
+            dmc_version: DMC version to load registry for
+
+        Returns:
+            True if initialized successfully
+        """
+        if self.registry is None:
+            self.registry = ComponentRegistry(dmc_version)
+
+        if not self.registry.is_loaded():
+            self.registry.load()
+
+        self._initialized = self.registry.is_loaded()
+        return self._initialized
+
+    async def list_components(
+        self,
+        category: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        List available DMC components, optionally filtered by category.
+
+        Args:
+            category: Optional category filter (e.g., "inputs", "buttons", "navigation")
+
+        Returns:
+            Dict with:
+                - components: Dict[category -> [component names]]
+                - categories: List of available categories
+                - version: Loaded DMC registry version
+                - total_count: Total number of components
+        """
+        if not self._initialized:
+            return {
+                "error": "Registry not initialized",
+                "components": {},
+                "categories": [],
+                "version": None,
+                "total_count": 0
+            }
+
+        components = self.registry.list_components(category)
+        all_categories = self.registry.get_categories()
+
+        # Count total components
+        total = sum(len(comps) for comps in components.values())
+
+        return {
+            "components": components,
+            "categories": all_categories if not category else [category],
+            "version": self.registry.loaded_version,
+            "total_count": total
+        }
+
+    async def get_component_props(self, component: str) -> Dict[str, Any]:
+        """
+        Get props schema for a specific component.
+
+        Args:
+            component: Component name (e.g., "Button", "TextInput")
+
+        Returns:
+            Dict with:
+                - component: Component name
+                - description: Component description
+                - props: Dict of prop name -> {type, default, enum, description}
+                - prop_count: Number of props
+                - required: List of required prop names
+            Or error dict if component not found
+        """
+        if not self._initialized:
+            return {
+                "error": "Registry not initialized",
+                "component": component,
+                "props": {},
+                "prop_count": 0
+            }
+
+        comp_def = self.registry.get_component(component)
+        if not comp_def:
+            # Try to suggest similar component name
+            similar = self._find_similar_component(component)
+            error_msg = f"Component '{component}' not found in registry"
+            if similar:
+                error_msg += f". Did you mean '{similar}'?"
+
+            return {
+                "error": error_msg,
+                "component": component,
+                "props": {},
+                "prop_count": 0
+            }
+
+        props = comp_def.get('props', {})
+
+        # Extract required props
+        required = [
+            name for name, schema in props.items()
+            if schema.get('required', False)
+        ]
+
+        return {
+            "component": component,
+            "description": comp_def.get('description', ''),
+            "props": props,
+            "prop_count": len(props),
+            "required": required,
+            "version": self.registry.loaded_version
+        }
+
+    async def validate_component(
+        self,
+        component: str,
+        props: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Validate component props against registry.
+
+        Args:
+            component: Component name
+            props: Props dict to validate
+
+        Returns:
+            Dict with:
+                - valid: bool - True if all props are valid
+                - errors: List of error messages
+                - warnings: List of warning messages
+                - validated_props: Number of props validated
+                - component: Component name for reference
+        """
+        if not self._initialized:
+            return {
+                "valid": False,
+                "errors": ["Registry not initialized"],
+                "warnings": [],
+                "validated_props": 0,
+                "component": component
+            }
+
+        errors: List[str] = []
+        warnings: List[str] = []
+
+        # Check if component exists
+        comp_def = self.registry.get_component(component)
+        if not comp_def:
+            similar = self._find_similar_component(component)
+            error_msg = f"Unknown component: {component}"
+            if similar:
+                error_msg += f". Did you mean '{similar}'?"
+            errors.append(error_msg)
+
+            return {
+                "valid": False,
+                "errors": errors,
+                "warnings": warnings,
+                "validated_props": 0,
+                "component": component
+            }
+
+        comp_props = comp_def.get('props', {})
+
+        # Check for required props
+        for prop_name, prop_schema in comp_props.items():
+            if prop_schema.get('required', False) and prop_name not in props:
+                errors.append(f"Missing required prop: '{prop_name}'")
+
+        # Validate each provided prop
+        for prop_name, prop_value in props.items():
+            # Skip special props that are always allowed
+            if prop_name in ('id', 'children', 'className', 'style', 'key'):
+                continue
+
+            result = self.registry.validate_prop(component, prop_name, prop_value)
+
+            if not result.get('valid', True):
+                error = result.get('error', f"Invalid prop: {prop_name}")
+                # Distinguish between typos/unknown props and type errors
+                if "Unknown prop" in error:
+                    errors.append(f"❌ {error}")
+                elif "expects one of" in error:
+                    errors.append(f"❌ {error}")
+                elif "expects type" in error:
+                    warnings.append(f"⚠️ {error}")
+                else:
+                    errors.append(f"❌ {error}")
+
+        # Check for props that exist but might have common mistakes
+        self._check_common_mistakes(component, props, warnings)
+
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "warnings": warnings,
+            "validated_props": len(props),
+            "component": component,
+            "version": self.registry.loaded_version
+        }
+
+    def _find_similar_component(self, component: str) -> Optional[str]:
+        """
+        Find a similar component name for suggestions.
+
+        Args:
+            component: The (possibly misspelled) component name
+
+        Returns:
+            Similar component name, or None if no close match
+        """
+        if not self.registry:
+            return None
+
+        comp_lower = component.lower()
+        all_components = []
+        for comps in self.registry.categories.values():
+            all_components.extend(comps)
+
+        for comp in all_components:
+            # Exact match after lowercase
+            if comp.lower() == comp_lower:
+                return comp
+            # Check if it's a prefix match
+            if comp.lower().startswith(comp_lower) or comp_lower.startswith(comp.lower()):
+                return comp
+            # Check for common typos
+            if abs(len(comp) - len(component)) <= 2:
+                if comp_lower[:4] == comp.lower()[:4]:
+                    return comp
+
+        return None
+
+    def _check_common_mistakes(
+        self,
+        component: str,
+        props: Dict[str, Any],
+        warnings: List[str]
+    ) -> None:
+        """
+        Check for common prop usage mistakes and add warnings.
+
+        Args:
+            component: Component name
+            props: Props being used
+            warnings: List to append warnings to
+        """
+        # Common mistake: using 'onclick' instead of callback pattern
+        if 'onclick' in [p.lower() for p in props.keys()]:
+            warnings.append(
+                "⚠️ Dash uses callback patterns, not inline event handlers. "
+                "Use 'n_clicks' prop with a callback instead."
+            )
+
+        # Common mistake: using 'class' instead of 'className'
+        if 'class' in props:
+            warnings.append(
+                "⚠️ Use 'className' instead of 'class' for CSS classes."
+            )
+
+        # Button-specific checks
+        if component == 'Button':
+            if 'href' in props and 'component' not in props:
+                warnings.append(
+                    "⚠️ Button with 'href' should also set 'component=\"a\"' for proper anchor behavior."
+                )
+
+        # Input-specific checks
+        if 'Input' in component:
+            if 'value' in props and 'onChange' in [p for p in props.keys()]:
+                warnings.append(
+                    "⚠️ Dash uses 'value' prop with callbacks, not 'onChange'. "
+                    "The value updates automatically through Dash callbacks."
+                )

mcp-servers/viz-platform/mcp_server/layout_tools.py

@@ -0,0 +1,367 @@
+"""
+Layout composition tools for dashboard building.
+
+Provides tools for creating structured layouts with grids, filters, and sections.
+"""
+import logging
+from typing import Dict, List, Optional, Any
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+
+# Layout templates
+TEMPLATES = {
+    "dashboard": {
+        "sections": ["header", "filters", "main", "footer"],
+        "default_grid": {"cols": 12, "spacing": "md"},
+        "description": "Standard dashboard with header, filters, main content, and footer"
+    },
+    "report": {
+        "sections": ["title", "summary", "content", "appendix"],
+        "default_grid": {"cols": 1, "spacing": "lg"},
+        "description": "Report layout with title, summary, and content sections"
+    },
+    "form": {
+        "sections": ["header", "fields", "actions"],
+        "default_grid": {"cols": 2, "spacing": "md"},
+        "description": "Form layout with header, fields, and action buttons"
+    },
+    "blank": {
+        "sections": ["main"],
+        "default_grid": {"cols": 12, "spacing": "md"},
+        "description": "Blank canvas for custom layouts"
+    }
+}
+
+
+# Filter type definitions
+FILTER_TYPES = {
+    "dropdown": {
+        "component": "Select",
+        "props": ["label", "data", "placeholder", "clearable", "searchable", "value"]
+    },
+    "multi_select": {
+        "component": "MultiSelect",
+        "props": ["label", "data", "placeholder", "clearable", "searchable", "value"]
+    },
+    "date_range": {
+        "component": "DateRangePicker",
+        "props": ["label", "placeholder", "value", "minDate", "maxDate"]
+    },
+    "date": {
+        "component": "DatePicker",
+        "props": ["label", "placeholder", "value", "minDate", "maxDate"]
+    },
+    "search": {
+        "component": "TextInput",
+        "props": ["label", "placeholder", "value", "icon"]
+    },
+    "checkbox_group": {
+        "component": "CheckboxGroup",
+        "props": ["label", "children", "value"]
+    },
+    "radio_group": {
+        "component": "RadioGroup",
+        "props": ["label", "children", "value"]
+    },
+    "slider": {
+        "component": "Slider",
+        "props": ["label", "min", "max", "step", "value", "marks"]
+    },
+    "range_slider": {
+        "component": "RangeSlider",
+        "props": ["label", "min", "max", "step", "value", "marks"]
+    }
+}
+
+
+class LayoutTools:
+    """
+    Dashboard layout composition tools.
+
+    Creates layouts that map to DMC Grid and AppShell components.
+    """
+
+    def __init__(self):
+        """Initialize layout tools."""
+        self._layouts: Dict[str, Dict[str, Any]] = {}
+
+    async def layout_create(
+        self,
+        name: str,
+        template: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new layout container.
+
+        Args:
+            name: Unique name for the layout
+            template: Optional template (dashboard, report, form, blank)
+
+        Returns:
+            Dict with:
+                - layout_ref: Reference to use in other tools
+                - template: Template used
+                - sections: Available sections
+                - grid: Default grid configuration
+        """
+        # Validate template
+        template = template or "blank"
+        if template not in TEMPLATES:
+            return {
+                "error": f"Invalid template '{template}'. Must be one of: {list(TEMPLATES.keys())}",
+                "layout_ref": None
+            }
+
+        # Check for name collision
+        if name in self._layouts:
+            return {
+                "error": f"Layout '{name}' already exists. Use a different name or modify existing.",
+                "layout_ref": name
+            }
+
+        template_config = TEMPLATES[template]
+
+        # Create layout structure
+        layout = {
+            "id": str(uuid4()),
+            "name": name,
+            "template": template,
+            "sections": {section: {"items": []} for section in template_config["sections"]},
+            "grid": template_config["default_grid"].copy(),
+            "filters": [],
+            "metadata": {
+                "description": template_config["description"]
+            }
+        }
+
+        self._layouts[name] = layout
+
+        return {
+            "layout_ref": name,
+            "template": template,
+            "sections": template_config["sections"],
+            "grid": layout["grid"],
+            "description": template_config["description"]
+        }
+
+    async def layout_add_filter(
+        self,
+        layout_ref: str,
+        filter_type: str,
+        options: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Add a filter control to a layout.
+
+        Args:
+            layout_ref: Layout name to add filter to
+            filter_type: Type of filter (dropdown, date_range, search, checkbox_group, etc.)
+            options: Filter options (label, data for dropdown, placeholder, position)
+
+        Returns:
+            Dict with:
+                - filter_id: Unique ID for the filter
+                - component: DMC component that will be used
+                - props: Props that were set
+                - position: Where filter was placed
+        """
+        # Validate layout exists
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found. Create it first with layout_create.",
+                "filter_id": None
+            }
+
+        # Validate filter type
+        if filter_type not in FILTER_TYPES:
+            return {
+                "error": f"Invalid filter_type '{filter_type}'. Must be one of: {list(FILTER_TYPES.keys())}",
+                "filter_id": None
+            }
+
+        filter_config = FILTER_TYPES[filter_type]
+        layout = self._layouts[layout_ref]
+
+        # Generate filter ID
+        filter_id = f"filter_{filter_type}_{len(layout['filters'])}"
+
+        # Extract relevant props
+        props = {"id": filter_id}
+        for prop in filter_config["props"]:
+            if prop in options:
+                props[prop] = options[prop]
+
+        # Determine position
+        position = options.get("position", "filters")
+        if position not in layout["sections"]:
+            # Default to first available section
+            position = list(layout["sections"].keys())[0]
+
+        # Create filter definition
+        filter_def = {
+            "id": filter_id,
+            "type": filter_type,
+            "component": filter_config["component"],
+            "props": props,
+            "position": position
+        }
+
+        layout["filters"].append(filter_def)
+        layout["sections"][position]["items"].append({
+            "type": "filter",
+            "ref": filter_id
+        })
+
+        return {
+            "filter_id": filter_id,
+            "component": filter_config["component"],
+            "props": props,
+            "position": position,
+            "layout_ref": layout_ref
+        }
+
+    async def layout_set_grid(
+        self,
+        layout_ref: str,
+        grid: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Configure the grid system for a layout.
+
+        Args:
+            layout_ref: Layout name to configure
+            grid: Grid configuration:
+                - cols: Number of columns (default 12)
+                - spacing: Gap between items (xs, sm, md, lg, xl)
+                - breakpoints: Responsive breakpoints {xs: cols, sm: cols, ...}
+                - gutter: Gutter size
+
+        Returns:
+            Dict with:
+                - grid: Updated grid configuration
+                - layout_ref: Layout reference
+        """
+        # Validate layout exists
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found. Create it first with layout_create.",
+                "grid": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        # Validate spacing if provided
+        valid_spacing = ["xs", "sm", "md", "lg", "xl"]
+        if "spacing" in grid and grid["spacing"] not in valid_spacing:
+            return {
+                "error": f"Invalid spacing '{grid['spacing']}'. Must be one of: {valid_spacing}",
+                "grid": layout["grid"]
+            }
+
+        # Validate cols
+        if "cols" in grid:
+            cols = grid["cols"]
+            if not isinstance(cols, int) or cols < 1 or cols > 24:
+                return {
+                    "error": f"Invalid cols '{cols}'. Must be integer between 1 and 24.",
+                    "grid": layout["grid"]
+                }
+
+        # Update grid configuration
+        layout["grid"].update(grid)
+
+        # Process breakpoints if provided
+        if "breakpoints" in grid:
+            bp = grid["breakpoints"]
+            layout["grid"]["breakpoints"] = bp
+
+        return {
+            "grid": layout["grid"],
+            "layout_ref": layout_ref
+        }
+
+    async def layout_get(self, layout_ref: str) -> Dict[str, Any]:
+        """
+        Get a layout's full configuration.
+
+        Args:
+            layout_ref: Layout name to retrieve
+
+        Returns:
+            Full layout configuration or error
+        """
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found.",
+                "layout": None
+            }
+
+        layout = self._layouts[layout_ref]
+
+        return {
+            "layout": layout,
+            "filter_count": len(layout["filters"]),
+            "sections": list(layout["sections"].keys())
+        }
+
+    async def layout_add_section(
+        self,
+        layout_ref: str,
+        section_name: str,
+        position: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Add a custom section to a layout.
+
+        Args:
+            layout_ref: Layout name
+            section_name: Name for the new section
+            position: Optional position index (appends if not specified)
+
+        Returns:
+            Dict with sections list and the new section name
+        """
+        if layout_ref not in self._layouts:
+            return {
+                "error": f"Layout '{layout_ref}' not found.",
+                "sections": []
+            }
+
+        layout = self._layouts[layout_ref]
+
+        if section_name in layout["sections"]:
+            return {
+                "error": f"Section '{section_name}' already exists.",
+                "sections": list(layout["sections"].keys())
+            }
+
+        # Add new section
+        layout["sections"][section_name] = {"items": []}
+
+        return {
+            "section_name": section_name,
+            "sections": list(layout["sections"].keys()),
+            "layout_ref": layout_ref
+        }
+
+    def get_available_templates(self) -> Dict[str, Any]:
+        """Get list of available layout templates."""
+        return {
+            name: {
+                "sections": config["sections"],
+                "description": config["description"]
+            }
+            for name, config in TEMPLATES.items()
+        }
+
+    def get_available_filter_types(self) -> Dict[str, Any]:
+        """Get list of available filter types."""
+        return {
+            name: {
+                "component": config["component"],
+                "props": config["props"]
+            }
+            for name, config in FILTER_TYPES.items()
+        }

mcp-servers/viz-platform/mcp_server/page_tools.py

@@ -0,0 +1,366 @@
+"""
+Multi-page app tools for viz-platform.
+
+Provides tools for building complete Dash applications with routing and navigation.
+"""
+import logging
+from typing import Dict, List, Optional, Any
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+
+# Navigation position options
+NAV_POSITIONS = ["top", "left", "right"]
+
+# Auth types supported
+AUTH_TYPES = ["none", "basic", "oauth", "custom"]
+
+
+class PageTools:
+    """
+    Multi-page Dash application tools.
+
+    Creates page definitions, navigation, and auth configuration.
+    """
+
+    def __init__(self):
+        """Initialize page tools."""
+        self._pages: Dict[str, Dict[str, Any]] = {}
+        self._navbars: Dict[str, Dict[str, Any]] = {}
+        self._app_config: Dict[str, Any] = {
+            "title": "Dash App",
+            "suppress_callback_exceptions": True
+        }
+
+    async def page_create(
+        self,
+        name: str,
+        path: str,
+        layout_ref: Optional[str] = None,
+        title: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new page definition.
+
+        Args:
+            name: Unique page name (used as identifier)
+            path: URL path for the page (e.g., "/", "/settings")
+            layout_ref: Optional layout reference to use for the page
+            title: Optional page title (defaults to name)
+
+        Returns:
+            Dict with:
+                - page_ref: Reference to use in other tools
+                - path: URL path
+                - registered: Whether page was registered
+        """
+        # Validate path format
+        if not path.startswith('/'):
+            return {
+                "error": f"Path must start with '/'. Got: {path}",
+                "page_ref": None
+            }
+
+        # Check for name collision
+        if name in self._pages:
+            return {
+                "error": f"Page '{name}' already exists. Use a different name.",
+                "page_ref": name
+            }
+
+        # Check for path collision
+        for page_name, page_data in self._pages.items():
+            if page_data['path'] == path:
+                return {
+                    "error": f"Path '{path}' already used by page '{page_name}'.",
+                    "page_ref": None
+                }
+
+        # Create page definition
+        page = {
+            "id": str(uuid4()),
+            "name": name,
+            "path": path,
+            "title": title or name,
+            "layout_ref": layout_ref,
+            "auth": None,
+            "metadata": {}
+        }
+
+        self._pages[name] = page
+
+        return {
+            "page_ref": name,
+            "path": path,
+            "title": page["title"],
+            "layout_ref": layout_ref,
+            "registered": True
+        }
+
+    async def page_add_navbar(
+        self,
+        pages: List[str],
+        options: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Generate a navigation component linking pages.
+
+        Args:
+            pages: List of page names to include in navigation
+            options: Navigation options:
+                - position: "top", "left", or "right"
+                - style: Style variant
+                - brand: Brand/logo text or config
+                - collapsible: Whether to collapse on mobile
+
+        Returns:
+            Dict with:
+                - navbar_id: Navigation ID
+                - pages: List of page links generated
+                - component: DMC component structure
+        """
+        options = options or {}
+
+        # Validate pages exist
+        missing_pages = [p for p in pages if p not in self._pages]
+        if missing_pages:
+            return {
+                "error": f"Pages not found: {missing_pages}. Create them first.",
+                "navbar_id": None
+            }
+
+        # Validate position
+        position = options.get("position", "top")
+        if position not in NAV_POSITIONS:
+            return {
+                "error": f"Invalid position '{position}'. Must be one of: {NAV_POSITIONS}",
+                "navbar_id": None
+            }
+
+        # Generate navbar ID
+        navbar_id = f"navbar_{len(self._navbars)}"
+
+        # Build page links
+        page_links = []
+        for page_name in pages:
+            page = self._pages[page_name]
+            page_links.append({
+                "label": page["title"],
+                "href": page["path"],
+                "page_ref": page_name
+            })
+
+        # Build DMC component structure
+        if position == "top":
+            component = self._build_top_navbar(page_links, options)
+        else:
+            component = self._build_side_navbar(page_links, options, position)
+
+        # Store navbar config
+        self._navbars[navbar_id] = {
+            "id": navbar_id,
+            "position": position,
+            "pages": pages,
+            "options": options,
+            "component": component
+        }
+
+        return {
+            "navbar_id": navbar_id,
+            "position": position,
+            "pages": page_links,
+            "component": component
+        }
+
+    async def page_set_auth(
+        self,
+        page_ref: str,
+        auth_config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Configure authentication for a page.
+
+        Args:
+            page_ref: Page name to configure
+            auth_config: Authentication configuration:
+                - type: "none", "basic", "oauth", "custom"
+                - required: Whether auth is required (default True)
+                - roles: List of required roles (optional)
+                - redirect: Redirect path for unauthenticated users
+
+        Returns:
+            Dict with:
+                - page_ref: Page reference
+                - auth_type: Type of auth configured
+                - protected: Whether page is protected
+        """
+        # Validate page exists
+        if page_ref not in self._pages:
+            available = list(self._pages.keys())
+            return {
+                "error": f"Page '{page_ref}' not found. Available: {available}",
+                "page_ref": page_ref
+            }
+
+        # Validate auth type
+        auth_type = auth_config.get("type", "basic")
+        if auth_type not in AUTH_TYPES:
+            return {
+                "error": f"Invalid auth type '{auth_type}'. Must be one of: {AUTH_TYPES}",
+                "page_ref": page_ref
+            }
+
+        # Build auth config
+        auth = {
+            "type": auth_type,
+            "required": auth_config.get("required", True),
+            "roles": auth_config.get("roles", []),
+            "redirect": auth_config.get("redirect", "/login")
+        }
+
+        # Handle OAuth-specific config
+        if auth_type == "oauth":
+            auth["provider"] = auth_config.get("provider", "generic")
+            auth["scopes"] = auth_config.get("scopes", [])
+
+        # Update page
+        self._pages[page_ref]["auth"] = auth
+
+        return {
+            "page_ref": page_ref,
+            "auth_type": auth_type,
+            "protected": auth["required"],
+            "roles": auth["roles"],
+            "redirect": auth["redirect"]
+        }
+
+    async def page_list(self) -> Dict[str, Any]:
+        """
+        List all registered pages.
+
+        Returns:
+            Dict with pages and their configurations
+        """
+        pages_info = {}
+        for name, page in self._pages.items():
+            pages_info[name] = {
+                "path": page["path"],
+                "title": page["title"],
+                "layout_ref": page["layout_ref"],
+                "protected": page["auth"] is not None and page["auth"].get("required", False)
+            }
+
+        return {
+            "pages": pages_info,
+            "count": len(pages_info),
+            "navbars": list(self._navbars.keys())
+        }
+
+    async def page_get_app_config(self) -> Dict[str, Any]:
+        """
+        Get the complete app configuration for Dash.
+
+        Returns:
+            Dict with app config including pages, navbars, and settings
+        """
+        # Build pages config
+        pages_config = []
+        for name, page in self._pages.items():
+            pages_config.append({
+                "name": name,
+                "path": page["path"],
+                "title": page["title"],
+                "layout_ref": page["layout_ref"]
+            })
+
+        # Build routing config
+        routes = {page["path"]: name for name, page in self._pages.items()}
+
+        return {
+            "app": self._app_config,
+            "pages": pages_config,
+            "routes": routes,
+            "navbars": list(self._navbars.values()),
+            "page_count": len(self._pages)
+        }
+
+    def _build_top_navbar(
+        self,
+        page_links: List[Dict[str, str]],
+        options: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Build a top navigation bar component."""
+        brand = options.get("brand", "App")
+
+        # Build nav links
+        nav_items = []
+        for link in page_links:
+            nav_items.append({
+                "component": "NavLink",
+                "props": {
+                    "label": link["label"],
+                    "href": link["href"]
+                }
+            })
+
+        return {
+            "component": "AppShell.Header",
+            "children": [
+                {
+                    "component": "Group",
+                    "props": {"justify": "space-between", "h": "100%", "px": "md"},
+                    "children": [
+                        {
+                            "component": "Text",
+                            "props": {"size": "lg", "fw": 700},
+                            "children": brand
+                        },
+                        {
+                            "component": "Group",
+                            "props": {"gap": "sm"},
+                            "children": nav_items
+                        }
+                    ]
+                }
+            ]
+        }
+
+    def _build_side_navbar(
+        self,
+        page_links: List[Dict[str, str]],
+        options: Dict[str, Any],
+        position: str
+    ) -> Dict[str, Any]:
+        """Build a side navigation bar component."""
+        brand = options.get("brand", "App")
+
+        # Build nav links
+        nav_items = []
+        for link in page_links:
+            nav_items.append({
+                "component": "NavLink",
+                "props": {
+                    "label": link["label"],
+                    "href": link["href"]
+                }
+            })
+
+        navbar_component = "AppShell.Navbar" if position == "left" else "AppShell.Aside"
+
+        return {
+            "component": navbar_component,
+            "props": {"p": "md"},
+            "children": [
+                {
+                    "component": "Text",
+                    "props": {"size": "lg", "fw": 700, "mb": "md"},
+                    "children": brand
+                },
+                {
+                    "component": "Stack",
+                    "props": {"gap": "xs"},
+                    "children": nav_items
+                }
+            ]
+        }

mcp-servers/viz-platform/mcp_server/server.py

@@ -0,0 +1,701 @@
+"""
+MCP Server entry point for viz-platform integration.
+
+Provides Dash Mantine Components validation, charting, layout, theming, and page tools
+to Claude Code via JSON-RPC 2.0 over stdio.
+"""
+import asyncio
+import logging
+import json
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from .config import VizPlatformConfig
+from .dmc_tools import DMCTools
+from .chart_tools import ChartTools
+from .layout_tools import LayoutTools
+from .theme_tools import ThemeTools
+from .page_tools import PageTools
+
+# Suppress noisy MCP validation warnings on stderr
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("root").setLevel(logging.ERROR)
+logging.getLogger("mcp").setLevel(logging.ERROR)
+logger = logging.getLogger(__name__)
+
+
+class VizPlatformMCPServer:
+    """MCP Server for visualization platform integration"""
+
+    def __init__(self):
+        self.server = Server("viz-platform-mcp")
+        self.config = None
+        self.dmc_tools = DMCTools()
+        self.chart_tools = ChartTools()
+        self.layout_tools = LayoutTools()
+        self.theme_tools = ThemeTools()
+        self.page_tools = PageTools()
+
+    async def initialize(self):
+        """Initialize server and load configuration."""
+        try:
+            config_loader = VizPlatformConfig()
+            self.config = config_loader.load()
+
+            # Initialize DMC tools with detected version
+            dmc_version = self.config.get('dmc_version')
+            self.dmc_tools.initialize(dmc_version)
+
+            # Log available capabilities
+            caps = []
+            if self.config.get('dmc_available'):
+                caps.append(f"DMC {dmc_version}")
+                if self.dmc_tools._initialized:
+                    caps.append(f"Registry loaded ({self.dmc_tools.registry.loaded_version})")
+            else:
+                caps.append("DMC (not installed)")
+
+            logger.info(f"viz-platform MCP Server initialized with: {', '.join(caps)}")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize: {e}")
+            raise
+
+    def setup_tools(self):
+        """Register all available tools with the MCP server"""
+
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """Return list of available tools"""
+            tools = []
+
+            # DMC validation tools (Issue #172)
+            tools.append(Tool(
+                name="list_components",
+                description=(
+                    "List available Dash Mantine Components. "
+                    "Returns components grouped by category with version info. "
+                    "Use this to discover what components are available before building UI."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "category": {
+                            "type": "string",
+                            "description": (
+                                "Optional category filter. Available categories: "
+                                "buttons, inputs, navigation, feedback, overlays, "
+                                "typography, layout, data_display, charts, dates"
+                            )
+                        }
+                    },
+                    "required": []
+                }
+            ))
+
+            tools.append(Tool(
+                name="get_component_props",
+                description=(
+                    "Get the props schema for a specific DMC component. "
+                    "Returns all available props with types, defaults, and allowed values. "
+                    "ALWAYS use this before creating a component to ensure valid props."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "component": {
+                            "type": "string",
+                            "description": "Component name (e.g., 'Button', 'TextInput', 'Select')"
+                        }
+                    },
+                    "required": ["component"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="validate_component",
+                description=(
+                    "Validate component props before use. "
+                    "Checks for invalid props, type mismatches, and common mistakes. "
+                    "Returns errors and warnings with suggestions for fixes."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "component": {
+                            "type": "string",
+                            "description": "Component name to validate"
+                        },
+                        "props": {
+                            "type": "object",
+                            "description": "Props object to validate"
+                        }
+                    },
+                    "required": ["component", "props"]
+                }
+            ))
+
+            # Chart tools (Issue #173)
+            tools.append(Tool(
+                name="chart_create",
+                description=(
+                    "Create a Plotly chart for data visualization. "
+                    "Supports line, bar, scatter, pie, heatmap, histogram, and area charts. "
+                    "Automatically applies theme colors when a theme is active."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "chart_type": {
+                            "type": "string",
+                            "enum": ["line", "bar", "scatter", "pie", "heatmap", "histogram", "area"],
+                            "description": "Type of chart to create"
+                        },
+                        "data": {
+                            "type": "object",
+                            "description": (
+                                "Data for the chart. For most charts: {x: [], y: []}. "
+                                "For pie: {labels: [], values: []}. "
+                                "For heatmap: {x: [], y: [], z: [[]]}"
+                            )
+                        },
+                        "options": {
+                            "type": "object",
+                            "description": (
+                                "Optional settings: title, x_label, y_label, color, "
+                                "showlegend, height, width, horizontal (for bar)"
+                            )
+                        }
+                    },
+                    "required": ["chart_type", "data"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="chart_configure_interaction",
+                description=(
+                    "Configure interactions on an existing chart. "
+                    "Add hover templates, enable click data capture, selection modes, "
+                    "and zoom behavior for Dash callback integration."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "figure": {
+                            "type": "object",
+                            "description": "Plotly figure JSON to modify"
+                        },
+                        "interactions": {
+                            "type": "object",
+                            "description": (
+                                "Interaction config: hover_template (string), "
+                                "click_data (bool), selection ('box'|'lasso'), zoom (bool)"
+                            )
+                        }
+                    },
+                    "required": ["figure", "interactions"]
+                }
+            ))
+
+            # Layout tools (Issue #174)
+            tools.append(Tool(
+                name="layout_create",
+                description=(
+                    "Create a new dashboard layout container. "
+                    "Templates available: dashboard, report, form, blank. "
+                    "Returns layout reference for use with other layout tools."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Unique name for the layout"
+                        },
+                        "template": {
+                            "type": "string",
+                            "enum": ["dashboard", "report", "form", "blank"],
+                            "description": "Layout template to use (default: blank)"
+                        }
+                    },
+                    "required": ["name"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="layout_add_filter",
+                description=(
+                    "Add a filter control to a layout. "
+                    "Filter types: dropdown, multi_select, date_range, date, search, "
+                    "checkbox_group, radio_group, slider, range_slider."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Layout name to add filter to"
+                        },
+                        "filter_type": {
+                            "type": "string",
+                            "enum": ["dropdown", "multi_select", "date_range", "date",
+                                    "search", "checkbox_group", "radio_group", "slider", "range_slider"],
+                            "description": "Type of filter control"
+                        },
+                        "options": {
+                            "type": "object",
+                            "description": (
+                                "Filter options: label, data (for dropdown), placeholder, "
+                                "position (section name), value, etc."
+                            )
+                        }
+                    },
+                    "required": ["layout_ref", "filter_type", "options"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="layout_set_grid",
+                description=(
+                    "Configure the grid system for a layout. "
+                    "Uses DMC Grid component patterns with 12 or 24 column system."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Layout name to configure"
+                        },
+                        "grid": {
+                            "type": "object",
+                            "description": (
+                                "Grid config: cols (1-24), spacing (xs|sm|md|lg|xl), "
+                                "breakpoints ({xs: cols, sm: cols, ...}), gutter"
+                            )
+                        }
+                    },
+                    "required": ["layout_ref", "grid"]
+                }
+            ))
+
+            # Theme tools (Issue #175)
+            tools.append(Tool(
+                name="theme_create",
+                description=(
+                    "Create a new design theme with tokens. "
+                    "Tokens include colors, spacing, typography, radii. "
+                    "Missing tokens are filled from defaults."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Unique theme name"
+                        },
+                        "tokens": {
+                            "type": "object",
+                            "description": (
+                                "Design tokens: colors (primary, background, text), "
+                                "spacing (xs-xl), typography (fontFamily, fontSize), radii (sm-xl)"
+                            )
+                        }
+                    },
+                    "required": ["name", "tokens"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="theme_extend",
+                description=(
+                    "Create a new theme by extending an existing one. "
+                    "Only specify the tokens you want to override."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "base_theme": {
+                            "type": "string",
+                            "description": "Theme to extend (e.g., 'default')"
+                        },
+                        "overrides": {
+                            "type": "object",
+                            "description": "Token overrides to apply"
+                        },
+                        "new_name": {
+                            "type": "string",
+                            "description": "Name for the new theme (optional)"
+                        }
+                    },
+                    "required": ["base_theme", "overrides"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="theme_validate",
+                description=(
+                    "Validate a theme for completeness. "
+                    "Checks for required tokens and common issues."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "theme_name": {
+                            "type": "string",
+                            "description": "Theme to validate"
+                        }
+                    },
+                    "required": ["theme_name"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="theme_export_css",
+                description=(
+                    "Export a theme as CSS custom properties. "
+                    "Generates :root CSS variables for all tokens."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "theme_name": {
+                            "type": "string",
+                            "description": "Theme to export"
+                        }
+                    },
+                    "required": ["theme_name"]
+                }
+            ))
+
+            # Page tools (Issue #176)
+            tools.append(Tool(
+                name="page_create",
+                description=(
+                    "Create a new page for a multi-page Dash application. "
+                    "Defines page routing and can link to a layout."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Unique page name (identifier)"
+                        },
+                        "path": {
+                            "type": "string",
+                            "description": "URL path (e.g., '/', '/settings')"
+                        },
+                        "layout_ref": {
+                            "type": "string",
+                            "description": "Optional layout reference to use"
+                        },
+                        "title": {
+                            "type": "string",
+                            "description": "Page title (defaults to name)"
+                        }
+                    },
+                    "required": ["name", "path"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="page_add_navbar",
+                description=(
+                    "Generate navigation component linking pages. "
+                    "Creates top or side navigation with DMC components."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "pages": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "List of page names to include"
+                        },
+                        "options": {
+                            "type": "object",
+                            "description": (
+                                "Navigation options: position (top|left|right), "
+                                "brand (app name), collapsible (bool)"
+                            )
+                        }
+                    },
+                    "required": ["pages"]
+                }
+            ))
+
+            tools.append(Tool(
+                name="page_set_auth",
+                description=(
+                    "Configure authentication for a page. "
+                    "Sets auth requirements, roles, and redirect behavior."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "page_ref": {
+                            "type": "string",
+                            "description": "Page name to configure"
+                        },
+                        "auth_config": {
+                            "type": "object",
+                            "description": (
+                                "Auth config: type (none|basic|oauth|custom), "
+                                "required (bool), roles (array), redirect (path)"
+                            )
+                        }
+                    },
+                    "required": ["page_ref", "auth_config"]
+                }
+            ))
+
+            return tools
+
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+            """Handle tool invocation."""
+            try:
+                # DMC validation tools
+                if name == "list_components":
+                    result = await self.dmc_tools.list_components(
+                        category=arguments.get('category')
+                    )
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "get_component_props":
+                    component = arguments.get('component')
+                    if not component:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "component is required"}, indent=2)
+                        )]
+                    result = await self.dmc_tools.get_component_props(component)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "validate_component":
+                    component = arguments.get('component')
+                    props = arguments.get('props', {})
+                    if not component:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "component is required"}, indent=2)
+                        )]
+                    result = await self.dmc_tools.validate_component(component, props)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Chart tools
+                elif name == "chart_create":
+                    chart_type = arguments.get('chart_type')
+                    data = arguments.get('data', {})
+                    options = arguments.get('options', {})
+                    if not chart_type:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "chart_type is required"}, indent=2)
+                        )]
+                    result = await self.chart_tools.chart_create(chart_type, data, options)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "chart_configure_interaction":
+                    figure = arguments.get('figure')
+                    interactions = arguments.get('interactions', {})
+                    if not figure:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "figure is required"}, indent=2)
+                        )]
+                    result = await self.chart_tools.chart_configure_interaction(figure, interactions)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Layout tools
+                elif name == "layout_create":
+                    layout_name = arguments.get('name')
+                    template = arguments.get('template')
+                    if not layout_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "name is required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_create(layout_name, template)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "layout_add_filter":
+                    layout_ref = arguments.get('layout_ref')
+                    filter_type = arguments.get('filter_type')
+                    options = arguments.get('options', {})
+                    if not layout_ref or not filter_type:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "layout_ref and filter_type are required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_add_filter(layout_ref, filter_type, options)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "layout_set_grid":
+                    layout_ref = arguments.get('layout_ref')
+                    grid = arguments.get('grid', {})
+                    if not layout_ref:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "layout_ref is required"}, indent=2)
+                        )]
+                    result = await self.layout_tools.layout_set_grid(layout_ref, grid)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Theme tools
+                elif name == "theme_create":
+                    theme_name = arguments.get('name')
+                    tokens = arguments.get('tokens', {})
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "name is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_create(theme_name, tokens)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "theme_extend":
+                    base_theme = arguments.get('base_theme')
+                    overrides = arguments.get('overrides', {})
+                    new_name = arguments.get('new_name')
+                    if not base_theme:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "base_theme is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_extend(base_theme, overrides, new_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "theme_validate":
+                    theme_name = arguments.get('theme_name')
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "theme_name is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_validate(theme_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "theme_export_css":
+                    theme_name = arguments.get('theme_name')
+                    if not theme_name:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "theme_name is required"}, indent=2)
+                        )]
+                    result = await self.theme_tools.theme_export_css(theme_name)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                # Page tools
+                elif name == "page_create":
+                    page_name = arguments.get('name')
+                    path = arguments.get('path')
+                    layout_ref = arguments.get('layout_ref')
+                    title = arguments.get('title')
+                    if not page_name or not path:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "name and path are required"}, indent=2)
+                        )]
+                    result = await self.page_tools.page_create(page_name, path, layout_ref, title)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "page_add_navbar":
+                    pages = arguments.get('pages', [])
+                    options = arguments.get('options', {})
+                    if not pages:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "pages list is required"}, indent=2)
+                        )]
+                    result = await self.page_tools.page_add_navbar(pages, options)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                elif name == "page_set_auth":
+                    page_ref = arguments.get('page_ref')
+                    auth_config = arguments.get('auth_config', {})
+                    if not page_ref:
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({"error": "page_ref is required"}, indent=2)
+                        )]
+                    result = await self.page_tools.page_set_auth(page_ref, auth_config)
+                    return [TextContent(
+                        type="text",
+                        text=json.dumps(result, indent=2)
+                    )]
+
+                raise ValueError(f"Unknown tool: {name}")
+
+            except Exception as e:
+                logger.error(f"Tool {name} failed: {e}")
+                return [TextContent(
+                    type="text",
+                    text=json.dumps({"error": str(e)}, indent=2)
+                )]
+
+    async def run(self):
+        """Run the MCP server"""
+        await self.initialize()
+        self.setup_tools()
+
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point"""
+    server = VizPlatformMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp-servers/viz-platform/mcp_server/theme_store.py

@@ -0,0 +1,259 @@
+"""
+Theme storage and persistence for viz-platform.
+
+Handles saving/loading themes from user and project locations.
+"""
+import json
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+
+# Default theme based on Mantine defaults
+DEFAULT_THEME = {
+    "name": "default",
+    "version": "1.0.0",
+    "tokens": {
+        "colors": {
+            "primary": "#228be6",
+            "secondary": "#868e96",
+            "success": "#40c057",
+            "warning": "#fab005",
+            "error": "#fa5252",
+            "info": "#15aabf",
+            "background": {
+                "base": "#ffffff",
+                "subtle": "#f8f9fa",
+                "dark": "#212529"
+            },
+            "text": {
+                "primary": "#212529",
+                "secondary": "#495057",
+                "muted": "#868e96",
+                "inverse": "#ffffff"
+            },
+            "border": "#dee2e6"
+        },
+        "spacing": {
+            "xs": "4px",
+            "sm": "8px",
+            "md": "16px",
+            "lg": "24px",
+            "xl": "32px"
+        },
+        "typography": {
+            "fontFamily": "Inter, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",
+            "fontFamilyMono": "ui-monospace, SFMono-Regular, Menlo, Monaco, monospace",
+            "fontSize": {
+                "xs": "12px",
+                "sm": "14px",
+                "md": "16px",
+                "lg": "18px",
+                "xl": "20px"
+            },
+            "fontWeight": {
+                "normal": 400,
+                "medium": 500,
+                "semibold": 600,
+                "bold": 700
+            },
+            "lineHeight": {
+                "tight": 1.25,
+                "normal": 1.5,
+                "relaxed": 1.75
+            }
+        },
+        "radii": {
+            "none": "0px",
+            "sm": "4px",
+            "md": "8px",
+            "lg": "16px",
+            "xl": "24px",
+            "full": "9999px"
+        },
+        "shadows": {
+            "none": "none",
+            "sm": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
+            "md": "0 4px 6px -1px rgb(0 0 0 / 0.1)",
+            "lg": "0 10px 15px -3px rgb(0 0 0 / 0.1)",
+            "xl": "0 20px 25px -5px rgb(0 0 0 / 0.1)"
+        },
+        "transitions": {
+            "fast": "150ms",
+            "normal": "300ms",
+            "slow": "500ms"
+        }
+    }
+}
+
+
+# Required token categories for validation
+REQUIRED_TOKEN_CATEGORIES = ["colors", "spacing", "typography", "radii"]
+
+
+class ThemeStore:
+    """
+    Store and manage design themes.
+
+    Handles persistence to user-level and project-level locations.
+    """
+
+    def __init__(self, project_dir: Optional[Path] = None):
+        """
+        Initialize theme store.
+
+        Args:
+            project_dir: Project directory for project-level themes
+        """
+        self.project_dir = project_dir
+        self._themes: Dict[str, Dict[str, Any]] = {}
+        self._active_theme: Optional[str] = None
+
+        # Load default theme
+        self._themes["default"] = DEFAULT_THEME.copy()
+
+    @property
+    def user_themes_dir(self) -> Path:
+        """User-level themes directory."""
+        return Path.home() / ".config" / "claude" / "themes"
+
+    @property
+    def project_themes_dir(self) -> Optional[Path]:
+        """Project-level themes directory."""
+        if self.project_dir:
+            return self.project_dir / ".viz-platform" / "themes"
+        return None
+
+    def load_themes(self) -> int:
+        """
+        Load themes from user and project directories.
+
+        Project themes take precedence over user themes.
+
+        Returns:
+            Number of themes loaded
+        """
+        count = 0
+
+        # Load user themes
+        if self.user_themes_dir.exists():
+            for theme_file in self.user_themes_dir.glob("*.json"):
+                try:
+                    with open(theme_file, 'r') as f:
+                        theme = json.load(f)
+                    name = theme.get('name', theme_file.stem)
+                    self._themes[name] = theme
+                    count += 1
+                    logger.debug(f"Loaded user theme: {name}")
+                except Exception as e:
+                    logger.warning(f"Failed to load theme {theme_file}: {e}")
+
+        # Load project themes (override user themes)
+        if self.project_themes_dir and self.project_themes_dir.exists():
+            for theme_file in self.project_themes_dir.glob("*.json"):
+                try:
+                    with open(theme_file, 'r') as f:
+                        theme = json.load(f)
+                    name = theme.get('name', theme_file.stem)
+                    self._themes[name] = theme
+                    count += 1
+                    logger.debug(f"Loaded project theme: {name}")
+                except Exception as e:
+                    logger.warning(f"Failed to load theme {theme_file}: {e}")
+
+        return count
+
+    def save_theme(
+        self,
+        theme: Dict[str, Any],
+        location: str = "project"
+    ) -> Path:
+        """
+        Save a theme to disk.
+
+        Args:
+            theme: Theme dict to save
+            location: "user" or "project"
+
+        Returns:
+            Path where theme was saved
+        """
+        name = theme.get('name', 'unnamed')
+
+        if location == "user":
+            target_dir = self.user_themes_dir
+        else:
+            target_dir = self.project_themes_dir
+            if not target_dir:
+                target_dir = self.user_themes_dir
+
+        target_dir.mkdir(parents=True, exist_ok=True)
+        theme_path = target_dir / f"{name}.json"
+
+        with open(theme_path, 'w') as f:
+            json.dump(theme, f, indent=2)
+
+        # Update in-memory store
+        self._themes[name] = theme
+
+        return theme_path
+
+    def get_theme(self, name: str) -> Optional[Dict[str, Any]]:
+        """Get a theme by name."""
+        return self._themes.get(name)
+
+    def list_themes(self) -> List[str]:
+        """List all available theme names."""
+        return list(self._themes.keys())
+
+    def set_active_theme(self, name: str) -> bool:
+        """
+        Set the active theme.
+
+        Args:
+            name: Theme name to activate
+
+        Returns:
+            True if theme was activated
+        """
+        if name in self._themes:
+            self._active_theme = name
+            return True
+        return False
+
+    def get_active_theme(self) -> Optional[Dict[str, Any]]:
+        """Get the currently active theme."""
+        if self._active_theme:
+            return self._themes.get(self._active_theme)
+        return None
+
+    def delete_theme(self, name: str) -> bool:
+        """
+        Delete a theme.
+
+        Args:
+            name: Theme name to delete
+
+        Returns:
+            True if theme was deleted
+        """
+        if name == "default":
+            return False  # Cannot delete default theme
+
+        if name in self._themes:
+            del self._themes[name]
+
+            # Remove file if exists
+            for themes_dir in [self.user_themes_dir, self.project_themes_dir]:
+                if themes_dir and themes_dir.exists():
+                    theme_path = themes_dir / f"{name}.json"
+                    if theme_path.exists():
+                        theme_path.unlink()
+
+            if self._active_theme == name:
+                self._active_theme = None
+
+            return True
+        return False

mcp-servers/viz-platform/mcp_server/theme_tools.py

@@ -0,0 +1,391 @@
+"""
+Theme management tools for viz-platform.
+
+Provides design token-based theming system for consistent visual styling.
+"""
+import copy
+import logging
+from typing import Dict, List, Optional, Any
+
+from .theme_store import ThemeStore, DEFAULT_THEME, REQUIRED_TOKEN_CATEGORIES
+
+logger = logging.getLogger(__name__)
+
+
+class ThemeTools:
+    """
+    Design token-based theming tools.
+
+    Creates and manages themes that integrate with DMC and Plotly.
+    """
+
+    def __init__(self, store: Optional[ThemeStore] = None):
+        """
+        Initialize theme tools.
+
+        Args:
+            store: Optional ThemeStore for persistence
+        """
+        self.store = store or ThemeStore()
+
+    async def theme_create(
+        self,
+        name: str,
+        tokens: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Create a new theme with design tokens.
+
+        Args:
+            name: Unique theme name
+            tokens: Design tokens dict with colors, spacing, typography, radii
+
+        Returns:
+            Dict with:
+                - name: Theme name
+                - tokens: Full token set (merged with defaults)
+                - validation: Validation results
+        """
+        # Check for name collision
+        if self.store.get_theme(name) and name != "default":
+            return {
+                "error": f"Theme '{name}' already exists. Use theme_extend to modify it.",
+                "name": name
+            }
+
+        # Start with default tokens and merge provided ones
+        theme_tokens = copy.deepcopy(DEFAULT_THEME["tokens"])
+        theme_tokens = self._deep_merge(theme_tokens, tokens)
+
+        # Create theme object
+        theme = {
+            "name": name,
+            "version": "1.0.0",
+            "tokens": theme_tokens
+        }
+
+        # Validate the theme
+        validation = self._validate_tokens(theme_tokens)
+
+        # Save to store
+        self.store._themes[name] = theme
+
+        return {
+            "name": name,
+            "tokens": theme_tokens,
+            "validation": validation,
+            "complete": validation["complete"]
+        }
+
+    async def theme_extend(
+        self,
+        base_theme: str,
+        overrides: Dict[str, Any],
+        new_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new theme by extending an existing one.
+
+        Args:
+            base_theme: Name of theme to extend
+            overrides: Token overrides to apply
+            new_name: Optional name for the new theme (defaults to base_theme_extended)
+
+        Returns:
+            Dict with the new theme or error
+        """
+        # Get base theme
+        base = self.store.get_theme(base_theme)
+        if not base:
+            available = self.store.list_themes()
+            return {
+                "error": f"Base theme '{base_theme}' not found. Available: {available}",
+                "name": None
+            }
+
+        # Determine new name
+        name = new_name or f"{base_theme}_extended"
+
+        # Check for collision
+        if self.store.get_theme(name) and name != base_theme:
+            return {
+                "error": f"Theme '{name}' already exists. Choose a different name.",
+                "name": name
+            }
+
+        # Merge tokens
+        theme_tokens = copy.deepcopy(base.get("tokens", {}))
+        theme_tokens = self._deep_merge(theme_tokens, overrides)
+
+        # Create theme
+        theme = {
+            "name": name,
+            "version": "1.0.0",
+            "extends": base_theme,
+            "tokens": theme_tokens
+        }
+
+        # Validate
+        validation = self._validate_tokens(theme_tokens)
+
+        # Save to store
+        self.store._themes[name] = theme
+
+        return {
+            "name": name,
+            "extends": base_theme,
+            "tokens": theme_tokens,
+            "validation": validation,
+            "complete": validation["complete"]
+        }
+
+    async def theme_validate(self, theme_name: str) -> Dict[str, Any]:
+        """
+        Validate a theme for completeness.
+
+        Args:
+            theme_name: Theme name to validate
+
+        Returns:
+            Dict with:
+                - valid: bool
+                - complete: bool (all optional tokens present)
+                - missing: List of missing required tokens
+                - warnings: List of warnings
+        """
+        theme = self.store.get_theme(theme_name)
+        if not theme:
+            available = self.store.list_themes()
+            return {
+                "error": f"Theme '{theme_name}' not found. Available: {available}",
+                "valid": False
+            }
+
+        tokens = theme.get("tokens", {})
+        validation = self._validate_tokens(tokens)
+
+        return {
+            "theme_name": theme_name,
+            "valid": validation["valid"],
+            "complete": validation["complete"],
+            "missing_required": validation["missing_required"],
+            "missing_optional": validation["missing_optional"],
+            "warnings": validation["warnings"]
+        }
+
+    async def theme_export_css(self, theme_name: str) -> Dict[str, Any]:
+        """
+        Export a theme as CSS custom properties.
+
+        Args:
+            theme_name: Theme name to export
+
+        Returns:
+            Dict with:
+                - css: CSS custom properties string
+                - variables: List of variable names
+        """
+        theme = self.store.get_theme(theme_name)
+        if not theme:
+            available = self.store.list_themes()
+            return {
+                "error": f"Theme '{theme_name}' not found. Available: {available}",
+                "css": None
+            }
+
+        tokens = theme.get("tokens", {})
+        css_vars = []
+        var_names = []
+
+        # Convert tokens to CSS custom properties
+        css_vars.append(f"/* Theme: {theme_name} */")
+        css_vars.append(":root {")
+
+        # Colors
+        colors = tokens.get("colors", {})
+        css_vars.append("  /* Colors */")
+        for key, value in self._flatten_tokens(colors, "color").items():
+            var_name = f"--{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Spacing
+        spacing = tokens.get("spacing", {})
+        css_vars.append("\n  /* Spacing */")
+        for key, value in spacing.items():
+            var_name = f"--spacing-{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Typography
+        typography = tokens.get("typography", {})
+        css_vars.append("\n  /* Typography */")
+        for key, value in self._flatten_tokens(typography, "font").items():
+            var_name = f"--{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Radii
+        radii = tokens.get("radii", {})
+        css_vars.append("\n  /* Border Radius */")
+        for key, value in radii.items():
+            var_name = f"--radius-{key}"
+            css_vars.append(f"  {var_name}: {value};")
+            var_names.append(var_name)
+
+        # Shadows
+        shadows = tokens.get("shadows", {})
+        if shadows:
+            css_vars.append("\n  /* Shadows */")
+            for key, value in shadows.items():
+                var_name = f"--shadow-{key}"
+                css_vars.append(f"  {var_name}: {value};")
+                var_names.append(var_name)
+
+        # Transitions
+        transitions = tokens.get("transitions", {})
+        if transitions:
+            css_vars.append("\n  /* Transitions */")
+            for key, value in transitions.items():
+                var_name = f"--transition-{key}"
+                css_vars.append(f"  {var_name}: {value};")
+                var_names.append(var_name)
+
+        css_vars.append("}")
+
+        css_content = "\n".join(css_vars)
+
+        return {
+            "theme_name": theme_name,
+            "css": css_content,
+            "variable_count": len(var_names),
+            "variables": var_names
+        }
+
+    async def theme_list(self) -> Dict[str, Any]:
+        """
+        List all available themes.
+
+        Returns:
+            Dict with theme names and active theme
+        """
+        themes = self.store.list_themes()
+        active = self.store._active_theme
+
+        theme_info = {}
+        for name in themes:
+            theme = self.store.get_theme(name)
+            theme_info[name] = {
+                "extends": theme.get("extends"),
+                "version": theme.get("version", "1.0.0")
+            }
+
+        return {
+            "themes": theme_info,
+            "active_theme": active,
+            "count": len(themes)
+        }
+
+    async def theme_activate(self, theme_name: str) -> Dict[str, Any]:
+        """
+        Set the active theme.
+
+        Args:
+            theme_name: Theme to activate
+
+        Returns:
+            Dict with activation status
+        """
+        if self.store.set_active_theme(theme_name):
+            return {
+                "active_theme": theme_name,
+                "success": True
+            }
+        return {
+            "error": f"Theme '{theme_name}' not found.",
+            "success": False
+        }
+
+    def _validate_tokens(self, tokens: Dict[str, Any]) -> Dict[str, Any]:
+        """Validate token structure and completeness."""
+        missing_required = []
+        missing_optional = []
+        warnings = []
+
+        # Check required categories
+        for category in REQUIRED_TOKEN_CATEGORIES:
+            if category not in tokens:
+                missing_required.append(category)
+
+        # Check colors structure
+        colors = tokens.get("colors", {})
+        required_colors = ["primary", "background", "text"]
+        for color in required_colors:
+            if color not in colors:
+                missing_required.append(f"colors.{color}")
+
+        # Check spacing
+        spacing = tokens.get("spacing", {})
+        required_spacing = ["xs", "sm", "md", "lg"]
+        for size in required_spacing:
+            if size not in spacing:
+                missing_optional.append(f"spacing.{size}")
+
+        # Check typography
+        typography = tokens.get("typography", {})
+        if "fontFamily" not in typography:
+            missing_optional.append("typography.fontFamily")
+        if "fontSize" not in typography:
+            missing_optional.append("typography.fontSize")
+
+        # Check radii
+        radii = tokens.get("radii", {})
+        if "sm" not in radii and "md" not in radii:
+            missing_optional.append("radii.sm or radii.md")
+
+        # Warnings for common issues
+        if "shadows" not in tokens:
+            warnings.append("No shadows defined - components may have no elevation")
+        if "transitions" not in tokens:
+            warnings.append("No transitions defined - animations will use defaults")
+
+        return {
+            "valid": len(missing_required) == 0,
+            "complete": len(missing_required) == 0 and len(missing_optional) == 0,
+            "missing_required": missing_required,
+            "missing_optional": missing_optional,
+            "warnings": warnings
+        }
+
+    def _deep_merge(
+        self,
+        base: Dict[str, Any],
+        override: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Deep merge two dictionaries."""
+        result = copy.deepcopy(base)
+
+        for key, value in override.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = self._deep_merge(result[key], value)
+            else:
+                result[key] = value
+
+        return result
+
+    def _flatten_tokens(
+        self,
+        tokens: Dict[str, Any],
+        prefix: str
+    ) -> Dict[str, str]:
+        """Flatten nested token dict for CSS export."""
+        result = {}
+
+        for key, value in tokens.items():
+            if isinstance(value, dict):
+                nested = self._flatten_tokens(value, f"{prefix}-{key}")
+                result.update(nested)
+            else:
+                result[f"{prefix}-{key}"] = str(value)
+
+        return result

mcp-servers/viz-platform/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viz-platform-mcp"
+version = "1.0.0"
+description = "MCP Server for visualization with Dash Mantine Components validation and theming"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Leo Miranda"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=0.9.0",
+    "plotly>=5.18.0",
+    "dash>=2.14.0",
+    "dash-mantine-components>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["mcp_server*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp-servers/viz-platform/registry/dmc_2_5.json

@@ -0,0 +1,668 @@
+{
+  "version": "2.5.1",
+  "generated": "2026-01-26",
+  "mantine_version": "7.x",
+  "categories": {
+    "buttons": ["Button", "ButtonGroup", "ActionIcon", "ActionIconGroup", "CopyButton", "CloseButton", "UnstyledButton"],
+    "inputs": [
+      "TextInput", "PasswordInput", "NumberInput", "Textarea", "Select", "MultiSelect",
+      "Checkbox", "CheckboxGroup", "CheckboxCard", "Switch", "Radio", "RadioGroup", "RadioCard",
+      "Slider", "RangeSlider", "ColorInput", "ColorPicker", "Autocomplete", "TagsInput",
+      "PinInput", "Rating", "SegmentedControl", "Chip", "ChipGroup", "JsonInput",
+      "NativeSelect", "FileInput", "Combobox"
+    ],
+    "navigation": ["Anchor", "Breadcrumbs", "Burger", "NavLink", "Pagination", "Stepper", "Tabs", "TabsList", "TabsTab", "TabsPanel"],
+    "feedback": ["Alert", "Loader", "Notification", "NotificationContainer", "Progress", "RingProgress", "Skeleton"],
+    "overlays": ["Modal", "Drawer", "DrawerStack", "Popover", "HoverCard", "Tooltip", "FloatingTooltip", "Menu", "MenuTarget", "MenuDropdown", "MenuItem", "Affix"],
+    "typography": ["Text", "Title", "Highlight", "Mark", "Code", "CodeHighlight", "Blockquote", "List", "ListItem", "Kbd"],
+    "layout": [
+      "AppShell", "AppShellHeader", "AppShellNavbar", "AppShellAside", "AppShellFooter", "AppShellMain", "AppShellSection",
+      "Container", "Center", "Stack", "Group", "Flex", "Grid", "GridCol", "SimpleGrid",
+      "Paper", "Card", "CardSection", "Box", "Space", "Divider", "AspectRatio", "ScrollArea"
+    ],
+    "data_display": [
+      "Accordion", "AccordionItem", "AccordionControl", "AccordionPanel",
+      "Avatar", "AvatarGroup", "Badge", "Image", "BackgroundImage",
+      "Indicator", "Spoiler", "Table", "ThemeIcon", "Timeline", "TimelineItem", "Tree"
+    ],
+    "charts": ["AreaChart", "BarChart", "LineChart", "PieChart", "DonutChart", "RadarChart", "ScatterChart", "BubbleChart", "CompositeChart", "Sparkline"],
+    "dates": ["DatePicker", "DateTimePicker", "DateInput", "DatePickerInput", "MonthPicker", "YearPicker", "TimePicker", "TimeInput", "Calendar", "MiniCalendar", "DatesProvider"]
+  },
+  "components": {
+    "Button": {
+      "description": "Button component for user interactions",
+      "props": {
+        "children": {"type": "any", "description": "Button content"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "transparent", "white", "subtle", "default", "gradient"], "default": "filled"},
+        "color": {"type": "string", "default": "blue", "description": "Key of theme.colors or CSS color"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl", "compact-xs", "compact-sm", "compact-md", "compact-lg", "compact-xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "disabled": {"type": "boolean", "default": false},
+        "loading": {"type": "boolean", "default": false},
+        "loaderProps": {"type": "object"},
+        "leftSection": {"type": "any", "description": "Content on the left side of label"},
+        "rightSection": {"type": "any", "description": "Content on the right side of label"},
+        "fullWidth": {"type": "boolean", "default": false},
+        "gradient": {"type": "object", "description": "Gradient for gradient variant"},
+        "justify": {"type": "string", "enum": ["center", "start", "end", "space-between"], "default": "center"},
+        "autoContrast": {"type": "boolean", "default": false},
+        "n_clicks": {"type": "integer", "default": 0, "description": "Dash callback trigger"}
+      }
+    },
+    "ActionIcon": {
+      "description": "Icon button without text label",
+      "props": {
+        "children": {"type": "any", "required": true, "description": "Icon element"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "transparent", "white", "subtle", "default", "gradient"], "default": "subtle"},
+        "color": {"type": "string", "default": "gray"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "disabled": {"type": "boolean", "default": false},
+        "loading": {"type": "boolean", "default": false},
+        "autoContrast": {"type": "boolean", "default": false},
+        "n_clicks": {"type": "integer", "default": 0}
+      }
+    },
+    "TextInput": {
+      "description": "Text input field",
+      "props": {
+        "value": {"type": "string", "default": ""},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "variant": {"type": "string", "enum": ["default", "filled", "unstyled"], "default": "default"},
+        "leftSection": {"type": "any"},
+        "rightSection": {"type": "any"},
+        "withAsterisk": {"type": "boolean", "default": false},
+        "debounce": {"type": "integer", "description": "Debounce delay in ms"},
+        "leftSectionPointerEvents": {"type": "string", "enum": ["none", "all"], "default": "none"},
+        "rightSectionPointerEvents": {"type": "string", "enum": ["none", "all"], "default": "none"}
+      }
+    },
+    "NumberInput": {
+      "description": "Numeric input with optional controls",
+      "props": {
+        "value": {"type": "number"},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "min": {"type": "number"},
+        "max": {"type": "number"},
+        "step": {"type": "number", "default": 1},
+        "hideControls": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "allowNegative": {"type": "boolean", "default": true},
+        "allowDecimal": {"type": "boolean", "default": true},
+        "clampBehavior": {"type": "string", "enum": ["strict", "blur", "none"], "default": "blur"},
+        "decimalScale": {"type": "integer"},
+        "fixedDecimalScale": {"type": "boolean", "default": false},
+        "thousandSeparator": {"type": "string"},
+        "decimalSeparator": {"type": "string"},
+        "prefix": {"type": "string"},
+        "suffix": {"type": "string"}
+      }
+    },
+    "Select": {
+      "description": "Dropdown select input",
+      "props": {
+        "value": {"type": "string"},
+        "data": {"type": "array", "required": true, "description": "Array of options: strings or {value, label} objects"},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "searchable": {"type": "boolean", "default": false},
+        "clearable": {"type": "boolean", "default": false},
+        "nothingFoundMessage": {"type": "string"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "maxDropdownHeight": {"type": "number", "default": 250},
+        "allowDeselect": {"type": "boolean", "default": true},
+        "checkIconPosition": {"type": "string", "enum": ["left", "right"], "default": "left"},
+        "comboboxProps": {"type": "object"},
+        "withScrollArea": {"type": "boolean", "default": true}
+      }
+    },
+    "MultiSelect": {
+      "description": "Multiple selection dropdown",
+      "props": {
+        "value": {"type": "array", "default": []},
+        "data": {"type": "array", "required": true},
+        "placeholder": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "searchable": {"type": "boolean", "default": false},
+        "clearable": {"type": "boolean", "default": false},
+        "maxValues": {"type": "integer"},
+        "hidePickedOptions": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "maxDropdownHeight": {"type": "number", "default": 250},
+        "withCheckIcon": {"type": "boolean", "default": true}
+      }
+    },
+    "Checkbox": {
+      "description": "Checkbox input",
+      "props": {
+        "checked": {"type": "boolean", "default": false},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "indeterminate": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "color": {"type": "string", "default": "blue"},
+        "labelPosition": {"type": "string", "enum": ["left", "right"], "default": "right"},
+        "autoContrast": {"type": "boolean", "default": false},
+        "icon": {"type": "any"},
+        "iconColor": {"type": "string"}
+      }
+    },
+    "Switch": {
+      "description": "Toggle switch input",
+      "props": {
+        "checked": {"type": "boolean", "default": false},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "color": {"type": "string", "default": "blue"},
+        "onLabel": {"type": "any"},
+        "offLabel": {"type": "any"},
+        "thumbIcon": {"type": "any"},
+        "labelPosition": {"type": "string", "enum": ["left", "right"], "default": "right"}
+      }
+    },
+    "Slider": {
+      "description": "Slider input for numeric values",
+      "props": {
+        "value": {"type": "number"},
+        "min": {"type": "number", "default": 0},
+        "max": {"type": "number", "default": 100},
+        "step": {"type": "number", "default": 1},
+        "label": {"type": "any"},
+        "disabled": {"type": "boolean", "default": false},
+        "marks": {"type": "array"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "color": {"type": "string", "default": "blue"},
+        "showLabelOnHover": {"type": "boolean", "default": true},
+        "labelAlwaysOn": {"type": "boolean", "default": false},
+        "thumbLabel": {"type": "string"},
+        "precision": {"type": "integer", "default": 0},
+        "inverted": {"type": "boolean", "default": false},
+        "thumbSize": {"type": "number"},
+        "restrictToMarks": {"type": "boolean", "default": false}
+      }
+    },
+    "Alert": {
+      "description": "Alert component for feedback messages",
+      "props": {
+        "children": {"type": "any"},
+        "title": {"type": "any"},
+        "color": {"type": "string", "default": "blue"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "default", "transparent", "white"], "default": "light"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "icon": {"type": "any"},
+        "withCloseButton": {"type": "boolean", "default": false},
+        "closeButtonLabel": {"type": "string"},
+        "autoContrast": {"type": "boolean", "default": false}
+      }
+    },
+    "Loader": {
+      "description": "Loading indicator",
+      "props": {
+        "color": {"type": "string", "default": "blue"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "type": {"type": "string", "enum": ["oval", "bars", "dots"], "default": "oval"}
+      }
+    },
+    "Progress": {
+      "description": "Progress bar",
+      "props": {
+        "value": {"type": "number", "required": true},
+        "color": {"type": "string", "default": "blue"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "striped": {"type": "boolean", "default": false},
+        "animated": {"type": "boolean", "default": false},
+        "autoContrast": {"type": "boolean", "default": false},
+        "transitionDuration": {"type": "number", "default": 100}
+      }
+    },
+    "Modal": {
+      "description": "Modal dialog overlay",
+      "props": {
+        "children": {"type": "any"},
+        "opened": {"type": "boolean", "required": true},
+        "title": {"type": "any"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl", "auto"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "centered": {"type": "boolean", "default": false},
+        "fullScreen": {"type": "boolean", "default": false},
+        "withCloseButton": {"type": "boolean", "default": true},
+        "closeOnClickOutside": {"type": "boolean", "default": true},
+        "closeOnEscape": {"type": "boolean", "default": true},
+        "overlayProps": {"type": "object"},
+        "padding": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "transitionProps": {"type": "object"},
+        "zIndex": {"type": "number", "default": 200},
+        "trapFocus": {"type": "boolean", "default": true},
+        "returnFocus": {"type": "boolean", "default": true},
+        "lockScroll": {"type": "boolean", "default": true}
+      }
+    },
+    "Drawer": {
+      "description": "Sliding panel drawer",
+      "props": {
+        "children": {"type": "any"},
+        "opened": {"type": "boolean", "required": true},
+        "title": {"type": "any"},
+        "position": {"type": "string", "enum": ["left", "right", "top", "bottom"], "default": "left"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "withCloseButton": {"type": "boolean", "default": true},
+        "closeOnClickOutside": {"type": "boolean", "default": true},
+        "closeOnEscape": {"type": "boolean", "default": true},
+        "overlayProps": {"type": "object"},
+        "padding": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "zIndex": {"type": "number", "default": 200},
+        "offset": {"type": "number", "default": 0},
+        "trapFocus": {"type": "boolean", "default": true},
+        "returnFocus": {"type": "boolean", "default": true},
+        "lockScroll": {"type": "boolean", "default": true}
+      }
+    },
+    "Tooltip": {
+      "description": "Tooltip on hover",
+      "props": {
+        "children": {"type": "any", "required": true},
+        "label": {"type": "any", "required": true},
+        "position": {"type": "string", "enum": ["top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end"], "default": "top"},
+        "color": {"type": "string"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "withArrow": {"type": "boolean", "default": false},
+        "arrowSize": {"type": "number", "default": 4},
+        "arrowOffset": {"type": "number", "default": 5},
+        "offset": {"type": "number", "default": 5},
+        "multiline": {"type": "boolean", "default": false},
+        "disabled": {"type": "boolean", "default": false},
+        "openDelay": {"type": "number", "default": 0},
+        "closeDelay": {"type": "number", "default": 0},
+        "transitionProps": {"type": "object"},
+        "zIndex": {"type": "number", "default": 300}
+      }
+    },
+    "Text": {
+      "description": "Text component with styling",
+      "props": {
+        "children": {"type": "any"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "c": {"type": "string", "description": "Color"},
+        "fw": {"type": "number", "description": "Font weight"},
+        "fs": {"type": "string", "enum": ["normal", "italic"], "description": "Font style"},
+        "td": {"type": "string", "enum": ["none", "underline", "line-through"], "description": "Text decoration"},
+        "tt": {"type": "string", "enum": ["none", "capitalize", "uppercase", "lowercase"], "description": "Text transform"},
+        "ta": {"type": "string", "enum": ["left", "center", "right", "justify"], "description": "Text align"},
+        "lineClamp": {"type": "integer"},
+        "truncate": {"type": "boolean", "default": false},
+        "inherit": {"type": "boolean", "default": false},
+        "gradient": {"type": "object"},
+        "span": {"type": "boolean", "default": false},
+        "lh": {"type": "string", "description": "Line height"}
+      }
+    },
+    "Title": {
+      "description": "Heading component",
+      "props": {
+        "children": {"type": "any"},
+        "order": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6], "default": 1},
+        "size": {"type": "string"},
+        "c": {"type": "string", "description": "Color"},
+        "ta": {"type": "string", "enum": ["left", "center", "right", "justify"]},
+        "td": {"type": "string", "enum": ["none", "underline", "line-through"]},
+        "tt": {"type": "string", "enum": ["none", "capitalize", "uppercase", "lowercase"]},
+        "lineClamp": {"type": "integer"},
+        "truncate": {"type": "boolean", "default": false}
+      }
+    },
+    "Stack": {
+      "description": "Vertical stack layout",
+      "props": {
+        "children": {"type": "any"},
+        "gap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end"], "default": "stretch"},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly"], "default": "flex-start"}
+      }
+    },
+    "Group": {
+      "description": "Horizontal group layout",
+      "props": {
+        "children": {"type": "any"},
+        "gap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end"], "default": "center"},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around"], "default": "flex-start"},
+        "grow": {"type": "boolean", "default": false},
+        "wrap": {"type": "string", "enum": ["wrap", "nowrap", "wrap-reverse"], "default": "wrap"},
+        "preventGrowOverflow": {"type": "boolean", "default": true}
+      }
+    },
+    "Flex": {
+      "description": "Flexbox container",
+      "props": {
+        "children": {"type": "any"},
+        "gap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "rowGap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "columnGap": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end", "baseline"]},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly"]},
+        "wrap": {"type": "string", "enum": ["wrap", "nowrap", "wrap-reverse"], "default": "nowrap"},
+        "direction": {"type": "string", "enum": ["row", "column", "row-reverse", "column-reverse"], "default": "row"}
+      }
+    },
+    "Grid": {
+      "description": "Grid layout component",
+      "props": {
+        "children": {"type": "any"},
+        "columns": {"type": "integer", "default": 12},
+        "gutter": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "grow": {"type": "boolean", "default": false},
+        "justify": {"type": "string", "enum": ["flex-start", "flex-end", "center", "space-between", "space-around"], "default": "flex-start"},
+        "align": {"type": "string", "enum": ["stretch", "center", "flex-start", "flex-end"], "default": "stretch"},
+        "overflow": {"type": "string", "enum": ["visible", "hidden"], "default": "visible"}
+      }
+    },
+    "SimpleGrid": {
+      "description": "Simple grid with equal columns",
+      "props": {
+        "children": {"type": "any"},
+        "cols": {"type": "integer", "default": 1},
+        "spacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "verticalSpacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]}
+      }
+    },
+    "Container": {
+      "description": "Centered container with max-width",
+      "props": {
+        "children": {"type": "any"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "fluid": {"type": "boolean", "default": false}
+      }
+    },
+    "Paper": {
+      "description": "Paper surface component",
+      "props": {
+        "children": {"type": "any"},
+        "shadow": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "p": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "description": "Padding"},
+        "withBorder": {"type": "boolean", "default": false}
+      }
+    },
+    "Card": {
+      "description": "Card container",
+      "props": {
+        "children": {"type": "any"},
+        "shadow": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "padding": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "withBorder": {"type": "boolean", "default": false}
+      }
+    },
+    "Tabs": {
+      "description": "Tabbed interface",
+      "props": {
+        "children": {"type": "any"},
+        "value": {"type": "string"},
+        "defaultValue": {"type": "string"},
+        "orientation": {"type": "string", "enum": ["horizontal", "vertical"], "default": "horizontal"},
+        "variant": {"type": "string", "enum": ["default", "outline", "pills"], "default": "default"},
+        "color": {"type": "string", "default": "blue"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "placement": {"type": "string", "enum": ["left", "right"], "default": "left"},
+        "grow": {"type": "boolean", "default": false},
+        "inverted": {"type": "boolean", "default": false},
+        "keepMounted": {"type": "boolean", "default": true},
+        "activateTabWithKeyboard": {"type": "boolean", "default": true},
+        "allowTabDeactivation": {"type": "boolean", "default": false},
+        "autoContrast": {"type": "boolean", "default": false}
+      }
+    },
+    "Accordion": {
+      "description": "Collapsible content panels",
+      "props": {
+        "children": {"type": "any"},
+        "value": {"type": "any"},
+        "defaultValue": {"type": "any"},
+        "multiple": {"type": "boolean", "default": false},
+        "variant": {"type": "string", "enum": ["default", "contained", "filled", "separated"], "default": "default"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "chevronPosition": {"type": "string", "enum": ["left", "right"], "default": "right"},
+        "disableChevronRotation": {"type": "boolean", "default": false},
+        "transitionDuration": {"type": "number", "default": 200},
+        "chevronSize": {"type": "any"},
+        "order": {"type": "integer", "enum": [2, 3, 4, 5, 6]}
+      }
+    },
+    "Badge": {
+      "description": "Badge for status or labels",
+      "props": {
+        "children": {"type": "any"},
+        "color": {"type": "string", "default": "blue"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "dot", "gradient", "default", "transparent", "white"], "default": "filled"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "fullWidth": {"type": "boolean", "default": false},
+        "leftSection": {"type": "any"},
+        "rightSection": {"type": "any"},
+        "autoContrast": {"type": "boolean", "default": false},
+        "circle": {"type": "boolean", "default": false}
+      }
+    },
+    "Avatar": {
+      "description": "User avatar image",
+      "props": {
+        "src": {"type": "string"},
+        "alt": {"type": "string"},
+        "children": {"type": "any", "description": "Fallback content"},
+        "color": {"type": "string", "default": "gray"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "md"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xl"},
+        "variant": {"type": "string", "enum": ["filled", "light", "outline", "gradient", "default", "transparent", "white"], "default": "filled"},
+        "autoContrast": {"type": "boolean", "default": false}
+      }
+    },
+    "Image": {
+      "description": "Image with fallback",
+      "props": {
+        "src": {"type": "string"},
+        "alt": {"type": "string"},
+        "w": {"type": "any", "description": "Width"},
+        "h": {"type": "any", "description": "Height"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"]},
+        "fit": {"type": "string", "enum": ["contain", "cover", "fill", "none", "scale-down"], "default": "cover"},
+        "fallbackSrc": {"type": "string"}
+      }
+    },
+    "Table": {
+      "description": "Data table component",
+      "props": {
+        "children": {"type": "any"},
+        "data": {"type": "object", "description": "Table data object with head, body, foot"},
+        "striped": {"type": "boolean", "default": false},
+        "highlightOnHover": {"type": "boolean", "default": false},
+        "withTableBorder": {"type": "boolean", "default": false},
+        "withColumnBorders": {"type": "boolean", "default": false},
+        "withRowBorders": {"type": "boolean", "default": true},
+        "verticalSpacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xs"},
+        "horizontalSpacing": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "xs"},
+        "captionSide": {"type": "string", "enum": ["top", "bottom"], "default": "bottom"},
+        "stickyHeader": {"type": "boolean", "default": false},
+        "stickyHeaderOffset": {"type": "number", "default": 0}
+      }
+    },
+    "AreaChart": {
+      "description": "Area chart for time series data",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "dataKey": {"type": "string", "required": true, "description": "X-axis data key"},
+        "series": {"type": "array", "required": true, "description": "Array of {name, color} objects"},
+        "h": {"type": "any", "description": "Chart height"},
+        "w": {"type": "any", "description": "Chart width"},
+        "curveType": {"type": "string", "enum": ["bump", "linear", "natural", "monotone", "step", "stepBefore", "stepAfter"], "default": "monotone"},
+        "connectNulls": {"type": "boolean", "default": true},
+        "withDots": {"type": "boolean", "default": true},
+        "withGradient": {"type": "boolean", "default": true},
+        "withLegend": {"type": "boolean", "default": false},
+        "withTooltip": {"type": "boolean", "default": true},
+        "withXAxis": {"type": "boolean", "default": true},
+        "withYAxis": {"type": "boolean", "default": true},
+        "gridAxis": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "x"},
+        "tickLine": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "y"},
+        "strokeDasharray": {"type": "string"},
+        "fillOpacity": {"type": "number", "default": 0.2},
+        "splitColors": {"type": "array"},
+        "areaChartProps": {"type": "object"},
+        "type": {"type": "string", "enum": ["default", "stacked", "percent", "split"], "default": "default"}
+      }
+    },
+    "BarChart": {
+      "description": "Bar chart for categorical data",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "dataKey": {"type": "string", "required": true},
+        "series": {"type": "array", "required": true},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "orientation": {"type": "string", "enum": ["horizontal", "vertical"], "default": "vertical"},
+        "withLegend": {"type": "boolean", "default": false},
+        "withTooltip": {"type": "boolean", "default": true},
+        "withXAxis": {"type": "boolean", "default": true},
+        "withYAxis": {"type": "boolean", "default": true},
+        "gridAxis": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "x"},
+        "tickLine": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "y"},
+        "barProps": {"type": "object"},
+        "type": {"type": "string", "enum": ["default", "stacked", "percent", "waterfall"], "default": "default"}
+      }
+    },
+    "LineChart": {
+      "description": "Line chart for trends",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "dataKey": {"type": "string", "required": true},
+        "series": {"type": "array", "required": true},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "curveType": {"type": "string", "enum": ["bump", "linear", "natural", "monotone", "step", "stepBefore", "stepAfter"], "default": "monotone"},
+        "connectNulls": {"type": "boolean", "default": true},
+        "withDots": {"type": "boolean", "default": true},
+        "withLegend": {"type": "boolean", "default": false},
+        "withTooltip": {"type": "boolean", "default": true},
+        "withXAxis": {"type": "boolean", "default": true},
+        "withYAxis": {"type": "boolean", "default": true},
+        "gridAxis": {"type": "string", "enum": ["x", "y", "xy", "none"], "default": "x"},
+        "strokeWidth": {"type": "number", "default": 2}
+      }
+    },
+    "PieChart": {
+      "description": "Pie chart for proportions",
+      "props": {
+        "data": {"type": "array", "required": true, "description": "Array of {name, value, color} objects"},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "withLabels": {"type": "boolean", "default": false},
+        "withLabelsLine": {"type": "boolean", "default": true},
+        "withTooltip": {"type": "boolean", "default": true},
+        "labelsPosition": {"type": "string", "enum": ["inside", "outside"], "default": "outside"},
+        "labelsType": {"type": "string", "enum": ["value", "percent"], "default": "value"},
+        "strokeWidth": {"type": "number", "default": 1},
+        "strokeColor": {"type": "string"},
+        "startAngle": {"type": "number", "default": 0},
+        "endAngle": {"type": "number", "default": 360}
+      }
+    },
+    "DonutChart": {
+      "description": "Donut chart (pie with hole)",
+      "props": {
+        "data": {"type": "array", "required": true},
+        "h": {"type": "any"},
+        "w": {"type": "any"},
+        "withLabels": {"type": "boolean", "default": false},
+        "withLabelsLine": {"type": "boolean", "default": true},
+        "withTooltip": {"type": "boolean", "default": true},
+        "thickness": {"type": "number", "default": 20},
+        "chartLabel": {"type": "any"},
+        "strokeWidth": {"type": "number", "default": 1},
+        "strokeColor": {"type": "string"},
+        "startAngle": {"type": "number", "default": 0},
+        "endAngle": {"type": "number", "default": 360},
+        "paddingAngle": {"type": "number", "default": 0}
+      }
+    },
+    "DatePicker": {
+      "description": "Date picker calendar",
+      "props": {
+        "value": {"type": "string"},
+        "type": {"type": "string", "enum": ["default", "range", "multiple"], "default": "default"},
+        "defaultValue": {"type": "any"},
+        "allowDeselect": {"type": "boolean", "default": false},
+        "allowSingleDateInRange": {"type": "boolean", "default": false},
+        "numberOfColumns": {"type": "integer", "default": 1},
+        "columnsToScroll": {"type": "integer", "default": 1},
+        "ariaLabels": {"type": "object"},
+        "hideOutsideDates": {"type": "boolean", "default": false},
+        "hideWeekdays": {"type": "boolean", "default": false},
+        "weekendDays": {"type": "array", "default": [0, 6]},
+        "renderDay": {"type": "any"},
+        "minDate": {"type": "string"},
+        "maxDate": {"type": "string"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"}
+      }
+    },
+    "DatePickerInput": {
+      "description": "Date picker input field",
+      "props": {
+        "value": {"type": "string"},
+        "label": {"type": "any"},
+        "description": {"type": "any"},
+        "error": {"type": "any"},
+        "placeholder": {"type": "string"},
+        "clearable": {"type": "boolean", "default": false},
+        "type": {"type": "string", "enum": ["default", "range", "multiple"], "default": "default"},
+        "valueFormat": {"type": "string", "default": "MMMM D, YYYY"},
+        "size": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "radius": {"type": "string", "enum": ["xs", "sm", "md", "lg", "xl"], "default": "sm"},
+        "disabled": {"type": "boolean", "default": false},
+        "required": {"type": "boolean", "default": false},
+        "minDate": {"type": "string"},
+        "maxDate": {"type": "string"},
+        "popoverProps": {"type": "object"},
+        "dropdownType": {"type": "string", "enum": ["popover", "modal"], "default": "popover"}
+      }
+    },
+    "DatesProvider": {
+      "description": "Provider for date localization settings",
+      "props": {
+        "children": {"type": "any", "required": true},
+        "settings": {"type": "object", "description": "Locale and formatting settings"}
+      }
+    }
+  }
+}

mcp-servers/viz-platform/requirements.txt

@@ -0,0 +1,15 @@
+# MCP SDK
+mcp>=0.9.0
+
+# Visualization
+plotly>=5.18.0
+dash>=2.14.0
+dash-mantine-components>=2.0.0
+
+# Utilities
+python-dotenv>=1.0.0
+pydantic>=2.5.0
+
+# Testing
+pytest>=7.4.3
+pytest-asyncio>=0.23.0

mcp-servers/viz-platform/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_VENV="$HOME/.cache/claude-mcp-venvs/leo-claude-mktplace/viz-platform/.venv"
+LOCAL_VENV="$SCRIPT_DIR/.venv"
+
+if [[ -f "$CACHE_VENV/bin/python" ]]; then
+    PYTHON="$CACHE_VENV/bin/python"
+elif [[ -f "$LOCAL_VENV/bin/python" ]]; then
+    PYTHON="$LOCAL_VENV/bin/python"
+else
+    echo "ERROR: No venv found. Run: ./scripts/setup-venvs.sh" >&2
+    exit 1
+fi
+
+cd "$SCRIPT_DIR"
+export PYTHONPATH="$SCRIPT_DIR"
+exec "$PYTHON" -m mcp_server.server "$@"

mcp-servers/viz-platform/scripts/generate-dmc-registry.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+Generate DMC Component Registry from installed dash-mantine-components package.
+
+This script introspects the installed DMC package and generates a JSON registry
+file containing component definitions, props, types, and defaults.
+
+Usage:
+    python generate-dmc-registry.py [--output registry/dmc_X_Y.json]
+
+Requirements:
+    - dash-mantine-components must be installed
+    - Run from the mcp-servers/viz-platform directory
+"""
+import argparse
+import inspect
+import json
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Any, Dict, List, Optional, get_type_hints
+
+
+def get_dmc_version() -> Optional[str]:
+    """Get installed DMC version."""
+    try:
+        from importlib.metadata import version
+        return version('dash-mantine-components')
+    except Exception:
+        return None
+
+
+def get_component_categories() -> Dict[str, List[str]]:
+    """Define component categories."""
+    return {
+        "buttons": ["Button", "ActionIcon", "CopyButton", "FileButton", "UnstyledButton"],
+        "inputs": [
+            "TextInput", "PasswordInput", "NumberInput", "Textarea",
+            "Select", "MultiSelect", "Checkbox", "Switch", "Radio",
+            "Slider", "RangeSlider", "ColorInput", "ColorPicker",
+            "DateInput", "DatePicker", "TimeInput"
+        ],
+        "navigation": ["Anchor", "Breadcrumbs", "Burger", "NavLink", "Pagination", "Stepper", "Tabs"],
+        "feedback": ["Alert", "Loader", "Notification", "Progress", "RingProgress", "Skeleton"],
+        "overlays": ["Dialog", "Drawer", "HoverCard", "Menu", "Modal", "Popover", "Tooltip"],
+        "typography": ["Blockquote", "Code", "Highlight", "Mark", "Text", "Title"],
+        "layout": [
+            "AppShell", "AspectRatio", "Center", "Container", "Flex",
+            "Grid", "Group", "Paper", "SimpleGrid", "Space", "Stack"
+        ],
+        "data": [
+            "Accordion", "Avatar", "Badge", "Card", "Image",
+            "Indicator", "Kbd", "Spoiler", "Table", "ThemeIcon", "Timeline"
+        ]
+    }
+
+
+def extract_prop_type(prop_info: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract prop type information from Dash component prop."""
+    result = {"type": "any"}
+
+    if 'type' not in prop_info:
+        return result
+
+    prop_type = prop_info['type']
+
+    if isinstance(prop_type, dict):
+        type_name = prop_type.get('name', 'any')
+
+        # Map Dash types to JSON schema types
+        type_mapping = {
+            'string': 'string',
+            'number': 'number',
+            'bool': 'boolean',
+            'boolean': 'boolean',
+            'array': 'array',
+            'object': 'object',
+            'node': 'any',
+            'element': 'any',
+            'any': 'any',
+            'func': 'any',
+        }
+
+        result['type'] = type_mapping.get(type_name, 'any')
+
+        # Handle enums
+        if type_name == 'enum' and 'value' in prop_type:
+            values = prop_type['value']
+            if isinstance(values, list):
+                enum_values = []
+                for v in values:
+                    if isinstance(v, dict) and 'value' in v:
+                        # Remove quotes from string values
+                        val = v['value'].strip("'\"")
+                        enum_values.append(val)
+                    elif isinstance(v, str):
+                        enum_values.append(v.strip("'\""))
+                if enum_values:
+                    result['enum'] = enum_values
+                    result['type'] = 'string'
+
+        # Handle union types
+        elif type_name == 'union' and 'value' in prop_type:
+            # For unions, just mark as any for simplicity
+            result['type'] = 'any'
+
+    elif isinstance(prop_type, str):
+        result['type'] = prop_type
+
+    return result
+
+
+def extract_component_props(component_class) -> Dict[str, Any]:
+    """Extract props from a Dash component class."""
+    props = {}
+
+    # Try to get _prop_names or similar
+    if hasattr(component_class, '_prop_names'):
+        prop_names = component_class._prop_names
+    else:
+        prop_names = []
+
+    # Try to get _type attribute for prop definitions
+    if hasattr(component_class, '_type'):
+        prop_types = getattr(component_class, '_type', {})
+    else:
+        prop_types = {}
+
+    # Get default values
+    if hasattr(component_class, '_default_props'):
+        defaults = component_class._default_props
+    else:
+        defaults = {}
+
+    # Try to extract from _prop_descriptions
+    if hasattr(component_class, '_prop_descriptions'):
+        descriptions = component_class._prop_descriptions
+    else:
+        descriptions = {}
+
+    for prop_name in prop_names:
+        if prop_name.startswith('_'):
+            continue
+
+        prop_info = {}
+
+        # Get type info if available
+        if prop_name in prop_types:
+            prop_info = extract_prop_type({'type': prop_types[prop_name]})
+        else:
+            prop_info = {'type': 'any'}
+
+        # Add default if exists
+        if prop_name in defaults:
+            prop_info['default'] = defaults[prop_name]
+
+        # Add description if exists
+        if prop_name in descriptions:
+            prop_info['description'] = descriptions[prop_name]
+
+        props[prop_name] = prop_info
+
+    return props
+
+
+def generate_registry() -> Dict[str, Any]:
+    """Generate the component registry from installed DMC."""
+    try:
+        import dash_mantine_components as dmc
+    except ImportError:
+        print("ERROR: dash-mantine-components not installed")
+        print("Install with: pip install dash-mantine-components")
+        sys.exit(1)
+
+    version = get_dmc_version()
+    categories = get_component_categories()
+
+    registry = {
+        "version": version,
+        "generated": date.today().isoformat(),
+        "categories": categories,
+        "components": {}
+    }
+
+    # Get all components from categories
+    all_components = set()
+    for comp_list in categories.values():
+        all_components.update(comp_list)
+
+    # Extract props for each component
+    for comp_name in sorted(all_components):
+        if hasattr(dmc, comp_name):
+            comp_class = getattr(dmc, comp_name)
+            try:
+                props = extract_component_props(comp_class)
+                if props:
+                    registry["components"][comp_name] = {
+                        "description": comp_class.__doc__ or f"{comp_name} component",
+                        "props": props
+                    }
+                    print(f"  Extracted: {comp_name} ({len(props)} props)")
+            except Exception as e:
+                print(f"  Warning: Failed to extract {comp_name}: {e}")
+        else:
+            print(f"  Warning: Component not found: {comp_name}")
+
+    return registry
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate DMC component registry from installed package"
+    )
+    parser.add_argument(
+        '--output', '-o',
+        type=str,
+        help='Output file path (default: auto-generated based on version)'
+    )
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Print to stdout instead of writing file'
+    )
+
+    args = parser.parse_args()
+
+    print("Generating DMC Component Registry...")
+    print("=" * 50)
+
+    registry = generate_registry()
+
+    print("=" * 50)
+    print(f"Generated registry for DMC {registry['version']}")
+    print(f"Total components: {len(registry['components'])}")
+
+    if args.dry_run:
+        print(json.dumps(registry, indent=2))
+        return
+
+    # Determine output path
+    if args.output:
+        output_path = Path(args.output)
+    else:
+        version = registry['version']
+        if version:
+            major_minor = '_'.join(version.split('.')[:2])
+            output_path = Path(__file__).parent.parent / 'registry' / f'dmc_{major_minor}.json'
+        else:
+            output_path = Path(__file__).parent.parent / 'registry' / 'dmc_unknown.json'
+
+    # Create directory if needed
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write registry
+    with open(output_path, 'w') as f:
+        json.dump(registry, indent=2, fp=f)
+
+    print(f"Registry written to: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

mcp-servers/viz-platform/tests/__init__.py

@@ -0,0 +1 @@
+"""viz-platform MCP Server tests."""

mcp-servers/viz-platform/tests/test_chart_tools.py

@@ -0,0 +1,271 @@
+"""
+Unit tests for chart creation tools.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def chart_tools():
+    """Create ChartTools instance"""
+    from mcp_server.chart_tools import ChartTools
+    return ChartTools()
+
+
+@pytest.fixture
+def chart_tools_with_theme():
+    """Create ChartTools instance with a theme"""
+    from mcp_server.chart_tools import ChartTools
+
+    tools = ChartTools()
+    tools.set_theme({
+        "colors": {
+            "primary": "#ff0000",
+            "secondary": "#00ff00",
+            "success": "#0000ff"
+        }
+    })
+    return tools
+
+
+def test_chart_tools_init():
+    """Test chart tools initialization"""
+    from mcp_server.chart_tools import ChartTools
+
+    tools = ChartTools()
+
+    assert tools.theme_store is None
+    assert tools._active_theme is None
+
+
+def test_set_theme(chart_tools):
+    """Test setting active theme"""
+    theme = {"colors": {"primary": "#123456"}}
+
+    chart_tools.set_theme(theme)
+
+    assert chart_tools._active_theme == theme
+
+
+def test_get_color_palette_default(chart_tools):
+    """Test getting default color palette"""
+    from mcp_server.chart_tools import DEFAULT_COLORS
+
+    palette = chart_tools._get_color_palette()
+
+    assert palette == DEFAULT_COLORS
+
+
+def test_get_color_palette_with_theme(chart_tools_with_theme):
+    """Test getting color palette from theme"""
+    palette = chart_tools_with_theme._get_color_palette()
+
+    # Should start with theme colors
+    assert palette[0] == "#ff0000"
+    assert palette[1] == "#00ff00"
+    assert palette[2] == "#0000ff"
+
+
+def test_resolve_color_from_theme(chart_tools_with_theme):
+    """Test resolving color token from theme"""
+    color = chart_tools_with_theme._resolve_color("primary")
+
+    assert color == "#ff0000"
+
+
+def test_resolve_color_hex(chart_tools):
+    """Test resolving hex color"""
+    color = chart_tools._resolve_color("#abcdef")
+
+    assert color == "#abcdef"
+
+
+def test_resolve_color_rgb(chart_tools):
+    """Test resolving rgb color"""
+    color = chart_tools._resolve_color("rgb(255, 0, 0)")
+
+    assert color == "rgb(255, 0, 0)"
+
+
+def test_resolve_color_named(chart_tools):
+    """Test resolving named color"""
+    color = chart_tools._resolve_color("blue")
+
+    assert color == "#228be6"  # DEFAULT_COLORS[0]
+
+
+def test_resolve_color_none(chart_tools):
+    """Test resolving None color defaults to first palette color"""
+    from mcp_server.chart_tools import DEFAULT_COLORS
+
+    color = chart_tools._resolve_color(None)
+
+    assert color == DEFAULT_COLORS[0]
+
+
+@pytest.mark.asyncio
+async def test_chart_create_line(chart_tools):
+    """Test creating a line chart"""
+    data = {
+        "x": [1, 2, 3, 4, 5],
+        "y": [10, 20, 15, 25, 30]
+    }
+
+    result = await chart_tools.chart_create("line", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "line"
+    assert "error" not in result or result["error"] is None
+
+
+@pytest.mark.asyncio
+async def test_chart_create_bar(chart_tools):
+    """Test creating a bar chart"""
+    data = {
+        "x": ["A", "B", "C"],
+        "y": [10, 20, 15]
+    }
+
+    result = await chart_tools.chart_create("bar", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "bar"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_scatter(chart_tools):
+    """Test creating a scatter chart"""
+    data = {
+        "x": [1, 2, 3, 4, 5],
+        "y": [10, 20, 15, 25, 30]
+    }
+
+    result = await chart_tools.chart_create("scatter", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "scatter"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_pie(chart_tools):
+    """Test creating a pie chart"""
+    data = {
+        "labels": ["A", "B", "C"],
+        "values": [30, 50, 20]
+    }
+
+    result = await chart_tools.chart_create("pie", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "pie"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_histogram(chart_tools):
+    """Test creating a histogram"""
+    data = {
+        "x": [1, 1, 2, 2, 2, 3, 3, 4, 5, 5, 5, 5]
+    }
+
+    result = await chart_tools.chart_create("histogram", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "histogram"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_area(chart_tools):
+    """Test creating an area chart"""
+    data = {
+        "x": [1, 2, 3, 4, 5],
+        "y": [10, 20, 15, 25, 30]
+    }
+
+    result = await chart_tools.chart_create("area", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "area"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_heatmap(chart_tools):
+    """Test creating a heatmap"""
+    data = {
+        "z": [[1, 2, 3], [4, 5, 6], [7, 8, 9]],
+        "x": ["A", "B", "C"],
+        "y": ["X", "Y", "Z"]
+    }
+
+    result = await chart_tools.chart_create("heatmap", data)
+
+    assert "figure" in result
+    assert result["chart_type"] == "heatmap"
+
+
+@pytest.mark.asyncio
+async def test_chart_create_invalid_type(chart_tools):
+    """Test creating chart with invalid type"""
+    data = {"x": [1, 2, 3], "y": [10, 20, 30]}
+
+    result = await chart_tools.chart_create("invalid_type", data)
+
+    assert "error" in result
+    assert "invalid" in result["error"].lower()
+
+
+@pytest.mark.asyncio
+async def test_chart_create_with_options(chart_tools):
+    """Test creating chart with options"""
+    data = {
+        "x": [1, 2, 3],
+        "y": [10, 20, 30]
+    }
+    options = {
+        "title": "My Chart",
+        "color": "red"
+    }
+
+    result = await chart_tools.chart_create("line", data, options=options)
+
+    assert "figure" in result
+    # The title should be applied to the figure
+
+
+@pytest.mark.asyncio
+async def test_chart_create_with_theme(chart_tools_with_theme):
+    """Test that theme colors are applied to chart"""
+    data = {
+        "x": [1, 2, 3],
+        "y": [10, 20, 30]
+    }
+
+    result = await chart_tools_with_theme.chart_create("line", data)
+
+    assert "figure" in result
+    # Chart should use theme colors
+
+
+@pytest.mark.asyncio
+async def test_chart_configure_interaction(chart_tools):
+    """Test configuring chart interaction"""
+    # Create a simple figure first
+    data = {"x": [1, 2, 3], "y": [10, 20, 30]}
+    chart_result = await chart_tools.chart_create("line", data)
+    figure = chart_result.get("figure", {})
+
+    if hasattr(chart_tools, 'chart_configure_interaction'):
+        result = await chart_tools.chart_configure_interaction(
+            figure=figure,
+            interactions={"zoom": True, "pan": True}
+        )
+
+        # Just verify it doesn't crash
+        assert result is not None
+
+
+def test_default_colors_defined():
+    """Test that DEFAULT_COLORS is properly defined"""
+    from mcp_server.chart_tools import DEFAULT_COLORS
+
+    assert len(DEFAULT_COLORS) == 10
+    assert all(c.startswith("#") for c in DEFAULT_COLORS)

mcp-servers/viz-platform/tests/test_component_registry.py

@@ -0,0 +1,292 @@
+"""
+Unit tests for DMC component registry.
+"""
+import pytest
+import json
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+@pytest.fixture
+def sample_registry_data():
+    """Sample registry data for testing"""
+    return {
+        "version": "2.5.1",
+        "categories": {
+            "buttons": ["Button", "ActionIcon"],
+            "inputs": ["TextInput", "NumberInput", "Select"]
+        },
+        "components": {
+            "Button": {
+                "description": "Button component",
+                "props": {
+                    "variant": {
+                        "type": "string",
+                        "enum": ["filled", "outline", "light"],
+                        "default": "filled"
+                    },
+                    "color": {
+                        "type": "string",
+                        "default": "blue"
+                    },
+                    "size": {
+                        "type": "string",
+                        "enum": ["xs", "sm", "md", "lg", "xl"],
+                        "default": "sm"
+                    },
+                    "disabled": {
+                        "type": "boolean",
+                        "default": False
+                    }
+                }
+            },
+            "TextInput": {
+                "description": "Text input field",
+                "props": {
+                    "value": {"type": "string", "default": ""},
+                    "placeholder": {"type": "string"},
+                    "disabled": {"type": "boolean", "default": False},
+                    "required": {"type": "boolean", "default": False}
+                }
+            }
+        }
+    }
+
+
+@pytest.fixture
+def registry_file(tmp_path, sample_registry_data):
+    """Create a temporary registry file"""
+    registry_dir = tmp_path / "registry"
+    registry_dir.mkdir()
+    registry_file = registry_dir / "dmc_2_5.json"
+    registry_file.write_text(json.dumps(sample_registry_data))
+    return registry_file
+
+
+@pytest.fixture
+def registry(registry_file):
+    """Create a ComponentRegistry with mock registry directory"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    reg = ComponentRegistry(dmc_version="2.5.1")
+    reg.registry_dir = registry_file.parent
+    reg.load()
+    return reg
+
+
+def test_registry_init():
+    """Test registry initialization"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    reg = ComponentRegistry(dmc_version="2.5.1")
+
+    assert reg.dmc_version == "2.5.1"
+    assert reg.components == {}
+    assert reg.categories == {}
+    assert reg.loaded_version is None
+
+
+def test_registry_load_success(registry, sample_registry_data):
+    """Test successful registry loading"""
+    assert registry.is_loaded()
+    assert registry.loaded_version == "2.5.1"
+    assert len(registry.components) == 2
+    assert "Button" in registry.components
+    assert "TextInput" in registry.components
+
+
+def test_registry_load_no_file():
+    """Test registry loading when no file exists"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    reg = ComponentRegistry(dmc_version="99.99.99")
+    reg.registry_dir = Path("/nonexistent/path")
+
+    result = reg.load()
+
+    assert result is False
+    assert not reg.is_loaded()
+
+
+def test_get_component(registry):
+    """Test getting a component by name"""
+    button = registry.get_component("Button")
+
+    assert button is not None
+    assert button["description"] == "Button component"
+    assert "props" in button
+
+
+def test_get_component_not_found(registry):
+    """Test getting a nonexistent component"""
+    result = registry.get_component("NonexistentComponent")
+
+    assert result is None
+
+
+def test_get_component_props(registry):
+    """Test getting component props"""
+    props = registry.get_component_props("Button")
+
+    assert props is not None
+    assert "variant" in props
+    assert "color" in props
+    assert props["variant"]["type"] == "string"
+    assert props["variant"]["enum"] == ["filled", "outline", "light"]
+
+
+def test_get_component_props_not_found(registry):
+    """Test getting props for nonexistent component"""
+    props = registry.get_component_props("Nonexistent")
+
+    assert props is None
+
+
+def test_list_components_all(registry):
+    """Test listing all components"""
+    result = registry.list_components()
+
+    assert "buttons" in result
+    assert "inputs" in result
+    assert "Button" in result["buttons"]
+    assert "TextInput" in result["inputs"]
+
+
+def test_list_components_by_category(registry):
+    """Test listing components by category"""
+    result = registry.list_components(category="buttons")
+
+    assert len(result) == 1
+    assert "buttons" in result
+    assert "Button" in result["buttons"]
+
+
+def test_list_components_invalid_category(registry):
+    """Test listing components with invalid category"""
+    result = registry.list_components(category="nonexistent")
+
+    assert result == {}
+
+
+def test_get_categories(registry):
+    """Test getting available categories"""
+    categories = registry.get_categories()
+
+    assert "buttons" in categories
+    assert "inputs" in categories
+
+
+def test_validate_prop_valid_enum(registry):
+    """Test validating a valid enum prop"""
+    result = registry.validate_prop("Button", "variant", "filled")
+
+    assert result["valid"] is True
+
+
+def test_validate_prop_invalid_enum(registry):
+    """Test validating an invalid enum prop"""
+    result = registry.validate_prop("Button", "variant", "invalid_variant")
+
+    assert result["valid"] is False
+    assert "expects one of" in result["error"]
+
+
+def test_validate_prop_valid_type(registry):
+    """Test validating a valid type"""
+    result = registry.validate_prop("Button", "disabled", True)
+
+    assert result["valid"] is True
+
+
+def test_validate_prop_invalid_type(registry):
+    """Test validating an invalid type"""
+    result = registry.validate_prop("Button", "disabled", "not_a_boolean")
+
+    assert result["valid"] is False
+    assert "expects type" in result["error"]
+
+
+def test_validate_prop_unknown_component(registry):
+    """Test validating prop for unknown component"""
+    result = registry.validate_prop("Nonexistent", "prop", "value")
+
+    assert result["valid"] is False
+    assert "Unknown component" in result["error"]
+
+
+def test_validate_prop_unknown_prop(registry):
+    """Test validating an unknown prop"""
+    result = registry.validate_prop("Button", "unknownProp", "value")
+
+    assert result["valid"] is False
+    assert "Unknown prop" in result["error"]
+
+
+def test_validate_prop_typo_detection(registry):
+    """Test typo detection for similar prop names"""
+    # colour vs color
+    result = registry.validate_prop("Button", "colour", "blue")
+
+    assert result["valid"] is False
+    # Should suggest 'color'
+    assert "color" in result.get("error", "").lower()
+
+
+def test_find_similar_props(registry):
+    """Test finding similar prop names"""
+    available = ["color", "variant", "size", "disabled"]
+
+    # Should match despite case difference
+    similar = registry._find_similar_props("Color", available)
+    assert similar == "color"
+
+    # Should match with slight typo
+    similar = registry._find_similar_props("colours", ["color", "variant"])
+    # May or may not match depending on heuristic
+
+
+def test_load_registry_convenience_function(registry_file):
+    """Test the convenience function"""
+    from mcp_server.component_registry import load_registry, ComponentRegistry
+
+    with patch.object(ComponentRegistry, '__init__', return_value=None) as mock_init:
+        with patch.object(ComponentRegistry, 'load', return_value=True):
+            mock_init.return_value = None
+            # Can't easily test this without mocking more - just ensure it doesn't crash
+            pass
+
+
+def test_find_registry_file_exact_match(tmp_path):
+    """Test finding exact registry file match"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    # Create registry files
+    registry_dir = tmp_path / "registry"
+    registry_dir.mkdir()
+    (registry_dir / "dmc_2_5.json").write_text('{"version": "2.5.0"}')
+
+    reg = ComponentRegistry(dmc_version="2.5.1")
+    reg.registry_dir = registry_dir
+
+    result = reg._find_registry_file()
+
+    assert result is not None
+    assert result.name == "dmc_2_5.json"
+
+
+def test_find_registry_file_fallback(tmp_path):
+    """Test fallback to latest registry when no exact match"""
+    from mcp_server.component_registry import ComponentRegistry
+
+    # Create registry files
+    registry_dir = tmp_path / "registry"
+    registry_dir.mkdir()
+    (registry_dir / "dmc_0_14.json").write_text('{"version": "0.14.0"}')
+
+    reg = ComponentRegistry(dmc_version="2.5.1")  # No exact match
+    reg.registry_dir = registry_dir
+
+    result = reg._find_registry_file()
+
+    assert result is not None
+    assert result.name == "dmc_0_14.json"  # Falls back to available

mcp-servers/viz-platform/tests/test_config.py

@@ -0,0 +1,156 @@
+"""
+Unit tests for viz-platform configuration loader.
+"""
+import pytest
+import os
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+
+@pytest.fixture
+def clean_env():
+    """Clean environment variables before test"""
+    env_vars = ['DMC_VERSION', 'CLAUDE_PROJECT_DIR', 'VIZ_DEFAULT_THEME']
+    saved = {k: os.environ.get(k) for k in env_vars}
+    for k in env_vars:
+        if k in os.environ:
+            del os.environ[k]
+    yield
+    # Restore after test
+    for k, v in saved.items():
+        if v is not None:
+            os.environ[k] = v
+        elif k in os.environ:
+            del os.environ[k]
+
+
+@pytest.fixture
+def config():
+    """Create VizPlatformConfig instance"""
+    from mcp_server.config import VizPlatformConfig
+    return VizPlatformConfig()
+
+
+def test_config_init(config):
+    """Test config initialization"""
+    assert config.dmc_version is None
+    assert config.theme_dir_user == Path.home() / '.config' / 'claude' / 'themes'
+    assert config.theme_dir_project is None
+    assert config.default_theme is None
+
+
+def test_config_load_returns_dict(config, clean_env):
+    """Test config.load() returns expected structure"""
+    result = config.load()
+
+    assert isinstance(result, dict)
+    assert 'dmc_version' in result
+    assert 'dmc_available' in result
+    assert 'theme_dir_user' in result
+    assert 'theme_dir_project' in result
+    assert 'default_theme' in result
+    assert 'project_dir' in result
+
+
+def test_config_respects_env_dmc_version(config, clean_env):
+    """Test that DMC_VERSION env var is respected"""
+    os.environ['DMC_VERSION'] = '0.14.7'
+
+    result = config.load()
+
+    assert result['dmc_version'] == '0.14.7'
+    assert result['dmc_available'] is True
+
+
+def test_config_respects_default_theme_env(config, clean_env):
+    """Test that VIZ_DEFAULT_THEME env var is respected"""
+    os.environ['VIZ_DEFAULT_THEME'] = 'my-dark-theme'
+
+    result = config.load()
+
+    assert result['default_theme'] == 'my-dark-theme'
+
+
+def test_detect_dmc_version_not_installed(config):
+    """Test DMC version detection when not installed"""
+    with patch('importlib.metadata.version', side_effect=ImportError("not installed")):
+        version = config._detect_dmc_version()
+
+    assert version is None
+
+
+def test_detect_dmc_version_installed(config):
+    """Test DMC version detection when installed"""
+    with patch('importlib.metadata.version', return_value='0.14.7'):
+        version = config._detect_dmc_version()
+
+    assert version == '0.14.7'
+
+
+def test_find_project_directory_from_env(config, clean_env, tmp_path):
+    """Test project directory detection from CLAUDE_PROJECT_DIR"""
+    os.environ['CLAUDE_PROJECT_DIR'] = str(tmp_path)
+
+    result = config._find_project_directory()
+
+    assert result == tmp_path
+
+
+def test_find_project_directory_with_git(config, clean_env, tmp_path):
+    """Test project directory detection with .git folder"""
+    git_dir = tmp_path / '.git'
+    git_dir.mkdir()
+
+    with patch.dict(os.environ, {'PWD': str(tmp_path)}):
+        result = config._find_project_directory()
+
+    assert result == tmp_path
+
+
+def test_find_project_directory_with_env_file(config, clean_env, tmp_path):
+    """Test project directory detection with .env file"""
+    env_file = tmp_path / '.env'
+    env_file.touch()
+
+    with patch.dict(os.environ, {'PWD': str(tmp_path)}):
+        result = config._find_project_directory()
+
+    assert result == tmp_path
+
+
+def test_load_config_convenience_function(clean_env):
+    """Test the convenience function load_config()"""
+    from mcp_server.config import load_config
+
+    result = load_config()
+
+    assert isinstance(result, dict)
+    assert 'dmc_version' in result
+
+
+def test_check_dmc_version_not_installed(clean_env):
+    """Test check_dmc_version when DMC not installed"""
+    from mcp_server.config import check_dmc_version
+
+    with patch('mcp_server.config.load_config', return_value={'dmc_available': False}):
+        result = check_dmc_version()
+
+    assert result['installed'] is False
+    assert 'not installed' in result['message'].lower()
+
+
+def test_check_dmc_version_installed_with_registry(clean_env, tmp_path):
+    """Test check_dmc_version when DMC installed with matching registry"""
+    from mcp_server.config import check_dmc_version
+
+    mock_config = {
+        'dmc_available': True,
+        'dmc_version': '2.5.1'
+    }
+
+    with patch('mcp_server.config.load_config', return_value=mock_config):
+        with patch('pathlib.Path.exists', return_value=True):
+            result = check_dmc_version()
+
+    assert result['installed'] is True
+    assert result['version'] == '2.5.1'

mcp-servers/viz-platform/tests/test_dmc_tools.py

@@ -0,0 +1,283 @@
+"""
+Unit tests for DMC validation tools.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def mock_registry():
+    """Create a mock component registry"""
+    registry = MagicMock()
+    registry.is_loaded.return_value = True
+    registry.loaded_version = "2.5.1"
+
+    registry.categories = {
+        "buttons": ["Button", "ActionIcon"],
+        "inputs": ["TextInput", "Select"]
+    }
+
+    registry.list_components.return_value = registry.categories
+    registry.get_categories.return_value = ["buttons", "inputs"]
+
+    # Mock Button component
+    registry.get_component.side_effect = lambda name: {
+        "Button": {
+            "description": "Button component",
+            "props": {
+                "variant": {"type": "string", "enum": ["filled", "outline"], "default": "filled"},
+                "color": {"type": "string", "default": "blue"},
+                "size": {"type": "string", "enum": ["xs", "sm", "md", "lg"], "default": "sm"},
+                "disabled": {"type": "boolean", "default": False, "required": False}
+            }
+        },
+        "TextInput": {
+            "description": "Text input",
+            "props": {
+                "value": {"type": "string", "required": True},
+                "placeholder": {"type": "string"}
+            }
+        }
+    }.get(name)
+
+    registry.get_component_props.side_effect = lambda name: {
+        "Button": {
+            "variant": {"type": "string", "enum": ["filled", "outline"], "default": "filled"},
+            "color": {"type": "string", "default": "blue"},
+            "size": {"type": "string", "enum": ["xs", "sm", "md", "lg"], "default": "sm"},
+            "disabled": {"type": "boolean", "default": False}
+        },
+        "TextInput": {
+            "value": {"type": "string", "required": True},
+            "placeholder": {"type": "string"}
+        }
+    }.get(name)
+
+    registry.validate_prop.side_effect = lambda comp, prop, val: (
+        {"valid": True} if prop in ["variant", "color", "size", "disabled", "value", "placeholder"]
+        else {"valid": False, "error": f"Unknown prop '{prop}'"}
+    )
+
+    return registry
+
+
+@pytest.fixture
+def dmc_tools(mock_registry):
+    """Create DMCTools instance with mock registry"""
+    from mcp_server.dmc_tools import DMCTools
+
+    tools = DMCTools(registry=mock_registry)
+    tools._initialized = True
+    return tools
+
+
+@pytest.fixture
+def uninitialized_tools():
+    """Create uninitialized DMCTools instance"""
+    from mcp_server.dmc_tools import DMCTools
+    return DMCTools()
+
+
+@pytest.mark.asyncio
+async def test_list_components_all(dmc_tools):
+    """Test listing all components"""
+    result = await dmc_tools.list_components()
+
+    assert "components" in result
+    assert "categories" in result
+    assert "version" in result
+    assert result["version"] == "2.5.1"
+
+
+@pytest.mark.asyncio
+async def test_list_components_by_category(dmc_tools, mock_registry):
+    """Test listing components by category"""
+    mock_registry.list_components.return_value = {"buttons": ["Button", "ActionIcon"]}
+
+    result = await dmc_tools.list_components(category="buttons")
+
+    assert "buttons" in result["components"]
+    mock_registry.list_components.assert_called_with("buttons")
+
+
+@pytest.mark.asyncio
+async def test_list_components_not_initialized(uninitialized_tools):
+    """Test listing components when not initialized"""
+    result = await uninitialized_tools.list_components()
+
+    assert "error" in result
+    assert result["total_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_get_component_props_success(dmc_tools):
+    """Test getting component props"""
+    result = await dmc_tools.get_component_props("Button")
+
+    assert result["component"] == "Button"
+    assert "props" in result
+    assert result["prop_count"] > 0
+
+
+@pytest.mark.asyncio
+async def test_get_component_props_not_found(dmc_tools, mock_registry):
+    """Test getting props for nonexistent component"""
+    mock_registry.get_component.return_value = None
+
+    result = await dmc_tools.get_component_props("Nonexistent")
+
+    assert "error" in result
+    assert "not found" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_get_component_props_not_initialized(uninitialized_tools):
+    """Test getting props when not initialized"""
+    result = await uninitialized_tools.get_component_props("Button")
+
+    assert "error" in result
+    assert result["prop_count"] == 0
+
+
+@pytest.mark.asyncio
+async def test_validate_component_valid(dmc_tools, mock_registry):
+    """Test validating valid component props"""
+    props = {
+        "variant": "filled",
+        "color": "blue",
+        "size": "md"
+    }
+
+    result = await dmc_tools.validate_component("Button", props)
+
+    assert result["valid"] is True
+    assert len(result["errors"]) == 0
+    assert result["component"] == "Button"
+
+
+@pytest.mark.asyncio
+async def test_validate_component_invalid_prop(dmc_tools, mock_registry):
+    """Test validating with invalid prop name"""
+    mock_registry.validate_prop.side_effect = lambda comp, prop, val: (
+        {"valid": False, "error": f"Unknown prop '{prop}'"} if prop == "unknownProp"
+        else {"valid": True}
+    )
+
+    props = {"unknownProp": "value"}
+
+    result = await dmc_tools.validate_component("Button", props)
+
+    assert result["valid"] is False
+    assert len(result["errors"]) > 0
+
+
+@pytest.mark.asyncio
+async def test_validate_component_missing_required(dmc_tools, mock_registry):
+    """Test validating with missing required prop"""
+    # TextInput has required value prop
+    mock_registry.get_component.return_value = {
+        "props": {
+            "value": {"type": "string", "required": True}
+        }
+    }
+
+    result = await dmc_tools.validate_component("TextInput", {})
+
+    assert result["valid"] is False
+    assert any("required" in e.lower() for e in result["errors"])
+
+
+@pytest.mark.asyncio
+async def test_validate_component_not_found(dmc_tools, mock_registry):
+    """Test validating nonexistent component"""
+    mock_registry.get_component.return_value = None
+
+    result = await dmc_tools.validate_component("Nonexistent", {"prop": "value"})
+
+    assert result["valid"] is False
+    assert "Unknown component" in result["errors"][0]
+
+
+@pytest.mark.asyncio
+async def test_validate_component_not_initialized(uninitialized_tools):
+    """Test validating when not initialized"""
+    result = await uninitialized_tools.validate_component("Button", {})
+
+    assert result["valid"] is False
+    assert "not initialized" in result["errors"][0].lower()
+
+
+@pytest.mark.asyncio
+async def test_validate_component_skips_special_props(dmc_tools, mock_registry):
+    """Test that special props (id, children, etc) are skipped"""
+    props = {
+        "id": "my-button",
+        "children": "Click me",
+        "className": "my-class",
+        "style": {"color": "red"},
+        "key": "btn-1"
+    }
+
+    result = await dmc_tools.validate_component("Button", props)
+
+    # Should not error on special props
+    assert result["valid"] is True
+
+
+def test_find_similar_component(dmc_tools, mock_registry):
+    """Test finding similar component names"""
+    # Should find Button when given 'button' (case mismatch)
+    similar = dmc_tools._find_similar_component("button")
+
+    assert similar == "Button"
+
+
+def test_find_similar_component_prefix(dmc_tools, mock_registry):
+    """Test finding similar component with prefix match"""
+    similar = dmc_tools._find_similar_component("Butt")
+
+    assert similar == "Button"
+
+
+def test_check_common_mistakes_onclick(dmc_tools):
+    """Test detection of onclick event handler mistake"""
+    warnings = []
+    dmc_tools._check_common_mistakes("Button", {"onClick": "handler"}, warnings)
+
+    assert len(warnings) > 0
+    assert any("callback" in w.lower() for w in warnings)
+
+
+def test_check_common_mistakes_class(dmc_tools):
+    """Test detection of 'class' instead of 'className'"""
+    warnings = []
+    dmc_tools._check_common_mistakes("Button", {"class": "my-class"}, warnings)
+
+    assert len(warnings) > 0
+    assert any("classname" in w.lower() for w in warnings)
+
+
+def test_check_common_mistakes_button_href(dmc_tools):
+    """Test detection of Button with href but no component prop"""
+    warnings = []
+    dmc_tools._check_common_mistakes("Button", {"href": "/link"}, warnings)
+
+    assert len(warnings) > 0
+    assert any("component" in w.lower() for w in warnings)
+
+
+def test_initialize_with_version():
+    """Test initializing tools with DMC version"""
+    from mcp_server.dmc_tools import DMCTools
+
+    tools = DMCTools()
+
+    with patch('mcp_server.dmc_tools.ComponentRegistry') as MockRegistry:
+        mock_instance = MagicMock()
+        mock_instance.is_loaded.return_value = True
+        MockRegistry.return_value = mock_instance
+
+        result = tools.initialize(dmc_version="2.5.1")
+
+        MockRegistry.assert_called_once_with("2.5.1")
+        assert result is True

mcp-servers/viz-platform/tests/test_theme_tools.py

@@ -0,0 +1,304 @@
+"""
+Unit tests for theme management tools.
+"""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+@pytest.fixture
+def theme_store():
+    """Create a fresh ThemeStore instance"""
+    from mcp_server.theme_store import ThemeStore
+    store = ThemeStore()
+    store._themes = {}  # Clear any existing themes
+    return store
+
+
+@pytest.fixture
+def theme_tools(theme_store):
+    """Create ThemeTools instance with fresh store"""
+    from mcp_server.theme_tools import ThemeTools
+    return ThemeTools(store=theme_store)
+
+
+def test_theme_store_init():
+    """Test theme store initialization"""
+    from mcp_server.theme_store import ThemeStore
+
+    store = ThemeStore()
+
+    # Should have default theme
+    assert store.get_theme("default") is not None
+
+
+def test_default_theme_structure():
+    """Test default theme has required structure"""
+    from mcp_server.theme_store import DEFAULT_THEME
+
+    assert "name" in DEFAULT_THEME
+    assert "tokens" in DEFAULT_THEME
+    assert "colors" in DEFAULT_THEME["tokens"]
+    assert "spacing" in DEFAULT_THEME["tokens"]
+    assert "typography" in DEFAULT_THEME["tokens"]
+    assert "radii" in DEFAULT_THEME["tokens"]
+
+
+def test_default_theme_colors():
+    """Test default theme has required color tokens"""
+    from mcp_server.theme_store import DEFAULT_THEME
+
+    colors = DEFAULT_THEME["tokens"]["colors"]
+
+    assert "primary" in colors
+    assert "secondary" in colors
+    assert "success" in colors
+    assert "warning" in colors
+    assert "error" in colors
+    assert "background" in colors
+    assert "text" in colors
+
+
+@pytest.mark.asyncio
+async def test_theme_create(theme_tools):
+    """Test creating a new theme"""
+    tokens = {
+        "colors": {
+            "primary": "#ff0000"
+        }
+    }
+
+    result = await theme_tools.theme_create("my-theme", tokens)
+
+    assert result["name"] == "my-theme"
+    assert "tokens" in result
+    assert result["tokens"]["colors"]["primary"] == "#ff0000"
+
+
+@pytest.mark.asyncio
+async def test_theme_create_merges_with_defaults(theme_tools):
+    """Test that new theme merges with default tokens"""
+    tokens = {
+        "colors": {
+            "primary": "#ff0000"
+        }
+    }
+
+    result = await theme_tools.theme_create("partial-theme", tokens)
+
+    # Should have primary from our tokens
+    assert result["tokens"]["colors"]["primary"] == "#ff0000"
+    # Should inherit secondary from defaults
+    assert "secondary" in result["tokens"]["colors"]
+
+
+@pytest.mark.asyncio
+async def test_theme_create_duplicate_name(theme_tools, theme_store):
+    """Test creating theme with existing name fails"""
+    # Create first theme
+    await theme_tools.theme_create("existing", {"colors": {}})
+
+    # Try to create with same name
+    result = await theme_tools.theme_create("existing", {"colors": {}})
+
+    assert "error" in result
+    assert "already exists" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_theme_extend(theme_tools, theme_store):
+    """Test extending an existing theme"""
+    # Create base theme
+    await theme_tools.theme_create("base", {
+        "colors": {"primary": "#0000ff"}
+    })
+
+    # Extend it
+    result = await theme_tools.theme_extend(
+        base_theme="base",
+        overrides={"colors": {"secondary": "#00ff00"}},
+        new_name="extended"
+    )
+
+    assert result["name"] == "extended"
+    # Should have base primary
+    assert result["tokens"]["colors"]["primary"] == "#0000ff"
+    # Should have override secondary
+    assert result["tokens"]["colors"]["secondary"] == "#00ff00"
+
+
+@pytest.mark.asyncio
+async def test_theme_extend_nonexistent_base(theme_tools):
+    """Test extending nonexistent theme fails"""
+    result = await theme_tools.theme_extend(
+        base_theme="nonexistent",
+        overrides={},
+        new_name="new"
+    )
+
+    assert "error" in result
+    assert "not found" in result["error"]
+
+
+@pytest.mark.asyncio
+async def test_theme_extend_default_name(theme_tools, theme_store):
+    """Test extending creates default name if not provided"""
+    await theme_tools.theme_create("base", {"colors": {}})
+
+    result = await theme_tools.theme_extend(
+        base_theme="base",
+        overrides={}
+        # No new_name provided
+    )
+
+    assert result["name"] == "base_extended"
+
+
+@pytest.mark.asyncio
+async def test_theme_validate(theme_tools, theme_store):
+    """Test theme validation"""
+    await theme_tools.theme_create("test-theme", {
+        "colors": {"primary": "#ff0000"},
+        "spacing": {"md": "16px"}
+    })
+
+    result = await theme_tools.theme_validate("test-theme")
+
+    assert "complete" in result or "validation" in result
+
+
+@pytest.mark.asyncio
+async def test_theme_validate_nonexistent(theme_tools):
+    """Test validating nonexistent theme"""
+    result = await theme_tools.theme_validate("nonexistent")
+
+    assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_theme_export_css(theme_tools, theme_store):
+    """Test exporting theme as CSS"""
+    await theme_tools.theme_create("css-theme", {
+        "colors": {"primary": "#ff0000"},
+        "spacing": {"md": "16px"}
+    })
+
+    result = await theme_tools.theme_export_css("css-theme")
+
+    assert "css" in result
+    # CSS should contain custom properties
+    assert "--" in result["css"]
+
+
+@pytest.mark.asyncio
+async def test_theme_export_css_nonexistent(theme_tools):
+    """Test exporting nonexistent theme"""
+    result = await theme_tools.theme_export_css("nonexistent")
+
+    assert "error" in result
+
+
+@pytest.mark.asyncio
+async def test_theme_list(theme_tools, theme_store):
+    """Test listing themes"""
+    await theme_tools.theme_create("theme1", {"colors": {}})
+    await theme_tools.theme_create("theme2", {"colors": {}})
+
+    result = await theme_tools.theme_list()
+
+    assert "themes" in result
+    assert "theme1" in result["themes"]
+    assert "theme2" in result["themes"]
+
+
+@pytest.mark.asyncio
+async def test_theme_activate(theme_tools, theme_store):
+    """Test activating a theme"""
+    await theme_tools.theme_create("active-theme", {"colors": {}})
+
+    result = await theme_tools.theme_activate("active-theme")
+
+    assert result.get("active_theme") == "active-theme" or result.get("success") is True
+
+
+@pytest.mark.asyncio
+async def test_theme_activate_nonexistent(theme_tools):
+    """Test activating nonexistent theme"""
+    result = await theme_tools.theme_activate("nonexistent")
+
+    assert "error" in result
+
+
+def test_theme_store_get_theme(theme_store):
+    """Test getting theme from store"""
+    from mcp_server.theme_store import DEFAULT_THEME
+
+    # Add a theme first, then retrieve it
+    theme_store._themes["test-theme"] = {"name": "test-theme", "tokens": {}}
+    result = theme_store.get_theme("test-theme")
+
+    assert result is not None
+    assert result["name"] == "test-theme"
+
+
+def test_theme_store_list_themes(theme_store):
+    """Test listing themes from store"""
+    result = theme_store.list_themes()
+
+    assert isinstance(result, list)
+
+
+def test_deep_merge(theme_tools):
+    """Test deep merging of token dicts"""
+    base = {
+        "colors": {
+            "primary": "#000",
+            "secondary": "#111"
+        },
+        "spacing": {"sm": "8px"}
+    }
+
+    override = {
+        "colors": {
+            "primary": "#fff"
+        }
+    }
+
+    result = theme_tools._deep_merge(base, override)
+
+    # primary should be overridden
+    assert result["colors"]["primary"] == "#fff"
+    # secondary should remain
+    assert result["colors"]["secondary"] == "#111"
+    # spacing should remain
+    assert result["spacing"]["sm"] == "8px"
+
+
+def test_validate_tokens(theme_tools):
+    """Test token validation"""
+    from mcp_server.theme_store import REQUIRED_TOKEN_CATEGORIES
+
+    tokens = {
+        "colors": {"primary": "#000"},
+        "spacing": {"md": "16px"},
+        "typography": {"fontFamily": "Inter"},
+        "radii": {"md": "8px"}
+    }
+
+    result = theme_tools._validate_tokens(tokens)
+
+    assert "complete" in result
+    # Check for either "missing" or "missing_required" key
+    assert "missing" in result or "missing_required" in result or "missing_optional" in result
+
+
+def test_validate_tokens_incomplete(theme_tools):
+    """Test validation of incomplete tokens"""
+    tokens = {
+        "colors": {"primary": "#000"}
+        # Missing spacing, typography, radii
+    }
+
+    result = theme_tools._validate_tokens(tokens)
+
+    # Should flag missing categories
+    assert result["complete"] is False or len(result.get("missing", [])) > 0

plugins/clarity-assist/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/vagueness-check.sh"
+      }
+    ]
+  }
+}

plugins/clarity-assist/hooks/vagueness-check.sh

@@ -0,0 +1,216 @@
+#!/bin/bash
+# clarity-assist vagueness detection hook
+# Analyzes user prompts for vagueness and suggests /clarity-assist when beneficial
+# All output MUST have [clarity-assist] prefix
+# This is a NON-BLOCKING hook - always exits 0
+
+PREFIX="[clarity-assist]"
+
+# Check if auto-suggest is enabled (default: true)
+AUTO_SUGGEST="${CLARITY_ASSIST_AUTO_SUGGEST:-true}"
+if [[ "$AUTO_SUGGEST" != "true" ]]; then
+    exit 0
+fi
+
+# Threshold for vagueness score (default: 0.6)
+THRESHOLD="${CLARITY_ASSIST_VAGUENESS_THRESHOLD:-0.6}"
+
+# Read user prompt from stdin
+PROMPT=""
+if [[ -t 0 ]]; then
+    # No stdin available
+    exit 0
+else
+    PROMPT=$(cat)
+fi
+
+# Skip empty prompts
+if [[ -z "$PROMPT" ]]; then
+    exit 0
+fi
+
+# Skip if prompt is a command (starts with /)
+if [[ "$PROMPT" =~ ^[[:space:]]*/[a-zA-Z] ]]; then
+    exit 0
+fi
+
+# Skip if prompt mentions specific files or paths
+if [[ "$PROMPT" =~ \.(py|js|ts|sh|md|json|yaml|yml|txt|css|html|go|rs|java|c|cpp|h)([[:space:]]|$|[^a-zA-Z]) ]] || \
+   [[ "$PROMPT" =~ [/\\][a-zA-Z0-9_-]+[/\\] ]] || \
+   [[ "$PROMPT" =~ (src|lib|test|docs|plugins|hooks|commands)/ ]]; then
+    exit 0
+fi
+
+# Initialize vagueness score
+SCORE=0
+
+# Count words in the prompt
+WORD_COUNT=$(echo "$PROMPT" | wc -w | tr -d ' ')
+
+# ============================================================================
+# Vagueness Signal Detection
+# ============================================================================
+
+# Signal 1: Very short prompts (< 10 words) are often vague
+if [[ "$WORD_COUNT" -lt 10 ]]; then
+    # But very short specific commands are OK
+    if [[ "$WORD_COUNT" -lt 3 ]]; then
+        # Extremely short - probably intentional or a command
+        :
+    else
+        SCORE=$(echo "$SCORE + 0.3" | bc)
+    fi
+fi
+
+# Signal 2: Vague action phrases (no specific outcome)
+VAGUE_ACTIONS=(
+    "help me"
+    "help with"
+    "do something"
+    "work on"
+    "look at"
+    "check this"
+    "fix it"
+    "fix this"
+    "make it better"
+    "make this better"
+    "improve it"
+    "improve this"
+    "update this"
+    "update it"
+    "change it"
+    "change this"
+    "can you"
+    "could you"
+    "would you"
+    "please help"
+)
+
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+for phrase in "${VAGUE_ACTIONS[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$phrase"* ]]; then
+        SCORE=$(echo "$SCORE + 0.2" | bc)
+        break
+    fi
+done
+
+# Signal 3: Ambiguous scope indicators
+AMBIGUOUS_SCOPE=(
+    "somehow"
+    "something"
+    "somewhere"
+    "anything"
+    "whatever"
+    "stuff"
+    "things"
+    "etc"
+    "and so on"
+)
+
+for word in "${AMBIGUOUS_SCOPE[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$word"* ]]; then
+        SCORE=$(echo "$SCORE + 0.15" | bc)
+        break
+    fi
+done
+
+# Signal 4: Missing context indicators (no reference to what/where)
+# Check if prompt lacks specificity markers
+HAS_SPECIFICS=false
+
+# Specific technical terms suggest clarity
+SPECIFIC_MARKERS=(
+    "function"
+    "class"
+    "method"
+    "variable"
+    "error"
+    "bug"
+    "test"
+    "api"
+    "endpoint"
+    "database"
+    "query"
+    "component"
+    "module"
+    "service"
+    "config"
+    "install"
+    "deploy"
+    "build"
+    "run"
+    "execute"
+    "create"
+    "delete"
+    "add"
+    "remove"
+    "implement"
+    "refactor"
+    "migrate"
+    "upgrade"
+    "debug"
+    "log"
+    "exception"
+    "stack"
+    "memory"
+    "performance"
+    "security"
+    "auth"
+    "token"
+    "session"
+    "route"
+    "controller"
+    "model"
+    "view"
+    "template"
+    "schema"
+    "migration"
+    "commit"
+    "branch"
+    "merge"
+    "pull"
+    "push"
+)
+
+for marker in "${SPECIFIC_MARKERS[@]}"; do
+    if [[ "$PROMPT_LOWER" == *"$marker"* ]]; then
+        HAS_SPECIFICS=true
+        break
+    fi
+done
+
+if [[ "$HAS_SPECIFICS" == false ]] && [[ "$WORD_COUNT" -gt 3 ]]; then
+    SCORE=$(echo "$SCORE + 0.2" | bc)
+fi
+
+# Signal 5: Question without context
+if [[ "$PROMPT" =~ \?$ ]] && [[ "$WORD_COUNT" -lt 8 ]]; then
+    # Short questions without specifics are often vague
+    if [[ "$HAS_SPECIFICS" == false ]]; then
+        SCORE=$(echo "$SCORE + 0.15" | bc)
+    fi
+fi
+
+# Cap score at 1.0
+if (( $(echo "$SCORE > 1.0" | bc -l) )); then
+    SCORE="1.0"
+fi
+
+# ============================================================================
+# Output suggestion if score exceeds threshold
+# ============================================================================
+
+# Compare score to threshold using bc
+if (( $(echo "$SCORE >= $THRESHOLD" | bc -l) )); then
+    # Format score as percentage for display
+    SCORE_PCT=$(echo "$SCORE * 100" | bc | cut -d'.' -f1)
+
+    # Gentle, non-blocking suggestion
+    echo "$PREFIX Your prompt could benefit from more clarity."
+    echo "$PREFIX Consider running /clarity-assist to refine your request."
+    echo "$PREFIX (Vagueness score: ${SCORE_PCT}% - this is a suggestion, not a block)"
+fi
+
+# Always exit 0 - this hook is non-blocking
+exit 0

plugins/cmdb-assistant/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cmdb-assistant",
-  "version": "1.0.0",
-  "description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
+  "version": "1.1.0",
+  "description": "NetBox CMDB integration with data quality validation - query, create, update, and manage network devices, IP addresses, sites, and more with best practices enforcement",
   "author": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
@@ -15,7 +15,9 @@
     "infrastructure",
     "network",
     "ipam",
-    "dcim"
+    "dcim",
+    "data-quality",
+    "validation"
   ],
   "commands": ["./commands/"],
   "mcpServers": ["./.mcp.json"]

plugins/cmdb-assistant/.mcp.json

@@ -1,12 +1,8 @@
 {
   "mcpServers": {
     "netbox": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox/.venv/bin/python",
-      "args": ["-m", "mcp_server.server"],
-      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox",
-      "env": {
-        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox"
-      }
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/netbox/run.sh",
+      "args": []
     }
   }
 }

plugins/cmdb-assistant/README.md

@@ -2,6 +2,14 @@
 
 A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.
 
+## What's New in v1.1.0
+
+- **Data Quality Validation**: Hooks for SessionStart and PreToolUse that check data quality and warn about missing fields
+- **Best Practices Skill**: Reference documentation for NetBox patterns (naming conventions, dependency order, role management)
+- **`/cmdb-audit`**: Analyze data quality across VMs, devices, naming conventions, and roles
+- **`/cmdb-register`**: Register the current machine into NetBox with all running applications (Docker containers, systemd services)
+- **`/cmdb-sync`**: Synchronize existing machine state with NetBox (detect drift, update with confirmation)
+
 ## Features
 
 - **Full CRUD Operations**: Create, read, update, and delete across all NetBox modules
@@ -9,6 +17,9 @@ A Claude Code plugin for NetBox CMDB integration - query, create, update, and ma
 - **IP Management**: Allocate IPs, manage prefixes, track VLANs
 - **Infrastructure Documentation**: Document servers, network devices, and connections
 - **Audit Trail**: Review changes and maintain infrastructure history
+- **Data Quality Validation**: Proactive checks for missing site, tenant, platform assignments
+- **Machine Registration**: Auto-discover and register servers with running applications
+- **Drift Detection**: Sync machine state and detect changes over time
 
 ## Installation
 
@@ -40,10 +51,14 @@ Add to your Claude Code plugins or marketplace configuration.
 
 | Command | Description |
 |---------|-------------|
+| `/initial-setup` | Interactive setup wizard for NetBox MCP server |
 | `/cmdb-search <query>` | Search for devices, IPs, sites, or any CMDB object |
 | `/cmdb-device <action>` | Manage network devices (list, create, update, delete) |
 | `/cmdb-ip <action>` | Manage IP addresses and prefixes |
 | `/cmdb-site <action>` | Manage sites and locations |
+| `/cmdb-audit [scope]` | Data quality analysis (all, vms, devices, naming, roles) |
+| `/cmdb-register` | Register current machine into NetBox with running apps |
+| `/cmdb-sync` | Sync machine state with NetBox (detect drift, update) |
 
 ## Agent
 
@@ -103,6 +118,15 @@ This plugin provides access to the full NetBox API:
 - **Wireless**: WLANs, Wireless Links
 - **Extras**: Tags, Custom Fields, Journal Entries, Audit Log
 
+## Hooks
+
+| Event | Purpose |
+|-------|---------|
+| `SessionStart` | Test NetBox connectivity, report data quality issues |
+| `PreToolUse` | Validate VM/device parameters before create/update |
+
+Hooks are **non-blocking** - they emit warnings but never prevent operations.
+
 ## Architecture
 
 ```
@@ -115,13 +139,23 @@ cmdb-assistant/
 │   ├── cmdb-search.md       # Search command
 │   ├── cmdb-device.md       # Device management
 │   ├── cmdb-ip.md           # IP management
-│   └── cmdb-site.md         # Site management
+│   ├── cmdb-site.md         # Site management
+│   ├── cmdb-audit.md        # Data quality audit (NEW)
+│   ├── cmdb-register.md     # Machine registration (NEW)
+│   └── cmdb-sync.md         # Machine sync (NEW)
+├── hooks/
+│   ├── hooks.json           # Hook configuration
+│   ├── startup-check.sh     # SessionStart validation
+│   └── validate-input.sh    # PreToolUse validation
+├── skills/
+│   └── netbox-patterns/
+│       └── SKILL.md         # NetBox best practices reference
 ├── agents/
 │   └── cmdb-assistant.md    # Main assistant agent
 └── README.md
 ```
 
-The plugin uses the shared NetBox MCP server at `../mcp-servers/netbox/`.
+The plugin uses the shared NetBox MCP server at `mcp-servers/netbox/`.
 
 ## Configuration
 

plugins/cmdb-assistant/agents/cmdb-assistant.md

@@ -76,3 +76,132 @@ When presenting data:
 - Suggest corrective actions
 - For permission errors, note what access is needed
 - For validation errors, explain required fields/formats
+
+## Data Quality Validation
+
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
+
+Before ANY create or update operation, validate against NetBox best practices:
+
+### VM Operations
+
+**Required checks before `virt_create_vm` or `virt_update_vm`:**
+
+1. **Cluster/Site Assignment** - VMs must have either cluster or site
+2. **Tenant Assignment** - Recommend if not provided
+3. **Platform Assignment** - Recommend for OS tracking
+4. **Naming Convention** - Check against `{env}-{app}-{number}` pattern
+5. **Role Assignment** - Recommend appropriate role
+
+**If user provides no site/tenant, ASK:**
+
+> "This VM has no site or tenant assigned. NetBox best practices recommend:
+> - **Site**: For location-based queries and power budgeting
+> - **Tenant**: For resource isolation and ownership tracking
+>
+> Would you like me to:
+> 1. Assign to an existing site/tenant (list available)
+> 2. Create new site/tenant first
+> 3. Proceed without (not recommended for production use)"
+
+### Device Operations
+
+**Required checks before `dcim_create_device` or `dcim_update_device`:**
+
+1. **Site is REQUIRED** - Fail without it
+2. **Platform Assignment** - Recommend for OS tracking
+3. **Naming Convention** - Check against `{role}-{location}-{number}` pattern
+4. **Role Assignment** - Ensure appropriate role selected
+5. **After Creation** - Offer to set primary IP
+
+### Cluster Operations
+
+**Required checks before `virt_create_cluster`:**
+
+1. **Site Scope** - Recommend assigning to site
+2. **Cluster Type** - Ensure appropriate type selected
+3. **Device Association** - Recommend linking to host device
+
+### Role Management
+
+**Before creating a new device role:**
+
+1. List existing roles with `dcim_list_device_roles`
+2. Check if a more general role already exists
+3. Recommend role consolidation if >10 specific roles exist
+
+**Example guidance:**
+
+> "You're creating role 'nginx-web-server'. An existing 'web-server' role exists.
+> Consider using 'web-server' and tracking nginx via the platform field instead.
+> This reduces role fragmentation and improves maintainability."
+
+## Dependency Order Enforcement
+
+When creating multiple objects, follow this order:
+
+```
+1. Regions → Sites → Locations → Racks
+2. Tenant Groups → Tenants
+3. Manufacturers → Device Types
+4. Device Roles, Platforms
+5. Devices (with site, role, type)
+6. Clusters (with type, optional site)
+7. VMs (with cluster)
+8. Interfaces → IP Addresses → Primary IP assignment
+```
+
+**CRITICAL Rules:**
+- NEVER create a VM before its cluster exists
+- NEVER create a device before its site exists
+- NEVER create an interface before its device exists
+- NEVER create an IP before its interface exists (if assigning)
+
+## Naming Convention Enforcement
+
+When user provides a name, check against patterns:
+
+| Object Type | Pattern | Example |
+|-------------|---------|---------|
+| Device | `{role}-{site}-{number}` | `web-dc1-01` |
+| VM | `{env}-{app}-{number}` or `{prefix}_{service}` | `prod-api-01` |
+| Cluster | `{site}-{type}` | `dc1-vmware`, `home-docker` |
+| Prefix | Include purpose in description | "Production /24 for web tier" |
+
+**If name doesn't match patterns, warn:**
+
+> "The name 'HotServ' doesn't follow naming conventions.
+> Suggested: `prod-hotserv-01` or `hotserv-cloud-01`.
+> Consistent naming improves searchability and automation compatibility.
+> Proceed with original name? [Y/n]"
+
+## Duplicate Prevention
+
+Before creating objects, always check for existing duplicates:
+
+```
+# Before creating device
+dcim_list_devices name=<proposed-name>
+
+# Before creating VM
+virt_list_vms name=<proposed-name>
+
+# Before creating prefix
+ipam_list_prefixes prefix=<proposed-prefix>
+```
+
+If duplicate found, inform user and suggest update instead of create.
+
+## Available Commands
+
+Users can invoke these commands for structured workflows:
+
+| Command | Purpose |
+|---------|---------|
+| `/cmdb-search <query>` | Search across all CMDB objects |
+| `/cmdb-device <action>` | Device CRUD operations |
+| `/cmdb-ip <action>` | IP address and prefix management |
+| `/cmdb-site <action>` | Site and location management |
+| `/cmdb-audit [scope]` | Data quality analysis |
+| `/cmdb-register` | Register current machine |
+| `/cmdb-sync` | Sync machine state with NetBox |

plugins/cmdb-assistant/commands/cmdb-audit.md

@@ -0,0 +1,195 @@
+---
+description: Audit NetBox data quality and identify consistency issues
+---
+
+# CMDB Data Quality Audit
+
+Analyze NetBox data for quality issues and best practice violations.
+
+## Usage
+
+```
+/cmdb-audit [scope]
+```
+
+**Scopes:**
+- `all` (default) - Full audit across all categories
+- `vms` - Virtual machines only
+- `devices` - Physical devices only
+- `naming` - Naming convention analysis
+- `roles` - Role fragmentation analysis
+
+## Instructions
+
+You are a data quality auditor for NetBox. Your job is to identify consistency issues and best practice violations.
+
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
+
+### Phase 1: Data Collection
+
+Run these MCP tool calls to gather data for analysis:
+
+```
+1. virt_list_vms (no filters - get all)
+2. dcim_list_devices (no filters - get all)
+3. virt_list_clusters (no filters)
+4. dcim_list_sites
+5. tenancy_list_tenants
+6. dcim_list_device_roles
+7. dcim_list_platforms
+```
+
+Store the results for analysis.
+
+### Phase 2: Quality Checks
+
+Analyze collected data for these issues by severity:
+
+#### CRITICAL Issues (must fix immediately)
+
+| Check | Detection |
+|-------|-----------|
+| VMs without cluster | `cluster` field is null AND `site` field is null |
+| Devices without site | `site` field is null |
+| Active devices without primary IP | `status=active` AND `primary_ip4` is null AND `primary_ip6` is null |
+
+#### HIGH Issues (should fix soon)
+
+| Check | Detection |
+|-------|-----------|
+| VMs without site | VM has no site (neither direct nor via cluster.site) |
+| VMs without tenant | `tenant` field is null |
+| Devices without platform | `platform` field is null |
+| Clusters not scoped to site | `site` field is null on cluster |
+| VMs without role | `role` field is null |
+
+#### MEDIUM Issues (plan to address)
+
+| Check | Detection |
+|-------|-----------|
+| Inconsistent naming | Names don't match patterns: devices=`{role}-{site}-{num}`, VMs=`{env}-{app}-{num}` |
+| Role fragmentation | More than 10 device roles with <3 assignments each |
+| Missing tags on production | Active resources without any tags |
+| Mixed naming separators | Some names use `_`, others use `-` |
+
+#### LOW Issues (informational)
+
+| Check | Detection |
+|-------|-----------|
+| Docker containers as VMs | Cluster type is "Docker Compose" - document this modeling choice |
+| VMs without description | `description` field is empty |
+| Sites without physical address | `physical_address` is empty |
+| Devices without serial | `serial` field is empty |
+
+### Phase 3: Naming Convention Analysis
+
+For naming scope, analyze patterns:
+
+1. **Extract naming patterns** from existing objects
+2. **Identify dominant patterns** (most common conventions)
+3. **Flag outliers** that don't match dominant patterns
+4. **Suggest standardization** based on best practices
+
+**Expected Patterns:**
+- Devices: `{role}-{location}-{number}` (e.g., `web-dc1-01`)
+- VMs: `{prefix}_{service}` or `{env}-{app}-{number}` (e.g., `prod-api-01`)
+- Clusters: `{site}-{type}` (e.g., `home-docker`)
+
+### Phase 4: Role Analysis
+
+For roles scope, analyze fragmentation:
+
+1. **List all device roles** with assignment counts
+2. **Identify single-use roles** (only 1 device/VM)
+3. **Identify similar roles** that could be consolidated
+4. **Suggest consolidation** based on patterns
+
+**Red Flags:**
+- More than 15 highly specific roles
+- Roles with technology in name (use platform instead)
+- Roles that duplicate functionality
+
+### Phase 5: Report Generation
+
+Present findings in this structure:
+
+```markdown
+## CMDB Data Quality Audit Report
+
+**Generated:** [timestamp]
+**Scope:** [scope parameter]
+
+### Summary
+
+| Metric | Count |
+|--------|-------|
+| Total VMs | X |
+| Total Devices | Y |
+| Total Clusters | Z |
+| **Total Issues** | **N** |
+
+| Severity | Count |
+|----------|-------|
+| Critical | A |
+| High | B |
+| Medium | C |
+| Low | D |
+
+### Critical Issues
+
+[List each with specific object names and IDs]
+
+**Example:**
+- VM `HotServ` (ID: 1) - No cluster or site assignment
+- Device `server-01` (ID: 5) - No site assignment
+
+### High Issues
+
+[List each with specific object names]
+
+### Medium Issues
+
+[Grouped by category with counts]
+
+### Recommendations
+
+1. **[Most impactful fix]** - affects N objects
+2. **[Second priority]** - affects M objects
+...
+
+### Quick Fixes
+
+Commands to fix common issues:
+
+```
+# Assign site to VM
+virt_update_vm id=X site=Y
+
+# Assign platform to device
+dcim_update_device id=X platform=Y
+```
+
+### Next Steps
+
+- Run `/cmdb-register` to properly register new machines
+- Use `/cmdb-sync` to update existing registrations
+- Consider bulk updates via NetBox web UI for >10 items
+```
+
+## Scope-Specific Instructions
+
+### For `vms` scope:
+Focus only on Virtual Machine checks. Skip device and role analysis.
+
+### For `devices` scope:
+Focus only on Device checks. Skip VM and cluster analysis.
+
+### For `naming` scope:
+Focus on naming convention analysis across all objects. Generate detailed pattern report.
+
+### For `roles` scope:
+Focus on role fragmentation analysis. Generate consolidation recommendations.
+
+## User Request
+
+$ARGUMENTS

plugins/cmdb-assistant/commands/cmdb-register.md

@@ -0,0 +1,322 @@
+---
+description: Register the current machine into NetBox with all running applications
+---
+
+# CMDB Machine Registration
+
+Register the current machine into NetBox, including hardware info, network interfaces, and running applications (Docker containers, services).
+
+## Usage
+
+```
+/cmdb-register [--site <site-name>] [--tenant <tenant-name>] [--role <role-name>]
+```
+
+**Options:**
+- `--site <name>`: Site to assign (will prompt if not provided)
+- `--tenant <name>`: Tenant for resource isolation (optional)
+- `--role <name>`: Device role (default: auto-detect based on services)
+
+## Instructions
+
+You are registering the current machine into NetBox. This is a multi-phase process that discovers local system information and creates corresponding NetBox objects.
+
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
+
+### Phase 1: System Discovery (via Bash)
+
+Gather system information using these commands:
+
+#### 1.1 Basic Device Info
+
+```bash
+# Hostname
+hostname
+
+# OS/Platform info
+cat /etc/os-release 2>/dev/null || uname -a
+
+# Hardware model (varies by system)
+# Raspberry Pi:
+cat /proc/device-tree/model 2>/dev/null || echo "Unknown"
+
+# x86 systems:
+cat /sys/class/dmi/id/product_name 2>/dev/null || echo "Unknown"
+
+# Serial number
+# Raspberry Pi:
+cat /proc/device-tree/serial-number 2>/dev/null || cat /proc/cpuinfo | grep Serial | cut -d: -f2 | tr -d ' ' 2>/dev/null
+
+# x86 systems:
+cat /sys/class/dmi/id/product_serial 2>/dev/null || echo "Unknown"
+
+# CPU info
+nproc
+
+# Memory (MB)
+free -m | awk '/Mem:/ {print $2}'
+
+# Disk (GB, root filesystem)
+df -BG / | awk 'NR==2 {print $2}' | tr -d 'G'
+```
+
+#### 1.2 Network Interfaces
+
+```bash
+# Get interfaces with IPs (JSON format)
+ip -j addr show 2>/dev/null || ip addr show
+
+# Get default gateway interface
+ip route | grep default | awk '{print $5}' | head -1
+
+# Get MAC addresses
+ip -j link show 2>/dev/null || ip link show
+```
+
+#### 1.3 Running Applications
+
+```bash
+# Docker containers (if docker available)
+docker ps --format '{"name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}","ports":"{{.Ports}}"}' 2>/dev/null || echo "Docker not available"
+
+# Docker Compose projects (check common locations)
+find ~/apps /home/*/apps -name "docker-compose.yml" -o -name "docker-compose.yaml" 2>/dev/null | head -20
+
+# Systemd services (running)
+systemctl list-units --type=service --state=running --no-pager --plain 2>/dev/null | grep -v "^UNIT" | head -30
+```
+
+### Phase 2: Pre-Registration Checks (via MCP)
+
+Before creating objects, verify prerequisites:
+
+#### 2.1 Check if Device Already Exists
+
+```
+dcim_list_devices name=<hostname>
+```
+
+**If device exists:**
+- Inform user and suggest `/cmdb-sync` instead
+- Ask if they want to proceed with re-registration (will update existing)
+
+#### 2.2 Verify/Create Site
+
+If `--site` provided:
+```
+dcim_list_sites name=<site-name>
+```
+
+If site doesn't exist, ask user if they want to create it.
+
+If no site provided, list available sites and ask user to choose:
+```
+dcim_list_sites
+```
+
+#### 2.3 Verify/Create Platform
+
+Based on OS detected, check if platform exists:
+```
+dcim_list_platforms name=<platform-name>
+```
+
+**Platform naming:**
+- `Raspberry Pi OS (Bookworm)` for Raspberry Pi
+- `Ubuntu 24.04 LTS` for Ubuntu
+- `Debian 12` for Debian
+- Use format: `{OS Name} {Version}`
+
+If platform doesn't exist, create it:
+```
+dcim_create_platform name=<platform-name> slug=<slug>
+```
+
+#### 2.4 Verify/Create Device Role
+
+Based on detected services:
+- If Docker containers found → `Docker Host`
+- If only basic services → `Server`
+- If specific role specified → Use that
+
+```
+dcim_list_device_roles name=<role-name>
+```
+
+### Phase 3: Device Registration (via MCP)
+
+#### 3.1 Get/Create Manufacturer and Device Type
+
+For Raspberry Pi:
+```
+dcim_list_manufacturers name="Raspberry Pi Foundation"
+dcim_list_device_types manufacturer_id=X model="Raspberry Pi 4 Model B"
+```
+
+Create if not exists.
+
+For generic x86:
+```
+dcim_list_manufacturers name=<detected-manufacturer>
+```
+
+#### 3.2 Create Device
+
+```
+dcim_create_device
+  name=<hostname>
+  device_type=<device_type_id>
+  role=<role_id>
+  site=<site_id>
+  platform=<platform_id>
+  tenant=<tenant_id>  # if provided
+  serial=<serial>
+  description="Registered via cmdb-assistant"
+```
+
+#### 3.3 Create Interfaces
+
+For each network interface discovered:
+```
+dcim_create_interface
+  device=<device_id>
+  name=<interface_name>  # eth0, wlan0, tailscale0, etc.
+  type=<type>            # 1000base-t, virtual, other
+  mac_address=<mac>
+  enabled=true
+```
+
+**Interface type mapping:**
+- `eth*`, `enp*` → `1000base-t`
+- `wlan*` → `ieee802.11ax` (or appropriate wifi type)
+- `tailscale*`, `docker*`, `br-*` → `virtual`
+- `lo` → skip (loopback)
+
+#### 3.4 Create IP Addresses
+
+For each IP on each interface:
+```
+ipam_create_ip_address
+  address=<ip/prefix>    # e.g., "192.168.1.100/24"
+  assigned_object_type="dcim.interface"
+  assigned_object_id=<interface_id>
+  status="active"
+  description="Discovered via cmdb-register"
+```
+
+#### 3.5 Set Primary IP
+
+Identify primary IP (interface with default route):
+```
+dcim_update_device
+  id=<device_id>
+  primary_ip4=<primary_ip_id>
+```
+
+### Phase 4: Container Registration (via MCP)
+
+If Docker containers were discovered:
+
+#### 4.1 Create/Get Cluster Type
+
+```
+virt_list_cluster_types name="Docker Compose"
+```
+
+Create if not exists:
+```
+virt_create_cluster_type name="Docker Compose" slug="docker-compose"
+```
+
+#### 4.2 Create Cluster
+
+For each Docker Compose project directory found:
+```
+virt_create_cluster
+  name=<project-name>  # e.g., "apps-hotport"
+  type=<cluster_type_id>
+  site=<site_id>
+  description="Docker Compose stack on <hostname>"
+```
+
+#### 4.3 Create VMs for Containers
+
+For each running container:
+```
+virt_create_vm
+  name=<container_name>
+  cluster=<cluster_id>
+  site=<site_id>
+  role=<role_id>        # Map container function to role
+  status="active"
+  vcpus=<cpu_shares>    # Default 1.0 if unknown
+  memory=<memory_mb>    # Default 256 if unknown
+  disk=<disk_gb>        # Default 5 if unknown
+  description=<container purpose>
+  comments=<image, ports, volumes info>
+```
+
+**Container role mapping:**
+- `*caddy*`, `*nginx*`, `*traefik*` → "Reverse Proxy"
+- `*db*`, `*postgres*`, `*mysql*`, `*redis*` → "Database"
+- `*webui*`, `*frontend*` → "Web Application"
+- Others → Infer from image name or use generic "Container"
+
+### Phase 5: Documentation
+
+#### 5.1 Add Journal Entry
+
+```
+extras_create_journal_entry
+  assigned_object_type="dcim.device"
+  assigned_object_id=<device_id>
+  comments="Device registered via /cmdb-register command\n\nDiscovered:\n- X network interfaces\n- Y IP addresses\n- Z Docker containers"
+```
+
+### Phase 6: Summary Report
+
+Present registration summary:
+
+```markdown
+## Machine Registration Complete
+
+### Device Created
+- **Name:** <hostname>
+- **Site:** <site>
+- **Platform:** <platform>
+- **Role:** <role>
+- **ID:** <device_id>
+- **URL:** https://netbox.example.com/dcim/devices/<id>/
+
+### Network Interfaces
+| Interface | Type | MAC | IP Address |
+|-----------|------|-----|------------|
+| eth0 | 1000base-t | aa:bb:cc:dd:ee:ff | 192.168.1.100/24 |
+| tailscale0 | virtual | - | 100.x.x.x/32 |
+
+### Primary IP: 192.168.1.100
+
+### Docker Containers Registered (if applicable)
+**Cluster:** <cluster_name> (ID: <cluster_id>)
+
+| Container | Role | vCPUs | Memory | Status |
+|-----------|------|-------|--------|--------|
+| media_jellyfin | Media Server | 2.0 | 2048MB | Active |
+| media_sonarr | Media Management | 1.0 | 512MB | Active |
+
+### Next Steps
+- Run `/cmdb-sync` periodically to keep data current
+- Run `/cmdb-audit` to check data quality
+- Add tags for classification (env:*, team:*, etc.)
+```
+
+## Error Handling
+
+- **Device already exists:** Suggest `/cmdb-sync` or ask to proceed
+- **Site not found:** List available sites, offer to create new
+- **Docker not available:** Skip container registration, note in summary
+- **Permission denied:** Note which operations failed, suggest fixes
+
+## User Request
+
+$ARGUMENTS

plugins/cmdb-assistant/commands/cmdb-sync.md

@@ -0,0 +1,336 @@
+---
+description: Synchronize current machine state with existing NetBox record
+---
+
+# CMDB Machine Sync
+
+Update an existing NetBox device record with the current machine state. Compares local system information with NetBox and applies changes.
+
+## Usage
+
+```
+/cmdb-sync [--full] [--dry-run]
+```
+
+**Options:**
+- `--full`: Force refresh all fields, even unchanged ones
+- `--dry-run`: Show what would change without applying updates
+
+## Instructions
+
+You are synchronizing the current machine's state with its NetBox record. This involves comparing current system state with stored data and updating differences.
+
+**IMPORTANT:** Load the `netbox-patterns` skill for best practice reference.
+
+### Phase 1: Device Lookup (via MCP)
+
+First, find the existing device record:
+
+```bash
+# Get current hostname
+hostname
+```
+
+```
+dcim_list_devices name=<hostname>
+```
+
+**If device not found:**
+- Inform user: "Device '<hostname>' not found in NetBox"
+- Suggest: "Run `/cmdb-register` to register this machine first"
+- Exit sync
+
+**If device found:**
+- Store device ID and all current field values
+- Fetch interfaces: `dcim_list_interfaces device_id=<device_id>`
+- Fetch IPs: `ipam_list_ip_addresses device_id=<device_id>`
+
+Also check for associated clusters/VMs:
+```
+virt_list_clusters  # Look for cluster associated with this device
+virt_list_vms cluster=<cluster_id>  # If cluster found
+```
+
+### Phase 2: Current State Discovery (via Bash)
+
+Gather current system information (same as `/cmdb-register`):
+
+```bash
+# Device info
+hostname
+cat /etc/os-release 2>/dev/null || uname -a
+nproc
+free -m | awk '/Mem:/ {print $2}'
+df -BG / | awk 'NR==2 {print $2}' | tr -d 'G'
+
+# Network interfaces with IPs
+ip -j addr show 2>/dev/null || ip addr show
+
+# Docker containers
+docker ps --format '{"name":"{{.Names}}","image":"{{.Image}}","status":"{{.Status}}"}' 2>/dev/null || echo "[]"
+```
+
+### Phase 3: Comparison
+
+Compare discovered state with NetBox record:
+
+#### 3.1 Device Attributes
+
+| Field | Compare |
+|-------|---------|
+| Platform | OS version changed? |
+| Status | Still active? |
+| Serial | Match? |
+| Description | Keep existing |
+
+#### 3.2 Network Interfaces
+
+| Change Type | Detection |
+|-------------|-----------|
+| New interface | Interface exists locally but not in NetBox |
+| Removed interface | Interface in NetBox but not locally |
+| Changed MAC | MAC address different |
+| Interface type | Type mismatch |
+
+#### 3.3 IP Addresses
+
+| Change Type | Detection |
+|-------------|-----------|
+| New IP | IP exists locally but not in NetBox |
+| Removed IP | IP in NetBox but not locally (on this device) |
+| Primary IP changed | Default route interface changed |
+
+#### 3.4 Docker Containers
+
+| Change Type | Detection |
+|-------------|-----------|
+| New container | Container running locally but no VM in cluster |
+| Stopped container | VM exists but container not running |
+| Resource change | vCPUs/memory different (if trackable) |
+
+### Phase 4: Diff Report
+
+Present changes to user:
+
+```markdown
+## Sync Diff Report
+
+**Device:** <hostname> (ID: <device_id>)
+**NetBox URL:** https://netbox.example.com/dcim/devices/<id>/
+
+### Device Attributes
+| Field | NetBox Value | Current Value | Action |
+|-------|--------------|---------------|--------|
+| Platform | Ubuntu 22.04 | Ubuntu 24.04 | UPDATE |
+| Status | active | active | - |
+
+### Network Interfaces
+
+#### New Interfaces (will create)
+| Interface | Type | MAC | IPs |
+|-----------|------|-----|-----|
+| tailscale0 | virtual | - | 100.x.x.x/32 |
+
+#### Removed Interfaces (will mark offline)
+| Interface | Type | Reason |
+|-----------|------|--------|
+| eth1 | 1000base-t | Not found locally |
+
+#### Changed Interfaces
+| Interface | Field | Old | New |
+|-----------|-------|-----|-----|
+| eth0 | mac_address | aa:bb:cc:00:00:00 | aa:bb:cc:11:11:11 |
+
+### IP Addresses
+
+#### New IPs (will create)
+- 192.168.1.150/24 on eth0
+
+#### Removed IPs (will unassign)
+- 192.168.1.100/24 from eth0
+
+### Docker Containers
+
+#### New Containers (will create VMs)
+| Container | Image | Role |
+|-----------|-------|------|
+| media_lidarr | linuxserver/lidarr | Media Management |
+
+#### Stopped Containers (will mark offline)
+| Container | Last Status |
+|-----------|-------------|
+| media_bazarr | Exited |
+
+### Summary
+- **Updates:** X
+- **Creates:** Y
+- **Removals/Offline:** Z
+```
+
+### Phase 5: User Confirmation
+
+If not `--dry-run`:
+
+```
+The following changes will be applied:
+- Update device platform to "Ubuntu 24.04"
+- Create interface "tailscale0"
+- Create IP "100.x.x.x/32" on tailscale0
+- Create VM "media_lidarr" in cluster
+- Mark VM "media_bazarr" as offline
+
+Proceed with sync? [Y/n]
+```
+
+**Use AskUserQuestion** to get confirmation.
+
+### Phase 6: Apply Updates (via MCP)
+
+Only if user confirms (or `--full` specified):
+
+#### 6.1 Device Updates
+
+```
+dcim_update_device
+  id=<device_id>
+  platform=<new_platform_id>
+  # ... other changed fields
+```
+
+#### 6.2 Interface Updates
+
+**For new interfaces:**
+```
+dcim_create_interface
+  device=<device_id>
+  name=<interface_name>
+  type=<type>
+  mac_address=<mac>
+  enabled=true
+```
+
+**For removed interfaces:**
+```
+dcim_update_interface
+  id=<interface_id>
+  enabled=false
+  description="Marked offline by cmdb-sync - interface no longer present"
+```
+
+**For changed interfaces:**
+```
+dcim_update_interface
+  id=<interface_id>
+  mac_address=<new_mac>
+```
+
+#### 6.3 IP Address Updates
+
+**For new IPs:**
+```
+ipam_create_ip_address
+  address=<ip/prefix>
+  assigned_object_type="dcim.interface"
+  assigned_object_id=<interface_id>
+  status="active"
+```
+
+**For removed IPs:**
+```
+ipam_update_ip_address
+  id=<ip_id>
+  assigned_object_type=null
+  assigned_object_id=null
+  description="Unassigned by cmdb-sync"
+```
+
+#### 6.4 Primary IP Update
+
+If primary IP changed:
+```
+dcim_update_device
+  id=<device_id>
+  primary_ip4=<new_primary_ip_id>
+```
+
+#### 6.5 Container/VM Updates
+
+**For new containers:**
+```
+virt_create_vm
+  name=<container_name>
+  cluster=<cluster_id>
+  status="active"
+  # ... other fields
+```
+
+**For stopped containers:**
+```
+virt_update_vm
+  id=<vm_id>
+  status="offline"
+  description="Container stopped - detected by cmdb-sync"
+```
+
+### Phase 7: Journal Entry
+
+Document the sync:
+
+```
+extras_create_journal_entry
+  assigned_object_type="dcim.device"
+  assigned_object_id=<device_id>
+  comments="Device synced via /cmdb-sync command\n\nChanges applied:\n- <list of changes>"
+```
+
+### Phase 8: Summary Report
+
+```markdown
+## Sync Complete
+
+**Device:** <hostname>
+**Sync Time:** <timestamp>
+
+### Changes Applied
+- Updated platform: Ubuntu 22.04 → Ubuntu 24.04
+- Created interface: tailscale0 (ID: X)
+- Created IP: 100.x.x.x/32 (ID: Y)
+- Created VM: media_lidarr (ID: Z)
+- Marked VM offline: media_bazarr (ID: W)
+
+### Current State
+- **Interfaces:** 4 (3 active, 1 offline)
+- **IP Addresses:** 5
+- **Containers/VMs:** 8 (7 active, 1 offline)
+
+### Next Sync
+Run `/cmdb-sync` again after:
+- Adding/removing Docker containers
+- Changing network configuration
+- OS upgrades
+```
+
+## Dry Run Mode
+
+If `--dry-run` specified:
+- Complete Phase 1-4 (lookup, discovery, compare, diff report)
+- Skip Phase 5-8 (no confirmation, no updates, no journal)
+- End with: "Dry run complete. No changes applied. Run without --dry-run to apply."
+
+## Full Sync Mode
+
+If `--full` specified:
+- Skip user confirmation
+- Update all fields even if unchanged (force refresh)
+- Useful for ensuring NetBox matches current state exactly
+
+## Error Handling
+
+- **Device not found:** Suggest `/cmdb-register`
+- **Permission denied on updates:** Note which failed, continue with others
+- **Cluster not found:** Offer to create or skip container sync
+- **API errors:** Log error, continue with remaining updates
+
+## User Request
+
+$ARGUMENTS

plugins/cmdb-assistant/hooks/hooks.json

@@ -0,0 +1,21 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "mcp__plugin_cmdb-assistant_netbox__virt_create|mcp__plugin_cmdb-assistant_netbox__virt_update|mcp__plugin_cmdb-assistant_netbox__dcim_create|mcp__plugin_cmdb-assistant_netbox__dcim_update",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate-input.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/cmdb-assistant/hooks/startup-check.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# cmdb-assistant SessionStart hook
+# Tests NetBox API connectivity and checks for data quality issues
+# All output MUST have [cmdb-assistant] prefix
+# Non-blocking: always exits 0
+
+set -euo pipefail
+
+PREFIX="[cmdb-assistant]"
+
+# Load NetBox configuration
+NETBOX_CONFIG="$HOME/.config/claude/netbox.env"
+
+if [[ ! -f "$NETBOX_CONFIG" ]]; then
+    echo "$PREFIX NetBox not configured - run /cmdb-assistant:initial-setup"
+    exit 0
+fi
+
+# Source config
+source "$NETBOX_CONFIG"
+
+# Validate required variables
+if [[ -z "${NETBOX_API_URL:-}" ]] || [[ -z "${NETBOX_API_TOKEN:-}" ]]; then
+    echo "$PREFIX Missing NETBOX_API_URL or NETBOX_API_TOKEN in config"
+    exit 0
+fi
+
+# Quick API connectivity test (5s timeout)
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" -m 5 \
+    -H "Authorization: Token $NETBOX_API_TOKEN" \
+    -H "Accept: application/json" \
+    "${NETBOX_API_URL}/" 2>/dev/null || echo "000")
+
+if [[ "$HTTP_CODE" == "000" ]]; then
+    echo "$PREFIX NetBox API unreachable (timeout/connection error)"
+    exit 0
+elif [[ "$HTTP_CODE" != "200" ]]; then
+    echo "$PREFIX NetBox API returned HTTP $HTTP_CODE - check credentials"
+    exit 0
+fi
+
+# Check for VMs without site assignment (data quality)
+VMS_RESPONSE=$(curl -s -m 5 \
+    -H "Authorization: Token $NETBOX_API_TOKEN" \
+    -H "Accept: application/json" \
+    "${NETBOX_API_URL}/virtualization/virtual-machines/?site__isnull=true&limit=1" 2>/dev/null || echo '{"count":0}')
+
+VMS_NO_SITE=$(echo "$VMS_RESPONSE" | grep -o '"count":[0-9]*' | cut -d: -f2 || echo "0")
+
+if [[ "$VMS_NO_SITE" -gt 0 ]]; then
+    echo "$PREFIX $VMS_NO_SITE VMs without site assignment - run /cmdb-audit for details"
+fi
+
+# Check for devices without platform
+DEVICES_RESPONSE=$(curl -s -m 5 \
+    -H "Authorization: Token $NETBOX_API_TOKEN" \
+    -H "Accept: application/json" \
+    "${NETBOX_API_URL}/dcim/devices/?platform__isnull=true&limit=1" 2>/dev/null || echo '{"count":0}')
+
+DEVICES_NO_PLATFORM=$(echo "$DEVICES_RESPONSE" | grep -o '"count":[0-9]*' | cut -d: -f2 || echo "0")
+
+if [[ "$DEVICES_NO_PLATFORM" -gt 0 ]]; then
+    echo "$PREFIX $DEVICES_NO_PLATFORM devices without platform - consider updating"
+fi
+
+exit 0

plugins/cmdb-assistant/hooks/validate-input.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# cmdb-assistant PreToolUse validation hook
+# Validates input parameters for create/update operations
+# NON-BLOCKING: Warns but allows operation to proceed (always exits 0)
+
+set -euo pipefail
+
+PREFIX="[cmdb-assistant]"
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract tool name from the input
+# Format varies, try to find tool_name or name field
+TOOL_NAME=""
+if echo "$INPUT" | grep -q '"tool_name"'; then
+    TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/' || true)
+elif echo "$INPUT" | grep -q '"name"'; then
+    TOOL_NAME=$(echo "$INPUT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/' || true)
+fi
+
+# If we can't determine the tool, exit silently
+if [[ -z "$TOOL_NAME" ]]; then
+    exit 0
+fi
+
+# VM creation/update validation
+if echo "$TOOL_NAME" | grep -qE "virt_create_vm|virt_create_virtual_machine|virt_update_vm|virt_update_virtual_machine"; then
+    WARNINGS=()
+
+    # Check for missing site
+    if ! echo "$INPUT" | grep -qE '"site"[[:space:]]*:[[:space:]]*[0-9]'; then
+        WARNINGS+=("no site assigned")
+    fi
+
+    # Check for missing tenant
+    if ! echo "$INPUT" | grep -qE '"tenant"[[:space:]]*:[[:space:]]*[0-9]'; then
+        WARNINGS+=("no tenant assigned")
+    fi
+
+    # Check for missing platform
+    if ! echo "$INPUT" | grep -qE '"platform"[[:space:]]*:[[:space:]]*[0-9]'; then
+        WARNINGS+=("no platform assigned")
+    fi
+
+    if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+        echo "$PREFIX VM best practice: $(IFS=', '; echo "${WARNINGS[*]}") - consider assigning for data quality"
+    fi
+fi
+
+# Device creation/update validation
+if echo "$TOOL_NAME" | grep -qE "dcim_create_device|dcim_update_device"; then
+    WARNINGS=()
+
+    # Check for missing platform
+    if ! echo "$INPUT" | grep -qE '"platform"[[:space:]]*:[[:space:]]*[0-9]'; then
+        WARNINGS+=("no platform assigned")
+    fi
+
+    # Check for missing tenant
+    if ! echo "$INPUT" | grep -qE '"tenant"[[:space:]]*:[[:space:]]*[0-9]'; then
+        WARNINGS+=("no tenant assigned")
+    fi
+
+    if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+        echo "$PREFIX Device best practice: $(IFS=', '; echo "${WARNINGS[*]}") - consider assigning"
+    fi
+fi
+
+# Cluster creation validation
+if echo "$TOOL_NAME" | grep -qE "virt_create_cluster"; then
+    # Check for missing site scope
+    if ! echo "$INPUT" | grep -qE '"site"[[:space:]]*:[[:space:]]*[0-9]'; then
+        echo "$PREFIX Cluster best practice: no site scope - clusters should be scoped to a site"
+    fi
+fi
+
+# Always allow operation (non-blocking)
+exit 0

plugins/cmdb-assistant/skills/netbox-patterns/SKILL.md

@@ -0,0 +1,249 @@
+---
+description: NetBox best practices for data quality and consistency based on official NetBox Labs guidelines
+---
+
+# NetBox Best Practices Skill
+
+Reference documentation for proper NetBox data modeling, following official NetBox Labs guidelines.
+
+## CRITICAL: Dependency Order
+
+Objects must be created in this order due to foreign key dependencies. Creating objects out of order results in validation errors.
+
+```
+1. ORGANIZATION (no dependencies)
+   ├── Tenant Groups
+   ├── Tenants (optional: Tenant Group)
+   ├── Regions
+   ├── Site Groups
+   └── Tags
+
+2. SITES AND LOCATIONS
+   ├── Sites (optional: Region, Site Group, Tenant)
+   └── Locations (requires: Site, optional: parent Location)
+
+3. DCIM PREREQUISITES
+   ├── Manufacturers
+   ├── Device Types (requires: Manufacturer)
+   ├── Platforms
+   ├── Device Roles
+   └── Rack Roles
+
+4. RACKS
+   └── Racks (requires: Site, optional: Location, Rack Role, Tenant)
+
+5. DEVICES
+   ├── Devices (requires: Device Type, Role, Site; optional: Rack, Location)
+   └── Interfaces (requires: Device)
+
+6. VIRTUALIZATION
+   ├── Cluster Types
+   ├── Cluster Groups
+   ├── Clusters (requires: Cluster Type, optional: Site)
+   ├── Virtual Machines (requires: Cluster OR Site)
+   └── VM Interfaces (requires: Virtual Machine)
+
+7. IPAM
+   ├── VRFs (optional: Tenant)
+   ├── Prefixes (optional: VRF, Site, Tenant)
+   ├── IP Addresses (optional: VRF, Tenant, Interface)
+   └── VLANs (optional: Site, Tenant)
+
+8. CONNECTIONS (last)
+   └── Cables (requires: endpoints)
+```
+
+**Key Rule:** NEVER create a VM before its cluster exists. NEVER create a device before its site exists.
+
+## HIGH: Site Assignment
+
+**All infrastructure objects should have a site:**
+
+| Object Type | Site Requirement |
+|-------------|------------------|
+| Devices | **REQUIRED** |
+| Racks | **REQUIRED** |
+| VMs | RECOMMENDED (via cluster or direct) |
+| Clusters | RECOMMENDED |
+| Prefixes | RECOMMENDED |
+| VLANs | RECOMMENDED |
+
+**Why Sites Matter:**
+- Location-based queries and filtering
+- Power and capacity budgeting
+- Physical inventory tracking
+- Compliance and audit requirements
+
+## HIGH: Tenant Usage
+
+Use tenants for logical resource separation:
+
+**When to Use Tenants:**
+- Multi-team environments (assign resources to teams)
+- Multi-customer scenarios (MSP, hosting)
+- Cost allocation requirements
+- Access control boundaries
+
+**Apply Tenants To:**
+- Sites (who owns the physical location)
+- Devices (who operates the hardware)
+- VMs (who owns the workload)
+- Prefixes (who owns the IP space)
+- VLANs (who owns the network segment)
+
+## HIGH: Platform Tracking
+
+Platforms track OS/runtime information for automation and lifecycle management.
+
+**Platform Examples:**
+| Device Type | Platform Examples |
+|-------------|-------------------|
+| Servers | Ubuntu 24.04, Windows Server 2022, RHEL 9 |
+| Network | Cisco IOS 17.x, Junos 23.x, Arista EOS |
+| Raspberry Pi | Raspberry Pi OS (Bookworm), Ubuntu Server ARM |
+| Containers | Docker Container (as runtime indicator) |
+
+**Benefits:**
+- Vulnerability tracking (CVE correlation)
+- Configuration management integration
+- Lifecycle management (EOL tracking)
+- Automation targeting
+
+## MEDIUM: Tag Conventions
+
+Use tags for cross-cutting classification that spans object types.
+
+**Recommended Tag Patterns:**
+
+| Pattern | Purpose | Examples |
+|---------|---------|----------|
+| `env:*` | Environment classification | `env:production`, `env:staging`, `env:development` |
+| `app:*` | Application grouping | `app:web`, `app:database`, `app:monitoring` |
+| `team:*` | Ownership | `team:platform`, `team:infra`, `team:devops` |
+| `backup:*` | Backup policy | `backup:daily`, `backup:weekly`, `backup:none` |
+| `monitoring:*` | Monitoring level | `monitoring:critical`, `monitoring:standard` |
+
+**Tags vs Custom Fields:**
+- Tags: Cross-object classification, multiple values, filtering
+- Custom Fields: Object-specific structured data, single values, reporting
+
+## MEDIUM: Naming Conventions
+
+Consistent naming improves searchability and automation compatibility.
+
+**Recommended Patterns:**
+
+| Object Type | Pattern | Examples |
+|-------------|---------|----------|
+| Devices | `{role}-{location}-{number}` | `web-dc1-01`, `db-cloud-02`, `fw-home-01` |
+| VMs | `{env}-{app}-{number}` | `prod-api-01`, `dev-worker-03` |
+| Clusters | `{site}-{type}` | `dc1-vmware`, `home-docker` |
+| Prefixes | Include purpose in description | "Production web tier /24" |
+| VLANs | `{site}-{function}` | `dc1-mgmt`, `home-iot` |
+
+**Avoid:**
+- Inconsistent casing (mixing `HotServ` and `hotserv`)
+- Mixed separators (mixing `hhl_cluster` and `media-cluster`)
+- Generic names without context (`server1`, `vm2`)
+- Special characters other than hyphen
+
+## MEDIUM: Role Consolidation
+
+Avoid role fragmentation - use general roles with platform/tags for specificity.
+
+**Instead of:**
+```
+nginx-web-server
+apache-web-server
+web-server-frontend
+web-server-api
+```
+
+**Use:**
+```
+web-server (role) + platform (nginx/apache) + tags (frontend, api)
+```
+
+**Recommended Role Categories:**
+
+| Category | Roles |
+|----------|-------|
+| Infrastructure | `hypervisor`, `storage-server`, `network-device`, `firewall` |
+| Compute | `application-server`, `database-server`, `web-server`, `api-server` |
+| Services | `container-host`, `load-balancer`, `monitoring-server`, `backup-server` |
+| Development | `development-workstation`, `ci-runner`, `build-server` |
+| Containers | `reverse-proxy`, `database`, `cache`, `queue`, `worker` |
+
+## Docker Containers as VMs
+
+NetBox's Virtualization module can model Docker containers:
+
+**Approach:**
+1. Create device for physical Docker host
+2. Create cluster (type: "Docker Compose" or "Docker Swarm")
+3. Associate cluster with host device
+4. Create VMs for each container in the cluster
+
+**VM Fields for Containers:**
+- `name`: Container name (e.g., `media_jellyfin`)
+- `role`: Container function (e.g., `Media Server`)
+- `vcpus`: CPU limit/shares
+- `memory`: Memory limit (MB)
+- `disk`: Volume size estimate
+- `description`: Container purpose
+- `comments`: Image, ports, volumes, dependencies
+
+**This is a pragmatic modeling choice** - containers aren't VMs, but the Virtualization module is the closest fit for tracking container workloads.
+
+## Primary IP Workflow
+
+To set a device/VM's primary IP:
+
+1. Create interface on device/VM
+2. Create IP address assigned to interface
+3. Set IP as `primary_ip4` or `primary_ip6` on device/VM
+
+**Why Primary IP Matters:**
+- Used for device connectivity checks
+- Displayed in device list views
+- Used by automation tools (NAPALM, Ansible)
+- Required for many integrations
+
+## Data Quality Checklist
+
+Before closing a sprint or audit:
+
+- [ ] All VMs have site assignment (direct or via cluster)
+- [ ] All VMs have tenant assignment
+- [ ] All active devices have platform
+- [ ] All active devices have primary IP
+- [ ] Naming follows conventions
+- [ ] No orphaned prefixes (allocated but unused)
+- [ ] Tags applied consistently
+- [ ] Clusters scoped to sites
+- [ ] Roles not overly fragmented
+
+## MCP Tool Reference
+
+**Dependency Order for Creation:**
+```
+1. dcim_create_site
+2. dcim_create_manufacturer
+3. dcim_create_device_type
+4. dcim_create_device_role
+5. dcim_create_platform
+6. dcim_create_device
+7. virt_create_cluster_type
+8. virt_create_cluster
+9. virt_create_vm
+10. dcim_create_interface / virt_create_vm_interface
+11. ipam_create_ip_address
+12. dcim_update_device (set primary_ip4)
+```
+
+**Lookup Before Create:**
+Always check if object exists before creating to avoid duplicates:
+```
+1. dcim_list_devices name=<hostname>
+2. If exists, update; if not, create
+```

plugins/contract-validator/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "contract-validator",
+  "version": "1.0.0",
+  "description": "Cross-plugin compatibility validation and Claude.md agent verification",
+  "author": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/contract-validator/README.md",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+  "license": "MIT",
+  "keywords": [
+    "validation",
+    "contracts",
+    "compatibility",
+    "agents",
+    "interfaces",
+    "cross-plugin"
+  ],
+  "commands": ["./commands/"],
+  "mcpServers": ["./.mcp.json"]
+}

plugins/contract-validator/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "contract-validator": {
+      "type": "stdio",
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/contract-validator/run.sh",
+      "args": []
+    }
+  }
+}

plugins/contract-validator/README.md

@@ -0,0 +1,157 @@
+# contract-validator Plugin
+
+Cross-plugin compatibility validation and CLAUDE.md agent verification for Claude Code plugin marketplaces.
+
+## Problem Statement
+
+As plugin marketplaces grow, several compatibility issues emerge:
+
+- **Command conflicts**: Multiple plugins defining the same slash command (e.g., `/initial-setup`)
+- **Tool name overlaps**: Different plugins using identical tool names with incompatible interfaces
+- **Undocumented dependencies**: Agents referencing tools that don't exist
+- **Broken data flows**: Agent sequences that expect outputs not produced by prior steps
+
+Contract-validator solves these by parsing plugin interfaces and validating compatibility before runtime.
+
+## Features
+
+- **Interface Parsing**: Extract commands, agents, and tools from plugin README.md files
+- **Agent Extraction**: Parse CLAUDE.md Four-Agent Model tables and Agents sections
+- **Compatibility Checks**: Pairwise validation between all plugins in a marketplace
+- **Data Flow Validation**: Verify agent tool sequences have valid data producers/consumers
+- **Comprehensive Reports**: Markdown or JSON reports with actionable suggestions
+
+## Installation
+
+This plugin is part of the leo-claude-mktplace. Install via:
+
+```bash
+# From marketplace
+claude plugins install leo-claude-mktplace/contract-validator
+
+# Setup MCP server venv
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/initial-setup` | Interactive setup wizard |
+| `/validate-contracts` | Full marketplace compatibility validation |
+| `/check-agent` | Validate single agent definition |
+| `/list-interfaces` | Show all plugin interfaces |
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `full-validation` | Complete cross-plugin compatibility validation |
+| `agent-check` | Single agent definition verification |
+
+## Tools Summary
+
+### Parse Tools (2)
+- `parse_plugin_interface` - Extract interface from plugin README.md
+- `parse_claude_md_agents` - Extract agents from CLAUDE.md
+
+### Validation Tools (3)
+- `validate_compatibility` - Check two plugins for conflicts
+- `validate_agent_refs` - Verify agent tool references exist
+- `validate_data_flow` - Check data flow through agent sequences
+
+### Report Tools (2)
+- `generate_compatibility_report` - Full marketplace validation report
+- `list_issues` - Filter issues by severity or type
+
+## Example Workflow
+
+```
+/validate-contracts ~/claude-plugins-work
+
+# Output:
+# Contract Validation Report
+#
+# | Metric     | Count |
+# |------------|-------|
+# | Plugins    | 12    |
+# | Commands   | 39    |
+# | Tools      | 32    |
+# | **Issues** | **7** |
+# | - Errors   | 3     |
+# | - Warnings | 0     |
+# | - Info     | 4     |
+#
+# ## Issues Found
+# [ERROR] Command conflict: projman and data-platform both define /initial-setup
+# [ERROR] Command conflict: projman and pr-review both define /initial-setup
+# ...
+```
+
+```
+/check-agent Planner ./CLAUDE.md
+
+# Output:
+# Agent: Planner
+# Status: VALID
+#
+# Tool References Found (3):
+# - create_issue ✓
+# - search_lessons ✓
+# - get_execution_order ✓
+#
+# Data Flow: No issues detected
+```
+
+## Issue Types
+
+| Type | Severity | Description |
+|------|----------|-------------|
+| `interface_mismatch` | ERROR | Command name conflict between plugins |
+| `missing_tool` | ERROR | Agent references non-existent tool |
+| `interface_mismatch` | WARNING | Tool name overlap (different plugins) |
+| `optional_dependency` | WARNING | Agent uses tool from non-required plugin |
+| `undeclared_output` | INFO | Agent has no documented tool references |
+
+## Parsed Interface Structure
+
+When parsing a plugin README.md, the following structure is extracted:
+
+```json
+{
+  "plugin_name": "data-platform",
+  "description": "Data engineering tools...",
+  "commands": [
+    {"name": "/ingest", "description": "Load data..."}
+  ],
+  "agents": [
+    {"name": "data-analysis", "description": "..."}
+  ],
+  "tools": [
+    {"name": "read_csv", "category": "pandas"}
+  ],
+  "tool_categories": {
+    "pandas": ["read_csv", "to_csv", ...],
+    "PostgreSQL": ["pg_query", ...]
+  },
+  "features": ["pandas Operations", "PostgreSQL/PostGIS", ...]
+}
+```
+
+## Best Practices
+
+### For Plugin Authors
+
+1. **Use unique command names**: Prefix with plugin name if generic (e.g., `/data-setup` vs `/initial-setup`)
+2. **Document all tools**: Include tool names in README.md with backticks
+3. **Specify tool categories**: Use `### Category (N tools)` headers
+4. **Declare agent tools**: List tools used by agents in their definitions
+
+### For Marketplace Maintainers
+
+1. **Run validation before merging**: Use `/validate-contracts` in CI/CD
+2. **Review warnings**: Tool overlaps may indicate design issues
+3. **Track issues over time**: Use JSON format for programmatic tracking

plugins/contract-validator/agents/agent-check.md

@@ -0,0 +1,90 @@
+# Agent Check Agent
+
+You are an agent definition validator. Your role is to verify that a specific agent's tool references and data flow are valid.
+
+## Capabilities
+
+- Parse agent definitions from CLAUDE.md
+- Validate tool references against available plugins
+- Verify data flow patterns through agent sequences
+- Provide detailed validation feedback
+
+## Available Tools
+
+### Parsing
+- `parse_claude_md_agents` - Extract all agents from CLAUDE.md
+- `parse_plugin_interface` - Extract interface from plugin (for available tools)
+
+### Validation
+- `validate_agent_refs` - Check agent tool references exist
+- `validate_data_flow` - Verify data flow through agent sequence
+
+### Reporting
+- `list_issues` - Filter issues for this agent
+
+## Workflow
+
+1. **Locate the agent**:
+   - Use `parse_claude_md_agents` on specified CLAUDE.md
+   - Find agent by name (case-insensitive match)
+   - If not found, list available agents
+
+2. **Gather available tools**:
+   - Scan plugins directory for available plugins
+   - For each plugin, use `parse_plugin_interface`
+   - Build set of all available tool names
+
+3. **Validate tool references**:
+   - Use `validate_agent_refs` with agent name and plugin paths
+   - Report found tools (valid references)
+   - Report missing tools (errors)
+   - Suggest corrections for typos
+
+4. **Validate data flow**:
+   - Use `validate_data_flow` to check sequence
+   - Verify data producers precede consumers
+   - Check for orphaned data references
+   - Identify potential flow issues
+
+5. **Report findings**:
+   - Agent name and source file
+   - Responsibilities extracted
+   - Tool references: found vs missing
+   - Data flow validation results
+   - Suggestions for improvement
+
+## Validation Rules
+
+### Tool Reference Rules
+- All referenced tools must exist in available plugins
+- Tool names are case-sensitive
+- Partial matches suggest typos
+
+### Data Flow Rules
+- Data producers (read_csv, pg_query, etc.) should precede consumers
+- Data consumers (describe, head, to_csv, etc.) need valid data_ref
+- Workflow steps should have logical sequence
+
+## Issue Severities
+
+- **ERROR**: Tool reference not found - agent will fail
+- **WARNING**: Data flow issue - agent may produce unexpected results
+- **INFO**: Undocumented reference - consider adding documentation
+
+## Example Interaction
+
+**User**: /check-agent Orchestrator
+
+**Agent**:
+1. Parses CLAUDE.md, finds Orchestrator agent
+2. Extracts responsibilities: "Sprint execution, parallel batching, Git operations"
+3. Finds tool refs: create_issue, update_issue, search_lessons
+4. Validates against plugins: all tools found in projman/gitea
+5. Validates data flow: no data producers/consumers used
+6. Reports: "Agent Orchestrator: VALID - all 3 tool references found"
+
+**User**: /check-agent InvalidAgent
+
+**Agent**:
+1. Parses CLAUDE.md, agent not found
+2. Reports: "Agent 'InvalidAgent' not found. Available agents: Planner, Orchestrator, Executor, Code Reviewer"

plugins/contract-validator/agents/full-validation.md

@@ -0,0 +1,87 @@
+# Full Validation Agent
+
+You are a contract validation specialist. Your role is to perform comprehensive cross-plugin compatibility validation for the entire marketplace.
+
+## Capabilities
+
+- Parse plugin interfaces from README.md files
+- Parse agent definitions from CLAUDE.md files
+- Validate cross-plugin compatibility
+- Identify interface mismatches and conflicts
+- Generate detailed validation reports
+
+## Available Tools
+
+### Parsing
+- `parse_plugin_interface` - Extract interface from plugin README.md
+- `parse_claude_md_agents` - Extract agents from CLAUDE.md
+
+### Validation
+- `validate_compatibility` - Check two plugins for conflicts
+- `validate_agent_refs` - Verify agent tool references exist
+- `validate_data_flow` - Check data flow through agent sequences
+
+### Reporting
+- `generate_compatibility_report` - Full marketplace report
+- `list_issues` - Filter issues by severity/type
+
+## Workflow
+
+1. **Discover plugins**:
+   - Locate marketplace plugins directory
+   - Identify plugins by `.claude-plugin/` marker
+   - Build list of all plugins to validate
+
+2. **Parse all interfaces**:
+   - For each plugin, use `parse_plugin_interface`
+   - Extract commands, agents, tools from README.md
+   - Track tool categories and features
+
+3. **Run pairwise compatibility checks**:
+   - For each pair of plugins, use `validate_compatibility`
+   - Check for command name conflicts (ERROR)
+   - Check for tool name overlaps (WARNING)
+   - Identify interface mismatches
+
+4. **Validate CLAUDE.md agents** (if present):
+   - Use `parse_claude_md_agents` on project CLAUDE.md
+   - For each agent, use `validate_agent_refs`
+   - Use `validate_data_flow` to check sequences
+
+5. **Generate comprehensive report**:
+   - Use `generate_compatibility_report`
+   - Format: markdown for human review, JSON for programmatic use
+   - Include summary statistics and detailed findings
+
+## Report Structure
+
+### Summary
+- Total plugins scanned
+- Total commands, agents, tools found
+- Issue counts by severity (error/warning/info)
+
+### Compatibility Matrix
+- Plugin pairs with conflicts
+- Shared tools between plugins
+- Unique tools per plugin
+
+### Issues List
+- ERROR: Command name conflicts (must fix)
+- WARNING: Tool name overlaps (review needed)
+- INFO: Undocumented references (improve docs)
+
+### Recommendations
+- Actionable suggestions per issue
+- Priority order for fixes
+
+## Example Interaction
+
+**User**: /validate-contracts ~/claude-plugins-work
+
+**Agent**:
+1. Discovers 12 plugins in marketplace
+2. Parses all README.md files
+3. Runs 66 pairwise compatibility checks
+4. Finds 3 errors, 4 warnings
+5. Reports: "Command conflict: projman and data-platform both define /initial-setup"
+6. Suggests: "Rename one command to avoid ambiguity"

plugins/contract-validator/claude-md-integration.md

@@ -0,0 +1,152 @@
+# contract-validator Plugin - CLAUDE.md Integration
+
+Add this section to your marketplace or project's CLAUDE.md to enable contract validation features.
+
+## Suggested CLAUDE.md Section
+
+```markdown
+## Contract Validation
+
+This marketplace uses the contract-validator plugin for cross-plugin compatibility checks.
+
+### Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/validate-contracts` | Full marketplace compatibility validation |
+| `/check-agent` | Validate single agent definition |
+| `/list-interfaces` | Show all plugin interfaces |
+
+### Validation Workflow
+
+Run before merging plugin changes:
+
+1. `/validate-contracts` - Check for conflicts
+2. Review errors (must fix) and warnings (should review)
+3. Fix issues before merging
+
+### Interface Documentation Standards
+
+For plugins to be validated correctly, document interfaces in README.md:
+
+**Commands Section:**
+```markdown
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/my-command` | What it does |
+```
+
+**Tools Section:**
+```markdown
+## Tools Summary
+
+### Category (N tools)
+`tool_a`, `tool_b`, `tool_c`
+```
+
+**Agents Section:**
+```markdown
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `my-agent` | What it does |
+```
+```
+
+## Declaring Agent Tool References
+
+For agent validation to work, document tool usage in CLAUDE.md:
+
+### Option 1: Four-Agent Model Table
+
+```markdown
+### Four-Agent Model
+
+| Agent | Personality | Responsibilities |
+|-------|-------------|------------------|
+| **Planner** | Methodical | Planning via `create_issue`, `search_lessons` |
+```
+
+### Option 2: Agent Sections
+
+```markdown
+### Planner Agent
+
+Uses these tools:
+- `create_issue` - Create planning issues
+- `search_lessons` - Find relevant lessons
+```
+
+## Best Practices for Plugin Authors
+
+### Unique Command Names
+
+Avoid generic names that may conflict:
+
+```markdown
+# BAD - Will conflict with other plugins
+| `/setup` | Setup wizard |
+
+# GOOD - Plugin-specific prefix
+| `/data-setup` | Data platform setup wizard |
+```
+
+### Document All Tools
+
+Ensure every MCP tool is listed in README.md:
+
+```markdown
+## Tools Summary
+
+### pandas (14 tools)
+`read_csv`, `read_parquet`, `read_json`, `to_csv`, `to_parquet`,
+`describe`, `head`, `tail`, `filter`, `select`, `groupby`, `join`,
+`list_data`, `drop_data`
+```
+
+### Specify Dependencies
+
+If agents depend on tools from other plugins, document it:
+
+```markdown
+## Dependencies
+
+This agent uses tools from:
+- `projman` - Issue management (`create_issue`, `update_issue`)
+- `data-platform` - Data loading (`read_csv`, `describe`)
+```
+
+## Typical Workflows
+
+### Pre-Merge Validation
+
+```
+# Before merging new plugin
+/validate-contracts
+
+# Check specific agent after changes
+/check-agent Orchestrator
+```
+
+### Plugin Development
+
+```
+# See what interfaces exist
+/list-interfaces
+
+# After adding new command, verify no conflicts
+/validate-contracts
+```
+
+### CI/CD Integration
+
+Add to your pipeline:
+
+```yaml
+- name: Validate Plugin Contracts
+  run: |
+    claude --skill contract-validator:validate-contracts --args "${{ github.workspace }}"
+```

plugins/contract-validator/commands/check-agent.md

@@ -0,0 +1,51 @@
+# /check-agent - Validate Agent Definition
+
+Validate a single agent's tool references and data flow.
+
+## Usage
+
+```
+/check-agent <agent_name> [claude_md_path]
+```
+
+## Parameters
+
+- `agent_name` (required): Name of the agent to validate (e.g., "Planner", "Orchestrator")
+- `claude_md_path` (optional): Path to CLAUDE.md file. Defaults to `./CLAUDE.md`
+
+## Workflow
+
+1. **Parse agent definition**:
+   - Locate agent in CLAUDE.md (Four-Agent Model table or Agents section)
+   - Extract responsibilities, tool references, workflow steps
+
+2. **Validate tool references**:
+   - Check each referenced tool exists in available plugins
+   - Report missing or misspelled tool names
+   - Suggest corrections for common mistakes
+
+3. **Validate data flow**:
+   - Analyze sequence of tools in agent workflow
+   - Verify data producers precede data consumers
+   - Check for orphaned data references
+
+4. **Report findings**:
+   - List all tool references found
+   - List any missing tools
+   - Data flow validation results
+   - Suggestions for improvement
+
+## Examples
+
+```
+/check-agent Planner
+/check-agent Orchestrator ./CLAUDE.md
+/check-agent data-analysis ~/project/CLAUDE.md
+```
+
+## Available Tools
+
+Use these MCP tools:
+- `validate_agent_refs` - Check agent tool references exist
+- `validate_data_flow` - Verify data flow through agent sequence
+- `parse_claude_md_agents` - Parse all agents from CLAUDE.md

plugins/contract-validator/commands/initial-setup.md

@@ -0,0 +1,152 @@
+---
+description: Interactive setup wizard for contract-validator plugin - verifies MCP server and shows capabilities
+---
+
+# Contract-Validator Setup Wizard
+
+This command sets up the contract-validator plugin for cross-plugin compatibility validation.
+
+## Important Context
+
+- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
+- **MCP tools won't work until after setup + session restart**
+- **No external credentials required** - this plugin validates local files only
+
+---
+
+## Phase 1: Environment Validation
+
+### Step 1.1: Check Python Version
+
+```bash
+python3 --version
+```
+
+Requires Python 3.10+. If below, stop setup and inform user:
+```
+Python 3.10 or higher is required. Please install it and run /initial-setup again.
+```
+
+---
+
+## Phase 2: MCP Server Setup
+
+### Step 2.1: Locate Contract-Validator MCP Server
+
+```bash
+# If running from installed marketplace
+ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_INSTALLED"
+
+# If running from source
+ls -la ~/claude-plugins-work/mcp-servers/contract-validator/ 2>/dev/null || echo "NOT_FOUND_SOURCE"
+```
+
+Determine which path exists and use that as the MCP server path.
+
+### Step 2.2: Check Virtual Environment
+
+```bash
+ls -la /path/to/mcp-servers/contract-validator/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
+```
+
+### Step 2.3: Create Virtual Environment (if missing)
+
+```bash
+cd /path/to/mcp-servers/contract-validator && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
+```
+
+**If pip install fails:**
+- Show the error to the user
+- Suggest: "Check your internet connection and try again."
+
+---
+
+## Phase 3: Validation
+
+### Step 3.1: Verify MCP Server
+
+```bash
+cd /path/to/mcp-servers/contract-validator && .venv/bin/python -c "from mcp_server.server import ContractValidatorMCPServer; print('MCP Server OK')"
+```
+
+If this fails, check the error and report it to the user.
+
+### Step 3.2: Summary
+
+Display:
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║          CONTRACT-VALIDATOR SETUP COMPLETE                      ║
+╠════════════════════════════════════════════════════════════════╣
+║ MCP Server:        ✓ Ready                                      ║
+║ Parse Tools:       ✓ Available (2 tools)                        ║
+║ Validation Tools:  ✓ Available (3 tools)                        ║
+║ Report Tools:      ✓ Available (2 tools)                        ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+### Step 3.3: Session Restart Notice
+
+---
+
+**Session Restart Required**
+
+Restart your Claude Code session for MCP tools to become available.
+
+**After restart, you can:**
+- Run `/validate-contracts` to check all plugins for compatibility issues
+- Run `/check-agent` to validate a single agent definition
+- Run `/list-interfaces` to see all plugin commands and tools
+
+---
+
+## Available Tools
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| Parse | `parse_plugin_interface`, `parse_claude_md_agents` | Extract interfaces from README.md and agents from CLAUDE.md |
+| Validation | `validate_compatibility`, `validate_agent_refs`, `validate_data_flow` | Check conflicts, tool references, and data flows |
+| Report | `generate_compatibility_report`, `list_issues` | Generate reports and filter issues |
+
+---
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/validate-contracts` | Full marketplace compatibility validation |
+| `/check-agent` | Validate single agent definition |
+| `/list-interfaces` | Show all plugin interfaces |
+
+---
+
+## Use Cases
+
+### 1. Pre-Release Validation
+Run `/validate-contracts` before releasing a new marketplace version to catch:
+- Command name conflicts between plugins
+- Missing tool references in agents
+- Broken data flows
+
+### 2. Agent Development
+Run `/check-agent` when creating or modifying agents to verify:
+- All referenced tools exist
+- Data flows are valid
+- No undeclared dependencies
+
+### 3. Plugin Audit
+Run `/list-interfaces` to get a complete view of:
+- All commands across plugins
+- All tools available
+- Potential overlap areas
+
+---
+
+## No Configuration Required
+
+This plugin doesn't require any configuration files. It reads plugin manifests and README files directly from the filesystem.
+
+**Paths it scans:**
+- Marketplace: `~/.claude/plugins/marketplaces/leo-claude-mktplace/plugins/`
+- Source (if available): `~/claude-plugins-work/plugins/`

plugins/contract-validator/commands/list-interfaces.md

@@ -0,0 +1,58 @@
+# /list-interfaces - Show Plugin Interfaces
+
+Display what each plugin in the marketplace produces and accepts.
+
+## Usage
+
+```
+/list-interfaces [marketplace_path]
+```
+
+## Parameters
+
+- `marketplace_path` (optional): Path to marketplace root. Defaults to current project root.
+
+## Workflow
+
+1. **Discover plugins**:
+   - Scan plugins directory for all plugins with `.claude-plugin/` marker
+   - Read each plugin's README.md
+
+2. **Parse interfaces**:
+   - Extract commands (slash commands offered by plugin)
+   - Extract agents (autonomous agents defined)
+   - Extract tools (MCP tools provided)
+   - Identify tool categories and features
+
+3. **Display summary**:
+   - Table of plugins with command/agent/tool counts
+   - Detailed breakdown per plugin
+   - Tool categories and their contents
+
+## Output Format
+
+```
+| Plugin      | Commands | Agents | Tools |
+|-------------|----------|--------|-------|
+| projman     | 12       | 4      | 26    |
+| data-platform| 7       | 2      | 32    |
+| ...         | ...      | ...    | ...   |
+
+## projman
+- Commands: /sprint-plan, /sprint-start, ...
+- Agents: Planner, Orchestrator, Executor, Code Reviewer
+- Tools: list_issues, create_issue, ...
+```
+
+## Examples
+
+```
+/list-interfaces
+/list-interfaces ~/claude-plugins-work
+```
+
+## Available Tools
+
+Use these MCP tools:
+- `parse_plugin_interface` - Parse individual plugin README
+- `generate_compatibility_report` - Get full interface data (JSON format)

plugins/contract-validator/commands/validate-contracts.md

@@ -0,0 +1,50 @@
+# /validate-contracts - Full Contract Validation
+
+Run comprehensive cross-plugin compatibility validation for the entire marketplace.
+
+## Usage
+
+```
+/validate-contracts [marketplace_path]
+```
+
+## Parameters
+
+- `marketplace_path` (optional): Path to marketplace root. Defaults to current project root.
+
+## Workflow
+
+1. **Discover plugins**:
+   - Scan plugins directory for all plugins with `.claude-plugin/` marker
+   - Parse each plugin's README.md to extract interface
+
+2. **Run compatibility checks**:
+   - Perform pairwise compatibility validation between all plugins
+   - Check for command name conflicts
+   - Check for tool name overlaps
+   - Identify interface mismatches
+
+3. **Validate CLAUDE.md agents**:
+   - Parse agent definitions from CLAUDE.md
+   - Validate all tool references exist
+   - Check data flow through agent sequences
+
+4. **Generate report**:
+   - Summary statistics (plugins, commands, tools, issues)
+   - Detailed findings by severity (error, warning, info)
+   - Actionable suggestions for each issue
+
+## Examples
+
+```
+/validate-contracts
+/validate-contracts ~/claude-plugins-work
+```
+
+## Available Tools
+
+Use these MCP tools:
+- `generate_compatibility_report` - Generate full marketplace report
+- `list_issues` - Filter issues by severity or type
+- `parse_plugin_interface` - Parse individual plugin interface
+- `validate_compatibility` - Check two plugins for conflicts

plugins/contract-validator/hooks/auto-validate.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# contract-validator SessionStart auto-validate hook
+# Validates plugin contracts only when plugin files have changed since last check
+# All output MUST have [contract-validator] prefix
+
+PREFIX="[contract-validator]"
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+# Enable/disable auto-check (default: true)
+AUTO_CHECK="${CONTRACT_VALIDATOR_AUTO_CHECK:-true}"
+
+# Cache location for storing last check hash
+CACHE_DIR="$HOME/.cache/claude-plugins/contract-validator"
+HASH_FILE="$CACHE_DIR/last-check.hash"
+
+# Marketplace location (installed plugins)
+MARKETPLACE_PATH="$HOME/.claude/plugins/marketplaces/leo-claude-mktplace"
+
+# ============================================================================
+# Early exit if disabled
+# ============================================================================
+
+if [[ "$AUTO_CHECK" != "true" ]]; then
+    exit 0
+fi
+
+# ============================================================================
+# Smart mode: Check if plugin files have changed
+# ============================================================================
+
+# Function to compute hash of all plugin manifest files
+compute_plugin_hash() {
+    local hash_input=""
+
+    if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+        # Hash all plugin.json, hooks.json, and agent files
+        while IFS= read -r -d '' file; do
+            if [[ -f "$file" ]]; then
+                hash_input+="$(md5sum "$file" 2>/dev/null | cut -d' ' -f1)"
+            fi
+        done < <(find "$MARKETPLACE_PATH/plugins" \
+            \( -name "plugin.json" -o -name "hooks.json" -o -name "*.md" -path "*/agents/*" \) \
+            -print0 2>/dev/null | sort -z)
+    fi
+
+    # Also include marketplace.json
+    if [[ -f "$MARKETPLACE_PATH/.claude-plugin/marketplace.json" ]]; then
+        hash_input+="$(md5sum "$MARKETPLACE_PATH/.claude-plugin/marketplace.json" 2>/dev/null | cut -d' ' -f1)"
+    fi
+
+    # Compute final hash
+    echo "$hash_input" | md5sum | cut -d' ' -f1
+}
+
+# Ensure cache directory exists
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+# Compute current hash
+CURRENT_HASH=$(compute_plugin_hash)
+
+# Check if we have a previous hash
+if [[ -f "$HASH_FILE" ]]; then
+    PREVIOUS_HASH=$(cat "$HASH_FILE" 2>/dev/null)
+
+    # If hashes match, no changes - skip validation
+    if [[ "$CURRENT_HASH" == "$PREVIOUS_HASH" ]]; then
+        exit 0
+    fi
+fi
+
+# ============================================================================
+# Run validation (hashes differ or no cache)
+# ============================================================================
+
+ISSUES_FOUND=0
+WARNINGS=""
+
+# Function to add warning
+add_warning() {
+    WARNINGS+="  - $1"$'\n'
+    ((ISSUES_FOUND++))
+}
+
+# 1. Check all installed plugins have valid plugin.json
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    for plugin_dir in "$MARKETPLACE_PATH/plugins"/*/; do
+        if [[ -d "$plugin_dir" ]]; then
+            plugin_name=$(basename "$plugin_dir")
+            plugin_json="$plugin_dir/.claude-plugin/plugin.json"
+
+            if [[ ! -f "$plugin_json" ]]; then
+                add_warning "$plugin_name: missing .claude-plugin/plugin.json"
+                continue
+            fi
+
+            # Basic JSON validation
+            if ! python3 -c "import json; json.load(open('$plugin_json'))" 2>/dev/null; then
+                add_warning "$plugin_name: invalid JSON in plugin.json"
+                continue
+            fi
+
+            # Check required fields
+            if ! python3 -c "
+import json
+with open('$plugin_json') as f:
+    data = json.load(f)
+required = ['name', 'version', 'description']
+missing = [r for r in required if r not in data]
+if missing:
+    exit(1)
+" 2>/dev/null; then
+                add_warning "$plugin_name: plugin.json missing required fields"
+            fi
+        fi
+    done
+fi
+
+# 2. Check hooks.json files are properly formatted
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    while IFS= read -r -d '' hooks_file; do
+        plugin_name=$(basename "$(dirname "$(dirname "$hooks_file")")")
+
+        # Validate JSON
+        if ! python3 -c "import json; json.load(open('$hooks_file'))" 2>/dev/null; then
+            add_warning "$plugin_name: invalid JSON in hooks/hooks.json"
+            continue
+        fi
+
+        # Validate hook structure
+        if ! python3 -c "
+import json
+with open('$hooks_file') as f:
+    data = json.load(f)
+if 'hooks' not in data:
+    exit(1)
+valid_events = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart', 'SessionEnd', 'Notification', 'Stop', 'SubagentStop', 'PreCompact']
+for event in data['hooks']:
+    if event not in valid_events:
+        exit(1)
+    for hook in data['hooks'][event]:
+        # Support both flat structure (type at top) and nested structure (matcher + hooks array)
+        if 'type' in hook:
+            # Flat structure: {type: 'command', command: '...'}
+            pass
+        elif 'matcher' in hook and 'hooks' in hook:
+            # Nested structure: {matcher: '...', hooks: [{type: 'command', ...}]}
+            for nested_hook in hook['hooks']:
+                if 'type' not in nested_hook:
+                    exit(1)
+        else:
+            exit(1)
+" 2>/dev/null; then
+            add_warning "$plugin_name: hooks.json has invalid structure or events"
+        fi
+    done < <(find "$MARKETPLACE_PATH/plugins" -path "*/hooks/hooks.json" -print0 2>/dev/null)
+fi
+
+# 3. Check agent references are valid (agent files exist and are markdown)
+if [[ -d "$MARKETPLACE_PATH/plugins" ]]; then
+    while IFS= read -r -d '' agent_file; do
+        plugin_name=$(basename "$(dirname "$(dirname "$agent_file")")")
+        agent_name=$(basename "$agent_file")
+
+        # Check file is not empty
+        if [[ ! -s "$agent_file" ]]; then
+            add_warning "$plugin_name: empty agent file $agent_name"
+            continue
+        fi
+
+        # Check file has markdown content (at least a header)
+        if ! grep -q '^#' "$agent_file" 2>/dev/null; then
+            add_warning "$plugin_name: agent $agent_name missing markdown header"
+        fi
+    done < <(find "$MARKETPLACE_PATH/plugins" -path "*/agents/*.md" -print0 2>/dev/null)
+fi
+
+# ============================================================================
+# Store new hash and report results
+# ============================================================================
+
+# Always store the new hash (even if issues found - we don't want to recheck)
+echo "$CURRENT_HASH" > "$HASH_FILE"
+
+# Report any issues found (non-blocking warning)
+if [[ $ISSUES_FOUND -gt 0 ]]; then
+    echo "$PREFIX Plugin contract validation found $ISSUES_FOUND issue(s):"
+    echo "$WARNINGS"
+    echo "$PREFIX Run /validate-contracts for full details"
+fi
+
+# Always exit 0 (non-blocking)
+exit 0

plugins/contract-validator/hooks/breaking-change-check.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# contract-validator breaking change detection hook
+# Warns when plugin interface changes might break consumers
+# This is a PostToolUse hook - non-blocking, warnings only
+
+PREFIX="[contract-validator]"
+
+# Check if warnings are enabled (default: true)
+if [[ "${CONTRACT_VALIDATOR_BREAKING_WARN:-true}" != "true" ]]; then
+    exit 0
+fi
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is a plugin interface file
+is_interface_file() {
+    local file="$1"
+
+    case "$file" in
+        */plugin.json) return 0 ;;
+        */.claude-plugin/plugin.json) return 0 ;;
+        */hooks.json) return 0 ;;
+        */hooks/hooks.json) return 0 ;;
+        */.mcp.json) return 0 ;;
+        */agents/*.md) return 0 ;;
+        */commands/*.md) return 0 ;;
+        */skills/*.md) return 0 ;;
+    esac
+
+    return 1
+}
+
+# Exit if not an interface file
+if ! is_interface_file "$FILE_PATH"; then
+    exit 0
+fi
+
+# Check if file exists and is in a git repo
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Get the directory containing the file
+FILE_DIR=$(dirname "$FILE_PATH")
+FILE_NAME=$(basename "$FILE_PATH")
+
+# Try to get the previous version from git
+cd "$FILE_DIR" 2>/dev/null || exit 0
+
+# Check if we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    exit 0
+fi
+
+# Get previous version (HEAD version before current changes)
+PREV_CONTENT=$(git show HEAD:"$FILE_PATH" 2>/dev/null || echo "")
+
+# If no previous version, this is a new file - no breaking changes possible
+if [ -z "$PREV_CONTENT" ]; then
+    exit 0
+fi
+
+# Read current content
+CURR_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+
+if [ -z "$CURR_CONTENT" ]; then
+    exit 0
+fi
+
+BREAKING_CHANGES=()
+
+# Detect breaking changes based on file type
+case "$FILE_PATH" in
+    */plugin.json|*/.claude-plugin/plugin.json)
+        # Check for removed or renamed fields in plugin.json
+
+        # Check if name changed
+        PREV_NAME=$(echo "$PREV_CONTENT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+        CURR_NAME=$(echo "$CURR_CONTENT" | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1)
+        if [ -n "$PREV_NAME" ] && [ "$PREV_NAME" != "$CURR_NAME" ]; then
+            BREAKING_CHANGES+=("Plugin name changed - consumers may need updates")
+        fi
+
+        # Check if version had major bump (semantic versioning)
+        PREV_VER=$(echo "$PREV_CONTENT" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([0-9]*\)\..*/\1/')
+        CURR_VER=$(echo "$CURR_CONTENT" | grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([0-9]*\)\..*/\1/')
+        if [ -n "$PREV_VER" ] && [ -n "$CURR_VER" ] && [ "$CURR_VER" -gt "$PREV_VER" ] 2>/dev/null; then
+            BREAKING_CHANGES+=("Major version bump detected - verify breaking changes documented")
+        fi
+        ;;
+
+    */hooks.json|*/hooks/hooks.json)
+        # Check for removed hook events
+        PREV_EVENTS=$(echo "$PREV_CONTENT" | grep -oE '"(PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|SessionEnd|Notification|Stop|SubagentStop|PreCompact)"' | sort -u)
+        CURR_EVENTS=$(echo "$CURR_CONTENT" | grep -oE '"(PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|SessionEnd|Notification|Stop|SubagentStop|PreCompact)"' | sort -u)
+
+        # Find removed events
+        REMOVED_EVENTS=$(comm -23 <(echo "$PREV_EVENTS") <(echo "$CURR_EVENTS") 2>/dev/null)
+        if [ -n "$REMOVED_EVENTS" ]; then
+            BREAKING_CHANGES+=("Hook events removed: $(echo $REMOVED_EVENTS | tr '\n' ' ')")
+        fi
+
+        # Check for changed matchers
+        PREV_MATCHERS=$(echo "$PREV_CONTENT" | grep -o '"matcher"[[:space:]]*:[[:space:]]*"[^"]*"' | sort -u)
+        CURR_MATCHERS=$(echo "$CURR_CONTENT" | grep -o '"matcher"[[:space:]]*:[[:space:]]*"[^"]*"' | sort -u)
+        if [ "$PREV_MATCHERS" != "$CURR_MATCHERS" ]; then
+            BREAKING_CHANGES+=("Hook matchers changed - verify tool coverage")
+        fi
+        ;;
+
+    */.mcp.json)
+        # Check for removed MCP servers
+        PREV_SERVERS=$(echo "$PREV_CONTENT" | grep -o '"[^"]*"[[:space:]]*:' | grep -v "mcpServers" | sort -u)
+        CURR_SERVERS=$(echo "$CURR_CONTENT" | grep -o '"[^"]*"[[:space:]]*:' | grep -v "mcpServers" | sort -u)
+
+        REMOVED_SERVERS=$(comm -23 <(echo "$PREV_SERVERS") <(echo "$CURR_SERVERS") 2>/dev/null)
+        if [ -n "$REMOVED_SERVERS" ]; then
+            BREAKING_CHANGES+=("MCP servers removed - tools may be unavailable")
+        fi
+        ;;
+
+    */agents/*.md)
+        # Check if agent file was significantly reduced (might indicate removal of capabilities)
+        PREV_LINES=$(echo "$PREV_CONTENT" | wc -l)
+        CURR_LINES=$(echo "$CURR_CONTENT" | wc -l)
+
+        # If more than 50% reduction, warn
+        if [ "$PREV_LINES" -gt 10 ] && [ "$CURR_LINES" -lt $((PREV_LINES / 2)) ]; then
+            BREAKING_CHANGES+=("Agent definition significantly reduced - capabilities may be removed")
+        fi
+
+        # Check if agent name/description changed in frontmatter
+        PREV_DESC=$(echo "$PREV_CONTENT" | head -20 | grep -i "description" | head -1)
+        CURR_DESC=$(echo "$CURR_CONTENT" | head -20 | grep -i "description" | head -1)
+        if [ -n "$PREV_DESC" ] && [ "$PREV_DESC" != "$CURR_DESC" ]; then
+            BREAKING_CHANGES+=("Agent description changed - verify consumer expectations")
+        fi
+        ;;
+
+    */commands/*.md|*/skills/*.md)
+        # Check if command/skill was significantly changed
+        PREV_LINES=$(echo "$PREV_CONTENT" | wc -l)
+        CURR_LINES=$(echo "$CURR_CONTENT" | wc -l)
+
+        if [ "$PREV_LINES" -gt 10 ] && [ "$CURR_LINES" -lt $((PREV_LINES / 2)) ]; then
+            BREAKING_CHANGES+=("Command/skill significantly reduced - behavior may change")
+        fi
+        ;;
+esac
+
+# Output warnings if any breaking changes detected
+if [[ ${#BREAKING_CHANGES[@]} -gt 0 ]]; then
+    echo ""
+    echo "$PREFIX WARNING: Potential breaking changes in $(basename "$FILE_PATH")"
+    echo "$PREFIX ============================================"
+    for change in "${BREAKING_CHANGES[@]}"; do
+        echo "$PREFIX   - $change"
+    done
+    echo "$PREFIX ============================================"
+    echo "$PREFIX Consider updating CHANGELOG and notifying consumers"
+    echo ""
+fi
+
+# Always exit 0 - non-blocking
+exit 0

plugins/contract-validator/hooks/hooks.json

@@ -0,0 +1,21 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/auto-validate.sh"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/breaking-change-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/contract-validator/mcp-servers/contract-validator

@@ -0,0 +1 @@
+../../../mcp-servers/contract-validator

plugins/data-platform/.mcp.json

@@ -2,9 +2,8 @@
   "mcpServers": {
     "data-platform": {
       "type": "stdio",
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/data-platform/.venv/bin/python",
-      "args": ["-m", "mcp_server.server"],
-      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/data-platform"
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/data-platform/run.sh",
+      "args": []
     }
   }
 }

plugins/data-platform/hooks/hooks.json

@@ -5,6 +5,17 @@
         "type": "command",
         "command": "${CLAUDE_PLUGIN_ROOT}/hooks/startup-check.sh"
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/schema-diff-check.sh"
+          }
+        ]
+      }
     ]
   }
 }

plugins/data-platform/hooks/schema-diff-check.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# data-platform schema diff detection hook
+# Warns about potentially breaking schema changes
+# This is a command hook - non-blocking, warnings only
+
+PREFIX="[data-platform]"
+
+# Check if warnings are enabled (default: true)
+if [[ "${DATA_PLATFORM_SCHEMA_WARN:-true}" != "true" ]]; then
+    exit 0
+fi
+
+# Read tool input from stdin (JSON with file_path)
+INPUT=$(cat)
+
+# Extract file_path from JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no file_path found, exit silently
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file is a schema-related file
+is_schema_file() {
+    local file="$1"
+
+    # Check file extension
+    case "$file" in
+        *.sql) return 0 ;;
+        */migrations/*.py) return 0 ;;
+        */migrations/*.sql) return 0 ;;
+        */models/*.py) return 0 ;;
+        */models/*.sql) return 0 ;;
+        *schema.prisma) return 0 ;;
+        *schema.graphql) return 0 ;;
+        */dbt/models/*.sql) return 0 ;;
+        */dbt/models/*.yml) return 0 ;;
+        */alembic/versions/*.py) return 0 ;;
+    esac
+
+    # Check directory patterns
+    if echo "$file" | grep -qE "(migrations?|schemas?|models)/"; then
+        return 0
+    fi
+
+    return 1
+}
+
+# Exit if not a schema file
+if ! is_schema_file "$FILE_PATH"; then
+    exit 0
+fi
+
+# Read the file content (if it exists and is readable)
+if [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+FILE_CONTENT=$(cat "$FILE_PATH" 2>/dev/null || echo "")
+
+if [[ -z "$FILE_CONTENT" ]]; then
+    exit 0
+fi
+
+# Detect breaking changes
+BREAKING_CHANGES=()
+
+# Check for DROP COLUMN
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+COLUMN"; then
+    BREAKING_CHANGES+=("DROP COLUMN detected - may break existing queries")
+fi
+
+# Check for DROP TABLE
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+TABLE"; then
+    BREAKING_CHANGES+=("DROP TABLE detected - data loss risk")
+fi
+
+# Check for DROP INDEX
+if echo "$FILE_CONTENT" | grep -qiE "DROP[[:space:]]+INDEX"; then
+    BREAKING_CHANGES+=("DROP INDEX detected - may impact query performance")
+fi
+
+# Check for ALTER TYPE / MODIFY COLUMN type changes
+if echo "$FILE_CONTENT" | grep -qiE "ALTER[[:space:]]+.*(TYPE|COLUMN.*TYPE)"; then
+    BREAKING_CHANGES+=("Column type change detected - may cause data truncation")
+fi
+
+if echo "$FILE_CONTENT" | grep -qiE "MODIFY[[:space:]]+COLUMN"; then
+    BREAKING_CHANGES+=("MODIFY COLUMN detected - verify data compatibility")
+fi
+
+# Check for adding NOT NULL to existing column
+if echo "$FILE_CONTENT" | grep -qiE "ALTER[[:space:]]+.*SET[[:space:]]+NOT[[:space:]]+NULL"; then
+    BREAKING_CHANGES+=("Adding NOT NULL constraint - existing NULL values will fail")
+fi
+
+if echo "$FILE_CONTENT" | grep -qiE "ADD[[:space:]]+.*NOT[[:space:]]+NULL[^[:space:]]*[[:space:]]+DEFAULT"; then
+    # Adding NOT NULL with DEFAULT is usually safe - don't warn
+    :
+elif echo "$FILE_CONTENT" | grep -qiE "ADD[[:space:]]+.*NOT[[:space:]]+NULL"; then
+    BREAKING_CHANGES+=("Adding NOT NULL column without DEFAULT - INSERT may fail")
+fi
+
+# Check for RENAME TABLE/COLUMN
+if echo "$FILE_CONTENT" | grep -qiE "RENAME[[:space:]]+(TABLE|COLUMN|TO)"; then
+    BREAKING_CHANGES+=("RENAME detected - update all references")
+fi
+
+# Check for removing from Django/SQLAlchemy models (Python files)
+if [[ "$FILE_PATH" == *.py ]]; then
+    if echo "$FILE_CONTENT" | grep -qE "^-[[:space:]]*[a-z_]+[[:space:]]*=.*Field\("; then
+        BREAKING_CHANGES+=("Model field removal detected in Python ORM")
+    fi
+fi
+
+# Check for Prisma schema changes
+if [[ "$FILE_PATH" == *schema.prisma ]]; then
+    if echo "$FILE_CONTENT" | grep -qE "@relation.*onDelete.*Cascade"; then
+        BREAKING_CHANGES+=("Cascade delete detected - verify data safety")
+    fi
+fi
+
+# Output warnings if any breaking changes detected
+if [[ ${#BREAKING_CHANGES[@]} -gt 0 ]]; then
+    echo ""
+    echo "$PREFIX WARNING: Potential breaking schema changes in $(basename "$FILE_PATH")"
+    echo "$PREFIX ============================================"
+    for change in "${BREAKING_CHANGES[@]}"; do
+        echo "$PREFIX   - $change"
+    done
+    echo "$PREFIX ============================================"
+    echo "$PREFIX Review before deploying to production"
+    echo ""
+fi
+
+# Always exit 0 - non-blocking
+exit 0

plugins/git-flow/hooks/branch-check.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# git-flow branch name validation hook
+# Validates branch names follow the convention: <type>/<description>
+# Command hook - guaranteed predictable behavior
+
+# Read tool input from stdin (JSON format)
+INPUT=$(cat)
+
+# Extract command from JSON input
+# The Bash tool sends {"command": "..."} format
+COMMAND=$(echo "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# If no command found, exit silently (allow)
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Check if this is a branch creation command
+# Patterns: git checkout -b, git branch (without -d/-D), git switch -c/-C
+IS_BRANCH_CREATE=false
+BRANCH_NAME=""
+
+# git checkout -b <branch>
+if echo "$COMMAND" | grep -qE 'git\s+checkout\s+(-b|--branch)\s+'; then
+    IS_BRANCH_CREATE=true
+    BRANCH_NAME=$(echo "$COMMAND" | sed -n 's/.*git\s\+checkout\s\+\(-b\|--branch\)\s\+\([^ ]*\).*/\2/p')
+fi
+
+# git switch -c/-C <branch>
+if echo "$COMMAND" | grep -qE 'git\s+switch\s+(-c|-C|--create|--force-create)\s+'; then
+    IS_BRANCH_CREATE=true
+    BRANCH_NAME=$(echo "$COMMAND" | sed -n 's/.*git\s\+switch\s\+\(-c\|-C\|--create\|--force-create\)\s\+\([^ ]*\).*/\2/p')
+fi
+
+# git branch <name> (without -d/-D/-m/-M which are delete/rename)
+if echo "$COMMAND" | grep -qE 'git\s+branch\s+[^-]' && ! echo "$COMMAND" | grep -qE 'git\s+branch\s+(-d|-D|-m|-M|--delete|--move|--list|--show-current)'; then
+    IS_BRANCH_CREATE=true
+    BRANCH_NAME=$(echo "$COMMAND" | sed -n 's/.*git\s\+branch\s\+\([^ -][^ ]*\).*/\1/p')
+fi
+
+# If not a branch creation command, exit silently (allow)
+if [ "$IS_BRANCH_CREATE" = false ]; then
+    exit 0
+fi
+
+# If we couldn't extract the branch name, exit silently (allow)
+if [ -z "$BRANCH_NAME" ]; then
+    exit 0
+fi
+
+# Remove any quotes from branch name
+BRANCH_NAME=$(echo "$BRANCH_NAME" | tr -d '"' | tr -d "'")
+
+# Skip validation for special branches
+case "$BRANCH_NAME" in
+    main|master|develop|development|staging|release|hotfix)
+        exit 0
+        ;;
+esac
+
+# Allowed branch types
+VALID_TYPES="feat|fix|chore|docs|refactor|test|perf|debug"
+
+# Validate branch name format: <type>/<description>
+# Description: lowercase letters, numbers, hyphens only, max 50 chars total
+if ! echo "$BRANCH_NAME" | grep -qE "^($VALID_TYPES)/[a-z0-9][a-z0-9-]*$"; then
+    echo ""
+    echo "[git-flow] Branch name validation failed"
+    echo ""
+    echo "Branch: $BRANCH_NAME"
+    echo ""
+    echo "Expected format: <type>/<description>"
+    echo ""
+    echo "Valid types: feat, fix, chore, docs, refactor, test, perf, debug"
+    echo ""
+    echo "Description rules:"
+    echo "  - Lowercase letters, numbers, and hyphens only"
+    echo "  - Must start with letter or number"
+    echo "  - No spaces or special characters"
+    echo ""
+    echo "Examples:"
+    echo "  feat/add-user-auth"
+    echo "  fix/login-timeout"
+    echo "  chore/update-deps"
+    echo "  docs/api-reference"
+    echo ""
+    exit 1
+fi
+
+# Check total length (max 50 chars)
+if [ ${#BRANCH_NAME} -gt 50 ]; then
+    echo ""
+    echo "[git-flow] Branch name too long"
+    echo ""
+    echo "Branch: $BRANCH_NAME (${#BRANCH_NAME} chars)"
+    echo "Maximum: 50 characters"
+    echo ""
+    exit 1
+fi
+
+# Valid branch name
+exit 0

plugins/git-flow/hooks/commit-msg-check.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# git-flow commit message validation hook
+# Validates git commit messages follow conventional commit format
+# PreToolUse hook for Bash commands - type: command
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Use Python to properly parse JSON and extract the command
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('command',''))" 2>/dev/null)
+
+# If no command or python failed, allow through
+if [ -z "$COMMAND" ]; then
+    exit 0
+fi
+
+# Check if it is a git commit command with -m flag
+if ! echo "$COMMAND" | grep -qE 'git\s+commit.*-m'; then
+    # Not a git commit with -m, allow through
+    exit 0
+fi
+
+# Extract commit message - handle various quoting styles
+# Try double quotes first
+COMMIT_MSG=$(echo "$COMMAND" | sed -n 's/.*-m[[:space:]]*"\([^"]*\)".*/\1/p')
+# If empty, try single quotes
+if [ -z "$COMMIT_MSG" ]; then
+    COMMIT_MSG=$(echo "$COMMAND" | sed -n "s/.*-m[[:space:]]*'\\([^']*\\)'.*/\\1/p")
+fi
+# If still empty, try HEREDOC pattern
+if [ -z "$COMMIT_MSG" ]; then
+    if echo "$COMMAND" | grep -qE -- '-m[[:space:]]+"\$\(cat <<'; then
+        # HEREDOC pattern - too complex to parse, allow through
+        exit 0
+    fi
+fi
+
+# If no message extracted, allow through
+if [ -z "$COMMIT_MSG" ]; then
+    exit 0
+fi
+
+# Validate conventional commit format
+# Format: <type>(<scope>): <description>
+# or: <type>: <description>
+# Valid types: feat, fix, docs, style, refactor, perf, test, chore, build, ci
+
+VALID_TYPES="feat|fix|docs|style|refactor|perf|test|chore|build|ci"
+
+# Check if message matches conventional commit format
+if echo "$COMMIT_MSG" | grep -qE "^($VALID_TYPES)(\([a-zA-Z0-9_-]+\))?:[[:space:]]+.+"; then
+    # Valid format
+    exit 0
+fi
+
+# Invalid format - output warning
+echo "[git-flow] WARNING: Commit message does not follow conventional commit format"
+echo ""
+echo "Expected format: <type>(<scope>): <description>"
+echo "  or: <type>: <description>"
+echo ""
+echo "Valid types: feat, fix, docs, style, refactor, perf, test, chore, build, ci"
+echo ""
+echo "Examples:"
+echo "  feat(auth): add password reset functionality"
+echo "  fix: resolve login timeout issue"
+echo "  docs(readme): update installation instructions"
+echo ""
+echo "Your message: $COMMIT_MSG"
+echo ""
+echo "To proceed anyway, use /commit command which auto-generates valid messages."
+
+# Exit with non-zero to block
+exit 1

plugins/git-flow/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/pr-review/.mcp.json

@@ -1,12 +1,8 @@
 {
   "mcpServers": {
     "gitea": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python",
-      "args": ["-m", "mcp_server.server"],
-      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea",
-      "env": {
-        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea"
-      }
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/run.sh",
+      "args": []
     }
   }
 }

plugins/projman/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "projman",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Sprint planning and project management with Gitea integration",
   "author": {
     "name": "Leo Miranda",

plugins/projman/.mcp.json

@@ -1,12 +1,8 @@
 {
   "mcpServers": {
     "gitea": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python",
-      "args": ["-m", "mcp_server.server"],
-      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea",
-      "env": {
-        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea"
-      }
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/run.sh",
+      "args": []
     }
   }
 }

plugins/projman/README.md

@@ -278,6 +278,17 @@ Investigate diagnostic issues and propose fixes with human approval.
 
 **When to use:** In the marketplace repo, to investigate and fix issues reported by `/debug-report`.
 
+### `/suggest-version`
+Analyze CHANGELOG and recommend semantic version bump.
+
+**What it does:**
+- Reads CHANGELOG.md `[Unreleased]` section
+- Analyzes changes to determine bump type (major/minor/patch)
+- Applies SemVer rules: breaking changes → major, features → minor, fixes → patch
+- Returns recommended version with rationale
+
+**When to use:** Before creating a release to determine the appropriate version number.
+
 ## Code Quality Commands
 
 The `/review` and `/test-check` commands complement the Executor agent by catching issues before work is marked complete. Run both commands before `/sprint-close` for a complete quality check.

plugins/projman/agents/executor.md

@@ -108,7 +108,127 @@ git branch --show-current
 
 ## Your Responsibilities
 
-### 1. Implement Features Following Specs
+### 1. Status Reporting (Structured Progress)
+
+**CRITICAL: Post structured progress comments for visibility.**
+
+**Standard Progress Comment Format:**
+```markdown
+## Progress Update
+**Status:** In Progress | Blocked | Failed
+**Phase:** [current phase name]
+**Tool Calls:** X (budget: Y)
+
+### Completed
+- [x] Step 1
+- [x] Step 2
+
+### In Progress
+- [ ] Current step (estimated: Z more calls)
+
+### Blockers
+- None | [blocker description]
+
+### Next
+- What happens after current step
+```
+
+**When to Post Progress Comments:**
+- **Immediately on starting** - Post initial status
+- **Every 20-30 tool calls** - Show progress
+- **On phase transitions** - Moving from implementation to testing
+- **When blocked or encountering errors**
+- **Before budget limit** - If approaching turn limit
+
+**Starting Work Example:**
+```
+add_comment(
+    issue_number=45,
+    body="""## Progress Update
+**Status:** In Progress
+**Phase:** Starting
+**Tool Calls:** 5 (budget: 100)
+
+### Completed
+- [x] Read issue and acceptance criteria
+- [x] Created feature branch feat/45-jwt-service
+
+### In Progress
+- [ ] Implementing JWT service
+
+### Blockers
+- None
+
+### Next
+- Create auth/jwt_service.py
+- Implement core token functions
+"""
+)
+```
+
+**Blocked Example:**
+```
+add_comment(
+    issue_number=45,
+    body="""## Progress Update
+**Status:** Blocked
+**Phase:** Testing
+**Tool Calls:** 67 (budget: 100)
+
+### Completed
+- [x] Implemented jwt_service.py
+- [x] Wrote unit tests
+
+### In Progress
+- [ ] Running tests - BLOCKED
+
+### Blockers
+- Missing PyJWT dependency in requirements.txt
+- Need orchestrator to add dependency
+
+### Next
+- Resume after blocker resolved
+"""
+)
+```
+
+**Failed Example:**
+```
+add_comment(
+    issue_number=45,
+    body="""## Progress Update
+**Status:** Failed
+**Phase:** Implementation
+**Tool Calls:** 89 (budget: 100)
+
+### Completed
+- [x] Created jwt_service.py
+- [x] Implemented generate_token()
+
+### In Progress
+- [ ] verify_token() - FAILED
+
+### Blockers
+- Critical: Cannot decode tokens - algorithm mismatch
+- Attempted: HS256, HS384, RS256
+- Error: InvalidSignatureError consistently
+
+### Next
+- Needs human investigation
+- Possible issue with secret key encoding
+"""
+)
+```
+
+**NEVER report "completed" unless:**
+- All acceptance criteria are met
+- Tests pass
+- Code is committed and pushed
+- No unresolved errors
+
+**If you cannot complete, report failure honestly.** The orchestrator needs accurate status to coordinate effectively.
+
+### 2. Implement Features Following Specs
 
 **You receive:**
 - Issue number and description
@@ -122,7 +242,7 @@ git branch --show-current
 - Proper error handling
 - Edge case coverage
 
-### 2. Follow Best Practices
+### 3. Follow Best Practices
 
 **Code Quality Standards:**
 
@@ -150,7 +270,7 @@ git branch --show-current
 - Handle errors gracefully
 - Follow OWASP guidelines
 
-### 3. Handle Edge Cases
+### 4. Handle Edge Cases
 
 Always consider:
 - What if input is None/null/undefined?
@@ -160,7 +280,7 @@ Always consider:
 - What if user doesn't have permission?
 - What if resource doesn't exist?
 
-### 4. Apply Lessons Learned
+### 5. Apply Lessons Learned
 
 Reference relevant lessons in your implementation:
 
@@ -179,7 +299,7 @@ def test_verify_expired_token(jwt_service):
     ...
 ```
 
-### 5. Create Merge Requests (When Branch Protected)
+### 6. Create Merge Requests (When Branch Protected)
 
 **MR Body Template - NO SUBTASKS:**
 
@@ -208,7 +328,7 @@ Closes #45
 
 The issue already tracks subtasks. MR body should be summary only.
 
-### 6. Auto-Close Issues via Commit Messages
+### 7. Auto-Close Issues via Commit Messages
 
 **Always include closing keywords in commits:**
 
@@ -229,7 +349,7 @@ Closes #45"
 
 This ensures issues auto-close when MR is merged.
 
-### 7. Generate Completion Reports
+### 8. Generate Completion Reports
 
 After implementation, provide a concise completion report:
 
@@ -304,18 +424,185 @@ As the executor, you interact with MCP tools for status updates:
 - Apply best practices
 - Deliver quality work
 
+## Checkpointing (Save Progress for Resume)
+
+**CRITICAL: Save checkpoints so work can be resumed if interrupted.**
+
+**Checkpoint Comment Format:**
+```markdown
+## Checkpoint
+**Branch:** feat/45-jwt-service
+**Commit:** abc123 (or "uncommitted")
+**Phase:** [current phase]
+**Tool Calls:** 45
+
+### Files Modified
+- auth/jwt_service.py (created)
+- tests/test_jwt.py (created)
+
+### Completed Steps
+- [x] Created jwt_service.py skeleton
+- [x] Implemented generate_token()
+- [x] Implemented verify_token()
+
+### Pending Steps
+- [ ] Write unit tests
+- [ ] Add token refresh logic
+- [ ] Commit and push
+
+### State Notes
+[Any important context for resumption]
+```
+
+**When to Save Checkpoints:**
+- After completing each major step (every 20-30 tool calls)
+- Before stopping due to budget limit
+- When encountering a blocker
+- After any commit
+
+**Checkpoint Example:**
+```
+add_comment(
+    issue_number=45,
+    body="""## Checkpoint
+**Branch:** feat/45-jwt-service
+**Commit:** uncommitted (changes staged)
+**Phase:** Testing
+**Tool Calls:** 67
+
+### Files Modified
+- auth/jwt_service.py (created, 120 lines)
+- auth/__init__.py (modified, added import)
+- tests/test_jwt.py (created, 50 lines, incomplete)
+
+### Completed Steps
+- [x] Created auth/jwt_service.py
+- [x] Implemented generate_token() with HS256
+- [x] Implemented verify_token()
+- [x] Updated auth/__init__.py exports
+
+### Pending Steps
+- [ ] Complete test_jwt.py (5 tests remaining)
+- [ ] Add token refresh logic
+- [ ] Commit changes
+- [ ] Push to remote
+
+### State Notes
+- Using PyJWT 2.8.0
+- Secret key from JWT_SECRET env var
+- Tests use pytest fixtures in conftest.py
+"""
+)
+```
+
+**Checkpoint on Interruption:**
+
+If you must stop (budget, failure, blocker), ALWAYS post a checkpoint FIRST.
+
+## Runaway Detection (Self-Monitoring)
+
+**CRITICAL: Monitor yourself to prevent infinite loops and wasted resources.**
+
+**Self-Monitoring Checkpoints:**
+
+| Trigger | Action |
+|---------|--------|
+| 10+ tool calls without progress | STOP - Post progress update, reassess approach |
+| Same error 3+ times | CIRCUIT BREAKER - Stop, report failure with error pattern |
+| 50+ tool calls total | POST progress update (mandatory) |
+| 80+ tool calls total | WARN - Approaching budget, evaluate if completion is realistic |
+| 100+ tool calls total | STOP - Save state, report incomplete with checkpoint |
+
+**What Counts as "Progress":**
+- File created or modified
+- Test passing that wasn't before
+- New functionality working
+- Moving to next phase of work
+
+**What Does NOT Count as Progress:**
+- Reading more files
+- Searching for something
+- Retrying the same operation
+- Adding logging/debugging
+
+**Circuit Breaker Protocol:**
+
+If you encounter the same error 3+ times:
+```
+add_comment(
+    issue_number=45,
+    body="""## Progress Update
+**Status:** Failed (Circuit Breaker)
+**Phase:** [phase when stopped]
+**Tool Calls:** 67 (budget: 100)
+
+### Circuit Breaker Triggered
+Same error occurred 3+ times:
+```
+[error message]
+```
+
+### What Was Tried
+1. [first attempt]
+2. [second attempt]
+3. [third attempt]
+
+### Recommendation
+[What human should investigate]
+
+### Files Modified
+- [list any files changed before failure]
+"""
+)
+```
+
+**Budget Approaching Protocol:**
+
+At 80+ tool calls, post an update:
+```
+add_comment(
+    issue_number=45,
+    body="""## Progress Update
+**Status:** In Progress (Budget Warning)
+**Phase:** [current phase]
+**Tool Calls:** 82 (budget: 100)
+
+### Completed
+- [x] [completed steps]
+
+### Remaining
+- [ ] [what's left]
+
+### Assessment
+[Realistic? Should I continue or stop and checkpoint?]
+"""
+)
+```
+
+**Hard Stop at 100 Calls:**
+
+If you reach 100 tool calls:
+1. STOP immediately
+2. Save current state
+3. Post checkpoint comment
+4. Report as incomplete (not failed)
+
 ## Critical Reminders
 
 1. **Never use CLI tools** - Use MCP tools exclusively for Gitea
-2. **Branch naming** - Always use `feat/`, `fix/`, or `debug/` prefix with issue number
-3. **Branch check FIRST** - Never implement on staging/production
-4. **Follow specs precisely** - Respect architectural decisions
-5. **Apply lessons learned** - Reference in code and tests
-6. **Write tests** - Cover edge cases, not just happy path
-7. **Clean code** - Readable, maintainable, documented
-8. **No MR subtasks** - MR body should NOT have checklists
-9. **Use closing keywords** - `Closes #XX` in commit messages
-10. **Report thoroughly** - Complete summary when done
+2. **Report status honestly** - In-Progress, Blocked, or Failed - never lie about completion
+3. **Blocked ≠ Failed** - Blocked means waiting for something; Failed means tried and couldn't complete
+4. **Self-monitor** - Watch for runaway patterns, trigger circuit breaker when stuck
+5. **Branch naming** - Always use `feat/`, `fix/`, or `debug/` prefix with issue number
+6. **Branch check FIRST** - Never implement on staging/production
+7. **Follow specs precisely** - Respect architectural decisions
+8. **Apply lessons learned** - Reference in code and tests
+9. **Write tests** - Cover edge cases, not just happy path
+10. **Clean code** - Readable, maintainable, documented
+11. **No MR subtasks** - MR body should NOT have checklists
+12. **Use closing keywords** - `Closes #XX` in commit messages
+13. **Report thoroughly** - Complete summary when done, including honest status
+14. **Hard stop at 100 calls** - Save checkpoint and report incomplete
 
 ## Your Mission
 

plugins/projman/agents/orchestrator.md

@@ -57,9 +57,42 @@ curl -X POST "https://gitea.../api/..."
 - Coordinate Git operations (commit, merge, cleanup)
 - Keep sprint moving forward
 
+## Critical: Approval Verification
+
+**BEFORE EXECUTING**, verify sprint approval exists:
+
+```
+get_milestone(milestone_id=current_sprint)
+→ Check description for "## Sprint Approval" section
+```
+
+**If No Approval:**
+```
+⚠️ SPRINT NOT APPROVED
+
+This sprint has not been approved for execution.
+Please run /sprint-plan to approve the sprint first.
+```
+
+**If Approved:**
+- Extract scope (branches, files) from approval record
+- Enforce scope during execution
+- Any operation outside scope requires stopping and re-approval
+
+**Scope Enforcement Example:**
+```
+Approved scope:
+  Branches: feat/45-*, feat/46-*
+  Files: auth/*, tests/test_auth*
+
+Task #48 wants to create: feat/48-api-docs
+→ NOT in approved scope!
+→ STOP and ask user to approve expanded scope
+```
+
 ## Critical: Branch Detection
 
-**BEFORE DOING ANYTHING**, check the current git branch:
+**AFTER approval verification**, check the current git branch:
 
 ```bash
 git branch --show-current
@@ -93,7 +126,44 @@ git branch --show-current
 
 **Workflow:**
 
-**A. Fetch Sprint Issues**
+**A. Fetch Sprint Issues and Detect Checkpoints**
+```
+list_issues(state="open", labels=["sprint-current"])
+```
+
+**For each open issue, check for checkpoint comments:**
+```
+get_issue(issue_number=45)  # Comments included
+→ Look for comments containing "## Checkpoint"
+```
+
+**If Checkpoint Found:**
+```
+Checkpoint Detected for #45
+
+Found checkpoint from previous session:
+  Branch: feat/45-jwt-service
+  Phase: Testing
+  Tool Calls: 67
+  Files Modified: 3
+  Completed: 4/7 steps
+
+Options:
+1. Resume from checkpoint (recommended)
+2. Start fresh (discard previous work)
+3. Review checkpoint details first
+
+Would you like to resume?
+```
+
+**Resume Protocol:**
+1. Verify branch exists: `git branch -a | grep feat/45-jwt-service`
+2. Switch to branch: `git checkout feat/45-jwt-service`
+3. Verify files match checkpoint
+4. Dispatch executor with checkpoint context
+5. Executor continues from pending steps
+
+**B. Fetch Sprint Issues (Standard)**
 ```
 list_issues(state="open", labels=["sprint-current"])
 ```
@@ -147,11 +217,56 @@ Relevant Lessons:
 Ready to start? I can dispatch multiple tasks in parallel.
 ```
 
-### 2. Parallel Task Dispatch
+### 2. File Conflict Prevention (Pre-Dispatch)
 
-**When starting execution:**
+**BEFORE dispatching parallel agents, analyze file overlap.**
 
-For independent tasks (same batch), spawn multiple Executor agents in parallel:
+**Conflict Detection Workflow:**
+
+1. **Read each issue's checklist/body** to identify target files
+2. **Build file map** for all tasks in the batch
+3. **Check for overlap** - Same file in multiple tasks?
+4. **Sequentialize conflicts** - Don't parallelize if same file
+
+**Example Analysis:**
+```
+Analyzing Batch 1 for conflicts:
+
+#45 - Implement JWT service
+  → auth/jwt_service.py, auth/__init__.py, tests/test_jwt.py
+
+#48 - Update API documentation
+  → docs/api.md, README.md
+
+Overlap check: NONE
+Decision: Safe to parallelize ✅
+```
+
+**If Conflict Detected:**
+```
+Analyzing Batch 2 for conflicts:
+
+#46 - Build login endpoint
+  → api/routes/auth.py, auth/__init__.py
+
+#49 - Add auth tests
+  → tests/test_auth.py, auth/__init__.py
+
+Overlap: auth/__init__.py ⚠️
+Decision: Sequentialize - run #46 first, then #49
+```
+
+**Conflict Resolution:**
+- Same file → MUST sequentialize
+- Same directory → Usually safe, review file names
+- Shared config → Sequentialize
+- Shared test fixture → Assign different fixture files or sequentialize
+
+### 3. Parallel Task Dispatch
+
+**After conflict check passes, dispatch parallel agents:**
+
+For independent tasks (same batch) WITH NO FILE CONFLICTS, spawn multiple Executor agents in parallel:
 
 ```
 Dispatching Batch 1 (2 tasks in parallel):
@@ -167,6 +282,14 @@ Task 2: #48 - Update API documentation
 Both tasks running in parallel. I'll monitor progress.
 ```
 
+**Branch Isolation:** Each task MUST have its own branch. Never have two agents work on the same branch.
+
+**Sequential Merge Protocol:**
+1. Wait for task to complete
+2. Merge its branch to development
+3. Then merge next completed task
+4. Never merge simultaneously
+
 **Branch Naming Convention (MANDATORY):**
 - Features: `feat/<issue-number>-<short-description>`
 - Bug fixes: `fix/<issue-number>-<short-description>`
@@ -177,7 +300,7 @@ Both tasks running in parallel. I'll monitor progress.
 - `fix/46-login-timeout`
 - `debug/47-investigate-memory-leak`
 
-### 3. Generate Lean Execution Prompts
+### 4. Generate Lean Execution Prompts
 
 **NOT THIS (too verbose):**
 ```
@@ -222,11 +345,127 @@ Dependencies: None (can start immediately)
 Ready to start? Say "yes" and I'll monitor progress.
 ```
 
-### 4. Progress Tracking
+### 5. Status Label Management
 
-**Monitor and Update:**
+**CRITICAL: Use Status labels to communicate issue state accurately.**
 
-**Add Progress Comments:**
+**When dispatching a task:**
+```
+update_issue(
+    issue_number=45,
+    labels=["Status/In-Progress", ...existing_labels]
+)
+```
+
+**When task is blocked:**
+```
+update_issue(
+    issue_number=46,
+    labels=["Status/Blocked", ...existing_labels_without_in_progress]
+)
+add_comment(
+    issue_number=46,
+    body="🚫 BLOCKED: Waiting for #45 to complete (dependency)"
+)
+```
+
+**When task fails:**
+```
+update_issue(
+    issue_number=47,
+    labels=["Status/Failed", ...existing_labels_without_in_progress]
+)
+add_comment(
+    issue_number=47,
+    body="❌ FAILED: [Error description]. Needs investigation."
+)
+```
+
+**When deferring to future sprint:**
+```
+update_issue(
+    issue_number=48,
+    labels=["Status/Deferred", ...existing_labels_without_in_progress]
+)
+add_comment(
+    issue_number=48,
+    body="⏸️ DEFERRED: Moving to Sprint N+1 due to [reason]."
+)
+```
+
+**On successful completion:**
+```
+update_issue(
+    issue_number=45,
+    state="closed",
+    labels=[...existing_labels_without_status]  # Remove all Status/* labels
+)
+```
+
+**Status Label Rules:**
+- Only ONE Status label at a time (In-Progress, Blocked, Failed, or Deferred)
+- Remove Status labels when closing successfully
+- Always add comment explaining status changes
+
+### 6. Progress Tracking (Structured Comments)
+
+**CRITICAL: Use structured progress comments for visibility.**
+
+**Standard Progress Comment Format:**
+```markdown
+## Progress Update
+**Status:** In Progress | Blocked | Failed
+**Phase:** [current phase name]
+**Tool Calls:** X (budget: Y)
+
+### Completed
+- [x] Step 1
+- [x] Step 2
+
+### In Progress
+- [ ] Current step (estimated: Z more calls)
+
+### Blockers
+- None | [blocker description]
+
+### Next
+- What happens after current step
+```
+
+**Example Progress Comment:**
+```
+add_comment(
+    issue_number=45,
+    body="""## Progress Update
+**Status:** In Progress
+**Phase:** Implementation
+**Tool Calls:** 45 (budget: 100)
+
+### Completed
+- [x] Created auth/jwt_service.py
+- [x] Implemented generate_token()
+- [x] Implemented verify_token()
+
+### In Progress
+- [ ] Writing unit tests (estimated: 20 more calls)
+
+### Blockers
+- None
+
+### Next
+- Run tests and fix any failures
+- Commit and push
+"""
+)
+```
+
+**When to Post Progress Comments:**
+- After completing each major phase (every 20-30 tool calls)
+- When status changes (blocked, failed)
+- When encountering unexpected issues
+- Before approaching tool call budget limit
+
+**Simple progress updates (for minor milestones):**
 ```
 add_comment(
     issue_number=45,
@@ -264,7 +503,7 @@ add_comment(
 - Notify that new tasks are ready for execution
 - Update the execution queue
 
-### 5. Monitor Parallel Execution
+### 7. Monitor Parallel Execution
 
 **Track multiple running tasks:**
 ```
@@ -282,7 +521,7 @@ Batch 2 (now unblocked):
 Starting #46 while #48 continues...
 ```
 
-### 6. Branch Protection Detection
+### 8. Branch Protection Detection
 
 Before merging, check if development branch is protected:
 
@@ -312,7 +551,7 @@ Closes #45
 
 **NEVER include subtask checklists in MR body.** The issue already has them.
 
-### 7. Sprint Close - Capture Lessons Learned
+### 9. Sprint Close - Capture Lessons Learned
 
 **Invoked by:** `/sprint-close`
 
@@ -564,6 +803,64 @@ Would you like me to handle git operations?
 - Document blockers promptly
 - Never let tasks slip through
 
+## Runaway Detection (Monitoring Dispatched Agents)
+
+**Monitor dispatched agents for runaway behavior:**
+
+**Warning Signs:**
+- Agent running 30+ minutes with no progress comment
+- Progress comment shows "same phase" for 20+ tool calls
+- Error patterns repeating in progress comments
+
+**Intervention Protocol:**
+
+When you detect an agent may be stuck:
+
+1. **Read latest progress comment** - Check tool call count and phase
+2. **If no progress in 20+ calls** - Consider stopping the agent
+3. **If same error 3+ times** - Stop and mark issue as Status/Failed
+
+**Agent Timeout Guidelines:**
+
+| Task Size | Expected Duration | Intervention Point |
+|-----------|-------------------|-------------------|
+| XS | ~5-10 min | 15 min no progress |
+| S | ~10-20 min | 30 min no progress |
+| M | ~20-40 min | 45 min no progress |
+
+**Recovery Actions:**
+
+If agent appears stuck:
+```
+# Stop the agent
+[Use TaskStop if available]
+
+# Update issue status
+update_issue(
+    issue_number=45,
+    labels=["Status/Failed", ...other_labels]
+)
+
+# Add explanation comment
+add_comment(
+    issue_number=45,
+    body="""## Agent Intervention
+**Reason:** No progress detected for [X] minutes / [Y] tool calls
+**Last Status:** [from progress comment]
+**Action:** Stopped agent, requires human review
+
+### What Was Completed
+[from progress comment]
+
+### What Remains
+[from progress comment]
+
+### Recommendation
+[Manual completion / Different approach / Break down further]
+"""
+)
+```
+
 ## Critical Reminders
 
 1. **Never use CLI tools** - Use MCP tools exclusively for Gitea
@@ -572,14 +869,18 @@ Would you like me to handle git operations?
 4. **Parallel dispatch** - Run independent tasks simultaneously
 5. **Lean prompts** - Brief, actionable, not verbose documents
 6. **Branch naming** - `feat/`, `fix/`, `debug/` prefixes required
-7. **No MR subtasks** - MR body should NOT have checklists
-8. **Auto-check subtasks** - Mark issue subtasks complete on close
-9. **Track meticulously** - Update issues immediately, document blockers
-10. **Capture lessons** - At sprint close, interview thoroughly
-11. **Update wiki status** - At sprint close, update implementation and proposal pages
-12. **Link lessons to wiki** - Include lesson links in implementation completion summary
-13. **Update CHANGELOG** - MANDATORY at sprint close, never skip
-14. **Run suggest-version** - Check if release is needed after CHANGELOG update
+7. **Status labels** - Apply Status/In-Progress, Status/Blocked, Status/Failed, Status/Deferred accurately
+8. **One status at a time** - Remove old Status/* label before applying new one
+9. **Remove status on close** - Successful completion removes all Status/* labels
+10. **Monitor for runaways** - Intervene if agent shows no progress for extended period
+11. **No MR subtasks** - MR body should NOT have checklists
+12. **Auto-check subtasks** - Mark issue subtasks complete on close
+13. **Track meticulously** - Update issues immediately, document blockers
+14. **Capture lessons** - At sprint close, interview thoroughly
+15. **Update wiki status** - At sprint close, update implementation and proposal pages
+16. **Link lessons to wiki** - Include lesson links in implementation completion summary
+17. **Update CHANGELOG** - MANDATORY at sprint close, never skip
+18. **Run suggest-version** - Check if release is needed after CHANGELOG update
 
 ## Your Mission
 

plugins/projman/agents/planner.md

@@ -310,14 +310,55 @@ Think through the technical approach:
 - `[Sprint 17] fix: Resolve login timeout issue`
 - `[Sprint 18] refactor: Extract authentication module`
 
-**Task Granularity Guidelines:**
-| Size | Scope | Example |
-|------|-------|---------|
-| **Small** | 1-2 hours, single file/component | Add validation to one field |
-| **Medium** | Half day, multiple files, one feature | Implement new API endpoint |
-| **Large** | Should be broken down | Full authentication system |
+**Task Sizing Rules (MANDATORY):**
 
-**If a task is too large, break it down into smaller tasks.**
+| Effort | Files | Checklist Items | Max Tool Calls | Agent Scope |
+|--------|-------|-----------------|----------------|-------------|
+| **XS** | 1 file | 0-2 items | ~30 | Single function/fix |
+| **S** | 1 file | 2-4 items | ~50 | Single file feature |
+| **M** | 2-3 files | 4-6 items | ~80 | Multi-file feature |
+| **L** | MUST BREAK DOWN | - | - | Too large for one agent |
+| **XL** | MUST BREAK DOWN | - | - | Way too large |
+
+**CRITICAL: L and XL tasks MUST be broken into subtasks.**
+
+**Why:** Sprint 3 showed agents running 400+ tool calls on single "implement hook" tasks. This causes:
+- Long wait times (1+ hour per task)
+- No progress visibility
+- Resource exhaustion
+- Difficult debugging
+
+**Task Scoping Checklist:**
+1. Can this be completed in one file? → XS or S
+2. Does it touch 2-3 files? → M (max)
+3. Does it touch 4+ files? → MUST break down
+4. Does it require complex decision-making? → MUST break down
+5. Would you estimate 50+ tool calls? → MUST break down
+
+**Breaking Down Large Tasks:**
+
+**BAD (L/XL - too broad):**
+```
+[Sprint 3] feat: Implement git-flow branch validation hook
+Labels: Efforts/L, ...
+```
+
+**GOOD (broken into S/M tasks):**
+```
+[Sprint 3] feat: Create branch validation hook skeleton
+Labels: Efforts/S, ...
+
+[Sprint 3] feat: Add prefix pattern validation (feat/, fix/, etc.)
+Labels: Efforts/S, ...
+
+[Sprint 3] feat: Add issue number extraction and validation
+Labels: Efforts/S, ...
+
+[Sprint 3] test: Add branch validation unit tests
+Labels: Efforts/S, ...
+```
+
+**If a task is estimated L or XL, STOP and break it down before creating.**
 
 **IMPORTANT: Include wiki implementation reference in issue body:**
 
@@ -479,5 +520,9 @@ Sprint 17 - User Authentication (Due: 2025-02-01)
 11. **Always use suggest_labels** - Don't guess labels
 12. **Always think through architecture** - Consider edge cases
 13. **Always cleanup local files** - Delete after migrating to wiki
+14. **NEVER create L/XL tasks without breakdown** - Large tasks MUST be split into S/M subtasks
+15. **Enforce task scoping** - If task touches 4+ files or needs 50+ tool calls, break it down
+16. **ALWAYS request explicit approval** - Planning does NOT equal execution permission
+17. **Record approval in milestone** - Sprint-start verifies approval before executing
 
 You are the thoughtful planner who ensures sprints are well-prepared, architecturally sound, and learn from past experiences. Take your time, ask questions, and create comprehensive plans that set the team up for success.

plugins/projman/commands/sprint-plan.md

@@ -136,6 +136,58 @@ The planner agent will:
     - Document dependency graph
     - Provide sprint overview with wiki links
 
+11. **Request Sprint Approval**
+    - Present approval request with scope summary
+    - Capture explicit user approval
+    - Record approval in milestone description
+    - Approval scopes what sprint-start can execute
+
+## Sprint Approval (MANDATORY)
+
+**Planning DOES NOT equal execution permission.**
+
+After creating issues, the planner MUST request explicit approval:
+
+```
+Sprint 17 Planning Complete
+===========================
+
+Created Issues:
+- #45: [Sprint 17] feat: JWT token generation
+- #46: [Sprint 17] feat: Login endpoint
+- #47: [Sprint 17] test: Auth tests
+
+Execution Scope:
+- Branches: feat/45-*, feat/46-*, feat/47-*
+- Files: auth/*, api/routes/auth.py, tests/test_auth*
+- Dependencies: PyJWT, python-jose
+
+⚠️ APPROVAL REQUIRED
+
+Do you approve this sprint for execution?
+This grants permission for agents to:
+- Create and modify files in the listed scope
+- Create branches with the listed prefixes
+- Install listed dependencies
+
+Type "approve sprint 17" to authorize execution.
+```
+
+**On Approval:**
+1. Record approval in milestone description
+2. Note timestamp and scope
+3. Sprint-start will verify approval exists
+
+**Approval Record Format:**
+```markdown
+## Sprint Approval
+**Approved:** 2026-01-28 14:30
+**Approver:** User
+**Scope:**
+- Branches: feat/45-*, feat/46-*, feat/47-*
+- Files: auth/*, api/routes/auth.py, tests/test_auth*
+```
+
 ## Issue Title Format (MANDATORY)
 
 ```
@@ -155,15 +207,70 @@ The planner agent will:
 - `[Sprint 17] fix: Resolve login timeout issue`
 - `[Sprint 18] refactor: Extract authentication module`
 
-## Task Granularity Guidelines
+## Task Sizing Rules (MANDATORY)
 
-| Size | Scope | Example |
-|------|-------|---------|
-| **Small** | 1-2 hours, single file/component | Add validation to one field |
-| **Medium** | Half day, multiple files, one feature | Implement new API endpoint |
-| **Large** | Should be broken down | Full authentication system |
+**CRITICAL: Tasks sized L or XL MUST be broken down into smaller tasks.**
 
-**If a task is too large, break it down into smaller tasks.**
+| Effort | Files | Checklist Items | Max Tool Calls | Agent Scope |
+|--------|-------|-----------------|----------------|-------------|
+| **XS** | 1 file | 0-2 items | ~30 | Single function/fix |
+| **S** | 1 file | 2-4 items | ~50 | Single file feature |
+| **M** | 2-3 files | 4-6 items | ~80 | Multi-file feature |
+| **L** | MUST BREAK DOWN | - | - | Too large for one agent |
+| **XL** | MUST BREAK DOWN | - | - | Way too large |
+
+**Why This Matters:**
+- Agents running 400+ tool calls take 1+ hour, with no visibility
+- Large tasks lack clear completion criteria
+- Debugging failures is extremely difficult
+- Small tasks enable parallel execution
+
+**Scoping Checklist:**
+1. Can this be completed in one file? → XS or S
+2. Does it touch 2-3 files? → M (maximum for single task)
+3. Does it touch 4+ files? → MUST break down
+4. Would you estimate 50+ tool calls? → MUST break down
+5. Does it require complex decision-making mid-task? → MUST break down
+
+**Example Breakdown:**
+
+**BAD (L - too broad):**
+```
+[Sprint 3] feat: Implement schema diff detection hook
+Labels: Efforts/L
+- Hook skeleton
+- Pattern detection for DROP/ALTER/RENAME
+- Warning output formatting
+- Integration with hooks.json
+```
+
+**GOOD (broken into S tasks):**
+```
+[Sprint 3] feat: Create schema-diff-check.sh hook skeleton
+Labels: Efforts/S
+- [ ] Create hook file with standard header
+- [ ] Add file type detection for SQL/migrations
+- [ ] Exit 0 (non-blocking)
+
+[Sprint 3] feat: Add DROP/ALTER pattern detection
+Labels: Efforts/S
+- [ ] Detect DROP COLUMN/TABLE/INDEX
+- [ ] Detect ALTER TYPE changes
+- [ ] Detect RENAME operations
+
+[Sprint 3] feat: Add warning output formatting
+Labels: Efforts/S
+- [ ] Format breaking change warnings
+- [ ] Add hook prefix to output
+- [ ] Test output visibility
+
+[Sprint 3] chore: Register hook in hooks.json
+Labels: Efforts/XS
+- [ ] Add PostToolUse:Edit hook entry
+- [ ] Test hook triggers on SQL edits
+```
+
+**The planner MUST refuse to create L/XL tasks without breakdown.**
 
 ## MCP Tools Available
 

plugins/projman/commands/sprint-start.md

@@ -6,6 +6,47 @@ description: Begin sprint execution with relevant lessons learned from previous
 
 You are initiating sprint execution. The orchestrator agent will coordinate the work, analyze dependencies for parallel execution, search for relevant lessons learned, and guide you through the implementation process.
 
+## Sprint Approval Verification
+
+**CRITICAL: Sprint must be approved before execution.**
+
+The orchestrator checks for approval in the milestone description:
+
+```
+get_milestone(milestone_id=17)
+→ Check description for "## Sprint Approval" section
+```
+
+**If Approval Missing:**
+```
+⚠️ SPRINT NOT APPROVED
+
+Sprint 17 has not been approved for execution.
+The milestone description does not contain an approval record.
+
+Please run /sprint-plan to:
+1. Review the sprint scope
+2. Approve the execution plan
+
+Then run /sprint-start again.
+```
+
+**If Approval Found:**
+```
+✓ Sprint Approval Verified
+  Approved: 2026-01-28 14:30
+  Scope:
+    Branches: feat/45-*, feat/46-*, feat/47-*
+    Files: auth/*, api/routes/auth.py, tests/test_auth*
+
+Proceeding with execution within approved scope...
+```
+
+**Scope Enforcement:**
+- Agents can ONLY create branches matching approved patterns
+- Agents can ONLY modify files within approved paths
+- Operations outside scope require re-approval via `/sprint-plan`
+
 ## Branch Detection
 
 **CRITICAL:** Before proceeding, check the current git branch:
@@ -25,7 +66,18 @@ If you are on a production or staging branch, you MUST stop and ask the user to
 
 The orchestrator agent will:
 
-1. **Fetch Sprint Issues**
+1. **Verify Sprint Approval**
+   - Check milestone description for `## Sprint Approval` section
+   - If no approval found, STOP and direct user to `/sprint-plan`
+   - If approval found, extract scope (branches, files)
+   - Agents operate ONLY within approved scope
+
+2. **Detect Checkpoints (Resume Support)**
+   - Check each open issue for `## Checkpoint` comments
+   - If checkpoint found, offer to resume from that point
+   - Resume preserves: branch, completed work, pending steps
+
+3. **Fetch Sprint Issues**
    - Use `list_issues` to fetch open issues for the sprint
    - Identify priorities based on labels (Priority/Critical, Priority/High, etc.)
 
@@ -72,6 +124,67 @@ Parallel Execution Batches:
 
 **Independent tasks in the same batch run in parallel.**
 
+## File Conflict Prevention (MANDATORY)
+
+**CRITICAL: Before dispatching parallel agents, check for file overlap.**
+
+**Pre-Dispatch Conflict Check:**
+
+1. **Identify target files** for each task in the batch
+2. **Check for overlap** - Do any tasks modify the same file?
+3. **If overlap detected** - Sequentialize those specific tasks
+
+**Example Conflict Detection:**
+```
+Batch 1 Analysis:
+  #45 - Implement JWT service
+        Files: auth/jwt_service.py, auth/__init__.py, tests/test_jwt.py
+
+  #48 - Update API documentation
+        Files: docs/api.md, README.md
+
+  Overlap: NONE → Safe to parallelize
+
+Batch 2 Analysis:
+  #46 - Build login endpoint
+        Files: api/routes/auth.py, auth/__init__.py
+
+  #49 - Add auth tests
+        Files: tests/test_auth.py, auth/__init__.py
+
+  Overlap: auth/__init__.py → CONFLICT!
+  Action: Sequentialize #46 and #49 (run #46 first)
+```
+
+**Conflict Resolution Rules:**
+
+| Conflict Type | Action |
+|---------------|--------|
+| Same file in checklist | Sequentialize tasks |
+| Same directory | Review if safe, usually OK |
+| Shared test file | Sequentialize or assign different test files |
+| Shared config | Sequentialize |
+
+**Branch Isolation Protocol:**
+
+Even for parallel tasks, each MUST run on its own branch:
+```
+Task #45 → feat/45-jwt-service (isolated)
+Task #48 → feat/48-api-docs (isolated)
+```
+
+**Sequential Merge After Completion:**
+```
+1. Task #45 completes → merge feat/45-jwt-service to development
+2. Task #48 completes → merge feat/48-api-docs to development
+3. Never merge simultaneously - always sequential to detect conflicts
+```
+
+**If Merge Conflict Occurs:**
+1. Stop second task
+2. Resolve conflict manually or assign to human
+3. Resume/restart second task with updated base
+
 ## Branch Naming Convention (MANDATORY)
 
 When creating branches for tasks:
@@ -239,6 +352,61 @@ Batch 2 (now unblocked):
 Starting #46 while #48 continues...
 ```
 
+## Checkpoint Resume Support
+
+If a previous session was interrupted (agent stopped, failure, budget exhausted), checkpoints enable resumption.
+
+**Checkpoint Detection:**
+The orchestrator scans issue comments for `## Checkpoint` markers containing:
+- Branch name
+- Last commit hash
+- Completed/pending steps
+- Files modified
+
+**Resume Flow:**
+```
+User: /sprint-start
+
+Orchestrator: Checking for checkpoints...
+
+Found checkpoint for #45 (JWT service):
+  Branch: feat/45-jwt-service
+  Last activity: 2 hours ago
+  Progress: 4/7 steps completed
+  Pending: Write tests, add refresh, commit
+
+Options:
+  1. Resume from checkpoint (recommended)
+  2. Start fresh (lose previous work)
+  3. Review checkpoint details
+
+User: 1
+
+Orchestrator: Resuming #45 from checkpoint...
+  ✓ Branch exists
+  ✓ Files match checkpoint
+  ✓ Dispatching executor with context
+
+Executor continues from pending steps...
+```
+
+**Checkpoint Format:**
+Executors save checkpoints after major steps:
+```markdown
+## Checkpoint
+**Branch:** feat/45-jwt-service
+**Commit:** abc123
+**Phase:** Testing
+
+### Completed Steps
+- [x] Step 1
+- [x] Step 2
+
+### Pending Steps
+- [ ] Step 3
+- [ ] Step 4
+```
+
 ## Getting Started
 
 Simply invoke `/sprint-start` and the orchestrator will:

plugins/projman/commands/sprint-status.md

@@ -79,7 +79,12 @@ Completed Issues (3):
 
 In Progress (2):
   #46: [Sprint 18] feat: Build login endpoint [Type/Feature, Priority/High]
+       Status: In Progress | Phase: Implementation | Tool Calls: 45/100
+       Progress: 3/5 steps | Current: Writing validation logic
+
   #49: [Sprint 18] test: Add auth tests [Type/Test, Priority/Medium]
+       Status: In Progress | Phase: Testing | Tool Calls: 30/100
+       Progress: 2/4 steps | Current: Testing edge cases
 
 Ready to Start (2):
   #50: [Sprint 18] feat: Integrate OAuth providers [Type/Feature, Priority/Low]
@@ -137,12 +142,53 @@ Show only backend issues:
 list_issues(labels=["Component/Backend"])
 ```
 
+## Progress Comment Parsing
+
+Agents post structured progress comments in this format:
+
+```markdown
+## Progress Update
+**Status:** In Progress | Blocked | Failed
+**Phase:** [current phase name]
+**Tool Calls:** X (budget: Y)
+
+### Completed
+- [x] Step 1
+
+### In Progress
+- [ ] Current step
+
+### Blockers
+- None | [blocker description]
+```
+
+**To extract real-time progress:**
+1. Fetch issue comments: `get_issue(number)` includes recent comments
+2. Look for comments containing `## Progress Update`
+3. Parse the **Status:** line for current state
+4. Parse **Tool Calls:** for budget consumption
+5. Extract blockers from `### Blockers` section
+
+**Progress Summary Display:**
+```
+In Progress Issues:
+  #45: [Sprint 18] feat: JWT service
+       Status: In Progress | Phase: Testing | Tool Calls: 67/100
+       Completed: 4/6 steps | Current: Writing unit tests
+
+  #46: [Sprint 18] feat: Login endpoint
+       Status: Blocked | Phase: Implementation | Tool Calls: 23/100
+       Blocker: Waiting for JWT service (#45)
+```
+
 ## Blocker Detection
 
 The command identifies blocked issues by:
-1. **Dependency Analysis** - Uses `list_issue_dependencies` to find unmet dependencies
-2. **Comment Keywords** - Checks for "blocked", "blocker", "waiting for"
-3. **Stale Issues** - Issues with no recent activity (>7 days)
+1. **Progress Comments** - Parse `### Blockers` section from structured comments
+2. **Status Labels** - Check for `Status/Blocked` label on issue
+3. **Dependency Analysis** - Uses `list_issue_dependencies` to find unmet dependencies
+4. **Comment Keywords** - Checks for "blocked", "blocker", "waiting for"
+5. **Stale Issues** - Issues with no recent activity (>7 days)
 
 ## When to Use
 

plugins/projman/hooks/startup-check.sh

@@ -5,14 +5,44 @@
 
 PREFIX="[projman]"
 
-# Check if MCP venv exists
+# Calculate paths
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(dirname "$(dirname "$(realpath "$0")")")}"
-VENV_PATH="$PLUGIN_ROOT/mcp-servers/gitea/.venv/bin/python"
+# Marketplace root is 2 levels up from plugin root (plugins/projman -> .)
+MARKETPLACE_ROOT="$(dirname "$(dirname "$PLUGIN_ROOT")")"
+VENV_REPAIR_SCRIPT="$MARKETPLACE_ROOT/scripts/venv-repair.sh"
+PLUGIN_CACHE="$HOME/.claude/plugins/cache/leo-claude-mktplace"
 
+# ============================================================================
+# Clear stale plugin cache (MUST run before MCP servers load)
+# ============================================================================
+# The cache at ~/.claude/plugins/cache/ holds versioned .mcp.json files.
+# After marketplace updates, cached configs may point to old paths.
+# Clearing forces Claude to read fresh configs from installed marketplace.
+
+if [[ -d "$PLUGIN_CACHE" ]]; then
+    rm -rf "$PLUGIN_CACHE"
+    # Don't output anything - this should be silent and automatic
+fi
+
+# ============================================================================
+# Auto-repair MCP venvs (runs before other checks)
+# ============================================================================
+
+if [[ -x "$VENV_REPAIR_SCRIPT" ]]; then
+    # Run venv repair - this creates symlinks to cached venvs
+    # Only outputs messages if something needed fixing
+    "$VENV_REPAIR_SCRIPT" 2>/dev/null || {
+        echo "$PREFIX MCP venv setup failed - run: cd $MARKETPLACE_ROOT && ./scripts/setup-venvs.sh"
+        exit 0
+    }
+else
+    # Fallback: just check if venv exists
+    VENV_PATH="$PLUGIN_ROOT/mcp-servers/gitea/.venv/bin/python"
     if [[ ! -f "$VENV_PATH" ]]; then
         echo "$PREFIX MCP venvs missing - run setup.sh from installed marketplace"
         exit 0
     fi
+fi
 
 # Check git remote vs .env config (only if .env exists)
 if [[ -f ".env" ]]; then

plugins/projman/skills/label-taxonomy/labels-reference.md

@@ -13,9 +13,9 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
 
 This skill provides the current label taxonomy used for issue classification in Gitea. Labels are **fetched dynamically** from Gitea and should never be hardcoded.
 
-**Current Taxonomy:** 43 labels (27 organization + 16 repository)
+**Current Taxonomy:** 47 labels (31 organization + 16 repository)
 
-## Organization Labels (27)
+## Organization Labels (31)
 
 Organization-level labels are shared across all repositories in your configured organization.
 
@@ -60,6 +60,12 @@ Organization-level labels are shared across all repositories in your configured
 - `Type/Test` (#1d76db) - Testing-related work (unit, integration, e2e)
 - `Type/Chore` (#fef2c0) - Maintenance, tooling, dependencies, build tasks
 
+### Status (4)
+- `Status/In-Progress` (#0052cc) - Work is actively being done on this issue
+- `Status/Blocked` (#ff5630) - Blocked by external dependency or issue
+- `Status/Failed` (#de350b) - Implementation attempted but failed, needs investigation
+- `Status/Deferred` (#6554c0) - Moved to a future sprint or backlog
+
 ## Repository Labels (16)
 
 Repository-level labels are specific to each project.
@@ -168,6 +174,28 @@ When suggesting labels for issues, consider the following patterns:
 - Keywords: "deploy", "deployment", "docker", "infrastructure", "ci/cd", "production"
 - Example: "Deploy authentication service to production"
 
+### Status Detection
+
+**Status/In-Progress:**
+- Applied when: Agent starts working on an issue
+- Remove when: Work completes, fails, or is blocked
+- Example: Orchestrator applies when dispatching task to executor
+
+**Status/Blocked:**
+- Applied when: Issue cannot proceed due to external dependency
+- Context: Waiting for another issue, external service, or decision
+- Example: "Blocked by #45 - need JWT service first"
+
+**Status/Failed:**
+- Applied when: Implementation was attempted but failed
+- Context: Errors, permission issues, technical blockers
+- Example: Agent hit permission errors and couldn't complete
+
+**Status/Deferred:**
+- Applied when: Work is moved to a future sprint
+- Context: Scope reduction, reprioritization
+- Example: "Moving to Sprint 5 due to scope constraints"
+
 ### Tech Detection
 
 **Tech/Python:**

plugins/viz-platform/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "viz-platform",
+  "version": "1.0.0",
+  "description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
+  "author": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/viz-platform/README.md",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+  "license": "MIT",
+  "keywords": [
+    "dash",
+    "plotly",
+    "mantine",
+    "charts",
+    "dashboards",
+    "theming",
+    "visualization",
+    "dmc"
+  ],
+  "commands": ["./commands/"],
+  "mcpServers": ["./.mcp.json"]
+}

plugins/viz-platform/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "viz-platform": {
+      "type": "stdio",
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/viz-platform/run.sh",
+      "args": []
+    }
+  }
+}

plugins/viz-platform/README.md

@@ -0,0 +1,196 @@
+# viz-platform Plugin
+
+Visualization tools with Dash Mantine Components validation, Plotly charts, and theming for Claude Code.
+
+## Features
+
+- **DMC Validation**: Prevent prop hallucination with version-locked component registry
+- **Chart Creation**: Plotly charts with automatic theme token application
+- **Layout Builder**: Dashboard layouts with filters, grids, and responsive design
+- **Theme System**: Create, extend, and export design tokens
+
+## Installation
+
+This plugin is part of the leo-claude-mktplace. Install via:
+
+```bash
+# From marketplace
+claude plugins install leo-claude-mktplace/viz-platform
+
+# Setup MCP server venv
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/viz-platform
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Configuration
+
+### System-Level (Optional)
+
+Create `~/.config/claude/viz-platform.env` for default theme preferences:
+
+```env
+VIZ_PLATFORM_COLOR_SCHEME=light
+VIZ_PLATFORM_PRIMARY_COLOR=blue
+```
+
+### Project-Level (Optional)
+
+Add to project `.env` for project-specific settings:
+
+```env
+VIZ_PLATFORM_THEME=my-custom-theme
+DMC_VERSION=0.14.7
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/initial-setup` | Interactive setup wizard for DMC and theme preferences |
+| `/component {name}` | Inspect component props and validation |
+| `/chart {type}` | Create a Plotly chart |
+| `/dashboard {template}` | Create a dashboard layout |
+| `/theme {name}` | Apply an existing theme |
+| `/theme-new {name}` | Create a new custom theme |
+| `/theme-css {name}` | Export theme as CSS |
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `theme-setup` | Design-focused theme creation specialist |
+| `layout-builder` | Dashboard layout and filter specialist |
+| `component-check` | Strict component validation specialist |
+
+## Tool Categories
+
+### DMC Validation (3 tools)
+Prevent invalid component props before runtime.
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List available components by category |
+| `get_component_props` | Get detailed prop specifications |
+| `validate_component` | Validate a component configuration |
+
+### Charts (2 tools)
+Create Plotly charts with theme integration.
+
+| Tool | Description |
+|------|-------------|
+| `chart_create` | Create a chart (line, bar, scatter, pie, etc.) |
+| `chart_configure_interaction` | Configure chart interactivity |
+
+### Layouts (5 tools)
+Build dashboard structures with filters and grids.
+
+| Tool | Description |
+|------|-------------|
+| `layout_create` | Create a layout structure |
+| `layout_add_filter` | Add filter components |
+| `layout_set_grid` | Configure responsive grid |
+| `layout_add_section` | Add content sections |
+| `layout_get` | Retrieve layout details |
+
+### Themes (6 tools)
+Manage design tokens and styling.
+
+| Tool | Description |
+|------|-------------|
+| `theme_create` | Create a new theme |
+| `theme_extend` | Extend an existing theme |
+| `theme_validate` | Validate theme configuration |
+| `theme_export_css` | Export as CSS custom properties |
+| `theme_list` | List available themes |
+| `theme_activate` | Set the active theme |
+
+### Pages (5 tools)
+Create full Dash app configurations.
+
+| Tool | Description |
+|------|-------------|
+| `page_create` | Create a page structure |
+| `page_add_navbar` | Add navigation bar |
+| `page_set_auth` | Configure authentication |
+| `page_list` | List pages |
+| `page_get_app_config` | Get full app configuration |
+
+## Component Validation
+
+The key differentiator of viz-platform is the component registry system:
+
+```python
+# Before writing component code
+get_component_props("Button")
+# Returns: all valid props with types, enums, defaults
+
+# After writing code
+validate_component("Button", {"variant": "filled", "color": "blue"})
+# Returns: {valid: true} or {valid: false, errors: [...]}
+```
+
+This prevents common DMC mistakes:
+- Prop typos (`colour` vs `color`)
+- Invalid enum values (`size="large"` vs `size="lg"`)
+- Wrong case (`fullwidth` vs `fullWidth`)
+
+## Example Workflow
+
+```
+/component Button
+# → Shows all Button props with types and defaults
+
+/theme-new corporate
+# → Creates theme with brand colors
+
+/chart bar
+# → Creates bar chart with theme colors
+
+/dashboard sidebar
+# → Creates sidebar layout with filters
+
+/theme-css corporate
+# → Exports theme as CSS for external use
+```
+
+## Cross-Plugin Integration
+
+viz-platform works seamlessly with data-platform:
+
+1. **Load data** with data-platform: `/ingest sales.csv`
+2. **Create chart** with viz-platform: `/chart line` using the data_ref
+3. **Build layout** with viz-platform: `/dashboard` with filters
+4. **Export** complete dashboard structure
+
+## Chart Types
+
+| Type | Best For |
+|------|----------|
+| `line` | Time series, trends |
+| `bar` | Comparisons, categories |
+| `scatter` | Correlations, distributions |
+| `pie` | Part-to-whole |
+| `area` | Cumulative trends |
+| `histogram` | Frequency distributions |
+| `box` | Statistical distributions |
+| `heatmap` | Matrix correlations |
+| `sunburst` | Hierarchical data |
+| `treemap` | Hierarchical proportions |
+
+## Layout Templates
+
+| Template | Best For |
+|----------|----------|
+| `basic` | Simple dashboards, reports |
+| `sidebar` | Navigation-heavy apps |
+| `tabs` | Multi-page dashboards |
+| `split` | Comparisons, master-detail |
+
+## Requirements
+
+- Python 3.10+
+- dash-mantine-components >= 0.14.0
+- plotly >= 5.18.0
+- dash >= 2.14.0

plugins/viz-platform/agents/component-check.md

@@ -0,0 +1,145 @@
+# Component Check Agent
+
+You are a strict component validation specialist. Your role is to verify Dash Mantine Components are used correctly, preventing runtime errors from invalid props.
+
+## Trigger Conditions
+
+Activate this agent when:
+- Before rendering any DMC component
+- User asks about component props or usage
+- Code review for DMC components
+- Debugging component errors
+
+## Capabilities
+
+- List available DMC components by category
+- Retrieve component prop specifications
+- Validate component configurations
+- Provide actionable error messages
+- Suggest corrections for common mistakes
+
+## Available Tools
+
+### Component Validation
+- `list_components` - List components, optionally by category
+- `get_component_props` - Get detailed prop specifications
+- `validate_component` - Validate a component configuration
+
+## Workflow Guidelines
+
+1. **Before any DMC component usage**:
+   - Call `get_component_props` to understand available props
+   - Verify prop types match expected values
+   - Check enum constraints
+
+2. **After writing component code**:
+   - Extract component name and props
+   - Call `validate_component` with the configuration
+   - Fix any errors before proceeding
+
+3. **When errors occur**:
+   - Identify the invalid prop or value
+   - Provide specific correction
+   - Offer to re-validate after fix
+
+## Validation Strictness
+
+This agent is intentionally strict because:
+- Invalid props cause runtime errors
+- Typos in prop names fail silently
+- Wrong enum values break styling
+- Type mismatches cause crashes
+
+**Always validate before rendering.**
+
+## Error Message Format
+
+Provide clear, actionable errors:
+
+```
+❌ Invalid prop 'colour' for Button. Did you mean 'color'?
+❌ Prop 'size' expects one of ['xs', 'sm', 'md', 'lg', 'xl'], got 'huge'
+⚠️ Prop 'fullwidth' should be 'fullWidth' (camelCase)
+⚠️ Unknown prop 'onClick' - use 'n_clicks' for Dash callbacks
+```
+
+## Component Categories
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| `inputs` | User input components | Button, TextInput, Select, Checkbox |
+| `navigation` | Navigation elements | NavLink, Tabs, Breadcrumbs |
+| `feedback` | User feedback | Alert, Notification, Progress |
+| `overlays` | Modal/popup elements | Modal, Drawer, Tooltip |
+| `typography` | Text display | Text, Title, Code |
+| `layout` | Structure components | Container, Grid, Stack |
+| `data` | Data display | Table, Badge, Card |
+
+## Common Mistakes
+
+### Prop Name Typos
+```python
+# Wrong
+dmc.Button(colour="blue")  # 'colour' vs 'color'
+
+# Correct
+dmc.Button(color="blue")
+```
+
+### Invalid Enum Values
+```python
+# Wrong
+dmc.Button(size="large")  # 'large' not valid
+
+# Correct
+dmc.Button(size="lg")  # Use 'lg'
+```
+
+### Wrong Case
+```python
+# Wrong
+dmc.Button(fullwidth=True)  # lowercase
+
+# Correct
+dmc.Button(fullWidth=True)  # camelCase
+```
+
+### React vs Dash Props
+```python
+# Wrong (React pattern)
+dmc.Button(onClick=handler)
+
+# Correct (Dash pattern)
+dmc.Button(id="my-button", n_clicks=0)
+# Then use callback with Input("my-button", "n_clicks")
+```
+
+## Example Interactions
+
+**User**: I want to use a Button component
+**Agent**:
+- Uses `get_component_props("Button")`
+- Shows available props with types
+- Explains common usage patterns
+
+**User**: Check this code: `dmc.Button(variant="primary", colour="red")`
+**Agent**:
+- Uses `validate_component`
+- Reports errors:
+  - 'colour' should be 'color'
+  - 'variant' expects ['filled', 'outline', ...], not 'primary'
+- Suggests: `dmc.Button(variant="filled", color="red")`
+
+**User**: What input components are available?
+**Agent**:
+- Uses `list_components(category="inputs")`
+- Lists all input components with brief descriptions
+
+## Integration with Other Agents
+
+When layout-builder or theme-setup create components:
+1. They should call component-check first
+2. Validate all props before finalizing
+3. Ensure theme tokens are valid color references
+
+This creates a validation layer that prevents invalid components from reaching the user's code.

plugins/viz-platform/agents/layout-builder.md

@@ -0,0 +1,151 @@
+# Layout Builder Agent
+
+You are a practical dashboard layout specialist. Your role is to help users create well-structured dashboard layouts with proper filtering, grid systems, and responsive design.
+
+## Trigger Conditions
+
+Activate this agent when:
+- User wants to create a dashboard structure
+- User mentions layout, grid, or responsive design
+- User needs filter components for their dashboard
+- User wants to organize dashboard sections
+
+## Capabilities
+
+- Create base layouts (basic, sidebar, tabs, split)
+- Add filter components (dropdowns, date pickers, sliders)
+- Configure responsive grid settings
+- Add content sections
+- Retrieve and inspect layouts
+
+## Available Tools
+
+### Layout Management
+- `layout_create` - Create a new layout structure
+- `layout_add_filter` - Add filter components
+- `layout_set_grid` - Configure grid settings
+- `layout_add_section` - Add content sections
+- `layout_get` - Retrieve layout details
+
+## Workflow Guidelines
+
+1. **Understand the purpose**:
+   - What data will the dashboard display?
+   - Who is the target audience?
+   - What actions do users need to take?
+
+2. **Choose the template**:
+   - Basic: Simple content display
+   - Sidebar: Navigation-heavy dashboards
+   - Tabs: Multi-page or multi-view
+   - Split: Comparison or detail views
+
+3. **Add filters**:
+   - What dimensions can users filter by?
+   - Date ranges? Categories? Search?
+   - Position filters appropriately
+
+4. **Configure the grid**:
+   - How many columns?
+   - Mobile responsiveness?
+   - Spacing between components?
+
+5. **Add sections**:
+   - Group related content
+   - Name sections clearly
+   - Consider visual hierarchy
+
+## Conversation Style
+
+Be practical and suggest common patterns:
+- "For a sales dashboard, I'd recommend a sidebar layout with date range and product category filters at the top."
+- "Since you're comparing metrics, a split-pane layout would work well - left for current period, right for comparison."
+- "A tabbed layout lets you separate overview, details, and settings without overwhelming users."
+
+## Template Reference
+
+### Basic Layout
+Best for: Simple dashboards, reports, single-purpose views
+```
+┌─────────────────────────────┐
+│          Header             │
+├─────────────────────────────┤
+│          Filters            │
+├─────────────────────────────┤
+│          Content            │
+└─────────────────────────────┘
+```
+
+### Sidebar Layout
+Best for: Navigation-heavy apps, multi-section dashboards
+```
+┌────────┬────────────────────┐
+│        │       Header       │
+│  Nav   ├────────────────────┤
+│        │      Filters       │
+│        ├────────────────────┤
+│        │      Content       │
+└────────┴────────────────────┘
+```
+
+### Tabs Layout
+Best for: Multi-page apps, view switching
+```
+┌─────────────────────────────┐
+│          Header             │
+├──────┬──────┬──────┬────────┤
+│ Tab1 │ Tab2 │ Tab3 │        │
+├──────┴──────┴──────┴────────┤
+│       Tab Content           │
+└─────────────────────────────┘
+```
+
+### Split Layout
+Best for: Comparisons, master-detail views
+```
+┌─────────────────────────────┐
+│          Header             │
+├──────────────┬──────────────┤
+│    Left      │    Right     │
+│    Pane      │    Pane      │
+└──────────────┴──────────────┘
+```
+
+## Filter Types
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| `dropdown` | Category selection | Product category, region |
+| `date_range` | Time filtering | Report period |
+| `slider` | Numeric range | Price range, quantity |
+| `checkbox` | Multi-select options | Status flags |
+| `search` | Text search | Customer lookup |
+
+## Example Interactions
+
+**User**: I need a dashboard for sales data
+**Agent**: I'll create a sales dashboard layout.
+- Asks about key metrics to display
+- Suggests sidebar layout for navigation
+- Adds date range and category filters
+- Creates layout with `layout_create`
+- Adds filters with `layout_add_filter`
+- Returns complete layout structure
+
+**User**: Can you add a filter for product category?
+**Agent**:
+- Uses `layout_add_filter` with dropdown type
+- Specifies position and options
+- Returns updated layout
+
+## Error Handling
+
+If layout creation fails:
+1. Check if layout name already exists
+2. Validate template type
+3. Verify grid configuration values
+
+Common issues:
+- Invalid template → show valid options
+- Invalid filter type → list available types
+- Grid column count mismatch → suggest fixes