@zackbart/connecta 0.28.1 → 0.30.0

package/documentation/operating.md

@@ -0,0 +1,135 @@
+# Operating an endpoint
+
+Use this guide as an agent connected to an existing Connecta endpoint. Setup
+and credentials are the deployment operator's responsibility; use
+[Deploying Connecta](./deploying.md) if you are that operator.
+[All agent routes](./README.md) are in the index.
+
+## Choose the call path
+
+Connecta exposes six top-level tools. Read [the tool table](./meta-tools.md#the-six-tools)
+for exact arguments and result envelopes. Follow the endpoint's supplied
+instructions and `skills` usage guide for deployment-specific context.
+
+| Work                                                               | Use                                                       |
+| ------------------------------------------------------------------ | --------------------------------------------------------- |
+| One known read, with usable arguments and a small result           | `call_tool`                                               |
+| Discover a tool, chain calls, combine services, or reduce a result | `execute_code`                                            |
+| One write on a read-only endpoint                                  | `call_destructive_tool`                                   |
+| Obtain connector instructions                                      | `skills` with the returned guide name                     |
+| Start a required authentication handoff                            | `authorize_connector`, using the returned recovery action |
+
+The endpoint's trust is part of its tool descriptions. On a `trusted` endpoint,
+programs may write within the caller's grants, and `execute_code` is annotated
+as a write. On `read-only`, every write is a separate top-level call. The host
+controls approval. Never change pool, identity, or trust to work around a refusal.
+[Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
+owns the full decision rules.
+
+## Discover before guessing
+
+Use two to four distinctive action/object terms for each operation, and name
+the connector when it is obvious. Read `catalogErrors`, `absence`, classification,
+and required inputs before selecting a result. An empty search may mean a
+failed catalog or a service outside the caller's grants.
+
+For normal reads, keep discovery, calls, and reduction in one program when the
+schemas suffice; return the answer rather than catalog matches. Use top-level
+`search_tools` for catalog inspection or to discover a write on a read-only
+endpoint, then dispatch each write with `call_destructive_tool`. An unfamiliar
+read result may return a bounded sample for inspection before the next program.
+
+Use the exact returned `address`, including punctuation. A TypeScript signature
+is guidance for writing JavaScript; do not paste types into executable code.
+If a schema is truncated or exact constraints matter, describe the address with
+`format: "json"`. Read a returned `guide` through `skills` or
+`connecta.skill` before relying on provider-specific conventions.
+[Discovery context](./meta-tools.md#discovery-context) and
+[guest search](./code-mode.md#connectasearch) define these results.
+
+## Call, combine, and reduce
+
+A program is one JavaScript `async` arrow expression. It has the `connecta`
+guest API and captured console output, with no portable imports, filesystem,
+network access, or credentials. Downstream calls return an envelope; read its
+`data` rather than treating the envelope as the provider's result.
+
+This illustrative tracker has a `list_issues` read accepting `state` and
+returning `data.nodes`. Discover its address, call it, and group the identifiers
+in one program:
+
+```js
+async () => {
+  const page = await connecta.search({
+    connector: "tracker",
+    query: "list issues",
+    safety: "readOnly",
+  });
+  if (page.catalogErrors.length || page.absence) {
+    return { gap: page.catalogErrors, absence: page.absence };
+  }
+  const tool = page.tools.find(t => t.name === "list_issues");
+  if (!tool) return { gap: "list_issues unavailable" };
+  const { data, format } = await connecta.call(tool.address, {
+    state: "started",
+  });
+  if (format !== "json" || !Array.isArray(data?.nodes)) {
+    return { gap: "Expected a JSON issues collection" };
+  }
+  const byOwner = Object.create(null);
+  for (const issue of data.nodes) {
+    const owner = issue.assignee?.name ?? "unassigned";
+    (byOwner[owner] ??= []).push(issue.identifier);
+  }
+  return byOwner;
+}
+```
+
+`tracker.list_issues` is illustrative, not a built-in address. Discover the real
+connector's schemas and pagination before adapting this program. Keep loops and
+parallel work bounded. [Parallel calls](./code-mode.md#parallel-calls),
+[results and projection](./code-mode.md#results-and-projection), and
+[cancellation and limits](./code-mode.md#cancellation-and-limits) own those rules.
+
+Discovery may label an output schema `observed`. It records field names and
+broad types from successful reads in bounded runtime memory, with no scalar
+values. Treat it as evidence, not a provider contract; handle missing fields.
+
+## Large results and resources
+
+Direct calls may return a preview and a result handle. Page the handle through
+`connecta.result` in a program using the returned offset and byte limits, or
+reduce the data in the original program. Handles are short-lived and bound to
+the admitted caller, endpoint/pool, and current grants. Never invent one or pass
+it between identities. [Paging](./meta-tools.md#paging-with-connectaresult)
+owns the envelope and expiry rules.
+
+For resources, use the exposed resource inventory and `connecta.read`; do not
+fetch an arbitrary URL. [Resource reads](./code-mode.md#connectaread) describe
+which URIs may be read. Connector guides and native skills are described in
+[skills](./meta-tools.md#connector-guides-and-skills).
+
+## Recover without replaying a write
+
+Read typed failures and their `nextAction`. Authorization recovery can point
+to consent, operator credential setup, or deployment configuration. Discovery
+and status do not begin consent on their own. Follow
+[authorization recovery](./meta-tools.md#authorization-recovery),
+[routing recovery](./meta-tools.md#routing-recovery), and
+[argument recovery](./meta-tools.md#argument-recovery) for the specific failure.
+
+A dispatched write is never automatically replayed. An ambiguous timeout may
+mean the provider applied it; inspect state or ask for the missing decision
+before issuing it again. [Retry semantics](./code-mode.md#retry-semantics) and
+[writes](./code-mode.md#writes) describe program outcomes and write accounting.
+
+## Implementation and evidence
+
+The endpoint's built-in [usage skill](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
+is maintained alongside [meta-tools](https://github.com/zackbart/connecta/blob/main/src/meta-tools.ts)
+and [execution](https://github.com/zackbart/connecta/blob/main/src/execute.ts).
+[Usage-guide tests](https://github.com/zackbart/connecta/blob/main/test/usage-guide.test.ts),
+[direct-call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
+and [guest-contract tests](https://github.com/zackbart/connecta/blob/main/test/guest-api-contract.test.ts)
+check the contracts. Executor-specific evidence is indexed in
+[code-mode verification](./code-mode.md#verification).

package/documentation/operator-tests.md

@@ -0,0 +1,97 @@
+# Operator UI tests
+
+Use this repository-maintenance guide when changing operator pages, data routes,
+or browser evidence. Read the [operator UI contract](./operator-ui.md) first.
+[The agent index](./README.md) routes deployment and endpoint tasks.
+
+`test/fixtures/operator-visual.ts` owns the visual data. It builds the config,
+live overlay, viewer, and legacy auth details through the current server routes,
+using the types in `src/operator-ui/contract.ts` and `model.ts`. Collections use
+their corresponding browser types. `test/operator-visual-fixtures.test.ts`
+validates contract versions, connector IDs, granted tools, classification,
+permissions, provenance, and secret exclusion on Node and Workers. A fixture's
+config cannot silently become a stale copy of the server serializer.
+
+`test/browser/operator-visual.spec.ts` intercepts API reads and serves the real
+hashed assets and HTML with the production CSP. Loading responses wait on an
+explicit gate. Error responses use fixed HTTP failures. Screenshots use a fixed
+clock, UTC, en-US, locally hosted fonts, disabled animations, hidden carets,
+and a 1280 × 900 viewport. Narrow fixtures use 390 × 844. Every test waits for
+its state and fonts before capturing.
+
+## Page and state matrix
+
+Each row runs empty, loading, error, populated, and restricted-viewer fixtures
+in both light and dark themes, for 120 screenshots.
+
+| Page or tab           | Empty state                          | Loading/error request | Restricted viewer                                   |
+| --------------------- | ------------------------------------ | --------------------- | --------------------------------------------------- |
+| Overview              | No connectors or attention items     | Config                | Scoped connectors, no privileged navigation         |
+| Connectors            | No connectors                        | Config                | Read grant and credential slot, no other connectors |
+| Connector Config      | Zero-tool connector                  | Config                | Scoped connector snapshot                           |
+| Connector Tools       | Empty catalog                        | Config                | Read tool only                                      |
+| Connector Auth        | Deployment-managed auth              | Config                | Visible slot, deployment-managed auth               |
+| Connector Activity    | No calls                             | Activity              | Unavailable                                         |
+| Connector Diagnostics | No observed drift/call               | Config                | Scoped diagnostics                                  |
+| Tools                 | Empty catalog                        | Config                | Read tool only                                      |
+| Access                | No pools or client tokens            | Config                | No token management                                 |
+| Access tokens         | No client tokens                     | Token list            | No token management                                 |
+| Activity              | No calls                             | Activity              | Unavailable                                         |
+| Config                | Snapshot without connectors or pools | Config                | Scoped snapshot                                     |
+
+Another 36 screenshots cover configured, mismatched, unreadable and multifield
+credentials; all three OAuth client mechanisms; clean and unobserved drift;
+historical Activity; client setup; schema dialog; read/write filters; expanded
+config provenance; narrow sign-in and Auth; and deployment branding. The base
+populated Activity fixture includes grouped calls, an ungrouped legacy row,
+classification/result size/client facts, and a catalog-change event.
+
+Screenshots cover presentation. Keep unit and server tests for INV-6 sentinels,
+secret disclosure, auth and grant boundaries, CSRF, identity fences, cancellation,
+request lifetime, and error sanitization. Keep browser tests for keyboard/focus,
+XSS, real CSP enforcement, and popup lifetimes. A screenshot
+cannot prove these rules.
+
+## Updating Linux snapshots
+
+The source of truth is `*-linux.png`, produced on `ubuntu-latest` with the
+lockfile's Playwright Chromium. Both CI workflows use the same runner, Node 22,
+and `npm run test:browser:install -- --with-deps`. macOS runs fixture routing and
+readiness checks but omits screenshot comparison. The update script refuses
+non-Linux hosts. Do not commit Darwin baselines.
+
+When Docker is unavailable, use the **Operator snapshots** workflow:
+
+```sh
+git push --force-with-lease origin feat/p4-ui-tests
+gh workflow run operator-snapshots.yml --ref feat/p4-ui-tests
+# Read the completed run ID from the Actions page or gh run list.
+gh run download RUN_ID --name operator-linux-snapshots \
+  --dir test/browser/operator-visual.spec.ts-snapshots
+```
+
+The workflow uploads all generated baselines and never commits them. Review the
+images and changed files, commit the intentional changes, and push again. The
+normal CI browser job must compare and pass against that commit. Opening the
+initial PR also runs the update workflow, so the first baselines can be generated
+before the workflow reaches main. Later updates use `workflow_dispatch`.
+
+On a matching Linux runner, `npm ci`, install Chromium with the command above,
+then run `npm run test:browser:snapshots`. The normal command is
+`npm run test:browser`. Missing baselines fail CI; retries cannot bless them.
+Set `OPERATOR_VISUAL_INSPECT=1` to retain local screenshots under ignored
+`test-results/` for inspection, without updating committed baselines.
+
+## Real-server flows
+
+`test/browser/operator-flows.spec.ts` uses `listen()` from `src/node.ts` with
+loopback TCP servers. It intercepts only Clerk provider traffic with a test
+publishable key; server identity uses the existing `fakeClerkAuth` seam. The
+OAuth provider validates the code exchange and PKCE. Credential Test calls a
+loopback downstream endpoint. Operator APIs, cookie/bearer admission, CSRF,
+assets, handoffs, callbacks, and encrypted storage use production code.
+
+The flows cover Clerk sign-in/reload/sign-out; OAuth connect/consent/callback/
+connected reread/reload; and credential save/test/replace/remove. They collect
+CSP violations across every document and popup, and fail on unexpected network
+traffic. No credentials enter visual fixtures or screenshot baselines.

package/documentation/operator-ui.md

@@ -0,0 +1,132 @@
+# Operator UI
+
+Use this guide to enable or maintain the optional operator interface. For
+client tool calls use [Operating an endpoint](./operating.md); for identities,
+credential ownership, and grants use [Auth](./auth.md).
+[All agent routes](./README.md) are in the index.
+
+## Task routes
+
+| Task                                            | Read                                                                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Enable UI, vault, or history in a deployment    | [Setup](#setup), then the platform template                                                                      |
+| Consume config, provenance, status, or activity | [Operator data contract](#operator-data-contract)                                                                |
+| Change a UI page or data route                  | [Source and tests](#source-and-tests), [browser verification](./operator-tests.md)                               |
+| Diagnose permission refusals                    | [Management permissions](./auth.md#management-permissions), [activity disclosure below](#operator-data-contract) |
+
+## Setup
+
+Set `ui: operatorUi()` using `@zackbart/connecta/ui`. Branding belongs in
+`operatorUi({ branding })`; the [Node template](../templates/node/README.md#select-optional-modules)
+and [Worker example](../examples/worker/README.md#select-optional-modules)
+own the runnable configuration, variables, and branding shape. The UI is an
+explicit optional import and stays outside the root package import graph.
+
+Overview, Connectors, Tools, Access, Activity, and Config show only what the
+caller may inspect. Connector detail tabs cover configuration, schemas,
+authentication, activity, and diagnostics. Config labels values as default or
+configured. Deployment code owns connectors, grants, pools, and classification;
+the UI changes only authorized authentication material.
+
+Install the vault for declared credential slots and activity history for
+persisted call records. Neither module grants permission to manage or read
+it. Credential administration, personal connection, access-token management,
+and activity access are separate identity decisions, denied by default where
+specified in [auth](./auth.md#management-permissions). Machine tokens never
+grant interactive credential or token management authority.
+
+## Operator data contract
+
+`GET /ui/api/config`, owned by `operatorUi()`, returns `OperatorUiContract`
+from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
+source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
+`config` is the construction-time `describeConfig()` snapshot, filtered to
+visible connectors, granted tools, classification overrides, and admitted
+pools. Pool tools are the intersection with the caller's identity grants.
+`configSources` labels each serialized leaf as `default` or `config`, based on
+option presence rather than equality with the default. Factory descriptions carry
+relative `optionSources` paths so resolved module and transport defaults retain
+their provenance. The snapshot copies only resolved values; the UI consumes
+these presence facts separately. Its paths use connector
+ids and pool names and are filtered after disclosure; hidden values leave no
+provenance keys. It contains no source code or credential material.
+Every response is private, `no-store` JSON. Only GET is allowed, with the
+same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
+
+`live.connectors` carries status and problem codes, complete registry tools
+with their final read/write classification, catalog age in milliseconds, and
+last-call time/outcome. Catalog descriptions and schemas are allowed for an
+authenticated reader; grammar-failing names and addresses become `<withheld>`.
+`auth.registrationPath` reports the selected downstream OAuth client mechanism when known.
+Status prose, error text, credential values or suffixes, arguments, results,
+and code are excluded. Static and unobserved catalogs have a null age;
+persisted catalogs retain their original fetch time. Probes run with bounded
+concurrency and the configured probe deadline, and release their scopes.
+
+Last-call lookup requires the existing activity permission and read gate. It
+scans up to 1,000 recent rows, filters connector/tool grants, and restricts
+personal connectors to the caller's activity identity. Each retained fact
+copies a validated timestamp and outcome only. A null call means unknown or
+absent in that window, not proof of no calls. `live.activity` distinguishes
+available, unconfigured, forbidden, and unavailable history. `you` names no
+identity or auth material; it reports grants, root and admitted-pool trust,
+and effective activity, token, and per-connector auth permissions.
+
+`connecta doctor --config` fetches this authenticated contract and prints only
+`config` as indented JSON. It requires the UI module and the existing doctor
+authentication environment variables; it runs no diagnostic program, follows
+no redirects, and prints no raw HTTP failure body.
+
+The operator shell uses React, TanStack Router/Query/Table, Radix, cmdk and
+Tailwind v4. Inter, CSS, JavaScript and dependency notices are hashed assets
+under `/ui/assets/*`, served identically with immutable cache headers on Node
+and Workers. HTML contains only mount points and escaped inert configuration;
+it remains uncached. `generated.ts` is ignored and generated before build and
+test; `check:operator-ui` detects stale assets and shared page styles. The UI
+stays behind `./ui`, outside the root import graph. The identity-fenced store
+owns authenticated reads and existing mutations. Overview, Connectors, connector
+detail, Tools, Access and Config consume the typed contract. Activity retains
+its authenticated data routes. Connector detail tabs live
+in the URL hash; Activity filters live in the query string and apply to loaded
+history. Both `/ui/activity` and `/ui/api/activity` require Activity access and
+pass the optional activity `readGate`. Interactive operators and machine callers
+admitted by `identity.activityAccess` share the same history disclosure rules.
+Connector/tool grants and grants for the recorded pool filter each event. Shared
+connector history can include other principals' events, with recorded request
+IDs, validated client name/version and package version, and actor kind, ID and
+namespace. Interactive reads may also add directory actor labels; machine reads
+never add them. Personal connector history is owner-only: the event must have a
+checked `principal` actor basis and actor ID/namespace matching the reader's
+admitted principal. Rows without a provable personal owner are withheld. Activity
+carries no arguments, results, code or raw downstream errors. The last-call
+overlay uses the same event filter but returns only timestamp and outcome.
+Calls group only by recorded request ids, with missing ids shown as
+separate calls. Classification and result size are shown only when recorded. The verdict is
+captured after registry resolution, and result size counts UTF-8 bytes of the
+downstream value before paging or truncation. Nullable SQL columns preserve old
+rows. Catalog changes use the same paging envelope with `kind: "catalog_drift"`,
+`source: "catalog_refresh"` and a checked `catalog_changed` fact containing only
+added, removed and changed tool counts. The first complete catalog is a baseline;
+one refresh-publication hook emits each later change. It includes the request's
+id and typed actor when available, otherwise a fresh id and system actor. No
+names, descriptions or schemas enter the event. Private catalog changes require
+a matching principal owner even when the connector uses shared auth. Empty credential declarations
+report `credential_required` before running a connector status or catalog probe.
+The Access adapter reports inbound provider kinds, admitted pools, grants, trust
+and endpoint setup; token controls retain their existing permission gate.
+Configuration remains in deployment code. The UI mutates only credentials,
+OAuth connections and client tokens through the existing routes.
+
+## Source and tests
+
+The contract type is [contract.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/contract.ts).
+[UI routes](https://github.com/zackbart/connecta/blob/main/src/routes/ui.ts) and
+[UI implementation](https://github.com/zackbart/connecta/blob/main/src/ui.ts)
+serve the authenticated shell and data. The browser lives in
+[src/operator-ui](https://github.com/zackbart/connecta/tree/main/src/operator-ui).
+[UI tests](https://github.com/zackbart/connecta/blob/main/test/ui.test.ts),
+[credential-route tests](https://github.com/zackbart/connecta/blob/main/test/ui-credentials.test.ts),
+[config snapshot tests](https://github.com/zackbart/connecta/blob/main/test/describe-config.test.ts),
+and [browser flows](https://github.com/zackbart/connecta/blob/main/test/browser/operator-ui.spec.ts)
+defend filtering and behavior. Use [Operator UI tests](./operator-tests.md)
+for the browser state matrix and Linux snapshot procedure.

package/documentation/provider-migration-0.29.md

@@ -0,0 +1,65 @@
+# Notion, Vercel and Cloudflare migration for 0.29
+
+Use this upgrade guide for an existing deployment.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
+version changes; [integrating services](./integrating.md) covers new connectors.
+[The agent index](./README.md) routes package maintenance separately.
+
+This is the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709).
+Deploy it with the consolidated 0.29 release, not while the rework is in progress.
+BePresent and One&Many use Notion and Cloudflare; their actual grants and
+connector ids must be checked in deployment configuration before that release.
+The provider audit establishes available auth modes, not production OAuth grants.
+
+All three providers now default to hosted MCP. `surface: "api"` explicitly
+selects a REST complement and accepts only its API-specific options. The old
+Vercel/Cloudflare API modes are no longer complete alternatives; Notion retains
+all operations required by its distinct integration identity. Adding `surface: "api"` keeps
+REST reads/gaps but does not restore removed duplicates. For both sets of
+capabilities, configure both connectors under distinct ids and authorize each.
+
+```ts
+connectors: [
+  notion("notion", { purpose: "Workspace content" }),
+  notion("notion_rest", { surface: "api", purpose: "Internal integration content and exact REST operations" }),
+  cloudflare("cloudflare", { purpose: "Estate mutations", auth: { type: "credential" } }),
+  cloudflare("cloudflare_rest", { surface: "api", purpose: "Estate reads and byte/header operations", accountId: "account-id", zoneId: "zone-id" }),
+]
+```
+
+Notion preserves headless/internal-integration capabilities. Add explicit
+`surface: "api"` to retain that identity and migrate old REST names to
+`integration_*`, for example `search` to `integration_search`, `create_page`
+to `integration_create_page`, and `query_data_source` to
+`integration_query_data_source`. Its token/sharing boundary stays intact.
+Hosted MCP acts as an OAuth user, has its own grant, and cannot adopt an internal
+token. Use it for user-owned work and hosted-only capabilities; authorize it
+explicitly if those are needed. Do not replace a bot with a user as an auth fix.
+All REST pagination, exact JSON blocks/properties, trash/restore and bot-owned
+content writes remain available.
+
+For Cloudflare, migrate ordinary JSON writes to hosted `search` then `execute`.
+A scoped API token can authorize hosted MCP without interactive OAuth; configure
+that credential independently even if it has the same value as the REST token.
+Keep REST reads in read-only programs. Global API Key/email and R2 jurisdiction/storage-class
+JSON mutations, plus byte/header-compatible uploads, stay in the explicit REST
+complement. Replace `update_r2_bucket` with `cloudflare_api_mutate` using
+`PATCH /accounts/{accountId}/r2/buckets/{bucketName}` and the header
+`cf-r2-storage-class` set to `Standard` or `InfrequentAccess`. Omit the body;
+include `cf-r2-jurisdiction` only when the bucket needs it. This remains a write.
+`execute` remains a write even when its program only calls GET.
+Trusted pools may execute writes; read-only pools use direct host-approved writes.
+
+For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
+domain listing/adding, deployment cancellation and file uploads to live MCP
+schemas, and keep the independently authorized REST complement for value-safe
+project environment variables (including `upsert: false` create-only writes), domain verification/removal and deployment
+deletion. Promotion now uses hosted `request_promote` from the rolling-releases
+category. Raw hatches refuse all published REST counterparts, including project
+creation/update. Do not copy REST argument
+shapes into vendor tools, even when a tool name is unchanged.
+
+The per-provider tables map every removed name and explain retained API tools:
+[Notion](https://github.com/zackbart/connecta/blob/main/src/providers/notion/reconciliation.md),
+[Vercel](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/reconciliation.md), and
+[Cloudflare](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/reconciliation.md).

package/examples/worker/AGENTS.md

@@ -2,12 +2,18 @@
 
 This repository is deployment configuration, not a copy of Connecta itself.
 
-- Edit `src/index.ts` for connectors, authentication, storage, and public URL.
-- Keep `cloudflareAccessAuth()` as the inbound auth provider. Cloudflare Access
-  authenticates the request before the Worker runs; do not add JWT parsing or a
-  second Worker-side identity gate.
+- Edit `src/connecta.config.ts` for connectors, authentication, storage, public
+  URL, and optional modules. `src/index.ts` only starts it. Set plain vars
+  `CONNECTA_ACTIVITY="on"` for preserved activity.
+- Keep `cloudflareAccessAuth()` for human identity and `accessTokens(storage)`
+  always installed over the same `CONNECTA_DB` for machines. Cloudflare Access
+  admits the request before the Worker runs; a service identity alone is
+  refused inside connecta. Do not add JWT parsing or another identity gate.
+  Grant `identity.accessTokenManagement` explicitly to interactive operators;
+  this example permits every signed-in human to manage connectors and tokens.
 - Attach Access to the Worker itself, not only its hostname. Enable Managed
-  OAuth and Dynamic Client Registration on that Access application.
+  OAuth on that Access application. CIMD is the spec's preferred client
+  registration; enable DCR as the fallback Access currently requires.
 - Managed OAuth's **Allowed redirect URIs** must contain all three entries
   below. This is application configuration under
   `oauth_configuration.dynamic_client_registration.allowed_uris`, not an
@@ -25,24 +31,40 @@ This repository is deployment configuration, not a copy of Connecta itself.
   allowed. If a client presents a different callback, copy that exact URI from
   its registration attempt and add the narrowest matching entry rather than
   broadening the allowlist to an entire origin.
-- Keep `new DynamicWorkerExecutor({ loader: env.LOADER })` loader-only. Do not
+
+- Keep `workerExecutor({ loader: env.LOADER })` loader-only. Do not
   add bindings, modules, or outbound access to generated code.
+  Import it from `@zackbart/connecta/worker`; direct upstream
+  `new DynamicWorkerExecutor()` construction throws at boot. Keep the
+  `@cloudflare/codemode` optional peer installed.
 - Keep credentials in Worker secrets. Never commit credential values, Access
   service-token secrets, or `CREDENTIAL_ENCRYPTION_KEY`.
+- All state lives in the one D1 database bound as `CONNECTA_DB`, through
+  `d1Storage` (and `d1ActivityStore`) from `@zackbart/connecta/d1`. Do not add
+  a KV namespace, a second database, or a copied storage adapter; connecta
+  creates its own tables. The only KV binding is in `kv-to-d1.wrangler.jsonc`,
+  which is never deployed. It exists for the one-shot copy from a 0.28 Workers
+  KV deployment (README.md § "Upgrading from 0.28"). Back up, block traffic
+  and background writers, drain, wait for stable KV, copy and verify, deploy
+  while maintenance remains, then mark cutover before reopening traffic. Never
+  rerun stale KV after cutover. Retain backups before removing KV.
 - Add application logic only inside deliberate `api()` connector handlers.
   Do not copy or modify Connecta package internals here.
 - 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 configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
-  tokens are removed. UI, vault, and activity use explicit optional imports;
+- Unattended clients and `connecta doctor` need Access service credentials
+  plus a stored `cta_` bearer. Set `CF_ACCESS_CLIENT_ID`,
+  `CF_ACCESS_CLIENT_SECRET`, and `CONNECTA_TOKEN` together for doctor.
+  Bootstrap tokens through the Access-authenticated operator page or trusted
+  `AccessTokenManager.create` tooling against this same D1 storage, as README
+  "Machine tokens" describes. Never configure a static bearer or open startup.
+  UI, vault, and activity use explicit optional imports;
   auth changes require code-derived shared or personal management permissions.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
-  rather than leaving the default. The commented block above
-  `ui: operatorUi()` in `src/index.ts` shows the shape; README "UI and
-  encrypted credentials" covers the rest.
+  rather than leaving the default. README "UI and encrypted credentials" shows
+  the shape.
 - After configuration changes, typecheck: inside the connecta repository that
   is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and