@zackbart/connecta 0.16.0 → 0.16.1

package/AGENTS.md

@@ -83,11 +83,18 @@ Two boundaries CI enforces that are not obvious from reading a file:
   and fails otherwise. Need a Node API? It goes behind an explicit Node-only
   subpath (`/node` or `/quickjs`), never the root.
 - **The published surface.** Platform-specific storage adapters live in
-  `examples/`, not the package. `@clerk/backend` and `quickjs-emscripten` are
-  optional peers behind the `./auth/clerk` and `./quickjs` subpaths and must
-  never become dependencies or install with core. Enforced by
-  `test/package-surface.test.ts` and `scripts/check-package.mjs`. Anything
-  heavyweight or platform-bound gets a subpath and an optional peer.
+  `examples/worker/`, never in `src/` and never in the `exports` map. That
+  example does ship in the tarball, Cloudflare KV and D1 adapters included —
+  it is the Workers starting template a consumer copies, and copying it is the
+  point — but every `exports` target resolves into `dist/`, so those adapters
+  are readable reference source and not an importable subpath. What is
+  forbidden is a platform-bound adapter becoming importable from the package,
+  not a file appearing in the artifact. `@clerk/backend` and
+  `quickjs-emscripten` are optional peers behind the `./auth/clerk` and
+  `./quickjs` subpaths and must never become dependencies or install with
+  core. Enforced by `test/package-surface.test.ts` and
+  `scripts/check-package.mjs`. Anything heavyweight or platform-bound gets a
+  subpath and an optional peer.
 
 ## Where new tests go
 

package/CHANGELOG.md

@@ -2,6 +2,193 @@
 
 All notable changes to this package are documented here.
 
+## 0.16.1 — 2026-08-13
+
+This is the cleanup that follows 0.16.0 out the door: the packaging housekeeping
+the pre-release smoke gauntlet turned up, one provider tool Cloudflare
+deprecated out from under us, a discovery answer that told a plain lie, and the
+upgrade runbook an existing deployment never had. Two things break, both on
+Cloudflare and both named here rather than left to the section below:
+`list_zone_settings` is gone from the `cloudflare()` named surface, and
+Cloudflare's 404 arrives as `not_found` instead of `connector_call_failed`.
+Nothing else does — no wire shape changes, no construction contract moves, no
+other code reclassified, and the per-setting operations `list_zone_settings`
+sat beside are the supported ones and are untouched. A deployment that writes
+no `api()` connectors, branches on no error code, and never asked an agent for
+a whole zone's settings in one call upgrades without reading further.
+
+Three things are additions rather than repairs, and they are the reason this
+release is worth reading rather than just installing: a new
+`ConnectorCallErrorCode` member, `not_found`, with a rule for when a connector
+may mint it; a `"./package.json"` entry in the `exports` map, so the installed
+manifest resolves; and `@cloudflare/codemode` declared as an optional peer at
+`^0.4.4 || ^0.5.0`. Strict semver would read those three as a minor, and would
+read the two Cloudflare changes above as more than that. This ships as a patch
+deliberately: every addition is opt-in at the point a deployment chooses to
+read it, and the tool removal and the 404 reclassification ride along in the
+same patch on purpose — both are scoped to one provider, both have a stated
+replacement, and both carry a version boundary in
+[`documentation/upgrading.md`](./documentation/upgrading.md). Holding them for
+a minor would mean shipping a release that keeps calling an endpoint its
+provider deprecated. The one install-time consequence is spelled out next.
+
+One thing to check before upgrading a Worker: `@cloudflare/codemode` is now a
+declared peer, so if your `package.json` holds it at a version outside
+`^0.4.4 || ^0.5.0` — a `0.3.x`, or a `0.4` below `0.4.4` — npm stops the
+upgrade with an `ERESOLVE` conflict rather than installing. Move it into the
+range this release is tested against, or pass `--legacy-peer-deps` if you have
+a reason to run outside it. A version already inside the range, and a range
+loose enough for npm to pick one that is, both resolve exactly as before.
+
+Alongside it, the upgrade path an existing deployment takes gets written down.
+`connecta init` was the golden path for a new deployment and the whole story
+for an old one, which is a gap with a shape: `init` refuses to merge into an
+existing path — the guard that keeps an initializer from eating a connector
+set — so an agent pointed at a deployment two releases behind had to
+reconstruct the procedure from release prose written for the maintainer. Both
+interesting failures there were silent too. It overwrites the configuration the
+deployment exists for, or it "fixes" a construction throw by weakening a
+fail-closed default and ships something quieter and wrong.
+
+### Added
+
+- **`not_found`, for a downstream that answered and had nothing to give.** A
+  hand-written connector meeting a 404 had exactly one honest code,
+  `connector_call_failed`, which also means "the call blew up" — so a program
+  inside `execute_code` could not tell a clean absence from a broken connector,
+  and a loop over ids had to abort where it should have skipped one. The new
+  code earns its place the way every code has to: it changes what the caller
+  does next. You do not wait, you do not go to `authorize_connector`, you do
+  not repair the arguments — you re-address. It is non-retryable, carries no
+  recovery envelope, derives no activity friction class, and is exported from
+  the root entry as part of `ConnectorCallErrorCode`.
+
+  The qualifier is the interesting half, and it is now written down in
+  [H11](./documentation/provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next):
+  map a status to `not_found` only where the provider tells absence apart from
+  a permission gap. Cloudflare does — a token that may not touch a resource is
+  refused with 401 or 403 — so its 404 is now `not_found` instead of
+  `connector_call_failed`. Notion does not: `object_not_found` means both "it
+  is gone" and "it was never shared with this integration", so it deliberately
+  stays generic with a message that says so. The hosted-MCP proxy path mints
+  the code never, because `P1` forbids re-shaping downstream framing and
+  provider prose is never parsed to invent a classification (#373).
+
+- **An upgrade runbook for existing deployments.**
+  [`documentation/upgrading.md`](./documentation/upgrading.md) is written for
+  the agent sitting inside a generated deployment it did not create: read the
+  exact pin and the template generation it implies, regenerate that generation
+  with `npx @zackbart/connecta@<pin> init` to get a real merge base, three-way
+  reconcile the scaffolding against the current template while `src/index.ts`
+  stays the deployment's own, cross the version boundaries that break
+  construction, and finish where `init` finishes — typecheck, start,
+  `connecta doctor`, then a program that exercises the deployment's *own*
+  connectors, which doctor deliberately knows nothing about. The migration
+  notes are per boundary and derived from this file: the 0.16.0 `api()`
+  construction contract (with the one safe answer for an unannotated tool
+  written down — `readOnlyHint: false`, which is the routing it already had),
+  the `linear()`, `mixpanel()`, and Cloudflare provider changes, redirect
+  refusal and the response ceilings, and the fail-closed shipped defaults; then
+  0.14's annotation-precedence change, 0.13's rewritten guide summaries, the
+  0.11.0 executor requirement, 0.7.0's `verifyState` requirement and
+  core-owned routes for the pre-template deployments that still have to cross
+  them, and every removed option that throws with its migration. It closes with five refusals, because each is somebody's plausible
+  shortcut: no re-init over the top, no weakening a fail-closed default to get
+  green, no pinning back, no vendored internals, no second project shape.
+  Reachable from the README, from `operations.md`, and — absolutely, because
+  that reader has no copy of this repository — from the template's `AGENTS.md`
+  (#380).
+- **A suite that keeps the guide honest.** `test/upgrade-guide.test.ts` pins
+  every claim its reader cannot check: the generated file inventory against
+  `templates/node/`, the seven tool names against the CLI's own list, each
+  named version boundary against a release that shipped, each removed option
+  against the release section that names its issue, the bump target against
+  this package's version, and the three places the guide is linked from. A template that gains a file now fails `npm run check` rather than
+  leaving an agent to guess which of the two is wrong (#380).
+- **`@cloudflare/codemode` is a declared optional peer.** Every Workers
+  deployment installs the executor behind `execute_code` by hand, and until now
+  the only version range anywhere was a devDependency no consumer can read — a
+  fresh install resolved a minor ahead of what this repository tests, silently.
+  The manifest now publishes `^0.4.4 || ^0.5.0` for it, optional like
+  `@clerk/backend` and `quickjs-emscripten`, so a supported version installs in
+  silence and an unsupported one stops the install with something to act on
+  instead of becoming skew a Worker discovers in production. It still installs
+  with nothing: a default `npm install @zackbart/connecta` pulls no executor,
+  and the package smoke proves that, both halves of the range behavior, and
+  that the version this repository develops against stays inside the range it
+  publishes (#376).
+
+### Changed
+
+- **Cloudflare's 404 is `not_found`.** A deployment branching on
+  `connector_call_failed` to detect an unknown zone or account id should read
+  `not_found` instead; retryability, the message, and its pointer to
+  `list_zones` / `list_accounts` are unchanged (#373).
+- `cloudflare()` no longer names a bulk zone-settings read.
+  `GET /zones/{zoneId}/settings` and its `PATCH` sibling are published as
+  `deprecated: true`, Cloudflare offers no bulk replacement, and the tool that
+  wrapped the read projected nothing — it took a zone id and grew the payload
+  by wrapping an unpaginated array in a page object. Read one setting with
+  `get_zone_setting` and write one with `update_zone_setting`, both on the
+  supported `/zones/{zoneId}/settings/{settingId}` operations. An operator who
+  still wants the whole set can name the deprecated path explicitly through
+  `cloudflare_api_get`. The named surface is 47 tools plus the three escape
+  hatches ([#361](https://github.com/zackbart/connecta/issues/361)).
+- The Cloudflare touched-endpoint manifest drops the deprecated row with the
+  tool, so `npm run drift:check -- --specs` is quiet about zone settings
+  because nothing calls the endpoint, not because a maintainer signed off on
+  calling it anyway.
+
+### Fixed
+
+- **A search for a connector's own name stops claiming the deployment has no
+  such capability.** A connector's `id` — the address prefix an agent already
+  holds — and its `title` are displayed, never indexed, so `search_tools({
+  query: "inventory" })` against a connector called `inventory` matched no tool
+  and was answered with "No matching capability is configured in this
+  deployment", which was plainly false. Connector identity stays out of the
+  lexical index, because putting it in would move ranking for every query that
+  already matches tools; instead an unscoped miss whose terms name configured
+  connectors says so, names up to three of them by ID, and sends the caller to
+  a scoped browse. A term that matches nothing in the deployment still gets the
+  original sentence, unchanged. One `queryAnalysis.guidance` string differs; no
+  ranking, result, or field changed (#372).
+- **Every relative link in the shipped Markdown resolves for the reader who
+  installed the package.** Ten of them pointed at `eval/`, `test/`, `scripts/`,
+  and the README hero — repository paths the tarball has never carried and, per
+  #346, should not start carrying. The link gate could not see any of them: it
+  read only `documentation/` targets, so the whole class was invisible and grew
+  with every trim. The policy is now stated once in the operations guide and
+  enforced over *every* relative link in packed Markdown: it either resolves
+  inside the tarball or it is cited as an absolute
+  `https://github.com/zackbart/connecta/blob/main/...` URL, which an outside
+  reader can follow and which `check:docs` resolves back to the checkout, so a
+  citation still fails when the file it names moves. The ten links were
+  rewritten that way, the README hero now loads from
+  `raw.githubusercontent.com` and still renders on npmjs.com, and the
+  repository reader loses no citation (#378).
+- **`@zackbart/connecta/package.json` resolves.** The `exports` map listed
+  every code subpath and nothing else, so a bundler plugin, framework build
+  step, or version probe reaching for the installed manifest — a thing the
+  ecosystem broadly expects to work — got `ERR_PACKAGE_PATH_NOT_EXPORTED`
+  instead of the file. The manifest is now exported. It is a data file, so this
+  widens the published surface by exactly zero code paths: the root entry's
+  Workers purity boundary and the optional-peer subpaths are untouched. The
+  package-surface gate now asserts the whole subpath set, manifest included, so
+  neither this entry nor an unwanted one can arrive unnoticed (#374).
+- **The published-surface rule says what it actually forbids.** `AGENTS.md`
+  claimed platform-specific storage adapters live in `examples/`, "not the
+  package", while the tarball has always carried `examples/worker` — Cloudflare
+  KV and D1 adapters included — because that example is the Workers starting
+  template a consumer copies. The invariant was never in danger: nothing under
+  `examples/` appears in the `exports` map, so those adapters are reference
+  source and not an importable subpath. The wording now draws the line where
+  the gates draw it — a platform-bound adapter must not reach `src/` or the
+  `exports` map — and says why the example ships, in `AGENTS.md`, the
+  operations guide, and the `scripts/check-package.mjs` comment. A new
+  assertion in `test/package-surface.test.ts` holds the instruction file and
+  the exports map to the same story (#377).
+
 ## 0.16.0 — 2026-08-12
 
 This is the agent-efficiency refocus. One release, sixteen merges, and a single

package/README.md

@@ -1,6 +1,6 @@
 # connecta
 
-![A monochrome clay Connecta hub joining many tools](./assets/connecta-clay-hero.png)
+![A monochrome clay Connecta hub joining many tools](https://raw.githubusercontent.com/zackbart/connecta/main/assets/connecta-clay-hero.png)
 
 One place for AI agents to connect to the tools you choose.
 
@@ -98,6 +98,11 @@ activity ship as commented configuration, each one a variable and an
 uncommented block away. The generated `README.md` walks through all four, and
 the [Worker example](./examples/worker/) does the same for KV and D1.
 
+Already have a deployment on an older version? `init` deliberately refuses to
+merge into it, so bringing one current is its own procedure:
+[Upgrading an existing deployment](./documentation/upgrading.md) is the
+runbook, written for the agent working inside that project.
+
 The template refuses to merge into an existing directory, so initialization
 cannot overwrite another project. Its generated programs have no filesystem,
 environment, arbitrary network, imports, or timers; only explicitly read-only

package/dist/catalog-service.js

@@ -1,4 +1,4 @@
-import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
+import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
@@ -10,6 +10,12 @@ export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
 const MAX_QUERY_TERMS = 8;
 const MAX_QUERY_TERM_LENGTH = 64;
+/**
+ * Connector IDs a no-match search will name back. Three is enough to point at
+ * the connector the query already named without turning a miss into a listing
+ * of the deployment.
+ */
+const MAX_IDENTITY_CONNECTORS = 3;
 const encoder = new TextEncoder();
 /** Clip one echoed query term without splitting a non-BMP code point. */
 function boundedQueryTerm(term) {
@@ -561,6 +567,36 @@ export class CatalogService {
                 required: connectorGuideRequired(scopedConnector),
             }
             : undefined;
+        // A connector's own id — the address prefix the caller already has — and
+        // the title it is displayed under are the most natural first query terms,
+        // and neither is a document in the lexical index. Indexing them would move
+        // ranking for every query that already matches tools, so instead a search
+        // that matched nothing asks the same lexical question of connector
+        // identity and corrects its own sentence: the deployment plainly has this
+        // capability, and one scoped browse away are its tools. Unscoped only —
+        // guidance for an explicit scope already names that connector rather than
+        // claiming the deployment has nothing.
+        const identityConnectorIds = matches.length === 0 && !isBrowse && !unsearchableQuery && !scopedConnector
+            ? connectors
+                // The full query, not `analyzedTerms`: that cap exists to bound
+                // the serialized term fields, and ranking already reads every
+                // term. A ninth term is a real search term, and a search that
+                // ranked against it must not deny the connector it names.
+                .filter((connector) => queryTerms.some((term) => matchesLexicalTerm(connector.id, term) ||
+                (connector.title !== undefined &&
+                    matchesLexicalTerm(connector.title, term))))
+                .map((connector) => connector.id)
+            : [];
+        const namedIdentityConnectors = identityConnectorIds
+            .slice(0, MAX_IDENTITY_CONNECTORS)
+            .map((id) => `"${id}"`)
+            .join(", ");
+        const unnamedIdentityConnectors = identityConnectorIds.length - MAX_IDENTITY_CONNECTORS;
+        const identityGuidance = identityConnectorIds.length === 0
+            ? undefined
+            : `No matching ${safetyLabel}capability was found${unavailableCatalogs === 0 ? "" : " in the catalogs that answered"}, but the query names configured connector${identityConnectorIds.length === 1 ? "" : "s"} ${namedIdentityConnectors}${unnamedIdentityConnectors > 0
+                ? ` and ${unnamedIdentityConnectors} more`
+                : ""}. Scope by connector and browse with an empty query to list the tools there.${filterRecovery}`;
         // A scope that resolved to nothing is the same silence one step earlier in
         // the lookup: no connector resolved, so no catalog was even attempted, so
         // no catalog failed and the unavailable path below never fires. Echo only
@@ -604,9 +640,10 @@ export class CatalogService {
                                 : scopedGuide?.required
                                     ? `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Fetch queryAnalysis.guide before calling, then refine terms or browse with an empty query.${filterRecovery}`
                                     : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
-                            : unavailableCatalogs === 0
-                                ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
-                                : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`))
+                            : (identityGuidance ??
+                                (unavailableCatalogs === 0
+                                    ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                                    : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`))))
                     : matchMode === "partial"
                         ? scopedConnector
                             ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`

package/dist/catalog.d.ts

@@ -18,6 +18,17 @@ export interface RankedTool {
     exactName: boolean;
     matchedTermCount: number;
 }
+/**
+ * Whether one query term matches a whole token of arbitrary text, under the
+ * same inflection rules the tool index uses.
+ *
+ * Connector identity — an `id` or a `title` — is deliberately not a document in
+ * that index: making it one would move ranking for every query that already
+ * matches tools. This lets a caller ask the index's question of a string that
+ * never became a document, which is what the no-match analysis needs to tell
+ * "nothing like this exists here" from "that word is a connector".
+ */
+export declare function matchesLexicalTerm(text: string, term: string): boolean;
 export interface LexicalCorpusStatistics {
     documentCount: number;
     documentFrequency: ReadonlyMap<string, number>;

package/dist/catalog.js

@@ -166,6 +166,26 @@ function matchingTokenCandidates(term) {
     }
     return candidates;
 }
+/**
+ * Whether one query term matches a whole token of arbitrary text, under the
+ * same inflection rules the tool index uses.
+ *
+ * Connector identity — an `id` or a `title` — is deliberately not a document in
+ * that index: making it one would move ranking for every query that already
+ * matches tools. This lets a caller ask the index's question of a string that
+ * never became a document, which is what the no-match analysis needs to tell
+ * "nothing like this exists here" from "that word is a connector".
+ */
+export function matchesLexicalTerm(text, term) {
+    const tokens = new Set(lexicalTokens(text));
+    if (tokens.size === 0)
+        return false;
+    for (const candidate of matchingTokenCandidates(term)) {
+        if (tokens.has(candidate))
+            return true;
+    }
+    return false;
+}
 /**
  * Compute query-specific document frequencies across every available catalog.
  * The caller does this once per search and shares the result with each

package/dist/errors.d.ts

@@ -1,5 +1,33 @@
-/** Machine-readable classification of a failed connector tool call. */
-export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args" | "input_required_unsupported" | "connector_call_failed";
+/**
+ * Machine-readable classification of a failed connector tool call.
+ *
+ * A code earns its place by changing what the caller does next, never by
+ * naming a cause — the rule provider conventions call H11.
+ */
+export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited" | "unavailable" | "invalid_args"
+/**
+ * The downstream answered, and the thing addressed is not there.
+ *
+ * Its own code because the next move is none of the others': not a retry,
+ * not `authorize_connector`, not a reshaped argument object, but
+ * re-addressing — look the identifier up again, or accept the absence and
+ * carry on. Inside `execute_code` a program reads that difference off a
+ * `connecta.batch` entry's `errorDetails.code` — continue past this one,
+ * abort on `connector_call_failed` — or lets the failure escape uncaught so
+ * the model sees the typed envelope. Never off a caught error: the guest
+ * bridge reduces a rejected host call to `new Error(message)` and drops
+ * every own property, and message prose cannot be classified.
+ *
+ * Use it only where the provider distinguishes absence from a permission
+ * gap. A status that means both "it is not there" and "you cannot see it" —
+ * Notion's `object_not_found` is the worked example — stays
+ * `connector_call_failed` with a message that states the ambiguity, because
+ * inventing certainty here is how an agent concludes a page was deleted when
+ * it was simply never shared. Addresses connecta itself cannot resolve are
+ * already framed as `unknown_address` or `unknown_tool` and never reach a
+ * connector, so this code is always about a resource the downstream owns.
+ */
+ | "not_found" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
     /** JSON Pointer into the submitted arguments; "/" means the root value. */

package/dist/errors.js

@@ -108,6 +108,7 @@ const RETRYABLE_BY_CODE = {
     unavailable: true,
     auth_required: false,
     invalid_args: false,
+    not_found: false,
     input_required_unsupported: false,
     connector_call_failed: false,
 };

package/dist/providers/cloudflare.js

@@ -235,8 +235,12 @@ function failureFor(status, headers, errors) {
     if (status === 400 || status === 409 || status === 422) {
         return new ConnectorCallError("invalid_args", `Cloudflare rejected the request (HTTP ${status}). ${detail}`);
     }
+    // Cloudflare's 404 is an honest absence: a token that may not touch a
+    // resource is refused with 401 or 403 above, not hidden behind a miss, so
+    // this is the unambiguous case `not_found` exists for — re-address, do not
+    // retry and do not re-authorize.
     if (status === 404) {
-        return new ConnectorCallError("connector_call_failed", `Cloudflare found no such resource (HTTP 404). ${detail} Confirm the zone or account id with list_zones or list_accounts.`);
+        return new ConnectorCallError("not_found", `Cloudflare found no such resource (HTTP 404). ${detail} Confirm the zone or account id with list_zones or list_accounts.`);
     }
     if (status >= 500) {
         return new ConnectorCallError("unavailable", `Cloudflare is unavailable (HTTP ${status}). ${detail}`);
@@ -1401,27 +1405,11 @@ function buildTools(scope, authentication) {
                 return args["raw"] === true ? result : projectZone(result);
             },
         },
-        {
-            name: "list_zone_settings",
-            description: "List the effective settings for a zone, including each setting's current value and whether the plan allows editing it.",
-            annotations: readOnly,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    zoneId: scopeProperty("zoneId", scope.zoneId),
-                },
-                required: scopeRequired("zoneId", scope.zoneId),
-                additionalProperties: false,
-            },
-            outputSchema: listOutputSchema("settings", OPEN_OBJECT_OUTPUT_SCHEMA),
-            handler: async (args, ctx) => {
-                const { result, resultInfo } = await callCloudflare(send, {
-                    method: "GET",
-                    path: `/zones/${encodePathSegment(zoneArg(args))}/settings`,
-                }, ctx);
-                return { settings: asArray(result), page: pageInfo(resultInfo) };
-            },
-        },
+        // There is deliberately no bulk zone-settings read here. Cloudflare
+        // publishes `GET /zones/{zone_id}/settings` as deprecated (#361), the
+        // per-setting operations below are not, and the tool that wrapped the bulk
+        // read projected nothing. See the Cloudflare guide's "What the named
+        // surface deliberately leaves out".
         {
             name: "get_zone_setting",
             description: "Get one zone setting by its Cloudflare setting id, such as ssl, always_use_https, min_tls_version, brotli, or development_mode.",
@@ -1433,7 +1421,7 @@ function buildTools(scope, authentication) {
                     settingId: {
                         type: "string",
                         minLength: 1,
-                        description: "Cloudflare zone setting id from list_zone_settings.",
+                        description: "Cloudflare zone setting id, such as ssl, brotli, http3, or min_tls_version.",
                     },
                 },
                 required: [...scopeRequired("zoneId", scope.zoneId), "settingId"],
@@ -1459,7 +1447,7 @@ function buildTools(scope, authentication) {
                     settingId: {
                         type: "string",
                         minLength: 1,
-                        description: "Cloudflare zone setting id from list_zone_settings.",
+                        description: "Cloudflare zone setting id, such as ssl, brotli, http3, or min_tls_version.",
                     },
                     value: {
                         type: ["string", "number", "boolean", "array"],
@@ -3215,7 +3203,7 @@ Account purpose: ${purpose}
 - Prefer a named tool: its schema is complete, projected, and enough to call it without provider documentation. For an operation without a named tool, use \`cloudflare_api_get\` for GET, \`cloudflare_api_mutate\` for JSON POST/PUT/PATCH/DELETE, or \`cloudflare_api_upload\` for raw and multipart content. Raw tools take a path below \`/client/v4\`; their argument schemas are complete, but endpoint-specific query, header, and body fields come from Cloudflare's API reference. Use \`headers\` for endpoint-specific controls such as \`cf-r2-jurisdiction\`, \`Range\`, \`If-None-Match\`, and Cloudflare product metadata. \`Authorization\`, \`Cookie\`, \`Host\`, \`Content-Length\`, \`Content-Type\`, and \`Transfer-Encoding\` are connector-owned and refused: authentication, host, content type, and request framing are not the caller's to set.
 - The raw tools cover the wider control plane without weakening routing: GET is explicitly read-only; every mutation and upload is destructive and must cross the host's approval boundary. The configured Cloudflare credential remains the hard provider-side permission boundary. Absolute URLs, traversal, and query strings embedded in \`path\` are refused locally.
 - Useful raw paths include \`/accounts/{accountId}/images/v1\` (Images), \`/accounts/{accountId}/stream\` (Stream), \`/zones/{zoneId}/email/routing/rules\` (Email Routing), \`/accounts/{accountId}/d1/database\` (D1), and \`/accounts/{accountId}/queues\` (Queues). On GET, use \`responseType: "text"\` or \`"base64"\` for non-JSON content. Direct-upload endpoints can issue upload URLs; \`cloudflare_api_upload\` can also send explicit text, base64 bytes, or multipart fields/files.
-- Two R2 areas are deliberately unnamed. Read a bucket's CORS policy with \`get_r2_cors\`, then change it with \`cloudflare_api_mutate\` — \`PUT\` or \`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors\`, rule fields per Cloudflare's reference — and read account storage totals with \`cloudflare_api_get\` at \`/accounts/{accountId}/r2/metrics\`.
+- Three areas are deliberately unnamed. Read a bucket's CORS policy with \`get_r2_cors\`, then change it with \`cloudflare_api_mutate\` — \`PUT\` or \`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors\`, rule fields per Cloudflare's reference — and read account storage totals with \`cloudflare_api_get\` at \`/accounts/{accountId}/r2/metrics\`. Zone settings are read one at a time with \`get_zone_setting\`: Cloudflare deprecated the bulk \`/zones/{zoneId}/settings\` read and published no replacement for it, so reach for the whole set through \`cloudflare_api_get\` only when one setting genuinely will not do.
 - Lists paginate with \`page\` and \`perPage\` and return a \`page\` object; request the next page only when \`page.hasMore\` is true. \`list_zone_rulesets\`, \`list_r2_buckets\`, \`list_r2_objects\`, and \`list_kv_keys\` page by cursor instead: pass \`cursor\`, continue while \`nextCursor\` is present, and expect no \`page\` object. Their schemas say so too. \`list_worker_scripts\` is unpaginated.
 - Results are projected to the fields that identify and describe a resource. Pass \`raw: true\` on a read when you genuinely need a field the projection drops.
 - ${authenticationLine}

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.16.1";

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.16.1";

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.
 

package/documentation/code-mode.md

@@ -329,8 +329,7 @@ not in the always-loaded usage skill, which `test/meta-tools.test.ts` caps at
 2,500 bytes — a budget the guide already spends nearly all of, so new text there
 displaces old rather than adding to what every request pays for.
 
-**E2.** The taxonomy. `retryable` is what connecta reports; `Y3` says what a
-program may do about it.
+**E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program may do.
 
 | Code | Raised when | `retryable` |
 | --- | --- | --- |
@@ -340,6 +339,7 @@ program may do about it.
 | `destructive_tool_requires_approval` | the tool is not explicitly read-only | false |
 | `auth_required` | the credential is missing, expired, or rejected | false |
 | `invalid_args` | arguments or discovery bounds were rejected | false |
+| `not_found` | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, classified off `errorDetails` per `E1` and never off a caught error, raised only where the provider tells absence from a permission gap ([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next)) | false |
 | `input_required_unsupported` | a downstream asked for mid-call input | false |
 | `rate_limited` | the downstream reported a rate limit | true |
 | `unavailable` | the downstream is down or unreachable | true |