@zackbart/connecta 0.16.0 → 0.17.0

package/dist/routes/mcp.js

@@ -234,6 +234,9 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
                 ? { discoveryConcurrency: opts.discoveryConcurrency }
                 : {}),
             requestSignal: request.signal,
+            ...(runtimeContext?.waitUntil
+                ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+                : {}),
         });
         registerExecuteTool(server, registry, {
             baseUrl,
@@ -241,6 +244,9 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
             logger: opts.logger,
             ...(activity ? { activity } : {}),
             requestSignal: request.signal,
+            ...(runtimeContext?.waitUntil
+                ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+                : {}),
             ...(opts.discoveryConcurrency !== undefined
                 ? { discoveryConcurrency: opts.discoveryConcurrency }
                 : {}),

package/dist/skills.d.ts

@@ -10,6 +10,10 @@ export declare function hasConnectorGuides(connectors: readonly Connector[]): bo
 export declare function connectorSkillName(connectorId: string): string;
 /** The connector's guide, or undefined when it declares none (or a blank one). */
 export declare function connectorGuide(connector: Connector): string | undefined;
+/** Discovery budget for one connector-guide summary, including an ellipsis. */
+export declare const GUIDE_SUMMARY_LENGTH = 120;
+/** Normalize authored and derived summaries under one construction contract. */
+export declare function normalizeGuideSummary(summary: string): string | undefined;
 /** Bounded, decision-useful discovery summary for a connector guide. */
 export declare function connectorGuideSummary(connector: Connector): string | undefined;
 /** Whether correct use always depends on conventions outside the tool schema. */

package/dist/skills.js

@@ -17,24 +17,24 @@ Use exact addresses from discovery; never invent one. Search 2–4 distinctive a
 
 ## Inside a program
 
-One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the \`connecta\` functions, and \`console.log\`.
+Portable code uses only connector globals (\`<connectorId>.<toolName>(args)\`), \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch/process/timers/crypto/WebSocket. Dynamic Workers require only \`{ loader }\`; bindings/modules/globalOutbound violate it. Then env maps are empty; node:fs/http/https absent; outbound fetch/WebSocket/node:net/tls denied; DNS unresolved. Runtime builtins remain through import() and process.getBuiltinModule(), including node:path and cloudflare:workers; the set can drift. Timers/process/crypto/WebSocket and data: fetch remain. Avoid them; QuickJS fails.
 
 - \`connecta.search({})\` loads all catalogs; pass \`connector: "<id>"\` when obvious to load one. \`safety: "readOnly"\` keeps executable calls. Neither grants authority. Matches carry \`address\` and annotations.
 - Exact schemas: \`connecta.describe({ address: "connector.tool" })\` for one, \`{ addresses: [...] }\` for many; \`format: "json"\` only for exact constraints.
-- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\` — how a program tells a policy refusal from a transient failure.
-- Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.
+- Caught Connecta errors have \`message\`, \`code\`, \`retryable\`, and \`details\`; branch on fields. For 2–10 independent calls, \`connecta.batch([...])\` returns success data or an \`errorDetails\` whose code and retryable flag match the throw.
+- Search inside the run; return only the reduction the answer needs, never raw payloads.
 - Only tools annotated \`readOnlyHint: true\` are reachable; the gate, credentials, and admission are enforced below the sandbox — nothing a program does widens its reach.
 
 ## Rendering a view
 
-\`connecta.ui(html)\` renders a display-only view on success for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
+\`connecta.ui(html)\` renders one success-only display view, never for the model. Fetch and check the shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables; the model reads the return value, not the view.
 
 `;
 /** Deployment-scoped guide routing appended to the shared usage guide. */
 const CONNECTOR_GUIDES_SECTION = `
 ## Per-connector guides
 
-When a connector here ships a deployment-scoped usage guide, \`skills({})\` and discovery return the exact \`guide\` name plus a bounded \`guideSummary\` saying what it covers. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop: fetch before calling. \`guideRequiredReasons\` says why — \`connector_required\` and \`approval_required\` stand however you expand the schema; \`schema_truncated\` clears once describe returns the exact one. Otherwise fetch when the summary names a connector-specific sequence, unit, pagination rule, alias, or generic API convention relevant to the task. A read-only call whose compact schema is complete and unambiguous may proceed without fetching an otherwise irrelevant guide. Connector guides do not replace the shared Connecta usage guide and never apply to another deployment implicitly.
+Connector guides appear in \`skills({})\` and discovery with an exact \`guide\` name and bounded \`guideSummary\`. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop. \`guideRequiredReasons\` says why: \`connector_required\` and \`approval_required\` stand after schema expansion; \`schema_truncated\` clears after exact describe. Otherwise fetch for a relevant sequence, unit, pagination rule, alias, or API convention. A read-only call with a complete compact schema may skip an irrelevant guide. Connector guides never apply to another deployment.
 `;
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
@@ -80,17 +80,63 @@ export function connectorGuide(connector) {
     const content = typeof guide === "string" ? guide : guide?.content;
     return content && content.trim() !== "" ? content : undefined;
 }
-const SUMMARY_LENGTH = 120;
+/** Discovery budget for one connector-guide summary, including an ellipsis. */
+export const GUIDE_SUMMARY_LENGTH = 120;
 /** A `---`/`***`/`___` rule, which also opens and closes YAML frontmatter. */
 const RULE_RE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
 /** A fenced code block's delimiter. */
 const FENCE_RE = /^\s*(?:```|~~~)/;
+/** Markdown blocks that end a paragraph without a blank physical line. */
+const HEADING_RE = /^\s*#{1,6}/;
+const LIST_ITEM_RE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)/;
+const SETEXT_UNDERLINE_RE = /^\s*=+\s*$/;
+const TABLE_DELIMITER_RE = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+const OPENS_CLAUSE_RE = /^(?:The|A|An)\b/u;
+const ARTICLE_RE = /^(?:the|a|an)\b/u;
 /**
  * Markup that carries no summary text of its own: horizontal rules, HTML
  * comments, and table rows. Skipped so a guide that opens with one is
  * summarized by its first real line instead of by punctuation.
  */
 const NOT_SUMMARY_RE = /^\s*(?:<!--|\|)|^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+/** A standard Markdown table starts with a pipe-bearing row and delimiter. */
+function startsTable(lines, index) {
+    const header = lines[index] ?? "";
+    const delimiter = lines[index + 1] ?? "";
+    return header.includes("|") && TABLE_DELIMITER_RE.test(delimiter);
+}
+/** True when a sentence-looking period belongs to an abbreviation. */
+function isAbbreviation(text, end) {
+    const token = text.slice(0, end).match(/\S+$/u)?.[0] ?? "";
+    // These introduce an example or restatement even before a capitalized word.
+    if (/^(?:e\.g|i\.e)\.$/iu.test(token))
+        return true;
+    // An initial or title belongs to the proper name that follows it.
+    if (/^[A-Z]\.$/u.test(token))
+        return true;
+    if (/^(?:Mr|Mrs|Ms|Dr|Prof|Sr|Jr|St)\.$/iu.test(token))
+        return true;
+    if (!/^(?:[A-Za-z]\.){2,}$/u.test(token) &&
+        !/^(?:vs|etc|approx|dept|fig|no)\.$/iu.test(token)) {
+        return false;
+    }
+    // Initialisms can end a sentence or extend a name ("U.S. East region").
+    // The mistakes are asymmetric: a false ending presents a fragment as a
+    // complete thought, while a missed ending gets an honest ellipsis. Count
+    // the period only with narrow evidence of a new clause: an article in one
+    // of its first two words. This is grammar evidence, not a starter-word list.
+    const following = text
+        .slice(end)
+        .match(/^[)\]}'"”’]*\s+(\S+)(?:\s+(\S+))?/u);
+    if (!following)
+        return false;
+    const [, nextWord, afterNext] = following;
+    const startsClause = nextWord !== undefined &&
+        /^\p{Lu}/u.test(nextWord) &&
+        (OPENS_CLAUSE_RE.test(nextWord) ||
+            (afterNext !== undefined && ARTICLE_RE.test(afterNext)));
+    return !startsClause;
+}
 /** Drop a leading YAML frontmatter block — metadata, not summary text. */
 function withoutFrontmatter(lines) {
     let start = 0;
@@ -102,33 +148,107 @@ function withoutFrontmatter(lines) {
     const close = lines.findIndex((line, i) => i > start && RULE_RE.test(line));
     return close === -1 ? lines : lines.slice(close + 1);
 }
+/** Normalize authored and derived summaries under one construction contract. */
+export function normalizeGuideSummary(summary) {
+    const normalized = summary.replace(/\s+/g, " ").trim();
+    return normalized === "" ? undefined : normalized;
+}
 /**
- * One line describing a guide, for the cheap list view: the guide's first
- * meaningful line (heading marks and list bullets stripped), falling back to
- * the connector's own description when the guide opens with nothing but
- * markup.
+ * Shorten a normalized summary at the strongest readable boundary available.
+ * A complete sentence needs no ellipsis; clause and word cuts do, so discovery
+ * never presents an unfinished fragment as the guide's complete thought.
  */
 function boundedSummary(summary) {
-    const line = summary.replace(/\s+/g, " ").trim();
-    if (line === "")
+    const normalized = normalizeGuideSummary(summary);
+    if (!normalized)
         return undefined;
-    return line.length <= SUMMARY_LENGTH
-        ? line
-        : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+    if (normalized.length <= GUIDE_SUMMARY_LENGTH)
+        return normalized;
+    const contentBudget = GUIDE_SUMMARY_LENGTH - 1;
+    let sentenceEnd = 0;
+    const sentenceBoundary = /[.!?…。！？](?:[)\]}'"”’]+)?(?=\s|$)/gu;
+    for (const match of normalized.matchAll(sentenceBoundary)) {
+        const end = (match.index ?? 0) + match[0].length;
+        if (end > GUIDE_SUMMARY_LENGTH)
+            break;
+        const punctuationEnd = (match.index ?? 0) + 1;
+        if (match[0].startsWith(".") &&
+            isAbbreviation(normalized, punctuationEnd)) {
+            continue;
+        }
+        // Do not mistake another short fragment for a useful complete thought.
+        if (end >= 24)
+            sentenceEnd = end;
+    }
+    if (sentenceEnd > 0)
+        return normalized.slice(0, sentenceEnd);
+    const available = normalized.slice(0, contentBudget);
+    let clauseEnd = 0;
+    const clauseBoundary = /[,;:](?=\s)|\s[—–-](?=\s)/g;
+    for (const match of available.matchAll(clauseBoundary)) {
+        const end = match.index ?? 0;
+        // Prefer a clause only when it retains most of the discovery budget.
+        if (end >= 80)
+            clauseEnd = end;
+    }
+    if (clauseEnd > 0) {
+        return `${available.slice(0, clauseEnd).trimEnd()}…`;
+    }
+    const wordEnd = available.search(/\s+\S*$/);
+    if (wordEnd > 0) {
+        const prefix = available
+            .slice(0, wordEnd)
+            .trimEnd()
+            .replace(/[,;:([{—–-]+$/u, "")
+            .trimEnd();
+        if (prefix !== "")
+            return `${prefix}…`;
+    }
+    let hardEnd = contentBudget;
+    const code = normalized.charCodeAt(hardEnd - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        hardEnd--;
+    return `${normalized.slice(0, hardEnd)}…`;
 }
+/**
+ * One thought describing a guide for the cheap list view: the first meaningful
+ * paragraph, joined across physical lines, with headings and the connector
+ * description as fallbacks when the guide opens with markup alone.
+ */
 function summarizeGuide(connector, guide) {
+    const lines = withoutFrontmatter(guide.split("\n"));
     let inFence = false;
+    let inComment = false;
     let headingFallback;
-    for (const raw of withoutFrontmatter(guide.split("\n"))) {
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index] ?? "";
+        if (inComment) {
+            if (raw.includes("-->"))
+                inComment = false;
+            continue;
+        }
         if (FENCE_RE.test(raw)) {
             inFence = !inFence;
             continue;
         }
         if (inFence)
             continue;
+        if (raw.trimStart().startsWith("<!--")) {
+            if (!raw.includes("-->"))
+                inComment = true;
+            continue;
+        }
+        if (startsTable(lines, index)) {
+            index++;
+            while (index + 1 < lines.length &&
+                (lines[index + 1] ?? "").includes("|")) {
+                index++;
+            }
+            continue;
+        }
         if (raw.trim() === "" || NOT_SUMMARY_RE.test(raw))
             continue;
-        const heading = /^\s*#{1,6}/.test(raw);
+        const heading = HEADING_RE.test(raw);
         const line = raw
             // `\s*` (not `\s+`) so a bare `#` strips to nothing and is skipped, and
             // an unspaced `#Heading` is still read as a heading.
@@ -142,7 +262,24 @@ function summarizeGuide(connector, guide) {
             headingFallback ??= boundedSummary(line);
             continue;
         }
-        return boundedSummary(line) ?? line;
+        const paragraph = [line];
+        while (index + 1 < lines.length) {
+            const next = lines[index + 1] ?? "";
+            if (next.trim() === "" ||
+                startsTable(lines, index + 1) ||
+                FENCE_RE.test(next) ||
+                HEADING_RE.test(next) ||
+                LIST_ITEM_RE.test(next) ||
+                SETEXT_UNDERLINE_RE.test(next) ||
+                NOT_SUMMARY_RE.test(next)) {
+                break;
+            }
+            paragraph.push(next.trim());
+            index++;
+            if (paragraph.join(" ").length > GUIDE_SUMMARY_LENGTH)
+                break;
+        }
+        return boundedSummary(paragraph.join(" ")) ?? line;
     }
     if (headingFallback)
         return headingFallback;
@@ -155,6 +292,8 @@ export function connectorGuideSummary(connector) {
     if (!guide)
         return undefined;
     const configured = typeof connector.usageGuide === "object"
+        // Registry construction rejects over-budget configured summaries. Keep
+        // normalization here so direct Connector callers see the same text.
         ? boundedSummary(connector.usageGuide.summary ?? "")
         : undefined;
     return configured ?? summarizeGuide(connector, guide);

package/dist/types.d.ts

@@ -180,6 +180,12 @@ export interface CatalogDriftReport extends CatalogDriftCounts {
     /** When the observation was taken; never when a probe was scheduled. */
     observedAt: string;
 }
+/** The last agent-facing catalog read this runtime served for one connector. */
+export interface CatalogAccessObservation {
+    /** Fresh means the read used a live or unexpired catalog; stale means SWR. */
+    state: "fresh" | "stale";
+    observedAt: string;
+}
 export interface ConnectorStatus {
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
@@ -193,6 +199,11 @@ export interface ConnectorStatus {
      * isolate or process has seen nothing, not that nothing drifted.
      */
     catalogDrift?: CatalogDriftReport;
+    /**
+     * The last agent-facing catalog read in this runtime. This payload-free
+     * observation is not persisted and operator reads do not replace it.
+     */
+    catalogAccess?: CatalogAccessObservation;
 }
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
@@ -313,8 +324,9 @@ export interface ConnectorUsageGuide {
     /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
     content: string;
     /**
-     * Bounded discovery hint describing the conventions the guide covers. When
-     * omitted, Connecta derives a summary from the guide's first meaningful line.
+     * Discovery hint describing the conventions the guide covers. Whitespace is
+     * normalized, and a value over 120 characters throws at construction. When
+     * omitted, Connecta derives a bounded summary from the first body paragraph.
      */
     summary?: string;
     /**

package/dist/ui.js

@@ -374,6 +374,9 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
             // `boundedCatalogDrift`, so what lands here cannot carry a name or a
             // schema even if the plugin seam returned one.
             ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
+            ...(status.catalogAccess
+                ? { catalogAccess: status.catalogAccess }
+                : {}),
             ...(c.disconnectAuth && c.startAuth ? { oauth: true } : {}),
             ...(credential ? { credential } : {}),
         };
@@ -461,7 +464,7 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
             : `<span class="product">${escapeHtmlAttr(brand.productName)}</span>`
         : "";
     const clerkScript = clerk && clerkScriptOrigin
-        ? `<script${nonceAttr} defer crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
     return `<!doctype html>
 <html lang="en">

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.16.0";
+export declare const CONNECTA_VERSION = "0.17.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.16.0";
+export const CONNECTA_VERSION = "0.17.0";

package/documentation/architecture.md

@@ -26,7 +26,10 @@ ethos invariant, not a style preference: a client retained across requests on
 Workers is a cross-request capability leak, and a promise awaited after the
 response is work the runtime may have already torn down. Deferred work has one
 sanctioned channel — `ctx.waitUntil`, threaded through `fetch(request, env,
-ctx)` and used for best-effort activity writes.
+ctx)`. Best-effort activity writes use it. An agent read that already demanded
+an expired catalog refresh may also use it while serving a complete catalog
+inside its stale window. That refresh owns a new scope and deadline; it never
+carries the inbound scope or signal past the request.
 
 The registry is deliberately on the long side of that line and the MCP server
 deliberately on the short side. A fresh `McpServer` per request is what makes
@@ -87,8 +90,8 @@ owns or hands out, and a change usually belongs in exactly one of them:
 
 | Module | Owns |
 | --- | --- |
-| `src/registry.ts` | The connector set, id validation, address resolution, connector health, per-connector call limiters, and the drift snapshot. Construction-time refusal of structural mistakes lives here. |
-| `src/catalog-service.ts` | Tool listing: cold-load coalescing, TTL, persistence as manifest plus revision-addressed chunks, stale fallback, and the completeness rule — a partial catalog is a failure, never a cache write. |
+| `src/registry.ts` | The connector set, address resolution, catalog TTL/persistence/completeness, shared refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
+| `src/catalog-service.ts` | Request-local tool listing, search, and describe. It coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
 | `src/invocation.ts` | One tool call: argument validation, call admission, per-attempt timeout, retry with the connector's own `Retry-After` honoured exactly or declined, result unwrapping, size capping, and the activity record. |
 | `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
 
@@ -137,7 +140,7 @@ src/
   apps-shell.ts       the one build-time MCP Apps template
   skills.ts           MCP instructions, the usage skill, connector guides
   registry.ts         connector set, addresses, health, call limiters
-  catalog-service.ts  catalog loading, caching, persistence, stale fallback
+  catalog-service.ts  request-local catalog access, search, and describe
   catalog.ts          ranking, summaries, compact schema rendering
   invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces

package/documentation/cloudflare.md

@@ -2,7 +2,7 @@
 
 Import `cloudflare()` independently from
 `@zackbart/connecta/providers/cloudflare`. It is a deliberate, hand-written
-surface over Cloudflare's v4 REST API. Fifty-two tools combine ergonomic,
+surface over Cloudflare's v4 REST API. Fifty-one tools combine ergonomic,
 fully described operations for common work with three guarded escape hatches
 for the rest of Cloudflare's fast-moving control plane. Reads, JSON mutations,
 and raw/multipart uploads remain separate so safety routing does not depend on
@@ -140,7 +140,7 @@ projections:
 
 | Area | Reads | Writes |
 | --- | --- | --- |
-| Zones | discovery, details, settings, rulesets | update a setting |
+| Zones | discovery, details, one setting at a time, rulesets | update a setting |
 | DNS/cache | list and get records | create, update, delete, targeted/full purge |
 | Workers | scripts, settings, deployments | delete a script |
 | KV | namespaces, keys, bulk values | create/rename/delete namespace, bulk write/delete |
@@ -158,9 +158,10 @@ asserts those properties rather than leaving them as a claim.
 A named tool is a permanent line item in every deployment's catalog, so the
 surface was measured against the escape hatches rather than assumed to beat
 them ([#350](https://github.com/zackbart/connecta/issues/350), evidence in
-[`eval/current-version/results/issue-350-evidence.md`](../eval/current-version/results/issue-350-evidence.md)).
-Two named tools lost that comparison, and a third followed one of them off the
-surface to keep a policy pair on one route:
+[`eval/current-version/results/issue-350-evidence.md`](https://github.com/zackbart/connecta/blob/main/eval/current-version/results/issue-350-evidence.md)).
+Two named tools lost that comparison, a third followed one of them off the
+surface to keep a policy pair on one route, and a fourth left because
+Cloudflare deprecated the only endpoint it could call:
 
 - **R2 CORS writes.** `set_r2_cors` declared its rule list as free-form objects
   — the untyped body this connection refuses everywhere else — so its schema
@@ -181,8 +182,31 @@ surface to keep a policy pair on one route:
   path, and returned the response untouched — `cloudflare_api_get` at
   `/accounts/{accountId}/r2/metrics` does the same thing without a permanent
   catalog line.
-
-The surviving 48 named tools all refuse malformed arguments locally, which is
+- **The bulk zone-settings read.** `list_zone_settings` called
+  `GET /zones/{zoneId}/settings`, which Cloudflare's published document now
+  marks `deprecated: true` along with its `PATCH` sibling
+  ([#361](https://github.com/zackbart/connecta/issues/361)). There is no bulk
+  replacement to repoint it at: the supported operations are the per-setting
+  `GET` and `PATCH /zones/{zoneId}/settings/{settingId}` that `get_zone_setting`
+  and `update_zone_setting` already call. Keeping the tool would have meant
+  maintaining a name over a contract Cloudflare has announced it intends to
+  stop honouring — and #350 had already measured this one as the sharpest
+  passthrough on the surface: it took a zone id, projected nothing, and *grew*
+  the payload 22.7% by wrapping Cloudflare's settings array in a page object an
+  unpaginated endpoint never filled. Read one setting with `get_zone_setting`.
+  Where the whole set is genuinely wanted — an audit, a config diff — an
+  operator can still ask for it explicitly through `cloudflare_api_get` at
+  `/zones/{zoneId}/settings`, which is the honest place for a call whose
+  endpoint is on its way out: named by the caller, at the caller's risk, rather
+  than promised by connecta's catalog.
+
+Because `scripts/drift/cloudflare-endpoints.json` records the endpoints this
+connection *calls*, dropping the tool drops the row — so
+`npm run drift:check -- --specs` is quiet about zone settings by construction
+rather than by a recorded exception. A path reached only through a hatch is
+named by the caller, so it was never a touched endpoint.
+
+The surviving 47 named tools all refuse malformed arguments locally, which is
 the one thing no escape hatch can do: a hatch's path is an opaque string, so it
 can only check that a path is a path.
 
@@ -324,9 +348,17 @@ the failure message so the provider's own code number survives to the agent.
 | 401 or 403 | `auth_required`, not retryable | Stops and reports which permission is missing |
 | 400 with a credential-shaped code (1001, 6003, 6111, 9103, 9106, 9107) | `auth_required`, not retryable | Stops; the header or key is malformed, not the arguments |
 | 400, 409, 422 | `invalid_args`, not retryable | Repairs the arguments |
-| 404 | `connector_call_failed`, not retryable | Re-runs discovery for the id |
+| 404 | `not_found`, not retryable | Re-runs discovery for the id |
 | 5xx or a transport error | `unavailable`, retryable | Retries |
 
+The 404 row is the unambiguous half of the `not_found` rule
+([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next)).
+Cloudflare refuses a token that may not touch a resource with 401 or 403, so a
+404 is an absence rather than a permission gap wearing a miss, and an agent can
+act on it: confirm the zone or account id with `list_zones` or `list_accounts`
+and address the right one. Notion's 404, which proves neither, stays
+`connector_call_failed`.
+
 The six credential-shaped codes deserve a caveat: Cloudflare publishes no
 official table mapping error codes to causes, so that set is assembled from
 community reports and probing, not from documentation. The same goes for the

package/documentation/code-first-exploration.md

@@ -13,7 +13,7 @@
 >   constraint below was dropped.** The owner decided the default directly on
 >   2026-07-30 and [#224](https://github.com/zackbart/connecta/issues/224)
 >   shipped it; the ethos records the eval-as-gate as `removed` and
->   [`eval/code-first-gate`](../eval/code-first-gate/README.md) continues as
+>   [`eval/code-first-gate`](https://github.com/zackbart/connecta/blob/main/eval/code-first-gate/README.md) continues as
 >   measurement that nothing waits on.
 
 ## Executive summary
@@ -227,7 +227,7 @@ changing the default surface. Run at least 20 independent samples per task and
 model, with prompt variation.
 
 That suite was built under
-[`eval/code-first-gate`](../eval/code-first-gate/README.md). Its recorded results
+[`eval/code-first-gate`](https://github.com/zackbart/connecta/blob/main/eval/code-first-gate/README.md). Its recorded results
 remain as measurement history; the runnable comparison was retired when #273
 removed the alternate deployment shapes.