@wootsup/mcp 0.3.0 → 0.4.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, 19-tool surface; 60 more behind `apimapper_advanced`; 79 total.
+Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transform → Output). One server, one Bearer key, 20-tool surface; 60 more behind `apimapper_advanced`; 80 total.
 
 ## Quickstart
 
@@ -44,7 +44,7 @@ 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_library_list({ search: 'sheets' })  # search for any API by name (param is `search`, 3+ chars)
 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
 ```
@@ -68,7 +68,7 @@ Tasks**, and more. Library activations come with:
 
 ## Step 2: Custom connection_create — ONLY when no template fits
 
-If `library_list({ query: '<api-name>' })` returns no match, fall back to
+If `library_list({ search: '<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
@@ -94,6 +94,81 @@ the audited override. Always prefer activation.
 
 For topic docs: `apimapper_get_skill topic="..."` or read `skill://apimapper/<topic>`.
 
+## Dynamize an existing designed layout ("keep the design exactly as it is")
+
+When the customer points at an EXISTING hand-designed section/page and wants it
+fed from your flow — *"bind these fields onto my section"*, *"the design must
+not change"*, *"use the layout from my X page"* — there is exactly one tool.
+
+> **Iron Law:** Dynamize an existing design ⇒ `yootheme_builder_page_dynamize`.
+> NEVER hand-edit layout JSON. NEVER `element_add` a "rebuild".
+
+The tool copies the reference subtree byte-identically server-side, swaps only
+the names you map, inserts nothing, rebuilds nothing, and publishes. You supply
+language-level inputs only.
+
+### The 3-step procedure
+
+1. **FIND the section** — `yootheme_builder_template_summary` → `named_sections`.
+   The customer's "X page" is often a NAMED SECTION inside another article, not
+   its own template. Copy the customer's NAMED section — never a category
+   template or a sibling mobile/card variant.
+2. **READ the flow** — `apimapper_yootheme_binding_for_flow({ flow_id })` →
+   the source name (`apiMapperFlow<Id>List`) + the flat field list.
+3. **DYNAMIZE — ONE call:**
+   ```jsonc
+   yootheme_builder_page_dynamize({
+     template_id, section_path,
+     source_name: "apiMapperFlowFcMatchesList",   // step 2
+     leaf_map: {
+       "field.home_team.crest.imagefile": "home_crest",  // nested original → flat flow field
+       "field.home_team.name":            "home_name",
+       "field.away_team.name":            "away_name",
+       "field.match_date":                "match_time"
+     },
+     publish: true
+   })
+   ```
+   FC-Greenfield: the flow emits FLAT records; the original binds NESTED
+   relational leaves. That mismatch is NOT a reason to rebuild — `leaf_map` just
+   renames leaves. Unmapped leaves are KEPT. Check `summary.unmatched_map_keys`
+   in the response.
+
+Full recipe (read before executing): `apimapper_get_skill topic="dynamize-existing-layout"`.
+
+### Rationalization table
+
+| Excuse | Reality |
+|--------|---------|
+| "My flow is flat but the design binds nested fields — I'll rebuild it" (R1) | Structure + every tuned prop transfer verbatim; `leaf_map` only renames leaves. Rebuilt-by-hand shipped 213px rows vs the 90px original. Copy, don't rebuild. |
+| "I'll add a column/slot for the league position" (R3) | INSERT NOTHING. Extra data goes INTO an existing leaf (compose `"AFC Richmond (3rd)"` in the flow). An inserted column collapsed sibling cells 213px→55px; names wrapped, crests overlapped. |
+| "I'll copy whichever row variant I find first" (R4a) | A section holds a desktop single-line row AND a mobile stacked card. Copying the card ships a 233px two-tier block. Copy the variant VISIBLE at the customer's desktop viewport (read `visibility` props). |
+| "This text field is close enough for the image slot" (R4b) | Binding a TEXT field (competition NAME) to an IMAGE prop renders a broken 0x0 image. Map image leaves to image/path fields only. Never invent an asset path — a guessed path 404s silently. |
+| "I'll copy from the category template, it looks the same" (R5) | The category template is NOT the customer's section — copying it shipped a 2-column masonry with missing date/matchday and 40px crests. Copy ONLY the customer's NAMED section from `template_summary`. |
+
+### Red flags — STOP
+
+- About to call `element_add` / `element_clone` while dynamizing → STOP.
+- About to write or hand-patch layout JSON → STOP, use the one call.
+- About to bind a TEXT field to an IMAGE prop → STOP, wrong field type.
+- About to invent an asset/image path you never read → STOP, it will 404.
+- About to copy a category template or mobile-card variant → STOP, copy the customer's named desktop section.
+
+All of these mean: one `yootheme_builder_page_dynamize` call against the right section.
+
+### Map COMPLETELY, then self-check
+
+Map EVERY bound leaf the section uses (incl. secondary slots like the TIME
+filter on a date leaf — a date-only field renders '0:00 AM'). After the call,
+read `summary`: `unmatched_map_keys` = your typos; `kept_unresolvable` = leaves
+that WILL render empty — extend `leaf_map` and re-run until both are empty.
+
+### Before you declare success
+
+Render the published URL and visually compare ONE row against the original at
+the customer's viewport. Same row height, no new wraps, images same size, same
+highlight count. "Similar but looser" = you rebuilt instead of copied — fail.
+
 ## Common Pitfalls
 
 - **Source not in YOOtheme Builder** → flow is *saved* but not *published*. Click Publish. Published name (not "API Mapper") appears in YOOtheme Source dropdown.

package/skills/apimapper/reference/dynamize-existing-layout.md

@@ -0,0 +1,158 @@
+# Dynamize an existing designed layout (keep the design EXACTLY as it is)
+
+Customer says: *"bind these fields onto my existing section"*, *"keep the design
+exactly as it is"*, *"use the layout from my X page"*, *"the design must not
+change"*. This topic is THE recipe for that job. It exists because two cold
+agents failed it the same way before it was written: one **rebuilt** the design
+element-by-element, one **inserted** an extra slot into the copied layout — both
+shipped visually broken pages that a human caught instantly.
+
+## The one rule
+
+**COPY the reference layout subtree byte-identically. Change ONLY leaf field
+names. Insert nothing. Rebuild nothing.**
+
+A designed YOOtheme section carries dozens of tuned props (`title_grid_width`,
+`image_align`, grid breakpoints, column `layout` strings) you cannot guess. Any
+hand-built "equivalent" renders visibly different — measured failures: 213px
+row height vs the original's 90px; one inserted column collapsed sibling cells
+from 213px to 55px so names wrapped and images overlapped text.
+
+## Pick the RIGHT variant before copying (F99)
+
+A designed section often contains MULTIPLE sibling variants of the same row —
+typically a compact single-line DESKTOP row AND a taller stacked CARD for
+mobile, switched via visibility props (`visibility: 'hidden@m'` etc.). Copying
+the stacked card produces a 233px two-tier block where the customer expects
+the 90px single-line row (measured failure). Before copying:
+
+1. List the candidate subtrees and read their `visibility` props.
+2. Copy the variant that is VISIBLE at the customer's desktop viewport —
+   usually the one hidden on small screens, not the one hidden on `@m`+.
+3. If unsure, copy ALL sibling variants together with their visibility props
+   intact (they are part of the design) — never just one of them.
+
+And when a leaf binds an IMAGE, map it to an image/path field — binding a TEXT
+field (e.g. a competition NAME) to an image prop renders a broken 0x0 image.
+
+## The loop — TWO discovery steps, then ONE call
+
+Steps 1-2 stay (you must tell the tool WHICH section and WHICH flow). Steps 3-5
+of the old hand-transform loop collapse into a **single
+`yootheme_builder_page_dynamize` call** — the server runs the deterministic
+copy-swap-write-publish itself. You supply only the language-level inputs (which
+section, which flow, and the leaf→field name map). This is the *hybrid
+execution* path: the recipe is now CODE, not a 100-call hand-edit.
+
+```
+1. FIND   yootheme_builder_template_summary → named_sections
+          (the customer's "X page" is often a NAMED SECTION inside another
+          article, not its own template; this is where the design lives)
+2. READ   apimapper_yootheme_binding_for_flow({ flow_id }) → the source name
+          (source_name_list = apiMapperFlow<Id>List) + the flat field list you
+          map leaves onto. (No page_get_layout hand-copy needed — the tool
+          reads the layout itself.)
+3. DYNAMIZE — ONE call:
+          yootheme_builder_page_dynamize({
+            template_id, section_path,
+            source_name: "apiMapperFlow<Id>List",
+            leaf_map: { "<original leaf field path>": "<your flat flow field>", … },
+            publish: true
+          })
+          The server copies the section subtree byte-identically, swaps the
+          iterating query name + every leaf field name from leaf_map, inserts
+          nothing, rebuilds nothing, and publishes. One call replaces the old
+          SWAP+WRITE+(manual)PUBLISH steps.
+4. VERIFY render the public URL and compare ONE row against the original at
+          the customer's viewport — wrap/overlap/missing icons are failures
+          even when the data is right.
+```
+
+### Worked example — the FC-Greenfield case
+
+The customer hand-designed a "Matches" section: each row is a single-line panel
+with a home crest, the two team names, a league-position meta, a kickoff time,
+and a "next match" highlight row. The flow (`flow_FcMatches`) emits a FLAT
+record — `home_crest`, `home_name`, `away_name`, `match_time`, `next` — while the
+original layout binds NESTED relational leaves
+(`field.home_team.crest.imagefile`, `field.home_team.name`, …). That mismatch is
+NOT a reason to rebuild; `leaf_map` just renames the leaves:
+
+```jsonc
+yootheme_builder_page_dynamize({
+  template_id:  "tpl_home",            // from template_summary
+  section_path: ".../section/matches", // the named section that holds the rows
+  source_name:  "apiMapperFlowFcMatchesList",   // binding_for_flow → source_name_list
+  leaf_map: {
+    // nested ORIGINAL leaf  →  your FLAT flow field
+    "field.home_team.crest.imagefile": "home_crest",
+    "field.home_team.name":            "home_name",
+    "field.away_team.name":            "away_name",
+    "field.match_date":                "match_time",
+    "field.is_next":                   "next"       // string '' / 'next' → highlight via _condition '!!'
+  },
+  publish: true
+})
+```
+
+The tool keeps the `#parent` repeater form and every tuned prop
+(`title_grid_width`, `image_align`, grid breakpoints, column `layout` strings)
+byte-identical; only the names inside `leaf_map` change. A leaf you have no flow
+field for is simply left OUT of `leaf_map` — the tool keeps its original binding
+(default KEEP). Per-row visibility (the one red "next" row) rides on the `next`
+string field via the copied `_condition` with `filters.condition: '!!'`.
+
+> **When `page_dynamize` is not available** (older yt-builder host, or you need a
+> shape it doesn't yet author): fall back to the hand-transform — read the
+> subtree with `yootheme_builder_page_get_layout`, apply the swaps in the JSON
+> yourself, and write it with `yootheme_builder_pages_create({ layout })`. The
+> `yootheme-source-to-builder-handoff` topic documents that `#parent`-JSON
+> anatomy in full. The hard rules below are exactly what the tool guarantees by
+> construction; if you hand-edit, you must honour them yourself.
+
+## Hard rules (the tool guarantees these by construction)
+
+`yootheme_builder_page_dynamize` enforces every rule in this section
+automatically — it copies the subtree, swaps only the `leaf_map` names, inserts
+nothing, and publishes. They are kept here as **background**: so you understand
+WHAT a design-exact dynamization is, and so that if you ever hand-edit the layout
+instead (the fallback above), you follow them yourself.
+
+These rules were learned from real failures:
+
+- **"My flow is FLAT but the original binds NESTED/relational fields" is NOT a
+  reason to rebuild.** Structure and props transfer verbatim; only leaf field
+  names change.
+- **INSERT NOTHING.** Extra data (a league position, a status) goes INTO an
+  existing bound leaf — compose it in the flow (`"AFC Richmond (3rd)"` as the
+  name value), never as a new element/column.
+- **Leaves you have no flow field for: default KEEP.** A static icon keeps its
+  original binding (or gets a flow constant). REMOVE a leaf only when its
+  TARGET cannot exist for the new data (a detail-link whose article doesn't
+  exist for API rows). Ask: "does this leaf's target still exist for my data?"
+- **Never invent asset paths.** If you didn't read the path from the layout or
+  an API response, don't guess one — a guessed path 404s silently.
+- **Per-row visibility (played vs upcoming vs highlight):** prefer emitting
+  string flags in the flow (`''`/`'next'`) and `_condition` with
+  `filters.condition: '!'`/`'!!'` in the copied JSON. If element-level tools
+  fight you, pre-filter in the FLOW (separate published lists per row group) —
+  that pattern passed a strict visual judge. The element-side bind/update tools
+  currently **cannot** author a filtered `_condition` (F95/F96/F97) — the
+  `yootheme-source-to-builder-handoff` topic's "Known tool limits when
+  authoring per-row visibility" section has the verified detail and the
+  pre-filtered-flows workaround.
+- The flow data work (connections, join, transforms) is unchanged by this
+  topic — see `merge-two-sources-on-key` and `jmespath-cookbook`.
+
+## Before you declare success — checklist
+
+- [ ] Section located via `template_summary` → `named_sections` (it may live
+      inside another article, not its own template)
+- [ ] Source name + flat fields read from `apimapper_yootheme_binding_for_flow`
+- [ ] Dynamization done in ONE `yootheme_builder_page_dynamize` call (or, on the
+      hand-edit fallback, the layout JSON came from `page_get_layout` — never
+      hand-built — with zero elements added/removed without a documented reason)
+- [ ] `leaf_map` covers every leaf you have a flow field for; unmapped leaves are
+      left KEPT (default), removed only with a "target cannot exist" reason
+- [ ] Published + routed (anonymous visitors can load it)
+- [ ] One row visually compared against the original at the target viewport

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

@@ -0,0 +1,241 @@
+# JMESPath Cookbook
+
+Copy-paste recipes for the Transform node. Every recipe below is verified
+against the actual API Mapper JMESPath engine (same one the Transform pipeline
+runs). For the trap list and date/number primitive reference, see
+`jmespath-pitfalls`. For joining two sources, see `merge-two-sources-on-key`.
+
+> **Iterate with `apimapper_jmespath_test`.** Before you wire an expression into
+> a Transform node, dry-run it: `apimapper_jmespath_test({ expression, sample_rows })`
+> returns `{ result, row_count }`, and a bad expression returns the SAME
+> teaching hint (arithmetic, depth-split) you'd hit at flow time — but instantly,
+> with no flow to clean up. Grab real rows with `apimapper_connection_data` first.
+
+---
+
+## If / else — `conditional()` (preferred) or the `(cond && X) || Y` ternary
+
+JMESPath has no native `if/else` statement. API Mapper ships a `conditional()`
+primitive AND the classic short-circuit ternary; pick whichever reads cleaner.
+
+### `conditional(condition, then_value [, else_value])`
+
+```jmespath
+[*].{
+  name: name,
+  status: conditional(stock > `0`, 'in stock', 'sold out')
+}
+# {stock:5} → "in stock"   {stock:0} → "sold out"
+```
+
+Returns `then_value` when `condition` is truthy, `else_value` (default `null`
+when omitted) when falsy. Truthiness mirrors the engine: `false`, `null`,
+`''`, `[]`, `{}` are falsy; **everything else — including `0` — is truthy**.
+
+It is flatter and more readable than the ternary for a simple two-way branch,
+and it **side-steps the ternary's falsy-`X` trap**: `conditional(cond, '', Y)`
+returns the empty string verbatim, whereas `(cond && '') || Y` would wrongly
+fall through to `Y`. (It is not "free" against the depth cap — a function call
+still costs +1 nesting level — but for the simple case it reads better.)
+
+### Ternary — `(cond && X) || Y`
+
+The short-circuit idiom: when `cond` is truthy the `&&` yields `X`; otherwise
+the `||` falls through to `Y`.
+
+```jmespath
+[*].{
+  name: name,
+  status: (stock > `0` && 'in stock') || 'sold out'
+}
+# {stock:5} → "in stock"   {stock:0} → "sold out"
+```
+
+**Gotcha:** if `X` itself can be falsy (e.g. the string `''`, `0`, `false`), the
+`|| Y` branch fires even when `cond` was true. Keep `X` a non-empty constant,
+use `conditional()` instead, or restructure. For a numeric comparison on a
+string field, cast first: `(to_number(price) > \`100\` && 'premium') || 'standard'`.
+You can chain ternaries for >2 branches (`(a && 'x') || (b && 'y') || 'z'`);
+`conditional()` covers the two-way case.
+
+---
+
+## String composition — `join`
+
+`join(separator, array_of_strings)` concatenates. All elements must be strings —
+cast numbers with `to_string()`.
+
+```jmespath
+# "A - 5"
+[*].join(' - ', [name, to_string(stock)])
+
+# Prefix a currency symbol onto a formatted number
+[*].{price: join('', ['$', format_number(price)])}
+# {price:"890000"} → "$890,000"
+
+# Build a full address from parts
+[*].{label: join(', ', [street, city, country])}
+```
+
+To concatenate with no separator, pass `''` as the first arg.
+
+---
+
+## Empty / filled field as a condition (result-pattern)
+
+To branch on whether a field is present-and-non-empty, reuse the ternary —
+an empty string, `null`, or `[]` is falsy:
+
+```jmespath
+[*].{
+  name: name,
+  has_tags: (tags && 'yes') || 'no'
+}
+# {tags:["x"]} → "yes"   {tags:[]} → "no"   {missing} → "no"
+```
+
+To FILTER to only the filled rows:
+
+```jmespath
+[?image_url]                       # keeps rows whose image_url is non-empty
+[?length(tags) > `0`]              # keeps rows with at least one tag
+[?contains(keys(@), 'price')]      # keeps rows where the KEY exists (any value)
+```
+
+(See pitfall #8 in `jmespath-pitfalls` for empty-array vs missing-key.)
+
+---
+
+## Sorting — `sort_by`
+
+`sort_by(array, &field)` sorts ascending by a field. Wrap in `reverse(...)` for
+descending. The `&` makes an expression-reference (don't forget it).
+
+```jmespath
+# Ascending by price
+sort_by([*], &price)
+
+# Descending by date, then take the first 3
+reverse(sort_by([*], &published_at))[:3]
+
+# Sort, then project just the names
+sort_by([*], &stock)[*].name
+```
+
+`sort_by` needs a comparable key. If the field is a numeric STRING, sorting is
+lexical (`"100" < "20"`); normalise upstream or accept string order.
+
+---
+
+## Coordinate keys for a Map element
+
+YOOtheme's Map element binds a `coordinates` array `[lat, lng]`. Build it inline:
+
+```jmespath
+[*].{
+  title: title,
+  coordinates: [lat, lng]
+}
+# → [{ title: "HQ", coordinates: [52.5, 13.4] }]
+```
+
+If lat/lng arrive as strings, cast: `coordinates: [to_number(lat), to_number(lng)]`.
+
+---
+
+## Number formatting — `format_number`
+
+`format_number(value [, decimals=0 [, decimal_sep='.' [, thousands_sep=',']]])`
+groups thousands. Accepts numbers OR numeric strings; returns `null` on
+non-numeric input.
+
+```jmespath
+# 890000 → "890,000"
+[*].{name: name, price: format_number(price)}
+
+# Two decimals: 1234.5 → "1,234.50"
+format_number(`1234.5`, `2`)
+
+# European grouping: 1234567.89 → "1.234.567,89"
+format_number(price, `2`, ',', '.')
+
+# Guard a column with stray non-numeric rows
+[*].coalesce_empty(format_number(price), 'n/a')
+```
+
+---
+
+## Date primitives — weekday / time / date / window
+
+JMESPath has no native date support; API Mapper ships four primitives. The
+optional last arg is an IANA timezone (`'Europe/Berlin'`, `'America/New_York'`,
+`'UTC'`); omit it to keep the offset already in the string. All return `null`
+(or `false` for `time_in_window`) on malformed input.
+
+```jmespath
+# Calendly slot → Sheet-comparable weekday + local time
+[*].{
+  day:        date_weekday(start_time, 'Europe/Berlin'),     # "Wednesday"
+  local_time: date_iso_to_time(start_time, 'Europe/Berlin'), # "09:30"
+  ymd:        date_iso_to_date(start_time, 'Europe/Berlin')  # "2026-06-03"
+}
+
+# Keep only slots inside business hours
+[?time_in_window(date_iso_to_time(start_time, 'Europe/Berlin'), '09:00', '17:00')]
+
+# Cross-midnight window (10pm..2am): from > to is supported
+[?time_in_window(local_time, '22:00', '02:00')]
+```
+
+See `merge-two-sources-on-key` for using these to join a weekday-name source
+against an ISO-datetime source.
+
+---
+
+## Two-Transform split against the depth limit
+
+Expression depth is capped at **10** levels of bracket / pipe nesting. A pipe
+`|` resets the depth counter, so the universal fix for a "too deeply nested"
+422 is to **split one Transform into two piped together** — either inside one
+expression with a pipe, or as two separate Transform nodes wired in series.
+
+```jmespath
+# Too deep — slice + multi-level hash in one breath
+[1:][*].{day: [0], hours: {open: [1], close: [2], extra: {note: [3]}}}
+
+# Fixed — pipe resets, second stage starts fresh and shallow
+[1:] | [*].{day: [0], hours: {open: [1], close: [2]}}
+```
+
+If you hit the cap, also reconsider whether you need the nesting at all — flat
+`[*].{a: x, b: y}` bucket shapes are almost always enough for a YOOtheme
+binding. (Full walk-through: `jmespath-pitfalls` → "Depth-cap warning".)
+
+---
+
+## GIBT-ES-NICHT — things JMESPath does NOT have (and the workaround)
+
+Stop trying these — they raise a syntax error (now annotated with a hint) or
+silently misbehave. Use the workaround.
+
+| You want… | Does NOT exist | Workaround |
+|-----------|----------------|------------|
+| Arithmetic `a + b`, `a - b`, `a * b`, `a / b` | No arithmetic operators at all. `price + tax` is a **syntax error** (annotated *"JMESPath has no arithmetic operators"*). | Compute upstream (in the API, a spreadsheet, or an n8n step), or in a YOOtheme element. For display-only concatenation use `join('', [a, b])`. |
+| Split a string `split(s, ',')` | No `split`. | Pre-split upstream, or if the API returns an array use it directly. For a CSV cell, request a structured endpoint instead. |
+| Regex match / replace | No regex. | Use `contains(@, 'substr')`, `starts_with`, `ends_with` for membership. For replace, normalise the data upstream. |
+| `if / else` / `switch` | No statement forms. | `conditional(cond, X, Y)` (flat, two-way) or the ternary `(cond && X) || Y` (above). Chain ternaries for >2 branches: `(a && 'x') || (b && 'y') || 'z'`. |
+| Uppercase / lowercase | No case functions. | Normalise casing upstream (the source API or a Transform-feeding step). |
+| Sum / count-with-condition | No `sum`/aggregate over a predicate. | `length([?cond])` counts matching rows. For a real sum, aggregate upstream. |
+| Date math (`+ 1 day`) | No date arithmetic. | Use the date primitives for extraction/formatting/windowing only; do calendar math upstream. |
+
+When in doubt, paste the expression into `apimapper_jmespath_test` — a failing
+expression tells you exactly which of these you tripped over.
+
+---
+
+## See also
+
+- `jmespath-pitfalls` — the 9 traps + primitive reference + depth-cap detail.
+- `merge-two-sources-on-key` — joining two sources, with date-primitive bridging.
+- `conditional-style-multi-items` — per-row YOOtheme styles from a row field.
+- `yootheme-source-to-builder-handoff` — where the empty/filled string fields you build here drive a theme layout's `_condition` (`'!'`/`'!!'`) in the `#parent` repeater form.

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

@@ -85,6 +85,87 @@ Cross-midnight windows (bars, support shifts):
 [?time_in_window(local_time, '22:00', '02:00')]   # 10pm..2am
 ```
 
+## Number formatting — `format_number()`
+
+JMESPath has no arithmetic and no number-format support, so a price field
+arrives as raw digits and renders as `$890000` instead of `$890,000`. The
+`format_number()` primitive (new in 2.0.13) groups thousands and fixes
+decimals — the number-format analogue of the date primitives above.
+
+| Signature | Returns |
+|-----------|---------|
+| `format_number(value [, decimals [, decimal_sep [, thousands_sep]]])` | grouped string, or `null` on non-numeric input |
+
+- `value` — a number OR a numeric string (Sheets/REST often deliver `"1250000"`). Anything non-numeric (including `true`/arrays/empty string) → `null`.
+- `decimals` — digits after the decimal separator (default `0`). Rounds half-up.
+- `decimal_sep` — default `"."`.
+- `thousands_sep` — default `","`.
+
+```jmespath
+# US dollars, no cents — the SunWest case
+[*].{name: name, price_display: format_number(price)}
+#   890000   → "890,000"
+#   1450000  → "1,450,000"
+```
+
+```jmespath
+# Two decimals
+format_number(`1234.5`, `2`)            # "1,234.50"
+
+# European grouping (1.234.567,89)
+format_number(price, `2`, ',', '.')
+```
+
+Prefix the currency symbol in the same expression with `join`:
+
+```jmespath
+[*].{price: join('', ['$', format_number(price)])}   # "$890,000"
+```
+
+Because `format_number` returns `null` on bad input, wrap it with
+`coalesce_empty` when a column may contain stray non-numeric rows:
+
+```jmespath
+coalesce_empty(format_number(price), 'n/a')
+```
+
+> Reminder: JMESPath still has **no arithmetic operators** (`+ - * /`). If you
+> try `price + tax` the engine raises a syntax error now annotated with
+> *"JMESPath has no arithmetic operators"*. Compute totals upstream, in a
+> YOOtheme element, or concatenate strings with `join('', [a, b])`.
+
+## Logic primitive — `conditional()`
+
+JMESPath has no `if/else` statement. The classic workaround is the
+short-circuit ternary `(cond && X) || Y`, but it has a sharp edge: when `X` is
+itself falsy (`''`, `0`, `false`) the `|| Y` branch fires even though `cond` was
+true. The `conditional()` primitive is a flat, readable if/else without that
+trap.
+
+| Signature | Returns |
+|-----------|---------|
+| `conditional(condition, then_value [, else_value])` | `then_value` when `condition` is truthy; `else_value` (default `null`) when falsy |
+
+Truthiness mirrors the engine: `false`, `null`, `''` (empty string), `[]`
+(empty array) and `{}` (empty object) are falsy — **everything else, including
+`0`, is truthy**.
+
+```jmespath
+# per-row in-stock badge from a stock field
+[*].{name: name, in_stock: conditional(stock > `0`, 'in stock', 'sold out')}
+#   {stock:5} → "in stock"   {stock:0} → "sold out"
+
+# returns a falsy then-value verbatim — no ternary fall-through
+[*].{label: conditional(is_featured, '', 'standard')}
+#   is_featured truthy → ""   (the ternary (is_featured && '') || 'standard' would
+#   have wrongly returned "standard")
+```
+
+`conditional()` is **flatter and more readable** than the ternary for a simple
+two-way branch — but it does NOT dodge the depth cap: a function call still
+costs `+1` nesting level. For >2 branches, chain ternaries
+(`(a && 'x') || (b && 'y') || 'z'`); `conditional()` covers the two-way case.
+
 ## 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)`.

package/skills/apimapper/reference/library-template-discovery.md

@@ -16,7 +16,7 @@ to debug from downstream tool calls.
 
 ```
 apimapper_library_featured({})                       # 1. the curated short-list
-apimapper_library_list({ query: '<api-name>' })      # 2. search the full catalog by name
+apimapper_library_list({ search: '<api-name>' })     # 2. search the full catalog by name (param is `search`, 3+ chars)
 apimapper_library_connection_detail({ id: '<id>' })  # 3. read the template's full contract
 apimapper_credential_list({})                        # 4. find a matching credential (auth-protected templates)
 apimapper_library_activate({ id, credential_id, extra_fields })  # 5. activate, fully configured