@zackbart/connecta 0.20.0 → 0.21.1

package/documentation/cloudflare.md

@@ -153,6 +153,18 @@ every constrained field, endpoint-specific pagination bounds, and a description
 on every property. `test/cloudflare-provider.test.ts` walks the surface and
 asserts those properties rather than leaving them as a claim.
 
+The per-setting zone tools accept Cloudflare's current non-empty setting ids,
+including `webmcp_enabled` and `webmcp_packs`. Cloudflare's
+[rendered setting reference](https://developers.cloudflare.com/api/resources/zones/subresources/settings/)
+and current OpenAPI now agree on both beta ids. Results preserve the value and
+the actual `editable` flag Cloudflare returned; Connecta does not apply the
+document's defaults locally.
+
+KV namespace jurisdiction is creation-only. `create_kv_namespace` accepts
+`eu`, `fedramp`, or `us`, and namespace reads preserve the returned value.
+R2 uses a different enum: `default`, `eu`, `us`, or `fedramp`, sent through
+`cf-r2-jurisdiction` by all eight named R2 operations.
+
 ### What the named surface deliberately leaves out
 
 A named tool is a permanent line item in every deployment's catalog, so the
@@ -206,7 +218,7 @@ connection *calls*, dropping the tool drops the row — so
 rather than by a recorded exception. A path reached only through a hatch is
 named by the caller, so it was never a touched endpoint.
 
-The surviving 47 named tools all refuse malformed arguments locally, which is
+The surviving 48 named tools all refuse malformed arguments locally, which is
 the one thing no escape hatch can do: a hatch's path is an opaque string, so it
 can only check that a path is a path.
 
@@ -318,6 +330,12 @@ renamed to `camelCase`. A zone comes back as `id`, `name`, `status`, `paused`,
 `type`, `accountId`, `accountName`, `plan`, `nameServers`, and timestamps —
 not the forty-field object Cloudflare sends.
 
+Every named tool declares useful top-level output keys. Zone settings, Worker
+settings and deployments, KV namespaces and bulk operations, rulesets, R2 CORS,
+and Pages resources use maintained result schemas instead of an open
+"Cloudflare object" declaration. The three raw escape hatches remain open by
+design because their result fields depend on the caller-supplied endpoint.
+
 Paginated lists add a `page` object derived from `result_info`:
 `{ page, perPage, count, totalCount, totalPages, hasMore }`. `hasMore` is the
 field to branch on.

package/documentation/code-mode.md

@@ -889,11 +889,11 @@ the upstream `Executor` shape assignable.
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |
 | `X7` | `P3`'s tests; the Workers superset is deliberately unused |
 
-The surface itself is checked by `test/server.test.ts` (the exact seven-tool
-list) and `test/code-first-surface.test.ts` (the fold's construction rules, the
+The surface itself is checked by `test/server.test.ts` (the exact seven-tool list)
+and `test/code-first-surface.test.ts` (the fold's construction rules, the
 required executor, the refusals a removed top-level tool now gets, copy, and
-measured size). There is one shape left to audit, so there is one audit:
+measured size). The small whole-agent benchmark checks both read routes, provider semantics, and private pagination:
 
 ```sh
-npm --prefix eval/current-version run audit
+npm --prefix eval/current-version run benchmark
 ```

package/documentation/linear.md

@@ -110,9 +110,10 @@ the connector is present and reports `auth_required`. See
 
 The wrapper classifies Linear's documented `list_*`, `get_*`, and
 `search_documentation` tools as reads, and its `save_*`, `create_*`, `delete_*`,
-`resolve_*`, `submit_*`, and `merge_*` tools as writes. An unfamiliar tool the
-downstream leaves unannotated fails closed onto `call_destructive_tool` until a
-Connecta release reviews it.
+`resolve_*`, `submit_*`, `merge_*`, `share_issue`, and `unshare_issue` tools as
+writes. Sharing changes an existing issue's access, so both halves are
+destructive. An unfamiliar tool the downstream leaves unannotated fails closed
+onto `call_destructive_tool` until a Connecta release reviews it.
 
 That classification fills in downstream silence and otherwise preserves
 explicit annotations. A tool on the read allowlist arriving with
@@ -136,7 +137,8 @@ though some calls only create. The genuine creates are `create_issue_label` and
 ## The catalog is not a fixed set
 
 Linear's hosted `tools/list` varies by workspace plan and enabled features:
-customer requests, releases, and code review do not appear in every workspace.
+customer requests, releases, code review, templates, and explicit issue sharing
+do not appear in every workspace.
 The maintained allowlists are therefore a superset — a classified name a
 workspace never returns costs nothing, and a genuinely new tool fails closed.
 Agents should search this connector's catalog for what the workspace actually

package/documentation/meta-tools.md

@@ -12,19 +12,19 @@ Every deployment requires an executor and `tools/list` is exactly seven:
 batching live in `connecta.search`, `connecta.describe`, and `connecta.batch`
 inside a program ([#273](https://github.com/zackbart/connecta/issues/273)).
 
-Code-first is what a model sees. Four overlapping ways to reach one connector
-became two: `search_tools` then `call_tool` for a single cold read — measurably
-cheaper direct than through a program — and `execute_code` for everything wider.
-The consolidation removed overlapping routing choices while preserving the
-cheaper direct path for one cold call. The [guest API contract](./code-mode.md)
-is what a program is promised.
-
-The route is chosen before discovery. A result that will be reduced, a call
-whose arguments depend on an earlier result, or work with multiple operations
-starts with one `execute_code` call and keeps discovery, calls, and reduction
-inside it. Distinct operations get distinct short `connecta.search` queries in
-that program. Only one unknown-address read takes the cheaper top-level
-`search_tools` → `call_tool` path; a known address needs only `call_tool`.
+Code-first is what a model sees. Read-only work has two routes: `call_tool` for
+one known address, and `execute_code` when discovery or any wider work is
+needed. Real hosted catalogs reversed the earlier synthetic result that made a
+top-level cold search look cheaper. Keeping discovery inside the program avoids
+returning every candidate schema to the model and removes a model round trip.
+The [guest API contract](./code-mode.md) is what a program is promised.
+
+The route is chosen before discovery. An unknown address, a result that will be
+reduced, a call whose arguments depend on an earlier result, or work with
+multiple operations starts with one `execute_code` call and keeps discovery,
+calls, and reduction inside it. Distinct operations get distinct short
+`connecta.search` queries in that program. A known address needs only
+`call_tool`.
 
 That routing is about read-only work, because that is the only work a program
 can do. Anything unannotated, write-capable, or destructive is inadmissible
@@ -68,13 +68,15 @@ and a truncated line ends with the exact `+N more` count. This reads only the
 configured registry: it loads no catalog, probes no credential, grants no
 capability, and does not replace canonical discovery or addressing.
 
-Start an unknown-address lookup with two to four distinctive action/object
-terms, not the full request, and omit `limit` so the default eight-result page
-stays small. When the integration is obvious, set `connector` to its id: a
-scoped search loads that catalog alone, while an unscoped search must fan out
-across every configured connector. Leave the search unscoped when the right
-integration is genuinely ambiguous. Set `safety: "readOnly"` when the result is
-headed to `call_tool` or generated code; `safety: "approvalRequired"` finds the
+Start a lookup with two to four distinctive action/object terms, not the full
+request. Read-only lookup belongs in `connecta.search` inside the program.
+Top-level `search_tools` remains available for explicit catalog inspection and
+approval-required discovery. Omit `limit` initially so the default
+eight-result page stays small. When the integration is obvious, set
+`connector` to its id: a scoped search loads that catalog alone, while an
+unscoped search must fan out across every configured connector. Leave the
+search unscoped when the right integration is genuinely ambiguous. Set
+`safety: "readOnly"` for generated code; `safety: "approvalRequired"` finds the
 complementary set that must cross `call_destructive_tool`. Omitting `safety`,
 or setting it to `"all"`, preserves the complete configured catalog. This is
 only a discovery filter: it neither grants authority nor changes invocation admission.

package/documentation/mixpanel.md

@@ -84,7 +84,7 @@ the maintained guide carries the missing call guidance:
 A read-only live audit on 2026-08-13 confirmed all three refusals against the
 US hosted endpoint. They are reported upstream as
 [`mixpanel/mixpanel-headless#202`](https://github.com/mixpanel/mixpanel-headless/issues/202).
-The vetted catalog records the same audit's schema digests for all 63 tools,
+The vetted catalog records current schema digests for all 64 tools,
 so a later schema correction or regression appears by tool name in the
 maintainer drift check. The guide can then shrink when the downstream schema
 becomes complete; Connecta does not absorb the defect permanently.
@@ -110,8 +110,10 @@ rest) leave `destructiveHint` unset; `readOnlyHint: false` already routes them
 through the destructive path, and asserting destruction only inflates the
 approval copy the host shows a human.
 
-Experiments and Feature Flags — 15 of the 63 classified tools — are Mixpanel
-beta surfaces. Expect their names and schemas to move faster than the rest.
+Experiments and Feature Flags are Mixpanel beta surfaces. Their three changed
+schemas were reviewed again on 2026-08-30. The same review added
+`Fill-Event-Metadata` as a destructive write because it applies generated names
+and descriptions to existing Lexicon events.
 
 ## Rate limits
 

package/documentation/operations.md

@@ -45,6 +45,10 @@ one.
 npx @zackbart/connecta init my-deployment
 cd my-deployment && npm install && npm start
 CONNECTA_TOKEN=… npx connecta doctor --url http://localhost:8787
+
+# A Worker protected by Cloudflare Access
+CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
+  npx connecta doctor --url https://connecta.example.workers.dev
 ```
 
 `init` copies the template, pins the generated deployment to the CLI package's
@@ -59,12 +63,17 @@ on the way out: `QuickJS` on the Node template, `DynamicWorkerExecutor` on the
 Worker example, and `code executed` when an executor identifies as nothing —
 a checker that asserts a sandbox it never saw is worse than one that says it
 does not know ([#368](https://github.com/zackbart/connecta/issues/368)). It
-refuses to send a bearer token over remote plaintext HTTP, and it
+refuses to send authentication credentials over remote plaintext HTTP, and it
 *reports* catalog drift without failing on it — an unclassified downstream tool
 already fails closed onto `call_destructive_tool`, so drift is a maintainer's
 next task rather than a broken deployment
 ([#343](https://github.com/zackbart/connecta/issues/343)).
 
+For an Access-protected Worker, doctor sends the service-token pair to both
+`/health` and `/mcp`; Access authenticates those requests before connecta runs.
+`CONNECTA_TOKEN` remains the Node and legacy Worker path, and may be supplied
+alongside the Access pair during rollback testing. A partial pair is refused.
+
 ### Configuration
 
 Structural seams stay top-level; tuning is grouped by subsystem. Every group is
@@ -74,7 +83,7 @@ optional.
 | --- | --- | --- |
 | `connectors` | — (required) | the connector set ([connectors](./connectors.md)) |
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
-| `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before Clerk ([inbound auth](./auth.md)) |
+| `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before interactive providers ([inbound auth](./auth.md)) |
 | `storage?` | `memoryStorage()` | the one state seam for catalogs, result paging, credentials, and access tokens ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
 | `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }` |
@@ -83,7 +92,7 @@ optional.
 | `deploymentInfo?` | unset | arbitrary metadata exposed by `/health` |
 | `activity?` | unset | `{ store, readGate?, deploymentId? }` — payload-free activity storage, an optional operator-read gate, and a stable event label |
 | `credentials.encryptionKey?` | unset | base64 32-byte AES key for the connector vault. Without it, connectors declaring `credential` warn and their slots stay unmanageable |
-| `accessTokens?` | unset | `{ maxActive? }` (default 100) for operator-issued MCP bearer tokens. Requires a Clerk provider, or construction throws ([access tokens](./auth.md#operator-issued-access-tokens)) |
+| `accessTokens?` | unset | `{ maxActive? }` (default 100) for operator-issued MCP bearer tokens. Requires an interactive operator provider, or construction throws ([access tokens](./auth.md#operator-issued-access-tokens)) |
 | `discovery.concurrency?` | 4 | connector catalogs/status probes in flight at once |
 | `discovery.catalogTtlSeconds?` | 300 | fresh TTL for cached tool lists |
 | `discovery.persistCatalog?` | true | persist serializable catalogs as a manifest plus revision-addressed chunks |
@@ -214,7 +223,7 @@ in.
 
 | Suite | Covers |
 | --- | --- |
-| `access-tokens.test.ts` | the `AccessTokenManager` — a one-time secret created, authenticated, renamed, and revoked, bounded names and active count, enumerable storage required, a deployment with no Clerk operator refused — and the Clerk-only routes, down to historical activity still resolving a revoked token's name |
+| `access-tokens.test.ts` | the `AccessTokenManager` — a one-time secret created, authenticated, renamed, and revoked, bounded names and active count, enumerable storage required, a deployment with no interactive operator refused — and the operator-only routes, down to historical activity still resolving a revoked token's name |
 | `activity.test.ts` | payload-free delivery: a rejected async write attaches to `waitUntil` instead of throwing, approved destructive calls record under their real entry point, result-size friction records without retaining the result, and a hallucinated connector id or invented identity is clamped so the event still cannot carry a payload |
 | `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, and the construction contract |
 | `bearer.test.ts` | constant-time bearer compare, case-insensitive scheme, 401 challenges, and the retired audience options refusing rather than silently unbinding |
@@ -223,7 +232,8 @@ in.
 | `catalog-drift.test.ts` | `vettedCatalog()`, `detectCatalogDrift()`, and `withVettedCatalog()`; drift on the registry surface and on `/health`; the connector seam projected rather than echoed; and the drift types being public |
 | `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
-| `cloudflare-provider.test.ts` | `cloudflare()` construction, tool surface, request building, projections, typed failures, and credential test |
+| `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
+| `cloudflare-provider.test.ts` | `cloudflare()` construction, tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and `connecta.ui` findable before connector search |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
@@ -237,14 +247,14 @@ in.
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
-| `linear-provider.test.ts` | the Linear proxy's construction, classification, and guide |
+| `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
 | `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
 | `meta-tools.test.ts` | the remaining registry-backed meta-tools: the complete on-demand usage skill, connector-guide selection and summary bounds, stored-credential drift, catalog health, authorization, probe timeouts, and unavailable or unknown browse recovery |
-| `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide and complete reviewed schema-digest manifest |
+| `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide, destructive metadata fill, and complete 64-tool schema-digest manifest |
 | `notion-provider.test.ts` | Notion's deliberate tool surface, including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
-| `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, `gate()`, the generation fence, and the request path |
+| `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `provider-registry.test.ts` | all six maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
@@ -253,11 +263,11 @@ in.
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
-| `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
+| `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the refund-preference read and argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
 | `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory and exact model-only Apps metadata → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, and deferred catalog reads through both discovery surfaces |
 | `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: every built-in answered ahead of connector routes inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
-| `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, admission, exact account selectors, and no-guess rule |
+| `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, current eleven-tool classifications, admission, exact account selectors, and no-guess rule |
 | `operator-view.test.ts` | the app's pure state rules from `view.ts`: filtering, page routing, capability states, activity summaries, drift display, and identity reset |
 | `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
 | `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus the URL safety gates |
@@ -272,13 +282,13 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | --- | --- | --- |
 | `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, one Node template that is also its own container, the same source running locally and in the container, the Node template's pinned esbuild install-script approval, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
 | `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
-| `doctor-cli.test.ts` | `connecta doctor`'s executor line end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, and a hostile name is bounded and stripped before it reaches a terminal | spawns the CLI against a Node HTTP deployment over real sockets |
+| `doctor-cli.test.ts` | `connecta doctor`'s executor line and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the maintainer drift checker — hosted-provider credential framing, recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |
 | `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
 | `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor, including identical caught failure codes and inline describe recovery, its exact absent globals, and blocked runtime imports | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |
 | `packed-links.test.ts` | the packed-link gate itself — shipped targets and repository URLs accepted, relative links into unshipped paths and directories rejected with the citation to write instead, reference definitions seen, fenced examples ignored, the changelog exempt | spawns the Node packed-link gate against filesystem fixtures |
-| `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, every provider independently importable, and the Cloudflare provider free of bare specifiers | walks the package tree with Node filesystem APIs |
+| `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, dependency-free Cloudflare Access behind its Worker subpath, every provider independently importable, and the Cloudflare API provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
 | `quickjs-child-stderr.test.ts` | abnormal child exits retaining only an 8 KiB stderr tail, included in the parent-side diagnostic | mocks Node child-process streams |
@@ -319,10 +329,15 @@ confinement does too.
 - **A connector with no `verifyState` refuses every callback.** That is the
   designed behavior, not a bug: handing an unverified code to `finishAuth` is
   the vulnerability. The startup warning names the connector.
-- **401 loops from a client that cannot discover auth.** The client must reach
+- **401 loops from a Clerk client that cannot discover auth.** The client must reach
   the open `/.well-known/oauth-protected-resource` (and the `/mcp` variant);
   confirm CORS and the Clerk keys, and that DCR is enabled on the Clerk
   instance.
+- **An Access-protected MCP client receives redirects or loops.** Enable Managed
+  OAuth on the Access application and use an RFC 8707-capable client. Access,
+  not connecta, must answer the unauthenticated challenge and `/.well-known/`
+  metadata. Do not bypass those routes. For unattended automation, use an
+  Access Service Auth policy and service-token headers instead.
 - **No sessions and no server push, by design.** The transport is stateless.
   Scope resolves per request, which is also where the MCP spec has arrived.
 - **A tool that should be callable from a program is not.** Only tools

package/documentation/operator-ui.md

@@ -39,10 +39,25 @@ their walkthrough, which is the honest version of the same page count.
 | `src/operator-ui/browser.css` | One stylesheet, inlined into the shell. |
 | `src/operator-ui/generated.ts` | The build output: the bundle and the stylesheet as two exported strings. |
 
-The server renders a mount point, not a page. Branding, the Clerk loader, and
-every operator-configured URL stay in `src/ui.ts`, where they are gated before
-they can become an attribute; the bundle renders everything that has a state.
-Two roots share one store: `#operatorNav` and `#operatorContent`.
+The server renders a mount point, not a page. Branding, the optional Clerk
+loader, and every operator-configured URL stay in `src/ui.ts`, where they are
+gated before they can become an attribute; the bundle renders everything that
+has a state. Two roots share one store: `#operatorNav` and `#operatorContent`.
+
+Cloudflare Access is ambient browser auth. When the current Worker invocation
+has `ctx.access`, the shell selects the `cloudflare-access` UI mode, emits no
+Clerk loader, and sends no browser-readable token. Same-origin fetch includes
+the HttpOnly `CF_Authorization` cookie, Access admits it at the edge, and the
+server reads the resulting runtime identity. Sign out navigates to
+`/cdn-cgi/access/logout`. Mutations still require an exact same-origin
+`Origin`; an ambient cookie does not weaken the CSRF boundary.
+
+This runtime selection is the Clerk migration seam. A deployment may contain
+both providers: before Worker-level Access is attached, the data-free shell
+selects Clerk; after Access supplies `ctx.access`, it selects ambient auth. That
+is not two same-hostname gates running in parallel. Access is upstream and a
+request it rejects never reaches Clerk. Keeping Clerk in the array preserves a
+code-level rollback after Access is detached.
 
 The Clerk loader is intentionally blocking. The inline operator bundle calls
 `boot()` as soon as the parser reaches the end of the body, so a deferred Clerk
@@ -58,7 +73,8 @@ the same ordering.
   credential, token, and activity data arrives only through the authenticated
   `/ui/*` APIs, and the shell is identical whether or not a caller is signed in.
 - **One store, one identity.** `store.ts` is the only file that touches `fetch`,
-  `localStorage`, or Clerk. Every request carries the current session's token,
+  `localStorage`, Clerk, or the ambient Access mode. Every token-bearing request carries the current session's token,
+  while Access requests deliberately carry none,
   and every response is dropped unless the identity that asked for it is still
   the one on screen. `resetIdentity` replaces all identity-scoped state at once
   and bumps a generation that work already in flight compares itself against.

package/documentation/provider-conventions.md

@@ -693,8 +693,10 @@ Cloudflare keep/prune half of that judgment was made in
 [#350](https://github.com/zackbart/connecta/issues/350): 30 keep, 18 improve,
 3 prune, measured per tool in
 [`eval/current-version/results/issue-350-evidence.md`](https://github.com/zackbart/connecta/blob/main/eval/current-version/results/issue-350-evidence.md).
-Its eighteen `improve` rows are H8 and H9 misses on tools that clearly earn
-their place, so they are this audit's work, not a second removal argument.
+Its eighteen `improve` rows were H8 and H9 misses on tools that clearly earned
+their place. Issue #488 resolved them with useful output keys and maintained
+projections; the measurements remain the reason those tools stayed rather than
+a second removal argument.
 
 Each provider's own guide ([Cloudflare](./cloudflare.md),
 [Linear](./linear.md), [Mixpanel](./mixpanel.md), [Notion](./notion.md),

package/documentation/revenuecat.md

@@ -152,17 +152,18 @@ names the `authorize_connector` recovery. A permission gap, a plan restriction,
 or a rejected argument arrives as RevenueCat wrote it and is not an
 authorization problem.
 
-## The ninety-five tools, and what they are classified as
+## The ninety-six tools, and what they are classified as
 
 RevenueCat's
 [tool reference](https://www.revenuecat.com/docs/tools/mcp/tools-reference),
-read on **2026-08-18**, documents ninety-five tools in a Read/Write table.
-Ninety-four carry an access column and are classified here: **50 read-only, 15
-additive writes, 29 destructive writes.**
+read on **2026-08-30**, documents ninety-six tools. Ninety-five carry an access
+column and are classified here: **51 read-only, 15 additive writes, 29
+destructive writes.**
 
 Reads are every `Read` row, verbatim — the nine project and app reads, the four
 product reads, the entitlement, offering, targeting, paywall, customer, virtual
-currency, chart, webhook, and SDK reads, and `get-paywall-ai-task`.
+currency, chart, webhook, and SDK reads, `get-paywall-ai-task`, and
+`get-refund-request-preferences`.
 
 Writes follow the verb where the verb is honest: `archive-*` and `unarchive-*`
 flip an existing object's active state, `update-*`, `delete-*`, `publish-*`,
@@ -191,14 +192,15 @@ beside the row:
 `create-webhook-integration` deserves a sentence too. No existing integration
 changes, so the verb reads additive — but with filters omitted the new one
 "starts delivering" every customer event in the project to a URL the caller
-typed. Customer data leaving the account is the `create_refund` argument again:
-filed destructive on consequence, so the approval copy says what is at stake.
+typed. Customer data leaving the account makes it destructive on consequence,
+so the approval copy says what is at stake.
 
 **`render-paywall-screenshot` is deliberately unclassified.** RevenueCat's
-reference gives it no access column at all, so no release has reviewed what it
-does. It fails closed onto `call_destructive_tool` rather than being guessed
-into the read path because its name sounds harmless (P5). The guide names it,
-so an agent does not read the approval prompt as a bug.
+reference gives it no access column. The current live server explicitly marks
+it read-only, so that catalog keeps it callable from `execute_code`; if a later
+catalog omits the annotation, it fails closed onto `call_destructive_tool`.
+Connecta preserves the provider's current annotation without inventing a
+release classification from the tool's harmless-sounding name (P5).
 
 That classification fills in downstream silence and otherwise preserves explicit
 annotations. A tool on the read allowlist arriving with `destructiveHint: true`
@@ -242,7 +244,7 @@ API v2 meters per minute and **per domain**
 | Charts & Metrics | 25 |
 
 A `ConnectorCallAdmissionPolicy` carries exactly one rule, so a connector-wide
-budget has to pick one of those six numbers for all ninety-five tools.
+budget has to pick one of those six numbers for all ninety-six tools.
 Transcribing 25 would throttle a customer read loop to a nineteenth of its
 documented allowance; transcribing 480 would leave a chart sweep unprotected.
 Neither is the provider's limit, and both would look like RevenueCat being
@@ -281,15 +283,13 @@ still needs restrained use.
 
 ## What is not verified
 
-- **Every tool name is transcribed from RevenueCat's published reference on
-  2026-08-18, not read from a live catalog.** No maintainer ran this against a
-  project with a real key before it shipped. A name the reference lists and the
-  server does not serve costs nothing; a tool the server serves and the
-  reference omits fails closed. The maintainer-run drift check with
-  `CONNECTA_DRIFT_REVENUECAT_KEY` set is what turns that into a finding with a
-  name attached.
-- **No input or output schema has been read**, which is why the manifest
-  carries no digests.
+- **The 2026-08-30 live review used a project-scoped catalog.** It proves the
+  additions that catalog serves, including `get-refund-request-preferences`,
+  but cannot prove a globally documented tool was removed. The manifest stays
+  a superset because plan, platform, and credential scope hide tools.
+- **No complete schema set has been recorded**, which is why the manifest
+  carries no digests. The review read the new live schemas, but its scoped
+  catalog omitted many classified writes.
 - **Whether `render-paywall-screenshot` mutates anything.** It has no access
   column, and guessing is exactly what P5 exists to prevent.
 

package/documentation/stripe.md

@@ -139,38 +139,39 @@ boots but cannot list tools is usually a dashboard toggle, not a bad key.
 
 ## The eleven tools, and what they are classified as
 
-Stripe documents eleven tools on the hosted server. Seven are reads:
+Stripe currently serves eleven tools. Seven are reads:
 
 `stripe_api_search`, `stripe_api_details`, `stripe_api_read`,
-`get_stripe_account_info`, `get_balance_summary`,
-`search_stripe_documentation`, `stripe_implementation_planner`.
+`get_balance_summary`, `list_available_accounts_or_orgs`,
+`manage_stripe_accounts`, and `search_stripe_documentation`.
 
 Four are writes:
 
-`stripe_api_write` and `create_refund` are classified destructive;
-`stripe_report` and `send_stripe_mcp_feedback` are additive.
+`stripe_api_write` is destructive. `stripe_implementation_planner`,
+`stripe_analytics`, and `send_stripe_mcp_feedback` are additive.
 
 Two of those deserve a sentence. `stripe_api_read` is a read because Stripe
 documents it as the `GET` half of a generic pair — the tool is the read
 boundary, not whichever endpoint an agent names inside it, and its sibling
 `stripe_api_write` carries every `POST`, `PATCH`, `PUT`, and `DELETE`.
-`create_refund` is filed destructive despite its name: it reverses a settled
-charge and moves money back out, which is a mutation of something that already
-exists rather than a fresh object appearing beside it. Additive writes
-(`stripe_report`, `send_stripe_mcp_feedback`) leave `destructiveHint` unset;
+`stripe_implementation_planner` creates and continues provider-side guide
+state. `stripe_analytics` combines retrieval with query-run creation behind one
+tool. Stripe marks both not read-only and not destructive, so Connecta records
+them as additive writes. They leave `destructiveHint` unset. Their explicit
 `readOnlyHint: false` already routes them through `call_destructive_tool`, and
-asserting destruction only inflates the approval copy the host shows a human.
+asserting destruction would misstate their effect.
 
 That classification fills in downstream silence and otherwise preserves
-explicit annotations. It supplies the annotations Stripe leaves unset — Stripe
-documents no MCP annotations at all. A tool on the read allowlist arriving with
+explicit annotations. The current server annotates all eleven tools, while the
+manifest records what this release reviewed and exposes later contradictions.
+A tool on the read allowlist arriving with
 `destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
 downstream said and stays behind `call_destructive_tool`. A tool on neither
 maintained list arriving with `readOnlyHint: true` keeps that too, and stays
 callable from `execute_code`. Both are the downstream telling you this release's
 allowlist is stale, and on a name no release has reviewed its word is the only
 evidence there is. One narrow fail-closed exception applies to a name this
-release reviewed and filed destructive: a `create_refund` claiming
+release reviewed and filed destructive: `stripe_api_write` claiming
 `readOnlyHint: true` is a downstream bug rather than news, and stays on the
 approval path.
 

package/documentation/upgrading.md

@@ -57,7 +57,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.20.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.21.1 | 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 +106,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.20.0
+npm pkg set dependencies.@zackbart/connecta=0.21.1
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.20.0 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.21.1 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,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.20.0 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.21.1 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 +207,79 @@ 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.20.0 → 0.21.1
+
+0.21.1 adds no deployment migration beyond 0.21.0. The boundary is additive
+for Node and existing Clerk deployments. The new Worker path
+uses Cloudflare Access identity directly and removes Clerk only after the edge
+cutover has been verified. An agent can perform every repository edit; a human
+must attach Access, choose its policy, create service credentials, and enable
+Managed OAuth in the Cloudflare dashboard.
+
+For a Worker currently using Clerk, keep rollback live through the cutover:
+
+1. Bump and install 0.21.1. Add the new provider **before** the existing Clerk
+   provider, but remove nothing:
+
+   ```ts
+   import { cloudflareAccessAuth } from
+     "@zackbart/connecta/auth/cloudflare-access";
+   import { clerkAuth } from "@zackbart/connecta/auth/clerk";
+
+   auth: [
+     cloudflareAccessAuth(),
+     // Keep the deployment's existing options and secrets unchanged.
+     clerkAuth({ /* existing configuration */ }),
+   ],
+   ```
+
+   Before Access is attached, the new provider fails closed and the operator
+   shell selects Clerk. Deploy this state and run doctor with the existing
+   `CONNECTA_TOKEN`. This separates the package/code change from the edge
+   change and proves the old path still works.
+
+2. In Cloudflare, attach Access to the Worker itself, apply the intended human
+   policy, and enable Managed OAuth. Through the API this is an Access
+   application destination of `{ "type": "worker", "worker_id": "<script
+   tag>" }`, not a hostname application for the `workers.dev` URL: the latter
+   gates traffic but does not provide `ctx.access`. Create an Access service
+   token and a **Service Auth** policy for doctor and fully unattended clients.
+   Do not create a bypass for `/.well-known/*`; Managed OAuth owns that
+   discovery surface.
+
+3. Reconnect interactive MCP clients to `<PUBLIC_URL>/mcp`. Their old Clerk
+   OAuth tokens are not Cloudflare credentials, so each client performs one new
+   browser authorization. An agent can edit client configuration and start the
+   flow; the user still completes the identity-provider prompt. Move CI, cron,
+   and server-to-server callers from connecta bearers to the two Access service
+   headers. The cutover warning is literal: once Access is attached, a static
+   bearer or `cta_…` token by itself is stopped at the edge before connecta can
+   inspect it.
+
+4. Verify the edge path:
+
+   ```sh
+   CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
+     npx connecta doctor --url https://connecta.example.workers.dev
+   ```
+
+   Open `/` as a human and exercise any enabled credential, token, and OAuth
+   controls. A service token may pass doctor and MCP but must receive 403 from
+   operator mutations.
+
+5. After an observation window, remove `clerkAuth`, its import,
+   `@clerk/backend`, and the Clerk variables/secrets. Until then they are inert
+   behind Access but preserve rollback. Rollback order matters: detach Access
+   first, then the untouched Clerk sessions and connecta bearers reach the
+   Worker again. Reverting code first cannot help a request the edge still
+   blocks. There is no storage migration and no token-format conversion.
+
+If the Worker exposes an intentionally public connector route, create a
+more-specific hostname/path Access application with a Bypass policy for that
+route only. `/health`, downstream OAuth callbacks, operator shells, and MCP are
+private under the canonical whole-Worker shape; doctor knows how to authenticate
+its health request.
+
 ### 0.19.0 → 0.20.0
 
 Three intake paths become deliberately strict. None changes storage, the two