@sky.ui/mcp 0.0.1 → 0.0.2

package/docs/cross-model-mcp-playbook.md

@@ -1,127 +1,127 @@
-# Cross-model MCP playbook (Sky UI)
-
-**Purpose:** Run Sky UI MCP across LLMs with **fewer tokens**, **predictable tool use**, and **verifiable** correctness. Fill the tables as you validate each vendor.
-
-**Reality check:** No assistant + MCP stack can guarantee **literal 100% accuracy for every framework and coding case**—models hallucinate, tools can return partial data (missing CEM, offline packages), and user code differs. Treat **“accuracy”** as **(a)** deterministic outputs for the same tool + inputs, **(b)** schema-valid shipped JSON, **(c)** golden tests on critical paths, **(d)** explicit fallbacks when data is missing.
-
----
-
-## 1. One-block router (paste once per session; keep short)
-
-Use this verbatim or trim per model token limits. The same text ships as **`packages/mcp/docs/starter-prompt.md`**.
-
-```
-You MUST use Sky UI MCP tools as the only source for component names, imports, props, events, slots, and theme tokens. Do not invent tags or --sky-* names.
-
-Styling priority (pages, layouts, shells): Prefer @sky.ui/utils utility classes on elements (`class` / `className`) for layout, spacing, typography, and colors. Use get_docs `packages/mcp/docs/utils-usage-guide.md` for setup; utility_classes (variant_prefixes, search_classes, check_class) for class names; get_theme (operation guide, then fields/field) for userTheme. Do NOT default to large hand-written plain CSS or unrelated CSS frameworks unless the user asks or a case truly cannot be expressed with utilities.
-
-Order: (1) get_project_guide (kind installation | setup) (2) get_sky_component_docs with optional surface (3) get_component_usage for lit/react/vue (4) get_reactivity_layer for @sky.ui/reactivity (5) get_chart_usage for sky-chart (6) theme: get_theme operation guide → match_intent/fields/field/compose (7) layout/styling: utility_classes + utils-usage-guide via get_docs.
-
-JSON payloads include `_skyUiMcp.truthLayer` and `agentMust`: obey them — confirm API facts with get_sky_component_docs.
-
-If a tool returns code starting with JSON parse errors or empty arrays, say what is missing (e.g. install or build @sky.ui/core for `custom-elements.json`) and retry after suggesting the user fix the environment.
-```
-
----
-
-## 2. Low-token rules (tool choice)
-
-| Goal | Prefer | Avoid |
-|------|--------|--------|
-| Single prop/event/slot/method slice | `get_sky_component_docs` + `surface` | Full docs when you only need one slice |
-| Multiple components | `get_sky_component_docs` + `names[]` | Many sequential single-name calls |
-| Theme JSON from user goals | `get_theme` `match_intent` → `compose` or `field` | Guessing ThemeConfig paths |
-| Token names list | `get_theme` `variables` | Guessing `--sky-*` |
-| Bundler wiring | `get_project_guide` (`kind: setup`) | Copying generic Vite docs from memory |
-| React/Vue usage | `get_component_usage` | Hand-written wrappers from memory |
-| Charts | `get_chart_usage` + `get_sky_component_docs` (`sky-chart`) | Inventing option keys |
-| Page/layout styling | `utility_classes` + utils-usage-guide | Big ad-hoc CSS unless user opts out |
-
----
-
-## 3. Framework fast paths (minimal sequence)
-
-### Lit (native web components)
-
-| Step | Tool | Notes |
-|------|------|-------|
-| 1 | `get_project_guide` (`kind: installation`, `lit` or `vanilla`) | |
-| 2 | `get_project_guide` (`kind: setup`, bundler param) | |
-| 3 | `get_component_usage` (`lit`, component name) | |
-| 4 | Split API: `get_sky_component_docs` + `surface` as needed | |
-
-### React (`@sky.ui/react`)
-
-| Step | Tool | Notes |
-|------|------|-------|
-| 1 | `get_project_guide` (`kind: installation`, `react`) | |
-| 2 | `get_component_usage` (`react`) | |
-| 3 | Split docs from core component name | |
-
-### Vue (`@sky.ui/vue`)
-
-| Step | Tool | Notes |
-|------|------|-------|
-| 1 | `get_project_guide` (`kind: installation`, `vue`) | |
-| 2 | `get_component_usage` (`vue`) | |
-| 3 | Split docs | |
-
-### `@sky.ui/reactivity` only
-
-| Step | Tool | Notes |
-|------|------|-------|
-| 1 | `get_reactivity_layer` (`operation: list_topics`) | |
-| 2 | `get_reactivity_layer` (`get_topic`) | |
-| 3 | Optional `get_docs` allowlisted README slice | |
-
----
-
-## 4. Accuracy guarantees you can enforce
-
-| Mechanism | What it proves | Owner action |
-|-----------|----------------|--------------|
-| **Golden tests** | Same tool input → same JSON shape | `test/mcp/run-mcp-test.mjs`, `contract-golden.mjs` |
-| **CEM present** (`npm run build:main`) | Manifest supplements AST docs | Document in onboarding |
-| **`sky-ui://catalog/tools` resource** | Discover tool names | Kept in sync via `verify-mcp-tool-parity.mjs` |
-| **Theme authoring contract** | Stable ThemeConfig paths + hooks | `get_theme` operations + `theme-authoring-contract.json` |
-| **Tool errors (`isError: true`)** | `{ code, error, ...extras }` | `McpErrorCode` in `mcp-tool-errors.ts` |
-
----
-
-## 5. Known systemic gaps
-
-| Gap | Symptom | Mitigation |
-|-----|---------|------------|
-| POST allowlist drift | 403 on valid tools | Build runs `verify-mcp-tool-parity.mjs` |
-| Huge responses | Context blow-up | Use `surface`, limits, pagination |
-| Offline / no CEM | AST-only or CEM-only docs | Build core; run from monorepo with source |
-| Utils not installed | `utility_classes` uses snapshot | Shipped `utils-suggestion-snapshot.json` at MCP build |
-
----
-
-## 6. Model evaluation matrix (your team fills)
-
-| Model / client | Stdio MCP | HTTP POST `/tool` | Notes |
-|----------------|-----------|-------------------|-------|
-| | ☐ | ☐ | |
-
-**Smoke checklist per row:** `sky_components` (`list`, limit 5) → `get_sky_component_docs` (`surface: props`, `sky-button`) → `get_theme` (`operation: guide`) → `get_theme` (`match_intent`, phrase `brand color`) → `get_theme` (`variables`, `max_names` 50) → `utility_classes` (`check_class`, `p-4`).
-
----
-
-## 7. Improvement backlog
-
-**Shipped (1.1.0):** Standard **9-tool** surface; `get_theme` guide/fields/field/match_intent/compose/variables; `get_reactivity_layer`; `get_chart_usage`; `utility_classes` snapshot fallback; docs aligned to new surface.
-
-1. Expand golden tests as tools evolve.
-2. Optional: richer component discovery heuristics without re-exposing removed guideline tools.
-
----
-
-## 8. How to fetch this file via MCP
-
-1. **`get_docs`** with path **`packages/mcp/docs/cross-model-mcp-playbook.md`**
-2. Short session prompt: **`packages/mcp/docs/starter-prompt.md`**
-3. **`crossModelPlaybookPath`** from **`get_theme`** `variables` response → **`get_docs`**
-
-*Last updated: 2026-06 — 9-tool standard surface.*
+# Cross-model MCP playbook (Sky UI)
+
+**Purpose:** Run Sky UI MCP across LLMs with **fewer tokens**, **predictable tool use**, and **verifiable** correctness. Fill the tables as you validate each vendor.
+
+**Reality check:** No assistant + MCP stack can guarantee **literal 100% accuracy for every framework and coding case**—models hallucinate, tools can return partial data (missing CEM, offline packages), and user code differs. Treat **“accuracy”** as **(a)** deterministic outputs for the same tool + inputs, **(b)** schema-valid shipped JSON, **(c)** golden tests on critical paths, **(d)** explicit fallbacks when data is missing.
+
+---
+
+## 1. One-block router (paste once per session; keep short)
+
+Use this verbatim or trim per model token limits. The same text ships as **`packages/mcp/docs/starter-prompt.md`**.
+
+```
+You MUST use Sky UI MCP tools as the only source for component names, imports, props, events, slots, and theme tokens. Do not invent tags or --sky-* names.
+
+Styling priority (pages, layouts, shells): Prefer @sky.ui/utils utility classes on elements (`class` / `className`) for layout, spacing, typography, and colors. Use get_docs `packages/mcp/docs/utils-usage-guide.md` for setup; utility_classes (variant_prefixes, search_classes, check_class) for class names; get_theme (operation guide, then fields/field) for userTheme. Do NOT default to large hand-written plain CSS or unrelated CSS frameworks unless the user asks or a case truly cannot be expressed with utilities.
+
+Order: (1) get_project_guide (kind installation | setup) (2) get_sky_component_docs with optional surface (3) get_component_usage for lit/react/vue (4) get_reactivity_layer for @sky.ui/reactivity (5) get_chart_usage for sky-chart (6) theme: get_theme operation guide → match_intent/fields/field/compose (7) layout/styling: utility_classes + utils-usage-guide via get_docs.
+
+JSON payloads include `_skyUiMcp.truthLayer` and `agentMust`: obey them — confirm API facts with get_sky_component_docs.
+
+If a tool returns code starting with JSON parse errors or empty arrays, say what is missing (e.g. install or build @sky.ui/core for `custom-elements.json`) and retry after suggesting the user fix the environment.
+```
+
+---
+
+## 2. Low-token rules (tool choice)
+
+| Goal | Prefer | Avoid |
+|------|--------|--------|
+| Single prop/event/slot/method slice | `get_sky_component_docs` + `surface` | Full docs when you only need one slice |
+| Multiple components | `get_sky_component_docs` + `names[]` | Many sequential single-name calls |
+| Theme JSON from user goals | `get_theme` `match_intent` → `compose` or `field` | Guessing ThemeConfig paths |
+| Token names list | `get_theme` `variables` | Guessing `--sky-*` |
+| Bundler wiring | `get_project_guide` (`kind: setup`) | Copying generic Vite docs from memory |
+| React/Vue usage | `get_component_usage` | Hand-written wrappers from memory |
+| Charts | `get_chart_usage` + `get_sky_component_docs` (`sky-chart`) | Inventing option keys |
+| Page/layout styling | `utility_classes` + utils-usage-guide | Big ad-hoc CSS unless user opts out |
+
+---
+
+## 3. Framework fast paths (minimal sequence)
+
+### Lit (native web components)
+
+| Step | Tool | Notes |
+|------|------|-------|
+| 1 | `get_project_guide` (`kind: installation`, `lit` or `vanilla`) | |
+| 2 | `get_project_guide` (`kind: setup`, bundler param) | |
+| 3 | `get_component_usage` (`lit`, component name) | |
+| 4 | Split API: `get_sky_component_docs` + `surface` as needed | |
+
+### React (`@sky.ui/react`)
+
+| Step | Tool | Notes |
+|------|------|-------|
+| 1 | `get_project_guide` (`kind: installation`, `react`) | |
+| 2 | `get_component_usage` (`react`) | |
+| 3 | Split docs from core component name | |
+
+### Vue (`@sky.ui/vue`)
+
+| Step | Tool | Notes |
+|------|------|-------|
+| 1 | `get_project_guide` (`kind: installation`, `vue`) | |
+| 2 | `get_component_usage` (`vue`) | |
+| 3 | Split docs | |
+
+### `@sky.ui/reactivity` only
+
+| Step | Tool | Notes |
+|------|------|-------|
+| 1 | `get_reactivity_layer` (`operation: list_topics`) | |
+| 2 | `get_reactivity_layer` (`get_topic`) | |
+| 3 | Optional `get_docs` allowlisted README slice | |
+
+---
+
+## 4. Accuracy guarantees you can enforce
+
+| Mechanism | What it proves | Owner action |
+|-----------|----------------|--------------|
+| **Golden tests** | Same tool input → same JSON shape | `test/mcp/run-mcp-test.mjs`, `contract-golden.mjs` |
+| **CEM present** (`npm run build:core`) | Manifest supplements AST docs | Document in onboarding |
+| **`sky-ui://catalog/tools` resource** | Discover tool names | Kept in sync via `verify-mcp-tool-parity.mjs` |
+| **Theme authoring contract** | Stable ThemeConfig paths + hooks | `get_theme` operations + `theme-authoring-contract.json` |
+| **Tool errors (`isError: true`)** | `{ code, error, ...extras }` | `McpErrorCode` in `mcp-tool-errors.ts` |
+
+---
+
+## 5. Known systemic gaps
+
+| Gap | Symptom | Mitigation |
+|-----|---------|------------|
+| POST allowlist drift | 403 on valid tools | Build runs `verify-mcp-tool-parity.mjs` |
+| Huge responses | Context blow-up | Use `surface`, limits, pagination |
+| Offline / no CEM | AST-only or CEM-only docs | Build core; run from monorepo with source |
+| Utils not installed | `utility_classes` uses snapshot | Shipped `utils-suggestion-snapshot.json` at MCP build |
+
+---
+
+## 6. Model evaluation matrix (your team fills)
+
+| Model / client | Stdio MCP | HTTP POST `/tool` | Notes |
+|----------------|-----------|-------------------|-------|
+| | ☐ | ☐ | |
+
+**Smoke checklist per row:** `sky_components` (`list`, limit 5) → `get_sky_component_docs` (`surface: props`, `sky-button`) → `get_theme` (`operation: guide`) → `get_theme` (`match_intent`, phrase `brand color`) → `get_theme` (`variables`, `max_names` 50) → `utility_classes` (`check_class`, `p-4`).
+
+---
+
+## 7. Improvement backlog
+
+**Shipped (1.1.0):** Standard **9-tool** surface; `get_theme` guide/fields/field/match_intent/compose/variables; `get_reactivity_layer`; `get_chart_usage`; `utility_classes` snapshot fallback; docs aligned to new surface.
+
+1. Expand golden tests as tools evolve.
+2. Optional: richer component discovery heuristics without re-exposing removed guideline tools.
+
+---
+
+## 8. How to fetch this file via MCP
+
+1. **`get_docs`** with path **`packages/mcp/docs/cross-model-mcp-playbook.md`**
+2. Short session prompt: **`packages/mcp/docs/starter-prompt.md`**
+3. **`crossModelPlaybookPath`** from **`get_theme`** `variables` response → **`get_docs`**
+
+*Last updated: 2026-06 — 9-tool standard surface.*

package/docs/example-site-and-mcp-training.md

@@ -1,82 +1,82 @@
-# Example site (`sky-ui-example`) vs MCP
-
-Use **two layers**:
-
-1. **`get_sky_component_docs`** — canonical **component API** from `@sky.ui/core` (CEM/AST). Names, types, slots, events, methods.
-2. **Example-site enrichment** (internal to the same tool) — bounded HTTPS reads of the published app under **`/api/mcp/`**, or offline **`exampleSiteEmbed`**. Multi-framework snippets (HTML / Sky / Vue / React) and **`sections[].ai`** construction skeletons aligned with `sky-codebox` pages.
-
-Do not treat rendered SPA HTML as ground truth; use the MCP endpoints or repo snippets.
-
----
-
-## Deployed endpoints (sky-ui-example)
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/api/mcp/manifest` | JSON manifest: component ids, titles, `docPath` links. |
-| GET | `/api/mcp/component/{id}` | JSON payload (`schema` `sky-ui-example-mcp/component/5`): `pageAi` routing + `sections[].ai` blueprints. Registry: **`sky-ui-example/server/mcp/component-payload-registry.ts`**. |
-| GET | `/api/mcp/component/{id}?format=markdown` | One markdown file (fenced code per framework). |
-
-`{id}` is kebab-case (e.g. `accordion`). Unknown id → 404.
-
----
-
-## How MCP consumes the example site
-
-Example-site data is merged into **`get_sky_component_docs`** when configured (see **Environment** below).
-
-When **`SKY_UI_EXAMPLE_SITE_BASE_URL`** is set (or the default `https://library.sky-ui.com` is used):
-
-- **`get_sky_component_docs`** may merge live data from **`GET /api/mcp/component/{id}`** (same shapes as the table above).
-- Responses may include **`_skyUiMcp.enrichmentNote`** with `truthLayer: external_optional` — treat as supplementary to CEM/AST.
-
-When the URL is **unset and disabled** (`SKY_UI_EXAMPLE_SITE_DISABLE=1`):
-
-- Optional **`exampleSiteEmbed`** in **`packages/mcp/data/design-guidelines/p0-guidelines.json`** (`manifest` and/or `components` map).
-- Supports **`npx @sky.ui/mcp`** offline without a deployed site.
-
-### Guards (HTTP enrichment)
-
-- Only **GET**; URLs built as `/api/mcp/manifest` or `/api/mcp/component/...`.
-- Host allowlist + path must start with `/api/mcp/`.
-- Body size cap (~600 KB); timeout (~25 s).
-
----
-
-## Required / optional env (MCP host)
-
-| Variable | Required | Notes |
-|----------|----------|-------|
-| **`SKY_UI_EXAMPLE_SITE_BASE_URL`** | No | Origin only, no path. Defaults to `https://library.sky-ui.com` (HeroUI-style). Override for local dev: `http://localhost:3000` |
-| **`SKY_UI_EXAMPLE_SITE_DISABLE`** | No | Set `1` to skip live site fetches (offline-only) |
-| **`SKY_UI_EXAMPLE_SITE_EXTRA_HOSTS`** | No | Comma-separated extra hosts after redirects |
-
-Example Cursor config:
-
-```json
-{
-  "mcpServers": {
-    "sky-ui": {
-      "command": "node",
-      "args": ["packages/mcp/dist/mcp-stdio-entry.js"],
-      "env": {
-        "SKY_UI_EXAMPLE_SITE_BASE_URL": "https://library.sky-ui.com"
-      }
-    }
-  }
-}
-```
-
----
-
-## Agent recipe
-
-**`packages/mcp/docs/agent-recipe-example-site.md`** — checklist for every registered `{id}` (minimal/full paths, adding new builders).
-
----
-
-## Adding a component to the manifest
-
-Step-by-step: **`sky-ui-example/docs/component-docs-mcp-pipeline.md`**.
-
-In **`sky-ui-example`**: add **`server/mcp/builders/<id>.ts`**, register in **`component-payload-registry.ts`**, add **`app/frameworks/<id>.frameworks.ts`**, reuse the same **`frameworks`** arrays on the Vue page.
+# Example site (`sky-ui-example`) vs MCP
+
+Use **two layers**:
+
+1. **`get_sky_component_docs`** — canonical **component API** from `@sky.ui/core` (CEM/AST). Names, types, slots, events, methods.
+2. **Example-site enrichment** (internal to the same tool) — bounded HTTPS reads of the published app under **`/api/mcp/`**, or offline **`exampleSiteEmbed`**. Multi-framework snippets (HTML / Sky / Vue / React) and **`sections[].ai`** construction skeletons aligned with `sky-codebox` pages.
+
+Do not treat rendered SPA HTML as ground truth; use the MCP endpoints or repo snippets.
+
+---
+
+## Deployed endpoints (sky-ui-example)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/mcp/manifest` | JSON manifest: component ids, titles, `docPath` links. |
+| GET | `/api/mcp/component/{id}` | JSON payload (`schema` `sky-ui-example-mcp/component/5`): `pageAi` routing + `sections[].ai` blueprints. Registry: **`sky-ui-example/server/mcp/component-payload-registry.ts`**. |
+| GET | `/api/mcp/component/{id}?format=markdown` | One markdown file (fenced code per framework). |
+
+`{id}` is kebab-case (e.g. `accordion`). Unknown id → 404.
+
+---
+
+## How MCP consumes the example site
+
+Example-site data is merged into **`get_sky_component_docs`** when configured (see **Environment** below).
+
+When **`SKY_UI_EXAMPLE_SITE_BASE_URL`** is set (or the default `https://library.sky-ui.com` is used):
+
+- **`get_sky_component_docs`** may merge live data from **`GET /api/mcp/component/{id}`** (same shapes as the table above).
+- Responses may include **`_skyUiMcp.enrichmentNote`** with `truthLayer: external_optional` — treat as supplementary to CEM/AST.
+
+When the URL is **unset and disabled** (`SKY_UI_EXAMPLE_SITE_DISABLE=1`):
+
+- Optional **`exampleSiteEmbed`** in **`packages/mcp/data/design-guidelines/p0-guidelines.json`** (`manifest` and/or `components` map).
+- Supports **`npx @sky.ui/mcp`** offline without a deployed site.
+
+### Guards (HTTP enrichment)
+
+- Only **GET**; URLs built as `/api/mcp/manifest` or `/api/mcp/component/...`.
+- Host allowlist + path must start with `/api/mcp/`.
+- Body size cap (~600 KB); timeout (~25 s).
+
+---
+
+## Required / optional env (MCP host)
+
+| Variable | Required | Notes |
+|----------|----------|-------|
+| **`SKY_UI_EXAMPLE_SITE_BASE_URL`** | No | Origin only, no path. Defaults to `https://library.sky-ui.com` (HeroUI-style). Override for local dev: `http://localhost:3000` |
+| **`SKY_UI_EXAMPLE_SITE_DISABLE`** | No | Set `1` to skip live site fetches (offline-only) |
+| **`SKY_UI_EXAMPLE_SITE_EXTRA_HOSTS`** | No | Comma-separated extra hosts after redirects |
+
+Example Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "sky-ui": {
+      "command": "node",
+      "args": ["packages/mcp/dist/mcp-stdio-entry.js"],
+      "env": {
+        "SKY_UI_EXAMPLE_SITE_BASE_URL": "https://library.sky-ui.com"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Agent recipe
+
+**`packages/mcp/docs/agent-recipe-example-site.md`** — checklist for every registered `{id}` (minimal/full paths, adding new builders).
+
+---
+
+## Adding a component to the manifest
+
+Step-by-step: **`sky-ui-example/docs/component-docs-mcp-pipeline.md`**.
+
+In **`sky-ui-example`**: add **`server/mcp/builders/<id>.ts`**, register in **`component-payload-registry.ts`**, add **`app/frameworks/<id>.frameworks.ts`**, reuse the same **`frameworks`** arrays on the Vue page.

package/docs/mcp-capability-status.md

@@ -1,51 +1,51 @@
-# MCP Capability Status
-
-Standard **9-tool** surface for `@sky.ui/mcp` (v1.1.x).
-
-## Snapshot
-
-- Scope: component discovery, docs, usage, reactivity, charts, theme authoring, utils classes, allowlisted guides
-- Status: Standard surface shipped; docs and golden tests aligned
-- Strength: predictable routing with smaller default payloads
-
----
-
-## Capability Matrix
-
-| Domain | Tool | Status | Maturity |
-|---|---|---|---|
-| Component discovery | `sky_components` (`list` \| `search` \| `search_by_api`) | Implemented | Stable |
-| Structured docs | `get_sky_component_docs` (`name` \| `names[]`, optional `surface`, deprecations) | Implemented | Stable |
-| Framework usage | `get_component_usage` (`lit` \| `react` \| `vue`) | Implemented | Stable |
-| Setup | `get_project_guide` (`installation` \| `setup`) | Implemented | Stable |
-| Reactivity | `get_reactivity_layer` (`list_topics` \| `get_topic` \| `package`) | Implemented | Stable |
-| Charts | `get_chart_usage` (`list_types` \| `get_type` \| `option_guide`) | Implemented | Stable |
-| Theme authoring | `get_theme` (`guide` \| `fields` \| `field` \| `match_intent` \| `compose` \| `variables`) | Implemented | Stable |
-| Utils classes | `utility_classes` (live engine or shipped snapshot) | Implemented | Stable |
-| Guides | `get_docs` (allowlisted paths) | Implemented | Stable |
-
----
-
-## Supporting data (not MCP tools)
-
-| Data | Used by |
-|------|---------|
-| Example-site payloads | `get_sky_component_docs` enrichment when `SKY_UI_EXAMPLE_SITE_BASE_URL` or `exampleSiteEmbed` is set |
-| `p0-guidelines.json` | Build validation; optional offline embed manifest |
-
----
-
-## Quality Gates
-
-- Build: `npm run build -w @sky.ui/mcp` (parity, guideline refs, banned patterns)
-- Smoke: `npm run test:mcp`
-- Contract golden: `node test/mcp/contract-golden.mjs`
-- Agent defaults: smaller omit-arg limits documented in README
-
----
-
-## Recommended Next Milestones
-
-1. Expand golden coverage for `get_theme` match_intent/compose edge cases
-2. Publish `@sky.ui/mcp@1.1.0` and pin in consumer `.cursor/mcp.json`
-3. Keep example-site embed manifest in sync with sky-ui-example page ids
+# MCP Capability Status
+
+Standard **9-tool** surface for `@sky.ui/mcp` (v1.1.x).
+
+## Snapshot
+
+- Scope: component discovery, docs, usage, reactivity, charts, theme authoring, utils classes, allowlisted guides
+- Status: Standard surface shipped; docs and golden tests aligned
+- Strength: predictable routing with smaller default payloads
+
+---
+
+## Capability Matrix
+
+| Domain | Tool | Status | Maturity |
+|---|---|---|---|
+| Component discovery | `sky_components` (`list` \| `search` \| `search_by_api`) | Implemented | Stable |
+| Structured docs | `get_sky_component_docs` (`name` \| `names[]`, optional `surface`, deprecations) | Implemented | Stable |
+| Framework usage | `get_component_usage` (`lit` \| `react` \| `vue`) | Implemented | Stable |
+| Setup | `get_project_guide` (`installation` \| `setup`) | Implemented | Stable |
+| Reactivity | `get_reactivity_layer` (`list_topics` \| `get_topic` \| `package`) | Implemented | Stable |
+| Charts | `get_chart_usage` (`list_types` \| `get_type` \| `option_guide`) | Implemented | Stable |
+| Theme authoring | `get_theme` (`guide` \| `fields` \| `field` \| `match_intent` \| `compose` \| `variables`) | Implemented | Stable |
+| Utils classes | `utility_classes` (live engine or shipped snapshot) | Implemented | Stable |
+| Guides | `get_docs` (allowlisted paths) | Implemented | Stable |
+
+---
+
+## Supporting data (not MCP tools)
+
+| Data | Used by |
+|------|---------|
+| Example-site payloads | `get_sky_component_docs` enrichment when `SKY_UI_EXAMPLE_SITE_BASE_URL` or `exampleSiteEmbed` is set |
+| `p0-guidelines.json` | Build validation; optional offline embed manifest |
+
+---
+
+## Quality Gates
+
+- Build: `npm run build -w @sky.ui/mcp` (parity, guideline refs, banned patterns)
+- Smoke: `npm run test:mcp`
+- Contract golden: `node test/mcp/contract-golden.mjs`
+- Agent defaults: smaller omit-arg limits documented in README
+
+---
+
+## Recommended Next Milestones
+
+1. Expand golden coverage for `get_theme` match_intent/compose edge cases
+2. Publish `@sky.ui/mcp@1.1.0` and pin in consumer `.cursor/mcp.json`
+3. Keep example-site embed manifest in sync with sky-ui-example page ids

package/docs/mcp-tooling-roadmap.md

@@ -1,36 +1,36 @@
-# MCP tooling roadmap
-
-Complements **`mcp-capability-status.md`**. Follow-ups after the **9-tool standard surface** (`@sky.ui/mcp` 1.1.x).
-
-## Shipped (1.1.x)
-
-- **9 public tools:** `get_project_guide`, `sky_components`, `get_sky_component_docs`, `get_component_usage`, `get_reactivity_layer`, `get_chart_usage`, `get_theme`, `get_docs`, `utility_classes`
-- **`get_theme`:** `guide`, `fields`, `field`, `match_intent`, `compose`, `variables`
-- **Offline snapshots:** `utils-suggestion-snapshot.json`, `reactivity-readme-snapshot.json`, `chart-api-sections.json`
-- **`_skyUiMcp`** metadata + **`--health`** diagnostics
-- Example-site enrichment internal to **`get_sky_component_docs`**
-- Guideline JSON for validation + embed only (`p0-guidelines.json`)
-
-## High priority
-
-| Area | Work |
-|------|------|
-| **Publish 1.1.x** | GitLab registry with `write_package_registry` |
-| **Example-site embed CI** | Snapshot test when embed manifest ids change |
-| **`get_project_guide`** | Optional JSON wrapper with `_skyUiMcp` |
-
-## Medium priority
-
-| Area | Work |
-|------|------|
-| **`utility_classes`** | Optional sandboxed read of user `skyui.config` |
-| **`get_theme` `variables`** | Source hash / extract timestamp in response |
-
-## Lower priority
-
-- HTTP POST bridge: document `_skyUiMcp` in README POST section
-- Optional consolidated design-assist tool (only if product asks)
-
-## Principle
-
-Prefer **`truthLayer` ∈ { `api_source`, `deterministic` }** for normative API answers. Treat **`external_optional`** and **`static_reference`** as supplementary.
+# MCP tooling roadmap
+
+Complements **`mcp-capability-status.md`**. Follow-ups after the **9-tool standard surface** (`@sky.ui/mcp` 1.1.x).
+
+## Shipped (1.1.x)
+
+- **9 public tools:** `get_project_guide`, `sky_components`, `get_sky_component_docs`, `get_component_usage`, `get_reactivity_layer`, `get_chart_usage`, `get_theme`, `get_docs`, `utility_classes`
+- **`get_theme`:** `guide`, `fields`, `field`, `match_intent`, `compose`, `variables`
+- **Offline snapshots:** `utils-suggestion-snapshot.json`, `reactivity-readme-snapshot.json`, `chart-api-sections.json`
+- **`_skyUiMcp`** metadata + **`--health`** diagnostics
+- Example-site enrichment internal to **`get_sky_component_docs`**
+- Guideline JSON for validation + embed only (`p0-guidelines.json`)
+
+## High priority
+
+| Area | Work |
+|------|------|
+| **Publish 1.1.x** | GitLab registry with `write_package_registry` |
+| **Example-site embed CI** | Snapshot test when embed manifest ids change |
+| **`get_project_guide`** | Optional JSON wrapper with `_skyUiMcp` |
+
+## Medium priority
+
+| Area | Work |
+|------|------|
+| **`utility_classes`** | Optional sandboxed read of user `skyui.config` |
+| **`get_theme` `variables`** | Source hash / extract timestamp in response |
+
+## Lower priority
+
+- HTTP POST bridge: document `_skyUiMcp` in README POST section
+- Optional consolidated design-assist tool (only if product asks)
+
+## Principle
+
+Prefer **`truthLayer` ∈ { `api_source`, `deterministic` }** for normative API answers. Treat **`external_optional`** and **`static_reference`** as supplementary.