iit-mcp-autotask 0.35.0 → 0.36.0

package/README.md

@@ -8,10 +8,10 @@ context into one call, a generic read layer for the long tail, one result envelo
 packaged playbooks, strong security boundaries, and predictable per-tenant in-process state (pooled
 client + SDK-owned TTL caches).
 
-> **Package status (2026-10-24):** the runtime dependency `node-autotask` is published to public npm
-> at `0.25.0`; the committed `pnpm-lock.yaml` pins that
+> **Package status (2026-10-29):** the runtime dependency `node-autotask` is published to public npm
+> at `0.37.0`; the committed `pnpm-lock.yaml` pins that
 > release with its integrity hash, so installs resolve deterministically. The dependency is always npm
-> (node-autotask pinned exactly at `0.25.0`) — never a `file:`, `git:`, `link:` or workspace reference
+> (node-autotask pinned exactly at `0.37.0`) — never a `file:`, `git:`, `link:` or workspace reference
 > to a local checkout.
 
 > **0.6.0 is a breaking release** (unreleased): tool names, result shapes and configuration all
@@ -21,7 +21,7 @@ client + SDK-owned TTL caches).
 
 The **core** toolset (12 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
 `finance` (or `all`, 19 tools); the operator profile adds two. The whole tool surface (21 tools) is
-listed below. Every other operation in the SDK's 1,216-operation registry stays
+listed below. Every other operation in the SDK's 1,281-operation registry stays
 reachable through the generic layer: `autotask_catalog` finds the key, `autotask_describe` serves
 its contract, `autotask_read` runs it.
 
@@ -763,7 +763,7 @@ independent review with its resolutions, [`docs/reviews/0.6.0.md`](docs/reviews/
 
 ## SDK dependency
 
-`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.25.0`** (an exact pin —
+`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.37.0`** (an exact pin —
 no range operator; subpaths `.` / `/capabilities` / `/operations` / `/resources` / `/types` /
 `/pool`) — the only **vendor** dependency; the other two runtime dependencies are
 `@modelcontextprotocol/server` (the MCP framework) and `zod` (schema validation). It never
@@ -773,7 +773,7 @@ user — the published tarball ships no lockfile) must resolve to the release th
 reviewed against, or the plan-hash boot check refuses to start.
 
 **Publishing `node-autotask` is the maintainer's action, done manually.** It is published on the
-public registry at `0.25.0` (published 2026-10-23); the
+public registry at `0.37.0` (published 2026-10-28 UTC); the
 exact pin and the committed `pnpm-lock.yaml` (with `pnpm-workspace.yaml`) pin the real published
 tarball with its integrity hash, so installs resolve to exactly that release — the lockfile
 freezes the pnpm/git/Docker paths, the pin freezes the npm/npx paths. The docs are written against this
@@ -867,9 +867,9 @@ physical assets (Autotask models them as Configuration Items — covered).
 
 | # | Item | Status |
 |---|------|--------|
-| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,216-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
+| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,281-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
 | B2 | **Time-entry writes on ww29/australia-nz for API-only users**: vendor 500 (live-verified). Time-entry creation works where the API user is a real resource, through the operator profile (`log-time-entry`); on ww29 the write is classified `failed` (a 500 with a vendor `errors[]` body), never `unknown`. | zone limitation |
-| B3 | **`time_entries.getPosted`/`getUnposted`: the zone's TimeEntry entity has no `postedDate`**, so SDK 0.31 and earlier 500ed (and `postedWithin`/`dateWorkedWindow` silently counted every entry unposted). SDK 0.32.0 derives posted state from a `billing_items.timeEntryID` join and returns `{ items, hasMore, window, approvedCount, unapprovedCount }` (optional date-only `dateFrom`/`dateTo`; no dates reads only the first 500 entries). Needs BillingItems read permission (one extra request per call); `approvedCount`/`unapprovedCount` are not posted state. Reachable via the generic layer. | resolved in SDK 0.32.0 (not re-verified live) |
+| B3 | **`time_entries.getPosted`/`getUnposted`: the zone's TimeEntry entity has no `postedDate`**, so SDK 0.31 and earlier 500ed (and `postedWithin`/`dateWorkedWindow` silently counted every entry unposted). SDK 0.32.0 derives posted state from a `billing_items.timeEntryID` join and returns `{ items, hasMore, window, approvedCount, unapprovedCount }` (optional date-only `dateFrom`/`dateTo`; no dates reads only the first 500 entries). Needs BillingItems read permission (one extra request per call); `approvedCount`/`unapprovedCount` are not posted state. SDK 0.37.0 adds `cursor`/`nextCursor` (page past 500 entries), `unconfirmed` (entries whose posted state is unknown, kept out of both counts) and `countOnly: true` on the four posted-state ops. Reachable via the generic layer. | resolved in SDK 0.32.0 (not re-verified live) |
 | B4 | **CI create on tenants without products** (ww29 product wall: `products.count = 0`): `configuration_items.create` requires an existing `productID`. No dedicated CI-create in v1; the wall is documented on the generic side. | zone limitation |
 | B5 | **Blind count/query surfaces on ww29** (companies not owned by the caller; tickets): count/query return 0/empty even when data exists. Not fixable client-side; the surface carries the typed blind-surface sentinel — `get(id)`/full-profile are the authorities. | zone limitation |
 | B6 | **`node-autotask` npm publish**: the Phase-C install gate re-checks the registry; if still 404 the build pauses and escalates (SCOPING-resolved: the user publishes — no git/file dependency fallback). | open — user action |

package/capabilities.json

@@ -69,7 +69,7 @@
     },
     {
       "id": "autotask.platform.catalog",
-      "description": "Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,216 registry operations, with effect and whether this deployment serves it. No vendor call.",
+      "description": "Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,281 registry operations, with effect and whether this deployment serves it. No vendor call.",
       "mcpPrimitive": "tool",
       "toolName": "autotask_catalog",
       "type": "read",
@@ -395,7 +395,7 @@
       "autotask_describe",
       "autotask_read"
     ],
-    "backingRegistryOperations": 1280,
+    "backingRegistryOperations": 1281,
     "note": "autotask_catalog finds the exact operation key (ranked search), autotask_describe serves its contract, autotask_read runs any effect=read key. Writes go through the operator profile (autotask_write then autotask_apply); authenticate.* is never served."
   },
   "schemas": {}

package/dist/tools/catalog-data.d.ts

@@ -65,10 +65,10 @@ export declare const UNTRUSTED_NOTE = "Externally-sourced free text in the resul
 /** The record's plan-derived untrusted field list (the registry stamp). */
 export declare function untrustedFieldsOf(rec: CapabilityRecord): string[];
 /**
- * The resources that carry user-defined fields (#183 S8), derived from the registry with zero wire:
- * the plan's `udfCapable` entities (the ones whose SDK resource class normalises `userDefinedFields`)
- * are exactly the resources whose records stamp `UDF1` in `metadata.untrustedFields`. Not the
- * `getUdfInfo` set (every vendor entity has that metadata read, UDFs or not). A test pins the exact set.
+ * The resources that carry user-defined fields (#183 S8), read from the registry with zero wire:
+ * each record's published `udfCapable` flag (node-autotask 0.37.0 #254; the plan's entities whose SDK
+ * resource class normalises `userDefinedFields`). Not the `getUdfInfo` set (every vendor entity has
+ * that metadata read, UDFs or not). A test pins the exact set.
  */
 export declare const UDF_CAPABLE: ReadonlySet<string>;
 /** The per-tool description budget (A0 slimming: every served description <= 250 chars). */
@@ -109,7 +109,7 @@ export declare function cacheOptionsForPreset(preset: 'on' | 'off', fieldCacheTt
  * fails the boot (or the CI test) instead of quietly shipping a tool surface that no longer
  * describes the SDK behind it.
  */
-export declare const BUILT_AGAINST_PLAN_HASH = "08cf890fa1b2b50574638a1364993fced7e83a5dfd4f630763d80cdc01d5a5f1";
+export declare const BUILT_AGAINST_PLAN_HASH = "5cd6c6679384651e7f67a0135915bcc031ef542640d9ebb6992b729ca42efe37";
 /**
  * Fail fast when the installed SDK's plan has moved out from under this surface.
  * Called at boot (main.ts) and safe to call repeatedly (pure comparison).

package/dist/tools/catalog-data.js

@@ -4,7 +4,7 @@
  * Two sources, both shipped inside the `node-autotask` package:
  * - `MCP_TOOL_CATALOG.json` — the machine catalog: one row per registry operation (projected
  *   tool, effect, dry-run/confirm, required args, tier, reach) and the plan hash;
- * - the compiled capability registry (`node-autotask/capabilities`) — the 1,216-operation
+ * - the compiled capability registry (`node-autotask/capabilities`) — the 1,281-operation
  *   records the SDK's own invoke governor resolves against.
  *
  * The JSON file is NOT behind the package's `exports` map, so it is read from the installed
@@ -102,12 +102,12 @@ export function untrustedFieldsOf(rec) {
     return Array.isArray(list) ? list : [];
 }
 /**
- * The resources that carry user-defined fields (#183 S8), derived from the registry with zero wire:
- * the plan's `udfCapable` entities (the ones whose SDK resource class normalises `userDefinedFields`)
- * are exactly the resources whose records stamp `UDF1` in `metadata.untrustedFields`. Not the
- * `getUdfInfo` set (every vendor entity has that metadata read, UDFs or not). A test pins the exact set.
+ * The resources that carry user-defined fields (#183 S8), read from the registry with zero wire:
+ * each record's published `udfCapable` flag (node-autotask 0.37.0 #254; the plan's entities whose SDK
+ * resource class normalises `userDefinedFields`). Not the `getUdfInfo` set (every vendor entity has
+ * that metadata read, UDFs or not). A test pins the exact set.
  */
-export const UDF_CAPABLE = new Set(RECORDS.filter((r) => untrustedFieldsOf(r).includes('UDF1')).map((r) => r.resource));
+export const UDF_CAPABLE = new Set(RECORDS.filter((r) => r.udfCapable).map((r) => r.resource));
 /** The per-tool description budget (A0 slimming: every served description <= 250 chars). */
 export const MAX_DESCRIPTION_CHARS = 250;
 /**
@@ -117,7 +117,7 @@ export const MAX_DESCRIPTION_CHARS = 250;
  */
 export const TOOL_DESCRIPTIONS = {
     autotask_guide: 'Step-by-step playbooks for multi-step Autotask tasks. No args: the index; {skill} returns one playbook, {skill, section} one section. Static text, no vendor call. Use it first when a task needs several tools.',
-    autotask_catalog: 'Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,216 registry operations, with effect and whether this deployment serves it. No vendor call.',
+    autotask_catalog: 'Find the exact operation key for anything without a dedicated tool: ranked search (q) over the 1,281 registry operations, with effect and whether this deployment serves it. No vendor call.',
     autotask_describe: 'One operation\'s (registry key or tool name) exact input/output contract, examples, errors, policy verdict and playbooks (operation), or one resource\'s relationship map: parent, children, lookup keys (resource). No vendor call.',
     autotask_read: 'Run reads by exact registry key, or up to 10 in one call: unbilled work, profitability and margin, SLA health. *.query: 50 rows; scope by company/contract ids (unscoped = tenant walk); roll-ups: autotask_aggregate; slim: includeFields, noteChars.',
     autotask_resolve: 'Find the record behind an identifier: id or name, ticket number, CI serial, contact email (by), staff by email, user name or name (resource resources, include_api_users); one resource or a sweep. Exact by default; contains: companies, tickets, sweep.',
@@ -173,7 +173,7 @@ export function cacheOptionsForPreset(preset, fieldCacheTtlMs) {
  * fails the boot (or the CI test) instead of quietly shipping a tool surface that no longer
  * describes the SDK behind it.
  */
-export const BUILT_AGAINST_PLAN_HASH = '08cf890fa1b2b50574638a1364993fced7e83a5dfd4f630763d80cdc01d5a5f1';
+export const BUILT_AGAINST_PLAN_HASH = '5cd6c6679384651e7f67a0135915bcc031ef542640d9ebb6992b729ca42efe37';
 /**
  * Fail fast when the installed SDK's plan has moved out from under this surface.
  * Called at boot (main.ts) and safe to call repeatedly (pure comparison).

package/dist/tools/dispatch.d.ts

@@ -56,6 +56,13 @@ export declare function abortedAnswer(corr: string): ToolReturn;
  * in a 4xx body; the error wrap value-scrubs them before the envelope crosses.
  */
 export declare function requestSecrets(ctx: ToolContext): string[];
+/**
+ * A vendor TimeEntries continuation URL (#224; mirrors the SDK's cursorToPath + entryCursorPath, tighter):
+ * printable ASCII with no whitespace, absolute and already in canonical form, on this request's own Autotask origin, no userinfo, no
+ * fragment, exactly the continuation path, and only `paging` / `search` query parameters with encoded
+ * values. Anything else is not granted the cursor exemption (it is served as wrapped, capped vendor text).
+ */
+export declare function isEntryCursor(value: string, origin: string | undefined): boolean;
 /**
  * Per-operation post-processing for results read through `autotask_read`: the helper operations
  * that used to have their own tools carry vendor text beyond the registry stamp, and this is where

package/dist/tools/dispatch.js

@@ -15,8 +15,9 @@ import { AutotaskConfigError } from 'node-autotask';
 import { stripUntrustedDeep } from 'node-autotask/untrusted';
 import { assertFilterShape, QUERY_LIMIT, QUERY_RESOURCES } from './schemas.js';
 import { recordById, untrustedFieldsOf } from './catalog-data.js';
+import { AUTOTASK_BASE_PATH } from '../base-hosts.js';
 import { releaseClientOnError } from './context.js';
-import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, outcome, refusalContent } from './results.js';
+import { abortedResult, closedArgsError, crossResourceUntrusted, errorContent, isFileOperation, markFilePayload, markResult, markServerField, outcome, refusalContent } from './results.js';
 import { lastFullCalendarMonth, lastFullCalendarMonthLabel } from './profitability-window.js';
 import { assertOperationPermitted } from '../policy.js';
 import { ACK_KEY, guardUnscopedWalk, ScopeRequiredError } from './scope-guard.js';
@@ -83,7 +84,7 @@ async function frame(ctx, input, rawArgs, extra, work) {
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
         const field = issue === undefined ? undefined : issue.path.map(String).join('.');
-        return errorContent(new InputInvalidError(`invalid input: ${parsed.error.issues.map((i) => `${i.path.map(String).join('.') || '(input)'}: ${i.message}`).join('; ')}`, field === '' ? undefined : field), ctx.correlationId);
+        return errorContent(new InputInvalidError(`invalid input: ${input.hint?.(raw) ?? ''}${parsed.error.issues.map((i) => `${i.path.map(String).join('.') || '(input)'}: ${i.message}`).join('; ')}`, field === '' ? undefined : field), ctx.correlationId);
     }
     if (ctx.refusal !== undefined)
         return refusalContent(ctx.refusal.kind, ctx.correlationId, ctx.refusal.anomalies ?? []);
@@ -143,6 +144,35 @@ export function requestSecrets(ctx) {
     }
     return out;
 }
+/** The time_entries posted-state reads whose `nextCursor` is a pass-back pagination cursor (SDK 0.37.0 #242). */
+const CURSOR_OPS = new Set(['time_entries.getPosted', 'time_entries.getUnposted', 'time_entries.postedWithin', 'time_entries.dateWorkedWindow']);
+/** The continuation path a TimeEntries cursor names, under the fixed base path (compared case-insensitively). */
+const ENTRY_CURSOR_PATH = `${AUTOTASK_BASE_PATH}/V1.0/TimeEntries/query/next`.toLowerCase();
+/** The query a vendor continuation URL carries: `paging` and `search`, URL-encoded values only. */
+const ENTRY_CURSOR_PARAM = /^(?:paging|search)=[A-Za-z0-9%._~+-]+$/;
+/**
+ * A vendor TimeEntries continuation URL (#224; mirrors the SDK's cursorToPath + entryCursorPath, tighter):
+ * printable ASCII with no whitespace, absolute and already in canonical form, on this request's own Autotask origin, no userinfo, no
+ * fragment, exactly the continuation path, and only `paging` / `search` query parameters with encoded
+ * values. Anything else is not granted the cursor exemption (it is served as wrapped, capped vendor text).
+ */
+export function isEntryCursor(value, origin) {
+    if (origin === undefined || !/^[\x21-\x7e]+$/.test(value) || !value.startsWith(`${origin}/`))
+        return false;
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (u.href !== value || u.origin !== origin || u.username !== '' || u.password !== '' || u.hash !== '' || value.includes('#'))
+        return false;
+    if (u.pathname.toLowerCase() !== ENTRY_CURSOR_PATH)
+        return false;
+    const query = u.search.replace(/^\?/, '');
+    return query === '' || query.split('&').every((p) => ENTRY_CURSOR_PARAM.test(p));
+}
 /** The reads behind the profitability result's customer and part containers (their untrusted stamps). */
 const PROFITABILITY_PART_OPS = [
     'contracts.profitability',
@@ -179,7 +209,30 @@ const PROFITABILITY_UNTRUSTED = [
  */
 export const READ_POSTPROCESS = {
     'contracts.profitability': (result) => markResult(result, PROFITABILITY_UNTRUSTED),
+    'operations.revenueRollup': markRevenueRollup,
 };
+/**
+ * `operations.revenueRollup` (SDK 0.37.0): the helper rows carry no `metadata.untrustedFields`. Vendor text
+ * sits in `rows[].keys.<dimension>` (`name`, `division`, `label`) and in the values of
+ * `coverage.contractTypeMap` / `contractCategoryMap` (id -> picklist label). The cross-resource list
+ * covers `name` and `label` at every depth; `division` (the LOB level-1 name) is added. ponytail: the
+ * `coverage.excluded.otherContract*` maps are keyed by label, and a key cannot be wrapped (it is still
+ * cleaned and capped by the output sanitiser).
+ */
+const ROLLUP_UNTRUSTED = [...crossResourceUntrusted(), 'division'];
+function markRevenueRollup(result) {
+    const out = markResult(result, ROLLUP_UNTRUSTED);
+    const cov = out?.coverage;
+    for (const key of ['contractTypeMap', 'contractCategoryMap']) {
+        const map = cov?.[key];
+        if (map === null || typeof map !== 'object' || Array.isArray(map))
+            continue;
+        for (const [id, label] of Object.entries(map))
+            if (typeof label === 'string')
+                markServerField(map, id, 'wrap');
+    }
+    return out;
+}
 /**
  * Server-built annotations added to a served result AFTER the untrusted marking (issue #102). Each
  * `operations.fieldCatalog` resource row says which `autotask_query` operation serves it (or null:
@@ -295,6 +348,10 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
     }
     const nameChecked = operation.endsWith('.query') || operation.endsWith('.count');
     const result = await ctx.ops.invokeRead(ctx.client, operation, cleanArgs, opts, signal).catch((err) => {
+        // #224: a refused cursor the caller passed is the caller's input; a refused vendor continuation is not
+        if (CURSOR_OPS.has(operation) && err?.code === 'RESPONSE_REJECTED' && cleanArgs.some((a) => a !== null && typeof a === 'object' && typeof a.cursor === 'string')) {
+            Object.assign(err, { callerInput: true });
+        }
         throw nameChecked ? rewriteFieldNameRefusal(err, operation, operation.slice(0, operation.lastIndexOf('.')), 'read') : err;
     });
     if (result === undefined)
@@ -312,6 +369,11 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
     const projected = result !== null && typeof result === 'object' ? markResult(result, crossResourceUntrusted()) : result;
     if (isFileOperation(operation))
         markFilePayload(projected);
+    // #224: the posted-state reads' nextCursor goes back verbatim as opts.cursor; the 500 cap would cut it
+    const cursor = CURSOR_OPS.has(operation) && projected !== null && typeof projected === 'object' ? projected.nextCursor : undefined;
+    // only a TimeEntries continuation URL is a cursor; anything else is vendor text (500 cap, wrapped)
+    if (typeof cursor === 'string')
+        markServerField(projected, 'nextCursor', isEntryCursor(cursor, ctx.origin) ? 'cursor' : 'wrap');
     if (operation === 'operations.fieldCatalog')
         annotateCatalogRows(projected);
     return { result: projected, ...(note !== undefined ? { note } : {}), ...(scopeNote !== undefined ? { scopeNote } : {}) };

package/dist/tools/field-pointer.d.ts

@@ -26,8 +26,8 @@ export declare const FIELD_INFO_EXPENSIVE = "Expensive: it returns the whole fie
  * read paths (#183 S8, AC13): `autotask_query` (`via: 'query'`: its argument is include_fields, and the escape is
  * an autotask_read call) and `autotask_read` of a `*.query` / `*.count` key (`via: 'read'`: the bag keeps
  * includeFields and fieldCheck). The SDK message separates the causes, so the remedy follows the cause: a FILTER
- * refusal names the UDF remedy (udf:true, max 1 per query, plus the include:["udf"], labels:true definitions read)
- * and says the fieldCheck:false escape is for genuine vendor field names, never a UDF name; an includeFields
+ * refusal on a UDF-capable resource names the UDF remedy (udf:true, max 1 per query, plus the include:["udf"], labels:true definitions read)
+ * and says the fieldCheck:false escape is for genuine vendor field names, never a UDF name (any other resource: the vendor-name remedy only, no UDF text); an includeFields
  * refusal carries no UDF advice (whether the vendor accepts a UDF name in IncludeFields is unverified) and keeps
  * the #76 escape. Every suggestedAction stays within the 500-character cap for every query resource (tests).
  */

package/dist/tools/field-pointer.js

@@ -1,4 +1,5 @@
 import { AutotaskConfigError } from 'node-autotask';
+import { UDF_CAPABLE } from './catalog-data.js';
 /**
  * tools/field-pointer.ts — the one place the "how do I list this resource's field names" call is
  * written (issues #102, #98). The bare `operations.fieldCatalog` serves the five workflow resources
@@ -33,8 +34,8 @@ export const FIELD_INFO_EXPENSIVE = 'Expensive: it returns the whole field table
  * read paths (#183 S8, AC13): `autotask_query` (`via: 'query'`: its argument is include_fields, and the escape is
  * an autotask_read call) and `autotask_read` of a `*.query` / `*.count` key (`via: 'read'`: the bag keeps
  * includeFields and fieldCheck). The SDK message separates the causes, so the remedy follows the cause: a FILTER
- * refusal names the UDF remedy (udf:true, max 1 per query, plus the include:["udf"], labels:true definitions read)
- * and says the fieldCheck:false escape is for genuine vendor field names, never a UDF name; an includeFields
+ * refusal on a UDF-capable resource names the UDF remedy (udf:true, max 1 per query, plus the include:["udf"], labels:true definitions read)
+ * and says the fieldCheck:false escape is for genuine vendor field names, never a UDF name (any other resource: the vendor-name remedy only, no UDF text); an includeFields
  * refusal carries no UDF advice (whether the vendor accepts a UDF name in IncludeFields is unverified) and keeps
  * the #76 escape. Every suggestedAction stays within the 500-character cap for every query resource (tests).
  */
@@ -42,9 +43,12 @@ export function rewriteFieldNameRefusal(err, operation, resource, via) {
     if (!(err instanceof AutotaskConfigError) || !err.message.includes('unknown field name'))
         return err;
     const escape = via === 'query' ? `autotask_read {operation:"${operation}", args:[{..., fieldCheck:false}]}` : 'fieldCheck:false in this args bag';
-    const suggestedAction = err.message.includes('filter condition(s) carry unknown field name')
+    // a resource outside UDF_CAPABLE has no UDFs (describe says 'not udf-capable'): its filter refusal serves only the vendor-name remedy
+    const suggestedAction = err.message.includes('filter condition(s) carry unknown field name') && UDF_CAPABLE.has(resource)
         ? `Use exact vendor field names: ${scopedCatalogCall(resource)}. A user-defined (tenant) field: filter on it with udf:true (max 1 per query); its names and picklist ids: ${udfCatalogCall(resource)}. ${escape} is for a genuine vendor name only, never a UDF name.`
-        : `Use exact vendor field names: ${scopedCatalogCall(resource)}. To skip the name check use ${escape}.`;
+        : err.message.includes('filter condition(s) carry unknown field name')
+            ? `Use exact vendor field names: ${scopedCatalogCall(resource)}. To skip the name check for a genuine vendor name use ${escape}.`
+            : `Use exact vendor field names: ${scopedCatalogCall(resource)}. To skip the name check use ${escape}.`;
     const stripped = err.message.replace(/\s*\(src\/field-sets\.ts\)/g, '');
     return new AutotaskConfigError(via === 'query' ? stripped.replace(/includeFields/g, 'include_fields') : stripped, { operation, suggestedAction });
 }

package/dist/tools/meta.d.ts

@@ -10,6 +10,12 @@ export declare function buildCatalog(ctx: ToolContext): BuiltTool;
 export declare function paramNames(operation: string, rec: unknown): Record<string, unknown> | undefined;
 /** `autotask_describe`: one operation's record + verdict + playbooks, or one resource's relationship map. */
 export declare function buildDescribe(ctx: ToolContext): BuiltTool;
+/** The single place to extend: entities the registry has no create for, yet the vendor documentation lists one, so the
+ * note would be false. `time_off_requests`: the swagger has a child create (POST /V1.0/Resources/{parentId}/TimeOffRequests,
+ * TimeOffRequestsChild_CreateEntity) and the SDK defines TimeOffRequestCreate; the SDK plan simply has no create row. */
+export declare const NO_CREATE_EXCLUDED: ReadonlySet<string>;
+/** The entities that carry the noCreate note (pinned by name in a test). */
+export declare const NO_CREATE_ENTITIES: ReadonlySet<string>;
 /** `autotask_read`: one read by exact key, or up to 10 (`items`) with per-item results. */
 export declare function buildRead(ctx: ToolContext): BuiltTool;
 /** `autotask_tenant_status`: identity / version / thresholds / server / time; each part degrades to typed absent. */

package/dist/tools/meta.js

@@ -18,6 +18,7 @@
 import { AutotaskConfigError } from 'node-autotask';
 import { effectiveRequiredFields } from 'node-autotask/operations';
 import { UDF_MERGE_NOTE, UDF_NONE, UDF_ROWS_NOTE, associationFields, associationRules, caveatNotes, constraintNotes, coupledNotes, dateConventionNotes, statusScopeNote, udfDefinitionRows, udfMergeNote, udfMoreNote, udfUnavailable } from './write-guidance.js';
+import { scrubDeep, scrubProvenance } from './provenance-scrub.js';
 import { CATALOG, RECORDS, SDK_VERSION, TOOL_NAME_BY_OP, UDF_CAPABLE, opsForTool, recordById, servedToolName, untrustedFieldsOf } from './catalog-data.js';
 import { releaseClientOnError } from './context.js';
 import { abortedAnswer, InputInvalidError, readOneItem, requestSecrets } from './dispatch.js';
@@ -252,12 +253,14 @@ const ENTITY_RESOURCES = new Set(RECORDS.filter((r) => r.id.endsWith('.getEntity
 /** The single place to extend: entities the registry has no create for, yet the vendor documentation lists one, so the
  * note would be false. `time_off_requests`: the swagger has a child create (POST /V1.0/Resources/{parentId}/TimeOffRequests,
  * TimeOffRequestsChild_CreateEntity) and the SDK defines TimeOffRequestCreate; the SDK plan simply has no create row. */
-const NO_CREATE_EXCLUDED = new Set(['time_off_requests']);
+export const NO_CREATE_EXCLUDED = new Set(['time_off_requests']);
+/** The entities that carry the noCreate note (pinned by name in a test). */
+export const NO_CREATE_ENTITIES = new Set([...ENTITY_RESOURCES].filter((r) => !CREATE_RESOURCES.has(r) && !NO_CREATE_EXCLUDED.has(r)));
 const NO_CREATE_NOTE = 'do not look for a create operation: this server has none for this entity, and the vendor API documentation lists none.';
 /**
  * S8 (#183): the UDF block for `describe {resource}`: the mechanism facts (SDK row shape) + the definitions
  * pointer. Zero wire: the capability fact is the registry itself (UDF_CAPABLE: the resources whose records
- * stamp UDF1, the plan's udfCapable entities; SDK 0.34.0 #219 N7), and the definitions are the live tenant
+ * carry the published udfCapable flag, SDK 0.37.0 #254; SDK 0.34.0 #219 N7), and the definitions are the live tenant
  * read the pointer names (the scoped fieldCatalog read with the `udf` include).
  */
 function udfBlock(resource) {
@@ -314,7 +317,7 @@ async function guidanceFor(ctx, rec, reachable) {
         // #173: the positional [from, to, opts] mixes types; the same window as one uniform-string filter
         return {
             exampleArgs: ['2026-10-20', '2026-10-22', { resourceID: 123 }],
-            sameWindowAsQuery: 'autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"123"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}: the same rows up to limit (the window caps at 500; dateWorked is a date, both days inclusive), without the posted counts, for a client that cannot send a mixed-type array.',
+            sameWindowAsQuery: 'autotask_query {resource:"time_entries", filter:[{field:"resourceID",op:"eq",value:"123"},{field:"dateWorked",op:"gte",value:"2026-10-20"},{field:"dateWorked",op:"lte",value:"2026-10-22"}], limit:500}: the same rows up to limit (one window call returns at most 500 and a nextCursor to pass as cursor for the rest; dateWorked is a date, both days inclusive), without the posted counts, for a client that cannot send a mixed-type array.',
         };
     }
     if (op === 'moveToTicket') {
@@ -350,8 +353,9 @@ async function guidanceFor(ctx, rec, reachable) {
             // The SDK's one precedence (live-proven > zone > spec) is a create fact; an update keeps the vendor's own set.
             const zone = op === 'create' ? await zoneFactsOf(ctx, rec.resource) : undefined;
             facts = zone?.createGuidance ?? undefined;
-            // the SDK's quirks are free text (provenance, tenant names, operator advice): none of it is served on a create, only a pointer
-            hasQuirks = (zone?.quirks?.length ?? 0) > 0;
+            // quirk statements are SDK free text: none is served on a create, only a pointer, and only when a quirk
+            // names the create op (SDK 0.37.0 #253 structured quirks; #224)
+            hasQuirks = (zone?.quirks ?? []).some((q) => Array.isArray(q?.ops) && q.ops.includes('create'));
             const eff = op === 'create' ? effectiveRequiredFields({ requiredFields: spec }, zone) : { fields: spec, from: 'spec', unproven: true };
             // eff.fields is already the unconditional set (value-gated fields are in eff.conditional, SDK 0.34.0)
             required = eff.fields;
@@ -414,21 +418,32 @@ async function zoneFactsOf(ctx, resource) {
 }
 /** The one read envelope of autotask_read and autotask_fetch_many (#97), served on the on-demand surface. */
 const READ_ENVELOPE = 'data = { results: Slot[], ok: <count>, failed: <count>, budget?, budgetWarning? }, always an array in input order, one slot for a single read. Slot = { ok: true, operation, result, windowNote?, scopeNote? } or { ok: false, operation, error }; autotask_fetch_many slots also echo resource and id (operation is "<resource>.get"; a miss is { ok: false, error: { code: "NOT_FOUND" } }). A single read that fails still answers the whole-call error envelope.';
-/** Served relationship map: createGuidance without the SDK's free text (`vendorEvidence`, `blocker.message`/`remedy`). */
+/** Served relationship map without the SDK's free text: createGuidance loses `vendorEvidence` and
+ * `blocker.message`/`remedy`; each structured `zoneFacts.quirks` entry loses `evidence` (SDK 0.37.0 #253: raw
+ * campaign strings) in {@link scrubDeep}, which drops every string `evidence` key and scrubs the rest (#224). */
 function projectMap(map) {
     const m = map;
-    const g = m?.zoneFacts?.createGuidance;
-    if (g === undefined || g === null || typeof g !== 'object')
-        return map;
-    const slim = { ...g };
-    delete slim.vendorEvidence;
-    if (slim.blocker !== null && typeof slim.blocker === 'object') {
-        const b = { ...slim.blocker };
-        delete b.message;
-        delete b.remedy;
-        slim.blocker = b;
+    const z = m?.zoneFacts;
+    if (z === undefined || z === null || typeof z !== 'object')
+        return scrubDeep(map);
+    const zone = { ...z };
+    // #224: a live write keeps its op and outcome; its date and note are maintainer history
+    const lw = z.liveWrites;
+    if (Array.isArray(lw))
+        zone.liveWrites = lw.map((w) => (w !== null && typeof w === 'object' ? { op: w.op, outcome: w.outcome } : w));
+    const g = z.createGuidance;
+    if (g !== undefined && g !== null && typeof g === 'object') {
+        const slim = { ...g };
+        delete slim.vendorEvidence;
+        if (slim.blocker !== null && typeof slim.blocker === 'object') {
+            const b = { ...slim.blocker };
+            delete b.message;
+            delete b.remedy;
+            slim.blocker = b;
+        }
+        zone.createGuidance = slim;
     }
-    return { ...m, zoneFacts: { ...m.zoneFacts, createGuidance: slim } };
+    return scrubDeep({ ...m, zoneFacts: zone });
 }
 /** Served record: `metadata.caveats` rows keep kind/fields/remedyOp, not the SDK's free-text `note`. */
 function projectCaveats(rec) {
@@ -458,14 +473,15 @@ function servedUsage(rec) {
     // the read-back is one `<resource>.get`: a create with no get in the registry answers `data.record: null`
     return u.includes(CREATE_USAGE_FALSE) && recordById(`${rec.resource}.get`) !== undefined ? u.replace(CREATE_USAGE_FALSE, CREATE_USAGE_TRUE) : u;
 }
-/** Served record: caveats projected and the create usage corrected (AC24). */
+/** Served record: caveats projected, the create usage corrected (AC24), the SDK's own test list dropped and
+ * its maintainer provenance scrubbed (#224). */
 function servedRecord(rec) {
-    const projected = projectCaveats(rec);
+    const projected = { ...projectCaveats(rec) };
+    delete projected.tests;
     const md = projected.metadata;
-    const usage = servedUsage(projected);
-    if (typeof md?.usage !== 'string' || usage === undefined || md.usage === usage)
-        return projected;
-    return { ...projected, metadata: { ...md, usage } };
+    const usage = servedUsage(rec);
+    const out = typeof md?.usage !== 'string' || usage === undefined || md.usage === usage ? projected : { ...projected, metadata: { ...md, usage } };
+    return scrubDeep(out);
 }
 /** The per-field caps of a describe summary (characters): purpose, args and usage only, about 2 KB in all (#197). */
 const SUMMARY_CAPS = { purpose: 500, args: 600, usage: 400 };
@@ -484,13 +500,13 @@ function summariseRecord(ctx, operation, viaTool) {
     const reason = refusalReason(operation, rec, ctx.config, ctx.writable);
     const md = (rec.metadata ?? {});
     const row = CATALOG.catalog.find((r) => r.operation === operation);
-    const text = (v) => (typeof v === 'string' ? v : '');
+    const text = (v) => (typeof v === 'string' ? scrubProvenance(v) : '');
     const cut = [];
     const tool = viaTool ?? TOOL_NAME_BY_OP[operation];
     return ok(`Summary of "${rec.id}" (purpose, args, usage).`, {
         operation: rec.id,
         ...(tool !== undefined ? { tool, ...toolServed(ctx, tool) } : {}),
-        purpose: capText(text(md.purpose) || (row?.purpose ?? ''), SUMMARY_CAPS.purpose, 'purpose', cut),
+        purpose: capText(text(md.purpose) || text(row?.purpose), SUMMARY_CAPS.purpose, 'purpose', cut),
         requiredArgs: row?.requiredArgs ?? [],
         args: capText(text(md.args), SUMMARY_CAPS.args, 'args', cut),
         usage: capText(text(servedUsage(rec)), SUMMARY_CAPS.usage, 'usage', cut),
@@ -513,7 +529,7 @@ async function describeRecord(ctx, operation, viaTool, summary = false) {
         ...(guidance !== undefined ? { guidance } : {}),
         ...(rec.effect === 'read' && (viaTool === 'autotask_fetch_many' || (viaTool === undefined && !rec.id.endsWith('.query'))) ? { readEnvelope: READ_ENVELOPE } : {}),
         record: { ...servedRecord(rec), untrustedFields: untrustedFieldsOf(rec) },
-        ...(rec.effect === 'read' && ENTITY_RESOURCES.has(rec.resource) && !CREATE_RESOURCES.has(rec.resource) && !NO_CREATE_EXCLUDED.has(rec.resource) ? { noCreate: NO_CREATE_NOTE } : {}),
+        ...(rec.effect === 'read' && NO_CREATE_ENTITIES.has(rec.resource) ? { noCreate: NO_CREATE_NOTE } : {}),
         reachable: reason === null,
         why_not: reason,
         playbooks: playbooksFor(rec.id),

package/dist/tools/provenance-scrub.d.ts

@@ -0,0 +1,20 @@
+/**
+ * tools/provenance-scrub.ts — maintainer provenance out of the SDK text `autotask_describe` serves (#224).
+ *
+ * The SDK's registry records and relationship maps carry its own build history inside otherwise useful
+ * guidance: the test zone (`ww29`), verification dates, issue numbers, campaign stages and markers, wall
+ * ids. None of it helps a model call the API, and some of it is tenant-identifying. Only the provenance
+ * tokens are removed: a parenthetical is split into clauses (`;`, ` — `, `, ` at its own depth) and only a
+ * clause that itself carries a marker is edited; a bare date survives unless its clause carries a marker
+ * (a format example such as `e.g. 2026-01-01` stays); a parenthetical left empty is dropped.
+ * Deterministic text surgery, not a guarantee: a marker the patterns below do not name passes through.
+ * ponytail: pattern list, extend it when an SDK bump adds a new marker shape.
+ */
+/** Object nesting bound for {@link scrubDeep}; deeper subtrees are dropped, never served unscrubbed. */
+export declare const MAX_DEEP = 32;
+export declare const MAX_PAREN_DEPTH = 16;
+/** `text` with the provenance tokens removed (a text with no marker is returned as it is). */
+export declare function scrubProvenance(text: string): string;
+export declare function scrubExample(text: string): string;
+/** A deep copy with every string scrubbed (`examples` by {@link scrubExample}) and the provenance-only string keys dropped. */
+export declare function scrubDeep(value: unknown, depth?: number): unknown;