@zackbart/connecta 0.37.1 → 0.39.0

package/documentation/deploying.md

@@ -64,12 +64,9 @@ platform, proxy or adapter cap still wins. See
 A Node host serving `connecta.fetch` without `listen()` has no owned sender:
 every maintained-provider write, every reviewed POST read and every remote MCP
 write is refused before sending. Downstream OAuth credential POSTs also require
-that sender; discovery GETs retain native fetch. Resource writes worked in 0.34.1;
-credential POSTs used native fetch through 0.34.1. For example, an `assistant` using
+that sender. For example, an `assistant` using
 `vercel_api_read` to POST `/v1/registrar/domains/availability` needs that
-transport even on a read-only endpoint. A Node deployment using only the root
-entry refuses those requests before sending them. Workers use their native
-fetch transport.
+transport even on a read-only endpoint. Workers use their native fetch transport.
 
 By default, Node's `listen()` handles SIGTERM and SIGINT: it stops accepting
 connections, closes idle connections and accepted sockets without a first HTTP
@@ -81,9 +78,8 @@ keepalive before shutdown is unchanged. Its shutdown deadline defaults to ten se
 (`shutdownTimeoutMs`). For example, retain the template's `listen(connecta, port)` when running it under
 Docker Compose so `docker compose stop` uses this cleanup.
 
-The owned Node sender connects directly by default. To send maintained-provider
-requests (including reads), remote MCP writes and OAuth credential POSTs through an HTTP(S) CONNECT
-proxy, set `proxy` explicitly on `listen`:
+The owned Node sender connects directly by default. For HTTP(S) CONNECT proxy
+egress, set `proxy` explicitly on `listen`:
 
 ```ts
 listen(connecta, { port: 3000, proxy: "http://proxy.example.com:8080" });
@@ -108,9 +104,7 @@ replayed by the sender, including after HTTP 421, a reset or a 503. An uncertain
 refresh requires authorization again; Connecta blocks the spent refresh
 fingerprint rather than redeeming it twice. Once a refresh claim has been
 submitted, that protection remains conservative even if proxy setup later fails.
-Use a fresh authorization flow to reconcile. OAuth discovery remains on native
-fetch and needs its own host proxy policy. These credential POST requirements
-change the native-fetch behavior of 0.34.1.
+Use a fresh authorization flow to reconcile.
 
 ## Start on Workers
 
@@ -136,10 +130,8 @@ verified ingress behavior and the cases that still require verification.
 Agents use `/agent/<pool>`, which connecta authenticates with the `cta_` token
 alone and which ignores Access context entirely
 ([agent endpoints](./auth.md#agent-endpoints)). Behind Access, the edge must
-let those requests through without an Access login or service token. The P0
-probe ([observations](./architecture.md#production-access-bypass-for-agent-endpoints))
-verified this shape on 2026-10-15. The Worker example's `alchemy.run.ts`
-declares both applications:
+let those requests through without an Access login or service token.
+The Worker example's `alchemy.run.ts` declares both applications:
 
 1. Keep the Worker-level application, whose destination is
    `{ "type": "worker", "worker_id": "<the Worker script tag>" }`, exactly as
@@ -170,12 +162,9 @@ declares both applications:
 3. Point each agent at `https://<host>/agent/<pool>` with
    `Authorization: Bearer cta_…` and drop its `CF-Access-Client-Id` and
    `CF-Access-Client-Secret` headers. The pool must list `"agent:<name>"`.
-4. Verify after the change has settled. Access changes took 15–19 seconds to
-   settle in the probe, and while they propagate the edge can answer with
-   transient 500 (`error code: 1104`) or 404 (`error code: 1042` or `1043`)
-   responses, and in one round a 403 on a bypassed path after more than 30
-   seconds. Do not rely on a fixed wait: repeat these checks until they agree
-   for several consecutive rounds. Without credentials, `/agent/<pool>`
+4. Verify after the change has settled. Do not rely on a fixed wait: repeat
+   these checks until they agree for several consecutive rounds. Without
+   credentials, `/agent/<pool>`
    reaches connecta (its 401 carries `WWW-Authenticate: Bearer`, not Access's
    403 page), while `/mcp` and `/` still get Access's refusal. Then run
    `connecta doctor --pool <pool>` with the agent's token.
@@ -185,11 +174,8 @@ Connecta answers there only an issued token of an agent listed in the pool,
 and gives every other spelling of the agent namespace a 404 before auth,
 because Access matches `/agent/*` after resolving dot segments, folding case,
 decoding unreserved escapes, and collapsing a leading `//`, while the Worker
-sees the raw path. Two cases were not tested: a human's `CF_Authorization`
-cookie on a bypassed path, whose `ctx.access` identity is unknown (connecta
-never reads it at `/agent/*`), and Custom Domains, which use the same
-documented hostname-and-path form but were not observed; only `workers.dev`
-was probed. Pinning the Worker-level application's AUD on human routes is
+sees the raw path. Connecta never reads `ctx.access` at `/agent/*`.
+Pinning the Worker-level application's AUD on human routes is
 recommended hardening that connecta does not yet do.
 
 ## Compose capabilities and access
@@ -221,9 +207,11 @@ existing-record migration.
 
 One deployment serves one tenant and may admit several people. Node uses Clerk
 for human auth; Access is Workers-only. With inbound auth, `maintainers` is
-required: only they reach plain `/mcp` and the operator UI. Everyone else
-reaches a pool that lists them in `members`: people at `/mcp/<pool>`, agents
-at `/agent/<pool>`. Maintainers alone administer shared credentials, manage
+required: they receive the whole catalog at plain `/mcp` and the operator UI.
+Everyone else reaches a pool that lists them in `members`: people at
+`/mcp/<pool>`, agents at `/agent/<pool>`. A person in exactly one pool may also
+use plain `/mcp`, which serves them that pool, so one client URL can be handed
+to every person; a person in several pools must use `/mcp/<pool>`. Maintainers alone administer shared credentials, manage
 agent tokens, and read activity; members connect their own accounts on
 personal connectors in their pools.
 [Auth](./auth.md#principals-visibility-and-operators) owns maintainers and members;
@@ -314,22 +302,16 @@ Bump the exact package pin, read the [changelog](../CHANGELOG.md) for every
 intervening release, and apply the relevant migration before startup. `init`
 does not merge changes into an existing deployment.
 
+Before upgrading past 0.37.1 with pre-0.29 state, follow
+[Retired layout migrations](./migration-retired-layouts.md). Version 0.37.1 is
+the last bridge for KV → D1, JSON → SQLite, and OAuth layout-2 conversions.
+
 For an existing Node deployment, add the Node entry's pinned optional peer
 before starting the upgraded package: `npm install --save-exact undici@6.29.1`.
 The current Node template already declares this dependency.
 
-For 0.35.0, serve Node with `listen` from `@zackbart/connecta/node`, as the
-current template does. Without `listen()`, a host serving `connecta.fetch` has
-no owned sender: every maintained-provider write, every reviewed POST read and
-every remote MCP write is refused before sending, although each worked in 0.34.1.
-Downstream OAuth token, registration and revocation POSTs also require that
-sender. With `listen()`, every maintained-provider request, reads included,
-remote MCP writes and those credential POSTs use the owned sender. Configure
-`listen(..., { proxy })` explicitly for HTTP(S) CONNECT proxy egress; ambient
-`NODE_USE_ENV_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY` and host proxy dispatchers do
-not configure it. Remote MCP reads and OAuth discovery GETs retain native fetch
-and need their own host proxy policy. An uncertain refresh requires fresh
-authorization rather than replaying the spent token. See [Start on Node](#start-on-node).
+For Node upgrades, retain the template's `listen` entrypoint and apply the
+[Node transport and proxy requirements](#start-on-node).
 
 Authenticated MCP bodies now default to 4 MiB through
 `admission.requests.maxBodyBytes`; Node's separate pre-auth buffer also defaults
@@ -352,10 +334,10 @@ and [Eve agents](./meta-tools.md#eve-agents).
 
 - [Provider migration for 0.35](./provider-migration-0.35.md) collects provider upgrade actions for 0.35.0, including removal of Infisical, Notion, and Mixpanel factories.
 - [Migration to 0.34](./migration-0.34.md) covers the Overview landing page, Endpoints at `/endpoints`, default browser titles, and Workspace discovery in owner-less agent pools. No storage migration or token rotation is needed from 0.33.
+- [Split mixed pools](./pool-membership-upgrade.md) before starting a deployment that lists people and agents together; mixed membership now throws at construction.
 - [Migration to 0.33](./migration-0.33.md) maps every removed access option to `maintainers`, pool `members`, and `agents`, moves agents to `/agent/<pool>`, and covers pool owners, token revisions, operator contract v2 with its operator route changes, and the pre-auth listen fix.
 - [Tokens issued before agents](./auth.md#agent-tokens-and-upgrading-from-earlier-tokens) stop admitting until each machine's token is bound once to a declared agent with `npm run adopt-token -- <token-id> <agent>` (Node) or `AccessTokenManager.adopt`, which keeps its secret. Human-bound tokens stay refused; issue those agents new tokens. Pool members name `"agent:<name>"` instead of matching token record ids.
-- [Node storage from 0.28](../templates/node/README.md#storage) uses `connecta migrate-state` to copy the JSON state into SQLite. Activity JSONL is not imported.
-- [Worker storage from 0.28](../examples/worker/README.md#upgrading-from-028) copies KV into D1 with a one-shot migration.
+- [Retired layout migrations](./migration-retired-layouts.md) requires completing Node JSON → SQLite, Workers KV → D1, and every OAuth layout-2 grant conversion on 0.37.1 before upgrading. The new package no longer supplies those migrations.
 - [Worker deployments on Wrangler](../examples/worker/README.md#moving-a-wrangler-deployed-worker-to-alchemy) move to Alchemy once, adopting the Worker, D1 database, and Access applications so the script tag and Access AUD stay unchanged.
 - [Notion, Vercel, and Cloudflare for 0.29](./provider-migration-0.29.md) records historical defaults and retained API tool names.
 - [Executor wiring](./code-mode.md#deploy-time-capability) requires branded shipped executors or a self-managed custom executor.

package/documentation/integrating.md

@@ -57,6 +57,7 @@ const crm = remoteMcp("crm", {
 });
 const base = ["crm", "tickets"]; // the agent's lowest tier
 // connectors: [crm, tickets], agents: ["assistant"],
+// Agent tiers list only agents; people use a separate pool sharing base.
 // pools: { assistant: { tools: base, members: ["agent:assistant"] } }
 ```
 
@@ -219,26 +220,11 @@ failure also reports an unknown outcome with no retry or wait advice; a proven
 unsent failure retains its own recovery advice. Connector `readOnly` remains
 optional and composes with endpoint policy.
 
-On Node, serve with `listen` from `@zackbart/connecta/node`: it installs the
-owned transport that prevents native fetch or a host-configured dispatcher
-from silently resending a remote MCP write. Without that transport, Node
-refuses remote writes before dispatch. A connector with its own `fetch` hands
-writes to that function instead, which owns their single attempt. Downstream OAuth token, registration and
-revocation POSTs also require the owned sender. Read calls and OAuth discovery
-GETs keep native fetch. Workers
-use their native fetch with manual redirects; transport failures after
+On Node, follow the [Node transport and proxy requirements](./deploying.md#start-on-node).
+A connector with its own `fetch` hands writes to that function, which owns their
+single attempt. Workers use native fetch with manual redirects; failures after
 dispatch remain unknown and non-retryable.
 
-The owned sender connects directly by default. For HTTP(S) CONNECT proxy egress,
-configure `listen(connecta, { port: 3000, proxy: "http://proxy.example.com:8080" })`.
-This controls maintained-provider requests, remote MCP writes and OAuth
-credential POSTs; it ignores `NODE_USE_ENV_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`
-and host proxy dispatchers. Remote MCP reads and OAuth discovery GETs retain
-native fetch and need their own host proxy policy. An uncertain refresh requires
-fresh authorization rather than replaying the spent token. See
-[Node startup](./deploying.md#start-on-node) for the proxy URL, credentials and
-TLS trust rules.
-
 Remote catalogs evolve. Discovery, direct calls, and programs enforce the
 current annotations and `ConnectaConfig.classification` overrides. A leftover
 `classify` option throws at construction and names that map. Provider reviews,
@@ -282,6 +268,14 @@ which binds the grant to configured API origins and manages authentication.
 [Downstream OAuth on api()](./auth.md#downstream-oauth-on-api) owns a concrete
 HTTP example and the client setup contract.
 
+Text a handler writes for the agent that names a Connecta route, such as "call
+authorize_connector" in an auth error, uses `ctx.routes` (`ctx.routes.authorize`,
+`ctx.routes.read`, `ctx.routes.write`, `ctx.routes.search`, `ctx.routes.program`,
+`ctx.routes.skills`). Connecta sets it on every context it builds to the names of
+the surface serving the call: the meta-tool names on the default surface, and
+the native contract's wording on a native pool. It is optional in the type, so
+fall back to the meta names for a context built elsewhere.
+
 Mark every side-effecting tool `readOnlyHint: false`. On a writable endpoint
 writes use `call_destructive_tool` or a program, within the caller's grants; a
 `readOnly` endpoint refuses them and omits them from search. Client approval is independent of
@@ -320,6 +314,11 @@ literal header credentials with personal scope. Review
 [management permissions](./auth.md#management-permissions) before exposing a
 new integration or its authentication controls.
 
+Plain `/mcp` serves maintainers the whole catalog and every other person their
+single pool, so one URL can serve the meta-tools to `alice` and a native pool's
+tools to `bob`. After changing a pool's `tools`, `readOnly`, `surface` or
+`executeCode`, check it as a member at plain `/mcp` as well as at `/mcp/<pool>`.
+
 After editing configuration, run the deployment's typecheck and doctor, then
 perform a bounded read. Add negative checks for target restrictions and writes
 when authoring a handler or provider. Follow repository verification policy
@@ -346,7 +345,7 @@ check shared behavior. Provider-specific tests remain beside each provider.
 
 Use [`@zackbart/connecta-eve`](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 in the Eve app for an app-owned connection and endpoint instructions refreshed
-once per turn. It requires Node 24 and Eve 0.84.x, and installs separately from
+once per turn. It requires Node 24 and Eve 0.90.x, and installs separately from
 Connecta. Follow its README for the two agent files, token environment variables,
 optional write approval and Vercel OIDC token source. Configure the server's
 [agent and pool membership](./auth.md#issue-rotate-or-revoke-an-agent-token)

package/documentation/meta-tools.md

@@ -49,7 +49,12 @@ write tools from `search_tools` results and describe, and refuses every write
 call. Connector `readOnly` applies the same restriction on every endpoint; effective read-only is endpoint OR connector. Neither setting changes connector visibility or read grants. Guides
 (`queryAnalysis.guideSummary`, `skills`, `connecta.skill`, skill
 `resources/read`) are documentation and may name tools the endpoint refuses. The four tools with structured-only success results
-advertise `outputSchema`. The two direct-call tools omit it because their default
+advertise `outputSchema`. `search_tools`'s schema defines its typed failure,
+including every authorization-handoff field, once under `$defs.failure`;
+`catalogErrors[]` references it through `allOf` with `connector` required, and
+`queryAnalysis.catalogError` references it directly. The schema declares no
+`$schema`, and validators for drafts 4, 7, 2019-09 and 2020-12 accept the same
+pages. The two direct-call tools omit it because their default
 mode returns native `content`. Default-mode successes declare
 `_meta["dev.connecta/format"]: "json" | "text"`; value mode places the value in
 `data` and declares `format` in its complete result envelope.
@@ -134,16 +139,25 @@ Live connector probing is not a fourth: the operator pages and `/health` own it.
 
 ## Discovery context
 
-The deployment-derived `execute_code` description carries a live connector
-inventory before any catalog search — registry order, each canonical id, and a
-distinct configured title, with no second name minted for programs. Titles
-normalize whitespace and cap at 48 UTF-8 bytes, the complete line caps at 256,
-entries stay whole, and a truncated line ends with the exact `+N more` count, so
-account and environment hints cannot eat the inventory. It reads only the
-configured registry: no catalog load, no credential probe, no capability, and no
-replacement for canonical discovery or addressing. Program search results carry
-the same bounded `connectorTitle` per tool, so choosing an account or
-environment costs no provider read. The inventory does not probe live access.
+The deployment-derived `execute_code` description carries a connector
+inventory before any catalog search — registry order and each canonical id,
+with no second name minted for programs. An entry adds the configured title
+only when it says more than the id: a title whose words the id already spells,
+such as `Google Calendar` for `google_calendar`, is dropped. Titles normalize
+whitespace and cap at 48 UTF-8 bytes. A connector with a guide says how to
+fetch it: `read first: skills({name:"connector:<id>"})` for a required guide,
+`guide: skills({name:"connector:<id>"})` otherwise. For example:
+`Connectors: crm (Customer CRM; read first: skills({name:"connector:crm"})), tickets.`
+
+The complete line caps at 1,024 UTF-8 bytes, which names every connector of a
+typical deployment. Past the cap, detail degrades before names do: titles are
+dropped first, then optional guide pointers. Only when bare ids and required
+guide pointers still exceed it do whole entries give way, in registry order, to
+an exact `+N more` count. The inventory reads only the configured registry: no
+catalog load, no credential probe, no live status, no capability, and no
+replacement for canonical discovery or addressing. Search pages carry the same
+bounded title once per connector in `connectors[<id>].title`, so choosing an
+account or environment costs no provider read.
 
 Read-only lookup belongs in `connecta.search` inside the program; top-level
 `search_tools` stays for explicit catalog inspection and approval-required
@@ -171,6 +185,56 @@ read/write filter. On `approvalRequired` searches the returned discovery tool
 is still a read. Hidden tools, missing grants and read-only restrictions remain
 in force. Browsing does not consult operation vocabulary.
 
+When a matched operation's call is fully determined, the first page also
+carries it in `readyCalls`, so a program can call it without operation search or
+details:
+
+```json
+{
+  "readyCalls": [
+    {
+      "address": "notes.notes_api_read",
+      "args": { "path": "/v1/notes" },
+      "classification": "read",
+      "summary": "List notes"
+    }
+  ]
+}
+```
+
+Pass `args` unchanged to `connecta.call(address, args)` or `call_tool`. An
+operation is fully determined only when it is a reviewed read served by the
+hatch's `_api_read` tool itself (no named tool), uses GET, the read tool's
+default method, and declares no path template, required parameter or required
+body. Anything needing an id, a method choice or an argument the agent must
+fill in stays behind `_api_search` and `_api_details`. Ready calls pass the same
+endpoint, connector read-only, safety, hidden-tool and grant checks as the
+vocabulary match, through a visible read tool in the caller's view. They are
+computed offline from the construction-time index, read no account data, and
+start no authorization.
+
+A ready call must also be what the query names. Each path segment, and the
+operationId without its action and version words, is one whole resource name:
+`event_destinations` is the name "event destination", never "event". Every
+query word other than an action (`list`, `get`, `count`, `show`, `create`,
+`update`, `delete` and their vocabulary aliases) must belong to a resource name
+whose words the query states in order, with singular/plural normalization and
+the provider's declared synonyms. Version segments such as `v1` never count, and
+a summary may supply only actions. A query with no object word gets no ready
+call. Ready calls are omitted entirely when the top result is an exact tool name
+or address, or a complete match on an authored tool, not the hatch's own search
+or read tool, whose name adds nothing to the query: each of its name words is an
+action or a query word, up to plural/singular and declared synonyms. For
+example, `list teams` returns `list_teams` and no ready call, even when other
+operations mention teams in their summaries, while `list projects` still offers
+`/v10/projects` beside `list_project_env_vars`, whose name adds `env` and `vars`.
+Each hatch offers only its top-ranked operation: a last path segment naming the
+resource first, then the fewest resource words the query did not ask for, then
+the shortest path. A connector offers at most one ready call and a page at most
+three, in connector order. Later pages carry none. A ready
+call keeps its read tool's `guideRequired` and `guideRequiredReasons`, and its
+connector appears in `connectors`.
+
 Vocabulary is bounded: queries at most 200 characters and eight terms; each
 hatch caches at most 8,192 rows and 2,097,152 characters, with at most 1,024
 characters per row and 128 query intersections. Longer queries and vocabulary
@@ -281,9 +345,11 @@ guide's first meaningful body paragraph. `required: true` is reserved for
 generic API wrappers and cross-operation conventions a complete downstream
 schema cannot express.
 
-Search and describe results carry a `guide: "connector:<id>"` pointer and a
-`guideSummary`. A matching tool also carries `guideRequired: true` and
-`guideRequiredReasons` when Connecta can prove review is necessary:
+Describe results carry a `guide: "connector:<id>"` pointer and a
+`guideSummary`; a search page carries both once per connector in
+`connectors[<id>]`. A matching tool row or description also carries
+`guideRequired: true` and `guideRequiredReasons` when Connecta can prove review
+is necessary:
 
 | Reason               | Raised by                            | Survives exact schema expansion                          |
 | -------------------- | ------------------------------------ | -------------------------------------------------------- |
@@ -297,8 +363,17 @@ is merely told to fetch the guide first, for any reason listed. Otherwise the
 bounded summary decides — connector-specific sequencing, units, pagination,
 aliases, and generic API conventions still need the guide when they affect the
 task, while a complete and unambiguous one-read schema proceeds directly. Guide
-lookup always uses an exact name returned by `skills({})`, search, or describe;
-callers never manufacture `connector:<id>` from an unmarked connector.
+lookup uses an exact name returned by `skills({})`, search, describe, or the
+`execute_code` inventory; callers never manufacture `connector:<id>` from an
+unmarked connector. A bare connector id, such as `skills({ name: "crm" })` or
+`connecta.skill("crm")`, also serves that connector's guide. Built-in skill
+names stay reserved: `usage` and `investigate` always fetch the built-in skill,
+even when a connector has that id, whose guide stays at `connector:usage` or
+`connector:investigate`. A bare id naming a connector without a guide fails with
+`Connector "<id>" has no usage guide.`; any other unknown name fails as an
+unknown skill. Names containing `:`, including URIs, never fall back to a bare
+id. MCP `skills/get` resolves names the same way; `resources/read` accepts only
+document URIs.
 
 A connector-scoped lexical miss keeps that connector's guide metadata under
 `queryAnalysis`. This matters for generic wrappers whose broad tool name
@@ -307,12 +382,29 @@ disappearing with the zero-tool page.
 
 Two built-in skills are byte-identical across deployments. `usage` is fetched
 only for missing guidance or program repair, and owns program selection detail, examples, runtime
-differences, and repair guidance; `investigate` is on-demand guidance for
-purchase verification, experiment checks, and customer or deployment
-investigations — shared guidance, not a saved workflow and not a source of
-deployment-specific ids. The always-loaded instructions and tool definitions keep
+differences, and repair guidance; `investigate` is domain-neutral on-demand
+guidance for an investigation that spans several services — shared guidance,
+not a saved workflow and not a source of deployment-specific ids. `skills`
+lists it; the `execute_code` description does not advertise it. The always-loaded instructions and tool definitions keep
 route selection, the fail-closed boundary, and the minimum guest syntax, so a
 client that never fetches a skill can still write a valid first program.
+
+The server instructions state the complete routing rule once. Some clients
+drop server instructions, so each tool description stays sufficient for its own
+correct use without restating that rule: `call_tool` names its scope (one
+known-address read) and points other read work to `execute_code`;
+`search_tools` names its scope (catalog inspection, or finding a write) and
+points read work into a program; `execute_code` opens with the terse
+three-route lead (`One known read: call_tool. One known write:
+call_destructive_tool. Everything else: execute_code.`, or the read-only
+two-route form). The `usage` skill points to those two sources instead of
+repeating them.
+
+Tool descriptions and output schemas carry deployment configuration only: the
+connector inventory, budgets, the endpoint's read-only setting, and whether any
+visible connector has a guide. No catalog outcome, call, authorization state,
+or other live status reaches `tools/list` or the instructions, so the
+always-loaded surface stays byte-stable for a client's prompt cache.
 The instructions are the same on every endpoint except one addition: at
 `/mcp/<pool>` and `/agent/<pool>`, a pool that sets a
 [`description`](./auth.md#pools) has it appended after `This endpoint: `, so
@@ -528,8 +620,10 @@ The default cap sits under both lines with room to spare. Preview plus notice
 stays under 25,000 bytes, which is under 50,000 characters for any text, because
 a character is at least one UTF-8 byte, and under 25,000 tokens for any text,
 because a token covers at least one byte. A `connecta.result` page is bounded by the same
-inline byte cap, and 24,000 matches the program result boundary in
-[code mode](./code-mode.md). A deployment whose
+inline byte cap, and 24,000 matches the default program result boundary in
+[code mode](./code-mode.md) (`execute.maxResultChars`). The `maxBytes` in
+`nextAction` is sized so one page fits that boundary under worst-case JSON
+escaping, capped by the call's own inline cap: 3,829 bytes by default. A deployment whose
 clients take more can raise the cap, and one whose clients take less can lower
 it, per connector if need be; a result between 24,000 and 50,000 bytes that
 used to arrive whole now pages. A client that spills rather than rejects keeps
@@ -616,7 +710,7 @@ a fixed warning without storage error prose. Never repeat a write to recover out
 page. Select tool rows from `page.tools`.
 With the same schema format, schema-key option, and scoped registry, both paths
 return identical data. Top-level search omits schemas unless requested; programs
-default to JSON schemas and schema-key metadata.
+default to TypeScript signatures and schema-key metadata.
 
 ```json
 {
@@ -625,12 +719,12 @@ default to JSON schemas and schema-key metadata.
     {
       "name": "get_ticket",
       "address": "tickets.get_ticket",
-      "connectorTitle": "Tickets",
       "classification": "read",
       "schemaFormat": "json",
       "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }
     }
   ],
+  "connectors": { "tickets": { "title": "Tickets", "guide": "connector:tickets", "guideSummary": "Ticket ids and states." } },
   "total": 1,
   "offset": 0,
   "limit": 8,
@@ -650,8 +744,26 @@ and connector id, never connector-supplied error text. Other failures retain
 `retryAfterMs`. A scoped search also keeps its bounded failure subset under
 `queryAnalysis.catalogError` for clients that already use it.
 
-Tool rows carry the address, configured display title when present, guide and
-guide summary when available, and stored classification. Requested schemas have
+An unscoped search gives each connector at most 5 seconds (or
+`discovery.probeTimeoutMs` when shorter) and ends within a 9-second discovery
+budget. A connector that recently timed out or failed slowly is skipped for up
+to 60 seconds: its entry keeps the recorded code with `retryable: true`,
+`retryAfterMs`, and the message `Connector "X" was skipped because its catalog
+lookup failed recently (CODE). Search with connector "X" to try it now.` A
+scoped search always probes. Records are kept per owner, admitted endpoint and
+described connector configuration. A healthy connector whose catalog always
+takes more than 5 seconds can stay out of unscoped search; search it with
+`connector`, or let any longer-deadline operation warm its complete catalog.
+See [Discovery health](./architecture.md#storage-credentials-and-connectors).
+
+Tool rows carry the address, stored classification, and tool-specific
+`guideRequired` and `guideRequiredReasons`. Facts shared by every row of one
+connector appear once per page in `connectors`, keyed by the connector id that
+prefixes each row's address: the configured display `title` when present and
+`guide` and `guideSummary` when the connector has a guide. The map names only
+connectors with a row or ready call on this page and is omitted when none has
+such facts.
+Requested schemas have
 `schemaFormat: "json"` for JSON Schema values or `schemaFormat: "text"` for
 compact schema strings and TypeScript signatures. Compact schemas are text;
 `inputSchema.properties` is meaningful only in JSON mode. Pagination counts
@@ -664,7 +776,19 @@ rare domain terms above ubiquitous action terms. Exact tool names and canonical
 addresses rank first, so `get_issue` beats `get_issue_status` even when a
 connector is named `issue`. Exact configured connector IDs, full display titles,
 and recognized service names rank next. Complete lexical matches then precede
-partial matches, with score and catalog order breaking ties.
+partial matches. Within a tier, a query whose first word outside connector names
+is `list`, `get`, `find`, `search`, `show`, `read`, `fetch`, or `count` ranks
+read rows before write rows; writes stay on the page. Score and catalog order
+break the remaining ties.
+
+A maintained provider may declare `searchSynonyms`: groups of single lowercase
+words its users and its vendor use for the same record, such as `household`
+and `family` for Church Community Builder. A query word then matches that
+provider's tools and operation vocabulary through any word in its group, as an
+ordinary whole-token match ranked below the word itself. Synonyms never widen
+another connector's matches. Church Community Builder declares
+`person`/`individual` and `household`/`family`; Granola declares
+`meeting`/`note`.
 An exact connector ID or title query browses that connector's tools, even when
 individual tool names or descriptions mention that identity. Connector identity
 terms that never occur in its tools need not be repeated in every tool description.
@@ -1025,28 +1149,77 @@ A remote MCP tool's advertised `inputSchema` is checked in the shared invocation
 path before admission and provider dispatch, so a mismatch is the non-retryable
 `invalid_args` identically on `call_tool`, `call_destructive_tool`,
 generated-code failures, and rejected promises. The error names the connector and
-operation and carries `validation.issues`: JSON Pointer `path`, schema-keyword
-`code`, and expected shape, with submitted values never copied into a finding. At
-most three are returned, and `validation.truncated` says when more exist — the
-same three-item bound describe's nearby-address list uses.
+operation and carries one recovery envelope, `validation`:
+
+```json
+{
+  "issues": [
+    { "path": "/limit", "expected": "at least 5", "received": "4" },
+    { "path": "/mode", "expected": "one of \"fast\", \"safe\"", "received": "string" },
+    { "path": "/<key>", "expected": "one of the accepted keys: mode, limit" }
+  ],
+  "acceptedKeys": ["mode", "limit"],
+  "example": { "mode": "fast", "limit": 5 }
+}
+```
+
+Every finding is listed, and the message repeats them, so one corrected call
+fixes them all.
+
+A refusal contains only names and literals the published schema declares at
+non-sensitive positions, numbers allowed by the bound rule below, and fixed
+placeholder text. It never contains a submitted string or object key, in the
+message, a finding, `acceptedKeys` or the example. A position is sensitive when
+it or an ancestor is `writeOnly`; a named tool's input schema marks each request
+secret that way. API hatch findings name only the operation contract's
+properties and enum members, as `*_api_details` publishes them.
+
+- `path` is a JSON Pointer naming declared properties and array indices. The
+  first key the schema does not declare (a misspelled argument, a map key)
+  reads `<key>` and ends the path, e.g. `/headers/<key>`.
+- `expected` states the constraint that failed, then every other constraint
+  the position declares: bounds, property and item counts, `multipleOf`,
+  `pattern`, `format`, `uniqueItems`, enum members, `dependentRequired`
+  (`string (required with tags)`). A sensitive position never renders an enum,
+  `const` or pattern literal. Each position gets one finding.
+- `received` is the submitted JSON type, `missing`, or, for a numeric bound at
+  a non-sensitive position of a named tool, the submitted number.
+
+At most eight findings are returned, each field clipped (path and expected 256
+characters, received 64), and `truncated: true` says something was omitted or
+clipped.
+
+`example` is one valid call synthesized from the published schema and checked
+against the same validator. It never copies a submitted value, and a sensitive
+position never renders a schema literal (`enum`, `const`, `default`,
+`examples`). Complex or unsatisfiable schemas get `exampleUnavailable` instead.
+Synthesis detects recursive references and shares a 128-node work budget.
+Invocation uses only this schema example, never a connector's copy of the
+call, unless the connector states `exampleUnavailable`. API hatches
+(`*_api_read`, `*_api_write`) always do: their generic schema says nothing
+about an operation's arguments, so the reason points to the operation's
+`*_api_details`.
+
+`acceptedKeys` names the tool's top-level arguments. `conditionalRequirements`
+lists known `dependentRequired` and `dependentSchemas` requirements by
+property name; `if`/`then`/`else` conditions are schema subtrees and are not
+rendered. The envelope has a 4 KiB budget:
+optional detail, then the example, then trailing findings are dropped whole,
+with `truncated: true`. A `repair` object a custom connector passes contributes
+its received types and schema facts. A custom connector's own findings must
+follow the same rule. Operator records contain only checked failure facts,
+never findings or examples.
 
 `nextAction` points to discovery scoped to the same connector and tool name when
 the compact schema is needed, routed like any other miss: a program to
 `connecta.search`, a top-level call to `search_tools`. `retry` says to correct
-the listed arguments and reissue the original operation. Which keyword a finding
-names, and what the local validator declines to evaluate, is
-[code mode](./code-mode.md#errors)'s `E8`.
-
-`repair` adds agent-only detail from that tool's published schema: accepted
-keys, received JSON types, enum values, numeric/length/item bounds, and known
-conditional requirements such as `dependentRequired` and `if`/`then`/`else`.
-Its `example` is synthesized without submitted values and checked against the
-same validator. Complex or unsatisfiable schemas get `exampleUnavailable`
-rather than an invalid example. Synthesis detects recursive references and
-shares a 128-node work budget. Alternative branches do not emit dependency
-advice unless the branch condition is known. Repair detail has a 4 KiB budget; oversized
-detail is withheld whole with `truncated: true`. Operator records still contain
-only checked failure facts, never findings or examples.
+the listed arguments and reissue the original operation. What the local
+validator declines to evaluate is [code mode](./code-mode.md#errors)'s `E8`.
+
+Earlier releases returned `validation.issues[].code` (the schema keyword)
+and a separate `repair` object. Both are gone from responses; a custom
+connector may still pass `code` and `repair` to `ConnectorCallError`, which
+folds `repair` into `validation`.
 
 Unknown-address errors list `configuredConnectors` from the current endpoint's
 scoped registry, including an empty list when none are accessible. They never
@@ -1144,7 +1317,9 @@ its code and message for diagnostics but is `retryable: false` with
 a program's `writes.unknown`. An HTTP refusal of the call's own write stays
 known only under the refusal rules above and a complete ledger proving the
 refusal covers the whole call; its recovery advice and program accounting both
-report failure. Partial or unknown ledgers remain conservative. An auth failure after entering a write with
+report failure. A `remoteMcp()` write answered with a 4xx (other than 401, 403,
+408 or 429) whose body is not a JSON-RPC error is unknown, never a refusal: a
+gateway may have answered after the server acted. Partial or unknown ledgers remain conservative. An auth failure after entering a write with
 no call-owned dispatch reports an unknown outcome and requires reconciliation,
 including credential refusals, static-OAuth refresh failures, and `remoteMcp()`
 connect or initialize 401s before `tools/call`. A non-auth refusal before
@@ -1309,7 +1484,7 @@ window, a native `tools/list` carries a 300-second private cache hint, against
 an hour on meta endpoints. This hint does not guarantee that a host refreshes
 its cached annotations; the stale-approval race is accepted on writable pools.
 
-**Listing.** `tools/list` is one page with no cursor (Eve 0.84 reads only the
+**Listing.** `tools/list` is one page with no cursor (Eve 0.90 reads only the
 first page). A pool listing more than 1,000 tools fails `tools/list` with a
 JSON-RPC error asking the operator to narrow the pool; nothing is silently
 dropped. A connector whose catalog cannot load is left out of that listing
@@ -1326,7 +1501,8 @@ never repeat a write; page a truncated result as its notice says. A pool
 **Recovery.** Repair and validation fields retain the exact constraint details.
 Discovery `nextAction` points to the host's tool search (`host: "search"`), with
 only a `query` argument. Retry actions and retry text name the native tool,
-never a meta wrapper. Auth actions carry `authorizationUrl` or `operatorUrl`;
+never a meta wrapper; a program on a native pool sees the same native wording
+in a failure it catches. An unknown name is reported as sent. Auth actions carry `authorizationUrl` or `operatorUrl`;
 give the returned URL and instructions to the user or operator. Capable modern
 clients may resume native auth and downstream form/URL input with the same
 wire name, arguments and returned `requestState`. Changed names, targets or
@@ -1380,8 +1556,6 @@ listing, and call translation live in
 [search tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-search.test.ts),
 [call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
 [skills tests](https://github.com/zackbart/connecta/blob/main/test/skills-extension.test.ts),
-[native surface tests](https://github.com/zackbart/connecta/blob/main/test/native-tools.test.ts),
-[surface tests](https://github.com/zackbart/connecta/blob/main/test/code-first-surface.test.ts),
-and [pool description tests](https://github.com/zackbart/connecta/blob/main/test/pool-description.test.ts)
+and [native surface tests](https://github.com/zackbart/connecta/blob/main/test/native-tools.test.ts)
 check the published contract. Guest parity and clause evidence are in
 [code-mode verification](./code-mode.md#verification).