@wootsup/mcp 0.3.0 → 0.4.0

package/skills/apimapper/reference/yootheme-source-to-builder-handoff.md

@@ -0,0 +1,348 @@
+# Handoff: API Mapper source → YOOtheme Builder element
+
+This is the bridge between the two halves of the job: you have a **published API Mapper flow** (built and published on THIS server), and you want it to actually drive a YOOtheme Builder element (Grid / List / Slider / **Map**) on the page. The element-side work happens on the **yt-builder-mcp** server, through its `yootheme_builder_*` tools. This topic walks the exact call sequence and the three things that bite cold agents: the `*_item` binding level, the `field_mappings` full-replace semantics, and the `map_item.location` `'lat,lng'` contract.
+
+> **Two servers.** Steps 1–2 are API Mapper (`apimapper_*`). Steps 3–5 are yt-builder-mcp (`yootheme_builder_*`). `apimapper_yootheme_binding_for_flow` is the only tool that spans the boundary — it tells you the exact source name + field names the yt-builder bind call needs.
+
+## The end-to-end sequence
+
+### Step 1 — Publish the flow (API Mapper)
+
+```jsonc
+apimapper_flow_full_recompile_publish({ flow_id: "flow_abc" })
+```
+
+This registers the flow as a YOOtheme source and flushes the schema cache. **Always** use this (not a bare compile) — derived/Transform fields are invisible downstream until a recompile-publish.
+
+### Step 2 — Discover the source name + bindable fields (API Mapper)
+
+```jsonc
+apimapper_yootheme_binding_for_flow({ flow_id: "flow_abc" })
+// → {
+//   source_name_singular: "apiMapperFlowAbc",
+//   source_name_list:     "apiMapperFlowAbcList",   // the Multi-Items target
+//   fields: [ { name: "title", type: "String" }, { name: "location", ... }, ... ],
+//   example_field_mappings: { title: "name", content: "popup_body", ... },
+//   ready_for_binding: true
+// }
+```
+
+- `source_name_list` is the **Multi-Items** target (grid / list / slider / map — one container, N children).
+- `source_name_singular` is the single-item wrapper (rare; for a single record).
+- `ready_for_binding: false` means the flow isn't compiled or its output node has no schema fields — fix that before binding.
+
+### Step 3 — Read the element's ETag (yt-builder-mcp)
+
+The bind tool is a write and requires an ETag (optimistic lock):
+
+```jsonc
+yootheme_builder_get_etag({ template_id: "tpl_home" })
+// → { etag: "W/\"…\"" }
+```
+
+### Step 4 — Bind the source on the `*_item` CHILD (yt-builder-mcp)
+
+`yootheme_builder_element_bind_source` is a **first-class** tool in `tools/list` (promoted to L1 by F116). Call it **directly**:
+
+```jsonc
+yootheme_builder_element_bind_source({
+  template_id:  "tpl_home",
+  element_path: "…/grid_item",          // the *_item child, NOT the grid container
+  source_name:  "apiMapperFlowAbcList", // the LIST name from step 2
+  bindingLevel: "item",
+  field_mappings: {
+    title:   "name",
+    content: "popup_body",
+    image:   "photo"
+  },
+  etag: "W/\"…\""
+})
+```
+
+> **Older server builds (pre-F116).** If your yt-builder-mcp host plugin predates the F116 promotion, the bind tool is still an *advanced* tool and a direct call returns `unknown tool`. On those builds, reach it through the gateway: `yootheme_builder_advanced({ tool: "yootheme_builder_element_bind_source", arguments: { … } })`. On a current build the gateway wrap returns `unknown_tool` — call the tool directly.
+
+### Step 5 — Publish the page and verify
+
+Publish via the yt-builder page tools, then confirm the element renders N children with real field values (not defaults / blanks).
+
+## Rule 1 — Bind on the `*_item` child, never the container
+
+For "1 container with N dynamic children", bind `source` + Multi-Items on the **`*_item` child**, never on the container. YT Pro clones the source-bearing element N times as siblings of its parent — binding on a `grid` produces N stacked grids, not 1 grid with N children.
+
+| Container | Bind target (the child) |
+|-----------|-------------------------|
+| `grid` | `grid_item` |
+| `list` | `list_item` |
+| `slider` | `slider_item` |
+| `slideshow` | `slideshow_item` |
+| `map` | `map_item` |
+
+`bindingLevel: "item"` makes a container `element_path` auto-resolve to its first `*_item` child; `bindingLevel: "container"` binds on the container and the response carries a cloning warning. When the target is already a leaf under a bound `*_item`, the tool auto-uses the YT-Pro INHERIT form (`__node_item__` sentinel) — a standalone query there renders empty on YT5/Joomla.
+
+## Rule 2 — `field_mappings` is a FULL REPLACE, not a merge (F43)
+
+Each `yootheme_builder_element_bind_source` call writes `source.props` **from scratch** out of the `field_mappings` you pass — it does **not** merge with the prior binding. Whatever you omit is dropped. So:
+
+- To refine one mapping, re-send **all** the mappings you want to keep, every call.
+- A bind call with `field_mappings: { content: "popup_body" }` after one with `{ title: "name", content: "old" }` leaves the element bound to `content` only — `title` is gone.
+
+Treat `field_mappings` as the complete desired prop→field map, not a patch.
+
+## Rule 3 — Map needs ONE `'lat,lng'` location field (A9 / F39)
+
+A `map_item` positions each pin from a **single** `location` field formatted `"lat,lng"`. Source APIs almost always deliver `lat` and `lng` as **separate** numeric fields, so you must synthesize the combined field in a Transform node BEFORE publishing:
+
+```jsonc
+// Transform projection (API Mapper side, step 0 — before step 1):
+[*].{
+  title:    name,
+  location: join(',', [to_string(lat), to_string(lng)]),   // "37.77,-122.41"
+  popup_body: name           // or a composed derived field — see below
+}
+```
+
+Then bind `location` on the `map_item`:
+
+```jsonc
+yootheme_builder_element_bind_source({
+  template_id, element_path: "…/map_item", source_name: "apiMapperFlowAbcList",
+  bindingLevel: "item",
+  field_mappings: { location: "location", title: "title", content: "popup_body" },
+  etag
+})
+```
+
+> **Silent zero-pin trap.** If `location` is left unbound, the Map renders structurally fine and the inspector reports it "correct" — but **zero pins** appear. Always bind `location`, and verify pins after publish.
+
+### Rich popups beyond the 4 slots (F42)
+
+A `map_item` popup has only `title` / `meta` / `content` / `image`. For more facets, compose them into one **derived field** in the Transform (`popup_body` above), then bind it to `content` — see `apimapper_get_skill({ topic: "yootheme" })` for the full derived-field recipe.
+
+## Rule 4 — Schema-changing Transform edits force recompile → re-bind (F44)
+
+Any Transform edit that adds or renames a field (a new derived `location`, a new `popup_body`) is **invisible** to `apimapper_yootheme_binding_for_flow` and to the yt-builder bind call until you re-publish. The loop is:
+
+```
+edit Transform  →  apimapper_flow_full_recompile_publish  →
+apimapper_yootheme_binding_for_flow (re-read fields)  →  re-bind (full field_mappings)
+```
+
+Skipping the recompile leaves you binding against the OLD schema — the new field name resolves to nothing and the element renders blank.
+
+## Two binding shapes — pick the one that matches the job
+
+Everything above is the **`field_mappings` shape**: you bind a flow into a *fresh* Builder element (a blank grid / list / map you just dropped in) and let `element_bind_source` author the `source.props` for you. That is the right shape for "build me a new grid from this API".
+
+There is a SECOND shape you reach for when the goal is **"dynamize an EXISTING, already-designed theme layout"** — the customer hand-built a beautiful section (match rows with logos, badges, a red highlight row) and just wants those *same* rows fed from your flow, pixel-identical. There you do NOT bind through `field_mappings`; you read the layout's own JSON and swap the query. This is the **theme-canonical `#parent` repeater form**, the form YT5 itself emits and renders. (Cold agents have hand-authored it twice successfully; it is documented here so you don't have to reverse-engineer it from a `page_get_layout` dump again.)
+
+> **For dynamizing an EXISTING layout, prefer `yootheme_builder_page_dynamize`
+> (one call).** It runs the copy-swap-write-publish below for you — you supply
+> only the section, the source name, and a `leaf_map` of leaf→field names. See
+> `apimapper_get_skill({ topic: "dynamize-existing-layout" })` for the worked
+> example. The `#parent` anatomy below is **background + fallback**: read it to
+> understand what the tool authors by construction, and use it for the
+> hand-edit path when `page_dynamize` is unavailable or can't author a shape you
+> need.
+
+### The `#parent` repeater anatomy
+
+An iterating list in a theme layout has three layers:
+
+1. **The repeating element** (a `column`, `panel`, row item, …) carries the source query:
+   ```jsonc
+   "source": { "query": { "name": "customArticles", "arguments": { … } } }
+   ```
+   **To dynamize it, swap ONLY that query name** to your published flow's LIST source:
+   ```jsonc
+   "source": { "query": { "name": "apiMapperFlow<Id>List" } }   // from binding_for_flow → source_name_list
+   ```
+   The swap *is* the dynamization — the rest of the designed markup is untouched.
+
+2. **The child `fragment`** = the clone body. It binds to the parent iteration via the `#parent` sentinel:
+   ```jsonc
+   "source": { "query": { "name": "#parent" } }
+   ```
+
+3. **Each leaf** (the bits that actually print a value) reads `#parent` plus a `props.content` pointing at one field, with formatting filters living **inside the binding**:
+   ```jsonc
+   "source": {
+     "query": { "name": "#parent" },
+     "props": { "content": { "name": "field.match_date", "filters": { "date": "D, d.m.y" } } }
+   }
+   ```
+   Field names use dot-paths (`field.match_date`, `club_crest.imagefile`). For a nested object, the leaf uses the subquery form: `"query": { "name": "#parent", "field": { "name": "field.match_home_team", "directives": [ … ] } }`.
+
+### `_condition` only bites with a `filters.condition` operator
+
+A leaf or element shows/hides via `_condition` — but `_condition: { name: X }` **alone is wireless** (it renders unconditionally). The operator must ride in `filters.condition`:
+
+- `"filters": { "condition": "!" }` → render only when the field is **EMPTY**.
+- `"filters": { "condition": "!!" }` → render only when the field is **FILLED**.
+
+### Boolean fields filter unreliably → use empty/filled STRING semantics
+
+Do **not** drive a `_condition` off a boolean flow field (`played`, `is_next`) — boolean binding is unreliable here. Instead, make the flow emit a **string that is empty or filled**, then condition on `!`/`!!`:
+
+```jsonc
+// Transform projection (API Mapper side):
+{
+  "result": "(played && score) || ''",        // '' when not played → hide score block with '!'
+  "next":   "(is_next && 'next') || ''"        // '' unless next → show the red highlight row with '!!'
+}
+```
+
+So the per-row highlight (exactly one red "next match" row) is just: emit `next` as `''`/`'next'`, then `_condition` with `filters.condition: '!!'` on the highlight element.
+
+### The dynamize-an-existing-layout loop
+
+```
+page_get_layout (read the section's JSON)
+  → find the repeating element's source.query.name
+  → swap it to apiMapperFlow<Id>List
+  → remap each leaf's props.content to your flow's field names (keep the filters)
+  → convert any boolean _condition to a '!'/'!!' string condition
+  → write the layout back (page create/update)
+```
+
+**This loop is the ONLY path to a design-exact result. COPY the reference
+subtree — NEVER rebuild the design element-by-element with `element_add`.**
+A hand-rebuilt "equivalent" layout renders visibly different (measured on the
+FC-Greenfield probe: 213px row height vs the reference's 90px, wrapped team
+names, missing league icon, missing CTA column) and FAILS any visual judge.
+The reference JSON carries dozens of tuned props (`title_grid_width`,
+`image_align`, grid breakpoints, column `layout` strings) you will not guess.
+
+**INSERT NOTHING into the copied subtree either.** Adding even ONE extra
+column/slot (e.g. a new "league position" text next to the matchup) shifts
+every sibling's computed width — measured on a probe: team-name cells
+collapsed from 213px to 55–67px, UIkit fell back to `uk-grid-stack`, names
+wrapped and crests overlapped the text. Extra data goes into EXISTING leaves:
+compose it into a field your flow already feeds a bound leaf with (e.g.
+`"AFC Richmond (3rd)"` as the team-name value, or the meta line) — never into
+a new element. Copy = byte-identical structure; only leaf field NAMES change.
+
+**KEEP every leaf you have no flow field for** (a static league/matchday icon,
+decorative images): leave its original binding untouched or feed it a flow
+constant. REMOVE a leaf only when its target cannot exist for the new data
+(e.g. a "go to review" link whose target article doesn't exist for sheet
+rows) — default KEEP, remove only with a reason. And NEVER invent asset paths:
+if you did not read the path from the reference layout or an API response, do
+not guess one (a guessed `…-league-logo.svg` 404s silently).
+
+**"But the original binds RELATIONAL/nested fields and my flow is FLAT" is
+NOT a reason to rebuild.** The element STRUCTURE and all its props transfer
+verbatim regardless of the binding shape. Only the leaf `source.props.*.name`
+values change: a nested original leaf like
+`field.match_home_team.club_crest.imagefile` simply becomes your flat field
+name (`home_crest`). Keep every other prop byte-identical. If the original
+leaves bind via `#parent`, keep the `#parent` query form too — just swap the
+field names inside `props`.
+
+Practical copy mechanics: take the section subtree from `page_get_layout`,
+perform the swaps above on the JSON, then create the page with
+`yootheme_builder_pages_create({ layout })` (or write a full layout via the
+pages update path). One write — no element-by-element surgery.
+
+### Leaves you have no flow field for: default KEEP, remove only with a reason
+
+When you copy the reference subtree you will hit leaves that your flow does
+**not** supply a value for — a static matchday/league icon, a divider image, a
+decorative crest. **The default is KEEP, not delete.** Deleting a leaf changes
+the visual composition the design depends on, so removal needs an explicit
+justification on a per-leaf basis. The two correct ways to keep an unmapped
+leaf:
+
+- **Static asset (an image / icon that never varies):** leave its binding
+  **exactly as the reference had it** — a static `image` URL or a theme asset
+  reference renders the same icon for every cloned row. Do not touch it.
+- **A value the flow can supply as a constant:** bind it to a **flow constant**
+  field (emit a fixed string from the Transform, e.g. `"league": 'Premier'`)
+  and point the leaf's `props.content` at that field. The icon/value is now
+  uniform across rows but flows through the same `#parent` plumbing.
+
+**Only REMOVE a leaf when its TARGET cannot exist for the new data.** The
+canonical example from the FC-Greenfield probe: the original row carried a
+`GO TO MATCH REVIEW` link whose `href` resolved to a CMS *article* per match.
+Sheet rows have **no backing article**, so that link target genuinely does not
+exist — removing that one leaf is **CORRECT**. Contrast the league icon in the
+same probe: it is a *static* asset with a target that still exists, so dropping
+it was a **regression** (the R2 visual delta flagged "missing league icon").
+Same probe, opposite verdicts — because one target vanished for sheet data and
+the other did not.
+
+Rule of thumb when judging a copy: walk every leaf and ask *"does this leaf's
+target still exist for my data?"* — KEEP if yes (static asset or flow
+constant), REMOVE only when the answer is a concrete no.
+
+### Authoring per-row visibility through `bind` — RESOLVED 2026-06-10 (F96 / F97); F95 still open
+
+**F96 / F97 — RESOLVED 2026-06-10.** You CAN now author a *filtered*
+`_condition` (e.g. "show this block only for played matches") directly through
+`element_bind_source` — no separate pre-filtered flows, no hand-authored
+`#parent`-JSON layout write. The fix landed in the yt-builder bind tool
+(`builders.ts` field_mappings, F96/F82, 2026-06-10): a `field_mappings` entry
+may now be an **object** carrying the operator, not just a bare field-name
+string.
+
+**The object-form `field_mappings` (the one-call recipe).** A mapping value is
+EITHER the old string (`element_prop: "source_field"`) OR an object
+`{ name, filters }` that rides a `filters.condition` operator straight onto the
+leaf:
+
+```jsonc
+yootheme_builder_element_bind_source({
+  template_id:  "tpl_home",
+  element_path: "…/grid_item",          // the *_item child, NOT the container
+  source_name:  "apiMapperFlowAbcList",
+  bindingLevel: "item",
+  field_mappings: {
+    // plain string mapping — unconditional
+    title:   "name",
+    content: "popup_body",
+    // OBJECT mapping — binds the field AND a filtered _condition in ONE call.
+    // '!!' → render only when `next_marker` is FILLED (the highlight row).
+    highlight: { name: "next_marker", filters: { condition: "!!" } }
+    // '!'  → render only when the field is EMPTY.
+  },
+  etag: "W/\"…\""
+})
+```
+
+`handlers-bind.ts` forwards the object-form verbatim and the PHP side
+normalises it, so the `filters.condition` lands as a real, wired `_condition`
+on the leaf — exactly the operator the `#parent`-JSON layout write produces.
+This is the one-call path: **bind the field and its visibility condition
+together**; you no longer need a separate flow per visibility bucket just to get
+per-row show/hide.
+
+> Same `'!'` / `'!!'` string-semantics rule as above applies — drive the
+> condition off a flow field that is **empty or filled** (emit `''` / `'next'`),
+> not off a raw boolean (`played`, `is_next`), because boolean binding is
+> unreliable here.
+
+**F95 — still OPEN: large inline-layout `pages_create` drops its params.** When
+the inline layout JSON gets large (~10 KB+), the create call's parameters are
+dropped in transit (an empty page is created); a single-row create (~4 KB) goes
+through fine. **Workaround:** write the layout in **smaller chunks** — one
+row-block create that goes through, then add the remaining rows — rather than
+one ~10 KB inline create.
+
+## F81 — Finding the design: it may be a NAMED SECTION inside another article
+
+The page the customer calls "the X page" frequently is **not its own template** — it is a **named section embedded inside another article** (e.g. the "Matches" rows live as a named section in the Home article). If `pages_list` / a route lookup doesn't surface it, don't assume it's missing.
+
+**Discovery tool:** `yootheme_builder_template_summary` lists a template's `named_sections`. Scan those to locate the design, then `page_get_layout` that template and work on the section's subtree. This turns a multi-scan hunt into one lookup.
+
+## F91 — Article-context cells render ~20% narrower than category templates
+
+The SAME layout JSON gets **~20% less cell width** in an **article context** than in a **category template** (measured ≈200px vs ≈253px on the FC match rows). So enrichment bindings you add to a designed row — an extra crest image, a meta line, a second value in a panel — can **wrap** in the article context even though they fit in the category template the design was lifted from.
+
+- After adding any enrichment binding (logo + meta on a panel, a second score line), **verify visually at the target viewport** — a text/DOM check will pass while the row visibly wraps.
+- If it wraps, drop the enrichment or move it to a slot with more room; do not assume "fits in the source template ⇒ fits here".
+
+## Related topics
+
+- `apimapper_get_skill({ topic: "yootheme" })` — publishing flows as sources; the derived-field rich-popup recipe.
+- `apimapper_get_skill({ topic: "merge-two-sources-on-key" })` — when the source itself is a merge of two APIs.
+- `apimapper_get_skill({ topic: "jmespath-pitfalls" })` — Transform projection traps + the date/number primitives used to synthesize derived fields.
+- `apimapper_get_skill({ topic: "jmespath-cookbook" })` — copy-paste recipes, incl. the two-transform split for the depth limit you hit when composing the string-condition fields above.

package/skills/apimapper/reference/yootheme.md

@@ -2,6 +2,8 @@
 
 API Mapper sources show up in the YOOtheme Builder Source dropdown ONLY when a flow ends in a YOOtheme Output node and the flow is **published** (not just saved). This is the most common "source isn't appearing" cause.
 
+> **REST tools only.** Build flows with the real `apimapper_*` REST tools below — `flow_setup_with_sources`, `flow_create`, `flow_update`, `flow_full_recompile_publish`, `yootheme_binding_for_flow`. This server has no UI-automation node-editing tools (the `add-node` / `configure-output` style tools belong to a separate UI MCP and are not callable here). To go from a published source into the actual Builder element, see `apimapper_get_skill({ topic: "yootheme-source-to-builder-handoff" })`.
+
 ## The publish pipeline
 
 ```
@@ -16,49 +18,82 @@ Source ─► [Filter] ─► [Transform] ─► [Merge] ─► Output
 
 Both output types can coexist on the same flow.
 
-## Step-by-step
+## Step-by-step (REST)
 
-1. **Build the flow** via `apimapper_flow_create` + `apimapper_app_add_node` calls, or one-shot via `apimapper_flow_setup_with_sources`.
+1. **Build the flow.** The one-shot path lays out source → (merge) → (filter) → output for you, including the YOOtheme output node:
 
-2. **Add a YOOtheme Output node** (NOT Shortcode):
-   ```
-   apimapper_app_configure_output(
-     flow_id="flow_abc",
-     output_type="yootheme",
-     source_name="Marketing Posts"
-   )
+   ```jsonc
+   apimapper_flow_setup_with_sources({
+     name: "Marketing Posts",
+     sources: [{ connection: "conn_blog" }],
+     output: { type: "yootheme", name: "Marketing Posts" }
+   })
    ```
-   The `source_name` is what appears in the YOOtheme Source dropdown. Keep it short and human-readable.
 
-3. **Compile** to validate schema + graph:
-   ```
-   apimapper_flow_compile(flow_id="flow_abc")
-   ```
-   This catches:
-   - Disconnected nodes
-   - Type drift between Transform output and Output input
-   - Missing required fields
-   - Filter expressions referencing fields that don't exist on the upstream
+   The output `name` is what appears in the YOOtheme Source dropdown. Keep it short and human-readable. For full control over nodes/edges use `apimapper_flow_create`; to edit an existing graph use `apimapper_flow_update` (advanced — call via `apimapper_advanced({ tool: "apimapper_flow_update", arguments: {…} })`).
+
+2. **Publish (compile + register + invalidate cache) in one call:**
 
-4. **Publish**:
+   ```jsonc
+   apimapper_flow_full_recompile_publish({ flow_id: "flow_abc" })
    ```
-   apimapper_flow_full_recompile_publish(flow_id="flow_abc")
+
+   This compiles the graph (catching disconnected nodes, type drift, missing fields, and filter expressions referencing non-existent fields), writes the flow into the YOOtheme Source registry, and invalidates the YOOtheme schema cache. Prefer this over a bare compile — a plain `apimapper_flow_compile` is gateway-only and does not force a schema-cache flush.
+
+3. **Discover the exact source name + bindable fields:**
+
+   ```jsonc
+   apimapper_yootheme_binding_for_flow({ flow_id: "flow_abc" })
+   // → { source_name_singular, source_name_list, fields, ready_for_binding, ... }
    ```
-   This writes the flow into the YOOtheme Source registry and invalidates the YOOtheme schema cache.
 
-5. **Verify in YOOtheme Builder**:
-   - Open any YOOtheme page or template.
-   - Add a Grid / Slider / Dynamic element.
-   - "Source" dropdown → look for **the name you set in step 2** ("Marketing Posts"), NOT a "API Mapper" entry.
+4. **Verify in the YOOtheme Builder:** open any page/template, add a Grid / Slider / Map element, and look for **the name you set in step 1** ("Marketing Posts") in the Source dropdown — NOT a "API Mapper" entry.
+
+## Binding the published source into a Builder element
+
+Once published, the source is bound to a Builder element through the **yt-builder-mcp** server, not here. The full bridge (recompile → `binding_for_flow` → `yootheme_builder_element_bind_source` with `bindingLevel`, `field_mappings`, and the Multi-Items `*_item` rule) lives in its own topic:
+
+```jsonc
+apimapper_get_skill({ topic: "yootheme-source-to-builder-handoff" })
+```
 
 ## Schema for YOOtheme dynamic content
 
-YOOtheme reads the published flow's output schema (introspected by `apimapper_flow_detect_schema`). Each field on the schema becomes a mappable property in the YOOtheme element editor (title, image, link, date, …).
+YOOtheme reads the published flow's output schema. Each field on the schema becomes a mappable property in the YOOtheme element editor (title, image, link, date, …).
+
+To control which fields YOOtheme sees, use a `Transform` node with an explicit JMESPath projection — e.g. `[*].{title: name, image: cover.url, link: permalink}`. The Visual Expression Builder in the UI produces equivalent expressions; both end up in the same compiled flow.
+
+### Rich popups / multi-facet displays via a DERIVED Transform field (F42)
+
+A `map_item` popup (and several other item slots) exposes only a small fixed set of bind targets — `title`, `meta`, `content`, `image`. When the customer wants **more facets than there are slots** (e.g. price + beds + baths + rating + review-count all in one popup), do **not** look for extra slots — compose them into a single **derived field** in the Transform node, then bind that one field to `content`:
+
+```jsonc
+// Transform projection — synthesize a composite field the schema will expose.
+[*].{
+  title: name,
+  image: photo,
+  location: join(',', [to_string(lat), to_string(lng)]),   // map_item.location wants ONE "lat,lng" field
+  popup_body: join(' · ', [
+    join('', ['$', to_string(price)]),
+    join(' ', [to_string(beds), 'bd']),
+    join(' ', [to_string(baths), 'ba']),
+    join('', ['★', to_string(rating)])
+  ])
+}
+```
 
-To control which fields YOOtheme sees:
-- Use a `Transform` node with an explicit JMESPath/expression projection.
-- `[*].{title: name, image: cover.url, link: permalink}` is a typical canonical projection.
-- The Visual Expression Builder in the UI produces equivalent expressions; both end up in the same compiled flow.
+After re-publishing, `popup_body` is a first-class field you bind to the popup's `content` slot. This is the canonical pattern for "5+ facets, 4 slots". (For the `'lat,lng'` `location` contract and the map binding itself, see the handoff topic.)
+
+> Derived fields are invisible to `apimapper_yootheme_binding_for_flow` until you re-run `apimapper_flow_full_recompile_publish`. Change the projection → recompile → re-read bindings → re-bind.
+
+## The map sequence (F46) — ETag-locked bind + publish, in order
+
+A Map element is wired with the same Multi-Items discipline as Grid/Slider, plus the coordinate + popup specifics. The end-to-end sequence:
+
+1. `apimapper_flow_full_recompile_publish({ flow_id })` — publish the source (with the derived `location` + popup fields above).
+2. `apimapper_yootheme_binding_for_flow({ flow_id })` — get `source_name_list` + field names.
+3. In yt-builder-mcp, read the element's ETag, then bind on the **`map_item` child** (never the `map` container) by calling `yootheme_builder_element_bind_source` directly (a first-class tool in tools/list), mapping `location` to the single `'lat,lng'` field and the popup slots to your fields. The exact call is in the handoff topic.
+4. Publish the page and verify markers render. If `location` is unbound the Map renders structurally fine with **zero pins** — bind `location` or no markers appear.
 
 ## Where YOOtheme features live (NOT in the flow)
 
@@ -72,25 +107,21 @@ These belong in YOOtheme, not in API Mapper:
 | Pagination | YOOtheme element + URL handling |
 | Per-page query overrides | YOOtheme element bindings (`source`) |
 
-API Mapper's job is to deliver typed clean JSON. The render-time slicing / sorting / filtering lives in YOOtheme. Don't reimplement it in a Transform node — it just bloats the flow and creates two truth sources.
+API Mapper's job is to deliver typed clean JSON. Render-time slicing / sorting / filtering lives in YOOtheme — don't reimplement it in a Transform node.
 
 ## Shortcode output (WordPress only)
 
-Same flow can ALSO emit a Shortcode output (`output_type="shortcode"`). Use this for:
-- Embedding in classic editor posts
-- Using outside YOOtheme (page builders, plugins)
-- Quick previews in admin
-
-Shortcode currently supports a subset of the YOOtheme render-time features. See `https://wootsup.com/docs/mcp/api-mapper/` (the shortcode subpage will land in a later release).
+The same flow can ALSO emit a Shortcode output (`output.type = "shortcode"`). Use this for embedding in classic editor posts, using outside YOOtheme, or quick admin previews. Shortcode currently supports a subset of the YOOtheme render-time features.
 
 ## Common pitfalls
 
-1. **Save vs Publish** — saving stores the flow in `wp_options` (or Joomla equivalent) but does NOT register it as a YOOtheme Source. Always publish.
-2. **Looking for "API Mapper" in the dropdown** — wrong. Sources appear under the **flow's published source_name**.
-3. **Stale YOOtheme schema cache** — after a major schema change (Transform projection updated, new field added), clear YOOtheme cache: `yootheme_clear_cache` (sibling MCP) or via WP-Admin → YOOtheme → Settings → Clear Cache.
-4. **Republishing without recompile** — schema drift won't propagate. Use `apimapper_flow_full_recompile_publish`, not `apimapper_flow_publish`.
-5. **Dynamic content fields show as empty** — usually case sensitivity. YOOtheme expects field names lowercase; the Transform projection must produce lowercase keys. Field-Cards in the UI handle this automatically.
+1. **Save vs Publish** — saving stores the flow but does NOT register it as a YOOtheme Source. Always publish via `apimapper_flow_full_recompile_publish`.
+2. **Looking for "API Mapper" in the dropdown** — wrong. Sources appear under the **flow's published source name**.
+3. **Stale YOOtheme schema cache** — `apimapper_flow_full_recompile_publish` flushes it; a bare publish or compile may not. Always use the recompile-publish tool after a schema change.
+4. **Derived fields missing after a Transform edit** — re-run `apimapper_flow_full_recompile_publish`, then re-read `apimapper_yootheme_binding_for_flow`. New fields are invisible to binding until recompile.
+5. **Dynamic content fields show as empty** — usually case sensitivity. YOOtheme expects lowercase field names; the Transform projection must produce lowercase keys.
+6. **Map with zero pins** — the `map_item.location` slot is unbound, or `location` is two separate lat/lng fields instead of one `'lat,lng'` field. Synthesize a single `location` field in the Transform.
 
 ## Multi-platform behaviour
 
-WordPress and Joomla produce identical YOOtheme schemas — the Source/Type registration goes through the same YOOtheme PHP API. But the underlying REST surface differs (see `skill://apimapper/joomla` for the Joomla envelope). Tools auto-detect the platform and route correctly.
+WordPress and Joomla produce identical YOOtheme schemas — the Source/Type registration goes through the same YOOtheme PHP API. The underlying REST surface differs (see `apimapper_get_skill({ topic: "joomla" })`). Tools auto-detect the platform and route correctly.