@wootsup/mcp 0.1.0 → 0.4.0

package/skills/apimapper/reference/merge-two-sources-on-key.md

@@ -0,0 +1,204 @@
+# Merge two sources on a shared key
+
+Join items from two sources on a shared key, optionally filter the join, surface the result as one Source for YOOtheme.
+
+## When to use
+
+- You have two APIs whose rows belong together but live behind separate endpoints (orders + customers, Calendly slots + Sheet schedule, GitHub issues + sprint planning).
+- The keys you want to join on either (a) are already string-equal, or (b) need a small Transform to be made comparable (e.g. ISO datetime → weekday name).
+
+## The canonical recipe (REST / MCP — no UI dragging)
+
+```
+Source-A  ─┐
+            ├─►  Merge (strategy: join, joinKey: <field>)  ─►  Filter  ─►  Output
+Source-B  ─┘
+```
+
+Build the whole thing in ONE call — `apimapper_flow_setup_with_sources` lays out the source → merge → (filter) → output graph for you:
+
+```jsonc
+apimapper_flow_setup_with_sources({
+  name: "Properties + Ratings",
+  sources: [
+    { connection: "con_properties" },   // Source-A
+    { connection: "con_ratings" }        // Source-B
+  ],
+  merge: {
+    strategy: "join",        // emit one row per matched A item, B fields flat-merged on (NOT nested under `b`)
+    joinKey: "property_id",  // field on Source-A
+    joinKeyRight: "propertyId", // field on Source-B — OMIT when both sides name it the same
+    joinType: "left"         // "left" keeps every A row; "inner" drops A rows with no B match
+  },
+  // optional: filter runs AFTER merge, references both A- and B-side fields by their bare names
+  filter: { field: "rating", operator: "gte", value: 4 },
+  output: { type: "yootheme", name: "RatedProperties" }
+})
+```
+
+Key points:
+- `strategy: "join"` (NOT `mode`), `joinKey` (NOT `key`). The old UI words `mode`/`key` are not REST parameters.
+- `joinKey` is the Source-A field; `joinKeyRight` is the Source-B field. When both sides use the **same** field name, set only `joinKey` (`joinKeyRight` defaults to it).
+- Discover the right `joinKey`/`joinKeyRight` BEFORE you build — see the next section.
+- Already have a saved flow? Edit the merge node with `apimapper_flow_update` (same `strategy`/`joinKey`/`joinKeyRight`/`joinType` node-data keys).
+
+## Discovering the join key
+
+You almost never know the join key up front, and **guessing wrong yields 0 matched rows with no error**. Discover it by sampling both sources first.
+
+1. **Sample Source-A:**
+   ```
+   apimapper_connection_data({ id: "con_properties", limit: 3 })
+   ```
+   Note the candidate key fields and their values, e.g. `property_id: "P-100"` (a **string**).
+2. **Sample Source-B:**
+   ```
+   apimapper_connection_data({ id: "con_ratings", limit: 3 })
+   ```
+   e.g. `propertyId: 42` (a **number**).
+3. **Pick a key that is present and comparable on BOTH sides.** The join compares values with `===`-style equality, so the two keys must match in **type AND format**:
+   - string `"P-100"` never equals number `42` — even `"42"` never equals `42`.
+   - `"  P-100"` (trailing/leading space) never equals `"P-100"`.
+   - `"p-100"` never equals `"P-100"` (case matters).
+4. **If the keys aren't comparable as-is, bridge them with a Transform** before the merge (see "When the keys aren't string-equal" below) — e.g. `to_string(propertyId)` on the number side, or a `date_weekday(...)` projection for datetime↔weekday joins.
+
+### When the join still returns 0 rows — the `merge_no_match` signal
+
+If `apimapper_graph_preview` returns `item_count: 0` for a join, check the response for `merge_diagnostics[<mergeNodeId>]`:
+
+```jsonc
+"merge_diagnostics": {
+  "merge-1": {
+    "reason": "merge_no_match",
+    "message": "Merge 'merge-1' (join inner) matched 0 rows: left joinKey 'property_id' (2 items) never equalled right joinKeyRight 'propertyId' (2 items). …",
+    "joinKey": "property_id",
+    "joinKeyRight": "propertyId",
+    "left_key_sample": ["P-100", "P-200"],
+    "right_key_sample": [42, 77]
+  }
+}
+```
+
+The `left_key_sample` / `right_key_sample` show the actual key values from each side. Compare them: above, the left side is strings (`"P-100"`) and the right side is numbers (`42`) — they can never match. Fix it by either picking a different key or adding a Transform to make them comparable, then re-preview.
+
+## The flat-merge contract (READ THIS)
+
+The Merge join does **NOT** nest the B-side under a `b` object. There is no `b.` prefix and no option to enable one. Each matched B row is merged **flat onto the A row**, field by field, with this collision rule:
+
+| Situation | Result |
+|-----------|--------|
+| B has a field A does **not** have | B's value is copied verbatim at the **top level** (e.g. `open`, `close`, `rating`, `email`). |
+| Both sides carry the field with the **same** value | Kept once from A — no duplicate, no prefix. |
+| Both sides carry the field with **different** values | A's value stays under the original key; **B's value is renamed `branch_1_<key>`** (the `branch_1` prefix denotes the secondary input handle `input-1`). |
+
+So if Source-A is the orders feed and Source-B (a products sheet) carries `rating`, the merged row exposes `rating` at the top level — bind to `rating`, **not** `b.rating` (which is always null). Only when a field name collides does the B value move, and it moves to `branch_1_<field>`, never `b.<field>`.
+
+### Worked example
+
+```
+Source-A (orders) row:    { "id": 7, "product": "Widget", "status": "shipped" }
+Source-B (products) row:  { "id": 7, "rating": 4.5, "status": "active" }
+```
+
+Join key `id`. The merged row is:
+
+```json
+{
+  "id": 7,
+  "product": "Widget",
+  "status": "shipped",
+  "rating": 4.5,
+  "branch_1_status": "active"
+}
+```
+
+- `rating` — B-only field, flat at top level.
+- `status` — present on BOTH with different values → A's `"shipped"` keeps the key, B's `"active"` becomes `branch_1_status`.
+- `id` — same value on both sides → kept once, no prefix.
+
+Bind YOOtheme element fields to `rating` and `branch_1_status`; binding to `b.rating` returns nothing.
+
+> **`join` is left-join by default** (every A row survives; A rows with no B match pass through unchanged). Set `joinType: inner` to drop A rows that have no match. A 1:N or N:M match emits one merged row per B match (the cartesian product of the matching rows).
+
+## When the keys aren't string-equal — date-primitive bridging
+
+This is the case Cold-AI #5 walk-through hit: Calendly emits `start_time` as ISO-UTC (`"2026-06-04T09:00:00+00:00"`), but the customer's Sheet schedule is keyed on weekday names (`"Wednesday"`). The keys aren't comparable as-is.
+
+**Fix:** insert a Transform node BEFORE Merge on the Calendly side that derives a Sheet-compatible key.
+
+### Maria's flow (Calendly + Google Sheet schedule)
+
+```
+Calendly available_times  ─► Transform (project day+local_time) ─┐
+                                                                  ├─► Merge (strategy: join, joinKey: day)  ─► Filter ─► Output
+Google Sheet schedule      ──────────────────────────────────────┘
+```
+
+#### Step 1 — Transform on the Calendly side
+
+```
+[].{
+  day: date_weekday(start_time, 'Europe/Berlin'),
+  local_time: date_iso_to_time(start_time, 'Europe/Berlin'),
+  start_time: start_time
+}
+```
+
+Each Calendly row now carries:
+
+| field | value |
+|-------|-------|
+| `day` | `"Wednesday"` — Sheet-comparable |
+| `local_time` | `"09:00"` — comparable to Sheet's `open`/`close` |
+| `start_time` | original ISO datetime (preserved for downstream rendering) |
+
+#### Step 2 — Merge on `day`
+
+Merge `strategy: "join"`, `joinKey: "day"` (both sides name it `day`/`weekday` — set `joinKeyRight: "weekday"` if the Sheet column is `weekday` rather than `day`). The matching Sheet row is **flat-merged** onto each Calendly row — its `weekday`, `open`, and `close` fields land at the top level (the Calendly side carries `day`/`local_time`/`start_time`, so there is no field-name collision and nothing gets a `branch_1_` prefix):
+
+```json
+{
+  "day": "Wednesday",
+  "local_time": "09:00",
+  "start_time": "2026-06-03T07:00:00+00:00",
+  "weekday": "Wednesday",
+  "open": "09:00",
+  "close": "17:00"
+}
+```
+
+#### Step 3 — Filter to slots inside business hours
+
+Reference the Sheet's `open`/`close` by their **bare top-level names** — there is no `b.` prefix:
+
+```
+[?time_in_window(local_time, open, close)]
+```
+
+`time_in_window` is left-closed, right-open ([from, to)) — a 17:00 close-time does NOT include a 17:00 slot. Cross-midnight windows (e.g. bar `22:00..02:00`) are also handled.
+
+#### Step 4 — Output
+
+Wire to a YOOtheme Output. Slots that survive Steps 1-3 become the rows of a YOOtheme Source named e.g. `BookableSlots`.
+
+## Other date-bridge patterns
+
+| Customer scenario | Source-A key | Source-B key | Bridge |
+|-------------------|--------------|--------------|--------|
+| HubSpot meetings ↔ office-hours | ISO datetime | weekday name | `date_weekday(@.start, tz)` |
+| Stripe invoices ↔ month-rollup | ISO datetime | `"YYYY-MM"` | `substring(date_iso_to_date(@.created, tz), 0, 7)` |
+| GitHub issues ↔ daily-standup notes | ISO datetime | `"YYYY-MM-DD"` | `date_iso_to_date(@.updated_at, tz)` |
+
+## Pitfalls
+
+- **No `b.` namespace.** B-side fields are flat-merged onto the row (see "The flat-merge contract"). Bind to the bare field name (`rating`, `open`), never `b.rating` / `b.open` — those resolve to null. The only time a B value moves is a name collision, and then it moves to `branch_1_<key>`, not `b.<key>`.
+- **Collisions are silent unless you name them.** If both sources carry a field of the same name with different values (e.g. both have `status`), A wins the original key and B is preserved as `branch_1_status`. If you actually wanted B's value, either rename it in a Transform on the B side before the Merge, or read `branch_1_status` downstream.
+- **Timezone matters.** A slot at `2026-06-04T23:30:00Z` is Wednesday in UTC but Thursday in Berlin. Always supply the second `tz` arg matching the customer's business timezone.
+- **`null` rows propagate.** A Calendly row with a malformed `start_time` projects to `{day: null, local_time: null, start_time: <bad>}`. The Merge will silently emit it under a `null` key — pre-filter with `[?day]` if you need to drop them.
+- **Depth limit.** Don't try to do the whole projection + merge + filter inside ONE expression. JMESPath caps depth at 10. Two transform nodes piped is cleaner and stays under the limit.
+- **0 rows? Read `merge_diagnostics`.** A join that matches nothing comes back as `item_count: 0`, not an error. `apimapper_graph_preview` attaches `merge_diagnostics[<mergeNodeId>]` (`reason: merge_no_match`) with the keys and a `left_key_sample`/`right_key_sample` so you can spot the type/format mismatch. Don't guess — sample both sides with `apimapper_connection_data` (see "Discovering the join key").
+
+## See also
+
+- `jmespath-pitfalls` — full pitfall catalogue + date-primitive function reference.
+- `yootheme` — how the published Source appears in YOOtheme Builder.

package/skills/apimapper/reference/oauth.md

@@ -2,93 +2,184 @@
 
 Wiring OAuth-protected sources (Pexels API key, Google Sheets/Drive, Instagram Graph, Facebook Pages, Notion, Airtable, …) through API Mapper.
 
+> **Schema note (read first).** Every snippet below uses the EXACT tool parameters the server accepts. The wire contract is snake_case: credentials carry `auth_type` / `auth_data` / `oauth_provider`; connections carry `endpoint` / `auth_type` / `credential_id`. The credential's auth shape is `auth_type` (never a bare `type`), its secrets live under `auth_data` (no top-level `scopes`), and a connection's request is described by `endpoint` + `method` (there is no driver-slug parameter and no nested driver-config object). Older drafts that showed those phantom params were wrong and the tools reject them.
+
+## Tool-surface map (which tools are top-level vs gateway)
+
+| Tool | Surface | How to call |
+|------|---------|-------------|
+| `apimapper_library_featured`, `apimapper_library_list`, `apimapper_library_activate` | top-level | call directly |
+| `apimapper_connection_create`, `apimapper_connection_data`, `apimapper_connection_list` | top-level | call directly |
+| `apimapper_credential_list`, `apimapper_oauth_authorize_begin` | top-level | call directly |
+| `apimapper_credential_create`, `apimapper_credential_get`, `apimapper_connection_test` | **advanced** | via `apimapper_advanced({ tool, arguments })` |
+
+A bare `apimapper_credential_create({…})` returns "No such tool" — it is reachable **only** through the `apimapper_advanced` gateway. The same is true of `apimapper_credential_get` and `apimapper_connection_test`.
+
 ## When to use OAuth vs static key
 
-| Auth shape | Examples | Credential type |
-|------------|----------|-----------------|
-| Static API key in header | Pexels, NewsAPI, OpenWeather | `bearer` or `apikey` |
-| OAuth2 authorization-code | Google Sheets/Drive, Instagram, Facebook, Notion | `oauth2_authcode` |
-| OAuth2 client-credentials | Spotify (catalog), some B2B APIs | `oauth2_clientcred` |
-| Personal access token | GitHub, GitLab, Airtable | `bearer` |
+| Auth shape | Examples | `auth_type` (credential) |
+|------------|----------|--------------------------|
+| Static API key | Pexels, NewsAPI, OpenWeather | `api_key` |
+| Bearer / personal access token | GitHub, GitLab, Airtable, Notion | `bearer` |
+| Basic auth (user + pass) | legacy/internal APIs | `basic_auth` |
+| OAuth2 authorization-code (user consent + refresh token) | Google Sheets/Drive, Instagram, Facebook | `oauth2_code` |
+| OAuth2 client-credentials (machine-to-machine) | Spotify catalog, some B2B APIs | `oauth2_cc` |
 
-If the API requires a user-consent screen and returns a `refresh_token`, you want `oauth2_authcode`. Everything else is `bearer`/`apikey`.
+If the API needs a user-consent screen and returns a `refresh_token`, use `oauth2_code`. Everything else is `bearer` / `api_key` / `basic_auth`.
 
-## Wiring an OAuth source — full flow
+## The canonical path for a covered API: activate a library template
 
-The two-step pattern is **always**: create credential → bind credential to connection. Credentials are reusable across connections.
+For Google Sheets, Drive, Docs, Slides, Tasks, Calendly, Notion, Airtable, GitHub, Pexels, Unsplash, OpenWeatherMap, REST Countries and more, **do not hand-build a credential + connection.** Activate the curated template — it pre-wires the auth shape, scopes, and field detection, and the server's library-first guard will block a custom create on a covered host anyway.
 
-### Step 1 — Create the credential
+```jsonc
+// 1. Find the template.
+apimapper_library_list({ search: "google sheets" })   // min 3 chars
 
+// 2. (OAuth templates) reuse an existing credential if you have one,
+//    otherwise create one — see "Creating an OAuth credential" below.
+apimapper_credential_list({})                          // top-level; find a reusable cred
+
+// 3. Activate. credential_id is auto-resolved when exactly ONE OAuth
+//    credential for the provider exists; pass it explicitly otherwise.
+apimapper_library_activate({
+  id: "google-sheets",
+  credential_id: "cred_google",                        // optional when unique
+  extra_fields: { spreadsheet_id: "1AbC2dEf...REPLACE_WITH_ID" }
+})
+```
+
+`extra_fields` carries the template placeholder values (for Sheets that is the **bare** spreadsheet id — see the note below). `apimapper_library_activate` produces a ready connection; you never touch `connection_create` for a covered API.
+
+> **Spreadsheet id, not URL.** `extra_fields.spreadsheet_id` wants the bare id (`1AbC2dEf…`), not the full `https://docs.google.com/spreadsheets/d/…/edit` Drive URL. Paste only the path segment between `/d/` and the next `/`.
+
+## Creating an OAuth credential (when none is reusable)
+
+`apimapper_credential_create` is an **advanced** tool — call it through the gateway. It does **not** return an authorize URL; you trigger consent separately with `apimapper_oauth_authorize_begin`.
+
+```jsonc
+// Step 1 — create the oauth2_code credential (via the gateway).
+apimapper_advanced({
+  tool: "apimapper_credential_create",
+  arguments: {
+    name: "My Google Account",
+    auth_type: "oauth2_code",
+    oauth_provider: "google",
+    auth_data: {
+      client_id: "…",
+      client_secret: "…",
+      authorization_url: "https://accounts.google.com/o/oauth2/v2/auth",
+      token_url: "https://oauth2.googleapis.com/token",
+      scopes: ["https://www.googleapis.com/auth/spreadsheets.readonly"]
+    }
+  }
+})
+// → { created: true, id: "cred_…", name, auth_type }   (NO authorize_url here)
 ```
-apimapper_credential_create(
-  name="My Google Account",
-  type="oauth2_authcode",
-  provider="google",
-  scopes=["https://www.googleapis.com/auth/spreadsheets.readonly"]
-)
+
+```jsonc
+// Step 2 — begin authorization → get the consent URL.
+apimapper_oauth_authorize_begin({ credential_id: "cred_…" })
+// → { authorize_url: "https://accounts.google.com/o/oauth2/v2/auth?…" }
 ```
 
-The tool returns a `credential_id` and an `authorize_url`. The caller (Claude / ChatGPT / Cursor) **must** surface the `authorize_url` to the user — the user clicks it, completes consent, the OAuth callback writes the `access_token` + `refresh_token` into the credential record.
+The caller (Claude / ChatGPT / Cursor) **must surface `authorize_url` to the user** — the user clicks it, completes consent, and the OAuth callback writes the `access_token` + `refresh_token` into the credential. If you skip surfacing the URL the credential stays `pending` and every call returns 401.
 
-If you skip surfacing the URL, the credential will stay in `pending` state and every subsequent call will return 401.
+`apimapper_oauth_authorize_begin` also resolves by `provider` when you omit `credential_id`: `apimapper_oauth_authorize_begin({ provider: "google" })` picks the unique `oauth2_code` credential for that provider (or asks you to choose when several match).
 
-### Step 2 — Begin authorization (when refresh failed)
+### Re-authorizing an expired credential
 
-If the credential is `expired` or the refresh token was revoked, re-trigger consent:
+If the credential is `expired` or its refresh token was revoked, re-trigger consent — **never delete-and-recreate** (that wipes the refresh token):
 
+```jsonc
+apimapper_oauth_authorize_begin({ credential_id: "cred_…" })
 ```
-apimapper_oauth_authorize_begin(credential_id="cred_abc123")
+
+Custom-provider (non-catalog) credentials re-authorize the same way — the server now recovers the stored `authorization_url` / `token_url` from the credential's `auth_data`, so a bare `apimapper_oauth_authorize_begin({ credential_id })` works without re-passing `oauth_config`.
+
+### A CUSTOM OAuth provider not in the catalog (authorization-code)
+
+For an authorization-code provider that has **no** library template (e.g. Teamleader, a self-hosted Keycloak, a niche SaaS), drive the whole consent flow in one call by passing `oauth_config` to `apimapper_oauth_authorize_begin`. You do **not** pre-create the credential — the callback creates it for you.
+
+```jsonc
+apimapper_oauth_authorize_begin({
+  client_id: "…",
+  client_secret: "…",
+  credential_name: "Teamleader Prod",          // display name for the new credential
+  oauth_config: {
+    authorization_url: "https://app.teamleader.eu/oauth2/authorize",
+    token_url: "https://app.teamleader.eu/oauth2/access_token",
+    scopes: [],                                 // OPTIONAL — omit/empty for scope-less providers
+    use_pkce: false                             // OPTIONAL — default true; turn off if the provider rejects PKCE
+  }
+})
+// → { authorize_url: "https://app.teamleader.eu/oauth2/authorize?…",
+//     redirect_uri: "https://your-site/wp-json/api-mapper/v1/oauth/callback",
+//     state: "…" }
 ```
 
-Returns a new `authorize_url`. Same surface-it-to-the-user rule applies.
+**Before opening `authorize_url`, add the returned `redirect_uri` to the provider's allowed-redirect list.** A mismatched redirect URI is the single most common custom-provider failure — the provider rejects the callback with `redirect_uri_mismatch` and no credential is created. The `redirect_uri` is platform-specific (WordPress `…/wp-json/api-mapper/v1/oauth/callback`; Joomla a path-based `…/index.php/apimapper/oauth/callback`), so always whitelist the exact value the response gives you.
 
-### Step 3 — Create the connection bound to the credential
+Notes:
+- **Scopes are optional.** Some providers (Teamleader class) reject a `scope` parameter entirely — pass `scopes: []` or omit it. For comma-separated providers, the server normalizes the delimiter.
+- **PKCE defaults on.** Leave `use_pkce` unset for modern providers; set it to `false` only if the provider does not support PKCE.
+- The `oauth_config` you pass is **never** echoed back in the response (secret hygiene) — only `authorize_url`, `redirect_uri`, and `state` are returned.
 
-```
-apimapper_connection_create(
-  name="Sheets — Marketing OKRs",
-  source_type="google_sheets",
-  credential_id="cred_abc123",
-  config={ "spreadsheet_id": "1AbC...", "range": "OKRs!A1:F100" }
-)
+## Creating a CUSTOM connection (only when no template fits)
+
+When the API is genuinely **not** covered by any library template, build a custom connection. `apimapper_connection_create` is top-level; its real parameters are `endpoint`, `method`, `auth_type` (`none` / `api_key` / `bearer` / `basic` / `oauth2`), `credential_id`, `items_path`, `cache_ttl`.
+
+```jsonc
+// Static-key example (Pexels-style, if it had no template).
+apimapper_connection_create({
+  name: "My Niche API",
+  endpoint: "https://api.example.com/v1/items",
+  method: "GET",
+  auth_type: "bearer",
+  credential_id: "cred_…",        // the bearer credential created via the gateway
+  items_path: "data"              // JSON path to the array of rows
+})
 ```
 
-`source_type` selects the upstream driver (REST request shape, response normalizer, schema profiler). `config` is driver-specific.
+The request shape comes entirely from `endpoint` + `method`, and auth from `credential_id` — there is no driver-slug parameter and no nested driver-config object to set. If the host is already covered by a template the server returns a **409** naming the template to activate; only set `acknowledge_no_library: true` **after** you receive that 409 and are sure the endpoint is genuinely uncovered.
 
-### Step 4 — Verify
+## Verify
 
-```
-apimapper_connection_test(connection_id="conn_xyz")
+```jsonc
+// connection_test is advanced — call via the gateway.
+apimapper_advanced({ tool: "apimapper_connection_test", arguments: { connection_id: "conn_…" } })
+
+// Or sample real rows (top-level):
+apimapper_connection_data({ id: "conn_…", limit: 3 })
 ```
 
-Returns one of:
-- `{ ok: true, sample: { ... } }` — green, you can build a flow on this
-- `{ ok: false, error: "401", hint: "credential expired → call apimapper_oauth_authorize_begin" }`
-- `{ ok: false, error: "scope_missing", hint: "credential lacks scope X → recreate with scopes=[...]" }`
+A green test (or non-empty `connection_data`) means you can build a flow on the connection.
 
 ## Common pitfalls
 
 1. **Recreating credentials after expiry** — wipes the `refresh_token`. Always `apimapper_oauth_authorize_begin` first; only delete-and-recreate if the user revoked access on the provider side.
-2. **Hardcoding tokens into `connection.config.auth.token`** — bypasses the credential system, breaks rotation, fails on token expiry. Always use `credential_id`.
-3. **Forgetting to surface the `authorize_url`** — the user can't grant consent telepathically. Treat the URL as a required UI step, not a debug log line.
-4. **Scope drift** — provider adds new scopes (e.g. Google's `drive.readonly` split). Add them to the credential definition and re-authorize; pre-existing tokens lack them silently until a call returns 403.
-5. **Sharing a credential across users** — credentials are per-user (tied to the WordPress/Joomla user that created them). Cross-user share is not supported in 2.0.x.
+2. **Hardcoding tokens** — bypasses the credential system, breaks rotation. Always reference a `credential_id`.
+3. **Forgetting to surface `authorize_url`** — the user can't grant consent telepathically. Treat the URL as a required UI step.
+4. **Calling `apimapper_credential_create` directly** — it is advanced; route it through `apimapper_advanced`. Same for `apimapper_credential_get` and `apimapper_connection_test`.
+5. **Custom-creating a covered API** — you'll hit a 409. Activate the template instead (`apimapper_library_activate`).
+6. **Pasting a Drive URL where a bare id is expected** — `extra_fields.spreadsheet_id` is the bare id, not the URL.
+7. **Sharing a credential across users** — credentials are per-user (tied to the WordPress/Joomla user that created them). Cross-user share is not supported in 2.0.x.
 
 ## Provider-specific notes
 
-- **Google** (Sheets/Drive/Calendar/Tasks) — needs `access_type=offline` and `prompt=consent` to issue a refresh token. The MCP server adds these automatically. If you bypass the MCP and craft the URL by hand, you must add them.
-- **Instagram Graph** — token expires every 60 days, refresh-token flow is non-standard (long-lived → exchange). API Mapper's refresh handler covers it; do not call the Meta endpoints directly.
-- **Notion / Airtable** — issue personal access tokens, not full OAuth. Use `bearer` credential type and paste the token; no `authorize_url` step.
-- **Pexels** — static API key; use `apikey` credential type. No consent screen.
+- **Google** (Sheets/Drive/Calendar/Tasks) — needs `access_type=offline` + `prompt=consent` for a refresh token; the server adds these automatically. Activate the `google-sheets` / `google-drive` templates rather than hand-building.
+- **Instagram Graph** — token expires every 60 days; the refresh flow is non-standard (long-lived → exchange). The server's refresh handler covers it.
+- **Notion / Airtable** — issue personal access tokens, not full OAuth. Use `auth_type: 'bearer'` and paste the token in `auth_data: { token: "…" }`; no `authorize_url` step.
+- **Pexels** — static API key; `auth_type: 'api_key'`, `auth_data: { api_key: "…" }`. No consent screen.
 
 ## Diagnose flow
 
-```
-apimapper_credential_get(credential_id="cred_abc123")
-# → { status: "expired", last_refresh_at: "2026-04-12T...", scopes: [...] }
+```jsonc
+apimapper_diagnose({ connection_id: "conn_…" })
+// consolidates credential state + last test + recent logs
 
-apimapper_diagnose(connection_id="conn_xyz")
-# → consolidates credential state + last connection_test + recent logs
+apimapper_advanced({ tool: "apimapper_credential_get", arguments: { id: "cred_…" } })
+// → sanitised metadata: { status: "expired", scopes: [...] }   (secrets redacted)
 ```
 
-For schema/transform issues (not auth issues), see `skill://apimapper/troubleshooting`.
+For schema/transform issues (not auth issues), see `apimapper_get_skill({ topic: "troubleshooting" })`.
+For the post-publish handoff into the YOOtheme Builder, see `apimapper_get_skill({ topic: "yootheme-source-to-builder-handoff" })`.

package/skills/apimapper/reference/troubleshooting.md

@@ -5,10 +5,10 @@ Diagnostic checklist when API Mapper tools return errors or flows misbehave. Wor
 ## Quick triage
 
 ```
-apimapper_diagnose(connection_id="conn_xyz")   # one-call summary
+apimapper_diagnose({ token: "amk_live_…", siteUrl: "https://example.com/wp" })   # validate a token+siteUrl pair
 ```
 
-`apimapper_diagnose` (Phase 8 composite tool) consolidates: credential state, last connection_test, recent error logs, license tier, schema profile. Use it FIRST before drilling into individual tools.
+`apimapper_diagnose` takes a **`token` + `siteUrl`** pair (NOT a `connection_id`). It runs token decode, an identity probe (WordPress first, Joomla fallback), an `iss`/site-URL match (anti-phishing), and capability + scope checks, then returns `ready: true/false` plus structured `blockers[]` and a recommendation. Use it FIRST when a token won't authenticate or before creating a profile — it pinpoints whether the problem is the token, the site URL, the platform, or a missing scope.
 
 If `apimapper_diagnose` is unavailable in your version, run the manual checks below.
 
@@ -79,6 +79,26 @@ If `apimapper_diagnose` is unavailable in your version, run the manual checks be
 ### "Source not appearing in YOOtheme Builder"
 - Flow is saved but not **published**. See `skill://apimapper/yootheme` step 4.
 
+### "YOOtheme Builder source list missing newly-published flow"
+
+Symptom: A flow was just published with `apimapper_flow_full_recompile_publish`, but
+YOOtheme Builder's source dropdown (or `yootheme_builder_sources_list` from the
+sibling MCP) doesn't show it. The schema cache went stale.
+
+Fix (one of):
+
+- `apimapper_cache_invalidate({ scope: "yootheme.schema" })` — explicit flush of the
+  YOOtheme GraphQL schema cache files (`schema-*.{php,gql,error.gql}`). Direct-file
+  surface, bypasses the InvalidationBus.
+- `apimapper_flow_full_recompile_publish({ id: ..., autofix: true })` — re-publish
+  with autofix. Since 2.0.8 (Wave-12 F8) this clears the schema-`.php`/`.gql`/`.error.gql`
+  triplets correctly.
+
+Root cause was a glob-pattern gap in `YOOthemeSchemaCacheBuster` pre-2.0.8 — the
+`.gql` file was the source-of-truth for YT's `LoadSourceSchema::handle()`, but only
+`.php` files were unlinked. The `yootheme.schema` scope is the manual escape hatch
+for customers still on cached state from before the fix landed.
+
 ### "Source shows but fields are empty"
 - Field-name case mismatch. YOOtheme expects lowercase keys.
 - Fix: Transform projection should lowercase: `[*].{title: name, image: cover_url}`.