@zackbart/connecta 0.31.0 → 0.33.0

package/documentation/operator-ui.md

@@ -10,6 +10,7 @@ credential ownership, and grants use [Auth](./auth.md).
 | Task                                            | Read                                                                                                             |
 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | Enable UI, vault, or history in a deployment    | [Setup](#setup), then the platform template                                                                      |
+| Find a member's endpoint or set up their client | [Use the member page](#use-the-member-page)                                                                      |
 | Consume config, provenance, status, or activity | [Operator data contract](#operator-data-contract)                                                                |
 | Change a UI page or data route                  | [Source and tests](#source-and-tests), [browser verification](./operator-tests.md)                               |
 | Diagnose permission refusals                    | [Management permissions](./auth.md#management-permissions), [activity disclosure below](#operator-data-contract) |
@@ -22,75 +23,326 @@ and [Worker example](../examples/worker/README.md#select-optional-modules)
 own the runnable configuration, variables, and branding shape. The UI is an
 explicit optional import and stays outside the root package import graph.
 
-Overview, Connectors, Tools, Access, Activity, and Config show only what the
-caller may inspect. Connector detail tabs cover configuration, schemas,
-authentication, activity, and diagnostics. Config labels values as default or
-configured. Deployment code owns connectors, grants, pools, and classification;
+Endpoints, Connectors, Activity, Tokens, and Settings are the maintainer's
+pages. Endpoints is the default page at `/`: one row for `/mcp` and each pool,
+with a copyable URL, who can use it, tool count, endpoint mode, and client
+setup. Who can use it is `root.maintainers` on `/mcp` and the pool's `members`
+elsewhere: a person by label, or by raw id when the label is null, beside their
+initials, and an agent as `agent:<name>` with a token mark. A row shows four
+and a "+N more" button that reveals the rest. A pool with
+agent members also shows its agent URL, muted. Expanding a row lists each
+connector on that endpoint with what it runs as and its tools, marking write
+tools. The runs-as label comes from that endpoint's matrix cell. A shared connector
+names its credential's source: "Shared · saved <date>" (vault), "Shared ·
+connected <date>" (OAuth), "Shared · not configured", "Shared · set in
+deployment", or "Shared · no credential needed"; a vault or OAuth cell without a
+date omits it. The others read "Personal · N of M connected", "Workspace · people:
+self · agents: <owner>" (or "none"), or "Everyone acts as <subject>" for a
+fixed-subject Workspace connector. Connector health is not repeated per
+endpoint: a connector that needs attention gets a status dot linking to its
+Connection tab. Counts intersect live tools with the pool's declared tools
+(the `/mcp` matrix cells for the root), guarded grants' live verdicts, and
+read-only mode. Connectors lists each connector with one status badge, auth
+scope, tool count, and last call; a problem adds one action (Connect, Replace
+key, or Inspect) that opens Connection. A List / Matrix toggle (`?view=matrix`)
+switches to a table of connectors by endpoint, `/mcp` first: each cell reads
+"all", a tool count, or a dash, read-only columns are tinted, and a Runs as
+column summarizes the `/mcp` cell, else the first pool's. A cell with tools is
+a button named like "GitHub on /mcp/support: 1 tool, read-only"; Enter, Space or
+a click opens a popover listing exactly that cell's tool names, write tools
+marked, with the cell's runs-as. Escape or Tab returns focus to the cell. The
+popover opens below its cell, or above when the viewport has more room there,
+with a capped height that scrolls; CSS anchor positioning places it, and the
+page sets no inline styles. A browser without anchor positioning gets the same
+list, with the same keys, in an expansion row under the connector. `GET /ui/api/config` is the browser's one gate: a 401
+shows sign-in, the private 404 shows a "No access" page naming who to ask, with
+Sign out or Change token, and a 200 renders by `role`. `/ui/data`, connector
+details, activity and tokens are requested only after the contract says
+`maintainer`, and every such read checks the role again when it is sent, focus
+returns included. Until a role is confirmed, the page shows its loading or
+error state and no navigation. The store keeps the last confirmed role through
+a failed refresh: a maintainer's page stays mounted, inert and dimmed, under
+one shell banner with Retry, whichever page it is, and sends nothing
+maintainer-only until a contract confirms the role again. Recovery closes the
+page's dialogs, drawers and popovers and the command palette, and moves focus
+to Retry. Credential and OAuth writes also wait for a contract that agrees
+with the confirmed role: a maintainer's for a connector it shows, a member's
+for a personal connector their contract lists with that action in `manage`;
+otherwise the write is not sent and its row says so. An
+answer with a different role clears everything read under the old one and
+admits the viewer again. A
+pool member sees the [member page](#use-the-member-page) on every path, with
+no tabs. Connector
+detail has Tools, Connection, and Activity tabs. Connection combines
+authentication (including the OAuth client mechanism), catalog diagnostics,
+one fix prompt beside each problem it reports, and the connector snapshot with its source. Settings combines inbound-auth facts with the
+configuration snapshot and labels values as default or configured. Deployment code owns connectors, grants, pools, and classification;
 the UI changes only authorized authentication material.
 
+Tokens has one row per agent declared in code, in `GET /ui/access-tokens`
+order: its pools, a state badge (No token, Issued or Revoked), the issue or
+revoke date, and last seen ("never" when null). One line says agents are
+declared in code; nothing creates or renames one. Issue appears for a slot with
+no token or a revoked one, Rotate and Revoke for an issued one; rotate and
+revoke ask first in a row under the agent's, with focus on Cancel. Every
+mutation sends `{ "expect": "<revision>" }` with the slot revision the
+operator confirmed against. A new secret opens once in a dialog with a copy
+button and a note that it won't be shown again; closing it drops the secret
+from the page, and recovery never closes it. A 409 `slot_changed` reads
+"Changed since you looked, refresh"; a 503 `outcome_unknown` or 499 `aborted`
+is a failure notice and is never retried. Sending a mutation leaves the slot
+unresolved until its successful response is validated, which resolves it. Any
+other outcome, a contract whose `agents[].token` disagrees with the list
+(revision included) or drops the agent, or a failed read leaves it unresolved
+until a slot-list read that started afterwards succeeds. Until then its
+controls are off with "Refresh to continue", and each action is
+checked again immediately before it is sent. Under the recovery banner Tokens
+offers no Refresh of its own, and an open rotate or revoke question closes.
+
 Install the vault for declared credential slots and activity history for
 persisted call records. Neither module grants permission to manage or read
-it. Credential administration, personal connection, access-token management,
-and activity access are separate identity decisions, denied by default where
-specified in [auth](./auth.md#management-permissions). Machine tokens never
-grant interactive credential or token management authority.
+it: [auth](./auth.md#management-permissions) does. Interactive maintainers
+administer shared credentials and agent tokens, maintainers read activity, and
+pool members connect their own accounts on personal connectors in their pools.
+Token management issues, rotates, and revokes the tokens of agents declared in
+code; it never creates, renames, or binds an agent. Agent tokens never grant
+interactive credential or token management authority.
+
+## Use the member page
+
+With `operatorUi()` enabled, sign in at the deployment's public URL using
+Clerk (Node) or Cloudflare Access (Workers). A person listed in a pool's
+`members` can open the page without becoming a maintainer. The page, **Your
+connections**, has no tabs; its top bar shows branding, the signed-in account
+(Clerk's primary email, when there is one) and Sign out or Change token. It
+lists:
+
+- **Your endpoints**: each 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 accounts**: the personal connectors in their pools, each with one
+  status badge and only the controls its `manage.actions` lists. An OAuth
+  connector offers Connect, Reconnect or Disconnect; Reconnect and Disconnect
+  ask first. A credential connector offers **Add credential** when only `save`
+  is listed, and Replace, Test and Clear once a value is stored.
+- **Shared with you**: shared connectors by name and tool count, without status.
+
+Every browser path shows that same member page; it does not expose maintainer
+connector-detail, activity, token, or settings pages, and it never sends a
+maintainer request. After an action, and when the tab regains focus while an
+authorization it started is still outstanding (up to ten minutes), it re-reads
+`GET /ui/api/config`. Each action is checked against the current `manage`
+again immediately before it is sent, and a refresh that drops an action closes
+its open confirmation or form. If a refresh fails or misses its deadline, the
+page shows its own error with Retry and moves focus to its heading; members
+never see the maintainer recovery banner.
+
+The page reads `GET /ui/api/config`: 200 with `role: "member"` confirms
+membership; 401 means sign in; a private 404 means the signed-in person has
+no maintainer role or human pool membership. A `cta_` agent token gets 401
+and cannot sign in to this page. Use the agent's `/agent/<pool>` endpoint
+for machine access instead.
+
+Personal OAuth can also start from the person's `/mcp/<pool>` connection with
+`authorize_connector`, finishing its signed browser link. Trusted clients that manage personal credentials use only the actions listed
+in the connector's `manage` field; the API contract below describes their
+routes and preconditions. Shared credentials always require a maintainer.
 
 ## Operator data contract
 
 `GET /ui/api/config`, owned by `operatorUi()`, returns `OperatorUiContract`
-from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
-source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
-`config` is the construction-time `describeConfig()` snapshot, filtered to
-visible connectors, granted tools, classification overrides, and admitted
-pools. Pool tools are the intersection with the caller's identity grants.
-`configSources` labels each serialized leaf as `default` or `config`, based on
-option presence rather than equality with the default. Factory descriptions carry
-relative `optionSources` paths so resolved module and transport defaults retain
-their provenance. The snapshot copies only resolved values; the UI consumes
-these presence facts separately. Its paths use connector
-ids and pool names and are filtered after disclosure; hidden values leave no
-provenance keys. It contains no source code or credential material.
-Every response is private, `no-store` JSON. Only GET is allowed, with the
-same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
-
-`live.connectors` carries status and problem codes, complete registry tools
-with their final read/write classification, catalog age in milliseconds, and
-last-call time/outcome. Catalog descriptions and schemas are allowed for an
-authenticated reader; grammar-failing names and addresses become `<withheld>`.
-`auth.registrationPath` reports the selected downstream OAuth client mechanism when known.
-Status prose, error text, credential values or suffixes, arguments, results,
-and code are excluded. Static and unobserved catalogs have a null age;
-persisted catalogs retain their original fetch time. Probes run with bounded
-concurrency and the configured probe deadline, and release their scopes.
-
-Last-call lookup requires the existing activity permission and read gate. It
-scans up to 1,000 recent rows, filters connector/tool grants, and restricts
-personal connectors to the caller's activity identity. Each retained fact
-copies a validated timestamp and outcome only. A null call means unknown or
-absent in that window, not proof of no calls. `live.activity` distinguishes
-available, unconfigured, forbidden, and unavailable history. `you` names no
-identity or auth material; it reports grants, root and admitted-pool trust,
-and effective activity, token, and per-connector auth permissions.
+(`OperatorUiContractV2`) from `@zackbart/connecta/ui`, `schemaVersion: 2`.
+Its declarations ship in `dist/operator-ui/contract.d.ts` in the installed package. Schema
+version 1, `hasGrant`, `you.grants`, and `you.permissions` were removed;
+v2 keeps `you.interactive` to describe whether the session is interactive. It is the page's
+only gate: a signed-out caller gets the auth provider's 401 challenge, and a
+`cta_` agent token the machine-only 401 Bearer challenge every human route
+gives it; a maintainer, or a person listed in a pool's `members`, gets 200
+with `role` `"maintainer"` or `"member"`; anyone else gets the private JSON 404
+`{ "error": "not found" }`. An open deployment's anonymous caller is
+a maintainer. Every response is private, `no-store` JSON, and only GET is
+allowed. One shape serves both roles; a field a role does not receive is
+`null` or empty, never omitted.
+
+The maintainer view carries:
+
+- `config`, the construction-time `describeConfig()` snapshot, including
+  `maintainers` and each pool's `members`, 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
+  provenance. Paths use connector ids and pool names and are filtered after
+  disclosure; hidden values leave no provenance keys. Neither contains source
+  code or credential material.
+- `root`: plain `/mcp`, its `readOnly`, and its `maintainers`, people only.
+- `pools`: every declared pool with `humanPath` (`/mcp/<name>`), `agentPath`
+  (`/agent/<name>`), `readOnly`, `owner` (the Workspace address its agents act
+  as), its declared `tools` (never intersected; no `requireReadOnly` is ever
+  true), and its `members`, agents as `{ kind: "agent", name }`. Every listed
+  person carries a `label` from the same directory lookup activity actor
+  labels use, on an interactive read only, and `null` without a directory
+  (Cloudflare Access) or an entry. An open deployment's anonymous maintainer
+  reads every `owner` as `null`.
+- `agents`: every agent declared in code, with its pools, its token slot
+  (`state`, `issuedAt`, `revokedAt`, `revision`) exactly as
+  `GET /ui/access-tokens` lists it, and `lastSeenAt`, the newest visible
+  activity row recorded for that agent, or `null` when activity is off or
+  none is visible. A slot read that fails answers 503 rather than drop agents.
+- `matrix`: a cell per connector for plain `/mcp` (`pool: null`) and for each
+  pool that serves it, with that endpoint's tool names or `"all"` and
+  `runsAs`. A Workspace connector with a subject mapping is
+  `{ kind: "workspace", humans: "self", agents }`, `agents` being the pool's
+  owner, or `null` on plain `/mcp` and in an ownerless pool; a fixed subject is
+  `{ kind: "workspaceFixed", subject }`. A personal connector counts the
+  endpoint's people (the maintainers on plain `/mcp`) and how many have
+  connected in their own partition: a stored credential of the declared shape,
+  or an `ok` status. A shared connector names its `source`: `vault` (a saved
+  slot, with `savedAt`), `missing` (a slot with nothing saved, or shared OAuth
+  reporting it needs authorizing), `oauth` (a shared grant; grants carry no
+  saved time, so `savedAt` is `null`), `unauthenticated` (a remote MCP server
+  that declares no auth), or `config` (everything else, held by deployment
+  code).
+- `live.connectors`: status and problem codes, complete registry tools with
+  their final read/write classification, catalog age in milliseconds, and
+  last-call time/outcome. Catalog descriptions and schemas are allowed;
+  grammar-failing names and addresses become `<withheld>`.
+  `auth.registrationPath` reports the selected downstream OAuth client
+  mechanism when known. Static and unobserved catalogs have a null age;
+  persisted catalogs retain their original fetch time.
+- `live.activity`: available, unconfigured, forbidden, or unavailable history.
+  Last-call and last-seen lookups need the activity permission and read gate,
+  scan up to 1,000 recent rows, filter connector/tool grants, restrict personal
+  connectors to the caller's activity identity, and copy a validated timestamp
+  and outcome only. A null means unknown or absent in that window.
+- `connectors: []`.
+
+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
+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
+connector, `null` for a shared one) and `manage`. `manage` is derived on the
+server. A shared connector is always `{ kind: "none" }`. For a personal one,
+the member's own permission (an interactive person in a pool that holds it)
+gates every action. A credential slot offers `save` when a vault is
+configured, `clear` when a value is stored in the member's partition, and
+`test` when one is stored in the declared shape and the connector has the
+matching test hook; an unreadable partition offers `save` alone, so the page
+reads stored-ness from `actions`. OAuth offers `connect` and `restart` when
+the connector has `startAuth`, `finishAuth` and `verifyState` and the
+deployment can sign the connect hand-off, and `disconnect` when it has
+`disconnectAuth`. No actions is `{ kind: "none" }`. The view carries no shared
+credential status, catalog ages, last calls, other members, agents, owners or
+activity. Status prose, error text, credential values or suffixes, arguments,
+results, and code are excluded from both views. Probes run with bounded
+concurrency and the configured probe deadline, and release their scopes. Every
+vault, token-slot and activity read the view makes runs under that same
+deadline and the request's signal, so a stalled store never hangs the page: it
+degrades fail-closed, to `save` alone for a member's credential, `missing` or
+an unconnected person in a matrix cell, unavailable activity, and a 503 for
+the token slots.
+
+`/ui/data`, `/ui/connectors/:id`, activity reads and access-token routes
+require a maintainer and give anyone else the same private 404. The connector
+auth routes, `/ui/oauth/<id>` and `/ui/credentials/<id>`, also admit a pool
+member for a personal connector in one of their pools, in their own
+partition. `/ui/oauth/<id>` gates each verb on its own hooks: a connect needs
+`startAuth`, `finishAuth` and `verifyState`, a disconnect only
+`disconnectAuth`. `/ui/credentials/<id>` refuses to clear an empty partition,
+the caller's own for a personal connector or the shared slot, with 409
+`{ "error": "no credential is stored to clear", "problem": "credential_required" }`,
+as its test route refuses to test one; a value that cannot be read can still be
+cleared. The routes thus accept what `manage` lists, with one recovery
+exception: clearing a stored value that cannot be read is accepted although
+`manage` lists only `save` in that state. Public HTML shells and static assets carry no catalog data.
+Access-token management also requires an interactive session.
+
+`GET /ui/api/config?connector=<id>` narrows the same contract to one connector
+before status and catalog probes. For a maintainer, config, provenance, live
+rows and matrix cells contain only that connector's facts; for a member,
+`connectors` does. Pools keep their declared tools. An id outside the
+caller's view receives a no-store 404. The selector never widens access.
 
 `connecta doctor --config` fetches this authenticated contract and prints only
-`config` as indented JSON. It requires the UI module and the existing doctor
-authentication environment variables; it runs no diagnostic program, follows
-no redirects, and prints no raw HTTP failure body.
+a maintainer's `config` as indented JSON; a member's view has none, and doctor
+says the snapshot is for maintainers. It requires the UI module and the
+existing doctor authentication environment variables; it runs no diagnostic
+program, follows no redirects, and prints no raw HTTP failure body.
 
 The operator shell uses React, TanStack Router/Query/Table, Radix, cmdk and
-Tailwind v4. Inter, CSS, JavaScript and dependency notices are hashed assets
+Tailwind v4. Geist Sans, Geist Mono, CSS, JavaScript and dependency notices are hashed assets
 under `/ui/assets/*`, served identically with immutable cache headers on Node
 and Workers. HTML contains only mount points and escaped inert configuration;
-it remains uncached. `generated.ts` is ignored and generated before build and
+it remains uncached. Ahead of the stylesheet, every operator page (sign-in
+gate, member page, maintainer pages) loads a blocking hashed scheme initializer
+of under 200 bytes, `src/operator-ui/app/scheme-init.ts`, with a plain
+`<script src>` and no inline code. When the server set no `html[data-scheme]`
+from a pinned `branding.theme.colorScheme`, it copies a saved `light` or `dark`
+from local storage key `connecta:scheme` onto that attribute, ignoring storage
+errors, so the first frame already has the viewer's scheme. The deferred bundle
+learns of a pin from `schemePinned` in the inert configuration; Appearance
+writes the key and moves the attribute live, and is read-only under a pin. Every
+local and session storage access in the UI tolerates storage that throws, as in
+private browsing: a read finds nothing stored and a write keeps nothing, so a
+bearer token is not remembered there. `generated.ts` is ignored and generated before build and
 test; `check:operator-ui` detects stale assets and shared page styles. The UI
 stays behind `./ui`, outside the root import graph. The identity-fenced store
-owns authenticated reads and existing mutations. Overview, Connectors, connector
-detail, Tools, Access and Config consume the typed contract. Activity retains
+owns authenticated reads and existing mutations. An Access-only shell selects
+Access even when the HTML request has no trusted context; only authenticated
+API responses establish the session. A gated Access session offers Retry.
+Focus, visibility, and timer-driven recovery share one admission-read schedule
+with at least two seconds between passive attempts. An admission read takes
+the contract first and, for a maintainer, then `/ui/data` and the connector
+details, which reuse that contract rather than read it again. An in-flight
+passive attempt coalesces returns until its admission read finishes, so slow
+successful reads can publish. Each admission read shares one 15-second
+deadline, including token acquisition, fetches and response bodies. This is an admission deadline, not a request
+lifetime limit: it releases the recovery guard and exposes Retry without aborting
+the pending read or invalidating its identity/revision fence. A late healthy
+response still publishes if that cycle is current. Passive timers and returns
+coalesce onto the pending cycle, including after its deadline; they never start
+duplicate summary, token, config, detail or body reads. The passive retry schedule
+stays bounded and does not reset its budget on a deadline. Retry remains available
+during recovery configuration loading and supersedes and aborts the old cycle;
+identity changes, navigation and connector-page unmount also cancel it. Navigation
+that cancels pending data schedules a bounded reread for the destination. Failed reads retry after
+2, 2, 4, and 8 seconds. Refusals preserve the throttle and retry budget. After
+those four automatic retries, a focus return can request one more read after
+the eight-second backoff, without replenishing the automatic budget. Retry
+resets the budget with a 150 ms click debounce. Successful reads and explicit
+identity transitions also reset recovery. Identity changes
+cancel pending retries and fence out responses from the previous identity.
+Queued focus callbacks carry the same identity fence. Explicit sign-out
+suppresses passive reads until an intentional sign-in or a new Clerk session.
+
+Catalog and connector auth details share one revisioned refresh cycle. Each
+completed connector publishes its catalog facts and auth controls together,
+while a slow provider leaves other rows usable.
+Catalog refresh, connector refresh, and mutation follow-up reads update both
+consumers together. A later refresh or mutation invalidates an older cycle's publication fence
+without aborting its read, and a failed contract read clears its old snapshot;
+the next refresh then reads the contract before any connector detail. After an explicit OAuth
+start, visible tabs poll only that connector's read-only catalog and auth facts
+every two seconds for up to 30 seconds. The scoped result replaces only that
+connector's matching live row and auth controls. Success, a failed read or status,
+disconnect, navigation away from the connector, unmount, or identity reset ends
+polling and aborts its in-flight reads. The deadline also aborts a stalled read.
+A later focus return can request another status read. Recovery never starts OAuth
+or replays a mutation.
+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. Endpoints, Connectors, connector
+detail, Settings, and the member page consume the typed contract; Activity opens
+only to a maintainer whose contract reports readable history. Connector detail
+reads auth permissions from its `/ui/data` connector. Activity retains
 its authenticated data routes. Connector detail tabs live
 in the URL hash; Activity filters live in the query string and apply to loaded
-history. Both `/ui/activity` and `/ui/api/activity` require Activity access and
-pass the optional activity `readGate`. Interactive operators and machine callers
-admitted by `identity.activityAccess` share the same history disclosure rules.
+history. Both `/ui/activity` and `/ui/api/activity` require a maintainer
+principal, interactive or not, and pass the optional activity `readGate`.
+Interactive and machine maintainer reads share the same history disclosure rules.
 Connector/tool grants and grants for the recorded pool filter each event. Shared
 connector history can include other principals' events, with recorded request
 IDs, validated client name/version and package version, and actor kind, ID and
@@ -112,12 +364,31 @@ id and typed actor when available, otherwise a fresh id and system actor. No
 names, descriptions or schemas enter the event. Private catalog changes require
 a matching principal owner even when the connector uses shared auth. Empty credential declarations
 report `credential_required` before running a connector status or catalog probe.
-The Access adapter reports inbound provider kinds, admitted pools, grants, trust
-and endpoint setup; token controls retain their existing permission gate.
+The top bar shows deployment branding and a name breadcrumb, then Search (the
+command palette), Appearance, and the session action (Change token or Sign out)
+at one quiet size; a member's top bar has only branding, the account and the
+session action. The tab row lists Endpoints, Connectors, Activity,
+Tokens, and Settings. Activity and Tokens keep their permission gates; a gated
+viewer sees no operator navigation. The command palette searches visible pages,
+connectors and tools, opening connector results on Tools. `/access` redirects
+to `/`, `/tools` to `/connectors`, and `/config` to `/settings` in the browser
+with history replacement. Connector hashes `#config`, `#auth` and `#diagnostics`
+redirect to `#connection`, preserving query parameters such as signed handoffs.
+Token controls retain their existing permission gate.
 Configuration remains in deployment code. The UI mutates only credentials,
-OAuth connections and client tokens through the existing routes.
+OAuth connections and agent tokens through the existing routes.
+
+## Contributor reference
+
+### Source and tests
 
-## Source and tests
+The browser store reads only v2 and checks `role` before reading a
+maintainer-only field. `test/fixtures/operator-contract-v2.ts` holds
+maintainer and member fixtures, and `test/helpers/operator-member-view.ts`
+checks a member response's exact shape and compares its values with a
+projection built from config, membership, the member's own partition status,
+and each personal connector's exact `manage`;
+`test/operator-contract-server.test.ts` runs it against real responses.
 
 The contract type is [contract.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/contract.ts).
 [UI routes](https://github.com/zackbart/connecta/blob/main/src/routes/ui.ts) and

package/documentation/provider-auth-migration.md

@@ -2,17 +2,14 @@
 
 Use this upgrade guide when moving a Stripe, Notion, Vercel, or Cloudflare
 deployment from 0.30 to 0.31, where `auth` selects each provider's
-implementation ([#801](https://github.com/zackbart/connecta/issues/801)).
-The [0.31.0 release notes](https://github.com/zackbart/connecta/blob/main/release-notes/0.31.0.md) summarize the change.
+implementation.
 [Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
 version changes; [integrating services](./integrating.md) covers new connectors.
 
 A dual provider requires `auth`. `{ type: "oauth" }` connects the vendor's
 hosted MCP server, OAuth only. A key type connects Connecta's REST connector
 with an operator-managed credential. There is no default, and one connector id
-uses one implementation: configure two ids for both. The
-[decision record](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
-explains why.
+uses one implementation: configure two ids for both.
 
 ## Stripe
 
@@ -62,6 +59,10 @@ contracts: search finds operations in a pinned API index, every call is
 checked against that index before it is sent, results arrive as
 `{ status, data, page? }`, and POST writes send the caller's `idempotencyKey`
 or a generated one as `Idempotency-Key` and return it (DELETE sends none).
+Caller-supplied keys may contain up to 255 characters. An ambiguous POST write
+also returns the key in `uncertainCall.recovery.idempotencyKey`, including when
+the call deadline interrupts it. See [argument recovery](./meta-tools.md#argument-recovery)
+before retrying.
 Every request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the
 version of the pinned index, whatever the account's default API version, so
 response shapes and accepted parameters follow that version. Check fields
@@ -73,9 +74,7 @@ A key whose `sk_live_`/`rk_live_` or `sk_test_`/`rk_test_` prefix contradicts
 Lost on the key path: natural-language Sigma (`stripe_analytics`), metrics,
 documentation search, the implementation planner, reports, and feedback exist
 only on the hosted OAuth connection. Programs calling those tools on a key
-connector need an OAuth connector beside it. The
-[Stripe skill](https://github.com/zackbart/connecta/blob/main/src/providers/stripe/SKILL.md)
-owns the conventions for both.
+connector need an OAuth connector beside it. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Notion
 
@@ -101,6 +100,15 @@ connectors: [
 | `integration_list_comments`, `integration_add_comment`                                                                                    | `notion_api_read` `GET /v1/comments`; `notion_api_write` `POST /v1/comments`.                                        |
 | `integration_update_page_properties`, `integration_trash_page`                                                                            | `notion_api_write` `PATCH /v1/pages/{page_id}` with `properties`, or `in_trash` to trash or restore.                 |
 
+Both auth variants accept optional `callAdmission`. On a token connector it
+replaces the whole default policy of 180 calls per minute and 3 concurrent
+per runtime. Malformed policies throw at construction. Notion's
+[request limits](https://developers.notion.com/reference/request-limits) allow
+600 requests per minute per connection on Business and Enterprise and 180 on
+other plans, with a separate workspace-wide limit shared by all connections.
+Account for other runtimes and tools that make multiple HTTP requests when
+choosing an override.
+
 The token connector gains Connecta's generic REST tools over Notion's pinned
 API index (`notion_api_search`, `notion_api_details`, `notion_api_read`,
 `notion_api_write`), so every public operation is reachable with the bot's
@@ -119,8 +127,7 @@ duplication, team and skill search, attachment downloads, or page-to-skill
 conversion. An OAuth connector acts as the user, and has none of the generic
 REST tools or the `integration_*` projections and authoring helpers. Configure
 both ids when a deployment needs both; a failed call is never retried on the
-other. The [Notion skill](https://github.com/zackbart/connecta/blob/main/src/providers/notion/SKILL.md)
-owns the conventions for both.
+other. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Vercel
 
@@ -156,7 +163,7 @@ variable tools (`list_project_env_vars`, `upsert_project_env_var`,
 (the runtime stream, stopped after `waitMs` or `maxRows`), and
 `vercel_api_upload`.
 
-Value safety follows a reviewed table (`src/providers/vercel/value-safety.ts`).
+Value safety follows a reviewed table bundled with the connector.
 Every operation whose response schema in the pinned spec may carry a credential
 or a stored secret has a verdict: refused (credential minting, Connect
 authorization, decrypted environment values, Global Config items and tokens,
@@ -183,12 +190,10 @@ connector beside the token connector.
 
 The hosted connection now lists `filter_project_envs`, `get_project_env`,
 `create_project_env`, and `edit_project_env`, which 0.29 hid. The two reads can
-return decrypted values, so they are reviewed as writes and the pool trust
-policy gates them. Vercel admits only reviewed and approved MCP clients to its
+return decrypted values, so they are reviewed as writes, and a `readOnly`
+endpoint refuses them. Vercel admits only reviewed and approved MCP clients to its
 hosted server; if authorization is refused for that reason, the deployment
-needs Vercel's approval or a token connector. The
-[Vercel skill](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/SKILL.md)
-owns the conventions for both.
+needs Vercel's approval or a token connector. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Cloudflare
 
@@ -245,17 +250,16 @@ hooks) and redacts stored secrets on every result. A pinned connector refuses
 operations that name no account or zone unless they are reviewed safe, such
 as `/certificates` and `/memberships/{id}`.
 
-Read-only pools: hosted `execute` is always a write, even for a program that
-only reads, so a read-only pool on an OAuth connector reaches only `search`.
+Read-only endpoints: hosted `execute` is always a write, even for a program
+that only reads, so a `readOnly` endpoint on an OAuth connector reaches only
+`search`.
 Use an API-token connector for read-only API access.
 
 Lost on each path. OAuth has no index validation, named tools, GraphQL tool,
 upload tool, or pin; Cloudflare's OAuth grant is the only boundary. A key has
 no hosted `search` over Cloudflare's live OpenAPI document; the pinned index
 replaces it and `providers:check` reports when it falls behind. A Global API
-Key cannot reach R2, which accepts API tokens only. The
-[Cloudflare skill](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/SKILL.md)
-owns the conventions for both.
+Key cannot reach R2, which accepts API tokens only. Read the connector runtime guide with `connecta.skill("connector:<id>")` in `execute_code` for its usage conventions.
 
 ## Value safety on every key connector
 
@@ -288,12 +292,16 @@ one; read or rotate withheld secrets in the vendor's dashboard.
   Failures of credential-bearing operations keep Stripe's type, code, and
   param but not its message. Create client-side sessions and links from your
   own server code.
-- **Notion** results withhold the signature, credential, and security-token
-  parameters of pre-signed file URLs, so a returned file URL no longer
-  downloads; credential-named fields, including database properties named
-  like credentials, read as `"[redacted]"`. Failures of the OAuth, file
-  upload, bot user, and agent operations keep Notion's code but not its
-  message.
+- **Notion** REST results and error text withhold the whole query and
+  fragment of canonical Notion file links, including links embedded in
+  Markdown and async task results. External proxy URLs keep their bytes;
+  AWS and Google signing-parameter values are withheld at any host. Writes
+  carrying the plain or encoded `[redacted]` placeholder in a Notion file
+  link's own query or fragment are refused before dispatch. See the
+  connector runtime guide through `connecta.skill("connector:<id>")` in `execute_code` for recognized hosts and scanning limits. Credential-named fields,
+  including database properties named like credentials, read as
+  `"[redacted]"`. Failures of the OAuth, file upload, bot user, and agent
+  operations keep Notion's code but not its message.
 - **Vercel** replaces environment values with `"[redacted]"` instead of
   dropping the field, and withholds Vercel's error text for every reviewed
   operation and every operation whose request takes a credential-named
@@ -305,3 +313,10 @@ one; read or rotate withheld secrets in the vendor's dashboard.
   destinations to their scheme and host. A credential-named field now loses
   its whole value, not only its strings (a `cookies` list, a variable named
   `API_KEY`).
+
+## Contributor reference
+
+[Decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
+explains why auth selects the implementation. Maintained provider source
+skills and review tables live under `src/providers/` in the repository;
+`src/providers/vercel/value-safety.ts` owns Vercel's reviewed table.

package/documentation/provider-migration-0.29.md

@@ -7,8 +7,8 @@ version changes; [integrating services](./integrating.md) covers new connectors.
 
 This is the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709).
 Deploy it with the consolidated 0.29 release, not while the rework is in progress.
-BePresent and One&Many use Notion and Cloudflare; their actual grants and
-connector ids must be checked in deployment configuration before that release.
+Deployments that use Notion or Cloudflare must check their actual grants and
+connector ids in deployment configuration before that release.
 The provider audit establishes available auth modes, not production OAuth grants.
 
 Cloudflare's part of this guide is superseded: `cloudflare()` now selects its
@@ -58,7 +58,7 @@ complement. Replace `update_r2_bucket` with `cloudflare_api_mutate` using
 `cf-r2-storage-class` set to `Standard` or `InfrequentAccess`. Omit the body;
 include `cf-r2-jurisdiction` only when the bucket needs it. This remains a write.
 `execute` remains a write even when its program only calls GET.
-Trusted pools may execute writes; read-only pools use direct host-approved writes.
+Writable endpoints may run `execute`; `readOnly` endpoints refuse it.
 
 Vercel's `surface` and ownership rules were later replaced: `auth` now selects
 the implementation. See the [provider auth migration](./provider-auth-migration.md#vercel).