@zackbart/connecta 0.22.3 → 0.24.0

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

@@ -237,8 +237,8 @@ not send the agent to `authorize_connector`, you do not repair the argument
 object. You re-address — look the id up again, or accept the absence and carry
 on — and a program looping over ids inside `execute_code` can continue past
 `not_found` where `connector_call_failed` would have to abort the run, reading
-the code off a `connecta.batch` entry's `errorDetails` rather than off a caught
-error, which the guest bridge has already stripped to prose. That
+the code from a caught error or a rejected promise. The guest bridge preserves
+the typed classification. That
 control-flow difference is the H11 test being met; it is not a label for the
 cause.
 
@@ -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", {

package/documentation/upgrading.md

@@ -17,6 +17,66 @@ the release notes broke, and prove it with `connecta doctor`.
 Work on a branch. Every step below is reversible until you delete the old
 lockfile, and you want the diff reviewable by whoever owns this deployment.
 
+## 0.24.0 optional modules
+
+UI, encrypted credentials, activity history, and configured bearer auth now use
+explicit module imports. Core keeps the same seven tools and enforcement.
+Connecta-issued tokens are removed. Shared and personal auth management require
+separate explicit permissions, both denied by default; visibility alone grants
+neither. `activityAccess` replaces `operatorAccess` for global history reads.
+
+Follow the [optional-module migration](./optional-modules-upgrade.md) before
+upgrading. It includes the complete before-and-after configuration, team Worker
+and personal Node permission examples, issued-token client migration, disabling
+features, and verification. Preserve existing connector ids, identity namespaces,
+storage, and encryption key. Vault and OAuth records need no format migration;
+old issued-token records remain inert rather than being deleted automatically.
+
+## 0.23.0 program API pruning
+
+This update removes MCP Apps rendering, connector shortcut globals,
+`connecta.batch`, automatic direct-call retries, and connector-owned HTTP routes. Refresh the client's MCP
+instructions and tool definitions after upgrading. The seven top-level tools,
+operator pages, credentials, result paging, and media emission remain.
+
+| Before | After |
+| --- | --- |
+| Connector `handleRequest(request, ctx)` | Move custom HTTP routes into the existing deployment fetch handler |
+| `await tracker.list_issues(args)` | `await connecta.call("tracker.list_issues", args)` using the exact address from discovery |
+| `await connecta.batch(calls)` | `Promise.all` over `connecta.call`, or `Promise.allSettled` to keep failures alongside successes |
+| `await connecta.ui(html)` | Return the data the client needs to render its own view |
+| `call_tool` or `call_destructive_tool` with `maxRetries` | Omit the removed argument; each call makes one attempt and returns typed failures with provider retry hints |
+
+A connector that still declares `handleRequest` refuses construction. Handle
+custom routes in the existing Node or Worker deployment before delegating other
+requests to `connecta.fetch`. The deployment owns authentication and security
+headers for its custom responses. Connecta returns 404 for unknown paths.
+Cloudflare Global API Key authentication and multi-field credentials remain
+supported; they need no migration.
+
+The direct-call schemas reject unknown arguments, including `maxRetries`, before
+invocation. Review stored programs and deployment-owned usage guides for the
+removed guest functions. Canonical addresses preserve punctuation; do not copy
+the old sanitized shortcut into the address string.
+
+```js
+async () => {
+  const outcomes = await Promise.allSettled([
+    connecta.call("tracker.list_issues", { state: "started" }),
+    connecta.call("tracker.list_projects", {}),
+  ]);
+  return outcomes.map((outcome) => outcome.status === "fulfilled"
+    ? { ok: true, data: outcome.value }
+    : { ok: false, code: outcome.reason.code, message: outcome.reason.message });
+}
+```
+
+Reduce large successful values before returning. Promise rejection reasons are
+Error objects; explicitly select their fields for JSON output. Every call still
+passes through the existing read-only checks, admission limits, deadlines, and
+20-call program budget. Rate-limited calls return `retryAfterMs` without waiting;
+the client can reissue after that delay. No storage migration is required.
+
 ## Read what you have first
 
 Three questions, in order. Answer all three before editing anything — the
@@ -57,7 +117,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.22.3 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.24.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +166,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.22.3
+npm pkg set dependencies.@zackbart/connecta=0.24.0
 npm install
 ```
 
@@ -130,7 +190,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.22.3 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.24.0 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +246,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.3 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.24.0 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,6 +267,19 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
+### 0.23.0 → 0.24.0
+
+Use the [optional-module migration](./optional-modules-upgrade.md) to select
+modules, grant auth-management permissions, and migrate issued-token clients.
+Preserve storage, encryption keys, and identity namespaces.
+
+### 0.22.3 → 0.23.0
+
+Migrate stored programs and custom connector routes using the
+[0.23.0 migration](#0230-program-api-pruning). Refresh client instructions
+and tool definitions so account titles and the revised discovery guidance take
+effect. No storage migration is required.
+
 ### 0.21.2 → 0.22.3
 
 Connector and user policy remain config-as-code. If `identity.connectorAccess`
@@ -572,10 +645,8 @@ all, so this is not a hook to stub out with `() => true`.
 previously fell through to connector `handleRequest` and then to a 404, so a
 connector that served any of the three is now shadowed without warning. `GET /`
 returns the operator shell where 0.6.1 returned 404, and a non-GET on those
-routes or on `/ui` returns 405 instead of falling through. Move such a handler
-to a path the core does not own: `handleRequest` still runs for everything the
-built-in routes miss, so it can add a route and never shadow one
-([architecture](./architecture.md)).
+routes or on `/ui` returns 405 instead of falling through. For the current release, move custom handlers into the deployment: connector
+`handleRequest` is now removed. See the [current migration](#0230-program-api-pruning).
 
 ### Removed options that throw
 
@@ -587,6 +658,10 @@ the migration map:
 
 | Option | Removed in | Do |
 | --- | --- | --- |
+| `accessTokens` | 0.24.0 | migrate issued-token clients to provider OAuth or configured bearer auth; old records become inert |
+| `credentials` | 0.24.0 | `vault: encryptedCredentialVault(storage, encryptionKey)` from `/credentials` |
+| `branding` | 0.24.0 | `ui: operatorUi({ branding })` from `/ui` |
+| `identity.operatorAccess` | 0.24.0 | `identity.activityAccess`; grant shared and personal auth management separately |
 | `toolkits`, `unscoped` | 0.8.1 (#178) | delete; deploy one instance per audience |
 | `credentials.health`, `credentialHealth` | 0.8.1 (#179) | delete; credentials fail at use |
 | `surface` | 0.11.0 (#273) | delete; there is one seven-tool surface |