@zackbart/connecta 0.32.0 → 0.33.0

package/documentation/code-mode.md

@@ -80,7 +80,7 @@ and cleanup at budget exhaustion, cancellation, and deadlines; the wrapper only
 
 ## What an executor must implement
 
-The Promise provider/result seam lives in `src/types.ts`. Custom implementations
+The Promise provider/result seam is declared in the installed `dist/types.d.ts`. Custom implementations
 also need the lifecycle wrapper above; structural compatibility alone is insufficient.
 
 ```ts
@@ -481,9 +481,9 @@ argument to the configured endpoint. It never fetches that
 URI or creates a connector from it.
 
 Resources are protocol reads on read-only and writable endpoints alike. A read
-requires a grant to the whole connector through the endpoint/pool and identity
-intersection. Exact-tool grants, including guarded grants, authorize no
-resources. An absent, hidden, tool-restricted or resource-incapable connector
+requires the whole connector on the endpoint: plain `/mcp`, or a pool whose
+`tools` list the connector id. A pool listing only exact `connector.tool`
+addresses authorizes no resources. An absent, hidden, tool-restricted or resource-incapable connector
 fails with `unknown_address`. The URI and extra arguments cannot select a
 different credential owner or downstream subject. Personal credentials come
 from the admitted principal, just as they do for tool calls.
@@ -737,9 +737,6 @@ and nonzero pad bits are rejected before collection. Size budgets still apply.
 MCP-native output a return value cannot carry: base64 is not projectable, so a
 block that fits the inline call limit (`S5`, `L6`) can use the separate
 emission transport budget instead of the `R2` return guard.
-The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
-([#267](https://github.com/zackbart/connecta/issues/267),
-[#270](https://github.com/zackbart/connecta/issues/270)).
 
 **M1.** `connecta.emit(result)` accepts a rich result from this program's
 `connecta.call` and forwards its original native content blocks, including
@@ -861,7 +858,7 @@ Programs and direct calls use the same invocation deadline and stages. A call's
 `timeoutMs` wins, then `calls.defaultTimeoutMs`, then `execute.hostCallTimeoutMs`
 (default 15,000). A guest may request a longer individual call, but the sandbox
 and request ceilings still bound the whole run. Timeout details are agent-facing;
-INV-6 operator records retain only checked classifications and numeric facts.
+operator records retain only checked classifications and numeric facts.
 A dispatched write timeout becomes `write_outcome_unknown` and retains its
 deadline details even when the program catches the failure. The final program
 error includes the first timeout in `details`; multiple write timeouts also
@@ -1018,7 +1015,7 @@ createConnecta({
   connectors, executor,
   readOnly: false, // required: false writes, true refuses every write call
   pools: {
-    reporting: { tools: ["posthog"], readOnly: true, grant },
+    reporting: { tools: ["posthog"], readOnly: true, members: analysts },
   },
   classification: {
     posthog: { exec: "read" }, // only for a deployment with a read-only exec contract
@@ -1028,7 +1025,7 @@ createConnecta({
 ```
 
 The removed `trust` option, on the deployment or a pool, fails construction
-with a message naming `readOnly` (`INV-11`).
+with a message naming `readOnly`.
 
 The registry computes one `classifyTool` verdict on each request-scoped
 published catalog entry. It caches and persists only raw downstream facts.
@@ -1194,7 +1191,13 @@ brand check and reads only own string data descriptors for diagnostics; guest
 accessors, serialization hooks, and Proxy traps do not run. Other thrown objects
 receive a fixed description.
 
-## Verification
+## Contributor reference
+
+### Verification
+
+The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
+([#267](https://github.com/zackbart/connecta/issues/267),
+[#270](https://github.com/zackbart/connecta/issues/270)).
 
 `test/guest-contract-cases.ts` runs on QuickJS in `test/guest-api-contract-quickjs.node.test.ts`
 and on the Worker adapter with a real Miniflare Loader in `test/guest-api-contract.test.ts`.

package/documentation/deploying.md

@@ -27,20 +27,25 @@ path and pins the generated project's Connecta dependency to the CLI version:
 npx @zackbart/connecta init my-connecta
 cd my-connecta
 npm install
-npm run --silent provision-token -- "local-machine"
+npm run --silent rotate-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;
+The agent connects to its pool's agent endpoint,
+`http://localhost:8787/agent/local-machine`, with
+`Authorization: Bearer <returned-cta-token>`. People use `/mcp` and
+`/mcp/<pool>`, which refuse `cta_` tokens. Machine clients are the agents
+declared in `agents` in `src/connecta.config.ts`; the generated project declares
+`local-machine` and always installs `accessTokens(storage)`. An agent with no
+issued token admits no MCP caller even though `/health` works. Rotating with the
+same command replaces the token immediately. `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.
+Edit `src/connecta.config.ts` for connectors, public URL, auth, maintainers,
+agents, pools, and optional modules. Lay out each agent's pools by
+[Organizing an agent's pools](./auth.md#organizing-an-agents-pools). `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.
@@ -56,12 +61,74 @@ 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
+allowlist. Machines are declared agents: they use `/agent/<pool>` with the
+agent's `cta_` bearer as their only credential, once the
+[agent bypass application](#agent-endpoints-behind-cloudflare-access) exists;
+Access 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).
 
+## Agent endpoints behind Cloudflare Access
+
+Agents use `/agent/<pool>`, which connecta authenticates with the `cta_` token
+alone and which ignores Access context entirely
+([agent endpoints](./auth.md#agent-endpoints)). Behind Access, the edge must
+let those requests through without an Access login or service token. The P0
+probe ([observations](./architecture.md#production-access-bypass-for-agent-endpoints))
+verified this shape on 2026-10-15:
+
+1. Keep the Worker-level application, whose destination is
+   `{ "type": "worker", "worker_id": "<the Worker script tag>" }`, exactly as
+   [Cloudflare Access on Workers](./auth.md#cloudflare-access-on-workers)
+   describes. It still protects every other path and supplies `ctx.access` to
+   human routes.
+2. For each hostname agents use (the `workers.dev` hostname, each Custom
+   Domain, each route host), add one more **self-hosted** Access application.
+   In the dashboard, set the domain to that hostname and the path to
+   `agent/*`. Give it a single policy whose action is **Bypass** and whose
+   include rule is **Everyone**. Through the API:
+
+   ```json
+   {
+     "type": "self_hosted",
+     "name": "connecta agents",
+     "destinations": [{ "type": "public", "uri": "connecta.example.com/agent/*" }],
+     "policies": [{ "name": "agents bypass", "decision": "bypass", "include": [{ "everyone": {} }] }]
+   }
+   ```
+
+   The more specific hostname-and-path application takes precedence over the
+   Worker-level one on matching paths only. Do not use a Worker destination
+   for it: a Worker destination belongs to one application, and a second one
+   is refused with 409 `destination belongs to another application`. For the
+   same reason a second hostname without Access is not an alternative.
+
+3. Point each agent at `https://<host>/agent/<pool>` with
+   `Authorization: Bearer cta_…` and drop its `CF-Access-Client-Id` and
+   `CF-Access-Client-Secret` headers. The pool must list `"agent:<name>"`.
+4. Verify after the change has settled. Access changes took 15–19 seconds to
+   settle in the probe, and while they propagate the edge can answer with
+   transient 500 (`error code: 1104`) or 404 (`error code: 1042` or `1043`)
+   responses, and in one round a 403 on a bypassed path after more than 30
+   seconds. Do not rely on a fixed wait: repeat these checks until they agree
+   for several consecutive rounds. Without credentials, `/agent/<pool>`
+   reaches connecta (its 401 carries `WWW-Authenticate: Bearer`, not Access's
+   403 page), while `/mcp` and `/` still get Access's refusal. Then run
+   `connecta doctor --pool <pool>` with the agent's token.
+
+The bypass makes `/agent/*` reachable from the internet without Access.
+Connecta answers there only an issued token of an agent listed in the pool,
+and gives every other spelling of the agent namespace a 404 before auth,
+because Access matches `/agent/*` after resolving dot segments, folding case,
+decoding unreserved escapes, and collapsing a leading `//`, while the Worker
+sees the raw path. Two cases were not tested: a human's `CF_Authorization`
+cookie on a bypassed path, whose `ctx.access` identity is unknown (connecta
+never reads it at `/agent/*`), and Custom Domains, which use the same
+documented hostname-and-path form but were not observed; only `workers.dev`
+was probed. Pinning the Worker-level application's AUD on human routes is
+recommended hardening that connecta does not yet do.
+
 ## Compose capabilities and access
 
 Both configurations use `defineConfig((env) => …)`, a required executor, and a required `readOnly` choice.
@@ -90,9 +157,13 @@ outside the database and source control, and preserve it across upgrades.
 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;
+for human auth; Access is Workers-only. With inbound auth, `maintainers` is
+required: only they reach plain `/mcp` and the operator UI. Everyone else
+reaches a pool that lists them in `members`: people at `/mcp/<pool>`, agents
+at `/agent/<pool>`. Maintainers alone administer shared credentials, manage
+agent tokens, and read activity; members connect their own accounts on
+personal connectors in their pools.
+[Auth](./auth.md#principals-visibility-and-operators) owns maintainers and members;
 [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.
 
@@ -102,44 +173,70 @@ inherits that value unless it sets its own. A writable endpoint (`false`) allows
 writes through `call_destructive_tool` and programs and marks `execute_code` as
 a write; the client decides what to approve. A read-only endpoint (`true`) omits
 write tools from search and describe and refuses every write call; provider
-guides may still name those tools. Pool membership intersects
-the caller's grants; it never widens them. See [pools](./auth.md#pools) before
-changing `readOnly`.
+guides may still name those tools. A pool serves exactly its `tools` to its
+`members`. See [pools](./auth.md#pools) before changing `readOnly`.
 
 ## Verify and diagnose
 
-With the deployment running, replace the placeholder with its saved client
-token and run doctor:
+With the deployment running, replace the placeholder with its saved agent
+token and run doctor against a pool that lists the agent:
+
+```sh
+CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787 --pool local-machine
+```
+
+Doctor checks health, the required executor, and the current six-tool set. A
+`cta_` token is checked at `/agent/<pool>` and needs `--pool`.
+For a Worker protected by Access, `/health` still needs edge admission even
+though `/agent/*` bypasses Access. Use an Access service token admitted by the
+Worker-level policy for that check, alongside the agent token:
 
 ```sh
-CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787
+CF_ACCESS_CLIENT_ID='<access-service-id>' CF_ACCESS_CLIENT_SECRET='<access-service-secret>' CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url https://connecta.example.com --pool assistant
 ```
 
-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
+The service headers admit the health probe at the edge; only the `cta_` token
+authenticates the agent endpoint inside Connecta. If the operator UI is enabled, maintainer-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.
+configuration, live facts, and permission rules. The config route is a human
+endpoint: an agent token cannot authenticate it.
 
 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).
 
+Use the failed check to choose the next step:
+
+| Symptom                             | Action                                                                                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Connection refused or timeout       | Check the public URL, listening process/port, proxy, and Worker deployment.                                                                      |
+| `/health` fails behind Access       | Check the Worker-level Access policy and the two service headers above. Do not broaden the agent bypass.                                         |
+| Executor check fails                | Retain `quickJsExecutor()` and its peer on Node, or `workerExecutor({ loader })`, the codemode peer, and `LOADER` on Workers.                    |
+| MCP 401                             | Check the saved token, declared agent, and slot state; rotated/revoked tokens refuse. Use `/agent/<pool>` with `--pool`.                         |
+| MCP 404                             | Check the pool name and `members: ["agent:assistant"]`; an existing but inaccessible pool is deliberately indistinguishable from a missing one.  |
+| Doctor passes but a connector fails | Discover its tools in that pool, check credential status/account ownership, and perform a bounded read. Doctor does not prove downstream access. |
+
+After a fix, repeat doctor with the same client credentials and pool. Never
+paste a token or raw downstream failure body into a committed diagnostic log.
+
 ## 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.
+- [Migration to 0.33](./migration-0.33.md) maps every removed access option to `maintainers`, pool `members`, and `agents`, moves agents to `/agent/<pool>`, and covers pool owners, token revisions, operator contract v2 with its operator route changes, and the pre-auth listen fix.
+- [Tokens issued before agents](./auth.md#agent-tokens-and-upgrading-from-earlier-tokens) stop admitting until each machine's token is bound once to a declared agent with `npm run adopt-token -- <token-id> <agent>` (Node) or `AccessTokenManager.adopt`, which keeps its secret. Human-bound tokens stay refused; issue those agents new tokens. Pool members name `"agent:<name>"` instead of matching token record ids.
 - [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
+## Contributor reference
+
+### 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

package/documentation/integrating.md

@@ -1,16 +1,62 @@
 # 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).
+Use this guide to change connectors in deployment configuration.
 [All agent routes](./README.md) are in the index.
 
+## Add or remove a connector
+
+Connectors are code-owned. Edit the deployment's `src/connecta.config.ts`;
+there is no install button or runtime registration API.
+
+To add one:
+
+1. Choose a maintained provider, `remoteMcp()`, or `api()` using the sections
+   below. Give it a unique, stable id such as `crm`; renaming an id selects
+   different stored credentials and changes every tool address.
+2. Put the constructed connector in `connectors`. Keep secrets in environment
+   variables or the encrypted vault. Choose shared or personal auth explicitly
+   for the intended audience; agents cannot see personal-auth connectors.
+3. Add the id (all its tools) or exact `id.tool` addresses to the intended
+   pools' `tools`. Maintainers at plain `/mcp` already see the whole catalog.
+   Follow [the agent pool layout](./auth.md#organizing-an-agents-pools) for an
+   agent: shared connectors go in its base constant, per-user connectors only
+   in that user's pool.
+4. Run the deployment's `npm run typecheck` (Worker copies: `tsc --noEmit`),
+   restart Node or redeploy the Worker, and
+   [connect its credential](./auth.md#connect-a-shared-credential) if needed.
+   Run [doctor](./deploying.md#verify-and-diagnose), discover its tools from
+   the intended pool, and perform a bounded read. Check an excluded pool too.
+
+For example, merge this fragment into the existing configuration, retaining
+its storage, executor, auth, and `readOnly` settings:
+
+```ts
+import { remoteMcp } from "@zackbart/connecta";
+
+const crm = remoteMcp("crm", {
+  url: "https://crm.example.com/mcp",
+  authScope: "shared",
+  auth: { type: "credential", credential: { label: "CRM API token" } },
+});
+const assistant = { tools: ["crm", "tickets"], members: ["agent:assistant"] };
+// connectors: [crm, tickets], agents: ["assistant"], pools: { assistant }
+```
+
+To remove `crm`, first disconnect its OAuth grant or delete its saved
+credential while the connector still exists, using a signed-in maintainer
+for shared auth. Each person disconnects their own personal account. Remove
+`crm` and all `crm.*` addresses from every pool (including base constants),
+then remove its entry from `connectors`, unused imports, and unused secret
+configuration. Remove any pools left with no tools (empty `tools` fails
+construction), and update or retire clients pointing at those pools. Typecheck, restart/redeploy, run doctor, and confirm discovery
+and calls no longer find it. Removing configuration alone does not revoke a
+credential at the downstream service; revoke unused credentials there too.
+
 ## 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                         |
+| A maintained integration         | Its `@zackbart/connecta/providers/<name>` factory | Published factory declarations, 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 |
 
@@ -19,6 +65,14 @@ 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.
 
+`callAdmission` is optional on `remoteMcp()`, `api()`, custom connectors, and
+provider variants that expose an override. Only omission or `undefined` uses
+the connector's documented default, which may be no admission. Every defined
+value is validated at construction. Malformed policies, including `false`,
+`null`, `0`, and `""`, throw before serving requests; they never disable
+admission or select a default. Custom connector policies are validated when
+the deployment constructs its registry.
+
 ## Maintained integrations
 
 Import a provider individually. For example, Linear requires an explicit
@@ -35,25 +89,26 @@ const tracker = linear("tracker", {
 ```
 
 Linear defaults to OAuth; its read-only endpoint requests only the downstream
-read scope. That is separate from a Connecta `readOnly` endpoint. 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.
+read scope. That is separate from a Connecta `readOnly` endpoint. Read the installed `dist/providers/linear/index.d.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
+integrations. In the installed package, `dist/providers/<name>/index.d.ts`
+and its imported declarations describe each factory's options. After adding
+a connector, use `search_tools` to discover its current tools and `connecta.skill("connector:<id>")` in `execute_code`
+to read its runtime guide; provider source skills are not installed files.
+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
+mapping from admitted identity to the downstream account; an agent acts as its
+pool's `owner` instead ([auth guide](auth.md#pool-owners-for-google-workspace)).
+A request must not choose its own account. Gmail never sends mail, and Drive never permanently
 deletes files.
 
 Wispr Flow uses OAuth only through `wisprFlow()` from
 `@zackbart/connecta/providers/wispr-flow`. It reaches the authorized account's
 Notetaker content, with personal and work accounts holding separate data.
-Its [provider guide](https://github.com/zackbart/connecta/blob/main/src/providers/wispr-flow/SKILL.md)
-owns account access, search limits, transcript permissions and paging. The
+Its runtime guide, available through `connecta.skill("connector:<id>")` in `execute_code`, describes account access,
+search limits, transcript permissions and paging. The
 reviewed classification includes task writes listed in Claude's directory even
 though Wispr's public help describes read-only access; discover the account's
 actual tools before assuming those writes exist.
@@ -75,6 +130,16 @@ MCP clients to its hosted server, an operational gate outside Connecta. See the
 To use both implementations of one provider, configure two connector ids with
 independent credentials.
 
+Both Notion auth variants accept optional `callAdmission`. For a token
+connector it replaces the whole per-runtime default of 180 calls per minute
+and 3 concurrent. Notion's [request limits](https://developers.notion.com/reference/request-limits)
+allow 600 requests per minute per connection on Business and Enterprise and
+180 on other plans. A separate workspace-wide limit is shared by all
+connections. Size an override for other runtime traffic and tools that make
+multiple HTTP requests. Only an omitted or `undefined` policy selects the
+default; malformed policies, including `false`, `null`, `0`, and `""`, throw
+at construction on both auth variants.
+
 Planning Center's `excludeApps` removes whole products from a connection, for
 example `planningCenter("pco", { purpose, excludeApps: ["giving"] })` for a
 deployment that keeps agents away from donor and financial data. Excluded
@@ -130,8 +195,8 @@ const service = remoteMcp("service", {
   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.
+// Add service to connectors. Configure the vault; a signed-in maintainer
+// supplies its credential through the operator UI.
 ```
 
 Credential auth defaults to an `Authorization: Bearer` header. Choose framing
@@ -198,10 +263,10 @@ schemas when known; runtime observations cannot replace them.
 
 `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
+controlled by maintainers and pool membership. 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
+[maintainers and members](./auth.md#principals-visibility-and-operators) and
 [management permissions](./auth.md#management-permissions) before exposing a
 new integration or its authentication controls.
 
@@ -210,7 +275,13 @@ 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
+## Contributor reference
+
+### Implementation and evidence
+
+To implement a 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).
 
 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),

package/documentation/meta-tools.md

@@ -194,8 +194,7 @@ discovery made the same bet).
 ```
 
 It is something to read, not something that runs: programs stay JavaScript,
-and `execute_code` accepts no erasable TypeScript
-([decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)). The output half is the provider's declared
+and `execute_code` accepts no erasable TypeScript. The output half is the provider's declared
 schema, else an `S9` observation that opens with the
 `/* observed, not declared */` marker and keeps the `outputSchemaSource`
 field, else `unknown` — runtime evidence never reads as a contract, even when
@@ -282,7 +281,7 @@ is its slug; other IDs use `connector-` followed by a stable SHA-256 prefix.
 The suffix makes each
 document a valid Agent Skills file; the roots `skill://connecta/usage` and
 `skill://connecta/connectors/<connector-id>` also resolve. Provider guides are
-built from the generated `src/providers/*/SKILL.md` content with the existing
+built from maintained provider guides with the existing
 connection context and deployment instructions. Local manifests contain a
 SHA-256 digest and UTF-8 byte size of the complete document. `usage` and
 `investigate` remain compatibility names; `connector:<id>` remains a
@@ -598,8 +597,8 @@ same when no visible connector ID or title names that service. This service-name
 vocabulary is query interpretation, not an inventory of configured providers.
 For other service names, use the explicit `connector` scope. An unavailable
 catalog is a catalog failure, never an absence. Absence records and catalog
-errors use only the endpoint/pool and grant intersection; a connector hidden by
-that intersection is indistinguishable from an unconfigured one.
+errors use only the endpoint's tools; a connector the endpoint does not serve
+is indistinguishable from an unconfigured one.
 
 If no tool covers every search term, wider any-term fallback remains available
 for ordinary action/object searches and the page carries `matchMode: "partial"`.
@@ -933,9 +932,13 @@ 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?, argsOmitted?, argsRedacted?, recovery? }`.
 No write is automatically replayed. `recovery` carries facts the connector
-recorded before dispatch (`src/call-recovery.ts`), such as the `idempotencyKey`
-a REST connector generated; a deliberate retry that reuses it with the exact
-original arguments cannot repeat the write while the vendor retains the key
+recorded before dispatch, such as a REST connector's
+generated or caller-supplied `idempotencyKey`. Recovery accepts keys up to 255
+characters, matching the REST write schema. Other recovery values remain capped
+at 128 characters, with at most four facts per call and camelCase names of at
+most 32 characters. Values outside these bounds are dropped whole. A deliberate
+retry that reuses the key with the exact original arguments cannot repeat the
+write while the vendor retains the key
 (Stripe may prune v1 keys after 24 hours). After that, look the object up before
 retrying. When a connector recorded such facts, any other dispatched write whose
 outcome is unknown (a lost response body, a 5xx) also carries `uncertainCall`
@@ -954,7 +957,9 @@ SDK timeout classes, and runtime network codes. Untyped prose is non-retryable:
 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
+## Contributor reference
+
+### 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)