@zackbart/connecta 0.38.0 → 0.40.0

package/documentation/meta-tools.md

@@ -49,7 +49,12 @@ write tools from `search_tools` results and describe, and refuses every write
 call. Connector `readOnly` applies the same restriction on every endpoint; effective read-only is endpoint OR connector. Neither setting changes connector visibility or read grants. Guides
 (`queryAnalysis.guideSummary`, `skills`, `connecta.skill`, skill
 `resources/read`) are documentation and may name tools the endpoint refuses. The four tools with structured-only success results
-advertise `outputSchema`. The two direct-call tools omit it because their default
+advertise `outputSchema`. `search_tools`'s schema defines its typed failure,
+including every authorization-handoff field, once under `$defs.failure`;
+`catalogErrors[]` references it through `allOf` with `connector` required, and
+`queryAnalysis.catalogError` references it directly. The schema declares no
+`$schema`, and validators for drafts 4, 7, 2019-09 and 2020-12 accept the same
+pages. The two direct-call tools omit it because their default
 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.
@@ -134,16 +139,25 @@ Live connector probing is not a fourth: the operator pages and `/health` own it.
 
 ## Discovery context
 
-The deployment-derived `execute_code` description carries a live connector
-inventory before any catalog search — registry order, each canonical id, and a
-distinct configured title, with no second name minted for programs. Titles
-normalize whitespace and cap at 48 UTF-8 bytes, the complete line caps at 256,
-entries stay whole, and a truncated line ends with the exact `+N more` count, so
-account and environment hints cannot eat the inventory. It reads only the
-configured registry: no catalog load, no credential probe, no capability, and no
-replacement for canonical discovery or addressing. Program search results carry
-the same bounded `connectorTitle` per tool, so choosing an account or
-environment costs no provider read. The inventory does not probe live access.
+The deployment-derived `execute_code` description carries a connector
+inventory before any catalog search — registry order and each canonical id,
+with no second name minted for programs. An entry adds the configured title
+only when it says more than the id: a title whose words the id already spells,
+such as `Google Calendar` for `google_calendar`, is dropped. Titles normalize
+whitespace and cap at 48 UTF-8 bytes. A connector with a guide says how to
+fetch it: `read first: skills({name:"connector:<id>"})` for a required guide,
+`guide: skills({name:"connector:<id>"})` otherwise. For example:
+`Connectors: crm (Customer CRM; read first: skills({name:"connector:crm"})), tickets.`
+
+The complete line caps at 1,024 UTF-8 bytes, which names every connector of a
+typical deployment. Past the cap, detail degrades before names do: titles are
+dropped first, then optional guide pointers. Only when bare ids and required
+guide pointers still exceed it do whole entries give way, in registry order, to
+an exact `+N more` count. The inventory reads only the configured registry: no
+catalog load, no credential probe, no live status, no capability, and no
+replacement for canonical discovery or addressing. Search pages carry the same
+bounded title once per connector in `connectors[<id>].title`, so choosing an
+account or environment costs no provider read.
 
 Read-only lookup belongs in `connecta.search` inside the program; top-level
 `search_tools` stays for explicit catalog inspection and approval-required
@@ -171,6 +185,56 @@ read/write filter. On `approvalRequired` searches the returned discovery tool
 is still a read. Hidden tools, missing grants and read-only restrictions remain
 in force. Browsing does not consult operation vocabulary.
 
+When a matched operation's call is fully determined, the first page also
+carries it in `readyCalls`, so a program can call it without operation search or
+details:
+
+```json
+{
+  "readyCalls": [
+    {
+      "address": "notes.notes_api_read",
+      "args": { "path": "/v1/notes" },
+      "classification": "read",
+      "summary": "List notes"
+    }
+  ]
+}
+```
+
+Pass `args` unchanged to `connecta.call(address, args)` or `call_tool`. An
+operation is fully determined only when it is a reviewed read served by the
+hatch's `_api_read` tool itself (no named tool), uses GET, the read tool's
+default method, and declares no path template, required parameter or required
+body. Anything needing an id, a method choice or an argument the agent must
+fill in stays behind `_api_search` and `_api_details`. Ready calls pass the same
+endpoint, connector read-only, safety, hidden-tool and grant checks as the
+vocabulary match, through a visible read tool in the caller's view. They are
+computed offline from the construction-time index, read no account data, and
+start no authorization.
+
+A ready call must also be what the query names. Each path segment, and the
+operationId without its action and version words, is one whole resource name:
+`event_destinations` is the name "event destination", never "event". Every
+query word other than an action (`list`, `get`, `count`, `show`, `create`,
+`update`, `delete` and their vocabulary aliases) must belong to a resource name
+whose words the query states in order, with singular/plural normalization and
+the provider's declared synonyms. Version segments such as `v1` never count, and
+a summary may supply only actions. A query with no object word gets no ready
+call. Ready calls are omitted entirely when the top result is an exact tool name
+or address, or a complete match on an authored tool, not the hatch's own search
+or read tool, whose name adds nothing to the query: each of its name words is an
+action or a query word, up to plural/singular and declared synonyms. For
+example, `list teams` returns `list_teams` and no ready call, even when other
+operations mention teams in their summaries, while `list projects` still offers
+`/v10/projects` beside `list_project_env_vars`, whose name adds `env` and `vars`.
+Each hatch offers only its top-ranked operation: a last path segment naming the
+resource first, then the fewest resource words the query did not ask for, then
+the shortest path. A connector offers at most one ready call and a page at most
+three, in connector order. Later pages carry none. A ready
+call keeps its read tool's `guideRequired` and `guideRequiredReasons`, and its
+connector appears in `connectors`.
+
 Vocabulary is bounded: queries at most 200 characters and eight terms; each
 hatch caches at most 8,192 rows and 2,097,152 characters, with at most 1,024
 characters per row and 128 query intersections. Longer queries and vocabulary
@@ -281,9 +345,11 @@ guide's first meaningful body paragraph. `required: true` is reserved for
 generic API wrappers and cross-operation conventions a complete downstream
 schema cannot express.
 
-Search and describe results carry a `guide: "connector:<id>"` pointer and a
-`guideSummary`. A matching tool also carries `guideRequired: true` and
-`guideRequiredReasons` when Connecta can prove review is necessary:
+Describe results carry a `guide: "connector:<id>"` pointer and a
+`guideSummary`; a search page carries both once per connector in
+`connectors[<id>]`. A matching tool row or description also carries
+`guideRequired: true` and `guideRequiredReasons` when Connecta can prove review
+is necessary:
 
 | Reason               | Raised by                            | Survives exact schema expansion                          |
 | -------------------- | ------------------------------------ | -------------------------------------------------------- |
@@ -297,8 +363,17 @@ is merely told to fetch the guide first, for any reason listed. Otherwise the
 bounded summary decides — connector-specific sequencing, units, pagination,
 aliases, and generic API conventions still need the guide when they affect the
 task, while a complete and unambiguous one-read schema proceeds directly. Guide
-lookup always uses an exact name returned by `skills({})`, search, or describe;
-callers never manufacture `connector:<id>` from an unmarked connector.
+lookup uses an exact name returned by `skills({})`, search, describe, or the
+`execute_code` inventory; callers never manufacture `connector:<id>` from an
+unmarked connector. A bare connector id, such as `skills({ name: "crm" })` or
+`connecta.skill("crm")`, also serves that connector's guide. Built-in skill
+names stay reserved: `usage` and `investigate` always fetch the built-in skill,
+even when a connector has that id, whose guide stays at `connector:usage` or
+`connector:investigate`. A bare id naming a connector without a guide fails with
+`Connector "<id>" has no usage guide.`; any other unknown name fails as an
+unknown skill. Names containing `:`, including URIs, never fall back to a bare
+id. MCP `skills/get` resolves names the same way; `resources/read` accepts only
+document URIs.
 
 A connector-scoped lexical miss keeps that connector's guide metadata under
 `queryAnalysis`. This matters for generic wrappers whose broad tool name
@@ -307,12 +382,29 @@ disappearing with the zero-tool page.
 
 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
+differences, and repair guidance; `investigate` is domain-neutral on-demand
+guidance for an investigation that spans several services — shared guidance,
+not a saved workflow and not a source of deployment-specific ids. `skills`
+lists it; the `execute_code` description does not advertise it. 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.
+
+The server instructions state the complete routing rule once. Some clients
+drop server instructions, so each tool description stays sufficient for its own
+correct use without restating that rule: `call_tool` names its scope (one
+known-address read) and points other read work to `execute_code`;
+`search_tools` names its scope (catalog inspection, or finding a write) and
+points read work into a program; `execute_code` opens with the terse
+three-route lead (`One known read: call_tool. One known write:
+call_destructive_tool. Everything else: execute_code.`, or the read-only
+two-route form). The `usage` skill points to those two sources instead of
+repeating them.
+
+Tool descriptions and output schemas carry deployment configuration only: the
+connector inventory, budgets, the endpoint's read-only setting, and whether any
+visible connector has a guide. No catalog outcome, call, authorization state,
+or other live status reaches `tools/list` or the instructions, so the
+always-loaded surface stays byte-stable for a client's prompt cache.
 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
@@ -618,7 +710,7 @@ a fixed warning without storage error prose. Never repeat a write to recover out
 page. Select tool rows from `page.tools`.
 With the same schema format, schema-key option, and scoped registry, both paths
 return identical data. Top-level search omits schemas unless requested; programs
-default to JSON schemas and schema-key metadata.
+default to TypeScript signatures and schema-key metadata.
 
 ```json
 {
@@ -627,12 +719,12 @@ default to JSON schemas and schema-key metadata.
     {
       "name": "get_ticket",
       "address": "tickets.get_ticket",
-      "connectorTitle": "Tickets",
       "classification": "read",
       "schemaFormat": "json",
       "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }
     }
   ],
+  "connectors": { "tickets": { "title": "Tickets", "guide": "connector:tickets", "guideSummary": "Ticket ids and states." } },
   "total": 1,
   "offset": 0,
   "limit": 8,
@@ -652,8 +744,26 @@ and connector id, never connector-supplied error text. Other failures retain
 `retryAfterMs`. A scoped search also keeps its bounded failure subset under
 `queryAnalysis.catalogError` for clients that already use it.
 
-Tool rows carry the address, configured display title when present, guide and
-guide summary when available, and stored classification. Requested schemas have
+An unscoped search gives each connector at most 5 seconds (or
+`discovery.probeTimeoutMs` when shorter) and ends within a 9-second discovery
+budget. A connector that recently timed out or failed slowly is skipped for up
+to 60 seconds: its entry keeps the recorded code with `retryable: true`,
+`retryAfterMs`, and the message `Connector "X" was skipped because its catalog
+lookup failed recently (CODE). Search with connector "X" to try it now.` A
+scoped search always probes. Records are kept per owner, admitted endpoint and
+described connector configuration. A healthy connector whose catalog always
+takes more than 5 seconds can stay out of unscoped search; search it with
+`connector`, or let any longer-deadline operation warm its complete catalog.
+See [Discovery health](./architecture.md#storage-credentials-and-connectors).
+
+Tool rows carry the address, stored classification, and tool-specific
+`guideRequired` and `guideRequiredReasons`. Facts shared by every row of one
+connector appear once per page in `connectors`, keyed by the connector id that
+prefixes each row's address: the configured display `title` when present and
+`guide` and `guideSummary` when the connector has a guide. The map names only
+connectors with a row or ready call on this page and is omitted when none has
+such facts.
+Requested schemas have
 `schemaFormat: "json"` for JSON Schema values or `schemaFormat: "text"` for
 compact schema strings and TypeScript signatures. Compact schemas are text;
 `inputSchema.properties` is meaningful only in JSON mode. Pagination counts
@@ -666,7 +776,19 @@ rare domain terms above ubiquitous action terms. Exact tool names and canonical
 addresses rank first, so `get_issue` beats `get_issue_status` even when a
 connector is named `issue`. Exact configured connector IDs, full display titles,
 and recognized service names rank next. Complete lexical matches then precede
-partial matches, with score and catalog order breaking ties.
+partial matches. Within a tier, a query whose first word outside connector names
+is `list`, `get`, `find`, `search`, `show`, `read`, `fetch`, or `count` ranks
+read rows before write rows; writes stay on the page. Score and catalog order
+break the remaining ties.
+
+A maintained provider may declare `searchSynonyms`: groups of single lowercase
+words its users and its vendor use for the same record, such as `household`
+and `family` for Church Community Builder. A query word then matches that
+provider's tools and operation vocabulary through any word in its group, as an
+ordinary whole-token match ranked below the word itself. Synonyms never widen
+another connector's matches. Church Community Builder declares
+`person`/`individual` and `household`/`family`; Granola declares
+`meeting`/`note`.
 An exact connector ID or title query browses that connector's tools, even when
 individual tool names or descriptions mention that identity. Connector identity
 terms that never occur in its tools need not be repeated in every tool description.
@@ -783,6 +905,16 @@ fulfill downstream input.
 
 ## Authorization recovery
 
+Every native pool lists `authorize_connector`, including pools without code.
+If a connector’s tools are missing, use its id from that tool’s granted-connector
+list to request a typed handoff. Give the URL and instructions to the operator;
+after repair the host must refresh its tool list before it can call the repaired
+tools (the cache hint is 300 seconds). A host that keeps its first list needs a
+reconnect or a new conversation; on a pool with `execute_code`, a program can call
+them by address without one.
+Listing never creates a handoff. Authorization accepts only connectors already
+granted to this request; it cannot enable a connector or expand pool scope.
+
 On MCP 2026-07-28, a host declaring `elicitation.url` receives
 `resultType: "input_required"` when an eligible call or program needs recoverable
 connector authentication and the admitted identity may manage that connector.
@@ -1027,28 +1159,77 @@ A remote MCP tool's advertised `inputSchema` is checked in the shared invocation
 path before admission and provider dispatch, so a mismatch is the non-retryable
 `invalid_args` identically on `call_tool`, `call_destructive_tool`,
 generated-code failures, and rejected promises. The error names the connector and
-operation and carries `validation.issues`: JSON Pointer `path`, schema-keyword
-`code`, and expected shape, with submitted values never copied into a finding. At
-most three are returned, and `validation.truncated` says when more exist — the
-same three-item bound describe's nearby-address list uses.
+operation and carries one recovery envelope, `validation`:
+
+```json
+{
+  "issues": [
+    { "path": "/limit", "expected": "at least 5", "received": "4" },
+    { "path": "/mode", "expected": "one of \"fast\", \"safe\"", "received": "string" },
+    { "path": "/<key>", "expected": "one of the accepted keys: mode, limit" }
+  ],
+  "acceptedKeys": ["mode", "limit"],
+  "example": { "mode": "fast", "limit": 5 }
+}
+```
+
+Every finding is listed, and the message repeats them, so one corrected call
+fixes them all.
+
+A refusal contains only names and literals the published schema declares at
+non-sensitive positions, numbers allowed by the bound rule below, and fixed
+placeholder text. It never contains a submitted string or object key, in the
+message, a finding, `acceptedKeys` or the example. A position is sensitive when
+it or an ancestor is `writeOnly`; a named tool's input schema marks each request
+secret that way. API hatch findings name only the operation contract's
+properties and enum members, as `*_api_details` publishes them.
+
+- `path` is a JSON Pointer naming declared properties and array indices. The
+  first key the schema does not declare (a misspelled argument, a map key)
+  reads `<key>` and ends the path, e.g. `/headers/<key>`.
+- `expected` states the constraint that failed, then every other constraint
+  the position declares: bounds, property and item counts, `multipleOf`,
+  `pattern`, `format`, `uniqueItems`, enum members, `dependentRequired`
+  (`string (required with tags)`). A sensitive position never renders an enum,
+  `const` or pattern literal. Each position gets one finding.
+- `received` is the submitted JSON type, `missing`, or, for a numeric bound at
+  a non-sensitive position of a named tool, the submitted number.
+
+At most eight findings are returned, each field clipped (path and expected 256
+characters, received 64), and `truncated: true` says something was omitted or
+clipped.
+
+`example` is one valid call synthesized from the published schema and checked
+against the same validator. It never copies a submitted value, and a sensitive
+position never renders a schema literal (`enum`, `const`, `default`,
+`examples`). Complex or unsatisfiable schemas get `exampleUnavailable` instead.
+Synthesis detects recursive references and shares a 128-node work budget.
+Invocation uses only this schema example, never a connector's copy of the
+call, unless the connector states `exampleUnavailable`. API hatches
+(`*_api_read`, `*_api_write`) always do: their generic schema says nothing
+about an operation's arguments, so the reason points to the operation's
+`*_api_details`.
+
+`acceptedKeys` names the tool's top-level arguments. `conditionalRequirements`
+lists known `dependentRequired` and `dependentSchemas` requirements by
+property name; `if`/`then`/`else` conditions are schema subtrees and are not
+rendered. The envelope has a 4 KiB budget:
+optional detail, then the example, then trailing findings are dropped whole,
+with `truncated: true`. A `repair` object a custom connector passes contributes
+its received types and schema facts. A custom connector's own findings must
+follow the same rule. Operator records contain only checked failure facts,
+never findings or examples.
 
 `nextAction` points to discovery scoped to the same connector and tool name when
 the compact schema is needed, routed like any other miss: a program to
 `connecta.search`, a top-level call to `search_tools`. `retry` says to correct
-the listed arguments and reissue the original operation. Which keyword a finding
-names, and what the local validator declines to evaluate, is
-[code mode](./code-mode.md#errors)'s `E8`.
-
-`repair` adds agent-only detail from that tool's published schema: accepted
-keys, received JSON types, enum values, numeric/length/item bounds, and known
-conditional requirements such as `dependentRequired` and `if`/`then`/`else`.
-Its `example` is synthesized without submitted values and checked against the
-same validator. Complex or unsatisfiable schemas get `exampleUnavailable`
-rather than an invalid example. Synthesis detects recursive references and
-shares a 128-node work budget. Alternative branches do not emit dependency
-advice unless the branch condition is known. Repair detail has a 4 KiB budget; oversized
-detail is withheld whole with `truncated: true`. Operator records still contain
-only checked failure facts, never findings or examples.
+the listed arguments and reissue the original operation. What the local
+validator declines to evaluate is [code mode](./code-mode.md#errors)'s `E8`.
+
+Earlier releases returned `validation.issues[].code` (the schema keyword)
+and a separate `repair` object. Both are gone from responses; a custom
+connector may still pass `code` and `repair` to `ConnectorCallError`, which
+folds `repair` into `validation`.
 
 Unknown-address errors list `configuredConnectors` from the current endpoint's
 scoped registry, including an empty list when none are accessible. They never
@@ -1146,7 +1327,9 @@ its code and message for diagnostics but is `retryable: false` with
 a program's `writes.unknown`. An HTTP refusal of the call's own write stays
 known only under the refusal rules above and a complete ledger proving the
 refusal covers the whole call; its recovery advice and program accounting both
-report failure. Partial or unknown ledgers remain conservative. An auth failure after entering a write with
+report failure. A `remoteMcp()` write answered with a 4xx (other than 401, 403,
+408 or 429) whose body is not a JSON-RPC error is unknown, never a refusal: a
+gateway may have answered after the server acted. Partial or unknown ledgers remain conservative. An auth failure after entering a write with
 no call-owned dispatch reports an unknown outcome and requires reconciliation,
 including credential refusals, static-OAuth refresh failures, and `remoteMcp()`
 connect or initialize 401s before `tools/call`. A non-auth refusal before
@@ -1264,10 +1447,10 @@ pool's surface.
 | Each visible downstream tool | Named `<connector>__<tool>`; object input constraints and local references preserved; no `outputSchema`; `_meta["dev.connecta/address"]` is its address           |
 | `execute_code`               | Unless `executeCode: false`. Each downstream tool's description then ends with `Program address: <connector>.<tool>`, the address `connecta.call` takes           |
 | `read_result`                | Only with `executeCode: false`: `{ id, offset?, page?, maxBytes? }` pages a stashed result exactly as `connecta.result` does, with the same bindings and rechecks |
+| `authorize_connector`        | Always; requests the existing typed authorization handoff for a granted connector                                                                                 |
 | `skills`                     | Always                                                                                                                                                            |
 
-`search_tools`, `call_tool`, `call_destructive_tool`, and `authorize_connector`
-are not listed. Auth failures still carry their handoff in the error envelope.
+`search_tools`, `call_tool`, and `call_destructive_tool` are not listed. Auth failures still carry their handoff in the error envelope.
 
 **Names.** A name is a pure function of the connector id and downstream tool
 name, so it survives catalog refreshes. It is `<connector>__<tool>` when the
@@ -1311,7 +1494,7 @@ window, a native `tools/list` carries a 300-second private cache hint, against
 an hour on meta endpoints. This hint does not guarantee that a host refreshes
 its cached annotations; the stale-approval race is accepted on writable pools.
 
-**Listing.** `tools/list` is one page with no cursor (Eve 0.86 reads only the
+**Listing.** `tools/list` is one page with no cursor (Eve's MCP client reads only the
 first page). A pool listing more than 1,000 tools fails `tools/list` with a
 JSON-RPC error asking the operator to narrow the pool; nothing is silently
 dropped. A connector whose catalog cannot load is left out of that listing
@@ -1325,10 +1508,18 @@ reduced calls; write tools are absent and refused on a read-only endpoint;
 never repeat a write; page a truncated result as its notice says. A pool
 `description` is appended as on meta endpoints.
 
-**Recovery.** Repair and validation fields retain the exact constraint details.
+**Recovery.** `authorize_connector` remains listed even when a catalog fails.
+Its description lists all granted connector ids independently of catalog health.
+Use it for a missing connector, then refresh the host tool list after repair.
+Endpoint instructions carry the same recovery rule for hosts that fetch them
+separately. A cached list retains the recovery tool; a refreshed list restores
+the repaired connector’s whole catalog.
+
+Repair and validation fields retain the exact constraint details.
 Discovery `nextAction` points to the host's tool search (`host: "search"`), with
 only a `query` argument. Retry actions and retry text name the native tool,
-never a meta wrapper. Auth actions carry `authorizationUrl` or `operatorUrl`;
+never a meta wrapper; a program on a native pool sees the same native wording
+in a failure it catches. An unknown name is reported as sent. Auth actions carry `authorizationUrl` or `operatorUrl`;
 give the returned URL and instructions to the user or operator. Capable modern
 clients may resume native auth and downstream form/URL input with the same
 wire name, arguments and returned `requestState`. Changed names, targets or

package/documentation/migration-0.33.md

@@ -40,6 +40,10 @@ the sections in order, then [verify](#verify).
 | `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                                                                         |
 
+This guide records the 0.33 migration. Current versions require every pool to
+list only people or only agents. If a 0.33 deployment combined them, follow
+[Split mixed pools](./pool-membership-upgrade.md) as well.
+
 ## Maintainers and pool members
 
 0.32 combined an identity resolver, a top-level `grant`, and pool `grant`
@@ -349,4 +353,4 @@ pools: {
    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`.
+6. Confirm each `<agent>-<user>` pool lists only the agent in `members` (the current construction rule).

package/documentation/migration-0.34.md

@@ -39,7 +39,9 @@ If an agent needs to act as Alice, put that access in her personal pool and set
 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.
+with a fixed `subject` address keep their behavior. Current versions also
+require each pool to list only people or only agents; see
+[Split mixed pools](./pool-membership-upgrade.md).
 
 ## Optional settings and development tooling
 

package/documentation/operator-tests.md

@@ -24,7 +24,7 @@ committed through the deployment's own store, so the contract's `agents` and
 last seen are fixed. The restricted state is the member fixture from
 `test/fixtures/operator-contract-v2.ts`, and the endpoint and matrix variants
 use its maintainer fixture, which covers every runs-as kind and agent pools,
-with `test/fixtures/operator-console.ts` crowding the team pool so its avatar
+with `test/fixtures/operator-console.ts` crowding the people-only team pool so its avatar
 stack collapses to "+3".
 Collections use their corresponding browser types. Real contract serialization,
 member projection and secret withholding are exercised through