@zackbart/connecta 0.24.2 → 0.24.4

package/documentation/cloudflare.md

@@ -1,471 +0,0 @@
-# Cloudflare prebuilt connection
-
-Import `cloudflare()` independently from
-`@zackbart/connecta/providers/cloudflare`. The deployment chooses one of two
-interfaces. The default is a deliberate, hand-written surface over
-Cloudflare's v4 REST API. Its 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. The other choice is
-Cloudflare's official whole-API hosted MCP, which exposes `search` and
-`execute` with live provider-owned schemas. Both are ordinary connectors and
-neither is reachable from Connecta's root entry.
-
-```ts
-import { cloudflare } from "@zackbart/connecta/providers/cloudflare";
-
-const edge = cloudflare("cloudflare_prod", {
-  surface: "api", // optional; this is the backward-compatible default
-  title: "Production edge",
-  purpose: "DNS and cache administration for the production estate",
-  zoneId: "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
-  accountId: "9f8e7d6c5b4a30291817263544332211",
-  instructions: "Never purge the whole zone during business hours.",
-});
-```
-
-Use Cloudflare's hosted code-mode interface instead:
-
-```ts
-const wholeApi = cloudflare("cloudflare_mcp", {
-  surface: "mcp",
-  purpose: "Cloudflare administration outside the curated REST workflows",
-});
-```
-
-Use the legacy user-scoped Global API Key when an existing deployment needs it:
-
-```ts
-const legacyEdge = cloudflare("cloudflare_legacy", {
-  purpose: "Legacy account administration",
-  authentication: "globalApiKey",
-});
-```
-
-The operator UI then asks for the Cloudflare user email and Global API Key as
-separate fields. The default remains a scoped API token.
-
-The `id` owns the ordinary connector namespaces; use a different id for every
-Cloudflare account or estate. `purpose` is required because an agent choosing
-between a production and a staging instance needs to know which one answers the
-question. Account `instructions` are appended to the maintained guide and
-cannot change the connector's safety classification.
-
-## Choosing an interface
-
-Use the API interface when its projected named tools cover the work. Connecta
-owns those schemas, projections, typed errors, pagination, and the split
-between read-only and mutating escape hatches.
-
-Use `surface: "mcp"` when broad product coverage matters more than projected
-results. Cloudflare's official server covers more than 2,500 API endpoints
-through two code-mode tools. `search` reads the OpenAPI document and is
-read-only. `execute` can run a program containing any authorized HTTP method,
-so Connecta always routes it through approval. A program that happens to use
-only GET cannot be proven observational from the tool schema.
-
-The MCP catalog and schemas come from the live server. The release manifest
-classifies the two known names but does not replace their schemas. OAuth is the
-default. A headless deployment may instead pass `auth` with a scoped API token.
-The credential remains the provider-side permission boundary either way. The
-MCP interface accepts `callAdmission` when the deployment has a concurrency or
-call-rate requirement; it does not reuse the API interface's REST-wide budget.
-
-The remaining sections document the hand-written API interface. MCP tool
-arguments and results are intentionally read from the live server instead.
-
-## No SDK, on purpose
-
-Cloudflare publishes an official `cloudflare` npm SDK, and this connection does
-not use it. The SDK's value is typed request wrappers and pagination helpers.
-Both are things this connection replaces rather than consumes: an agent needs a
-projected result and a `page.hasMore` boolean, not Cloudflare's full response
-object, so the SDK's types would be re-projected away at the boundary. What the
-dependency would cost is real — an optional peer with its own install step and
-version skew, an import that never belongs in the root graph, and a second
-opinion about what a Cloudflare call looks like.
-
-The API itself does not need one. It is authenticated `fetch` with a uniform
-`{ success, errors, messages, result, result_info }` response envelope. JSON,
-raw bytes, and multipart request bodies all use Web APIs, which keeps the
-provider Workers-clean and means `@zackbart/connecta/providers/cloudflare`
-installs and runs with nothing extra. `test/package-surface.test.ts` pins the
-claim: the `cloudflare` package must not appear in `dependencies`,
-`peerDependencies`, or `devDependencies`, and every import in the provider
-must be relative.
-
-## API credentials
-
-The default credential is a scoped Cloudflare API token, sent as
-`Authorization: Bearer <token>`. Create it under My Profile → API Tokens →
-Create Token.
-
-Set `authentication: "globalApiKey"` to use the legacy user-scoped scheme. The
-credential form stores two encrypted fields and sends them as `X-Auth-Email`
-and `X-Auth-Key`. The Global API Key has the same access as its Cloudflare user
-across every account and zone that user can reach. It cannot be scoped, only
-one can exist per user, and it has no expiry or IP limits. Cloudflare recommends
-API tokens for new use, but existing Global API Keys remain supported.
-
-Grant only what the deployment needs:
-
-| Tools | Token permission | Scope |
-| --- | --- | --- |
-| Zone discovery and settings reads | Zone Read | Zone |
-| `update_zone_setting` | Zone Settings Write | Zone |
-| Zone ruleset reads | Relevant Rules product Read permission, such as Transform Rules Read or Firewall Services Read | Zone |
-| `list_dns_records`, `get_dns_record` | DNS Read | Zone |
-| `create_dns_record`, `update_dns_record`, `delete_dns_record` | DNS Write | Zone |
-| `purge_cache` | Cache Purge | Zone |
-| Worker script/deployment reads | Workers Scripts Read | Account |
-| Worker writes through named or raw tools | Workers Scripts Write | Account |
-| KV reads | Workers KV Storage Read | Account |
-| KV creates, renames, writes, and deletes | Workers KV Storage Write | Account |
-| R2 reads | Workers R2 Storage Read | Account |
-| R2 creates, changes, uploads, deletes, and configuration writes | Workers R2 Storage Write | Account |
-| Pages reads | Cloudflare Pages Read | Account |
-| Pages retries, rollbacks, domains, purges, uploads, and deletes | Cloudflare Pages Write | Account |
-| Images, Stream, Email Routing, D1, Queues, and other raw calls | Matching product Read or Write permission | Account or Zone |
-
-Most names above appear directly in the token editor. Ruleset access is split
-by product and phase, so grant the narrow Rules permission for the phases the
-agent must inspect rather than looking for one generic "Zone Rulesets Read"
-scope. "Cache Purge" is a single permission with no Read/Write split, and
-Cloudflare's own reference renders a few labels differently between its
-Dashboard and API tabs.
-
-`verify_api_token` needs no permission beyond the token existing. In legacy
-mode, `verify_global_api_key` reads `/user` to confirm the email and key pair.
-The connection UI Test action at `/` runs the matching check before storage.
-
-Cloudflare rate-limits *authentication failures* aggressively and separately
-from the global limit: a few requests with a bad token return HTTP 429 with
-code `10502`, "Too many authentication failures". That surfaces here as
-`rate_limited`, not `auth_required`, which is correct — the token may well be
-fine by the time the window clears — but it means a broken token should be
-diagnosed once with `verify_api_token` rather than by retrying real calls.
-
-## Scoping
-
-`zoneId` and `accountId` are deployment defaults, not restrictions. When a
-default is set, the corresponding argument drops out of the tool's `required`
-list and calls that omit it use the default; a call may still pass a different
-id. When no default is set, the argument is required and the schema's own
-description names the discovery tool that produces it — `list_zones` for a
-zone, `list_accounts` for an account.
-
-That is the discovery flow worth knowing: Cloudflare addresses almost
-everything by an opaque 32-character id, and an agent that only knows a domain
-name must call `list_zones` with `name: "example.com"` first. Configuring
-`zoneId` removes that hop entirely for a single-zone deployment.
-
-`list_zones` is the one tool a configured `accountId` deliberately does *not*
-reach. It is the discovery step, and a default that quietly filtered it would
-be a restriction in all but name — one with no argument that escapes it, since
-an empty `accountId` would fall back to the default again. A deployment that
-wants zones from one account passes `accountId` explicitly, and the property
-says so.
-
-## API tools
-
-The named surface covers workflows that benefit most from concise schemas and
-projections:
-
-| Area | Reads | Writes |
-| --- | --- | --- |
-| 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 |
-| R2 | buckets, object metadata, CORS | create/update/delete bucket, delete object |
-| Pages | projects, deployments, domains | retry/rollback/delete deployments, add/delete domains, purge build cache, delete project |
-
-Every named tool carries a complete hand-written input schema: closed
-(`additionalProperties: false`), with an accurate `required` list, an `enum` on
-every constrained field, endpoint-specific pagination bounds, and a description
-on every property. `test/cloudflare-provider.test.ts` walks the surface and
-asserts those properties rather than leaving them as a claim.
-
-The per-setting zone tools accept Cloudflare's current non-empty setting ids,
-including `webmcp_enabled` and `webmcp_packs`. Cloudflare's
-[rendered setting reference](https://developers.cloudflare.com/api/resources/zones/subresources/settings/)
-and current OpenAPI now agree on both beta ids. Results preserve the value and
-the actual `editable` flag Cloudflare returned; Connecta does not apply the
-document's defaults locally.
-
-KV namespace jurisdiction is creation-only. `create_kv_namespace` accepts
-`eu`, `fedramp`, or `us`, and namespace reads preserve the returned value.
-R2 uses a different enum: `default`, `eu`, `us`, or `fedramp`, sent through
-`cf-r2-jurisdiction` by all eight named R2 operations.
-
-### What the named surface deliberately leaves out
-
-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`](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
-  validated the bucket name and waved through the part of the call that
-  actually fails. It also returned Cloudflare's response unprojected and was
-  destructive either way, which left nothing for it to beat
-  `cloudflare_api_mutate` on. `delete_r2_cors` did not lose that comparison:
-  it returned a fixed `{deleted: true}` behind a closed output schema and
-  refused every malformed argument locally. It went anyway, because naming only
-  the delete would mean one CORS policy is set through the raw route and
-  cleared through a named tool. Read a policy with `get_r2_cors`; change one
-  with `cloudflare_api_mutate` at
-  `PUT`/`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors`. This is the
-  same split the [DNS record types](#dns-record-types) already use: structured
-  bodies stay readable through named tools and writable through the
-  approval-gated raw route.
-- **R2 account metrics.** `get_r2_metrics` took one account id, put it in a
-  path, and returned the response untouched — `cloudflare_api_get` at
-  `/accounts/{accountId}/r2/metrics` does the same thing without a permanent
-  catalog line.
-- **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 48 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.
-
-### The whole-v4 escape hatch
-
-Cloudflare adds products and endpoints faster than a curated connector should
-grow tool names. Three provider-relative tools cover the rest without turning
-method classification into user input:
-
-- `cloudflare_api_get` accepts only GET and is explicitly read-only. JSON is the
-  default; `responseType: "text" | "base64"` retrieves scripts, logs, R2
-  objects, and media bodies without pretending they have a JSON envelope.
-- `cloudflare_api_mutate` accepts JSON POST, PUT, PATCH, and DELETE. It is always
-  destructive, even when a particular POST is merely additive. It preserves
-  ordinary non-envelope JSON from endpoints such as `/graphql`.
-- `cloudflare_api_upload` accepts POST or PUT plus exactly one of raw text,
-  base64 bytes, or multipart fields/files. It is always destructive and reads
-  no local files.
-
-All three accept explicit endpoint-specific headers, which supports R2
-jurisdictions, conditional requests, encryption controls, and object metadata.
-`Authorization`, `Cookie`, `Host`, `Content-Length`, `Content-Type`, and
-`Transfer-Encoding` remain connector-owned and are refused: authentication,
-host selection, content type, and request framing are not the caller's to set.
-That refused list lives in the usage guide rather than in each header property
-description, because the compact renderer inlines a property description once
-per tool that shares it, and repeating it three times pushed
-`cloudflare_api_upload`'s compact input shape past the 1,024-byte discovery
-budget.
-
-Paths are relative to `/client/v4`. Absolute URLs, protocol-relative paths,
-`..` traversal, fragments, and embedded query strings are refused locally;
-query parameters are explicit name/value pairs. These tools reuse the same
-credential, admission budget, abort signal, envelope parsing, and typed failure
-mapping as named tools. They do not widen the configured credential's access.
-
-This is intentionally not OpenAPI ingestion: it creates three stable tools,
-not one tool per Cloudflare operation. For example, an agent can list Images at
-`/accounts/{accountId}/images/v1`, manage Stream at
-`/accounts/{accountId}/stream`, manage Email Routing at
-`/zones/{zoneId}/email/routing/rules`, reach D1 at
-`/accounts/{accountId}/d1/database`, and reach Queues at
-`/accounts/{accountId}/queues`. The endpoint-specific query and body shape still
-comes from Cloudflare's API reference.
-
-### Where the `perPage` bounds come from
-
-`api()` enforces every hand-written schema, so an out-of-range `perPage` is
-refused locally before it reaches Cloudflare. That is only a favor when the bound is really
-Cloudflare's, so the schemas record which ones are and the descriptions say so
-out loud:
-
-| Tool | `perPage` | Default | Whose bound |
-| --- | --- | --- | --- |
-| `list_accounts`, `list_zones` | 5–50 | 20 | Cloudflare's, as documented |
-| `list_kv_namespaces` | 1–1000 | 20 | Cloudflare's, as documented |
-| `list_dns_records` | 1–1000 | 100 | Cloudflare's minimum; the ceiling is ours |
-| `list_pages_projects` | 1–100 | — | Ours entirely |
-
-Two need the note. Cloudflare's schema documents `per_page` on
-`/zones/{id}/dns_records` as 1 to **5,000,000** — a nominal ceiling no listing
-will honor — so this connection caps it at 1,000, the same conservative-reading
-move as the [one-variant purge rule](#cache-purging): a local cap an agent is
-told about beats a page size that fails somewhere inside Cloudflare. And
-`/accounts/{id}/pages/projects` documents no bounds and no default at all, so
-1 to 100 is a choice made here and labeled as one.
-
-### DNS record types
-
-Cloudflare accepts 21 record types, exported as `CLOUDFLARE_DNS_RECORD_TYPES`.
-Eight of them take a single `content` string; the other thirteen (CAA, CERT,
-DNSKEY, DS, HTTPS, LOC, NAPTR, SMIMEA, SRV, SSHFP, SVCB, TLSA, URI) take a
-per-type structured `data` object with its own field set.
-
-`list_dns_records` filters on all 21. `create_dns_record` and
-`update_dns_record` accept only the eight content-based types, exported as
-`CLOUDFLARE_CONTENT_DNS_RECORD_TYPES`. Supporting the rest would mean either a
-free-form `data` passthrough — the untyped `{}` this connection exists to
-avoid — or thirteen more hand-written schemas for record types that are rare in
-day-to-day zone administration. Structured-data records stay fully readable.
-The named create/update tools omit them and the enum says so rather than letting
-the call reach Cloudflare and 400; an operator who needs one can use the
-approval-gated raw mutation tool with Cloudflare's documented per-type `data`
-body.
-
-### Cache purging
-
-`purge_cache` takes exactly one variant per call: `everything: true`, or one of
-`files`, `tags`, `hosts`, or `prefixes`. Cloudflare caps a purge at 100
-operations per request (500 files on Enterprise), and all four targeted methods
-are available on every plan — tag, host, and prefix purging is no longer
-Enterprise-only.
-
-The one-variant rule is this connection's contract, not a documented API
-restriction. Cloudflare's schema models the body as `anyOf`, which does not
-forbid combining, and the only explicit exclusivity statement in its
-documentation is about the Workers cache binding rather than the REST endpoint.
-Refusing a combined call locally is the conservative reading: an agent gets a
-clear `invalid_args` naming the conflict instead of a purge whose actual scope
-is ambiguous. If a future deployment needs combined tag-and-prefix purging,
-that is a deliberate change to make here, not something to discover in
-production.
-
-## Results
-
-Reads return Cloudflare's `result` unwrapped and projected: identity and
-description fields kept, plan/permission/meta noise dropped, `snake_case`
-renamed to `camelCase`. A zone comes back as `id`, `name`, `status`, `paused`,
-`type`, `accountId`, `accountName`, `plan`, `nameServers`, and timestamps —
-not the forty-field object Cloudflare sends.
-
-Every named tool declares useful top-level output keys. Zone settings, Worker
-settings and deployments, KV namespaces and bulk operations, rulesets, R2 CORS,
-and Pages resources use maintained result schemas instead of an open
-"Cloudflare object" declaration. The three raw escape hatches remain open by
-design because their result fields depend on the caller-supplied endpoint.
-
-Paginated lists add a `page` object derived from `result_info`:
-`{ page, perPage, count, totalCount, totalPages, hasMore }`. `hasMore` is the
-field to branch on.
-
-Some endpoints do not work that way, and the schemas say so rather than leaving
-an agent to discover it. `list_zone_rulesets`, `list_r2_buckets`,
-`list_r2_objects`, and `list_kv_keys` paginate by cursor and return
-`nextCursor` instead of `page`. On those four the `cursor` argument says the
-endpoint pages by cursor rather than page number, and the `nextCursor` result
-says it is the only signal and that no `page` object is coming — so the loop
-condition is legible from either end of one tool, without fetching the guide.
-`list_worker_scripts` reports no counters at all and omits `page` entirely.
-
-Projected resource reads expose `raw: true` where the provider's larger object
-is commonly useful. `cloudflare_api_get` is the universal unprojected escape
-hatch. Raw shapes can hit a deployment's result cap, so programs should still
-filter and project before returning them.
-
-## Typed failures
-
-Cloudflare's error envelope carries an array of `{ code, message }` entries and
-sometimes a nested `error_chain`; the connection flattens the whole chain into
-the failure message so the provider's own code number survives to the agent.
-
-| Cloudflare | Connecta failure | Agent behavior |
-| --- | --- | --- |
-| 429 | `rate_limited`, retryable | Waits `retryAfterMs` — the `retry-after` header when present, otherwise the full five-minute window |
-| 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 | `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
-claim below that `10000` is overloaded — that is an observation about responses
-seen in practice. Treat both as well-supported readings that Cloudflare could
-invalidate without notice. Prefer `verify_api_token` or
-`verify_global_api_key`, as configured, when a diagnosis matters.
-
-Two ordering decisions are deliberate. The 429 branch is checked before the
-authentication codes, because Cloudflare reuses the generic `10000` code on
-throttled responses and reading a rate limit as an auth failure would tell an
-agent to stop when it should wait. And `10000` is *not* itself treated as an
-auth code: Cloudflare returns it for "Authentication error" but also for
-ordinary validation failures like "Invalid pagination cursor" and
-"domain_name is required", so routing on it would tell an agent its credential was
-broken when its arguments were. Genuine `10000` auth failures arrive with 401
-or 403 and are caught by status.
-
-Because the connection declares an operator-managed credential rather than an
-OAuth flow, an `auth_required` failure resolves to the `operator_config`
-recovery mode — the fix is a human updating the credential, not an authorization
-URL the agent can open. A missing credential fails that way before any request
-is made.
-
-Some failures never reach Cloudflare at all. A blank scope id, a `purge_cache`
-call with no variant or two, and an `update_dns_record` with nothing to change
-are all refused locally as `invalid_args` with a validation issue attached,
-because a round trip that can only 400 is a wasted call and a worse
-explanation.
-
-## Rate limits
-
-Cloudflare documents a global limit of
-[1,200 requests per five minutes per user](https://developers.cloudflare.com/fundamentals/api/reference/limits/),
-counted cumulatively across the dashboard, API keys, and API tokens. The
-connection declares a matching rolling-window admission budget plus a
-`maxConcurrency` of 6, overridable with the `maxConcurrency` option.
-
-The budget is a best-effort approximation of the per-user limit, not an
-enforcement of it. Each runtime keeps its own counter, so N Worker isolates or
-Node processes serving one deployment can each admit up to 1,200 — and the
-dashboard traffic of a human sharing the account is counted by Cloudflare but
-not by Connecta. `maxConcurrency` is the bound that actually protects a shared
-credential, because a single `execute_code` program can fan out far faster than
-the window notices.
-
-## Contract checks
-
-`npm run providers:check` compares the 49 fixed REST endpoints with
-Cloudflare's published OpenAPI document and the two MCP names, endpoint, and
-OAuth support with Cloudflare's official MCP page. It needs no Cloudflare
-credential. The MCP schemas are not vendored or reconstructed: the live
-`tools/list` response remains the contract agents receive.
-
-## Conventions
-
-This connection is audited against
-[the provider conventions](./provider-conventions.md). Its verdict per
-convention, including every recorded exception, is the Cloudflare section of
-[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/connector-guides.md

@@ -1,176 +0,0 @@
-# Connector guides
-
-Descriptions and schemas say *what* a connector's tools are. They do not say
-which tool to prefer, which id format an address quirk expects, how the service
-paginates, or how hard you may hammer it. A connector's optional `usageGuide`
-is where that goes — deployment-owned configuration, served by the `skills`
-meta-tool as `connector:<id>` and returned verbatim, with a bounded `summary`
-surfaced in discovery so an agent learns the guide exists at the moment it
-matters. See [meta-tools](./meta-tools.md#connector-guide-selection) for the
-discovery contract and [connectors](./connectors.md#catalog-contract) for how a
-guide is configured.
-
-## The shape of a guide
-
-`usageGuide` accepts a bare markdown string, which is still the shortest
-correct configuration, or the structured form:
-
-```ts
-const notion = remoteMcp("notion", {
-  url: "https://mcp.notion.com/mcp",
-  description: "Notion — pages, databases, comments",
-  auth: { type: "oauth" },
-  usageGuide: {
-    content: `# Notion usage
-
-Search before listing: \`notion.search\` covers pages and databases in one call.
-
-- Page ids are dashed UUIDs. Strip the trailing slug from a pasted URL first.
-- Paginate with \`start_cursor\`; \`page_size\` is capped at 100.
-- Writes replace blocks wholesale — read the block, merge, then write.
-`,
-    summary: "Search before listing; dashed-UUID page ids; cursor pagination",
-  },
-});
-```
-
-The field is on the `Connector` interface, not on a factory, so it works
-identically for `api()`, `remoteMcp()`, a prebuilt connection, and a
-hand-written connector. It is deployment-owned configuration like everything
-else here: an edit and a redeploy, never a runtime registration.
-
-`content` is returned byte for byte by `skills({ name: "connector:<id>" })`.
-`summary` is normalized and must fit 120 characters. A longer configured value
-refuses construction instead of silently changing the operator's words. Omit
-it and connecta derives the same bounded summary the skills listing uses: the
-first meaningful body paragraph, joined across Markdown's physical line wraps,
-with frontmatter, fences, rules, comments, and tables skipped. When the
-paragraph does not fit, connecta keeps a useful complete sentence when one
-fits, then prefers a clause or word boundary before adding an ellipsis. A heading is used
-only when the guide has no body, and the connector's description is the last
-resort. A derived summary is usually worse than a written one — it was written
-to open a document, not to answer "is this guide relevant to what I am about
-to do".
-
-`connector:<id>` is the only address for a guide, and built-in skill names are
-bare identifiers, so a guide can never shadow or be shadowed by `usage`: a
-connector whose id is literally `usage` is listed as `connector:usage`, and
-`skills({ name: "usage" })` still returns the built-in guide. Every miss —
-unknown name, unknown connector, connector with no guide — is an explicit
-error. Nothing silently falls back to the generic guide, because a generic
-answer to a specific question is worse than no answer.
-
-Discovery text is conditional on the deployment actually having a guide. Short
-pointers in the `skills`, `search_tools`, `call_destructive_tool`, and
-`execute_code` descriptions appear only when at least one visible connector
-declares one. The detailed selection rules live only in the built-in `usage`
-skill. That skill stays byte-identical across deployments, including its
-per-connector-guides section, so an agent reads it at most once per task.
-
-## What belongs in a guide
-
-The test is not "is this true" but "can a schema carry it". If a schema can,
-fix the schema instead — a constraint in the schema is enforced, is visible at
-the moment of the call, and costs nothing to a caller who never fetches the
-guide.
-
-So a guide carries:
-
-- **Tool preference.** Which of two plausible tools is the right one, and the
-  fact that decides it.
-- **Sequence.** What must happen first — resolving a name to an id, listing a
-  parent before a child.
-- **Identity and address quirks.** The id format an address expects, the
-  difference between the id in the URL and the id the API wants.
-- **Pagination conventions.** The cursor field, the page cap, whether the
-  connector has more than one convention.
-- **Units and aliases.** What a bare number means; what the service calls the
-  thing the caller calls something else.
-- **Reduction advice.** Which fields matter, for a downstream whose results are
-  large and whose schemas you do not control.
-- **Rate-limit etiquette**, with the number.
-
-And a guide does not carry: anything readable off the schema, background on
-what the service is, marketing, a tool list, or a second copy of the tool
-descriptions. It is fetched into a live context window — every line that
-repeats the schema is a line that displaced one that did not.
-
-**Style.** Write for the agent, not the operator; the built-in `usage` skill
-(`src/skills.ts`) is the model. Concise and imperative, leading with the
-decision rather than the background ("Search before listing", not "Notion has a
-search API"). Prefer short bullets to prose. Name exact tool addresses and
-argument names. State a constraint with its number.
-
-## The `required` rule
-
-`required: true` on the structured form means: fetch this guide before every
-operation on this connector. It surfaces as `guideRequired: true` with
-`guideRequiredReasons: ["connector_required"]` on discovery results.
-
-It is an instruction, not a gate. Nothing refuses the call — connecta tells the
-agent to read the guide first and then believes it, because a server-side
-refusal here would be a policy engine, which
-[`ethos.md`](../ethos.md) refuses.
-
-Reserve it for connectors whose correct arguments or sequence *cannot* be
-expressed by the downstream tool schema at all: generic API wrappers whose one
-broad tool name carries no endpoint vocabulary, and cross-operation conventions
-no single schema can state. Two categories already produce the flag on their
-own and must not be hand-declared for it — an unannotated or write-capable tool
-(`approval_required`) and a compact schema that was capped
-(`schema_truncated`). `connector_required` and `approval_required` survive
-exact schema expansion; `schema_truncated` clears once describe returns the
-exact shape.
-
-The failure mode of over-declaring is quiet and expensive: an agent that must
-fetch a guide before every call pays that fetch on the calls where the schema
-was already complete and unambiguous. `required` earns its cost on connectors
-where the alternative is a wrong call, not on connectors where it is a slightly
-slower right one.
-
-## Provider conventions
-
-The maintained prebuilt connections come in two shapes, and each has its own
-convention set — including the shape of its usage guide, which is one of the
-few things both shapes fully own:
-
-- [Hand-written HTTP providers](./provider-conventions.md#hand-written-http-providers)
-  (H1–H14) — `api()` surfaces where Connecta owns every name, schema,
-  projection, and error. Cloudflare, Notion, and Vercel.
-- [Hosted-MCP proxies](./provider-conventions.md#hosted-mcp-proxies) (P1–P13) —
-  `remoteMcp()` wrappers where the downstream owns the catalog and Connecta
-  owns the endpoint, credential, classification, guide, and budget. Linear,
-  Stripe, Mixpanel, and RevenueCat.
-
-Both sets are judged by one measure: what the convention saves the model that
-interacts with connecta, priced in discovery tokens, wrong-tool selection,
-argument retries, or result size. The same document defines
-[what a provider audit checks](./provider-conventions.md#what-the-audit-checks),
-so [#342](https://github.com/zackbart/connecta/issues/342) can run against it
-convention by convention rather than by taste.
-
-Two of those conventions decide how a guide is written, and they differ by
-shape. A hand-written provider's guide carries only what a schema cannot,
-because it owns the schemas and should fix them instead
-([H13](./provider-conventions.md#h13--the-guide-carries-only-what-a-schema-cannot)).
-A proxy's guide carries the reduction and identity-resolution advice its
-schemas will never carry, because it cannot change them
-([P7](./provider-conventions.md#p7--the-guide-carries-the-reduction-advice-the-schemas-cannot),
-[P8](./provider-conventions.md#p8--identity-resolution-comes-before-action)).
-
-## Tests that enforce this
-
-`test/meta-tools.test.ts` owns the guide behavior end to end: the skills
-listing carrying one entry per guided connector, summaries joining a
-hard-wrapped opening paragraph and shortening at readable boundaries,
-configured summaries refusing construction past the bound, heading and
-description fallbacks, markup skipping, whitespace-only guides treated as no
-guide, content returned verbatim including surrounding padding, identical
-content in two deployments staying isolated, every miss erroring rather than
-falling back to the generic guide with an identically labelled skills list on
-each branch, the `guide` pointer in search output, and `guideRequired`
-appearing for connector-required conventions, approval-bound tools, and
-truncated schemas — and being absent from a search that asked for no schemas.
-`test/server.test.ts` owns the conditional half: it compares a guide-free
-deployment's four short pointers against a guided one's, and asserts the
-complete `usage` skill is byte-identical between them.