@zackbart/connecta 0.38.0 → 0.40.0

package/dist/operator-ui/model.d.ts

@@ -20,8 +20,12 @@ export interface UiTool extends Pick<OperatorTool, "name" | "address" | "descrip
  * (`credential_required`), or a secret that lives in deployment configuration
  * (`auth_required`). Principal forwarding instead reports `caller_refused`,
  * which has no secret-repair prompt.
+ *
+ * `connector_timeout` is a downstream that did not answer before the operator
+ * page's deadline: slow or unreachable, not known to be broken. The page
+ * stops retrying it on its own until someone asks with Refresh.
  */
-export type UiProblem = "connector_unavailable" | "oauth_required" | "credential_required" | "auth_required" | "caller_refused" | "credential_mismatch" | "catalog_failed";
+export type UiProblem = "connector_unavailable" | "connector_timeout" | "oauth_required" | "credential_required" | "auth_required" | "caller_refused" | "credential_mismatch" | "catalog_failed";
 /** A stored credential that cannot be used, by cause. */
 export type UiCredentialProblem = "credential_mismatch" | "credential_unreadable";
 interface UiCredentialField {
@@ -35,6 +39,13 @@ interface UiCredentialField {
     lastFour?: string;
     updatedAt?: string;
 }
+/** Mirrors `CredentialVerification` in src/credential-verification.ts. */
+export interface UiVerification {
+    outcome: "ok" | "unverified" | UiCredentialFailure;
+    observedAt: string;
+}
+/** Why a credential test failed, as the route reports it. */
+export type UiCredentialFailure = "rejected" | "scope" | "unreachable" | "timeout" | "failed";
 interface UiCredential {
     label: string;
     description?: string;
@@ -83,11 +94,21 @@ export interface UiConnector {
     authorizationUrl?: string;
     toolCount: number;
     tools: UiTool[];
+    /** Age of the stored status observation this row shows; absent on a live read. */
+    observedAgeMs?: number;
+    /** Browser-only: the stored observation's time, fixed as the row lands. */
+    observedAt?: number;
     /** This connector exposes manageable downstream OAuth lifecycle hooks. */
     oauth?: boolean;
     /** Selected downstream client identity mechanism; never a client ID or secret. */
     registrationPath?: "cimd" | "dcr" | "static";
     credential?: UiCredential;
+    /**
+     * The stored last verification of this connector's operator-managed
+     * credential. Absent when nothing has verified the save stored now. A
+     * typed outcome and a time; never vendor text.
+     */
+    verification?: UiVerification;
     /**
      * Drift the last catalog refresh saw *in this runtime*
      * ([#343](https://github.com/zackbart/connecta/issues/343)). Four counts and

package/dist/provider-call-facts.js

@@ -133,9 +133,13 @@ export function renewedAfterUnauthorized(request, sent, fresh) {
 export function refusalRequest(error) {
     return error !== null && typeof error === "object" ? refusals.get(error) : undefined;
 }
-export function knownProviderFailure(error) {
-    if (error !== null && typeof error === "object")
+/** A local refusal may additionally name the physical request it prevented. */
+export function knownProviderFailure(error, unsent) {
+    if (error !== null && typeof error === "object") {
         knownFailures.add(error);
+        if (unsent && !unsent.dispatched)
+            refusals.set(error, unsent);
+    }
     return error;
 }
 export function isKnownProviderFailure(error) {

package/dist/providers/_shared/rest/operation-index.js

@@ -11,7 +11,7 @@ import { parseIndexDetails } from "./compact-index.js";
 // are refused with the accepted names, because a guessed argument is the most
 // common way an agent wastes a call. Drift between the pin and the vendor is
 // caught by `providers:check` and refreshed by `providers:spec`.
-import { ConnectorCallError } from "../../../errors.js";
+import { ConnectorCallError, issueSummary } from "../../../errors.js";
 const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
 const MAX_ISSUES = 20;
 function words(text) {
@@ -21,11 +21,16 @@ function words(text) {
         .split(/[^a-z0-9]+/)
         .filter(Boolean);
 }
-function invalid(message, issues, repair) {
-    throw new ConnectorCallError("invalid_args", message, {
-        ...(issues ? { validation: { issues } } : {}),
-        ...(repair ? { repair } : {}),
-    });
+/** Index findings name no example: the hatch schema cannot prove an operation's arguments safe to echo. */
+function invalid(message, issues, details) {
+    throw new ConnectorCallError("invalid_args", message, issues
+        ? {
+            validation: {
+                issues,
+                exampleUnavailable: `Examples are withheld for API operations; read ${details} for the contract.`,
+            },
+        }
+        : {});
 }
 function typesOf(node) {
     return node.t === undefined ? [] : typeof node.t === "string" ? [node.t] : node.t;
@@ -42,7 +47,7 @@ function distance(a, b) {
     }
     return previous[b.length];
 }
-/** The accepted names, bounded and led by the likeliest intended one; repair details carry the full list. */
+/** The accepted names, bounded and led by the likeliest intended one; the full list is in the tool schema. */
 function oneOf(names, given) {
     const close = given === undefined
         ? undefined
@@ -245,7 +250,7 @@ export class OperationIndex {
                 best.rows.push(row);
         });
         if (best.rows.length === 0) {
-            invalid(`${this.#title} has no ${path} operation in the pinned API index (${this.revision}). ` +
+            invalid(`${this.#title} has no operation at that path in the pinned API index (${this.revision}). ` +
                 `Nearest: ${this.nearest(method, segments).join("; ")}. Find operations with ${this.#vendorTool("search")}.`);
         }
         const templates = new Set(best.rows.map((row) => this.ops[row].path));
@@ -279,17 +284,16 @@ export class OperationIndex {
             }
         });
         const issues = [];
-        const repair = [];
         for (const [name, at, , schema] of this.#row(op)?.[0] ?? []) {
             if (at === "path" && params[name] !== undefined)
-                this.#check(schema, decodeURIComponent(params[name]), `/path/${name}`, issues, repair);
+                this.#check(schema, decodeURIComponent(params[name]), `/path/${name}`, issues);
         }
         if (issues.length) {
             const shown = issues
                 .slice(0, 5)
-                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .map((issue) => issueSummary([issue]))
                 .join("; ");
-            invalid(`Not sent: the path does not match ${op.method} ${op.path} in the pinned API index: ${shown}. Substitute real ids matching ${this.#vendorTool("details")}.${issues.some((issue) => issue.expected?.includes("safe integer")) ? " Integer ids use canonical ASCII decimal notation within the safe-integer range." : ""}`, issues.slice(0, MAX_ISSUES));
+            invalid(`Not sent: the path does not match ${op.method} ${op.path} in the pinned API index: ${shown}. Substitute real ids matching ${this.#vendorTool("details")}.${issues.some((issue) => issue.expected?.includes("safe integer")) ? " Integer ids use canonical ASCII decimal notation within the safe-integer range." : ""}`, issues.slice(0, MAX_ISSUES), this.#vendorTool("details"));
         }
         return { op, params };
     }
@@ -458,7 +462,7 @@ export class OperationIndex {
             }
         }
         if (only !== undefined && parameters.length === 0 && body === undefined) {
-            invalid(`${op.method} ${op.path} has no parameter named ${only}.`);
+            invalid(`${op.method} ${op.path} has no parameter by that name.`);
         }
         return {
             method: op.method,
@@ -480,7 +484,6 @@ export class OperationIndex {
     check(op, query, body) {
         const row = this.#row(op);
         const issues = [];
-        const repair = [];
         const declared = (row ? row[0] : []).filter(([, at]) => at === "query");
         const accepted = declared.map(([name]) => name);
         for (const [name, value] of Object.entries(query)) {
@@ -489,40 +492,39 @@ export class OperationIndex {
             const param = declared.find(([key]) => key === name);
             if (!param) {
                 issues.push({
-                    path: `/query/${name}`,
-                    code: "additionalProperties",
+                    path: "/query/<key>",
                     expected: accepted.length ? oneOf(accepted, name) : "no query parameters",
+                    received: valueType(value),
                 });
-                repair.push({ path: `/query/${name}`, receivedType: valueType(value), acceptedKeys: accepted });
                 continue;
             }
-            this.#check(param[3], value, `/query/${name}`, issues, repair);
+            this.#check(param[3], value, `/query/${name}`, issues);
         }
         for (const [name, , required] of declared) {
             if (required === 1 && query[name] === undefined) {
-                issues.push({ path: `/query/${name}`, code: "required", expected: "a value" });
+                issues.push({ path: `/query/${name}`, expected: "a value (required)", received: "missing" });
             }
         }
         const bodyRow = row && row[1] !== 0 ? row[1] : undefined;
         if (body !== undefined) {
             if (!bodyRow) {
-                issues.push({ path: "/body", code: "false", expected: "no body for this operation" });
+                issues.push({ path: "/body", expected: "no body for this operation" });
             }
             else {
-                this.#check(bodyRow[1], body, "/body", issues, repair);
+                this.#check(bodyRow[1], body, "/body", issues);
             }
         }
         else if (bodyRow?.[2] === 1) {
             // An optional body may be omitted whole; a required one may not.
-            issues.push({ path: "/body", code: "required", expected: `a ${bodyRow[0]} body` });
+            issues.push({ path: "/body", expected: `a ${bodyRow[0]} body (required)`, received: "missing" });
         }
         if (issues.length > 0) {
             const shown = issues
                 .slice(0, 5)
-                .map((issue) => `${issue.path} (${issue.code}: ${issue.expected})`)
+                .map((issue) => issueSummary([issue]))
                 .join("; ");
             invalid(`Not sent: the arguments do not match ${op.method} ${op.path} in the pinned API index: ${shown}` +
-                `${issues.length > 5 ? `; ${issues.length - 5} more` : ""}. Read ${this.#vendorTool("details")} for the contract.`, issues.slice(0, MAX_ISSUES), repair.length ? { issues: repair.slice(0, 5) } : undefined);
+                `${issues.length > 5 ? `; ${issues.length - 5} more` : ""}. Read ${this.#vendorTool("details")} for the contract.`, issues.slice(0, MAX_ISSUES), this.#vendorTool("details"));
         }
     }
     #vendorTool(kind) {
@@ -606,7 +608,7 @@ export class OperationIndex {
             out["truncated"] = true;
         return out;
     }
-    #check(node, value, at, issues, repair) {
+    #check(node, value, at, issues) {
         if (issues.length >= MAX_ISSUES)
             return;
         const schema = this.#deref(node);
@@ -624,7 +626,6 @@ export class OperationIndex {
                 (integer && !Number.isSafeInteger(numeric))) {
                 issues.push({
                     path: at,
-                    code: "type",
                     expected: integer ? "a canonical ASCII decimal safe integer" : "a canonical ASCII decimal number",
                 });
                 return;
@@ -635,7 +636,7 @@ export class OperationIndex {
             if (types.includes("boolean") && (value === "true" || value === "false"))
                 value = value === "true";
             else {
-                issues.push({ path: at, code: "type", expected: types.join(" or ") });
+                issues.push({ path: at, expected: types.join(" or ") });
                 return;
             }
         }
@@ -644,7 +645,7 @@ export class OperationIndex {
         // Conflicting composed constraints (disjoint enums or types) admit nothing,
         // not even the null or "" that otherwise unsets a field.
         if (schema.e?.length === 0) {
-            issues.push({ path: at, code: "enum", expected: "no value: this field's combined constraints admit none" });
+            issues.push({ path: at, expected: "no value: this field's combined constraints admit none" });
             return;
         }
         // Only newly opted-in bounded schemas enforce scalar numeric values;
@@ -661,42 +662,40 @@ export class OperationIndex {
                     ? Number(value)
                     : NaN;
             if (!Number.isFinite(numeric) || (integer && !Number.isSafeInteger(numeric))) {
-                issues.push({ path: at, code: "type", expected: integer ? "integer" : "finite number" });
+                issues.push({ path: at, expected: integer ? "integer" : "finite number" });
                 return;
             }
             if (schema.l !== undefined && numeric < schema.l)
-                issues.push({ path: at, code: "minimum", expected: `at least ${schema.l}` });
+                issues.push({ path: at, expected: `at least ${schema.l}`, received: "number" });
             if (schema.u !== undefined && numeric > schema.u)
-                issues.push({ path: at, code: "maximum", expected: `at most ${schema.u}` });
+                issues.push({ path: at, expected: `at most ${schema.u}`, received: "number" });
         }
         if (value === null || value === "")
             return;
         if (schema.a) {
             let fewest;
             for (const branch of schema.a) {
-                const attempt = { issues: [], repair: [] };
-                this.#check(branch, value, at, attempt.issues, attempt.repair);
-                if (attempt.issues.length === 0)
+                const attempt = [];
+                this.#check(branch, value, at, attempt);
+                if (attempt.length === 0)
                     return;
-                if (!fewest || attempt.issues.length < fewest.issues.length)
+                if (!fewest || attempt.length < fewest.length)
                     fewest = attempt;
             }
-            if (fewest) {
-                issues.push(...fewest.issues);
-                repair.push(...fewest.repair);
-            }
+            if (fewest)
+                issues.push(...fewest);
             return;
         }
         if (schema.e && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")) {
             if (!schema.e.some((option) => option === value || String(option) === String(value))) {
-                issues.push({ path: at, code: "enum", expected: oneOf(schema.e.map(String)) });
+                issues.push({ path: at, expected: oneOf(schema.e.map(String)) });
             }
             return;
         }
         if (schema.p || types.includes("object")) {
             if (!isRecord(value)) {
                 if (types.length === 0 || types.includes("object")) {
-                    issues.push({ path: at, code: "type", expected: "object" });
+                    issues.push({ path: at, expected: "object" });
                 }
                 return;
             }
@@ -707,35 +706,34 @@ export class OperationIndex {
                     continue;
                 const child = properties[key];
                 if (child)
-                    this.#check(child, item, `${at}/${key}`, issues, repair);
+                    this.#check(child, item, `${at}/${key}`, issues);
                 else if (schema.m)
-                    this.#check(schema.m, item, `${at}/${key}`, issues, repair);
+                    this.#check(schema.m, item, `${at}/<key>`, issues);
                 else if (schema.p) {
                     issues.push({
-                        path: `${at}/${key}`,
-                        code: "additionalProperties",
+                        path: `${at}/<key>`,
                         expected: accepted.length ? oneOf(accepted, key) : "no properties",
+                        received: valueType(item),
                     });
-                    repair.push({ path: `${at}/${key}`, receivedType: valueType(item), acceptedKeys: accepted });
                 }
             }
             for (const key of schema.r ?? []) {
                 if (value[key] === undefined)
-                    issues.push({ path: `${at}/${key}`, code: "required", expected: "a value" });
+                    issues.push({ path: `${at}/${key}`, expected: "a value (required)", received: "missing" });
             }
             return;
         }
         if (schema.i || types.includes("array")) {
             if (!Array.isArray(value)) {
-                issues.push({ path: at, code: "type", expected: "array" });
+                issues.push({ path: at, expected: "array" });
                 return;
             }
             if (schema.i)
-                value.forEach((item, index) => this.#check(schema.i, item, `${at}/${index}`, issues, repair));
+                value.forEach((item, index) => this.#check(schema.i, item, `${at}/${index}`, issues));
             return;
         }
         if (types.length > 0 && (isRecord(value) || Array.isArray(value))) {
-            issues.push({ path: at, code: "type", expected: types.join(" or ") });
+            issues.push({ path: at, expected: types.join(" or ") });
         }
     }
 }

package/dist/providers/_shared/rest/value-safety.js

@@ -1338,6 +1338,53 @@ function acceptsCredential(schema, depth) {
         acceptsCredential(node.items, depth + 1) ||
         (node.anyOf ?? []).some((branch) => acceptsCredential(branch, depth + 1)));
 }
+const ENV_VALUE_NAMES = ENV_VALUE_FIELDS.map(normalizedName);
+/** `data[].id` segments as tokens, a list's items as `[]`: `["data", "[]", "id"]`. */
+function tokensOf(segments) {
+    return segments.flatMap((segment) => segment === "[]"
+        ? ["[]"]
+        : segment.endsWith("[]")
+            ? [normalizedName(segment.slice(0, -2)), "[]"]
+            : [normalizedName(segment)]);
+}
+/**
+ * A best-effort hint for discovery over rules that change every non-null value
+ * they reach: a path is withheld when it sits at or inside a reviewed redaction
+ * path (matched from the body's root, or at any depth with `anyDepth`), or any
+ * of its names satisfies the name rule, which also sees the parent's name.
+ * Paths carry their list markers: a reviewed `[]` needs a declared list there,
+ * while a named segment also reaches every item of a list. Rules that can leave
+ * a value unchanged (`url:`, `origin:` or `#url` sanitizing, `[?…]`, `@keys`)
+ * are not hints. Names compare normalized, and `{}` or `*` matches any name.
+ */
+export function pathWithholds(rules) {
+    const patterns = (rules.paths ?? []).flatMap((raw) => {
+        const { mode, segments } = parsePath(raw);
+        if (mode !== "redact" || segments.some((segment) => segment.startsWith("[?") || segment === "@keys"))
+            return [];
+        return [segments.map((segment) => (segment === "[]" ? "[]" : segment === "{}" ? "*" : normalizedName(segment)))];
+    });
+    const reaches = (pattern, tokens, from) => {
+        let at = from;
+        for (const part of pattern) {
+            if (part !== "[]")
+                while (tokens[at] === "[]")
+                    at += 1;
+            if (at >= tokens.length || (part === "[]" ? tokens[at] !== "[]" : part !== "*" && part !== tokens[at]))
+                return false;
+            at += 1;
+        }
+        return true;
+    };
+    return (path) => {
+        const tokens = tokensOf(path);
+        const names = tokens.filter((token) => token !== "[]");
+        if (rules.names && names.some((name, at) => rules.names(name, names[at - 1] ?? "")))
+            return true;
+        const starts = rules.anyDepth ? tokens.flatMap((token, at) => (token === "[]" ? [] : [at])) : [0];
+        return patterns.some((pattern) => starts.some((at) => reaches(pattern, tokens, at)));
+    };
+}
 /** A vendor's value-safety mechanism over its reviewed table and pinned index. */
 export function valueSafety(table, index) {
     const fields = table.fields ?? {};
@@ -1347,9 +1394,42 @@ export function valueSafety(table, index) {
         const key = `${method} ${template}`;
         return Object.hasOwn(table.operations, key) ? table.operations[key] : undefined;
     };
+    const hints = new Map();
+    const redactedNames = Object.entries(fields)
+        .filter(([, review]) => review.verdict === "redact")
+        .map(([name]) => normalizedName(name));
+    const keptNames = Object.entries(fields)
+        .filter(([, review]) => review.verdict === "keep")
+        .map(([name]) => normalizedName(name));
+    const scopeParents = scopeMaps.map(normalizedName);
     return {
         table,
         verdict,
+        withholds(method, template) {
+            const key = `${method} ${template}`;
+            let hint = hints.get(key);
+            if (!hint) {
+                const reviewed = verdict(method, template);
+                const env = table.envBodies?.test(template) === true;
+                const kept = new Set([
+                    ...keptNames,
+                    ...(reviewed && reviewed.verdict !== "refuse" ? (reviewed.keep ?? []) : []).map((path) => trailOf(path).map(normalizedName).at(-1)),
+                ]);
+                hint =
+                    reviewed?.verdict === "refuse"
+                        ? () => true
+                        : pathWithholds({
+                            paths: reviewed?.verdict === "redact" ? reviewed.paths : [],
+                            names: (name, parent) => redactedNames.includes(name) ||
+                                (env && ENV_VALUE_NAMES.includes(name)) ||
+                                (parent === "deployhooks" && name === "url") ||
+                                // The suffix rule scrubs only strings, so only the whole-value credential rule hints.
+                                (!kept.has(name) && !scopeParents.includes(parent) && containsCredential(name)),
+                        });
+                hints.set(key, hint);
+            }
+            return hint;
+        },
         refusal(method, template) {
             const reviewed = verdict(method, template);
             return reviewed?.verdict === "refuse" ? `Connecta refuses ${method} ${template}. ${reviewed.reason}` : undefined;

package/dist/providers/breeze/api.js

@@ -1,3 +1,5 @@
+import { Routes, routePhrases } from "../../agent-routes.js";
+import { pathWithholds } from "../_shared/rest/value-safety.js";
 import { asRecord } from "../_shared/json.js";
 // Breeze's reviewed GET-only vendor. HTTP methods do not establish safety: see tools.ts.
 import { Effect, Schema } from "effect";
@@ -467,10 +469,11 @@ export const admit = (url) => {
 };
 export const authenticate = Effect.gen(function* () {
     const values = yield* (yield* Credentials).values.pipe(Effect.mapError((error) => new Refusal({ error })));
+    const routes = yield* Routes;
     const key = values?.["value"]?.trim();
     if (!key)
         return yield* Effect.fail(new Refusal({
-            error: new ConnectorCallError("auth_required", "No Breeze API key is configured for this connector. Call authorize_connector for recovery options. When available, an operator can add the key in this connection in the operator UI."),
+            error: new ConnectorCallError("auth_required", `No Breeze API key is configured for this connector. ${routePhrases(routes).authorizeFor("recovery options")}. When available, an operator can add the key in this connection in the operator UI.`),
         }));
     return { "Api-Key": key };
 });
@@ -537,6 +540,9 @@ export const breezeSafety = {
             })(),
         }),
         redact: (body, op) => withoutCalendarFeeds(op.template, body),
+        withholds: (op) => op.template === "/events/calendars/list"
+            ? pathWithholds({ names: (name) => name === "address" || name === "embedkey" })
+            : () => false,
         withholdsErrors: () => false,
     },
     sensitiveFields: { names: [], choice: "drop" },

package/dist/providers/breeze/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Church records\n\nBreeze ChMS (now Tithely Church Management) holds people, tags, events,\nattendance, forms, volunteers and giving. People carry contact information,\nbirthdates and family ties; giving reveals donors and amounts. Reduce records\nin code and return only the names, counts or totals the task needs.\n\n## Ids and joins\n\nIds are numeric strings. Resolve them from the relevant inventory before\nwriting. Events have an occurrence id and a series `eventId`; attendance,\nvolunteers and check-in use the occurrence id. Event and pledge lists can lag\nup to 15 minutes behind the site. An all-zero MySQL date means no time was\nrecorded, including no check-out.\n\nProfile `details` use field ids, not names. Resolve field and option ids from\n`list_profile_fields`; multiple-choice filters join option ids with `-`.\nA person-name lookup requires listing people and matching in code. Form entry\nresponses similarly join to that form's field ids.\n\n## Giving\n\nGiving, funds and pledges use archival endpoints removed from the public\nreference in 2023. They can change or vanish without notice. Amounts are\nexact decimal strings: reduce them with integer-cent arithmetic, and read the\ncurrency from `get_account_summary`. A split gift's fund amounts belong to\nits fund ids. Tithe.ly deposits sync in batches, so recent gifts can be absent.\nEditing a giving transaction may return a new payment id.\nUse `limit: 1000` when reducing broad giving ranges: each local page refetches\nthe bounded vendor list, so larger windows avoid repeated full-list fetches.\n\n## Required sequences\n\nCheck for an existing person before adding one: creation does not deduplicate.\nResolve profile fields before updating them. Text, dates (M/D/YYYY) and option\nids use `response`; email, phone, address and family-role values use `details`.\nNamed person writes take these entries in `values`.\nFamily changes can remove previous associations. Attendance check-out records\na departure time; removing attendance deletes the record instead.\n\nBreeze sends writes as GET requests too. Query names ending in `_json` take\nJSON-encoded strings. The named person writes encode their typed profile values\nfor you. The account-log `object_json` is a serialized affected-object value;\nits free-text description has no stable schema. Events and account logs have\nvendor caps: narrow the date range when the result fills its limit.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `breeze_api_details`, `breeze_api_search`, `list_attendance`, `list_contributions`, `list_funds`, `list_people`, `list_profile_fields`, `list_tags`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `breeze_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 100, at most 1000). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `breeze_api_search` finds this API's operations and reads no account data, `breeze_api_details` shows one operation's contract, and `breeze_api_read` calls a reviewed read. `breeze_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## Church records\n\nBreeze ChMS (now Tithely Church Management) holds people, tags, events,\nattendance, forms, volunteers and giving. People carry contact information,\nbirthdates and family ties; giving reveals donors and amounts. Reduce records\nin code and return only the names, counts or totals the task needs.\n\n## Ids and joins\n\nIds are numeric strings. Resolve them from the relevant inventory before\nwriting. Events have an occurrence id and a series `eventId`; attendance,\nvolunteers and check-in use the occurrence id. Event and pledge lists can lag\nup to 15 minutes behind the site. An all-zero MySQL date means no time was\nrecorded, including no check-out.\n\nProfile `details` use field ids, not names. Resolve field and option ids from\n`list_profile_fields`; multiple-choice filters join option ids with `-`.\nA person-name lookup requires listing people and matching in code. Form entry\nresponses similarly join to that form's field ids.\n\n## Giving\n\nGiving, funds and pledges use archival endpoints removed from the public\nreference in 2023. They can change or vanish without notice. Amounts are\nexact decimal strings: reduce them with integer-cent arithmetic, and read the\ncurrency from `get_account_summary`. A split gift's fund amounts belong to\nits fund ids. Tithe.ly deposits sync in batches, so recent gifts can be absent.\nEditing a giving transaction may return a new payment id.\nUse `limit: 1000` when reducing broad giving ranges: each local page refetches\nthe bounded vendor list, so larger windows avoid repeated full-list fetches.\n\n## Required sequences\n\nCheck for an existing person before adding one: creation does not deduplicate.\nResolve profile fields before updating them. Text, dates (M/D/YYYY) and option\nids use `response`; email, phone, address and family-role values use `details`.\nNamed person writes take these entries in `values`.\nFamily changes can remove previous associations. Attendance check-out records\na departure time; removing attendance deletes the record instead.\n\nBreeze sends writes as GET requests too. Query names ending in `_json` take\nJSON-encoded strings. The named person writes encode their typed profile values\nfor you. The account-log `object_json` is a serialized affected-object value;\nits free-text description has no stable schema. Events and account logs have\nvendor caps: narrow the date range when the result fills its limit.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `breeze_api_details`, `breeze_api_search`, `list_attendance`, `list_contributions`, `list_funds`, `list_people`, `list_profile_fields`, `list_tags`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `breeze_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 100, at most 1000). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `breeze_api_search` finds this API's operations and reads no account data, `breeze_api_details` shows one operation's contract, and `breeze_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `breeze_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Church instructions"
 };

package/dist/providers/breeze/tools.js

@@ -6,7 +6,7 @@ import { ConnectorCallError } from "../../errors.js";
 import { Refusal } from "../../http/errors.js";
 import { Integer, isMinChars, isMaxChars } from "../../http/json-schema.js";
 import { RequestSecrets, Classification } from "../../http/services.js";
-import { fieldsInput, fieldsProblem, selectFields } from "../../http/fields.js";
+import { fieldsContract, selectFields } from "../../http/fields.js";
 import { read, list, write as writeTool } from "../../http/tools.js";
 import { READ_ENDPOINTS } from "./api.js";
 const DEFAULT_EVENT_LIMIT = 100;
@@ -218,6 +218,7 @@ const Result_list_events = Schema.Struct({
 });
 const Row_list_events = Result_list_events.fields.events.value;
 const SelectedEvent = Schema.Struct(Object.fromEntries(Object.entries(Row_list_events.fields).map(([name, schema]) => [name, Schema.optionalKey(schema)])));
+const EVENT_FIELDS = fieldsContract("item", SelectedEvent);
 const Result_list_attendance = Schema.Struct({
     "attendance": Schema.Array(Schema.Struct({
         "personId": Schema.String,
@@ -527,7 +528,7 @@ export function breezeTools({ connection, pageSize: defaultPageSize, }) {
                     description: "Instances returned, 1 to Breeze's 1000. Defaults to 100.",
                     default: 100,
                 })),
-                fields: Schema.optionalKey(fieldsInput("Dot paths to keep in each event item.")),
+                fields: Schema.optionalKey(EVENT_FIELDS.input),
             }),
             output: Schema.Struct({
                 items: Schema.Array(SelectedEvent),
@@ -535,7 +536,7 @@ export function breezeTools({ connection, pageSize: defaultPageSize, }) {
                 truncated: Schema.optionalKey(Schema.Array(Schema.String)),
             }),
             run: (args) => Effect.gen(function* () {
-                const error = fieldsProblem(args.fields, new Set(Object.keys(Row_list_events.fields)), "an event item");
+                const error = EVENT_FIELDS.problem(args.fields);
                 if (error)
                     return yield* Effect.fail(new Refusal({ error }));
                 const result = yield* load_list_events(args);

package/dist/providers/ccb/api.js

@@ -1,4 +1,5 @@
 import { asRecord, asArray } from "../_shared/json.js";
+import { routePhrases } from "../../agent-routes.js";
 import { CCB_MEDIA_TYPE, CCB_ENVIRONMENTS, CCB_READ_SCOPES, CCB_WRITE_SCOPES, CCB_SENSITIVE_FIELDS, } from "./lib/constants.js";
 // Pushpay ChMS v2 JSON contracts, OAuth, status meanings, admission and privacy.
 // The legacy per-church XML API is outside this provider's scope.
@@ -465,7 +466,7 @@ export const errors = {
     statuses: {
         401: () => ({
             code: "auth_required",
-            words: (detail) => `${detail} CCB rejected the connection's access token. Call authorize_connector for this connector.`,
+            words: (detail, routes) => `${detail} CCB rejected the connection's access token. ${routePhrases(routes).authorizeFor("this connector")}.`,
             advice: ", then retry",
         }),
         403: () => ({

package/dist/providers/ccb/index.js

@@ -47,6 +47,11 @@ export const ccb = defineApiProvider({
         note: "./providers/ccb merged GitHub/Cloudflare/CCB step-2 snapshot measures 391,649 B standalone gzip-9 before recording these bundle facts, Node 26.12.0 with zlib-ng 1.3.1; recomputed with the combined opt-in hatch support. Earlier step-2 standalone gzip snapshot at ffd64b04, CI run 40080865116 static job, Node 22.23.3, against main ce0c7492 (345,272 B). Includes the reviewed 385-operation request/response index. Shared Effect is paid once per deployment; provider entries are reported, uncapped and non-additive (#703) (#899).",
     },
     skill,
+    // The guide resolves a person from individuals and a household from families.
+    searchSynonyms: [
+        ["person", "individual"],
+        ["household", "family"],
+    ],
     options: CCB_OPTIONS,
     displayTitle: (options) => defaultTitle(options.environment, options.mode, writable(options)),
     description: (options) => `Church Community Builder (Pushpay ChMS) — ${routingLine(options.environment, options.mode, writable(options))}: ${options.purpose}`,

package/dist/providers/ccb/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## People, households and groups\n\nCCB v2 addresses records by integer ids. Resolve a person from the individual\nlist and a household from families; never guess ids. Family membership and\nchurch group membership join by individual id. A membership role belongs to\nthat group, rather than being a property of the person everywhere.\n\nIdentity Auth acts with the signed-in person's permissions. A permission\nrefusal can mean that person lacks access even when the connection is healthy.\n\n## Events and attendance\n\nAn event is a series; its dated occurrence is a separate identity. Attendance\njoins need both the event id and occurrence. Preserve the vendor's date and\ntime-zone meaning instead of treating every occurrence as UTC midnight.\n\n## Pastoral and financial records\n\nNotes, background checks, pledges and giving metrics can be sensitive. Read\nonly what the task needs and reduce those records inside execute_code before\nreturning an answer. Gift metrics are counts by period, with a range of at\nmost twelve months. Per-gift transactions and amounts belong to the legacy\nv1 XML API, which this v2 connector does not reach.\n\n## Vendor call rates and recovery\n\nCCB meters endpoints separately per API client. Individual profile reads have\nno burst; individual advanced searches allow one call per five seconds, and\ncategory schedule lists allow one per two seconds. Prefer list pages over a\nloop of individual gets. Other deployments sharing the client spend from the\nsame vendor allowance.\n\nFor a profile edit, resolve the individual first and preserve fields outside\nthe requested change. Use `ccb_api_write` for the edit; the host may ask the\nuser to confirm. After an ambiguous update, read that profile to determine\nwhat actually changed before deciding whether another write is needed.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `ccb_api_details`, `ccb_api_read`, `ccb_api_search`, `list_event_attendees`, `list_events`, `list_families`, `list_group_members`, `list_groups`, `list_individual_groups`, `list_individual_notes`, `list_individuals`, `search_records`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `ccb_api_search` finds this API's operations and reads no account data, `ccb_api_details` shows one operation's contract, and `ccb_api_read` calls a reviewed read. `ccb_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 14 operations are refused by design; use `ccb_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## People, households and groups\n\nCCB v2 addresses records by integer ids. Resolve a person from the individual\nlist and a household from families; never guess ids. Family membership and\nchurch group membership join by individual id. A membership role belongs to\nthat group, rather than being a property of the person everywhere.\n\nIdentity Auth acts with the signed-in person's permissions. A permission\nrefusal can mean that person lacks access even when the connection is healthy.\n\n## Events and attendance\n\nAn event is a series; its dated occurrence is a separate identity. Attendance\njoins need both the event id and occurrence. Preserve the vendor's date and\ntime-zone meaning instead of treating every occurrence as UTC midnight.\n\n## Pastoral and financial records\n\nNotes, background checks, pledges and giving metrics can be sensitive. Read\nonly what the task needs and reduce those records inside execute_code before\nreturning an answer. Gift metrics are counts by period, with a range of at\nmost twelve months. Per-gift transactions and amounts belong to the legacy\nv1 XML API, which this v2 connector does not reach.\n\n## Vendor call rates and recovery\n\nCCB meters endpoints separately per API client. Individual profile reads have\nno burst; individual advanced searches allow one call per five seconds, and\ncategory schedule lists allow one per two seconds. Prefer list pages over a\nloop of individual gets. Other deployments sharing the client spend from the\nsame vendor allowance.\n\nFor a profile edit, resolve the individual first and preserve fields outside\nthe requested change. Use `ccb_api_write` for the edit; the host may ask the\nuser to confirm. After an ambiguous update, read that profile to determine\nwhat actually changed before deciding whether another write is needed.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `ccb_api_details`, `ccb_api_read`, `ccb_api_search`, `list_event_attendees`, `list_events`, `list_families`, `list_group_members`, `list_groups`, `list_individual_groups`, `list_individual_notes`, `list_individuals`, `search_records`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 25, at most 100). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Hatch:** `ccb_api_search` finds this API's operations and reads no account data, `ccb_api_details` shows one operation's contract, and `ccb_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `ccb_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 14 operations are refused by design; use `ccb_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Church instructions"
 };

package/dist/providers/cloudflare/api.js

@@ -433,7 +433,7 @@ class CloudflareIndex extends OperationIndex {
         for (const name of EXCLUSIVE_PATH_IDS[`${match.op.method} ${match.op.path}`] ?? []) {
             if (Number(decodeURIComponent(match.params[name])) < 1) {
                 throw new ConnectorCallError("invalid_args", `Not sent: Cloudflare path parameter ${name} must be at least 1. Read cloudflare_api_details for the pinned contract.`, {
-                    validation: { issues: [{ path: `/path/${name}`, code: "minimum", expected: "at least 1" }] },
+                    validation: { issues: [{ path: `/path/${name}`, expected: "at least 1" }] },
                 });
             }
         }
@@ -528,6 +528,13 @@ export const safety = () => {
                 }
                 : SAFETY.redact(body, operation.method, canonical(operation)),
             withholdsErrors: (operation) => operation.method === "POST" && operation.template === "/graphql" ? false : reviewed.withholdsErrors(operation),
+            // The table applies to the envelope and again to its result, as redact does.
+            withholds: (operation) => {
+                const hint = reviewed.withholds(operation);
+                return (path) => hint(path) ||
+                    (path[0] === "result" && hint(path.slice(1))) ||
+                    (path[0] === "result[]" && hint(["[]", ...path.slice(1)]));
+            },
         },
         sensitiveFields: { names: [], choice: "drop" },
     };

package/dist/providers/cloudflare/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Accounts, domains and records\n\nResolve account and zone ids before acting. A zone is a domain, found by its name;\nits account id joins it to the account inventory. Cloudflare ids are normally\n32-character hex strings. A default id routes a request; a pin limits its scope.\n\nDNS TTL is in seconds; TTL 1 means automatic. Read the record before changing it.\nPATCH changes supplied fields; PUT replaces the record, so preserve its type,\nname and content. Read state before replacing, rolling back or purging. Prefer\na targeted cache purge by files, tags, hosts or prefixes over purging everything.\n\nHatch data keeps Cloudflare's vendor envelope. For example, select DNS record\nidentities with `fields: [\"result.id\", \"result.name\"]`; a list stays under\n`data.result`. Named account and zone lists keep projected rows with camelCase\naccount and name-server fields.\n\n## Workers, storage and analytics\n\nWorker script source is code; secret binding values are separate and unavailable.\nKV values are application data. Encode a slash inside a KV key or R2 object key\nas `%2F`. R2 requires API-token authentication, rather than a Global API Key.\n\nGraphQL Analytics uses accountTag and zoneTag for account/zone identities.\nFilter every accounts/zones field by equality or an explicit set of those ids.\nA pinned query uses one operation per document and every declared fragment.\nAnalytics Engine SQL is read-only; D1 SQL and Durable Object queries can write.\nAI inference, previews and outbound checks can cost money or activate work.\n\n## Disqualifiers and recovery\n\nCredential minting, rotation, stored secrets, private session captures and signed\nupload or deployment links are unavailable. Use the Cloudflare dashboard for\ncredential administration. A Global API Key cannot change user settings or\nmemberships through this connection.\n\nAfter an authentication failure, use `verify_credential` once to distinguish a\nrejected credential from a permission gap. An operator replaces the credential;\nrepeating the failed request does not add permissions. Cloudflare's global limit\ncounts dashboard traffic and all tokens together, so reduce requests as well as\nhonoring the returned wait.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `cloudflare_api_details`, `cloudflare_api_search`, `list_accounts`, `list_zones`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `cloudflare_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 20, at most 50). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Envelope fields:** hatch data keeps the vendor envelope. Select declared fields with `fields: [\"result.id\", \"result.name\"]`; array traversal also accepts `result[].id`. Named reads keep their projected fields.\n- **Hatch:** `cloudflare_api_search` finds this API's operations and reads no account data, `cloudflare_api_details` shows one operation's contract, and `cloudflare_api_read` calls a reviewed read. `cloudflare_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 70 operations are refused by design; use `cloudflare_api_details` with the method and path to inspect the original operation summary and its separate refusal. Use details for refused methods outside the read/write call schemas; those methods remain unavailable.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
+    "content": "## Accounts, domains and records\n\nResolve account and zone ids before acting. A zone is a domain, found by its name;\nits account id joins it to the account inventory. Cloudflare ids are normally\n32-character hex strings. A default id routes a request; a pin limits its scope.\n\nDNS TTL is in seconds; TTL 1 means automatic. Read the record before changing it.\nPATCH changes supplied fields; PUT replaces the record, so preserve its type,\nname and content. Read state before replacing, rolling back or purging. Prefer\na targeted cache purge by files, tags, hosts or prefixes over purging everything.\n\nHatch data keeps Cloudflare's vendor envelope. For example, select DNS record\nidentities with `fields: [\"result.id\", \"result.name\"]`; a list stays under\n`data.result`. Named account and zone lists keep projected rows with camelCase\naccount and name-server fields.\n\n## Workers, storage and analytics\n\nWorker script source is code; secret binding values are separate and unavailable.\nKV values are application data. Encode a slash inside a KV key or R2 object key\nas `%2F`. R2 requires API-token authentication, rather than a Global API Key.\n\nGraphQL Analytics uses accountTag and zoneTag for account/zone identities.\nFilter every accounts/zones field by equality or an explicit set of those ids.\nA pinned query uses one operation per document and every declared fragment.\nAnalytics Engine SQL is read-only; D1 SQL and Durable Object queries can write.\nAI inference, previews and outbound checks can cost money or activate work.\n\n## Disqualifiers and recovery\n\nCredential minting, rotation, stored secrets, private session captures and signed\nupload or deployment links are unavailable. Use the Cloudflare dashboard for\ncredential administration. A Global API Key cannot change user settings or\nmemberships through this connection.\n\nAfter an authentication failure, use `verify_credential` once to distinguish a\nrejected credential from a permission gap. An operator replaces the credential;\nrepeating the failed request does not add permissions. Cloudflare's global limit\ncounts dashboard traffic and all tokens together, so reduce requests as well as\nhonoring the returned wait.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `cloudflare_api_details`, `cloudflare_api_search`, `list_accounts`, `list_zones`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `cloudflare_api_read`, put it in `query[page.param]` or `body[page.param]`, as `page.in` specifies. Keep the original method, path, filters, page size, fields and headers. Paged `list_*` and `search_*` reads take `limit` (default 20, at most 50). The last page has no `nextCursor`. If `page.hasMore` is true without a cursor, the data is incomplete and continuation was withheld. When approaching execute_code's per-program call limit, return page.nextCursor before the call that would exceed it and continue in the next program; don't restart.\n- **Results:** `fields` narrows a read's result to the dot paths you name. `truncated` lists the dot paths a result cut for size; the ids that fetch what was cut stay in the result.\n- **Envelope fields:** hatch data keeps the vendor envelope. Select declared fields with `fields: [\"result.id\", \"result.name\"]`; array traversal also accepts `result[].id`. Named reads keep their projected fields.\n- **Hatch:** `cloudflare_api_search` finds this API's operations and reads no account data, `cloudflare_api_details` shows one operation's contract, and `cloudflare_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `cloudflare_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 70 operations are refused by design; use `cloudflare_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Writes:** a write is sent once and never retried. When its outcome is unknown, read the target before repeating it. Writes take no idempotency key.\n- **Errors:** codes come from the vendor's statuses and error facts, never its prose. `not_found` means the record does not exist; this API tells absence from a permission gap. It documents no conflict.\n- **Withheld values:** a value withheld for safety reads `\"[redacted]\"`. Writes refuse whole marker values and withheld links; longer prose may mention the marker. Paths and queries refuse any containment.",
     "instructionsHeading": "Account instructions"
 };