@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

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

@@ -0,0 +1,401 @@
+# §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

@@ -0,0 +1,116 @@
+---
+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                                                                   |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `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
+`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 `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).
+
+---