@zackbart/connecta 0.29.0 → 0.30.0

package/documentation/deploying.md

@@ -0,0 +1,146 @@
+# Deploying Connecta
+
+Use this guide when creating or maintaining a deployment. For changes to the
+Connecta package itself, follow [repository policy](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
+For work through an already connected endpoint, use [Operating an endpoint](./operating.md).
+[All agent routes](./README.md) are in the index.
+
+## Choose a deployment
+
+| Platform           | Runnable instructions                                                                     | Required runtime and state                                                   |
+| ------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Node               | [Node template](../templates/node/README.md)                                              | Node 22.13 or later, QuickJS peer, one SQLite file                           |
+| Docker             | [Container setup in the same Node template](../templates/node/README.md#run-it-in-docker) | Same source and config, persistent named volume                              |
+| Cloudflare Workers | [Worker example](../examples/worker/README.md#deploy)                                     | Workers Paid plan, Worker Loader binding, one D1 database, Cloudflare Access |
+
+These are the two deployment shapes. Docker packages the Node project.
+Templates and their configuration files own the full runnable steps and
+environment-variable names; follow them rather than rebuilding their setup
+from the contract reference.
+
+## Start on Node
+
+Create a new deployment directory with the CLI. `init` refuses an existing
+path and pins the generated project's Connecta dependency to the CLI version:
+
+```sh
+npx @zackbart/connecta init my-connecta
+cd my-connecta
+npm install
+npm run --silent provision-token -- "local-machine"
+# Save the returned cta_ token privately. It is shown only once.
+npm start
+```
+
+The client connects to `http://localhost:8787/mcp` with
+`Authorization: Bearer <returned-cta-token>`. The generated project always
+installs `accessTokens(storage)`. An empty database admits no MCP caller even
+though `/health` works. `CONNECTA_TOKEN` is only a client/doctor variable;
+it never configures server authentication. The local commands read the process
+environment and do not load `.env`; Docker Compose does.
+
+Edit `src/connecta.config.ts` for connectors, public URL, auth, identity rules,
+and optional modules. `src/index.ts` only constructs and starts the deployment.
+Follow the [template README](../templates/node/README.md) for storage paths,
+backups, Docker provisioning, secrets, and optional modules. Run the deployment's
+`npm run typecheck` after configuration changes.
+
+## Start on Workers
+
+Follow the [Worker example](../examples/worker/README.md#deploy) to create D1,
+set secrets, configure `PUBLIC_URL` and `LOADER`, and deploy with Wrangler.
+When copying it into a separate repository, follow
+[the separate-project installation](../examples/worker/README.md#copied-into-its-own-repository)
+and pin Connecta's exact version. The optional `@cloudflare/codemode` peer
+must be installed for the Worker executor.
+
+Attach Cloudflare Access to the Worker destination. Interactive MCP clients
+need Managed OAuth, Dynamic Client Registration, and the documented redirect
+allowlist. Machines need Access service headers at the edge plus a stored
+`cta_` bearer inside Connecta; service identity alone is refused. Keep
+`enable_request_signal`, construct Connecta once per isolate, and pass `ctx`
+through to `fetch`. The example owns those details and
+[the machine-token procedure](../examples/worker/README.md#machine-tokens).
+
+## Compose capabilities and access
+
+Both configurations use `defineConfig((env) => …)` and a required executor.
+[Integrating services](./integrating.md) explains the `connectors` array.
+Configuration selects optional factories through explicit slots:
+
+| Slot           | Factory/import                                                       | Purpose                                            |
+| -------------- | -------------------------------------------------------------------- | -------------------------------------------------- |
+| `ui`           | `operatorUi()` from `@zackbart/connecta/ui`                          | Operator pages and scoped config inspection        |
+| `vault`        | `encryptedCredentialVault()` from `@zackbart/connecta/credentials`   | Encrypted operator-managed credentials             |
+| `activity`     | `activityHistory()` from `@zackbart/connecta/activity`               | Payload-free history over the platform's SQL store |
+| `auth`         | Clerk or Cloudflare Access from `@zackbart/connecta/auth/*`          | Interactive inbound authentication                 |
+| `accessTokens` | `accessTokens(storage)` from `@zackbart/connecta/auth/access-tokens` | Stored machine-token authentication                |
+
+Omitting an optional module leaves its implementation inactive. Invalid or
+unknown configuration refuses construction; do not catch it and silently
+fall back. [Configuration](./architecture.md#configuration) owns validation
+and `describeConfig()`, and [optional modules](./architecture.md#optional-deployment-modules)
+owns their composition contracts.
+
+Enable `encryptedCredentialVault(storage, key)` before persisting downstream
+OAuth credentials. Without a sealing vault, OAuth grants are stored as plaintext.
+The platform templates describe the base64 32-byte encryption key. Keep it
+outside the database and source control, and preserve it across upgrades.
+[OAuth state at rest](./auth.md#downstream-oauth-state-at-rest) owns sealing and
+existing-record migration.
+
+One deployment serves one tenant and may admit several people. Node uses Clerk
+for human auth; Access is Workers-only. Keep credential administration,
+personal connection, token management, and activity access explicit.
+[Auth](./auth.md#principals-visibility-and-operators) owns identity and grants;
+[Clerk setup](./auth.md#clerk-oauth-tokens-and-operator-sessions) owns resource-bound
+tokens and `aud_claim_enabled`. A person's operator session is not an MCP token.
+
+Root and named pools default to `read-only`. A `trusted` pool allows writes
+inside programs and marks `execute_code` as a write. Host approval remains the
+host's decision. Pool membership intersects the caller's grants; it never
+widens them. See [pools](./auth.md#pools) before changing trust.
+
+## Verify and diagnose
+
+With the deployment running, replace the placeholder with its saved client
+token and run doctor:
+
+```sh
+CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787
+```
+
+Doctor checks health, the required executor, and the current six-tool set.
+For a Worker protected by Access, follow the example's doctor credentials
+and service-header setup. If the operator UI is enabled, authenticated
+`connecta doctor --config --url <public-url>` prints the caller-scoped
+configuration snapshot as JSON. It runs no diagnostic program and prints no
+raw HTTP failure body. [Operator UI](./operator-ui.md) describes the returned
+configuration, live facts, and permission rules.
+
+Health success alone does not prove a client can authenticate or reach an
+integration. Check client connection and a bounded read through a chosen
+connector; resolve credentials using [authorization recovery](./meta-tools.md#authorization-recovery).
+
+## Upgrade an existing deployment
+
+Bump the exact package pin, read the [changelog](../CHANGELOG.md) for every
+intervening release, and apply the relevant migration before startup. `init`
+does not merge changes into an existing deployment.
+
+- [Managed tokens from v0.23](./auth.md#managed-client-tokens-and-upgrading-from-v023) keep their secrets when storage, namespaces, and grants are retained. Replace the old boolean config with `accessTokens(storage)`; machine tokens gain no operator authority.
+- [Node storage from 0.28](../templates/node/README.md#storage) uses `connecta migrate-state` to copy the JSON state into SQLite. Activity JSONL is not imported.
+- [Worker storage from 0.28](../examples/worker/README.md#upgrading-from-028) copies KV into D1 with a one-shot migration.
+- [Notion, Vercel, and Cloudflare for 0.29](./provider-migration-0.29.md) change defaults and retained API tool names.
+- [Executor wiring](./code-mode.md#deploy-time-capability) requires branded shipped executors or a self-managed custom executor.
+
+## Implementation and evidence
+
+Check the [CLI](https://github.com/zackbart/connecta/blob/main/bin/connecta.mjs),
+[Node configuration](../templates/node/src/connecta.config.ts), and
+[Worker configuration](../examples/worker/src/connecta.config.ts) when changing
+setup. [Deployment-shape tests](https://github.com/zackbart/connecta/blob/main/test/deployment-shapes.node.test.ts),
+[config tests](https://github.com/zackbart/connecta/blob/main/test/config.test.ts),
+and [package smoke](https://github.com/zackbart/connecta/blob/main/scripts/check-package.mjs)
+check the deployment and published package boundaries. Repository verification
+requirements remain in AGENTS.md.

package/documentation/integrating.md

@@ -0,0 +1,159 @@
+# Integrating services
+
+Use this guide to add a connector to deployment configuration. To implement a
+new maintained provider in Connecta itself, follow the repository's
+[add-provider skill](https://github.com/zackbart/connecta/blob/main/.claude/skills/add-provider/SKILL.md)
+and [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md).
+[All agent routes](./README.md) are in the index.
+
+## Choose a connector
+
+| Need                             | Configuration path                                | Check before using                                                                    |
+| -------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| A maintained integration         | Its `@zackbart/connecta/providers/<name>` factory | Provider `SKILL.md`, options, auth ownership, supported tools                         |
+| Another hosted remote MCP server | `remoteMcp()` from the root package               | Endpoint, authentication, current catalog, and read/write annotations                 |
+| A selected HTTP API capability   | `api()` from the root package                     | Input/output schemas, explicit read/write hints, bounded handler, credential handling |
+
+All produce connectors in the deployment's `connectors` array and use the same
+registry enforcement, caller grants, result bounds, and activity paths. There
+is no runtime installation or registration. Keep connector IDs unique and
+stable because they prefix canonical `<connectorId>.<toolName>` addresses.
+
+## Maintained integrations
+
+Import a provider individually. For example, Linear requires an explicit
+choice of its downstream endpoint:
+
+```ts
+import { linear } from "@zackbart/connecta/providers/linear";
+
+const tracker = linear("tracker", {
+  purpose: "Engineering issues in our workspace",
+  access: "read-only",
+});
+// Add tracker to the deployment's connectors array.
+```
+
+Linear defaults to OAuth; its read-only endpoint requests only the downstream
+read scope. That is separate from Connecta pool trust. Read the
+[Linear skill](https://github.com/zackbart/connecta/blob/main/src/providers/linear/SKILL.md)
+and [factory options](https://github.com/zackbart/connecta/blob/main/src/providers/linear/index.ts)
+for API-key framing, workspace instructions, and admission choices.
+
+The [human README](../README.md#what-you-can-do-with-it) lists available
+integrations. Each [provider folder](https://github.com/zackbart/connecta/tree/main/src/providers)
+contains its scoped guide, options, tests, fixtures, and review data. Prefer
+that guide to general assumptions about a service's API. Google Workspace
+providers require administrator-managed domain-wide delegation and a deployment
+mapping from admitted identity to the downstream account; a request must not
+choose its own account. Gmail never sends mail, and Drive never permanently
+deletes files.
+
+Notion, Vercel, and Cloudflare default to hosted MCP. Their explicit
+`surface: "api"` choices retain selected REST capabilities, with Notion's
+internal-integration identity preserved. To use both, configure distinct IDs
+and independent credentials. Read the [0.29 migration guide](./provider-migration-0.29.md)
+and its provider reconciliation tables for retained and removed names.
+
+## Another remote MCP server
+
+Declare its endpoint and intended auth mode. This fragment uses a server-stored
+credential slot; replace the illustrative URL with the real endpoint:
+
+```ts
+import { remoteMcp } from "@zackbart/connecta";
+
+const service = remoteMcp("service", {
+  url: "https://mcp.example.com/mcp",
+  description: "Our team's hosted service",
+  auth: { type: "credential" },
+});
+// Add service to connectors. Configure the vault and permitted operators
+// before supplying its credential through the operator UI.
+```
+
+Credential auth defaults to an `Authorization: Bearer` header. Choose framing
+from the downstream contract, not from its HTTP API's convention. Remote auth
+also supports OAuth, static headers, and request-local token resolution. Use
+[shared and personal auth](./auth.md#shared-and-personal-auth),
+[client registration](./auth.md#downstream-oauth-client-registration), and
+[request-local tokens](./auth.md#request-local-downstream-bearer-tokens)
+for those cases. Secrets belong in deployment secret storage or the vault,
+not source literals.
+
+Remote catalogs evolve. Discovery, direct calls, and program calls all enforce
+classification against the current catalog. Missing or contradictory read hints
+fail closed as writes. `classify` can supply a reviewed per-tool verdict;
+schema changes can invalidate a reviewed read. Exact deployment classification
+overrides take precedence. See
+[reviewed classification](./architecture.md#providers-and-reviewed-classification)
+for precedence, schema digests, and `unlisted: "hide"`. Review the behavior
+before declaring a read, and do not use classification to bypass provider target
+scopes or caller grants.
+
+## A hand-written HTTP capability
+
+Define only the operations the deployment needs. Every `api()` tool needs a
+nonempty description and explicit `readOnlyHint`. This local time tool matches
+the shape used by the deployment templates:
+
+```ts
+import { api } from "@zackbart/connecta";
+
+const time = api("time", {
+  description: "Time, current timestamp",
+  tools: [{
+    name: "get_now",
+    description: "Return the current time as an ISO 8601 timestamp.",
+    inputSchema: { type: "object", properties: {} },
+    outputSchema: {
+      type: "object",
+      properties: { now: { type: "string" } },
+      required: ["now"],
+    },
+    annotations: { readOnlyHint: true },
+    handler: async () => ({ now: new Date().toISOString() }),
+  }],
+});
+```
+
+For an HTTP handler, use its supplied `ctx.fetch` to register outgoing secrets
+for redaction, pass the request signal, and bound any pagination or fanout.
+Read declared credential slots through `ctx.credential`; do not return their
+values. With a declared static OAuth configuration, use `ctx.oauth.fetch`,
+which binds the grant to configured API origins and manages authentication.
+`api()` refuses simultaneous `oauth` and `credential` declarations.
+[Downstream OAuth on api()](./auth.md#downstream-oauth-on-api) owns a concrete
+HTTP example and the client setup contract.
+
+Mark every side-effecting tool `readOnlyHint: false`. On read-only endpoints
+writes use `call_destructive_tool`; trusted programs may write within their
+grants. Host approval is independent of tool definition. Use declared output
+schemas when known; runtime observations cannot replace them.
+
+## Separate ownership from visibility
+
+`authScope: "shared"` uses deployment-owned downstream auth; `"personal"` uses
+the admitted principal's partition. Visibility is a different decision,
+controlled by identity and pool grants. A personal connector must not close
+over a shared secret or derive its owner from arguments. Remote MCP refuses
+literal header credentials with personal scope. Review
+[principals and grants](./auth.md#principals-visibility-and-operators) and
+[management permissions](./auth.md#management-permissions) before exposing a
+new integration or its authentication controls.
+
+After editing configuration, run the deployment's typecheck and doctor, then
+perform a bounded read. Add negative checks for target restrictions and writes
+when authoring a handler or provider. Follow repository verification policy
+when changing package code.
+
+## Implementation and evidence
+
+Factory contracts live in [remote MCP](https://github.com/zackbart/connecta/blob/main/src/connectors/remote-mcp.ts),
+[API connector](https://github.com/zackbart/connecta/blob/main/src/connectors/api-connector.ts),
+and [provider construction](https://github.com/zackbart/connecta/blob/main/src/provider.ts).
+[Remote tests](https://github.com/zackbart/connecta/blob/main/test/remote-mcp.test.ts),
+[API tests](https://github.com/zackbart/connecta/blob/main/test/api-connector.test.ts),
+[provider contracts](https://github.com/zackbart/connecta/blob/main/test/provider-contracts.test.ts),
+and [classification tests](https://github.com/zackbart/connecta/blob/main/test/classified-decorators.test.ts)
+check shared behavior. Provider-specific tests remain beside each provider.

package/documentation/meta-tools.md

@@ -9,6 +9,21 @@ This guide is the contract an MCP client sees. The in-program `connecta.*` API
 those tools imply belongs to [code mode](./code-mode.md); inbound identity and
 credential administration belong to [auth](./auth.md).
 
+## Task routes
+
+Start with [Operating an endpoint](./operating.md) for a workflow, or
+[the agent index](./README.md) for setup and repository tasks. This reference
+owns the top-level MCP contract; it does not require reading the core internals.
+
+| Task                                               | Sections                                                                                                                                    |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Choose a tool or construct its arguments           | [Six-tool table](#the-six-tools), [call routing](#routing-between-the-call-surfaces), [downstream input](#downstream-input-on-direct-calls) |
+| Find an operation and its schema                   | [Discovery context](#discovery-context), [TypeScript signatures](#typescript-signatures), [lexical discovery](#lexical-discovery)           |
+| Load provider instructions or native skills        | [Connector guides](#connector-guides-and-skills), [native extension](#native-skills-extension)                                              |
+| Interpret a direct response or page a large result | [Representation](#result-representation), [truncation](#truncated-direct-call-results), [paging](#paging-with-connectaresult)               |
+| Recover a refused or invalid call                  | [Authorization](#authorization-recovery), [routing](#routing-recovery), [arguments](#argument-recovery), [echo budgets](#echo-budgets)      |
+| Change the contract                                | [Source and tests](#source-and-tests), [guest API](./code-mode.md#verification)                                                             |
+
 ## The six tools
 
 Every deployment requires an executor, so `tools/list` is exactly six. No
@@ -19,9 +34,11 @@ never depends on the storage behind the deployment. There was an eighth,
 is annotated `readOnlyHint: true, destructiveHint: false` on a `read-only`
 endpoint, and `readOnlyHint: false, destructiveHint: true` on a `trusted`
 endpoint. Approval belongs to the host. Pool trust never changes connector
-visibility or tool grants. Every meta-tool advertises `outputSchema` for its
-structured content; raw downstream MCP content stays in `content`. Direct
-results declare `format: "json" | "text"`, and value mode places the value in `data`.
+visibility or tool grants. The four tools with structured-only success results
+advertise `outputSchema`. The two direct-call tools omit it because their default
+mode returns native `content`. Default-mode successes declare
+`_meta["dev.connecta/format"]: "json" | "text"`; value mode places the value in
+`data` and declares `format` in its complete result envelope.
 
 | Tool                    | Arguments                                                                                                                           | Returns                                                                                                       |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -72,9 +89,9 @@ a small sample for inspection before continuing in another call, which avoids
 repeated guesses at text formats and collection roots without restoring a
 mandatory discovery-only round trip. A one-time write can return the only copy
 of its result. Inspect and reduce the full value before a program returns, or
-use a direct `call_destructive_tool` result and page it with `connecta.result` after
-the write runs once. A program return has no page handle; sampling or slicing
-a write's output there can discard the answer.
+page the completed direct-call result or oversized program return with
+`connecta.result` after the write runs once. Sampling or slicing a write's output
+inside the program can still discard the answer.
 
 A `trusted` pool lets the same program discover and dispatch writes.
 A `read-only` pool refuses writes before validation or dispatch with
@@ -302,16 +319,25 @@ and [2026-07-28 Resources](https://modelcontextprotocol.io/specification/2026-07
 
 ## Result representation
 
-For object results, `structuredContent` is the canonical full-fidelity value and
+For structured envelopes, `structuredContent` is the canonical full-fidelity value and
 `content` carries the same complete value as compact JSON for clients that only
 consume text. Keeping both follows MCP's backwards-compatibility guidance;
 dropping the text copy waits on host-forwarding measurements showing supported
 clients do not need it. Direct-call failures set `isError: true` and carry the
 same `{ ok: false, error, durationMs, attempts }` envelope in both forms, whether
 `resultMode` is omitted, `"mcp"`, or `"value"`. Plain-text guidance stays
-text-only. A downstream MCP tool's successful native content blocks pass through
-in MCP result mode.
-When no text block exists and `structuredContent` is present, Connecta appends a
+text-only. Successful direct calls with `resultMode` omitted or `"mcp"` return
+their data only in `content`, with the downstream format in
+`_meta["dev.connecta/format"]`. They omit `structuredContent`, including on
+truncated results, so clients that prefer it cannot replace data or a preview
+with metadata. API results keep their serialized value; downstream MCP native
+content blocks pass through. Value-mode successes retain
+`{ ok: true, data, format, durationMs, attempts }` in both forms, including when
+`data` is a truncation notice. Direct-call tools advertise no `outputSchema`:
+MCP requires a tool declaring one to supply conforming structured results, which
+default native content does not promise.
+When downstream MCP content has no text block and downstream `structuredContent`
+is present, Connecta appends a
 text block carrying its compact JSON and then applies the same content size
 guard, which preserves structured-only results including `null`, arrays, and
 scalars. An existing text mirror stays unchanged; Connecta adds no second copy.
@@ -346,7 +372,14 @@ when it has one and `connecta:auth:<provider kind>` otherwise. Keep subject ids
 distinct within that namespace. An explicit principal is the fallback subject
 when neither id is supplied, and open deployments and auth providers that supply
 no identity share one partition. Each new stash also binds the principal,
-endpoint/pool, request origin, connector, tool, and classification. A page must
+endpoint/pool, request origin, connector, tool, and classification. Program-return
+stashes bind every contributing call, resource or skill read, and catalog lookup,
+including dependencies inherited from pages read during the run. Downstream skill and
+resource content requires a whole-connector grant on every page. Local guides and catalog
+metadata require the contributing connector or tool to remain visible, including
+caught catalog-load errors, unknown-tool failures, and recovery messages that
+list visible connectors or local guides. Returns with no downstream calls still
+require matching identity, origin and endpoint, current auth, and pool membership. A page must
 match those bindings and pass current auth, connector/tool grants, pool membership,
 and trust checks. Old entries lacking bindings fail closed. A random UUID is a
 handle, never an access grant.
@@ -361,6 +394,14 @@ including pre-upgrade single-key envelopes and raw-text entries. Offsets and `to
 original UTF-8 text, not the envelope. A supplied offset inside a character
 moves back to its start; page ends also align to character boundaries, and a
 page smaller than one character widens just enough to make progress.
+Decoding preserves every payload code point, including U+FEFF at the start of
+the result or any page, so joining pages reproduces the original UTF-8 text.
+Oversized raw text containing unpaired UTF-16 surrogates cannot use this UTF-8
+page/offset contract. It returns a successful truncation notice explaining that
+the text cannot be paged and suggesting a JSON value request for recovery,
+without a stash id, paging action, or altered preview.
+Completed writes remain successful and must not be repeated. JSON values still
+round-trip such strings through their escaped JSON representation.
 
 A per-call `timeoutMs` covers catalog resolution, admission, and connector
 execution under one deadline. The admission queue's own timeout may expire
@@ -373,7 +414,8 @@ retryable timeout while Connecta prepares its response.
 A `call_tool` or `call_destructive_tool` result over its cap — the connector's
 `maxResultBytes`, else `calls.maxResultBytes`, else 24,000 bytes — comes back
 as one text block. Its first line is the truncation notice, one line of compact
-JSON; everything after the first newline is the preview:
+JSON; everything after the first newline is the preview. `structuredContent`
+is absent, so the notice cannot hide the preview in clients that prefer it:
 
 ```text
 {"truncated":true,"resultId":"…","totalBytes":161420,"hint":"This write already ran: do not call it again to see its result. Bytes 0-24000 of 161420 follow; page the rest with connecta.result using nextAction.","nextOffset":24000,"nextAction":{"tool":"execute_code","arguments":{"code":"async () => await connecta.result(\"…\", { offset: 24000 })"}}}
@@ -437,13 +479,19 @@ When paging is available, `nextAction` is the page handle for either kind of cal
 the one next step connecta can spell out exactly, while a reduction is a
 program the agent has to write. `resultId` stays beside the exact `nextAction`,
 so the handle is actionable without copying an identifier out of prose.
-Program results and oversized discovery responses carry no such route: paging a
-program's return value is a refused shape, because a program can shrink
-anything before it returns.
+Oversized program returns carry the same route, with a bounded preview after
+its notice fields. They stash the compact JSON return and page from offset 0;
+see [program returns](./code-mode.md#results-and-projection). A run that completed
+any write gets the same no-repeat warning. Oversized discovery responses carry
+no paging route.
 
 ### Paging with connecta.result
 
-Paging is a guest operation, never another top-level tool. A direct call's
+Paging is a guest operation, never another top-level tool. Program calls also
+return handles for oversized values; see [program result limits](./code-mode.md#cancellation-and-limits).
+`connecta.result(handle, { page: 0 })` accepts those handles alongside direct
+result IDs. Numbered pages are zero-based and mutually exclusive with offset.
+Keep maxBytes fixed while incrementing pages. A direct call's
 notice carries a `resultId`, `nextOffset`, and an executable `execute_code`
 recovery action. Read and reduce the result in one program:
 
@@ -461,7 +509,7 @@ async () => {
 
 A page is `{ resultId, offset, bytes, totalBytes, hasMore, nextOffset?,
 format: "text", text }`. The page size is clamped to the original call's inline
-cap, with UTF-8 alignment and forward progress. Reassemble inside the sandbox;
+cap and a 32 KiB program bridge ceiling, with UTF-8 alignment and forward progress. Reassemble inside the sandbox;
 returning pages unchanged can hit the program result cap. The admitted subject
 and principal, endpoint/pool, request origin, connector, and tool bindings must
 match. The host rechecks current access and trust before returning each page; a
@@ -472,7 +520,7 @@ usable bounded preview. It says paging is unavailable and the write already
 ran; it carries no result handle or recovery action and stores no unreachable
 stash. Write paging remains available on trusted endpoints.
 
-A refused stash write cannot undo a downstream success. Both call tools return
+A refused stash write cannot undo a downstream success. Direct calls and program returns produce
 a paging-unavailable notice, without a handle or recovery action. A write's
 notice still says it already ran. Activity records success; operator logs receive
 a fixed warning without storage error prose. Never repeat a write to recover output.
@@ -709,6 +757,8 @@ An OAuth call failure uses this envelope:
   "connector": "service",
   "operation": "service.read",
   "recovery": "oauth",
+  "authorizationUrl": "https://connecta.example/connect/service?h=...",
+  "instructions": "Copy authorizationUrl exactly as returned and sign in as the initiating user.",
   "nextAction": {
     "tool": "authorize_connector",
     "arguments": { "connector": "service" },
@@ -718,9 +768,13 @@ An OAuth call failure uses this envelope:
 }
 ```
 
-`recovery` is `oauth`, `operator_config`, or `unavailable`. Call
-`authorize_connector` only after this error. It returns the class-specific
-handoff:
+`recovery` is `oauth`, `operator_config`, or `unavailable`. On hosts without URL
+elicitation, auth errors carry the same handoff fields that `authorize_connector`
+returns for the admitted user, connector, and pool. Direct calls include them in
+`error`; program `connecta.call` failures include them in `error.data` and
+`error.details`. Search `catalogErrors` and scoped `queryAnalysis.catalogError`,
+and describe `errorDetails`, carry them too. When an auth error includes a
+handoff, give it to the user or operator. The class-specific handoff is:
 
 - `oauth`: an `authorizationUrl` to connecta's `/connect/<connector>?h=...` route
   and instructions to sign in as the initiating user;
@@ -733,6 +787,13 @@ The class follows what the connector declares, not how it was authored: a
 and no OAuth flow, so it uses `operator_config` when both vault and UI are
 configured. Without either it returns `unavailable`, never a dead UI link.
 
+Errors mint at most one handoff per connector per direct call or program run,
+including concurrent and repeated call or catalog errors. The request reuses the
+same signed URL; a later request can issue a fresh one. Issuing a link is
+stateless and starts no consent. Errors never request `force`; use an explicit
+`authorize_connector` call for a restart or a fresh expired link. URL-elicitation
+hosts keep the existing prompt and retry flow.
+
 The tool accepts no secret and starts no downstream consent. `force` applies
 only to OAuth and requests a restart when the verified browser opens the signed
 link. That visit may discard the stored grant before restarting consent. Static credential values are written
@@ -740,9 +801,12 @@ only through the same-origin interactive-user credential route, and only for a
 connector visible to that user with the relevant shared or personal management
 permission; Issuing an OAuth link, `force` included, requires that permission too. The
 `/connect` visit and callback both verify the same initiating user under Clerk or
-Cloudflare Access, including for shared connectors. The URL expires after fifteen
-minutes and carries no browser authentication. A signing credential vault is
-required; deployments without either interactive provider return `unavailable`
+Cloudflare Access, including for shared connectors.
+
+Copy `authorizationUrl` exactly as returned. Do not decode or re-encode its opaque,
+unpadded base64url handoff token. If the link is invalid or expired, request a fresh link with
+`authorize_connector`. The URL expires after fifteen minutes and carries no browser authentication.
+A signing credential vault is required; deployments without either interactive provider return `unavailable`
 with a clear configuration message. Status reads stay passive and never expose
 a downstream authorization-server URL. These routes work without the UI. After OAuth
 consent or a human update, retry the original operation; a static update is read
@@ -786,13 +850,36 @@ what happens over budget differs by field.
 | unknown `connecta.result(id)`, `authorize_connector.connector`, `skills.name` | clamped the same way                                        |
 | `search_tools.connector`                                                      | rejected with `invalid_args` before catalog lookup          |
 
-Arguments go all or nothing because the agent already holds what it sent, and
-half of it would describe a call nobody made. The address gets the opposite rule
+Arguments are schema-filtered before budgeting. `writeOnly: true` values are
+omitted at any depth, including array items and prefixes, local `$ref`/`$defs`,
+and `allOf`. `oneOf`/`anyOf` alternatives must agree on sensitivity. Unresolved
+or remote references, sensitive `patternProperties`/`additionalProperties`
+schemas, unsupported sensitivity rules, and traversal limits omit the entire
+echo. A private array element omits its containing array to keep indices intact.
+`argsRedacted: true` marks partial or withheld echoes. Use them only to identify
+the target for reconciliation; any new call requires the original arguments.
+The filtered snapshot is never clipped: over-budget arguments are dropped whole.
+The address gets the opposite rule
 because it is the thing being corrected: a clipped one still identifies the
 mistake, and a short one — every real one — comes back exact and untagged. A
 scope is rejected outright because a clipped one could select a different
 connector. A failed result-storage read returns typed `unavailable` without
 exposing backend error text.
+Submitted `writeOnly` values also enter the call's sent-secret output redaction
+set, including property names inside private object subtrees. Downstream
+result and error text quoting them, in raw or credential-supported encoded
+forms, is redacted before direct-call output, program returns, logs, and emits,
+or result stash persistence; paging in a later request reads already-redacted
+bytes. A program's `connecta.read` resources, connector usage guides, and
+downstream `connecta.skill` files take the same rules before the program sees
+them. JSON stays valid: a matching number or boolean becomes `"[redacted]"`.
+Empty private strings are exempt. A private value shorter than eight characters
+redacts only structured fields that equal it, so identifiers and approval state
+remain, and withholds prose that contains it, including error messages, while
+typed classification, retry facts, and write outcome remain.
+Work limits withhold the affected text without failing the call. See
+[output redaction](./auth.md#what-a-servers-errors-may-say)
+for the shared encoding, budget, and argument-filter contract.
 
 Activity records each of these refusals with the coarse `friction` class derived
 from its typed error code — `tool_not_found`, `schema_retry`,
@@ -837,10 +924,12 @@ scoped registry, including an empty list when none are accessible. They never
 list connectors from another pool or identity's grants.
 
 A write that times out after dispatch returns `write_outcome_unknown` with
-`retryable: false` and an agent-only `uncertainCall: { address, args }`. No write
-is automatically replayed. Arguments over the 512-byte echo budget are omitted
-whole with `argsOmitted: true`; use the exact arguments already sent when
-checking the target. A timeout before dispatch remains `timeout`. Trusted
+`retryable: false` and an agent-only `uncertainCall: { address, args?, argsOmitted?, argsRedacted? }`.
+No write is automatically replayed. `args` may be partial reconciliation context
+with `argsRedacted: true`. A withheld echo or arguments over the 512-byte budget
+carry `argsOmitted: true`; sensitive or unresolved schemas also carry
+`argsRedacted: true`. When `args` is absent or redacted, use the original
+arguments if reconciliation requires another call. A timeout before dispatch remains `timeout`. Trusted
 program write accounting keeps this detail even if the guest catches the
 failure or returns early. Multiple uncertain writes use `uncertainCalls`,
 bounded to ten calls with `uncertainCallsTruncated` when more exist.
@@ -850,3 +939,19 @@ SDK timeout classes, and runtime network codes. Untyped prose is non-retryable:
 "timeout", "temporarily unavailable", "rate limit", or "503" in a body, tool
 name, or URL never changes the verdict. JSON-RPC `ProtocolError.data` is dropped
 at the downstream boundary, even when the agent may see the error's message.
+
+## Source and tests
+
+Handlers and schemas live in [meta-tools.ts](https://github.com/zackbart/connecta/blob/main/src/meta-tools.ts).
+[Catalog service](https://github.com/zackbart/connecta/blob/main/src/catalog-service.ts)
+and [invocation](https://github.com/zackbart/connecta/blob/main/src/invocation.ts)
+serve both direct tools and programs. [Skills](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
+owns the supplied usage instructions and connector guides.
+
+[Schema tests](https://github.com/zackbart/connecta/blob/main/test/meta-tool-schemas.test.ts),
+[search tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-search.test.ts),
+[call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
+[skills tests](https://github.com/zackbart/connecta/blob/main/test/skills-extension.test.ts),
+and [surface tests](https://github.com/zackbart/connecta/blob/main/test/code-first-surface.test.ts)
+check the published contract. Guest parity and clause evidence are in
+[code-mode verification](./code-mode.md#verification).