@zackbart/connecta 0.29.0 → 0.31.0

package/documentation/operating.md

@@ -0,0 +1,135 @@
+# Operating an endpoint
+
+Use this guide as an agent connected to an existing Connecta endpoint. Setup
+and credentials are the deployment operator's responsibility; use
+[Deploying Connecta](./deploying.md) if you are that operator.
+[All agent routes](./README.md) are in the index.
+
+## Choose the call path
+
+Connecta exposes six top-level tools. Read [the tool table](./meta-tools.md#the-six-tools)
+for exact arguments and result envelopes. Follow the endpoint's supplied
+instructions and `skills` usage guide for deployment-specific context.
+
+| Work                                                               | Use                                                       |
+| ------------------------------------------------------------------ | --------------------------------------------------------- |
+| One known read, with usable arguments and a small result           | `call_tool`                                               |
+| Discover a tool, chain calls, combine services, or reduce a result | `execute_code`                                            |
+| One write on a read-only endpoint                                  | `call_destructive_tool`                                   |
+| Obtain connector instructions                                      | `skills` with the returned guide name                     |
+| Start a required authentication handoff                            | `authorize_connector`, using the returned recovery action |
+
+The endpoint's trust is part of its tool descriptions. On a `trusted` endpoint,
+programs may write within the caller's grants, and `execute_code` is annotated
+as a write. On `read-only`, every write is a separate top-level call. The host
+controls approval. Never change pool, identity, or trust to work around a refusal.
+[Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
+owns the full decision rules.
+
+## Discover before guessing
+
+Use two to four distinctive action/object terms for each operation, and name
+the connector when it is obvious. Read `catalogErrors`, `absence`, classification,
+and required inputs before selecting a result. An empty search may mean a
+failed catalog or a service outside the caller's grants.
+
+For normal reads, keep discovery, calls, and reduction in one program when the
+schemas suffice; return the answer rather than catalog matches. Use top-level
+`search_tools` for catalog inspection or to discover a write on a read-only
+endpoint, then dispatch each write with `call_destructive_tool`. An unfamiliar
+read result may return a bounded sample for inspection before the next program.
+
+Use the exact returned `address`, including punctuation. A TypeScript signature
+is guidance for writing JavaScript; do not paste types into executable code.
+If a schema is truncated or exact constraints matter, describe the address with
+`format: "json"`. Read a returned `guide` through `skills` or
+`connecta.skill` before relying on provider-specific conventions.
+[Discovery context](./meta-tools.md#discovery-context) and
+[guest search](./code-mode.md#connectasearch) define these results.
+
+## Call, combine, and reduce
+
+A program is one JavaScript `async` arrow expression. It has the `connecta`
+guest API and captured console output, with no portable imports, filesystem,
+network access, or credentials. Downstream calls return an envelope; read its
+`data` rather than treating the envelope as the provider's result.
+
+This illustrative tracker has a `list_issues` read accepting `state` and
+returning `data.nodes`. Discover its address, call it, and group the identifiers
+in one program:
+
+```js
+async () => {
+  const page = await connecta.search({
+    connector: "tracker",
+    query: "list issues",
+    safety: "readOnly",
+  });
+  if (page.catalogErrors.length || page.absence) {
+    return { gap: page.catalogErrors, absence: page.absence };
+  }
+  const tool = page.tools.find(t => t.name === "list_issues");
+  if (!tool) return { gap: "list_issues unavailable" };
+  const { data, format } = await connecta.call(tool.address, {
+    state: "started",
+  });
+  if (format !== "json" || !Array.isArray(data?.nodes)) {
+    return { gap: "Expected a JSON issues collection" };
+  }
+  const byOwner = Object.create(null);
+  for (const issue of data.nodes) {
+    const owner = issue.assignee?.name ?? "unassigned";
+    (byOwner[owner] ??= []).push(issue.identifier);
+  }
+  return byOwner;
+}
+```
+
+`tracker.list_issues` is illustrative, not a built-in address. Discover the real
+connector's schemas and pagination before adapting this program. Keep loops and
+parallel work bounded. [Parallel calls](./code-mode.md#parallel-calls),
+[results and projection](./code-mode.md#results-and-projection), and
+[cancellation and limits](./code-mode.md#cancellation-and-limits) own those rules.
+
+Discovery may label an output schema `observed`. It records field names and
+broad types from successful reads in bounded runtime memory, with no scalar
+values. Treat it as evidence, not a provider contract; handle missing fields.
+
+## Large results and resources
+
+Direct calls may return a preview and a result handle. Page the handle through
+`connecta.result` in a program using the returned offset and byte limits, or
+reduce the data in the original program. Handles are short-lived and bound to
+the admitted caller, endpoint/pool, and current grants. Never invent one or pass
+it between identities. [Paging](./meta-tools.md#paging-with-connectaresult)
+owns the envelope and expiry rules.
+
+For resources, use the exposed resource inventory and `connecta.read`; do not
+fetch an arbitrary URL. [Resource reads](./code-mode.md#connectaread) describe
+which URIs may be read. Connector guides and native skills are described in
+[skills](./meta-tools.md#connector-guides-and-skills).
+
+## Recover without replaying a write
+
+Read typed failures and their `nextAction`. Authorization recovery can point
+to consent, operator credential setup, or deployment configuration. Discovery
+and status do not begin consent on their own. Follow
+[authorization recovery](./meta-tools.md#authorization-recovery),
+[routing recovery](./meta-tools.md#routing-recovery), and
+[argument recovery](./meta-tools.md#argument-recovery) for the specific failure.
+
+A dispatched write is never automatically replayed. An ambiguous timeout may
+mean the provider applied it; inspect state or ask for the missing decision
+before issuing it again. [Retry semantics](./code-mode.md#retry-semantics) and
+[writes](./code-mode.md#writes) describe program outcomes and write accounting.
+
+## Implementation and evidence
+
+The endpoint's built-in [usage skill](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
+is maintained alongside [meta-tools](https://github.com/zackbart/connecta/blob/main/src/meta-tools.ts)
+and [execution](https://github.com/zackbart/connecta/blob/main/src/execute.ts).
+[Usage-guide tests](https://github.com/zackbart/connecta/blob/main/test/usage-guide.test.ts),
+[direct-call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
+and [guest-contract tests](https://github.com/zackbart/connecta/blob/main/test/guest-api-contract.test.ts)
+check the contracts. Executor-specific evidence is indexed in
+[code-mode verification](./code-mode.md#verification).

package/documentation/operator-tests.md

@@ -1,5 +1,9 @@
 # Operator UI tests
 
+Use this repository-maintenance guide when changing operator pages, data routes,
+or browser evidence. Read the [operator UI contract](./operator-ui.md) first.
+[The agent index](./README.md) routes deployment and endpoint tasks.
+
 `test/fixtures/operator-visual.ts` owns the visual data. It builds the config,
 live overlay, viewer, and legacy auth details through the current server routes,
 using the types in `src/operator-ui/contract.ts` and `model.ts`. Collections use

package/documentation/operator-ui.md

@@ -0,0 +1,132 @@
+# Operator UI
+
+Use this guide to enable or maintain the optional operator interface. For
+client tool calls use [Operating an endpoint](./operating.md); for identities,
+credential ownership, and grants use [Auth](./auth.md).
+[All agent routes](./README.md) are in the index.
+
+## Task routes
+
+| Task                                            | Read                                                                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Enable UI, vault, or history in a deployment    | [Setup](#setup), then the platform template                                                                      |
+| Consume config, provenance, status, or activity | [Operator data contract](#operator-data-contract)                                                                |
+| Change a UI page or data route                  | [Source and tests](#source-and-tests), [browser verification](./operator-tests.md)                               |
+| Diagnose permission refusals                    | [Management permissions](./auth.md#management-permissions), [activity disclosure below](#operator-data-contract) |
+
+## Setup
+
+Set `ui: operatorUi()` using `@zackbart/connecta/ui`. Branding belongs in
+`operatorUi({ branding })`; the [Node template](../templates/node/README.md#select-optional-modules)
+and [Worker example](../examples/worker/README.md#select-optional-modules)
+own the runnable configuration, variables, and branding shape. The UI is an
+explicit optional import and stays outside the root package import graph.
+
+Overview, Connectors, Tools, Access, Activity, and Config show only what the
+caller may inspect. Connector detail tabs cover configuration, schemas,
+authentication, activity, and diagnostics. Config labels values as default or
+configured. Deployment code owns connectors, grants, pools, and classification;
+the UI changes only authorized authentication material.
+
+Install the vault for declared credential slots and activity history for
+persisted call records. Neither module grants permission to manage or read
+it. Credential administration, personal connection, access-token management,
+and activity access are separate identity decisions, denied by default where
+specified in [auth](./auth.md#management-permissions). Machine tokens never
+grant interactive credential or token management authority.
+
+## Operator data contract
+
+`GET /ui/api/config`, owned by `operatorUi()`, returns `OperatorUiContract`
+from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
+source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
+`config` is the construction-time `describeConfig()` snapshot, filtered to
+visible connectors, granted tools, classification overrides, and admitted
+pools. Pool tools are the intersection with the caller's identity grants.
+`configSources` labels each serialized leaf as `default` or `config`, based on
+option presence rather than equality with the default. Factory descriptions carry
+relative `optionSources` paths so resolved module and transport defaults retain
+their provenance. The snapshot copies only resolved values; the UI consumes
+these presence facts separately. Its paths use connector
+ids and pool names and are filtered after disclosure; hidden values leave no
+provenance keys. It contains no source code or credential material.
+Every response is private, `no-store` JSON. Only GET is allowed, with the
+same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
+
+`live.connectors` carries status and problem codes, complete registry tools
+with their final read/write classification, catalog age in milliseconds, and
+last-call time/outcome. Catalog descriptions and schemas are allowed for an
+authenticated reader; grammar-failing names and addresses become `<withheld>`.
+`auth.registrationPath` reports the selected downstream OAuth client mechanism when known.
+Status prose, error text, credential values or suffixes, arguments, results,
+and code are excluded. Static and unobserved catalogs have a null age;
+persisted catalogs retain their original fetch time. Probes run with bounded
+concurrency and the configured probe deadline, and release their scopes.
+
+Last-call lookup requires the existing activity permission and read gate. It
+scans up to 1,000 recent rows, filters connector/tool grants, and restricts
+personal connectors to the caller's activity identity. Each retained fact
+copies a validated timestamp and outcome only. A null call means unknown or
+absent in that window, not proof of no calls. `live.activity` distinguishes
+available, unconfigured, forbidden, and unavailable history. `you` names no
+identity or auth material; it reports grants, root and admitted-pool trust,
+and effective activity, token, and per-connector auth permissions.
+
+`connecta doctor --config` fetches this authenticated contract and prints only
+`config` as indented JSON. It requires the UI module and the existing doctor
+authentication environment variables; it runs no diagnostic program, follows
+no redirects, and prints no raw HTTP failure body.
+
+The operator shell uses React, TanStack Router/Query/Table, Radix, cmdk and
+Tailwind v4. Inter, CSS, JavaScript and dependency notices are hashed assets
+under `/ui/assets/*`, served identically with immutable cache headers on Node
+and Workers. HTML contains only mount points and escaped inert configuration;
+it remains uncached. `generated.ts` is ignored and generated before build and
+test; `check:operator-ui` detects stale assets and shared page styles. The UI
+stays behind `./ui`, outside the root import graph. The identity-fenced store
+owns authenticated reads and existing mutations. Overview, Connectors, connector
+detail, Tools, Access and Config consume the typed contract. Activity retains
+its authenticated data routes. Connector detail tabs live
+in the URL hash; Activity filters live in the query string and apply to loaded
+history. Both `/ui/activity` and `/ui/api/activity` require Activity access and
+pass the optional activity `readGate`. Interactive operators and machine callers
+admitted by `identity.activityAccess` share the same history disclosure rules.
+Connector/tool grants and grants for the recorded pool filter each event. Shared
+connector history can include other principals' events, with recorded request
+IDs, validated client name/version and package version, and actor kind, ID and
+namespace. Interactive reads may also add directory actor labels; machine reads
+never add them. Personal connector history is owner-only: the event must have a
+checked `principal` actor basis and actor ID/namespace matching the reader's
+admitted principal. Rows without a provable personal owner are withheld. Activity
+carries no arguments, results, code or raw downstream errors. The last-call
+overlay uses the same event filter but returns only timestamp and outcome.
+Calls group only by recorded request ids, with missing ids shown as
+separate calls. Classification and result size are shown only when recorded. The verdict is
+captured after registry resolution, and result size counts UTF-8 bytes of the
+downstream value before paging or truncation. Nullable SQL columns preserve old
+rows. Catalog changes use the same paging envelope with `kind: "catalog_drift"`,
+`source: "catalog_refresh"` and a checked `catalog_changed` fact containing only
+added, removed and changed tool counts. The first complete catalog is a baseline;
+one refresh-publication hook emits each later change. It includes the request's
+id and typed actor when available, otherwise a fresh id and system actor. No
+names, descriptions or schemas enter the event. Private catalog changes require
+a matching principal owner even when the connector uses shared auth. Empty credential declarations
+report `credential_required` before running a connector status or catalog probe.
+The Access adapter reports inbound provider kinds, admitted pools, grants, trust
+and endpoint setup; token controls retain their existing permission gate.
+Configuration remains in deployment code. The UI mutates only credentials,
+OAuth connections and client tokens through the existing routes.
+
+## Source and tests
+
+The contract type is [contract.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/contract.ts).
+[UI routes](https://github.com/zackbart/connecta/blob/main/src/routes/ui.ts) and
+[UI implementation](https://github.com/zackbart/connecta/blob/main/src/ui.ts)
+serve the authenticated shell and data. The browser lives in
+[src/operator-ui](https://github.com/zackbart/connecta/tree/main/src/operator-ui).
+[UI tests](https://github.com/zackbart/connecta/blob/main/test/ui.test.ts),
+[credential-route tests](https://github.com/zackbart/connecta/blob/main/test/ui-credentials.test.ts),
+[config snapshot tests](https://github.com/zackbart/connecta/blob/main/test/describe-config.test.ts),
+and [browser flows](https://github.com/zackbart/connecta/blob/main/test/browser/operator-ui.spec.ts)
+defend filtering and behavior. Use [Operator UI tests](./operator-tests.md)
+for the browser state matrix and Linux snapshot procedure.

package/documentation/provider-auth-migration.md

@@ -0,0 +1,307 @@
+# Provider auth migration
+
+Use this upgrade guide when moving a Stripe, Notion, Vercel, or Cloudflare
+deployment from 0.30 to 0.31, where `auth` selects each provider's
+implementation ([#801](https://github.com/zackbart/connecta/issues/801)).
+The [0.31.0 release notes](https://github.com/zackbart/connecta/blob/main/release-notes/0.31.0.md) summarize the change.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
+version changes; [integrating services](./integrating.md) covers new connectors.
+
+A dual provider requires `auth`. `{ type: "oauth" }` connects the vendor's
+hosted MCP server, OAuth only. A key type connects Connecta's REST connector
+with an operator-managed credential. There is no default, and one connector id
+uses one implementation: configure two ids for both. The
+[decision record](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)
+explains why.
+
+## Stripe
+
+Stripe's hosted MCP server stops accepting secret keys and untagged
+restricted keys on 2026-10-31; Stripe still documents agent-tagged restricted
+keys for it. Connecta's hosted Stripe connection is OAuth only either way, and
+every key, tagged or not, uses the REST connector. Every `stripe()` call must
+now name `auth`:
+
+```ts
+connectors: [
+  stripe("stripe", {
+    purpose: "Organization billing",
+    auth: { type: "oauth" },
+  }),
+  stripe("stripe_live", {
+    purpose: "Live billing",
+    auth: { type: "apiKey" },
+    mode: "production",
+  }),
+  stripe("stripe_sandbox", {
+    purpose: "Rehearsal",
+    auth: { type: "apiKey" },
+    mode: "sandbox",
+  }),
+  stripe("stripe_merchant", {
+    purpose: "One connected merchant",
+    auth: { type: "apiKey" },
+    mode: "production",
+    connectedAccount: "acct_…",
+  }),
+];
+```
+
+| 0.30 configuration                               | Now                                                                                                                  |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| No `auth`, or `auth: { type: "oauth" }`          | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, guide conventions, and grant.                            |
+| `auth: { type: "headers", headers }` with `mode` | `auth: { type: "apiKey" }` with `mode`. Paste the key into the connection in the operator UI; literal keys are gone. |
+| `auth: { type: "credential" }` with `mode`       | `auth: { type: "apiKey" }` with `mode`. A key stored for the same connector id carries over; run its Test action.    |
+| `connectedAccount` with `headers` auth           | `connectedAccount` with `auth: { type: "apiKey" }`; it now works with an operator-managed key.                       |
+| `mode` or `connectedAccount` with OAuth          | Refused by name at construction, as before.                                                                          |
+
+The key connector keeps Stripe's tool names (`stripe_api_search`,
+`stripe_api_details`, `stripe_api_read`, `stripe_api_write`,
+`get_stripe_account_info`, and `get_balance_summary`) with Connecta's own
+contracts: search finds operations in a pinned API index, every call is
+checked against that index before it is sent, results arrive as
+`{ status, data, page? }`, and POST writes send the caller's `idempotencyKey`
+or a generated one as `Idempotency-Key` and return it (DELETE sends none).
+Every request, v1 and v2, sends `Stripe-Version: 2026-09-30.endive`, the
+version of the pinned index, whatever the account's default API version, so
+response shapes and accepted parameters follow that version. Check fields
+your programs rely on with `stripe_api_details`.
+A key whose `sk_live_`/`rk_live_` or `sk_test_`/`rk_test_` prefix contradicts
+`mode` is refused before any request. Organization keys (`sk_org_…`) need a
+`Stripe-Context` header the connector does not send; use an account key.
+
+Lost on the key path: natural-language Sigma (`stripe_analytics`), metrics,
+documentation search, the implementation planner, reports, and feedback exist
+only on the hosted OAuth connection. Programs calling those tools on a key
+connector need an OAuth connector beside it. The
+[Stripe skill](https://github.com/zackbart/connecta/blob/main/src/providers/stripe/SKILL.md)
+owns the conventions for both.
+
+## Notion
+
+Every `notion()` call must now name `auth`. 0.30 defaulted to hosted MCP and
+selected the REST interface with `surface: "api"`; `surface` is gone:
+
+```ts
+connectors: [
+  notion("notion", { purpose: "Workspace content as the signed-in user", auth: { type: "oauth" } }),
+  notion("notion_bot", { purpose: "Internal integration content", auth: { type: "token" } }),
+]
+```
+
+| 0.30 configuration                                                                                                                        | Now                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| No `surface`, or `surface: "mcp"`                                                                                                         | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, grant, and optional `callAdmission`.                     |
+| `surface: "api"`                                                                                                                          | `auth: { type: "token" }`. The integration token stored for the same connector id carries over; run its Test action. |
+| `credentialLabel` or `defaultPageSize`                                                                                                    | Token only, as before. Under OAuth they are refused by name at construction.                                         |
+| `integration_search`, `_get_page`, `_get_page_content`, `_get_data_source_schema`, `_query_data_source`, `_create_page`, `_append_blocks` | Unchanged names and contracts. `integration_append_blocks` also takes `checklist`.                                   |
+| `integration_get_database`                                                                                                                | `notion_api_read` `GET /v1/databases/{database_id}`.                                                                 |
+| `integration_get_page_property`                                                                                                           | `notion_api_read` `GET /v1/pages/{page_id}/properties/{property_id}`; `truncated_properties` names it.               |
+| `integration_list_users`, `integration_get_self`                                                                                          | `notion_api_read` `GET /v1/users` or `GET /v1/users/me`.                                                             |
+| `integration_list_comments`, `integration_add_comment`                                                                                    | `notion_api_read` `GET /v1/comments`; `notion_api_write` `POST /v1/comments`.                                        |
+| `integration_update_page_properties`, `integration_trash_page`                                                                            | `notion_api_write` `PATCH /v1/pages/{page_id}` with `properties`, or `in_trash` to trash or restore.                 |
+
+The token connector gains Connecta's generic REST tools over Notion's pinned
+API index (`notion_api_search`, `notion_api_details`, `notion_api_read`,
+`notion_api_write`), so every public operation is reachable with the bot's
+token: views, page moves and Markdown, meeting notes, custom agents and
+sessions, file uploads by `external_url`, and data source changes. Every call
+is checked against the index before it is sent, and results arrive as
+`{ status, data, page? }`. The read-only POST queries (search, data source,
+meeting notes, agents, sessions, and session events) use `notion_api_read`;
+`page.in: "body"` says their cursor goes back in the body. Notion's OAuth token
+endpoints and multipart file sends are refused. The 0.29 reconciliation table
+and the `surface: "api"` complement rules no longer apply to Notion.
+
+Lost per mode. A token connector acts as the integration bot, never as a
+person, and has none of the hosted MCP's search across connected apps, page
+duplication, team and skill search, attachment downloads, or page-to-skill
+conversion. An OAuth connector acts as the user, and has none of the generic
+REST tools or the `integration_*` projections and authoring helpers. Configure
+both ids when a deployment needs both; a failed call is never retried on the
+other. The [Notion skill](https://github.com/zackbart/connecta/blob/main/src/providers/notion/SKILL.md)
+owns the conventions for both.
+
+## Vercel
+
+Every `vercel()` call must now name `auth`. `surface` is gone, and so are the
+0.29 ownership rules that made the REST complement refuse whatever the hosted
+server also covered: each implementation is complete on its own.
+
+```ts
+connectors: [
+  vercel("vercel", { purpose: "Deployment diagnosis", auth: { type: "oauth" } }),
+  vercel("vercel_rest", { purpose: "Production apps", auth: { type: "token" }, teamId: "team_…" }),
+]
+```
+
+| 0.30 configuration                                                    | Now                                                                                                                                                           |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `surface`, or `surface: "mcp"`                                     | `auth: { type: "oauth" }`. Same endpoint, reviewed catalog, and grant.                                                                                        |
+| `surface: "api"` with `teamId` or `baseUrl`                           | `auth: { type: "token" }` with the same options. A token stored for the same connector id carries over; run its Test action.                                  |
+| `defaultPageSize`                                                     | Removed (it already had no effect). Pass `limit` in `query`, and follow `page.next` as `page.param`.                                                          |
+| `teamId` or `baseUrl` with OAuth                                      | Refused by name at construction.                                                                                                                              |
+| `vercel_api_get`, `vercel_api_mutate`                                 | `vercel_api_read` and `vercel_api_write`: `query` is a JSON object, not name/value pairs, and `teamId: null` replaces `personalAccount: true`.                |
+| `verify_project_domain`, `remove_project_domain`, `delete_deployment` | `vercel_api_write` with the operation from `vercel_api_search`, such as `DELETE /v13/deployments/{id}`.                                                       |
+| `vercel_api_upload` with any path and headers                         | `vercel_api_upload` on octet-stream operations in the index (`POST /v2/files`, project avatars, Remote Cache artifacts); Connecta computes `x-vercel-digest`. |
+
+The token connector serves `vercel_api_search`, `vercel_api_details`,
+`vercel_api_read`, and `vercel_api_write` over Vercel's OpenAPI document,
+pinned by content hash because Vercel does not version it. Every call is
+checked against the pinned index before it is sent, and results arrive as
+`{ status, data, page? }`. It adds `list_teams`, the value-safe environment
+variable tools (`list_project_env_vars`, `upsert_project_env_var`,
+`update_project_env_var`, `delete_project_env_var`),
+`get_deployment_build_logs` (build events, never following), `get_runtime_logs`
+(the runtime stream, stopped after `waitMs` or `maxRows`), and
+`vercel_api_upload`.
+
+Value safety follows a reviewed table (`src/providers/vercel/value-safety.ts`).
+Every operation whose response schema in the pinned spec may carry a credential
+or a stored secret has a verdict: refused (credential minting, Connect
+authorization, decrypted environment values, Global Config items and tokens,
+domain transfer codes, KMS signing), redacted at reviewed field paths
+(environment values, protection-bypass secrets, deploy hook URLs, drain and
+webhook headers and destination URLs beyond their origin, external route and
+redirect destinations beyond their origin, the args and values of every header,
+cookie, and query rule (route transforms and conditions, firewall conditions), team invite codes, synced Global Config items, URL credentials, and signing
+secrets, including the one a new webhook or drain returns at creation), or
+safe with a reason. Detection reads field names, field descriptions, and
+operation descriptions, so a project transfer request (whose code lets another
+team claim the project) is refused too. A test fails when
+a newly flagged operation has no verdict. A key-name heuristic covers every
+other body as defense in depth. Secret-family failures carry fixed messages
+instead of Vercel's text, and every other reviewed operation also withholds that
+text ([value safety](#value-safety-on-every-key-connector)). Read or rotate withheld secrets in the Vercel
+dashboard. A domain move-out is refused because its answer is a transfer token.
+
+Lost on the token path: documentation search, runtime error clusters, toolbar
+threads, agent runs, web analytics summaries, purchase quotes and guided
+purchases, `deploy_to_vercel`, and access grants for protected URLs exist only
+on the hosted OAuth connection. Programs calling those tools need an OAuth
+connector beside the token connector.
+
+The hosted connection now lists `filter_project_envs`, `get_project_env`,
+`create_project_env`, and `edit_project_env`, which 0.29 hid. The two reads can
+return decrypted values, so they are reviewed as writes and the pool trust
+policy gates them. Vercel admits only reviewed and approved MCP clients to its
+hosted server; if authorization is refused for that reason, the deployment
+needs Vercel's approval or a token connector. The
+[Vercel skill](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/SKILL.md)
+owns the conventions for both.
+
+## Cloudflare
+
+Every `cloudflare()` call must now name `auth`. 0.30 defaulted to hosted MCP
+when `surface` was omitted; that default is gone with `surface` itself:
+
+```ts
+connectors: [
+  cloudflare("cloudflare", {
+    purpose: "Estate changes",
+    auth: { type: "oauth" },
+  }),
+  cloudflare("cloudflare_api", {
+    purpose: "Production DNS and Workers",
+    auth: { type: "apiToken" },
+    accountId: "<account id>",
+    zoneId: "<zone id>",
+    pin: { accountIds: ["<account id>"] },
+  }),
+  cloudflare("cloudflare_legacy", {
+    purpose: "Legacy zones behind a user key",
+    auth: { type: "globalApiKey" },
+    pin: { zoneIds: ["<zone id>"] },
+  }),
+];
+```
+
+| 0.30 configuration                                   | Now                                                                                                                                      |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| No `surface`, or `surface: "mcp"`, with OAuth        | `auth: { type: "oauth" }`. Same endpoint, catalog, and grant.                                                                            |
+| `surface: "mcp"` with `auth: { type: "credential" }` | `auth: { type: "apiToken" }`: bearer tokens no longer reach `mcp.cloudflare.com`. A token stored for the same connector id carries over. |
+| `surface: "api"` (API token)                         | `auth: { type: "apiToken" }` with the same `accountId`, `zoneId`, `baseUrl`, and `maxConcurrency`.                                       |
+| `surface: "api"`, `authentication: "globalApiKey"`   | `auth: { type: "globalApiKey" }` plus `pin: { accountIds, zoneIds }`, or `unpinned: true` to accept the user's whole estate.             |
+| `credential` override                                | Removed; the credential slot's copy is fixed.                                                                                            |
+| `callAdmission` with hosted MCP                      | Unchanged under `auth: { type: "oauth" }`.                                                                                               |
+
+The key connector is complete on its own. JSON writes that 0.30 refused on an
+API token (they belonged to hosted `execute`) go through
+`cloudflare_api_write`, checked against a pinned API index before they are
+sent. The 23 hand-written reads (`get_zone`, `list_dns_records`,
+`list_r2_objects`, `list_pages_deployments`, and the rest) are replaced by
+`cloudflare_api_read` on the same paths; results are Cloudflare's own
+`result`, unprojected, so programs pass `select` instead of reading the old
+projections. `list_accounts`, `list_zones`, and `cloudflare_api_upload` keep
+their names (upload now takes `parts` for multipart); `verify_api_token` and
+`verify_global_api_key` become `verify_credential`; `cloudflare_api_get` and
+`cloudflare_api_mutate` become `cloudflare_api_read` and `cloudflare_api_write`.
+`graphql_query` is new.
+
+Credentials stay in the dashboard. The key connector refuses every operation
+that mints, rotates, or returns a credential (API tokens, Access service
+tokens, R2 temporary credentials, signing keys, direct-upload URLs, deploy
+hooks) and redacts stored secrets on every result. A pinned connector refuses
+operations that name no account or zone unless they are reviewed safe, such
+as `/certificates` and `/memberships/{id}`.
+
+Read-only pools: hosted `execute` is always a write, even for a program that
+only reads, so a read-only pool on an OAuth connector reaches only `search`.
+Use an API-token connector for read-only API access.
+
+Lost on each path. OAuth has no index validation, named tools, GraphQL tool,
+upload tool, or pin; Cloudflare's OAuth grant is the only boundary. A key has
+no hosted `search` over Cloudflare's live OpenAPI document; the pinned index
+replaces it and `providers:check` reports when it falls behind. A Global API
+Key cannot reach R2, which accepts API tokens only. The
+[Cloudflare skill](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/SKILL.md)
+owns the conventions for both.
+
+## Value safety on every key connector
+
+All four key connectors now share one value-safety mechanism: a reviewed
+table per vendor over every operation the detector flags in the pinned spec,
+one redaction pass on every result, and one error policy
+([architecture](./architecture.md#value-safety-for-rest-vendors)). Results
+lose fields they returned before. A `"[redacted]"` value is never the real
+one; read or rotate withheld secrets in the vendor's dashboard.
+
+- **Stripe** refuses operations that hand out a credential: ephemeral keys,
+  Terminal connection tokens, account links, Express login links, account and
+  customer sessions, billing portal sessions, file link creation, Financial
+  Connections session creation, and the meter event session. Results redact
+  client secrets (PaymentIntents, SetupIntents, Checkout and Identity
+  sessions, Sources, Financial Connections, invoice confirmation secrets),
+  webhook and event destination signing secrets, Apps secret payloads,
+  app-install authorization codes, Terminal Wi-Fi passwords, forwarded
+  request header values, and Issuing card numbers and CVCs; webhook, file
+  link, and pre-signed import URLs keep only their scheme and host, and the
+  rules follow each object into expansions, lists, and events (an expanded
+  File's links, an event's `previous_attributes`). Identity verification
+  URLs are unchanged. A Checkout Session's URL is returned whole only for a
+  guest payment session (`mode: "payment"`, no `customer` or
+  `customer_account`, no customer creation, no saved payment method options);
+  any other session returns only its scheme and host, because its page can
+  show, reuse, or remove a customer's saved payment methods. v2 account
+  links and Terminal onboarding links are refused too. Issuing `number` and
+  `cvc` expansions are refused on every Issuing path, not only cards.
+  Failures of credential-bearing operations keep Stripe's type, code, and
+  param but not its message. Create client-side sessions and links from your
+  own server code.
+- **Notion** results withhold the signature, credential, and security-token
+  parameters of pre-signed file URLs, so a returned file URL no longer
+  downloads; credential-named fields, including database properties named
+  like credentials, read as `"[redacted]"`. Failures of the OAuth, file
+  upload, bot user, and agent operations keep Notion's code but not its
+  message.
+- **Vercel** replaces environment values with `"[redacted]"` instead of
+  dropping the field, and withholds Vercel's error text for every reviewed
+  operation and every operation whose request takes a credential-named
+  field, not only secret families. Audit event invite codes, integration
+  drain headers, and route header values are redacted too.
+- **Cloudflare** redacts Hyperdrive database passwords, RealtimeKit storage
+  credentials, transform-rule header values, and dispatch binding values,
+  and reduces notification, RealtimeKit, and data security webhook
+  destinations to their scheme and host. A credential-named field now loses
+  its whole value, not only its strings (a `cookies` list, a variable named
+  `API_KEY`).

package/documentation/provider-migration-0.29.md

@@ -1,11 +1,21 @@
 # Notion, Vercel and Cloudflare migration for 0.29
 
+Use this upgrade guide for an existing deployment.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
+version changes; [integrating services](./integrating.md) covers new connectors.
+[The agent index](./README.md) routes package maintenance separately.
+
 This is the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709).
 Deploy it with the consolidated 0.29 release, not while the rework is in progress.
 BePresent and One&Many use Notion and Cloudflare; their actual grants and
 connector ids must be checked in deployment configuration before that release.
 The provider audit establishes available auth modes, not production OAuth grants.
 
+Cloudflare's part of this guide is superseded: `cloudflare()` now selects its
+implementation by `auth` and its key connector is complete on its own. Follow
+the [provider auth migration](./provider-auth-migration.md#cloudflare) for
+Cloudflare; the Cloudflare lines below record the 0.29 transition only.
+
 All three providers now default to hosted MCP. `surface: "api"` explicitly
 selects a REST complement and accepts only its API-specific options. The old
 Vercel/Cloudflare API modes are no longer complete alternatives; Notion retains
@@ -22,6 +32,11 @@ connectors: [
 ]
 ```
 
+Notion has since moved to auth-selected implementations: `surface` is gone,
+and `auth: { type: "oauth" }` or `{ type: "token" }` selects hosted MCP or the
+REST connector. Upgrade with the
+[provider auth migration](./provider-auth-migration.md#notion); the rest of
+this paragraph records the 0.29 rules.
 Notion preserves headless/internal-integration capabilities. Add explicit
 `surface: "api"` to retain that identity and migrate old REST names to
 `integration_*`, for example `search` to `integration_search`, `create_page`
@@ -45,7 +60,9 @@ include `cf-r2-jurisdiction` only when the bucket needs it. This remains a write
 `execute` remains a write even when its program only calls GET.
 Trusted pools may execute writes; read-only pools use direct host-approved writes.
 
-For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
+Vercel's `surface` and ownership rules were later replaced: `auth` now selects
+the implementation. See the [provider auth migration](./provider-auth-migration.md#vercel).
+The 0.29 Vercel guidance follows for history. For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
 domain listing/adding, deployment cancellation and file uploads to live MCP
 schemas, and keep the independently authorized REST complement for value-safe
 project environment variables (including `upsert: false` create-only writes), domain verification/removal and deployment
@@ -54,7 +71,7 @@ category. Raw hatches refuse all published REST counterparts, including project
 creation/update. Do not copy REST argument
 shapes into vendor tools, even when a tool name is unchanged.
 
-The per-provider tables map every removed name and explain retained API tools:
-[Notion](https://github.com/zackbart/connecta/blob/main/src/providers/notion/reconciliation.md),
-[Vercel](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/reconciliation.md), and
-[Cloudflare](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/reconciliation.md).
+Every provider's table is retired with `surface`; the provider auth migration
+maps their names ([Notion](./provider-auth-migration.md#notion),
+[Cloudflare](./provider-auth-migration.md#cloudflare),
+[Vercel](./provider-auth-migration.md#vercel)).