@zackbart/connecta 0.22.1 → 0.22.3

package/documentation/provider-conventions.md

@@ -7,11 +7,13 @@ writes the judgment down so it can be argued with, audited, and reused.
 There are two genuinely different provider shapes, and one convention set
 cannot honestly cover both:
 
-- **Hand-written HTTP providers** — `api()` surfaces where Connecta owns every
-  tool name, schema, projection, and error. Today: Cloudflare, Notion, Vercel.
-- **Hosted-MCP proxies** — `remoteMcp()` wrappers around a server somebody else
+- **Hand-written HTTP providers**: `api()` surfaces where Connecta owns every
+  tool name, schema, projection, and error. Today: Cloudflare, Notion, and the
+  Vercel API surface.
+- **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, RevenueCat.
+  are. Today: Cloudflare, Linear, Stripe, Mixpanel, Notion, RevenueCat, and
+  Vercel MCP interfaces.
 
 The governing principle for every convention below is the same: **keep the
 model that interacts with connecta as efficient as possible.** A convention
@@ -85,8 +87,8 @@ other source with no description or no `inputSchema`.
 ## Hand-written HTTP providers
 
 Connecta owns the whole surface here, which means every miss is ours. These
-apply to `api()`-based prebuilt connections (Cloudflare, Notion, Vercel) and are the
-bar any future one is written to.
+apply to `api()`-based prebuilt connections (Cloudflare, Notion, and Vercel's
+API surface) and are the bar any future one is written to.
 
 None of them asks an author to re-derive transport safety. URL confinement,
 query and body construction, `ctx.signal`, redirect refusal, credential
@@ -513,15 +515,12 @@ credential probe, and no automatic issue filing. Proactive credential liveness
 stays removed ([#179](https://github.com/zackbart/connecta/issues/179)); this
 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
-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
-rather than a silent zero.
+**What a manifest holds.** Every tool name a release reviewed and its verdict
+(`read-only`, `additive`, or `destructive`). A manifest may also carry a schema
+digest from a prior review, but that digest is runtime drift evidence, not a
+schema Connecta serves. The credential-free provider check neither requires nor
+updates schema digests. The live `tools/list` definition always remains the
+agent-facing contract.
 
 **What it counts.** Four categories, and only counts:
 
@@ -547,8 +546,9 @@ One activity event per *change* in the counts — an identical report every TTL
 is a heartbeat, not news — carrying the connector id and four integers. The
 event type has nowhere to put a tool name, a schema, an argument, a result, or
 downstream error prose, which is the same construction guarantee the tool-call
-event makes. Which tool drifted is deliberately absent from the runtime: it is
-answered by the maintainer-run check, with a live catalog in front of it.
+event makes. Which account-specific tool drifted is deliberately absent from
+this payload-free runtime report. The public check can name documented drift;
+it cannot recover a plan-gated name the provider does not publish.
 
 **How far an observation reaches.** One runtime, and no further. The
 observation lives in the isolate or process that served the refresh; unlike the
@@ -558,8 +558,9 @@ the instance that took the request: on Workers a `connecta doctor` run will
 usually land on an isolate that has served no refresh and print nothing, and
 behind more than one process it is a coin flip. Read an empty report as *this
 runtime has observed nothing*, never as *nothing drifted* — the durable record
-of a finding is the activity event a sink already stored, and naming the tool
-is still the maintainer-run check's job.
+of a finding is the activity event a sink already stored. The public check can
+name a documented change. Naming an unpublished, account-only tool is outside a
+credential-free checker.
 
 **What a finding obliges.** A contradicted vetted verdict — the downstream
 calling a release-reviewed destructive tool `readOnlyHint: true`, or a vetted
@@ -570,33 +571,43 @@ whether or not anybody noticed it arrived.
 
 ## The maintainer-run drift check
 
-`npm run drift:check` is the other half
+`npm run providers:check` is the other half
 ([#351](https://github.com/zackbart/connecta/issues/351)): a human at a laptop,
-before a release, with local credentials and the published specifications in
-front of them. It lives in
+before a release, using only published specifications and documentation. It
+lives in
 [`scripts/drift-check.mjs`](https://github.com/zackbart/connecta/blob/main/scripts/drift-check.mjs) and ships nowhere —
 `scripts/` is outside the package, no runtime module imports it, and nothing it
 reads becomes a runtime input.
 
-**Hosted-MCP catalogs.** `--hosted` lists each proxy's live catalog with the
-maintainer's own key and diffs it against the same `vettedCatalog()` manifest
-the connector classifies from, reporting tools *by name*: added, no longer
-served, annotation conflicts with what the downstream actually claimed, and —
-once a manifest records schema digests — which tool's schemas moved. The names
-live here rather than in the runtime because the runtime's counts are
-payload-free by construction, and a name has no reader there anyway. It then
-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`, `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
-as a complete Authorization value and passes through unchanged.
+**Published MCP references.** `--docs` checks
+the official setup page for each maintained hosted MCP connection, including
+the endpoint and OAuth support. Cloudflare, Stripe, Mixpanel, Notion,
+RevenueCat, and Vercel also publish structured tool inventories. The checker
+compares their documented names with the same vetted manifests the wrappers
+use. Linear's setup page does not enumerate tools, so its result says that only
+setup metadata was checked.
+
+A documented addition with no classification is a finding. A classified tool
+missing from public docs is printed but does not fail the run, because account
+scope, staged rollout, and documentation lag can all hide a tool that an
+earlier release reviewed. RevenueCat's `render-paywall-screenshot` is the odd
+one out: the official inventory names it but leaves its Access column blank.
+The checker reports the reviewed exception and Connecta keeps it fail-closed.
+
+`npm run providers:check` runs this documentation check for every maintained
+hosted MCP connection and the touched-endpoint OpenAPI check for every
+hand-written HTTP connection. It never reads a provider credential. The network
+keeps it outside `npm run check`; a provider outage must not make the
+deterministic test suite flaky.
+
+MCP schema handling needs a different assertion. Connecta does not vendor or
+reconstruct those schemas, so there is no static MCP schema snapshot for this
+command to compare. The live `tools/list` response is passed through at runtime,
+and the deterministic `catalog-drift.test.ts` suite pins that the vetted wrapper
+changes safety annotations only while preserving the provider input schema,
+output schema, and description. A parameter table in a docs page is never
+promoted into a runtime schema. The report states this directly instead of
+printing a misleading authenticated-schema requirement.
 
 **Touched endpoints.** A hand-written provider is written against a published
 OpenAPI document and calls a few dozen of its operations, so
@@ -630,13 +641,16 @@ H11's business, mapped from the status. `--record` rewrites the manifests from
 the documents on hand; run it when a finding has been reviewed, and read the
 diff before committing it.
 
-Narrowing is checked against the half being run: `--specs --provider linear`
-and `--hosted --provider notion` exit 2 rather than checking nothing and
-reporting no drift, because a false green from a plausible typo is the one
-failure mode a release-time exit code cannot afford.
+Narrowing is checked against the part being run: `--specs --provider linear`
+and `--specs --provider stripe` exit 2 rather than checking nothing and
+reporting no drift. `npm run providers:check -- --provider vercel` checks the
+REST OpenAPI contract and public MCP documentation without credentials.
+`npm run drift:check` is the lower-level equivalent with the same
+credential-free default plus fixture and recording flags.
 
-**What it never does.** No downstream credential reaches CI. No scheduled job,
-no background traffic in a deployment, no automatic issue filing. A finding is
+**What it never does.** No provider credential is read at all. There is no
+scheduled job, background traffic in a deployment, or automatic issue filing.
+Public docs do not generate tools or replace the live MCP catalog. A finding is
 read by a human and becomes a GitHub issue they wrote, because the decision a
 finding needs — the provider moved this endpoint, or connecta has to stop
 calling it — is not one a diff can make. Published specifications remain drift

package/documentation/revenuecat.md

@@ -218,13 +218,10 @@ 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)).
+**No schemas are vendored.** The manifest ships names and safety verdicts only.
+The live `tools/list` response remains the schema agents receive; Connecta does
+not replace it with a snapshot or require a maintainer credential to validate
+one.
 
 ## Rate limits
 
@@ -287,12 +284,19 @@ still needs restrained use.
   additions that catalog serves, including `get-refund-request-preferences`,
   but cannot prove a globally documented tool was removed. The manifest stays
   a superset because plan, platform, and credential scope hide tools.
-- **No complete schema set has been recorded**, which is why the manifest
-  carries no digests. The review read the new live schemas, but its scoped
-  catalog omitted many classified writes.
+- **No complete schema set is vendored.** The live review read the new schemas,
+  but its scoped catalog omitted many classified writes. Runtime schemas still
+  come from the server.
 - **Whether `render-paywall-screenshot` mutates anything.** It has no access
   column, and guessing is exactly what P5 exists to prevent.
 
+`npm run drift:check -- --docs --provider revenuecat` checks the official setup
+page and its 105-row tool reference without a credential. It compares the
+documented names with the release-reviewed classifications. The screenshot
+tool's blank Access column is a manually reviewed exception: the checker
+reports it separately and Connecta keeps it fail-closed. The check reads names,
+not live schemas or machine-interpreted access verdicts.
+
 ## Conventions
 
 This connection is audited against

package/documentation/stripe.md

@@ -247,6 +247,13 @@ about rather than read:
   tools' arguments is not documented. The guide states them because an agent
   that ignores them is wrong either way.
 
+`npm run drift:check -- --docs --provider stripe` compares Stripe's official
+16-tool table with the vetted manifest and checks the hosted endpoint plus OAuth
+support. `list_available_accounts_or_orgs` and `manage_stripe_accounts` remain
+classified from an authenticated review even though the current public table
+does not list them. The command prints that discrepancy without treating docs
+silence as proof that a live account no longer serves them.
+
 ## Conventions
 
 This connection is audited against

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.22.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.22.3 | 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.22.1
+npm pkg set dependencies.@zackbart/connecta=0.22.3
 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.22.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.22.3 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.22.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.3 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,7 +207,7 @@ 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.21.2 → 0.22.1
+### 0.21.2 → 0.22.3
 
 Connector and user policy remain config-as-code. If `identity.connectorAccess`
 is configured, every interactive human may now manage the authentication of

package/documentation/vercel.md

@@ -1,44 +1,58 @@
 # Vercel
 
 Import `vercel()` independently from `@zackbart/connecta/providers/vercel`.
-It is a hand-written `api()` connection over Vercel's public REST API. The
-connection owns 18 named operations and three provider-relative REST hatches.
-It adds no provider dependency, imports no `node:` builtin, and is not reachable
-from Connecta's root entry.
+It offers two explicit provider surfaces:
+
+| `surface` | Contract owner | Authentication | Best fit |
+| --- | --- | --- | --- |
+| `"api"` or omitted | Connecta's hand-written schemas and projections | Vercel access token | Stable named operations, guarded REST hatches, environment variables, domains, and deployment lifecycle |
+| `"mcp"` | Vercel's live MCP catalog and schemas | OAuth | Vercel's newest agent tools, documentation search, observability, purchases, toolbar comments, and direct deployment |
+
+The choice belongs to deployment configuration. It never changes during an
+agent run, and neither surface receives different Connecta privileges. Use two
+connector ids when a deployment needs both.
 
 ```ts
 import { vercel } from "@zackbart/connecta/providers/vercel";
 
-const hosting = vercel("hosting", {
+const hostingApi = vercel("hosting_api", {
+  surface: "api",
   purpose: "Production web applications for the product team",
   teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
 });
+
+const hostingMcp = vercel("hosting_mcp", {
+  surface: "mcp",
+  purpose: "Production diagnosis and Vercel-native agent workflows",
+});
 ```
 
+Omitting `surface` still selects `"api"`, so existing configurations do not
+change behavior.
+
+## API surface
+
+The API surface is a hand-written `api()` connection over Vercel's public REST
+API. It owns 18 named operations and three provider-relative REST hatches. It
+adds no provider dependency, imports no `node:` builtin, and is not reachable
+from Connecta's root entry.
+
 The deployment stores one Vercel access token in Connecta's credential vault.
 Create the token in Vercel Account Settings under Tokens. Scope it to the
 personal account or team this connection needs and give it an expiration date.
 The operator UI's Test action calls `GET /v2/user` and reports the authenticated
 username, email, name, or id. Connecta never probes it in the background.
 
-## Why this uses REST instead of Vercel MCP
-
-Vercel MCP provides useful project, deployment, and log reads, but it does not
-cover the public API. This connection keeps those common reads and adds project
-domains, value-safe environment-variable management, deployment promotion and
-deletion, and direct access to versioned REST endpoints. The three hatches mean
-a newly published Vercel endpoint does not require a Connecta release before an
-agent can use it.
-
-This is still authored rather than generated. No OpenAPI document creates tools
-at runtime. The named operations are reviewed, projected, classified, and
-tested by hand. The published OpenAPI document is used only by
-`npm run drift:check` to compare the 19 named endpoints this connection calls.
+This surface is authored rather than generated. No OpenAPI document creates
+tools at runtime. The named operations are reviewed, projected, classified,
+and tested by hand. The published OpenAPI document is used only by
+`npm run drift:check` to compare the 19 named endpoints this surface calls.
 
 ## Configuration
 
 ```ts
 vercel("hosting", {
+  surface: "api",
   title: "Production hosting",
   authScope: "shared",
   purpose: "Customer-facing sites owned by Platform",
@@ -69,7 +83,35 @@ from replacing `Authorization`, passes `ctx.signal`, and stops reading at 8 MiB.
 The runtime-log read also returns at most 500 rows and stops a stream that stays
 open past 10 seconds. HTTP is accepted only for a loopback test double.
 
-## Named tools
+## MCP surface
+
+The MCP surface proxies Vercel's official hosted endpoint at
+`https://mcp.vercel.com` and uses OAuth. Connecta does not copy Vercel's schemas
+into this repository. Each complete `tools/list` response is preserved as the
+live catalog, cached under the connector id, and invalidated when authorization
+changes.
+
+Connecta does vendor one thing: the 32 tool names and their release-reviewed
+read, additive-write, or destructive-write verdicts from Vercel's
+[official MCP tool reference](https://vercel.com/docs/agent-resources/vercel-mcp/tools).
+Those verdicts fill in missing annotations and keep reviewed destructive tools
+off the read-only execution path. A new tool remains fail-closed until a release
+classifies it. The provider check needs no schema digest because Connecta does
+not serve a schema snapshot.
+
+This separation matters when diagnosing a schema mismatch:
+
+- On `surface: "api"`, the schema in `src/providers/vercel.ts` is Connecta's
+  contract and its tests must prove the behavior.
+- On `surface: "mcp"`, Vercel's live `tools/list` response is the contract.
+  Connecta does not rewrite it. `search_tools` with compact schemas is a lossy
+  preview; use `describe` with JSON format when the exact schema matters.
+
+[integrations.sh's Vercel record](https://integrations.sh/vercel.com/) remains
+useful discovery evidence. The contract check uses Vercel's official setup and
+tool pages instead. Neither source replaces the live MCP schemas.
+
+## API named tools
 
 | Tool | What it does |
 | --- | --- |
@@ -188,7 +230,12 @@ the REST hatches share one guarded transport.
 
 The trade is API drift, handled explicitly. `scripts/drift/vercel-endpoints.json`
 records the method, versioned path, specification revision, and request/response
-digest for every fixed endpoint. Before a release, `npm run drift:check` compares
-those rows with Vercel's published OpenAPI document at
-`https://openapi.vercel.sh/`. The hatches are intentionally absent from that
-list because their endpoint is chosen by deployment code at call time.
+digest for every fixed endpoint. Before a release,
+`npm run providers:check -- --provider vercel` compares those rows with
+Vercel's published OpenAPI document at `https://openapi.vercel.sh/`, compares
+the vendored MCP inventory with Vercel's official tool reference, and checks
+the endpoint and OAuth support in Vercel's setup page. It states that live MCP
+schemas are not vendored and that the live `tools/list` response remains their
+runtime authority. The API hatches are absent from the endpoint manifest
+because deployment code chooses their path at call time. No Vercel credential
+is needed for this check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -114,6 +114,7 @@
     "check:security": "npm audit --omit=dev --audit-level=moderate",
     "check:package": "node scripts/check-package.mjs",
     "load:admission": "npm run build && node eval/admission-load.mjs",
+    "providers:check": "tsx scripts/drift-check.mjs --specs --docs",
     "drift:check": "tsx scripts/drift-check.mjs",
     "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:examples",
     "release:check": "npm run check && npm run check:security && npm run check:package",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.22.1",
+    "@zackbart/connecta": "0.22.3",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {