@vectros-ai/mcp-server 0.17.2 → 0.18.0

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 
-// ../../node_modules/@vectros-ai/sdk/dist/index.mjs
+// node_modules/@vectros-ai/sdk/dist/index.mjs
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -23,6 +23,7 @@ __export(api_exports, {
   ContentTooLargeError: () => ContentTooLargeError,
   DocumentContextEvent: () => DocumentContextEvent,
   DocumentLookupRequest: () => DocumentLookupRequest,
+  DocumentPatchRequest: () => DocumentPatchRequest,
   DocumentRequest: () => DocumentRequest,
   DocumentResponse: () => DocumentResponse,
   DoneEvent: () => DoneEvent,
@@ -366,6 +367,13 @@ var DocumentLookupRequest;
     Desc: "desc"
   };
 })(DocumentLookupRequest || (DocumentLookupRequest = {}));
+var DocumentPatchRequest;
+((DocumentPatchRequest2) => {
+  DocumentPatchRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
+})(DocumentPatchRequest || (DocumentPatchRequest = {}));
 var FileUploadRequest;
 ((FileUploadRequest2) => {
   FileUploadRequest2.IndexMode = {
@@ -378,6 +386,7 @@ var FileUploadRequest;
 var documents_exports = {};
 __export(documents_exports, {
   DocumentLookupRequest: () => DocumentLookupRequest,
+  DocumentPatchRequest: () => DocumentPatchRequest,
   FileUploadRequest: () => FileUploadRequest,
   LookupDocumentsRequestOrder: () => LookupDocumentsRequestOrder
 });
@@ -3042,6 +3051,7 @@ var AuthClient = class {
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.PaymentRequiredError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -3091,6 +3101,8 @@ var AuthClient = 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 429:
@@ -4936,7 +4948,7 @@ var ComplianceClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Submits a right-to-erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
+   * Submits a right-to-erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure removes exactly the data the subject solely owns across the declared contexts, plus its identity and lookup rows when all contexts are covered. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
    *
    * @param {Vectros.ErasureRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4999,7 +5011,7 @@ var ComplianceClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/erasure-requests");
   }
   /**
-   * Polls an erasure request by id. While the job is still running this returns its status only; once it completes, the response also includes the verifiable completion certificate (which contexts were swept, per-context deletion counts, and reports of dangling references and shared rows that were left intact). Requires a root API key.
+   * Polls an erasure request by id. While the job is still running this returns its status only; once it completes, the response also includes the verifiable completion certificate (which contexts were swept, per-context deletion counts, whether the identity was kept, and reports of dangling references and shared rows left intact). Requires a root API key.
    *
    * @param {Vectros.GetErasureRequestRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5242,7 +5254,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents");
   }
   /**
-   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the `documents:r` scope — a credential holding `documents:c` alone receives a `400` ("already exists") on collision instead of the document.
+   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the `documents:r` scope — a credential holding `documents:c` alone receives a `400` ("already exists") on collision instead of the document. Supplying `externalId` WITHOUT `schemaId` is refused (`400`) unless you also pass `confirmUntyped=true` — externalId uniqueness is scoped per schema, so omitting `schemaId` by mistake would otherwise silently create a separate untyped document instead of targeting the typed one you likely meant.
    *
    * @param {Vectros.IngestDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5262,10 +5274,11 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__ingestDocument(request, requestOptions));
   }
   async __ingestDocument(request, requestOptions) {
-    const { upsert, allowClear, body: _body } = request;
+    const { upsert, allowClear, confirmUntyped, body: _body } = request;
     const _queryParams = {
       upsert,
-      allowClear
+      allowClear,
+      confirmUntyped
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -5500,7 +5513,7 @@ var DocumentsClient = class {
   /**
    * Partially updates a document using an RFC 7386 JSON Merge Patch. The `payload` object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to `null` is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (`title`, `folderId`, `schemaId`, ownership) are set when present and left unchanged when omitted; sending a top-level field as `null` is rejected. Supplying `text` re-ingests the document body (same as PUT). `indexMode`, `externalId`, and `storeText` (text retention is fixed at ingest) are immutable and rejected if present. The merged result is validated against the bound schema. Pass `expectedVersion` for optimistic concurrency (409 on conflict). Requires the `documents:u` scope.
    *
-   * @param {Vectros.PatchDocumentRequest} request
+   * @param {Vectros.DocumentPatchRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
@@ -5511,17 +5524,14 @@ var DocumentsClient = class {
    *
    * @example
    *     await client.documents.patchDocument({
-   *         id: "id",
-   *         body: {
-   *             title: "Patient Intake Form \u2014 Jane Doe"
-   *         }
+   *         id: "id"
    *     })
    */
   patchDocument(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__patchDocument(request, requestOptions));
   }
   async __patchDocument(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, ..._body } = request;
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -5893,7 +5903,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 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.
+   * 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. Supplying `externalId` WITHOUT `schemaId` is refused (`400`) unless you also pass `confirmUntyped=true` — externalId uniqueness is scoped per schema, so omitting `schemaId` by mistake would otherwise silently create a separate untyped document instead of targeting the typed one you likely meant.
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5912,9 +5922,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__uploadDocument(request, requestOptions));
   }
   async __uploadDocument(request, requestOptions) {
-    const { upsert, ..._body } = request;
+    const { upsert, confirmUntyped, ..._body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      confirmUntyped
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -10215,7 +10226,7 @@ import {
   ListToolsRequestSchema,
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { z as z24 } from "zod";
+import { z as z25 } from "zod";
 
 // src/auth.ts
 var KEY_RE = /^(sk|ssk|st)_(live|test)_/;
@@ -10259,8 +10270,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.17.2" : "dev",
-  sdk: true ? "0.45.0" : "dev"
+  mcpServer: true ? "0.18.0" : "dev",
+  sdk: true ? "0.46.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -10555,7 +10566,7 @@ var inputSchema = {
     "Keyword-match precision for the BM25 leg (TEXT/HYBRID modes). OR = any term (broad recall), AND = all terms (higher precision), PHRASE = contiguous phrase. Default: PHRASE (slop 3) in HYBRID, OR in TEXT. (The advanced raw-query COMPLEX mode is intentionally not exposed here.)"
   ),
   limit: z.number().int().min(1).max(MCP_MAX_LIMIT).optional().describe(
-    `Max hits per page. Defaults to a low ${MCP_DEFAULT_LIMIT} to protect the agent context window; raise up to ${MCP_MAX_LIMIT} (the most a single search returns) in one call when you can accept the larger result, or page with \`offset\` instead.`
+    `Max hits per page. Defaults to a low ${MCP_DEFAULT_LIMIT} to protect the agent context window; raise up to ${MCP_MAX_LIMIT} (this tool's ceiling) in one call when you can accept the larger result, or page with \`offset\` instead.`
   ),
   offset: z.number().int().min(0).max(200).optional().describe("Skip the first N hits \u2014 for pagination (0\u2013200)."),
   folderId: z.string().optional().describe("Scope to content in this EXACT folder (Vectros folder id)."),
@@ -11304,52 +11315,61 @@ var recordDelete = ({ client, log }) => ({
 var record_delete_default = recordDelete;
 
 // src/tools/rag_ask.ts
+import { z as z10 } from "zod";
+
+// src/tools/provider-alias.ts
 import { z as z9 } from "zod";
+var providerAliasInput = z9.string().min(1, "providerAlias must be non-empty when supplied").optional().describe(
+  "Route THIS call through your own model provider instead of the platform-hosted default, by the alias of a provider config your account has activated. It works only after your account has set up that provider and signed the platform's risk-acceptance waiver; without both, the platform refuses the call with a 403, which is returned to you as written. A call served by your own provider leaves the platform-hosted Bedrock path, and Vectros's AWS BAA boundary. Omit it (the default) to use the platform-hosted path. When set, `model` names the model on your provider's own id space, and falls back to that provider config's default model when omitted."
+);
+
+// src/tools/rag_ask.ts
 var SEARCH_MCP_DEFAULT_LIMIT = 5;
 var SEARCH_MCP_MAX_LIMIT = 50;
 var inputSchema9 = {
-  query: z9.string().min(1, "query must be non-empty").describe("Question to ground against retrieved content."),
-  instructions: z9.string().optional().describe(
+  query: z10.string().min(1, "query must be non-empty").describe("Question to ground against retrieved content."),
+  instructions: z10.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: z9.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."
+  model: z10.string().optional().describe(
+    "Inference model alias (e.g. claude-haiku-4-5, claude-sonnet-5, claude-opus-5-5). Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach. When `providerAlias` is set, this instead names the model on that provider's own id space."
   ),
-  search: z9.object({
-    mode: z9.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("Retrieval mode. Default HYBRID."),
-    limit: z9.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.`
+  providerAlias: providerAliasInput,
+  search: z10.object({
+    mode: z10.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("Retrieval mode. Default HYBRID."),
+    limit: z10.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} (this tool's ceiling) 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: z9.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
-    scope: z9.string().optional().describe(
+    userId: z10.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
+    scope: z10.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.'
     ),
-    scopeFilters: z9.array(z9.string()).min(1, "scopeFilters must name at least one dimension when supplied").optional().describe(
+    scopeFilters: z10.array(z10.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: z9.string().optional().describe("Restrict retrieval to this exact folder."),
-    rootFolderId: z9.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
-    typeName: z9.string().optional().describe("Restrict record retrieval to this schema type."),
-    contentTypes: z9.array(z9.enum(["documents", "records"])).optional().describe('Narrow retrieval to content types. ["documents"] or ["records"]; omit for both.'),
-    filters: z9.record(z9.unknown()).optional().describe(
+    folderId: z10.string().optional().describe("Restrict retrieval to this exact folder."),
+    rootFolderId: z10.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
+    typeName: z10.string().optional().describe("Restrict record retrieval to this schema type."),
+    contentTypes: z10.array(z10.enum(["documents", "records"])).optional().describe('Narrow retrieval to content types. ["documents"] or ["records"]; omit for both.'),
+    filters: z10.record(z10.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: z9.string().optional().describe(
+    createdAfter: z10.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: z9.string().optional().describe("Same creation-time basis as createdAfter, bounding at/before this ISO 8601 UTC value."),
-    requireComplete: z9.boolean().optional().describe("Fail closed (503) on a degraded search backend instead of grounding on partial results. Default false.")
+    createdBefore: z10.string().optional().describe("Same creation-time basis as createdAfter, bounding at/before this ISO 8601 UTC value."),
+    requireComplete: z10.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: z9.number().int().min(1).optional().describe("Max output tokens."),
-  temperature: z9.number().min(0).max(1).optional().describe("Sampling temperature (0.0\u20131.0). Default 0.3 \u2014 lower favors deterministic, retrieval-grounded answers.")
+  maxTokens: z10.number().int().min(1).optional().describe("Max output tokens."),
+  temperature: z10.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 \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.",
+  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. Calls without `providerAlias` are served by platform-hosted AWS Bedrock. A call that sets `providerAlias` goes to your own model provider, outside Vectros's AWS 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
@@ -11391,6 +11411,7 @@ var ragAsk = ({ client, log }) => ({
         query: args.query,
         instructions: args.instructions,
         model: args.model,
+        providerAlias: args.providerAlias,
         search,
         maxTokens: args.maxTokens,
         temperature: args.temperature
@@ -11445,19 +11466,20 @@ var ragAsk = ({ client, log }) => ({
 var rag_ask_default = ragAsk;
 
 // src/tools/document_ask.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var inputSchema10 = {
-  documentId: z10.string().min(1, "documentId is required").describe("ID of the document to ask against."),
-  prompt: z10.string().min(1, "prompt is required").describe("Question to ask about the document."),
-  model: z10.string().optional().describe(
-    "Inference model alias. Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
+  documentId: z11.string().min(1, "documentId is required").describe("ID of the document to ask against."),
+  prompt: z11.string().min(1, "prompt is required").describe("Question to ask about the document."),
+  model: z11.string().optional().describe(
+    "Inference model alias. Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach. When `providerAlias` is set, this instead names the model on that provider's own id space."
   ),
-  maxTokens: z10.number().int().min(1).optional().describe("Max output tokens.")
+  providerAlias: providerAliasInput,
+  maxTokens: z11.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.",
+  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`. Calls without `providerAlias` are served by platform-hosted AWS Bedrock. A call that sets `providerAlias` goes to your own model provider, outside Vectros's AWS BAA boundary.",
   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
@@ -11474,6 +11496,7 @@ var documentAsk = ({ client, log }) => ({
         id: args.documentId,
         prompt: args.prompt,
         model: args.model,
+        providerAlias: args.providerAlias,
         maxTokens: args.maxTokens
       });
       const progressToken = extra._meta?.progressToken;
@@ -11526,18 +11549,18 @@ var documentAsk = ({ client, log }) => ({
 var document_ask_default = documentAsk;
 
 // src/tools/list_schemas.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var inputSchema11 = {
-  userId: z11.string().optional().describe(
+  userId: z12.string().optional().describe(
     "Filter to schemas visible to a specific user. Optional; default returns all schemas the credential can see."
   ),
-  scope: z11.string().optional().describe(
+  scope: z12.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: z11.enum(["record", "document", "user", "entity"]).optional().describe(
+  surface: z12.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: z11.string().optional().describe(
+  recordType: z12.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.'
   )
 };
@@ -11573,19 +11596,19 @@ var listSchemas = ({ client, log }) => ({
 var list_schemas_default = listSchemas;
 
 // src/tools/document_get.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var MAX_TEXT_CHARS = 32e3;
 var inputSchema12 = {
-  documentId: z12.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
-  externalId: z12.string().optional().describe(
+  documentId: z13.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
+  externalId: z13.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: z12.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
-  includeText: z12.boolean().optional().describe(
+  type: z13.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
+  includeText: z13.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: z12.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."
+  includeDownloadUrl: z13.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. `downloadExpires` is an upper bound, not a guarantee: if the file behind this document is replaced (a document_ingest upsert) after this URL is minted, the URL can stop working before that time. Request a fresh one after any re-ingest rather than reusing one you already hold."
   )
 };
 function truncateText(text) {
@@ -11668,28 +11691,28 @@ var documentGet = ({ client, log }) => ({
 var document_get_default = documentGet;
 
 // src/tools/document_query.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var MCP_DEFAULT_LIMIT3 = 3;
 var MCP_MAX_LIMIT3 = 100;
 var inputSchema13 = {
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
-  field: z13.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
-  value: z13.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields too."),
-  from: z13.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Range-enabled, non-sensitive fields only."),
-  to: z13.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
-  prefix: z13.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
-  order: z13.enum(["asc", "desc"]).optional().describe(
+  field: z14.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
+  value: z14.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields too."),
+  from: z14.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Range-enabled, non-sensitive fields only."),
+  to: z14.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
+  prefix: z14.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
+  order: z14.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: z13.string().optional().describe("Lookup mode: the document type (the bound schema's type). Required with `field`."),
+  type: z14.string().optional().describe("Lookup mode: the document type (the bound schema's type). Required with `field`."),
   // List-mode args:
-  folderId: z13.string().optional().describe("List mode: only documents in this folder (Vectros folder id)."),
-  userId: z13.string().optional().describe("List mode: scope to documents owned by this user."),
-  scope: z13.string().optional().describe(
+  folderId: z14.string().optional().describe("List mode: only documents in this folder (Vectros folder id)."),
+  userId: z14.string().optional().describe("List mode: scope to documents owned by this user."),
+  scope: z14.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: z13.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: z13.number().int().min(1).max(MCP_MAX_LIMIT3).optional().describe(
+  startFrom: z14.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: z14.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.`
   )
 };
@@ -11779,29 +11802,29 @@ var documentQuery = ({ client, log }) => ({
 var document_query_default = documentQuery;
 
 // src/tools/document_update.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var inputSchema14 = {
-  documentId: z14.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
-  externalId: z14.string().optional().describe(
+  documentId: z15.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
+  externalId: z15.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: z14.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
-  title: z14.string().optional().describe("New title. Omit to keep the current title."),
-  fields: z14.record(z14.string(), z14.unknown()).optional().describe(
+  type: z15.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
+  title: z15.string().optional().describe("New title. Omit to keep the current title."),
+  fields: z15.record(z15.string(), z15.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: z14.string().optional().describe(
+  text: z15.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: z14.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
-  status: z14.enum(["ACTIVE", "ARCHIVED"]).optional().describe(
+  folderId: z15.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
+  status: z15.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: z14.string().optional().describe("Reassign the owning user (Vectros UUID)."),
-  scopes: z14.array(z14.string()).optional().describe(
+  userId: z15.string().optional().describe("Reassign the owning user (Vectros UUID)."),
+  scopes: z15.array(z15.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: z14.number().int().optional().describe(
+  expectedVersion: z15.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."
   )
 };
@@ -11829,18 +11852,18 @@ var documentUpdate = ({ client, log }) => ({
     try {
       const resolved = await resolveDocumentIdByExternalId(client, { id: documentId, externalId, type });
       if ("error" in resolved) return toolError("document_update", new Error(resolved.error));
-      const body = {};
-      if (title !== void 0) body.title = title;
-      if (fields !== void 0) body.payload = fields;
-      if (text !== void 0) body.text = text;
-      if (folderId !== void 0) body.folderId = folderId;
-      if (status !== void 0) body.status = status;
-      if (userId !== void 0) body.userId = userId;
-      if (scopes !== void 0) body.scopes = scopes;
-      if (expectedVersion !== void 0) body.expectedVersion = expectedVersion;
+      const patch = {};
+      if (title !== void 0) patch.title = title;
+      if (fields !== void 0) patch.payload = fields;
+      if (text !== void 0) patch.text = text;
+      if (folderId !== void 0) patch.folderId = folderId;
+      if (status !== void 0) patch.status = status;
+      if (userId !== void 0) patch.userId = userId;
+      if (scopes !== void 0) patch.scopes = scopes;
+      if (expectedVersion !== void 0) patch.expectedVersion = expectedVersion;
       const updated = await client.documents.patchDocument({
         id: resolved.id,
-        body
+        ...patch
       });
       log.debug({ tool: "document_update", documentId: resolved.id, externalId }, "document_update ok");
       return { content: [{ type: "text", text: JSON.stringify(updated, null, 2) }] };
@@ -11853,9 +11876,9 @@ var documentUpdate = ({ client, log }) => ({
 var document_update_default = documentUpdate;
 
 // src/tools/document_delete.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var inputSchema15 = {
-  documentId: z15.string().min(1, "documentId is required").describe("The Vectros document id to delete.")
+  documentId: z16.string().min(1, "documentId is required").describe("The Vectros document id to delete.")
 };
 var documentDelete = ({ client, log }) => ({
   name: "document_delete",
@@ -11882,18 +11905,18 @@ var documentDelete = ({ client, log }) => ({
 var document_delete_default = documentDelete;
 
 // src/tools/folder_query.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var MCP_DEFAULT_LIMIT4 = 10;
 var MCP_MAX_LIMIT4 = 100;
 var inputSchema16 = {
-  id: z16.string().optional().describe("Get mode: fetch this single folder by id."),
-  parentId: z16.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
-  userId: z16.string().optional().describe("List mode: scope to folders owned by this user."),
-  scope: z16.string().optional().describe(
+  id: z17.string().optional().describe("Get mode: fetch this single folder by id."),
+  parentId: z17.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
+  userId: z17.string().optional().describe("List mode: scope to folders owned by this user."),
+  scope: z17.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: z16.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
-  limit: z16.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(
+  startFrom: z17.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
+  limit: z17.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\`.`
   )
 };
@@ -11933,16 +11956,16 @@ var folderQuery = ({ client, log }) => ({
 var folder_query_default = folderQuery;
 
 // src/tools/folder_create.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 var inputSchema17 = {
-  name: z17.string().min(1, "name is required").describe("Folder display name."),
-  description: z17.string().optional().describe("Optional description of the folder's purpose."),
-  parentId: z17.string().optional().describe("Parent folder id \u2014 places the folder under this parent. Omit for the context default root. Create-only."),
-  slug: z17.string().optional().describe(
+  name: z18.string().min(1, "name is required").describe("Folder display name."),
+  description: z18.string().optional().describe("Optional description of the folder's purpose."),
+  parentId: z18.string().optional().describe("Parent folder id \u2014 places the folder under this parent. Omit for the context default root. Create-only."),
+  slug: z18.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: z17.string().optional().describe("Owning user (Vectros UUID)."),
-  scopes: z17.array(z17.string()).optional().describe(
+  userId: z18.string().optional().describe("Owning user (Vectros UUID)."),
+  scopes: z18.array(z18.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.'
   )
 };
@@ -11984,16 +12007,16 @@ var folderCreate = ({ client, log }) => ({
 var folder_create_default = folderCreate;
 
 // src/tools/folder_update.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 var inputSchema18 = {
-  id: z18.string().min(1, "id is required").describe("The Vectros folder id to update."),
-  name: z18.string().optional().describe("New folder name. Omit to keep the current name."),
-  description: z18.string().optional().describe("New description. Omit to leave unchanged."),
-  userId: z18.string().optional().describe("Reassign the owning user (Vectros UUID)."),
-  scopes: z18.array(z18.string()).optional().describe(
+  id: z19.string().min(1, "id is required").describe("The Vectros folder id to update."),
+  name: z19.string().optional().describe("New folder name. Omit to keep the current name."),
+  description: z19.string().optional().describe("New description. Omit to leave unchanged."),
+  userId: z19.string().optional().describe("Reassign the owning user (Vectros UUID)."),
+  scopes: z19.array(z19.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: z18.number().int().optional().describe(
+  expectedVersion: z19.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."
   )
 };
@@ -12032,9 +12055,9 @@ var folderUpdate = ({ client, log }) => ({
 var folder_update_default = folderUpdate;
 
 // src/tools/folder_delete.ts
-import { z as z19 } from "zod";
+import { z as z20 } from "zod";
 var inputSchema19 = {
-  id: z19.string().min(1, "id is required").describe("The Vectros folder id to delete.")
+  id: z20.string().min(1, "id is required").describe("The Vectros folder id to delete.")
 };
 var folderDelete = ({ client, log }) => ({
   name: "folder_delete",
@@ -12084,7 +12107,7 @@ var currentIdentity = ({ log, apiKey, environment }) => ({
 var current_identity_default = currentIdentity;
 
 // src/tools/document_ingest.ts
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 import { readFile, realpath } from "fs/promises";
 import { basename, extname, resolve, relative, isAbsolute } from "path";
 var IngestPathError = class extends Error {
@@ -12160,43 +12183,46 @@ function inferMimeType(filePath) {
   return EXT_TO_MIME[ext] ?? "application/octet-stream";
 }
 var inputSchema21 = {
-  title: z20.string().min(1, "title is required").describe("Human-readable document title \u2014 appears in search results and the UI."),
-  indexMode: z20.enum(["HYBRID", "SEMANTIC", "TEXT", "NONE"]).optional().describe(
+  title: z21.string().min(1, "title is required").describe("Human-readable document title \u2014 appears in search results and the UI."),
+  indexMode: z21.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: z20.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.'
+  externalId: z21.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. Pass `schemaId` with it: an externalId with no `schemaId` is refused (400) unless `confirmUntyped` is true.'
+  ),
+  upsert: z21.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. Omitting schemaId is refused (400) unless `confirmUntyped` is true, and with it the call targets the UNTYPED namespace, so it mints or updates an untyped document and never touches the typed one. The response `created` flag confirms which happened (created:true = a new document was minted)."
   ),
-  upsert: z20.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: z21.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 (an untyped document that also carries an `externalId` needs `confirmUntyped`)."
   ),
-  schemaId: z20.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."
+  confirmUntyped: z21.boolean().optional().describe(
+    "Set true to confirm that an UNTYPED document is what you intend when you pass `externalId` without `schemaId`. Without it the platform refuses that combination (400): externalId is unique per schema, so a forgotten `schemaId` would otherwise quietly create a separate untyped copy instead of reaching the typed document you meant. Do not set it just to get past that error \u2014 check that the document really is untyped first. Ignored when `schemaId` is given or `externalId` is omitted."
   ),
-  payload: z20.record(z20.string(), z20.unknown()).optional().describe(
+  payload: z21.record(z21.string(), z21.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: z20.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
-  storeText: z20.boolean().optional().describe(
+  text: z21.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
+  storeText: z21.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: z20.string().min(1).optional().describe(
+  filePath: z21.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: z20.string().optional().describe('MIME type of the file (e.g. "application/pdf"). Inferred from filePath extension if omitted.'),
+  fileType: z21.string().optional().describe('MIME type of the file (e.g. "application/pdf"). Inferred from filePath extension if omitted.'),
   // Common (both modes):
-  folderId: z20.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
-  userId: z20.string().optional().describe("Owning user ID. Optional."),
-  scopes: z20.array(z20.string()).optional().describe(
+  folderId: z21.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
+  userId: z21.string().optional().describe("Owning user ID. Optional."),
+  scopes: z21.array(z21.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."
   )
 };
 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`.",
+  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 `document_get` until indexStatus is INDEXED. EXCEPTION \u2014 re-ingesting file mode against an externalId that already has a document (response `created:false`): the file body is replaced by ANY such re-ingest, whether or not `upsert` was set (`upsert` there only additionally applies `payload`/`title` to the matched document). The document keeps serving the OLD file's bytes until the new one is adopted, and indexStatus already reads INDEXED left over from that old file, so polling it returns immediately without waiting for the new content. Poll `document_get` and watch `fileItemId` instead \u2014 once it differs from the value it held before this call, the new file has been adopted. Re-request any download URL after that: one minted before adoption can stop working even within its stated `downloadExpires`.\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; in FILE MODE a re-ingest against an existing externalId needs documents:u). TEXT MODE: without `upsert`, the existing document's content is genuinely unchanged. FILE MODE: as noted above, a re-ingest against an existing externalId always replaces the file body regardless of `upsert` \u2014 only the `payload`/`title` metadata overwrite is gated by 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). An `externalId` with no `schemaId` is refused (400) unless you also pass `confirmUntyped:true` to confirm that an untyped document is intended. 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: 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
@@ -12214,6 +12240,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
     const filePath = args.filePath;
     const schemaId = args.schemaId;
     const upsert = args.upsert;
+    const confirmUntyped = args.confirmUntyped;
     const indexMode = args.indexMode ?? (schemaId ? void 0 : "HYBRID");
     if (!text && !filePath) {
       return toolError(
@@ -12262,6 +12289,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       if (text) {
         const result = await client.documents.ingestDocument({
           upsert,
+          confirmUntyped,
           body: {
             title,
             text,
@@ -12302,6 +12330,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       const storeTextFile = args.storeText ?? true;
       const upload = await client.documents.uploadDocument({
         upsert,
+        confirmUntyped,
         fileName,
         fileType,
         indexMode,
@@ -12334,6 +12363,8 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
         { tool: "document_ingest", mode: "file", id: docId, fileName, fileType, bytes: bytes.length },
         "document_ingest file ok"
       );
+      const uploadCreated = upload?.created;
+      const note = uploadCreated === false ? "File replaced: this re-ingest matched an existing externalId, which always replaces that document's file body (upsert or not \u2014 upsert only additionally applies payload/title to it). The next document_get call may already show indexStatus: INDEXED \u2014 that is left over from the PREVIOUS file, not confirmation the new one is ready, and the document keeps serving the old file's bytes until adoption completes. Poll document_get(id) and watch fileItemId instead: once it differs from the value it held before this call, the new file has been adopted. Any download URL already held for this document was minted for the old file and can stop working before its stated downloadExpires once adoption happens \u2014 request a fresh one after fileItemId changes." : "File uploaded; indexing is asynchronous. Poll document_get(id) until indexStatus is INDEXED.";
       return {
         content: [
           {
@@ -12342,7 +12373,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
               {
                 ...upload,
                 indexStatus: "PENDING_INDEX",
-                _note: "File uploaded; indexing is asynchronous. Poll document_get(id) until indexStatus is INDEXED."
+                _note: note
               },
               null,
               2
@@ -12366,29 +12397,29 @@ function presignedUploadHeaders(response) {
 }
 
 // src/tools/lookup_principal.ts
-import { z as z21 } from "zod";
+import { z as z22 } from "zod";
 var MCP_DEFAULT_LIMIT5 = 10;
 var MCP_MAX_LIMIT5 = 100;
 var inputSchema22 = {
-  kind: z21.string().describe(
+  kind: z22.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: z21.string().optional().describe(
+  externalId: z22.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: z21.string().optional().describe(
+  contextId: z22.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: z21.string().optional().describe('Lookup mode: the identity schema\'s record type (e.g. "person_v1"). Required with `field`.'),
-  field: z21.string().optional().describe('Lookup mode: name of the schema-declared lookup field to query by (e.g. "email").'),
-  value: z21.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields."),
-  from: z21.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
-  to: z21.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
-  prefix: z21.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
-  order: z21.enum(["asc", "desc"]).optional().describe("Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc`."),
-  startFrom: z21.string().optional().describe("Lookup mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
-  limit: z21.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(
+  type: z22.string().optional().describe('Lookup mode: the identity schema\'s record type (e.g. "person_v1"). Required with `field`.'),
+  field: z22.string().optional().describe('Lookup mode: name of the schema-declared lookup field to query by (e.g. "email").'),
+  value: z22.string().optional().describe("Lookup mode (equality): exact-match value for `field`. Works on sensitive fields."),
+  from: z22.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
+  to: z22.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
+  prefix: z22.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
+  order: z22.enum(["asc", "desc"]).optional().describe("Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc`."),
+  startFrom: z22.string().optional().describe("Lookup mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
+  limit: z22.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\`.`
   )
 };
@@ -12472,11 +12503,11 @@ var lookupPrincipal = ({ client, log }) => ({
 var lookup_principal_default = lookupPrincipal;
 
 // src/tools/version_history.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 var inputSchema23 = {
-  resourceType: z22.enum(["record", "document"]).describe("Which kind of entity the id refers to: a record or a document."),
-  id: z22.string().min(1, "id is required").describe("The Vectros id of the record or document whose history you want."),
-  startFrom: z22.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch older entries.")
+  resourceType: z23.enum(["record", "document"]).describe("Which kind of entity the id refers to: a record or a document."),
+  id: z23.string().min(1, "id is required").describe("The Vectros id of the record or document whose history you want."),
+  startFrom: z23.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch older entries.")
 };
 var versionHistory = ({ client, log }) => ({
   name: "version_history",
@@ -12600,7 +12631,7 @@ var ALL_RESOURCE_FACTORIES = {
 };
 
 // src/zod-to-json-schema.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "zod";
 function zodShapeToJsonSchema(shape) {
   const properties = {};
   const required = [];
@@ -12615,40 +12646,40 @@ function zodShapeToJsonSchema(shape) {
 function zodTypeToJsonSchema(schema) {
   const description = schema.description;
   let current = schema;
-  while (current instanceof z23.ZodOptional || current instanceof z23.ZodDefault || current instanceof z23.ZodNullable) {
+  while (current instanceof z24.ZodOptional || current instanceof z24.ZodDefault || current instanceof z24.ZodNullable) {
     current = current._def.innerType;
   }
   const base = description ? { description } : {};
-  if (current instanceof z23.ZodString) {
+  if (current instanceof z24.ZodString) {
     return { ...base, type: "string" };
   }
-  if (current instanceof z23.ZodNumber) {
+  if (current instanceof z24.ZodNumber) {
     return { ...base, type: "number" };
   }
-  if (current instanceof z23.ZodBoolean) {
+  if (current instanceof z24.ZodBoolean) {
     return { ...base, type: "boolean" };
   }
-  if (current instanceof z23.ZodEnum) {
+  if (current instanceof z24.ZodEnum) {
     return {
       ...base,
       type: "string",
       enum: current.options
     };
   }
-  if (current instanceof z23.ZodArray) {
+  if (current instanceof z24.ZodArray) {
     return {
       ...base,
       type: "array",
       items: zodTypeToJsonSchema(current.element)
     };
   }
-  if (current instanceof z23.ZodObject) {
+  if (current instanceof z24.ZodObject) {
     return {
       ...base,
       ...zodShapeToJsonSchema(current.shape)
     };
   }
-  if (current instanceof z23.ZodRecord) {
+  if (current instanceof z24.ZodRecord) {
     const valueType = current._def.valueType;
     return {
       ...base,
@@ -12777,7 +12808,7 @@ var VectrosMCPServer = class {
       if (!tool) {
         result = toolError(req.params.name ?? "unknown", new Error("No such tool."));
       } else {
-        const parsed = z24.object(tool.inputSchema).strict().safeParse(req.params.arguments ?? {});
+        const parsed = z25.object(tool.inputSchema).strict().safeParse(req.params.arguments ?? {});
         if (!parsed.success) {
           result = toolError(tool.name, new Error(formatArgError(tool, parsed.error)));
         } else {