@zackbart/connecta 0.16.1 → 0.18.0

package/documentation/operations.md

@@ -8,15 +8,18 @@ needs most.
 
 `createConnecta(config)` returns `{ fetch, registry, close }`. `fetch` takes
 the Workers `(request, env, ctx)` signature; passing `ctx` through is what lets
-connecta hand deferred work — best-effort activity writes — to `ctx.waitUntil`
-instead of losing it when the response returns.
+connecta hand deferred work to `ctx.waitUntil` instead of losing it when the
+response returns. That work is best-effort activity writes and the bounded
+refresh an agent catalog read already demanded while it served a complete stale
+entry. Node's adapter tracks the same promises and drains them on shutdown.
 
 An `executor` is required. A deployment without one throws at construction
 rather than serving a smaller surface
 ([#273](https://github.com/zackbart/connecta/issues/273)): Node uses
 `quickJsExecutor()` from `@zackbart/connecta/quickjs`, Workers use
 `new DynamicWorkerExecutor({ loader: env.LOADER })` from
-`@cloudflare/codemode`.
+`@cloudflare/codemode`. The Worker executor must stay loader-only: `bindings`,
+`modules`, and `globalOutbound` grant ambient guest authority.
 
 Both executor packages are optional peers: they never install with connecta,
 and a deployment installs the one its runtime needs. The manifest publishes the
@@ -84,7 +87,7 @@ optional.
 | `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 |
-| `discovery.staleCatalogSeconds?` | 3600 | how long an expired catalog stays usable as a failure fallback |
+| `discovery.staleCatalogSeconds?` | 3600 | how long a complete expired catalog stays usable for agent SWR and as a refresh-failure fallback |
 | `discovery.probeTimeoutMs?` | 30_000 | per-connector deadline for catalog fan-out; a timed-out connector degrades alone. Not a tool-call deadline |
 | `calls.defaultTimeoutMs?` | **unset (opt-in)** | deadline for calls that pass no `timeoutMs`. Bounds one attempt, so retries can still extend total duration |
 | `calls.maxResultBytes?` | 50_000 | inline result cap before truncation and `get_result` paging; a connector may override it. Invalid values warn and fall back |
@@ -180,7 +183,7 @@ Two more runners are deliberately outside `check`:
 
 - `npm run test:browser` — Playwright against a real headless Chromium
   (`npm run test:browser:install` once). It covers the embedded bundle without
-  adding a browser download to both CI Node-version jobs.
+  adding a browser download to the CI release check.
 - `npm run drift:check` — the maintainer-run provider drift check, with local
   provider credentials exported. No credential goes near CI and nothing files
   itself; findings are read by a human and become issues
@@ -221,36 +224,36 @@ in.
 | `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-registry.test.ts` | the same provider inside a real deployment: discovery, addressing, and admission through the registry |
-| `code-first-surface.test.ts` | the seven-tool surface itself — an executor required and both runtime configurations named, every removed option and removed top-level tool refused, and `connecta.ui` findable before an agent chooses catalog search |
+| `cloudflare-registry.test.ts` | the same provider inside a real deployment: discovery including compact page bounds, addressing, and admission through the registry |
+| `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 |
 | `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, fail-closed filtering of destructive and unannotated tools, and MCP/code-mode invocation parity |
+| `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 |
 | `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 executor-independent half of the guest API contract cases, including the serialized truncation envelope, capped logs, truncation reported as success, and an in-flight host call failing when the run ends |
+| `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` / `linear-registry.test.ts` | the Linear proxy's construction, classification, and guide; then the same connector inside a real deployment |
-| `meta-tools.test.ts` | the registry-backed meta-tools: bounded discovery with page and address maxima, concise and full descriptions, compact and JSON schemas, structured errors, `skills` and connector-guide selection, stored-credential drift, catalog-lookup health accounting, `fields` selection, truncation and `get_result` offset validation and character alignment, per-connector `maxResultBytes`, probe timeouts, and empty-query browse of an unavailable or unconfigured catalog |
-| `mixpanel-provider.test.ts` / `mixpanel-registry.test.ts` | the Mixpanel proxy, then the same connector inside a real deployment |
-| `notion-provider.test.ts` / `notion-registry.test.ts` | Notion's tool surface, request construction, lean projections, both pagination conventions, error mapping, and writes; then the connector in a real deployment |
+| `meta-tools.test.ts` | the registry-backed meta-tools: bounded discovery with page and address maxima, compact descriptions and the complete on-demand usage skill, compact and JSON schemas with constraints, typed describe recovery and suggestions, structured errors, connector-guide selection and summary bounds, stored-credential drift, catalog health, field projection, truncation and `get_result`, per-connector result bounds, probe timeouts, and unavailable or unknown browse recovery |
+| `mixpanel-provider.test.ts` / `mixpanel-registry.test.ts` | the Mixpanel proxy, its conditional-input guide and complete reviewed schema-digest manifest, then the same connector inside a real deployment |
+| `notion-provider.test.ts` / `notion-registry.test.ts` | Notion's deliberate tool surface, including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes; then the connector in a real deployment |
 | `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 |
-| `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
-| `registry.test.ts` | construction and id validation, startup convention and result-cap warnings, address resolution, tool-cache TTL, and broken-connector isolation |
+| `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) |
+| `registry.test.ts` | construction and id validation, startup warnings, address resolution, 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 |
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
 | `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 |
-| `server.test.ts` | end-to-end `/mcp` (401 → initialize instructions → seven tools → usage skill → `call_tool`), the open routes, Clerk `.well-known` metadata with no network, and an end-to-end code-mode run |
+| `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-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` / `stripe-registry.test.ts` | the Stripe proxy's endpoint modes and admission, then the connector in a real deployment |
-| `ui.test.ts` | the server shell and `/ui/*` routes and the app's pure state rules from `view.ts` — filtering, page routing and capability states, credential management, gated `/ui/data` with broken-connector isolation, and the URL safety gates |
+| `stripe-provider.test.ts` / `stripe-registry.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, admission, exact account selectors, and no-guess rule; then fixed credentials in a real deployment |
+| `ui.test.ts` | the server shell and `/ui/*` routes and the app's pure state rules from `view.ts` — filtering, page routing and capability states, credential management, gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, and the URL safety gates |
 | `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
@@ -260,12 +263,12 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | Suite | Covers | Why Node |
 | --- | --- | --- |
-| `deployment-shapes.test.ts` | the Worker as the only example, one Node template that is also its own container, the same source running locally and in the container, 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 |
+| `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 |
-| `drift-check.test.ts` | the maintainer drift checker — 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 |
+| `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 | runs the contract cases on the Node QuickJS executor |
+| `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 |
@@ -283,7 +286,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: 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/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](./program-ui-read-calls.md)) |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is

package/documentation/operator-ui.md

@@ -44,6 +44,14 @@ 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 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
+script would make an expected parse-time gap look like a permanent network
+failure. Blocking also preserves the existing failure path: after a real
+loader error, the parser continues and `boot()` renders the Clerk load message.
+Clerk's redirect from the major-version loader URL to its pinned asset keeps
+the same ordering.
+
 ## Rules that are not obvious
 
 - **No operator data in the shell.** Every page serves the same markup. Connector,
@@ -93,9 +101,11 @@ well as Node and there is no DOM in either:
   something calls them when the identity actually changes. It typechecks in the
   DOM-lib program (`tsconfig.operator-ui.json`) because it imports the store.
 - `test/browser/operator-ui.spec.ts` — the wiring, in a real browser:
+  Clerk loader order across its version redirect and a real load failure, plus
   credential, token, and OAuth flows end to end, including their failure and
-  empty states. Run it with `npm run test:browser` (`npm run test:browser:install`
-  once, for Chromium). It is not part of `npm run check`.
+  empty states. Run it with `npm run test:browser`
+  (`npm run test:browser:install` once, for Chromium). It is not part of
+  `npm run check`.
 
 ## Why the bundle is committed
 

package/documentation/provider-audit.md

@@ -81,6 +81,14 @@ deliberate surface.
 | H13 guide | meets | structured, declared summary, `required: true` with a stated reason — the database→data-source lookup is a sequence no complete schema can express |
 | H14 hatch | **missed → fixed** | Notion has no guarded raw-REST tool, which H14 explicitly permits for a finite surface — provided it says so. It did not. The guide now names the absence, so an agent does not spend a search proving there is no `notion_api_get` |
 
+The 0.17.0 drift review also considered Notion's expanded create and update
+contracts. Workspace-private creation, templates, placement, richer media,
+locking, and irreversible content erasure stay outside the maintained surface.
+They are separate ownership, ordering, asynchronous, coordination, file, or
+deletion workflows rather than missing fields on the five existing writes
+([#408](https://github.com/zackbart/connecta/issues/408),
+[#409](https://github.com/zackbart/connecta/issues/409)).
+
 ## Linear — hosted-MCP proxy
 
 | Convention | Verdict | Notes |
@@ -104,17 +112,17 @@ deliberate surface.
 | Convention | Verdict | Notes |
 | --- | --- | --- |
 | P1 add, never rewrite | meets | annotations only |
-| P2 identity | meets | required `purpose`, `instructions` appended, classification untouchable from there |
-| P3 routing fact | meets | production versus sandbox appears in the title, the description, and the guide's first line |
-| P4 endpoint default | meets | exemplary, and the model for the second clause: one published endpoint, `mode` required with no default, and construction throws when a recognizable key prefix contradicts the declared mode without reading anything it cannot classify |
+| P2 identity | meets | required `purpose`, `instructions` appended, classification untouchable from there; purpose states deployment routing intent and the guide says it is not proof of authenticated account identity |
+| P3 routing fact | meets | OAuth metadata states mixed account scope and the guide resolves mode from `livemode`; fixed header credentials retain their mode in every routing surface |
+| P4 endpoint default | meets | OAuth has no connector-wide mode to default; static headers require one, and construction throws when a recognizable key prefix contradicts it |
 | P5 classification | meets | including the two verdicts that needed an argument — `stripe_api_read` is a read because the tool is the boundary, `create_refund` is destructive despite its name |
 | P6 catalog varies | **missed → fixed** | the doc already knew this (`get_balance_summary` is Treasury and gated; a `create_customer` example survives in Stripe's prose but not its tool table), but the *guide* did not say it, and the guide is what reaches the agent. Added |
-| P7 reduction advice | **missed → fixed** | bare string; the derived summary was "Mode: production. Account purpose: …", spending the 120-character budget on the operator's prose. Now a declared, mode-shaped summary. `required` unset: the four generic tools are the routing decision and the mode warning already rides the title and description |
-| P8 identity resolution | **missed → fixed** | Stripe's writes take ids and the guide never said where they come from. Added: the typed prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), the rule that a plausible-looking id belongs to a different object or to nobody, and the read tools that produce a real one |
-| P9 authentication | meets | OAuth default, `requireHttps`, restricted key documented as a secret and paired with the narrowest scope. The `auth_required` → `authorize_connector` route was added to the guide alongside P8, since a proxy's only recovery instruction lives there |
+| P7 reduction advice | **missed → fixed** | OAuth has a mixed-scope summary; fixed credentials keep mode-shaped summaries. `required` stays unset because the four generic tools remain the routing decision |
+| P8 identity resolution | **missed → fixed** | The guide names typed object ids and their read sources. For OAuth it requires `list_available_accounts_or_orgs`, then carries the returned `stripe_context` and `livemode` unchanged; ambiguity stops ([#404](https://github.com/zackbart/connecta/issues/404), [#414](https://github.com/zackbart/connecta/issues/414)) |
+| P9 authentication | meets | OAuth default, `requireHttps`, restricted key documented as a secret and paired with the narrowest scope. The guide distinguishes organization accounts within an OAuth session from Connect connected accounts, whose calls reject OAuth and use a deployment-configured restricted key plus `Stripe-Account`. The `auth_required` → `authorize_connector` route was added alongside P8, since a proxy's only recovery instruction lives there |
 | P10 no credential test | meets | no credential slot; the mode/key contradiction throws at construction instead, which is where P10 says the H12 guarantee gets paid |
 | P11 transport vs tool error | meets | inherited from `remoteMcp()`; the guide now also says that a rejected argument or plan restriction arrives in Stripe's own words and is not an authorization problem |
-| P12 admission budget | meets | a citable documented number (100/s live, 25/s sandbox), transcribed per mode, with `maxConcurrency` labeled as Connecta's own conservative choice |
+| P12 admission budget | meets | fixed credentials use their documented mode rate; mixed OAuth uses the stricter 25/s sandbox rate and concurrency bound |
 | P13 drift visible | meets | both lists are module-level constants in one file, and are the manifest the refresh-time drift check compares against ([#343](https://github.com/zackbart/connecta/issues/343)) |
 
 ## Mixpanel — hosted-MCP proxy

package/documentation/provider-conventions.md

@@ -50,19 +50,24 @@ floor. From `src/catalog.ts` and `src/catalog-service.ts`:
   `fullDescriptions: true`. Prose past those points reaches an agent only when
   it pays for the expansion.
 - **A compact schema renders into at most 1,024 UTF-8 bytes**, and any single
-  enum node into at most 256. Past either cap the renderer keeps what fits and
-  degrades the rest — a prefix of the enum plus `unknown`, a required-first
-  object with `unknown` types, or `unknown /* truncated */` — and flags the
-  match, which costs a describe round trip to recover.
+  enum or constraint annotation into at most 256. Numeric bounds, string
+  length bounds, patterns, and formats ride beside their TypeScript-like type.
+  Past a cap the renderer keeps what fits and degrades the rest — a prefix of
+  the enum plus `unknown`, a shape without the constraints that did not fit, a
+  required-first object with `unknown` types, or
+  `unknown /* truncated */` — and flags the match, which costs a describe
+  round trip to recover.
 - **`inputKeys`, `requiredInputKeys`, and `outputKeys` come only from bounded
   plain-object schemas.** A top-level `anyOf` has no keys to list, so a caller
   learns nothing about the arguments without expanding the schema.
-- **A guide summary is capped at 120 characters**, defaulting to the guide's
-  first meaningful body line.
+- **A guide summary is bounded at 120 characters.** A configured value past
+  the bound refuses construction. An omitted one defaults to the guide's first
+  meaningful body paragraph, joined across physical line wraps and shortened
+  at a readable boundary.
 - **Search returns a connector's `id`, `title`, `guide`, and `guideSummary` —
   never its `description`.** The description reaches an agent only as the
-  fallback summary for a guide with no usable body line. Routing facts belong
-  in the title and the guide's first line; a routing fact that lives only in
+  fallback summary for a guide with no usable body paragraph. Routing facts belong
+  in the title and the guide's opening paragraph; a routing fact that lives only in
   the connector description has been written into a field the model does not
   read. Neither the `id` nor the `title` is a lexical document, so a term drawn
   from one of them is not a search hit — it is a no-match whose guidance names
@@ -141,7 +146,8 @@ wrong-tool selection.
 Every tool carries a hand-written `inputSchema`: a plain object at the top
 level, `additionalProperties: false`, an accurate `required` list, an `enum` on
 every constrained field, explicit numeric bounds on every page size and count,
-and a description on every property — nested objects and array items included,
+explicit string bounds where length or shape is constrained, and a description
+on every property — nested objects and array items included,
 because a caller composing an array element is reading that element's fields,
 not the parent's prose. `api()` enforces the enforceability half for free since
 [#340](https://github.com/zackbart/connecta/issues/340): a schema the validator
@@ -165,10 +171,12 @@ argument retries.
 ### H7 — Schemas fit the compact renderer, or selection does not depend on the part that is cut
 
 Keep the common path's compact input and output shapes inside 1,024 bytes and
-each enum node inside 256. Where a legitimate enum genuinely cannot fit — 21
-DNS record types — the truncation is acceptable only if the tool's name and
-description already carry enough for selection, so the caller expands the
-schema to *call*, not to *choose*.
+each enum or constraint annotation inside 256. Numeric and string constraints
+render when they fit. Search drops complete constraints that do not fit and
+sets the existing truncation flag; compact describe keeps them. Where a
+legitimate enum genuinely cannot fit — 21 DNS record types — the truncation is
+acceptable only if the tool's name and description already carry enough for
+selection, so the caller expands the schema to *call*, not to *choose*.
 
 *Why:* a truncated compact shape costs a describe round trip. *Cost:* discovery
 tokens.
@@ -561,6 +569,11 @@ One credential per provider comes from the environment —
 `CONNECTA_DRIFT_LINEAR_KEY`, `CONNECTA_DRIFT_STRIPE_KEY`,
 `CONNECTA_DRIFT_MIXPANEL_KEY` — and a missing or dead one stops the run with a
 message naming it rather than reporting an empty catalog as mass removal.
+Linear and bare Stripe values use their documented bearer or Basic framing.
+Mixpanel's beta service-account form is provider-specific:
+`user:secret` becomes `Bearer Basic <base64(user:secret)>`, exactly as its MCP
+documentation requires. A value that already includes whitespace is treated
+as a complete Authorization value and passes through unchanged.
 
 **Touched endpoints.** A hand-written provider is written against a published
 OpenAPI document and calls a few dozen of its operations, so

package/documentation/stripe.md

@@ -1,71 +1,63 @@
 # Stripe prebuilt connection
 
 Import `stripe()` independently from `@zackbart/connecta/providers/stripe`. It
-wraps [Stripe's hosted MCP server](https://docs.stripe.com/mcp) with a required
-production/sandbox mode, OAuth by default, a mode-scaled admission policy, a
+wraps [Stripe's hosted MCP server](https://docs.stripe.com/mcp) with OAuth by
+default, account-scoped mode guidance, a conservative admission policy, a
 task-oriented usage guide, and a vetted safety classification. It adds no
 provider dependency and is not reachable from Connecta's root entry.
 
 ```ts
 import { stripe } from "@zackbart/connecta/providers/stripe";
 
-const billing = stripe("stripe_live", {
-  mode: "production",
-  title: "Stripe (production)",
-  purpose: "Revenue, disputes, and refunds for the real business",
+const billing = stripe("stripe", {
+  purpose: "Revenue, disputes, and refunds across our Stripe organization",
   instructions: "Never refund above $500 without a human in the loop.",
 });
 ```
 
-The `id` owns the ordinary connector namespaces; use a different id for every
-Stripe account. `purpose` is required because an agent choosing between two
-instances needs to know which account answers the question. Account
+The `id` owns the ordinary connector namespaces. Choose a connector boundary
+for its credential or OAuth session and business purpose — not automatically
+for each Stripe account. One OAuth session may cover live and sandbox accounts
+in the same Stripe organization. Use separate connectors when the credential
+or business purpose differs.
+
+`purpose` is required because it tells an agent where the deployment intends
+to route a question. The connector id, title, and purpose are configuration,
+not proof of which account the authenticated Stripe session will use. Account
 `instructions` are appended to the maintained guide and cannot change the
 connector's safety classification.
 
-## Mode is required, and it is the whole point
+## OAuth mode belongs to the selected account
 
-`mode` accepts `"production"` or `"sandbox"` and has **no default**. There is no
-safe guess between an account that moves real money and one that does not, so
-the deployment has to say which it configured.
+Do not pass `mode` for OAuth. Stripe's `list_available_accounts_or_orgs` returns
+each available account with its `stripe_context` and `livemode`. The same OAuth
+session can return both `livemode: true` and `livemode: false` results.
 
-Stripe publishes exactly one endpoint — `https://mcp.stripe.com/` — and the
-environment is selected by the credential, not the URL. Connecta therefore
-cannot *route* by mode; what it can do is make the mode impossible for an agent
-to miss, and refuse a deployment whose declaration and credential disagree.
+The served guide tells agents to call that tool before each account-scoped
+operation. They select the intended result and carry its exact `stripe_context`
+and `livemode` unchanged. Connector id, title, purpose, and OAuth identity are
+routing hints. They never prove the account or mode. Ambiguity stops the call.
 
-`mode` shows up in four places an agent actually reads:
+OAuth metadata therefore stays neutral:
 
-- the default `title` (`Stripe (production)` / `Stripe (sandbox)`);
-- the `description`, which is what `search_tools` ranks and returns — production
-  reads `Stripe payments (production — live money and real customers) — …`,
-  sandbox reads `Stripe payments (sandbox — test data, no real money) — …`;
-- the first two lines of the usage guide, which state the mode and then say
-  either "every write moves real money … a refund cannot be undone" or "never
-  answer a question about live revenue, payouts, or a named customer from this
-  connector";
-- the admission policy, below.
+- the default title is `Stripe`;
+- the description says `live and sandbox accounts`;
+- the guide warns that live writes move real money and sandbox writes change
+  test data;
+- admission uses the stricter sandbox ceiling, because Connecta cannot select
+  a different connector policy after the account-scoped call begins.
 
-And one place a deployment author reads: if `auth` is a `headers` credential
-carrying a recognizable Stripe key prefix (`sk_`, `rk_`, or `pk_` with `_live_`
-or `_test_`), construction throws when the key's mode contradicts the declared
-one. That check reads nothing it cannot classify — an OAuth connector, or a
-credential shape this release does not recognize, is left alone rather than
-guessed at — and the error names only the two modes, never the key.
+`mode` remains required for `headers` auth. A restricted key has one fixed live
+or sandbox scope. Its title, description, guide, and admission policy keep the
+fixed-mode behavior. Construction still throws when a recognizable key prefix
+contradicts its declared mode.
 
-Deploy both side by side. Two instances are isolated exactly like two
-hand-written connectors with different ids: separate addresses, catalogs,
-credentials, storage, admission counters, and health.
+For OAuth, deploy one connector for the session:
 
 ```ts
 connectors: [
-  stripe("stripe_live", {
-    mode: "production",
-    purpose: "Revenue, disputes, and refunds for the real business",
-  }),
-  stripe("stripe_sandbox", {
-    mode: "sandbox",
-    purpose: "Rehearsing billing changes before they touch production",
+  stripe("stripe", {
+    purpose: "Live and sandbox billing for our Stripe organization",
   }),
 ]
 ```
@@ -74,7 +66,17 @@ connectors: [
 
 OAuth is the default and the option Stripe recommends: it supports dynamic
 client registration and PKCE, and each connector instance keeps its own flow
-and tokens in connector-scoped storage. Stripe also accepts a
+and tokens in connector-scoped storage. Stripe's current
+[session-management documentation](https://docs.stripe.com/mcp#manage-mcp-client-sessions)
+says one OAuth session can be tied to more than one account in the same Stripe
+organization. It does not say every session has multiple accounts.
+
+That scope changes what an agent must prove before an account-scoped call. It
+calls `list_available_accounts_or_orgs`, resolves the intended result, and
+carries its exact `stripe_context` and `livemode`. If more than one account
+fits, the agent stops and asks.
+
+Stripe also accepts a
 [restricted API key](https://docs.stripe.com/keys#create-restricted-api-key) as
 a bearer token for headless agents:
 
@@ -93,9 +95,12 @@ Use a restricted key, not a secret key, and scope it to the operations the
 agent actually needs; Stripe's own guidance is to "limit your agent's access to
 exactly the functionality it requires". Keep it in the runtime's secret store.
 
-Connect platforms can act as a connected account with `connectedAccount`, which
-adds Stripe's `Stripe-Account` header. Stripe does not support OAuth for
-connected-account calls, so this requires `headers` auth and throws otherwise:
+Organization accounts in one OAuth session are not Stripe Connect connected
+accounts. Connect platforms can act as a connected account with
+`connectedAccount`, which adds Stripe's documented `Stripe-Account` header at
+connector construction. Stripe does not support OAuth for connected-account
+calls, so this requires a restricted key through `headers` auth and throws
+otherwise:
 
 ```ts
 stripe("merchant_42", {
@@ -109,8 +114,7 @@ stripe("merchant_42", {
 });
 ```
 
-Administrators must enable MCP access in the Stripe Dashboard, and Stripe
-manages that setting **separately for sandbox and live mode**. A connector that
+Administrators must enable MCP access in the Stripe Dashboard. A connector that
 boots but cannot list tools is usually a dashboard toggle, not a bad key.
 
 ## The eleven tools, and what they are classified as
@@ -158,7 +162,7 @@ serves, an unclassified and unannotated `create_customer` lands on the approval
 path. Expect the undocumented Treasury tools Stripe alludes to to arrive
 unclassified as well — annotated ones will be taken at their word.
 
-The upshot is that this account's tool list is not a fixed set, and the usage
+The upshot is that this connection's tool list is not a fixed set, and the usage
 guide tells the agent so: search this connector for what it actually exposes
 rather than assuming a documented tool is present. The guide also names the id
 discipline the downstream schemas cannot enforce — Stripe ids are typed
@@ -166,6 +170,13 @@ prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), a plausible-looking one
 belongs to a different object or to nobody, and the id a write takes comes from
 `stripe_api_search` or a list read rather than from a guess.
 
+Account selection comes before that object-id rule. The served guide names
+`list_available_accounts_or_orgs`, `stripe_context`, and `livemode`, and tells
+the agent to stop when the account, mode, or selector is ambiguous. It keeps
+organization-account selection separate from the restricted-key-only Connect
+path, so an agent cannot repair uncertainty by fabricating `Stripe-Account` as
+a tool argument.
+
 Stripe publishes no stability or deprecation policy for this tool set and
 invites tool requests by email, so treat the list as unversioned. `get_balance_summary`
 is Treasury, which Stripe labels public preview and gates behind an access
@@ -179,9 +190,10 @@ Stripe documents no rate limit specific to the MCP server. The connection
 therefore transcribes the account limit that MCP traffic spends
 ([rate limits](https://docs.stripe.com/rate-limits)): **100 requests per second
 in live mode, 25 in a sandbox**, and any single endpoint is capped at 25 per
-second regardless of mode, so paging one list is the real constraint. The
-`maxConcurrency` beside it — 8 for
-production, 4 for sandbox — is Connecta's own conservative choice: Stripe
+second regardless of mode. OAuth uses 25 calls per second and concurrency 4,
+the safe bound for a session that can reach either mode. Fixed live credentials
+use 100 calls per second and concurrency 8. Fixed sandbox credentials use 25
+and concurrency 4. Stripe
 documents that per-account and per-endpoint concurrency limits exist, and
 surface as `429` with a `Stripe-Rate-Limited-Reason` of `global-concurrency` or
 `endpoint-concurrency`, but publishes no number.
@@ -195,14 +207,9 @@ admission and still needs restrained use.
 
 ## What is not verified
 
-Stripe's MCP documentation is silent on two things this connection had to reason
+Stripe's MCP documentation is silent on one thing this connection had to reason
 about rather than read:
 
-- **How an OAuth session resolves to live versus sandbox at call time.** Stripe
-  says sessions are "scoped to … the current environment (live mode or a
-  sandbox)" and that dashboard access is managed separately per environment, but
-  never states the mechanism. The key-prefix check covers `headers` auth only;
-  for OAuth, `mode` is a declaration Connecta surfaces and cannot verify.
 - **Whether pagination cursors and `Idempotency-Key` are passable through
   `stripe_api_read` / `stripe_api_write`.** The conventions in the usage guide
   are Stripe's documented API conventions; how they thread through the generic

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.16.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 |
+| **B** | 0.16.0 – 0.18.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.16.1
+npm pkg set dependencies.@zackbart/connecta=0.18.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.16.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.18.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.16.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.18.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,48 @@ 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.17.0 → 0.18.0
+
+One floor moves and one always-loaded surface shrinks; neither changes a
+deployment's configuration.
+
+**Node 22 is the minimum supported release.** The published engine range and
+the Node template both declare `>=22.0.0`, matching the template's
+`node:22-slim` image. A Docker deployment already runs Node 22; a bare-metal
+deployment on Node 20 must upgrade its runtime before taking this version.
+Worker deployments are unaffected (#422).
+
+**Model-facing guidance is split by load cost.** MCP instructions and tool
+definitions now carry route selection, the fail-closed boundary, and minimum
+guest syntax. Detailed selection, repair, runtime, and example guidance moved
+to the existing `skills({ name: "usage" })` response. Clients that never fetch
+the skill keep the same routes and need no deployment change; clients that
+cache tool definitions should refresh them after upgrading (#418).
+
+### 0.16.1 → 0.17.0
+
+Two construction rules need a deployment check.
+
+**A Dynamic Worker executor is loader-only.** The supported construction is
+exactly:
+
+```ts
+new DynamicWorkerExecutor({ loader: env.LOADER })
+```
+
+Remove `bindings`, `modules`, or `globalOutbound` from that options object.
+Those fields grant guest code ambient configuration, code, or egress. This is
+the supported sandbox boundary rather than a new Connecta-side inspection of
+the third-party executor object. The shipped Worker example was already
+loader-only, and Node deployments use `quickJsExecutor()`, so neither needs a
+change (#390).
+
+**An explicit guide summary must fit discovery.** Connecta normalizes
+whitespace in `usageGuide.summary` and refuses registry construction when the
+result is longer than 120 characters. Shorten it to 120 characters or fewer,
+or omit it and let Connecta derive a bounded summary from the guide's opening
+prose. A blank explicit summary still takes the derived-summary path (#392).
+
 ### 0.16.0 → 0.16.1
 
 Nothing throws, and a Node deployment crosses this on the version bump alone.