@zackbart/connecta 0.23.0 → 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

@@ -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,21 @@ 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,
@@ -102,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.23.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 |
+| **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
@@ -151,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.23.0
+npm pkg set dependencies.@zackbart/connecta=0.24.0
 npm install
 ```
 
@@ -175,7 +190,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.23.0 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
@@ -231,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.23.0 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`**.
@@ -252,6 +267,12 @@ 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
@@ -637,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 |

package/ethos.md

@@ -4,38 +4,25 @@ Connecta’s scope, refusals, and invariants. Contradictions require a design de
 
 ## What this is
 
-- **One MCP endpoint, one programmable surface.** Every integration you chose
-  sits behind a capability catalog that agents reach by writing JavaScript,
-  ringed by a few explicit tools for the boundaries code must not cross.
-- **A deployment is config-as-code.** One tenant and connector set; principals
-  receive config-derived views.
-- **Curated when available, open when not.** Prefer a maintained prebuilt
-  connection; `remoteMcp()` and `api()` stay first-class for everything else.
-  Every path yields the same `Connector` with the same rules.
-- **Seven tools, an executor required.** The primary surface is a program, so
-  every deployment runs an executor and one without refuses to boot. A
-  capability earns a top-level tool only by being inexpressible as a program.
-- **Safe by default.** Only tools explicitly annotated read-only run without
-  crossing `call_destructive_tool`, where the host can ask a human. Approval is
-  the host's job; connecta makes the question visible.
-- **One fetch-native core, two runtimes.** Web APIs only in the core; Node
-  touches live behind explicit subpaths. Cloudflare Worker or Docker, your pick.
-- **Observable, actionable only over authentication material.** Operator pages
-  show status and payload-free activity and may rotate credentials, issue
-  tokens, and run OAuth. Declared capability they cannot touch.
+- **One MCP endpoint.** Agents reach configured connectors through JavaScript
+  and seven meta-tools. Every deployment requires an executor.
+- **Config-as-code.** One tenant and connector set; identities receive
+  config-derived views. Maintained providers, `remoteMcp()`, and `api()` obey
+  the same connector contract.
+- **Safe by default.** Only explicitly read-only tools run inside a program.
+  Others cross `call_destructive_tool`; the host owns human approval.
+- **One fetch-native core.** Web APIs support Node and Workers. Platform code
+  and optional features use explicit subpath imports.
+- **Human auth management.** Optional pages show status and payload-free history.
+  Explicit permissions allow credential changes and OAuth. Capabilities stay in code.
 
 ## What this isn't
 
-- **Not a platform.** No runtime registration, admin-editable capability,
-  policy engine, approvals, or pauses.
-- **Not a schema ingester.** No OpenAPI or GraphQL → tools.
-- **Not multi-tenant.** No accounts, groups, or sessions. Inbound auth owns
-  identity; personal state stays within one tenant.
-- **Not stateful.** No protocol sessions, no server push; scope resolves per
-  request.
-- **Not a nanny.** Credentials fail loudly at use; nothing probes one.
-- **Not a promise to strangers — yet.** Breaking changes are cheap; the version
-  number signals change, not stability.
+No runtime registration, admin-editable capabilities, policy engine, approvals,
+or pauses. No schema ingestion, accounts, groups, protocol sessions, or server
+push. Inbound providers own identity; personal state remains within one tenant.
+Credentials fail at use, without background probes. Breaking changes remain
+acceptable; version numbers signal change, not stability.
 
 ## Decisions
 
@@ -48,6 +35,9 @@ subsystem guides and the CHANGELOG.
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
+| Optional deployment modules | accepted | explicit imports and typed config slots select UI, activity history, credential vault, and inbound auth; discovery, execution, invocation, and enforcement stay in core |
+| Generic plugin lifecycle or marketplace | refused | modules organize deployment code; runtime installation and discovery add no required behavior |
+| Connecta-issued access tokens | removed | inbound identity providers own client authentication; configured bearer auth remains an optional adapter |
 | Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
 | Protocol sessions & server push | refused | stateless per request |
@@ -97,7 +87,9 @@ requires a design decision.
 - **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
 - **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
 - **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Human routes manage auth, never capability.** Signed-in humans manage auth for visible connectors; operators also manage tokens and global activity.
+- **Human routes manage auth, never capability.** Visibility grants use, not credential administration. Shared and personal auth mutations require separate config-derived permissions, both denied by default. Activity has its own read permission.
+- **Omitted modules do no work.** Core imports no UI bundle, encrypted vault implementation, activity implementation, or bearer adapter. OAuth callbacks remain available without UI.
+- **Status reads do not start authorization.** OAuth starts through an explicit authorized action; loading the UI never creates a consent flow.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
 Connecta simplifies [executor](https://github.com/UsefulSoftwareCo/executor).

package/examples/worker/AGENTS.md

@@ -34,7 +34,9 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Prefer `api()` when the agent must see an exact reviewed capability set;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
 - Use Access service credentials for `connecta doctor` and unattended clients.
-  A `cta_` token or static Connecta bearer cannot cross the Access edge alone.
+  A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
+  tokens are removed. UI, vault, and activity use explicit optional imports;
+  auth changes require code-derived shared or personal management permissions.
 - Run the repository's `npm run check:examples` after configuration changes.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
   complete their browser authorization flows before calling setup complete.