@zackbart/connecta 0.32.0 → 0.34.0

package/documentation/provider-auth-migration.md

@@ -2,17 +2,14 @@
 
 Use this upgrade guide when moving a Stripe, Notion, Vercel, or Cloudflare
 deployment from 0.30 to 0.31, where `auth` selects each provider's
-implementation ([#801](https://github.com/zackbart/connecta/issues/801)).
-The [0.31.0 release notes](https://github.com/zackbart/connecta/blob/main/release-notes/0.31.0.md) summarize the change.
+implementation.
 [Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
 version changes; [integrating services](./integrating.md) covers new connectors.
 
 A dual provider requires `auth`. `{ type: "oauth" }` connects the vendor's
 hosted MCP server, OAuth only. A key type connects Connecta's REST connector
 with an operator-managed credential. There is no default, and one connector id
-uses one implementation: configure two ids for both. The
-[decision record](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
-explains why.
+uses one implementation: configure two ids for both.
 
 ## Stripe
 
@@ -62,6 +59,10 @@ contracts: search finds operations in a pinned API index, every call is
 checked against that index before it is sent, results arrive as
 `{ status, data, page? }`, and POST writes send the caller's `idempotencyKey`
 or a generated one as `Idempotency-Key` and return it (DELETE sends none).
+Caller-supplied keys may contain up to 255 characters. An ambiguous POST write
+also returns the key in `uncertainCall.recovery.idempotencyKey`, including when
+the call deadline interrupts it. See [argument recovery](./meta-tools.md#argument-recovery)
+before retrying.
 Every request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the
 version of the pinned index, whatever the account's default API version, so
 response shapes and accepted parameters follow that version. Check fields
@@ -73,9 +74,7 @@ A key whose `sk_live_`/`rk_live_` or `sk_test_`/`rk_test_` prefix contradicts
 Lost on the key path: natural-language Sigma (`stripe_analytics`), metrics,
 documentation search, the implementation planner, reports, and feedback exist
 only on the hosted OAuth connection. Programs calling those tools on a key
-connector need an OAuth connector beside it. The
-[Stripe skill](https://github.com/zackbart/connecta/blob/main/src/providers/stripe/SKILL.md)
-owns the conventions for both.
+connector need an OAuth connector beside it. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Notion
 
@@ -101,6 +100,15 @@ connectors: [
 | `integration_list_comments`, `integration_add_comment`                                                                                    | `notion_api_read` `GET /v1/comments`; `notion_api_write` `POST /v1/comments`.                                        |
 | `integration_update_page_properties`, `integration_trash_page`                                                                            | `notion_api_write` `PATCH /v1/pages/{page_id}` with `properties`, or `in_trash` to trash or restore.                 |
 
+Both auth variants accept optional `callAdmission`. On a token connector it
+replaces the whole default policy of 180 calls per minute and 3 concurrent
+per runtime. Malformed policies throw at construction. 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, with a separate workspace-wide limit shared by all connections.
+Account for other runtimes and tools that make multiple HTTP requests when
+choosing an override.
+
 The token connector gains Connecta's generic REST tools over Notion's pinned
 API index (`notion_api_search`, `notion_api_details`, `notion_api_read`,
 `notion_api_write`), so every public operation is reachable with the bot's
@@ -119,8 +127,7 @@ duplication, team and skill search, attachment downloads, or page-to-skill
 conversion. An OAuth connector acts as the user, and has none of the generic
 REST tools or the `integration_*` projections and authoring helpers. Configure
 both ids when a deployment needs both; a failed call is never retried on the
-other. The [Notion skill](https://github.com/zackbart/connecta/blob/main/src/providers/notion/SKILL.md)
-owns the conventions for both.
+other. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Vercel
 
@@ -156,7 +163,7 @@ variable tools (`list_project_env_vars`, `upsert_project_env_var`,
 (the runtime stream, stopped after `waitMs` or `maxRows`), and
 `vercel_api_upload`.
 
-Value safety follows a reviewed table (`src/providers/vercel/value-safety.ts`).
+Value safety follows a reviewed table bundled with the connector.
 Every operation whose response schema in the pinned spec may carry a credential
 or a stored secret has a verdict: refused (credential minting, Connect
 authorization, decrypted environment values, Global Config items and tokens,
@@ -186,9 +193,7 @@ The hosted connection now lists `filter_project_envs`, `get_project_env`,
 return decrypted values, so they are reviewed as writes, and a `readOnly`
 endpoint refuses them. Vercel admits only reviewed and approved MCP clients to its
 hosted server; if authorization is refused for that reason, the deployment
-needs Vercel's approval or a token connector. The
-[Vercel skill](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/SKILL.md)
-owns the conventions for both.
+needs Vercel's approval or a token connector. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Cloudflare
 
@@ -254,9 +259,7 @@ Lost on each path. OAuth has no index validation, named tools, GraphQL tool,
 upload tool, or pin; Cloudflare's OAuth grant is the only boundary. A key has
 no hosted `search` over Cloudflare's live OpenAPI document; the pinned index
 replaces it and `providers:check` reports when it falls behind. A Global API
-Key cannot reach R2, which accepts API tokens only. The
-[Cloudflare skill](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/SKILL.md)
-owns the conventions for both.
+Key cannot reach R2, which accepts API tokens only. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Value safety on every key connector
 
@@ -289,12 +292,16 @@ one; read or rotate withheld secrets in the vendor's dashboard.
   Failures of credential-bearing operations keep Stripe's type, code, and
   param but not its message. Create client-side sessions and links from your
   own server code.
-- **Notion** results withhold the signature, credential, and security-token
-  parameters of pre-signed file URLs, so a returned file URL no longer
-  downloads; credential-named fields, including database properties named
-  like credentials, read as `"[redacted]"`. Failures of the OAuth, file
-  upload, bot user, and agent operations keep Notion's code but not its
-  message.
+- **Notion** REST results and error text withhold the whole query and
+  fragment of canonical Notion file links, including links embedded in
+  Markdown and async task results. External proxy URLs keep their bytes;
+  AWS and Google signing-parameter values are withheld at any host. Writes
+  carrying the plain or encoded `[redacted]` placeholder in a Notion file
+  link's own query or fragment are refused before dispatch. See the
+  connector runtime guide through `connecta.skill("connector:<id>")` in `execute_code` for recognized hosts and scanning limits. Credential-named fields,
+  including database properties named like credentials, read as
+  `"[redacted]"`. Failures of the OAuth, file upload, bot user, and agent
+  operations keep Notion's code but not its message.
 - **Vercel** replaces environment values with `"[redacted]"` instead of
   dropping the field, and withholds Vercel's error text for every reviewed
   operation and every operation whose request takes a credential-named
@@ -306,3 +313,10 @@ one; read or rotate withheld secrets in the vendor's dashboard.
   destinations to their scheme and host. A credential-named field now loses
   its whole value, not only its strings (a `cookies` list, a variable named
   `API_KEY`).
+
+## Contributor reference
+
+[Decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
+explains why auth selects the implementation. Maintained provider source
+skills and review tables live under `src/providers/` in the repository;
+`src/providers/vercel/value-safety.ts` owns Vercel's reviewed table.

package/documentation/provider-migration-0.29.md

@@ -7,8 +7,8 @@ version changes; [integrating services](./integrating.md) covers new connectors.
 
 This is the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709).
 Deploy it with the consolidated 0.29 release, not while the rework is in progress.
-BePresent and One&Many use Notion and Cloudflare; their actual grants and
-connector ids must be checked in deployment configuration before that release.
+Deployments that use Notion or Cloudflare must check their actual grants and
+connector ids in deployment configuration before that release.
 The provider audit establishes available auth modes, not production OAuth grants.
 
 Cloudflare's part of this guide is superseded: `cloudflare()` now selects its

package/examples/worker/AGENTS.md

@@ -2,6 +2,12 @@
 
 This repository is deployment configuration, not a copy of Connecta itself.
 
+Start every operator task at
+`node_modules/@zackbart/connecta/documentation/README.md#operator-tasks`.
+That installed index routes adding/removing connectors, organizing agent pools,
+adding people, connecting shared credentials, issuing/rotating/revoking agent
+tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
+
 - Edit `src/connecta.config.ts` for connectors, authentication, storage, public
   URL, and optional modules. `src/index.ts` only starts it. Set plain vars
   `CONNECTA_ACTIVITY="on"` for preserved activity.
@@ -9,8 +15,8 @@ This repository is deployment configuration, not a copy of Connecta itself.
   always installed over the same `CONNECTA_DB` for machines. Cloudflare Access
   admits the request before the Worker runs; a service identity alone is
   refused inside connecta. Do not add JWT parsing or another identity gate.
-  Grant `identity.accessTokenManagement` explicitly to interactive operators;
-  this example permits every signed-in human to manage connectors and tokens.
+  Signed-in maintainers alone manage shared credentials and agent tokens; pool
+  members connect only their own accounts on personal connectors in their pools.
 - Attach Access to the Worker itself, not only its hostname. Enable Managed
   OAuth on that Access application. CIMD is the spec's preferred client
   registration; enable DCR as the fallback Access currently requires.
@@ -57,21 +63,43 @@ This repository is deployment configuration, not a copy of Connecta itself.
   Do not copy or modify Connecta package internals here.
 - Prefer `api()` when the agent must see an exact reviewed capability set;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
-- Unattended clients and `connecta doctor` need Access service credentials
-  plus a stored `cta_` bearer. Set `CF_ACCESS_CLIENT_ID`,
-  `CF_ACCESS_CLIENT_SECRET`, and `CONNECTA_TOKEN` together for doctor.
-  Bootstrap tokens through the Access-authenticated operator page or trusted
-  `AccessTokenManager.create` tooling against this same D1 storage, as README
+- Agents (unattended clients) use `<PUBLIC_URL>/agent/<pool>` with a stored
+  `cta_` bearer as their only credential. That needs one self-hosted Access
+  application per hostname for `<host>/agent/*` with a single Bypass policy,
+  beside the Worker-level application (README.md § "Let agents through
+  Access"). Never bypass any other path. `/mcp` and `/mcp/<pool>` refuse `cta_`.
+  `connecta doctor` also reads `/health` behind Access: set
+  `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET`, and `CONNECTA_TOKEN`
+  together, and pass `--pool ci`, a pool that lists the agent.
+  Machine clients are the `agents` declared in `src/connecta.config.ts`. Issue
+  or rotate a token through the operator Tokens page as a signed-in maintainer or trusted
+  `AccessTokenManager.rotate` tooling against this same D1 storage, as README
   "Machine tokens" describes. Never configure a static bearer or open startup.
   UI, vault, and activity use explicit optional imports;
-  auth changes require code-derived shared or personal management permissions.
+  auth changes require a maintainer, or a pool member for their own personal account.
+- Organize agent pools by connecta's agent pool layout:
+  `node_modules/@zackbart/connecta/documentation/auth.md#organizing-an-agents-pools`
+  ([online](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#organizing-an-agents-pools)).
+  Each agent keeps one Connecta connection whose harness, never the model,
+  picks the pool per turn. Tiers are nested pools of shared connectors with
+  no `owner`, each spreading the tool list below. Recommended names are
+  `<agent>` for the lowest and `<agent>-<tier>` above it; any named pool,
+  including an existing `team` or `leadership` pool, may be a tier if all its
+  human members are cleared for it. A chat gets the most capable tier everyone
+  present is cleared for, and the lowest when anyone present is unknown.
+  `<agent>-<user>` (that user's highest tier plus their own connector ids,
+  `owner` set to their Workspace address) is used only in a one-on-one with
+  that user. List only cleared people in a tier, and never another person in
+  a `<agent>-<user>` pool: its per-user connectors act as that user for every
+  member. Never add a second Connecta connection or mount downstream tools
+  directly.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
   rather than leaving the default. README "UI and encrypted credentials" shows
   the shape.
 - After configuration changes, typecheck: inside the connecta repository that
-  is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
+  is `pnpm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
   complete their browser authorization flows before calling setup complete.
 

package/examples/worker/README.md

@@ -11,7 +11,8 @@ A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
 API connector, guarded by Cloudflare Access. It uses three Cloudflare resources
 and nothing else: one D1 database (`CONNECTA_DB`) for every piece of state, the
 Worker Loader binding (`LOADER`) behind the six-tool surface, which requires
-the Workers Paid plan, and one secret (`CREDENTIAL_ENCRYPTION_KEY`).
+the Workers Paid plan, and two secrets: `DOWNSTREAM_TOKEN` (the example remote
+MCP connector's token) and `CREDENTIAL_ENCRYPTION_KEY` (the credential vault).
 
 This is also the **starting template for a deployment**: a real deployment
 should be its own repository that pins an exact `@zackbart/connecta` version and
@@ -46,9 +47,11 @@ This example has no `package.json` of its own — it resolves the installed
 package from the repository root.
 
 ```sh
-npm install                                    # from the package root
+pnpm install                                   # from the repository root
 
 wrangler d1 create connecta                    # paste the id into wrangler.jsonc
+# In wrangler.jsonc also set PUBLIC_URL to this Worker's URL and
+# CONNECTA_MAINTAINERS to your Access user ids (user_uuid, else email).
 
 cd examples/worker
 wrangler secret put DOWNSTREAM_TOKEN
@@ -81,10 +84,10 @@ attempt and add the narrowest matching entry rather than allowing its entire
 origin.
 
 Access then serves OAuth discovery and turns the client's opaque token into the
-trusted human `ctx.access` identity connecta reads. A cron job or CI client
-needs Access service headers to cross the edge and a stored `cta_` bearer to
-authenticate inside connecta. An Access service identity alone is refused.
-See [Machine tokens](#machine-tokens).
+trusted human `ctx.access` identity connecta reads. A cron job or CI client is
+an agent: it uses `/agent/<pool>` with a stored `cta_` bearer as its only
+credential, once [the agent bypass](#let-agents-through-access) exists. An
+Access service identity alone is refused. See [Machine tokens](#machine-tokens).
 
 Through the API, the relevant part of the application is:
 
@@ -112,8 +115,36 @@ owns client registration, redirect allowlists, and token lifetimes.
 working in a copied deployment. Do not remove the entries there when changing
 the Access policy or application.
 
+### Let agents through Access
+
+Add one more self-hosted Access application for each hostname agents use (the
+`workers.dev` hostname and each custom domain): domain set to that hostname,
+path `agent/*`, and a single policy whose action is **Bypass** and whose include
+rule is **Everyone**. Keep the Worker-level application; it still protects every
+other path. 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": {} }] }]
+}
+```
+
+It must be a hostname-and-path (`public`) destination: a second Worker
+destination is refused because the Worker-level application owns it. Changes
+took 15–19 seconds to settle when probed, occasionally longer, with transient
+edge errors meanwhile. Do not rely on a fixed wait: verify that `/agent/ci`
+without credentials returns connecta's 401 (`WWW-Authenticate: Bearer`) while
+`/mcp` still returns Access's refusal, several times in a row. Connecta ignores Access
+context on `/agent/*` and refuses every other spelling of that namespace before
+auth. [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#agent-endpoints-behind-cloudflare-access)
+records the untested cases and the propagation details.
+
 The checked-in `access.dev` block gives `wrangler dev` a local operator
-identity. Remove the block to test the missing-Access refusal. It has no effect
+identity; it requires Wrangler 4.123.0 or later, and earlier versions ignore it
+with an unexpected-field warning. Remove the block to test the missing-Access refusal. It has no effect
 on a deployed Worker's production identity.
 
 ### Optional resource management with Alchemy
@@ -201,12 +232,34 @@ Access adoption or preserve production identity.
 
 ### Copied into its own repository
 
-The `npm install` above is the connecta repository's, which already has every
+The `pnpm install` above is the connecta repository's, which already has every
 dependency this file imports. A copy with its own `package.json` installs
 Connecta and the separately installed `@cloudflare/codemode` peer:
 
 ```sh
-npm install @zackbart/connecta @cloudflare/codemode
+npm install --save-exact @zackbart/connecta@<version>
+npm install @cloudflare/codemode
+npm install --save-dev wrangler @cloudflare/workers-types typescript @types/node
+```
+
+A `tsconfig.json` like the following lets `tsc --noEmit` resolve `D1Database`,
+`WorkerLoader`, and `ExecutionContext`. `wrangler` also serves
+`scripts/copy-kv-to-d1.mjs`.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types", "node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}
 ```
 
 `@cloudflare/codemode` is the optional peer behind `execute_code`, declared in
@@ -219,57 +272,63 @@ discover the skew in production ([#376](https://github.com/zackbart/connecta/iss
 no Clerk import, secret, package, or fallback provider. Docker deployments keep
 the Clerk path in the Node template.
 
-Then point an MCP client at `<PUBLIC_URL>/mcp`. The example explicitly enables
-`ui: operatorUi()`; open `<PUBLIC_URL>/` for Connections and each connection's
-authentication controls. The page labels tool safety, offers fixed repair
+Then list the maintainers' Access user ids (`user_uuid`, else email) in the
+`CONNECTA_MAINTAINERS` var and point a maintainer's MCP client at
+`<PUBLIC_URL>/mcp`. Other people use `<PUBLIC_URL>/mcp/<pool>`, and agents
+`<PUBLIC_URL>/agent/<pool>`, for a pool that lists them in `members`. The example explicitly enables
+`ui: operatorUi()`; open `<PUBLIC_URL>/` for endpoints, and each connector's Connection tab
+(`/connectors/<id>`) for its authentication controls. The page labels tool safety, offers fixed repair
 prompts for classified failures, and shows client setup commands for endpoints
 the signed-in person may use. Those commands contain no token. There is no
-separate Credentials tab. The Access tokens page is available to permitted
-interactive operators.
+separate Credentials tab. The Tokens page, listing one token slot per
+declared agent, is available to signed-in maintainers.
 
 ## Select optional modules
 
 `cloudflareAccessAuth()` reads trusted identity after Access admits the Worker
-request. Humans may use their code-derived connector view and operator pages.
-Machines authenticate with `accessTokens(storage)` over the same D1 database;
-Access service headers alone never grant MCP access or interactive authority.
+request. Maintainers use plain `/mcp` and the operator pages; people in a pool
+use `/mcp/<pool>`, and agents in it `/agent/<pool>`, which serve exactly that
+pool's tools. Agents authenticate with `accessTokens(storage)` over the same D1
+database; human endpoints refuse their tokens, and Access service headers alone
+never grant MCP access or interactive authority.
 Keep users, groups, and admission in Access. Connector visibility and management
 permissions belong in `src/connecta.config.ts`.
 
-`identity.connectorAccess` selects discoverable and callable connectors.
-`credentialAdministration` separately allows shared credential and OAuth
-management, while `personalConnection` allows a human to connect their own
-account. Both management permissions default to none. Grant the intended
-owner's shared permissions explicitly, and grant users personal permissions
-only for connectors configured with `authScope: "personal"`. Static headers
-remain deployment configuration. `activityAccess` governs global history reads.
-`accessTokenManagement` separately allows interactive operators to create, rename,
-and revoke machine tokens. This example grants that permission to every signed-in
-human, matching its connector-management permissions; narrow all three for a team.
+`maintainers` and each pool's `members` select who reaches which endpoint and
+who manages what. Signed-in maintainers alone administer shared credentials
+and OAuth grants, issue, rotate, and revoke agent tokens, and read activity.
+A pool member connects their own account only on connectors configured with
+`authScope: "personal"` in their pools. Static headers remain deployment
+configuration.
 See [inbound identity](../../documentation/auth.md#principals-visibility-and-operators).
 
 ### Machine tokens
 
-`accessTokens(storage)` is always installed over `CONNECTA_DB`, with no new
-binding. Empty token storage admits no machine client. A human authenticated
-through Access can still sign in and bootstrap the first token. Open
-`<PUBLIC_URL>/`, select Access tokens, and create a named token. Save the
-returned `cta_` secret privately; it is returned once. UI-issued tokens retain
-the issuing human's principal, while connector and pool rules are evaluated
-on every request. They never grant interactive operator authority.
-
-A machine sends all three headers:
+Machine clients are agents declared by name in `agents` in
+`src/connecta.config.ts`; this example declares `ci`. Each agent has one
+`cta_` token held by `accessTokens(storage)` over `CONNECTA_DB`, with no new
+binding. An agent with no issued token admits nothing. A maintainer (an Access
+identity listed in `CONNECTA_MAINTAINERS`) signs in and issues the first token.
+Open `<PUBLIC_URL>/`, select Tokens, and issue the agent's token. Save the
+returned `cta_` secret privately; it is returned once. Rotating replaces it
+immediately: the old secret stops on its next request. An agent has no human
+principal, so personal connectors are absent for it; connector and pool rules
+recognize it by `identity.agent` on every request. It never has interactive
+operator authority. Removing a name from `agents` stops its token on the next
+request.
+
+An agent connects to `<PUBLIC_URL>/agent/<pool>` for a pool that lists it and
+sends one header:
 
 ```text
-CF-Access-Client-Id: <access-service-client-id>
-CF-Access-Client-Secret: <access-service-client-secret>
 Authorization: Bearer <stored-cta-token>
 ```
 
-Permit the service credentials in the Worker-level Access application's policy.
-The service headers admit the request at the edge; connecta verifies the bearer
-against D1. Neither credential works alone for machine access. Doctor uses
-the same three credentials; see [Client authentication and activity](#client-authentication-and-activity).
+[The agent bypass](#let-agents-through-access) lets the request past the edge;
+connecta verifies the bearer against D1 and ignores any Access context or
+headers there. `/mcp` and `/mcp/<pool>` refuse the token. Doctor also reads
+`/health`, which stays behind Access, so it needs Access service credentials
+too; see [Client authentication and activity](#client-authentication-and-activity).
 
 For programmatic bootstrap, trusted provisioning code that already holds this
 deployment's D1 binding can use the published API against that same storage:
@@ -278,16 +337,18 @@ deployment's D1 binding can use the published API against that same storage:
 import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
 import { d1Storage } from "@zackbart/connecta/d1";
 
-const manager = new AccessTokenManager(d1Storage(env.CONNECTA_DB));
-const { token } = await manager.create("ci-client", "trusted-provisioning");
+const manager = new AccessTokenManager(d1Storage(env.CONNECTA_DB), { agents: ["ci"] });
+const { token } = await manager.rotate("ci", "trusted-provisioning");
 // Deliver token once to the client's secret store, outside logs and source control.
 ```
 
-This creates a token without a human principal. The name is a label, never a
-grant. Provision only through trusted operator tooling; do not expose this
-code as a public route or mint a token at startup. Existing unrevoked `cta_`
-tokens survive a state migration into this same D1 namespace. Keep
-`accessTokens(storage)` configured and preserve the identity and pool rules.
+Provision only through trusted operator tooling; do not expose this code as a
+public route or rotate a token at startup. Tokens issued before agents survive a
+state migration into this same D1 namespace but stop admitting until trusted
+tooling binds each machine's token once with
+`manager.adopt(tokenId, "ci")`, which keeps its secret working. Human-bound
+tokens cannot be adopted; issue the agent a new token instead. Keep
+`accessTokens(storage)` configured over the same storage.
 
 ### UI and encrypted credentials
 
@@ -323,11 +384,13 @@ does not create credentials or permissions by itself.
 
 ### Client authentication and activity
 
-Interactive MCP clients use Access Managed OAuth. Machine clients need both
-Access service credentials and a stored `cta_` bearer, provisioned as described
-in [Machine tokens](#machine-tokens). `accessTokens(storage)` is always enabled,
-and the example grants token management to every interactive Access operator.
-Keep token, connector, and pool grants in deployment code.
+Interactive MCP clients use Access Managed OAuth. Agents send only a declared
+agent's `cta_` bearer to `/agent/<pool>`, issued as described in
+[Machine tokens](#machine-tokens). `accessTokens(storage)` is always
+enabled, and every signed-in maintainer manages agent tokens.
+Keep maintainers, pools, and their members in deployment code. An agent reaches
+only `/agent/<pool>` for a pool that lists it (the example's `ci` pool lists
+`agent:ci`); `/mcp` and `/mcp/<pool>` refuse its token.
 
 Activity uses `activityHistory({ store: d1ActivityStore(env.CONNECTA_DB) })`,
 with `activityHistory` from `@zackbart/connecta/activity` and `d1ActivityStore`
@@ -335,13 +398,15 @@ from `@zackbart/connecta/d1`. See [Activity history](#activity-history-optional)
 Omit the module and store wiring to record no history and show no Activity tab. Diagnostics remain independent; `logger: "silent"` suppresses
 them explicitly.
 
-Verify MCP health and the exact six tools with:
+Verify MCP health and the exact six tools with the following. Doctor reads
+`/health` through Access with the service credentials, then checks `/agent/ci`
+with the `cta_` token alone:
 
 ```sh
 CF_ACCESS_CLIENT_ID='REPLACE_WITH_ACCESS_CLIENT_ID' \
 CF_ACCESS_CLIENT_SECRET='REPLACE_WITH_ACCESS_CLIENT_SECRET' \
 CONNECTA_TOKEN='cta_REPLACE_WITH_STORED_SECRET' \
-connecta doctor --url "$PUBLIC_URL"
+npx connecta doctor --url https://connecta.example.workers.dev --pool ci
 ```
 
 Doctor reports the configured `DynamicWorkerExecutor`, not a presumed Node
@@ -400,7 +465,8 @@ CREATE TABLE IF NOT EXISTS connecta_kv (
 );
 CREATE INDEX IF NOT EXISTS connecta_kv_expiry ON connecta_kv (expires_at_ms);
 -- tool_call_activity: one row per completed call, keyset-paged on
--- (occurred_at_ms, id); see src/storage/sql.ts in the package.
+-- (occurred_at_ms, id); see
+-- https://github.com/zackbart/connecta/blob/main/src/storage/sql.ts
 ```
 
 ### Upgrading from 0.28
@@ -430,7 +496,7 @@ CREATE INDEX IF NOT EXISTS connecta_kv_expiry ON connecta_kv (expires_at_ms);
 - **Workers KV** (`CONNECTA_KV` and `cloudflare-kv.ts`). Workers KV is no longer
   supported: `createConnecta` refuses storage without `compareAndSet` at boot.
   Copy its state into D1 once, as described below, so OAuth grants, vault
-  credentials, and `cta_` access tokens keep working.
+  credentials, and `cta_` access token records carry over.
 
 #### Copying Workers KV state into D1
 
@@ -462,7 +528,7 @@ then `wrangler login` and check the prepared deployment with a dry run.
 1. Back up KV with a bulk export including values and expiration metadata.
    Export D1 with `wrangler d1 export <db> --remote --output before-cutover.sql`.
    Store backups securely and preserve the exact credential encryption key,
-   including One&Many's `CONNECTA_CREDENTIALS_KEY`.
+   whatever secret name the deployment stores it under.
 2. Block traffic using maintenance mode or turn the route off. Stop cron,
    queue consumers, scheduled jobs, and every other KV/D1 writer. Drain all
    in-flight requests, including OAuth callbacks and token refreshes.
@@ -488,8 +554,8 @@ then `wrangler login` and check the prepared deployment with a dry run.
    invalid entry or mismatch. Keep traffic and writers stopped until these
    counts are resolved. A verification pass does not rewrite copied entries.
 5. Deploy the D1 configuration with `wrangler deploy` while maintenance remains.
-   Run `connecta doctor` using Access service credentials plus a stored `cta_`
-   bearer through `CONNECTA_TOKEN`. Verify an existing
+   Run `connecta doctor --pool <pool>` using Access service credentials plus a
+   stored `cta_` bearer through `CONNECTA_TOKEN`. Verify an existing
    OAuth connector without re-consent, an existing `cta_` token, a connector
    using a vault credential, and prior activity in the Activity view. Run
    these controlled checks with other traffic and background writers blocked.