@zackbart/connecta 0.21.2 → 0.22.1

package/documentation/connectors.md

@@ -1,5 +1,18 @@
 # Connectors
 
+Every connector may set `authScope: "shared" | "personal"`. Shared is the
+default and keeps one deployment-wide downstream grant. Personal auth requires
+a stable human principal and partitions connector state, credentials, OAuth,
+catalogs, and observed shapes by that principal. Connector visibility is a
+separate deployment rule under `identity.connectorAccess`; hiding a connector
+does not change who owns its auth. See [shared and personal auth](./storage-and-credentials.md#shared-and-personal-auth).
+
+`authScope` partitions connecta-owned context, not arbitrary variables captured
+by connector code. A custom personal connector must read auth from
+`ctx.credential` or `ctx.storage`; a secret closed over by its handler remains
+shared JavaScript state. `remoteMcp()` rejects the equivalent mistake when
+literal headers are combined with personal scope.
+
 Connectors are the boundary between Connecta's fixed meta-tool surface and
 downstream capabilities. Prefer a prebuilt connection when Connecta maintains
 one for the provider. Use `api()` to define a deliberate HTTP API surface and
@@ -124,6 +137,7 @@ Maintained provider guides:
 - [Notion](./notion.md)
 - [RevenueCat](./revenuecat.md)
 - [Stripe](./stripe.md)
+- [Vercel](./vercel.md)
 
 ## The `api()` construction contract
 
@@ -213,12 +227,13 @@ into a result or a typed failure. That split is not fastidiousness. Notion's
 cannot fix it — while Cloudflare's means a token scope, and the two want
 opposite next moves. A helper that guessed would be wrong for one of them.
 
-Cloudflare and Notion both run on it. Their existing suites carried over
-unchanged, which proves the migration kept the behavior those suites cover —
-not that nothing changed. Three things did, and the changelog names them: a
-3xx is refused where both providers used to follow it, both now fail past
-their byte ceiling, and `cloudflare()`'s `baseUrl` is validated at
-construction. Each suite gained one test for the ceiling, because the one
+Cloudflare, Notion, and Vercel run on it. The first two existing suites carried
+over unchanged when the helper was extracted, which proves that migration kept
+the behavior those suites cover — not that nothing changed. Three things did,
+and the changelog names them: a 3xx is refused where both providers used to
+follow it, both now fail past their byte ceiling, and `cloudflare()`'s
+`baseUrl` is validated at construction. Each suite gained one test for the
+ceiling, because the one
 guard the helper was written to add is the one a provider's own mapper can
 most easily disarm: a bare `catch` around `response.json()` swallows the
 transport's refusal along with a parse error, and turns a response nobody was

package/documentation/meta-tools.md

@@ -307,9 +307,10 @@ credential.
 
 The tool accepts no secret. `force` applies only to OAuth and may discard its
 stored grant before restarting consent. Static credential values are written
-only through the same-origin, Clerk-operator credential route. After OAuth
-consent or an operator update, retry the original operation; a static update is
-read from the vault on the next call and needs no redeploy.
+only through the same-origin interactive-user credential route, and only for a
+connector visible to that user. After OAuth consent or a human update, retry
+the original operation; a static update is read from the vault on the next call
+and needs no redeploy.
 
 ## Routing recovery
 

package/documentation/operations.md

@@ -84,6 +84,7 @@ optional.
 | `connectors` | — (required) | the connector set ([connectors](./connectors.md)) |
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
 | `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before interactive providers ([inbound auth](./auth.md)) |
+| `identity?` | all connectors; every interactive human is an operator | `{ connectorAccess?, operatorAccess? }` derives the request's connector view and shared-auth authority from its authenticated identity ([principals](./auth.md#principals-visibility-and-operators)) |
 | `storage?` | `memoryStorage()` | the one state seam for catalogs, result paging, credentials, and access tokens ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
 | `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }` |
@@ -247,6 +248,7 @@ in.
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
+| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, shared-auth operator control, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
 | `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
@@ -256,7 +258,7 @@ in.
 | `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, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
-| `provider-registry.test.ts` | all six maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
+| `provider-registry.test.ts` | all seven maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `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-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
@@ -272,6 +274,7 @@ in.
 | `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
 | `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus 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 |
+| `vercel-provider.test.ts` | `vercel()` construction, team scoping, project and deployment projections, finite build and runtime logs, value-safe environment variables, domains, lifecycle writes, REST hatches, typed failures, and credential test |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
 
@@ -280,7 +283,7 @@ 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 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 |
+| `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, its agent instructions and setup guide pinning Claude and both ChatGPT Managed OAuth callback forms, 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 and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the maintainer drift checker — hosted-provider credential framing, recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |

package/documentation/operator-ui.md

@@ -5,10 +5,10 @@ the authentication material behind it. It is a small Preact app compiled by the
 repository's own esbuild step and inlined into a data-free server shell.
 
 Read [`ethos.md`](../ethos.md) first. The boundary this subsystem lives inside
-is the operator row in its decisions table: **operator routes may manage
-authentication material for capabilities declared in deployment configuration,
-and may not change the connector set, the tool catalog or annotations, requested
-OAuth scopes, admission policy, authorization rules, or caller tool scope.**
+is the human-management invariant: **members may manage authentication material
+for every connector their code-derived view includes, operators may also manage
+deployment tokens and global activity, and neither may change the connector set, tool catalog,
+annotations, requested OAuth scopes, admission policy, or identity rules.**
 `test/operator-boundary.test.ts` proves it after every mutation route.
 
 Both deployment shapes ship the whole feature set behind it, because pages for
@@ -52,6 +52,15 @@ server reads the resulting runtime identity. Sign out navigates to
 `/cdn-cgi/access/logout`. Mutations still require an exact same-origin
 `Origin`; an ambient cookie does not weaken the CSRF boundary.
 
+The shell is shared by members and operators. `/ui/data` uses the same
+identity-scoped registry view as `/mcp`, so it cannot list a connector the
+current caller cannot discover. A member sees credential and OAuth controls for
+every visible connector. Personal actions resolve to that member's principal
+partition; shared actions change the deployment-wide grant. The access-token
+and global activity pages require `identity.operatorAccess`. Existing
+deployments that omit that resolver keep every interactive human as an
+operator.
+
 This runtime selection is the Clerk migration seam. A deployment may contain
 both providers: before Worker-level Access is attached, the data-free shell
 selects Clerk; after Access supplies `ctx.access`, it selects ambient auth. That

package/documentation/provider-conventions.md

@@ -1,6 +1,6 @@
 # Provider conventions
 
-The six maintained prebuilt connections grew one at a time, and until now
+The seven 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.
 
@@ -8,7 +8,7 @@ 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.
+  tool name, schema, projection, and error. Today: Cloudflare, Notion, Vercel.
 - **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.
@@ -85,7 +85,7 @@ 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) and are the
+apply to `api()`-based prebuilt connections (Cloudflare, Notion, Vercel) and are the
 bar any future one is written to.
 
 None of them asks an author to re-derive transport safety. URL confinement,
@@ -646,11 +646,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 six providers and returns a verdict per
+runs this document against each of the seven 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 six reports live in [provider-audit.md](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md), and the
+Its seven reports live in [provider-audit.md](https://github.com/zackbart/connecta/blob/main/records/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.

package/documentation/request-admission.md

@@ -49,7 +49,8 @@ which is also why `/health` always has a code-admission shape to report.
 
 The request pool is global FIFO across identities. It is a capacity boundary,
 not tenant fairness: one busy caller can occupy it. Per-tenant fairness needs a
-policy above connecta, and one deployment serves one audience anyway
+policy above connecta, and one deployment still serves one tenant even when
+identity rules give its principals different connector views
 ([`ethos.md`](../ethos.md)), so a global queue is not pretending to supply
 something it does not.
 

package/documentation/storage-and-credentials.md

@@ -6,7 +6,7 @@ token is an independent record rather than one shared, race-prone manifest.
 The built-in memory and file adapters implement it, as does the Cloudflare KV
 example.
 
-Connectors may declare an operator-managed `credential` slot. When
+Connectors may declare a human-managed `credential` slot. When
 `credentials.encryptionKey` is configured, Connecta encrypts values in the
 deployment storage and exposes read-only access only through that connector's
 `ctx.credential`. Values, masked values, call arguments, and raw errors never
@@ -27,13 +27,40 @@ Credential mutation is intentionally narrower than MCP access:
 
 - a static bearer may call tools and receive the operator handoff, but it
   cannot write credentials;
-- only an admitted Clerk user may use the same-origin credential mutation
-  routes; and
+- an admitted interactive human may mutate credentials for every visible
+  connector: their own partition for personal auth, or the deployment-wide
+  value for shared auth; and
 - saving, replacing, testing, or removing a value never returns that value.
 
-The vault is read for each call. Once an operator saves a replacement,
+The vault is read for each call. Once a signed-in human saves a replacement,
 the agent can retry immediately without restarting or redeploying Connecta.
 
+## Shared and personal auth
+
+Connector auth defaults to `authScope: "shared"`. Its credential, OAuth state,
+tokens, catalog cache, and connector storage belong to the deployment. Set
+`authScope: "personal"` when every human principal needs a separate downstream
+account:
+
+```ts
+remoteMcp("linear", {
+  url: "https://mcp.linear.app/mcp",
+  authScope: "personal",
+  auth: { type: "oauth" },
+});
+```
+
+Personal connectors disappear from a request that has no stable human
+principal. For a principal that can see one, connecta partitions connector
+storage, encrypted vault records, catalog caches, OAuth generations, and
+observed result shapes under an opaque SHA-256 identity key. Results used by
+`get_result` are partitioned by the authenticated subject, so one token cannot
+page another token's call even when both tokens belong to the same principal.
+
+Literal `auth: { type: "headers" }` cannot be personal because its secret lives
+in deployment code. `remoteMcp()` refuses that combination at construction.
+Use operator-managed credential auth or OAuth instead.
+
 ## A remote MCP connector's static credential
 
 `remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
@@ -97,6 +124,17 @@ Registration and token envelopes are bound to the validated authorization
 server `issuer`. An unbound pre-0.9 envelope is upgraded in place on its first
 issuer-aware read, preserving the existing grant.
 
+For personal OAuth, the authorization handoff also stores a 15-minute mapping
+from a SHA-256 digest of `state` to the principal partition. The public callback
+uses that mapping before it verifies state or exchanges the code. Neither the
+browser nor a callback parameter can select a principal. The callback deletes
+the mapping before it exchanges the code, so a second callback cannot replay
+the principal handoff in strongly consistent storage. Cloudflare KV deletion
+is eventually consistent, so handoff consumption there is best-effort across
+PoPs; the downstream authorization code remains single-use. If the callback
+request also carries an interactive identity, Connecta refuses it when that
+principal did not start the flow.
+
 If later discovery resolves a different issuer, Connecta does not send the old
 client identifier or tokens to it. The provider publishes a new generation
 epoch, makes every older credential namespace unreadable, cleans up the retired

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.21.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 |
+| **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 |
 
 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.21.2
+npm pkg set dependencies.@zackbart/connecta=0.22.1
 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.21.2 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.22.1 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.21.2 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.1 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,22 @@ 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
+
+Connector and user policy remain config-as-code. If `identity.connectorAccess`
+is configured, every interactive human may now manage the authentication of
+each connector that resolver makes visible. A personal connector changes only
+that principal's partition; a shared connector changes the deployment-wide
+grant. Keep shared connectors out of a member's view, or change them to
+`authScope: "personal"`, when that member must not rotate the shared grant.
+`identity.operatorAccess` continues to govern deployment access tokens and
+global activity.
+
+Paged results also move under the authenticated subject's storage partition.
+Finish any important in-flight `get_result` sequence before upgrading; its old
+result id is not readable from the new partition after deployment. No persisted
+connector catalog or credential migration is required.
+
 ### 0.20.0 → 0.21.2
 
 0.21.2 adds no deployment migration beyond 0.21.0. The boundary is additive
@@ -244,6 +260,21 @@ For a Worker currently using Clerk, keep rollback live through the cutover:
    tag>" }`, not a hostname application for the `workers.dev` URL: the latter
    gates traffic but does not provide `ctx.access`. Create an Access service
    token and a **Service Auth** policy for doctor and fully unattended clients.
+   In the application's Managed OAuth settings, enable Dynamic Client
+   Registration and add these three **Allowed redirect URIs**:
+
+   ```text
+   https://claude.ai/api/mcp/auth_callback
+   https://chatgpt.com/connector_platform_oauth_redirect
+   https://chatgpt.com/connector/oauth/*
+   ```
+
+   They map to
+   `oauth_configuration.dynamic_client_registration.allowed_uris` in the
+   Access API, not to the identity policy. The two ChatGPT entries cover its
+   stable and callback-id forms. An empty list fails client registration only
+   after discovery, so do not treat a working `/.well-known/*` response as
+   proof that this step is complete.
    Do not create a bypass for `/.well-known/*`; Managed OAuth owns that
    discovery surface.
 

package/documentation/vercel.md

@@ -0,0 +1,194 @@
+# 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.
+
+```ts
+import { vercel } from "@zackbart/connecta/providers/vercel";
+
+const hosting = vercel("hosting", {
+  purpose: "Production web applications for the product team",
+  teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
+});
+```
+
+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.
+
+## Configuration
+
+```ts
+vercel("hosting", {
+  title: "Production hosting",
+  authScope: "shared",
+  purpose: "Customer-facing sites owned by Platform",
+  teamId: "team_...",
+  defaultPageSize: 20,
+  instructions: "Never promote the docs project from this connection.",
+  maxResultBytes: 512_000,
+  callAdmission: {
+    rules: [{ maxConcurrency: 6 }],
+  },
+});
+```
+
+`purpose` is required and blank text throws at construction. `teamId` is a
+default, not a hidden lock. Named account-scoped tools accept a `teamId`
+override; pass `null` to target the token owner's personal account explicitly.
+Without a configured default or an override, Vercel uses that personal account.
+`list_teams` returns the ids needed to reach a team.
+
+`defaultPageSize` defaults to 20 and must be a whole number from 1 through 100.
+Vercel meters endpoints separately, so the connection invents no global request
+budget. A deployment may supply `callAdmission` when it has its own concurrency
+or call-rate requirement.
+
+`baseUrl` exists for a test double or an HTTPS proxy. The guarded transport
+confines every path under that base, refuses redirects, prevents request headers
+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
+
+| Tool | What it does |
+| --- | --- |
+| `list_teams` | Lists teams the token can reach. |
+| `list_projects` | Searches or lists lean project summaries. |
+| `get_project` | Reads build settings, Git identity, and the production deployment. |
+| `list_deployments` | Filters deployments by project, target, state, branch, or SHA. |
+| `get_deployment` | Reads one deployment by id or hostname. |
+| `get_build_logs` | Reads at most 1,000 existing build events with live following disabled. |
+| `get_runtime_logs` | Reads a 1–500 row runtime-log snapshot and stops a stream open past 10 seconds. |
+| `list_project_domains` | Lists verification, redirect, branch, and custom-environment state. |
+| `add_project_domain` | Adds a regular, redirect, branch, or custom-environment domain. |
+| `verify_project_domain` | Rechecks a pending domain after its DNS challenge is complete. |
+| `remove_project_domain` | Removes a project domain, optionally with domains redirecting to it. |
+| `list_project_env_vars` | Lists metadata without asking Vercel to decrypt values. |
+| `upsert_project_env_var` | Creates or replaces one variable. |
+| `update_project_env_var` | Patches one variable by its id. |
+| `delete_project_env_var` | Removes one variable from future deployments. |
+| `promote_deployment` | Promotes an existing build to production without rebuilding. |
+| `cancel_deployment` | Cancels work that is queued, initializing, or building. |
+| `delete_deployment` | Permanently removes a deployment and its URL. |
+
+Every read returns a lean projection by default. Projects drop security,
+billing, and presentation settings. Deployments keep state, target, timestamps,
+creator, and Git identity. Domain reads keep the verification challenge because
+dropping it would make an unverified result unusable. The project, deployment,
+domain, and build-log reads accept `raw: true` when a Vercel field omitted by
+the projection matters.
+
+`raw: true` preserves unprojected list items while keeping the named tool's
+declared envelope: list calls still return their item key and `page`, and build
+logs still return `{ events }`.
+
+## Environment values are write-only here
+
+`list_project_env_vars` sends `decrypt=false`, then drops `value` even if
+Vercel returns one anyway. It returns the key, id, storage type, visibility,
+targets, branch, custom-environment ids, comment, and timestamps. The create and
+update tools accept a value as input, but their result projection drops it too.
+
+That boundary is deliberate. An agent can audit placement and make a requested
+change without filling its context with database URLs or API keys. Sensitive
+values cannot be read back from Vercel in any case. The generic
+`vercel_api_get` hatch returns the endpoint's untouched response, so a caller
+that deliberately requests an endpoint capable of decrypting a non-sensitive
+value has asked to cross the named tool's safer boundary.
+
+Environment changes affect future deployments. They do not rewrite a value
+already embedded in an existing deployment, and none of the environment tools
+triggers a deployment on its own.
+
+## REST hatches
+
+Vercel's API is too large and changes too often for every operation to deserve
+a permanent named tool.
+
+- `vercel_api_get` accepts only GET and is explicitly read-only.
+- `vercel_api_mutate` accepts JSON POST, PUT, PATCH, and DELETE. It always
+  crosses `call_destructive_tool`.
+- `vercel_api_upload` accepts POST or PUT with exactly one explicit UTF-8 or
+  base64 body. It also crosses `call_destructive_tool`.
+
+All three take a path beginning with `/` and including Vercel's version, such
+as `/v1/edge-config`. Query parameters are name/value rows rather than a string
+to parse. They use the configured default team unless the caller passes
+`personalAccount: true`; that flag cannot be combined with a `teamId` or `slug`
+query row. The upload hatch accepts endpoint-specific headers such as a digest,
+but refuses credential, cookie, host, content-type, content-length, and
+transfer-encoding headers. It reads no local file. The caller supplies the
+bytes, content type, and any checksum the endpoint requires.
+
+Use a named tool when one exists. A named tool wins on argument validation,
+result size, or safety routing. The hatch is for products such as Edge Config,
+feature flags, drains, checks, security, and team settings that are not worth a
+large permanent catalog.
+
+## Pagination
+
+The four list families expose one connector-wide contract:
+
+```ts
+{
+  items: [],
+  page: { hasMore: true, nextCursor: "opaque" }
+}
+```
+
+The item key is `teams`, `projects`, `deployments`, or `domains`. Pass
+`nextCursor` back as `cursor` unchanged. Vercel uses different parameter names
+and cursor types behind the four endpoints. The connector owns that mapping so
+programs do not parse timestamps or branch on provider-specific pagination.
+
+Environment-variable listing has no pagination in Vercel's published contract
+and returns `{ variables }` without a false page object.
+
+## Typed failures
+
+- HTTP 401 and 403 become `auth_required`. Vercel uses 403 both for a bad token
+  and for a token outside the requested team or operation scope.
+- HTTP 404 becomes `not_found`. Re-list the owning project, deployment, domain,
+  or environment variable before using the id again.
+- HTTP 400, 409, and 422 become `invalid_args`.
+- HTTP 429 becomes `rate_limited`. `Retry-After` wins; otherwise the connector
+  derives the delay from `X-RateLimit-Reset`.
+- HTTP 5xx becomes `unavailable`.
+
+The error text keeps Vercel's error code and message. It never parses prose to
+invent a class.
+
+## No SDK on purpose
+
+The connection imports only Connecta modules and Web APIs. `@vercel/sdk` is not
+a dependency or optional peer. Direct fetch keeps the root Workers-safe, avoids
+shipping the generated model graph, and lets the reviewed named operations and
+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.

package/ethos.md

@@ -8,8 +8,8 @@ preserve. A contradiction needs a design decision, not a drive-by edit.
 - **One MCP endpoint, one programmable surface.** Every integration you chose
   sits behind a capability catalog that agents reach by writing JavaScript,
   ringed by a few explicit tools for the boundaries code must not cross.
-- **A deployment is a small config-as-code file.** Changing what agents can
-  reach is an edit and a redeploy. One deployment, one tenant, one audience.
+- **A deployment is config-as-code.** One tenant and connector set; principals
+  receive config-derived views.
 - **Curated when available, open when not.** Prefer a maintained prebuilt
   connection; `remoteMcp()` and `api()` stay first-class for everything else.
   Every path yields the same `Connector` with the same rules.
@@ -30,8 +30,8 @@ preserve. A contradiction needs a design decision, not a drive-by edit.
 - **Not a platform.** No runtime registration, admin-editable capability,
   policy engine, approvals, or pauses.
 - **Not a schema ingester.** No OpenAPI or GraphQL → tools.
-- **Not multi-tenant.** No account model or per-user credential store; scope
-  stays connector-level, and ambiguity stops rather than guesses.
+- **Not multi-tenant.** No accounts, groups, or sessions. Inbound auth owns
+  identity; personal state stays within one tenant.
 - **Not stateful.** No protocol sessions, no server push; scope resolves per
   request.
 - **Not a nanny.** Credentials fail loudly at use; nothing probes one.
@@ -47,7 +47,7 @@ CHANGELOG, not here.
 | Decision | Verdict | Why |
 | --- | --- | --- |
 | OpenAPI / GraphQL ingestion | refused | the disease is a tool nobody chose — a document authored it; hand-written literals, even through a shared factory, are still authorship |
-| Multi-tenancy / account model | refused | one deployment per tenant; deploy again |
+| Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
 | Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
@@ -67,7 +67,7 @@ CHANGELOG, not here.
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
 | Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
-| Toolkits (scoped views) | removed | deploy per audience ([#178](https://github.com/zackbart/connecta/issues/178)) |
+| Caller-selected toolkits | removed | only config may derive an identity's connector view ([#178](https://github.com/zackbart/connecta/issues/178)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
@@ -91,10 +91,10 @@ Breaking one is a design change wearing a disguise.
 - **A downstream catalog is complete or it is a failure.** A partial catalog is never cached, persisted, or served.
 - **Activity is payload-free by construction.** The event type has nowhere to put arguments, results, code, or raw errors.
 - **An observed shape is never a declaration.** Names and broad types only, labeled, and gone behind any declared schema.
-- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector, rendered by nothing.
+- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
 - **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
 - **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Operator routes manage authentication material, never declared capability.** A downstream catalog is discovered, not declared.
+- **Human routes manage auth, never capability.** Signed-in humans manage auth for visible connectors; operators also manage tokens and global activity.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
 Connecta began as a radical simplification of

package/examples/worker/AGENTS.md

@@ -0,0 +1,44 @@
+# Working on this Connecta Worker deployment
+
+This repository is deployment configuration, not a copy of Connecta itself.
+
+- Edit `src/index.ts` for connectors, authentication, storage, and public URL.
+- Keep `cloudflareAccessAuth()` as the inbound auth provider. Cloudflare Access
+  authenticates the request before the Worker runs; do not add JWT parsing or a
+  second Worker-side identity gate.
+- Attach Access to the Worker itself, not only its hostname. Enable Managed
+  OAuth and Dynamic Client Registration on that Access application.
+- Managed OAuth's **Allowed redirect URIs** must contain all three entries
+  below. This is application configuration under
+  `oauth_configuration.dynamic_client_registration.allowed_uris`, not an
+  Access Allow policy:
+
+  ```text
+  https://claude.ai/api/mcp/auth_callback
+  https://chatgpt.com/connector_platform_oauth_redirect
+  https://chatgpt.com/connector/oauth/*
+  ```
+
+  The first is Claude's hosted MCP callback. The two ChatGPT entries cover its
+  stable callback and its callback-id form. An empty allowlist lets Access
+  discovery work but makes client registration fail with `redirect_uri` not
+  allowed. If a client presents a different callback, copy that exact URI from
+  its registration attempt and add the narrowest matching entry rather than
+  broadening the allowlist to an entire origin.
+- Keep `new DynamicWorkerExecutor({ loader: env.LOADER })` loader-only. Do not
+  add bindings, modules, or outbound access to generated code.
+- Keep credentials in Worker secrets. Never commit credential values, Access
+  service-token secrets, or `CREDENTIAL_ENCRYPTION_KEY`.
+- Add application logic only inside deliberate `api()` connector handlers.
+  Do not copy or modify Connecta package internals here.
+- Prefer `api()` when the agent must see an exact reviewed capability set;
+  `remoteMcp()` follows the downstream server's evolving tool catalog.
+- Use Access service credentials for `connecta doctor` and unattended clients.
+  A `cta_` token or static Connecta bearer cannot cross the Access edge alone.
+- Run the repository's `npm run check:examples` after configuration changes.
+  After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
+  complete their browser authorization flows before calling setup complete.
+
+Do not add alternate entrypoints, policy layers, generated connector catalogs,
+or runtime connector registration. Keep the deployment small enough to review
+as configuration.