@wootsup/mcp 0.1.0 → 0.4.0

package/dist/modules/apimapper/library.js

@@ -1,8 +1,114 @@
 import { z } from "zod";
 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";
+import { withOverflowFooter } from "./list-footer.js";
+import { normalizeResourceIdFields } from "./resource-id.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;
+}
+/**
+ * F51 (2026-06-10): reduce a provider slug to its OAuth credential FAMILY.
+ *
+ * One OAuth login backs many product-specific templates: a single Google
+ * credential serves google-sheets / google-drive / google-docs / gmail, a
+ * single Meta credential serves instagram / facebook, etc. Library templates
+ * ship a product-specific provider slug ("google-sheets"), but the stored
+ * credential carries the family slug ("google"). Exact-string matching then
+ * yields 0 candidates and the agent gets a false `credential_required` —
+ * a weaker agent would launch a redundant OAuth flow (the Run-C benchmark
+ * finding). Family matching closes that gap.
+ *
+ * Strategy is generic + prefix-based: strip a known family PREFIX, plus a
+ * small alias table for families whose members don't share a prefix (Meta).
+ * Returns the input lower-cased + trimmed when no family rule applies, so a
+ * provider with no family still equals itself (a no-op for non-family APIs).
+ */
+const PROVIDER_FAMILY_ALIASES = {
+    // Meta family members don't share a common prefix.
+    instagram: "meta",
+    facebook: "meta",
+    "facebook-pages": "meta",
+    whatsapp: "meta",
+    // Microsoft family.
+    outlook: "microsoft",
+    "microsoft-teams": "microsoft",
+    onedrive: "microsoft",
+};
+function providerFamily(slug) {
+    if (typeof slug !== "string")
+        return undefined;
+    const s = slug.toLowerCase().trim();
+    if (s === "")
+        return undefined;
+    if (s in PROVIDER_FAMILY_ALIASES)
+        return PROVIDER_FAMILY_ALIASES[s];
+    // Prefix families: "google-sheets" → "google", "microsoft-graph" → "microsoft".
+    const FAMILY_PREFIXES = ["google", "microsoft", "meta", "amazon", "zoho"];
+    for (const prefix of FAMILY_PREFIXES) {
+        if (s === prefix || s.startsWith(prefix + "-") || s.startsWith(prefix + "_")) {
+            return prefix;
+        }
+    }
+    return s;
+}
 /** F-14: best-effort JSON.stringify length. Falls back to 0 on cycle. */
 function computeCatalogSize(catalog) {
     try {
@@ -117,12 +223,7 @@ export function registerLibraryTools(server) {
         params.set("limit", String(limit));
         const r = await request(`/library?${params.toString()}`);
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library list failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { category, provider, activated, search, page, limit },
-            });
+            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)
@@ -142,7 +243,9 @@ export function registerLibraryTools(server) {
             map: mapLibraryRow,
             compactMap: compactLibraryRow,
             header: (n) => `${n} library items (page ${page})`,
-            footer: LIST_NEXT_STEPS,
+            // Minor (2026-06-10): overflow-aware footer (see list-footer.ts) — the
+            // full catalogue easily exceeds the 21-row compaction threshold.
+            footer: withOverflowFooter(LIST_NEXT_STEPS, items.length, "library items"),
         });
     });
     // ── apimapper_library_categories ───────────────────────────────────
@@ -163,11 +266,7 @@ export function registerLibraryTools(server) {
     }, async () => {
         const r = await request("/library/categories");
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library categories failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-            });
+            return restErrorResult(r, undefined, { message: "library categories failed" });
         }
         const cats = Array.isArray(r.data?.categories) ? r.data.categories : [];
         const rows = cats
@@ -199,7 +298,14 @@ export function registerLibraryTools(server) {
     // ── 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)"),
@@ -209,24 +315,30 @@ export function registerLibraryTools(server) {
         const params = new URLSearchParams({ limit: String(limit) });
         const r = await request(`/library/featured?${params.toString()}`);
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library featured failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { limit },
-            });
+            return restErrorResult(r, { limit }, { message: "library featured failed" });
         }
-        const items = Array.isArray(r.data?.connections)
+        const raw = Array.isArray(r.data?.connections)
             ? r.data.connections
             : Array.isArray(r.data?.items)
                 ? r.data.items
                 : [];
+        // Minor (2026-06-10) — the endpoint sometimes returns the WHOLE
+        // catalogue mislabelled "featured". Curate honestly:
+        //   - if any row carries a truthy `featured` flag, keep ONLY those;
+        //   - otherwise fall back to a top-N popularity slice (N ≤ 5) and SAY so
+        //     in the header instead of claiming the catalogue is the curated set.
+        const curated = raw.filter((c) => c.featured === true);
+        const usingFallback = curated.length === 0;
+        const FALLBACK_N = Math.min(5, limit);
+        const items = usingFallback ? raw.slice(0, FALLBACK_N) : curated;
         return tableResult(toRows(items), {
             columns: LIBRARY_TABLE_COLUMNS,
             compactColumns: LIBRARY_COMPACT_COLUMNS,
             map: mapLibraryRow,
             compactMap: compactLibraryRow,
-            header: (n) => `${n} featured library items`,
+            header: (n) => usingFallback
+                ? `${n} library items (no curated featured set — showing top ${n} by popularity)`
+                : `${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,
@@ -235,7 +347,13 @@ export function registerLibraryTools(server) {
     // ── 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)"),
@@ -245,12 +363,7 @@ export function registerLibraryTools(server) {
         const params = new URLSearchParams({ limit: String(limit) });
         const r = await request(`/library/popular?${params.toString()}`);
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library popular failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { limit },
-            });
+            return restErrorResult(r, { limit }, { message: "library popular failed" });
         }
         const items = Array.isArray(r.data?.connections)
             ? r.data.connections
@@ -278,27 +391,63 @@ export function registerLibraryTools(server) {
     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: {},
+            "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 () => {
+    }, 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 errorResult({
-                message: r.error ?? "library catalog failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-            });
+            return restErrorResult(r, undefined, { message: "library catalog failed" });
         }
         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: {
+            meta: {
                 size_bytes: sizeBytes,
                 item_count: itemCount,
             },
@@ -316,12 +465,7 @@ export function registerLibraryTools(server) {
     }, async ({ id }) => {
         const r = await request(`/library/connections/${encodeURIComponent(id)}`);
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library connection detail failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            return restErrorResult(r, { id }, { message: "library connection detail failed" });
         }
         if (!r.data || (typeof r.data === "object" && Object.keys(r.data).length === 0)) {
             return errorResult({
@@ -339,18 +483,21 @@ export function registerLibraryTools(server) {
     // ── 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({ title: "List Activated Library Connections", openWorld: true }),
     }, async () => {
         const r = await request("/library/activated");
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library activated failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-            });
+            return restErrorResult(r, undefined, { message: "library activated failed" });
         }
         // F-A4-01: PHP returns `connections`; tolerate legacy `items`.
         const items = (Array.isArray(r.data?.connections)
@@ -371,52 +518,260 @@ export function registerLibraryTools(server) {
         });
     });
     // ── 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\n⚠️ Template fields passed at the TOP LEVEL of the call are silently " +
+            "ignored (the schema strips unknown keys) — they MUST be nested under " +
+            "`extra_fields` (F186)." +
+            "\n\n**REQUIRED extra_fields per template (the install 422s with " +
+            "`incomplete_setup` if any are missing — pass them up front):**\n" +
+            "  - google-sheets: `spreadsheet_id` (bare ID or Drive/Sheets URL) AND " +
+            "`range` (A1 notation, e.g. 'A1:Z1000'; tab-qualified 'Sheet-Tab!A:Z' or " +
+            "open-ended 'A:Z' forms are valid; the tab name is OPTIONAL).\n" +
+            "  - google-docs: `document_id`.\n" +
+            "  - airtable: `base_id` AND `table_name`.\n" +
+            "  - strapi: `site_url` AND `content_type`.\n" +
+            "  (Call apimapper_library_connection_detail({ id }) to read the exact " +
+            "required/optional extra_fields + examples for ANY template.)\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…', range: 'A1:Z1000' } })  // 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()
-                .describe('Template placeholder values (e.g., {"spreadsheet_id":"...","user_uri":"..."}). REST key: extra_fields.'),
+                .describe('Template placeholder values. REST key: extra_fields. Each library ' +
+                'template declares its own required/optional keys — read them via ' +
+                'apimapper_library_connection_detail({ id }). Common required sets:\n' +
+                '  • google-sheets: { spreadsheet_id, range }. spreadsheet_id may be the ' +
+                'bare ID or a full Drive/Sheets URL ' +
+                '(https://docs.google.com/spreadsheets/d/<ID>/edit) — a pasted URL is ' +
+                'auto-extracted to the bare ID (A5). `range` is A1 notation, ' +
+                'e.g. "A1:Z1000"; a tab-qualified "Sheet-Tab!A:Z" or open-ended "A:Z" ' +
+                'form is also valid and the tab name is OPTIONAL.\n' +
+                '  • airtable: { base_id, table_name }.  • strapi: { site_url, content_type }.  ' +
+                '• google-docs: { document_id }.'),
             library_connection: z
                 .record(z.string(), z.unknown())
                 .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."),
         },
         // W1.26 (IA-1): activate is idempotent — re-activating the same template
-        // yields the same connection (PHP returns the existing row instead of
-        // duplicating). mutating() is the correct semantic class.
+        // 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 }) => {
+    }, 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.
+                    let candidates = tplProvider
+                        ? allCreds.filter((c) => credentialProviderSlug(c)?.toLowerCase() === tplProvider.toLowerCase())
+                        : allCreds.filter((c) => c.auth_type === tplAuthType);
+                    // F51 (2026-06-10): when an EXACT provider match yields nothing,
+                    // fall back to provider-FAMILY matching (google-sheets → google).
+                    // Exact match always wins (we only reach here on 0 exact hits), so
+                    // a Sheets-specific credential is preferred over a generic Google
+                    // one when both exist. familyMatched flags the response so the
+                    // agent can confirm the auto-link reused an existing credential
+                    // instead of demanding a fresh OAuth flow.
+                    let familyMatched = false;
+                    if (candidates.length === 0 && tplProvider) {
+                        const tplFamily = providerFamily(tplProvider);
+                        if (tplFamily) {
+                            candidates = allCreds.filter((c) => providerFamily(credentialProviderSlug(c)) === tplFamily);
+                            familyMatched = candidates.length > 0;
+                        }
+                    }
+                    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,
+                        familyMatched,
+                    };
+                }
+            }
+            // 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;
+        // A5 (2026-06-10): normalize a pasted Drive/Sheets URL in
+        // extra_fields.spreadsheet_id to the bare ID before it hits the activate
+        // endpoint — the {{spreadsheet_id}} placeholder needs the bare id, and
+        // the cold-agent customer supplies only a URL.
         if (extra_fields)
-            body.extra_fields = extra_fields;
+            body.extra_fields = normalizeResourceIdFields(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 errorResult({
-                message: r.error ?? "library activate failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            // F186 (2026-06-12): the most common cause of a missing-fields 422
+            // WITHOUT extra_fields in the call is that the caller passed the
+            // template fields at the TOP LEVEL — the schema layer silently
+            // stripped them. Name the fix explicitly instead of letting the
+            // agent re-guess.
+            const missingFields = /missing required field/i.test(String(r.error ?? ""));
+            if (missingFields && !extra_fields) {
+                return restErrorResult(r, { id }, {
+                    message: "library activate failed",
+                    suggestion: "If you passed the template fields (e.g. spreadsheet_id, range) as " +
+                        "top-level arguments they were ignored — nest them under " +
+                        "extra_fields: apimapper_library_activate({ id, extra_fields: { … } }).",
+                });
+            }
+            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
@@ -426,16 +781,61 @@ 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,
+                        // F51 — when true, the credential was matched by OAuth
+                        // FAMILY (e.g. a "google" credential for a "google-sheets"
+                        // template) rather than an exact provider string. Surfaced
+                        // so the agent confirms an existing credential was reused
+                        // instead of needing a fresh OAuth flow.
+                        ...(autoLinkedFrom.familyMatched ? { family_matched: true } : {}),
+                    },
+                }
+                : {}),
+            // 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 ───────────────────────────────────
@@ -465,12 +865,7 @@ export function registerLibraryTools(server) {
             method: "DELETE",
         });
         if (!r.success) {
-            return errorResult({
-                message: r.error ?? "library deactivate failed",
-                code: r.errorCode ?? (r.status ? String(r.status) : undefined),
-                suggestion: hintFor(r.errorCode),
-                details: { id },
-            });
+            return restErrorResult(r, { id }, { message: "library deactivate failed" });
         }
         return formatResult({ deactivated: true, id }, false, { maxChars: 1500 });
     });
@@ -490,21 +885,88 @@ function buildConnectionDetail(id, connection) {
         { key: "description", label: "Description", value: str(connection.description) },
     ];
     const overview = overviewAll.filter((e) => e.value !== null);
-    // Endpoints arrive as an array of objects — surface the count plus each
-    // endpoint's label so the detail view stays scalar-only.
+    // 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.map((ep, idx) => {
+        ...endpoints.flatMap((ep, idx) => {
             const epObj = ep && typeof ep === "object" ? ep : {};
-            const label = str(epObj.label) ?? str(epObj.id) ?? `endpoint ${idx + 1}`;
-            return {
-                key: `endpoint_${idx}`,
-                label: `  ${str(epObj.id) ?? idx + 1}`,
-                value: label,
-            };
+            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;
@@ -520,6 +982,9 @@ function buildConnectionDetail(id, connection) {
         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