@wootsup/mcp 0.1.0 → 0.3.0

package/docs/tools.md

@@ -1,24 +1,29 @@
 # Tools reference
 
-Auto-extracted from `src/modules/apimapper/*.ts` on **2026-05-18**.
+Auto-extracted from `src/modules/apimapper/*.ts` on **2026-06-03**.
 
 To regenerate after adding tools, run:
 
 ```bash
 cd packages/apimapper-mcp
-node scripts/extract-tools.mjs
+npm run build                              # ensure dist/ is fresh
+node scripts/extract-tool-descriptions.mjs # writes .grounding/tools-truth.json + a markdown table on stdout
 ```
 
-…and paste the `---MD---` output into the sections below. (The
-extractor is intentionally simple; a fully auto-generated build-step
-is tracked as a future improvement.)
+…and reconcile the sections below against the table. (The extractor
+boots a real `McpServer` and reads each tool's evaluated description —
+no source-text scraping. A fully auto-generated build-step is tracked
+as a future improvement.)
 
 ## Summary
 
-- **Total tools:** 77 registered (+ a few system surfaces brought in
+- **Total tools:** 79 registered (+ a few system surfaces brought in
   via `@getimo/mcp-toolkit`).
-- **Annotation breakdown:** 43 `readOnly`, 15 `mutating`, 10 `creating`,
-  6 `destructive`.
+- **Surface split:** 19 first-class in `tools/list` (15 module
+  essentials + the `apimapper_advanced` gateway + 3 top-level tools
+  registered in `index.ts`); the other 60 route through
+  `apimapper_advanced` so the listed surface stays under each client's
+  tool cap.
 
 The annotation tells the AI client what kind of side-effect each tool
 has. Destructive tools additionally require a `confirm: true`
@@ -30,7 +35,7 @@ vault) for the full convention.
 
 | Module | Tools | Notes |
 |---|---:|---|
-| `connections.ts` | 11 | CRUD + probe + sample-data + resources |
+| `connections.ts` | 12 | CRUD + probe + sample-data + resources + recover |
 | `flows.ts` | 11 | CRUD + compile + import/export + trace |
 | `library.ts` | 9 | Catalog + activate / deactivate templates |
 | `credentials.ts` | 7 | CRUD + link + OAuth begin |
@@ -42,11 +47,14 @@ vault) for the full convention.
 | `graph.ts` | 2 | Preview + validate |
 | `cache.ts` | 2 | Stats + invalidate |
 | `schema.ts` | 2 | Profile + snapshot list |
+| `gateway/advanced-tool.ts` | 1 | `apimapper_advanced` gateway to the 60 advanced tools |
+| `render/` | 1 | `apimapper_render` deterministic table/diagram/chart renderer |
+| `yootheme-binding.ts` | 1 | `apimapper_yootheme_binding_for_flow` source-name bridge |
 | `onboarding.ts` | 1 | Composite startup report |
 | `diagnose.ts` | 1 | Composite token + identity probe |
 | `inspect.ts` | 1 | Token decode (network-free) |
 | `get-skill.ts` | 1 | Read bundled skill doc |
-| `use-profile.ts` | 1 | Switch active profile |
+| `use-profile.ts` | 2 | Switch active profile + list profiles |
 | `index.ts` | 1 | `apimapper_rest_modules_status` |
 
 ### Adapter Status (`index.ts`)
@@ -55,6 +63,24 @@ vault) for the full convention.
 |------|------------|-------------|
 | `apimapper_rest_modules_status` | `readOnly` | Module-loading status for this MCP adapter (which sub-modules registered cleanly). |
 
+### Advanced Tool Gateway (`gateway/advanced-tool.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_advanced` | `creating` | Gateway to the 60 advanced tools. Call `{ tool }` for a target's schema + annotations (discovery), or `{ tool, arguments }` to run it. The target tool's own confirmation guards stay in effect. |
+
+### Render (`render/`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_render` | `readOnly` | Render structured data as deterministic, pre-formatted text (tables, charts, flow-diagrams). Use when the user asks to visualize / show as a diagram / draw / display as a table or chart. |
+
+### YOOtheme Binding Bridge (`yootheme-binding.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_yootheme_binding_for_flow` | `readOnly` | Given a published flow ID, return the exact YOOtheme GraphQL source names (singular + List) and the schema fields available for binding. Replaces a multi-call chain. |
+
 ### Health, Releases, Brandfetch & Feedback (`misc.ts`)
 
 | Tool | Annotation | Description |
@@ -92,7 +118,8 @@ vault) for the full convention.
 | `apimapper_connection_get` | `readOnly` | Fetch full configuration of a single connection by ID. |
 | `apimapper_connection_health_check` | `readOnly` | Probe a set of connections in one batch and report status. May take 10-30s. |
 | `apimapper_connection_list` | `readOnly` | List all API Mapper connections. Use `apimapper_connection_get` for full details. |
-| `apimapper_connection_pipeline_update` | `mutating` | Update the connection's pipeline (endpoints, default_params, headers, items_path, items_shape). |
+| `apimapper_connection_pipeline_update` | `mutating` | Update the connection's pipeline (endpoints, default_params, default_headers, headers, items_path, items_shape, body, body_type, graphql_variables, response_type). |
+| `apimapper_connection_recover` | `mutating` | Recover a connection that is un-editable because its `params` field is corrupt (stored as a JSON-string with embedded UI metadata instead of an object). Resets `params` to a clean object. Has a `confirm` guard. |
 | `apimapper_connection_resources` | `readOnly` | List browseable resources on a connection (drive files, sheets, IG media). |
 | `apimapper_connection_test` | `readOnly` | Probe a connection's upstream endpoint to verify reachability + auth. |
 | `apimapper_connection_update` | `mutating` | Update fields on an existing connection. Only provided fields are changed; wire-format is snake_case. |
@@ -211,7 +238,8 @@ vault) for the full convention.
 
 | Tool | Annotation | Description |
 |------|------------|-------------|
-| `apimapper_use_profile` | `readOnly` | Activate a configured site profile and probe its identity endpoint to confirm the site is reachable and the plugin signature matches. |
+| `apimapper_list_profiles` | `readOnly` | List all configured site profiles (name, siteUrl, platform) with an `is_active` flag. Use to discover profile names before calling `apimapper_use_profile`. |
+| `apimapper_use_profile` | `mutating` | Activate a configured site profile and probe its identity endpoint to confirm the site is reachable and the plugin signature matches. |
 
 ## Convention reminders
 

package/manifest.json

@@ -1,85 +1,83 @@
 {
-  "dxt_version": "0.1",
-  "name": "@wootsup/mcp",
-  "display_name": "API Mapper for WordPress & Joomla",
-  "version": "0.1.0-rc.13-w3.1",
-  "description": "Build API integrations, OAuth credentials, and YOOtheme sources via natural conversation. Connects your AI assistant to API Mapper running on WordPress or Joomla.",
-  "author": {
-    "name": "WootsUp",
-    "url": "https://wootsup.com"
-  },
-  "homepage": "https://wootsup.com",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/wootsup/api-mapper"
-  },
-  "license": "MIT",
-  "keywords": [
-    "api-mapper",
-    "wordpress",
-    "joomla",
-    "yootheme",
-    "mcp",
-    "claude"
-  ],
-  "server": {
-    "type": "node",
-    "entry_point": "dist/index.js",
-    "mcp_config": {
-      "command": "node",
-      "args": [
-        "${__dirname}/dist/index.js"
-      ],
-      "env": {
-        "APIMAPPER_TOKEN": "${user_config.APIMAPPER_TOKEN}",
-        "APIMAPPER_SITE_URL": "${user_config.APIMAPPER_SITE_URL}",
-        "APIMAPPER_PLATFORM": "${user_config.APIMAPPER_PLATFORM}",
-        "APIMAPPER_PROFILE": "${user_config.APIMAPPER_PROFILE}"
-      }
-    }
-  },
-  "user_config": [
-    {
-      "key": "APIMAPPER_TOKEN",
-      "type": "string",
-      "title": "API Mapper MCP key",
-      "description": "Your amk_live_... key from API Mapper → Settings → MCP Keys",
-      "required": true,
-      "secret": true
-    },
-    {
-      "key": "APIMAPPER_SITE_URL",
-      "type": "string",
-      "title": "Site URL",
-      "description": "The base URL of your WordPress or Joomla site (e.g. https://example.com)",
-      "required": true
+    "dxt_version": "0.1",
+    "name": "@wootsup/mcp",
+    "display_name": "API Mapper for WordPress & Joomla",
+    "version": "0.3.0",
+    "description": "Build API integrations, OAuth credentials, and YOOtheme sources via natural conversation. Connects your AI assistant to API Mapper running on WordPress or Joomla.",
+    "icon": "icon.png",
+    "author": {
+        "name": "WootsUp",
+        "url": "https://wootsup.com"
     },
-    {
-      "key": "APIMAPPER_PLATFORM",
-      "type": "string",
-      "title": "Platform",
-      "description": "Either 'wordpress' or 'joomla'",
-      "required": true,
-      "default": "wordpress"
+    "homepage": "https://wootsup.com",
+    "documentation": "https://wootsup.com/docs/mcp/api-mapper/installation",
+    "support": "https://wootsup.com/contact/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/wootsup/api-mapper"
     },
-    {
-      "key": "APIMAPPER_PROFILE",
-      "type": "string",
-      "title": "Profile name",
-      "description": "Optional label for this site profile, used to switch between multiple sites via apimapper_use_profile. Defaults to 'default'.",
-      "required": false,
-      "default": "default"
-    }
-  ],
-  "compatibility": {
-    "claude_desktop": ">=0.10.0",
-    "platforms": [
-      "darwin",
-      "win32",
-      "linux"
+    "license": "MIT",
+    "keywords": [
+        "api-mapper",
+        "wordpress",
+        "joomla",
+        "yootheme",
+        "mcp",
+        "claude"
     ],
-    "runtimes": {
-      "node": ">=22.0.0"
+    "server": {
+        "type": "node",
+        "entry_point": "dist/index.js",
+        "mcp_config": {
+            "command": "node",
+            "args": [
+                "${__dirname}/dist/index.js"
+            ],
+            "env": {
+                "APIMAPPER_SITE_URL": "${user_config.APIMAPPER_SITE_URL}",
+                "APIMAPPER_TOKEN": "${user_config.APIMAPPER_TOKEN}",
+                "APIMAPPER_PROFILE": "${user_config.APIMAPPER_PROFILE}",
+                "APIMAPPER_SITES_FILE": "${user_config.APIMAPPER_SITES_FILE}"
+            }
+        }
+    },
+    "user_config": {
+        "APIMAPPER_SITE_URL": {
+            "type": "string",
+            "title": "Site URL",
+            "description": "Single-site setup: the base URL of your WordPress or Joomla site (e.g. https://example.com). Leave empty if you use the Sites file below.",
+            "required": false
+        },
+        "APIMAPPER_TOKEN": {
+            "type": "string",
+            "title": "API Mapper MCP key",
+            "description": "Single-site setup: your amk_live_... key from API Mapper → ⋮ menu → Settings → MCP Access. Leave empty if you use the Sites file below.",
+            "required": false,
+            "sensitive": true
+        },
+        "APIMAPPER_PROFILE": {
+            "type": "string",
+            "title": "Profile name (Optional for Single Site Configuration)",
+            "description": "Optional label for this site profile. Defaults to 'default'. With a Sites file, it selects which configured site is active; switch any time via apimapper_use_profile.",
+            "required": false,
+            "default": "default"
+        },
+        "APIMAPPER_SITES_FILE": {
+            "type": "string",
+            "title": "Sites file (for Multi-Site Configurations)",
+            "description": "Advanced / agency setups only: path to a sites.json that manages several sites from one install. Leave empty for a single site (use Site URL + key above). Normally populated by the setup wizard.",
+            "required": false
+        }
+    },
+    "compatibility": {
+        "claude_desktop": ">=0.10.0",
+        "platforms": [
+            "darwin",
+            "win32",
+            "linux"
+        ],
+        "runtimes": {
+            "node": ">=22.0.0"
+        }
     }
-  }
 }

package/package.json

@@ -1,67 +1,70 @@
 {
-  "name": "@wootsup/mcp",
-  "version": "0.1.0",
-  "type": "module",
-  "description": "API Mapper MCP Server — multi-platform (WordPress/Joomla), multi-AI-client, Stripe-style auth, bundled skills",
-  "license": "MIT",
-  "author": "WootsUp <hello@wootsup.com>",
-  "homepage": "https://wootsup.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wootsup/api-mapper.git",
-    "directory": "packages/apimapper-mcp"
-  },
-  "bugs": "https://github.com/wootsup/api-mapper/issues",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "api-mapper",
-    "wordpress",
-    "joomla",
-    "claude",
-    "chatgpt",
-    "cursor"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "apimapper-mcp": "./dist/index.js"
-  },
-  "files": [
-    "dist/",
-    "skills/",
-    "docs/",
-    "manifest.json",
-    "CHANGELOG.md",
-    "SECURITY.md"
-  ],
-  "scripts": {
-    "build": "tsc && chmod +x dist/index.js 2>/dev/null || true",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "dev": "tsx watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "start:http": "node dist/server-http.js",
-    "build:dxt": "node scripts/build-dxt.js",
-    "token-baseline": "node scripts/token-baseline.mjs"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.10.0",
-    "@getimo/mcp-toolkit": "^1.1.1",
-    "@modelcontextprotocol/sdk": "^1.27.0",
-    "@napi-rs/keyring": "^1.3.0",
-    "undici": "^7.25.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/archiver": "^7.0.0",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "~2.1.9",
-    "archiver": "^8.0.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
-  }
+    "name": "@wootsup/mcp",
+    "version": "0.3.0",
+    "type": "module",
+    "description": "API Mapper MCP Server — multi-platform (WordPress/Joomla), multi-AI-client, Stripe-style auth, bundled skills",
+    "license": "MIT",
+    "author": "WootsUp <hello@wootsup.com>",
+    "homepage": "https://wootsup.com",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/wootsup/api-mapper.git",
+        "directory": "packages/apimapper-mcp"
+    },
+    "bugs": "https://wootsup.com/contact/",
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "api-mapper",
+        "wordpress",
+        "joomla",
+        "claude",
+        "chatgpt",
+        "cursor"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "apimapper-mcp": "./dist/index.js"
+    },
+    "files": [
+        "dist/",
+        "skills/",
+        "docs/",
+        "manifest.json",
+        "CHANGELOG.md",
+        "SECURITY.md"
+    ],
+    "scripts": {
+        "prepublishOnly": "node -e \"if (process.env.RELEASE_PHP_PUBLISH !== '1') { console.error('Manual npm publish is no longer supported. Use: php scripts/release.php release apimapper-mcp <bump> followed by php scripts/release.php push-tag apimapper-mcp <version>, which triggers the GitHub Actions publish workflow (.github/workflows/apimapper-mcp-publish.yml). Set RELEASE_PHP_PUBLISH=1 only if you know you are running from that workflow.'); process.exit(1); }\"",
+        "build": "tsc && chmod +x dist/index.js 2>/dev/null || true",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "dev": "tsx watch src/index.ts",
+        "typecheck": "tsc --noEmit",
+        "build:dxt": "node scripts/build-dxt.js",
+        "bump": "node scripts/bump-version.mjs",
+        "token-baseline": "node scripts/token-baseline.mjs"
+    },
+    "dependencies": {
+        "@clack/prompts": "^0.10.0",
+        "@getimo/mcp-toolkit": "^1.1.1",
+        "@modelcontextprotocol/sdk": "^1.27.0",
+        "@napi-rs/keyring": "^1.3.0",
+        "undici": "^7.25.0",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "@types/archiver": "^7.0.0",
+        "@types/node": "^22.0.0",
+        "@vitest/coverage-v8": "~2.1.9",
+        "ajv": "^8.20.0",
+        "archiver": "^8.0.0",
+        "esbuild": "^0.21.5",
+        "tsx": "^4.21.0",
+        "typescript": "^5.6.0",
+        "vitest": "^2.1.0"
+    }
 }

package/skills/apimapper/SKILL.md

@@ -10,7 +10,7 @@ allowed-tools:
 
 # API Mapper
 
-Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transform → Output). One server, one Bearer key, 17-tool gateway surface (77 capabilities behind `apimapper_advanced`).
+Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transform → Output). One server, one Bearer key, 19-tool surface; 60 more behind `apimapper_advanced`; 79 total.
 
 ## Quickstart
 
@@ -19,8 +19,8 @@ Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transf
    npx -y @wootsup/mcp setup
    ```
    Interactive wizard: paste your MCP key, pick the AI client(s) to configure
-   (Claude Desktop, Cursor, Zed, Continue, Cline, Roo Code), wizard writes
-   the config files for you.
+   (Claude Desktop, Claude Code, Cursor, VS Code, Cline, Codex CLI), wizard
+   writes the config files for you.
 
 2. **Generate a key**
    - WordPress: click *API Mapper* in the WP admin menu to open the editor.
@@ -36,14 +36,60 @@ Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transf
    apimapper_onboarding → lists platform, existing flows
    ```
 
+## Step 1 (mandatory): Check the library FIRST
+
+Before reaching for `apimapper_connection_create`, look in the library. Most
+common APIs already have curated templates with OAuth wizard, auto-header
+detection, and a YOOtheme source schema baked in.
+
+```
+apimapper_library_featured()             # the top featured templates
+apimapper_library_list({ query: 'sheets' })  # search for any API by name
+apimapper_credential_list({})            # ALWAYS check credentials BEFORE activating an auth-protected template
+apimapper_library_activate({ id: '<template-id>', credential_id: '<cred-id>' })  # the canonical activation path
+```
+
+**Auth-protected templates (Google Sheets, Notion, Airtable, Pexels, OpenWeatherMap,
+Calendly, GitHub, …): you MUST link a credential.** The activation tool auto-links
+when exactly ONE matching credential exists for the template's provider; otherwise
+it returns a structured `credential_required` / `credential_ambiguous` error
+listing the candidates. Always call `apimapper_credential_list({})` first, then
+pass the right `credential_id` explicitly to `library_activate`. Missing the
+credential silently lands a broken connection (empty endpoint, no auth) that
+returns empty data and is hard to debug from downstream tool calls.
+
+Templates ship today for: **Google Sheets, Calendly, Notion, Airtable, GitHub,
+Pexels, Unsplash, OpenWeatherMap, REST Countries, Google Drive/Docs/Slides/
+Tasks**, and more. Library activations come with:
+- OAuth wizard (no manual app-registration pain)
+- Auto-header detection for spreadsheet sources (Google Sheets!)
+- Curated YOOtheme source schema (no positional-field-name footguns)
+- Pre-configured caching and items_path
+
+## Step 2: Custom connection_create — ONLY when no template fits
+
+If `library_list({ query: '<api-name>' })` returns no match, fall back to
+`apimapper_connection_create` for niche or unknown APIs.
+
+**Server-enforced (not just prose).** A custom `connection_create` whose
+endpoint host is covered by a curated template is rejected with HTTP 409
+`error_code: library_template_available`; the error message names the template
+and the exact `apimapper_library_activate({ id })` call, and a structured
+`library_suggestion` ({matched_host, templates[], activate_call}) accompanies
+it. When the endpoint is genuinely NOT covered (a niche/write/webhook call on a
+covered host), retry `connection_create` with `acknowledge_no_library: true` —
+the audited override. Always prefer activation.
+
 ## Common Tools
 
 | Tool | Use for |
 |------|---------|
-| `apimapper_connection_create` | New REST/OAuth source |
+| `apimapper_library_featured` | **Start here** — top templates, mandatory first call |
+| `apimapper_library_list` | Search/browse the library by name or category |
+| `apimapper_library_activate` | Activate a featured template (canonical path) |
+| `apimapper_connection_create` | Custom connection — only when no template matches |
 | `apimapper_flow_setup_with_sources` | One-shot connection+flow+publish |
 | `apimapper_flow_compile` | Validate graph before publish |
-| `apimapper_library_activate` | Drop a featured template |
 | `apimapper_diagnose` | Triage 401/404/5xx |
 
 For topic docs: `apimapper_get_skill topic="..."` or read `skill://apimapper/<topic>`.
@@ -52,6 +98,6 @@ For topic docs: `apimapper_get_skill topic="..."` or read `skill://apimapper/<to
 
 - **Source not in YOOtheme Builder** → flow is *saved* but not *published*. Click Publish. Published name (not "API Mapper") appears in YOOtheme Source dropdown.
 - **Joomla 404 on `/wp-json/...`** → Joomla wraps in `com_ajax`. See `apimapper_get_skill topic="joomla"`.
-- **OAuth expired** → use `apimapper_credential_link` to re-auth, NOT delete-and-recreate (loses `refresh_token`).
+- **OAuth expired** → use `apimapper_oauth_authorize_begin` to re-auth (re-runs the OAuth2 authorize flow on the existing credential), NOT delete-and-recreate (loses `refresh_token`). `apimapper_credential_link` only *attaches* a credential to a connection; it does not re-authorize.
 
-Full docs: `wootsup.com/docs/mcp/`
+Full docs: `https://wootsup.com/docs/mcp/api-mapper/`

package/skills/apimapper/reference/conditional-style-multi-items.md

@@ -0,0 +1,114 @@
+# Conditional Style on Multi-Items
+
+How to drive per-row YOOtheme styles (panel, card, text, button, label) from a
+row field, and where the YT-Pro enums trap you. This topic exists because of
+two real Cold-AI sessions that wired customers into infinite loops with
+`text_style: 'primary'` (not a valid enum) and lost an hour debugging "why is
+the style not changing".
+
+The short version:
+
+- `text_style` does **not** accept `'primary'`. Use `text_color: 'primary'`
+  on the `text` element, or wrap it in a `grid_item` / `panel` whose
+  `panel_style` is `'primary'`.
+- Conditional values come from JMESPath in the Transform stage and bind to
+  the Multi-Items element via the row's expression slot (`${item.foo}`).
+
+## Canonical YT-Pro 4.5 enum table
+
+The values below are pinned against YOOtheme Pro 4.5
+`wp-content/themes/yootheme/packages/builder/elements/<element>/element.json`.
+
+| Property        | Valid values                                                                  | Where it lives                                       |
+|-----------------|-------------------------------------------------------------------------------|------------------------------------------------------|
+| `text_style`    | `""`, `"meta"`, `"lead"`, `"small"`, `"large"`                                | `text` element                                       |
+| `text_color`    | `""`, `"muted"`, `"emphasis"`, `"primary"`, `"secondary"`, `"success"`, `"warning"`, `"danger"` | `text`, `heading`, `subtitle`        |
+| `panel_style`   | `""`, `"default"`, `"primary"`, `"secondary"`                                 | `grid_item`, `panel`, `card` (legacy) wrappers       |
+| `card_style`    | `""`, `"default"`, `"primary"`, `"secondary"`, `"hover"`                      | `card` element                                       |
+| `button_style` | `"default"`, `"primary"`, `"secondary"`, `"danger"`, `"text"`, `"link"`        | `button` element                                     |
+| `label_style`   | `""`, `"success"`, `"warning"`, `"danger"`                                    | `label` element                                      |
+
+### Trap: `text_style: 'primary'` is not a thing
+
+`text_style` is a typographic-role enum (caption, lead paragraph etc.), not a
+color scheme. If you want the body text emphasized in the theme's primary
+color, you have two correct routes:
+
+1. **Cheap route: `text_color: 'primary'` on the `text` element.**
+   The text element supports both `text_style` (size/weight) and
+   `text_color` (theme color slot). They compose — `text_style: 'lead'` +
+   `text_color: 'primary'` is valid.
+
+2. **Heavy route: wrap in `grid_item` with `panel_style: 'primary'`.**
+   This gives the whole row a primary-themed panel background and applies
+   the YT-Pro panel typography ramp. Use this when the cell needs a colored
+   pill/card around it, not just colored text.
+
+If you see `requires_confirm: true` looping or you get an unhelpful YT-Pro
+"unknown style" warning in the page render, this is the first thing to check.
+
+## Recipe A — text_color from row field
+
+Bind the row field `priority` to the text element's `text_color`. The row's
+JMESPath transform precomputes a valid enum value so the binding is just
+`${item.color}`.
+
+```jmespath
+items[].{
+  title: title,
+  body:  description,
+  color: (priority == `high` && `danger`) ||
+         (priority == `medium` && `warning`) ||
+         `muted`
+}
+```
+
+In the YT-Pro Multi-Items element layout, the `text` child binds:
+
+```
+title       → ${item.title}
+content     → ${item.body}
+text_color  → ${item.color}
+text_style  → "lead"
+```
+
+Note `text_style` stays a literal (`"lead"`) — only `text_color` varies per
+row. Both compose cleanly.
+
+## Recipe B — panel_style wrapper from row field
+
+Use this when each row needs a colored card or pill background, not just
+colored text. The wrapper is a `grid_item` with its `panel_style` bound to
+the row's color.
+
+```jmespath
+items[].{
+  title:    title,
+  body:     description,
+  panelKey: (status == `error` && `primary`) ||
+            (status == `warn`  && `secondary`) ||
+            `default`
+}
+```
+
+In the Multi-Items layout, the `grid_item` wrapping the row content binds:
+
+```
+panel_style → ${item.panelKey}
+panel_card  → "default"   (literal — keeps card chrome consistent)
+```
+
+Inside that grid_item, the `text` child stays color-neutral
+(`text_color: ""`, `text_style: ""`) so the panel's own typography applies.
+
+## Why `text_style: 'primary'` keeps tripping AIs
+
+Customers (and AIs) generalize from the `panel_style` / `card_style` /
+`button_style` precedent: those all accept `'primary'`. `text_style` looks
+like the same family, but it isn't — it's a holdover from the original
+UIkit text-role API where roles are `lead`/`meta`/`small`/`large`. YT-Pro's
+"is this row important?" intent belongs in `text_color` or `panel_style`,
+never in `text_style`.
+
+When in doubt: prefer Recipe A (cheap, composes with everything), upgrade to
+Recipe B only when the row needs visible chrome.