@zackbart/connecta 0.33.0 → 0.34.1

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 what a page shows or where a route goes    | [Pages](#pages)                                                                                                  |
 | 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)                               |
@@ -23,82 +24,6 @@ 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.
 
-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: [auth](./auth.md#management-permissions) does. Interactive maintainers
@@ -108,24 +33,333 @@ 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.
 
+## Pages
+
+The UI shows configuration and never edits it. Deployment code owns
+connectors, grants, pools, agents and classification. The UI changes only
+credentials, OAuth connections and agent tokens, through the existing routes.
+No select menu displays configuration. Copy is short labels; a failure names
+what to do next in one or two sentences and never quotes a route's or
+downstream's text.
+
+| Path               | Page                                                   | Who        |
+| ------------------ | ------------------------------------------------------ | ---------- |
+| `/`                | Overview (a member gets the member page)               | Maintainer |
+| `/endpoints`       | Endpoints; `#mcp/<pool>` opens that row                | Maintainer |
+| `/connectors`      | Connectors list; `?view=matrix` for the matrix         | Maintainer |
+| `/connectors/<id>` | Connector detail; `#tools`, `#connection`, `#activity` | Maintainer |
+| `/activity`        | Activity                                               | Maintainer |
+| `/tokens`          | Tokens, when token management is open to the viewer    | Maintainer |
+| `/settings`        | Settings                                               | Maintainer |
+
+`/access` redirects to `/endpoints`, `/tools` to `/connectors`, and `/config`
+to `/settings`, replacing the history entry. Connector hashes `#config`,
+`#auth` and `#diagnostics` redirect to `#connection` and keep query
+parameters such as signed handoffs. A pool member sees the
+[member page](#use-the-member-page) on every path.
+
+### Overview
+
+- **Status pill.** "N need attention" (red when a connector is failing) or
+  "All healthy". No pill without connectors.
+- **Stat tiles.** Connectors (healthy of total, a bar with one segment per
+  connector in its health color), Endpoints (count, a bar split read-only and
+  read-write), and People · Agents (both counts, up to eight avatars and agent
+  marks; a tokenless agent's mark is hollow). A dot legend counts each segment
+  kind; the first two tiles link to their pages. At 760px and below the tiles
+  sit two up, with People · Agents as one row across both.
+- **Needs attention.** One row per connector whose health is not ok, in
+  configuration order, then one per agent in a pool whose token is missing or revoked. A
+  row names the problem ("crm needs authorization"), the endpoints it
+  affects ("Affects /mcp and /mcp/team") or the agent URL it can't connect at,
+  and links to the existing fix: Connect, Replace key or Inspect on
+  the connector's Connection tab, or Issue token on Tokens. A row with a
+  problem code also has Copy fix prompt. A problem keeps its row and
+  prompt when the connector's detail read failed, prefixed "Details didn't
+  load". Surviving connector rows retain their order as individual reads settle,
+  even when their severity changes. With no rows it reads "All clear".
+- **Who reaches what.** The [connection map](#connection-map).
+
+### Connection map
+
+An SVG flow of callers (people in contract order, then declared agents) to
+endpoints (`/mcp`, then pools) to connectors in config order, with a last
+column of each connector's read and write tool counts. A connector whose
+catalog is unknown (failed or not yet observed) draws a muted dash there
+instead of "0 tools".
+
+- A grant link takes its connector's health color. Grants on a read-only
+  endpoint are dashed; an agent's link to its pool is dotted while it has no
+  issued token. Plain `/mcp` admits no agents. A read-only endpoint carries a
+  read-only chip.
+- Hovering or focusing a node dims everything off its paths and replaces the
+  legend with one sentence, such as "alice reaches 2 connectors through /mcp
+  and /mcp/team: 6 tools, 1 write." The sentence is also the node's accessible
+  name. Hover wins while both are set.
+- The map is one tab stop. Arrow keys move within a column and to the nearest
+  node in the next one; Home and End go to the first and last node.
+- Click or Enter opens the node's page: a connector's Tools tab (Connection
+  when it needs attention), an endpoint's row on Endpoints, a person's first
+  endpoint, or Tokens for an agent when that page is open. A node without a
+  page is a `group`.
+- The drawing never scales below 880px; a narrower card scrolls it sideways.
+  At 960px and below it becomes a list with one entry per endpoint: its mode,
+  its callers as chips that link like map nodes, and its connectors with
+  health. With no connectors it reads "Nothing to map yet".
+
+### Endpoints
+
+One row each for `/mcp` and every pool: the path, a read-only pill on a
+read-only endpoint, a copyable URL, who can use it, its connectors as colored
+monograms (four, then "+N"), its tool count over a read and write bar, and a
+Setup button.
+
+- Who can use it is `root.maintainers` on `/mcp` and the pool's `members`
+  elsewhere, as an avatar stack named on hover and to screen readers (label,
+  raw id when the label is null, or agent name). Four show, then a "+N"
+  button. A pool with agent members labels its two URLs People and Agents.
+- Expanding a row lists everyone by name, then each connector with what it
+  runs as and its tools, write tools amber with a pencil. Runs-as comes from
+  the endpoint's matrix cell: "Shared · saved <date>", "Shared · connected
+  <date>", "Shared · not configured", "Shared · set in deployment", "Shared ·
+  no credential needed", "Personal · N of M connected", "Workspace · people:
+  self · agents: <owner>" (or "none"), or "Everyone acts as <subject>".
+- A connector that needs attention gets a status dot on its monogram and
+  beside its name, linking to its Connection tab.
+- Setup opens a drawer with the URL and a Claude Code, Codex or JSON snippet
+  with a copy button. No snippet carries a token.
+
+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
+
+One card per connector: title and id, one status pill, a Shared or Per person
+badge, a Read-only badge when connector `readOnly` is enabled, its tool count over a read and write bar, and when it was last called.
+All, Needs attention and Healthy filter the cards, with counts, beside a
+search field. A connector that is not fine adds one action (Connect, Replace
+key or Inspect) that opens its Connection tab.
+
+Every view shares one verdict per connector: the server's problem code first
+(a failed catalog reads "Catalog failed", never "Connected"), then a failed
+detail read ("Couldn't load", with no fix prompt), then a non-ok status.
+Catalog drift is informational: it stays in the connector's Connection panel
+with its fix prompt and in Activity, and never affects health or attention.
+
+Health does not bounce while details load. A connector whose detail read is
+in flight (its `/ui/data` row is `loading`, during sign-in, Retry or a
+connector's Refresh) keeps the verdict the page last showed for it on every
+view (cards, filter counts, the Overview headline, bar, attention list and map,
+Endpoints and the connector page) until that read settles, never "Loading
+details" or an in-between verdict. A connector with no earlier verdict shows
+its contract status. Each connector changes only when its own read settles,
+so one slow read never holds back the others and no row moves for an
+in-between verdict. A new signed-in identity starts fresh. Cards reserve the action footer
+even when no action is needed and the tool bar row even when the catalog is
+empty. Each card header keeps its title, status and id/scope badges on single
+lines; long text truncates with ellipsis and retains its full value on hover
+and for screen readers. The connector detail header and Overview attention
+text follow the same rule, and truncated links remain keyboard focusable.
+Wider status labels never change the card height.
+
+The top bar uses an icon-only Search button (⌘K or Ctrl+K opens the palette).
+Deployment names stay on one line with ellipsis and their full name on hover;
+a name matching the product label is omitted. Tabs scroll horizontally when
+needed, moving to a second row on narrow screens.
+
+A List / Matrix toggle (`?view=matrix`) switches to a table of connectors by
+endpoint, `/mcp` first. A row header is the connector's monogram and name, plus
+a status dot linking to Connection when it needs fixing. Each cell is a pie of
+how much of the live catalog it grants, with "all", a count, or a dash for
+none; read-only columns are hatched. Only granted names still in the live
+catalog count. An unknown catalog shows a dashed empty ring and "?". A cell
+with grants is a button named like "GitHub on /mcp/support: 1 of 2 live
+tools, read-only"; it opens a popover of that cell's tools, each with a read
+or write pill (a write struck through on a read-only endpoint), and its
+runs-as. Escape or Tab returns focus to the cell. CSS anchor positioning
+places the popover below the cell, or above when there is more room, and the
+page sets no inline styles. Without anchor support the same list opens as a
+row under the connector.
+
+### Connector detail
+
+The title, status pill, id, auth badge and read and write bar, then three
+tabs:
+
+- **Tools.** Each tool by its mono address with a Read or Write badge and
+  annotation badges (Destructive, Open world), filtered by search and All,
+  Read and Write. A tool opens its schema in a side drawer.
+- **Connection.** An Authentication card (mode, OAuth client mechanism, who
+  manages it, OAuth actions, and the credential card with masked last four,
+  field states, and Replace, Test and Remove); a Diagnostics card of tiles
+  (catalog age, last call, drift counts) with a fix prompt beside each
+  problem; and a Configuration card. Its badges name the kind (Remote MCP,
+  HTTP API or Custom), provider, auth scope, endpoint host and usage guide.
+  The auth row names the mode and draws each auth fact as a mono badge
+  (credential fields, header and scheme, static header names, OAuth scope, API
+  origins as `→ api.crm.example`, OAuth endpoints, client metadata host,
+  token auth method, Client secret, PKCE, extra parameter and header names).
+  Tiles follow for the result cap, call admission rules and transport. Any
+  other key becomes a tile labelled from its name.
+- **Activity.** The [Activity](#activity) page for that connector, without
+  connector chips or monograms.
+
+#### Read catalog drift
+
+The connector's drift panel reports the last catalog comparison in this
+runtime and identity partition. It never lists tool names or schemas. A
+personal OAuth refresh belongs to that user; another user or endpoint subject
+does not inherit it. A runtime restart or bounded observation eviction resets
+the report until another listing is served.
+
+“No catalog refresh yet” means this partition has no observation. “No reviewed
+baseline” means a listing was observed without a reviewed classification.
+“Matches the reviewed manifest” requires a baseline, successful verification,
+no differences, and schema pins for every live reviewed tool. “Schemas not
+pinned” and “Partial schema coverage” describe missing review evidence; they
+are not clean schema comparisons. “Schema verification unavailable” replaces
+an earlier successful report if hashing fails. Known differences remain visible
+alongside coverage or verification limits. Each operator refresh returns the
+comparison from the catalog it just loaded, including hashing failures and
+schema changes, without another downstream status probe.
+
+The unserved count excludes reviewed names explicitly marked optional for
+plan, feature, or permission gating. Present optional tools still participate
+in annotation and schema comparisons. Dropped tool names are counted even
+without a baseline, and do not establish one.
+
+### Settings
+
+The configuration snapshot as tiles, tagged "Defined in code", with no
+editing controls. An empty section is not drawn.
+
+- **Deployment.** Fact chips: name and version (`Production · v1`), Writes
+  allowed or Read-only, connecta version, public URL, allowed origins,
+  sandbox, storage, activity store, deployment ID, website, icon count and
+  `deploymentInfo` keys. Default memory storage reads "Memory · default" as a
+  warning: on Node a restart loses it.
+- **Sign-in.** One tile per inbound auth provider in the order they are tried,
+  with its mark and whether it admits people or machines; the agent-token
+  tile counts agents ("3 agents"). Then a Maintainers tile with the `/mcp`
+  maintainers, or "None". With no providers an Open tile comes first.
+- **Features.** Vault ("Seals OAuth" when it does), activity, agent tokens
+  and any other module, on or off.
+- **Limits.** Each limit as a value over a short label: durations in their
+  largest whole unit, sizes in decimal KB or MB with exact bytes as a
+  tooltip, counts with separators, "No limit", and On or Off. A null tool
+  timeout shows the host-call timeout it falls back to. Headline limits and
+  any limit set in code draw large. The rest sit behind one disclosure
+  ("17 defaults") with Discovery, Results, Programs and Requests groups. A
+  value set in code (by `configSources`) has an accent dot; a default reads
+  muted. Activity retention counts as set only when the activity store
+  reports `optionSources.retentionDays` as `"config"`, as the shipped D1 and
+  SQLite stores do.
+- **Overrides.** Each classification override as tool address and verdict.
+- **Other.** Any snapshot key Settings does not map, as a tile labelled from
+  its name, set only when its value carries `source: "config"`.
+
+### Tokens
+
+One row per agent declared in code, in `GET /ui/access-tokens` order: agent
+mark and name, pools as chips, a state pill (No token, Issued or Revoked), the
+issue or revoke date, and last seen ("never" when null). The heading note
+reads "Declared in code"; nothing creates or renames an agent. Narrow screens
+stack each row into a card.
+
+- Issue appears for a slot with no token or a revoked one; Rotate and a quiet
+  red Revoke for an issued one. Rotate and Revoke ask first in a row under the
+  agent, with focus on Cancel.
+- Every mutation sends `{ "expect": "<revision>" }` with the slot revision the
+  operator saw. A new secret opens once in a dialog with a copy button and
+  "You won't see this token again."; closing it drops the secret, 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.
+- A sent mutation leaves its slot unresolved until its successful response is
+  validated. 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 later slot-list read succeeds. Until then its
+  controls are off with "Refresh to continue", and each action is checked
+  again just before it is sent.
+- Under the recovery banner Tokens has no Refresh or list Retry of its own,
+  and an open rotate or revoke question closes.
+
+### Activity
+
+Counts for the loaded history (calls, failed, tools, catalog changes), also
+in its accessible summary, and a strip of calls over time with failures in
+red when the calls span more than a minute.
+
+- **Filters.** One bar: search, All / Failed / Succeeded (`?outcome=failed`
+  keeps errors and timeouts, `?outcome=succeeded` successes and approvals),
+  and chips for each loaded connector and source (`?connector=`, `?source=`).
+  Pressing a pressed chip clears it, and a selected value keeps its chip.
+  Another `?outcome=` value matches exactly and shows as a clearable Exact
+  outcome chip.
+- **Rows.** Grouped by recorded request id on a shared rail. Each shows a
+  status dot, time, caller (a person by label or id with initials, an agent
+  by name with its mark, anything else by kind), connector monogram and tool
+  address, a write tag, the failure reason, and duration and size. Opening a
+  row lists what was recorded: result, how it ran, classification, exact
+  duration and size, caller, stable caller id, request id, client, and
+  connecta version. Unrecorded fields are left out. Catalog changes are rows
+  with added, removed and changed counts.
+- **Empty.** "No calls yet" with Refresh, or "No matches" with Clear filters.
+
+### Navigation, gates and recovery
+
+The top bar is one row: the mark, branding and deployment name, the section
+links (Overview, Endpoints, Connectors, Activity, Tokens, Settings), then
+icon-only Search (the command palette, also ⌘K or Ctrl+K), Appearance, and Account
+(the signed-in account with Sign out or Change token). The mark is connecta's
+drawn "C" only when no product name, owner or favicon is configured; with
+`branding.favicon.svg` it is that SVG; otherwise there is none. The sign-in
+gate shows the same mark above "Sign in". Below 820px the section links move
+to a second row that scrolls sideways and keeps the current section in view,
+with Search remaining an icon. A member's top bar has only branding and
+Account. The command palette searches visible pages, connectors and tools,
+opening connector results on Tools.
+
+`GET /ui/api/config` is the browser's one gate: a 401 shows sign-in, the
+private 404 shows "No access" with who to ask and 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 each read
+checks the role again when it is sent. Until a role is confirmed the page
+shows its loading or error state and no navigation. Activity and Tokens keep
+their own permission gates.
+
+The store keeps the last confirmed role through a failed refresh: a
+maintainer's page stays mounted, inert and dimmed, under one shell banner
+("Couldn't load configuration" with Retry), and sends nothing maintainer-only
+until a contract confirms the role again. Recovery closes the page's dialogs,
+drawers, 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 whose `manage` lists that action. Otherwise the write is
+not sent and its row says so. An answer with a different role clears
+everything read under the old one.
+
 ## 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:
+connections**, has no tabs; its heading shows the signed-in email when the
+sign-in exposes one (Clerk's primary email), and its top bar shows branding and
+an **Account** button with Sign out or Change token. It lists:
 
-- **Your endpoints**: each admitted `/mcp/<pool>` URL with a copy button and
-  **Client setup**. For example, Bob in pool `team` copies
+- **Your endpoints**: one card per admitted `/mcp/<pool>` URL with a copy button
+  and **Client setup**. For example, Bob in pool `team` copies
   `https://connecta.example.com/mcp/team` into an MCP client and authenticates
   as Bob.
-- **Your 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.
+- **Your accounts**: the personal connectors in their pools, each with a
+  monogram, tool count, one status badge in an aligned column, and only the
+  controls its `manage.actions` lists. A saved credential that no longer fits
+  or does not work adds a short note beside the tool count. 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; Clear asks first.
 - **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
@@ -160,8 +394,9 @@ 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
+`{ "error": "not found" }`. An open deployment's anonymous caller gets
+`role: "maintainer"` but has no principal: activity is `"forbidden"`, the
+activity and access-token routes answer 404, and owners are `null`. 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.
 
@@ -193,7 +428,8 @@ The maintainer view carries:
   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
+  owner, or `null` on plain `/mcp` and in an ownerless pool, where agents do
+  not see the connector at all; 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,
@@ -273,7 +509,7 @@ 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. Geist Sans, Geist Mono, CSS, JavaScript and dependency notices are hashed assets
+Tailwind v4. Hanken Grotesk, JetBrains 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. Ahead of the stylesheet, every operator page (sign-in
@@ -334,7 +570,7 @@ A later focus return can request another status read. Recovery never starts OAut
 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
+is empty. Overview, 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
@@ -364,19 +600,6 @@ 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 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 agent tokens through the existing routes.
 
 ## Contributor reference
 
@@ -390,6 +613,20 @@ 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 Overview's map and attention rows are pure functions of the contract in
+[connection-map.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/connection-map.ts)
+and [overview.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/overview.ts),
+covered by `test/operator-connection-map.test.ts` and
+`test/operator-overview.test.ts`; `src/operator-ui/styles/overview.css` holds
+the page's styles.
+
+`src/operator-ui/config-summary.ts` maps the snapshot and its provenance to
+those tiles: one table of limit labels, the formatters, and the walk that turns
+an unmapped key into an Other tile. `app/config-tiles.tsx` draws them, and
+`test/operator-config-summary.test.ts` checks formatting, provenance, unknown
+keys, an empty deployment, and that a real deployment's snapshot leaves no key
+unmapped.
+
 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
 [UI implementation](https://github.com/zackbart/connecta/blob/main/src/ui.ts)

package/documentation/provider-auth-migration.md

@@ -13,6 +13,28 @@ uses one implementation: configure two ids for both.
 
 ## Stripe
 
+## Choose OAuth or an API key
+
+Import `stripe` from `@zackbart/connecta/providers/stripe`. Choose one of two setup paths:
+
+```ts
+// OAuth: Stripe's hosted MCP. Authorize the connection with Stripe.
+stripe("billing", { purpose: "Payments", auth: { type: "oauth" } });
+stripe("billing", { purpose: "Revenue reports", auth: { type: "oauth" }, readOnly: true });
+
+// API key: Connecta's REST connector. Paste the key into this connection in the operator UI.
+stripe("billing", { purpose: "Payments", auth: { type: "apiKey" }, mode: "production" });
+stripe("billing", { purpose: "Revenue reports", auth: { type: "apiKey" }, mode: "production", readOnly: true });
+```
+
+For an API key, set `mode` to `"production"` or `"sandbox"` to match the key.
+Use a secret (`sk_`) or restricted (`rk_`) key. For read-only access, prefer a
+restricted `rk_` key configured with only read permissions: Stripe enforces
+those permissions too. Connecta's `readOnly: true` omits non-read tools and
+refuses their calls on every endpoint. Omit it for the default writable connector;
+endpoint restrictions still apply. OAuth needs no `mode` and can reach both live
+and sandbox accounts through Stripe's account selectors.
+
 Stripe's hosted MCP server stops accepting secret keys and untagged
 restricted keys on 2026-10-31; Stripe still documents agent-tagged restricted
 keys for it. Connecta's hosted Stripe connection is OAuth only either way, and

package/examples/worker/AGENTS.md

@@ -72,7 +72,7 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
   `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET`, and `CONNECTA_TOKEN`
   together, and pass `--pool ci`, a pool that lists the agent.
   Machine clients are the `agents` declared in `src/connecta.config.ts`. Issue
-  or rotate a token through the Access-authenticated operator page or trusted
+  or rotate a token through the operator Tokens page as a signed-in maintainer or trusted
   `AccessTokenManager.rotate` tooling against this same D1 storage, as README
   "Machine tokens" describes. Never configure a static bearer or open startup.
   UI, vault, and activity use explicit optional imports;
@@ -80,20 +80,26 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
 - Organize agent pools by connecta's agent pool layout:
   `node_modules/@zackbart/connecta/documentation/auth.md#organizing-an-agents-pools`
   ([online](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#organizing-an-agents-pools)).
-  Each agent keeps one Connecta connection whose client picks the pool per
-  turn: base pool `<agent>` (shared connectors, no `owner`) outside a
-  one-on-one, and `<agent>-<user>` (the base plus that user's own connector
-  ids, `owner` set to their Workspace address) only with that user. Never list
-  another person in a `<agent>-<user>` pool: its per-user connectors act as
-  that user for every member. Never add a second Connecta connection or mount
-  downstream tools directly.
+  Each agent keeps one Connecta connection whose harness, never the model,
+  picks the pool per turn. Tiers are nested pools of shared connectors with
+  no `owner`, each spreading the tool list below. Recommended names are
+  `<agent>` for the lowest and `<agent>-<tier>` above it; any named pool,
+  including an existing `team` or `leadership` pool, may be a tier if all its
+  human members are cleared for it. A chat gets the most capable tier everyone
+  present is cleared for, and the lowest when anyone present is unknown.
+  `<agent>-<user>` (that user's highest tier plus their own connector ids,
+  `owner` set to their Workspace address) is used only in a one-on-one with
+  that user. List only cleared people in a tier, and never another person in
+  a `<agent>-<user>` pool: its per-user connectors act as that user for every
+  member. Never add a second Connecta connection or mount downstream tools
+  directly.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
   rather than leaving the default. README "UI and encrypted credentials" shows
   the shape.
 - After configuration changes, typecheck: inside the connecta repository that
-  is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
+  is `pnpm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
   complete their browser authorization flows before calling setup complete.