@zackbart/connecta 0.19.0 → 0.21.0

package/documentation/code-mode.md

@@ -503,9 +503,9 @@ the security posture live in the [design record](https://github.com/zackbart/con
 [#277](https://github.com/zackbart/connecta/issues/277)); this section is the
 contract, and it wins where the two disagree.
 
-**U1.** `connecta.ui(html, options?)` accepts one non-empty HTML string and at
-most the bounded read manifest `V1` defines. The one-argument call stays
-display-only; every other shape throws catchably and accepts nothing.
+**U1.** `connecta.ui(html)` accepts exactly one non-empty HTML string. There is
+no options parameter, read manifest, or sugar form. Every other shape throws
+catchably and accepts nothing.
 
 **U2.** At most one payload per run. A second call throws catchably, naming the
 constraint; the first accepted payload stands. One tool result renders one view,
@@ -513,7 +513,7 @@ and last-wins would silently discard a payload the program deliberately
 supplied.
 
 **U3.** Delivered on success only, and out of model context: the tool result
-gains `_meta["connecta/ui"] = { html, reads? }` and the JSON envelope gains `ui: true`,
+gains `_meta["connecta/ui"] = { html }` and the JSON envelope gains `ui: true`,
 so the model learns a view rendered without seeing its bytes. `structuredContent`
 stays the envelope alone. The single-label `connecta/ui` prefix is deliberate —
 connecta has no domain to reverse, and fabricating one to satisfy MCP's
@@ -526,29 +526,31 @@ with `emittedDiscarded: N` when one failure discards both.
 
 **U4.** The payload spends the aggregate emit byte budget
 (`ConnectaConfig.execute.maxEmittedBytes`), measured at the call as the
-serialized bytes of `{ html, reads? }` — `M5`'s measurement. Over budget throws
+serialized bytes of `{ html }` — `M5`'s measurement. Over budget throws
 catchably, naming the budget and the room remaining, with nothing partially
 accepted. It spends no block count (`maxEmittedBlocks`: it is not a block) and no
 host-call budget (`L4`). One transport bound covers everything rich a program
 delivers.
 
 **U5.** One static shell: a connecta-authored HTML5 document at
-`ui://connecta/program-ui/v2`, mimeType `text/html;profile=mcp-app`, declared on
+`ui://connecta/program-ui/v3`, mimeType `text/html;profile=mcp-app`, declared on
 `execute_code` via `_meta.ui.resourceUri` together with an explicit
-`_meta.ui.visibility: ["model"]`. Only `call_tool` declares app visibility; all
-other tools say model-only. A `resources/read` handler answers exactly that
-URI and fails on any other; `resources/list` is served and returns an empty list.
+`_meta.ui.visibility: ["model"]`. The other six tools declare the same
+model-only visibility without a resource URI. Omission defaults to model and
+app visibility, which would let a display-only view call them. A
+`resources/read` handler answers exactly that URI and fails on any other;
+`resources/list` is served and returns an empty list.
 The version segment bumps whenever the shell's bytes change, because hosts cache
 templates by URI.
 
 **U6.** The shell renders the payload in a nested iframe
 (`srcdoc`, `sandbox="allow-scripts"`, no `allow-same-origin`) and declares no CSP
 domains, so the host applies its restrictive default and the `about:srcdoc` frame
-inherits `default-src 'none'; connect-src 'none'`. One argument stays display-only;
-a `V1` manifest installs only named `connecta.read`, with no direct network, raw
-tool calls, discovery, conversation, writes, or links. The shell participates in the Apps lifecycle —
-initialize, tool-result, size-changed, resource-teardown — and forwards no
-channel whatsoever from the inner frame to the host. That isolation makes
+inherits `default-src 'none'; connect-src 'none'`. The shell offers no direct
+network, tool calls, discovery, conversation messages, writes, or links. It
+participates in the Apps lifecycle — initialize, tool-result, size-changed,
+resource-teardown — and forwards no channel whatsoever from the inner frame to
+the host. That isolation makes
 program views fixed-height by construction: with no bridge there is no
 content-height signal, the shell reports only its own box, and content taller
 than that scrolls inside the inner frame rather than growing the view.
@@ -591,16 +593,14 @@ the same mistake as automatic host-side projection, refused in `ethos.md`
 
 **U13.** The always-loaded MCP instructions locate `connecta.ui(html)` before an
 agent chooses a route: it exists only inside `execute_code`, never in connector
-search, and carries `U12`'s mirrored-return duty. The detailed call, binding,
-budget, and repair rules live in the on-demand `usage` skill. The location
+search, and carries `U12`'s mirrored-return duty. The detailed call, budget,
+and repair rules live in the on-demand `usage` skill. The location
 distinction rides `initialize`, under a 1,000-character ceiling for the complete
 instructions string. This promotes existing contract, not capability: the
 seven-tool surface, guest API, catalog, Apps delivery, and runtime do not change
 ([#286](https://github.com/zackbart/connecta/issues/286),
 [#418](https://github.com/zackbart/connecta/issues/418)).
 
-Bounded view reads follow normative [`V1`–`V8`](https://github.com/zackbart/connecta/blob/main/records/program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
-
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -878,7 +878,7 @@ the upstream `Executor` shape assignable.
 | `U1`, `U2` | `test/guest-api-contract.test.ts` (invalid and repeated calls throw catchably, first payload stands), `test/execute-ui.test.ts` (every rejected shape) |
 | `U3` | `test/guest-api-contract.test.ts` (`_meta` payload and `ui: true`, identical on both executors), `test/execute-ui.test.ts` (`structuredContent`, byte-for-byte no-call path, discard structured and plain, coexistence with `emittedDiscarded`), `test/quickjs-executor.test.ts` (mid-run shutdown) |
 | `U4` | `test/execute-ui.test.ts` (one shared byte aggregate crossed in either order; block count and host-call budget untouched) |
-| `U5`, `U10`, `U11` | `test/server.test.ts` (the shell URI, mimeType, and body; every other URI fails; empty listing; `execute_code`'s `_meta.ui`; exactly one declared extension) |
+| `U5`, `U10`, `U11` | `test/server.test.ts` (the shell URI, mimeType, and body; every other URI fails; empty listing; exact model-only `_meta.ui` on all seven tools; exactly one declared extension) |
 | `U6` | `test/execute-ui.test.ts` (valid HTML5, `srcdoc` and sandbox attributes, no `allow-same-origin`, no path from the inner frame to the host) |
 | `U7`, `U8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `U9` | `test/execute-ui.test.ts` (a `ui` byte aggregate distinct from `emitted`, absent when nothing was accepted) |
@@ -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/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.
@@ -192,36 +194,10 @@ offsets and totals refer to that exact compact text.
 A `call_tool` truncation notice carries both the historical `resultId` and an
 exact `nextAction: { tool: "get_result", arguments: { id, offset: 0 } }`. The
 handle is therefore
-directly actionable without copying an identifier out of prose; re-calling with
-`fields` remains the smaller alternative when projection is possible. Program results and oversized discovery responses carry no such
-route — paging a program's return value is a refused shape, because a program
-can shrink anything before it returns.
-
-`fields` keeps its historical flat `{ "<path>": value }` result when every
-requested dot-path resolves. Dot notation traverses objects; append `[]` to an
-array field before continuing, as in `results[].id`. Empty arrays resolve to
-empty arrays. An exact downstream
-`$connecta` field is always escaped under `data`. If any path misses—or that
-reserved name is selected—the result carries matches under `data` and reserves `$connecta` for a
-`type: "field_projection"` recovery record naming each `unmatchedFields`
-entry. A path that resolves for only some array elements stays in `data` and
-appears in `partialFields`; its unresolved positions serialize as `null`, while
-the recovery record distinguishes them from genuine downstream nulls. A path
-that misses every element appears in `unmatchedFields` and is omitted from
-`data`. Both lists scale with requested paths, never with array length. When a
-miss matches a declared array path except for `[]`, the record also carries the
-traversal hint. The discriminator means downstream fields
-named `data`, `projection`,
-or `$connecta` remain ordinary values nested under `data`, never apparent
-metadata. A declared output schema contributes a bounded `availableFields`
-list and a `schemaCoverage` verdict. Only a completely analyzed, closed schema
-can label paths `invalidFields`; open, patterned, tuple, unresolvable, cyclic,
-`$ref`-sibling, or traversal-limited shapes stay `partial`. Traversal bounds
-depth, nodes, path count, individual path characters/bytes, and cumulative path
-characters/bytes before sorting or rendering. Without a schema, Connecta
-reports only observed misses and does not pretend it knows the complete runtime
-shape. API values and JSON-parseable downstream MCP text blocks follow the same
-rule.
+directly actionable without copying an identifier out of prose. Program results
+and oversized discovery responses carry no such route — paging a program's
+return value is a refused shape, because a program can shrink anything before
+it returns.
 
 ## Lexical discovery
 

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 |
@@ -96,14 +105,14 @@ optional.
 | `admission.requests?` | 16 active / 32 queued / 5 s / 1 s | global FIFO `/mcp` capacity, taken before auth ([request admission](./request-admission.md)) |
 | `admission.code?` | 2 active / 8 queued / 5 s / 1 s | fallback pool for an executor that owns no `acquire()`; ignored with a warning when it does |
 
-Options removed in earlier releases throw with their migration named rather
-than falling back to a default: `toolkits`
-([#178](https://github.com/zackbart/connecta/issues/178)), `credentials.health`
-([#179](https://github.com/zackbart/connecta/issues/179)), `surface` and
-`calls.maxBatchResultBytes`
-([#273](https://github.com/zackbart/connecta/issues/273)), and the flat v0.6
-paths. Silently ignoring a removed option is how a deployment ends up running a
-policy its config file says it has.
+An unknown own option throws before construction does deployment work. The
+check covers the top level, every configuration group, admission pools,
+branding icons, and server icons; the error names the rejected path without
+copying its value. Removed options such as `toolkits`, `credentials.health`,
+`surface`, `calls.maxBatchResultBytes`, and the flat v0.6 paths now take that
+same path. The [upgrade guide](./upgrading.md#removed-options-that-throw) keeps
+their historical mappings. Silently ignoring either a typo or a removed option
+is how a deployment runs a policy its config file does not describe.
 
 ### Deployment as a release unit
 
@@ -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,28 +232,29 @@ 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-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, request building, projections, 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 one complete migration error for legacy own-properties |
+| `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 |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
 | `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and races, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
 | `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
 | `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
-| `execute-ui.test.ts` | `connecta.ui` (U1–U9) — validation, multiplicity and budget, the provider, `_meta` delivery, and the Apps shell |
+| `execute-ui.test.ts` | display-only `connecta.ui` (U1–U13) — one-string validation, multiplicity and budget, the provider, `_meta` delivery, shell isolation, and the absence of a payload-to-host call path |
 | `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 |
-| `meta-tools-call.test.ts` | registry-backed calls: structured errors, field projection, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
+| `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 |
 | `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 |
@@ -254,7 +264,7 @@ in.
 | `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` |
-| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory → 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.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 |
@@ -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 |
@@ -294,7 +304,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | Suite | Covers |
 | --- | --- |
 | `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
-| `browser/program-ui.spec.ts` | the Apps shell in a real browser: a bound view merging fixed and declared arguments and correlating concurrent reads, and the one-string payload receiving no read bridge ([program UI read calls](https://github.com/zackbart/connecta/blob/main/records/program-ui-read-calls.md)) |
+| `browser/program-ui.spec.ts` | the display-only Apps shell in a real browser: local payload JavaScript runs, `connecta` stays absent, and forged payload messages never become host tool calls |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is
 internal, not public API: when set, `remoteMcp()` uses that `Transport` instead
@@ -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

@@ -183,10 +183,9 @@ tokens.
 
 ### H8 — Every tool declares an `outputSchema`
 
-Declared outputs are what produce `outputKeys` and the `fields` projection's
-`availableFields`, and they let a program reduce a result without first
-fetching one to look at. Connecta measured *declared* output schemas at 0 of 30
-tools on one real deployment and 3 of 30 on another
+Declared outputs produce `outputKeys` and let a program reduce a result without
+first fetching one to look at. Connecta measured *declared* output schemas at 0
+of 30 tools on one real deployment and 3 of 30 on another
 ([#282](https://github.com/zackbart/connecta/issues/282)) — nearly every tool an
 agent meets is a shape it can only learn by calling. A maintained provider has
 no excuse to join that majority.

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.19.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.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +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.19.0
+npm pkg set dependencies.@zackbart/connecta=0.21.0
 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.19.0 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.21.0 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.19.0 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.21.0 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,6 +207,102 @@ 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.0
+
+This 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.0. 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
+deployment shapes, or the exact seven-tool MCP surface.
+
+- `createConnecta` now rejects every unknown own configuration property by its
+  complete path. Remove typos and options retired before 0.19, including the
+  top-level `toolkits`, `credentialHealth`, `surface`, and `maxResultBytes`,
+  plus `credentials.health` and `calls.maxBatchResultBytes`. Connector, auth,
+  storage, activity-store, logger, deployment-metadata, and executor
+  implementations remain open objects; their implementation-specific fields
+  are not configuration typos.
+- `call_tool` and `call_destructive_tool` no longer accept `fields`. Put
+  projection in one `execute_code` program. For a legitimate oversized direct
+  read, call without `fields` and follow the returned `get_result` action; that
+  paging path remains part of the seven-tool surface.
+- `connecta.ui` accepts one HTML string and is display-only. Remove its second
+  read-binding argument and any page calls to `connecta.read`. Fetch and shape
+  data in the program before rendering, then return the same compact summary
+  the view initially displays. Views cannot call any Connecta tool.
+
+The Node template layout remains generation B. Reconcile it as usual after the
+version bump; no new deployment file or environment variable is required.
+
 ### 0.18.3 → 0.19.0
 
 Nothing changes for a deployment. Bump the version and reconcile the template
@@ -451,9 +547,11 @@ built-in routes miss, so it can add a route and never shadow one
 
 ### Removed options that throw
 
-These fail at construction with their migration named rather than falling back
-to a default, because silently ignoring a removed option is how a deployment
-ends up running a policy its config file says it has:
+These fail at construction rather than falling back to a default, because
+silently ignoring a removed option is how a deployment runs a policy its config
+file says it has. Releases through 0.19 name the migration in the error. Version
+0.20's strict configuration boundary names the unknown path; this table remains
+the migration map:
 
 | Option | Removed in | Do |
 | --- | --- | --- |
@@ -461,7 +559,7 @@ ends up running a policy its config file says it has:
 | `credentials.health`, `credentialHealth` | 0.8.1 (#179) | delete; credentials fail at use |
 | `surface` | 0.11.0 (#273) | delete; there is one seven-tool surface |
 | `calls.maxBatchResultBytes` | 0.11.0 (#273) | delete; program batching is bounded by `execute_code`'s own limits |
-| flat v0.6 config paths | 0.7.0 | move into their groups — one complete migration error lists them ([operations](./operations.md#configuration)) |
+| flat v0.6 config paths | 0.7.0 | move into their groups ([operations](./operations.md#configuration)) |
 
 ## Verify