@zackbart/connecta 0.23.0 → 0.24.1

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`.

package/documentation/optional-modules-upgrade.md

@@ -0,0 +1,243 @@
+# Upgrade to 0.24.0 optional modules
+
+This is a breaking configuration change. Core still owns the same seven tools,
+connector discovery, execution, invocation, and enforcement. UI, encrypted
+credential storage, activity history, and configured bearer authentication now
+have explicit imports. Select features when constructing the deployment;
+there is no runtime plugin installation or registration.
+
+Do this migration in the deployment repository on a branch. Do not re-run
+`connecta init`, replace the connector set, or copy a template over local code.
+The examples below omit unchanged connectors, executors, and storage adapters.
+Install and pin `@zackbart/connecta@0.24.0` after completing the migration.
+
+### Configuration and import changes
+
+| Before | After |
+| --- | --- |
+| UI implicitly available | Import `operatorUi` from `@zackbart/connecta/ui` and set `ui: operatorUi()` |
+| Root `branding` | `ui: operatorUi({ branding })` |
+| `credentials: { encryptionKey }` | Import `encryptedCredentialVault` from `@zackbart/connecta/credentials`; set `vault: encryptedCredentialVault(storage, encryptionKey)` |
+| `activity: { store, deploymentId, readGate }` | Import `activityHistory` from `@zackbart/connecta/activity`; set `activity: activityHistory({ store, deploymentId, readGate })` |
+| Root `bearerToken` import | Import from `@zackbart/connecta/auth/bearer`; preserve its token and subject configuration |
+| `accessTokens: { ... }` | Remove after migrating every client that uses a Connecta-issued token |
+| `identity.operatorAccess` | `identity.activityAccess` for global activity reads; grant auth management separately |
+| Visibility implicitly permits auth changes | Explicit `credentialAdministration` for shared auth and `personalConnection` for personal auth; both default to `"none"` |
+
+Removed configuration is refused at construction. Do not silence TypeScript
+errors with casts; they identify decisions this upgrade needs you to make.
+
+Before:
+
+```ts
+import { createConnecta, bearerToken } from "@zackbart/connecta";
+
+const connecta = createConnecta({
+  connectors,
+  executor,
+  storage,
+  auth: [bearerToken(token), interactiveAuth],
+  branding,
+  credentials: { encryptionKey },
+  accessTokens: {},
+  activity: { store: activityStore, deploymentId: "production" },
+  identity: {
+    connectorAccess,
+    operatorAccess: isOwner,
+  },
+});
+```
+
+After, with the same features except issued tokens:
+
+```ts
+import { createConnecta } from "@zackbart/connecta";
+import { bearerToken } from "@zackbart/connecta/auth/bearer";
+import { operatorUi } from "@zackbart/connecta/ui";
+import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
+import { activityHistory } from "@zackbart/connecta/activity";
+
+const connecta = createConnecta({
+  connectors,
+  executor,
+  storage,
+  auth: [bearerToken(token), interactiveAuth],
+  ui: operatorUi({ branding }),
+  vault: encryptedCredentialVault(storage, encryptionKey),
+  activity: activityHistory({ store: activityStore, deploymentId: "production" }),
+  identity: {
+    connectorAccess,
+    credentialAdministration: ({ principal }) =>
+      principal && isOwner(principal) ? "all" : "none",
+    personalConnection: () => "all",
+    activityAccess: isOwner,
+  },
+});
+```
+
+`personalConnection: () => "all"` permits visible personal connections for
+interactive principals. It does not permit shared grant changes or create a
+principal for bearer or service identities. Use an explicit list of connector
+ids if only some personal connections should be connectable.
+
+### Decide permissions explicitly
+
+A teammate who can use a shared connector should not automatically be able to
+replace the credentials everybody uses. Preserve the existing
+`connectorAccess` resolver, then add the two management resolvers. They return
+`"all"`, `"none"`, or declared connector ids and intersect with visibility.
+Thrown resolvers and unknown ids fail closed. Literal deployment-provided
+secrets remain configuration; UI permissions do not make them editable.
+
+For a team Worker using Cloudflare Access:
+
+```ts
+import { cloudflareAccessAuth } from "@zackbart/connecta/auth/cloudflare-access";
+
+import type { ConnectaConfig } from "@zackbart/connecta";
+
+const identity: NonNullable<ConnectaConfig["identity"]> = {
+  connectorAccess: ({ principal }) =>
+    principal?.id === "owner-access-id" ? "all" : ["shared_docs", "personal_linear"],
+  credentialAdministration: ({ principal }) =>
+    principal?.id === "owner-access-id" ? "all" : "none",
+  personalConnection: () => ["personal_linear"],
+  activityAccess: ({ id }) => id === "owner-access-id",
+};
+
+createConnecta({
+  connectors, executor, storage,
+  auth: cloudflareAccessAuth(),
+  identity,
+  ui: operatorUi(),
+  vault: encryptedCredentialVault(storage, encryptionKey),
+});
+```
+
+Use ids declared in this deployment and the real identity provider's stable
+principal id. The strings above are illustrative, not a BePresent access
+policy. Retain the Worker `ctx` forwarding and Worker-level Access application
+with Managed OAuth. Access owns admission and identity; these resolvers own
+Connecta permissions. Do not introduce a second user roster.
+
+For a personal Node deployment with Clerk and a configured client bearer:
+
+```ts
+import type { AuthenticatedIdentity } from "@zackbart/connecta";
+
+const isOwner = ({ principal }: AuthenticatedIdentity) =>
+  principal?.id === "owner-clerk-id";
+
+createConnecta({
+  connectors, executor, storage,
+  auth: [bearerToken(token, { subjectId: "static-token" }), clerk],
+  ui: operatorUi({ branding }),
+  vault: encryptedCredentialVault(storage, encryptionKey),
+  identity: {
+    connectorAccess: () => "all",
+    credentialAdministration: identity => isOwner(identity) ? "all" : "none",
+    personalConnection: identity => isOwner(identity) ? "all" : "none",
+    activityAccess: ({ id }) => id === "owner-clerk-id",
+  },
+});
+```
+
+This preserves shared-connector MCP access for the configured bearer while
+reserving auth changes for the owner signing in through Clerk. The bearer does
+not inherit the owner's personal connections. To make invocation owner-only
+as well, restrict inbound admission or `connectorAccess` explicitly. Do not
+replace an existing identity resolver with `"all"` just to match this example.
+
+`activityAccess` receives an `IdentityReference` with `id` and `namespace`,
+while management resolvers receive an `AuthenticatedIdentity` with `principal`.
+`activityAccess` defaults to interactive humans. Set it deliberately for a team
+if global activity must remain owner-only. Omitting it is broader than an old
+owner-only `operatorAccess` resolver.
+
+### Migrate issued-token clients before upgrading
+
+Connecta no longer issues or authenticates `cta_` tokens. The Tokens tab and
+its creation, rename, and revocation endpoints are removed. Existing token
+secrets immediately stop admitting requests to the upgraded deployment;
+removing `accessTokens` alone does not migrate clients.
+
+1. Inventory clients using issued tokens while the old deployment can still
+   identify them. Do not paste secrets into logs, documentation, or a migration
+   issue.
+2. Move interactive clients to the configured identity provider's OAuth flow.
+   On Workers, use Cloudflare Access Managed OAuth and keep the required client
+   redirect allowlist. On Node, use the configured interactive provider.
+3. If an actual unattended Node client remains, configure the optional
+   `bearerToken` adapter and update that client. Preserve stable `subjectId`
+   values for existing configured bearers. On Workers, Access service tokens
+   provide edge admission; a Connecta bearer alone cannot cross Access.
+4. Verify each replacement client before removing `accessTokens` and deploying
+   the new package. An issued token previously inherited its creator's personal
+   principal; a configured bearer does not. Clients needing personal grants
+   must use a human identity flow.
+
+Stored issued-token records become inert. They are not deleted automatically
+and are not converted into configured bearer credentials. No storage sweep is
+required for this upgrade. If rolling back to an older binary, remember that it
+understands those old records again; retire or revoke old tokens in the old
+system before migration if rollback must not restore them.
+
+### Preserve vault and OAuth state
+
+Pass the existing storage adapter and the same encryption key to
+`encryptedCredentialVault`. Do not generate a replacement key as part of this
+refactor. Keep connector ids, identity namespaces, principal ids, and owner
+partitions stable. The encrypted vault binds connector and owner into its
+AES-GCM context; moving records between owners does not migrate ownership.
+
+No vault record, OAuth grant, or catalog storage-format migration is required.
+Downstream OAuth continues to use connector storage, independently of the vault
+module. Existing activity stores and retention policies remain deployment-owned;
+wrap the existing store in `activityHistory` rather than creating a new database.
+A replacement `CredentialVault` must preserve connector and owner isolation.
+
+### Omit features you do not need
+
+Omit `ui` and its import for an API-only deployment. UI shells, data APIs, and
+auth mutation routes disappear. Core `/mcp`, `/health`, auth metadata, and OAuth
+callbacks remain. An authorized interactive MCP caller can use
+`authorize_connector` and complete OAuth without UI. Static credential recovery
+returns `unavailable` without a mounted UI or vault, instead of a missing page.
+UI-free callbacks use neutral branding and offer no dead return link.
+
+Omit `activity` and its imports to stop recording and remove the Activity tab.
+Remove deployment-only store wiring or database bindings only if nothing else
+uses them. Existing history is not deleted. Diagnostic output is separate;
+set `logger: "silent"` only when you also want to suppress it.
+
+Omit `vault` when credentials come entirely from deployment configuration or
+OAuth. A connector declaring a vault slot then remains unmanageable; do not
+omit it while expecting stored vault credentials to keep resolving.
+
+There is no generic module list. Keep ordinary explicit imports and the typed
+configuration slots. The implementations may ship in the package, but core
+does not load them merely because the package is installed.
+
+### Verify the upgraded deployment
+
+- Run the deployment's typecheck and build with the new imports and exact pin.
+  Keep its connector declarations, executor, and custom routing intact.
+- Run `connecta doctor` against the running deployment using its actual inbound
+  authentication. Confirm the same seven tools and a working executor.
+- Sign in as an owner and a teammate. Confirm visibility, shared auth controls,
+  personal connection controls, and activity access match code. A member may
+  invoke a shared connector while having no authority to change its grant.
+- Open Connections. Its configured list should appear before downstream details;
+  one slow or failing provider should not delay the other cards. OAuth starts
+  only after an explicit action, and action feedback does not await other probes.
+- Read existing vault-backed and personal OAuth connections without re-entering
+  secrets. Exercise one permitted auth flow and confirm other principals cannot
+  manage it. With UI omitted, verify OAuth callback completion and the honest
+  unavailable response for static credential handoff.
+- Update bookmarks and operator instructions to the connection-centered UI.
+  There is no separate Credentials or Tokens tab. Verify optional Activity and
+  the absence of UI routes in a deployment that omits the UI.
+
+Keep the old pin, configuration, and storage backup available until these checks
+pass. This guide changes package configuration; it does not authorize or perform
+any deployment, credential rotation, or storage deletion.

package/documentation/provider-conventions.md

@@ -416,13 +416,15 @@ default. The provider's own headless credential — a personal API key, a
 restricted key, a service account — is supported two ways: explicit `headers`
 auth, documented as a secret rather than configuration, and `{ type:
 "credential" }`, which declares an operator slot and takes the same secret from
-`/credentials` instead. Either way it is paired with the narrowest mode the
+the connection UI at `/` instead. Either way it is paired with the narrowest mode the
 deployment can use, and the framing matches the provider's *published* contract
 for the MCP endpoint — not a convention borrowed from that provider's other
 APIs, and not this repository's earlier example, which is the same claim wearing
 a circle. `requireHttps` is set. Recovery from an expired authorization is the
 ordinary `auth_required` → `authorize_connector` route, which returns the
-consent URL for OAuth and the `/credentials` handoff for a declared slot.
+consent URL for permitted OAuth starts and a connection UI handoff at `/` for
+a declared slot when UI and vault are mounted. Missing modules yield
+`unavailable`; never advertise a route the deployment cannot serve.
 
 *Why:* one route back from an expired credential is what keeps a failed call
 from becoming an abandoned task. *Cost:* wrong-tool selection.
@@ -442,7 +444,7 @@ deployment file to read — and a dead, revoked, or absent credential fails loud
 at use as `auth_required` with the `authorize_connector` route attached (P9).
 
 `testCredential` exists only behind the operator-pressed Test action on
-`/credentials`, and only for a declared slot. It connects with the stored value
+the connection UI at `/`, and only for a declared slot. It connects with the stored value
 and reports how many tools the downstream served, which is the whole honest
 check for a proxy: which account, project, or mode a key reaches is the
 provider's answer, not Connecta's. That is not the shape

package/documentation/revenuecat.md

@@ -81,7 +81,7 @@ connectors: [
 ```
 
 Neither key has to be a runtime secret. Declare the slot instead and each
-connector's key is pasted, tested, and rotated on `/credentials`:
+connector's key is pasted, tested, and rotated on the connection UI at `/`:
 
 ```ts
 connectors: [

package/documentation/storage-and-credentials.md

@@ -1,39 +1,59 @@
 # Storage and credentials
 
-The core `KVStorage` seam supports `get`, `set`, and `delete`; adapters may also
-implement `list(prefix)`. Named access tokens require listing because every
-token is an independent record rather than one shared, race-prone manifest.
-The built-in memory and file adapters implement it, as does the Cloudflare KV
-example.
-
-Connectors may declare a human-managed `credential` slot. When
-`credentials.encryptionKey` is configured, Connecta encrypts values in the
-deployment storage and exposes read-only access only through that connector's
-`ctx.credential`. Values, masked values, call arguments, and raw errors never
-enter model-facing recovery responses or activity records.
-
-Proactive credential liveness probing was **removed in 0.9** by ethos decision
-([#179](https://github.com/zackbart/connecta/issues/179)). The vault, local
-credential-shape drift detection, and operator-triggered credential tests remain.
-
-Credentials fail at use. A typed `auth_required` response directs the agent to
-`authorize_connector`, which returns one of the recovery modes documented in
-[meta-tools](./meta-tools.md#authorization-recovery). A declared slot with a
-configured vault returns a secret-free `/credentials` handoff. A missing vault
-returns `recovery: "unavailable"` and names `credentials.encryptionKey`;
-Connecta also warns at startup.
-
-Credential mutation is intentionally narrower than MCP access:
-
-- a static bearer may call tools and receive the operator handoff, but it
-  cannot write credentials;
-- an admitted interactive human may mutate credentials for every visible
-  connector: their own partition for personal auth, or the deployment-wide
-  value for shared auth; and
-- saving, replacing, testing, or removing a value never returns that value.
-
-The vault is read for each call. Once a signed-in human saves a replacement,
-the agent can retry immediately without restarting or redeploying Connecta.
+The core `KVStorage` contract supports `get`, `set`, and `delete`; adapters may
+also implement `list(prefix)`. Core uses storage for connector state, catalogs,
+and result paging. The vault is an explicit independent option:
+
+```ts
+import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
+
+createConnecta({
+  connectors,
+  executor,
+  storage,
+  vault: encryptedCredentialVault(storage, encryptionKey),
+});
+```
+
+`encryptionKey` is a base64 32-byte AES key. The factory implements the
+root-exported `CredentialVault` contract. Core depends on the contract without
+importing the encrypted implementation; deployments may supply their own.
+A replacement must isolate both connector id and optional owner, preserve
+metadata-only reads for the UI, and keep plaintext confined to host credential
+resolution. The built-in AES-GCM implementation binds connector and owner into
+authenticated encryption context. Sharing a backend is not permission to share
+a principal's credentials.
+
+Connectors declare a human-managed `credential` slot in code. The vault exposes
+read access only through that connector's `ctx.credential`. Values, masked
+values, call arguments, and raw errors never enter model recovery or activity.
+Omitting the vault leaves literal deployment-provided secrets and downstream
+OAuth available, but declared vault slots cannot be managed.
+
+Credentials fail at use. Proactive liveness probing remains removed by
+[the 0.9 decision](../ethos.md). Operator-triggered tests and local credential
+shape checks remain. `authorize_connector` returns a human credential handoff
+only when both a vault and the UI are configured. Without either, recovery is
+`unavailable` and explains the missing configuration.
+
+A static bearer may invoke a connector but never mutate its auth as a browser
+user. Interactive users need visibility plus `credentialAdministration` for
+shared auth or `personalConnection` for their own personal auth. Both management
+permissions default to none. Saving, testing, replacing, or removing a value
+never returns it. The vault is read for each call, so a saved replacement takes
+effect without restarting the deployment.
+
+## Storage continuity
+
+This module extraction changes no encrypted record keys, owner partitions, or
+OAuth storage format. Reuse the existing storage and encryption key when
+constructing `encryptedCredentialVault`. Keep connector ids, principal ids, and
+identity namespaces unchanged. Losing the encryption key makes old vault
+values unreadable; changing identity context selects another personal partition.
+
+Removed Connecta-issued token records remain inert in storage. This upgrade
+does not delete them, convert them to another credential, or migrate their
+clients automatically.
 
 ## Shared and personal auth
 
@@ -54,8 +74,7 @@ Personal connectors disappear from a request that has no stable human
 principal. For a principal that can see one, connecta partitions connector
 storage, encrypted vault records, catalog caches, OAuth generations, and
 observed result shapes under an opaque SHA-256 identity key. Results used by
-`get_result` are partitioned by the authenticated subject, so one token cannot
-page another token's call even when both tokens belong to the same principal.
+`get_result` are partitioned by the authenticated subject, so one authenticated subject cannot page another subject's call.
 
 Literal `auth: { type: "headers" }` cannot be personal because its secret lives
 in deployment code. `remoteMcp()` refuses that combination at construction.
@@ -73,7 +92,7 @@ remoteMcp("revenuecat_bepresent", {
 ```
 
 The connector, its endpoint, and the credential *slot* stay declared in code;
-only the secret arrives through `/credentials`. That is the same boundary
+only the secret arrives through the connection UI at `/`. That is the same boundary
 `api()` has always had, and the reason a project-wide key no longer has to be a
 Worker secret or an environment variable
 ([#439](https://github.com/zackbart/connecta/issues/439)).
@@ -99,8 +118,8 @@ redaction that keeps part of a secret is still a leak.
 An empty slot is not a boot failure and not a silently absent connector. The
 connector is present, its status reads `auth_required`, calls fail with the same
 typed error a missing OAuth grant produces, and `authorize_connector` returns
-the `/credentials` handoff. With no vault configured at all, the failure names
-`credentials.encryptionKey`, and Connecta already warned at startup.
+a connection UI handoff at `/` when UI and vault are configured. Without either,
+it returns `unavailable` and explains what is missing.
 
 The vault is read before any cached downstream client is trusted, so a rotation
 lands on the next call rather than the next deploy. Connecta compares a SHA-256
@@ -111,7 +130,7 @@ message. A cleartext `http://` destination warns at construction here exactly as
 it does for literal headers — who owns the secret changed, not what the wire
 carries.
 
-`/credentials`' Test action connects with the stored value and reports how many
+The connection UI Test action connects with the stored value and reports how many
 tools the downstream served. That is the whole honest check for a proxy: which
 account, project, or mode the key reaches is the provider's answer, not
 Connecta's.

package/documentation/stripe.md

@@ -95,7 +95,7 @@ Use a restricted key, not a secret key, and scope it to the operations the
 agent actually needs; Stripe's own guidance is to "limit your agent's access to
 exactly the functionality it requires". Keep it in the runtime's secret store.
 
-The same key can come from `/credentials` instead:
+The same key can come from the connection UI at `/` instead:
 
 ```ts
 stripe("stripe_sandbox", {