@zackbart/connecta 0.32.0 → 0.34.0

package/documentation/code-mode.md

@@ -80,7 +80,7 @@ and cleanup at budget exhaustion, cancellation, and deadlines; the wrapper only
 
 ## What an executor must implement
 
-The Promise provider/result seam lives in `src/types.ts`. Custom implementations
+The Promise provider/result seam is declared in the installed `dist/types.d.ts`. Custom implementations
 also need the lifecycle wrapper above; structural compatibility alone is insufficient.
 
 ```ts
@@ -481,9 +481,9 @@ argument to the configured endpoint. It never fetches that
 URI or creates a connector from it.
 
 Resources are protocol reads on read-only and writable endpoints alike. A read
-requires a grant to the whole connector through the endpoint/pool and identity
-intersection. Exact-tool grants, including guarded grants, authorize no
-resources. An absent, hidden, tool-restricted or resource-incapable connector
+requires the whole connector on the endpoint: plain `/mcp`, or a pool whose
+`tools` list the connector id. A pool listing only exact `connector.tool`
+addresses authorizes no resources. An absent, hidden, tool-restricted or resource-incapable connector
 fails with `unknown_address`. The URI and extra arguments cannot select a
 different credential owner or downstream subject. Personal credentials come
 from the admitted principal, just as they do for tool calls.
@@ -555,6 +555,15 @@ URL-elicitation hosts retain their existing flow.
 **E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program
 may do. A provider maps each downstream failure to the code that tells the
 caller what to do next, and never invents a cause it was not told.
+The table lists the codes a program commonly sees. Codes owned by one
+mechanism are specified with it: `resource_template_ambiguous` and
+`resource_match_budget_exceeded` with resource reads above; the
+`executor_*` admission codes in `E5`; `destructive_tool_requires_approval` with
+direct calls; and `input_required_invalid`, `input_required_limit`,
+`downstream_oauth_required`, `oauth_revocation_failed`,
+`provider_permission_denied`, and `auth_replay_refused` in
+[meta-tools](./meta-tools.md). Each of those is non-retryable except
+`executor_overloaded`.
 
 | Code                         | Raised when                                                                                                                                                                                           | `retryable`   |
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
@@ -577,6 +586,7 @@ caller what to do next, and never invents a cause it was not told.
 | `result_too_large`           | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
 | `budget_exceeded`            | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
 | `write_outcome_unknown`      | a program write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                       | false         |
+| `executor_failed`            | the executor returned a malformed result or failed outside the guest program                                                                                                                          | false         |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -685,6 +695,12 @@ when the metadata describes a write on a read-only endpoint.
 Caught call failures retain that connector visibility when catalog loading or
 tool resolution fails. Recovery messages listing configured connectors or
 local guides retain visibility of those contributors too.
+Search guidance retains its referenced connectors even when no tool matches,
+including connectors named by id or title and identities summarized as an
+additional count. Scoped guides and summaries, absence rosters, and catalog
+errors retain their contributing connectors as well.
+Search counts, ranking, and term analysis retain every searched connector,
+including matches outside the returned page or beyond the requested offset.
 Each page rechecks current auth,
 grants, pool membership, and the endpoint's `readOnly`. Reading a stash inside a program carries
 its dependencies forward to any new return stash. The page cap is the smallest
@@ -711,7 +727,7 @@ has no host log stream and cannot supply logs from its suspended guest (`L4`).
 
 **R6.** Every run returns `hostCalls: { attempted, admitted, succeeded, failed }`,
 including admission failure, cancellation, budget refusal, and code-size refusal.
-Calls include search, describe, call, result, and skill. `emit` has separate budgets.
+Calls include search, describe, call, read, result, and skill. `emit` has separate budgets.
 An abandoned host call counts as failed when the run ends; guest catches do not
 change the counts. These numbers are outside the program's returned `result`.
 `diagnostics: true` adds the existing payload-free timing block. Emitting adds
@@ -737,9 +753,6 @@ and nonzero pad bits are rejected before collection. Size budgets still apply.
 MCP-native output a return value cannot carry: base64 is not projectable, so a
 block that fits the inline call limit (`S5`, `L6`) can use the separate
 emission transport budget instead of the `R2` return guard.
-The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
-([#267](https://github.com/zackbart/connecta/issues/267),
-[#270](https://github.com/zackbart/connecta/issues/270)).
 
 **M1.** `connecta.emit(result)` accepts a rich result from this program's
 `connecta.call` and forwards its original native content blocks, including
@@ -773,7 +786,8 @@ a successful result, appended to `content` after the JSON envelope, which gains
 response (`R6`). `structuredContent` stays the envelope alone — emission is
 presentation, not a second data channel.
 
-**M3.** Text emission shares `R2`'s 24,000 serialized-character cap. Its
+**M3.** Text emission shares `R2`'s 24,000 serialized-character cap, less 512
+characters reserved for the envelope (23,488 for emitted text). Its
 serialized block size reduces the return budget, and oversized text fails with
 `result_too_large`. Image/audio blocks use the separate transport budget and
 reach the model as real MCP media content, including when `emit` is not awaited.
@@ -861,7 +875,7 @@ Programs and direct calls use the same invocation deadline and stages. A call's
 `timeoutMs` wins, then `calls.defaultTimeoutMs`, then `execute.hostCallTimeoutMs`
 (default 15,000). A guest may request a longer individual call, but the sandbox
 and request ceilings still bound the whole run. Timeout details are agent-facing;
-INV-6 operator records retain only checked classifications and numeric facts.
+operator records retain only checked classifications and numeric facts.
 A dispatched write timeout becomes `write_outcome_unknown` and retains its
 deadline details even when the program catches the failure. The final program
 error includes the first timeout in `details`; multiple write timeouts also
@@ -884,7 +898,7 @@ because connecta enforces them above the sandbox:
 
 | Bound                                                                                   | Value                                                                                                        |
 | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Host calls per execution, shared by `search`, `describe`, `call`, and `read`            | 20 by default, `execute.maxHostCalls`                                                                        |
+| Host calls per execution, shared by every guest call except `emit`                      | 20 by default, `execute.maxHostCalls`                                                                        |
 | Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
 | Deadline per host call                                                                  | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
 | Discovery page                                                                          | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
@@ -894,8 +908,9 @@ because connecta enforces them above the sandbox:
 | Result                                                                                  | 24,000 serialized characters                                                                                 |
 | Logs presented to the model                                                             | 4,000 characters                                                                                             |
 
-Every `call`, `read`, `search`, and `describe` spends one host call on entry, before
-resolution, validation, or dispatch. Catching a local refusal refunds nothing.
+Every `call`, `read`, `search`, `describe`, `result`, and `skill` spends one host
+call on entry, before resolution, validation, or dispatch; automatic transfer
+pages of a paged result do not. Catching a local refusal refunds nothing.
 The first call beyond the budget ends the host run with one non-retryable
 `budget_exceeded` (`E2`). Its bridge stays pending until lease disposal so guest
 `try/catch` cannot swallow it. Later host access, including `emit`, stops; pending
@@ -1018,7 +1033,7 @@ createConnecta({
   connectors, executor,
   readOnly: false, // required: false writes, true refuses every write call
   pools: {
-    reporting: { tools: ["posthog"], readOnly: true, grant },
+    reporting: { tools: ["posthog"], readOnly: true, members: analysts },
   },
   classification: {
     posthog: { exec: "read" }, // only for a deployment with a read-only exec contract
@@ -1028,7 +1043,7 @@ createConnecta({
 ```
 
 The removed `trust` option, on the deployment or a pool, fails construction
-with a message naming `readOnly` (`INV-11`).
+with a message naming `readOnly`.
 
 The registry computes one `classifyTool` verdict on each request-scoped
 published catalog entry. It caches and persists only raw downstream facts.
@@ -1194,7 +1209,13 @@ brand check and reads only own string data descriptors for diagnostics; guest
 accessors, serialization hooks, and Proxy traps do not run. Other thrown objects
 receive a fixed description.
 
-## Verification
+## Contributor reference
+
+### Verification
+
+The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
+([#267](https://github.com/zackbart/connecta/issues/267),
+[#270](https://github.com/zackbart/connecta/issues/270)).
 
 `test/guest-contract-cases.ts` runs on QuickJS in `test/guest-api-contract-quickjs.node.test.ts`
 and on the Worker adapter with a real Miniflare Loader in `test/guest-api-contract.test.ts`.

package/documentation/deploying.md

@@ -27,20 +27,25 @@ path and pins the generated project's Connecta dependency to the CLI version:
 npx @zackbart/connecta init my-connecta
 cd my-connecta
 npm install
-npm run --silent provision-token -- "local-machine"
+npm run --silent rotate-token -- local-machine
 # Save the returned cta_ token privately. It is shown only once.
 npm start
 ```
 
-The client connects to `http://localhost:8787/mcp` with
-`Authorization: Bearer <returned-cta-token>`. The generated project always
-installs `accessTokens(storage)`. An empty database admits no MCP caller even
-though `/health` works. `CONNECTA_TOKEN` is only a client/doctor variable;
+The agent connects to its pool's agent endpoint,
+`http://localhost:8787/agent/local-machine`, with
+`Authorization: Bearer <returned-cta-token>`. People use `/mcp` and
+`/mcp/<pool>`, which refuse `cta_` tokens. Machine clients are the agents
+declared in `agents` in `src/connecta.config.ts`; the generated project declares
+`local-machine` and always installs `accessTokens(storage)`. An agent with no
+issued token admits no MCP caller even though `/health` works. Rotating with the
+same command replaces the token immediately. `CONNECTA_TOKEN` is only a client/doctor variable;
 it never configures server authentication. The local commands read the process
 environment and do not load `.env`; Docker Compose does.
 
-Edit `src/connecta.config.ts` for connectors, public URL, auth, identity rules,
-and optional modules. `src/index.ts` only constructs and starts the deployment.
+Edit `src/connecta.config.ts` for connectors, public URL, auth, maintainers,
+agents, pools, and optional modules. Lay out each agent's pools by
+[Organizing an agent's pools](./auth.md#organizing-an-agents-pools). `src/index.ts` only constructs and starts the deployment.
 Follow the [template README](../templates/node/README.md) for storage paths,
 backups, Docker provisioning, secrets, and optional modules. Run the deployment's
 `npm run typecheck` after configuration changes.
@@ -56,12 +61,74 @@ must be installed for the Worker executor.
 
 Attach Cloudflare Access to the Worker destination. Interactive MCP clients
 need Managed OAuth, Dynamic Client Registration, and the documented redirect
-allowlist. Machines need Access service headers at the edge plus a stored
-`cta_` bearer inside Connecta; service identity alone is refused. Keep
+allowlist. Machines are declared agents: they use `/agent/<pool>` with the
+agent's `cta_` bearer as their only credential, once the
+[agent bypass application](#agent-endpoints-behind-cloudflare-access) exists;
+Access service identity alone is refused. Keep
 `enable_request_signal`, construct Connecta once per isolate, and pass `ctx`
 through to `fetch`. The example owns those details and
 [the machine-token procedure](../examples/worker/README.md#machine-tokens).
 
+## Agent endpoints behind Cloudflare Access
+
+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:
+
+1. Keep the Worker-level application, whose destination is
+   `{ "type": "worker", "worker_id": "<the Worker script tag>" }`, exactly as
+   [Cloudflare Access on Workers](./auth.md#cloudflare-access-on-workers)
+   describes. It still protects every other path and supplies `ctx.access` to
+   human routes.
+2. For each hostname agents use (the `workers.dev` hostname, each Custom
+   Domain, each route host), add one more **self-hosted** Access application.
+   In the dashboard, set the domain to that hostname and the path to
+   `agent/*`. Give it a single policy whose action is **Bypass** and whose
+   include rule is **Everyone**. Through the API:
+
+   ```json
+   {
+     "type": "self_hosted",
+     "name": "connecta agents",
+     "destinations": [{ "type": "public", "uri": "connecta.example.com/agent/*" }],
+     "policies": [{ "name": "agents bypass", "decision": "bypass", "include": [{ "everyone": {} }] }]
+   }
+   ```
+
+   The more specific hostname-and-path application takes precedence over the
+   Worker-level one on matching paths only. Do not use a Worker destination
+   for it: a Worker destination belongs to one application, and a second one
+   is refused with 409 `destination belongs to another application`. For the
+   same reason a second hostname without Access is not an alternative.
+
+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>`
+   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.
+
+The bypass makes `/agent/*` reachable from the internet without Access.
+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
+recommended hardening that connecta does not yet do.
+
 ## Compose capabilities and access
 
 Both configurations use `defineConfig((env) => …)`, a required executor, and a required `readOnly` choice.
@@ -90,9 +157,13 @@ outside the database and source control, and preserve it across upgrades.
 existing-record migration.
 
 One deployment serves one tenant and may admit several people. Node uses Clerk
-for human auth; Access is Workers-only. Keep credential administration,
-personal connection, token management, and activity access explicit.
-[Auth](./auth.md#principals-visibility-and-operators) owns identity and grants;
+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
+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;
 [Clerk setup](./auth.md#clerk-oauth-tokens-and-operator-sessions) owns resource-bound
 tokens and `aud_claim_enabled`. A person's operator session is not an MCP token.
 
@@ -102,44 +173,74 @@ inherits that value unless it sets its own. A writable endpoint (`false`) allows
 writes through `call_destructive_tool` and programs and marks `execute_code` as
 a write; the client decides what to approve. A read-only endpoint (`true`) omits
 write tools from search and describe and refuses every write call; provider
-guides may still name those tools. Pool membership intersects
-the caller's grants; it never widens them. See [pools](./auth.md#pools) before
-changing `readOnly`.
+guides may still name those tools. A pool serves exactly its `tools` to its
+`members`. See [pools](./auth.md#pools) before changing `readOnly`.
 
 ## Verify and diagnose
 
-With the deployment running, replace the placeholder with its saved client
-token and run doctor:
+With the deployment running, replace the placeholder with its saved agent
+token and run doctor against a pool that lists the agent:
+
+```sh
+CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787 --pool local-machine
+```
+
+Doctor checks health, the required executor, and the current six-tool set. A
+`cta_` token is checked at `/agent/<pool>` and needs `--pool`.
+For a Worker protected by Access, `/health` still needs edge admission even
+though `/agent/*` bypasses Access. Use an Access service token admitted by the
+Worker-level policy for that check, alongside the agent token:
 
 ```sh
-CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787
+CF_ACCESS_CLIENT_ID='<access-service-id>' CF_ACCESS_CLIENT_SECRET='<access-service-secret>' CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url https://connecta.example.com --pool assistant
 ```
 
-Doctor checks health, the required executor, and the current six-tool set.
-For a Worker protected by Access, follow the example's doctor credentials
-and service-header setup. If the operator UI is enabled, authenticated
-`connecta doctor --config --url <public-url>` prints the caller-scoped
+The service headers admit the health probe at the edge; only the `cta_` token
+authenticates the agent endpoint inside Connecta. If the operator UI is enabled, maintainer-authenticated
+`connecta doctor --config --url <public-url>` (on Node, `CONNECTA_TOKEN` set to a
+maintainer's current Clerk session token issued for this deployment's origin;
+Clerk OAuth access tokens are refused here, and Access on Workers has no
+non-browser maintainer credential, so otherwise use the UI's Settings page) prints the caller-scoped
 configuration snapshot as JSON. It runs no diagnostic program and prints no
 raw HTTP failure body. [Operator UI](./operator-ui.md) describes the returned
-configuration, live facts, and permission rules.
+configuration, live facts, and permission rules. The config route is a human
+endpoint: an agent token cannot authenticate it.
 
 Health success alone does not prove a client can authenticate or reach an
 integration. Check client connection and a bounded read through a chosen
 connector; resolve credentials using [authorization recovery](./meta-tools.md#authorization-recovery).
 
+Use the failed check to choose the next step:
+
+| Symptom                             | Action                                                                                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Connection refused or timeout       | Check the public URL, listening process/port, proxy, and Worker deployment.                                                                      |
+| `/health` fails behind Access       | Check the Worker-level Access policy and the two service headers above. Do not broaden the agent bypass.                                         |
+| Executor check fails                | Retain `quickJsExecutor()` and its peer on Node, or `workerExecutor({ loader })`, the codemode peer, and `LOADER` on Workers.                    |
+| MCP 401                             | Check the saved token, declared agent, and slot state; rotated/revoked tokens refuse. Use `/agent/<pool>` with `--pool`.                         |
+| MCP 404                             | Check the pool name and `members: ["agent:assistant"]`; an existing but inaccessible pool is deliberately indistinguishable from a missing one.  |
+| Doctor passes but a connector fails | Discover its tools in that pool, check credential status/account ownership, and perform a bounded read. Doctor does not prove downstream access. |
+
+After a fix, repeat doctor with the same client credentials and pool. Never
+paste a token or raw downstream failure body into a committed diagnostic log.
+
 ## Upgrade an existing deployment
 
 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.
 
-- [Managed tokens from v0.23](./auth.md#managed-client-tokens-and-upgrading-from-v023) keep their secrets when storage, namespaces, and grants are retained. Replace the old boolean config with `accessTokens(storage)`; machine tokens gain no operator authority.
+- [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.
+- [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.
 - [Notion, Vercel, and Cloudflare for 0.29](./provider-migration-0.29.md) change defaults and retained API tool names.
 - [Executor wiring](./code-mode.md#deploy-time-capability) requires branded shipped executors or a self-managed custom executor.
 
-## Implementation and evidence
+## Contributor reference
+
+### Implementation and evidence
 
 Check the [CLI](https://github.com/zackbart/connecta/blob/main/bin/connecta.mjs),
 [Node configuration](../templates/node/src/connecta.config.ts), and

package/documentation/integrating.md

@@ -1,16 +1,65 @@
 # Integrating services
 
-Use this guide to add a connector to deployment configuration. To implement a
-new maintained provider in Connecta itself, follow the repository's
-[add-provider skill](https://github.com/zackbart/connecta/blob/main/.claude/skills/add-provider/SKILL.md)
-and [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
+Use this guide to change connectors in deployment configuration.
 [All agent routes](./README.md) are in the index.
 
+## Add or remove a connector
+
+Connectors are code-owned. Edit the deployment's `src/connecta.config.ts`;
+there is no install button or runtime registration API.
+
+To add one:
+
+1. Choose a maintained provider, `remoteMcp()`, or `api()` using the sections
+   below. Give it a unique, stable id such as `crm`; renaming an id selects
+   different stored credentials and changes every tool address.
+2. Put the constructed connector in `connectors`. Keep secrets in environment
+   variables or the encrypted vault. Choose shared or personal auth explicitly
+   for the intended audience; agents cannot see personal-auth connectors.
+3. Add the id (all its tools) or exact `id.tool` addresses to the intended
+   pools' `tools`. Maintainers at plain `/mcp` already see the whole catalog.
+   Follow [the agent pool layout](./auth.md#organizing-an-agents-pools) for an
+   agent: a shared connector goes in the tool list of the lowest tier whose
+   entire audience is authorized to use it (billing restricted to leads goes
+   in the leads tier); per-user connectors and Workspace connectors with a
+   mapping `subject` go only in personal pools.
+4. Run the deployment's `npm run typecheck` (Worker copies: `tsc --noEmit`),
+   restart Node or redeploy the Worker, and
+   [connect its credential](./auth.md#connect-a-shared-credential) if needed.
+   Run [doctor](./deploying.md#verify-and-diagnose), discover its tools from
+   the intended pool, and perform a bounded read. Check an excluded pool too.
+
+For example, merge this fragment into the existing configuration, retaining
+its storage, executor, auth, and `readOnly` settings:
+
+```ts
+import { remoteMcp } from "@zackbart/connecta";
+
+const crm = remoteMcp("crm", {
+  url: "https://crm.example.com/mcp",
+  authScope: "shared",
+  auth: { type: "credential", credential: { label: "CRM API token" } },
+});
+const base = ["crm", "tickets"]; // the agent's lowest tier
+// connectors: [crm, tickets], agents: ["assistant"],
+// pools: { assistant: { tools: base, members: ["agent:assistant"] } }
+```
+
+To remove `crm`, first disconnect its OAuth grant or delete its saved
+credential while the connector still exists, using a signed-in maintainer
+for shared auth. Each person disconnects their own personal account. Remove
+`crm` and all `crm.*` addresses from every pool (including tier tool lists),
+then remove its entry from `connectors`, unused imports, and unused secret
+configuration. Remove any pools left with no tools (empty `tools` fails
+construction), and update or retire clients pointing at those pools. Typecheck, restart/redeploy, run doctor, and confirm discovery
+and calls no longer find it. Removing configuration alone does not revoke a
+credential at the downstream service; revoke unused credentials there too.
+
 ## Choose a connector
 
 | Need                             | Configuration path                                | Check before using                                                                    |
 | -------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| A maintained integration         | Its `@zackbart/connecta/providers/<name>` factory | Provider `SKILL.md`, options, auth ownership, supported tools                         |
+| A maintained integration         | Its `@zackbart/connecta/providers/<name>` factory | Published factory declarations, auth ownership, supported tools                       |
 | Another hosted remote MCP server | `remoteMcp()` from the root package               | Endpoint, authentication, current catalog, and read/write annotations                 |
 | A selected HTTP API capability   | `api()` from the root package                     | Input/output schemas, explicit read/write hints, bounded handler, credential handling |
 
@@ -19,6 +68,14 @@ registry enforcement, caller grants, result bounds, and activity paths. There
 is no runtime installation or registration. Keep connector IDs unique and
 stable because they prefix canonical `<connectorId>.<toolName>` addresses.
 
+`callAdmission` is optional on `remoteMcp()`, `api()`, custom connectors, and
+provider variants that expose an override. Only omission or `undefined` uses
+the connector's documented default, which may be no admission. Every defined
+value is validated at construction. Malformed policies, including `false`,
+`null`, `0`, and `""`, throw before serving requests; they never disable
+admission or select a default. Custom connector policies are validated when
+the deployment constructs its registry.
+
 ## Maintained integrations
 
 Import a provider individually. For example, Linear requires an explicit
@@ -35,25 +92,26 @@ const tracker = linear("tracker", {
 ```
 
 Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from a Connecta `readOnly` endpoint. Read the
-[Linear skill](https://github.com/zackbart/connecta/blob/main/src/providers/linear/SKILL.md)
-and [factory options](https://github.com/zackbart/connecta/blob/main/src/providers/linear/index.ts)
-for API-key framing, workspace instructions, and admission choices.
-
-The [human README](../README.md#what-you-can-do-with-it) lists available
-integrations. Each [provider folder](https://github.com/zackbart/connecta/tree/main/src/providers)
-contains its scoped guide, options, tests, fixtures, and review data. Prefer
-that guide to general assumptions about a service's API. Google Workspace
+read scope. That is separate from a Connecta `readOnly` endpoint. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
+workspace instructions, and admission choices.
+
+The [human README](../README.md#what-you-can-connect) lists available
+integrations. In the installed package, `dist/providers/<name>/index.d.ts`
+and its imported declarations describe each factory's options. After adding
+a connector, use `search_tools` to discover its current tools and `connecta.skill("connector:<id>")` in `execute_code`
+to read its runtime guide; provider source skills are not installed files.
+Google Workspace
 providers require administrator-managed domain-wide delegation and a deployment
-mapping from admitted identity to the downstream account; a request must not
-choose its own account. Gmail never sends mail, and Drive never permanently
+mapping from admitted identity to the downstream account; an agent acts as its
+pool's `owner` instead ([auth guide](auth.md#pool-owners-for-google-workspace)).
+A request must not choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
 Wispr Flow uses OAuth only through `wisprFlow()` from
 `@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
 Notetaker content, with personal and work accounts holding separate data.
-Its [provider guide](https://github.com/zackbart/connecta/blob/main/src/providers/wispr-flow/SKILL.md)
-owns account access, search limits, transcript permissions and paging. The
+Its runtime guide, available through `connecta.skill("connector:<id>")` in `execute_code`, describes account access,
+search limits, transcript permissions and paging. The
 reviewed classification includes task writes listed in Claude's directory even
 though Wispr's public help describes read-only access; discover the account's
 actual tools before assuming those writes exist.
@@ -75,6 +133,16 @@ MCP clients to its hosted server, an operational gate outside Connecta. See the
 To use both implementations of one provider, configure two connector ids with
 independent credentials.
 
+Both Notion auth variants accept optional `callAdmission`. For a token
+connector it replaces the whole per-runtime default of 180 calls per minute
+and 3 concurrent. Notion's [request limits](https://developers.notion.com/reference/request-limits)
+allow 600 requests per minute per connection on Business and Enterprise and
+180 on other plans. A separate workspace-wide limit is shared by all
+connections. Size an override for other runtime traffic and tools that make
+multiple HTTP requests. Only an omitted or `undefined` policy selects the
+default; malformed policies, including `false`, `null`, `0`, and `""`, throw
+at construction on both auth variants.
+
 Planning Center's `excludeApps` removes whole products from a connection, for
 example `planningCenter("pco", { purpose, excludeApps: ["giving"] })` for a
 deployment that keeps agents away from donor and financial data. Excluded
@@ -130,8 +198,8 @@ const service = remoteMcp("service", {
   description: "Our team's hosted service",
   auth: { type: "credential" },
 });
-// Add service to connectors. Configure the vault and permitted operators
-// before supplying its credential through the operator UI.
+// Add service to connectors. Configure the vault; a signed-in maintainer
+// supplies its credential through the operator UI.
 ```
 
 Credential auth defaults to an `Authorization: Bearer` header. Choose framing
@@ -198,10 +266,10 @@ schemas when known; runtime observations cannot replace them.
 
 `authScope: "shared"` uses deployment-owned downstream auth; `"personal"` uses
 the admitted principal's partition. Visibility is a different decision,
-controlled by identity and pool grants. A personal connector must not close
+controlled by maintainers and pool membership. A personal connector must not close
 over a shared secret or derive its owner from arguments. Remote MCP refuses
 literal header credentials with personal scope. Review
-[principals and grants](./auth.md#principals-visibility-and-operators) and
+[maintainers and members](./auth.md#principals-visibility-and-operators) and
 [management permissions](./auth.md#management-permissions) before exposing a
 new integration or its authentication controls.
 
@@ -210,7 +278,13 @@ perform a bounded read. Add negative checks for target restrictions and writes
 when authoring a handler or provider. Follow repository verification policy
 when changing package code.
 
-## Implementation and evidence
+## Contributor reference
+
+### Implementation and evidence
+
+To implement a maintained provider in Connecta itself, follow the repository's
+[add-provider skill](https://github.com/zackbart/connecta/blob/main/.claude/skills/add-provider/SKILL.md)
+and [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
 
 Factory contracts live in [remote MCP](https://github.com/zackbart/connecta/blob/main/src/connectors/remote-mcp.ts),
 [API connector](https://github.com/zackbart/connecta/blob/main/src/connectors/api-connector.ts),