@zackbart/connecta 0.17.0 → 0.18.1

package/documentation/operations.md

@@ -183,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
@@ -225,23 +225,23 @@ in.
 | `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 including compact page bounds, 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 |
+| `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, authenticated thrown-failure framing, 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 shared guest contract on the Dynamic Worker, including caught call, 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 |
+| `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 with numeric and string constraints, structured errors, `skills` and connector-guide selection including paragraph-aware summaries and configured-summary construction bounds, stored-credential drift, catalog-lookup health accounting, `fields` selection including total and partial misses below nested arrays, truncation and `get_result` offset validation and character alignment, per-connector `maxResultBytes`, probe timeouts, and empty-query browse of an unavailable or unconfigured catalog |
+| `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 tool surface, request construction, lean projections, both pagination conventions, error mapping, and writes; then the connector in 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), 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) |
@@ -249,10 +249,11 @@ in.
 | `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, an end-to-end code-mode run, and `waitUntil` reaching agent catalog reads through both `search_tools` and `execute_code` |
+| `revenuecat-provider.test.ts` / `revenuecat-registry.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`; then two project-scoped keys as two connectors in a real deployment |
+| `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, admission, multi-account OAuth guidance, and no-guess account selection; then the connector in a real deployment |
+| `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 |
 
@@ -263,12 +264,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 with a loader-only sandbox, 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 — 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, its exact absent globals, and blocked runtime imports | 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 |

package/documentation/provider-audit.md

@@ -1,7 +1,7 @@
 # Provider audit
 
 [`provider-conventions.md`](./provider-conventions.md) wrote the bar down. This
-document runs it against the five maintained prebuilt connections and returns a
+document runs it against the six maintained prebuilt connections and returns a
 verdict for every applicable convention: **meets**, **misses** (with the fix),
 or **n/a** (with the reason). A convention is never quietly skipped, and an
 accepted miss is recorded as a provider-specific exception with its argument
@@ -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 |
@@ -105,16 +113,16 @@ deliberate surface.
 | --- | --- | --- |
 | P1 add, never rewrite | meets | annotations only |
 | 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 | 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 |
+| 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 one belongs to a different object or to nobody, and the read tools that produce a real one. The guide now also accounts for OAuth sessions tied to several organization accounts: connector metadata is not identity proof, the exact selector must come from the live tool schema, and an ambiguous target or selection mechanism stops rather than becoming a guessed argument or header ([#404](https://github.com/zackbart/connecta/issues/404)) |
+| 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
@@ -139,6 +147,28 @@ Linear's reasoning.
 | P12 admission budget | **missed → fixed** | the connection hardcoded a 600-call hourly budget transcribed from a limit Mixpanel meters **per user**. P12 names this case exactly: a per-runtime counter cannot approximate a per-user quota in either direction — one runtime serving several users under-counts, several isolates sharing one credential each admit a full budget. The default is removed; `callAdmission` is now an operator option with a documented example, matching Linear |
 | 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)) |
 
+## RevenueCat — hosted-MCP proxy
+
+Written after the conventions existed, so it has no misses to record — only two
+places where the honest answer departs from the obvious one, both argued below.
+Ninety-five documented tools, ninety-four classified, one deliberately not.
+
+| Convention | Verdict | Notes |
+| --- | --- | --- |
+| P1 add, never rewrite | meets | `listTools` maps annotations and returns every other field untouched |
+| P2 identity | meets | required `purpose` (blank throws), `instructions` appended under `## Project instructions`, and appended text cannot reach the classification |
+| P3 routing fact | meets, with the fact split in two | the routing fact is scope, and it has two halves. The *shape* — one project versus every project the account can reach — is knowable at construction and rides the default title (`RevenueCat (single project)` versus `RevenueCat`). *Which* project a key opens is not knowable without calling something, which P10 forbids, so it rides the guide's first line and the declared summary, built from the operator's `purpose`. That makes this the one maintained proxy with a purpose-bearing summary rather than a static one, and the reason is P3's own cost: two `sk_` connectors share a title, an endpoint, and a catalog, so a static summary would leave them indistinguishable in the only field search returns |
+| P4 endpoint default | n/a — one endpoint, and the scope rides the credential | RevenueCat publishes a single MCP endpoint, so there is nothing to select between. The scope difference comes from the credential shape itself, which the constructor reads rather than asks for: `auth.type === "headers"` *is* the single-project declaration. There is no mode to default and no mode to contradict, so the P4 machinery Stripe needs has nothing to do here |
+| P5 classification | meets | 50 reads, 15 additive writes, 29 destructive writes named; `render-paywall-screenshot` is on neither list because RevenueCat's reference gives it no access column, and it fails closed. Nine borderline verdicts are argued beside the rows they decide, and asserted in the suite so a silent flip fails |
+| P6 catalog varies | meets | the guide names paywall AI editing, benchmarks, experiments, virtual currencies, and account billing as the plan-, platform-, and beta-gated areas where absence is expected, and separately names the unclassified tool so its approval prompt does not read as a bug |
+| P7 reduction advice | meets | structured guide, declared summary, cursor-then-reduce advice aimed at the two objects that are actually large here (customers and their event history). `required` stays unset: the project-resolution sequence is worth reading before a run, not before every call |
+| P8 identity resolution | meets | the guide names the whole chain — `list-projects` for the `project_id` every project-scoped call takes, then `list-apps`, `list-products`, `list-entitlements`, `list-offerings`, `list-paywalls`, `list-audiences`, and `list-customers` for the ids their `get-`, `update-`, `archive-`, and `delete-` counterparts expect — and says a plausible-looking id belongs to another project or to nobody. For OAuth it also says to stop and ask when more than one project fits |
+| P9 authentication | meets | OAuth default, `requireHttps`, the API v2 secret key documented as a secret and paired with the narrowest scope RevenueCat offers (one project). The guide names the `auth_required` → `authorize_connector` route, and separately says that a read-only key's refusal is RevenueCat's own words rather than an authorization gap connecta can repair |
+| P10 no credential test | meets | no `credential`, `testCredential`, or `testCredentials`. This is also where the constructor's most tempting option was refused: a `project?: string` checked against `list-projects` at construction is a credential test wearing a configuration hat, so the operator's stated purpose carries the claim and the agent confirms it on first use. There is no recognizable-credential contradiction to throw on either — an `sk_` key encodes no project — so the construction-time half of P10 has nothing to check here, exactly as it has nothing to check for Mixpanel's region |
+| P11 transport vs tool error | meets | inherited whole from `remoteMcp()`; the wrapper adds no error handling and reads no downstream prose. The guide says a rejected argument, a permission gap, and a plan restriction all arrive in RevenueCat's own words |
+| P12 admission budget | meets, by declining a number that exists | RevenueCat does publish limits, which is why this row needed an argument rather than a shrug. It meters per domain — 480/min for customer information, virtual currencies, and refunds; 60 for project configuration and audiences; 25 for charts and metrics — and a `ConnectorCallAdmissionPolicy` carries exactly one rule. Picking 25 throttles a customer read loop to a nineteenth of its allowance; picking 480 leaves a chart sweep unprotected; neither is the provider's limit. The metering scope repeats the point: developer-level keys are metered per developer, which a per-runtime counter cannot approximate. So the guide states RevenueCat's own numbers and the `429` / `Retry-After` / `backoff_ms` signals, and `callAdmission` stays an operator option with a documented example |
+| P13 drift visible | meets | both lists are module-level constants in one file and *are* the manifest the wrapper classifies from, compared against the live catalog on every refresh ([#343](https://github.com/zackbart/connecta/issues/343)). The maintainer-run check accepts `revenuecat` with `CONNECTA_DRIFT_REVENUECAT_KEY`. No schema digests are recorded, and the manifest says so rather than shipping invented ones |
+
 ## Scoreboard
 
 | Provider | Meets | Missed and fixed | Recorded exception | Open |
@@ -148,8 +178,9 @@ Linear's reasoning.
 | Linear | 11 | 2 | P4 departs from the letter | — |
 | Stripe | 10 | 3 | — | — |
 | Mixpanel | 7 | 5 | P10 half n/a | — |
+| RevenueCat | 12 | 0 | P4 n/a (one endpoint); P3 met with a purpose-bearing summary | — |
 
-Nineteen misses, nineteen fixes, four recorded exceptions, one judgment left to
+Nineteen misses, nineteen fixes, six recorded exceptions, one judgment left to
 the issue that owns it. The pattern in the misses is worth naming: sixteen of
 the nineteen are a guide, a title, or a schema description failing to *say*
 something the implementation already did correctly. Only three changed what a
@@ -158,3 +189,10 @@ access declaration, Mixpanel dropping a budget it could not honestly compute.
 The conventions are mostly not asking for different behavior. They are asking
 for the behavior to reach the agent, which is a different problem and, on this
 evidence, the one the providers were losing.
+
+RevenueCat is the first connection written *after* the conventions and adds no
+misses to those nineteen, which is the least interesting thing about its row.
+The interesting part is that two conventions came out somewhere other than
+their obvious reading — P4 has no endpoint to select and P12 declines a number
+the provider actually publishes — and both had to be argued rather than
+skipped. A convention that only ever returns "meets" is not being applied.

package/documentation/provider-conventions.md

@@ -1,6 +1,6 @@
 # Provider conventions
 
-The five maintained prebuilt connections grew one at a time, and until now
+The six maintained prebuilt connections grew one at a time, and until now
 "excellent provider" meant whatever the last author thought. This document
 writes the judgment down so it can be argued with, audited, and reused.
 
@@ -11,7 +11,7 @@ cannot honestly cover both:
   tool name, schema, projection, and error. Today: Cloudflare, Notion.
 - **Hosted-MCP proxies** — `remoteMcp()` wrappers around a server somebody else
   operates, where the names, schemas, results, and error prose arrive as they
-  are. Today: Linear, Stripe, Mixpanel.
+  are. Today: Linear, Stripe, Mixpanel, RevenueCat.
 
 The governing principle for every convention below is the same: **keep the
 model that interacts with connecta as efficient as possible.** A convention
@@ -386,11 +386,18 @@ complete spends calls proving it is not. *Cost:* wrong-tool selection.
 
 A proxy cannot project a downstream result, so the guide tells the agent to
 page with the cursor rather than raising the page size, and to reduce inside
-`execute_code` before returning anything. Structured form, explicit `summary`,
-`required: true` only for a genuine cross-tool sequence or a generic wrapper.
-
-*Why:* the only projection available is the one the program writes. *Cost:*
-result size.
+`execute_code` before returning anything — and, where a value's rendering is
+the provider's rule rather than the schema's, what that value means: Mixpanel
+renders an absent boolean property as `false` in a breakdown, so the guide
+says to confirm presence before reading `false` as a signal
+([#430](https://github.com/zackbart/connecta/issues/430)). Structured form,
+explicit `summary`, `required: true` only for a genuine cross-tool sequence or
+a generic wrapper.
+
+*Why:* the only projection available is the one the program writes, and a
+value the schema types correctly can still mislead without the provider's
+rendering rule beside it — the agent then re-queries to explain a signal that
+was never there. *Cost:* result size.
 
 ### P8 — Identity resolution comes before action
 
@@ -494,8 +501,8 @@ is the shape that does not become it.
 **What a manifest holds.** Every tool name a release reviewed, the verdict it
 reviewed it as (`read-only`, `additive`, `destructive`), and — where a release
 actually read them — a digest of that tool's input and output schemas. Today
-the three proxies ship names and verdicts and no digests, because no release
-has read a live schema and written it down, and an invented digest reports a
+three of the four proxies ship names and verdicts and no digests, because no
+release has read a live schema and written it down, and an invented digest reports a
 change that never happened. `npm run drift:check -- --record` reads them from a
 live catalog and prints the block a release pastes in; until a release does,
 a manifest without digests counts no schema changes, which is the honest answer
@@ -567,9 +574,10 @@ compares its own totals against `detectCatalogDrift()`: two readings of one
 manifest that disagree mean one of them is lying, which is worth failing over.
 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.
+`CONNECTA_DRIFT_MIXPANEL_KEY`, `CONNECTA_DRIFT_REVENUECAT_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, bare Stripe, and RevenueCat `sk_` 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
@@ -623,11 +631,11 @@ evidence and nothing else: no tool is generated from one, which is the
 ## What the audit checks
 
 The provider audit ([#342](https://github.com/zackbart/connecta/issues/342))
-runs this document against each of the five providers and returns a verdict per
+runs this document against each of the six providers and returns a verdict per
 convention: **meets**, **misses** (with the fix), or **not applicable** (with
 the reason). A convention is never quietly skipped, and an accepted miss is
 recorded as a provider-specific exception with its argument, not left blank.
-Its five reports live in [provider-audit.md](./provider-audit.md), and the
+Its six reports live in [provider-audit.md](./provider-audit.md), and the
 mechanically checkable half of the hand-written bar runs on every test run in
 [`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts) —
 so a convention that was met once stays met, or fails loudly.
@@ -675,6 +683,7 @@ their place, so they are this audit's work, not a second removal argument.
 
 Each provider's own guide ([Cloudflare](./cloudflare.md),
 [Linear](./linear.md), [Mixpanel](./mixpanel.md), [Notion](./notion.md),
-[Stripe](./stripe.md)) is part of the audited surface: documentation moves with
+[RevenueCat](./revenuecat.md), [Stripe](./stripe.md)) is part of the audited
+surface: documentation moves with
 the work, and a guide describing a surface that shipped differently is itself a
 miss.

package/documentation/revenuecat.md

@@ -0,0 +1,279 @@
+# RevenueCat prebuilt connection
+
+Import `revenuecat()` independently from
+`@zackbart/connecta/providers/revenuecat`. It wraps
+[RevenueCat's hosted MCP server](https://www.revenuecat.com/docs/tools/mcp/setup)
+with OAuth by default, project-scoping guidance that differs by credential
+shape, 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 { revenuecat } from "@zackbart/connecta/providers/revenuecat";
+
+const subscriptions = revenuecat("revenuecat", {
+  purpose: "Subscription state, entitlements, and revenue across our projects",
+  instructions: "Never grant a promotional entitlement without a support ticket.",
+});
+```
+
+The endpoint is `https://mcp.revenuecat.ai/mcp` over streamable HTTP.
+
+`purpose` is required, and it does more work here than in any other maintained
+connection. RevenueCat's own tools do not report which project a static key
+reaches until you call one, and Connecta runs no credential test at construction
+(P10), so `purpose` is the only place the deployment's intent is written down.
+It opens the guide and it *is* the guide summary, which is the field search
+returns. Project `instructions` are appended to the maintained guide and cannot
+change the connector's safety classification.
+
+## The scoping fact this connection exists to get right
+
+RevenueCat has two credential shapes with two different scopes, and the guide
+you get depends on which one you configured.
+
+**A secret API key is project-wide.** RevenueCat's own words:
+"Secret API keys are project-wide and can be created and revoked by project
+Admins" ([authentication](https://www.revenuecat.com/docs/projects/authentication)).
+`list-projects` "lists all RevenueCat projects accessible with the provided API
+key" — with an `sk_` key that is exactly one project. So a `headers`-auth
+connector reaches one project and nothing outside it. Its title is
+`RevenueCat (single project)` and its guide opens by naming the project the
+operator said the key is for.
+
+**OAuth is account-scoped.** One session reaches every project the account can
+see, and each project-scoped tool takes a `project_id`. Its title is
+`RevenueCat` and its guide opens with the resolution discipline: call
+`list-projects` first, carry the exact `project_id` it returned into every
+project-scoped call, and stop and ask when more than one project fits.
+Connecta does not pick a project, and the connector id, title, and purpose are
+routing hints rather than proof of where a call will land.
+
+The constructor deliberately has no `project` option. Declaring a project that
+Connecta then checked against `list-projects` at construction would be a
+credential test, which P10 forbids — a proxy makes no unasked-for downstream
+call. The operator's stated purpose carries the claim; the agent confirms it
+with `list-projects` on first use.
+
+## Several projects
+
+One key, one project, one connector. A deployment that needs two projects
+declares two connectors, each with its own key and its own id:
+
+```ts
+import { revenuecat } from "@zackbart/connecta/providers/revenuecat";
+
+connectors: [
+  revenuecat("bepresent_ios", {
+    purpose: "Subscription state for the BePresent iOS project",
+    auth: {
+      type: "headers",
+      headers: { Authorization: `Bearer ${env.REVENUECAT_BEPRESENT_KEY}` },
+    },
+  }),
+  revenuecat("biblescroll", {
+    purpose: "Subscription state for the BibleScroll project",
+    auth: {
+      type: "headers",
+      headers: { Authorization: `Bearer ${env.REVENUECAT_BIBLESCROLL_KEY}` },
+    },
+  }),
+]
+```
+
+That is config-as-code doing what an account model would otherwise do: one
+credential per connector, each with its own catalog, storage namespace, health,
+and admission counters. The two share a title, because Connecta cannot know
+which project a key opens — so the guide summary is what tells them apart, and
+it is built from `purpose`. Write a purpose that names the project, not one
+that names RevenueCat.
+
+If the deployment genuinely needs to move between projects in one session, use
+OAuth instead and let the agent resolve `project_id`. Do not point a
+project-scoped key's `project_id` argument at a project it cannot reach; the
+call fails at RevenueCat, which is the correct outcome but a wasted round trip.
+
+## Authentication
+
+OAuth is the default and the option RevenueCat recommends: "OAuth provides a
+seamless authentication experience: log in to your RevenueCat account and grant
+access to the MCP server, with no API keys to manage." Each connector instance
+keeps its own flow and tokens in connector-scoped storage.
+
+RevenueCat also accepts an API v2 secret key as a bearer token for headless
+agents:
+
+```ts
+revenuecat("bepresent_ios", {
+  purpose: "Subscription state for the BePresent iOS project",
+  auth: {
+    type: "headers",
+    headers: { Authorization: `Bearer ${env.REVENUECAT_KEY}` },
+  },
+});
+```
+
+Keys are prefixed `sk_`, are issued read-only or write-enabled, and can be
+revoked at any time by a project Admin. RevenueCat's setup guidance is to "use
+a write-enabled key if you plan to create/modify resources"; "a read-only key
+works if you only need to view data". Keep the key in the runtime's secret
+store, never in the deployment file.
+
+**Connecta does not filter writes for a read-only key.** It has no way to tell
+which kind a key is without spending a call, so every write in the catalog is
+offered, reaches RevenueCat, and fails there in RevenueCat's own words. The
+guide says so, so an agent reads that refusal as "this key cannot write" rather
+than as a bad argument and repairs it by routing to a write-enabled connector
+instead of retrying.
+
+An expired or revoked credential surfaces as `auth_required`, and the guide
+names the `authorize_connector` recovery. A permission gap, a plan restriction,
+or a rejected argument arrives as RevenueCat wrote it and is not an
+authorization problem.
+
+## The ninety-five tools, and what they are classified as
+
+RevenueCat's
+[tool reference](https://www.revenuecat.com/docs/tools/mcp/tools-reference),
+read on **2026-08-18**, documents ninety-five tools in a Read/Write table.
+Ninety-four carry an access column and are classified here: **50 read-only, 15
+additive writes, 29 destructive writes.**
+
+Reads are every `Read` row, verbatim — the nine project and app reads, the four
+product reads, the entitlement, offering, targeting, paywall, customer, virtual
+currency, chart, webhook, and SDK reads, and `get-paywall-ai-task`.
+
+Writes follow the verb where the verb is honest: `archive-*` and `unarchive-*`
+flip an existing object's active state, `update-*`, `delete-*`, `publish-*`,
+`unpublish-*`, and `detach-*` change or remove something that already exists,
+and a plain `create-*` brings a new object into being beside the old ones.
+`set-product-store-state` is an upsert and `submit-products-to-store` sends
+products to Apple for review, so both are destructive.
+`assign-customer-offering` and `grant-customer-entitlement` change a real
+customer's access, so both are destructive too.
+
+Nine verdicts are not decided by the verb, and each is argued in the source
+beside the row:
+
+| Tool | Verdict | Why |
+| --- | --- | --- |
+| `create-product-prices` | destructive | named `create-`, described "Configure prices for a product". The price set already exists and configuring it replaces what is there. Money-facing and overwriting |
+| `equalize-subscription-prices` | additive | "Fills **missing** App Store subscription territory prices" — by RevenueCat's own word it writes only where nothing is set |
+| `validate-app-credentials` | additive | RevenueCat files it `Write`, so it does not reach the read path, but it leaves the saved credentials alone and only records the outcome of a check |
+| `upload-product-store-state-screenshot` | additive | "Reserves an App Store Connect review screenshot slot" — a new slot appears; nothing existing is replaced |
+| `attach-products-to-entitlement` | additive | attach adds membership and removes nothing; `detach-products-from-entitlement` is the destructive half. Filing both destructive would make the pair read identically in the approval copy a human sees |
+| `attach-products-to-package` | additive | the same argument one level down |
+| `duplicate-paywall` | additive | "Duplicates an existing paywall's current draft" — the original is untouched |
+| `create-paywall-ai` | additive | starts an async task that creates a paywall; every existing one is left alone |
+| `edit-paywall-ai` | destructive | starts an async task that rewrites a draft that already exists |
+
+`create-webhook-integration` deserves a sentence too. No existing integration
+changes, so the verb reads additive — but with filters omitted the new one
+"starts delivering" every customer event in the project to a URL the caller
+typed. Customer data leaving the account is the `create_refund` argument again:
+filed destructive on consequence, so the approval copy says what is at stake.
+
+**`render-paywall-screenshot` is deliberately unclassified.** RevenueCat's
+reference gives it no access column at all, so no release has reviewed what it
+does. It fails closed onto `call_destructive_tool` rather than being guessed
+into the read path because its name sounds harmless (P5). The guide names it,
+so an agent does not read the approval prompt as a bug.
+
+That classification fills in downstream silence and otherwise preserves explicit
+annotations. A tool on the read allowlist arriving with `destructiveHint: true`
+or `readOnlyHint: false` keeps exactly what the downstream said and stays behind
+`call_destructive_tool`. A tool on neither maintained list arriving with
+`readOnlyHint: true` keeps that too. Both are the downstream telling you this
+release's allowlist is stale. The one fail-closed exception applies to a name
+this release reviewed and filed destructive: a `grant-customer-entitlement`
+claiming `readOnlyHint: true` is a downstream bug rather than news, and stays on
+the approval path.
+
+The tool list is not a fixed set, and the guide says so. RevenueCat gates parts
+of its catalog by plan, platform, and beta enrollment — paywall AI editing,
+benchmarks, experiments, virtual currencies, and the account-billing tools are
+the usual absentees — so search this connector for what it actually exposes
+rather than assuming a documented tool is here.
+
+**No schema digests are recorded.** No release has read RevenueCat's live
+schemas and written them down; that needs a live project and a maintainer's own
+key. The manifest therefore ships names and verdicts only, and the drift check
+honestly counts zero schema changes rather than reporting an invented one.
+`npm run drift:check -- --record` reads them from a live catalog and prints the
+block a release pastes in
+([#351](https://github.com/zackbart/connecta/issues/351)).
+
+## Rate limits
+
+RevenueCat documents numbers, and this connection still declares no budget.
+
+API v2 meters per minute and **per domain**
+([rate limits](https://www.revenuecat.com/docs/api-v2#tag/Rate-Limit), read
+2026-08-18):
+
+| Domain | Requests per minute |
+| --- | --- |
+| Customer Information | 480 |
+| Virtual Currencies | 480 |
+| Subscription Transactions Refunds | 480 |
+| Audiences | 60 |
+| Project Configuration | 60 |
+| Charts & Metrics | 25 |
+
+A `ConnectorCallAdmissionPolicy` carries exactly one rule, so a connector-wide
+budget has to pick one of those six numbers for all ninety-five tools.
+Transcribing 25 would throttle a customer read loop to a nineteenth of its
+documented allowance; transcribing 480 would leave a chart sweep unprotected.
+Neither is the provider's limit, and both would look like RevenueCat being
+flaky. The metering scope says the same thing again: the limit applies per API
+key for app-level keys and **per developer** for developer-level keys, so an
+OAuth session shares one budget with everything else that developer does, which
+a per-runtime counter cannot approximate in either direction.
+
+So the number stays with the operator who knows the account (P12), and the
+guide states RevenueCat's own limits instead, along with the `429`,
+`Retry-After`, and `backoff_ms` signals to back off on. Supply one like this:
+
+```ts
+revenuecat("revenuecat", {
+  purpose: "Revenue charts and cohort reporting",
+  callAdmission: {
+    rules: [
+      {
+        maxConcurrency: 4,
+        queueTimeoutMs: 5_000,
+        retryAfterMs: 2_000,
+        // The Charts & Metrics ceiling, because this connector is used for
+        // charts. A customer-lookup connector would declare 480.
+        budget: { kind: "rolling-window", maxCalls: 25, windowMs: 60_000 },
+      },
+    ],
+  },
+});
+```
+
+As with every connector policy this is a **best-effort approximation** of the
+provider's limit, not an enforcement of it. Each runtime keeps its own counter,
+so N Worker isolates or Node processes serving one deployment can each admit up
+to the stated rate. Discovery traffic is outside connector call admission and
+still needs restrained use.
+
+## What is not verified
+
+- **Every tool name is transcribed from RevenueCat's published reference on
+  2026-08-18, not read from a live catalog.** No maintainer ran this against a
+  project with a real key before it shipped. A name the reference lists and the
+  server does not serve costs nothing; a tool the server serves and the
+  reference omits fails closed. The maintainer-run drift check with
+  `CONNECTA_DRIFT_REVENUECAT_KEY` set is what turns that into a finding with a
+  name attached.
+- **No input or output schema has been read**, which is why the manifest
+  carries no digests.
+- **Whether `render-paywall-screenshot` mutates anything.** It has no access
+  column, and guessing is exactly what P5 exists to prevent.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention is the RevenueCat section of
+[the provider audit](./provider-audit.md).