@zackbart/connecta 0.33.0 → 0.34.1

package/documentation/integrating.md

@@ -3,6 +3,21 @@
 Use this guide to change connectors in deployment configuration.
 [All agent routes](./README.md) are in the index.
 
+## Make one connection read-only
+
+Every connector accepts optional `readOnly?: boolean`, defaulting to `false`:
+`remoteMcp("notes", { url: "https://notes.example.com/mcp", auth: { type: "headers", headers: {} }, readOnly: true })`,
+`api("tickets", { readOnly: true, tools: [] })`, and maintained providers such as
+`stripe("billing", { purpose: "Revenue reports", auth: { type: "oauth" }, readOnly: true })`.
+A custom `Connector` sets `readOnly: true` on its connector object.
+
+Only tools classified read appear in search and describe, and every write or
+unclassified tool call is refused before dispatch on every endpoint, including
+maintainers' plain `/mcp`, programs, `call_tool`, and `call_destructive_tool`.
+Effective read-only is endpoint `readOnly` OR connector `readOnly`; connector
+`false` never widens an endpoint. Existing pool/deployment inheritance is unchanged.
+Guides may still name unavailable tools. The operator UI shows a Read-only badge.
+
 ## Add or remove a connector
 
 Connectors are code-owned. Edit the deployment's `src/connecta.config.ts`;
@@ -19,8 +34,10 @@ To add one:
 3. Add the id (all its tools) or exact `id.tool` addresses to the intended
    pools' `tools`. Maintainers at plain `/mcp` already see the whole catalog.
    Follow [the agent pool layout](./auth.md#organizing-an-agents-pools) for an
-   agent: shared connectors go in its base constant, per-user connectors only
-   in that user's pool.
+   agent: a shared connector goes in the tool list of the lowest tier whose
+   entire audience is authorized to use it (billing restricted to leads goes
+   in the leads tier); per-user connectors and Workspace connectors with a
+   mapping `subject` go only in personal pools.
 4. Run the deployment's `npm run typecheck` (Worker copies: `tsc --noEmit`),
    restart Node or redeploy the Worker, and
    [connect its credential](./auth.md#connect-a-shared-credential) if needed.
@@ -38,14 +55,15 @@ const crm = remoteMcp("crm", {
   authScope: "shared",
   auth: { type: "credential", credential: { label: "CRM API token" } },
 });
-const assistant = { tools: ["crm", "tickets"], members: ["agent:assistant"] };
-// connectors: [crm, tickets], agents: ["assistant"], pools: { assistant }
+const base = ["crm", "tickets"]; // the agent's lowest tier
+// connectors: [crm, tickets], agents: ["assistant"],
+// pools: { assistant: { tools: base, members: ["agent:assistant"] } }
 ```
 
 To remove `crm`, first disconnect its OAuth grant or delete its saved
 credential while the connector still exists, using a signed-in maintainer
 for shared auth. Each person disconnects their own personal account. Remove
-`crm` and all `crm.*` addresses from every pool (including base constants),
+`crm` and all `crm.*` addresses from every pool (including tier tool lists),
 then remove its entry from `connectors`, unused imports, and unused secret
 configuration. Remove any pools left with no tools (empty `tools` fails
 construction), and update or retire clients pointing at those pools. Typecheck, restart/redeploy, run doctor, and confirm discovery
@@ -89,10 +107,10 @@ const tracker = linear("tracker", {
 ```
 
 Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from a Connecta `readOnly` endpoint. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
+read scope. That is separate from Connecta endpoint or connector `readOnly`. Read the installed `dist/providers/linear/index.d.ts` for API-key framing,
 workspace instructions, and admission choices.
 
-The [human README](../README.md#what-you-can-do-with-it) lists available
+The [human README](../README.md#what-you-can-connect) lists available
 integrations. In the installed package, `dist/providers/<name>/index.d.ts`
 and its imported declarations describe each factory's options. After adding
 a connector, use `search_tools` to discover its current tools and `connecta.skill("connector:<id>")` in `execute_code`
@@ -104,6 +122,34 @@ pool's `owner` instead ([auth guide](auth.md#pool-owners-for-google-workspace)).
 A request must not choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
+Intercom uses `intercom()` from `@zackbart/connecta/providers/intercom`:
+
+```ts
+import { intercom } from "@zackbart/connecta/providers/intercom";
+
+const support = intercom("support", {
+  purpose: "Customer support triage",
+  region: "eu",
+});
+// Add support to the deployment's connectors array.
+```
+
+Set `region` explicitly to `"us"` or `"eu"` to match the workspace; AU is
+unsupported. OAuth defaults to personal ownership because it acts as the
+authorizing teammate. Non-loopback OAuth callbacks require an Intercom Customer
+Support allowlist entry for the deployment's redirect URI before authorization
+can complete. Alternatively, set `auth: { type: "credential" }` and connect an
+API token through the [shared credential procedure](./auth.md#connect-a-shared-credential);
+token auth defaults to shared ownership. Fin Operator tools require OAuth,
+workspace availability and teammate permission. Their expected absence adds no
+missing-tool drift; missing core tools still do. Schema coverage reports all
+present reviewed tools as unpinned. Article operations, internal
+notes and Operator actions can write; a note can reopen a snoozed conversation.
+Use a read-only endpoint when writes are unwanted. Catalog review is based on
+[Intercom's docs](https://developers.intercom.com/docs/guides/mcp), with unpinned
+schemas; inspect live tools and the runtime guide before acting on sensitive
+customer data.
+
 Wispr Flow uses OAuth only through `wisprFlow()` from
 `@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
 Notetaker content, with personal and work accounts holding separate data.
@@ -113,6 +159,8 @@ reviewed classification includes task writes listed in Claude's directory even
 though Wispr's public help describes read-only access; discover the account's
 actual tools before assuming those writes exist.
 
+For minimal Stripe OAuth/API-key examples with and without connector `readOnly`, see [Stripe setup](./provider-auth-migration.md#stripe). With an API key, prefer a restricted `rk_` key with only read permissions for read-only access; Stripe enforces it too.
+
 Stripe requires `auth`: `{ type: "oauth" }` reaches Stripe's hosted MCP
 server, and `{ type: "apiKey" }` with `mode` reaches Connecta's REST connector
 with an operator-managed key. Notion requires `auth` the same way:
@@ -218,6 +266,15 @@ for precedence, schema digests, and `unlisted: "hide"`. Review the behavior
 before declaring a read, and do not use classification to bypass provider target
 scopes or caller grants.
 
+A reviewed name is required by default for drift comparison. Mark a tool
+`optional: true` only when the downstream can omit it because of plan,
+feature, or permission gating. For example, a remote `crm` connector can use
+`classify: { tools: { list_accounts: "read", list_customers: { verdict: "read",
+optional: true } } }`. Absence of `list_customers` then adds no unserved count;
+when present, its verdict, annotations, and any pinned schema are still checked.
+A missing schema pin means that tool's schema has not been verified against a
+review. Zero schema changes alone does not establish a matching schema.
+
 ## A hand-written HTTP capability
 
 Define only the operations the deployment needs. Every `api()` tool needs a

package/documentation/meta-tools.md

@@ -35,7 +35,7 @@ is annotated `readOnlyHint: true, destructiveHint: false` on a read-only
 endpoint, and `readOnlyHint: false, destructiveHint: true` on a writable one.
 Approval belongs to the client. A read-only endpoint keeps all six tools, omits
 write tools from `search_tools` results and describe, and refuses every write
-call; `readOnly` never changes connector visibility or read grants. Guides
+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
@@ -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.
 
@@ -221,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
@@ -253,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.
@@ -386,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
@@ -394,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,
@@ -426,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",…
 ```
 
@@ -458,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
@@ -521,7 +533,7 @@ cap and a 32 KiB program bridge ceiling, with UTF-8 alignment and forward progre
 returning pages unchanged can hit the program result cap. The admitted subject
 and principal, endpoint/pool, request origin, connector, and tool bindings must
 match. The host rechecks current access and whether the endpoint is read-only
-before returning each page; a read-only endpoint cannot read a write stash.
+before returning each page; a read-only endpoint or connector cannot read a write stash.
 Caller arguments select no partition. A read-only endpoint never runs a write,
 so every write result it could page came from a writable endpoint.
 
@@ -682,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.
@@ -965,12 +977,14 @@ Handlers and schemas live in [meta-tools.ts](https://github.com/zackbart/connect
 [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

@@ -127,7 +127,12 @@ 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`.
+   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
@@ -205,7 +210,8 @@ membership contract.
 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, and fails `auth_required` in a pool without one. People always act
+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.
 
@@ -303,24 +309,26 @@ pools: {
 // 0.33
 agents: ["assistant"],
 pools: {
-  assistant,
-  "assistant-alice": { ...assistant, tools: [...assistant.tools, "notes_alice", "gmail"], owner: "alice@example.com" },
-  "assistant-bob": { ...assistant, tools: [...assistant.tools, "notes_bob", "gmail"], owner: "bob@example.com" },
+  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 assistant = { tools: ["crm", "tickets"], members: ["agent:assistant"] };
+// 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 `<agent>` once with the shared connectors and
-   `members: ["agent:<agent>"]`, and spread it into one `<agent>-<user>` pool
-   per person, adding that person's connectors and `owner`.
+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, `/agent/<agent>`
-   otherwise. Remove any second Connecta connection.
+   `/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:
 
@@ -339,6 +347,6 @@ pools: {
 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`. `auth_required` is what an agent gets only in a pool
-   without an owner that does list a Workspace connector.
+   `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

@@ -24,7 +24,7 @@ descriptions. On a writable endpoint, programs and `call_destructive_tool` may
 write within the caller's grants, and `execute_code` is annotated as a write;
 the client controls approval. On a read-only endpoint, search and describe omit
 write tools and every write call is refused with `read_only_endpoint`, even one
-a connector guide names; tell the user rather than looking for another route. Never change pool, identity, or `readOnly` to work
+a connector guide names; tell the user rather than looking for another route. A connector marked Read-only serves only read-classified tools even on a writable endpoint; writes and unclassified tools are omitted from search/describe and refused on every call path. Endpoint and connector restrictions compose by OR. Never change pool, identity, or `readOnly` to work
 around a refusal.
 [Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
 owns the full decision rules.

package/documentation/operator-tests.md

@@ -13,15 +13,19 @@ or browser evidence. Read the [operator UI contract](./operator-ui.md) first.
 `test/fixtures/operator-visual.ts` owns the visual data. It builds the
 maintainer's contract v2, live overlay, and legacy auth details through the
 current server routes, using the types in `src/operator-ui/contract.ts` and
-`model.ts`; its people carry labels from a fake directory. Its Tokens agents
+`model.ts`; its people carry labels from a fake directory. It sets a few
+limits, an activity retention, one classification override and a GitHub call
+admission rule in code, so Settings and the connector Configuration card show
+set values beside defaults; Slack describes OAuth facts (scope, endpoints, an
+API origin, client secret, PKCE) for the card's auth row. Its Tokens agents
 (`claude-desktop` issued, `triage` none, `nightly` revoked) are real slots
 committed through the deployment's own store, so the contract's `agents` and
 `GET /ui/access-tokens` agree, revisions included; only their timestamps 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 chips
-collapse to "+3 more".
+with `test/fixtures/operator-console.ts` crowding the team pool so its avatar
+stack collapses to "+3".
 Collections use their corresponding browser types.
 `test/operator-visual-fixtures.test.ts` validates contract versions, connector
 IDs, granted tools, matrix cells, classification, provenance, and secret
@@ -31,7 +35,10 @@ server serializer.
 
 `test/browser/operator-visual.spec.ts` intercepts API reads and serves the real
 hashed assets and HTML with the production CSP. Loading responses wait on an
-explicit gate. Error responses use fixed HTTP failures. Screenshots use a fixed
+explicit gate. Error responses use fixed HTTP failures. The map trace focuses its
+node instead of hovering it: the capture scrolls to the top first, which would
+move the node out from under a pointer and drop the highlight, so the test waits
+for `.map-svg.tracing` before capturing. Screenshots use a fixed
 clock, UTC, en-US, locally hosted fonts, disabled animations, hidden carets,
 and a 1280 × 900 viewport. Narrow fixtures use 390 × 844. Every test waits for
 its state and fonts before capturing.
@@ -39,11 +46,12 @@ its state and fonts before capturing.
 ## Page and state matrix
 
 Each row runs empty, loading, error, populated, and restricted-viewer fixtures
-in both light and dark themes, for 80 screenshots. The restricted viewer is a
+in both light and dark themes, for 90 screenshots. The restricted viewer is a
 pool member, who gets the member page, with no tabs, on every path.
 
 | Page or tab          | Empty state                          | Loading/error request | Restricted viewer (member)          |
 | -------------------- | ------------------------------------ | --------------------- | ----------------------------------- |
+| Overview             | No connectors: nothing to map        | Config                | Member page at `/`                  |
 | Endpoints            | Root endpoint without tools          | Config                | Member page: endpoints, accounts    |
 | Connectors           | No connectors                        | Config                | Member page, no connector request   |
 | Connector Tools      | Empty catalog                        | Config                | Member page, no connector request   |
@@ -53,24 +61,26 @@ pool member, who gets the member page, with no tabs, on every path.
 | Activity             | No calls                             | Activity              | Member page, no activity request    |
 | Settings             | Snapshot without connectors or pools | Config                | Member page, no configuration facts |
 
-Populated Endpoints shows who can use each endpoint; populated Tokens has one
+Populated Overview has a failing connector, auth and credential problems
+and a tokenless agent in its attention list. Populated Endpoints shows who can use each endpoint; populated Tokens has one
 agent per slot state, with pools and last seen.
 
-Another 54 screenshots cover configured, mismatched, unreadable and multifield
+Another 60 screenshots cover the Overview map on the frozen v2 maintainer, one
+person's trace, and the narrow map list; configured, mismatched, unreadable and multifield
 credentials; all three OAuth client mechanisms; clean and unobserved drift;
-historical Activity; client setup; schema dialog; read/write filters; expanded
-config provenance; narrow sign-in and Connection; deployment branding; `/mcp`
+historical Activity; client setup; schema dialog; read/write filters; narrow
+Settings; narrow sign-in and Connection; deployment branding; `/mcp`
 and an agent pool expanded with every runs-as kind; command search; narrow
 endpoints; the connector × endpoint matrix, one cell's open popover, and the
 narrow matrix; a new token's one-time secret dialog; and the member page, wide
 and narrow. `endpoints-expanded` and `narrow-endpoints` include the team row
-collapsed to "+3 more". The base
+collapsed to "+3". The base
 populated Activity fixture includes grouped calls, an ungrouped legacy row,
 classification/result size/client facts, and a catalog-change event.
 
 `test/browser/operator-matrix.spec.ts` serves the frozen v2 fixtures to the
-real shell. It covers the matrix's table semantics, cell names and runs-as
-labels, popover keyboard behavior, placement at a short viewport, the in-flow
+real shell. It covers the matrix's table semantics, cell names, status dots,
+runs-as labels in each kind's popover, popover keyboard behavior, placement at a short viewport, the in-flow
 fallback without CSS anchors, and the absence of `style` attributes, agent URLs on Endpoints, the member page (its
 received body checked with `expectMemberViewWithholds`, `/ui/data` answering 404
 and never requested, no maintainer fact rendered, no maintainer request sent),
@@ -80,9 +90,31 @@ refresh that stalls past its deadline (one focusable Retry, no maintainer
 request until Retry succeeds), an open client setup drawer closed by a failed
 refresh with focus on Retry, Tokens under recovery (an open rotate question
 closes with focus on Retry and nothing sent; an unseen secret dialog stays open
-over the banner until dismissed), payload sentinels, CSP, and the refusal of a v1 body. `test/operator-endpoints.test.ts` covers the view model.
+over the banner until dismissed), payload sentinels, CSP, and the refusal of a v1 body. Matrix coverage excludes retired grants from
+its live counts and pie, keeps their names inspectable in the popover, and
+renders an unavailable catalog as a dashed empty ring with "?" and an unknown
+accessible name. Cell names distinguish equal grants against different live
+catalog sizes. `test/operator-endpoints.test.ts` covers those view-model cases,
+including a known empty catalog versus an unavailable one.
+`test/operator-connection-map.test.ts` also checks that a failed or unobserved
+catalog counts no tools, which the map draws as a muted dash, while a known
+empty catalog counts zero.
+`test/browser/operator-overview.spec.ts` covers the Overview on the frozen v2
+fixtures: the status pill, stat labels and numbers, map columns, dashed read-only grants and dotted
+tokenless access; attention rows with their fix links, a copied fix prompt equal
+to the catalogue's text, config order through a staggered full refresh, prototype-named
+connector IDs during loading and failure, and stable single-card height when
+its catalog empties. A single long-id, long-title card at 320, 390, 1024 and
+1440px covers all eight status labels, both auth scopes, with and without the
+Read-only badge, tools and an action. Text rows stay single-line, full text
+remains accessible, links stay focusable, and the detail header and Overview
+attention rows retain their height; the hover
+sentence replacing the legend, and dimming; keyboard focus in column order with each node's sentence
+as its accessible name, Enter opening an endpoint's row and a connector; the
+narrow list, whose caller chips link where their map nodes do; an empty deployment; and a member at `/` getting the member page
+with no maintainer read, plus CSP and no `style` attributes.
 `test/browser/operator-console.spec.ts` covers UI-3: who-can-use chips by
-label, raw id and agent mark and "+N more" from the keyboard; Tokens rows,
+label, raw id and agent mark and "+N" from the keyboard; Tokens rows,
 issue with the once-only secret dialog, in-row rotate and revoke questions,
 503, 499 and 409 failures that send exactly one request, slots missing from
 the list or left unresolved shown with disabled controls until Refresh; and the
@@ -121,15 +153,15 @@ cannot prove these rules.
 
 The source of truth is `*-linux.png`, produced on `ubuntu-latest` with the
 lockfile's Playwright Chromium. Both CI workflows use the same runner, Node 22,
-and `npm run test:browser:install -- --with-deps`. macOS runs fixture routing and
+and `pnpm run test:browser:install --with-deps`. macOS runs fixture routing and
 readiness checks but omits screenshot comparison. The update script refuses
 non-Linux hosts. Do not commit Darwin baselines.
 
 When Docker is unavailable, use the **Operator snapshots** workflow:
 
 ```sh
-git push --force-with-lease origin ui/834-shell
-gh workflow run operator-snapshots.yml --ref ui/834-shell
+git push --force-with-lease origin <branch>
+gh workflow run operator-snapshots.yml --ref <branch>
 # Read the completed run ID from the Actions page or gh run list.
 gh run download RUN_ID --name operator-linux-snapshots \
   --dir test/browser/operator-visual.spec.ts-snapshots
@@ -140,9 +172,9 @@ images and changed files, commit the intentional changes, and push again. The
 normal CI browser job must compare and pass against that commit. Snapshot
 updates run only through `workflow_dispatch`.
 
-On a matching Linux runner, `npm ci`, install Chromium with the command above,
-then run `npm run test:browser:snapshots`. The normal command is
-`npm run test:browser`. Missing baselines fail CI; retries cannot bless them.
+On a matching Linux runner, `pnpm install --frozen-lockfile`, install Chromium with the command above,
+then run `pnpm run test:browser:snapshots`. The normal command is
+`pnpm run test:browser`. Missing baselines fail CI; retries cannot bless them.
 Set `OPERATOR_VISUAL_INSPECT=1` to retain local screenshots under ignored
 `test-results/` for inspection, without updating committed baselines.