@zackbart/connecta 0.38.0 → 0.40.0

package/documentation/operator-ui.md

@@ -113,6 +113,12 @@ Pool endpoint rows show the effective surface (`meta` or `native`) and whether
 code is on. These are read-only facts from deployment configuration; change
 `surface` and `executeCode` in deployment code.
 
+Plain `/mcp` is routed by sign-in: the `/mcp` row and matrix column show the
+whole catalog maintainers receive, and a pool row shows what its people
+receive at both `/mcp/<pool>` and, when they belong to no other pool, plain
+`/mcp`. A note above the rows says so. People in several pools appear in
+`config.peopleInSeveralPools`; plain `/mcp` refuses them.
+
 One row each for `/mcp` and every pool: the path, a read-only pill on a
 read-only endpoint, a copyable URL, who can use it, its connectors as colored
 monograms (four, then "+N"), its tool count over a read and write bar, and a
@@ -121,7 +127,9 @@ Setup button.
 - Who can use it is `root.maintainers` on `/mcp` and the pool's `members`
   elsewhere, as an avatar stack named on hover and to screen readers (label,
   raw id when the label is null, or agent name). Four show, then a "+N"
-  button. A pool with agent members labels its two URLs People and Agents.
+  button. A pool lists only people or only agents. An agent pool's row
+  still shows two URLs labeled People and Agents; the People URL
+  (`/mcp/<pool>`) admits no one, because the pool has no people.
 - Expanding a row lists everyone by name, then each connector with what it
   runs as and its tools, write tools amber with a pencil. Runs-as comes from
   the endpoint's matrix cell: "Shared · saved <date>", "Shared · connected
@@ -194,8 +202,9 @@ tabs:
   annotation badges (Destructive, Open world), filtered by search and All,
   Read and Write. A tool opens its schema in a side drawer.
 - **Connection.** An Authentication card (mode, OAuth client mechanism, who
-  manages it, OAuth actions, and the credential card with masked last four,
-  field states, and Replace, Test and Remove); a Diagnostics card of tiles
+  manages it, the last verification, OAuth actions, and the credential card
+  with masked last four, field states, and Replace, Test and Remove); a
+  Diagnostics card of tiles
   (catalog age and last call) with a fix prompt beside each
   problem; and a Configuration card. Its badges name the kind (Remote MCP,
   HTTP API or Custom), provider, auth scope, endpoint host and usage guide.
@@ -340,10 +349,12 @@ connections**, has no tabs; its heading shows the signed-in email when the
 sign-in exposes one (Clerk's primary email), and its top bar shows branding and
 an **Account** button with Sign out or Change token. It lists:
 
-- **Your endpoints**: one card per admitted `/mcp/<pool>` URL with a copy button
-  and **Client setup**. For example, Bob in pool `team` copies
-  `https://connecta.example.com/mcp/team` into an MCP client and authenticates
-  as Bob.
+- **Your endpoints**: one card per address with a copy button and **Client
+  setup**. A member of exactly one pool sees one card for plain `/mcp`, named
+  after the pool it serves; a member of several pools sees one
+  `/mcp/<pool>` card per pool. For example, Bob, only in pool `team`, copies
+  `https://connecta.example.com/mcp` into an MCP client and authenticates as
+  Bob.
 - **Your accounts**: the personal connectors in their pools, each with a
   monogram, tool count, one status badge in an aligned column, and only the
   controls its `manage.actions` lists. A saved credential that no longer fits
@@ -415,7 +426,8 @@ without this capability contribute an unconfirmed count of zero. For example,
 The maintainer view carries:
 
 - `config`, the construction-time `describeConfig()` snapshot, including
-  `maintainers` and each pool's `members`, and `configSources`, which labels
+  `maintainers`, each pool's `members`, `peopleInSeveralPools` (non-maintainer
+  people plain `/mcp` refuses because they are in several pools), and `configSources`, which labels
   each serialized leaf as `default` or `config` from option presence rather
   than equality with the default. Factory descriptions carry relative
   `optionSources` paths so resolved module and transport defaults retain their
@@ -488,7 +500,9 @@ The maintainer view carries:
 The member view is exactly that member's projection: `config`,
 `configSources` and `root` are `null`, `live.connectors`, `agents` and
 `matrix` are empty, and `live.activity` is `"forbidden"`. `pools` lists only
-their pools, each with `owner: null` and `members: []`. `connectors` lists
+their pools, each with `owner: null` and `members: []`. With exactly one pool,
+its `humanPath` is `/mcp`, the address that serves them that pool, and the
+member's catalog reads carry that pool as plain `/mcp` would. `connectors` lists
 each connector in those pools with its title, the member's pools that serve
 it, its auth scope, the tools those pools grant with their classification,
 `connection` (their own partition's state and problem code for a personal
@@ -556,6 +570,58 @@ the config snapshot, and never treats a `per_caller` overlay as an error.
 complete classified tools with input/output schemas, registration path, catalog
 age, and activity-derived last-call facts under the reader's disclosure policy.
 A failed or timed-out connector releases its own scope; siblings finish independently.
+The status and catalog observation has its own deadline: 8 seconds, or
+`discovery.probeTimeoutMs` when that is shorter, in which case the whole row
+uses that one deadline. The 8-second value is fixed, not configured; agent
+discovery keeps the full `discovery.probeTimeoutMs`. When the deadline ends
+first, the downstream read is aborted and the row returns `status: "error"`
+with `problem: "connector_timeout"` in the row and its overlay. The row still
+carries its credential card and auth permissions, so a slow connector's slot
+stays manageable. Any other failure keeps `connector_unavailable`. The
+connector renders as **Not responding**, with fixed copy, a fix prompt and
+Refresh.
+**Stored status.** Each live `GET /ui/connectors/:id` records one status
+observation for that connector and viewer partition before it answers: its
+state, problem code, tool count and observation time. Authored static catalogs
+such as `api()` connectors are recorded too, since their status still checks
+auth. The record lives in the `connector-health:v1:` family under the same
+owner partition as the catalog cache (principal, subject, caller identity and
+pool, endpoint, described configuration and package version), so a personal
+connector's observation is one person's. It also carries the catalog
+generation read before the probe, through the request's read memo that the
+catalog listing reuses. It holds no tools, schemas, status prose or
+credential facts. It expires 120 seconds after it was observed, and lapses at
+once when a credential change, OAuth connect or disconnect, or invalidation
+rotates the generation. A read that ends at the row's own deadline, including
+a configured `discovery.probeTimeoutMs` shorter than 8 seconds, records
+`connector_timeout` before it answers. An observation is written only while
+the caller is still waiting: a request its caller has already left starts no
+write. A write that has started is never raced against a deadline or
+detached, because a storage write cannot be withdrawn once sent. The request,
+whether it times out or its caller leaves meanwhile, settles only after that
+write does, bounded by the storage layer like every other awaited write, so
+nothing commits after the request ends.
+
+`GET /ui/connectors/:id?observation=stored` answers from a current observation
+without probing the downstream. The row and overlay carry `observedAgeMs`, the
+stored `status`, `problem` and `toolCount`, and `tools: []`; the tools stay in
+the catalog cache. The credential card, drift, permissions and any
+authorization link are computed fresh on every request. Without a current
+observation the route does the live read and records it, with no
+`observedAgeMs`. Nothing is refreshed after the response: no deferred work and
+no `ctx.waitUntil`.
+
+The browser asks each connector for its stored observation on the page load
+that follows admission, and fixes the observation time once as each stored
+row lands. The list card and the connector page mark a stored row the same
+way, "Stored status, checked … ago", with an age that keeps counting, and
+show its tools as awaiting the live read rather than as none. The browser then
+sends one plain live read per stored row, through the same queue of eight
+detail reads. A stored `connector_timeout` row is not read again on its own;
+its mark says to Refresh, and it waits for Refresh like a live timeout.
+Refresh, a single connector's read, recovery retries and OAuth polls always
+read live.
+
 The summary and each detail carry `viewerKey` for the principal admitted to that
 request. The browser publishes the detail and overlay atomically only when that
 key matches admission. A changed viewer key, including an Access switch between
@@ -568,7 +634,7 @@ screen. The first answer for the new viewer triggers readmission, which clears
 everything retained.
 Config observations never
 overwrite a completed detail row. Each connector opens at most one live observation
-per page load; the summary `/ui/data` performs no downstream probes.
+per page load, after its stored read; the summary `/ui/data` performs no downstream probes.
 
 `GET /ui/api/config?connector=<id>` narrows the same contract to one connector
 before status and catalog probes. For a maintainer, config, provenance, live
@@ -628,8 +694,23 @@ bounded at 2, 2, 4 and 8 seconds; a later focus return can try again after backo
 
 Connector Refresh, focus recovery and mutation follow-ups read only affected
 connectors. Focus probes unhealthy rows, never healthy siblings. All detail reads
-share a four-request limit and coalesce per connector. Failures retry only their
+in one tab share an eight-request limit and coalesce per connector, so a page of
+up to eight connectors loads in one round. The limit is fixed, not configured.
+It bounds how many connectors one tab waits on at once; a tab still reads each
+connector once per load, so the limit adds no requests to any one connector.
+Detail reads do not consume `admission.requests` permits, which govern `/mcp`
+only. They still share isolate CPU and memory, D1, and downstream account quotas
+with agent traffic; each tab adds up to eight concurrent downstream reads, and
+several connectors on one vendor account share that vendor's rate limit. Over HTTP/1.1 the browser itself allows about six
+connections per origin.
+Failures retry only their
 connector with the same bounded backoff; recovery never replays a mutation.
+A `connector_timeout` row is parked instead. It spends its automatic retry
+budget, and focus and visibility returns skip it. Only Refresh, a full refresh
+or a mutation follow-up reads it again, so an outage holds a detail slot once
+per explicit request, never repeatedly. An OAuth start's consent-return poll is
+the exception: a timeout during its 30-second window keeps polling, and success
+still stops it.
 Mutations cancel affected reads and advance their publication fence both at
 dispatch and on settlement, including failure. Follow-ups require an observation
 started after settlement, so a Refresh or retry started during the write cannot
@@ -638,9 +719,21 @@ while identity and full refresh revisions fence the complete view. An explicit
 OAuth start polls only that connector every two seconds for up to 30 seconds.
 Concurrent authorizations retain independent cancellation and publication. Success,
 failed reads, disconnect, navigation, unmount and identity reset stop the matching
-poll. Recovery never starts authorization. A scoped result cannot confirm identity,
+poll; a `connector_timeout` result does not. Recovery never starts authorization. A scoped result cannot confirm identity,
 role, token slots or any other deployment-wide admission fact.
 
+A credential connector's `/ui/data` and `/ui/connectors/<id>` row carries
+`verification: { outcome, observedAt }` when a record of the stored save
+exists (see [last verification](./auth.md#test-then-save-and-last-verification)).
+The auth facts show it as **Last verified**: Verified, Saved without a test,
+Rejected, Missing permission, Service unreachable, Test timed out or Test
+failed, with its time. A maintainer's credential form on a testable connector
+saves through **Test and save** (`verify: "test"`). A failed test leaves the
+form open with fixed copy for its failure class, and adds **Save without
+testing**, a save without `verify`. Test shows the same per-class copy and reloads
+the connector so its last verification updates. The member page's
+credential form saves without a test and offers Test once a value is stored.
+
 Unreadable credential metadata uses `configured: null`, including named fields,
 and renders as unavailable with a retry prompt. It does not claim that the slot
 is empty. Overview, Endpoints, Connectors, connector

package/documentation/pool-membership-upgrade.md

@@ -0,0 +1,44 @@
+# Split mixed pools
+
+Every pool must list only people or only `agent:` references. A mixed pool
+throws `ConfigError` at construction naming the pool, for example
+`ConnectaConfig.pools.team.members mixes people and agents; list only one kind.`
+This also applies to personal pools with or without `owner`. Pool names and
+connector ids do not decide membership type. People-only pools may retain an
+`owner`; it never changes the account a person uses.
+
+Before upgrading, inspect every pool's `members`, including generated lists.
+For each mixed team pool, define its tool list once and create two pools:
+
+```ts
+const teamTools = ["crm", "tickets"];
+const pools = {
+  team: { tools: teamTools, members: ["user_alice", "user_bob"] },
+  "assistant-team": { tools: teamTools, members: ["agent:assistant"] },
+};
+```
+
+Keep the original human pool name when possible so people's existing
+`/mcp/team` address stays valid. Point the agent harness at
+`/agent/assistant-team` and update its tier list to that name. Copy the
+original `readOnly`, `surface`, `executeCode` and `description` settings
+to both new pools as appropriate so each preserves its intended behavior.
+If the mixed pool set `owner`, keep `owner` on the agent pool: it is the
+Workspace address the agent acts as, and without it Workspace connectors with
+a mapping `subject` disappear for the agent. People never use `owner`; they
+always act as themselves, so the people pool does not need it. Agent pools
+never count toward a person's plain `/mcp` routing, so a person who was in
+one mixed pool and no other still reaches the people pool at plain `/mcp`.
+
+For personal `assistant-alice` pools, keep only `"agent:assistant"` in
+`members` and retain the owner's Workspace address and tools. Give people
+their own people-only pools. Workspace mapping connectors act as each person;
+shared-auth connectors act as their saved account for every member, so review
+those grants before copying personal tool lists.
+
+An agent can still belong to many pools with one token. Tokens, credentials,
+`poolFor` tier selection logic and the Eve helper need no changes beyond pool
+names in client configuration. Rebuild and restart the deployment, then verify
+people and agents can each open their intended endpoints. See
+[Organizing an agent's pools](./auth.md#organizing-an-agents-pools) for the
+complete layout.

package/documentation/providers.md

@@ -360,6 +360,67 @@ discovery for your deployment's catalog.
 
 <!-- provider-inventory:end -->
 
+## Field selection with `fields`
+
+Every maintained read that projects a result takes an optional `fields`
+argument: up to 50 dot paths, each 1 to 200 characters, that narrow the
+returned data. Selection runs after value safety and privacy filtering, so it
+can only remove values. `a.b` and `a[].b` are equivalent; a list on the way is
+narrowed item by item.
+
+Where paths start, the anchor, depends on the tool and is stated in each
+`fields` schema description with one valid example:
+
+| Tool                                       | Paths start at                     | Example                                      |
+| ------------------------------------------ | ---------------------------------- | -------------------------------------------- |
+| A named read (`get_*` and similar)         | The result                         | `["id"]`, `["owner.name"]`                   |
+| A named list or search (`{ items, page }`) | Each item in `items`               | `["id"]`, not `["items.id"]`                 |
+| `*_api_read` and `*_api_write`             | The vendor response body in `data` | `["projects.name"]`, not `["data.projects"]` |
+
+A hatch body that is a list is narrowed item by item, so its paths start at
+each item. An enveloping vendor nests records under a root, such as
+`{ "projects": [...] }`; select `projects.name`, not `name`. Copy hatch paths
+from the operation's `*_api_details` `response.fields`, which are already in
+these coordinates. Paging, cut and recovery metadata (`page`, `truncated`)
+remain outside the selection where a tool says so.
+
+**Refused before dispatch.** A path outside the declared contract returns
+`invalid_args` before any request. Each finding names the entry position
+(`/fields/1`), the segment where the path left the contract and the properties
+declared there, never the submitted path:
+
+- Named tools check the first segment against the properties their published
+  output schema declares for the result or item. Deeper segments follow JSON
+  Schema's default: an object is closed only where the schema says
+  `additionalProperties: false`, and only such an object refuses an undeclared
+  property. Paths through other objects, open values such as GitHub
+  `search_scoped` rows' `item`, and paths past a scalar are accepted; a miss
+  there is omitted from the selection.
+- Hatch reads and writes check the first segment against the operation's
+  declared response roots. An operation that declares no response properties
+  refuses `fields`. The pinned index does not establish whether deeper levels
+  are complete, so deeper segments are not refused.
+
+**Declared but absent is not an error.** Optional values, empty lists and
+values that value safety or privacy filtering removed are ordinary. A declared
+path the current response lacks is never refused, and the selection omits it.
+
+**Hatch miss warnings.** A hatch answer adds `warnings: string[]` when a
+`fields` entry matched nothing anywhere in a nonempty response. Each warning
+names the entry position, the segment where matching stopped and the
+properties the operation's contract declares there, for example
+`fields/1 matched nothing in this response after value safety and privacy
+filtering, at segment 2; declared there: id, name.` Where the contract
+declares none, such as inside an open map, it says so. A warning never lists
+the response's own keys, which in an open map such as `metadata` are data, and
+never repeats the submitted path. A path that matched in any listed item, a
+path that runs past a scalar (selection keeps the scalar), and any path of an
+empty body (`null`, `[]` or `{}`) produce no warning. Warnings are bounded: each
+is at most 512 characters, at most 10 are kept within 4,096 characters
+together, reviewed vendor warnings included, and a final entry counts the rest
+(`3 more warnings omitted.`). Treat a warning as a repair hint for the next
+call, not as a failure.
+
 ## API operation discovery and boundaries
 
 Standard API operation search accepts resource nouns, actions and conversational
@@ -418,6 +479,50 @@ then follow `page.nextCursor` to reach operations beyond the leading profile
 results. Responses contain at most eight compact hits within 16 KiB; fetch
 operation details separately and keep the same query when continuing.
 
+Operation details return the request contract and, for an operation that is
+not refused and declares success-response properties, a `response` section.
+Write `fields` filters and reductions from it without a sampling read:
+
+- `anchor` is `data` when paths start at the read result's `data`, or `data[]`
+  when the body is a list and each path applies to every item.
+- `fields` lists the declared paths a read can select, in the read and write
+  tools' `fields` coordinates; pass them unchanged, such as
+  `fields: ["data[].id"]`.
+- `withheld` is a best-effort, incomplete hint: the listed paths whose
+  non-null values value safety always withholds or redacts, by a reviewed
+  redaction path, a credential name, the deployment's sensitive-field choice
+  or a closed projection. A rule that can leave some value unchanged is never
+  a hint. Examples are URL sanitizing, reduction to an origin, which returns a
+  bare origin unchanged, redaction by a key, type or label, and a credential
+  suffix rule that scrubs only strings. A container above a hinted path is
+  not hinted either. Every hinted path also appears in `fields`.
+- `omitted` counts declared paths not listed.
+
+**`response` promises no readability.** Value safety runs on every read. A
+value at any listed path, hinted or not, may still be withheld or redacted at
+read time. An unlisted path may be too, so never treat it as safe. Many rules
+depend on the values a vendor returns, which no index knows in advance:
+
+- An expanded or polymorphic object is redacted by its type: for example, a
+  Stripe event's `data` or a Checkout Session's expanded `payment_intent`
+  loses a payment intent's `client_secret`.
+- An opaque container is redacted by its contents: Google Docs
+  `inlineObjects` loses image `contentUri` capabilities, and Vercel drain
+  `headers`, deployment `env` and `protectionBypass` keys are withheld.
+- A labelled or typed record is redacted by its label or type.
+- URLs carrying credentials are sanitized. QuickBooks replaces every http(s)
+  URL in a returned string, including ordinary text such as a Customer
+  `DisplayName` or `CompanyName`, with `[redacted]`.
+- A value echoing a secret the request sent is redacted.
+
+Paths list shallowest first, in index order, up to 100 paths and 4,096
+characters of path JSON, the hint included; a path over 200 characters is
+never listed. The pinned index carries names only, never response types or
+example values. Only the first page of a whole-operation answer carries
+`response`; `param` answers and continuation pages omit it. An operation
+without declared response properties has no `response`, and its reads refuse
+`fields`.
+
 Maintained REST hatches validate path parameters against their pinned contracts
 before dispatch. Integer ids use canonical ASCII decimal notation within the
 safe-integer range and obey the operation's declared bounds; for example,

package/examples/worker/AGENTS.md

@@ -95,16 +95,16 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   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.
+  `<agent>` for the lowest and `<agent>-<tier>` above it. Every pool lists
+  only people or only `agent:` references; mixing them throws at
+  construction. Tiers and `<agent>-<user>` pools list only the agent. People
+  with a tier's reach get their own people-only pool (for example `team`
+  beside `assistant-team`) spreading the same tool-list constant. 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. 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

@@ -380,9 +380,10 @@ declared agent, is available to signed-in maintainers.
 ## Select optional modules
 
 `cloudflareAccessAuth()` reads trusted identity after Access admits the Worker
-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
+request. Maintainers use plain `/mcp` and the operator pages; people in a
+people pool use `/mcp/<pool>` (or plain `/mcp` when it is their only pool), and
+agents in an agent pool use `/agent/<pool>`; each serves 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

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

@@ -111,6 +111,7 @@ export default defineConfig((env: Env) => {
     // 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.
+    // Each pool lists only people or only agents; share tool lists across separate pools.
     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),

package/guides/connecting-agents.md

@@ -11,7 +11,8 @@ has exact setup and verification steps.
 
 Imagine an agent named `assistant` that helps with CRM records and tickets.
 Its operator creates a pool with the actions needed for that job and adds
-the agent as a member. The pool can be read-only if updates must be impossible.
+the agent as a member. Agent pools contain only agents; people use separate
+pools that can share the same tool list. The pool can be read-only if updates must be impossible.
 
 ```mermaid
 flowchart LR

package/guides/how-it-works.md

@@ -41,7 +41,7 @@ For setup and migrations, see [Integrating services](../documentation/integratin
 
 A **pool** is a named selection of tools and the people or agents allowed
 to use them. The operator creates it and gives it an **endpoint**: a
-connection address for that pool.
+connection address for that pool. Each pool lists only people or only agents.
 
 One pool might let the assistant read CRM records. Another might let a
 person update tickets. Tools and accounts are separate choices: a pool
@@ -65,7 +65,9 @@ choose the right one for the conversation. The model does not choose its
 own access level.
 
 Maintainers run the deployment and can reach its whole tool list through
-the main human endpoint. Other people use their assigned pools.
+the main human endpoint, `/mcp`. Other people use their assigned pools. A
+person in exactly one pool can use that same `/mcp` address: their sign-in
+selects the pool, and they get only its tools.
 Agents use shared accounts selected by the operator. They do not inherit
 the account of the person chatting with them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.38.0",
+  "version": "0.40.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.",

package/templates/node/AGENTS.md

@@ -33,8 +33,9 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   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`
+  Plain `/mcp` serves `maintainers` the whole catalog and each other person
+  in exactly one pool that pool; people also 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`
@@ -45,16 +46,16 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   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.
+  `<agent>` for the lowest and `<agent>-<tier>` above it. Every pool lists
+  only people or only `agent:` references; mixing them throws at
+  construction. Tiers and `<agent>-<user>` pools list only the agent. People
+  with a tier's reach get their own people-only pool (for example `team`
+  beside `assistant-team`) spreading the same tool-list constant. 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. 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/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.38.0",
+    "@zackbart/connecta": "0.40.0",
     "quickjs-emscripten": "0.32.0",
     "undici": "6.29.1"
   },

package/templates/node/src/connecta.config.ts

@@ -102,6 +102,7 @@ export default defineConfig((env: Env) => {
     // `npm run doctor` checks /agent/local-machine with its token. The starter
     // pool is the agent's base pool, its lowest tier (shared connectors, no
     // owner), named after the agent as the agent pool layout requires.
+    // Each pool lists only people or only agents; share tool lists across separate pools.
     pools: { "local-machine": { tools: ["time"], members: ["agent:local-machine"] } },
     // Machine clients are agents declared here by name, each with one cta_
     // token. Issue or rotate one locally with