@zackbart/connecta 0.22.3 → 0.24.0

package/documentation/meta-tools.md

@@ -8,9 +8,8 @@ annotations, and `get_result` pages bounded results.
 
 Every deployment requires an executor and `tools/list` is exactly seven:
 `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
-`authorize_connector`, `get_result`, and `skills`. Discovery breadth and
-batching live in `connecta.search`, `connecta.describe`, and `connecta.batch`
-inside a program ([#273](https://github.com/zackbart/connecta/issues/273)).
+`authorize_connector`, `get_result`, and `skills`. Discovery uses `connecta.search` and `connecta.describe`; programs compose
+calls with JavaScript promises ([#273](https://github.com/zackbart/connecta/issues/273)).
 
 Code-first is what a model sees. Read-only work has two routes: `call_tool` for
 one known address, and `execute_code` when discovery or any wider work is
@@ -21,8 +20,11 @@ The [guest API contract](./code-mode.md) is what a program is promised.
 
 The route is chosen before discovery. An unknown address, a result that will be
 reduced, a call whose arguments depend on an earlier result, or work with
-multiple operations starts with one `execute_code` call and keeps discovery,
-calls, and reduction inside it. Distinct operations get distinct short
+multiple operations starts with `execute_code` and keeps discovery, calls, and reduction inside it
+when the schemas and result shapes suffice. An unfamiliar provider result may
+return a small sample for inspection before continuing in another call. This
+exception avoids repeated guesses at text formats or collection roots; it does
+not restore a mandatory discovery-only round trip. Distinct operations get distinct short
 `connecta.search` queries in that program. A known address needs only
 `call_tool`.
 
@@ -41,11 +43,13 @@ The measurements never contain program source, arguments, values, addresses,
 credentials, logs, or raw error text.
 
 Nothing became unreachable. `connecta.describe` takes the same addresses and
-formats as the internal catalog service, `connecta.batch` runs 1–10 parallel
-read-only calls and returns typed outcomes, and an unfiltered
+formats as the internal catalog service, ordinary promises compose read-only
+calls, and an unfiltered
 `connecta.search({})` browses every catalog a program can reach. Live connector
 probing is an operator concern: the operator pages and `/health` own it.
 
+Program search includes a bounded `connectorTitle` on each tool when configured, so choosing an account or environment does not require a provider read. It is context, not a ranking input or proof of live access.
+
 The three discovery routes use deliberately different envelopes. These are
 their smallest successful one-tool shapes:
 
@@ -62,7 +66,7 @@ their smallest successful one-tool shapes:
 
 The deployment-derived `execute_code` description includes a live connector
 inventory before any catalog search. It preserves registry order and uses each
-canonical id, adding `shortcut <name>` only when the program namespace differs.
+canonical id and a distinct configured title without generating a second name for programs. Titles normalize whitespace and are capped at 48 UTF-8 bytes, so account and environment hints cannot consume the entire inventory.
 The complete inventory line is capped at 256 UTF-8 bytes. Entries stay whole,
 and a truncated line ends with the exact `+N more` count. This reads only the
 configured registry: it loads no catalog, probes no credential, grants no
@@ -177,6 +181,22 @@ This split avoids two normative copies while preserving a valid first program
 for clients that never fetch the skill. Deployments without connector guides
 receive none of the short conditional guide pointers in their definitions.
 
+## Task guidance
+
+`skills({ name: "investigate" })` provides on-demand guidance for purchase
+verification, experiment checks, and customer or deployment investigations.
+The execute description points to it when planning is unclear; routine reads need no additional guide fetch. It explains how to
+resolve app/account/environment, follow evidence across services, establish
+capability limits, and stop with a clear answer or a specific gap. It is shared
+guidance, not a saved workflow or a source of deployment-specific ids. Existing
+connector titles, purposes, and guides still own those distinctions.
+
+The usage skill keeps the executable mechanics. Its dependent-call example
+searches each operation separately, uses the page's `tools` array and canonical
+addresses, and reports unresolved evidence instead of inventing an address or
+querying another account. Its source runs against local fixtures in the QuickJS
+suite, including missing and approval-required evidence.
+
 ## Result representation
 
 For object results, `structuredContent` is the canonical full-fidelity value.
@@ -296,19 +316,21 @@ Every typed `auth_required` call failure uses the same envelope:
 handoff:
 
 - `oauth`: an `authorizationUrl` and consent instructions;
-- `operator_config`: an `operatorUrl` ending in `/credentials`, plus the
+- `operator_config`: an `operatorUrl` to the mounted connection UI, plus the
   declared credential label and field names/guidance; or
 - `unavailable`: an honest deployment/configuration message.
 
 The class follows what the connector declares, not how it was authored: a
 `remoteMcp()` connection using `auth: { type: "credential" }` declares a slot
-and no OAuth flow, so it lands in `operator_config` beside every `api()`
-credential.
+and no OAuth flow, so it uses `operator_config` when both vault and UI are
+configured. Without either it returns `unavailable`, never a dead UI link.
 
 The tool accepts no secret. `force` applies only to OAuth and may discard its
 stored grant before restarting consent. Static credential values are written
 only through the same-origin interactive-user credential route, and only for a
-connector visible to that user. After OAuth consent or a human update, retry
+connector visible to that user with the relevant shared or personal management
+permission. OAuth start, including `force`, requires that permission too. Core
+callbacks work without the UI for authorized interactive callers. After OAuth consent or a human update, retry
 the original operation; a static update is read from the vault on the next call
 and needs no redeploy.
 
@@ -338,8 +360,7 @@ That route echoes the caller's own arguments back only while they fit a
 512-byte budget, and then whole — never clipped. An error envelope is not
 size-guarded the way a result is, so an unbounded echo would let a large
 argument object produce a refusal many times the deployment's result cap, on
-both `call_tool` and calls a program routes through `connecta.call` or
-`connecta.batch`. Over budget, `args` is absent and the `purpose` says to
+both `call_tool` and program calls through `connecta.call`. Over budget, `args` is absent and the `purpose` says to
 re-send what was just sent: the agent already holds its own arguments, and half
 of them would describe a call nobody made.
 
@@ -352,9 +373,7 @@ recovery query, each of which lands in both the text content and
 the address is the thing being corrected, a clipped one still identifies the
 mistake, and a short one — every real one — comes back exact and untagged.
 
-Shortcut ambiguity inside `execute_code` returns every colliding canonical
-address and points at `connecta.call`; the program or model must still choose
-which one matches the user's intent. `call_destructive_tool` accepts an optional
+`call_destructive_tool` accepts an optional
 `reason` of at most 500 characters for the host's human approval view. It is
 outer-call context only: Connecta neither treats it as authority nor passes it
 to the downstream connector, and an empty or whitespace-only one is read as no
@@ -395,7 +414,7 @@ about the mistake as all 40,000 would.
 A remote MCP tool's advertised `inputSchema` is checked in the shared
 invocation path before admission and provider dispatch. A mismatch is the
 non-retryable `invalid_args`, consistently across `call_tool`,
-`call_destructive_tool`, batch outcomes, and generated-code failures. The error
+`call_destructive_tool`, generated-code failures, and rejected promises. The error
 names the connector and operation and carries bounded `validation.issues`:
 JSON Pointer `path`, schema-keyword `code`, and expected shape. Submitted
 values are never copied into those findings.

package/documentation/mixpanel.md

@@ -50,7 +50,7 @@ password, not ordinary configuration. Mixpanel currently labels service-account
 MCP authentication beta. Prefer OAuth unless the deployment is intentionally
 headless.
 
-The same service account can arrive from `/credentials` instead, and there the
+The same service account can arrive from the connection UI at `/` instead, and there the
 operator pastes the readable pair rather than an encoded blob:
 
 ```ts

package/documentation/notion.md

@@ -58,7 +58,7 @@ it does not assume the REST interface's endpoint budget describes MCP traffic.
 
 One operator-managed credential: an internal integration token from
 [notion.so/profile/integrations](https://www.notion.so/profile/integrations).
-The deployment needs `credentials.encryptionKey` configured, or the token
+The deployment needs `vault: encryptedCredentialVault(storage, encryptionKey)` configured, or the token
 cannot be stored and every call fails `auth_required` at use.
 
 Two Notion-specific facts decide whether a working token is enough:
@@ -69,7 +69,7 @@ Two Notion-specific facts decide whether a working token is enough:
   default. `list_comments` and `add_comment` fail with 403 until an operator
   turns them on in Notion.
 
-`/credentials` offers a Test action, which calls `GET /v1/users/me` — the
+The connection UI at `/` offers a Test action, which calls `GET /v1/users/me` — the
 cheapest call that proves a token is live — and reports the workspace it
 authenticated into.
 

package/documentation/operations.md

@@ -33,8 +33,7 @@ and `test/package-surface.test.ts` fails if the two ever drift apart.
 There are exactly two deployment shapes.
 [`templates/node/`](../templates/node/) is what `connecta init` copies — the
 one standalone Node project, Docker-ready rather than Docker-only — and
-[`examples/worker/`](../examples/worker/) is the Cloudflare shape. Both ship
-the whole operator feature set; each README walks through its own enablement.
+[`examples/worker/`](../examples/worker/) is the Cloudflare shape. Both show explicit optional modules; each README walks through enablement.
 A third scaffold that is a diff away from either is the shape
 [#344](https://github.com/zackbart/connecta/issues/344) deleted, so do not add
 one.
@@ -84,22 +83,21 @@ optional.
 | `connectors` | — (required) | the connector set ([connectors](./connectors.md)) |
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
 | `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before interactive providers ([inbound auth](./auth.md)) |
-| `identity?` | all connectors; every interactive human is an operator | `{ connectorAccess?, operatorAccess? }` derives the request's connector view and shared-auth authority from its authenticated identity ([principals](./auth.md#principals-visibility-and-operators)) |
-| `storage?` | `memoryStorage()` | the one state seam for catalogs, result paging, credentials, and access tokens ([storage](./storage-and-credentials.md)) |
+| `identity?` | all visible; auth management denied; interactive activity reads | `{ connectorAccess?, credentialAdministration?, personalConnection?, activityAccess? }` derives separate use and management permissions ([identity](./auth.md#principals-visibility-and-operators)) |
+| `storage?` | `memoryStorage()` | connector state, catalogs, and result paging; pass storage explicitly to the optional vault ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
-| `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }` |
-| `branding?` | neutral Connecta defaults | operator-page and OAuth result-page labels and marks |
+| `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }`, or `"silent"` to suppress diagnostic output; independent of activity history |
+| `ui?` | unset | `operatorUi({ branding? })` from `/ui`; omitted means no browser UI routes or bundle imports |
 | `serverInfo?` | `connecta` / package version | `{ name, version, title?, websiteUrl?, icons? }` per the MCP icons spec |
 | `deploymentInfo?` | unset | arbitrary metadata exposed by `/health` |
-| `activity?` | unset | `{ store, readGate?, deploymentId? }` — payload-free activity storage, an optional operator-read gate, and a stable event label |
-| `credentials.encryptionKey?` | unset | base64 32-byte AES key for the connector vault. Without it, connectors declaring `credential` warn and their slots stay unmanageable |
-| `accessTokens?` | unset | `{ maxActive? }` (default 100) for operator-issued MCP bearer tokens. Requires an interactive operator provider, or construction throws ([access tokens](./auth.md#operator-issued-access-tokens)) |
+| `activity?` | unset | `activityHistory({ store, readGate?, deploymentId? })` from `/activity`; omitted means no event recording or history reads |
+| `vault?` | unset | `CredentialVault`; `encryptedCredentialVault(storage, encryptionKey)` from `/credentials` supplies the built-in encrypted implementation |
 | `discovery.concurrency?` | 4 | connector catalogs/status probes in flight at once |
 | `discovery.catalogTtlSeconds?` | 300 | fresh TTL for cached tool lists |
 | `discovery.persistCatalog?` | true | persist serializable catalogs as a manifest plus revision-addressed chunks |
 | `discovery.staleCatalogSeconds?` | 3600 | how long a complete expired catalog stays usable for agent SWR and as a refresh-failure fallback |
 | `discovery.probeTimeoutMs?` | 30_000 | per-connector deadline for catalog fan-out; a timed-out connector degrades alone. Not a tool-call deadline |
-| `calls.defaultTimeoutMs?` | **unset (opt-in)** | deadline for calls that pass no `timeoutMs`. Bounds one attempt, so retries can still extend total duration |
+| `calls.defaultTimeoutMs?` | **unset (opt-in)** | deadline for calls that pass no `timeoutMs`. Each admitted call makes one attempt |
 | `calls.maxResultBytes?` | 50_000 | inline result cap before truncation and `get_result` paging; a connector may override it. Invalid values warn and fall back |
 | `execute.maxEmittedBytes?` | 4_000_000 | aggregate `connecta.emit` bytes per run — a transport bound, not a context bound |
 | `execute.maxEmittedBlocks?` | 32 | content blocks `connecta.emit` accepts per run |
@@ -229,7 +227,6 @@ in.
 
 | Suite | Covers |
 | --- | --- |
-| `access-tokens.test.ts` | the `AccessTokenManager` — a one-time secret created, authenticated, renamed, and revoked, bounded names and active count, enumerable storage required, a deployment with no interactive operator refused — and the operator-only routes, down to historical activity still resolving a revoked token's name |
 | `activity.test.ts` | payload-free delivery: a rejected async write attaches to `waitUntil` instead of throwing, approved destructive calls record under their real entry point, result-size friction records without retaining the result, and a hallucinated connector id or invented identity is clamped so the event still cannot carry a payload |
 | `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, and the construction contract |
 | `bearer.test.ts` | constant-time bearer compare, case-insensitive scheme, 401 challenges, and the retired audience options refusing rather than silently unbinding |
@@ -240,20 +237,19 @@ in.
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
 | `cloudflare-provider.test.ts` | `cloudflare()` API and MCP construction, the code-mode safety manifest, API tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
-| `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and `connecta.ui` findable before connector search |
+| `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and no rendering instructions |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
 | `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, runtime-local rotating-token refresh coordination across request scopes, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
 | `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
-| `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
+| `execute.test.ts` | the code-mode host bridge: identifier sanitization, account titles in program discovery, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
-| `execute-ui.test.ts` | display-only `connecta.ui` (U1–U13) — one-string validation, multiplicity and budget, the provider, `_meta` delivery, shell isolation, and the absence of a payload-to-host call path |
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
-| `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
-| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, shared-auth operator control, and personal OAuth callback ownership |
+| `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, parallel-call, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
+| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, separate shared-auth and personal-auth management permissions, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
 | `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
@@ -262,17 +258,18 @@ in.
 | `notion-provider.test.ts` | Notion's API and MCP construction, the hosted safety manifest and drift behavior, the deliberate REST surface including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
 | `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
+| `optional-modules.test.ts` | absent modules, UI-free OAuth, fast lists and independent detail deadlines, explicit auth-management grants, invalid-resolver refusal, and passive OAuth consent-state protection |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `provider-registry.test.ts` | all seven maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
-| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
+| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from the connection UI: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
 | `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the refund-preference read and argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
-| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory and exact model-only Apps metadata → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, and deferred catalog reads through both discovery surfaces |
-| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: every built-in answered ahead of connector routes inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
+| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory, account titles, on-demand investigation guidance, and no Apps metadata or resource capability → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, removed connector HTTP hooks rejected at construction, and deferred catalog reads through both discovery surfaces |
+| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: built-in routes and unknown-path 404s inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
 | `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, current eleven-tool classifications, admission, exact account selectors, and no-guess rule |
 | `operator-view.test.ts` | the app's pure state rules from `view.ts`: filtering, page routing, capability states, activity summaries, drift display, and identity reset |
@@ -288,7 +285,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | Suite | Covers | Why Node |
 | --- | --- | --- |
-| `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, its agent instructions and setup guide pinning Claude and both ChatGPT Managed OAuth callback forms, one Node template that is also its own container, the same source running locally and in the container, the Node template's pinned esbuild install-script approval, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
+| `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, its agent instructions and setup guide pinning Claude and both ChatGPT Managed OAuth callback forms, one Node template that is also its own container, the same source running locally and in the container, the Node template's pinned esbuild install-script approval, explicit optional modules in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
 | `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
 | `doctor-cli.test.ts` | `connecta doctor`'s executor line and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the credential-free maintainer drift checker: recorded touched endpoints, heading, table, and inline MCP inventories, setup-only providers, live-schema ownership, a quiet revision bump, clear failures for unavailable inputs, `$ref` traversal, and one well-formed row per endpoint | spawns the checker against filesystem fixtures |
@@ -300,7 +297,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
 | `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, plus abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic | mocks Node child-process streams |
-| `quickjs-executor.test.ts` | the child-process sandbox — code normalization, lazy namespace proxies, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
+| `quickjs-executor.test.ts` | executable usage example with dependent, missing, and approval-required evidence; the child-process sandbox — code normalization, provider bridges and canonical connector calls, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |
@@ -311,8 +308,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | Suite | Covers |
 | --- | --- |
-| `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
-| `browser/program-ui.spec.ts` | the display-only Apps shell in a real browser: local payload JavaScript runs, `connecta` stays absent, and forged payload messages never become host tool calls |
+| `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is
 internal, not public API: when set, `remoteMcp()` uses that `Transport` instead

package/documentation/operator-ui.md

@@ -4,109 +4,87 @@ The browser surface a human uses to see what a deployment exposes and to manage
 the authentication material behind it. It is a small Preact app compiled by the
 repository's own esbuild step and inlined into a data-free server shell.
 
-Read [`ethos.md`](../ethos.md) first. The boundary this subsystem lives inside
-is the human-management invariant: **members may manage authentication material
-for every connector their code-derived view includes, operators may also manage
-deployment tokens and global activity, and neither may change the connector set, tool catalog,
-annotations, requested OAuth scopes, admission policy, or identity rules.**
-`test/operator-boundary.test.ts` proves it after every mutation route.
-
-Both deployment shapes ship the whole feature set behind it, because pages for
-things a deployment cannot do are worse than no pages
-([#345](https://github.com/zackbart/connecta/issues/345)). The
-[Node template](../templates/node/) carries sign-in, vault, tokens, and
-activity as commented blocks in `src/index.ts` — plus a deployment-owned
-`src/file-activity.ts` that is compiled rather than commented — and the
-[Worker example](../examples/worker/) wires the first three and comments the
-fourth, which needs a D1 database. Each README walks through its own
-enablement.
-
-The vault is the one whose page needs a second thing. `/credentials` lists
-connector credential slots, so `credentialManagement` stays `no_slots` — and
-the nav entry stays hidden — until a connector declares `credential`, however
-well-configured the vault is. Neither shape's shipped connectors need a secret,
-so both carry the slot's shape as a comment beside a connector and say so in
-their walkthrough, which is the honest version of the same page count.
-
-## The shape
-
-| Piece | What it owns |
-| --- | --- |
-| `src/ui.ts` | The served HTML: branding, gated URLs, CSP-nonced script tags, the four page titles, and `buildUiData` — the `/ui/data` payload. |
-| `src/operator-ui/model.ts` | The transport types both sides share, plus connector filtering. |
-| `src/operator-ui/view.ts` | The app's state shape and every pure rule over it. No DOM, so `test/ui.test.ts` calls it directly. |
-| `src/operator-ui/app/` | The browser app: `store.ts` (state and every request), `main.tsx` (shell, gate, router), and one component file per page. |
-| `src/operator-ui/browser.css` | One stylesheet, inlined into the shell. |
-| `src/operator-ui/generated.ts` | The build output: the bundle and the stylesheet as two exported strings. |
-
-The server renders a mount point, not a page. Branding, the optional Clerk
-loader, and every operator-configured URL stay in `src/ui.ts`, where they are
-gated before they can become an attribute; the bundle renders everything that
-has a state. Two roots share one store: `#operatorNav` and `#operatorContent`.
-
-Cloudflare Access is ambient browser auth. When the current Worker invocation
-has `ctx.access`, the shell selects the `cloudflare-access` UI mode, emits no
-Clerk loader, and sends no browser-readable token. Same-origin fetch includes
-the HttpOnly `CF_Authorization` cookie, Access admits it at the edge, and the
-server reads the resulting runtime identity. Sign out navigates to
-`/cdn-cgi/access/logout`. Mutations still require an exact same-origin
-`Origin`; an ambient cookie does not weaken the CSRF boundary.
-
-The shell is shared by members and operators. `/ui/data` uses the same
-identity-scoped registry view as `/mcp`, so it cannot list a connector the
-current caller cannot discover. A member sees credential and OAuth controls for
-every visible connector. Personal actions resolve to that member's principal
-partition; shared actions change the deployment-wide grant. The access-token
-and global activity pages require `identity.operatorAccess`. Existing
-deployments that omit that resolver keep every interactive human as an
-operator.
-
-This runtime selection is the Clerk migration seam. A deployment may contain
-both providers: before Worker-level Access is attached, the data-free shell
-selects Clerk; after Access supplies `ctx.access`, it selects ambient auth. That
-is not two same-hostname gates running in parallel. Access is upstream and a
-request it rejects never reaches Clerk. Keeping Clerk in the array preserves a
-code-level rollback after Access is detached.
-
-The Clerk loader is intentionally blocking. The inline operator bundle calls
-`boot()` as soon as the parser reaches the end of the body, so a deferred Clerk
-script would make an expected parse-time gap look like a permanent network
-failure. Blocking also preserves the existing failure path: after a real
-loader error, the parser continues and `boot()` renders the Clerk load message.
-Clerk's redirect from the major-version loader URL to its pinned asset keeps
-the same ordering.
-
-## Rules that are not obvious
-
-- **No operator data in the shell.** Every page serves the same markup. Connector,
-  credential, token, and activity data arrives only through the authenticated
-  `/ui/*` APIs, and the shell is identical whether or not a caller is signed in.
-- **One store, one identity.** `store.ts` is the only file that touches `fetch`,
-  `localStorage`, Clerk, or the ambient Access mode. Every token-bearing request carries the current session's token,
-  while Access requests deliberately carry none,
-  and every response is dropped unless the identity that asked for it is still
-  the one on screen. `resetIdentity` replaces all identity-scoped state at once
-  and bumps a generation that work already in flight compares itself against.
-- **Escaping is structural.** Components return elements; nothing builds HTML
-  from strings. A value that could be a URL passes `safeHttpHref` before it may
-  become an `href`, mirroring the server-side gate in `src/ui.ts`.
-- **Secrets are shown once.** A created access token lives in state only, and
-  leaving the page — by navigation or by `pagehide`, which covers the
-  back-forward cache — unmounts it.
-- **Every flow has four states.** Loading, error, empty, and success, with no
-  dead end: a failed save keeps the form and its typed value, a failed list
-  offers a retry, and an empty collection says what would fill it. A mutation
-  that fails is still a resolved promise — `mutate` lands the failure in state
-  rather than rejecting — so a caller that clears a form must clear it on a
-  confirmed success, never on resolution. `createAccessToken` returns that
-  answer as a boolean for exactly this reason.
-- **Drift is counts, and absence is its own answer.** The connector card reads
-  `catalogDrift` ([#343](https://github.com/zackbart/connecta/issues/343)) as
-  four category counts and a timestamp. There is no drill-down, because a tool
-  name or a schema here would make an operator page the payload surface the
-  drift model refuses to be. A connector with no report renders as *not
-  observed*, never as clean: this runtime having seen no refresh is not the
-  same claim as a refresh having found nothing.
+Read [`ethos.md`](../ethos.md) first. Code declares capabilities and access;
+the UI displays the current user's effective permissions and manages only
+authentication material explicitly permitted by that code. It never edits the
+connector set, tool catalog, annotations, OAuth scopes, or permission rules.
+
+## Enable the UI
+
+```ts
+import { operatorUi } from "@zackbart/connecta/ui";
+
+createConnecta({
+  connectors,
+  executor,
+  auth,
+  ui: operatorUi({ branding: { productName: "Team connections" } }),
+});
+```
+
+The UI module owns its browser bundle and routes. Omit `ui` to omit those
+routes and runtime imports. OAuth callbacks remain in core; authorized
+interactive MCP callers can complete consent without the UI. Branding belongs
+to `operatorUi` options, with neutral callback branding when no UI is mounted.
+
+## Connections and activity
+
+Connections is the main page. Each connection combines its status, effective
+permissions, credential metadata, and permitted OAuth or credential actions.
+There is no separate Credentials or Tokens tab. A user may see and invoke a
+shared connector without permission to replace the grant everyone uses.
+`identity.credentialAdministration` and `identity.personalConnection` select
+shared and personal management rights, and both default to none.
+
+Activity appears only when the optional history module has a readable store
+and the caller passes `identity.activityAccess` and any additional read gate.
+It is a global history, so permission to use one connector does not imply
+permission to inspect that history. There is no member roster or policy editor.
+
+The Node and Worker deployment READMEs show how to enable the modules and grant
+the intended identities access. The configured bearer in the Node template can
+read connection status but never mutate credentials as an interactive human.
+
+## Loading and request lifetime
+
+The server shell contains no connector or credential data. Authenticated
+`/ui/data` returns the configured visible connection list without waiting for
+provider status or tool discovery. Details load through `GET /ui/connectors/<id>`, independently,
+under a bounded request lifetime. Unknown and loading states stay explicit;
+a provider failure leaves the other connections usable.
+
+A status read does not start OAuth or create authorization handoffs. Connect is
+an explicit authorized POST. Successful save, reconnect, and disconnect actions
+show their result without waiting for an unrelated full-catalog reload. Server
+mutations still await catalog invalidation before replying, so another request
+cannot consume a persisted catalog from before a credential change.
+
+Each details request owns and closes its downstream connector scope. Never
+cache a transport, request signal, or awaited promise in the UI module.
+
+## Browser identity and security
+
+Cloudflare Access is ambient browser auth. When the Worker invocation has
+`ctx.access`, the shell emits no Clerk loader or browser-readable token.
+Same-origin fetch carries the HttpOnly Access cookie, and the server uses the
+trusted runtime identity. Sign out navigates to `/cdn-cgi/access/logout`.
+Clerk deployments use their configured interactive provider.
+
+Mutation requires exact same-origin `Origin`, an interactive identity,
+connector visibility, and the relevant management permission. Personal actions
+resolve only to the current principal's partition. Credential reads return
+metadata, never saved values or masked fragments. Mutation cannot change any
+declared capability. `test/operator-boundary.test.ts` checks that boundary.
+
+The browser store fences responses by identity generation. Switching identity
+clears the prior identity's state and discards its outstanding responses.
+Components render elements, not HTML strings; links pass the shared URL gate.
+Loading, failure, empty, and success states must all provide a useful next
+step. A failed mutation preserves form input and does not masquerade as success.
+
+Catalog drift remains counts and a timestamp. A missing observation means
+"not observed", not that the downstream catalog is unchanged. The UI does not
+expose tool schemas or raw payloads as diagnostics.
 
 ## Working on it
 
@@ -127,7 +105,7 @@ well as Node and there is no DOM in either:
   DOM-lib program (`tsconfig.operator-ui.json`) because it imports the store.
 - `test/browser/operator-ui.spec.ts` — the wiring, in a real browser:
   Clerk loader order across its version redirect and a real load failure, plus
-  credential, token, and OAuth flows end to end, including their failure and
+  credential and OAuth flows end to end, including their failure and
   empty states. Run it with `npm run test:browser`
   (`npm run test:browser:install` once, for Chromium). It is not part of
   `npm run check`.