@zackbart/connecta 0.18.0 → 0.18.2

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
 
@@ -405,33 +412,49 @@ retries.
 
 OAuth per connector instance, stored in connector-scoped storage, is the
 default. The provider's own headless credential — a personal API key, a
-restricted key, a service account — is supported through explicit `headers`
-auth, documented as a secret rather than configuration, and paired with the
-narrowest mode the deployment can use. `requireHttps` is set. Recovery from an
-expired authorization is the ordinary `auth_required` → `authorize_connector`
-route.
+restricted key, a service account — is supported two ways: explicit `headers`
+auth, documented as a secret rather than configuration, and `{ type:
+"credential" }`, which declares an operator slot and takes the same secret from
+`/credentials` instead. Either way it is paired with the narrowest mode the
+deployment can use, and the framing matches the provider's *published* contract
+for the MCP endpoint — not a convention borrowed from that provider's other
+APIs, and not this repository's earlier example, which is the same claim wearing
+a circle. `requireHttps` is set. Recovery from an expired authorization is the
+ordinary `auth_required` → `authorize_connector` route, which returns the
+consent URL for OAuth and the `/credentials` handoff for a declared slot.
 
 *Why:* one route back from an expired credential is what keeps a failed call
 from becoming an abandoned task. *Cost:* wrong-tool selection.
 
-### P10 — There is no credential test; the equivalent check happens at construction
+### P10 — Nothing probes a credential unasked; a declared slot may be tested on request
 
-A proxy declares no operator credential slot and implements neither
-`testCredential` nor `testCredentials`. `remoteMcp()` has no `credential`
-option, and neither shape of proxy credential is vault-managed: OAuth lives in
+A proxy declares an operator credential slot exactly when its auth is `{ type:
+"credential" }`, and then it inherits H12 whole
+([#439](https://github.com/zackbart/connecta/issues/439)). The other two shapes
+declare no slot and hold nothing for the credentials page: OAuth lives in
 connector-scoped storage and is exercised by the authorization flow itself,
-while a headless key arrives as deployment configuration in `headers`, so there
-is nothing for the operator credentials page to hold or test. H12's guarantee is
-still owed, and a proxy pays it in two other places: construction throws when a
-recognizable credential contradicts the declared mode (P4), and a dead or
-revoked credential fails loudly at use as `auth_required` with the
-`authorize_connector` route attached (P9). Connecta never probes a downstream to
-see whether a credential is still alive — that shape is `removed` in the ethos
-([#179](https://github.com/zackbart/connecta/issues/179)). A provider that later
-does take a vault-managed secret inherits H12 whole.
+while a `headers` key arrives as deployment configuration. H12 is owed in every
+shape, and a proxy pays it in two places that do not depend on a slot:
+construction throws when a recognizable credential contradicts the declared mode
+(P4) — a check a vault-managed key cannot get, because there is nothing in the
+deployment file to read — and a dead, revoked, or absent credential fails loudly
+at use as `auth_required` with the `authorize_connector` route attached (P9).
+
+`testCredential` exists only behind the operator-pressed Test action on
+`/credentials`, and only for a declared slot. It connects with the stored value
+and reports how many tools the downstream served, which is the whole honest
+check for a proxy: which account, project, or mode a key reaches is the
+provider's answer, not Connecta's. That is not the shape
+[#179](https://github.com/zackbart/connecta/issues/179) removed. What was
+removed is the *unasked* probe — a liveness call every deployment pays on a
+schedule or at startup to answer a question only a misconfigured one has. A
+human clicking Test has asked, `api()` has had that button since the vault
+existed, and nothing here probes on its own: no timer, no warmup, no check on
+the read path.
 
 *Why:* an unasked-for liveness probe spends a call on every deployment to answer
-a question only a misconfigured one has. *Cost:* result size.
+a question only a misconfigured one has; a requested one spends a call the
+person requesting it chose. *Cost:* result size.
 
 ### P11 — Connecta classifies the transport; the downstream owns the tool error
 
@@ -494,8 +517,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 +590,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 +647,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.
@@ -658,8 +682,8 @@ than by reading:
 | P4 | endpoint or mode option exists, with the documented default (or no default, where none is safe) |
 | P5 | reads and writes are named lists; an unlisted tool resolves to not-read-only; a reviewed destructive name beats a contradictory `readOnlyHint: true` |
 | P6, P8 | the guide contains the catalog-varies note and the id-resolution rule |
-| P9 | `auth` defaults to OAuth and `requireHttps` is set |
-| P10 | no `credential`, `testCredential`, or `testCredentials` on the wrapper; the mode/key contradiction throws at construction instead |
+| P9 | `auth` defaults to OAuth and `requireHttps` is set; a credential-auth shape frames the key the way the provider's MCP documentation does |
+| P10 | a `credential` slot exactly when auth is `{ type: "credential" }`; `testCredential` runs only from the operator's Test action, never on a timer or a read path; the mode/key contradiction still throws at construction |
 | P11 | an authorization failure surfaces as `auth_required`; a downstream tool error is returned unchanged, with no code chosen from its prose |
 | P12 | a declared budget matches a citable documented limit, or the absence is justified in the guide |
 | P13 | classification lists are maintained in one place per provider and built into the manifest the wrapper classifies from, so the drift check compares against the same fact the caller is served |
@@ -675,6 +699,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,301 @@
+# 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}` },
+    },
+  }),
+]
+```
+
+Neither key has to be a runtime secret. Declare the slot instead and each
+connector's key is pasted, tested, and rotated on `/credentials`:
+
+```ts
+connectors: [
+  revenuecat("bepresent_ios", {
+    purpose: "Subscription state for the BePresent iOS project",
+    auth: { type: "credential", credential: { label: "API v2 secret key" } },
+  }),
+  revenuecat("biblescroll", {
+    purpose: "Subscription state for the BibleScroll project",
+    auth: { type: "credential", credential: { label: "API v2 secret key" } },
+  }),
+]
+```
+
+Two ids, two slots, two single-project catalogs — the `credential` option is
+optional, and omitting it gives the same "API v2 secret key" label. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
+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 — or declare
+`auth: { type: "credential" }` and let the operator hold it in the vault
+instead, which is the shape the two-project example above uses.
+
+**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).

package/documentation/storage-and-credentials.md

@@ -34,6 +34,61 @@ Credential mutation is intentionally narrower than MCP access:
 The vault is read for each call. Once an operator saves a replacement,
 the agent can retry immediately without restarting or redeploying Connecta.
 
+## A remote MCP connector's static credential
+
+`remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
+
+```ts
+remoteMcp("revenuecat_bepresent", {
+  url: "https://mcp.revenuecat.ai/mcp",
+  auth: { type: "credential", credential: { label: "API v2 secret key" } },
+});
+```
+
+The connector, its endpoint, and the credential *slot* stay declared in code;
+only the secret arrives through `/credentials`. That is the same boundary
+`api()` has always had, and the reason a project-wide key no longer has to be a
+Worker secret or an environment variable
+([#439](https://github.com/zackbart/connecta/issues/439)).
+
+`header` defaults to `Authorization` and `scheme` to `Bearer`. `scheme: null`
+sends the stored value verbatim, which is what Linear's personal API keys
+expect. A scheme whose last token is `Basic` declares HTTP Basic credentials, so
+the stored `user:secret` is base64-encoded first — `"Basic"` produces
+`Basic <base64>`, and Mixpanel's documented `"Bearer Basic"` produces
+`Bearer Basic <base64>`. There is one reserved `value` field and no multi-field
+header composition: named `credential.fields` are refused at construction.
+
+A stored value is checked before anything frames it: a line break or other
+control character — what a key pasted across two lines leaves behind — is
+refused as `auth_required` with a message naming the problem and never the
+value. That check exists because the runtime that rejects such a header quotes
+the whole offending value back in its `TypeError`, and that message would
+otherwise reach the agent, the operator page, and the activity log. Behind it,
+any error whose message quotes the credential or the header it became is
+discarded whole and replaced; nothing is masked or truncated, because a
+redaction that keeps part of a secret is still a leak.
+
+An empty slot is not a boot failure and not a silently absent connector. The
+connector is present, its status reads `auth_required`, calls fail with the same
+typed error a missing OAuth grant produces, and `authorize_connector` returns
+the `/credentials` handoff. With no vault configured at all, the failure names
+`credentials.encryptionKey`, and Connecta already warned at startup.
+
+The vault is read before any cached downstream client is trusted, so a rotation
+lands on the next call rather than the next deploy. Connecta compares a SHA-256
+digest of the value the cached client connected with; a different digest closes
+that client and reconnects. The plaintext lives in the connect attempt's local
+scope, never on connector state, never in a log, and never in a status or error
+message. A cleartext `http://` destination warns at construction here exactly as
+it does for literal headers — who owns the secret changed, not what the wire
+carries.
+
+`/credentials`' Test action connects with the stored value and reports how many
+tools the downstream served. That is the whole honest check for a proxy: which
+account, project, or mode the key reaches is the provider's answer, not
+Connecta's.
+
 ## Downstream OAuth
 
 `remoteMcp()` stores dynamic client registration, tokens, PKCE material, state,

package/documentation/stripe.md

@@ -95,12 +95,32 @@ 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.
 
+The same key can come from `/credentials` instead:
+
+```ts
+stripe("stripe_sandbox", {
+  mode: "sandbox",
+  purpose: "Automated billing rehearsal",
+  auth: { type: "credential" },
+});
+```
+
+`mode` is required either way — a static key answers for exactly one
+environment and cannot report which. The literal-header form is checked against
+the key's `_live_`/`_test_` prefix at construction; an operator-managed key is
+not in the deployment file to read, so the declared mode stands alone and a key
+pointed at the other environment fails at Stripe. Declare the mode carefully:
+that check is the one guard Connecta can offer, and this shape does not get it.
+See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 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:
+calls, and `Stripe-Account` is a second header beside the credential's own,
+which the operator-managed shape does not assemble — so this requires a
+restricted key through `headers` auth and throws otherwise:
 
 ```ts
 stripe("merchant_42", {
@@ -177,6 +197,16 @@ 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.
 
+The guide also carries the reduction advice the generic schemas cannot (P7):
+a list or search read that returns full objects belongs inside `execute_code`,
+projected to the fields the question needs before `return`, because an
+unprojected list truncates and a projected one keeps customer PII out of the
+transcript. It names Stripe search's per-resource field set — charges search
+has no `payment_intent` field, so the path is the PaymentIntent's
+`latest_charge` — and the account → search → details → read sequence as one
+program rather than four turns, and it names `outcome`, `failure_code`, and
+`failure_message` on the charge as the answer to "why did this payment fail".
+
 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

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.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 |
+| **B** | 0.16.0 – 0.18.2 | 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.18.0
+npm pkg set dependencies.@zackbart/connecta=0.18.2
 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.18.0 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.18.2 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.18.0 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.18.2 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,33 @@ 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.18.1 → 0.18.2
+
+Nothing throws for an existing deployment, and the version bump alone crosses
+it. The release adds a third `auth` shape to `remoteMcp()` and every maintained
+hosted connection — `{ type: "credential" }` — under which the connector
+declares an operator slot on `/credentials` and reads the pasted value on each
+request. A deployment carrying a static key as a runtime secret
+(`auth: { type: "headers", headers: { Authorization: env.KEY } }`) keeps
+working unchanged; moving it behind `/credentials` is an edit to the connector's
+`auth` and one paste on the operator page, and needs `credentials.encryptionKey`
+configured — a deployment without a vault gets a startup warning and
+`recovery: "unavailable"` at use for that connector, not a boot failure. Two
+Linear notes: the `headers` example in `documentation/linear.md` now shows
+`Bearer ${key}` (Linear's MCP server documents that framing), and the credential
+shape sends `Bearer` by default; a `headers` connector already sending a bare
+key is untouched.
+
+### 0.18.0 → 0.18.1
+
+Nothing throws, no option moves, and every deployment crosses this on the
+version bump alone. The release adds one provider subpath,
+`@zackbart/connecta/providers/revenuecat`, and rewrites guide text inside the
+`mixpanel()` and `stripe()` connections; a deployment that constructs neither
+sees no change, and one that does gets better first-line advice for the same
+constructor calls. Clients that cache connector guides should refresh them
+after upgrading.
+
 ### 0.17.0 → 0.18.0
 
 One floor moves and one always-loaded surface shrinks; neither changes a