@adia-ai/adia-ui-factory 0.2.4 → 0.8.0

package/skills/adia-ui-kit/references/mcp.md

@@ -1,401 +0,0 @@
-# §MCP — Installing the AdiaUI MCP server
-
-> **Loading note.** Reference bundle extracted from `SKILL.md` per the
-> §LoadingProtocol inversion contract (v2.20.0+). Load via
-> `skill_view(name='adia-ui-kit', file_path='references/mcp.md')` when
-> you need to install/configure the AdiaUI MCP server for an agent IDE
-> (Claude Desktop / Claude Code / Cursor / Windsurf). Skip if you're
-> not setting up generative-UI tooling.
-
-The AdiaUI MCP server (`@adia-ai/a2ui-mcp`) exposes 30 tools (v0.6.7+) for UI
-generation, component discovery, validation, and corpus feedback to any
-MCP-capable host: Claude Desktop, Claude Code, Cursor, Windsurf, and
-any other client that speaks the stdio MCP protocol.
-
-**This section is for wiring the MCP server into your AI client.**
-For composing UI using the tools once connected, see `adia-ui-a2ui`.
-
----
-
-### 1. Install the package
-
-```bash
-# Global — exposes the `adiaui-mcp` CLI bin
-npm install -g @adia-ai/a2ui-mcp
-
-# Local — invoke via npx (no global install needed)
-npm install @adia-ai/a2ui-mcp
-
-# Verify it works
-npx adiaui-mcp --version     # or: adiaui-mcp --version (if global)
-```
-
----
-
-### 2. Set API keys
-
-At least one LLM provider key is required for `generate_ui`. Set these
-before starting the server:
-
-```bash
-# Required — at least one
-export ANTHROPIC_API_KEY=sk-ant-…
-export OPENAI_API_KEY=sk-…
-export GEMINI_API_KEY=AIza…
-
-# Or add to a .env file in your project root
-echo "ANTHROPIC_API_KEY=sk-ant-…" >> .env
-```
-
-The server reads `.env` at startup via `scripts/load-env.mjs`.
-Keys cannot be changed while the server is running — restart to pick
-up new values.
-
----
-
-### 3. Configure your MCP host
-
-#### Claude Desktop
-
-Config file location:
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "npx",
-      "args": ["@adia-ai/a2ui-mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-…",
-        "OPENAI_API_KEY": "sk-…"
-      }
-    }
-  }
-}
-```
-
-Or with a global install:
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "adiaui-mcp",
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-…"
-      }
-    }
-  }
-}
-```
-
-Restart Claude Desktop after editing this file.
-
-#### Claude Code (CLI)
-
-Register in `.claude/settings.json` at your project root:
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "npx",
-      "args": ["@adia-ai/a2ui-mcp"]
-    }
-  }
-}
-```
-
-Or from a local checkout:
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "node",
-      "args": ["packages/a2ui/mcp/server.js"]
-    }
-  }
-}
-```
-
-#### Cursor
-
-Config file: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-local).
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "npx",
-      "args": ["@adia-ai/a2ui-mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-…"
-      }
-    }
-  }
-}
-```
-
-#### Windsurf
-
-Config file: `~/.codeium/windsurf/mcp_config.json`
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "npx",
-      "args": ["@adia-ai/a2ui-mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-…"
-      }
-    }
-  }
-}
-```
-
-#### Generic MCP host (any stdio-compatible client)
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "npx",
-      "args": ["@adia-ai/a2ui-mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "sk-ant-…"
-      }
-    }
-  }
-}
-```
-
-The server speaks the MCP stdio transport — `command` + `args` is all
-any compliant host needs. Adjust the key name (`adia-ui`) to whatever
-your host uses for tool namespacing.
-
----
-
-### 4. Verify the connection
-
-Once configured and restarted, ask your AI client:
-
-> "What AdiaUI tools are available?"
-
-A connected server will list 30 tools (v0.6.7+). If it doesn't respond, check:
-
-1. `npx @adia-ai/a2ui-mcp` runs without error in a terminal
-2. API key environment variable is set and exported
-3. The config file is valid JSON (no trailing commas)
-4. Claude Desktop / Cursor / Windsurf was fully restarted after editing config
-
----
-
-### 5. Core tools for UI generation
-
-| Tool | What it does | When to use |
-|---|---|---|
-| `generate_ui` | Intent → A2UI messages + HTML | Primary generation tool |
-| `lookup_component` | Look up a component's API by name | Before composing to verify props/slots |
-| `get_component_map` | Full catalog of all 96 components | Discover what exists |
-| `search_chunks` | Search the pre-authored chunk corpus | Find patterns matching an intent |
-| `validate_schema` | Validate A2UI JSON against the schema | After generating, before rendering |
-| `check_anti_patterns` | Scan rendered HTML for anti-patterns | Quality gate |
-| `convert_html` | Convert existing HTML to A2UI JSON | Migrating existing markup |
-| `classify_intent` | Detect the UI domain from a prompt | Debugging generation routing |
-
-**New in v0.6.7:**
-
-| Tool | What it does | When to use |
-|---|---|---|
-| `list_patterns` | Enumerate the corpus with optional `domain`/`category` filter | Browse, not search |
-| `refine_ui` | Re-run monolithic generation with validation errors fed back to the LLM | After `validate_schema` fails |
-| `server_status` | Report transport + sampling + corpus stats + version | Health check / observability |
-
-**`generate_ui` parameters:**
-
-```json
-{
-  "intent":    "A login page with email and password",
-  "engine":    "monolithic",
-  "mode":      "pro",
-  "sessionId": "optional — for multi-turn zettel refinement"
-}
-```
-
-- `engine`: `"monolithic"` (default, pattern-match + LLM adapt) or `"zettel"` (fragment-graph composer)
-- `mode`: `"pro"` (default, LLM + pattern), `"thinking"` (deep LLM), `"instant"` (fast pattern-only, no LLM)
-- `sessionId`: pass the same ID across calls to mutate a prior canvas (zettel multi-turn only)
-
----
-
-### 6. Gotchas
-
-- **Corpus load is noisy.** The zettel engine prints corpus stats to
-  stderr on first invocation. Some MCP clients surface this as a warning;
-  it's normal.
-- **Keys must be set before server start.** Changing env vars after
-  startup doesn't hot-reload — restart the server.
-- **Multi-turn state is in-memory.** Restarting the server drops all
-  `sessionId` chains. Pass `currentCanvas` on resume if you need
-  continuity across restarts.
-- **Score < 70 is still returned.** `generate_ui` doesn't auto-retry.
-  Check the `passed` boolean or `score` field in the response and
-  call `validate_schema` + `check_anti_patterns` to triage failures.
-- **`adiaui-mcp` binary requires Node 22+.** The server uses
-  `import.meta.glob` and top-level await. Verify with `node --version`.
-
----
-
-### 7. Using the MCP tools inside a coding agent (Claude Code, Cursor, Hermes)
-
-**The short answer:** register the local `server.js` once in your agent's
-MCP config. Most tools work with zero API keys. Only `generate_ui` in
-`pro` or `thinking` mode needs one — `instant` mode and all discovery/
-validation tools work immediately with nothing.
-
-#### Step 1 — Register the server (one-time, no npm install)
-
-Add to `.claude/settings.json` (Claude Code), `.cursor/mcp.json`
-(Cursor), or your host's equivalent:
-
-```json
-{
-  "mcpServers": {
-    "adia-ui": {
-      "command": "node",
-      "args": ["packages/a2ui/mcp/server.js"]
-    }
-  }
-}
-```
-
-Restart the agent after saving. The server starts on demand — no
-background process to manage.
-
-#### Step 2 — Verify (ask the agent)
-
-> "List the available AdiaUI MCP tools."
-
-You should see 30 tools (v0.6.7+). If not, run `node packages/a2ui/mcp/server.js`
-in a terminal and check for startup errors.
-
-#### Step 3 — Use the tools natively
-
-The agent calls these directly as tool invocations — no curl, no HTTP,
-no scripts. The same way it calls any other MCP tool.
-
-**All of these work with zero API keys:**
-
-```
-lookup_component("table-ui")
-  → full prop/slot/event API from the yaml
-
-get_component_map()
-  → complete 95-component catalog
-
-search_chunks("login form email password")
-  → pre-authored chunk patterns matching the intent
-
-validate_schema(messages)
-  → { passed: true, score: 91, violations: [] }
-
-check_anti_patterns(html)
-  → [] (clean) or [{ rule, location, fix }]
-
-convert_html(html)
-  → A2UI JSON equivalent of existing markup
-
-classify_intent("settings page with billing section")
-  → { domain: "settings", confidence: 0.94 }
-
-get_traits("button-ui")
-  → pressable, focusable, ...
-
-get_wiring_catalog()
-  → available controller + handler bindings
-```
-
-**`generate_ui` with `mode: "instant"` — also zero API keys:**
-
-```
-generate_ui(intent: "login form with email and password", mode: "instant")
-  → A2UI JSON + HTML from 96+ corpus pattern match
-  → < 200ms, deterministic, no tokens spent
-```
-
-Use `instant` for scaffolding and exploration. Good enough for most
-structural questions; lower quality than LLM modes on novel intents.
-
-**`generate_ui` with `mode: "pro"` or `"thinking"` — currently needs its own key**
-
-> **stdio mode (local IDE):** `generate_ui` uses the host's LLM automatically
-> via MCP `sampling/createMessage` — no API key needed. The server sends
-> messages to Claude Code / Cursor / Hermes and they run inference with
-> their own model and return the result. Same model, same token budget,
-> zero credentials to manage.
->
-> **HTTP mode (deployed service):** no sampling-capable host is present,
-> so API keys in `.env` are required. Add at least one:
-
-```bash
-ANTHROPIC_API_KEY=sk-ant-…   # auto-detected first
-OPENAI_API_KEY=sk-…          # fallback
-GEMINI_API_KEY=AIza…         # fallback
-LLM_PROVIDER=anthropic       # optional — pin provider explicitly
-LLM_MODEL=claude-haiku-4-5-20251001  # optional — pin model
-```
-
-The server reads `.env` at startup. If no key is found, `pro` mode
-silently falls back to `instant`.
-
-#### How an agent uses these in practice
-
-```
-User: "Build an admin claims UI."
-
-Agent calls:
-  1. search_chunks("claims management admin table")
-     → finds: claims-list-table, claim-status-badge, claim-detail-drawer
-
-  2. lookup_component("table-ui")
-     → confirms: .columns and .data set via JS, always pair with table-toolbar-ui
-
-  3. generate_ui("claims list with status filter and detail drawer", mode: "instant")
-     → scaffold HTML + A2UI JSON
-
-  4. validate_schema(result.messages)
-     → { passed: true, score: 88 }
-
-  5. check_anti_patterns(result.html)
-     → [] — no violations
-
-Agent writes the output files.
-```
-
-No manual HTTP calls. No curl. The agent just uses the tools.
-
-#### If MCP registration isn't possible — HTTP fallback
-
-If your agent can make HTTP requests but can't use MCP tools directly:
-
-```bash
-npm run proxy   # starts packages/llm/server.js on :3456
-
-curl -X POST http://localhost:3456/api/generate \
-  -H "Content-Type: application/json" \
-  -d '{ "intent": "login form", "mode": "instant" }'
-# → { messages: [...], validation: { score, passed }, elapsedMs }
-```
-
-#### Quick-reference — what needs what
-
-| | Needs API key? | Needs server? |
-|---|---|---|
-| `lookup_component`, `get_component_map`, `search_chunks`, `validate_schema`, `check_anti_patterns`, `convert_html`, `classify_intent`, `get_traits`, `get_wiring_catalog` | No | Yes — `node packages/a2ui/mcp/server.js` |
-| `generate_ui mode: instant` | No | Yes — same |
-| `generate_ui mode: pro` / `thinking` | stdio: No (uses host LLM via sampling). HTTP: Yes — `.env` | Yes — same |
-| Via npm package / Claude Desktop | Yes — `env:` in config | No — `npx` starts it |

package/skills/adia-ui-kit/references/migration.md

@@ -1,116 +0,0 @@
----
-name: migration
-load-when: Migrating existing code: @agent-ui-kit to @adia-ai/* namespace rename, v0.4.x retired ADR-0024 shapes, between @adia-ai/* versions
-load-size-tokens: ~1,500
-required-for:
-  - version upgrades
-  - namespace migrations
-  - retired-shape sweeps
----
-
-# §Migration — Bringing existing code current
-
-If you're inheriting a codebase that pre-dates the current
-`@adia-ai/*@^0.6.0` lockstep, **migrate before adding features.** Don't
-mix new component vocabulary into a tree that still has retired legacy
-shapes — you'll re-rewrite later, the legacy shapes don't render, and
-sweep tools can't tell the new code apart from author error.
-
-### Canonical sources (do not duplicate — route to these)
-
-This section is a **routing layer**. The mechanics live elsewhere:
-
-| Source                                                 | What it gives you                                                                   |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `.claude/docs/MIGRATION GUIDE.md` (note the space in the path) | Version-by-version BREAKING items, code diffs, search-and-replace recipes           |
-| `adia-ui-migration` skill (in `.agents/skills/`)       | Mechanical sweep automation — grep audits, perl rewrites, verification gate calls   |
-| `.brain/adrs/0024-legacy-shell-shapes-retired.md`      | The contract decision retiring legacy shell shapes in `0.4.0` (rationale + scope)   |
-| Per-package CHANGELOGs                                 | Patch-level detail not in the consolidated guide                                    |
-
-**LLM directive:** When the user asks "migrate from X to Y" / "upgrade to
-v0.Y.Z" / "what changed in v0.Y" / "we're on @agent-ui-kit and want to
-move", **do not paste migration commands inline from memory.** Read
-`.claude/docs/MIGRATION GUIDE.md` for the target version section, then invoke the
-`adia-ui-migration` skill for the mechanical sweep. This skill names the
-breaking-change surface (so the user knows what they're in for); it does
-not own the sweep recipes.
-
-### Migration surface (what you're in for, by source)
-
-**From `@agent-ui-kit/*` (predecessor namespace):**
-
-- Package rename: `@agent-ui-kit/web-components` → `@adia-ai/*`
-  9-package monorepo (`web-components`, `web-modules`, `llm`,
-  `a2ui-runtime`, `a2ui-compose`, `a2ui-corpus`, `a2ui-mcp`,
-  `a2ui-retrieval`, `a2ui-validator` — all in lockstep at `^0.6.0`).
-- Base class: `AgentElement` / `AdiaElement` → `UIElement`.
-- Design tokens: `--agent-*` → `--a-*` prefix.
-- CSS import path: `@agent-ui-kit/web-components/dist/agent-ui.css` →
-  `@adia-ai/web-components/css`.
-- Trait subpath: `@agent-ui-kit/web-components/traits` → registered
-  automatically via the barrel import (no separate import needed).
-
-**From older `@adia-ai/*` versions — the two largest breaks:**
-
-- **`0.0.20`** — Safari floor raise, deprecated alias removal (`variant="danger"`
-  was `variant="error"`), Phase 6 contract decisions. Most comprehensive
-  break in the `0.0.x` line.
-- **`0.4.0`** — Legacy shell authoring shapes RETIRED across all 3 shell
-  hosts (admin / chat / editor). Consumers MUST use the bespoke
-  `<admin-shell>` / `<chat-shell>` / `<editor-shell>` vocabulary
-  established by ADR-0023 in `0.3.4`–`0.3.6`. Closes the ADR-0023 arc;
-  per ADR-0024.
-
-**Smaller version-cut breaks (`0.6.x` line):**
-
-- `0.6.0` — `stat-ui.{js,css}` filename rename to `stat.{js,css}`
-  (deep-importers only).
-- `0.6.1` — `<link-ui>` token rename `--link-color-*` → `--link-fg-*`.
-
-**Breaks on the `0.7.x` line:**
-
-- `0.7.12` — **token-theme attribute renamed `data-theme` → `theme`** (BREAKING,
-  pre-1.0 PATCH cadence). `<html data-theme="ocean">` → `<html theme="ocean">`;
-  `[data-theme="…"]` selectors → `[theme="…"]`. Compound attrs (`data-theme-slug`,
-  `data-themed`, …) are untouched — sweep `data-theme` on a **word boundary**.
-  Converges with `<canvas-ui theme="…">` and the new `<theme-provider theme="…">`.
-
-**Additive cuts that need no migration** (drop-in upgrades):
-`0.0.5`–`0.0.11`, `0.0.12`–`0.0.19`, `0.0.21`, `0.3.0`–`0.3.6`,
-`0.5.0`–`0.5.21`, `0.6.2`–`0.6.7`. See the version table at the top of
-`MIGRATION GUIDE.md` for the full per-version classification.
-
-### Workflow (when the user invokes migration)
-
-1. **Identify source and target versions.** Ask if not obvious:
-   "What version is the codebase on? (Check `package.json` for
-   `@adia-ai/*` or `@agent-ui-kit/*` ranges.) What target version do you
-   want?"
-2. **Read `.claude/docs/MIGRATION GUIDE.md`** for the target version section
-   (or merged span if the consumer is jumping multiple versions).
-   Re-state the breaking surface in your own words so the user can
-   confirm scope.
-3. **Hand off to the `adia-ui-migration` skill** for the mechanical
-   sweep. That skill owns the grep audits, perl rewrites, and the
-   post-sweep verification gate. Don't re-implement it here.
-4. **Verify in your app** — re-render the migrated screens and confirm they
-   mount + behave (a browser smoke against your dev server, or a manual pass).
-   Migration isn't done until *your* app renders clean. (`components.mjs
-   --verify` / `verify:traits` are the framework's *producer* gates — not
-   consumer commands.)
-5. **Then proceed to §0** for new feature work on the now-current tree.
-
-### Anti-patterns
-
-- ❌ Pasting migration commands from memory without reading the guide
-  (versions drift; the guide is the source of truth).
-- ❌ Adding new feature work to a codebase that still has retired legacy
-  shell shapes — the new code mixes with broken old code, sweep tools
-  can't tell them apart, and you'll re-rewrite later.
-- ❌ Mixing source versions in `package.json` (`@adia-ai/web-components@^0.5.0`
-  + `@adia-ai/web-modules@^0.6.0`) — the 9-package lockstep is normative,
-  cross-major drift breaks A2UI surface contracts.
-- ❌ Skipping the verification gate and shipping. The gate catches
-  half-applied sweeps (e.g. CSS migrated but markup not, or vice versa).
-
----