@zackbart/connecta 0.32.0 → 0.33.0

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,14 +63,30 @@ 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 Access-authenticated operator page 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 client picks the pool per
+  turn: base pool `<agent>` (shared connectors, no `owner`) outside a
+  one-on-one, and `<agent>-<user>` (the base plus that user's own connector
+  ids, `owner` set to their Workspace address) only with that user. Never list
+  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

package/examples/worker/README.md

@@ -81,10 +81,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,6 +112,33 @@ 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
 on a deployed Worker's production identity.
@@ -219,57 +246,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
+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 Connections and each connection's
 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 Access tokens page, listing one token slot per
+declared agent, is available to permitted interactive operators.
 
 ## 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 human authenticated
+through Access can still sign in and issue the first token. Open
+`<PUBLIC_URL>/`, select Access 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 +311,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 +358,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 +372,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"
+connecta doctor --url "$PUBLIC_URL" --pool ci
 ```
 
 Doctor reports the configured `DynamicWorkerExecutor`, not a presumed Node
@@ -430,7 +469,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 +501,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 +527,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.

package/examples/worker/src/connecta.config.ts

@@ -31,9 +31,15 @@
  *      Claude's https://claude.ai/api/mcp/auth_callback plus ChatGPT's
  *      https://chatgpt.com/connector_platform_oauth_redirect and
  *      https://chatgpt.com/connector/oauth/* forms (see ../AGENTS.md).
+ *      Then add one self-hosted Access application per hostname for
+ *      `<host>/agent/*` with a single Bypass policy (Everyone), so agents send
+ *      only their cta_ token (README.md § "Let agents through Access").
  *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
- *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
- *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
+ *   6. List the maintainers' Access user ids (the identity's user_uuid, else
+ *      its email) in the CONNECTA_MAINTAINERS var, comma-separated.
+ *   7. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
+ *      lives. Point a maintainer's MCP client at `<PUBLIC_URL>/mcp`, and an
+ *      agent's at `<PUBLIC_URL>/agent/ci`.
  */
 import { api, defineConfig, remoteMcp } from "@zackbart/connecta";
 import { activityHistory } from "@zackbart/connecta/activity";
@@ -55,6 +61,8 @@ export interface Env {
   CREDENTIAL_ENCRYPTION_KEY?: string;
   DOWNSTREAM_TOKEN: string;
   PUBLIC_URL: string;
+  /** Comma-separated Access user ids (user_uuid, else email) of the maintainers. */
+  CONNECTA_MAINTAINERS: string;
   /** "on" switches on activity history, in CONNECTA_DB. */
   CONNECTA_ACTIVITY?: string;
   /**
@@ -77,26 +85,34 @@ export default defineConfig((env: Env) => {
     // Required adapter owns each run's handles; direct upstream construction throws.
     executor: workerExecutor({ loader: env.LOADER }),
     // Access owns edge admission and proves human identity for MCP and the
-    // operator pages. Machines need Access service headers at the edge plus a
-    // stored cta_ bearer inside connecta; a service identity alone is refused.
+    // operator pages. Agents use /agent/<pool>, which Access bypasses and
+    // connecta authenticates with the cta_ bearer alone; a service identity
+    // alone is refused everywhere.
     auth: [cloudflareAccessAuth()],
-    // Always installed over the same D1 storage. Empty storage admits no
-    // machine client; an Access-authenticated operator can provision tokens.
+    // Machine clients are agents declared here by name, each with one cta_
+    // token. An Access-authenticated operator issues, rotates, and revokes it
+    // in the operator UI; removing a name stops its token on the next request.
+    agents: ["ci"],
+    // Always installed over the same D1 storage. An agent with no issued token
+    // admits nothing.
     accessTokens: accessTokens(storage),
-    // Code-owned roster. Access proves the identity; connecta derives
-    // connector visibility and management permissions from the stable id it
-    // supplies. Add `connectorAccess` and `activityAccess` to split members
-    // from operators; here every signed-in human may manage every connector
-    // and access token. Machine tokens never receive interactive authority.
-    identity: {
-      credentialAdministration: () => "all",
-      personalConnection: () => "all",
-      accessTokenManagement: () => true,
-    },
-    // Connectors that declare a `credential` slot become editable by every
-    // signed-in human who can see that connector, encrypted with this key
-    // before anything reaches D1. A saved replacement takes effect on the
-    // next call; credentials fail at use.
+    // Code-owned roster. Access proves the identity; maintainers alone use
+    // plain /mcp, which serves every connector, and the operator UI, where they
+    // administer shared credentials, manage agent tokens, and read activity.
+    // Startup refuses an empty list.
+    maintainers: env.CONNECTA_MAINTAINERS.split(",")
+      .map((id) => id.trim())
+      .filter(Boolean),
+    // Everyone else uses a pool that lists them, which serves exactly its
+    // tools: people at /mcp/<name>, agents at /agent/<name>. Members are
+    // Access user ids or "agent:<name>". The starter pool is the agent's base
+    // pool (shared connectors, no owner), named after the agent as the agent
+    // pool layout requires.
+    pools: { ci: { tools: ["echo"], members: ["agent:ci"] } },
+    // Connectors that declare a `credential` slot become editable by a
+    // maintainer (shared) or by the member it belongs to (personal),
+    // encrypted with this key before anything reaches D1. A saved replacement
+    // takes effect on the next call; credentials fail at use.
     vault: env.CREDENTIAL_ENCRYPTION_KEY ? encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY) : undefined,
     // Payload-free activity at /ui/api/activity in CONNECTA_DB. The shared
     // D1 mapping persists the build version and validated client facts, and

package/examples/worker/wrangler.jsonc

@@ -13,6 +13,9 @@
   "vars": {
     // "CONNECTA_ACTIVITY": "on",
     "PUBLIC_URL": "https://connecta.example.workers.dev",
+    // Comma-separated Access user ids (user_uuid, else email) of the
+    // maintainers. This one matches the local dev identity below.
+    "CONNECTA_MAINTAINERS": "operator@example.com",
   },
 
   // Local-only Access identity. Remove this block to exercise the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -263,7 +263,8 @@
     "@cloudflare/codemode": "^0.5.0",
     "@cloudflare/vitest-pool-workers": "^0.18.8",
     "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
-    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/geist-mono": "^5.3.0",
     "@playwright/test": "^1.62.0",
     "@radix-ui/react-dialog": "^1.2.0",
     "@radix-ui/react-slot": "^1.4.0",

package/templates/node/.env.example

@@ -26,6 +26,9 @@ CONNECTA_DATABASE=
 # may write a credential; machine access tokens grant no interactive authority.
 CLERK_PUBLISHABLE_KEY=
 CLERK_SECRET_KEY=
+# Required with Clerk: comma-separated Clerk user ids of the maintainers, who
+# alone use plain /mcp and the operator UI.
+CONNECTA_MAINTAINERS=
 
 # Credential vault. Base64-encoded 32-byte AES key encrypting the values an
 # operator saves inside a connection on /. Generate one with:

package/templates/node/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.
 - Keep `executor: quickJsExecutor()` for the prescribed six-tool code-first
@@ -19,15 +25,30 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Prefer `api()` when the agent must see an exact reviewed capability surface;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
 - Optional modules (Clerk sign-in, credential vault, activity history) are type-checked code in `src/connecta.config.ts`, switched on by
-  their environment variables. Follow README "Select optional modules". Auth management requires explicit
-  `credentialAdministration` or `personalConnection` permissions; visibility
-  alone never grants it. Clerk supplies human identity; `cta_` access tokens cover machine clients.
+  their environment variables. Follow README "Select optional modules". Shared auth management
+  requires a signed-in maintainer, and a pool member manages only their own
+  account on a personal connector in their pools; visibility alone never grants it. Clerk supplies human identity; machine clients are the
+  `agents` declared by name in `src/connecta.config.ts`, each with one `cta_` token.
   Keep `accessTokens(storage)` installed even before the first token exists.
-  Bootstrap machines with `npm run provision-token -- "machine-name"` against
-  the same database the server uses. `CONNECTA_TOKEN` is only for clients and
-  doctor; never add a configured static bearer or an open startup mode.
+  Issue or rotate an agent's token with `npm run --silent rotate-token -- <agent>`
+  against the same configuration and database the server uses; bind a token
+  from before agents once with `npm run adopt-token -- <token-id> <agent>`.
+  Plain `/mcp` serves `maintainers` only; other people reach `/mcp/<pool>` and
+  agents `/agent/<pool>` for a pool listing them in `members` (`npm run doctor`
+  checks `/agent/local-machine`). Human endpoints refuse `cta_` tokens. `CONNECTA_TOKEN` is only for clients and doctor; never add a configured
+  static bearer or an open startup mode.
   All state, activity included, lives in the one SQLite file `CONNECTA_DATABASE`
   names, through `@zackbart/connecta/sqlite`.
+- 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 client picks the pool per
+  turn: base pool `<agent>` (shared connectors, no `owner`) outside a
+  one-on-one, and `<agent>-<user>` (the base plus that user's own connector
+  ids, `owner` set to their Workspace address) only with that user. Never list
+  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

package/templates/node/Dockerfile

@@ -2,8 +2,8 @@
 # image installs @zackbart/connecta from the registry exactly like any other
 # consumer, so nothing here depends on the Connecta repository.
 #
-# Provision a stored machine token on the volume first; README.md gives the
-# exact build, provisioning, and startup commands. Empty storage is fail-closed.
+# Issue a declared agent's token on the volume first; README.md gives the
+# exact build, rotation, and startup commands. Empty storage is fail-closed.
 FROM node:22-slim
 
 WORKDIR /app