@zackbart/connecta 0.32.0 → 0.34.0

package/dist/routes/ui-data.js

@@ -137,8 +137,8 @@ export function uiData(registry, baseUrl, options) {
                 const fields = credentialFields();
                 return Effect.succeed({
                     ...card,
-                    ...(fields?.length ? { fields } : {}),
-                    configured: false,
+                    ...(fields?.length ? { fields: fields.map((field) => ({ ...field, configured: null })) } : {}),
+                    configured: null,
                     removable: true,
                     testable: testRule.mode !== null,
                     error: "Stored credential could not be read.",

package/dist/routes/ui.js

@@ -9,7 +9,7 @@ import { CONNECTA_VERSION } from "../version.js";
 import { CONNECTA_FAVICON_ICO } from "../favicon.js";
 import { CONNECTA_FAVICON_SVG, operatorPageForPath, renderUiHtml } from "../ui.js";
 import { authorized, refuse, scopeFor, serveOperator, visibleRegistry, } from "./operator.js";
-import { mayManageConnector, privateJson } from "./shared.js";
+import { managesAgentTokens, mayManageConnector, privateJson, readsActivity } from "./shared.js";
 import { routeUiConfig } from "./ui-config.js";
 import { uiData } from "./ui-data.js";
 /**
@@ -84,7 +84,8 @@ export async function routeUi(context) {
             ? opts.config.auth.find((provider) => provider.uiAuth?.kind === "cloudflare-access")?.uiAuth
             : undefined;
         const uiAuth = ambient ??
-            opts.config.auth.find((provider) => provider.uiAuth && provider.uiAuth.kind !== "cloudflare-access")?.uiAuth;
+            opts.config.auth.find((provider) => provider.uiAuth && provider.uiAuth.kind !== "cloudflare-access")?.uiAuth ??
+            opts.config.auth.find((provider) => provider.uiAuth?.kind === "cloudflare-access")?.uiAuth;
         const mcpUrl = new URL("/mcp", baseUrl).toString();
         const clerkOrigin = uiAuth?.kind === "clerk" && isSafeHttpsUrl(uiAuth.frontendApiUrl)
             ? new URL(uiAuth.frontendApiUrl).origin
@@ -115,14 +116,14 @@ function operatorView({ opts }, authz, registry) {
     const visible = registry.listConnectors();
     const mayManage = (id) => {
         const connector = registry.getConnector(id);
-        return Boolean(connector && mayManageConnector(authz, connector));
+        return Boolean(connector && mayManageConnector(opts, authz, connector));
     };
     const permissions = (connector) => ({
         use: true,
         manageSharedAuth: connector.authScope !== "personal" && mayManage(connector.id),
         connectPersonal: connector.authScope === "personal" && mayManage(connector.id),
     });
-    const activityEnabled = Boolean(opts.config.activity?.store.list) && authz.operator;
+    const activityEnabled = Boolean(opts.config.activity?.store.list) && readsActivity(opts, authz);
     const credentialManagement = visible.some((c) => c.credential && mayManage(c.id))
         ? opts.config.vault
             ? "available"
@@ -169,17 +170,9 @@ function summary(context) {
         const authz = yield* authorized(context);
         const registry = yield* visibleRegistry(context, authz);
         const { visible, mayManage, permissions, activityEnabled, credentialManagement } = operatorView(context, authz, registry);
-        // Setup commands are offered per pool, but only for pools this identity's
-        // grant admits: `/mcp/<name>` answers every other name with one flat 404 so
-        // a credential cannot enumerate them, and the page must not undo that.
-        const pools = [];
-        for (const [name, pool] of opts.pools ?? []) {
-            const granted = yield* Effect.tryPromise(async () => (await pool.grant(authz.identity)) === true).pipe(
-            // A throwing grant is a refusal at the endpoint, and so a refusal here.
-            Effect.orElseSucceed(() => false));
-            if (granted)
-                pools.push(name);
-        }
+        // Only maintainers reach here (#837); setup commands are offered for every
+        // declared pool, since they administer them all.
+        const pools = [...opts.pools.keys()];
         return privateJson({
             ...(pools.length ? { pools } : {}),
             serverInfo: opts.config.serverInfo,
@@ -187,7 +180,7 @@ function summary(context) {
             activityEnabled,
             ...(opts.config.accessTokens
                 ? {
-                    accessTokenManagement: authz.accessTokenManagement && authz.identity.principal ? "available" : "requires_operator",
+                    accessTokenManagement: managesAgentTokens(opts, authz) ? "available" : "requires_operator",
                 }
                 : {}),
             credentialManagement,

package/dist/runtime/call-admission.js

@@ -12,6 +12,15 @@
 // shared queue between them was refused.
 import { Effect } from "effect";
 let program;
+const budgetCharges = new WeakMap();
+/** Bind budget-only admission to the partition already owned by this permit. */
+export function provideCallBudgetCharge(permit, charge) {
+    budgetCharges.set(permit, charge);
+}
+/** Charge an internal request without acquiring another concurrency permit. */
+export function chargeCallBudget(permit, signal) {
+    return Effect.clockWith((clock) => budgetCharges.get(permit)?.(clock.currentTimeMillisUnsafe(), signal) ?? Effect.void);
+}
 // What the live Clock reads, looked up on every call rather than bound once,
 // so a Date faked after a caller queued (vitest's setSystemTime) still counts.
 const liveNow = () => Date.now();

package/dist/server.js

@@ -2,6 +2,7 @@ import { Effect } from "effect";
 import { notFoundResponse } from "./branding.js";
 import { aggregateCallAdmissionSnapshots } from "./call-admission.js";
 import { isAdmittingExecutor } from "./executor-admission.js";
+import { isAgentPath } from "./routes/agent-path.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
 import { routeOAuthCallback } from "./routes/oauth.js";
 import { routeOAuthClientMetadata } from "./routes/oauth-client-metadata.js";
@@ -59,6 +60,10 @@ export function createFetchHandler(opts) {
     };
     const route = (context) => Effect.gen(function* () {
         const { request, path, baseUrl } = context;
+        // The agent namespace is routed before anything else, so no path
+        // Cloudflare Access bypasses as `/agent/*` can reach a human route.
+        if (isAgentPath(path))
+            return (yield* routeMcp.handle(context)) ?? notFoundResponse(request, opts.config);
         const clientMetadata = routeOAuthClientMetadata(context);
         if (clientMetadata)
             return clientMetadata;

package/dist/skills.js

@@ -13,6 +13,16 @@ const RECOVERY = 'When an auth error includes a handoff, give it to the user or
  * and describe and refuses every write call. Guides may still name them.
  */
 export const CONNECTA_INSTRUCTIONS = `${ROUTE} On a writable endpoint, programs and call_destructive_tool may write. On a read-only endpoint, search omits write tools and every write call is refused; guides may still name them. The execute_code description says which this endpoint is. Never repeat a write to recover its output. ${RECOVERY}`;
+/**
+ * The instructions one endpoint serves: {@link CONNECTA_INSTRUCTIONS}, then
+ * the admitted pool's `description` after a fixed lead-in. Plain `/mcp` and a
+ * pool without a description serve the constant unchanged. The description
+ * comes from deployment config for the pool the request was admitted through;
+ * nothing a request sends reaches it.
+ */
+export function endpointInstructions(description) {
+    return description === undefined ? CONNECTA_INSTRUCTIONS : `${CONNECTA_INSTRUCTIONS} This endpoint: ${description}`;
+}
 export { USAGE_SKILL } from "./usage-guide.js";
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {

package/dist/storage/keys.js

@@ -164,7 +164,12 @@ export const oauthHandoffKeys = {
     },
     handoff: (connectorId, stateHash) => validateStorageKey(`oauth-handoff:v1:${connectorId}:${stateHash}`),
 };
-/** Connecta-issued `cta_` access tokens: records, digest lookups, capacity. */
+/**
+ * Connecta-issued `cta_` access tokens: token records, digest lookups, one
+ * slot per declared agent naming its live record, and a never-deleted claim per
+ * legacy record an adoption has taken. `active` is the capacity
+ * ledger releases before 0.33 wrote; nothing writes it now.
+ */
 export const accessTokenKeys = {
     family: {
         name: "access-token",
@@ -178,6 +183,9 @@ export const accessTokenKeys = {
     recordPrefix: "access-token:v1:record:",
     record: (id) => validateStorageKey(`access-token:v1:record:${id}`),
     lookup: (tokenHash) => validateStorageKey(`access-token:v1:lookup:${tokenHash}`),
+    agent: (name) => validateStorageKey(`access-token:v1:agent:${name}`),
+    /** Write-once claim that a legacy token record has been taken by one agent's adoption. */
+    adopted: (legacyRecordId) => validateStorageKey(`access-token:v1:adopted:${legacyRecordId}`),
     active: "access-token:v1:active",
 };
 /**

package/dist/storage/sql.js

@@ -492,7 +492,11 @@ export function sqlActivityStore(driver, kind, options = {}) {
         }
     });
     return {
-        describe: () => ({ kind, retentionDays }),
+        describe: () => ({
+            kind,
+            retentionDays,
+            optionSources: { retentionDays: options.retentionDays === undefined ? "default" : "config" },
+        }),
         async record(event) {
             await ensure();
             const occurredAtMs = Date.parse(event.occurredAt);

package/dist/types.d.ts

@@ -727,6 +727,11 @@ export type AuthResult = {
     sessionCookies?: readonly string[];
     /** Human owner represented by a non-interactive access credential. */
     principal?: IdentityReference;
+    /**
+     * Declared agent name. Only the built-in `accessTokens()` adapter may
+     * set it; a result from any other provider that carries it is refused.
+     */
+    agent?: string;
 } | {
     ok: false;
     response: Response;
@@ -747,6 +752,12 @@ export interface AuthenticatedIdentity {
     subject?: IdentityReference;
     /** Human owner of personal connector authentication. */
     principal?: IdentityReference;
+    /**
+     * Name of the code-declared agent this caller is, from `agents`. Set only
+     * when the built-in access-token adapter admitted a `cta_` token bound to
+     * a currently declared agent; an agent never has a `principal`.
+     */
+    agent?: string;
     interactive: boolean;
 }
 /** Public browser-auth configuration exposed to connecta's status UI. */
@@ -811,7 +822,7 @@ export interface ConnectaBranding {
     description?: string;
     /**
      * Browser tab title and page meta name. Defaults to
-     * `"<productName> — <ownerName>"`, or just `productName` when no owner is set.
+     * `"<productName> · <ownerName>"`, or just `productName` when no owner is set.
      */
     pageTitle?: string;
     /**
@@ -821,14 +832,18 @@ export interface ConnectaBranding {
      * elsewhere (it replaces the `/favicon.svg` link in the page head; the
      * `/favicon.*` routes still serve whatever `svg`/`ico` provide). `href` must
      * be an absolute `http(s)` URL or a root-relative path; anything else falls
-     * back to the default mark.
+     * back to the default mark. With `svg` set, the top bar shows it beside the
+     * name; the drawn mark shows only when no branding is set.
      */
     favicon?: {
         svg?: string;
         ico?: Uint8Array;
         href?: string;
     };
-    /** `theme-color` meta value. Defaults to "#ffffff". */
+    /**
+     * `theme-color` meta value. Unset, pages follow the page background:
+     * `#f6f4ef` in light and `#12110f` in dark.
+     */
     themeColor?: string;
     /**
      * Operator-page appearance. Every field is optional, and a rejected value
@@ -849,18 +864,25 @@ export interface ConnectaBranding {
 export interface ConnectaTheme {
     /**
      * The brand color: links, focus rings, primary actions, the active nav item.
-     * Hex only (`#rgb`, `#rrggbb`, or `#rrggbbaa`). Defaults to `#2f5fe0`.
+     * Hex only (`#rgb`, `#rrggbb`, or `#rrggbbaa`). Defaults to `#4c44e0`
+     * (`#8c86ff` in dark). Text on it and accent text in dark derive from it.
      */
     accent?: string;
     /**
      * Corner rounding for cards, inputs, and buttons. A CSS length (`10px`,
      * `0.5rem`) or a bare number read as pixels. `0` restores square corners.
-     * Defaults to `10px`.
+     * Defaults to `14px`.
      */
     radius?: string | number;
-    /** Body font stack. A plain CSS font-family list. Defaults to a system stack. */
+    /**
+     * Body font stack. A plain CSS font-family list. Defaults to Hanken
+     * Grotesk, served with the operator UI, then a system stack.
+     */
     fontFamily?: string;
-    /** Monospace font stack for addresses, ids, and the endpoint URL. */
+    /**
+     * Monospace font stack for addresses, ids, and the endpoint URL. Defaults
+     * to JetBrains Mono, served with the operator UI, then a system stack.
+     */
     monoFamily?: string;
     /**
      * `"system"` (the default) follows the operator's OS setting; `"light"` and

package/dist/ui.d.ts

@@ -49,4 +49,4 @@ _nonce?: string, page?: OperatorPage): string;
 export declare function operatorUi(options?: {
     branding?: ConnectaBranding;
 }): OperatorSurface;
-export type { OperatorUiContract, OperatorConnectorOverlay, OperatorTool, OperatorViewer, OperatorGrant, OperatorPool, OperatorLastCall, } from "./operator-ui/contract.js";
+export type { OperatorUiContract, OperatorUiContractV2, OperatorRole, OperatorMember, OperatorPoolV2, OperatorRootEndpoint, OperatorMemberConnector, OperatorMemberManage, OperatorAgent, OperatorSharedSource, OperatorRunsAs, OperatorConnectorPoolCell, OperatorConnectorOverlay, OperatorTool, OperatorGrant, OperatorLastCall, } from "./operator-ui/contract.js";

package/dist/ui.js

@@ -4,33 +4,34 @@ import { routeCredentials } from "./routes/credentials.js";
 import { routeOAuthManagement } from "./routes/oauth-management.js";
 import { uiData } from "./routes/ui-data.js";
 import { runEdge } from "./runtime/run.js";
-import { OPERATOR_UI_STYLE_PATH, OPERATOR_UI_SCRIPT_PATH, OPERATOR_UI_NOTICES_PATH } from "./operator-ui/generated.js";
+import { OPERATOR_UI_STYLE_PATH, OPERATOR_UI_SCHEME_PATH, OPERATOR_UI_SCRIPT_PATH, OPERATOR_UI_NOTICES_PATH, } from "./operator-ui/generated.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { escapeHtml, isSafeHttpsUrl, renderPage, resolveBranding } from "./branding.js";
+import { brandMark, escapeHtml, isSafeHttpsUrl, renderPage, resolveBranding } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 const OPERATOR_PAGE_LABELS = {
     overview: "Overview",
+    endpoints: "Endpoints",
     connections: "Connectors",
     connector: "Connector",
-    tools: "Tools",
-    access: "Access",
-    config: "Config",
-    tokens: "Access tokens",
+    settings: "Settings",
+    tokens: "Tokens",
     activity: "Activity",
 };
 export function operatorPageForPath(path) {
     if (path === "/")
         return "overview";
+    if (path === "/endpoints")
+        return "endpoints";
     if (path === "/connectors")
         return "connections";
     if (/^\/connectors\/[a-z0-9_-]+$/.test(path))
         return "connector";
     if (path === "/tools")
-        return "tools";
+        return "connections";
     if (path === "/access")
-        return "access";
-    if (path === "/config")
-        return "config";
+        return "endpoints";
+    if (path === "/config" || path === "/settings")
+        return "settings";
     if (path === "/tokens")
         return "tokens";
     if (path === "/activity")
@@ -38,7 +39,7 @@ export function operatorPageForPath(path) {
     return undefined;
 }
 export function operatorPageTitle(page, configuredTitle) {
-    return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
+    return `${OPERATOR_PAGE_LABELS[page]} · ${configuredTitle}`;
 }
 /** Report the verdict the registry stored, independent of whether an endpoint is read-only. */
 export function uiToolSafety(definition) {
@@ -101,7 +102,7 @@ function jsonForInlineScript(value) {
  */
 export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, 
 /** @deprecated Scripts load from same-origin assets; ignored. */
-_nonce, page = "overview") {
+_nonce, page = "endpoints") {
     const clerk = uiAuth?.kind === "clerk" ? uiAuth : undefined;
     // The Clerk loader's origin. A value that fails the gate is dropped rather
     // than escaped into the page: the loader tag is simply not emitted, the gate
@@ -130,13 +131,15 @@ _nonce, page = "overview") {
         : "";
     // The shared layout owns the head, scheme, theme, and masthead; the shell
     // adds its own bundle (which already imports the shared tokens), the nav
-    // mount, and the app.
+    // mount, and the app. The scheme initializer blocks, ahead of the
+    // stylesheet, so a saved color scheme holds from the first paint.
     return renderPage(branding, {
         title: operatorPageTitle(page, brand.pageTitle),
         uiMounted: true,
         operatorShell: true,
         styles: "",
-        head: `<link rel="stylesheet" href="${OPERATOR_UI_STYLE_PATH}"><link rel="license" href="${OPERATOR_UI_NOTICES_PATH}">` +
+        head: `<script src="${OPERATOR_UI_SCHEME_PATH}"></script>` +
+            `<link rel="stylesheet" href="${OPERATOR_UI_STYLE_PATH}"><link rel="license" href="${OPERATOR_UI_NOTICES_PATH}">` +
             clerkScript,
         skipTo: { id: "operatorContent", label: "Skip to operator page" },
         mastheadEnd: '<div id="operatorNav"></div>',
@@ -146,8 +149,8 @@ _nonce, page = "overview") {
     <h1>${OPERATOR_PAGE_LABELS[page]}</h1>
     <div class="lead-copy">
       <p>${escapeHtml(brand.description)}</p>
-      <noscript><p class="msg">The operator pages need JavaScript. Nothing else here
-      does — agents reach this deployment through <span class="mono">/mcp</span>.</p></noscript>
+      <noscript><p class="msg">Operator pages need JavaScript. Agents connect at
+      <span class="mono">/mcp</span>.</p></noscript>
     </div>
   </div>
 </main>
@@ -156,8 +159,10 @@ _nonce, page = "overview") {
             auth,
             mcpUrl,
             initialPage: page,
+            schemePinned: brand.theme.colorScheme !== "system",
             titleSuffix: brand.pageTitle,
             productName: brand.productName,
+            brandMark: brandMark(branding, true),
             productDescription: brand.description,
             productOperatorLabel: brand.productName + " operator",
         })}</script><script defer src="${OPERATOR_UI_SCRIPT_PATH}"></script>`,
@@ -181,11 +186,13 @@ export function operatorUi(options = {}) {
     options = assertKnownOptions(options, "operatorUi()", OPERATOR_UI_OPTIONS);
     const reservedPaths = [
         "/",
+        "/endpoints",
         "/connectors",
         "/connectors/*",
         "/tools",
         "/access",
         "/config",
+        "/settings",
         "/ui",
         "/ui/*",
         "/favicon.svg",

package/dist/usage-guide.js

@@ -77,7 +77,7 @@ async () => {
 
 Host-call budget exhaustion ends the run with budget_exceeded. Catch and
 allSettled cannot recover it or return partial output. Bound batches before
-starting them; search, describe, call, result, and skill spend host calls.
+starting them; every guest call except emit spends host calls.
 Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONNECTA_VERSION = "0.32.0";
+export declare const CONNECTA_VERSION = "0.34.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.32.0";
+export const CONNECTA_VERSION = "0.34.0";

package/dist/workspace-address.js

@@ -0,0 +1,9 @@
+// The one rule for a Google Workspace address, shared by the Workspace
+// providers' fixed `subject` and a pool's `owner` (#837, decisions/0006), so
+// config accepts exactly the addresses a delegated token can be minted for.
+/** A plausible mailbox: one `@`, no whitespace or control characters. */
+const ADDRESS = /^[^\s@<>()",;:\\[\]]+@[^\s@<>()",;:\\[\]]+\.[^\s@<>()",;:\\[\]]+$/;
+/** Whether `value`, already trimmed, is a Workspace email address. */
+export function isWorkspaceAddress(value) {
+    return typeof value === "string" && ADDRESS.test(value);
+}

package/dist/workspace-subject.js

@@ -0,0 +1,23 @@
+// Whose account a Google Workspace connector acts as, for the operator
+// matrix (#837, decisions/0006). The Workspace providers tag the connector
+// they build; nothing else can, and nothing a request sends reaches this.
+// Read only by the operator contract, which never shows a mapping function.
+const tagged = new WeakMap();
+/** Tag a Workspace connector with its subject kind, returning it unchanged. */
+export function tagWorkspaceSubject(connector, subject) {
+    tagged.set(connector, typeof subject === "string" ? { kind: "fixed", subject } : { kind: "mapping" });
+    return connector;
+}
+/**
+ * The subject kind of a tagged connector, or undefined for any other. Walks
+ * the prototype chain, since provider construction may wrap a connector it
+ * cannot restamp in an object that inherits from it.
+ */
+export function workspaceSubjectOf(connector) {
+    for (let current = connector; current; current = Object.getPrototypeOf(current)) {
+        const subject = tagged.get(current);
+        if (subject)
+            return subject;
+    }
+    return undefined;
+}

package/documentation/README.md

@@ -1,34 +1,58 @@
 # Agent documentation
 
-Choose a route by the work you are doing. Each route identifies the task guide
-and contracts needed to operate an endpoint, set up a deployment, connect a
-service, or change Connecta itself.
+Start here when operating a deployment installed with `@zackbart/connecta`.
+All operator procedures below are available in the installed package; paths in
+this directory are relative to `node_modules/@zackbart/connecta/documentation/`.
+For an existing endpoint, start with [Operating an endpoint](./operating.md).
+For a new deployment, start with [Deploying Connecta](./deploying.md).
 
-| Your task                                                             | Start here                                                            | Read next when needed                                                                                                                            |
-| --------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Use an existing endpoint to answer a question or perform a task       | [Operating an endpoint](./operating.md)                               | [Meta-tools](./meta-tools.md), [guest API](./code-mode.md)                                                                                       |
-| Set up, configure, upgrade, or diagnose a deployment                  | [Deploying Connecta](./deploying.md)                                  | [Auth](./auth.md), [operator UI](./operator-ui.md)                                                                                               |
-| Add a maintained integration, remote MCP, or HTTP API to a deployment | [Integrating services](./integrating.md)                              | Provider skill, [classification](./architecture.md#providers-and-reviewed-classification), [downstream auth](./auth.md#shared-and-personal-auth) |
-| Change Connecta's source, tests, or published contracts               | [AGENTS.md](https://github.com/zackbart/connecta/blob/main/AGENTS.md) | [Principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md), [architecture](./architecture.md), then the affected contract        |
+## Operator tasks
+
+| Task                                     | Self-contained procedure                                                                                                            |
+| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Add or remove a connector                | [Change the connector roster](./integrating.md#add-or-remove-a-connector)                                                           |
+| Organize an agent's pools and tiers      | [Organizing an agent's pools](./auth.md#organizing-an-agents-pools)                                                                 |
+| Add a person (maintainer or pool member) | [Add a person](./auth.md#add-a-person), [member page](./operator-ui.md#use-the-member-page)                                         |
+| Connect a shared credential              | [Connect a shared credential](./auth.md#connect-a-shared-credential)                                                                |
+| Issue, rotate, or revoke an agent token  | [Manage an agent token](./auth.md#issue-rotate-or-revoke-an-agent-token)                                                            |
+| Upgrade between versions                 | [Upgrade an existing deployment](./deploying.md#upgrade-an-existing-deployment), including [migration to 0.33](./migration-0.33.md) |
+| Diagnose with `connecta doctor`          | [Verify and diagnose](./deploying.md#verify-and-diagnose)                                                                           |
+
+## Audience rule
+
+Shipped docs (`documentation/`, `templates/`, `examples/worker/`, and the root
+`README.md`) are written first for an agent operating a deployment from the
+installed package. Operator conventions must be self-contained rules plus a
+neutral example. Decision records and issues explain why; no operator task
+requires them, `spec/`, `.claude/`, or the Connecta source checkout. Those
+three directories do not ship. Contributor source maps, INV citations, and
+implementation/test evidence belong under clearly labeled contributor
+headings and are optional for operators. Use `assistant`, `alice`, `bob`,
+`crm`, `tickets`, `notes_alice`, and `alice@example.com` in examples; never
+real deployment, client, person, or organization names. Maintained provider
+product names stay.
 
 ## Contract reference
 
-| Guide                                                       | Owns                                                                                                          |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| [Meta-tools](./meta-tools.md)                               | Six top-level tools, discovery, direct-call results, paging, skills, and recovery                             |
-| [Code mode](./code-mode.md)                                 | JavaScript guest API, executor requirements, output, retries, cancellation, limits, and writes                |
-| [Auth](./auth.md)                                           | Inbound identity, grants, pools, machine tokens, credential ownership, and downstream OAuth                   |
-| [Architecture](./architecture.md)                           | Request lifetimes, routes, storage, configuration, import boundaries, and Effect implementation               |
-| [Operator UI](./operator-ui.md)                             | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
-| [Operator UI tests](./operator-tests.md)                    | Browser state matrix, real-server flows, and snapshot maintenance                                             |
-| [Provider migration for 0.29](./provider-migration-0.29.md) | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
-| [Provider auth migration](./provider-auth-migration.md)     | Upgrade actions when `auth` selects hosted MCP or Connecta's REST connector, Stripe and Vercel                |
+| Guide                                                            | Owns                                                                                                          |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [Meta-tools](./meta-tools.md)                                    | Six top-level tools, discovery, direct-call results, paging, skills, and recovery                             |
+| [Code mode](./code-mode.md)                                      | JavaScript guest API, executor requirements, output, retries, cancellation, limits, and writes                |
+| [Auth](./auth.md)                                                | Inbound identity, maintainers, pools and members, agents, credential ownership, and downstream OAuth          |
+| [Architecture (contributor reference)](./architecture.md)        | Request lifetimes, routes, storage, configuration, import boundaries, and Effect implementation               |
+| [Operator UI](./operator-ui.md)                                  | Optional UI setup, scoped configuration and live-data contract, activity disclosure, and UI implementation    |
+| [Operator UI tests (contributor reference)](./operator-tests.md) | Browser state matrix, real-server flows, and snapshot maintenance                                             |
+| [Migration to 0.33](./migration-0.33.md)                         | Upgrade actions from 0.32 options to maintainers, members, agents, agent endpoints, and pool owners           |
+| [Provider migration for 0.29](./provider-migration-0.29.md)      | Upgrade actions for Notion, Vercel, and Cloudflare; provider reconciliation tables supply exact name mappings |
+| [Provider auth migration](./provider-auth-migration.md)          | Upgrade actions when `auth` selects hosted MCP or Connecta's REST connector, Stripe and Vercel                |
 
 Each long contract starts with task routes. Follow those section links before
-reading the whole guide. Source and test pointers identify where to check a
-claim or implement a change.
+reading the whole guide. Contributor references at the end are optional
+implementation evidence.
+
+## Contributor reference
 
-## Documentation ownership
+### Documentation ownership
 
 The root [README](../README.md) explains the product for people. It owns what
 Connecta offers, how the pieces connect, deployment choices, and the setup
@@ -47,7 +71,7 @@ own scoped change procedures. Each [provider folder](https://github.com/zackbart
 owns its maintained `SKILL.md`, options, tests, fixtures, and review data.
 Use those details instead of copying provider catalogs into general guides.
 The provider list in the human README is generated; preserve its marker pair
-and run `npm run check:providers-generated` after edits.
+and run `pnpm run check:providers-generated` after edits.
 
 When changing behavior, update its owning contract and task guide in the same
 change. Check examples against current source and point to the tests that