@zackbart/connecta 0.15.0 → 0.16.0

package/documentation/call-admission.md

@@ -1,7 +1,143 @@
-# Call admission
+# Downstream call admission
 
-> **Stub.** The old manual was retired in the phase-1 docs restructure. This
-> document will be rewritten as an agent-facing guide — what the subsystem is
-> for, how to work on it, and what it must never do — once the ideas in
-> [ethos.md](../ethos.md) settle. The prior text lives in git history as
-> `docs/call-admission.md`.
+One admitted MCP request can fan out into many downstream calls. A program
+calls tools from loops, from `connecta.batch`, and from branches the caller
+never saw. The deployment-wide request pool
+([request admission](./request-admission.md)) bounds the envelope; it cannot
+see anything inside it. A provider that publishes "60 requests per minute"
+needs a bound that counts calls, not requests.
+
+So a connector may declare `callAdmission`: an optional per-runtime policy
+around its own `Connector.callTool` attempts.
+
+```ts
+const projects = api("projects", {
+  description: "Projects — issues and reports",
+  callAdmission: {
+    // Plural-ready public shape; this release requires exactly one rule.
+    rules: [{
+      maxConcurrency: 5,
+      maxQueueSize: 10,       // default 32
+      queueTimeoutMs: 2_000,  // default 5_000
+      retryAfterMs: 1_000,    // concurrency-overload hint
+      budget: { kind: "rolling-window", maxCalls: 60, windowMs: 60 * 60_000 },
+      partitionKey({ toolName, args }) {
+        return projectIdFor(toolName, args);
+      },
+    }],
+    maxPartitions: 1_024,     // default
+  },
+  tools: [/* … */],
+});
+```
+
+`api()`, `remoteMcp()`, and a hand-written `Connector` all accept it. Maintained
+prebuilt connections set it themselves — but only when the provider documents a
+number, which is convention
+[P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number).
+An invented budget is a throttle with no source.
+
+## Policy contract
+
+`maxConcurrency` and `budget` are independently optional, but a rule must
+declare at least one — a rule that bounds nothing is a typo, not a policy.
+Queue settings require `maxConcurrency`, because there is nothing to queue
+behind without it, and `maxQueueSize: 0` is the fail-fast shape. Numeric bounds
+are finite whole numbers: concurrency, timeouts, budget values, and
+`maxPartitions` are positive; queue size and `retryAfterMs` may be zero.
+`budget.kind` must be `"rolling-window"`. Everything invalid throws during
+registry construction.
+
+The container is an array so a later release can add atomic rules over
+different partition dimensions, but **exactly one rule** is accepted today.
+Zero or several throw rather than imply semantics the runtime does not have.
+Multiple rules cannot be faked as sequential leases: consuming one rolling
+token before a later rule refuses would charge a call that never reached the
+provider — the exact accounting error a budget exists to prevent.
+
+Omitting `partitionKey` gives one connector-wide partition. A callback runs
+synchronously on model-supplied arguments and must return a non-secret string
+of at most 128 UTF-8 bytes. A throw or an invalid return is a typed local
+`connector_call_failed`; neither the callback text nor the arguments are
+surfaced. The callback is operator code and may abort the caller synchronously,
+so cancellation is rechecked after it returns — otherwise a cancelled call
+could still consume a budget entry.
+
+State retains the returned key, bounded timestamps, counters, signals, and
+promise continuations. Nothing copies arguments into the limiter; the queued
+waiter closure deliberately captures the `AbortSignal` rather than the input
+object, because closing over the input would retain its `args`. At most
+`maxPartitions` states are live, and an idle state is evicted only once its
+active calls, queue, and rolling-window history are all empty — eviction must
+not be a way to reset a live budget. Exhausted partition capacity is
+`rate_limited` with the configured retry hint, not a silent unbounded map.
+
+## Attempt semantics
+
+The registry owns the limiter, and `InvocationService.invoke` acquires a permit
+immediately before `Connector.callTool` and releases it in `finally`. Both call
+paths — top-level `call_tool` and a program's `connecta.call` or
+`connecta.batch` — reach that same seam, so a program cannot buy itself a
+second limit by taking the other route.
+
+- **A retry is another attempt.** It reacquires and can consume another budget
+  entry, because the provider counts it that way. Backoff never holds a
+  concurrency permit.
+- **A proactive short-window `rate_limited` refusal** participates in the
+  ordinary retry policy and counts as an attempt. Activity records the final
+  outcome and the attempt count.
+- **A queued cancellation consumes nothing.** It is removed from the queue with
+  no rolling-window entry charged.
+- **Caller cancellation is terminal.** It is non-retryable, releases its
+  permit, records a `cancelled` activity outcome, and is not connector-health
+  evidence.
+- **Budget exhaustion fails immediately** as `rate_limited`, `retryable: true`,
+  with the exact `retryAfterMs` to the next free slot. Concurrency overflow
+  uses the configured hint instead, because there is no exact answer.
+- **Local refusals are not connector health failures.** They are activity
+  errors, but no provider call happened, so poisoning the connector's health
+  with them would report the limiter's success as the downstream's failure.
+  `isCallAdmissionError` is what keeps `recordFailure` out of that path.
+
+Only tool execution is covered. Catalog `listTools`, status probes, credential
+checks, and authorization operations stay outside the budget: they are not the
+calls a provider is rate-limiting, and charging discovery for them would make
+a program's first search cost it capacity to act.
+
+Queue admission and connector execution have separate clocks. `queueTimeoutMs`
+bounds only the wait for a permit; a per-attempt `timeoutMs` starts after
+admission. A saturated call can therefore take up to their sum. With
+`diagnostics: true`, `admissionMs` reports the permit wait and `connectorMs`
+the admitted attempt — which is the only way to tell "the provider is slow"
+from "we are throttling ourselves".
+
+## Enforcement scope
+
+This is deliberately **per-runtime**. It completely contains fan-out inside one
+request, including a wide `connecta.batch` in one Worker isolate. A rolling
+budget is exact inside one Node process or Worker isolate, and best-effort
+across isolates, replicas, and restarts.
+
+KV cannot coordinate the invariant without atomic operations, and this release
+adds no Durable Object or other distributed coordinator. The async typed permit
+is the seam a coordinator would slot into later; until then the guide says what
+the bound actually is rather than implying a global one.
+
+## Observations
+
+`/health` exposes payload-free aggregates at
+`admission.downstreamCalls.connectors.<id>`: retained partition count, current
+active and queued gauges, cumulative admitted/queued/rejected/rate-limited/
+cancelled counts, and queue-wait count, total, and maximum. The open endpoint
+never exposes partition keys, tool arguments, or results — a partition key can
+be a customer identifier, which is precisely why it stays out of an unauthenticated
+payload. Ordinary payload-free activity records the final call outcome and its
+typed error code.
+
+## Tests that enforce this
+
+| Invariant | Suite |
+| --- | --- |
+| Independent partitions, exact rolling-window reset and retry, queued cancellation charging no budget, synchronous cancel during partition derivation, validated values snapshotted rather than read from mutable config, bounded partition state and contained `partitionKey` failures, empty and multi-rule policies refused | `test/call-admission.test.ts` (controller) |
+| One base-registry limiter shared by direct and program calls, batch bounds with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, short proactive windows retried without poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
+| Where provider budgets are allowed to come from at all | [provider conventions P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number), [provider audit](./provider-audit.md) |

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-five tools combine ergonomic,
+surface over Cloudflare's v4 REST API. Fifty-two 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
@@ -23,6 +23,18 @@ const edge = cloudflare("cloudflare_prod", {
 });
 ```
 
+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
@@ -40,7 +52,7 @@ 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 Bearer-token `fetch` with a uniform
+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`
@@ -51,10 +63,16 @@ must be relative.
 
 ## Credentials
 
-The connection declares one operator-managed credential: a scoped Cloudflare
-API token, sent as `Authorization: Bearer <token>`. Create it under My Profile →
-API Tokens → Create Token. Do not use a Global API Key — it carries every
-permission on the account and cannot be scoped.
+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:
 
@@ -83,10 +101,9 @@ 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, which is what
-makes it the right first call when something fails. The `/credentials` Test
-action runs the same verification against the candidate token before it is
-stored.
+`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 `/credentials` Test action 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
@@ -127,7 +144,7 @@ projections:
 | 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, metrics, CORS | create/update/delete bucket, delete object, replace/delete CORS |
+| 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
@@ -136,6 +153,39 @@ 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.
 
+### 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`](../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:
+
+- **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 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
@@ -146,21 +196,28 @@ method classification into user input:
   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.
+  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.
-Authentication, host selection, content type, content length, and transfer
-framing remain connector-owned and cannot be overridden.
+`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 token's Cloudflare permissions.
+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
@@ -173,8 +230,8 @@ comes from Cloudflare's API reference.
 
 ### Where the `perPage` bounds come from
 
-`strictValidation` is on, so an out-of-range `perPage` is refused locally
-before it reaches Cloudflare. That is only a favor when the bound is really
+`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:
 
@@ -242,8 +299,12 @@ Paginated lists add a `page` object derived from `result_info`:
 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_r2_buckets`, `list_r2_objects`, and
-`list_kv_keys` paginate by cursor and return `nextCursor` instead of `page`.
+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
@@ -271,8 +332,8 @@ 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, and prefer `verify_api_token` over the code list
-when a diagnosis actually matters.
+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
@@ -280,15 +341,15 @@ 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 token was
+"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 token, not an authorization
-URL the agent can open. A missing token fails that way before any request is
-made.
+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
@@ -309,5 +370,12 @@ 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
-token, because a single `execute_code` program can fan out far faster than the
-window notices.
+credential, because a single `execute_code` program can fan out far faster than
+the window notices.
+
+## 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](./provider-audit.md).

package/documentation/code-mode.md

@@ -8,10 +8,9 @@ it is specified in prose first and implemented second — the same discipline th
 [MCP spec bump](./mcp-2026-07-28.md) followed.
 
 Two executors implement this document: QuickJS in a child process on Node, and
-`DynamicWorkerExecutor` from `@cloudflare/codemode` on Workers. Divergence
-between them is a bug unless it appears in
-[Executor exceptions](#executor-exceptions), which names the reason. Anyone can
-implement a third executor from this document without reading either.
+`DynamicWorkerExecutor` from `@cloudflare/codemode` on Workers. Divergence between
+them is a bug unless it appears in [Executor exceptions](#executor-exceptions),
+which names the reason. Anyone can implement a third from this document alone.
 
 The [code-first exploration](./code-first-exploration.md) is the evidence behind
 the direction; [`ethos.md`](../ethos.md) carries the verdicts. Where its prototype
@@ -43,7 +42,7 @@ const connecta = createConnecta({
 CPU, wall-time, memory, stack, queue, result, log, and IPC bounds are configured
 on the executor. Server bundlers must keep the `@zackbart/connecta/quickjs`
 package files external so the child entry stays on disk. The
-[Node example](../examples/node/README.md) carries the complete setup.
+[Node template](../templates/node/README.md) carries the complete setup.
 
 On Cloudflare Workers, the Worker Loader binding provides the required sandbox:
 
@@ -54,9 +53,8 @@ createConnecta({
 });
 ```
 
-Dynamic Workers require the Workers Paid plan. The
-[Worker example](../examples/worker/README.md#code-mode) carries the complete
-required binding and package setup.
+Dynamic Workers require the Workers Paid plan. The complete required binding and
+package setup is in the [Worker example](../examples/worker/README.md#code-mode).
 
 ## What an executor must implement
 
@@ -64,6 +62,7 @@ The host side of the seam is two types in `src/types.ts` and nothing else.
 
 ```ts
 interface Executor {
+  readonly name?: string;                       // what /health and doctor report
   execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
   close?(): void | Promise<void>;
 }
@@ -113,11 +112,12 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 
 Optionally implement `AdmittingExecutor` (`acquire()` returning a lease whose
 `execute` runs once) for bounded admission (`L7`) and `close()` for shutdown;
-connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise.
+connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise. The
+optional `name` — else a class's constructor name, which a minifier may rewrite
+— is what [`/health` and `doctor`](./operations.md#the-cli) report.
 
-Note what is *not* on this list: [emitted output](#emitted-output) asks
-nothing of an executor — `connecta.emit` is just another provider function
-(`M8`).
+Note what is *not* on this list: [emitted output](#emitted-output) asks nothing
+of an executor — `connecta.emit` is just another provider function (`M8`).
 
 ## The program
 

package/documentation/connector-guides.md

@@ -1,7 +1,174 @@
 # Connector guides
 
-> **Stub.** The old manual was retired in the phase-1 docs restructure. This
-> document will be rewritten as an agent-facing guide — what the subsystem is
-> for, how to work on it, and what it must never do — once the ideas in
-> [ethos.md](../ethos.md) settle. The prior text lives in git history as
-> `docs/connector-guides.md`.
+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 capped at 120 characters for discovery. Omit it and
+connecta derives the same bounded line the skills listing uses: the first
+meaningful body line, with frontmatter, fences, rules, comments, and table rows
+skipped, a heading used only when the guide has no body, and the connector's
+description as 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. The
+guide sentences in the `skills`, `search_tools`, `call_destructive_tool`, and
+`execute_code` descriptions appear only when at least one visible connector
+declares one — the connector set is fixed at construction, so this is stable
+per deployment, and a deployment with no guides pays no always-loaded context
+for a feature it does not use. The built-in `usage` skill is the deliberate
+exception: it stays byte-identical across every deployment, including its
+per-connector-guides section, so an agent that has read it once in a task never
+needs a deployment-local copy of it.
+
+## 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 and Notion.
+- [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, and Mixpanel.
+
+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 derived from the
+first meaningful line and falling back to the connector description when the
+guide is all markup, 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 tool
+descriptions against a guided one's, and asserts the `usage` skill is
+byte-identical between them.