@sky.ui/mcp 0.0.1

package/docs/agent-recipe-example-site.md

@@ -0,0 +1,91 @@
+# Agent recipe — Example site (`sky-ui-example` / `/api/mcp`)
+
+Unified workflow for **every** component doc page registered in **`COMPONENT_EXAMPLE_PAYLOAD_BUILDERS`** (`sky-ui-example/server/mcp/component-payload-registry.ts`).
+
+**MCP surface (v1.1+):** Example-site matrices are **not** a separate tool. They merge into **`get_sky_component_docs`** when **`SKY_UI_EXAMPLE_SITE_BASE_URL`** is set or **`exampleSiteEmbed`** is shipped in `p0-guidelines.json`.
+
+---
+
+## 1. Authority split (all components)
+
+| Need | Source |
+|------|--------|
+| Props, events, slots, methods, types | **`get_sky_component_docs`** (optional **`surface`**, **`include_deprecations`**) |
+| Lit / React / Vue snippets | **`get_component_usage`** |
+| Runnable matrices + `pageAi` routing + `sections[].ai` skeleton | **`get_sky_component_docs`** enrichment → live `GET /api/mcp/component/{id}` or offline **`exampleSiteEmbed`** |
+| Theme / `userTheme` | **`get_theme`** (`guide` → `fields` / `field` / `match_intent` / `compose`) |
+| Layout CSS classes | **`utility_classes`** + **`get_docs`** `utils-usage-guide.md` |
+
+Payload shape (example site): top-level **`schema`** (e.g. `sky-ui-example-mcp/component/5`), **`pageAi.schema`** = `sky-ui-example/page-routing/1`, **`sections[].ai`** = structural blueprint.
+
+**Interaction hints (optional, since `component/5`):** `pageAi.customEvents`, `pageAi.publicMethods`, and per-section `*InPlay` fields are routing aids — always confirm with **`get_sky_component_docs`**.
+
+---
+
+## 2. Minimal path (any `{id}` — low tokens)
+
+1. **`get_sky_component_docs`** for the primary tag(s) in **`pageAi.guidelinesComponents`** (or the obvious root component).
+2. If the response includes **`exampleSiteEmbed`** / enriched sections, use **`sections[].ai`** + one **`frameworks[]`** block for the user’s stack.
+3. Otherwise **`get_component_usage`** for a paste-ready starter, then refine from docs surfaces.
+
+Never invent `sky-*` tags, slot names, or `--sky-*` tokens.
+
+---
+
+## 3. Full path (production UX)
+
+After §2:
+
+- **`get_sky_component_docs`** with **`names[]`** when multiple related tags matter
+- **`get_component_usage`** (`lit` \| `react` \| `vue`) + split **`surface`** calls as needed
+- **`get_docs`** → `packages/mcp/docs/vue-wrapper-v-model.md` for Vue two-way binding patterns
+- Re-read **`pageAi.mcpToolChain`** inside enriched JSON when present (pages may customize ordering)
+
+---
+
+## 4. Adding a new component page (checklist)
+
+**Authoring playbook (Vue page, `sky-title`, `setSection`, `sky-doctable`):** **`sky-ui-example/docs/component-docs-mcp-pipeline.md`**.
+
+**In `sky-ui-example` (summary):**
+
+1. Add **`app/frameworks/<id>.frameworks.ts`** — `FrameworkSnippet[]` + `*ExampleRouting` via **`createExamplePageRouting`**.
+2. Add **`server/mcp/builders/<id>.ts`** — `buildXxxExamplePayload(): McpComponentExamplePayload`, or run **`npm run gen:mcp-builders`**.
+3. Register in **`server/mcp/component-payload-registry.ts`**.
+4. Wire the Vue page `sky-codebox` `:frameworks` to the same snippet arrays.
+
+Shared types: **`app/frameworks/mcp-example.schema.ts`**, **`app/frameworks/mcp-example.defaults.ts`**.
+
+---
+
+## 5. Environment (MCP server)
+
+| Variable | Purpose |
+|----------|---------|
+| **`SKY_UI_EXAMPLE_SITE_BASE_URL`** | Origin only (e.g. `https://library.sky-ui.com`). Enables HTTP enrichment in **`get_sky_component_docs`**. |
+| **`SKY_UI_EXAMPLE_SITE_EXTRA_HOSTS`** | Optional redirect allowlist (HTTP mode). |
+| *(unset)* | Falls back to optional **`exampleSiteEmbed`** in **`packages/mcp/data/design-guidelines/p0-guidelines.json`**. |
+
+Set these on the **machine running MCP** (e.g. Cursor `.cursor/mcp.json` → `env`).
+
+---
+
+## 6. Direct HTTP (humans / scripts)
+
+When not using MCP:
+
+| Method | Path |
+|--------|------|
+| GET | `/api/mcp/manifest` |
+| GET | `/api/mcp/component/{id}` |
+| GET | `/api/mcp/component/{id}?format=markdown` |
+
+`{id}` is kebab-case (e.g. `accordion`).
+
+---
+
+## 7. Related `get_docs` files
+
+- **`packages/mcp/docs/example-site-and-mcp-training.md`**
+- **`packages/mcp/docs/cross-model-mcp-playbook.md`**
+- **`packages/mcp/docs/starter-prompt.md`**

package/docs/ai-design-mcp-blueprint.md

@@ -0,0 +1,75 @@
+# AI-Ready Design MCP Blueprint
+
+> **Status (2026):** Research blueprint for design-assistant capabilities. The **published MCP surface** is the **9-tool standard** (see `mcp-capability-status.md`). Guideline JSON and embed data stay in-repo for validation and example-site enrichment.
+
+**Goal:** evolve `@sky.ui/mcp` from metadata retrieval into a **design decision engine** that can answer: what to use, why, when **not** to use it, and how to compose accessible UI.
+
+---
+
+## Current public MCP mapping (9 tools)
+
+| Blueprint domain | Use today |
+|------------------|-----------|
+| Component API, methods, deprecations | **`get_sky_component_docs`** (+ optional `surface`, `include_deprecations`) |
+| Discovery / search | **`sky_components`** (`list`, `search`, `search_by_api`) |
+| Framework usage | **`get_component_usage`** |
+| Theme / tokens | **`get_theme`** (`guide`, `fields`, `field`, `match_intent`, `compose`, `variables`) |
+| Utils / layout | **`utility_classes`** + **`get_docs`** `utils-usage-guide.md` |
+| Charts | **`get_chart_usage`** + **`get_sky_component_docs`** (`sky-chart`) |
+| Reactivity | **`get_reactivity_layer`** |
+| Install / bundler | **`get_project_guide`** |
+| Prose guides | **`get_docs`** (allowlisted paths) |
+| Example-site matrices | **`get_sky_component_docs`** enrichment when URL/embed configured |
+| Blueprint domains (routing, patterns, a11y matrices) | Assistant reasoning + component docs; guideline JSON is data-only |
+
+---
+
+## Why the blueprint still matters
+
+| Gap | Blueprint target | Current mitigation |
+|-----|------------------|-------------------|
+| Selection logic | Use-case recommendation with trade-offs | **`sky_components`** search + assistant reasoning; guideline data internal |
+| Composition recipes | Pattern-level component trees | Example-site **`sections[].ai`** via doc enrichment |
+| State / variant intelligence | State matrices | **`get_sky_component_docs`** props/events; prose in component pages |
+| Token semantics | Intent-based mapping | **`get_theme`** `match_intent` + `compose` |
+| A11y design | Pattern checklists | Component docs + human review; guideline JSON for future tools |
+
+---
+
+## Data contract (in-repo, versioned)
+
+| Entity | Location |
+|--------|----------|
+| **ComponentGuideline** | `packages/mcp/data/design-guidelines/p0-guidelines.json` |
+| **Theme authoring** | `packages/mcp/data/theme-authoring-contract.json` |
+| **Chart API sections** | `packages/mcp/data/chart-api-sections.json` |
+| **Utils catalog snapshot** | `packages/mcp/data/utils-suggestion-snapshot.json` |
+| **Reactivity README snapshot** | `packages/mcp/data/reactivity-readme-snapshot.json` |
+
+Build validates: schema, component refs, banned patterns, tool parity (`verify-mcp-tool-parity.mjs`).
+
+---
+
+## Future phases (optional re-expansion)
+
+If product needs dedicated design-assistant tools again, prefer **one** consolidated tool (e.g. `design_assist`) rather than re-adding 10+ overlapping names. Until then:
+
+| Phase | Outcome |
+|-------|---------|
+| **Phase 1** | ✅ Standard 9-tool surface + theme intent routing |
+| **Phase 2** | Richer embed manifests; CI for example-site parity |
+| **Phase 3** | Optional a11y/contrast helpers behind new tool(s) |
+| **Phase 4** | Design lint / review with golden tests |
+
+---
+
+## Anti-rework guardrails
+
+1. **Stable schemas** with `schemaVersion` on shipped JSON.
+2. **Golden tests** (`test/mcp/run-mcp-test.mjs`, `contract-golden.mjs`).
+3. **Additive evolution** — new fields over breaking response changes.
+4. **Single tool parity check** on every `@sky.ui/mcp` build.
+
+---
+
+*Document version: 1.1 — aligned with 9-tool standard surface; blueprint domains mapped to current tools.*

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

@@ -0,0 +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.*

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

@@ -0,0 +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.

package/docs/mcp-capability-status.md

@@ -0,0 +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

package/docs/mcp-tooling-roadmap.md

@@ -0,0 +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.

package/docs/sky-chart-option-api.md

@@ -0,0 +1,47 @@
+# sky-chart — option API for AI assistants
+
+Use this when the user needs **charts, dashboards, or ECharts-shaped configuration** on **`sky-chart`**. It complements **`get_sky_component_docs`** and **`get_chart_usage`**.
+
+## Tool order
+
+1. **`get_sky_component_docs`** with **`name: "sky-chart"`** (optional **`surface`**) for props, events, slots.
+2. **`get_chart_usage`** — **`list_types`**, then **`get_type`** with **`chart_type`**, or **`option_guide`** for the compact mental model.
+3. **`get_docs`** with **`packages/mcp/docs/sky-chart-option-api.md`** (this file) when you need prose without calling MCP again.
+4. Example-site snippet matrices (when configured) arrive via **`get_sky_component_docs`** enrichment—not a separate tool.
+
+## Mental model
+
+| Input | Role |
+|--------|------|
+| **`type`** | Selects which **lazy-loaded renderer** runs (`bar`, `line`, `pie`, `map`, `radar`, `sankey`, `brush`, …). Must match the chart family you are building. |
+| **`option`** | **Root chart configuration**: ECharts-style field names (`series`, `xAxis`, `tooltip`, …). The host merges theme and layout; renderers read the subset they need. |
+| **`theme`** (attribute) | `light` \| `dark` \| `""`. Empty string follows the active **`sky-theme-provider`**. |
+| **`option.theme`** | Optional **named palette** inside the option object (host may merge backgrounds / colors). |
+
+**`type="brush"`** is a **range UI** (overview + detail). Use host **`start`** / **`end`** (0–100). Linked charts get their own **`option`** and usual **`type`** values.
+
+## Root **`option`** shape (authoritative summary)
+
+The shipped TypeScript root interface is **`EChartsOption`** in the Sky UI repo file **`components-raw/sky-chart/echarts-option.ts`**. Its **top-level keys** include:
+
+- **`series`** (required in the type model; each entry has **`type`** for that series, e.g. `bar`, `line`, `pie`, `map`, …).
+- **`xAxis`**, **`yAxis`**, **`grid`**, **`polar`**, **`angleAxis`**, **`radiusAxis`**, **`radar`**, **`geo`**, **`parallel`**, **`parallelAxis`**, **`calendar`** — coordinate and layout systems as needed.
+- **`dataset`** (and optional **transform**, e.g. boxplot).
+- **`tooltip`**, **`legend`**, **`axisPointer`**, **`dataZoom`**, **`visualMap`**, **`brush`**, **`timeline`** / **`options`** (multi-step timelines).
+- **`color`**, **`backgroundColor`**, **`decal`**, **`graphic`**, **`fisheye`**, **`animation`** / **`animationDuration`** / related fields — presentation and motion.
+
+Fields not listed in **`echarts-option.ts`** may still work when they match **Apache ECharts option** naming for features Sky has wired through; treat **extra fields** as **best-effort** unless confirmed in source or examples.
+
+## Accuracy rules
+
+1. **Prefer `get_sky_component_docs("sky-chart")`** over guessing tags or prop names.
+2. **`type`** on the **custom element** picks the **primary renderer**; keep **`option.series`** consistent with that mode (avoid declaring an unsupported primary renderer).
+3. **`option` is data**, not HTML: validate **untrusted** JSON before assigning (same risk class as remote config).
+4. For **a11y**, pair charts with **text, tables, or live regions** when exact values matter; confirm keyboard/focus behavior from **`get_sky_component_docs`** events and slots.
+
+## Repo paths (for humans / monorepo clones)
+
+- **Root option type:** `components-raw/sky-chart/echarts-option.ts` — interface **`EChartsOption`**.
+- **Renderer registry:** `components-raw/sky-chart/renderer/index.ts` — **`SkyChartType`** keys and lazy imports.
+
+Published installs may not ship **`components-raw/`**; use **`get_sky_component_docs`** and this doc from **@sky.ui/mcp** instead.

package/docs/starter-prompt.md

@@ -0,0 +1,17 @@
+# Sky UI — starter prompt for assistants
+
+Paste this at the start of a session when building with Sky UI (Cursor, Claude, Copilot, etc.).
+
+```
+You are helping build UI with Sky UI (@sky.ui/core web components, optional @sky.ui/react / @sky.ui/vue wrappers, @sky.ui/utils for layout CSS, @sky.ui/reactivity when needed).
+
+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 with packages/mcp/docs/utils-usage-guide.md for setup; utility_classes (variant_prefixes, search_classes, check_class) to discover and validate class names; align 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) for install/bundler (2) get_sky_component_docs with optional surface (3) get_component_usage for lit/react/vue (4) get_reactivity_layer for @sky.ui/reactivity topics (5) get_chart_usage for sky-chart types and option guide (6) theme: get_theme operation guide then fields/field (7) layout/styling: utility_classes + get_docs utils-usage-guide. For sky-chart props/events, get_sky_component_docs(name: sky-chart).
+
+When citing MCP JSON, respect `_skyUiMcp.truthLayer` and `_skyUiMcp.agentMust` — do not treat guideline_scoring or heuristic_search as guaranteed API contracts.
+
+If a tool returns code starting with JSON parse errors or empty arrays, say what is missing (e.g. `@sky.ui/core` not installed/built) and retry after suggesting the user fix the environment.
+```