@wootsup/mcp 0.1.0 → 0.4.0

package/dist/modules/apimapper/gateway/essentials.js

@@ -2,16 +2,34 @@
 //
 // Single source of truth for the "essentials" surface: the tools kept as
 // first-class entries in `tools/list`. Cursor caps MCP servers at ~40 tools;
-// the API Mapper adapter has 77 registered tools, so all but the essentials
-// are routed through the `apimapper_advanced` gateway (see advanced-tool.ts).
+// the API Mapper adapter has 81 registered tools (18 module-real = 16 module
+// essentials + the apimapper_advanced gateway + the apimapper_advanced_read
+// gateway, + 60 advanced-registry tools, + 3 tools registered directly in
+// src/index.ts), so all but the essentials are routed through the gateways
+// (see advanced-tool.ts / advanced-read-tool.ts). That keeps the first-class
+// `tools/list` surface at 21 — well under the cap. The canonical counts are
+// asserted live in gateway/gateway.test.ts (A2); this comment cites what that
+// test proves.
+//
+// F115 (2026-06-11): apimapper_health promoted from the advanced registry to
+// a module-registered essential — the documented "run this first" verify tool
+// was itself only reachable via the gateway (first-call deadend). This shifts
+// module essentials 15→16, advanced 60→59 (total then 79).
+//
+// F200b (2026-06-12): apimapper_advanced_read added as a 2nd module-real
+// gateway — module-real 17→18, surface 20→21, total 80→81. It whitelists the
+// read-only advanced subtools (readOnlyHint-derived) and carries a readOnly
+// annotation so hosts stop prompting on every advanced read.
 /** Tools kept as first-class entries in tools/list (Cursor-cap-safe surface). */
 export const ESSENTIAL_TOOLS = [
     "apimapper_onboarding",
     "apimapper_diagnose",
     "apimapper_list_profiles",
     "apimapper_use_profile",
+    "apimapper_library_featured",
     "apimapper_library_list",
     "apimapper_library_activate",
+    "apimapper_health",
     "apimapper_connection_list",
     "apimapper_connection_create",
     "apimapper_connection_data",
@@ -19,6 +37,7 @@ export const ESSENTIAL_TOOLS = [
     "apimapper_oauth_authorize_begin",
     "apimapper_flow_setup_with_sources",
     "apimapper_flow_full_recompile_publish",
+    "apimapper_yootheme_binding_for_flow",
     "apimapper_render",
     "apimapper_get_skill",
 ];

package/dist/modules/apimapper/gateway/essentials.js.map

@@ -1 +1 @@
-{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/essentials.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAE9E,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,sBAAsB;IACtB,oBAAoB;IACpB,yBAAyB;IACzB,uBAAuB;IACvB,wBAAwB;IACxB,4BAA4B;IAC5B,2BAA2B;IAC3B,6BAA6B;IAC7B,2BAA2B;IAC3B,2BAA2B;IAC3B,iCAAiC;IACjC,mCAAmC;IACnC,uCAAuC;IACvC,kBAAkB;IAClB,qBAAqB;CACb,CAAC;AAUX,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"essentials.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/essentials.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,eAAe;AACf,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,2DAA2D;AAC3D,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,6DAA6D;AAE7D,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,sBAAsB;IACtB,oBAAoB;IACpB,yBAAyB;IACzB,uBAAuB;IACvB,4BAA4B;IAC5B,wBAAwB;IACxB,4BAA4B;IAC5B,kBAAkB;IAClB,2BAA2B;IAC3B,6BAA6B;IAC7B,2BAA2B;IAC3B,2BAA2B;IAC3B,iCAAiC;IACjC,mCAAmC;IACnC,uCAAuC;IACvC,qCAAqC;IACrC,kBAAkB;IAClB,qBAAqB;CACb,CAAC;AAUX,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/modules/apimapper/gateway/gateway-shared.d.ts

@@ -0,0 +1,21 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ZodRawShape } from "zod";
+import type { AdvancedToolEntry } from "./capturing-server.js";
+export declare const DOMAIN_ORDER: readonly ["connection", "credential", "flow", "graph", "library", "license", "settings", "cache", "local_source", "schema", "diagnostics", "release", "brandfetch", "feedback", "features", "health", "inspect", "node_snapshot", "platform", "workflow", "onboarding", "render", "yootheme", "misc"];
+/** Maps a tool name to its display domain (the segment after `apimapper_`). */
+export declare function domainOf(toolName: string): string;
+/** Groups tool names by domain, in DOMAIN_ORDER, for stable output. */
+export declare function groupByDomain(toolNames: string[]): Map<string, string[]>;
+/** Renders the grouped tool list as readable text (used in description + errors). */
+export declare function renderGroupedList(toolNames: string[]): string;
+/** Reads the captured config's inputSchema as a Zod raw-shape (or empty). */
+export declare function shapeOf(entry: AdvancedToolEntry): ZodRawShape;
+/**
+ * F200b: a registry entry is read-only when its annotation carries
+ * `readOnlyHint === true`. This is the SOLE classifier for the read gateway's
+ * whitelist — derived from the subtool's own annotation, zero per-provider
+ * branching.
+ */
+export declare function isReadOnlyEntry(entry: AdvancedToolEntry): boolean;
+/** Builds the discovery-mode result for a target tool. */
+export declare function discoveryResult(toolName: string, entry: AdvancedToolEntry): CallToolResult;

package/dist/modules/apimapper/gateway/gateway-shared.js

@@ -0,0 +1,124 @@
+// src/modules/apimapper/gateway/gateway-shared.ts — F200b
+//
+// Shared machinery for the two gateway tools:
+//   - apimapper_advanced       (advanced-tool.ts) — every advanced subtool.
+//   - apimapper_advanced_read  (advanced-read-tool.ts) — the READ-ONLY subset.
+//
+// Both expose the same two modes (discovery / execution), group their tool list
+// by domain, and project a target's Zod inputSchema to JSON-Schema for
+// discovery. Factoring it here keeps the read gateway free of per-provider
+// branching and guarantees the two surfaces never drift in their rendering.
+import { z } from "zod";
+// Domains used to group advanced tool names in descriptions + errors. Kept in
+// one place so both gateways render identical groupings.
+export const DOMAIN_ORDER = [
+    "connection",
+    "credential",
+    "flow",
+    "graph",
+    "library",
+    "license",
+    "settings",
+    "cache",
+    "local_source",
+    "schema",
+    "diagnostics",
+    "release",
+    "brandfetch",
+    "feedback",
+    "features",
+    "health",
+    "inspect",
+    "node_snapshot",
+    "platform",
+    "workflow",
+    "onboarding",
+    "render",
+    "yootheme",
+    "misc",
+];
+/** Maps a tool name to its display domain (the segment after `apimapper_`). */
+export function domainOf(toolName) {
+    const stem = toolName.replace(/^apimapper_/, "");
+    for (const domain of DOMAIN_ORDER) {
+        if (stem === domain || stem.startsWith(`${domain}_`))
+            return domain;
+    }
+    return "misc";
+}
+/** Groups tool names by domain, in DOMAIN_ORDER, for stable output. */
+export function groupByDomain(toolNames) {
+    const groups = new Map();
+    for (const domain of DOMAIN_ORDER)
+        groups.set(domain, []);
+    for (const name of [...toolNames].sort()) {
+        const domain = domainOf(name);
+        const bucket = groups.get(domain);
+        if (bucket)
+            bucket.push(name);
+    }
+    for (const [domain, names] of groups) {
+        if (names.length === 0)
+            groups.delete(domain);
+    }
+    return groups;
+}
+/** Renders the grouped tool list as readable text (used in description + errors). */
+export function renderGroupedList(toolNames) {
+    const groups = groupByDomain(toolNames);
+    const lines = [];
+    for (const [domain, names] of groups) {
+        lines.push(`  ${domain}: ${names.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+/** Reads the captured config's inputSchema as a Zod raw-shape (or empty). */
+export function shapeOf(entry) {
+    const schema = entry.config.inputSchema;
+    if (schema && typeof schema === "object")
+        return schema;
+    return {};
+}
+/**
+ * F200b: a registry entry is read-only when its annotation carries
+ * `readOnlyHint === true`. This is the SOLE classifier for the read gateway's
+ * whitelist — derived from the subtool's own annotation, zero per-provider
+ * branching.
+ */
+export function isReadOnlyEntry(entry) {
+    const annotations = entry.config.annotations;
+    return annotations?.readOnlyHint === true;
+}
+/** Builds the discovery-mode result for a target tool. */
+export function discoveryResult(toolName, entry) {
+    const cfg = entry.config;
+    let schema;
+    try {
+        schema = z.toJSONSchema(z.object(shapeOf(entry)));
+    }
+    catch {
+        // A schema that cannot be JSON-projected still yields a usable discovery
+        // payload — the description and annotations carry the rest.
+        schema = { note: "input schema could not be derived" };
+    }
+    const payload = {
+        tool: toolName,
+        description: cfg.description ?? "",
+        inputSchema: schema,
+        annotations: cfg.annotations ?? {},
+    };
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Discovery for ${toolName}\n\n` +
+                    `${cfg.description ?? ""}\n\n` +
+                    `Annotations: ${JSON.stringify(cfg.annotations ?? {})}\n\n` +
+                    `Input schema:\n${JSON.stringify(schema, null, 2)}\n\n` +
+                    `Call the gateway again with { tool: "${toolName}", arguments: {...} } to run it.`,
+            },
+        ],
+        structuredContent: payload,
+    };
+}
+//# sourceMappingURL=gateway-shared.js.map

package/dist/modules/apimapper/gateway/gateway-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-shared.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/gateway-shared.ts"],"names":[],"mappings":"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"}

package/dist/modules/apimapper/gateway/test-support.d.ts

@@ -1,17 +1 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { ApimapperRestModule } from "../index.js";
-/** A tool entry as seen by tests: handler + the registered config. */
-export interface CollectedTool {
-    handler: (args: Record<string, unknown>, extra?: unknown) => CallToolResult | Promise<CallToolResult>;
-    title?: string;
-    description?: string;
-    inputSchema?: unknown;
-    annotations?: Record<string, unknown>;
-}
-/**
- * Returns every API Mapper tool — the essentials registered on the real
- * McpServer plus the advanced tools captured in the gateway registry —
- * keyed by tool name. `module.register(server)` must have run first.
- */
-export declare function collectModuleTools(server: McpServer, module: ApimapperRestModule): Record<string, CollectedTool>;
+export { collectModuleTools, type CollectedTool, } from "./collect-module-tools.js";

package/dist/modules/apimapper/gateway/test-support.js

@@ -7,37 +7,8 @@
 // every tool (essentials on the real server + advanced from the registry),
 // keeping their lookup semantics identical to the pre-gateway behaviour.
 //
-// Test-only: not imported by any runtime path.
-/**
- * Returns every API Mapper tool — the essentials registered on the real
- * McpServer plus the advanced tools captured in the gateway registry —
- * keyed by tool name. `module.register(server)` must have run first.
- */
-export function collectModuleTools(server, module) {
-    const result = {};
-    const realTools = server._registeredTools;
-    for (const [name, tool] of Object.entries(realTools)) {
-        result[name] = {
-            handler: tool.handler,
-            title: tool.title,
-            description: tool.description,
-            inputSchema: tool.inputSchema,
-            annotations: tool.annotations,
-        };
-    }
-    const advanced = module.getAdvancedRegistry();
-    if (advanced) {
-        for (const [name, entry] of advanced) {
-            const cfg = entry.config;
-            result[name] = {
-                handler: entry.handler,
-                title: cfg.title,
-                description: cfg.description,
-                inputSchema: cfg.inputSchema,
-                annotations: cfg.annotations,
-            };
-        }
-    }
-    return result;
-}
+// `collectModuleTools` + `CollectedTool` now live in `collect-module-tools.ts`
+// (the build/release path imports them too, so they are NOT test-only). This
+// module re-exports them so existing test imports keep working unchanged.
+export { collectModuleTools, } from "./collect-module-tools.js";
 //# sourceMappingURL=test-support.js.map

package/dist/modules/apimapper/gateway/test-support.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-support.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/test-support.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,sEAAsE;AACtE,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,+CAA+C;AA0B/C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAA2B;IAE3B,MAAM,MAAM,GAAkC,EAAE,CAAC;IAEjD,MAAM,SAAS,GACb,MACD,CAAC,gBAAgB,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,GAAG;YACb,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9C,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;YACrC,MAAM,GAAG,GAAG,KAAK,CAAC,MAKjB,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,GAAG;gBACb,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;aAC7B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"test-support.js","sourceRoot":"","sources":["../../../../src/modules/apimapper/gateway/test-support.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,4EAA4E;AAC5E,sEAAsE;AACtE,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,yEAAyE;AACzE,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,0EAA0E;AAE1E,OAAO,EACL,kBAAkB,GAEnB,MAAM,2BAA2B,CAAC"}

package/dist/modules/apimapper/get-skill-cores.d.ts

@@ -0,0 +1,4 @@
+import type { SkillTopic } from "./get-skill.js";
+/** Appended to every core so the agent can reach the long form. */
+export declare const FULL_DOC_POINTER = "\n\nFull doc (long form, examples, pitfalls): apimapper_get_skill({ topic, full: true }).";
+export declare const SKILL_CORES: Record<SkillTopic, string>;

package/dist/modules/apimapper/get-skill-cores.js

@@ -0,0 +1,220 @@
+// src/modules/apimapper/get-skill-cores.ts — F196 (Desktop-E2E #2, 2026-06-12)
+//
+// Condensed CORE for each skill topic. `apimapper_get_skill` returns the core
+// BY DEFAULT (full markdown only with `full: true`). The forensics showed
+// get_skill responses dominated the transcript — merge-two-sources-on-key
+// alone was 11 KB, returned multiple times. The core keeps the
+// recipe/patterns (join-key rules, transform[] cue, the one-call tool name)
+// and drops prose + repeated examples; the long form stays one flag away.
+//
+// CONTRACT (pinned by get-skill.test.ts):
+//   - every core is < 2500 chars,
+//   - the big topics shrink dramatically vs the full markdown,
+//   - the merge core keeps joinKey/strategy + flat-merge + transform cue,
+//   - the dynamize core keeps page_dynamize + leaf_map,
+//   - the conditional-style core keeps the recipe element names.
+//
+// Each core ends with a one-line "full doc" pointer so the agent knows the
+// long form is reachable.
+/** Appended to every core so the agent can reach the long form. */
+export const FULL_DOC_POINTER = "\n\nFull doc (long form, examples, pitfalls): apimapper_get_skill({ topic, full: true }).";
+export const SKILL_CORES = {
+    "getting-started": [
+        "# API Mapper — getting started (core)",
+        "",
+        "Bridge any REST API into YOOtheme via a saved flow: Source → Filter → Transform → Output.",
+        "",
+        "## Step 1 (MANDATORY): check the library FIRST",
+        "apimapper_library_featured() / apimapper_library_list({ search }) → if a template",
+        "covers your API, activate it: apimapper_library_activate({ id, credential_id?, extra_fields? }).",
+        "Templates ship OAuth wizard, auto-header detection, curated YOOtheme schema, caching, items_path.",
+        "",
+        "## Step 2: custom connection_create — ONLY when no template fits",
+        "A custom create on a covered host is 409-blocked; the error names the template + the",
+        "apimapper_library_activate({ id }) call. Override with acknowledge_no_library:true only after a real 409.",
+        "",
+        "## Common tools",
+        "apimapper_health (run first), apimapper_connection_list/_get/_data, apimapper_flow_setup_with_sources,",
+        "apimapper_flow_full_recompile_publish (Save ≠ Publish), apimapper_yootheme_binding_for_flow.",
+        "Most tools are gateway-only: apimapper_advanced({ tool, arguments }). Read-only ones: apimapper_advanced_read.",
+    ].join("\n"),
+    oauth: [
+        "# OAuth sources (core)",
+        "",
+        "## Canonical path for a covered API: activate the template",
+        "apimapper_library_activate({ id, credential_id, extra_fields }). extra_fields carries the",
+        "placeholder values (Sheets: the BARE spreadsheet_id, not the Drive URL). Never touch connection_create for a covered API.",
+        "",
+        "## Tool surface",
+        "top-level: apimapper_library_*, apimapper_credential_list, apimapper_oauth_authorize_begin.",
+        "GATEWAY-only: apimapper_credential_create / _get, apimapper_connection_test — call via",
+        "apimapper_advanced({ tool: 'apimapper_credential_create', arguments: {...} }).",
+        "",
+        "## Create an OAuth credential (none reusable)",
+        "1. apimapper_advanced({ tool:'apimapper_credential_create', arguments:{ auth_type:'oauth2_code',",
+        "   oauth_provider:'google', auth_data:{ client_id, client_secret } } }) → { id } (NO authorize_url here).",
+        "2. apimapper_oauth_authorize_begin({ credential_id }) → { authorize_url }. SURFACE the URL to the user;",
+        "   they consent, the callback writes access_token+refresh_token. Skip it → credential stays pending → 401.",
+        "Re-authorize an expired credential IN PLACE (same credential_id) — never delete+recreate (drops refresh token).",
+        "Custom connection (no template): apimapper_connection_create({ ..., endpoint, auth_type }).",
+    ].join("\n"),
+    yootheme: [
+        "# Expose API Mapper sources to YOOtheme (core)",
+        "",
+        "## Publish pipeline (REST)",
+        "1. apimapper_flow_setup_with_sources(...) builds + saves the flow.",
+        "2. apimapper_flow_full_recompile_publish({ flow_id }) — compile + register + invalidate, in ONE call.",
+        "   Save ≠ Publish: saving stores the flow but does NOT register the YOOtheme Source. Always publish.",
+        "3. apimapper_yootheme_binding_for_flow({ flow_id }) → the source name + flat field list to bind.",
+        "",
+        "## Bind into a Builder element (yt-builder)",
+        "yootheme_builder_advanced({ tool:'yootheme_builder_element_bind_source', arguments:{ bindingLevel, field_mappings } }).",
+        "Multi-Items (grid_item/list_item) bind at item level. Rich popups: add a DERIVED Transform field, map_item onto it.",
+        "Map element: bind `location` or it renders 0 pins. Use only real REST apimapper_* tools — no app_* tools.",
+    ].join("\n"),
+    joomla: [
+        "# Joomla gotchas (core)",
+        "",
+        "## Endpoint shape — com_ajax envelope",
+        "index.php?option=com_ajax&plugin=apimapper&format=json&task=connections.list (NOT /wp-json on Joomla).",
+        "The MCP server resolves paths for you; let it.",
+        "",
+        "## Auth tiers",
+        "Tier 1 — Bearer fast-path (what credential_create uses, headless).",
+        "Tier 2 — Joomla user session. Tier 3 — OAuth trampoline (System Plugin event, stable callback URL).",
+        "",
+        "## Pitfalls",
+        "OAuth callback can fail silently when SEF rewriting swallows query params — verify with/without SEF.",
+        "com_ajax caches by URL — add &_= cache-bust in dev. Plugin lives in plugins/system/apimapper/.",
+    ].join("\n"),
+    troubleshooting: [
+        "# Troubleshooting (core)",
+        "",
+        "Run apimapper_health FIRST. Triage by HTTP status:",
+        "- 401: MCP key MISSING/invalid → regenerate token + update client env. Credential expired →",
+        "  apimapper_oauth_authorize_begin({ credential_id }), surface URL. Do NOT delete+recreate.",
+        "- 403: license tier blocks the action (2nd connection / JMESPath on Free) → apimapper_license_status.",
+        "- 404: plugin disabled (health → plugin:enabled) or wrong flow id → apimapper_flow_list.",
+        "- 422/400: body failed validation — read validation_errors[]; check shape vs apimapper_local_source_schema.",
+        "- 429: rate-limited → retry, raise cache_ttl, or bind to a same-schema mirror connection.",
+        "Depth-limit 422 → split the JMESPath into a transform[] ARRAY of stages (pipe resets the depth counter).",
+    ].join("\n"),
+    render: [
+        "# Render (core)",
+        "",
+        "Two-step: fetch data, then apimapper_render({ type, data }). `type` is one of 7 viz-types:",
+        "- table — data: array of objects (apimapper_connection_data / graph_preview / flow_trace).",
+        "- chart-bar / chart-line — data: { labels[], values[] } (equal length).",
+        "- schema-diagram — data: a schema profile with fields[] (apimapper_schema_profile, pass through).",
+        "- flow-diagram — data: a flow with nodes[]+edges[] (apimapper_flow_get, pass the flow object).",
+        "- json-tree — data: any JSON value (catch-all inspector).",
+        "- diff — data: { old, new }.",
+    ].join("\n"),
+    "jmespath-pitfalls": [
+        "# JMESPath pitfalls (core)",
+        "",
+        "GIBT-ES-NICHT: arithmetic (+ - * /), split, regex, if-else — use conditional(cond, then, else) or ternary `(cond && a) || b` and primitives.",
+        "Date/number/logic primitives (resolve in Transform AND apimapper_jmespath_test):",
+        "- date_weekday(iso, tz) → 'Wednesday'; date_iso_to_time(iso, tz) → '09:00'; date_iso_to_date(iso, tz) → 'YYYY-MM-DD'.",
+        "- time_in_window(t, open, close) — left-closed/right-open; handles cross-midnight.",
+        "- format_number(890000) → '890,000'. coalesce_empty(a, b) for fallbacks.",
+        "- conditional(cond, then, else?) — flat if/else; returns a falsy then verbatim (sidesteps the ternary trap).",
+        "DEPTH CAP = 10. A deep reshape fails with a depth-limit 422 — SPLIT into a transform[] ARRAY of stages;",
+        "the pipe between stages resets the depth counter, so each stage gets its own budget.",
+        "Iterate risk-free with apimapper_jmespath_test({ expression, sample_rows }).",
+    ].join("\n"),
+    "jmespath-cookbook": [
+        "# JMESPath cookbook (core)",
+        "",
+        "Copy-paste patterns (iterate via apimapper_jmespath_test):",
+        "- if/else: conditional(stock > `0`, 'in stock', 'sold out')  - or ternary: color: (priority == `high` && `danger`) || `muted`",
+        "- join: join(', ', tags)   - sort: sort_by(@, &price)   - coordinates: [lat, lng]",
+        "- numbers: format_number(price) → '1,250,000'   - dates: date_weekday/date_iso_to_time/date_iso_to_date.",
+        "GIBT-ES-NICHT: arithmetic, split, regex, if-else → use conditional(cond, then, else) or ternary + primitives.",
+        "Two-Transform split: when one expression overflows depth 10, pass transform as an ARRAY of stages —",
+        "each stage gets its own depth budget; the pipe between stages resets the counter.",
+    ].join("\n"),
+    "merge-two-sources-on-key": [
+        "# Merge two sources on a shared key (core)",
+        "",
+        "## Recipe (REST, one call)",
+        "apimapper_flow_setup_with_sources({ name, sources:[{connection:A},{connection:B}],",
+        "  merge:{ strategy:'join', joinKey:'<A-field>', joinKeyRight:'<B-field>', joinType:'left' },",
+        "  filter?, output:{ type:'yootheme', name } }).",
+        "Vocabulary is strategy/joinKey (NOT the UI words mode/key). joinType 'left' keeps every A row; 'inner' drops unmatched.",
+        "Omit joinKeyRight when both sides name the field the same.",
+        "",
+        "## Discover the join key FIRST (guessing wrong = 0 rows, no error)",
+        "Sample both sides: apimapper_connection_data({ id:A, limit:3 }) and { id:B, limit:3 }.",
+        "Keys compare with === — string 'P-100' never equals number 42; case + whitespace matter.",
+        "Not comparable? Bridge with a Transform BEFORE merge (e.g. date_weekday for ISO↔weekday joins).",
+        "",
+        "## Flat-merge contract (no `b.` prefix)",
+        "B fields land FLAT on the A row. Bind to the bare name (`rating`), never `b.rating` (always null).",
+        "Same-name collision: A keeps the key, B becomes branch_1_<field>.",
+        "",
+        "## 0 rows? read merge_diagnostics[<node>] (reason: merge_no_match) with left/right_key_sample.",
+        "Deep reshape on either side overflows depth 10 → split into a transform[] ARRAY of stages.",
+    ].join("\n"),
+    "conditional-style-multi-items": [
+        "# Conditional style on Multi-Items (core)",
+        "",
+        "TRAP: text_style does NOT accept 'primary' — text_style is a typographic role (meta/lead/small/large).",
+        "For a primary COLOR use text_color:'primary' on the text element, or wrap in grid_item with panel_style:'primary'.",
+        "Enums: text_color ∈ muted/emphasis/primary/secondary/success/warning/danger; panel_style ∈ default/primary/secondary.",
+        "",
+        "## Recipe A — text_color from a row field",
+        "Transform precomputes a valid enum: color: (priority==`high` && `danger`) || `warning`.",
+        "Multi-Items text child binds: text_color → ${item.color}; text_style stays a literal ('lead').",
+        "",
+        "## Recipe B — panel_style wrapper from a row field",
+        "Wrap the row in a grid_item; bind panel_style → ${item.panelKey} (precomputed enum). Inner text stays neutral.",
+    ].join("\n"),
+    "library-template-discovery": [
+        "# Library template discovery (core)",
+        "",
+        "Before apimapper_library_activate, inspect the template to learn its auth + required placeholders.",
+        "Sequence: apimapper_library_list / _featured → pick id →",
+        "apimapper_library_connection_detail({ id }) → read base_url (which API), auth scheme, and extra_fields",
+        "(the placeholder values YOU must supply, e.g. spreadsheet_id, api_key — unset = broken connection).",
+        "Then ACTIVATE (not create): apimapper_library_activate({ id, credential_id?, extra_fields }).",
+        "Auth-protected templates: create/pick the credential first, pass credential_id explicitly.",
+        "The library-first guard 409-blocks a custom create on a covered host and names the activate call.",
+    ].join("\n"),
+    "yootheme-source-to-builder-handoff": [
+        "# apimapper → yt-builder handoff (core)",
+        "",
+        "## Bridge: recompile → binding_for_flow → bind via the gateway",
+        "1. apimapper_flow_full_recompile_publish({ flow_id }).",
+        "2. apimapper_yootheme_binding_for_flow({ flow_id }) → source_name (apiMapperFlow<Id>List) + flat field list.",
+        "3. yootheme_builder_advanced({ tool:'yootheme_builder_element_bind_source',",
+        "   arguments:{ element_id, bindingLevel, field_mappings } }).",
+        "field_mappings is a FULL REPLACE — every call replaces ALL mappings; resend every field you want to keep.",
+        "Multi-Items: bind at item level (grid_item/list_item); use map_item for derived/rich fields.",
+        "",
+        "## Dynamize an EXISTING designed layout (#parent repeater form)",
+        "The theme-canonical form: a column carries the iterating query; the child fragment clones via query.name '#parent';",
+        "leaves bind #parent + props. Per-row visibility rides on _condition with filters.condition '!' / '!!'",
+        "(booleans are unreliable — emit '' / 'next' string flags, empty/filled string semantics).",
+        "Find a design that lives inside another article via yootheme_builder_template_summary → named_sections.",
+        "WARN: article-context cells are ~20% narrower than category templates — verify visually at the target viewport.",
+    ].join("\n"),
+    "dynamize-existing-layout": [
+        "# Dynamize an existing designed layout (core)",
+        "",
+        "ONE RULE: copy the reference subtree byte-identically, change ONLY leaf field names. Insert nothing, rebuild nothing.",
+        "",
+        "## The loop — 2 discovery steps, then ONE call",
+        "1. FIND the section: yootheme_builder_template_summary → named_sections (the design often lives inside another article).",
+        "2. READ the source + flat fields: apimapper_yootheme_binding_for_flow({ flow_id }) → source_name (apiMapperFlow<Id>List).",
+        "3. DYNAMIZE in ONE call: yootheme_builder_page_dynamize({ template_id, section_path, source_name,",
+        "   leaf_map: { '<original nested leaf>': '<your flat flow field>', ... }, publish:true }).",
+        "   The server copies the subtree, swaps the query name + leaf names from leaf_map, inserts nothing, publishes.",
+        "4. VERIFY: render the public URL, compare one row to the original at the customer's viewport (wrap/overlap = fail).",
+        "",
+        "leaf_map example: 'field.home_team.crest.imagefile' → 'home_crest'. A leaf with no flow field is left KEPT.",
+        "The tool guarantees the hard rules (flat≠nested is fine, insert nothing, never invent asset paths) BY CONSTRUCTION.",
+        "Per-row visibility: emit '' / 'next' string flags, highlight via copied _condition filters.condition '!!'.",
+    ].join("\n"),
+};
+//# sourceMappingURL=get-skill-cores.js.map

package/dist/modules/apimapper/get-skill-cores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-skill-cores.js","sourceRoot":"","sources":["../../../src/modules/apimapper/get-skill-cores.ts"],"names":[],"mappings":"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"}

package/dist/modules/apimapper/get-skill.d.ts

@@ -1,4 +1,4 @@
 import type { ToolRegistrar } from "./gateway/capturing-server.js";
-export declare const SKILL_TOPICS: readonly ["getting-started", "oauth", "yootheme", "joomla", "troubleshooting", "render"];
+export declare const SKILL_TOPICS: readonly ["getting-started", "oauth", "yootheme", "joomla", "troubleshooting", "render", "jmespath-pitfalls", "jmespath-cookbook", "merge-two-sources-on-key", "conditional-style-multi-items", "library-template-discovery", "yootheme-source-to-builder-handoff", "dynamize-existing-layout"];
 export type SkillTopic = (typeof SKILL_TOPICS)[number];
 export declare function registerGetSkillTool(server: ToolRegistrar, rootDir?: string): void;