@zackbart/connecta 0.32.0 → 0.34.0

package/documentation/meta-tools.md

@@ -43,14 +43,14 @@ 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.
 
-| Tool                    | Arguments                                                                                                                           | Returns                                                                                                       |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `execute_code`          | `code`, `diagnostics?`                                                                                                              | `{ result?, error?, hostCalls }`, plus diagnostics when asked                                                 |
-| `search_tools`          | `query?`, `connector?`, `safety?`, `limit?`, `offset?`, `fullDescriptions?`, `includeSchemas?: "compact" \| "json" \| "typescript"` | `{ catalogErrors, tools, total, offset, limit, hasMore }`, plus `queryAnalysis` on a partial or failed search |
-| `call_tool`             | `address`, `args?`, `resultMode?: "mcp" \| "value"`, `timeoutMs?`, `diagnostics?`                                                   | the downstream result, bounded as [result representation](#result-representation) describes                   |
-| `call_destructive_tool` | the same, plus `reason?`                                                                                                            | the same                                                                                                      |
-| `authorize_connector`   | `connector`, `force?`                                                                                                               | the class-specific handoff in [authorization recovery](#authorization-recovery)                               |
-| `skills`                | `name?`                                                                                                                             | the listing when `name` is absent, that skill's markdown when it is present                                   |
+| Tool                    | Arguments                                                                                                                           | Returns                                                                                                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `execute_code`          | `code`, `diagnostics?`                                                                                                              | `{ result?, error?, hostCalls }`, plus `logs`, `emitted`, and `emittedDiscarded` when present and diagnostics when asked                                                                                                                               |
+| `search_tools`          | `query?`, `connector?`, `safety?`, `limit?`, `offset?`, `fullDescriptions?`, `includeSchemas?: "compact" \| "json" \| "typescript"` | `{ catalogErrors, tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remain, `absence` when the query names a service with no configured connector, and `queryAnalysis` on a partial, failed, unsearchable, or absent-service search |
+| `call_tool`             | `address`, `args?`, `resultMode?: "mcp" \| "value"`, `timeoutMs?`, `diagnostics?`                                                   | the downstream result, bounded as [result representation](#result-representation) describes                                                                                                                                                            |
+| `call_destructive_tool` | the same, plus `reason?`                                                                                                            | the same                                                                                                                                                                                                                                               |
+| `authorize_connector`   | `connector`, `force?`                                                                                                               | the class-specific handoff in [authorization recovery](#authorization-recovery)                                                                                                                                                                        |
+| `skills`                | `name?`                                                                                                                             | the listing when `name` is absent, that skill's markdown when it is present                                                                                                                                                                            |
 
 `limit` defaults to 8 and is capped at 100, as is one `connecta.describe` batch.
 `connecta.result`'s `offset` is a whole number of bytes ≥ 0 defaulting to 0 and
@@ -66,8 +66,8 @@ refuse a consequential call.
 
 `diagnostics: true` adds compact request-local timing and serialized-size
 aggregates for a caller measuring a workflow: a `diagnostics` block from
-`execute_code`, a `timing` block on a call response that is already structured
-(value mode, or a failure carrying recovery). Normal calls pay nothing for it,
+`execute_code`, a `timing` block on every structured call response: value-mode successes
+and every `{ ok: false }` failure. Normal calls pay nothing for it,
 and the measurements never contain program source, arguments, values, addresses,
 credentials, logs, or raw error text.
 
@@ -194,8 +194,7 @@ discovery made the same bet).
 ```
 
 It is something to read, not something that runs: programs stay JavaScript,
-and `execute_code` accepts no erasable TypeScript
-([decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)). The output half is the provider's declared
+and `execute_code` accepts no erasable TypeScript. The output half is the provider's declared
 schema, else an `S9` observation that opens with the
 `/* observed, not declared */` marker and keeps the `outputSchemaSource`
 field, else `unknown` — runtime evidence never reads as a contract, even when
@@ -222,7 +221,7 @@ declared schema exactly as they do for compact.
 A connector may attach a deployment-owned guide as markdown, keeping the
 original `usageGuide: string` configuration, or as
 `{ content, summary?, required? }` — which registers no connector and creates no
-shared runtime template. The registry prepends Agent Skills frontmatter to
+shared runtime template. The skills catalog prepends Agent Skills frontmatter to
 `content` and preserves the guide body, including its whitespace.
 `summary` is normalized and refuses construction over 120 characters; absent,
 Connecta derives the same bounded fallback the skills listing uses from the
@@ -254,14 +253,22 @@ A connector-scoped lexical miss keeps that connector's guide metadata under
 contains no endpoint vocabulary: a required guide stays discoverable instead of
 disappearing with the zero-tool page.
 
-Two built-in skills are byte-identical across deployments. `usage` says to read
-it at most once per task and owns program selection detail, examples, runtime
+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
 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. Connector
+client that never fetches a skill can still write a valid first program.
+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
+the model learns that endpoint's scope, for example
+`This endpoint: Team tier: shared tools only. For someone's own mail or files, ask them to message you one-on-one.`
+Plain `/mcp` never carries one. The description changes no tool or tool
+description, and `initialize` and `server/discover` stay `cacheScope: "private"`,
+so a client keeps what it learned per endpoint. Connector
 guides stay scoped to the deployment that listed them even when two deployments
 use identical content, and a deployment with no connector guides receives none of
 the short conditional guide pointers in its tool definitions.
@@ -282,7 +289,7 @@ is its slug; other IDs use `connector-` followed by a stable SHA-256 prefix.
 The suffix makes each
 document a valid Agent Skills file; the roots `skill://connecta/usage` and
 `skill://connecta/connectors/<connector-id>` also resolve. Provider guides are
-built from the generated `src/providers/*/SKILL.md` content with the existing
+built from maintained provider guides with the existing
 connection context and deployment instructions. Local manifests contain a
 SHA-256 digest and UTF-8 byte size of the complete document. `usage` and
 `investigate` remain compatibility names; `connector:<id>` remains a
@@ -387,7 +394,11 @@ including dependencies inherited from pages read during the run. Downstream skil
 resource content requires a whole-connector grant on every page. Local guides and catalog
 metadata require the contributing connector or tool to remain visible, including
 caught catalog-load errors, unknown-tool failures, and recovery messages that
-list visible connectors or local guides. Returns with no downstream calls still
+list visible connectors or local guides. No-match search guidance also retains
+the connectors it names or summarizes by count, including matches to connector
+titles; scoped guides and summaries, absence rosters, and catalog errors retain
+their contributors. Search counts, ranking, and term analysis also retain every
+searched connector, including matches outside the returned page. Returns with no downstream calls still
 require matching identity, origin and endpoint, current auth, and pool membership. A page must
 match those bindings and pass current auth, connector/tool grants, pool membership,
 and read-only checks. Old entries lacking bindings fail closed. A random UUID is a
@@ -395,7 +406,7 @@ handle, never an access grant.
 
 New entries store UTF-8 bytes in a base64 envelope split across storage keys,
 48 KiB of result text per chunk — widening past roughly 1.5 MB so no result
-occupies more than 33 keys, because every chunk is also a write. `connecta.result`
+occupies more than 32 keys, because every chunk is also a write. `connecta.result`
 reads and decodes only the chunks a page covers plus a few boundary bytes, so
 paging a 1.2 MB result costs the same per page as paging a 300 KB one; it
 neither encodes nor reads the whole result per page. Entries without the required identity and invocation bindings fail closed,
@@ -427,7 +438,7 @@ JSON; everything after the first newline is the preview. `structuredContent`
 is absent, so the notice cannot hide the preview in clients that prefer it:
 
 ```text
-{"truncated":true,"resultId":"…","totalBytes":161420,"hint":"This write already ran: do not call it again to see its result. Bytes 0-24000 of 161420 follow; page the rest with connecta.result using nextAction.","nextOffset":24000,"nextAction":{"tool":"execute_code","arguments":{"code":"async () => await connecta.result(\"…\", { offset: 24000 })"}}}
+{"truncated":true,"resultId":"…","totalBytes":161420,"hint":"This write already ran: do not call it again to see its result. Bytes 0-24000 of 161420 follow; page the rest with connecta.result using nextAction.","nextOffset":24000,"nextAction":{"tool":"execute_code","arguments":{"code":"async () => await connecta.result(\"…\", { offset: 24000, maxBytes: 3829 })"}}}
 {"ts":"2026-09-16T21:31:11.759Z","actor":"sam.ortiz@example.com",…
 ```
 
@@ -459,7 +470,7 @@ characters. One that rejects outright — Claude Code with
 `MAX_MCP_OUTPUT_TOKENS` set below 12,500 — needs a cap under twice its limit.
 
 The preview is the head of what `connecta.result` pages, cut on a character
-boundary, so `nextAction.arguments.offset` continues exactly where it stops. A
+boundary, so the `offset` in `nextAction.arguments.code` continues exactly where it stops. A
 lone text block — including the one synthesized from `structuredContent` — is
 measured, stashed, previewed, and paged as its text: wrapping it in a content
 envelope added nothing but a second layer of JSON escaping, so a JSON payload
@@ -598,8 +609,8 @@ same when no visible connector ID or title names that service. This service-name
 vocabulary is query interpretation, not an inventory of configured providers.
 For other service names, use the explicit `connector` scope. An unavailable
 catalog is a catalog failure, never an absence. Absence records and catalog
-errors use only the endpoint/pool and grant intersection; a connector hidden by
-that intersection is indistinguishable from an unconfigured one.
+errors use only the endpoint's tools; a connector the endpoint does not serve
+is indistinguishable from an unconfigured one.
 
 If no tool covers every search term, wider any-term fallback remains available
 for ordinary action/object searches and the page carries `matchMode: "partial"`.
@@ -683,8 +694,8 @@ replay. Downstream payloads and input responses are capped at 64 KiB, with at
 most 16 inputs and 256 characters per downstream key. The combined private
 state history is also capped at 64 KiB. Sealed wire state is
 capped at 128 KiB. `input_required_invalid`, `input_required_limit`,
-`input_required_unsupported`, and `input_required_round_limit` are non-retryable
-typed failures.
+and `input_required_unsupported` are non-retryable typed failures;
+`input_required_round_limit` is an untyped failure with `retryable: false`.
 
 Programs and in-process meta-tools return `input_required_unsupported`, with a
 `nextAction` naming the equivalent direct call and bounded original arguments.
@@ -933,9 +944,13 @@ list connectors from another pool or identity's grants.
 A write that times out after dispatch returns `write_outcome_unknown` with
 `retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted?, recovery? }`.
 No write is automatically replayed. `recovery` carries facts the connector
-recorded before dispatch (`src/call-recovery.ts`), such as the `idempotencyKey`
-a REST connector generated; a deliberate retry that reuses it with the exact
-original arguments cannot repeat the write while the vendor retains the key
+recorded before dispatch, such as a REST connector's
+generated or caller-supplied `idempotencyKey`. Recovery accepts keys up to 255
+characters, matching the REST write schema. Other recovery values remain capped
+at 128 characters, with at most four facts per call and camelCase names of at
+most 32 characters. Values outside these bounds are dropped whole. A deliberate
+retry that reuses the key with the exact original arguments cannot repeat the
+write while the vendor retains the key
 (Stripe may prune v1 keys after 24 hours). After that, look the object up before
 retrying. When a connector recorded such facts, any other dispatched write whose
 outcome is unknown (a lost response body, a 5xx) also carries `uncertainCall`
@@ -954,18 +969,22 @@ SDK timeout classes, and runtime network codes. Untyped prose is non-retryable:
 name, or URL never changes the verdict. JSON-RPC `ProtocolError.data` is dropped
 at the downstream boundary, even when the agent may see the error's message.
 
-## Source and tests
+## Contributor reference
+
+### Source and tests
 
 Handlers and schemas live in [meta-tools.ts](https://github.com/zackbart/connecta/blob/main/src/meta-tools.ts).
 [Catalog service](https://github.com/zackbart/connecta/blob/main/src/catalog-service.ts)
 and [invocation](https://github.com/zackbart/connecta/blob/main/src/invocation.ts)
 serve both direct tools and programs. [Skills](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
-owns the supplied usage instructions and connector guides.
+owns the supplied usage instructions, each endpoint's instructions
+(`endpointInstructions`), and connector guides.
 
 [Schema tests](https://github.com/zackbart/connecta/blob/main/test/meta-tool-schemas.test.ts),
 [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),
-and [surface tests](https://github.com/zackbart/connecta/blob/main/test/code-first-surface.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)
 check the published contract. Guest parity and clause evidence are in
 [code-mode verification](./code-mode.md#verification).

package/documentation/migration-0.33.md

@@ -0,0 +1,352 @@
+# Migration to 0.33
+
+Use this upgrade guide for an existing deployment moving to 0.33.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
+general procedure; [the agent index](./README.md) routes other work.
+
+0.33 makes pools the access model.
+Every deployment with inbound auth changes its configuration. Each removed
+option fails construction with a message naming its replacement, so a
+deployment that starts has no leftover option silently ignored. Work through
+the sections in order, then [verify](#verify).
+
+## Old option to new option
+
+| 0.32                                                                                  | 0.33                                                                                                                                    |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `identity.connectorAccess`                                                            | A pool per audience, with `tools` and `members`. A guarded `{ tool, requireReadOnly: true }` grant becomes a pool with `readOnly: true` |
+| Top-level `grant`                                                                     | `maintainers`                                                                                                                           |
+| Pool `grant`                                                                          | Pool `members`                                                                                                                          |
+| `describeConfig().hasGrant` (root and pools)                                          | `describeConfig().maintainers` and each pool's `members`                                                                                |
+| `identity.credentialAdministration`                                                   | `maintainers` (interactive)                                                                                                             |
+| `identity.personalConnection`                                                         | Pool `members` for personal connectors in their pools; maintainers for their own                                                        |
+| `identity.accessTokenManagement`                                                      | `maintainers` (interactive)                                                                                                             |
+| `identity.activityAccess`                                                             | `maintainers`, still narrowed by `activity.readGate`                                                                                    |
+| The `identity` section, even empty                                                    | Removed; delete it                                                                                                                      |
+| `ConnectaIdentityConfig`, `ConnectorPermission` types                                 | Removed                                                                                                                                 |
+| Tokens created or named in the UI, human-bound tokens                                 | `agents: ["<name>"]`, one token slot each                                                                                               |
+| `accessTokens(storage, { maxActive })`                                                | `accessTokens(storage)`                                                                                                                 |
+| `describeConfig().modules.accessTokens.maxActive`                                     | `describeConfig().agents`                                                                                                               |
+| Node template `provision-token`                                                       | `npm run --silent rotate-token -- <agent>`; existing tokens: `npm run adopt-token`                                                      |
+| A machine at `/mcp` or `/mcp/<pool>` with `cta_`                                      | `/agent/<pool>`, with `"agent:<name>"` in the pool's `members`                                                                          |
+| Access service token plus `cta_` behind Cloudflare Access                             | `cta_` alone, through an `/agent/*` Access Bypass application                                                                           |
+| Grant callbacks matching token record ids                                             | Membership by agent name; `identity.agent` in custom code                                                                               |
+| A Workspace `subject` mapping that answered for machine tokens                        | The pool's `owner`                                                                                                                      |
+| One Workspace connector per person (`gmail_alice`)                                    | One connector with a mapping `subject`, plus pool owners                                                                                |
+| `POST`/`DELETE /ui/access-tokens/<agent>` without a body                              | `{ "expect": "<revision>" }` from `GET /ui/access-tokens`                                                                               |
+| Operator contract `schemaVersion: 1`, `you.grants`, `you.permissions`, and `hasGrant` | `schemaVersion: 2` with `role`, `root`, `pools`, `agents`, `matrix`, and `connectors`; `OperatorUiContract` names v2                    |
+| `OperatorViewer`, `OperatorPool` types                                                | Removed; `OperatorPoolV2`, `OperatorRootEndpoint`, `OperatorMemberConnector` and the other v2 types                                     |
+| `/ui/data`, `/ui/connectors/<id>`                                                     | Maintainers only; members read their view from `/ui/api/config`                                                                         |
+| A connector that connects with `startAuth` alone, or disconnects only alongside it    | Connect needs `startAuth`, `finishAuth`, and `verifyState`; disconnect needs only `disconnectAuth`                                      |
+| `DELETE /ui/credentials/<id>` on an empty slot answering 204                          | 409 `{ "problem": "credential_required" }`                                                                                              |
+| The `agent_not_maintainer` denial reason                                              | Removed; agents are refused at human endpoints before admission                                                                         |
+
+## Maintainers and pool members
+
+0.32 combined an identity resolver, a top-level `grant`, and pool `grant`
+callbacks. 0.33 reads access from two static lists in code:
+
+- `maintainers` names the people who reach plain `/mcp`, which serves the
+  whole catalog, and every operator route. It is required whenever an inbound
+  provider that admits people is configured.
+- Each pool's `members` names who reaches it: people at `/mcp/<pool>`, agents
+  as `"agent:<name>"` at `/agent/<pool>`. A pool serves exactly its `tools`,
+  intersected with nothing. A maintainer opens no pool implicitly.
+
+```ts
+// 0.32
+createConnecta({
+  auth: clerkAuth({ publishableKey, secretKey }),
+  grant: ({ principal }) => principal?.id === "user_alice",
+  identity: { connectorAccess, credentialAdministration, activityAccess },
+  pools: {
+    support: { tools: ["tickets", "crm.search"], grant: ({ principal }) => support.has(principal?.id ?? "") },
+  },
+  // …
+});
+
+// 0.33
+createConnecta({
+  auth: clerkAuth({ publishableKey, secretKey }),
+  maintainers: ["user_alice"],
+  pools: {
+    support: { tools: ["tickets", "crm.search"], members: [...support] },
+  },
+  // …
+});
+```
+
+A reference is a bare principal id when the deployment has exactly one
+interactive provider, `{ namespace, id }` otherwise, or `"agent:<name>"`.
+Rewrite a predicate as the list it computed; ordinary code at construction
+(`team.map(...)`) can build it. [Principals and operators](./auth.md#principals-visibility-and-operators)
+owns the rules. A non-maintainer at `/mcp`, a non-member, and an undeclared
+pool get the same 404.
+
+### Preserve effective access
+
+Before deleting `identity.connectorAccess`, compute what each audience could
+actually use: its endpoint's tools intersected with that identity's old
+connector permissions, including read-only guards. Write that effective set
+into the new pool. Copying an old pool's broader `tools` verbatim would widen
+access because 0.33 has no second intersection. A person previously admitted
+to plain `/mcp` with restricted connector permissions needs a pool and a new
+`/mcp/<pool>` client URL, not a maintainer entry. Maintainers have the whole
+root catalog and administrative authority.
+
+For example, suppose Alice administered the deployment, while Bob's old team
+pool listed `crm` and `tickets` but his `connectorAccess` allowed only
+`{ tool: "tickets.search", requireReadOnly: true }`. The new configuration is:
+
+```ts
+maintainers: ["user_alice"],
+pools: {
+  team: { tools: ["tickets.search"], members: ["user_bob"], readOnly: true },
+},
+// Delete identity and all grant callbacks; Bob connects at /mcp/team.
+```
+
+A read-only guard applies to the whole new endpoint. If an audience previously
+had both writable tools and guarded reads, separate those into explicit pools
+with the appropriate `readOnly` choice rather than dropping the guard. Then
+update clients to the intended endpoints.
+
+## Management
+
+The four management resolvers are gone, and the `identity` section with them.
+[Management permissions](./auth.md#management-permissions) has the table:
+interactive maintainers administer shared credentials and OAuth grants and
+issue, rotate, and revoke agent tokens; maintainers read activity, within an
+optional `readGate`; a pool member connects and disconnects their own account
+on a personal connector in one of their pools. Agents manage nothing.
+
+## Agents and their tokens
+
+Machine clients are agents declared by name. Each has one token slot that a
+maintainer issues, rotates, and revokes; nothing outside code adds, renames,
+or rebinds one, and removing a name stops its token on the next request.
+
+1. Add `agents: ["<name>", …]` and keep `accessTokens(storage)` on the same
+   storage and key namespace. Drop `maxActive`. A Node template deployment
+   from before 0.33 also copies `src/rotate-token.ts` and `src/adopt-token.ts`
+   from `node_modules/@zackbart/connecta/templates/node/src/`, deletes
+   `src/provision-token.ts`, and replaces the `provision-token` and `doctor`
+   scripts with the installed template's `rotate-token`, `adopt-token`, and
+   `doctor` (`connecta doctor --pool <pool>`) scripts.
+2. Keep each machine's existing secret by adopting its token once:
+   `npm run adopt-token` lists the tokens that can be adopted, and
+   `npm run adopt-token -- <token-id> <agent>` binds one (Node template), or
+   call `AccessTokenManager.adopt(tokenId, agent)` from trusted provisioning.
+   Until then the token refuses.
+3. A human-bound token, issued from the UI before 0.33, cannot be adopted and
+   stays refused. Issue that agent a new token with
+   `npm run --silent rotate-token -- <agent>` or from the Tokens page.
+4. Clients that call the token routes send the slot's `revision`:
+   `POST /ui/access-tokens/<agent>` (issue, rotate) and `DELETE` (revoke) take
+   `{ "expect": "<revision>" }` from `GET /ui/access-tokens`, and a slot that
+   changed answers 409 `slot_changed`. A missing `expect` is 400.
+   `AccessTokenManager` takes the same optional `expect`.
+
+### Programmatic token management
+
+Trusted provisioning code that constructs its own `AccessTokenManager` must
+pass the declared agents. The deployment's top-level `agents` does not bind a
+separately constructed manager, so `new AccessTokenManager(storage)` knows no
+agent and every `rotate` and `adopt` fails with `unknown_agent`.
+
+| 0.32                                             | 0.33                                                                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `new AccessTokenManager(storage, { maxActive })` | `new AccessTokenManager(storage, { agents })`, with the same names as the deployment's `agents`                |
+| `create(name, createdBy)`                        | `rotate(agent, issuedBy?, options?)`, returning `{ token, agent }`; the first rotation issues the slot's token |
+| `rename(id, name)`                               | Removed; agents are named only in code                                                                         |
+| `revoke(tokenId, revokedBy)`                     | `revoke(agent, options?)`, returning the slot                                                                  |
+| `list()` of token records                        | `list()` of one slot per declared agent: `{ name, state, issuedAt?, revokedAt?, revision }`                    |
+| (none)                                           | `adopt(tokenId, agent, options?)` and `unboundTokens()` for tokens issued before agents                        |
+
+`options` is `{ expect?, signal?, deadline? }`. `expect` is the slot
+`revision` read from `list()`; when given, a slot that changed since refuses
+with an `AccessTokenError` whose `code` is `slot_changed`, and nothing is
+minted or written. Without it the calls behave as before.
+
+```ts
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+
+const manager = new AccessTokenManager(storage, { agents: ["assistant"] });
+const slot = (await manager.list()).find((agent) => agent.name === "assistant")!;
+const { token } = await manager.rotate("assistant", "provisioning", { expect: slot.revision });
+```
+
+Rotation is an immediate cutover: the old secret refuses on its next request.
+An agent has no principal, so personal connectors are absent for it.
+[Agent tokens](./auth.md#agent-tokens-and-upgrading-from-earlier-tokens) owns
+the slot, revision, and adoption contracts.
+
+## Agent endpoints
+
+Agents move from `/mcp/<pool>` to `/agent/<pool>`, and every human route
+(`/mcp`, `/mcp/<pool>`, the operator pages and APIs, `/connect`, OAuth starts
+and callbacks) refuses a `cta_` token before reading token storage. Agents are
+never maintainers, so a machine that used plain `/mcp` moves to a pool that
+holds its tools.
+
+1. List `"agent:<name>"` in the `members` of each pool the agent uses.
+2. Point its client at `https://<host>/agent/<pool>` with
+   `Authorization: Bearer cta_…` as its only credential.
+3. Behind Cloudflare Access, add one self-hosted Access application per agent
+   hostname for `<host>/agent/*` with a single Bypass policy, beside the
+   Worker-level application, then drop the agent's `CF-Access-Client-Id` and
+   `CF-Access-Client-Secret` headers. The
+   [deploying guide](./deploying.md#agent-endpoints-behind-cloudflare-access)
+   has the steps and the checks to repeat until the change settles. Never
+   bypass any other path.
+4. Run `connecta doctor --pool <pool>` with the agent's token; doctor checks
+   `/agent/<pool>` for a `cta_` token and requires `--pool`.
+
+[Agent endpoints](./auth.md#agent-endpoints) owns the path, auth, and
+membership contract.
+
+## Google Workspace pool owners
+
+In 0.32 a `cta_` token reached a Workspace connector's `subject` mapping,
+which usually answered nothing for a caller without a principal. In 0.33 an
+agent never reaches the mapping. It acts as the `owner` of the pool it came
+through; in a pool without one the connector is absent for it, as a personal
+connector is. People always act
+as themselves through the mapping, in any pool. A fixed `subject` address
+still applies to every caller.
+
+If your mapping returned an address for a machine token, set that address as
+the `owner` of the agent's pool. Replace per-person connectors such as
+`gmail_alice` and `gmail_bob` with one `gmail()` whose `subject` is a mapping
+function, and give each person's pool its `owner`.
+[Pool owners](./auth.md#pool-owners-for-google-workspace) owns the rules.
+
+## Operator contract v2
+
+`GET /ui/api/config` serves `OperatorUiContractV2` (`schemaVersion: 2`) and
+is the operator page's only gate; the v1 contract is removed:
+
+- A signed-out caller gets 401 with the auth challenge.
+- A `cta_` agent token gets the machine-only 401 Bearer challenge, as on every
+  human route, before token storage is read.
+- A signed-in person who is neither a maintainer nor in any pool's `members`
+  gets the private JSON 404.
+- A maintainer, or a person in a pool's `members`, gets 200 with their `role`.
+
+The maintainer view carries `config`, `configSources`, `root`, every pool
+with its owner and labelled members, every declared agent with its token slot
+and `lastSeenAt`, and the connector × endpoint `matrix`. The member view
+carries only that member's pools, without owner or members, and the
+connectors in them, with their own connection and a `manage` naming the
+actions they may take. `/ui/data` and `/ui/connectors/<id>` are
+maintainer-only and give anyone else the same 404. Code that read v1's
+`hasGrant`, `you.grants`, or `you.permissions` reads v2's `role`, `root`,
+`pools`, `agents`, `matrix`, and `connectors` instead;
+[the operator contract](./operator-ui.md#operator-data-contract) documents
+every field. Read the published declarations in
+`dist/operator-ui/contract.d.ts` inside the installed package for the exact
+typed shape; `you.interactive` remains in v2. `OperatorUiContract` now names v2, and `OperatorViewer` and
+`OperatorPool` are removed. `connecta doctor --config` reads v2 and prints a
+maintainer's `config`; a member's view has none.
+
+The connector auth routes accept what `manage` lists, with one recovery
+exception: a stored credential that cannot be read can still be cleared,
+although `manage` lists only `save` in that state.
+`/ui/oauth/<id>` gates each verb on its own hooks: connecting needs
+`startAuth`, `finishAuth`, and `verifyState`, and disconnecting needs only
+`disconnectAuth`. A custom connector that offered connect with `startAuth`
+alone adds the other two, without which its callback never completed. A
+connector provisioned out of band, with `disconnectAuth` and no `startAuth`,
+can now be disconnected. `DELETE /ui/credentials/<id>` refuses to clear a slot
+that holds nothing, the caller's own partition for a personal connector, with
+409 `{ "error": "no credential is stored to clear", "problem": "credential_required" }`.
+The bundled operator UI needs no change.
+
+## Security fix: pre-auth listen buffering
+
+Versions 0.29.0 through 0.32.0 buffered the whole body of an unauthenticated
+`POST` carrying `Mcp-Method: subscriptions/listen` to `/mcp` or `/mcp/<pool>`,
+with no byte cap, before authentication and request admission. An anonymous
+client could hold unbounded memory per request without taking an admission
+permit. No credential or data was exposed; the risk is memory exhaustion.
+
+0.33 authenticates first, then checks endpoint admission, before reading any
+body on `/mcp`, `/mcp/<pool>`, and `/agent/<pool>`. A pre-dispatch read takes
+at most 64 KiB; past that, connecta answers 413 with JSON-RPC code `-33006`
+and stops reading. The new `/agent/*` Access bypass therefore does not reopen
+the issue.
+
+What operators should know:
+
+- The fix ships in 0.33.0 only; there is no patch release for 0.29–0.32.
+  Upgrade.
+- No configuration change is needed for the fix itself.
+- A Worker behind a Worker-level Access application received only requests
+  Access admitted. A deployment reachable without edge authentication, such
+  as Node behind a public URL, was exposed. If you cannot upgrade at once,
+  cap request body size at your proxy or refuse unauthenticated requests that
+  carry `Mcp-Method: subscriptions/listen` there.
+
+## Moving to the agent pool layout
+
+A 0.32 agent usually reached `/mcp/<pool>` through a pool `grant` matching
+its token, often with one connector per person and a second connection or
+pool for each person's accounts. Move it to
+[connecta's agent pool layout](./auth.md#organizing-an-agents-pools): one
+connection; a base pool named after the agent with shared connectors and no
+owner; one `<agent>-<user>` pool per person with their own connectors and
+their Workspace address as `owner`.
+
+```ts
+// 0.32
+pools: {
+  assistant: {
+    tools: ["crm", "tickets", "notes_alice", "gmail_alice", "notes_bob", "gmail_bob"],
+    grant: ({ actor }) => actor.kind === "access_token" && actor.id === assistantTokenId,
+  },
+},
+
+// 0.33
+agents: ["assistant"],
+pools: {
+  assistant: { tools: base, members },
+  "assistant-alice": { tools: [...base, "notes_alice", "gmail"], owner: "alice@example.com", members },
+  "assistant-bob": { tools: [...base, "notes_bob", "gmail"], owner: "bob@example.com", members },
+},
+// with const base = ["crm", "tickets"], members = ["agent:assistant"];
+```
+
+1. Declare the agent in `agents` and adopt its token (see
+   [Agents and their tokens](#agents-and-their-tokens)).
+2. Define the base pool's tool list once with the shared connectors, and
+   spread it into the base pool `<agent>` and one `<agent>-<user>` pool per
+   person, adding that person's connectors and `owner`. Each pool lists
+   `members: ["agent:<agent>"]`. If group chats should get different tools
+   depending on who is present, add tiers as the layout describes.
+3. Collapse per-person Workspace connectors into one connector with a mapping
+   `subject`. Keep other per-person accounts as their own shared-auth
+   connector ids (`notes_alice`) and list each only in its person's pool.
+4. Change the agent's client to one connection whose URL it sets per turn:
+   `/agent/<agent>-<user>` in a one-on-one with that user, otherwise the
+   layout's tier for who is present (`/agent/<agent>` with a single tier). Remove any second Connecta connection.
+5. Add this line to your deployment's own AGENTS.md (or its CLAUDE.md
+   equivalent), so agents find all operator procedures after the upgrade:
+
+   ```text
+   For every Connecta operator task, start at node_modules/@zackbart/connecta/documentation/README.md#operator-tasks
+   ```
+
+## Verify
+
+1. Start the deployment; construction errors name each removed option's
+   replacement.
+2. Sign in as a maintainer and confirm plain `/mcp` and the operator UI work.
+3. Run `connecta doctor --pool <pool>` with each agent's token, and confirm
+   the same token at `/mcp` is refused.
+4. Confirm a pool member sees exactly that pool's tools at `/mcp/<pool>`.
+5. For Workspace, call a read in an agent's personal pool and confirm it acts
+   as the pool's owner. In the base pool, confirm Workspace connectors are
+   absent: search finds none of their tools and a call fails
+   `unknown_address`. The same holds in any pool without an owner, even one
+   that lists a Workspace connector with a subject mapping.
+6. Confirm each `<agent>-<user>` pool lists no other person in `members`.

package/documentation/migration-0.34.md

@@ -0,0 +1,67 @@
+# Migration to 0.34
+
+Use this guide when upgrading an existing deployment from 0.33 to 0.34.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
+general procedure; [the agent index](./README.md) routes other work. Upgrades
+from earlier versions must also apply the intervening migrations.
+
+No storage migration, token rotation or required configuration field is added.
+Review the following changes before updating the package pin.
+
+## Operator links and browser titles
+
+Maintainers now land on Overview at `/`. Endpoints is at `/endpoints`, and
+`/access` redirects to `/endpoints`. Update saved links and browser automation
+that expected Endpoints at `/`, including row links: `/#mcp/support` becomes
+`/endpoints#mcp/support`. Members still get their member page on every operator
+page path. MCP client URLs (`/mcp`, `/mcp/<pool>` and `/agent/<pool>`) do not change.
+
+The default `branding.pageTitle` joins `productName` and `ownerName` with a
+middle dot, for example `Assistant · Example team`. A title set explicitly in
+`branding.pageTitle` is unchanged. If automation requires the previous title,
+set that exact title explicitly; otherwise update its expectation. With no
+owner name, the default remains the product name alone.
+
+Activity links can use `failed` or `succeeded` for the outcome filter. Older
+exact outcome values in saved links still work. See the
+[operator UI guide](./operator-ui.md) for the new pages and controls.
+
+## Workspace connectors in agent pools
+
+An agent in a pool without an `owner` no longer sees a Google Workspace
+connector whose `subject` is a mapping function. Previously the connector
+appeared but its calls failed `auth_required`; now discovery, search, describe,
+skills and code mode omit it, and a call by address fails `unknown_address`.
+Paging a saved program return also rechecks visibility, including contributions
+to search counts and guidance.
+
+Keep a shared or group pool owner-less when it must not act as one person.
+If an agent needs to act as Alice, put that access in her personal pool and set
+`owner: "alice@example.com"` there, using the Workspace account she is intended
+to use. Confirm the pool's tools and members before adding an owner. Follow
+[the agent pool layout](./auth.md#organizing-an-agents-pools) for the full
+configuration. People in the same pool, agents in owned pools and connectors
+with a fixed `subject` address keep their behavior.
+
+## Optional settings and development tooling
+
+Pool `description` is optional; omit it to preserve the existing MCP
+instructions. A custom activity store can optionally return
+`describe().optionSources.retentionDays` as `"config"` or `"default"` to mark
+whether code explicitly set retention. Existing implementations need no
+change; Settings marks retention as explicitly set only when the store
+reports `"config"`.
+
+The repository now uses pnpm for development and CI. Installed deployments and
+the Node template continue to use npm; keep their npm commands and lockfiles.
+Deployments without the operator UI or mapping-subject Workspace connectors in
+owner-less agent pools can skip the UI and discovery steps above.
+
+## Verify
+
+After upgrading, open `/` as a maintainer and confirm Overview loads, then open
+`/endpoints` and a saved endpoint row link. Check any automation that reads the
+browser title. With an agent's existing credentials, discover tools in its base
+and personal pools and perform a bounded Workspace read in the owned pool.
+Owner-less pools must omit mapping-subject Workspace connectors. Run
+`connecta doctor` as described in [deployment upgrades](./deploying.md#upgrade-an-existing-deployment).

package/documentation/operating.md

@@ -126,7 +126,9 @@ mean the provider applied it; inspect state or ask for the missing decision
 before issuing it again. [Retry semantics](./code-mode.md#retry-semantics) and
 [writes](./code-mode.md#writes) describe program outcomes and write accounting.
 
-## Implementation and evidence
+## Contributor reference
+
+### Implementation and evidence
 
 The endpoint's built-in [usage skill](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
 is maintained alongside [meta-tools](https://github.com/zackbart/connecta/blob/main/src/meta-tools.ts)