@zackbart/connecta 0.41.0 → 0.42.0

package/dist/providers/overflow/index.js

@@ -68,6 +68,8 @@ export const overflow = defineApiProvider({
     pageSize: { default: DEFAULT_PAGE_SIZE, max: MAX_PAGE_SIZE },
     credential: API_KEY_CREDENTIAL,
     authenticate,
+    // docs.overflow.co/api-reference/authentication: "Public identifier"; x-api-key is the secret.
+    publicIdentifierHeaders: ["x-client-id"],
     admit,
     errors,
     idempotencyKey: false,

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Giving records and joins\n\nDonor ids join profiles, contributions, subscriptions and payment methods.\nCampaigns and subcampaigns allocate gifts; locations identify campuses.\nResolve names to ids before editing a donor or moving money. There is no funds\nendpoint: fund and sub-fund identifiers occur only in payment authorization.\nA donor profile owned by a donor account cannot be edited through this API;\nwhen reads work but its edit is denied, changing the credential does not fix it.\n\nTap groups contain devices and point to destinations. A tap is engagement,\nnot a gift; use contributions to establish giving.\n\n## Money and final status\n\nRead the unit per field. Values named `InCents` are cents, including deposits,\nrefunds, chargebacks and payment authorization. Subscription `amount` is\nin dollars. Contribution and saved-method charge `amount` have no stated unit\nin the public schema: establish it from a known gift before reporting a sum\nor authorizing a charge. Do not assume every numeric amount uses the same unit.\n\nA gift is final at `PAID_OUT` for `CASH`, `CONFIRMED` for manual cash or crypto,\n`CONTRIBUTION_RECEIVED` or `BILLED` for stock, and `CONTRIBUTION_RECEIVED` for\nDAF. A status bucket is coarser than those asset-specific states. Polling by\nupdated date finds later state changes; initiated date identifies when a donor gave.\n\n## Reconcile a deposit\n\nFind the bank payout, inspect its summary totals, then its line items.\nEach line item's `referenceId` names a contribution, refund or chargeback\naccording to its type; contributions can also carry a `depositId`.\nKeep gross, fee and net cent amounts separate and convert only for presentation.\nAn eligible cash gift under $1,000 is refunded with `POST /contributions/{contributionId}/initiate-refund`, which takes no body; its string acknowledgement means the refund started.\nA refund request starts processing; verify the gift or refund before claiming\nthat funds have reached the donor. Canceling a recurring gift stops future\npayments and does not refund earlier gifts.\n\n## Reduce donor and delivery data\n\nGiving history and donor contact details are personal data. Aggregate or join\ninside code and return names, email, phone and address only when the task needs\nthem. Lean contribution rows carry donor identity; the full donor lookup\ncarries contact details. Webhook delivery logs can include delivered donor\npayloads and the receiving server's response: select the status, response code\nand error needed for diagnosis instead of returning those payloads wholesale.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_campaigns`, `list_chargebacks`, `list_contributions`, `list_deposits`, `list_donors`, `list_locations`, `list_payment_methods`, `list_refunds`, `list_subscriptions`, `overflow_api_details`, `overflow_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `overflow_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 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:** `overflow_api_search` finds this API's operations and reads no account data, `overflow_api_details` shows one operation's contract, and `overflow_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `overflow_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": "## Giving records and joins\n\nDonor ids join profiles, contributions, subscriptions and payment methods.\nCampaigns and subcampaigns allocate gifts; locations identify campuses.\nResolve names to ids before editing a donor or moving money. There is no funds\nendpoint: fund and sub-fund identifiers occur only in payment authorization.\nA donor profile owned by a donor account cannot be edited through this API;\nwhen reads work but its edit is denied, changing the credential does not fix it.\n\nTap groups contain devices and point to destinations. A tap is engagement,\nnot a gift; use contributions to establish giving.\n\n## Money and final status\n\nRead the unit per field. Values named `InCents` are cents, including deposits,\nrefunds, chargebacks and payment authorization. Subscription `amount` is\nin dollars. Contribution and saved-method charge `amount` have no stated unit\nin the public schema: establish it from a known gift before reporting a sum\nor authorizing a charge. Do not assume every numeric amount uses the same unit.\n\nA gift is final at `PAID_OUT` for `CASH`, `CONFIRMED` for manual cash or crypto,\n`CONTRIBUTION_RECEIVED` or `BILLED` for stock, and `CONTRIBUTION_RECEIVED` for\nDAF. A status bucket is coarser than those asset-specific states. Polling by\nupdated date finds later state changes; initiated date identifies when a donor gave.\n\n## Reconcile a deposit\n\nFind the bank payout, inspect its summary totals, then its line items.\nEach line item's `referenceId` names a contribution, refund or chargeback\naccording to its type; contributions can also carry a `depositId`.\nKeep gross, fee and net cent amounts separate and convert only for presentation.\nAn eligible cash gift under $1,000 is refunded with `POST /contributions/{contributionId}/initiate-refund`, which takes no body; its string acknowledgement means the refund started.\nA refund request starts processing; verify the gift or refund before claiming\nthat funds have reached the donor. Canceling a recurring gift stops future\npayments and does not refund earlier gifts.\n\n## Reduce donor and delivery data\n\nGiving history and donor contact details are personal data. Aggregate or join\ninside code and return names, email, phone and address only when the task needs\nthem. Lean contribution rows carry donor identity; the full donor lookup\ncarries contact details. Webhook delivery logs can include delivered donor\npayloads and the receiving server's response: select the status, response code\nand error needed for diagnosis instead of returning those payloads wholesale.\n\n## Conventions\n\n- **Hatch:** `overflow_api_search` finds operations, `overflow_api_details` shows one contract, `overflow_api_read` calls a reviewed read and `overflow_api_write` a reviewed write.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap.",
     "instructionsHeading": "Nonprofit instructions"
 };

package/dist/providers/planning-center/index.js

@@ -36,11 +36,17 @@ export const planningCenter = defineApiProvider({
     safety: () => safety,
     probe,
     blocks: {
-        keys: [...PLANNING_CENTER_APPS, "lists", "limited"],
-        select: (options) => [
-            ...PLANNING_CENTER_APPS.filter((app) => !excludedApps(options.excludeApps).has(app)),
-            excludedApps(options.excludeApps).size === 0 ? "lists" : "limited",
-        ],
+        keys: [...PLANNING_CENTER_APPS, "lists", "limited", "people-writes", "giving-writes", "api-writes"],
+        select: (options) => {
+            const apps = PLANNING_CENTER_APPS.filter((app) => !excludedApps(options.excludeApps).has(app));
+            return [
+                ...apps,
+                excludedApps(options.excludeApps).size === 0 ? "lists" : "limited",
+                ...(options.readOnly
+                    ? []
+                    : ["people", "giving", "api"].filter((app) => apps.includes(app)).map((app) => `${app}-writes`)),
+            ];
+        },
     },
     guide: (options) => ({
         heading: "Planning Center usage",

package/dist/providers/planning-center/lib/constants.d.ts

@@ -55,4 +55,4 @@ export declare const PLANNING_CENTER_MAX_RESPONSE_BYTES: number;
  */
 export declare const PLANNING_CENTER_ADMISSION: ConnectorCallAdmissionPolicy;
 /** Planning Center refuses a request without a descriptive one (HTTP 403). */
-export declare const DEFAULT_USER_AGENT = "connecta/0.41.0 (+https://github.com/zackbart/connecta)";
+export declare const DEFAULT_USER_AGENT = "connecta/0.42.0 (+https://github.com/zackbart/connecta)";

package/dist/providers/planning-center/skill.generated.js

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Identity first\n\nA People person id joins records across products. Resolve people by identity,\nthen join on `person_id`; names can repeat. A membership, scheduled person,\nworkflow card and person each have their own record id.\n\n`get_me` identifies the token's user and the organization's time zone. Bare\ndates mean the organization's local day; use a timestamp with an offset for\nan exact boundary. Name filters are exact unless their value ends in `%`.\n\nAn old person id may have been merged. Read `/people/v2/person_mergers` with\n`where[person_to_remove_id]`, follow `person_to_keep_id`, then read that profile.\nAn empty history does not establish that a person was merged.\n\nReduce pastoral information inside `execute_code` and return aggregates unless\nthe task needs named people. A named projection omits some safe vendor fields;\nread the indexed record when the task needs those fields.\n\n<!-- when: people -->\n## People and follow-up\n\nResolve a person before changing their profile. An omitted attribute leaves\nthe current value alone; `null` clears it. Archiving a person is reversible;\ndeleting a profile is permanent.\n\nWorkflow cards join people to a workflow and its ordered steps. Resolve both\nthe card id and its person id before acting on a card. Snoozing needs a duration;\npromoting a card completes its step, while skipping moves on without completing\nit. A workflow card note and a profile note are different records. Profile note\ncategories can notify their subscribers.\n\nCustom field values need their field-definition records to supply names and\ndata types. Form answers similarly join submissions, values and fields; the\nAPI cannot submit a form on someone's behalf.\n<!-- end -->\n\n<!-- when: lists -->\nSaved People lists are live cross-product queries. Their results are only as\nfresh as their last refresh. Refreshing a list can fire its automations, such\nas adding a person to a workflow, and is a write even when the task is a count.\n<!-- end -->\n\n<!-- when: services -->\n## Services plans and schedules\n\nResolve the service type before finding a dated plan. Plan times define the\nservice dates. `get_plan` combines the plan, order of service and scheduled\nteam; a cut section can be read through its indexed items or team-members path.\nItem durations are seconds, so divide by 60 when reporting minutes.\n\nScheduling needs a team and may need a position. `C` means confirmed, `U`\nunconfirmed and `D` declined. Preparing a notification and sending it are\ndifferent actions. A song item's identity comes from its song and arrangement;\nmusical keys are not credentials. Services cannot upload a file through this\nconnection.\n<!-- end -->\n\n<!-- when: groups -->\n## Groups membership joins\n\nUse a group's membership records to distinguish leaders from members. On this\nAPI version memberships carry no person attributes; `include=person` supplies\nnames, and the related person id supplies contact details and other product\nrecords. The API can change memberships and group settings, but cannot create\na group, create a meeting or record group attendance.\n<!-- end -->\n\n<!-- when: check-ins -->\n## Check-Ins occurrences\n\nAn event is recurring; its event period is a dated occurrence. Period counts\nare the efficient attendance answer. Individual check-ins join a person to a\nperiod, and date filtering uses the period's start, not the check-in's creation\ntime. The API cannot check anyone in or out.\n<!-- end -->\n\n<!-- when: calendar -->\n## Calendar occurrences\n\nEvent instances expand recurrence into occurrences. A booking can return a\n`BookedEvent` stub when the user lacks access to its event. Events, instances\nand times are read-only; tags, resources, rooms and folders have write APIs.\n<!-- end -->\n\n<!-- when: registrations -->\n## Registrations\n\nA signup describes a registration event. Its attendee records join back to\nPeople and distinguish active, waitlisted and canceled attendees. This API\ncannot register someone.\n<!-- end -->\n\n<!-- when: giving -->\n## Giving amounts and donor joins\n\nAmounts are integer cents with an explicit currency. A donation's designations\nallocate it across funds; do not count a donation once per designation. Join\ndonors by person id and funds by fund id. Recurring schedules and the donations\nthey produce are different records. Creating/editing a donation, refunding it\nor committing a batch changes financial records; named giving tools only read.\n<!-- end -->\n\n<!-- when: publishing -->\n## Publishing\n\nEpisodes, channels and resources are available through the indexed API. A public\nChurch Center link and a media resource are different things; use the record\nthe task asks for. Signed download URL generation is refused because the\nprivate link would remain withheld.\n<!-- end -->\n\n<!-- when: webhooks -->\n## Webhooks\n\nA subscription names an event and callback destination. Signing keys, private\ndownload destinations and opaque event/delivery payloads or headers remain\nwithheld. Status and event metadata are available for audits.\nWebhook signing-key rotation is refused: the new credential cannot be returned\nor installed on the receiver through this connection.\n<!-- end -->\n\n<!-- when: api -->\n## Organization API\n\nThe organization API includes application metadata and personal-access-token\ninventory. Inventory records describe tokens; they do not return their values.\nRevoking a token is a write and may interrupt another integration, including\nthis connection if its own token is revoked.\n<!-- end -->\n\n<!-- when: limited -->\n## Product boundary\n\nSome products are unavailable on this connection. People lists and their rules\nare unavailable because they can query another product. Webhook payloads and\nchanges to existing subscriptions are unavailable because their ids do not name\ntheir product. A new subscription must name a reachable product's event.\n\nStored workflow cards, notes, custom fields and form answers remain readable\nwhen reachable: staff or automations may have copied information into them.\nThe connection does not infer the provenance of those stored records.\n<!-- end -->\n\n## Not available\n\nOnly reviewed product versions and indexed operations are callable. File\nuploads use a separate host this connection does not reach. Credentials and\nprivate calendar access codes cannot be recovered through a tool.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_person_field_data`, `list_person_notes`, `list_workflow_cards`, `list_workflows`, `pco_api_details`, `pco_api_search`, `search_people`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `pco_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 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<!-- when: services -->\n- **Paging:** For `list_person_schedules`, `list_plans`, `list_service_types`, `list_teams`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\n<!-- when: groups -->\n- **Paging:** For `list_group_memberships`, `list_groups`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\n<!-- when: giving -->\n- **Paging:** For `list_donations`, `list_funds`, pass `page.nextCursor` as the top-level `cursor`.\n<!-- end -->\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:** `pco_api_search` finds this API's operations and reads no account data, `pco_api_details` shows one operation's contract, and `pco_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `pco_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 2 operations are refused by design; use `pco_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. `conflict` means: HTTP 409 for duplicate records in People.\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": "## Identity first\n\nThe People person id joins products; names repeat, so join on `person_id`.\nMemberships, scheduled people and workflow cards have their own ids. `get_me`\ngives the organization's time zone: bare dates mean its local day, and exact\nboundaries need an offset. Name filters are exact unless the value ends in `%`.\n\nAn old person id may be merged: read `/people/v2/person_mergers` with\n`where[person_to_remove_id]` and follow `person_to_keep_id`. An empty history\ndoes not prove no merge happened.\n\nPastoral data: reduce inside `execute_code` and return aggregates unless the task\nneeds named people. Named reads omit some fields; read the indexed record when the\ntask needs them.\n\n<!-- when: people -->\n## People\n\nWorkflow cards join people to a workflow and its ordered steps. Custom values and\nform answers need their field records for names and types.\n<!-- end -->\n\n<!-- when: people-writes -->\nAn omitted attribute stays; `null` clears it. Archiving is reversible; deleting a\nprofile is permanent. Resolve the card id and its person id before acting on a\nworkflow card. Promoting completes a step; skipping moves on without completing\nit. Card notes and profile notes are different records, and note categories can\nnotify subscribers. No named form-submission tool exists; the generic hatch\nadmits that endpoint as a destructive operation.\n<!-- end -->\n\n<!-- when: lists -->\nSaved lists are only as fresh as their last refresh. Refreshing can fire\nautomations, such as adding someone to a workflow, so it is a write even for a count.\n<!-- end -->\n\n<!-- when: services -->\n## Services\n\nResolve the service type before a dated plan; plan times define its service dates.\nA cut `get_plan` section reads through its indexed items or team-members path. Item\ndurations are seconds. Schedule status: `C` confirmed, `U` unconfirmed, `D`\ndeclined. Preparing a notification and sending it are different actions. Services\ncannot upload a file through this connection.\n<!-- end -->\n\n<!-- when: groups -->\n## Groups\n\nMemberships distinguish leaders from members but carry no person attributes;\n`include=person` supplies names, and the person id supplies contact details.\n<!-- end -->\n\n<!-- when: check-ins -->\n## Check-Ins\n\nAn event recurs; its period is a dated occurrence. Period counts are the efficient\nattendance answer. Date filters use the period start, not the check-in creation time.\n<!-- end -->\n\n<!-- when: calendar -->\n## Calendar\n\nEvent instances expand recurrence. A booking can return a `BookedEvent` stub when\nthe user lacks access to its event.\n<!-- end -->\n\n<!-- when: registrations -->\n## Registrations\n\nAttendee records join to People and separate active, waitlisted and canceled attendees.\n<!-- end -->\n\n<!-- when: giving -->\n## Giving\n\nAmounts are integer cents with a currency. Designations split a donation across\nfunds, so never count a donation once per designation. Recurring schedules and the\ndonations they produce are different records. Named giving tools only read.\n<!-- end -->\n\n<!-- when: giving-writes -->\nCreating, editing or refunding a donation or committing a batch changes financial\nrecords.\n<!-- end -->\n\n<!-- when: publishing -->\n## Publishing\n\nA Church Center link and a media resource are different records; use the one the\ntask asks for.\n<!-- end -->\n\n<!-- when: webhooks -->\n## Webhooks\n\nSigning keys, private destinations and event payloads stay withheld; status and\nevent metadata remain available for audits.\n<!-- end -->\n\n<!-- when: api -->\n## Organization API\n\nToken inventory never returns values.\n<!-- end -->\n\n<!-- when: api-writes -->\nRevoking a token is a write that may break another integration, including this\nconnection.\n<!-- end -->\n\n<!-- when: limited -->\n## Product boundary\n\nSome products are unavailable. A new webhook subscription must name a reachable\nproduct's event. Stored workflow cards, notes, custom fields and form answers stay\nreadable and may contain copied information; provenance is not inferred.\n<!-- end -->\n\n## Conventions\n\n- **Hatch:** `pco_api_search` finds operations, `pco_api_details` shows one contract, `pco_api_read` calls a reviewed read and `pco_api_write` a reviewed write. 2 operations are refused by design; use `pco_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap. `conflict` means: HTTP 409 for duplicate records in People.",
     "instructionsHeading": "Organization instructions"
 };

package/dist/providers/quickbooks/index.js

@@ -54,12 +54,13 @@ export const quickbooks = defineApiProvider({
         }),
         describe: () => "Connected to the configured QuickBooks Online company.",
     },
+    blocks: { keys: ["writes"], select: (options) => (options.readOnly === false ? ["writes"] : []) },
     guide: (options) => ({
         context: [
             `Company ${options.realmId}, ${options.environment}: ${options.purpose}`,
             options.readOnly === false
                 ? "Bounded named writes are enabled. The API hatch remains read-only."
-                : "This connection is read-only. Set readOnly: false in deployment code to enable bounded named writes.",
+                : "This connection is read-only; named writes are unavailable.",
             "Contact details, bank/card/tax identifiers, credentials and private links are withheld on every read.",
         ],
         summary: "Load for QuickBooks accounting reads and enabled customer or service-invoice writes.",
@@ -85,9 +86,5 @@ export const quickbooks = defineApiProvider({
             configurable: true,
         });
     },
-    transformGuide: (guide) => ({
-        ...guide,
-        content: guide.content.replace("Writes take no idempotency key.", "Every named write requires requestId, sent as Intuit's requestid query parameter; no idempotencyKey header argument is accepted."),
-    }),
     tools: quickbooksTools,
 });

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Accounting identity and joins\n\nAn Id identifies a record inside this company and record family. DocNumber is\na human label, may repeat, and is not an Id. SyncToken is the public record\nversion used for concurrency control, not an OAuth credential. References carry\nthe target Id in value; invoice CustomerRef joins Customer, bill VendorRef\njoins Vendor, and payment Line.LinkedTxn joins invoices or bills.\n\nAccounting Payment and BillPayment records describe received and paid money;\nreading them does not execute a payment. Desktop, Payments, Payroll, attachments,\nand unreviewed accounting entities are outside this connection.\n\n## Money, time and reports\n\nAmounts use decimal currency units, never integer cents. Preserve CurrencyRef\nand ExchangeRate when combining transactions; never sum unlike currencies.\nTxnDate is the company's accounting date, not a UTC instant. MetaData timestamps\ncarry their own offset. Customer and vendor searches omit inactive records\nunless the Active filter explicitly selects them.\n\nReports are trees with Header, Columns, nested Rows and section summaries.\nRead column types and metadata together with row values; column order and\nsection labels can change. Empty amount strings mean no value, not zero.\nDo not flatten away section identity or add totals to their component rows.\nCheck the returned period, basis, currency and NoReportData option before\ncomparing reports. Aging is an as-of snapshot, rather than a transaction range.\n\nReturn aggregates and the few identifying records the task needs; avoid\ncopying full customer or vendor directories into the conversation.\n\n\n## Named writes and reconciliation\n\nThe connector defaults to read-only. Deployment code must set `readOnly: false`\nto expose named writes; endpoint and pool read-only policies still apply. The\nAPI hatch remains read-only. `create_customer` accepts DisplayName and optional\nCompanyName. `update_customer` requires caller-observed Id and SyncToken and\nchanges only those naming fields with sparse:true. Omitted CompanyName stays\nunchanged. A stale-version conflict never fetches a newer version or overwrites\nit. Read and review the current record before proposing a new update.\nDisplayName must be unique across customers, vendors and employees.\n\n`create_invoice` creates a real accounting transaction, never a draft, for a\nverified US company and a customer using USD. This bounds the no-email claim\nto the reviewed US autosend contract and money to two-decimal USD units. First\nobserve an active customer with its CurrencyRef and active Service item Ids.\nSupply currency USD, a positive explicit exchange rate, accounting and\ndue dates, a reconciliation DocNumber and 1–20 lines. Each line is one service\nunit with an explicit positive amount in decimal currency units, supplied as a\nstring with exactly two fractional digits. No prices, dates or exchange rates\nare defaulted or fetched. Preflight reads verify the fixed company Country is US\nand recheck customer currency and item activity/type; they are not an atomic snapshot. Vendor validation can still\nreject changed references. Taxes and totals are computed by QuickBooks: inspect\nthe returned currency, exchange rate and totals; line sums are not a promise of\nan untaxed total. Locale/company tax requirements may reject this narrow body.\nNo customer/item creation happens implicitly.\nEach additional request charges the call-admission budget before dispatch.\nContradictory returned references, dates, rate or service prices produce an\nunknown outcome; reconcile through reads rather than repeating the write.\n\nInvoice email status is fixed to NotSet; online, IPN, credit-card, ACH, PayPal\nand Affirm payment flags are fixed false. No email field or send operation is\nexposed. Company invoice-autosend opt-in does not supply the documented\nNeedToSend request state. This prevents this creation request from asking Intuit\nto email the invoice, including when the customer has an email on file.\n`update_unsent_invoice` changes only DocNumber, with caller-observed Id and\nSyncToken. It reads the US company and invoice before dispatch and requires USD,\nexplicit NotSet, no DeliveryInfo and every payment flag explicitly false.\nMissing state, send-ready and delivered invoices are refused. It preserves all\nomitted settings through sparse:true and never substitutes a newer version.\nNo date edits are exposed. This removes documented autosend prerequisites;\napplying them to updates is an inference, not an Intuit update-specific no-email\nguarantee. NotSet cannot prove that no historical delivery ever occurred.\nRead the known Id after an uncertain response; never blindly resend.\nDeletes, voids, email delivery, charges, refunds, other accounting writes and\narbitrary mutations are unavailable.\n\nEvery write requires a caller-generated `requestId`: 1–50 ASCII letters,\ndigits, underscores or hyphens, starting with a letter or digit. Keep it stable\nfor the exact intent and unique across requests/tools for this company. It is\nsent in Intuit's requestid query parameter with minorversion 75, rather than an\nidempotency header. Intuit documents recognizing the same content and ID and\nreturning the original response; no retention duration is established. This\nnever permits automatic replay. A dispatched write is sent once even after\n401, timeout, server failure or an invalid success response.\n\nAfter an unknown customer-create outcome, search exact DisplayName, including\ninactive records when needed, and inspect the match. For an invoice, search\nDocNumber plus CustomerRef and inspect currency, dates, lines and computed\namounts. DocNumber can repeat, so it alone proves nothing. Reconcile and report\nambiguity before considering another create; never generate a fresh requestId\nand blindly repeat a potentially committed intent. Unknown update outcomes\nneed a read of the known Id and version. A requestId is not a lookup endpoint or\na permanent duplicate-prevention guarantee.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `quickbooks_api_details`, `quickbooks_api_search`, `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:** `quickbooks_api_search` finds this API's operations and reads no account data, `quickbooks_api_details` shows one operation's contract, and `quickbooks_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. An operation without a reviewed verdict is refused. 3 operations are refused by design; use `quickbooks_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: Intuit fault 5010 for a stale SyncToken; Intuit fault 6240 for a duplicate DisplayName.\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": "## Identity and joins\n\n`Id` identifies a record within this company and record family. `DocNumber` is a\nlabel that can repeat; never use it as an Id. `SyncToken` is the public record\nversion, not a credential. References carry the target Id in `value`: invoice\n`CustomerRef`, bill `VendorRef`, payment `Line.LinkedTxn`.\n\nPayment and BillPayment are accounting records; reading one executes nothing.\nDesktop, Payments, Payroll and attachments are outside this connection.\n\n## Money, time and reports\n\nAmounts are decimal currency units, not cents. Never sum unlike currencies;\npreserve `CurrencyRef` and `ExchangeRate`. `TxnDate` is an accounting date, not\na UTC instant; `MetaData` timestamps carry their own offset. Customer and vendor\nsearches omit inactive records unless `Active` selects them.\n\nReports are trees. Read column metadata with row values, because order and\nlabels can change. Empty amounts mean no value, not zero. Do not flatten sections\nor add totals to their component rows. Before comparing reports, check period,\nbasis, currency and `NoReportData`. Aging is an as-of snapshot, not a transaction\nrange.\n\nReturn aggregates and the few records the task needs, not full customer or\nvendor directories.\n\n<!-- when: writes -->\n## Writes\n\nDeletes, voids, email delivery, charges, refunds and other accounting writes are\nunavailable. `DisplayName` must be unique across customers, vendors and employees.\n\n**requestId.** Keep it stable for one exact intent and unique across requests\nand tools for this company. It never permits replay, and it is neither a lookup\nnor a lasting duplicate guarantee. Never generate a fresh one to repeat an intent\nthat may have committed.\n\n**create_invoice** creates a real transaction, never a draft, and creates no\ncustomer or item implicitly. First observe an active customer with its\n`CurrencyRef` and active Service item Ids. Nothing is defaulted, and amounts are\nstrings with exactly two decimals. QuickBooks computes taxes and totals, so inspect\nthe returned currency, rate and totals; line sums do not promise an untaxed total.\nCompany tax rules may still reject it. Preflight reads are not an atomic snapshot,\nand each spends call-admission budget. Contradictory returned values mean an\nunknown outcome.\n\n**Email.** No email or send operation exists; creation fixes `NotSet` and false\npayment flags, so it does not ask Intuit to email the invoice.\n`update_unsent_invoice` changes only `DocNumber` and refuses missing, send-ready\nor delivered state. `NotSet` cannot prove no earlier delivery occurred.\n\n**Stale versions.** A conflict never fetches or overwrites a newer version. Read\nand review the record before proposing another update.\n\n**Unknown outcome: reconcile, never resend.**\n\n- Customer: search the exact `DisplayName`, including inactive records.\n- Invoice: search `DocNumber` plus `CustomerRef`, then inspect currency, dates,\n  lines and amounts. `DocNumber` alone proves nothing.\n- Update: read the known Id and its version.\n\nReport any ambiguity before considering another create.\n<!-- end -->\n\n## Conventions\n\n- **Hatch:** `quickbooks_api_search` finds operations, `quickbooks_api_details` shows one contract, `quickbooks_api_read` calls a reviewed read. 3 operations are refused by design; use `quickbooks_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: Intuit fault 5010 for a stale SyncToken; Intuit fault 6240 for a duplicate DisplayName.",
     "instructionsHeading": "Company instructions"
 };

package/dist/providers/sheets/index.js

@@ -100,6 +100,7 @@ export const sheets = defineApiProvider({
     errors,
     safety: () => safety,
     probe,
+    blocks: { keys: ["writes"], select: (options) => (options.readOnly ? [] : ["writes"]) },
     guide: (options) => ({
         context: [
             `Purpose: ${options.purpose}`,

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Find the workbook and resolve ranges\n\nSheets starts from a spreadsheet id. A spreadsheet id the person gives works\nas is; search Drive only for a name. The Drive file id is\nthe spreadsheet id. Moving, sharing and trashing the file also belong to Drive.\nRead `get_spreadsheet` first to resolve sheet titles, numeric sheet ids and named\nranges before writing. Sheet id zero is valid; a tab's position is not its id.\n\nA1 ranges use sheet titles; structural GridRanges use numeric sheet ids with\nzero-based, end-exclusive row and column indexes. Quote titles containing\nspaces or punctuation and double apostrophes: `'Alice''s costs'!A1:D7`.\nA bare title may resolve to a named range; quote it to address the whole tab.\n\n## Read cell meaning\n\nDisplayed values reflect spreadsheet locale and number formats. Use\nunformatted numbers for arithmetic and formulas when inspecting expressions.\nDate serials count days from 1899-12-30; interpret dates using the workbook's\ntime zone. Trailing empty rows and cells may be absent. An empty range is a\nvalid result, not proof that the sheet is missing.\n\nWhole-row content reads can resume partway through a range. A named range or\nwhole-sheet reference may be re-read and earlier rows skipped; rowOffset is\nrelative to Google's echoed range. Reduce amounts inside execute_code before\nreturning them. Read an oversized cell separately to recover its full text.\n\n## Edit and reconcile\n\nUse RAW for external data; USER_ENTERED can turn leading equals signs into\nformulas. In cell writes, null leaves a cell unchanged and an empty string\nclears it. Clearing preserves formatting and validation. `append_values` is\npinned to INSERT_ROWS and inserts rows after the detected table. A vendor append using\nOVERWRITE can replace existing cells below that table.\n\nRead just before replacing another person's cells. Sheets has no revision\nprecondition or replay key: concurrent edits can be overwritten. After an\nuncertain append, read the target table and identify the row before adding\nanything missing. After an uncertain workbook create, search Drive by title\nbefore creating another workbook.\n\nStructural batches apply atomically, but can delete rows, sheets or\nprotections. An oversized reply may be summarized after the edit saved;\ninspect the workbook to recover details. Preview comment mutations and\nexternal data-source configuration, refresh and administration are outside\nthis connection. Developer-metadata searches and data-filter reads are\nread-only even though their wire method is POST.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_values`, `sheets_api_details`, `sheets_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. 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:** `sheets_api_search` finds this API's operations and reads no account data, `sheets_api_details` shows one operation's contract, and `sheets_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `sheets_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. 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": "## Find the workbook and resolve ranges\n\nSheets starts from a spreadsheet id. A spreadsheet id the person gives works\nas is; search Drive only for a name. The Drive file id is\nthe spreadsheet id. Moving, sharing and trashing the file also belong to Drive.\nRead `get_spreadsheet` first to resolve sheet titles, numeric sheet ids and named\nranges before writing. Sheet id zero is valid; a tab's position is not its id.\n\nA1 ranges use sheet titles; structural GridRanges use numeric sheet ids with\nzero-based, end-exclusive row and column indexes. Quote titles containing\nspaces or punctuation and double apostrophes: `'Alice''s costs'!A1:D7`.\nA bare title may resolve to a named range; quote it to address the whole tab.\n\n## Read cell meaning\n\nDisplayed values reflect spreadsheet locale and number formats. Use\nunformatted numbers for arithmetic and formulas when inspecting expressions.\nDate serials count days from 1899-12-30; interpret dates using the workbook's\ntime zone. Trailing empty rows and cells may be absent. An empty range is a\nvalid result, not proof that the sheet is missing.\n\nWhole-row content reads can resume partway through a range. A named range or\nwhole-sheet reference may be re-read and earlier rows skipped; rowOffset is\nrelative to Google's echoed range. Reduce amounts inside execute_code before\nreturning them. Read an oversized cell separately to recover its full text.\n\n<!-- when: writes -->\n## Edit and reconcile\n\nUse RAW for external data; USER_ENTERED can turn leading equals signs into\nformulas. In cell writes, null leaves a cell unchanged and an empty string\nclears it. Clearing preserves formatting and validation. `append_values` is\npinned to INSERT_ROWS and inserts rows after the detected table. A vendor append using\nOVERWRITE can replace existing cells below that table.\n\nRead just before replacing another person's cells. Sheets has no revision\nprecondition or replay key: concurrent edits can be overwritten. After an\nuncertain append, read the target table and identify the row before adding\nanything missing. After an uncertain workbook create, search Drive by title\nbefore creating another workbook.\n\nStructural batches apply atomically, but can delete rows, sheets or\nprotections. An oversized reply may be summarized after the edit saved;\ninspect the workbook to recover details. Preview comment mutations and\nexternal data-source configuration, refresh and administration are outside\nthis connection. Developer-metadata searches and data-filter reads are\nread-only even though their wire method is POST.\n<!-- end -->\n\n## Conventions\n\n- **Hatch:** `sheets_api_search` finds operations, `sheets_api_details` shows one contract, `sheets_api_read` calls a reviewed read and `sheets_api_write` a reviewed write.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart.",
     "instructionsHeading": "Connection instructions"
 };

package/dist/providers/slides/index.js

@@ -122,12 +122,12 @@ export const slides = defineApiProvider({
         binding: ({ connection }) => slidesBinding(connection),
     },
     probe,
+    blocks: { keys: ["writes"], select: (options) => (options.readOnly ? [] : ["writes"]) },
     guide: (options) => ({
         context: [
             `Purpose: ${options.purpose}`,
             "Workspace delegation is configured. Each call acts as the account deployment code maps the caller to; an agent uses its pool owner unless one shared account is configured. No argument selects a subject.",
-            "Content windows: get_presentation defaults to 20 slides (maximum 100); get_page to 50 elements (maximum 500); list_layouts to 100 rows (maximum 500); list_comments to 50 threads (maximum 500). Slides has no vendor list pagination.",
-            "Generic thumbnails/preview links are refused; get_slide_thumbnail is the reviewed short-lived-link workflow. The generic batch retains only the 49 shipped request kinds; no extra preview methods are admitted.",
+            "The generic batch retains only the 49 shipped request kinds.",
             ...(options.readOnly ? ["This connection is read-only; writes are refused."] : []),
         ],
         summary: "Load for deck text, notes, layouts, comments and guarded Slides edits.",

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Find and read a deck\n\nSlides cannot search or list decks. Find the file through Drive, or take the\npresentation id from `/presentation/d/<id>/` in its URL. A presentation is a\nDrive file; finding one does not grant permission to open it. A user-given id\nworks as is; no Drive lookup is needed to use it.\n\n`get_presentation` reads text in page order, with speaker notes, alt text and\nplaceholder ids. `get_page` opens groups and reads a slide, layout, master or\nnotes page. A slide's `index` is zero-based. Resolve a layout's placeholders\nwith `list_layouts` and `get_page` before filling a new slide.\nNamed-read `fields` narrows data while preserving `page` and `truncated` cut disclosures.\n\nText and notes have independent continuation. Pass an element's `textCursor`\nor a slide's `elementsCursor` to `get_page` with that slide's id; pass a\n`notesCursor` with its `notesPageId`. A deck's `layoutsCursor` continues in\n`list_layouts`. Content cursors bind to the deck's revision and the text they\ncontinue; a changed deck requires a fresh read. Follow continuation even when\na result contains fewer rows than requested.\n\nFor styles, transforms, HTML comment content, anchors' ranges or other full\nstructural JSON, use `slides_api_read`. Operation details use the legacy\n`presentationsId` spelling for presentations.get; pages and batch updates use\n`presentationId`. These are path parameter names, not query arguments.\nSpell colons and unreserved characters literally in hatch paths; encode other\ncharacters within one id segment. Named tools handle their own id encoding.\n\n`slides_api_read` with `{path: \"/presentations/<id>\"}` returns `{status,data}`;\nthe vendor presentation is `data`. A Connecta call's result delivery wraps that\ntool value in its own `data`; follow its result handle for large JSON.\nContent cursors belong to the named reading tools and are separate from that delivery handle.\n\n`get_slide_thumbnail` returns a link that opens as the delegated person for\nabout 30 minutes. Keep it private. Generic thumbnail/preview operations are\nrefused; use the named thumbnail workflow.\n\n## Edit at the version you read\n\nRead before editing and use its `revisionId` as the write precondition.\nRevision ids are preconditions, not replay keys. `create_slide` adds an empty\nslide; read its placeholder ids before inserting text. `replace_all_text`\nreplaces literal text, with `matchCase` and an optional `requiredRevisionId`.\nEach write returns the new `revisionId` for the next one. A `conflict` means\nthe deck changed since your read: re-read, rebuild the requests, and send them\nwith the new `revisionId`. A failure that says the write applied means Google\nanswered 2xx: do not repeat it; re-read. No Slides tool shares, moves or deletes\nthe deck file.\n\n`batch_update_presentation` takes the existing reviewed Request kinds.\nThe generic batch hatch uses `POST /presentations/deck1:batchUpdate` with\n`body: {requests: [{insertText: {objectId: \"shape1\", text: \"Hello\"}}],\nwriteControl: {requiredRevisionId: \"revision-from-read\"}}`. It retains the\nsame request-kind and revision guards. No additional preview capabilities are\nadmitted by indexing the complete Discovery document.\n\n## Comments can save separately\n\nA comment thread's `commentId` identifies the thread; its head post and\nreplies have their own `postId`. Authors' `user` ids are stable; display names\nare labels. Anchors join to page and object ids; speaker-note comments belong\nto the notes page. Reading comments requires comment access. A view-only\naccount may be refused rather than receiving an apparently empty list.\n\nResolve, reopen or reassign a thread with `update_comment_thread`; edit its\ntext with `update_comment_post`. Reassignment requires content. Only the\npost's author can edit or delete that post. Comments notify people as in the\nSlides editor.\n\n`create_comment` sends one `insertComment` by itself. When one edit changes\nthe deck and adds or changes comments, send it as one `batch_update_presentation`\ncall: `insertComment`, `addCommentReply`, `updateCommentPost`, `deleteComment`\nand `deleteCommentReply` are Request kinds and share a batch with deck kinds\nsuch as `updateTextStyle`, under the same `requiredRevisionId`. Slides saves\nthe deck part and the comment part separately, so a successful mixed batch can\nsave the deck without confirming the comments. When `commentUpdateState` is not\n`ALL_SAVED`, or the result says comment saves are unconfirmed, read the deck and\n`list_comments`, report the deck part and the comment part each as saved or\nunconfirmed, and send neither the batch nor its comment part again. Keep every\ncreated id for reconciliation.\n\n`create_comment_reply` sends one reply by itself. The write hatch keeps\ncomment-save state and advice in envelope-level `warnings`, even with\n`fields: [\"replies\"]`; Google's own state remains in vendor `data` when supplied.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `get_page`, `get_presentation`, `list_comments`, `list_layouts`, `slides_api_details`, `slides_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. 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:** `slides_api_search` finds this API's operations and reads no account data, `slides_api_details` shows one operation's contract, and `slides_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `slides_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 1 operation is refused by design; use `slides_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409; The content or revision bound to a named continuation cursor changed; restart the read.\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": "## Find and read\n\nSlides cannot search decks: use Drive, the id in `/presentation/d/<id>/`, or an\nid the person gives, which works as is. Finding a deck does not grant access.\nSlide `index` is zero-based. Before filling a new slide, resolve placeholders\nwith `list_layouts` and `get_page`.\n\nContinuation is per content kind: `textCursor` or `elementsCursor` goes to\n`get_page` with that slide's id, `notesCursor` with its `notesPageId`,\n`layoutsCursor` to `list_layouts`. Cursors bind to the deck's revision, so a\nchanged deck needs a fresh read. Follow them even when a result has fewer rows\nthan requested.\n\n`slides_api_read` covers styles, transforms and full structure. It returns\n`{status,data}` with the vendor presentation in `data`; a program call nests that\nin its own `data`. In operation details, presentations.get names its path\nparameter `presentationsId`; pages and batch updates use `presentationId`. Spell\ncolons literally and encode other reserved characters within one id segment.\n\n`get_slide_thumbnail` returns a link that opens as the delegated person: keep it\nprivate. Generic thumbnail and preview operations are refused.\n\n`commentId` names a thread; its posts have their own `postId`. Speaker-note\ncomments belong to the notes page. A view-only account may be refused; that is not\nan empty list.\n\n<!-- when: writes -->\n## Edit at the version you read\n\nPass the `revisionId` you read as the write precondition; each write returns the\nnext one. It is a precondition, not a replay key. On `conflict`, re-read, rebuild\nthe requests and send them with the new id. A failure saying the write applied\nmeans Google answered 2xx: re-read, never repeat. `create_slide` adds no text, so\nread its placeholder ids first. No Slides tool shares, moves or deletes the file.\n\nThe generic batch is `POST /presentations/<id>:batchUpdate` with\n`body: {requests, writeControl: {requiredRevisionId}}`, under the same guards.\n\n## Comments save separately\n\nComments notify people as in the editor. When one edit changes the deck and\ncomments, send one `batch_update_presentation` under one `requiredRevisionId`;\ncomment changes are Request kinds. Slides saves the two parts separately, so success\ncan leave comments unconfirmed. If `commentUpdateState` is not `ALL_SAVED`, or the\nresult says saves are unconfirmed: read the deck and `list_comments`, report each\npart as saved or unconfirmed, keep every created id, and resend neither the batch\nnor its comment part. The write hatch reports this state in envelope `warnings`,\neven when `fields` narrows.\n<!-- end -->\n\n## Conventions\n\n- **Hatch:** `slides_api_search` finds operations, `slides_api_details` shows one contract, `slides_api_read` calls a reviewed read and `slides_api_write` a reviewed write. 1 operation is refused by design; use `slides_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. `conflict` means: A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409; The content or revision bound to a named continuation cursor changed; restart the read.",
     "instructionsHeading": "Connection instructions"
 };

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Account and money\n\nBefore investigating a payment or moving money, confirm the account and mode\nwith `get_stripe_account_info`. A Connect account's objects belong to that\naccount, rather than the platform's account. Sandbox objects do not establish anything about live\ncustomers, revenue or payouts.\n\nResolve ids before acting. Stripe ids identify types: `cus_` customer, `sub_`\nsubscription, `ch_` charge, `pi_` PaymentIntent, `in_` invoice and `acct_`\naccount. A plausible-looking id can refer to a different object or to nobody.\n\nAmounts are integers in the currency's minor unit: 1099 is 10.99 USD, while\n10 is 10 JPY. Keep currencies separate when totaling balances or payments.\n\n## Payment investigations\n\nA PaymentIntent's `latest_charge` joins it to the charge holding the payment's\n`outcome`, `failure_code` and `failure_message`. Follow that reference to\nexplain a decline. Search supports a documented field set for each resource;\ncharge search has no `payment_intent` field. Resolve the parent and follow its\nreference when the needed relationship is not searchable.\n\nSearch is eventually consistent; use a direct object read to reconcile a\nrecent write. A POST's idempotency key identifies the exact operation and\nparameters. Stripe v1 may prune keys after 24 hours, so reconcile the object\nbefore attempting the operation outside that window. A new key can create a\nsecond payment or refund.\n\nIn v1 requests, an empty string (`\"\"`) or `null` unsets a field.\n\n## Data reduction and boundaries\n\nKeep only the customer and payment facts the question needs. Reduce lists to\ncounts, totals or matching records before returning them to the conversation.\nUse the account and balance summaries when their projections answer the task;\nother account fields and balance transactions are available through the API.\n\nCredential creation, customer/account sign-in links, secret payload expansions,\nfull Issuing card details, file uploads and the meter-event stream are outside\nthis connection's surface. Use the Dashboard or application server for those\nflows. Single meter events remain available. A guest Checkout payment page is\navailable only when it is unbound to a Customer or Account and cannot manage\nsaved payment methods; use a payment link or hosted invoice for other cases.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `stripe_api_details`, `stripe_api_read`, `stripe_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. Keep the original method, path, filters, page size, fields and headers. 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:** `stripe_api_search` finds this API's operations and reads no account data, `stripe_api_details` shows one operation's contract, and `stripe_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `stripe_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 15 operations are refused by design; use `stripe_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. A write that takes `idempotencyKey` may be repeated with the same key and arguments while the vendor retains it.\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. `conflict` means: HTTP 409 when the request conflicts with another request, including a concurrent use of the same idempotency key; HTTP 429 with code lock_timeout when another request holds the object's lock.\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": "## Account and money\n\nBefore investigating a payment or moving money, confirm the account and mode\nwith `get_stripe_account_info`. A Connect account's objects belong to that\naccount, rather than the platform's account. Sandbox objects do not establish anything about live\ncustomers, revenue or payouts.\n\nResolve ids before acting. Stripe ids identify types: `cus_` customer, `sub_`\nsubscription, `ch_` charge, `pi_` PaymentIntent, `in_` invoice and `acct_`\naccount. A plausible-looking id can refer to a different object or to nobody.\n\nAmounts are integers in the currency's minor unit: 1099 is 10.99 USD, while\n10 is 10 JPY. Keep currencies separate when totaling balances or payments.\n\n## Payment investigations\n\nA PaymentIntent's `latest_charge` joins it to the charge holding the payment's\n`outcome`, `failure_code` and `failure_message`. Follow that reference to\nexplain a decline. Search supports a documented field set for each resource;\ncharge search has no `payment_intent` field. Resolve the parent and follow its\nreference when the needed relationship is not searchable.\n\nSearch is eventually consistent; use a direct object read to reconcile a\nrecent write. A POST's idempotency key identifies the exact operation and\nparameters. Stripe v1 may prune keys after 24 hours, so reconcile the object\nbefore attempting the operation outside that window. A new key can create a\nsecond payment or refund.\n\nIn v1 requests, an empty string (`\"\"`) or `null` unsets a field.\n\n## Data reduction and boundaries\n\nKeep only the customer and payment facts the question needs. Reduce lists to\ncounts, totals or matching records before returning them to the conversation.\nUse the account and balance summaries when their projections answer the task;\nother account fields and balance transactions are available through the API.\n\nCredential creation, customer/account sign-in links, secret payload expansions,\nfull Issuing card details, file uploads and the meter-event stream are outside\nthis connection's surface. Use the Dashboard or application server for those\nflows. Single meter events remain available. A guest Checkout payment page is\navailable only when it is unbound to a Customer or Account and cannot manage\nsaved payment methods; use a payment link or hosted invoice for other cases.\n\n## Conventions\n\n- **Hatch:** `stripe_api_search` finds operations, `stripe_api_details` shows one contract, `stripe_api_read` calls a reviewed read and `stripe_api_write` a reviewed write. 15 operations are refused by design; use `stripe_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 that takes `idempotencyKey` may be repeated with the same key and arguments while the vendor retains it.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap. `conflict` means: HTTP 409 when the request conflicts with another request, including a concurrent use of the same idempotency key; HTTP 429 with code lock_timeout when another request holds the object's lock.",
     "instructionsHeading": "Account instructions"
 };

package/dist/providers/tithely/index.js

@@ -81,6 +81,7 @@ function usageGuide(options) {
 }
 /** A maintained Tithe.ly giving connection over the v1 REST API. */
 export const tithely = defineApiProvider({
+    blocks: { keys: ["writes"], select: (options) => (options.readOnly ? [] : ["writes"]) },
     name: "tithely",
     title: "Tithe.ly",
     readme: "Tithe.ly",

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Giving data is pastoral\n\nDonor names, emails, addresses, and gift amounts are pastoral data. Reduce\ninside `execute_code`: page, filter, and total there, and return the\naggregate (sums by fund, month, or donor count), not donor rows, unless the\ntask needs named people.\n\n## Ids and joins\n\n- Ids carry their kind: `org_` organization, `user_` donor account, `ch_`\n  charge, `rc_` recurring gift, `pm_` payment method. Read them from the list\n  tools; never guess one.\n- Tithe.ly lists charges and recurring gifts only for one organization or one\n  donor, so pass `organizationId` or `accountId`.\n- A charge carries its donor's name and email, its organization's name, and\n  its payment method, so most joins need no second read.\n- `list_accounts` covers every account these keys can see; `scope: \"api\"`\n  narrows it to accounts created through this API.\n- The named reads project Tithe.ly's records. A field a projection omits, such\n  as an account's phone and postal address, comes back from `tithely_api_read`\n  on that record's path.\n\n## Money, dates and funds\n\n- A fund is a Tithe.ly giving type: `giving_type` in Tithe.ly's records,\n  `fund` in projections.\n- Projections give amounts as integer `…Cents` and dates as ISO 8601 UTC\n  `…At`. Tithe.ly's own records, from `tithely_api_read`, keep string cents\n  and Unix seconds.\n- `depositedAt` may be `\"pending\"`. There is no deposits resource: net amount\n  and fees live on each charge.\n- A charge a recurring gift produced has `recurring: true`; a one-time gift\n  has `recurring: false`.\n\n## Writes\n\n- Every write moves money or changes a donor's records. Bodies are form\n  fields in integer cents and Unix seconds.\n- `POST /refunds/{charge_id}` refunds a whole charge.\n  `DELETE /recurring/{recurring_id}` stops future charges and refunds nothing.\n- Card and bank tokens, which `POST /charge-once` and `POST /payment-methods`\n  need, come only from Tithely.js in a donor's browser. An agent cannot\n  create one.\n- Tithe.ly reports most refusals as HTTP 200 with `status: \"fail\"` and a\n  reason but no code. They arrive as `connector_call_failed`; read the reason\n  before deciding what to do next.\n\n## Not available\n\nOnly Tithe.ly's API v1 is reachable; its undocumented v2 is not.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_accounts`, `list_charges`, `list_organizations`, `list_payment_methods`, `list_recurring_charges`, `tithely_api_details`, `tithely_api_search`, 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 99). 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:** `tithely_api_search` finds this API's operations and reads no account data, `tithely_api_details` shows one operation's contract, and `tithely_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `tithely_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. An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart. 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": "## Giving data is pastoral\n\nDonor names, emails, addresses, and gift amounts are pastoral data. Reduce\ninside `execute_code`: page, filter, and total there, and return the\naggregate (sums by fund, month, or donor count), not donor rows, unless the\ntask needs named people.\n\n## Ids and joins\n\n- Ids carry their kind: `org_` organization, `user_` donor account, `ch_`\n  charge, `rc_` recurring gift, `pm_` payment method. Read them from the list\n  tools; never guess one.\n- Tithe.ly lists charges and recurring gifts only for one organization or one\n  donor, so pass `organizationId` or `accountId`.\n- A charge carries its donor's name and email, its organization's name, and\n  its payment method, so most joins need no second read.\n- `list_accounts` covers every account these keys can see; `scope: \"api\"`\n  narrows it to accounts created through this API.\n- The named reads project Tithe.ly's records. A field a projection omits, such\n  as an account's phone and postal address, comes back from `tithely_api_read`\n  on that record's path.\n\n## Money, dates and funds\n\n- A fund is a Tithe.ly giving type: `giving_type` in Tithe.ly's records,\n  `fund` in projections.\n- Projections give amounts as integer `…Cents` and dates as ISO 8601 UTC\n  `…At`. Tithe.ly's own records, from `tithely_api_read`, keep string cents\n  and Unix seconds.\n- `depositedAt` may be `\"pending\"`. There is no deposits resource: net amount\n  and fees live on each charge.\n- A charge a recurring gift produced has `recurring: true`; a one-time gift\n  has `recurring: false`.\n\n<!-- when: writes -->\n## Writes\n\n- Every write moves money or changes a donor's records. Bodies are form\n  fields in integer cents and Unix seconds.\n- `POST /refunds/{charge_id}` refunds a whole charge.\n  `DELETE /recurring/{recurring_id}` stops future charges and refunds nothing.\n- Card and bank tokens, which `POST /charge-once` and `POST /payment-methods`\n  need, come only from Tithely.js in a donor's browser. An agent cannot\n  create one.\n- Tithe.ly reports most refusals as HTTP 200 with `status: \"fail\"` and a\n  reason but no code. They arrive as `connector_call_failed`; read the reason\n  before deciding what to do next.\n<!-- end -->\n\n## Not available\n\nOnly Tithe.ly's API v1 is reachable; its undocumented v2 is not.\n\n## Conventions\n\n- **Hatch:** `tithely_api_search` finds operations, `tithely_api_details` shows one contract, `tithely_api_read` calls a reviewed read and `tithely_api_write` a reviewed write.\n- **Errors:** An unknown id, or one these credentials cannot reach, fails as `connector_call_failed`; this API does not tell the two apart.",
     "instructionsHeading": "Account instructions"
 };

package/dist/providers/vercel/api.js

@@ -1,7 +1,7 @@
 import { isRecord } from "../_shared/json.js";
 // Vercel's pinned contract, authentication, failures and value-safety boundary.
 import { Effect, Schema } from "effect";
-import { ConnectorCallError } from "../../errors.js";
+import { ConnectorCallError, tokenPrefix } from "../../errors.js";
 import { Refusal, StatusFailure, UnreadableBody } from "../../http/errors.js";
 import { restSafety } from "../../http/safety.js";
 import { Credentials, RequestSecrets } from "../../http/services.js";
@@ -93,7 +93,7 @@ export const vercelErrors = {
         const code = text(error["code"]);
         const message = text(error["message"])?.trim() ?? text(root["message"])?.trim() ?? `Vercel returned HTTP ${status}.`;
         const reviewed = withheld ? facts["code"] : reviewedCode(code);
-        const detail = (code ? `Vercel ${code}: ${message}` : message).slice(0, 1_000);
+        const detail = tokenPrefix(code ? `Vercel ${code}: ${message}` : message, 1_000) || `Vercel returned HTTP ${status}.`;
         if (status >= 200 && status <= 299 && facts["envRejected"] === true)
             return `Vercel rejected the environment-variable write${reviewed ? ` (${reviewed})` : ""}; its message is withheld because this operation handles secret values.`;
         return withheld

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

@@ -1,5 +1,5 @@
 // Generated by scripts/generate-providers.mjs; do not edit.
 export const skill = {
-    "content": "## Projects, deployments and domains\n\nResolve a team by slug, a project by name, and deployments by the observed\nproject id. Team ids start with `team_`, project ids with `prj_`, and deployment\nids with `dpl_`. A deployment hostname and a deployment id identify the same\ndeployment; an alias can later point to a different deployment.\n\nSome project paths accept a project name, but a deployment list's projectId\nfilter requires the observed `prj_` id. Resolve the name before listing its\ndeployments; an empty result for a guessed name does not prove absence.\nComplete each identifier lookup before starting the reads that depend on it.\n\n<!-- when: unpinned -->\nThe configured team is a routing default, not a restriction. Explicit teamId\nor slug selects another team the token can reach; teamId: null selects personal\nscope. Vercel token permissions determine access. Prefer an explicit team when\njoining resources across several calls.\n<!-- end -->\n\n<!-- when: pinned -->\nThe deployment confines this connection to one team. A supplied team slug must\nbelong to that team; personal scope and foreign teams are refused. Project and\ndeployment references require ownership reads. Global/account and transfer\noperations without a verifiable team boundary remain unavailable. A team list\nreturns only the pinned team.\n<!-- end -->\n\nRead deployment state before its build events. Runtime logs diagnose requests\nafter a deployment built; build logs explain a failed build. Narrow time windows\nbefore raising collection limits. Generic reads refuse live follow streams;\nuse the bounded build/runtime readers. Deployment timestamps are milliseconds.\n\nProject domains and deployment aliases are different joins: a project domain\nbelongs to the project, while an alias identifies its assigned deployment.\nRead a pending domain's verification instructions before changing DNS.\n\n## Environment changes\n\nResolve environment-variable ids using metadata, including target, branch and\ncustom environment. A key can have distinct production and preview values.\nExisting values cannot be retrieved. Supply new values only when the task asks\nfor a change; confirm the returned id and metadata.\n\nEnvironment changes apply to future deployments. A new deployment is a separate\nwrite. Promoting an existing deployment does not rebuild it or update embedded\nenvironment values. After an uncertain update, reconcile observable metadata\nsuch as id, targets and comment; reading metadata cannot verify a secret value.\n\n## Explicit files and credentials\n\nDeployment files can reference previously uploaded digests. File uploads accept\nexplicit bytes and never read a path on the agent's machine. Decrypted-value,\ncredential-minting, protection-bypass-link, signing and domain move-out operations\nare refused; use Vercel's dashboard for those workflows.\n\n## Conventions\n\n- **Paging:** while `page.hasMore` is true, continue with `page.nextCursor` unchanged. For `list_teams`, `vercel_api_details`, `vercel_api_search`, pass it as the top-level `cursor`; omit raw paging anchors on continuations. For `vercel_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 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:** `vercel_api_search` finds this API's operations and reads no account data, `vercel_api_details` shows one operation's contract, and `vercel_api_read` calls a reviewed read. Details' `response.fields` promises selection only; `withheld` hints are incomplete, and absence never means safe or readable. `vercel_api_write` calls a reviewed write; the host may ask the user to confirm it. An operation without a reviewed verdict is refused. 29 operations are refused by design; use `vercel_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.",
+    "content": "## Projects, deployments and domains\n\nResolve a team by slug, a project by name, and deployments by the observed\nproject id. Team ids start with `team_`, project ids with `prj_`, and deployment\nids with `dpl_`. A deployment hostname and a deployment id identify the same\ndeployment; an alias can later point to a different deployment.\n\nSome project paths accept a project name, but a deployment list's projectId\nfilter requires the observed `prj_` id. Resolve the name before listing its\ndeployments; an empty result for a guessed name does not prove absence.\nComplete each identifier lookup before starting the reads that depend on it.\n\n<!-- when: unpinned -->\nThe configured team is a routing default, not a restriction. Explicit teamId\nor slug selects another team the token can reach; teamId: null selects personal\nscope. Vercel token permissions determine access. Prefer an explicit team when\njoining resources across several calls.\n<!-- end -->\n\n<!-- when: pinned -->\nThe deployment confines this connection to one team. A supplied team slug must\nbelong to that team; personal scope and foreign teams are refused. Project and\ndeployment references require ownership reads. Global/account and transfer\noperations without a verifiable team boundary remain unavailable. A team list\nreturns only the pinned team.\n<!-- end -->\n\nRead deployment state before its build events. Runtime logs diagnose requests\nafter a deployment built; build logs explain a failed build. Narrow time windows\nbefore raising collection limits. Generic reads refuse live follow streams;\nuse the bounded build/runtime readers. Deployment timestamps are milliseconds.\n\nProject domains and deployment aliases are different joins: a project domain\nbelongs to the project, while an alias identifies its assigned deployment.\nRead a pending domain's verification instructions before changing DNS.\n\n## Environment changes\n\nResolve environment-variable ids using metadata, including target, branch and\ncustom environment. A key can have distinct production and preview values.\nExisting values cannot be retrieved. Supply new values only when the task asks\nfor a change; confirm the returned id and metadata.\n\nEnvironment changes apply to future deployments. A new deployment is a separate\nwrite. Promoting an existing deployment does not rebuild it or update embedded\nenvironment values. After an uncertain update, reconcile observable metadata\nsuch as id, targets and comment; reading metadata cannot verify a secret value.\n\n## Explicit files and credentials\n\nDeployment files can reference previously uploaded digests. File uploads accept\nexplicit bytes and never read a path on the agent's machine. Decrypted-value,\ncredential-minting, protection-bypass-link, signing and domain move-out operations\nare refused; use Vercel's dashboard for those workflows.\n\n## Conventions\n\n- **Hatch:** `vercel_api_search` finds operations, `vercel_api_details` shows one contract, `vercel_api_read` calls a reviewed read and `vercel_api_write` a reviewed write. 29 operations are refused by design; use `vercel_api_details` with the method and path to see each summary and refusal, even for methods outside the read/write schemas.\n- **Errors:** `not_found` means the record does not exist; this API tells absence from a permission gap.",
     "instructionsHeading": "Account instructions"
 };

package/dist/registry.d.ts

@@ -2,6 +2,7 @@ import type { CatalogDriftActivityContext } from "./activity.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
 import { type ConnectorCaller } from "./connector-caller.js";
 import type { CredentialVault } from "./credential-contract.js";
+import { type ClassificationOverride } from "./tool-safety.js";
 import type { Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
@@ -45,7 +46,7 @@ export declare function resolveMaxResultBytes(value: number | undefined, inherit
 export interface RegistryOptions {
     publicUrl?: string | undefined;
     oauthClientName?: string | undefined;
-    classification?: Readonly<Record<string, Readonly<Record<string, "read" | "write" | "hidden">>>> | undefined;
+    classification?: Readonly<Record<string, Readonly<Record<string, ClassificationOverride>>>> | undefined;
     storage: KVStorage;
     /** Internal deployment root, preserved when a personal registry partitions storage. */
     rootStorage?: KVStorage;
@@ -99,6 +100,13 @@ export interface ProgramResultDependency {
     tool?: string;
     classification: "read" | "write";
 }
+/** A cached catalog as discovery may list it. */
+export interface CatalogPeek {
+    tools: ToolDef[];
+    fetchedAt: number;
+    /** Whether the connector's own cache would serve this now, with no failure to report. */
+    fresh: boolean;
+}
 export interface RegistryView {
     credentialUiAvailable(): boolean;
     /** Deployment-wide result-size cap threaded to the meta-tools. */
@@ -114,6 +122,12 @@ export interface RegistryView {
         toolName: string;
     } | null;
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
+    /**
+     * The newest complete catalog this caller could be listed, classified and
+     * filtered as a listing is, from storage alone. For discovery; a call never
+     * resolves through it. Undefined for a static catalog or a miss.
+     */
+    peekCatalog(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<CatalogPeek | undefined>;
     contextFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): ConnectorContext;
     /** Acquire the connector's shared downstream-call permit. */
     admitCall(id: string, input: {
@@ -125,8 +139,19 @@ export interface RegistryView {
     resultIdentity(): ResultIdentity;
     /** One validation pass: admit once, then check every dependency under that scope. */
     recheckResultAccess(dependencies: readonly ProgramResultDependency[], classification: "read" | "write", signal?: AbortSignal): Promise<boolean>;
-    /** Reserve deployment-wide capacity before writing a paging envelope's chunks. */
-    stashResult(id: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
+    /**
+     * Reserve deployment-wide capacity before writing a paging envelope's chunks.
+     * `holdFirst` charges the whole envelope but leaves chunk 0, which makes the
+     * result readable, for the caller to write once the result is sealed.
+     */
+    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, options?: {
+        readonly holdFirst?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Give back a stashed result nobody can name any more. Best effort: a failure
+     * leaves it charged until its expiry.
+     */
+    releaseResult(id: string, chunkCount: number): Promise<void>;
     /**
      * Local declared-vs-stored credential mismatch, with no downstream I/O. With
      * `requestScope`, the read joins that request's read memo.
@@ -260,7 +285,11 @@ export declare class Registry implements RegistryView {
      * unconfirmed and retain their charge. Cleanup/release and settlement each
      * stop waiting after 15 seconds. Storage TTL reclaims the rows.
      */
-    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, partition?: string): Promise<boolean>;
+    stashResult(id: string, chunks: readonly string[], ttlSeconds: number, options?: {
+        readonly partition?: string;
+        readonly holdFirst?: boolean;
+    }): Promise<boolean>;
+    releaseResult(id: string, chunkCount: number, partition?: string): Promise<void>;
     /**
      * Storage namespaced to the root result partition, kept separate from any
      * connector's namespace. Backs connecta.result.
@@ -280,6 +309,8 @@ export declare class Registry implements RegistryView {
     /** Compare only the fingerprints accepted in this exact cache partition. */
     private recordCatalogDrift;
     private loadDownstreamTools;
+    /** See {@link RegistryView.peekCatalog}. Same classification and filtering as `loadTools`. */
+    private loadPeek;
     /** The served catalog excludes control-character names; raw caches stay complete. */
     private acceptToolNames;
     /**
@@ -292,6 +323,7 @@ export declare class Registry implements RegistryView {
     /** Construction-only view for the secret-free static config description. */
     describeStaticTools(id: string): ToolDef[] | undefined;
     private validateClassification;
+    peekCatalog(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<CatalogPeek | undefined>;
     getTools(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<ToolDef[]>;
     credentialDriftFor(id: string, requestScope?: object): Promise<string | undefined>;
     /** Age of a complete cache entry; reads never refresh it. */