@zackbart/connecta 0.15.1 → 0.16.1

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-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,11 +140,11 @@ 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 |
-| 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
@@ -153,6 +153,63 @@ 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`](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 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.
+
 ### The whole-v4 escape hatch
 
 Cloudflare adds products and endpoints faster than a curated connector should
@@ -171,8 +228,14 @@ method classification into user input:
 
 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;
@@ -191,8 +254,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:
 
@@ -260,8 +323,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
@@ -281,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
@@ -329,3 +404,10 @@ 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.
+
+## 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-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

@@ -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
 
@@ -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 |

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.