@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/library.js

@@ -1,22 +1,171 @@
 import { z } from "zod";
-import { formatResult, autoFormatTable, readOnly, creating, destructive, } from "@getimo/mcp-toolkit";
+import { formatResult, tableResult, detailResult, errorResult, readOnly, mutating, destructive, } from "@getimo/mcp-toolkit";
 import { request, hintFor } from "./client.js";
+import { restErrorResult } from "./tool-result.js";
 import { unwrapEntity } from "./envelope.js";
+import { toRows } from "./types.js";
+/**
+ * Wave-6 R1 (2026-05-29): Treat any non-"none" / non-empty auth_type as
+ * "credential required". The set is intentionally inclusive — the worker
+ * library uses both canonical (`oauth2_code`, `api_key`, `bearer`, `basic`)
+ * and legacy (`oauth`, `apiKey`) values; we don't try to enumerate them.
+ */
+function templateRequiresCredential(authType) {
+    if (typeof authType !== "string")
+        return false;
+    const t = authType.toLowerCase().trim();
+    if (t === "" || t === "none")
+        return false;
+    return true;
+}
+/**
+ * Wave-6 R1: read the provider slug from a library template. Tolerates
+ * both top-level `provider` and `auth_scheme.provider`.
+ */
+function templateProvider(tpl) {
+    if (typeof tpl.provider === "string" && tpl.provider !== "")
+        return tpl.provider;
+    const auth = tpl.auth_scheme;
+    if (auth && typeof auth === "object") {
+        const p = auth.provider;
+        if (typeof p === "string" && p !== "")
+            return p;
+    }
+    return undefined;
+}
+/**
+ * Wave-6 R1: read auth_type from a library template, normalising the
+ * pre-2.0 alias `oauth → oauth2_code`.
+ */
+function templateAuthType(tpl) {
+    let t = tpl.auth_type;
+    if (typeof t !== "string" || t === "") {
+        const auth = tpl.auth_scheme;
+        if (auth && typeof auth === "object") {
+            const at = auth.type;
+            if (typeof at === "string" && at !== "")
+                t = at;
+        }
+    }
+    if (typeof t !== "string" || t === "")
+        return undefined;
+    if (t === "oauth")
+        return "oauth2_code";
+    if (t === "apiKey")
+        return "api_key";
+    return t;
+}
+/**
+ * Wave-6 R1: credential lookup helpers shared with credentials.ts. Reads
+ * `oauth_provider` first, then `provider`.
+ */
+function credentialProviderSlug(c) {
+    return c.oauth_provider ?? c.provider ?? undefined;
+}
+/** F-14: best-effort JSON.stringify length. Falls back to 0 on cycle. */
+function computeCatalogSize(catalog) {
+    try {
+        return JSON.stringify(catalog).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * F-14: derive item count from common catalog shapes (items[] / connections[]).
+ * Falls back to total field, or 0 if nothing detectable.
+ */
+function computeCatalogItemCount(catalog, totalFallback) {
+    if (catalog && typeof catalog === "object") {
+        const co = catalog;
+        if (Array.isArray(co.items))
+            return co.items.length;
+        if (Array.isArray(co.connections))
+            return co.connections.length;
+    }
+    return typeof totalFallback === "number" ? totalFallback : 0;
+}
+// ── Shared table shape for every library list tool ────────────────────
+// IA-7: NAME is the human-readable label. ID is opaque but the LLM needs it
+// for follow-up calls (library_activate / library_connection_detail), so it
+// stays in the ASCII text — `llmOnly: true` keeps it out of the Rich Card UI.
+const LIBRARY_TABLE_COLUMNS = [
+    { key: "id", label: "ID", width: 28, llmOnly: true },
+    { key: "name", label: "NAME", width: 32 },
+    { key: "provider", label: "PROVIDER", width: 14 },
+    { key: "category", label: "CATEGORY", width: 14 },
+    { key: "activated", label: "ACT", width: 4 },
+];
+// T1 (W3.2): reduced column set for 21+ items — id (llmOnly) + name + one key
+// field (activation status). PROVIDER/CATEGORY are dropped at compact level.
+const LIBRARY_COMPACT_COLUMNS = [
+    { key: "id", label: "ID", width: 28, llmOnly: true },
+    { key: "name", label: "NAME", width: 32 },
+    { key: "activated", label: "ACT", width: 4 },
+];
+/** Standard row map: full LibraryItem → table row. */
+function mapLibraryRow(i) {
+    return {
+        id: String(i.id ?? ""),
+        name: String(i.name ?? ""),
+        provider: i.provider ? String(i.provider) : "—",
+        category: i.category ? String(i.category) : "—",
+        activated: i.is_activated ? "✓" : "✗",
+    };
+}
+/** T1 compact row map: only the columns LIBRARY_COMPACT_COLUMNS renders. */
+function compactLibraryRow(i) {
+    return {
+        id: String(i.id ?? ""),
+        name: String(i.name ?? ""),
+        activated: i.is_activated ? "✓" : "✗",
+    };
+}
+// IA-10: actionable next-step guidance, kept in the table footer so it is
+// VISIBLE in the LLM-readable text of every migrated list tool.
+const LIST_NEXT_STEPS = "Next: apimapper_library_activate({ id }) to activate a template · " +
+    "apimapper_advanced({ tool: 'apimapper_library_connection_detail', arguments: { id } }) for full template config.";
 export function registerLibraryTools(server) {
     // ── apimapper_library_list ─────────────────────────────────────────
+    // rc.10 (2026-05-19) — schema + description hardened against the
+    // discovery-thrash pattern observed in Maria-walkthrough logs (29
+    // calls including 12 per-category iterations and 5 single-char
+    // search probes over a catalog of just 34 templates). Two guard
+    // rails: (1) wire-level zod constraints reject the worst probes,
+    // (2) description states the catalog is small enough that one
+    // unfiltered call returns everything.
     server.registerTool("apimapper_library_list", {
         title: "List Library Items",
-        description: "List all library items (connection templates) shipping with API Mapper." +
-            "\n\nExample:\n  apimapper_library_list({ category: 'media' })",
+        description: "List connection templates shipping with API Mapper. The catalog is " +
+            "small (~30-50 templates) — a SINGLE CALL without filters returns the " +
+            "full set in one round-trip. Do NOT iterate per category and do NOT " +
+            "probe with short search strings; call apimapper_library_categories " +
+            "first if you need an overview of available slugs, then filter the " +
+            "table you already have client-side." +
+            "\n\nServer-side filters (sent as query params, server returns pre-filtered):\n" +
+            "  - category: narrow by category slug (e.g. 'media', 'productivity')\n" +
+            "  - search:   substring match on template name/description\n" +
+            "\nClient-side filters (applied AFTER fetch in this MCP process):\n" +
+            "  - provider:  narrow by upstream provider (e.g. 'google', 'meta')\n" +
+            "  - activated: narrow to currently-activated or not-activated\n" +
+            "\nImplication: When combined with `limit`, the total reflects the " +
+            "post-server filter — if you set limit:50 + provider:meta and the " +
+            "server returns 50 mixed-provider items, you may see <50 after the " +
+            "client filter. Re-call with a higher limit or omit the client-side " +
+            "filter to see the full server-side result." +
+            "\n\nExamples:\n" +
+            "  apimapper_library_list({})  // returns the whole catalog\n" +
+            "  apimapper_library_list({ category: 'media' })  // narrow to one category (server-side)\n" +
+            "  apimapper_library_list({ provider: 'google', limit: 200 })  // raise limit because provider filter is client-side",
         inputSchema: {
-            category: z.string().optional().describe('Filter by category slug (use apimapper_library_categories)'),
+            category: z.string().optional().describe('Filter by category slug. Use apimapper_library_categories to discover slugs — do NOT loop over every category, the result of an unfiltered list({}) already covers them all.'),
             provider: z.string().optional().describe('Filter by provider (e.g., "google", "meta")'),
             activated: z.enum(["any", "yes", "no"]).default("any").describe("Filter by activation status"),
-            search: z.string().optional().describe("Free-text search"),
-            page: z.number().min(1).default(1).describe("Pagination page (1-based)"),
-            limit: z.number().min(1).max(500).default(100).describe("Max items (1-500)"),
+            search: z.string().min(3).optional().describe("Free-text search. Must be 3+ characters — single-char probes are blocked because the catalog is too small to need typeahead."),
+            page: z.number().min(1).max(2).default(1).describe("Pagination page (1-based). Capped at 2 — the catalog rarely fills more than one page at the default limit, iterating further yields empty results."),
+            limit: z.number().min(1).max(500).default(100).describe("Max items per page (1-500). The default of 100 already exceeds the full catalog — increase only if you have a specific reason."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Library Connections", openWorld: true }),
     }, async ({ category, provider, activated, search, page, limit }) => {
         const params = new URLSearchParams();
         if (category)
@@ -27,13 +176,7 @@ export function registerLibraryTools(server) {
         params.set("limit", String(limit));
         const r = await request(`/library?${params.toString()}`);
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { category, provider, activated, search, page, limit },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { category, provider, activated, search, page, limit }, { message: "library list failed" });
         }
         // F-SEED-02: PHP returns `connections`; tolerate legacy `items`.
         let items = Array.isArray(r.data?.connections)
@@ -47,22 +190,13 @@ export function registerLibraryTools(server) {
             items = items.filter((i) => i.is_activated);
         if (activated === "no")
             items = items.filter((i) => !i.is_activated);
-        return autoFormatTable(items.map((i) => ({
-            id: i.id,
-            name: i.name,
-            provider: i.provider || "—",
-            category: i.category || "—",
-            activated: i.is_activated ? "✓" : "✗",
-        })), {
-            columns: [
-                { key: "id", label: "ID", width: 28 },
-                { key: "name", label: "NAME", width: 32 },
-                { key: "provider", label: "PROVIDER", width: 14 },
-                { key: "category", label: "CATEGORY", width: 14 },
-                { key: "activated", label: "ACT", width: 4 },
-            ],
+        return tableResult(toRows(items), {
+            columns: LIBRARY_TABLE_COLUMNS,
+            compactColumns: LIBRARY_COMPACT_COLUMNS,
+            map: mapLibraryRow,
+            compactMap: compactLibraryRow,
             header: (n) => `${n} library items (page ${page})`,
-            footer: "Use apimapper_library_connection_detail <id> for template config.",
+            footer: LIST_NEXT_STEPS,
         });
     });
     // ── apimapper_library_categories ───────────────────────────────────
@@ -79,11 +213,11 @@ export function registerLibraryTools(server) {
             "below exist." +
             "\n\nExample:\n  apimapper_library_categories({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Library Categories", openWorld: true }),
     }, async () => {
         const r = await request("/library/categories");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, undefined, { message: "library categories failed" });
         }
         const cats = Array.isArray(r.data?.categories) ? r.data.categories : [];
         const rows = cats
@@ -93,76 +227,171 @@ export function registerLibraryTools(server) {
             name: typeof c.name === "string" ? c.name : "",
             count: typeof c.count === "number" ? c.count : 0,
         }));
-        const total = rows.reduce((sum, r) => sum + r.count, 0);
-        return autoFormatTable(rows, {
+        const total = rows.reduce((sum, row) => sum + row.count, 0);
+        return tableResult(toRows(rows), {
             columns: [
-                { key: "id", label: "SLUG", width: 16 },
+                // IA-7: SLUG is the opaque identifier the LLM needs for
+                // library_list({category}); NAME is the human label.
+                { key: "id", label: "SLUG", width: 16, llmOnly: true },
                 { key: "name", label: "NAME", width: 28 },
-                { key: "count", label: "COUNT", width: 6 },
+                { key: "count", label: "COUNT", width: 6, align: "right" },
             ],
             header: (n) => `${n} library categories (${total} templates total)`,
-            footer: "Authoritative list — every customer-visible category lives in this table. " +
-                "Use the SLUG with apimapper_library_list({category}) to filter templates.",
+            // rc.10 A2 (2026-05-19) — footer explicitly states a single
+            // unfiltered list({}) returns the whole catalog (the old wording
+            // caused the Maria-walkthrough AI to iterate every slug — 12
+            // calls). IA-10 (W3.9): the footer also carries the next step.
+            footer: "Authoritative list of every customer-visible category. The total above is small — " +
+                "do NOT iterate library_list({category:'…'}) once per slug.\n" +
+                "Next: apimapper_library_list({}) returns the complete catalog in one call; filter by category client-side.",
         });
     });
     // ── apimapper_library_featured ─────────────────────────────────────
     server.registerTool("apimapper_library_featured", {
         title: "List Featured Library Items",
-        description: "Fetch curated/featured library items shown on the catalog landing." +
+        description: "List the curated, featured connection templates — the MANDATORY first " +
+            "call before building any new API integration. Use this to discover whether " +
+            "a ready-made template (with OAuth wizard, auto-header detection, and a " +
+            "curated YOOtheme schema) already exists for the API you need. " +
+            "Keywords: featured, recommended, starter, popular templates, pre-built, catalog landing. " +
+            "When NOT to use: to search the WHOLE catalog by name use apimapper_library_list; " +
+            "to read one template's full contract use apimapper_library_connection_detail; " +
+            "only fall back to apimapper_connection_create when no template matches." +
             "\n\nExample:\n  apimapper_library_featured({})",
         inputSchema: {
             limit: z.number().min(1).max(100).default(12).describe("Max items (1-100)"),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Featured Library Connections", openWorld: true }),
     }, async ({ limit }) => {
         const params = new URLSearchParams({ limit: String(limit) });
         const r = await request(`/library/featured?${params.toString()}`);
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { limit }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { limit }, { message: "library featured failed" });
         }
         const items = Array.isArray(r.data?.connections)
             ? r.data.connections
             : Array.isArray(r.data?.items)
                 ? r.data.items
                 : [];
-        return formatResult({ count: items.length, items }, false, { maxChars: 4000 });
+        return tableResult(toRows(items), {
+            columns: LIBRARY_TABLE_COLUMNS,
+            compactColumns: LIBRARY_COMPACT_COLUMNS,
+            map: mapLibraryRow,
+            compactMap: compactLibraryRow,
+            header: (n) => `${n} featured library items`,
+            footer: "Subset of the full catalog — NOT the complete library. " +
+                "Use apimapper_library_list({}) for the entire catalog.\n" +
+                LIST_NEXT_STEPS,
+        });
     });
     // ── apimapper_library_popular ──────────────────────────────────────
     server.registerTool("apimapper_library_popular", {
         title: "List Popular Library Items",
-        description: "Fetch most-activated library items." +
+        description: "List the most-activated connection templates across all users — a " +
+            "social-proof ranking of what other people actually wire up. Use to " +
+            "discover proven, in-demand integrations when you are exploring options. " +
+            "Keywords: popular, trending, most-used, most-activated, top templates. " +
+            "When NOT to use: for the editorial short-list use apimapper_library_featured; " +
+            "to search by API name use apimapper_library_list; to see what THIS user has " +
+            "already activated use apimapper_library_activated." +
             "\n\nExample:\n  apimapper_library_popular({})",
         inputSchema: {
             limit: z.number().min(1).max(100).default(12).describe("Max items (1-100)"),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Popular Library Connections", openWorld: true }),
     }, async ({ limit }) => {
         const params = new URLSearchParams({ limit: String(limit) });
         const r = await request(`/library/popular?${params.toString()}`);
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { limit }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { limit }, { message: "library popular failed" });
         }
         const items = Array.isArray(r.data?.connections)
             ? r.data.connections
             : Array.isArray(r.data?.items)
                 ? r.data.items
                 : [];
-        return formatResult({ count: items.length, items }, false, { maxChars: 4000 });
+        return tableResult(toRows(items), {
+            columns: LIBRARY_TABLE_COLUMNS,
+            compactColumns: LIBRARY_COMPACT_COLUMNS,
+            map: mapLibraryRow,
+            compactMap: compactLibraryRow,
+            header: (n) => `${n} popular library items`,
+            footer: "Subset of the full catalog — NOT the complete library. " +
+                "Use apimapper_library_list({}) for the entire catalog.\n" +
+                LIST_NEXT_STEPS,
+        });
     });
     // ── apimapper_library_catalog ──────────────────────────────────────
+    // NOT migrated to a structuredContent builder: the response is a
+    // multi-section object (items + categories + featured + popular), which
+    // is neither a flat list (tableResult) nor a single-entity detail
+    // (detailResult). formatResult preserves the nested structure, and the
+    // F-14 _meta.size_bytes / item_count already give the AI the
+    // size-decision signal a Rich Card would otherwise add.
     server.registerTool("apimapper_library_catalog", {
         title: "Get Full Library Catalog",
         description: "Fetch the entire library catalog (all categories + items + featured/popular in one shot). " +
-            "Heavy — use filtered endpoints for narrower queries." +
-            "\n\nExample:\n  apimapper_library_catalog({})",
-        inputSchema: {},
-        annotations: readOnly(),
-    }, async () => {
+            "Heavy — pass `template_id` to narrow the response to a single template's full record " +
+            "(skips the 8000-char truncation cap) or call apimapper_library_connection_detail for the " +
+            "rendered detail view." +
+            "\n\nExamples:\n" +
+            "  apimapper_library_catalog({})  // full catalog, may truncate at 8000 chars\n" +
+            "  apimapper_library_catalog({ template_id: 'google-sheets' })  // single template, full record",
+        inputSchema: {
+            // Wave-5 F12 (2026-05-29): cold-AI #3 hit 8k truncation on the
+            // unfiltered catalog and could not retrieve a target template's
+            // computed_fields / default_params. Filtering server-side via the
+            // same /library/connections/{id} endpoint that library_connection_detail
+            // uses gives the AI the FULL record without exceeding maxChars.
+            template_id: z
+                .string()
+                .optional()
+                .describe("Filter the catalog response to ONE template's full record (e.g. 'google-sheets'). " +
+                "Returns the connection template payload directly under the `connection` key " +
+                "(same shape as /library/connections/{id}) — skips the 8000-char truncation cap " +
+                "that applies to the unfiltered multi-section response."),
+        },
+        annotations: readOnly({ title: "Get Library Catalog", openWorld: true }),
+    }, async ({ template_id }) => {
+        // Wave-5 F12: single-template filter routes through the per-connection
+        // endpoint to skip the maxChars:8000 truncation that swallows mid-size
+        // records in the multi-section catalog response.
+        if (typeof template_id === "string" && template_id !== "") {
+            const r = await request(`/library/connections/${encodeURIComponent(template_id)}`);
+            if (!r.success) {
+                return restErrorResult(r, { template_id }, { message: "library catalog (filtered) failed" });
+            }
+            const connection = unwrapEntity(r.data, "connection") ?? {};
+            // DATA-LOW (Wave-B 2026-06-03): the data-level diagnostics key is named
+            // `meta` (not `_meta`) to avoid colliding in naming with the
+            // protocol-level `_meta` on the result object. This is text content, so
+            // the rename is harmless to clients but removes maintainer confusion.
+            return formatResult({
+                connection,
+                meta: {
+                    filtered_by: { template_id },
+                    source_endpoint: `/library/connections/${template_id}`,
+                },
+            }, false, { maxChars: 16000 });
+        }
         const r = await request("/library/catalog");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, undefined, { message: "library catalog failed" });
         }
-        return formatResult(r.data ?? {}, false, { maxChars: 8000 });
+        const catalog = r.data?.catalog ?? r.data ?? {};
+        // F-14: surface payload size + item count so the AI can decide whether
+        // to call this heavy tool again, or call a narrower endpoint.
+        const sizeBytes = computeCatalogSize(catalog);
+        const itemCount = computeCatalogItemCount(catalog, r.data?.total);
+        // DATA-LOW (Wave-B 2026-06-03): `meta` (not `_meta`) — see the filtered
+        // branch above. Avoids naming-collision with the protocol-level `_meta`.
+        return formatResult({
+            ...catalog,
+            meta: {
+                size_bytes: sizeBytes,
+                item_count: itemCount,
+            },
+        }, false, { maxChars: 8000 });
     });
     // ── apimapper_library_connection_detail ────────────────────────────
     server.registerTool("apimapper_library_connection_detail", {
@@ -172,49 +401,98 @@ export function registerLibraryTools(server) {
         inputSchema: {
             id: z.string().describe("Library item ID. Use apimapper_library_list to find."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Library Connection Detail", openWorld: true }),
     }, async ({ id }) => {
         const r = await request(`/library/connections/${encodeURIComponent(id)}`);
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "library connection detail failed" });
         }
         if (!r.data || (typeof r.data === "object" && Object.keys(r.data).length === 0)) {
-            return formatResult({ error: "library item not found", status: r.status, context: { id }, hint: hintFor("not_found") }, true);
+            return errorResult({
+                message: "library item not found",
+                code: r.status ? String(r.status) : "not_found",
+                suggestion: hintFor("not_found"),
+                details: { id },
+            });
         }
         // F-A4-02: PHP returns `{success, connection: {...}}`. Use the shared
         // envelope helper so we tolerate both wrapped + flat shapes.
         const connection = unwrapEntity(r.data, "connection") ?? {};
-        return formatResult(connection, false, { maxChars: 8000 });
+        return buildConnectionDetail(id, connection);
     });
     // ── apimapper_library_activated ────────────────────────────────────
     server.registerTool("apimapper_library_activated", {
         title: "List Activated Library Items",
-        description: "List library items the user has activated (= has a connection for)." +
+        description: "List the library templates THIS site has already activated (each one " +
+            "has a backing connection). Use to check what is already wired up before " +
+            "activating a duplicate, or to find the connection that came from a template. " +
+            "Keywords: activated, installed, my templates, already connected, in use. " +
+            "When NOT to use: to browse templates you could activate use " +
+            "apimapper_library_featured / apimapper_library_list; to activate one use " +
+            "apimapper_library_activate; to deactivate (deletes the connection) use " +
+            "apimapper_library_deactivate." +
             "\n\nExample:\n  apimapper_library_activated({})",
         inputSchema: {},
-        annotations: readOnly(),
+        annotations: readOnly({ title: "List Activated Library Connections", openWorld: true }),
     }, async () => {
         const r = await request("/library/activated");
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, undefined, { message: "library activated failed" });
         }
         // F-A4-01: PHP returns `connections`; tolerate legacy `items`.
-        const items = Array.isArray(r.data?.connections)
+        const items = (Array.isArray(r.data?.connections)
             ? r.data.connections
             : Array.isArray(r.data?.items)
                 ? r.data.items
-                : [];
-        return formatResult({ count: items.length, items }, false, { maxChars: 4000 });
+                : []);
+        return tableResult(items, {
+            columns: LIBRARY_TABLE_COLUMNS,
+            compactColumns: LIBRARY_COMPACT_COLUMNS,
+            // activated list rows are always activated — force the ✓ marker.
+            map: (i) => ({ ...mapLibraryRow(i), activated: "✓" }),
+            compactMap: (i) => ({ ...compactLibraryRow(i), activated: "✓" }),
+            header: (n) => `${n} activated library items`,
+            footer: "Library templates the user has activated.\n" +
+                "Next: apimapper_advanced({ tool: 'apimapper_library_deactivate', arguments: { id, confirm: true } }) to remove one · " +
+                "apimapper_connection_list({}) to inspect the underlying connections.",
+        });
     });
     // ── apimapper_library_activate ─────────────────────────────────────
+    // Wave-6 R1 (2026-05-29): For auth-protected templates (most APIs), the
+    // tool now auto-resolves `credential_id` when the user has exactly ONE
+    // OAuth credential matching the template's provider — and fails loudly
+    // (structured `credential_required` / `credential_ambiguous`) instead of
+    // landing a broken connection (empty endpoint, auth_type:none) when no
+    // unique match exists. Cold-AI #4 root cause: agents called
+    // `library_activate({id, extra_fields})` without a `credential_id`, the
+    // server-side defensive hydration silently fell through, and the resulting
+    // connection produced empty data the AI couldn't debug from the response.
     server.registerTool("apimapper_library_activate", {
         title: "Activate Library Template",
-        description: "Activate a library template — creates a new connection. REST contract: " +
-            "`extra_fields` (template placeholder values) + optional `library_connection` (template metadata override)." +
-            "\n\nExample:\n  apimapper_library_activate({ id: 'pexels', extra_fields: { api_key: 'a1b2c3d4...' } })",
+        description: "Activate a library template — creates a new connection. " +
+            "\n\n**FOR AUTH-PROTECTED TEMPLATES (most APIs incl. Google Sheets, Notion, " +
+            "Airtable, Pexels, OpenWeatherMap, Calendly, GitHub):** you MUST link a " +
+            "credential. The tool auto-links when exactly ONE matching credential exists " +
+            "for the template's provider; otherwise it fails with `credential_required` " +
+            "or `credential_ambiguous`. Pre-flight: call " +
+            "`apimapper_credential_list({})` and confirm a credential exists for the " +
+            "provider — if not, create one via `apimapper_oauth_authorize_begin` (OAuth) " +
+            "or `apimapper_advanced({tool:'apimapper_credential_create',arguments:{…}})` " +
+            "(api_key/bearer). " +
+            "\n\nREST contract: `extra_fields` (template placeholder values) + optional " +
+            "`library_connection` (template metadata override) + optional `credential_id`." +
+            "\n\nExamples:\n" +
+            "  apimapper_library_activate({ id: 'pexels', credential_id: 'cred_pexels', extra_fields: { api_key: '…' } })\n" +
+            "  apimapper_library_activate({ id: 'google-sheets', extra_fields: { spreadsheet_id: '1AbC…' } })  // auto-links the unique Google OAuth credential",
         inputSchema: {
             id: z.string().describe("Library item ID. Use apimapper_library_list to find."),
-            credential_id: z.string().optional().describe("Credential ID to link (required for auth-protected templates)"),
+            credential_id: z
+                .string()
+                .optional()
+                .describe("Credential ID. REQUIRED for auth-protected templates unless exactly " +
+                "one matching credential exists (then auto-linked). Use " +
+                "apimapper_credential_list({}) to find one, or " +
+                "apimapper_oauth_authorize_begin({provider}) to create one."),
             extra_fields: z
                 .record(z.string(), z.unknown())
                 .optional()
@@ -224,27 +502,159 @@ export function registerLibraryTools(server) {
                 .optional()
                 .describe('Optional template metadata override (rename connection, override base_url, etc.). ' +
                 'REST key: library_connection.'),
+            // F1 (2026-06-08): one credential can back MULTIPLE connections (one per
+            // resource — e.g. several Airtable bases). The backend reuses an
+            // existing connection only when the SAME resource (extra_fields) is
+            // requested AND that connection is healthy. Pass `force_new: true` to
+            // skip reuse entirely and always create a fresh connection (a distinct
+            // resource on the same credential). REST key: force_new.
+            force_new: z
+                .boolean()
+                .optional()
+                .describe("Force creation of a NEW connection even if a matching one exists " +
+                "(default: false → the backend reuses a healthy connection for the " +
+                "same resource). Set true when wiring a second/different resource " +
+                "on the same credential. REST key: force_new."),
         },
-        annotations: creating(),
-    }, async ({ id, credential_id, extra_fields, library_connection }) => {
+        // W1.26 (IA-1): activate is idempotent — re-activating the same template
+        // for the same resource yields the same connection (the backend returns
+        // the existing row instead of duplicating). mutating() is the correct
+        // semantic class.
+        annotations: mutating({ title: "Activate Library Connection", openWorld: true }),
+    }, async ({ id, credential_id, extra_fields, library_connection, force_new }) => {
+        // Wave-6 R1 (2026-05-29): Credential auto-resolution gate.
+        // When `credential_id` is missing AND the template has a non-none auth_type,
+        // fetch the template + credential list, try to auto-link a unique match,
+        // and fail-loud with a structured error when 0 or >1 candidates exist.
+        // The auto-link logic mirrors `apimapper_oauth_authorize_begin` (which
+        // resolves an OAuth credential by provider) but applies to ANY auth_type
+        // (api_key, bearer, basic_auth, oauth2_*).
+        let resolvedCredentialId = credential_id;
+        let autoLinkedFrom;
+        if (!resolvedCredentialId) {
+            // Fetch template metadata to discover its auth scheme.
+            const tr = await request(`/library/connections/${encodeURIComponent(id)}`);
+            if (tr.success && tr.data) {
+                const tplRaw = unwrapEntity(tr.data, "connection") ?? {};
+                const tplAuthType = templateAuthType(tplRaw);
+                const tplProvider = templateProvider(tplRaw);
+                if (templateRequiresCredential(tplAuthType)) {
+                    // Fetch credentials sanitised — we only need id/name/provider/auth_type.
+                    const cr = await request("/credentials", {}, { sanitize: true });
+                    if (!cr.success) {
+                        return restErrorResult(cr, { id, template_provider: tplProvider, template_auth_type: tplAuthType }, {
+                            message: "credential lookup failed during activation",
+                            // Per-site nuance: a domain code fallback + a fixed
+                            // activation-recovery suggestion override hintFor().
+                            code: "credential_lookup_failed",
+                            suggestion: "Retry, or pass an explicit `credential_id`. " +
+                                "Use apimapper_credential_list({}) to find one.",
+                        });
+                    }
+                    const allCreds = Array.isArray(cr.data?.credentials) ? cr.data.credentials : [];
+                    // Match by provider first; if template has no provider, fall back to auth_type.
+                    const candidates = tplProvider
+                        ? allCreds.filter((c) => credentialProviderSlug(c)?.toLowerCase() === tplProvider.toLowerCase())
+                        : allCreds.filter((c) => c.auth_type === tplAuthType);
+                    if (candidates.length === 0) {
+                        const providerHint = tplProvider ?? tplAuthType ?? "the template's provider";
+                        return errorResult({
+                            message: `Template "${id}" requires authentication (${tplAuthType}) but no matching ` +
+                                `credential exists for "${providerHint}".`,
+                            code: "credential_required",
+                            suggestion: `Create a credential first:\n` +
+                                `  • OAuth: apimapper_oauth_authorize_begin({ provider: "${tplProvider ?? "<provider>"}" })\n` +
+                                `  • api_key/bearer/basic: apimapper_advanced({ tool: "apimapper_credential_create", arguments: { auth_type: "${tplAuthType}", ... } })\n` +
+                                `Then retry apimapper_library_activate with the new credential_id.`,
+                            details: {
+                                id,
+                                template_provider: tplProvider,
+                                template_auth_type: tplAuthType,
+                                available_credentials: allCreds.map((c) => ({
+                                    id: c.id,
+                                    name: c.name,
+                                    provider: credentialProviderSlug(c),
+                                    auth_type: c.auth_type,
+                                })),
+                            },
+                        });
+                    }
+                    if (candidates.length > 1) {
+                        return errorResult({
+                            message: `Template "${id}" requires authentication and ${candidates.length} candidate ` +
+                                `credentials exist for "${tplProvider ?? tplAuthType}". Pass an explicit credential_id.`,
+                            code: "credential_ambiguous",
+                            suggestion: "Re-call apimapper_library_activate with one of the credential_ids below " +
+                                "(see `details.candidates`).",
+                            details: {
+                                id,
+                                template_provider: tplProvider,
+                                template_auth_type: tplAuthType,
+                                candidates: candidates.map((c) => ({
+                                    id: c.id,
+                                    name: c.name,
+                                    provider: credentialProviderSlug(c),
+                                    auth_type: c.auth_type,
+                                })),
+                            },
+                        });
+                    }
+                    // Exactly one match → auto-link.
+                    const picked = candidates[0];
+                    resolvedCredentialId = picked.id;
+                    autoLinkedFrom = {
+                        provider: credentialProviderSlug(picked),
+                        credentialName: picked.name,
+                    };
+                }
+            }
+            // Note: if template fetch fails or auth_type is "none"/missing, we
+            // fall through to the original (no credential) activation path. The
+            // server-side validator will still reject missing required extra_fields.
+        }
         const body = {};
-        if (credential_id)
-            body.credential_id = credential_id;
+        if (resolvedCredentialId)
+            body.credential_id = resolvedCredentialId;
         if (extra_fields)
             body.extra_fields = extra_fields;
         if (library_connection)
             body.library_connection = library_connection;
+        // F1 (2026-06-08): only send force_new when explicitly true — keep the
+        // request body minimal so a default activate stays byte-identical to the
+        // pre-F1 wire shape (the backend defaults to reuse).
+        if (force_new === true)
+            body.force_new = true;
         const r = await request(`/library/${encodeURIComponent(id)}/activate`, {
             method: "POST",
             body: JSON.stringify(body),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "library activate failed" });
         }
-        // F-A4-03: PHP returns `{success, connection: {id, ...}, reused?, flow?}`.
-        // Read the nested `connection` directly (we DO NOT use unwrapEntity here
-        // because its fall-back to `data` would surface the wrong `id` if the
-        // envelope key is missing).
+        // F1 (2026-06-08): the backend is now the SOLE authority on reuse vs.
+        // create vs. heal. One credential can back MANY connections (one per
+        // resource); the backend reuses a connection only when the SAME resource
+        // is requested AND that connection is healthy, and it NEVER mutates a
+        // healthy row. It reports its decision via three booleans on the response:
+        //
+        //   reused:true,  mutated:false             → existing healthy connection
+        //                                             returned unchanged.
+        //   reused:true,  healed:true, mutated:true → existing connection was
+        //                                             corrupt; the backend repaired
+        //                                             it in place.
+        //   (no reused / reused:false)              → a brand-new connection was
+        //                                             created (new resource or
+        //                                             force_new:true).
+        //
+        // The MCP layer no longer re-derives a mismatch and rejects after the
+        // fact (the old `connection_reused_with_stale_state` path assumed a
+        // mutation that the backend no longer performs). We simply INTERPRET the
+        // backend's booleans into a clear, human-readable status string.
+        //
+        // F-A4-03: PHP returns `{success, connection: {id, ...}, reused?, healed?,
+        // mutated?, flow?}`. Read the nested `connection` directly (we DO NOT use
+        // unwrapEntity here because its fall-back to `data` would surface the
+        // wrong `id` if the envelope key is missing).
         const dataObj = r.data && typeof r.data === "object" ? r.data : {};
         const conn = (dataObj.connection && typeof dataObj.connection === "object")
             ? dataObj.connection
@@ -254,16 +664,55 @@ export function registerLibraryTools(server) {
             (typeof dataObj.connectionId === "string" ? dataObj.connectionId : undefined) ||
             null;
         const reused = typeof dataObj.reused === "boolean" ? dataObj.reused : undefined;
+        const healed = typeof dataObj.healed === "boolean" ? dataObj.healed : undefined;
+        const mutated = typeof dataObj.mutated === "boolean" ? dataObj.mutated : undefined;
         const flowSummary = dataObj.flow && typeof dataObj.flow === "object"
             ? dataObj.flow
             : undefined;
+        // F1: derive a single status + note from the backend's decision booleans.
+        let status;
+        let note;
+        if (reused === true && healed === true) {
+            status = "reused_healed";
+            note =
+                "Reused (healed): an existing connection for this resource was corrupt " +
+                    "and the backend repaired it in place. No duplicate was created.";
+        }
+        else if (reused === true) {
+            status = "reused";
+            note =
+                "Reused (unchanged): a healthy connection already existed for this " +
+                    "resource and was returned as-is — no changes were made. Pass " +
+                    "force_new:true to create a separate connection for a different resource.";
+        }
+        else {
+            status = "activated";
+            note = "Connection created; use apimapper_connection_list to find the new id.";
+        }
         return formatResult({
             activated: true,
+            status,
             id,
             connection_id: connectionId,
-            reused,
+            // Wave-6 R1 — surface auto-link decision when the tool resolved
+            // the credential for the agent. Helps the AI confirm which
+            // credential ended up wired in (vs. a previously stored one).
+            ...(autoLinkedFrom
+                ? {
+                    auto_linked_credential: {
+                        credential_id: resolvedCredentialId,
+                        provider: autoLinkedFrom.provider,
+                        credential_name: autoLinkedFrom.credentialName,
+                    },
+                }
+                : {}),
+            // F1 — echo the backend's decision booleans verbatim so the agent
+            // can branch on them too (only when the backend supplied them).
+            ...(reused !== undefined ? { reused } : {}),
+            ...(healed !== undefined ? { healed } : {}),
+            ...(mutated !== undefined ? { mutated } : {}),
             flow: flowSummary,
-            note: "Connection created; use apimapper_connection_list to find the new id.",
+            note,
         }, false, { maxChars: 3000 });
     });
     // ── apimapper_library_deactivate ───────────────────────────────────
@@ -279,7 +728,7 @@ export function registerLibraryTools(server) {
                 .default(false)
                 .describe("Must be true to execute. Ask user for confirmation first."),
         },
-        annotations: destructive(),
+        annotations: destructive({ title: "Deactivate Library Connection", openWorld: true }),
     }, async ({ id, confirm }) => {
         if (!confirm) {
             return formatResult({
@@ -293,9 +742,145 @@ export function registerLibraryTools(server) {
             method: "DELETE",
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "library deactivate failed" });
         }
         return formatResult({ deactivated: true, id }, false, { maxChars: 1500 });
     });
 }
+/**
+ * Build a structured detail view for one library connection template.
+ * IA-7: technical IDs are copyable entries; IA-10: a dedicated "Next steps"
+ * group carries the actionable follow-up calls (visible in the LLM text).
+ */
+function buildConnectionDetail(id, connection) {
+    const str = (v) => typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : null;
+    const overviewAll = [
+        { key: "id", label: "ID", value: str(connection.id) ?? id, format: "code", copyable: true },
+        { key: "name", label: "Name", value: str(connection.name) },
+        { key: "provider", label: "Provider", value: str(connection.provider) },
+        { key: "category", label: "Category", value: str(connection.category) },
+        { key: "description", label: "Description", value: str(connection.description) },
+    ];
+    const overview = overviewAll.filter((e) => e.value !== null);
+    // Endpoints arrive as an array of objects. Friction-3 fix (Task #46,
+    // 2026-05-29): expand each endpoint to surface its NAME (not "Endpoint 1")
+    // and the list of required/optional extra_fields the template declares —
+    // those are the values an AI agent must pass into `library_activate({extra_fields})`.
+    const endpoints = Array.isArray(connection.endpoints) ? connection.endpoints : [];
+    const templateExtraFields = Array.isArray(connection.extra_fields)
+        ? connection.extra_fields
+        : [];
+    const endpointEntries = [
+        { key: "endpoint_count", label: "Endpoints", value: endpoints.length },
+        ...endpoints.flatMap((ep, idx) => {
+            const epObj = ep && typeof ep === "object" ? ep : {};
+            const name = str(epObj.name) ?? str(epObj.id) ?? `endpoint ${idx + 1}`;
+            const description = str(epObj.description) ?? str(epObj.label);
+            const path = str(epObj.path);
+            const method = str(epObj.method);
+            const entries = [
+                {
+                    key: `endpoint_${idx}_name`,
+                    label: `  ${idx + 1}. Name`,
+                    value: name,
+                    format: "code",
+                    copyable: true,
+                },
+            ];
+            if (description) {
+                entries.push({
+                    key: `endpoint_${idx}_description`,
+                    label: "     Description",
+                    value: description,
+                });
+            }
+            if (path || method) {
+                entries.push({
+                    key: `endpoint_${idx}_route`,
+                    label: "     Route",
+                    value: `${method ?? "GET"} ${path ?? "—"}`,
+                });
+            }
+            return entries;
+        }),
+    ];
+    // Friction-3 (Task #46): list required + optional extra_fields. AI agents
+    // need to know which keys MUST appear in the `extra_fields` argument of
+    // library_activate.
+    const extraFieldEntries = [];
+    if (templateExtraFields.length > 0) {
+        for (const ef of templateExtraFields) {
+            const efName = str(ef.name);
+            if (!efName)
+                continue;
+            const required = ef.required === true;
+            const efType = str(ef.type) ?? "string";
+            // Wave-8 C1 (2026-05-29): featured-connections templates ship the
+            // human-readable description under `help_text` (not `description`).
+            // The label-fallback was kept but now ranks below help_text so
+            // google-sheets' "Choose from your recent spreadsheets or paste a URL"
+            // surfaces instead of just "Spreadsheet".
+            const efDesc = str(ef.help_text) ??
+                str(ef.description) ??
+                str(ef.label) ??
+                "";
+            const efExample = str(ef.example) ?? str(ef.placeholder) ?? "";
+            const valueParts = [];
+            valueParts.push(`type=${efType}`);
+            if (required)
+                valueParts.push("REQUIRED");
+            else
+                valueParts.push("optional");
+            if (efExample)
+                valueParts.push(`e.g. "${efExample}"`);
+            if (efDesc)
+                valueParts.push(efDesc);
+            extraFieldEntries.push({
+                key: `extra_${efName}`,
+                label: `  ${efName}`,
+                value: valueParts.join(" · "),
+                format: "code",
+                copyable: true,
+            });
+        }
+    }
+    const auth = connection.auth_scheme && typeof connection.auth_scheme === "object"
+        ? connection.auth_scheme
+        : undefined;
+    const authEntries = auth
+        ? [{ key: "auth_type", label: "Auth scheme", value: str(auth.type) ?? "configured", format: "badge" }]
+        : [];
+    return detailResult({
+        title: str(connection.name) ?? id,
+        subtitle: str(connection.provider) ?? undefined,
+        badge: connection.is_activated
+            ? { text: "Activated", variant: "success" }
+            : { text: "Not activated", variant: "secondary" },
+        groups: [
+            { label: "Template", entries: overview },
+            ...(endpointEntries.length > 0 ? [{ label: "Endpoints", entries: endpointEntries }] : []),
+            ...(extraFieldEntries.length > 0
+                ? [{ label: "Required/Optional extra_fields", entries: extraFieldEntries }]
+                : []),
+            ...(authEntries.length > 0 ? [{ label: "Authentication", entries: authEntries }] : []),
+            {
+                // IA-10 (W3.9): actionable next steps in a dedicated group — visible
+                // in the LLM-readable detail text.
+                label: "Next steps",
+                entries: [
+                    {
+                        key: "activate",
+                        label: "Activate",
+                        value: `apimapper_library_activate({ id: '${id}' }) — creates a connection from this template`,
+                    },
+                    {
+                        key: "credentials",
+                        label: "Auth-protected?",
+                        value: "apimapper_credential_list({}) to find a credential_id, then pass it to library_activate",
+                    },
+                ],
+            },
+        ],
+    });
+}
 //# sourceMappingURL=library.js.map