@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/manifest.json

@@ -1,76 +1,83 @@
 {
-  "dxt_version": "0.1",
-  "name": "@wootsup/mcp",
-  "display_name": "API Mapper for WordPress & Joomla",
-  "version": "0.1.0-rc.9",
-  "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/products/api-mapper",
-  "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}"
-      }
-    }
-  },
-  "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
+    "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_SITE_URL",
-      "type": "string",
-      "title": "Site URL",
-      "description": "The base URL of your WordPress or Joomla site (e.g. https://example.com)",
-      "required": true
+    "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_PLATFORM",
-      "type": "string",
-      "title": "Platform",
-      "description": "Either 'wordpress' or 'joomla'",
-      "required": true,
-      "default": "wordpress"
-    }
-  ],
-  "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,62 +1,70 @@
 {
-  "name": "@wootsup/mcp",
-  "version": "0.1.0-rc.9",
-  "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/products/api-mapper",
-  "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",
-    "dev": "tsx watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "start:http": "node dist/server-http.js",
-    "build:dxt": "node scripts/build-dxt.js"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.10.0",
-    "@getimo/mcp-toolkit": "^1.0.2",
-    "@modelcontextprotocol/sdk": "^1.27.0",
-    "@napi-rs/keyring": "^1.3.0",
-    "undici": "^7.25.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/node": "^22.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, 74 MCP tools.
+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.

package/skills/apimapper/reference/jmespath-pitfalls.md

@@ -0,0 +1,108 @@
+# JMESPath Pitfalls
+
+The nine traps that bite every Transform JMESPath expression in API Mapper, plus the date-primitive functions added in 2.0.8 that finally make weekday-name ↔ ISO-datetime joins tractable.
+
+## The 9 traps
+
+1. **Top-level vs item-level scope.** A flat `[].name` projects across items; bare `name` reads the wrapper object. Mixing the two is the most common cause of `null` everywhere.
+2. **Implicit numeric coercion.** `[?price > 100]` reads `price` as a string when the API returns a string. Cast first with `to_number(price) > \`100\`` or normalize upstream.
+3. **`@` vs nothing.** Inside multi-select hashes the `@` refers to the current item — `{name: @.name}` is shorthand. Forgetting `@` inside a filter expression (`[?@.x == 'y']`) is silently parsed as a function call.
+4. **String-quoted literals.** JSON literals use backticks: `\`100\``, `\`true\``, `\`null\``. Single-quoted strings (`'red'`) are raw strings. Mixing them up yields lexer errors that the engine reports far from the actual typo.
+5. **`null` propagation through pipes.** `items | [].name | [?contains(@, 'foo')]` returns `null` (not `[]`) when an item has no `name`. Wrap with `coalesce_empty(@, '')` or filter `not_null(@)`.
+6. **`length()` on null.** Vendor `length(null)` throws. Use `length(@.items || \`[]\`)` to default.
+7. **Backslash-escapes inside raw strings.** Single-quoted strings do NOT honour `\n` / `\t`. To embed a literal `'` use `'\\''` (close, escape, open).
+8. **Empty-array vs missing-key.** `[?tags]` keeps items whose `tags` is non-empty AND non-null. To match items with the *key* present regardless of value, use `[?contains(keys(@), 'tags')]`.
+9. **Multi-projection collapse on header-skip slices.** `[1:][*].{weekday: [0], open: [1]}` looks like "slice off the header row, then map each remaining row into a hash", but JMESPath parses `[1:][*]` as a *chained multi-projection* that flattens row boundaries before the hash runs. The fix is one pipe: `[1:] | [*].{weekday: [0], open: [1]}`. See "Symptom / Cause / Fix" below.
+
+### Pitfall 9 in detail (header-skip slice → hash projection)
+
+**Symptom.** Output schema auto-detection returns flat columns prefixed with the row index, like:
+
+```
+0_weekday, 0_open, 0_close,
+1_weekday, 1_open, 1_close,
+2_weekday, 2_open, 2_close, ...
+```
+
+Each row also reads as `null` in the actual data preview. Every binding in the Multi-Items element lands on the wrapper object instead of the row.
+
+**Cause.** `[1:][*]` is two consecutive projections. JMESPath flattens them: the inner array index dissolves, so the trailing `.{weekday: [0], ...}` operates on the wrapper object's positional slots, not on each row. The auto-detected schema reflects that flattened shape.
+
+**Fix.** Insert a pipe between the slice and the hash projection so the second stage starts fresh:
+
+```jmespath
+# Working — pipe resets the projection so [*] iterates row-by-row
+[1:] | [*].{
+  weekday: [0],
+  open:    [1],
+  close:   [2]
+}
+```
+
+This recipe is the canonical shape for "Google Sheets export with a header row" sources. If you find yourself debugging `0_*` / `1_*` / `2_*` column names in the YOOtheme source field picker, this is almost always the cause.
+
+## Date-primitive functions (new in 2.0.8)
+
+JMESPath has no built-in date support. API Mapper ships four custom date primitives so weekday-name ↔ ISO-datetime joins (Calendly → Sheet schedule, HubSpot meeting-times → office-hours, etc.) become possible without exporting to a sidecar service.
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `date_weekday` | `date_weekday(iso_string [, tz])` | English weekday name `"Monday"`..`"Sunday"`, or `null` on bad input |
+| `date_iso_to_time` | `date_iso_to_time(iso_string [, tz])` | `"HH:MM"` 24-hour time, or `null` |
+| `date_iso_to_date` | `date_iso_to_date(iso_string [, tz])` | `"YYYY-MM-DD"` calendar date, or `null` |
+| `time_in_window` | `time_in_window(time, from, to)` | `true` if `time` is in `[from, to)`. Supports cross-midnight when `from > to`. `false` on any malformed input |
+
+### Timezone rules
+
+- `tz` is an IANA timezone string (`"Europe/Berlin"`, `"America/New_York"`, `"UTC"`).
+- If `tz` is omitted, the offset already encoded in the input string is preserved. A Calendly payload `"2026-06-04T09:00:00+02:00"` returns `"09:00"` from `date_iso_to_time(@, )` (no second arg) — i.e. the customer's local time.
+- If `tz` IS supplied, the datetime is shifted into that zone first.
+- An unknown timezone (typo, mistaken country code) returns `null`. This is the same graceful-failure mode as malformed datetimes — one bad row never crashes the flow.
+
+### The Maria recipe (Calendly + Sheet weekday-join)
+
+```
+# Source A — Calendly available_times
+[].{
+  day: date_weekday(start_time, 'Europe/Berlin'),
+  local_time: date_iso_to_time(start_time, 'Europe/Berlin'),
+  start_time: start_time
+}
+```
+
+Now each Calendly slot carries a Sheet-comparable `day` (e.g. `"Wednesday"`) AND a comparable `local_time` (e.g. `"09:30"`). See `merge-two-sources-on-key` for the full join pattern.
+
+### Slot-against-business-hours filter
+
+```
+[?time_in_window(date_iso_to_time(start_time, 'Europe/Berlin'),
+                 '09:00', '17:00')]
+```
+
+Cross-midnight windows (bars, support shifts):
+
+```
+[?time_in_window(local_time, '22:00', '02:00')]   # 10pm..2am
+```
+
+## Depth-cap warning
+
+JMESPath expression depth is capped at **10 levels** of bracket / pipe nesting. Above that, the engine returns `expression too deeply nested (N levels)`.
+
+**As of 2.0.8 this is caught at flow-write time** (HTTP 422 on `flow_create` / `flow_update`) with per-node `jmespathErrors`. The response payload looks like:
+
+```json
+{
+  "success": false,
+  "error": "1 JMESPath expression exceeded the depth limit of 10",
+  "jmespathErrors": { "t1": "JMESPath expression too deeply nested (13 levels). Maximum: 10" },
+  "status": 422
+}
+```
+
+If you hit this, the cure is almost always to split the expression into TWO transform nodes piped together — that resets the depth counter and is easier to debug.
+
+## See also
+
+- `merge-two-sources-on-key` — joining two sources on a shared key, with date-primitive bridging.
+- `troubleshooting` — broader error triage.

package/skills/apimapper/reference/joomla.md

@@ -70,7 +70,7 @@ Joomla extensions install as a `.zip` (system plugin). The MCP server bundles a
 To verify the plugin is loaded:
 ```
 apimapper_health
-# → { platform: "joomla", version: "2.0.7", plugin: "enabled" }
+# → { platform: "joomla", version: "2.0.13", plugin: "enabled" }
 ```
 
 If `plugin: "disabled"`, enable via Joomla admin → Extensions → Plugins → search "API Mapper".