@wootsup/mcp 0.1.0 → 0.4.0

package/package.json

@@ -1,67 +1,71 @@
 {
-  "name": "@wootsup/mcp",
-  "version": "0.1.0",
-  "type": "module",
-  "description": "API Mapper MCP Server — multi-platform (WordPress/Joomla), multi-AI-client, Stripe-style auth, bundled skills",
-  "license": "MIT",
-  "author": "WootsUp <hello@wootsup.com>",
-  "homepage": "https://wootsup.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wootsup/api-mapper.git",
-    "directory": "packages/apimapper-mcp"
-  },
-  "bugs": "https://github.com/wootsup/api-mapper/issues",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "api-mapper",
-    "wordpress",
-    "joomla",
-    "claude",
-    "chatgpt",
-    "cursor"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "apimapper-mcp": "./dist/index.js"
-  },
-  "files": [
-    "dist/",
-    "skills/",
-    "docs/",
-    "manifest.json",
-    "CHANGELOG.md",
-    "SECURITY.md"
-  ],
-  "scripts": {
-    "build": "tsc && chmod +x dist/index.js 2>/dev/null || true",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "dev": "tsx watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "start:http": "node dist/server-http.js",
-    "build:dxt": "node scripts/build-dxt.js",
-    "token-baseline": "node scripts/token-baseline.mjs"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.10.0",
-    "@getimo/mcp-toolkit": "^1.1.1",
-    "@modelcontextprotocol/sdk": "^1.27.0",
-    "@napi-rs/keyring": "^1.3.0",
-    "undici": "^7.25.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/archiver": "^7.0.0",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "~2.1.9",
-    "archiver": "^8.0.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
-  }
+    "name": "@wootsup/mcp",
+    "version": "0.4.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",
+        "export:catalog": "npm run build && node scripts/export-catalog.mjs",
+        "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.28.1",
+        "tsx": "^4.21.0",
+        "typescript": "^5.6.0",
+        "vitest": "^2.1.0"
+    }
 }

package/skills/apimapper/SKILL.md

@@ -10,7 +10,7 @@ allowed-tools:
 
 # API Mapper
 
-Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transform → Output). One server, one Bearer key, 17-tool gateway surface (77 capabilities behind `apimapper_advanced`).
+Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transform → Output). One server, one Bearer key, 20-tool surface; 60 more behind `apimapper_advanced`; 80 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,22 +36,143 @@ 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({ 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
+```
+
+**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({ 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
+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>`.
 
+## 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.
 - **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/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