@turquoisehealth/pit-viper 2.179.1-dev.0 → 2.181.0

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,5 +1,11 @@
 {
   "name": "pit-viper",
-  "version": "1.0.0",
-  "description": "Pit Viper design system tooling for Claude Code"
+  "version": "0.0.2",
+  "description": "Pit Viper design system tooling for Claude Code",
+  "marketplace": {
+    "type": "github",
+    "owner": "turquoisehealth",
+    "repo": "pit-viper",
+    "path": "claude-plugin"
+  }
 }

package/claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}

package/claude-plugin/CLAUDE.md

@@ -1,286 +1,107 @@
-# Pit Viper Design System Reference
+# Pit Viper Design System
 
-This plugin provides tooling for Turquoise Health's Pit Viper design system. Use `/pit-viper:resolve` to find components and `/pit-viper:audit` to check compliance.
+Pit Viper is Turquoise Health's design system. Use it for all frontend work.
 
-## Resources
-
-- **Storybook:** https://pit-viper-storybook.netlify.app
-- **Icons:** https://pitviper.turquoise.health/visual-style/icons/
-
-### CSS Themes
-
-For complete utility class definitions, fetch the appropriate theme:
-
-| Theme | URL | Usage |
-|-------|-----|-------|
-| **Platform** (default) | https://pitviper.turquoise.health/assets/css/pit-viper-v2.css | Internal platform apps |
-| **Consumer** | https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css | Marketing / consumer-facing pages |
-
-Do not use the `-scoped` variant.
-
-## Overview
-
-Pit Viper is Turquoise Health's custom design system. It exists as:
-
-1. **CSS framework** — utility classes for spacing, typography, color, layout (`pv-*` prefix)
-2. **Vue component library** — `@turquoisehealth/pit-viper`, providing 58+ components
-
-**Package:** `@turquoisehealth/pit-viper` in `node_modules/`
-**Font:** Inter (400, 500, 600)
-**Type scale:** Compact (body-md = 0.75rem / 12px)
-
-## Color Palette
-
-### Brand Colors
-| Token | Hex | Usage |
-|---|---|---|
-| Primary Brand | `#176F6F` | Interactive text, links, primary buttons, borders |
-| Secondary Brand | `#02363D` | Body text, secondary buttons, dark surfaces |
-| Brand Accent Light | `#A8E6E1` | Inverse buttons, AI button, tertiary buttons |
-| Brand Accent Bg | `#F3FCFB` | Brand accent backgrounds |
-| Brand Variant | `#16696D` | Visited links, tag primary, status success |
-| Brand Gradient | `linear-gradient(109deg, #176F6F 0%, #02363D 100%)` | Brand surface gradient |
-
-### Semantic Colors
-| Token | Hex | Usage |
-|---|---|---|
-| Error / Critical | `#DA1E28` | Error text, destructive buttons |
-| Error Hover | `#A2191F` | Error border, destructive hover |
-| Warning | `#896000` | Warning text |
-| Success | `#0E6027` | Success text |
-| Success Status | `#218C88` | Checked states, success status dots |
-| Yellow Status | `#E5A000` | Status indicators |
-
-### Text Colors
-| Class | Hex | Usage |
-|---|---|---|
-| `.pv-text-default` | `#02363D` | Primary body text |
-| `.pv-text-subdued` | `#6E7784` | Secondary/helper text |
-| `.pv-text-tertiary` | `#6E8081` | Tertiary text |
-| `.pv-text-inverse` | `#FFFFFF` | Text on dark surfaces |
-| `.pv-text-brand` | `#176F6F` | Brand-colored text, links |
-| `.pv-text-critical` | `#DA1E28` | Error messages |
-| `.pv-text-warning` | `#896000` | Warning text |
-| `.pv-text-success` | `#0E6027` | Success text |
-
-### Surface Colors
-| Class | Hex | Usage |
-|---|---|---|
-| `.pv-surface` | `#FFFFFF` | Default background |
-| `.pv-surface-accent` | `#F8F8FA` | Subtle alternate backgrounds |
-| `.pv-surface-brand` | `#02363D` | Dark brand surfaces |
-| `.pv-surface-brand-inverse` | `#176F6F` | Teal brand surfaces |
-| `.pv-surface-highlight` | `#E4F8F6` | Highlight/selection backgrounds |
-| `.pv-surface-brand-accent` | `#F3FCFB` | Light teal backgrounds |
-| `.pv-surface-inverse` | `#242626` | Dark mode surfaces |
-| `.pv-surface-warning` | `#FAECCC` | Warning backgrounds |
-| `.pv-surface-success` | `#E8FDEA` | Success backgrounds |
-| `.pv-surface-critical` | `#FFF1F1` | Error backgrounds |
-
-### Border Colors
-| Token | Hex | Usage |
-|---|---|---|
-| Default | `#DCDFE4` | Standard borders |
-| Accent | `#176F6F` | Active/focus borders |
-| Warning | `#EFC666` | Warning borders |
-| Critical | `#A2191F` | Error borders |
-| Brand | `#02363D` | Brand borders |
-
-### Data Visualization Colors (in order)
-1. `#36C5BA` 2. `#16696D` 3. `#FF7A4E` 4. `#C97AEB` 5. `#F2AD0D` 6. `#7C8AF4` 7. `#95C54C`
+## Philosophy
 
-## Typography
+Pit Viper enforces visual consistency across 50+ Turquoise Health apps by:
 
-### Headings
-| Class | Size | Line Height | Weight |
-|---|---|---|---|
-| `.pv-heading-1` | 1.25rem (20px) | 1.2 | 600 |
-| `.pv-heading-2` | 1rem (16px) | 1.5 | 600 |
-| `.pv-heading-3` | 0.875rem (14px) | 1.43 | 600 |
-| `.pv-heading-4` | 0.75rem (12px) | 1.33 | 600 |
-| `.pv-heading-5` | 0.75rem (12px) | 1.33 | 600 |
+- **Eliminating custom CSS** — Use only pv-* utility classes
+- **Replacing raw HTML elements** — Use semantic Pit Viper components
+- **Maintaining brand coherence** — Consistent colors, typography, spacing
 
-### Body Text
-| Class | Size | Line Height |
-|---|---|---|
-| `.pv-text-body-xl` | 0.875rem (14px) | 1.14 |
-| `.pv-text-body-lg` | 0.875rem (14px) | 1.14 |
-| `.pv-text-body-md` | 0.75rem (12px) | 1.33 |
-| `.pv-text-body-sm` | 0.6875rem (11px) | 1.45 |
-| `.pv-text-body-xs` | 0.6875rem (11px) | 1.45 |
-
-### Title Classes (semibold variants)
-`.pv-text-title-xl`, `.pv-text-title-lg`, `.pv-text-title-md`, `.pv-text-title-sm`, `.pv-text-title-xs` — same sizes as body, weight 600.
-
-### Eyebrow Classes
-| Class | Size | Weight | Style |
-|---|---|---|---|
-| `.pv-text-eyebrow-lg` | 0.875rem | 700 | Uppercase, letter-spacing 0.0375rem |
-| `.pv-text-eyebrow-sm` | 0.75rem | 700 | Uppercase, letter-spacing 0.0375rem |
-
-## Spacing
-
-All spacing uses a 4px base grid. Classes apply `margin-bottom` (stack) or `padding` (inset).
-
-### Stack (Vertical Margin)
-| Class | Value |
-|---|---|
-| `.pv-stack-0` | 0 |
-| `.pv-stack-4` | 0.25rem (4px) |
-| `.pv-stack-8` | 0.5rem (8px) |
-| `.pv-stack-12` | 0.75rem (12px) |
-| `.pv-stack-16` | 1rem (16px) |
-| `.pv-stack-20` | 1.25rem (20px) |
-| `.pv-stack-24` | 1.5rem (24px) |
-| `.pv-stack-32` | 2rem (32px) |
-| `.pv-stack-64` | 4rem (64px) |
-| `.pv-stack-128` | 8rem (128px) |
+## Rules
 
-Responsive variants (e.g. `.pv-stack-16-responsive`) use half-size on mobile, full size at 768px+.
+These are non-negotiable:
 
-### Inset (Padding)
-| Pattern | Example Classes | Description |
-|---|---|---|
-| Square (all sides) | `.pv-inset-square-8` through `-48` | Equal padding |
-| Squish (horiz > vert) | `.pv-inset-squish-8`, `-12`, `-16` | e.g. `0.75rem 1rem` |
-| Block (vertical) | `.pv-inset-block-8` through `-32` | `padding-block` only |
-| Inline (horizontal) | `.pv-inset-inline-16` through `-32` | `padding-inline` only |
+1. **No custom CSS** — Only pv-* utility classes. No `<style>` blocks.
+2. **No Tailwind** — Pit Viper has its own utility system.
+3. **No raw form elements** — Use PvInput, PvButton, PvSelectButton, etc.
+4. **No guessing** — Verify icons and component names exist before using.
 
-### Flow (Gap between children)
-`.pv-flow-8`, `.pv-flow-16`, `.pv-flow-24` — margin-bottom on all children except last.
+## LLM Endpoints
 
-### Flex
-| Class | Description |
-|---|---|
-| `.pv-flex` | `display: flex; gap: 0.5rem; align-items: center` |
-| `.pv-flex-vertical` | Column direction |
-| `.pv-flex-responsive` | Column on mobile, row at 768px+ |
-| `.pv-flex-item` | `flex: 1` |
-| `.pv-space-between` | `justify-content: space-between` |
+Use these to look up current component info (via WebFetch):
 
-Use CSS custom property `--flex-gap` to override gap, `--flex-justify` for justify-content.
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /llm/search?q={query}` | Search Vue + CSS components |
+| `GET /llm/component/{name}` | Get component props, stories, source |
+| `GET /llm/component` | List all Vue components |
+| `GET /llm/css/{component}` | Get CSS component docs |
+| `GET /llm/css` | List all CSS components |
+| `GET /llm/tokens?category={cat}` | Get design tokens (color, spacing, etc.) |
 
-## Border Radius
+Base URL: `https://pitviper.turquoise.health`
 
-| Class | Value |
-|---|---|
-| `.pv-radius-sm` | 2px |
-| `.pv-radius` | 5px (default) |
-| `.pv-radius-lg` | 12px |
-| `.pv-radius-top` | 5px 5px 0 0 |
-| `.pv-radius-bottom` | 0 0 5px 5px |
+Always search before assuming a component or class exists.
 
-## Shadows & Elevation
+## Quick Reference
 
-| Level | Usage | Value |
-|---|---|---|
-| Button | Default button elevation | `0px 6px 8px rgba(0,0,0,0.05), 0px 4px 6px -2px rgba(0,0,0,0.04)` |
-| Popover | Dropdowns, popovers | `0px 8px 12px -4px rgba(0,0,0,0.08), 0px 12px 16px rgba(0,0,0,0.1)` |
-| Elevated Hover | Button hover state | `0px 12px 16px rgba(0,0,0,0.1), 0px 8px 12px -4px rgba(0,0,0,0.08)` |
-| Modal | Dialogs, drawers | `0px 12px 20px rgba(0,0,0,0.25), 0px 16px 28px -8px rgba(0,0,0,0.25)` |
+### Themes
 
-## Responsive Breakpoints
+| Theme | CSS File | Use Case |
+|-------|----------|----------|
+| Platform | `pit-viper-v2.css` | Internal tools, dashboards |
+| Consumer | `pit-viper-consumer.css` | Marketing, public sites |
 
-| Breakpoint | Usage |
-|---|---|
-| **768px** | Primary breakpoint — sidebar collapses, flex columns stack, responsive spacing adjusts |
+### Common Classes
 
-Container max-widths: `.pv-container-sm` (768px), `.pv-container-md` (972px), `.pv-container-lg` (1448px).
+**Typography:**
+- `.pv-heading-1` through `.pv-heading-5`
+- `.pv-text-body-md`, `.pv-text-body-sm`
+- `.pv-text-title-md`, `.pv-text-subdued`
 
-Standard transition duration: **0.125s ease-in-out**.
+**Spacing (4px grid):**
+- `.pv-stack-8`, `.pv-stack-16`, `.pv-stack-24` (margin-bottom)
+- `.pv-inset-square-16`, `.pv-inset-squish-12` (padding)
+- `.pv-flow-16` (gap between children)
 
-## Components
+**Layout:**
+- `.pv-flex`, `.pv-flex-vertical`
+- `.pv-space-between`
+- `.pv-container-md`, `.pv-container-lg`
 
-### Most Commonly Used
-| Component | Purpose |
-|---|---|
-| `PvButton` | All buttons (props: `variant`, `size`, `leftIcon`, `rightIcon`, `loading`, `disabled`, `inverse`) |
-| `PvAiButton` | AI-specific action buttons |
-| `PvIcon` | SVG icon (props: `name`, `size`: 10/12/20/24/32/64) |
-| `PvSpinner` | Loading spinner (props: `variant`, `size`) |
-| `PvInput` | Text input (v-model, props: `type`, `variant`, `placeholder`, `error`, `disabled`) |
-| `PvTextArea` | Multi-line input |
-| `PvCheckbox` | Checkbox (v-model, props: `indeterminate`, `disabled`) |
-| `PvSwitch` | Toggle switch (v-model, props: `size`, `label`, `disabled`) |
-| `PvSelectButton` | Dropdown with search (v-model, props: `options`, `optionsVariant`, `label`) |
-| `PvTabs` | Tab bar (v-model, props: `tabs` array with `label`/`counter`/`icon`) |
-| `PvSegmentedControl` | Button group toggle |
-| `PvModal` | Dialog (v-model, props: `header`, `subheader`; slots: `#body`, `#footer`) |
-| `PvDrawer` | Side panel (v-model, props: `header`, `showSearchbar`; slots: `#header`, `#default`, `#footer`) |
-| `PvAccordion` | Collapsible section (v-model, props: `header`, `chevronPosition`, `counter`) |
-| `PvToast` | Notification (props: `label`, `variant`: success/error/info/dark) |
-| `PvTooltip` | Tooltip (props: `variant`, `tooltipPosition`, `interactive`; slots: `#label`, `#tooltip-content`) |
-| `PvPopoverMenu` | Dropdown menu |
-| `PvTag` | Inline tag |
-| `PvPill` | Rounded badge |
-| `PvCounterBadge` | Numeric badge |
-| `PvBanner` | Alert banner |
-| `PvAvatar` | User avatar |
-| `PvCard` | Card container |
-| `PvSkeleton` | Loading placeholder |
-| `PvProgressBar` | Progress indicator |
-| `PvTree` | Hierarchical tree |
-| `PvSidePanel` | Three-column layout |
-| `PvBreadcrumbs` | Breadcrumb nav |
-| `PvPagination` | Pagination controls |
+**Colors:**
+- `.pv-text-default`, `.pv-text-brand`, `.pv-text-subdued`
+- `.pv-surface`, `.pv-surface-accent`, `.pv-surface-brand`
 
-### Visualization Components
-Import from `@turquoisehealth/pit-viper/components/visualizations`:
+### Common Components
 
-| Component | Purpose |
-|---|---|
-| `PvDataTable` | AG Grid wrapper for data tables |
-| `PvChart` | AG Charts wrapper for visualizations |
-| `PvDataTableWithChart` | Combined table and chart view |
-| `PvMapChart` | Geographic map visualization |
+| Need | Component |
+|------|-----------|
+| Button | `PvButton` |
+| Text input | `PvInput` |
+| Dropdown | `PvSelectButton` |
+| Multi-select | `PvMultiSelectButton` |
+| Data table | `PvDataTable` |
+| Chart | `PvChart` |
+| Modal | `PvModal` |
+| Drawer | `PvDrawer` |
+| Tabs | `PvTabs` |
+| Card | `PvCard` |
 
-## Import Paths
+### Import Paths
 
 ```typescript
 // Base components
-import { PvButton, PvInput, PvModal } from '@turquoisehealth/pit-viper/components'
+import { PvButton, PvInput } from '@turquoisehealth/pit-viper/components'
 
 // Visualization components
 import { PvDataTable, PvChart } from '@turquoisehealth/pit-viper/components/visualizations'
-```
-
-## Theme Selection
-
-Choose the appropriate theme based on the application type:
-
-| Application Type | Theme | CSS File |
-|-----------------|-------|----------|
-| Internal tools, dashboards, admin panels | Platform | `pit-viper-v2.css` |
-| Marketing pages, public websites, consumer apps | Consumer | `pit-viper-consumer.css` |
-
-### Key Visual Differences
-
-| Property | Platform | Consumer |
-|----------|----------|----------|
-| Font Family | Inter | GT Standard |
-| Heading-1 Size | 1.25rem (20px) | 3.875rem (62px) |
-| Body Text Size | 0.75rem (12px) | 1rem (16px) |
-| Overall Density | Compact | Spacious |
-| Color Warmth | Cool blue-gray | Warmer teal |
-
-### Theme URLs
 
-```
-Platform: https://pitviper.turquoise.health/assets/css/pit-viper-v2.css
-Consumer: https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css
+// Layout (direct import)
+import PvSidePanel from '@turquoisehealth/pit-viper/components/layout/PvSidePanel/PvSidePanel.vue'
 ```
 
-### Web Components (for non-Vue apps)
+## Resources
 
-```html
-<script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
-```
+- **Storybook:** https://pit-viper-storybook.netlify.app
+- **Icons:** https://pitviper.turquoise.health/visual-style/icons/
+- **LLM API:** https://pitviper.turquoise.health/llm
 
-Web components use kebab-case: `<pv-button>`, `<pv-input>`, `<pv-card>`, etc.
+## Skills
 
-## Rules
+- `/pit-viper` — Main skill for all FE work (implicit triggering)
 
-1. **No custom CSS** — Use only Pit Viper utility classes (see CSS Themes above)
-2. **No Tailwind** — Pit Viper has its own utility system
-3. **Prefer components** — Use Pit Viper components over raw HTML elements
-4. **Valid icons only** — Only use icon names from https://pitviper.turquoise.health/visual-style/icons/
+To audit files for compliance, ask the skill: "audit this file" or "check for pit viper violations".

package/claude-plugin/README.md

@@ -1,20 +1,34 @@
 # Pit Viper Claude Plugin
 
-Internal Claude Code plugin for Pit Viper design system tooling.
+Claude Code plugin for Pit Viper design system.
 
 ## Installation
 
-### Claude Code CLI
+### Option 1: Install from GitHub (recommended)
 
+**Step 1: Add the marketplace**
+
+Claude Code CLI:
 ```bash
-claude --plugin-dir ~/claude-plugins-pit-viper
+/plugin
 ```
+Then select **Marketplace** → **Add marketplace** → enter `turquoisehealth/pit-viper`
+
+Claude Code Desktop:
+Customize → Create plugin → Add marketplace → enter `turquoisehealth/pit-viper`
 
-Or add to your Claude Code settings for persistent installation.
+**Step 2: Install the plugin**
+```bash
+/plugin install turquoisehealth@pit-viper
+```
 
-### Cowork
+### Option 2: Clone and install locally
 
-Contact DevTools team for managed installation.
+```bash
+git clone https://github.com/turquoisehealth/pit-viper.git
+cd pit-viper
+/plugin add ./claude-plugin
+```
 
 ## Prerequisites
 
@@ -26,94 +40,134 @@ npm install @turquoisehealth/pit-viper
 
 For Figma integration, authenticate via `/mcp` in Claude Code.
 
-## Available Skills
+## Skills
 
-### `/pit-viper:create`
+### `/pit-viper` (Implicit)
 
-Build complete pages and layouts from natural language descriptions. No Vue, imports, or CSS knowledge required.
+The main skill triggers automatically on all frontend work — UI building, Vue/HTML editing, component usage, and visual interface work.
 
-**Usage:**
-```
-/pit-viper:create a dashboard with a sidebar and data table
-/pit-viper:create a login form
-/pit-viper:create a settings page with tabs for profile and notifications
-/pit-viper:create a marketing landing page with hero and features
-```
+**Output Modes:**
+- **Engineer Mode**: Vue 3 Composition API code (when editing .vue files)
+- **Prototype Mode**: HTML with pv-* classes (for quick prototypes, non-technical users)
+- **Design Review Mode**: Component selection rationale (for design discussions)
 
-**Output:** Complete Vue SFC or HTML file ready to use.
+**Workflow:**
+1. Searches for components via `/llm/search`
+2. Gets detailed props/usage via `/llm/component/{name}`
+3. Fetches CSS utilities and tokens via `/llm/css` and `/llm/tokens`
+4. Generates appropriate output based on context
 
-**Theme Detection:**
-- Keywords like "marketing", "landing", "consumer" → Consumer theme (large typography)
-- Keywords like "dashboard", "admin", "internal" → Platform theme (compact, default)
-- Override with `--theme=consumer` or `--theme=platform`
+### Auditing Files
 
-**Format Options:**
-- Default: Vue Single File Component (`<script setup>` + `<template>`)
-- Add `--format=html` for plain HTML with web components
+To check files for design system compliance, ask the skill:
+- "audit this file for pit viper violations"
+- "check src/components/Foo.vue for compliance"
+- "fix any pit viper violations in changed files"
 
-### `/pit-viper:resolve`
+The skill will check for custom CSS, raw HTML elements, invalid classes, and wrong imports — then auto-fix them.
 
-Find the correct Pit Viper component for a UI element.
+## LLM Endpoints
 
-**Usage:**
-```
-/pit-viper:resolve dropdown with search
-/pit-viper:resolve <figma-url>
-/pit-viper:resolve <html-snippet>
-```
+The skill uses Pit Viper's `/llm` HTTP endpoints (via WebFetch) for dynamic component lookup:
 
-**Output:** Component name, import path, props, and usage example.
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /llm` | API index |
+| `GET /llm/search?q={query}` | Search across CSS and Vue components |
+| `GET /llm/component` | List all Vue components |
+| `GET /llm/component/{name}` | Get component details (props, stories, source) |
+| `GET /llm/component/{name}?web_component=true` | Get web component variant |
+| `GET /llm/css` | List all CSS components |
+| `GET /llm/css/{component}` | Get CSS component documentation |
+| `GET /llm/css/themes` | Get theme CDN URLs |
+| `GET /llm/tokens` | List all design tokens |
+| `GET /llm/tokens?category={cat}` | Filter tokens (color, spacing, typography, border, shadow) |
 
-### `/pit-viper:audit`
+Base URL: `https://pitviper.turquoise.health`
 
-Check files for design system compliance and auto-fix violations.
+## MCP Servers
 
-**Usage:**
-```
-/pit-viper:audit                           # Audit git-changed files
-/pit-viper:audit src/components/Foo.vue    # Audit specific file
-/pit-viper:audit --all                     # Audit all Vue/HTML files
+The plugin includes an MCP configuration for Figma integration:
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}
 ```
 
-**Checks:**
-- Custom CSS (`<style>` blocks, inline styles)
-- Raw HTML elements that should be Pit Viper components
-- Invalid CSS class names
-- Wrong import paths
+To authenticate, run `/mcp` in Claude Code and follow the Figma OAuth flow.
 
-## Adding Production Examples
+## Running Evals
 
-Add curated code snippets to `examples/` for the resolve skill to reference:
+The plugin includes an eval suite to verify skill behavior. Evals are stored in `pit-viper-workspace/evals/`.
+
+### Using skill-creator
+
+```bash
+/skill-creator
+```
+
+Then follow the prompts to run evals against the pit-viper skill. The skill-creator will:
+1. Spawn test cases with and without the skill
+2. Grade assertions automatically
+3. Generate a benchmark report
+4. Open a viewer for qualitative review
+
+### Eval structure
 
 ```
-examples/
-├── PvDataTable.vue         # Common table patterns
-├── PvSelectButton.vue      # Dropdown usage
-├── PvModal.vue             # Modal with form
-└── ...
+pit-viper-workspace/
+├── evals/
+│   ├── evals.json         # Test cases with prompts and assertions
+│   └── fixtures/          # Vue files used as test inputs
+└── iteration-N/           # Results from each eval run
+    ├── eval-name/
+    │   ├── with_skill/
+    │   └── without_skill/
+    └── benchmark.json
 ```
 
-The resolve skill checks `examples/{ComponentName}.vue` before falling back to Storybook.
+### Eval categories
+
+| Category | Tests |
+|----------|-------|
+| Engineer (E1-E3) | Vue component generation, loading states, unknown components |
+| Prototype (P1-P3) | HTML generation, settings pages, iterative context |
+| Design (D1-D3) | Component selection, token validation, layout review |
+| Cross (X1-X4) | Tailwind avoidance, theme detection, mode ambiguity, icons |
+| Tables (T1-T4) | PvDataTable usage, PvChart usage, HTML tables, chart rejection |
 
 ## Resources
 
 - **Storybook:** https://pit-viper-storybook.netlify.app
 - **Icons:** https://pitviper.turquoise.health/visual-style/icons/
-- **Design Tokens:** See `CLAUDE.md` for full color, typography, and spacing reference
-- **MCP Server:** https://pitviper.turquoise.health/mcp
-
-## MCP Tools
-
-The plugin uses the Pit Viper MCP server for fast component lookups. Available tools:
+- **Design Tokens:** See `CLAUDE.md` for quick reference
+- **LLM API:** https://pitviper.turquoise.health/llm
 
-| Tool | Purpose |
-|------|---------|
-| `mcp__pit-viper__search` | Search across CSS and Vue components |
-| `mcp__pit-viper__storybook_get_component` | Get Vue component details (props, stories, source) |
-| `mcp__pit-viper__storybook_list_components` | List all Vue components with stories |
-| `mcp__pit-viper__css_get_docs` | Get CSS component documentation |
-| `mcp__pit-viper__css_list_components` | List CSS components by category |
-| `mcp__pit-viper__css_list_tokens` | List design tokens (colors, spacing, etc.) |
-| `mcp__pit-viper__css_search_classes` | Search CSS classes by pattern |
+## Plugin Structure
 
-The MCP server is automatically enabled when using this plugin in the pit-viper repo.
+```
+claude-plugin/
+├── .claude-plugin/
+│   └── plugin.json              # Plugin metadata
+├── .mcp.json                    # MCP server configuration (Figma)
+├── CLAUDE.md                    # Philosophy, rules, quick reference
+├── README.md                    # This file
+├── skills/
+│   └── pit-viper/
+│       ├── SKILL.md             # Main skill (implicit triggering)
+│       └── references/
+│           ├── design-rules.md      # Mandatory spacing, typography, layout rules
+│           ├── patterns-core.md     # Universal utility class patterns (always loaded)
+│           ├── vue-guidelines.md    # Engineer Mode — Vue patterns + anti-patterns
+│           ├── html-patterns.md     # Prototype Mode — HTML patterns + anti-patterns
+│           ├── design-language.md   # Design Review Mode reference
+│           ├── layout-patterns.md   # Page layout patterns
+│           └── theme-guide.md       # Theme selection guide
+└── examples/                    # Example usage files
+```