@vectros-ai/mcp-server 0.16.1 → 0.17.1

package/dist/cli.js

@@ -60,6 +60,7 @@ __export(api_exports, {
   FieldDef: () => FieldDef,
   FileUploadRequest: () => FileUploadRequest,
   ForbiddenError: () => ForbiddenError,
+  GatewayTimeoutError: () => GatewayTimeoutError,
   IdentityLookupRequest: () => IdentityLookupRequest,
   IndexFailure: () => IndexFailure,
   InternalServerError: () => InternalServerError,
@@ -84,9 +85,12 @@ __export(api_exports, {
   SearchRequest: () => SearchRequest,
   SearchResult: () => SearchResult,
   SearchResultsEvent: () => SearchResultsEvent,
+  ServiceUnavailableError: () => ServiceUnavailableError,
   TooManyRequestsError: () => TooManyRequestsError,
+  TriggerFailureResponse: () => TriggerFailureResponse,
   TruncationWarningEvent: () => TruncationWarningEvent,
   UnauthorizedError: () => UnauthorizedError,
+  UnprocessableEntityError: () => UnprocessableEntityError,
   UserExistsResponse: () => UserExistsResponse,
   UserRequest: () => UserRequest,
   UserResponse: () => UserResponse,
@@ -98,7 +102,9 @@ __export(api_exports, {
   inference: () => inference_exports,
   records: () => records_exports,
   schemas: () => schemas_exports,
-  search: () => search_exports
+  scripts: () => scripts_exports,
+  search: () => search_exports,
+  triggers: () => triggers_exports
 });
 var toJson = (value, replacer, space) => {
   return JSON.stringify(value, replacer, space);
@@ -218,6 +224,21 @@ var ForbiddenError = class extends VectrosError {
     this.name = this.constructor.name;
   }
 };
+var GatewayTimeoutError = class extends VectrosError {
+  constructor(body, rawResponse) {
+    super({
+      message: "GatewayTimeoutError",
+      statusCode: 504,
+      body,
+      rawResponse
+    });
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+    this.name = this.constructor.name;
+  }
+};
 var InternalServerError = class extends VectrosError {
   constructor(body, rawResponse) {
     super({
@@ -278,6 +299,21 @@ var PaymentRequiredError = class extends VectrosError {
     this.name = this.constructor.name;
   }
 };
+var ServiceUnavailableError = class extends VectrosError {
+  constructor(body, rawResponse) {
+    super({
+      message: "ServiceUnavailableError",
+      statusCode: 503,
+      body,
+      rawResponse
+    });
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+    this.name = this.constructor.name;
+  }
+};
 var TooManyRequestsError = class extends VectrosError {
   constructor(body, rawResponse) {
     super({
@@ -308,6 +344,21 @@ var UnauthorizedError = class extends VectrosError {
     this.name = this.constructor.name;
   }
 };
+var UnprocessableEntityError = class extends VectrosError {
+  constructor(body, rawResponse) {
+    super({
+      message: "UnprocessableEntityError",
+      statusCode: 422,
+      body,
+      rawResponse
+    });
+    Object.setPrototypeOf(this, new.target.prototype);
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+    this.name = this.constructor.name;
+  }
+};
 var auth_exports = {};
 var ErasureRequest;
 ((ErasureRequest2) => {
@@ -397,6 +448,7 @@ var LookupRecordsRequestOrder = {
   Desc: "desc"
 };
 var schemas_exports = {};
+var scripts_exports = {};
 var SearchRequest;
 ((SearchRequest2) => {
   SearchRequest2.Mode = {
@@ -422,6 +474,7 @@ var search_exports = {};
 __export(search_exports, {
   SearchRequest: () => SearchRequest
 });
+var triggers_exports = {};
 var AccessProfileRequest;
 ((AccessProfileRequest2) => {
   AccessProfileRequest2.Status = {
@@ -451,7 +504,9 @@ var BatchWriteResult;
     Created: "created",
     Updated: "updated",
     Conflict: "conflict",
-    Invalid: "invalid"
+    Invalid: "invalid",
+    Forbidden: "forbidden",
+    NotCommitted: "not_committed"
   };
 })(BatchWriteResult || (BatchWriteResult = {}));
 var ChatMessage;
@@ -755,13 +810,23 @@ var SearchResultsEvent;
     SearchResults: "search_results"
   };
 })(SearchResultsEvent || (SearchResultsEvent = {}));
+var TriggerFailureResponse;
+((TriggerFailureResponse2) => {
+  TriggerFailureResponse2.Event = {
+    Create: "CREATE",
+    Update: "UPDATE",
+    Delete: "DELETE"
+  };
+})(TriggerFailureResponse || (TriggerFailureResponse = {}));
 var TruncationWarningEvent;
 ((TruncationWarningEvent2) => {
   TruncationWarningEvent2.Event = {
     TruncationWarning: "truncation_warning"
   };
   TruncationWarningEvent2.Reason = {
-    ContextWindowBudget: "context_window_budget"
+    ContextWindowBudget: "context_window_budget",
+    NoGroundableContent: "no_groundable_content",
+    ContextWindowBudgetAndNoContent: "context_window_budget_and_no_content"
   };
 })(TruncationWarningEvent || (TruncationWarningEvent = {}));
 var UserExistsResponse;
@@ -776,8 +841,7 @@ var UserRequest;
 ((UserRequest2) => {
   UserRequest2.Status = {
     Active: "ACTIVE",
-    Suspended: "SUSPENDED",
-    Pending: "PENDING"
+    Suspended: "SUSPENDED"
   };
   UserRequest2.Type = {
     Human: "HUMAN",
@@ -2245,6 +2309,16 @@ function mergeHeaders(...headersArray) {
   }
   return result;
 }
+function mergeOnlyDefinedHeaders(...headersArray) {
+  const result = {};
+  for (const [key, value] of headersArray.filter((headers) => headers != null).flatMap((headers) => Object.entries(headers))) {
+    const insensitiveKey = key.toLowerCase();
+    if (value != null) {
+      result[insensitiveKey] = value;
+    }
+  }
+  return result;
+}
 function normalizeClientOptions(options) {
   const headers = mergeHeaders(
     {
@@ -2515,7 +2589,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/admin/keys/scoped");
   }
   /**
-   * Creates a scoped API key (an `ssk_*` secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the `keys:c` scope. If you use a scoped credential, `keys:c` alone is not sufficient: because the minted key is durably bound to the profile you name, the profile's effective scopes may not exceed your own, and you may only mint against a profile whose `identityOverrides` values your own identity holds. Minting a key bound to your OWN principal needs nothing further; minting one bound to a DIFFERENT principal additionally requires the `delegate-mint` capability (`granted_capabilities`) on your credential — without it the request is refused. A root API key (`sk_`) is exempt from all three bounds.
+   * Creates a scoped API key (an `ssk_*` secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the `keys:c` scope. If you use a scoped credential, `keys:c` alone is not sufficient: because the minted key is durably bound to the profile you name, the profile's effective scopes may not exceed your own, and you may only mint against a profile whose `identityOverrides` values your own identity holds. Minting a key bound to your OWN principal needs nothing further; minting one bound to a DIFFERENT principal additionally requires the `delegate-mint` capability (`granted_capabilities`) on your credential — without it the request is refused. A root API key (`sk_`) is exempt from all three bounds. The profile you name must be `active` AND the user you name must not be `SUSPENDED`: either is refused with `409`, and no root exemption applies to that. Both refusals stop ISSUANCE only. Suspending the profile additionally stops credentials already bound to it, within about five minutes; suspending the user does not stop their existing keys at all. A `PENDING` user is fine.
    *
    * @param {Vectros.CreateScopedKeyRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -2523,6 +2597,7 @@ var AuthClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -2571,6 +2646,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -2982,7 +3059,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/app-contexts");
   }
   /**
-   * Creates a new app context. This call is idempotent by `contextId`: if an app context with the same `contextId` already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's `name`/`description` instead of returning it unchanged, set `?upsert=true` (this also requires the `app-contexts:u` scope). The reserved `contextId` value `vectros-admin` cannot be created through this endpoint; it is provisioned automatically for your account. Requires the `app-contexts:c` scope.
+   * Creates a new app context. This call is idempotent by `contextId`: if an app context with the same `contextId` already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's `name`/`description`/`companyName` instead of returning it unchanged, set `?upsert=true` (this also requires the `app-contexts:u` scope). The reserved `contextId` value `vectros-admin` cannot be created through this endpoint; it is provisioned automatically for your account. Requires the `app-contexts:c` scope.
    *
    * @param {Vectros.CreateAppContextRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3348,6 +3425,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -3390,6 +3468,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -3466,7 +3546,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/app-contexts/{contextId}");
   }
   /**
-   * Updates the name and/or description of an app context. This is a partial update: any field you omit (or send as null) keeps its existing value. The `contextId` is immutable and is taken from the URL path, so any `contextId` in the request body is ignored. Requires the `app-contexts:u` scope.
+   * Updates the name, description, and/or companyName of an app context. This is a partial update: any field you omit (or send as null) keeps its existing value. The `contextId` is immutable and is taken from the URL path, so any `contextId` in the request body is ignored. Requires the `app-contexts:u` scope.
    *
    * @param {Vectros.UpdateAppContextRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3534,7 +3614,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/app-contexts/{contextId}");
   }
   /**
-   * Permanently deletes an app context and everything in it — every record, document, folder, schema, role, and access profile belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's `status` field to observe when the teardown completes (`purging` while draining, then `deleted`). To guard against accidental deletion, you must echo the contextId back in the `confirm` query parameter (`?confirm={contextId}`). The reserved `default` and `vectros-admin` contexts cannot be deleted. This operation requires a root API key (one beginning with `sk_`): no scoped credential, not even one with full wildcard (`*`) scope, can trigger this teardown.
+   * Permanently deletes an app context and everything in it — every record, document, folder, schema, role, access profile, and trusted-issuer registration belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's `status` field to observe when the teardown completes (`purging` while draining, then `deleted`). To guard against accidental deletion, you must echo the contextId back in the `confirm` query parameter (`?confirm={contextId}`). The reserved `default` and `vectros-admin` contexts cannot be deleted. This operation requires a root API key (one beginning with `sk_`): no scoped credential, not even one with full wildcard (`*`) scope, can trigger this teardown.
    *
    * @param {Vectros.DeleteAppContextRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3948,7 +4028,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when `year` and `month` are omitted. Requires the `billing:r` scope on scoped tokens; API keys always have access. **A token confined to a single app context sees only that context's usage**: totals, the environment split, and the `contexts` breakdown narrow to it, and the environment your context is not bound to is omitted (`null`), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: `reads.calls.used`/`reads.dataOut.bytes` (metered per account, not per context) read as `0` for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and `credits.limit` stays your whole plan's ceiling, so `credits.remaining` may overstate the account's true remaining room.
+   * Returns full usage detail for the requested calendar month, broken down by category (search, documents, records, and trigger-script execution time) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when `year` and `month` are omitted. Requires the `billing:r` scope on scoped tokens; API keys always have access. **A token confined to a single app context sees only that context's usage**: totals, the environment split, and the `contexts` breakdown narrow to it, and the environment your context is not bound to is omitted (`null`), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: `reads.calls.used`/`reads.dataOut.bytes` (metered per account, not per context) read as `0` for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and `credits.limit` stays your whole plan's ceiling, so `credits.remaining` may overstate the account's true remaining room. The `execution` section narrows correctly for a confined token, like the other per-context charge fields — but note its credits carry sub-credit remainders forward across your whole account for the period, so compare `execution.creditsMilli` against your account-wide figure rather than recomputing it from one context's `billableMillis`.
    *
    * @param {Vectros.GetUsageRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4069,7 +4149,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers/{issuerId}");
   }
   /**
-   * Updates the mutable fields of a registered issuer: `subClaim`, `emailClaim`, `status` (`active`/`suspended` — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and `selfSignupPolicies`. Fields omitted from the body are left unchanged (partial update). `issuer`, `jwksUri`, `audience`, and `contextId` are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.
+   * Updates the mutable fields of a registered issuer: `subClaim`, `emailClaim`, `userinfoUri`, `capturedClaims`, `restrictedToDomain` (a new non-blank value must already be a VERIFIED domain for your account; an empty string clears it back to domain-less; see `IssuerUpdateRequest.restrictedToDomain` for the full semantics), `status` (`active`/`suspended` — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and `selfSignupPolicies`. Fields omitted from the body are left unchanged (partial update). `issuer`, `jwksUri`, `audience`, and `contextId` are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. **`subClaim` is identity-determining, not merely cosmetic**: it names which verified JWT claim is read as the federated user's identifier, so changing it on an issuer that already has bound users would silently re-identify (or, under self-signup, orphan) every one of them — changing it is therefore refused once any user has bound through this issuer, the same guard `DELETE` already applies, and is only free before the first real login. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.
    *
    * @param {Vectros.IssuerUpdateRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4136,7 +4216,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/auth/issuers/{issuerId}");
   }
   /**
-   * Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through `POST /v1/auth/token/exchange`) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.
+   * Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through `POST /v1/auth/token/exchange`) — that access cannot be silently orphaned. This is unconditional on the affected users' `status`: suspending them first does not lift the refusal. **A bound registration cannot be replaced, self-service, within its own app context**: registering a replacement issuer under a different issuerId in the SAME context also fails, because the context's one-active-issuer claim is released only when THIS registration is deleted. Two real options: suspend this issuer (stops new exchanges immediately) and register a replacement under a DIFFERENT app context — note that targets a different context, so this context's existing users/roles/access profiles are not carried over; or contact your platform operator, who can force-release this registration so a replacement may be registered in the SAME context under a new issuerId. **The operator path is not a lighter-weight alternative to the first — it PERMANENTLY RETIRES this issuerId and leaves every bound user unable to ever exchange through it again; it does not preserve continuity for them any better than registering under a different context does.** An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.
    *
    * @param {Vectros.DeleteIssuerRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4262,7 +4342,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers");
   }
   /**
-   * Registers a trusted third-party IdP issuer that BYO-IdP token exchange (`POST /v1/auth/token/exchange`) may accept a `subject_token` from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. A credential authorized only via the provisioning capability may register only against the app context it is bound to; naming a different one returns 403. A root API key is unaffected and may register against any of its contexts. Idempotent by `issuerId` within your tenant; the `(issuer, audience)` pair must not already be registered by a different issuerId/tenant. If `issuerId` collides with a registration owned by a different app context than the one you're confined to, the request fails with 400 rather than returning that context's configuration. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct `audience`.
+   * Registers a trusted third-party IdP issuer that BYO-IdP token exchange (`POST /v1/auth/token/exchange`) may accept a `subject_token` from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. A credential authorized only via the provisioning capability may register only against the app context it is bound to; naming a different one returns 403. A root API key is unaffected and may register against any of its contexts. Idempotent by `issuerId` within your tenant; the `(issuer, audience)` pair must not already be registered by a different issuerId/tenant. If `issuerId` collides with a registration owned by a different app context than the one you're confined to, the request fails with 400 rather than returning that context's configuration. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct `audience`. Optionally name `restrictedToDomain` to scope this registration's (issuer, audience) uniqueness to a specific VERIFIED domain rather than the bare pair — see that field's own description for the full contract, including why it does NOT protect a shared/consumer-IdP registration with no company-domain population.
    *
    * @param {Vectros.IssuerRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5760,7 +5840,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/versions");
   }
   /**
-   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata).
+   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL for the SAME existing document, targeting a newly-staged object rather than the document's current one — your PUT lands there first, and the document only adopts it once the upload is validated (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata). **Your PUT to `uploadUrl` MUST include the header named in the response's `requiredHeaderName`, set to `requiredHeaderValue` exactly.** It is a signed part of the presigned request — the PUT never reaches this service either way, so neither failure uses this API's JSON error shape. Omitting it, or sending a different value, invalidates the request's signature and S3 rejects it with a 403 `SignatureDoesNotMatch`. Sending it correctly makes the URL single-use: `requiredHeaderName` is always `If-None-Match` and `requiredHeaderValue` is always `*` — a create, a recovery upload for a document whose earlier file is missing, and a re-upload ALL target a freshly-minted, never-written key, so the same S3 conditional-write precondition applies uniformly (S3's own documented conditional-write behavior): a replay after the object already exists (from your own completed PUT, or anyone else's) fails with `412 Precondition Failed`; a replay after the object was deleted and never re-created finds an absent key again and can succeed — single-use is a property of the object's existence, not a one-time token. **Either precondition can also fail with `409 Conflict` if your PUT genuinely races a concurrent delete on the same object.** Whichever of `412` or `409` you receive, the remedy is the same: call this endpoint again for a fresh URL rather than retrying the same PUT — a fresh call always targets a new key, so it is never subject to whatever raced the previous one.
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6082,7 +6162,7 @@ var FoldersClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/folders/{id}");
   }
   /**
-   * Permanently deletes a folder. The folder must be empty (contain no documents or sub-folders) and must not be protected. Your context's root folder is protected and cannot be deleted. Requires the `folders:d` scope.
+   * Permanently deletes a folder. The folder must be empty — it must contain no documents, no records, and no sub-folders — and must not be protected. Your context's root folder is protected and cannot be deleted. Requires the `folders:d` scope.
    *
    * @param {Vectros.DeleteFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6491,11 +6571,12 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/entities/{namespace}/{id}");
   }
   /**
-   * Updates the mutable fields of an entity. Omitted fields are preserved (a null value does not clear a field), and the `payload` object is replaced in full when supplied. Providing `scopes` replaces the entity's parent edges. Requires the `entities:u:<namespace>` scope.
+   * Updates the mutable fields of an entity. Omitted fields are preserved (a null value does not clear a field), and the `payload` object is replaced in full when supplied. Providing `scopes` replaces the entity's parent edges. Supplying a different `externalId` re-points the entity's identifier; it must still be unused in this namespace and app context. Requires the `entities:u:<namespace>` scope.
    *
    * @param {Vectros.UpdateEntityRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -6545,6 +6626,8 @@ var IdentityClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -7523,7 +7606,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/exists-by-email");
   }
   /**
-   * Returns the audit trail of changes to a user, most recent first. Identity history is always recorded and always available. Sensitive field values are redacted in every historical version. Returns a page in the `{data, nextCursor}` envelope. Requires the `users:r` scope.
+   * Returns the audit trail of changes to a user, most recent first, including after the user has been deleted. Identity history is always recorded. Post-delete, this is readable by an account-level (root) API key only — a context-confined credential 404s after the delete, the same response it would get for a nonexistent id. Sensitive field values are redacted in every historical version. Returns a page in the `{data, nextCursor}` envelope. Requires the `users:r` scope.
    *
    * @param {Vectros.GetUserVersionsRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7769,7 +7852,7 @@ var InferenceClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/documents/{id}/ask");
   }
   /**
-   * Runs hybrid search over your indexed content, then streams a model answer grounded in the top results. The SSE stream emits a `search_results` event first (carrying the matched results and their metadata), an optional `truncation_warning` if lower-scoring results were dropped to fit the model's context window, then `content_delta` chunks, and finally a terminal `done` event. Requires the `inference:r` scope.
+   * Runs hybrid search over your indexed content, then streams a model answer grounded in the top results. The SSE stream emits a `search_results` event first (carrying the matched results and their metadata), an optional `truncation_warning` if some retrieved results were dropped before the prompt was built — either because they didn't fit the model's context window or because a result had no groundable text to include — then `content_delta` chunks, and finally a terminal `done` event. Requires the `inference:r` scope.
    */
   ragInference(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__ragInference(request, requestOptions));
@@ -7964,14 +8047,18 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/records/lookup/batch");
   }
   /**
-   * Reserved endpoint for bulk record writes. The published response shape includes a per-item partial-failure envelope and an atomicity flag. It currently returns 501 (not implemented). The documented 200 response schema is the stable shape this endpoint will use once available, published now so SDK integrations against it will not break when it ships. Requires the `records:c` scope.
+   * Writes up to 50 records (or 50 with `atomicity: all_or_nothing`) in a single request. Each item in `items` has exactly the same shape, and goes through exactly the same validation, authorization and idempotency rules, as the body of a single `POST /v1/records` — including schema validation, `externalId` idempotency, unique-field enforcement, and the `records:c:<type>` scope check, which is applied per item against that item's own record type. A batch is not a way to write a type your credential could not write one at a time.
+   *
+   * `atomicity` selects how the batch commits. `best_effort` (the default) writes each item independently: some can succeed while others fail, and each item's own outcome is reported. `all_or_nothing` commits every item in one transaction — if any item fails, no record is created or updated at all, and every item that was itself fine reports `not_committed` while the ones that failed report why. Because the transaction is bounded by the number of underlying storage rows rather than by the number of records, a large `all_or_nothing` batch can be refused as too large to commit atomically even when it is within the item limit; the error says so, and nothing is written when it happens.
+   *
+   * The response is HTTP 200 whenever the batch was processed at all — including when every item failed — so always inspect `results` rather than relying on the status code. Match each result to the item you sent using its `index`. Requires the `records:c` scope.
    *
    * @param {Vectros.BatchWriteRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
-   * @throws {@link Vectros.NotImplementedError}
    *
    * @example
    *     await client.records.batchWriteRecords()
@@ -7980,6 +8067,11 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__batchWriteRecords(request, requestOptions));
   }
   async __batchWriteRecords(request = {}, requestOptions) {
+    const { upsert, allowClear, ..._body } = request;
+    const _queryParams = {
+      upsert,
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -7994,9 +8086,9 @@ var RecordsClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -8008,12 +8100,12 @@ var RecordsClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
-        case 501:
-          throw new NotImplementedError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -8584,7 +8676,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/records/lookup");
   }
   /**
-   * Returns the tombstone left behind when a record was hard-deleted, confirming the deletion and recording when it happened. Look it up using the deleted record's original ID. Requires the `records:r:<type>` scope.
+   * Returns the tombstone left behind when a record was hard-deleted, confirming the deletion and recording when it happened. Look it up using the deleted record's original ID. Requires the `records:r:<type>` scope, granted without a `data_scope` restriction: the owner of a deleted record cannot be checked, so a credential confined to an ownership compartment (e.g. `data_scope: {scope:org: [org_A]}`) cannot read tombstones, including for records it owned.
    *
    * @param {Vectros.GetRecordTombstoneRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8916,7 +9008,7 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/schemas/{id}");
   }
   /**
-   * Updates a record schema. Fields you omit are preserved; `typeName` is immutable and cannot be changed. Collection fields (`fields`, `lookupFields`, `renderHints`, `capabilities`) are replaced in full when supplied. Requires the `schemas:u` scope.
+   * Updates a record schema. Fields you omit are preserved; `typeName` is immutable and cannot be changed. Collection fields (`fields`, `lookupFields`, `renderHints`, `capabilities`) are replaced in full when supplied. Because `capabilities` is replaced in full, omitting `triggersEnabled` clears it — the request is refused with 409 if that would disable triggers while trigger rules still fire off this schema, so delete those rules first. Requires the `schemas:u` scope.
    *
    * @param {Vectros.UpdateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8924,6 +9016,7 @@ var SchemasClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -8975,6 +9068,8 @@ var SchemasClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -8988,7 +9083,7 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/schemas/{id}");
   }
   /**
-   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. A lineage base (a schema other schemas declare `basedOn`) also cannot be deleted while any such variant still exists — delete the variant schema(s) first. Requires the `schemas:d` scope.
+   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. The same applies to documents bound to this schema (for a schema declaring the `document` surface) — delete those documents first. A lineage base (a schema other schemas declare `basedOn`) also cannot be deleted while any such variant still exists — delete the variant schema(s) first. It is likewise refused while any trigger rule fires off this schema — delete those trigger rules first. Requires the `schemas:d` scope.
    *
    * @param {Vectros.DeleteSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9110,46 +9205,70 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/schemas/{id}/versions");
   }
 };
-var SearchClient = class {
+var ScriptsClient = class {
   constructor(options) {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Runs a hybrid, semantic, or text search across the content you have indexed. By default it returns both documents and records in a single unified result set; pass `contentTypes` to narrow the results (for example `["documents"]`). Each result carries a `sourceType` discriminator (`PartnerDocument` or `GenericRecord`) so you can branch on the type. Requires the `search:r` scope.
+   * Runs a script you previously pushed to `POST /v1/scripts`, under your own credential, and returns what it returned. Every write the script makes is buffered and committed as ONE transaction after the script finishes: either all of them land or none do, and the response is sent only after they have committed — so everything in `result` is committed state or the script's own computation over it. On any failure the body is the standard error envelope and nothing the script staged is committed: its rows are written only when the transaction commits, and a document body or a large payload is DECIDED at that point and WRITTEN to storage only after the commit, so an aborted execution leaves nothing behind. The one residual sits after a successful commit, outside this response: if storing a body fails then, the row exists and the body does not until the platform's repair lands — so a `200` guarantees the rows, and a document's text should be read before it is relied on.
    *
-   * @param {Vectros.SearchRequest} request
-   * @param {SearchClient.RequestOptions} requestOptions - Request-specific configuration.
+   * **Permission.** Requires the `scripts:x` scope — the permission to *execute* — separate from the `scripts:c` permission to push scripts. Bare `scripts:x` grants every script in the context; `scripts:x:<name>` grants exactly that script name, every version of it. Execution discloses no source, so `scripts:r` is not needed. Inside the script, every read and write is enforced by your credential's data scopes exactly as the equivalent REST call would be — `scripts:x` alone can read and write nothing.
+   *
+   * **Input.** Your script sees `input.event` (the literal `"execute"`), `input.userId` (your credential's user id, or null), and `input.params` (the `input` object you sent, verbatim). That is the same `input` grammar a trigger rule uses, so one script can serve both by branching on `input.event`. `params` is not validated — a script that needs a shape checks for it and throws; the script's `declaredInputContract` is documentation for readers and is not enforced.
+   *
+   * **Budget.** Seconds of useful work: the script has 15 s of wall clock (never more than 16) and a bounded number of statements and host calls; a runaway script is stopped early with `RESOURCE_LIMIT_EXCEEDED`. The transaction is bounded by the number of underlying storage rows it writes — 100 rows after merging — rather than by the number of entities: creating a folder costs 3 rows; creating a plain text document or a record costs 1 row plus one per range-indexed lookup field plus one per `reference` field. So "create a folder and file N documents" holds up to 97 plain documents, 48 with one range field or one reference, 32 with both; if a script exceeds the limit the error says so (`WRITE_BUFFER_CAP_EXCEEDED`, with `total` and `limit`) and nothing is committed. This request takes the write-path limits (burst, credit ceiling, principal quota) once, before the script runs — there is no free-read allowance here, so an account over its credit ceiling is refused even for a read-only script. Reads the script performs are metered as reads, writes as writes, and execution time beyond what those operations include is charged as script execution time (see `GET /v1/usage`).
+   *
+   * **Reads inside the script.** A `get` sees the script's own staged writes. A list, query or lookup never shows a row the script has deleted, shows a row it re-saved with the updated content, and does not show a row it created — you hold that row's id from `create()`.
+   *
+   * **Retries.** Send an optional `Idempotency-Key` header (1–128 characters of letters, digits, `.`, `_`, `:` or `-`) to make a retry safe: a request repeated under the same key within 24 hours receives the same response as the first attempt without executing again — when that first attempt SUCCEEDED (a duplicate still in flight is refused with `409 IDEMPOTENCY_IN_PROGRESS`; the same key on a different request is refused with `422 IDEMPOTENCY_KEY_REUSED`). A first attempt that FAILED with any other status is not remembered: the same key is free to try again, so a retry after a `400` or a `429` executes. If an execution's outcome cannot be determined — the script did not finish inside the budget while its writes may have committed — the response is `500 EXECUTION_OUTCOME_UNKNOWN` carrying `execution.id`, and a keyed retry receives that same answer: inspect what the script would have written, then use a NEW key for a new attempt. When a key is present the serialised `result` is capped at 16 KB instead of 256 KB. Without a key, a lost response cannot be distinguished from a failed one; re-read before retrying.
+   *
+   * @param {Vectros.ScriptExecuteRequest} request
+   * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.PaymentRequiredError}
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.ContentTooLargeError}
+   * @throws {@link Vectros.UnprocessableEntityError}
    * @throws {@link Vectros.TooManyRequestsError}
+   * @throws {@link Vectros.InternalServerError}
+   * @throws {@link Vectros.ServiceUnavailableError}
+   * @throws {@link Vectros.GatewayTimeoutError}
    *
    * @example
-   *     await client.search.content({
-   *         query: "patient intake form diabetes"
+   *     await client.scripts.executeScript({
+   *         "Idempotency-Key": "order-8412-attempt",
+   *         scriptRef: {
+   *             name: "notify-assignee",
+   *             version: "3"
+   *         }
    *     })
    */
-  content(request, requestOptions) {
-    return HttpResponsePromise.fromPromise(this.__content(request, requestOptions));
+  executeScript(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__executeScript(request, requestOptions));
   }
-  async __content(request, requestOptions) {
+  async __executeScript(request, requestOptions) {
+    const { "Idempotency-Key": idempotencyKey, ..._body } = request;
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
       this._options?.headers,
+      mergeOnlyDefinedHeaders({ "Idempotency-Key": idempotencyKey }),
       requestOptions?.headers
     );
     const _response = await fetcher({
       url: url_exports.join(
         await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
-        "v1/search"
+        "v1/scripts/execute"
       ),
       method: "POST",
       headers: _headers,
       contentType: "application/json",
       queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -9163,10 +9282,26 @@ var SearchClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 402:
+          throw new PaymentRequiredError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 413:
+          throw new ContentTooLargeError(_response.error.body, _response.rawResponse);
+        case 422:
+          throw new UnprocessableEntityError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        case 500:
+          throw new InternalServerError(_response.error.body, _response.rawResponse);
+        case 503:
+          throw new ServiceUnavailableError(_response.error.body, _response.rawResponse);
+        case 504:
+          throw new GatewayTimeoutError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -9175,102 +9310,880 @@ var SearchClient = class {
           });
       }
     }
-    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/search");
-  }
-};
-var VectrosClient = class {
-  constructor(options) {
-    this._options = normalizeClientOptionsWithAuth(options);
-  }
-  get auth() {
-    return this._auth ?? (this._auth = new AuthClient(this._options));
-  }
-  get documents() {
-    return this._documents ?? (this._documents = new DocumentsClient(this._options));
-  }
-  get identity() {
-    return this._identity ?? (this._identity = new IdentityClient(this._options));
-  }
-  get compliance() {
-    return this._compliance ?? (this._compliance = new ComplianceClient(this._options));
-  }
-  get folders() {
-    return this._folders ?? (this._folders = new FoldersClient(this._options));
-  }
-  get inference() {
-    return this._inference ?? (this._inference = new InferenceClient(this._options));
-  }
-  get records() {
-    return this._records ?? (this._records = new RecordsClient(this._options));
-  }
-  get schemas() {
-    return this._schemas ?? (this._schemas = new SchemasClient(this._options));
-  }
-  get search() {
-    return this._search ?? (this._search = new SearchClient(this._options));
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/scripts/execute");
   }
   /**
-   * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
-   * This is useful for making requests to endpoints not yet supported in the SDK.
-   * The input can be a URL string, URL object, or Request object. Relative paths are resolved against the configured base URL.
+   * Returns a paginated list of your scripts. Pass `name` to list every version of one script name (oldest first); omit it for a flat list across every name in your account (newest first). Results are returned as a `{data, nextCursor}` envelope — pass `nextCursor` as `startFrom` to fetch the next page. Requires the `scripts:r` scope. **Each row's `source` is omitted by default** (`sourceOmitted: true`) — scripts are immutable per version, so a name's version history can otherwise carry every version's complete source in one response. Pass `?includeSource=true` to get it back inline, or fetch one version's full source with a by-id GET. **`?name=<n>&latest=true`** answers "what is the current version of this name" in one bounded call — a single `ScriptResponse` object (not a page), instead of draining every page of the name's version history to find the newest yourself.
    *
-   * @param {Request | string | URL} input - The URL, path, or Request object.
-   * @param {RequestInit} init - Standard fetch RequestInit options.
-   * @param {core.PassthroughRequest.RequestOptions} requestOptions - Per-request overrides (timeout, retries, headers, abort signal).
-   * @returns {Promise<Response>} A standard Response object.
+   * @param {Vectros.ListScriptsRequest} request
+   * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.NotFoundError}
+   *
+   * @example
+   *     await client.scripts.listScripts({
+   *         name: "notify-assignee",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
+   *     })
    */
-  async fetch(input, init, requestOptions) {
-    return makePassthroughRequest(
-      input,
-      init,
-      {
-        baseUrl: this._options.baseUrl ?? this._options.environment,
-        headers: this._options.headers,
-        timeoutInSeconds: this._options.timeoutInSeconds,
-        maxRetries: this._options.maxRetries,
-        fetch: this._options.fetch,
-        logging: this._options.logging,
-        getAuthHeaders: async () => (await this._options.authProvider.getAuthRequest()).headers
-      },
-      requestOptions
-    );
-  }
-};
-var logging;
-((logging2) => {
-  logging2.LogLevel = LogLevel;
-  logging2.ConsoleLogger = ConsoleLogger;
-})(logging || (logging = {}));
-
-// src/server.ts
-var import_types3 = require("@modelcontextprotocol/sdk/types.js");
-var import_zod23 = require("zod");
-
-// src/auth.ts
-var KEY_RE = /^(sk|ssk|st)_(live|test)_/;
-var InvalidApiKeyError = class extends Error {
-  constructor(reason) {
-    super(`Invalid VECTROS_API_KEY: ${reason}`);
-    this.name = "InvalidApiKeyError";
+  listScripts(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__listScripts(request, requestOptions));
   }
-};
-function parseApiKey(raw) {
-  if (!raw || raw.trim().length === 0) {
-    throw new InvalidApiKeyError(
-      "env var is missing or empty. Set VECTROS_API_KEY to a Vectros key (recommended: ssk_live_... or ssk_test_...)."
+  async __listScripts(request = {}, requestOptions) {
+    const { name, startFrom, limit, includeSource, latest } = request;
+    const _queryParams = {
+      name,
+      startFrom,
+      limit,
+      includeSource,
+      latest
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
     );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/scripts"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/scripts");
   }
-  const match = raw.match(KEY_RE);
-  if (!match) {
-    throw new InvalidApiKeyError(
-      `key must start with sk_, ssk_, or st_ followed by "live_" or "test_". Got prefix "${raw.slice(0, 12)}...".`
-    );
+  /**
+   * Stores a new version of a script object. Every POST creates a genuinely new version — this is NOT idempotent-by-name: pushing `name` again always creates a new row with `scriptVersion` auto-incremented (the first version pushed for a name is 1). `source` is stored as-is: nothing parses or validates it at push time. A version runs when a trigger rule references it (`POST /v1/triggers`) or when `POST /v1/scripts/execute` names it. `provisionedBy` MAY BE SET ON ABSENT, NEVER CHANGED, evaluated against the CURRENT LATEST version of this `name` at push time: if the latest version has no marker recorded, this push may set any value; if the latest version already has one, an omitted value inherits it forward and a DIFFERENT value is refused — a live comparison against whichever version is newest at push time, not a value fixed for the name's whole history. Pushing onto an EXISTING name with no `provisionedBy` recorded on its current latest version additionally requires that you were the caller who pushed that latest version — a name carrying a `provisionedBy` marker is exempt from this check (proving you can supply or inherit the matching marker is itself the ownership proof there). Requires the `scripts:c` scope.
+   *
+   * @param {Vectros.ScriptRequest} request
+   * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.scripts.createScript({
+   *         name: "notify-assignee",
+   *         source: "export default function(input) { return { ok: true }; }"
+   *     })
+   */
+  createScript(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__createScript(request, requestOptions));
   }
-  return {
-    prefix: match[1],
-    env: match[2],
-    raw
-  };
+  async __createScript(request, requestOptions) {
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/scripts"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: request,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/scripts");
+  }
+  /**
+   * Retrieves a single script version by its ID. Requires the `scripts:r` scope.
+   *
+   * @param {Vectros.GetScriptRequest} request
+   * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.NotFoundError}
+   *
+   * @example
+   *     await client.scripts.getScript({
+   *         id: "id"
+   *     })
+   */
+  getScript(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__getScript(request, requestOptions));
+  }
+  async __getScript(request, requestOptions) {
+    const { id } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/scripts/${url_exports.encodePathParam(id)}`
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/scripts/{id}");
+  }
+  /**
+   * Scripts are immutable per version; this endpoint always returns a 400 regardless of scope or credential — push a new version via `POST /v1/scripts` instead.
+   *
+   * @param {Vectros.UpdateScriptRequest} request
+   * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.scripts.updateScript({
+   *         id: "id",
+   *         body: {
+   *             name: "notify-assignee",
+   *             source: "export default function(input) { return { ok: true }; }"
+   *         }
+   *     })
+   */
+  updateScript(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__updateScript(request, requestOptions));
+  }
+  async __updateScript(request, requestOptions) {
+    const { id, body: _body } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/scripts/${url_exports.encodePathParam(id)}`
+      ),
+      method: "PUT",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: _body,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: void 0, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/scripts/{id}");
+  }
+  /**
+   * Permanently deletes one script version by ID. Deleting one version does not affect any other version of the same name. Requires the `scripts:d` scope. Refused with 409 if a live trigger rule still references this version — either directly (a pinned `scriptRef`), or via `"latest"` when this IS the newest version of its name. Delete or re-point those rules first.
+   *
+   * @param {Vectros.DeleteScriptRequest} request
+   * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.scripts.deleteScript({
+   *         id: "id"
+   *     })
+   */
+  deleteScript(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__deleteScript(request, requestOptions));
+  }
+  async __deleteScript(request, requestOptions) {
+    const { id } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/scripts/${url_exports.encodePathParam(id)}`
+      ),
+      method: "DELETE",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: void 0, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "DELETE", "/v1/scripts/{id}");
+  }
+};
+var SearchClient = class {
+  constructor(options) {
+    this._options = normalizeClientOptionsWithAuth(options);
+  }
+  /**
+   * Runs a hybrid, semantic, or text search across the content you have indexed. By default it returns both documents and records in a single unified result set; pass `contentTypes` to narrow the results (for example `["documents"]`). Each result carries a `sourceType` discriminator (`PartnerDocument` or `GenericRecord`) so you can branch on the type. Requires the `search:r` scope.
+   *
+   * @param {Vectros.SearchRequest} request
+   * @param {SearchClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.search.content({
+   *         query: "patient intake form diabetes"
+   *     })
+   */
+  content(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__content(request, requestOptions));
+  }
+  async __content(request, requestOptions) {
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/search"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: request,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/search");
+  }
+};
+var TriggersClient = class {
+  constructor(options) {
+    this._options = normalizeClientOptionsWithAuth(options);
+  }
+  /**
+   * Returns a page of trigger executions that failed — what went wrong, whether the platform will retry it, and which of your records and rules were involved. Use this to find automation that has stopped running.
+   *
+   * A record appears once per FIRING, not once per attempt: if the platform retries a retryable failure, the same record's `attempts` count rises rather than a new record appearing. **If a retry later succeeds, the record is removed** — so this endpoint describes what is currently broken, not a permanent history. Records also expire 30 days after the firing first failed.
+   *
+   * `detail` is safe to surface to your own users: it carries only your own content (a script's own thrown message) or public API vocabulary, never platform internals. For `INTERNAL_ERROR` it is absent and a `correlationId` is returned instead — quote that to support.
+   *
+   * Scoped to your account and app context, derived from your token — never from input. Requires the `triggers:r` scope.
+   *
+   * @param {Vectros.ListTriggerFailuresRequest} request
+   * @param {TriggersClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @example
+   *     await client.triggers.listTriggerFailures({
+   *         ruleId: "3b1c9f2e7a5d8410f6c2e9a1b7d4038f5e6a91c2d7f0b3a4586c9e2f1d0a7b3c",
+   *         category: "SCRIPT_ERROR",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
+   *     })
+   */
+  listTriggerFailures(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__listTriggerFailures(request, requestOptions));
+  }
+  async __listTriggerFailures(request = {}, requestOptions) {
+    const { ruleId, category, retryable, from: from_, to, startFrom, limit } = request;
+    const _queryParams = {
+      ruleId,
+      category,
+      retryable,
+      from: from_,
+      to,
+      startFrom,
+      limit
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/trigger-failures"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      throw new VectrosError({
+        statusCode: _response.error.statusCode,
+        body: _response.error.body,
+        rawResponse: _response.rawResponse
+      });
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/trigger-failures");
+  }
+  /**
+   * Returns a paginated list of your trigger rules, newest first. Results are returned as a `{data, nextCursor}` envelope — pass `nextCursor` as `startFrom` to fetch the next page. Requires the `triggers:r` scope.
+   *
+   * @param {Vectros.ListTriggersRequest} request
+   * @param {TriggersClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @example
+   *     await client.triggers.listTriggers({
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
+   *     })
+   */
+  listTriggers(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__listTriggers(request, requestOptions));
+  }
+  async __listTriggers(request = {}, requestOptions) {
+    const { startFrom, limit } = request;
+    const _queryParams = {
+      startFrom,
+      limit
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/triggers"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      throw new VectrosError({
+        statusCode: _response.error.statusCode,
+        body: _response.error.body,
+        rawResponse: _response.rawResponse
+      });
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/triggers");
+  }
+  /**
+   * Declares a new trigger rule, or (with `?upsert=true`) reconciles an existing one of the same name to the submitted shape. Once declared, the rule fires: a record write on the named schema dispatches the referenced script, which runs asynchronously under this rule's own grant. Because that grant is executed, a scoped credential may not declare a trigger whose grant exceeds its own — such a request is rejected with a `403`, and a `roleIds` entry that does not resolve in this context with a `400`. Requires the `triggers:c` scope (also `triggers:u` when `?upsert=true` matches an existing row).
+   *
+   * @param {Vectros.CreateTriggerRequest} request
+   * @param {TriggersClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.triggers.createTrigger({
+   *         body: {
+   *             name: "on-intake-create",
+   *             firingSource: {
+   *                 schemaId: "sch_9f8e7d6c",
+   *                 event: "CREATE"
+   *             },
+   *             scriptRef: {
+   *                 name: "notify-assignee",
+   *                 version: "3"
+   *             }
+   *         }
+   *     })
+   */
+  createTrigger(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__createTrigger(request, requestOptions));
+  }
+  async __createTrigger(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/triggers"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: _body,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/triggers");
+  }
+  /**
+   * Retrieves a single trigger rule by its ID. Requires the `triggers:r` scope.
+   *
+   * @param {Vectros.GetTriggerRequest} request
+   * @param {TriggersClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.NotFoundError}
+   *
+   * @example
+   *     await client.triggers.getTrigger({
+   *         id: "id"
+   *     })
+   */
+  getTrigger(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__getTrigger(request, requestOptions));
+  }
+  async __getTrigger(request, requestOptions) {
+    const { id } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/triggers/${url_exports.encodePathParam(id)}`
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/triggers/{id}");
+  }
+  /**
+   * Updates an existing trigger rule in place. The rule's resulting grant must be within your own granted scope — including a grant you did not change, because a trigger's other fields (its `scriptRef`, its `principalId`) determine what that grant executes. `name`, `principalId` and `provisionedBy` are immutable once set. Requires the `triggers:u` scope.
+   *
+   * @param {Vectros.UpdateTriggerRequest} request
+   * @param {TriggersClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.triggers.updateTrigger({
+   *         id: "id",
+   *         body: {
+   *             name: "on-intake-create",
+   *             firingSource: {
+   *                 schemaId: "sch_9f8e7d6c",
+   *                 event: "CREATE"
+   *             },
+   *             scriptRef: {
+   *                 name: "notify-assignee",
+   *                 version: "3"
+   *             }
+   *         }
+   *     })
+   */
+  updateTrigger(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__updateTrigger(request, requestOptions));
+  }
+  async __updateTrigger(request, requestOptions) {
+    const { id, body: _body } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/triggers/${url_exports.encodePathParam(id)}`
+      ),
+      method: "PUT",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: _body,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/triggers/{id}");
+  }
+  /**
+   * Permanently deletes one trigger rule by ID. Requires the `triggers:d` scope.
+   *
+   * @param {Vectros.DeleteTriggerRequest} request
+   * @param {TriggersClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.triggers.deleteTrigger({
+   *         id: "id"
+   *     })
+   */
+  deleteTrigger(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__deleteTrigger(request, requestOptions));
+  }
+  async __deleteTrigger(request, requestOptions) {
+    const { id } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/triggers/${url_exports.encodePathParam(id)}`
+      ),
+      method: "DELETE",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: void 0, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "DELETE", "/v1/triggers/{id}");
+  }
+};
+var VectrosClient = class {
+  constructor(options) {
+    this._options = normalizeClientOptionsWithAuth(options);
+  }
+  get auth() {
+    return this._auth ?? (this._auth = new AuthClient(this._options));
+  }
+  get documents() {
+    return this._documents ?? (this._documents = new DocumentsClient(this._options));
+  }
+  get identity() {
+    return this._identity ?? (this._identity = new IdentityClient(this._options));
+  }
+  get compliance() {
+    return this._compliance ?? (this._compliance = new ComplianceClient(this._options));
+  }
+  get folders() {
+    return this._folders ?? (this._folders = new FoldersClient(this._options));
+  }
+  get inference() {
+    return this._inference ?? (this._inference = new InferenceClient(this._options));
+  }
+  get records() {
+    return this._records ?? (this._records = new RecordsClient(this._options));
+  }
+  get schemas() {
+    return this._schemas ?? (this._schemas = new SchemasClient(this._options));
+  }
+  get scripts() {
+    return this._scripts ?? (this._scripts = new ScriptsClient(this._options));
+  }
+  get search() {
+    return this._search ?? (this._search = new SearchClient(this._options));
+  }
+  get triggers() {
+    return this._triggers ?? (this._triggers = new TriggersClient(this._options));
+  }
+  /**
+   * Make a passthrough request using the SDK's configured auth, retry, logging, etc.
+   * This is useful for making requests to endpoints not yet supported in the SDK.
+   * The input can be a URL string, URL object, or Request object. Relative paths are resolved against the configured base URL.
+   *
+   * @param {Request | string | URL} input - The URL, path, or Request object.
+   * @param {RequestInit} init - Standard fetch RequestInit options.
+   * @param {core.PassthroughRequest.RequestOptions} requestOptions - Per-request overrides (timeout, retries, headers, abort signal).
+   * @returns {Promise<Response>} A standard Response object.
+   */
+  async fetch(input, init, requestOptions) {
+    return makePassthroughRequest(
+      input,
+      init,
+      {
+        baseUrl: this._options.baseUrl ?? this._options.environment,
+        headers: this._options.headers,
+        timeoutInSeconds: this._options.timeoutInSeconds,
+        maxRetries: this._options.maxRetries,
+        fetch: this._options.fetch,
+        logging: this._options.logging,
+        getAuthHeaders: async () => (await this._options.authProvider.getAuthRequest()).headers
+      },
+      requestOptions
+    );
+  }
+};
+var logging;
+((logging2) => {
+  logging2.LogLevel = LogLevel;
+  logging2.ConsoleLogger = ConsoleLogger;
+})(logging || (logging = {}));
+
+// src/server.ts
+var import_types3 = require("@modelcontextprotocol/sdk/types.js");
+var import_zod24 = require("zod");
+
+// src/auth.ts
+var KEY_RE = /^(sk|ssk|st)_(live|test)_/;
+var InvalidApiKeyError = class extends Error {
+  constructor(reason) {
+    super(`Invalid VECTROS_API_KEY: ${reason}`);
+    this.name = "InvalidApiKeyError";
+  }
+};
+function parseApiKey(raw) {
+  if (!raw || raw.trim().length === 0) {
+    throw new InvalidApiKeyError(
+      "env var is missing or empty. Set VECTROS_API_KEY to a Vectros key (recommended: ssk_live_... or ssk_test_...)."
+    );
+  }
+  const match = raw.match(KEY_RE);
+  if (!match) {
+    throw new InvalidApiKeyError(
+      `key must start with sk_, ssk_, or st_ followed by "live_" or "test_". Got prefix "${raw.slice(0, 12)}...".`
+    );
+  }
+  return {
+    prefix: match[1],
+    env: match[2],
+    raw
+  };
 }
 function warnOnSuboptimalKey(key, log) {
   if (key.prefix === "sk") {
@@ -9288,8 +10201,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.16.1" : "dev",
-  sdk: true ? "0.42.0" : "dev"
+  mcpServer: true ? "0.17.1" : "dev",
+  sdk: true ? "0.44.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -9600,11 +10513,18 @@ var inputSchema = {
   // Ownership.
   userId: import_zod.z.string().optional().describe("Restrict to content owned by this user (Vectros UUID)."),
   scope: import_zod.z.string().optional().describe(
-    'Restrict to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
+    'Restrict to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. Mutually exclusive with `scopeFilters` \u2014 use this for ONE dimension.'
+  ),
+  scopeFilters: import_zod.z.array(import_zod.z.string()).min(1, "scopeFilters must name at least one dimension when supplied").optional().describe(
+    'Restrict to content matching ALL of these scope values \u2014 one per namespace \u2014 for a credential whose access spans more than one ownership dimension. e.g. ["org:<uuid>", "client:<uuid>"] narrows to one specific client WITHIN one specific org, which `scope` alone cannot express. Same `namespace:value` form as `scope`; naming the same namespace twice is rejected. Mutually exclusive with `scope` \u2014 use `scope` for a single dimension.'
   ),
   // Date window.
-  createdAfter: import_zod.z.string().optional().describe("Restrict to content created at/after this ISO 8601 UTC timestamp."),
-  createdBefore: import_zod.z.string().optional().describe("Restrict to content created at/before this ISO 8601 UTC timestamp."),
+  createdAfter: import_zod.z.string().optional().describe(
+    "Restrict to content CREATED at/after this ISO 8601 UTC timestamp \u2014 the item's own creation time, which does NOT move when the item is later re-indexed. One bounded exception: an item matched on its FIRST index may be checked against the moment it was indexed instead, a small allowance for clock skew between creating and indexing it. Do not confuse this with a hit's returned `createdAt`, which is the index timestamp and can be later \u2014 see the tool description."
+  ),
+  createdBefore: import_zod.z.string().optional().describe(
+    "Restrict to content CREATED at/before this ISO 8601 UTC timestamp \u2014 same creation-time basis, and the same first-index allowance, as createdAfter."
+  ),
   // Relevance tuning.
   minSimilarity: import_zod.z.number().min(0).max(1).optional().describe("Minimum semantic similarity (0.0\u20131.0); results below are excluded."),
   minTextRelevance: import_zod.z.number().min(0).max(1).optional().describe("Minimum relative keyword (BM25) relevance (0.0\u20131.0); the keyword-leg analogue of minSimilarity."),
@@ -9619,11 +10539,21 @@ var inputSchema = {
 var hybridSearch = ({ client, log }) => ({
   name: "hybrid_search",
   title: "Hybrid search",
-  description: 'Search your tenant\'s indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/scope), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller\'s scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword (BM25) leg matched nothing (all textScores 0) \u2014 typically the default PHRASE mode finding no contiguous match for a long natural-language query. Loosen the keyword leg: shorten the query to its key terms, or set textMode "AND" (all terms, higher precision) or "OR" (any term, broad recall).',
+  description: 'Search your tenant\'s indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId, and scope for ONE ownership dimension or scopeFilters for several at once \u2014 e.g. one client within one org), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller\'s scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents AND records are excluded from results \u2014 fetch them by id via document_get/record_get, or restore them by setting status back to ACTIVE. One exception to know: an item archived before the platform enforced this can still be returned here until it is next written to, and nothing sweeps for those \u2014 if an archived item does come back as a hit, re-send status ARCHIVED on it (document_update / record_update) to re-assert the retraction. A hit\'s `createdAt` is when the item entered the search INDEX, which is the moment it was created in the common case but is later for anything re-indexed since \u2014 so do not report it to a user as the creation time; fetch the item with document_get/record_get and read its own createdAt for that. (The createdAfter/createdBefore filters are a separate thing and do filter on true creation time.) To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword (BM25) leg matched nothing (all textScores 0) \u2014 typically the default PHRASE mode finding no contiguous match for a long natural-language query. Loosen the keyword leg: shorten the query to its key terms, or set textMode "AND" (all terms, higher precision) or "OR" (any term, broad recall).',
   inputSchema,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
     const mode = args.mode ?? "HYBRID";
+    if (args.scope !== void 0 && args.scopeFilters !== void 0) {
+      return toolError(
+        "hybrid_search",
+        new Error(
+          "'scope' and 'scopeFilters' are mutually exclusive \u2014 pass 'scope' for a single ownership dimension, or 'scopeFilters' for more than one, not both."
+        )
+      );
+    }
     try {
       const result = await client.search.content({
         query: args.query,
@@ -9638,6 +10568,7 @@ var hybridSearch = ({ client, log }) => ({
         filters: args.filters,
         userId: args.userId,
         scope: args.scope,
+        scopeFilters: args.scopeFilters,
         createdAfter: args.createdAfter,
         createdBefore: args.createdBefore,
         minSimilarity: args.minSimilarity,
@@ -9716,7 +10647,9 @@ async function drainPages(fetchPage) {
 var MCP_DEFAULT_LIMIT2 = 3;
 var MCP_MAX_LIMIT2 = 100;
 var inputSchema2 = {
-  type: import_zod2.z.string().min(1, "type (record type) is required").describe('Record type / schema name (e.g. "patient", "clinical_note").'),
+  type: import_zod2.z.string().min(1, "type must be non-empty when supplied").optional().describe(
+    'Record type / schema name (e.g. "patient", "clinical_note"). REQUIRED for a lookup (`field`). In list mode it is one of three ways to choose what to list \u2014 supply `type`, `folderId`, or `recent` \u2014 and it may be combined with `folderId` to list one type within one folder.'
+  ),
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | values | from+to | prefix.
   field: import_zod2.z.string().optional().describe(
     'Lookup mode: name of the lookup-indexed field to query by. `externalId` is always queryable \u2014 e.g. `{type:"control", field:"externalId", value:"ctrl-scoped-key"}` finds the record you created under that externalId. (record_get / record_update also accept externalId directly.) For a SCHEMA-declared composite lookup \u2014 check list_schemas\' lookupFields for a fieldNames entry, not any two fields you pick \u2014 give those field names comma-joined in the declared order (e.g. "status,area"). Use `values` to match on several of those fields at once, or `value` to match on just the FIRST field named (equivalent to a one-element `values`); range/prefix are not valid on a composite field.'
@@ -9738,6 +10671,12 @@ var inputSchema2 = {
     "Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc` \u2014 use `desc` with a range/prefix lookup to get the most-recent / highest values first (e.g. latest-N). Ignored in list mode."
   ),
   // List-mode args:
+  folderId: import_zod2.z.string().optional().describe(
+    "List mode: list the records filed in this folder (a Vectros folder UUID), regardless of type \u2014 the record-side counterpart of document_query's folderId. Combine with `type` to list a single type within the folder. Use this to see what a folder holds before deleting it: folder_delete refuses a folder that still contains records."
+  ),
+  recent: import_zod2.z.boolean().optional().describe(
+    "List mode: return the account-wide recently-updated feed across ALL record types, newest first \u2014 a type-agnostic activity view, and the one way to read records without naming a type. Standalone: it cannot be combined with `type`, `folderId`, `userId` or `scope` (the API ignores them here, so this tool rejects the combination rather than silently returning something else). You still see only the record types your credential may read."
+  ),
   userId: import_zod2.z.string().optional().describe("List mode: scope to records owned by this user."),
   scope: import_zod2.z.string().optional().describe(
     'List mode: filter to records carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
@@ -9750,11 +10689,15 @@ var inputSchema2 = {
 var recordQuery = ({ client, log }) => ({
   name: "record_query",
   title: "Record query (list or lookup)",
-  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `values` (exact, composite \u2014 one value per field; a single-element array is the same as `value`), `from`+`to` (range), or `prefix`. `values` with more than one entry, or a comma-joined `field`, ONLY works for a lookup the schema itself declared over several fields together \u2014 check list_schemas' lookupFields for a fieldNames entry, then pass those field names comma-joined as `field`; `from`/`to`/`prefix` are not valid there. Works on sensitive fields too. Optionally narrow an exact match to a window with `sortFrom`/`sortTo`.\n  \u2022 List by type: omit `field`; optionally filter by `userId` or `scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. A composite lookup given fewer than its full field count returns records grouped by the unspecified fields, ordered within each group. Mode is auto-detected from the arguments present.",
+  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `values` (exact, composite \u2014 one value per field; a single-element array is the same as `value`), `from`+`to` (range), or `prefix`. `values` with more than one entry, or a comma-joined `field`, ONLY works for a lookup the schema itself declared over several fields together \u2014 check list_schemas' lookupFields for a fieldNames entry, then pass those field names comma-joined as `field`; `from`/`to`/`prefix` are not valid there. Works on sensitive fields too. Optionally narrow an exact match to a window with `sortFrom`/`sortTo`.\n  \u2022 List: omit `field`, then choose ONE of `type` (every record of a type), `folderId` (every record filed in a folder, any type \u2014 combine with `type` for one type within one folder), or `recent` (the account-wide recently-updated feed across every type, newest first \u2014 the only way to read records without naming a type, and standalone: no other filter applies to it). `userId`/`scope` further narrow the type and folder modes.\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. A composite lookup given fewer than its full field count returns records grouped by the unspecified fields, ordered within each group. Mode is auto-detected from the arguments present.",
   inputSchema: inputSchema2,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT2;
     const type = args.type;
+    const folderId = args.folderId;
+    const recent = args.recent;
     const field = args.field;
     const value = args.value;
     const values = args.values;
@@ -9772,6 +10715,48 @@ var recordQuery = ({ client, log }) => ({
         )
       );
     }
+    if (field && (folderId !== void 0 || recent !== void 0)) {
+      return toolError(
+        "record_query",
+        new Error(
+          "'folderId' and 'recent' are list-mode selectors and do not apply to a lookup ('field') \u2014 a lookup runs within one `type` and would ignore them. Drop `field` to list, or drop these to look up."
+        )
+      );
+    }
+    if (field && !type) {
+      return toolError(
+        "record_query",
+        new Error(
+          "a lookup ('field') is always within one record type \u2014 pass 'type'. To read across types, use list mode with 'folderId' or 'recent'."
+        )
+      );
+    }
+    if (!field) {
+      if (recent && (type !== void 0 || folderId !== void 0)) {
+        return toolError(
+          "record_query",
+          new Error(
+            "'recent' is the account-wide feed across all types and cannot be narrowed \u2014 it is mutually exclusive with 'type' and 'folderId'. Drop 'recent' to list by type/folder."
+          )
+        );
+      }
+      if (recent && (args.userId !== void 0 || args.scope !== void 0)) {
+        return toolError(
+          "record_query",
+          new Error(
+            "'recent' ignores the owner filters \u2014 'userId'/'scope' would be silently dropped. List by 'type' or 'folderId' to filter by owner."
+          )
+        );
+      }
+      if (!recent && type === void 0 && folderId === void 0) {
+        return toolError(
+          "record_query",
+          new Error(
+            "list mode needs one of 'type' (records of a type), 'folderId' (records in a folder, any type), or 'recent' (the account-wide recently-updated feed). Add 'field' to run a lookup."
+          )
+        );
+      }
+    }
     try {
       let page;
       if (field) {
@@ -9835,6 +10820,7 @@ var recordQuery = ({ client, log }) => ({
           }
         }
         page = await client.records.lookupRecordsByBody({
+          // Non-null: the `field && !type` guard above returns before reaching lookup mode.
           type,
           field: normalizedField,
           value,
@@ -9855,13 +10841,22 @@ var recordQuery = ({ client, log }) => ({
       } else {
         page = await client.records.listRecords({
           type,
+          folderId,
+          ...recent ? { recent: "true" } : {},
           userId: args.userId,
           scope: args.scope,
           startFrom,
           limit
         });
         log.debug(
-          { tool: "record_query", mode: "list", type, limit, returned: pageItems(page).length },
+          {
+            tool: "record_query",
+            mode: recent ? "list:recent" : folderId ? "list:folder" : "list:type",
+            type,
+            folderId,
+            limit,
+            returned: pageItems(page).length
+          },
           "record_query list ok"
         );
       }
@@ -9943,6 +10938,8 @@ var recordGet = ({ client, log }) => ({
   title: "Get a record by id or externalId",
   description: "Fetch a single structured record, including the full payload. Select it EITHER by its Vectros `id` (e.g. from record_query / hybrid_search) OR by your own `externalId` + `type` \u2014 the same key you passed to record_create, resolved for you (no manual record_query lookup needed). Very large payloads are truncated to protect the agent context window. The response carries the record's processing `indexStatus`; when it is FAILED an `indexFailure.code` explains whether the content is still searchable (e.g. VECTOR_LIMIT_EXCEEDED keeps keyword search vs INDEXING_FAILED = not findable at all) \u2014 branch on the `code`, not the message.",
   inputSchema: inputSchema3,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     const externalId = args.externalId;
@@ -9988,6 +10985,8 @@ var recordBatchGet = ({ client, log }) => ({
   title: "Get multiple records by id in one call",
   description: "Fetch several structured records by id in a single call (1-100 ids), each with its full payload \u2014 the same hydration record_get gives a single id. Use this instead of N record_get calls when you already hold several ids (e.g. a page of record_query/hybrid_search results). Any id you can't access is silently omitted from `data`; the response also returns `missingIds` \u2014 every requested id not present in `data` \u2014 so you can tell a partial result from a complete one. As with record_get, an oversized payload is truncated into a labelled `payloadPreview` rather than shipped whole.",
   inputSchema: inputSchema4,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const ids = args.ids;
     try {
@@ -10038,7 +11037,7 @@ var inputSchema5 = {
   folderId: import_zod5.z.string().optional().describe("Group this record into a folder."),
   userId: import_zod5.z.string().optional().describe("Owning user id."),
   scopes: import_zod5.z.array(import_zod5.z.string()).optional().describe(
-    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the record\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE record owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the record\'s COMPLETE scope declaration, and each entry must fall inside the `data_scope` of a single clause of your credential that also grants this write \u2014 your identity supplies the DEFAULT when you state none, it does not limit which value you may state. An empty array `[]` creates a PRIVATE record owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
   )
 };
 var recordCreate = ({ client, log }) => ({
@@ -10046,6 +11045,13 @@ var recordCreate = ({ client, log }) => ({
   title: "Create a record",
   description: "Create a structured record of a given type. Provide `type` and `fields` (the payload, validated against the type schema \u2014 call list_schemas first to learn required fields and enums). Idempotent by `externalId`. Requires the key to allow records:c (and records:r to receive the existing record on a collision).",
   inputSchema: inputSchema5,
+  // Creates, never modifies or deletes an existing record. Idempotent ONLY when the caller
+  // supplies `externalId` (optional, per the doc comment above) — re-creating with the same
+  // one returns the existing record rather than duplicating it. `externalId` is not required,
+  // so annotated for the less-safe default (omit it, and a retry creates a second record),
+  // not the safer opt-in — same standard applied to record_batch_write, which has the
+  // identical optional-externalId shape.
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args) => {
     const type = args.type;
     try {
@@ -10071,19 +11077,110 @@ var recordCreate = ({ client, log }) => ({
 });
 var record_create_default = recordCreate;
 
-// src/tools/record_update.ts
+// src/tools/record_batch_write.ts
 var import_zod6 = require("zod");
-var inputSchema6 = {
-  id: import_zod6.z.string().optional().describe("The Vectros record id to update. Provide this OR externalId+type."),
+var MCP_MAX_ITEMS = 50;
+var itemSchema = import_zod6.z.strictObject({
+  type: import_zod6.z.string().min(1, "type is required").describe('Record type / schema name (e.g. "task"). Must match an existing schema \u2014 see list_schemas.'),
+  fields: import_zod6.z.record(import_zod6.z.string(), import_zod6.z.unknown()).describe(
+    "The record payload \u2014 a JSON object of field\u2192value, validated against the type schema. Same rules as record_create, including the signed 64-bit range on numbers (send a larger whole number as a STRING)."
+  ),
   externalId: import_zod6.z.string().optional().describe(
+    'Stable caller-supplied id, unique per type \u2014 supply it to make a batch safely retryable, since without one a re-submitted item creates a second record. Without `upsert`, an item whose externalId already matches a COMMITTED record comes back `updated` (the idempotent repeat \u2014 nothing was overwritten) if your credential can read that type; a create-only credential gets `conflict` instead, because it may not be shown the existing record. \u26A0\uFE0F Two items sharing ONE externalId WITHIN a single batch are only refused as a `conflict` under atomicity:"all_or_nothing". Under the DEFAULT best_effort each item is written independently, so the second matches what the first just wrote and reports `updated` \u2014 a duplicate key in your input silently collapses two rows into one, counted in `succeeded`, not in `failed`. De-duplicate by externalId before sending, or use all_or_nothing if you need the batch to refuse. A result returns the record\'s `id`, not the record itself; fetch that with record_get/record_batch_get.'
+  ),
+  indexMode: import_zod6.z.enum(["HYBRID", "SEMANTIC", "TEXT", "NONE"]).optional().describe(
+    "Search-index strategy for this record, set at create only and NOT changeable later. HYBRID (BM25 + dense), SEMANTIC (dense only), TEXT (BM25 only), NONE (store-only \u2014 the record never appears in hybrid_search/rag_ask, though it stays retrievable by id and by structured-field lookup). Omit to inherit the type schema's default; if that default is NONE and you want these records searchable, set it here, because it cannot be fixed after the write."
+  ),
+  status: import_zod6.z.string().optional().describe("Record lifecycle status. Defaults to ACTIVE server-side."),
+  folderId: import_zod6.z.string().optional().describe("Group this record into a folder."),
+  userId: import_zod6.z.string().optional().describe("Owning user id."),
+  scopes: import_zod6.z.array(import_zod6.z.string()).optional().describe(
+    "Scope ownership as `namespace:value` entries, at most 2 namespaces. When supplied this is the record's COMPLETE scope declaration, and each entry must fall inside the `data_scope` of a single clause of your credential that also grants this write \u2014 your identity supplies the DEFAULT when you state none, it does not limit which value you may state. `[]` creates a PRIVATE record owned by the calling user alone. Omit to inherit the credential's full identity."
+  )
+});
+var inputSchema6 = {
+  items: import_zod6.z.array(itemSchema).min(1).max(MCP_MAX_ITEMS).describe(
+    `The records to write, 1-${MCP_MAX_ITEMS}. Each item is shaped like a record_create call (\`type\` + \`fields\`, plus the same optional externalId/indexMode/status/folderId/userId/scopes) and is validated and scope-checked individually against its OWN type \u2014 items may mix types.`
+  ),
+  atomicity: import_zod6.z.enum(["best_effort", "all_or_nothing"]).optional().describe(
+    'How the batch commits. "best_effort" (the default) writes each item independently \u2014 some can succeed while others fail. "all_or_nothing" commits every item in ONE transaction: if any item fails nothing is written at all, and the items that were themselves fine report status "not_committed". Choose all_or_nothing when the records are interdependent or a half-written set would be worse than none; note it can still be refused as too large to commit atomically even within the item limit, because that transaction is bounded by underlying storage rows rather than by item count (nothing is written when that happens).'
+  ),
+  upsert: import_zod6.z.boolean().optional().describe(
+    "Applies to every item: when true, an item whose `externalId` already exists OVERWRITES that record instead of returning it unchanged. Needs records:u:<type> in addition to records:c:<type>, checked per item. Default false."
+  ),
+  allowClear: import_zod6.z.boolean().optional().describe(
+    "Only meaningful with upsert:true, which overwrites as a FULL replacement. If an item's `fields` omits (or nulls) a stored field that only comes back as an indexed projection \u2014 a large record whose payload is stored externally \u2014 the overwrite is refused unless you set this to true to confirm you mean to clear those fields. Default false. To change some fields without clearing the omitted ones, use record_update instead of an upserting batch."
+  )
+};
+var recordBatchWrite = ({ client, log }) => ({
+  name: "record_batch_write",
+  title: "Create or upsert multiple records in one call",
+  description: 'Write up to 50 structured records in a single call \u2014 use this instead of N record_create calls when you hold several records (e.g. filing a parsed table, or seeding a set of tasks). Items may mix types; each one is schema-validated, externalId-idempotent and scope-checked individually against its own type (records:c:<type> per item), so a batch cannot write a type you could not write one at a time. `atomicity` chooses the commit shape: "best_effort" (default) writes each item independently; "all_or_nothing" commits every item in one transaction, writing nothing at all if any item fails \u2014 prefer it when a half-written set would be worse than none. IMPORTANT: this call reports success whenever the batch was PROCESSED, including when every item failed \u2014 so always read the per-item `results` and the `succeeded`/`failed` counts rather than treating a non-error result as "all written". This differs from record_create, where a failure is an error result. Results are NOT guaranteed to arrive in the order you submitted: match each one to its item by its `index` (zero-based, the position in your `items` array). A result carries the written record\'s `id` (null on failure) and, when it failed, an `error` with a machine-readable `code` and a human-readable `message` \u2014 read it before resubmitting. It does NOT carry the record itself; fetch that with record_get/record_batch_get. A per-item `status` is created (new record written), updated (an existing record matched \u2014 overwritten only if you passed upsert:true, otherwise returned unchanged, so this is not by itself evidence of a write), conflict (uniqueness or version), invalid (validation \u2014 read `error.message` for which field), forbidden (your credential lacks the scope or ownership that item needed \u2014 fix the credential, not the item), or not_committed (this item was fine but an all_or_nothing batch was aborted by a different item, so resubmitting with that one fixed writes this one unchanged).',
+  inputSchema: inputSchema6,
+  // Creates by default, and can overwrite existing records as a FULL replacement when
+  // `upsert:true` is passed (destructive to whatever fields the old version carried and
+  // this call omits). Idempotent ONLY when every item supplies `externalId` (optional,
+  // per its own field doc above) — re-submitting then converges, with or without
+  // `upsert:true`. `externalId` is not required, so annotated for the less-safe default:
+  // an item with no `externalId` at all has no dedup key, and a resubmit creates a second
+  // record for it regardless of `upsert`. Same standard applied to record_create/
+  // document_ingest's identical optional-externalId shape.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+  handler: async (args) => {
+    const items = args.items;
+    const atomicity = args.atomicity;
+    try {
+      const body = {
+        items: items.map((item) => ({
+          typeName: item.type,
+          payload: item.fields,
+          externalId: item.externalId,
+          indexMode: item.indexMode,
+          status: item.status,
+          folderId: item.folderId,
+          userId: item.userId,
+          scopes: item.scopes
+        })),
+        atomicity,
+        upsert: args.upsert,
+        allowClear: args.allowClear
+      };
+      const response = await client.records.batchWriteRecords(body, { maxRetries: 0 });
+      log.debug(
+        {
+          tool: "record_batch_write",
+          submitted: items.length,
+          atomicity: atomicity ?? "best_effort",
+          succeeded: response.succeeded,
+          failed: response.failed
+        },
+        "record_batch_write ok"
+      );
+      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+    } catch (err) {
+      log.warn(
+        { tool: "record_batch_write", itemCount: items?.length, err: String(err) },
+        "record_batch_write failed"
+      );
+      return toolError("record_batch_write", err);
+    }
+  }
+});
+var record_batch_write_default = recordBatchWrite;
+
+// src/tools/record_update.ts
+var import_zod7 = require("zod");
+var inputSchema7 = {
+  id: import_zod7.z.string().optional().describe("The Vectros record id to update. Provide this OR externalId+type."),
+  externalId: import_zod7.z.string().optional().describe(
     "Your caller-owned externalId \u2014 an alternative selector to `id` (requires `type`). Updates the record you created under that externalId without a manual record_query lookup first."
   ),
-  type: import_zod6.z.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
-  fields: import_zod6.z.record(import_zod6.z.string(), import_zod6.z.unknown()).describe(
+  type: import_zod7.z.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
+  fields: import_zod7.z.record(import_zod7.z.string(), import_zod7.z.unknown()).describe(
     "Field\u2192value changes DEEP-MERGED into the existing payload: keys you send overwrite (recursing into nested objects), a key set to `null` is deleted, and unspecified fields are preserved."
   ),
-  status: import_zod6.z.string().optional().describe("Set the record lifecycle status (e.g. ARCHIVED) \u2014 archive/workflow without physical deletion."),
-  expectedVersion: import_zod6.z.number().int().optional().describe(
+  status: import_zod7.z.string().optional().describe("Set the record lifecycle status (e.g. ARCHIVED) \u2014 archive/workflow without physical deletion."),
+  expectedVersion: import_zod7.z.number().int().optional().describe(
     "Optimistic concurrency: the version you last read. If the record changed since, the update is refused as a conflict (re-read and retry). Omit for last-write-wins."
   )
 };
@@ -10091,7 +11188,11 @@ var recordUpdate = ({ client, log }) => ({
   name: "record_update",
   title: "Update a record by id or externalId",
   description: "Update a record \u2014 select it by its Vectros `id` OR by your own `externalId` + `type` (the same key you passed to record_create, resolved for you). The provided `fields` are DEEP-MERGED into the existing payload (unspecified fields are preserved; a field set to `null` is deleted). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Use `status` to archive without deleting. Requires the key to allow records:u.",
-  inputSchema: inputSchema6,
+  inputSchema: inputSchema7,
+  // A JSON Merge Patch — overwrites the fields it names, so it can destroy a prior field
+  // value the caller did not mean to lose. Re-applying the same patch converges to the
+  // same state, so it is idempotent.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     const externalId = args.externalId;
@@ -10117,15 +11218,19 @@ var recordUpdate = ({ client, log }) => ({
 var record_update_default = recordUpdate;
 
 // src/tools/record_delete.ts
-var import_zod7 = require("zod");
-var inputSchema7 = {
-  id: import_zod7.z.string().min(1, "id is required").describe("The Vectros record id to delete.")
+var import_zod8 = require("zod");
+var inputSchema8 = {
+  id: import_zod8.z.string().min(1, "id is required").describe("The Vectros record id to delete.")
 };
 var recordDelete = ({ client, log }) => ({
   name: "record_delete",
   title: "Delete a record",
   description: "Permanently delete a record by id (leaves a tombstone). Requires the key to allow records:d \u2014 a key without it gets a permission error. To archive without deleting, use record_update to set status instead.",
-  inputSchema: inputSchema7,
+  inputSchema: inputSchema8,
+  // Deletes (leaves a tombstone server-side, but the record is gone from every normal
+  // read path). Idempotent in the standard REST sense: the end state ("this id no longer
+  // resolves") is the same whether this is the first delete or a repeat of one.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     try {
@@ -10141,49 +11246,72 @@ var recordDelete = ({ client, log }) => ({
 var record_delete_default = recordDelete;
 
 // src/tools/rag_ask.ts
-var import_zod8 = require("zod");
+var import_zod9 = require("zod");
 var SEARCH_MCP_DEFAULT_LIMIT = 5;
 var SEARCH_MCP_MAX_LIMIT = 50;
-var inputSchema8 = {
-  query: import_zod8.z.string().min(1, "query must be non-empty").describe("Question to ground against retrieved content."),
-  instructions: import_zod8.z.string().optional().describe(
+var inputSchema9 = {
+  query: import_zod9.z.string().min(1, "query must be non-empty").describe("Question to ground against retrieved content."),
+  instructions: import_zod9.z.string().optional().describe(
     'System prompt that overrides the default for the generation step \u2014 e.g. "answer only from the provided context, cite sources, be concise". Default: a generic answer-from-context instruction.'
   ),
-  model: import_zod8.z.string().optional().describe(
+  model: import_zod9.z.string().optional().describe(
     "Inference model alias (e.g. claude-haiku-4-5, claude-sonnet-5, claude-opus-4-8). Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
   ),
-  search: import_zod8.z.object({
-    mode: import_zod8.z.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("Retrieval mode. Default HYBRID."),
-    limit: import_zod8.z.number().int().min(1).max(SEARCH_MCP_MAX_LIMIT).optional().describe(
+  search: import_zod9.z.object({
+    mode: import_zod9.z.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("Retrieval mode. Default HYBRID."),
+    limit: import_zod9.z.number().int().min(1).max(SEARCH_MCP_MAX_LIMIT).optional().describe(
       `Passages to retrieve before generating (the grounding-corpus size). Default ${SEARCH_MCP_DEFAULT_LIMIT}; raise up to ${SEARCH_MCP_MAX_LIMIT} (the RAG search API max) for a broader corpus when the extra grounding is worth the larger prompt.`
     ),
     // Retrieval scoping — parity with hybrid_search so an agent can ground the
     // answer on a specific owner / folder / type / metadata subset, not just the
     // whole-tenant corpus.
-    userId: import_zod8.z.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
-    scope: import_zod8.z.string().optional().describe(
-      'Restrict retrieval to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
+    userId: import_zod9.z.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
+    scope: import_zod9.z.string().optional().describe(
+      'Restrict retrieval to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. Mutually exclusive with `scopeFilters` \u2014 use this for ONE dimension.'
     ),
-    folderId: import_zod8.z.string().optional().describe("Restrict retrieval to this exact folder."),
-    rootFolderId: import_zod8.z.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
-    typeName: import_zod8.z.string().optional().describe("Restrict record retrieval to this schema type."),
-    contentTypes: import_zod8.z.array(import_zod8.z.enum(["documents", "records"])).optional().describe('Narrow retrieval to content types. ["documents"] or ["records"]; omit for both.'),
-    filters: import_zod8.z.record(import_zod8.z.unknown()).optional().describe(
+    scopeFilters: import_zod9.z.array(import_zod9.z.string()).min(1, "scopeFilters must name at least one dimension when supplied").optional().describe(
+      'Restrict retrieval to content matching ALL of these scope values \u2014 one per namespace \u2014 for a credential whose access spans more than one ownership dimension. e.g. ["org:<uuid>", "client:<uuid>"] grounds the answer on one specific client WITHIN one specific org, which `scope` alone cannot express. Naming the same namespace twice is rejected. Mutually exclusive with `scope`.'
+    ),
+    folderId: import_zod9.z.string().optional().describe("Restrict retrieval to this exact folder."),
+    rootFolderId: import_zod9.z.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
+    typeName: import_zod9.z.string().optional().describe("Restrict record retrieval to this schema type."),
+    contentTypes: import_zod9.z.array(import_zod9.z.enum(["documents", "records"])).optional().describe('Narrow retrieval to content types. ["documents"] or ["records"]; omit for both.'),
+    filters: import_zod9.z.record(import_zod9.z.unknown()).optional().describe(
       'Field-level metadata filters (AND-combined). Value = scalar (equality), array (OR-set), or operator map ($eq/$ne/$gt/$gte/$lt/$lte, $in/$nin). e.g. {"status":"open"}.'
     ),
-    createdAfter: import_zod8.z.string().optional().describe("Restrict to content created at/after this ISO 8601 UTC timestamp."),
-    createdBefore: import_zod8.z.string().optional().describe("Restrict to content created at/before this ISO 8601 UTC timestamp."),
-    requireComplete: import_zod8.z.boolean().optional().describe("Fail closed (503) on a degraded search backend instead of grounding on partial results. Default false.")
+    createdAfter: import_zod9.z.string().optional().describe(
+      "Restrict retrieval to content CREATED at/after this ISO 8601 UTC timestamp \u2014 the item's own creation time, which does not move when it is re-indexed. An item matched on its FIRST index may be checked against its index time instead, a bounded clock-skew allowance."
+    ),
+    createdBefore: import_zod9.z.string().optional().describe("Same creation-time basis as createdAfter, bounding at/before this ISO 8601 UTC value."),
+    requireComplete: import_zod9.z.boolean().optional().describe("Fail closed (503) on a degraded search backend instead of grounding on partial results. Default false.")
   }).optional().describe("Retrieval params + scoping. Default mode HYBRID, limit " + SEARCH_MCP_DEFAULT_LIMIT + "."),
-  maxTokens: import_zod8.z.number().int().min(1).optional().describe("Max output tokens."),
-  temperature: import_zod8.z.number().min(0).max(1).optional().describe("Sampling temperature (0.0\u20131.0). Default 0.3 \u2014 lower favors deterministic, retrieval-grounded answers.")
+  maxTokens: import_zod9.z.number().int().min(1).optional().describe("Max output tokens."),
+  temperature: import_zod9.z.number().min(0).max(1).optional().describe("Sampling temperature (0.0\u20131.0). Default 0.3 \u2014 lower favors deterministic, retrieval-grounded answers.")
 };
 var ragAsk = ({ client, log }) => ({
   name: "rag_ask",
   title: "RAG ask (corpus-wide)",
-  description: "Ask a question grounded against your tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership, folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
-  inputSchema: inputSchema8,
+  description: "Ask a question grounded against your tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership \u2014 `scope` for one ownership dimension or `scopeFilters` for several at once, e.g. one client within one org \u2014 folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
+  inputSchema: inputSchema9,
+  // NOT a pure read: this call reserves an atomic hold against the caller's prepaid inference
+  // balance before generation starts, then debits it on completion — a real financial side
+  // effect that can trigger a configured auto-recharge against the tenant's card.
+  // `readOnlyHint:true` would let a host
+  // skip a confirmation prompt on a call with real, unbounded-under-retry spend; ordinary reads
+  // that merely meter usage stay `readOnlyHint:true` (hybrid_search has no inference-cost leg),
+  // but a call that can debit a balance and possibly charge a card is a different class. Not
+  // idempotent either: every repeat charges again, and generation is non-deterministic.
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args, extra) => {
+    const rawSearch = args.search ?? {};
+    if (rawSearch.scope !== void 0 && rawSearch.scopeFilters !== void 0) {
+      return toolError(
+        "rag_ask",
+        new Error(
+          "search.scope and search.scopeFilters are mutually exclusive \u2014 pass 'scope' for a single ownership dimension, or 'scopeFilters' for more than one, not both."
+        )
+      );
+    }
     try {
       const searchArg = args.search ?? {};
       const search = {
@@ -10191,6 +11319,7 @@ var ragAsk = ({ client, log }) => ({
         limit: searchArg.limit ?? SEARCH_MCP_DEFAULT_LIMIT,
         userId: searchArg.userId,
         scope: searchArg.scope,
+        scopeFilters: searchArg.scopeFilters,
         folderId: searchArg.folderId,
         rootFolderId: searchArg.rootFolderId,
         typeName: searchArg.typeName,
@@ -10258,20 +11387,29 @@ var ragAsk = ({ client, log }) => ({
 var rag_ask_default = ragAsk;
 
 // src/tools/document_ask.ts
-var import_zod9 = require("zod");
-var inputSchema9 = {
-  documentId: import_zod9.z.string().min(1, "documentId is required").describe("ID of the document to ask against."),
-  prompt: import_zod9.z.string().min(1, "prompt is required").describe("Question to ask about the document."),
-  model: import_zod9.z.string().optional().describe(
+var import_zod10 = require("zod");
+var inputSchema10 = {
+  documentId: import_zod10.z.string().min(1, "documentId is required").describe("ID of the document to ask against."),
+  prompt: import_zod10.z.string().min(1, "prompt is required").describe("Question to ask about the document."),
+  model: import_zod10.z.string().optional().describe(
     "Inference model alias. Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
   ),
-  maxTokens: import_zod9.z.number().int().min(1).optional().describe("Max output tokens.")
+  maxTokens: import_zod10.z.number().int().min(1).optional().describe("Max output tokens.")
 };
 var documentAsk = ({ client, log }) => ({
   name: "document_ask",
   title: "Document ask (single-document)",
   description: "Ask a question against a single indexed document. Returns a grounded answer with the document context that informed it. For documents exceeding the input-token cap, the API returns a structured 413 with `estimatedTokens` and `limitTokens`. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
-  inputSchema: inputSchema9,
+  inputSchema: inputSchema10,
+  // NOT a pure read: this call reserves an atomic hold against the caller's prepaid inference
+  // balance before generation starts, then debits it on completion — a real financial side
+  // effect that can trigger a configured auto-recharge against the tenant's card.
+  // `readOnlyHint:true` would let a host
+  // skip a confirmation prompt on a call with real, unbounded-under-retry spend; ordinary reads
+  // that merely meter usage stay `readOnlyHint:true` (hybrid_search has no inference-cost leg),
+  // but a call that can debit a balance and possibly charge a card is a different class. Not
+  // idempotent either: every repeat charges again, and generation is non-deterministic.
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args, extra) => {
     try {
       const stream = await client.inference.documentAsk({
@@ -10330,18 +11468,18 @@ var documentAsk = ({ client, log }) => ({
 var document_ask_default = documentAsk;
 
 // src/tools/list_schemas.ts
-var import_zod10 = require("zod");
-var inputSchema10 = {
-  userId: import_zod10.z.string().optional().describe(
+var import_zod11 = require("zod");
+var inputSchema11 = {
+  userId: import_zod11.z.string().optional().describe(
     "Filter to schemas visible to a specific user. Optional; default returns all schemas the credential can see."
   ),
-  scope: import_zod10.z.string().optional().describe(
+  scope: import_zod11.z.string().optional().describe(
     'Filter to schemas carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other. Optional; default returns all schemas the credential can see.'
   ),
-  surface: import_zod10.z.enum(["record", "document", "user", "entity"]).optional().describe(
+  surface: import_zod11.z.enum(["record", "document", "user", "entity"]).optional().describe(
     "Filter to schemas bindable to this surface \u2014 e.g. `document` to list only document types, or `record` for record types. Identity entities in any namespace (org/client/one you registered) bind under the single `entity` surface; `user` and `entity` are account-wide. Optional."
   ),
-  recordType: import_zod10.z.string().optional().describe(
+  recordType: import_zod11.z.string().optional().describe(
     'Resolve the single schema for this record type (its natural handle, e.g. "patient") instead of listing \u2014 returns a one-element result, or empty if none. Combine with `surface=user|entity` for an identity schema. Takes precedence over userId. Optional.'
   )
 };
@@ -10349,7 +11487,9 @@ var listSchemas = ({ client, log }) => ({
   name: "list_schemas",
   title: "List record schemas",
   description: 'List the structured-record schema catalog for your tenant. Each schema describes a record type (e.g. "patient", "clinical_note") \u2014 its fields, lookup-indexed fields, and capabilities. Use this to discover what record types exist before calling `record_query`. Filter with `surface` (record/document/user/entity \u2014 e.g. only document types), `recordType` (resolve one schema by its type name), or `userId`/`scope`; default returns everything the credential can see.',
-  inputSchema: inputSchema10,
+  inputSchema: inputSchema11,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const userId = args.userId;
     const scope = args.scope;
@@ -10375,18 +11515,18 @@ var listSchemas = ({ client, log }) => ({
 var list_schemas_default = listSchemas;
 
 // src/tools/document_get.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 var MAX_TEXT_CHARS = 32e3;
-var inputSchema11 = {
-  documentId: import_zod11.z.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
-  externalId: import_zod11.z.string().optional().describe(
+var inputSchema12 = {
+  documentId: import_zod12.z.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
+  externalId: import_zod12.z.string().optional().describe(
     "Your caller-owned externalId \u2014 an alternative selector to `documentId` (requires `type`). Fetches the document you ingested under that externalId without a manual lookup first."
   ),
-  type: import_zod11.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
-  includeText: import_zod11.z.boolean().optional().describe(
+  type: import_zod12.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
+  includeText: import_zod12.z.boolean().optional().describe(
     "If true, fetch and include the document text (capped at ~8K tokens, truncated: true flag if cut). Default false \u2014 metadata only. For larger documents, prefer `document_ask` over dumping text into context."
   ),
-  includeDownloadUrl: import_zod11.z.boolean().optional().describe(
+  includeDownloadUrl: import_zod12.z.boolean().optional().describe(
     "If true, also return a short-lived presigned `downloadUrl` for the original file (file-backed documents only \u2014 the way to retrieve the raw bytes of a document ingested via file mode). Default false. Unavailable for text-only documents \u2014 `downloadAvailable: false` is set instead."
   )
 };
@@ -10403,7 +11543,9 @@ var documentGet = ({ client, log }) => ({
   name: "document_get",
   title: "Get document metadata (and optionally text)",
   description: "Fetch metadata for a single document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). Text is available for every text-ingested document and for file-ingested documents unless they were uploaded with `storeText: false` (extracted text discarded after indexing) \u2014 then `textAvailable: false` is set; the original file is still retrievable via `includeDownloadUrl`. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns the full document metadata, including its lifecycle `status` (ACTIVE, or ARCHIVED when soft-retracted from search \u2014 restorable via document_update) and its processing `indexStatus`. When `indexStatus` is FAILED the response also carries `indexFailure` with a machine-readable `code` telling you whether the content is still findable \u2014 e.g. TEXT_INDEX_FAILED / VECTOR_LIMIT_EXCEEDED (one leg still serves it) vs INDEXING_FAILED (not findable by search at all). Branch on `code`, not on the message.",
-  inputSchema: inputSchema11,
+  inputSchema: inputSchema12,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const documentId = args.documentId;
     const externalId = args.externalId;
@@ -10468,28 +11610,28 @@ var documentGet = ({ client, log }) => ({
 var document_get_default = documentGet;
 
 // src/tools/document_query.ts
-var import_zod12 = require("zod");
+var import_zod13 = require("zod");
 var MCP_DEFAULT_LIMIT3 = 3;
 var MCP_MAX_LIMIT3 = 100;
-var inputSchema12 = {
+var inputSchema13 = {
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
-  field: import_zod12.z.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
-  value: import_zod12.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields too."),
-  from: import_zod12.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Range-enabled, non-sensitive fields only."),
-  to: import_zod12.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
-  prefix: import_zod12.z.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
-  order: import_zod12.z.enum(["asc", "desc"]).optional().describe(
+  field: import_zod13.z.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
+  value: import_zod13.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields too."),
+  from: import_zod13.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Range-enabled, non-sensitive fields only."),
+  to: import_zod13.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
+  prefix: import_zod13.z.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
+  order: import_zod13.z.enum(["asc", "desc"]).optional().describe(
     "Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc` \u2014 use `desc` with a range/prefix lookup to get the most-recent / highest values first (e.g. latest-N). Ignored in list mode."
   ),
-  type: import_zod12.z.string().optional().describe("Lookup mode: the document type (the bound schema's type). Required with `field`."),
+  type: import_zod13.z.string().optional().describe("Lookup mode: the document type (the bound schema's type). Required with `field`."),
   // List-mode args:
-  folderId: import_zod12.z.string().optional().describe("List mode: only documents in this folder (Vectros folder id)."),
-  userId: import_zod12.z.string().optional().describe("List mode: scope to documents owned by this user."),
-  scope: import_zod12.z.string().optional().describe(
+  folderId: import_zod13.z.string().optional().describe("List mode: only documents in this folder (Vectros folder id)."),
+  userId: import_zod13.z.string().optional().describe("List mode: scope to documents owned by this user."),
+  scope: import_zod13.z.string().optional().describe(
     'List mode: filter to documents carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
   ),
-  startFrom: import_zod12.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
-  limit: import_zod12.z.number().int().min(1).max(MCP_MAX_LIMIT3).optional().describe(
+  startFrom: import_zod13.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
+  limit: import_zod13.z.number().int().min(1).max(MCP_MAX_LIMIT3).optional().describe(
     `Max documents per page. Defaults to a low ${MCP_DEFAULT_LIMIT3} to protect the agent context window; raise up to ${MCP_MAX_LIMIT3} (the documents API max) in one call when you can accept the larger payload, or page with \`startFrom\` instead.`
   )
 };
@@ -10497,7 +11639,9 @@ var documentQuery = ({ client, log }) => ({
   name: "document_query",
   title: "Document query (list or lookup)",
   description: "Query document metadata. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields (equality only there); range/prefix need a range-enabled field.\n  \u2022 List: omit `field`; optionally filter by `folderId`/`userId`/`scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` documents (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected. Use document_get for the full text/download URL of one document.",
-  inputSchema: inputSchema12,
+  inputSchema: inputSchema13,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT3;
     const field = args.field;
@@ -10577,29 +11721,29 @@ var documentQuery = ({ client, log }) => ({
 var document_query_default = documentQuery;
 
 // src/tools/document_update.ts
-var import_zod13 = require("zod");
-var inputSchema13 = {
-  documentId: import_zod13.z.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
-  externalId: import_zod13.z.string().optional().describe(
+var import_zod14 = require("zod");
+var inputSchema14 = {
+  documentId: import_zod14.z.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
+  externalId: import_zod14.z.string().optional().describe(
     "Your caller-owned externalId \u2014 an alternative selector to `documentId` (requires `type`). Updates the document you ingested under that externalId without a manual lookup first."
   ),
-  type: import_zod13.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
-  title: import_zod13.z.string().optional().describe("New title. Omit to keep the current title."),
-  fields: import_zod13.z.record(import_zod13.z.string(), import_zod13.z.unknown()).optional().describe(
+  type: import_zod14.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
+  title: import_zod14.z.string().optional().describe("New title. Omit to keep the current title."),
+  fields: import_zod14.z.record(import_zod14.z.string(), import_zod14.z.unknown()).optional().describe(
     "Typed-payload field\u2192value changes DEEP-MERGED into the existing payload (a field set to `null` is deleted; unspecified fields preserved). Omit to leave the payload unchanged."
   ),
-  text: import_zod13.z.string().optional().describe(
+  text: import_zod14.z.string().optional().describe(
     "New raw text body. Supplying it re-ingests the document body and re-queues it for indexing, so the search index reflects the edit (text-ingested documents only \u2014 not file-backed ones). Omit to leave the stored text unchanged. This is the in-place alternative to re-ingesting with upsert:true."
   ),
-  folderId: import_zod13.z.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
-  status: import_zod13.z.enum(["ACTIVE", "ARCHIVED"]).optional().describe(
+  folderId: import_zod14.z.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
+  status: import_zod14.z.enum(["ACTIVE", "ARCHIVED"]).optional().describe(
     "Lifecycle status. `ARCHIVED` soft-retracts the document \u2014 it is pulled from search and recall but kept and recoverable; set it back to `ACTIVE` to re-index and restore it. The way to retire superseded content when the credential has no delete authority. Omit to leave unchanged."
   ),
-  userId: import_zod13.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
-  scopes: import_zod13.z.array(import_zod13.z.string()).optional().describe(
+  userId: import_zod14.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
+  scopes: import_zod14.z.array(import_zod14.z.string()).optional().describe(
     'Reassign scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]) \u2014 the COMPLETE new parent set. `org`/`client` are reserved namespace names, registered like any other. Omit to leave ownership unchanged; `[]` clears it (private to the owning user).'
   ),
-  expectedVersion: import_zod13.z.number().int().optional().describe(
+  expectedVersion: import_zod14.z.number().int().optional().describe(
     "Optimistic concurrency: the version you last read. If the document changed since, the update is refused as a conflict (re-read and retry). Omit for last-write-wins."
   )
 };
@@ -10607,7 +11751,11 @@ var documentUpdate = ({ client, log }) => ({
   name: "document_update",
   title: "Update a document",
   description: 'Update a document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). `fields` are DEEP-MERGED into the existing typed payload (unspecified fields preserved; a field set to `null` is deleted); title/folderId/status/ownership are updated when provided and preserved otherwise. Supply `text` to re-ingest and re-index the document body in place (text documents only). Set `status: "ARCHIVED"` to soft-retract a document (pulled from search, kept and recoverable) and `status: "ACTIVE"` to restore it. Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Requires the key to allow documents:u.',
-  inputSchema: inputSchema13,
+  inputSchema: inputSchema14,
+  // A JSON Merge Patch — overwrites the fields it names, so it can destroy a prior field
+  // value the caller did not mean to lose. Re-applying the same patch converges to the
+  // same state, so it is idempotent.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const documentId = args.documentId;
     const externalId = args.externalId;
@@ -10647,15 +11795,18 @@ var documentUpdate = ({ client, log }) => ({
 var document_update_default = documentUpdate;
 
 // src/tools/document_delete.ts
-var import_zod14 = require("zod");
-var inputSchema14 = {
-  documentId: import_zod14.z.string().min(1, "documentId is required").describe("The Vectros document id to delete.")
+var import_zod15 = require("zod");
+var inputSchema15 = {
+  documentId: import_zod15.z.string().min(1, "documentId is required").describe("The Vectros document id to delete.")
 };
 var documentDelete = ({ client, log }) => ({
   name: "document_delete",
   title: "Delete a document",
   description: 'Permanently delete a document by id (removes it and its indexed content). Requires the key to allow documents:d \u2014 a key without it gets a permission error. To archive without deleting, use document_update to set status: "ARCHIVED" instead (recoverable, and needs no delete authority).',
-  inputSchema: inputSchema14,
+  inputSchema: inputSchema15,
+  // Deletes. Idempotent in the standard REST sense: the end state ("this id no longer
+  // resolves") is the same whether this is the first delete or a repeat of one.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const documentId = args.documentId;
     try {
@@ -10673,18 +11824,18 @@ var documentDelete = ({ client, log }) => ({
 var document_delete_default = documentDelete;
 
 // src/tools/folder_query.ts
-var import_zod15 = require("zod");
+var import_zod16 = require("zod");
 var MCP_DEFAULT_LIMIT4 = 10;
 var MCP_MAX_LIMIT4 = 100;
-var inputSchema15 = {
-  id: import_zod15.z.string().optional().describe("Get mode: fetch this single folder by id."),
-  parentId: import_zod15.z.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
-  userId: import_zod15.z.string().optional().describe("List mode: scope to folders owned by this user."),
-  scope: import_zod15.z.string().optional().describe(
+var inputSchema16 = {
+  id: import_zod16.z.string().optional().describe("Get mode: fetch this single folder by id."),
+  parentId: import_zod16.z.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
+  userId: import_zod16.z.string().optional().describe("List mode: scope to folders owned by this user."),
+  scope: import_zod16.z.string().optional().describe(
     'List mode: filter to folders carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
   ),
-  startFrom: import_zod15.z.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
-  limit: import_zod15.z.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(
+  startFrom: import_zod16.z.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
+  limit: import_zod16.z.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(
     `List mode: max folders per page. Default 10; raise up to ${MCP_MAX_LIMIT4} (the folders API max) in one call when you can accept the larger page, or page with \`startFrom\`.`
   )
 };
@@ -10692,7 +11843,9 @@ var folderQuery = ({ client, log }) => ({
   name: "folder_query",
   title: "Folder query (list or get)",
   description: "Read folders. Two modes:\n  \u2022 Get: pass `id` \u2192 returns the single folder.\n  \u2022 List: omit `id`; pass `parentId` for a folder's direct children (tree navigation) or omit for a flat tenant list. Optionally filter by `userId` or `scope` (`namespace:value`).\nList mode returns `{ data, nextCursor }` (default 10, max 100 per page \u2014 raise it in one call when you can accept the larger page); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page through all folders. Get mode returns the single folder object.",
-  inputSchema: inputSchema15,
+  inputSchema: inputSchema16,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     try {
@@ -10722,22 +11875,34 @@ var folderQuery = ({ client, log }) => ({
 var folder_query_default = folderQuery;
 
 // src/tools/folder_create.ts
-var import_zod16 = require("zod");
-var inputSchema16 = {
-  name: import_zod16.z.string().min(1, "name is required").describe("Folder display name."),
-  description: import_zod16.z.string().optional().describe("Optional description of the folder's purpose."),
-  parentId: import_zod16.z.string().optional().describe("Parent folder id \u2014 places the folder under this parent. Omit for the context default root. Create-only."),
-  slug: import_zod16.z.string().optional().describe("Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. Derived from name when omitted."),
-  userId: import_zod16.z.string().optional().describe("Owning user (Vectros UUID)."),
-  scopes: import_zod16.z.array(import_zod16.z.string()).optional().describe(
+var import_zod17 = require("zod");
+var inputSchema17 = {
+  name: import_zod17.z.string().min(1, "name is required").describe("Folder display name."),
+  description: import_zod17.z.string().optional().describe("Optional description of the folder's purpose."),
+  parentId: import_zod17.z.string().optional().describe("Parent folder id \u2014 places the folder under this parent. Omit for the context default root. Create-only."),
+  slug: import_zod17.z.string().optional().describe(
+    "Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. SUPPLY THIS to make a retry safe \u2014 if omitted, a derived slug is only ever a freshly-proved-free one, so a redelivered call creates a new sibling folder every time rather than matching the first."
+  ),
+  userId: import_zod17.z.string().optional().describe("Owning user (Vectros UUID)."),
+  scopes: import_zod17.z.array(import_zod17.z.string()).optional().describe(
     'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the folder\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE folder owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
   )
 };
 var folderCreate = ({ client, log }) => ({
   name: "folder_create",
   title: "Create a folder",
-  description: "Create a folder to organize documents and records. Pass `parentId` to nest it (create-only \u2014 folders cannot be moved later). Idempotent by `slug` within the parent. Requires the key to allow folders:c (and folders:r to receive the existing folder on a collision).",
-  inputSchema: inputSchema16,
+  description: "Create a folder to organize documents and records. Pass `parentId` to nest it (create-only \u2014 folders cannot be moved later). Idempotent by `slug` within the parent ONLY when you pass `slug` explicitly \u2014 omitting it derives a fresh, always-free slug on every call, so a retry creates a new sibling folder rather than matching the first. Requires the key to allow folders:c (and folders:r to receive the existing folder on a collision).",
+  inputSchema: inputSchema17,
+  // Idempotent ONLY when the caller supplies `slug` explicitly (see the doc comment above): an
+  // omitted slug is derived through a collision-probing suffix loop that returns only a
+  // freshly-proved-free value, so the idempotency check running after that derivation can never
+  // match on the default path. `slug` is optional, so this is annotated for the less-safe default —
+  // the same standard applied to record_create/document_ingest/record_batch_write's identical
+  // optional-dedupe-key shape. (A prior version of this annotation claimed unconditional
+  // idempotency, reasoning that the derived slug made this tool "genuinely structurally different"
+  // from the optional-externalId tools — that reasoning was wrong: the derivation is unconditional,
+  // but it is unconditionally NON-colliding by construction, which is the opposite property.)
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args) => {
     try {
       const folder = await client.folders.createFolder({
@@ -10761,16 +11926,16 @@ var folderCreate = ({ client, log }) => ({
 var folder_create_default = folderCreate;
 
 // src/tools/folder_update.ts
-var import_zod17 = require("zod");
-var inputSchema17 = {
-  id: import_zod17.z.string().min(1, "id is required").describe("The Vectros folder id to update."),
-  name: import_zod17.z.string().optional().describe("New folder name. Omit to keep the current name."),
-  description: import_zod17.z.string().optional().describe("New description. Omit to leave unchanged."),
-  userId: import_zod17.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
-  scopes: import_zod17.z.array(import_zod17.z.string()).optional().describe(
+var import_zod18 = require("zod");
+var inputSchema18 = {
+  id: import_zod18.z.string().min(1, "id is required").describe("The Vectros folder id to update."),
+  name: import_zod18.z.string().optional().describe("New folder name. Omit to keep the current name."),
+  description: import_zod18.z.string().optional().describe("New description. Omit to leave unchanged."),
+  userId: import_zod18.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
+  scopes: import_zod18.z.array(import_zod18.z.string()).optional().describe(
     'Reassign scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]) \u2014 the COMPLETE new parent set. `org`/`client` are reserved namespace names, registered like any other. Omit to leave ownership unchanged; `[]` clears it (private to the owning user).'
   ),
-  expectedVersion: import_zod17.z.number().int().optional().describe(
+  expectedVersion: import_zod18.z.number().int().optional().describe(
     "Optimistic concurrency: the version you last read. If the folder changed since, the update is refused as a conflict (re-read and retry). Omit for last-write-wins."
   )
 };
@@ -10778,7 +11943,11 @@ var folderUpdate = ({ client, log }) => ({
   name: "folder_update",
   title: "Update a folder",
   description: "Update a folder's name / description / ownership by id (RFC-7386 merge \u2014 omitted fields preserved). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Folders cannot be moved (re-parenting is not supported by the API). Requires the key to allow folders:u.",
-  inputSchema: inputSchema17,
+  inputSchema: inputSchema18,
+  // A JSON Merge Patch — overwrites the fields it names, so it can destroy a prior field
+  // value the caller did not mean to lose. Re-applying the same patch converges to the
+  // same state, so it is idempotent.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     const name = args.name;
@@ -10805,15 +11974,18 @@ var folderUpdate = ({ client, log }) => ({
 var folder_update_default = folderUpdate;
 
 // src/tools/folder_delete.ts
-var import_zod18 = require("zod");
-var inputSchema18 = {
-  id: import_zod18.z.string().min(1, "id is required").describe("The Vectros folder id to delete.")
+var import_zod19 = require("zod");
+var inputSchema19 = {
+  id: import_zod19.z.string().min(1, "id is required").describe("The Vectros folder id to delete.")
 };
 var folderDelete = ({ client, log }) => ({
   name: "folder_delete",
   title: "Delete a folder",
-  description: "Permanently delete a folder by id. Requires the key to allow folders:d \u2014 a key without it gets a permission error. Protected folders (e.g. a context root) cannot be deleted.",
-  inputSchema: inputSchema18,
+  description: 'Permanently delete a folder by id. The folder must be EMPTY first \u2014 it must contain no documents, no records, and no sub-folders \u2014 and a non-empty folder is refused, which is the most common way this call fails. Use record_query with this folderId, and document_query, to see what is in it. Clearing it differs by content type: a document can be moved out (document_update with a different folderId) or deleted. A RECORD can also be re-filed into another folder \u2014 the API supports it \u2014 but THIS SERVER does not expose that yet: record_update has no folderId argument, so from here your only option is record_delete (needs records:d). Do NOT read that as "the record cannot be moved" and delete partner data on that basis: if the record should be kept, move it with the Vectros API/SDK directly rather than deleting it here. A sub-folder cannot be re-parented at all, so nested folders have to be emptied and deleted innermost-first. Note the emptiness check counts everything in the folder, INCLUDING items your credential cannot read \u2014 so a refusal you cannot account for from what you can list is expected behaviour, not a bug, and retrying will not clear it. Requires the key to allow folders:d \u2014 a key without it gets a permission error. Protected folders (e.g. a context root) cannot be deleted at all, however empty.',
+  inputSchema: inputSchema19,
+  // Deletes. Idempotent in the standard REST sense: the end state ("this id no longer
+  // resolves") is the same whether this is the first delete or a repeat of one.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     try {
@@ -10829,14 +12001,16 @@ var folderDelete = ({ client, log }) => ({
 var folder_delete_default = folderDelete;
 
 // src/tools/current_identity.ts
-var inputSchema19 = {
+var inputSchema20 = {
   // No args — current_identity describes the current credential.
 };
 var currentIdentity = ({ log, apiKey, environment }) => ({
   name: "current_identity",
   title: "Current identity (tenant + principal scope)",
   description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's verb+ownership reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Note: this does not yet include granted_capabilities (member-lifecycle / forensic-read / context-directory-read / delegate-mint, as of API 0.40.0, joined by delegate-principal-stamp in 0.42.0) \u2014 a separate reach dimension a scope clause can carry that /v1/ping does not report yet, so allowedActions+dataScope may understate a credential's true reach. Also reports mcpServerVersion (this server's own package version) and sdkVersion (the bundled @vectros-ai/sdk version) so a caller can tell what build it's talking to. Use this when the user asks 'what can you do here?', 'what tenant am I in?', or 'what version is this?'. Calls GET /v1/ping under the hood.",
-  inputSchema: inputSchema19,
+  inputSchema: inputSchema20,
+  // A pure read (/v1/ping) — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async () => {
     try {
       const identity = await resolveIdentity({ log, apiKey, environment });
@@ -10852,7 +12026,7 @@ var currentIdentity = ({ log, apiKey, environment }) => ({
 var current_identity_default = currentIdentity;
 
 // src/tools/document_ingest.ts
-var import_zod19 = require("zod");
+var import_zod20 = require("zod");
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
 var IngestPathError = class extends Error {
@@ -10927,37 +12101,37 @@ function inferMimeType(filePath) {
   const ext = (0, import_node_path.extname)(filePath).toLowerCase();
   return EXT_TO_MIME[ext] ?? "application/octet-stream";
 }
-var inputSchema20 = {
-  title: import_zod19.z.string().min(1, "title is required").describe("Human-readable document title \u2014 appears in search results and the UI."),
-  indexMode: import_zod19.z.enum(["HYBRID", "SEMANTIC", "TEXT", "NONE"]).optional().describe(
+var inputSchema21 = {
+  title: import_zod20.z.string().min(1, "title is required").describe("Human-readable document title \u2014 appears in search results and the UI."),
+  indexMode: import_zod20.z.enum(["HYBRID", "SEMANTIC", "TEXT", "NONE"]).optional().describe(
     "Index strategy. HYBRID (BM25 + dense, default; best for general retrieval), SEMANTIC (dense only; concept-driven queries), TEXT (BM25 only; exact-match / keyword), NONE (store-only / archival \u2014 retrievable by id and structured-field lookup but never in search results). Omit to inherit the bound schema's default."
   ),
-  externalId: import_zod19.z.string().optional().describe(
+  externalId: import_zod20.z.string().optional().describe(
     'Stable caller-supplied id. Immutable; unique per type within your context. Re-ingesting with the same externalId returns the existing document (idempotent) instead of creating a duplicate \u2014 use it to make ingests safely retryable and as the key other records reference. Mirrors record_create. Receiving the existing document back is a read of it and needs documents:r in addition to documents:c; a create-only key gets an "already exists" error instead of the document.'
   ),
-  upsert: import_zod19.z.boolean().optional().describe(
+  upsert: import_zod20.z.boolean().optional().describe(
     "When true, re-ingesting an existing externalId OVERWRITES that document and re-indexes the new body (text mode) / re-uploads and re-indexes the new file (file mode), instead of returning the existing one unchanged. This is the curation/re-sync primitive: edit a source, re-ingest with upsert:true, and the search index reflects the new content. Requires the documents:u scope. IMPORTANT: pass the SAME schemaId (and type) you used originally \u2014 externalId is unique WITHIN a type, so omitting schemaId resolves in the untyped namespace and mints a duplicate instead of updating. The response `created` flag confirms which happened (created:true = a new document was minted)."
   ),
-  schemaId: import_zod19.z.string().optional().describe(
+  schemaId: import_zod20.z.string().optional().describe(
     "Bind this document to a record schema. When set, `payload` is validated against the schema and its lookup fields become directly queryable via document_query (records parity). Resolve a schema id from its type via list_schemas. Omit for an untyped document."
   ),
-  payload: import_zod19.z.record(import_zod19.z.string(), import_zod19.z.unknown()).optional().describe(
+  payload: import_zod20.z.record(import_zod20.z.string(), import_zod20.z.unknown()).optional().describe(
     "The document's structured data \u2014 a flat key/value object. With `schemaId`, declared fields are validated and lookup fields indexed; undeclared keys pass through as free-form and are searchable via the hybrid_search `filters` param. Without a schema it is stored as free-form metadata. Every number must fall within the signed 64-bit range \u2014 send a larger whole number as a STRING (stored exactly, exact-match lookup), else the ingest is refused with a 400 naming the field."
   ),
   // Inline text mode (mutually exclusive with filePath):
-  text: import_zod19.z.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
-  storeText: import_zod19.z.boolean().optional().describe(
+  text: import_zod20.z.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
+  storeText: import_zod20.z.boolean().optional().describe(
     "FILE MODE ONLY. Whether the uploaded file's EXTRACTED text is retained after indexing (default true), fixed at ingest. true keeps the extracted text retrievable via document_get(includeText:true) and usable by document_ask; false discards it once indexing completes \u2014 search still works and the original file remains downloadable, but includeText returns textAvailable:false and document_ask is unavailable. NOT accepted with `text`: a text-ingested body is the document itself and is ALWAYS retained, so the backend has no storeText knob on the text path \u2014 passing it with `text` is rejected rather than silently ignored."
   ),
   // File upload mode (mutually exclusive with text; stdio-transport-only):
-  filePath: import_zod19.z.string().min(1).optional().describe(
+  filePath: import_zod20.z.string().min(1).optional().describe(
     "Local filesystem path to upload. Mutually exclusive with text. STDIO TRANSPORT ONLY \u2014 rejected on HTTP transport (remote MCP servers can't read your filesystem; use text mode or call the SDK's uploadDocument directly). Must resolve INSIDE the configured ingest root (VECTROS_MCP_INGEST_ROOT, else the server's working directory); paths that escape it (traversal/absolute/symlink) or match a sensitive pattern are rejected."
   ),
-  fileType: import_zod19.z.string().optional().describe('MIME type of the file (e.g. "application/pdf"). Inferred from filePath extension if omitted.'),
+  fileType: import_zod20.z.string().optional().describe('MIME type of the file (e.g. "application/pdf"). Inferred from filePath extension if omitted.'),
   // Common (both modes):
-  folderId: import_zod19.z.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
-  userId: import_zod19.z.string().optional().describe("Owning user ID. Optional."),
-  scopes: import_zod19.z.array(import_zod19.z.string()).optional().describe(
+  folderId: import_zod20.z.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
+  userId: import_zod20.z.string().optional().describe("Owning user ID. Optional."),
+  scopes: import_zod20.z.array(import_zod20.z.string()).optional().describe(
     "TEXT MODE ONLY. Scope ownership as `namespace:value` entries, at most 2 (e.g. [\"org:<uuid>\", \"group:eng-team\"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the document's COMPLETE scope declaration and values must come from the credential's own identity. An empty array `[]` creates a PRIVATE document owned by the calling user alone. Omit to stamp the credential's full identity \u2014 the default. Rejected with `filePath` (file uploads do not accept a scope declaration): a file-uploaded document is stamped with the credential's full identity."
   )
 };
@@ -10965,7 +12139,17 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   name: "document_ingest",
   title: "Ingest a new document (text body or file upload)",
   description: "Create a new document in your Vectros tenant. Two modes:\n  \u2022 Text mode: pass `text` (string body). Single-call. Use for crawled content, notes, generated text.\n  \u2022 File mode: pass `filePath` (local path on the MCP server's host machine). STDIO-TRANSPORT ONLY \u2014 rejected on HTTP transport. MCP server reads the bytes, requests a presigned upload URL, and PUTs them. Returns when the upload is accepted (indexStatus: PENDING_INDEX); poll with `document_get` until indexStatus is INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate \u2014 requires documents:r in addition to documents:c, since being handed the existing document is a read of it). To UPDATE an existing document instead \u2014 re-index an edited body \u2014 pass `upsert:true` with the same `externalId` (and the same `schemaId`); this is the re-sync primitive for keeping a knowledge base current. Pass `schemaId` + `payload` for a typed, lookup-queryable document (records parity). indexMode defaults to HYBRID for untyped documents (omit to inherit a bound schema's default). storeText is a FILE-MODE knob (default true): false discards the uploaded file's extracted text after indexing (search + file download keep working; text retrieval and document_ask do not). Text-mode bodies are always retained, so storeText is not accepted with `text`.",
-  inputSchema: inputSchema20,
+  inputSchema: inputSchema21,
+  // Creates by default, idempotent ONLY when the caller supplies `externalId` (optional,
+  // per the doc comment above) — re-ingest then returns the existing document rather than
+  // duplicating it. `externalId` is not required, so annotated for the less-safe default
+  // (omit it, and every call creates a new document), same standard applied to
+  // record_create/record_batch_write's identical optional-externalId shape. `upsert:true`
+  // is a further, real, named capability of this tool that OVERWRITES an existing
+  // document's content and re-indexes it — that path is destructive to the prior body, so
+  // this is flagged destructive rather than claiming create-only safety a caller can
+  // invoke past.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
   handler: async (args) => {
     const title = args.title;
     const text = args.text;
@@ -11076,7 +12260,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       }
       const putRes = await fetch(uploadUrl, {
         method: "PUT",
-        headers: { "Content-Type": fileType },
+        headers: { "Content-Type": fileType, ...presignedUploadHeaders(upload) },
         body: bytes
       });
       if (!putRes.ok) {
@@ -11115,31 +12299,38 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   }
 });
 var document_ingest_default = documentIngest;
+function presignedUploadHeaders(response) {
+  if (typeof response !== "object" || response === null) return {};
+  const { requiredHeaderName, requiredHeaderValue } = response;
+  if (typeof requiredHeaderName !== "string" || requiredHeaderName === "") return {};
+  if (typeof requiredHeaderValue !== "string") return {};
+  return { [requiredHeaderName]: requiredHeaderValue };
+}
 
 // src/tools/lookup_principal.ts
-var import_zod20 = require("zod");
+var import_zod21 = require("zod");
 var MCP_DEFAULT_LIMIT5 = 10;
 var MCP_MAX_LIMIT5 = 100;
-var inputSchema21 = {
-  kind: import_zod20.z.string().describe(
+var inputSchema22 = {
+  kind: import_zod21.z.string().describe(
     'Which principal to look up: "user" (the fixed principal surface), or an entity namespace \u2014 "org", "client" (reserved, registered like any other), or a namespace you registered.'
   ),
-  externalId: import_zod20.z.string().optional().describe(
+  externalId: import_zod21.z.string().optional().describe(
     "Resolve mode: your own stable identifier for the principal. Returns the single matching principal (with its Vectros UUID), or an empty array if none. The fastest path to the UUID the ownership filters need. Takes precedence if both this and a `field` lookup are supplied."
   ),
-  contextId: import_zod20.z.string().optional().describe(
+  contextId: import_zod21.z.string().optional().describe(
     "Entity kinds only (not `user`, which is always tenant-wide): the app context to look up entities in, for a namespace registered as context-owned rather than tenant-wide. A context-confined credential's own context is used automatically without this; supply it to name a context explicitly (required for an unconfined/root credential to reach a context-owned namespace). Rejected if the namespace turns out to be tenant-wide."
   ),
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
-  type: import_zod20.z.string().optional().describe('Lookup mode: the identity schema\'s record type (e.g. "person_v1"). Required with `field`.'),
-  field: import_zod20.z.string().optional().describe('Lookup mode: name of the schema-declared lookup field to query by (e.g. "email").'),
-  value: import_zod20.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields."),
-  from: import_zod20.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
-  to: import_zod20.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
-  prefix: import_zod20.z.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
-  order: import_zod20.z.enum(["asc", "desc"]).optional().describe("Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc`."),
-  startFrom: import_zod20.z.string().optional().describe("Lookup mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
-  limit: import_zod20.z.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(
+  type: import_zod21.z.string().optional().describe('Lookup mode: the identity schema\'s record type (e.g. "person_v1"). Required with `field`.'),
+  field: import_zod21.z.string().optional().describe('Lookup mode: name of the schema-declared lookup field to query by (e.g. "email").'),
+  value: import_zod21.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields."),
+  from: import_zod21.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
+  to: import_zod21.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
+  prefix: import_zod21.z.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
+  order: import_zod21.z.enum(["asc", "desc"]).optional().describe("Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc`."),
+  startFrom: import_zod21.z.string().optional().describe("Lookup mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
+  limit: import_zod21.z.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(
     `Max principals per page. Defaults to ${MCP_DEFAULT_LIMIT5}; raise up to ${MCP_MAX_LIMIT5} (the principals API max) in one call when you can accept the payload, or page with \`startFrom\`.`
   )
 };
@@ -11147,7 +12338,9 @@ var lookupPrincipal = ({ client, log }) => ({
   name: "lookup_principal",
   title: "Look up a user identity or a namespaced identity entity",
   description: "Resolve a user, or an identity entity in a namespace (org/client/one you registered). Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) For an entity kind, `contextId` names a specific app context when the namespace is context-owned rather than tenant-wide; a context-confined credential's own context is used automatically without it. Returns a `{ data, nextCursor }` page (default 10, max 100 \u2014 raise it in one call when you can accept the payload); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom`. Read-only \u2014 does not create or modify identities.",
-  inputSchema: inputSchema21,
+  inputSchema: inputSchema22,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const kind = args.kind;
     const isUser = kind === "user";
@@ -11221,17 +12414,19 @@ var lookupPrincipal = ({ client, log }) => ({
 var lookup_principal_default = lookupPrincipal;
 
 // src/tools/version_history.ts
-var import_zod21 = require("zod");
-var inputSchema22 = {
-  resourceType: import_zod21.z.enum(["record", "document"]).describe("Which kind of entity the id refers to: a record or a document."),
-  id: import_zod21.z.string().min(1, "id is required").describe("The Vectros id of the record or document whose history you want."),
-  startFrom: import_zod21.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch older entries.")
+var import_zod22 = require("zod");
+var inputSchema23 = {
+  resourceType: import_zod22.z.enum(["record", "document"]).describe("Which kind of entity the id refers to: a record or a document."),
+  id: import_zod22.z.string().min(1, "id is required").describe("The Vectros id of the record or document whose history you want."),
+  startFrom: import_zod22.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch older entries.")
 };
 var versionHistory = ({ client, log }) => ({
   name: "version_history",
   title: "Version history (record or document)",
   description: "Read the audit/version trail (CREATE/UPDATE/DELETE, with actor, timestamp, and diff) for a single record or document. Pass `resourceType` (record|document) and `id`. Returns `{ data, nextCursor }`; pass `nextCursor` back as `startFrom` to page through older entries. Entities without audit history (untyped) return an empty trail. Read-only.",
-  inputSchema: inputSchema22,
+  inputSchema: inputSchema23,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const resourceType = args.resourceType;
     const id = args.id;
@@ -11260,6 +12455,7 @@ var TOOL_NAMES = [
   "record_get",
   "record_batch_get",
   "record_create",
+  "record_batch_write",
   "record_update",
   "record_delete",
   "rag_ask",
@@ -11286,6 +12482,7 @@ var ALL_TOOL_FACTORIES = {
   record_get: record_get_default,
   record_batch_get: record_batch_get_default,
   record_create: record_create_default,
+  record_batch_write: record_batch_write_default,
   record_update: record_update_default,
   record_delete: record_delete_default,
   rag_ask: rag_ask_default,
@@ -11345,7 +12542,7 @@ var ALL_RESOURCE_FACTORIES = {
 };
 
 // src/zod-to-json-schema.ts
-var import_zod22 = require("zod");
+var import_zod23 = require("zod");
 function zodShapeToJsonSchema(shape) {
   const properties = {};
   const required = [];
@@ -11360,40 +12557,40 @@ function zodShapeToJsonSchema(shape) {
 function zodTypeToJsonSchema(schema) {
   const description = schema.description;
   let current = schema;
-  while (current instanceof import_zod22.z.ZodOptional || current instanceof import_zod22.z.ZodDefault || current instanceof import_zod22.z.ZodNullable) {
+  while (current instanceof import_zod23.z.ZodOptional || current instanceof import_zod23.z.ZodDefault || current instanceof import_zod23.z.ZodNullable) {
     current = current._def.innerType;
   }
   const base = description ? { description } : {};
-  if (current instanceof import_zod22.z.ZodString) {
+  if (current instanceof import_zod23.z.ZodString) {
     return { ...base, type: "string" };
   }
-  if (current instanceof import_zod22.z.ZodNumber) {
+  if (current instanceof import_zod23.z.ZodNumber) {
     return { ...base, type: "number" };
   }
-  if (current instanceof import_zod22.z.ZodBoolean) {
+  if (current instanceof import_zod23.z.ZodBoolean) {
     return { ...base, type: "boolean" };
   }
-  if (current instanceof import_zod22.z.ZodEnum) {
+  if (current instanceof import_zod23.z.ZodEnum) {
     return {
       ...base,
       type: "string",
       enum: current.options
     };
   }
-  if (current instanceof import_zod22.z.ZodArray) {
+  if (current instanceof import_zod23.z.ZodArray) {
     return {
       ...base,
       type: "array",
       items: zodTypeToJsonSchema(current.element)
     };
   }
-  if (current instanceof import_zod22.z.ZodObject) {
+  if (current instanceof import_zod23.z.ZodObject) {
     return {
       ...base,
       ...zodShapeToJsonSchema(current.shape)
     };
   }
-  if (current instanceof import_zod22.z.ZodRecord) {
+  if (current instanceof import_zod23.z.ZodRecord) {
     const valueType = current._def.valueType;
     return {
       ...base,
@@ -11507,7 +12704,12 @@ var VectrosMCPServer = class {
           // MCP client (a well-behaved client rejects an unknown key before the call).
           // The server enforces it too (z.object(...).strict() below) so a raw JSON-RPC
           // call that skips client validation is still rejected — belt and suspenders.
-          inputSchema: { ...zodShapeToJsonSchema(t.inputSchema), additionalProperties: false }
+          inputSchema: { ...zodShapeToJsonSchema(t.inputSchema), additionalProperties: false },
+          // Forwarded from the tool's own definition, not hand-copied here: adding an
+          // annotation to a tool factory does nothing for a client unless it also reaches
+          // this emitted list — the actual `tools/list` response a host reads, not the
+          // source that builds it.
+          ...t.annotations ? { annotations: t.annotations } : {}
         }))
       })
     );
@@ -11517,7 +12719,7 @@ var VectrosMCPServer = class {
       if (!tool) {
         result = toolError(req.params.name ?? "unknown", new Error("No such tool."));
       } else {
-        const parsed = import_zod23.z.object(tool.inputSchema).strict().safeParse(req.params.arguments ?? {});
+        const parsed = import_zod24.z.object(tool.inputSchema).strict().safeParse(req.params.arguments ?? {});
         if (!parsed.success) {
           result = toolError(tool.name, new Error(formatArgError(tool, parsed.error)));
         } else {
@@ -11791,7 +12993,8 @@ async function main() {
   if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.stdout.write(`${formatBuildInfo()}
 `);
-    process.exit(0);
+    process.exitCode = 0;
+    return;
   }
   const log = createLogger2();
   const resolved = await resolveApiKey();
@@ -11800,7 +13003,8 @@ async function main() {
   if (notice) log[notice.level]({ alias: notice.alias }, notice.message);
   if (!apiKey) {
     log.fatal({ reason: resolved.reason }, noKeyMessage(resolved));
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const apiBaseUrl = process.env.VECTROS_API_BASE_URL;
   if (apiBaseUrl !== void 0) {
@@ -11812,7 +13016,8 @@ async function main() {
       } else {
         log.fatal({ err: String(err) }, "invalid VECTROS_API_BASE_URL");
       }
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   }
   let tools;
@@ -11820,7 +13025,8 @@ async function main() {
     tools = parseToolsEnv(process.env.VECTROS_MCP_TOOLS);
   } catch (err) {
     log.fatal({ err: String(err) }, "invalid VECTROS_MCP_TOOLS");
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const skipFlag = (process.env.VECTROS_MCP_SKIP_PING_VALIDATION ?? "").toLowerCase();
   const validateOnStart = !(skipFlag === "1" || skipFlag === "true");
@@ -11839,9 +13045,21 @@ async function main() {
     } else {
       log.fatal({ err: String(err) }, "startup failed");
     }
-    process.exit(1);
+    process.exitCode = 1;
+    return;
   }
   const transport = createStdioTransport();
+  try {
+    await server.connect(transport);
+    log.info(
+      { version: BUILD_INFO.mcpServer, sdk: BUILD_INFO.sdk },
+      "vectros-mcp-server listening on stdio"
+    );
+  } catch (err) {
+    log.fatal({ err: String(err) }, "failed to connect transport");
+    process.exitCode = 2;
+    return;
+  }
   const shutdown = async (signal) => {
     log.info({ signal }, "shutdown requested");
     try {
@@ -11853,16 +13071,6 @@ async function main() {
   };
   process.on("SIGINT", () => void shutdown("SIGINT"));
   process.on("SIGTERM", () => void shutdown("SIGTERM"));
-  try {
-    await server.connect(transport);
-    log.info(
-      { version: BUILD_INFO.mcpServer, sdk: BUILD_INFO.sdk },
-      "vectros-mcp-server listening on stdio"
-    );
-  } catch (err) {
-    log.fatal({ err: String(err) }, "failed to connect transport");
-    process.exit(2);
-  }
 }
 main().catch((err) => {
   process.stderr.write(`fatal: ${err instanceof Error ? err.stack : String(err)}