@vectros-ai/mcp-server 0.10.0 → 0.12.0

package/dist/index.js

@@ -77,6 +77,7 @@ __export2(api_exports, {
   FileUploadRequest: () => FileUploadRequest,
   ForbiddenError: () => ForbiddenError,
   IdentityLookupRequest: () => IdentityLookupRequest,
+  IndexFailure: () => IndexFailure,
   InternalServerError: () => InternalServerError,
   ListEntitiesRequestOrder: () => ListEntitiesRequestOrder,
   ListUsersRequestOrder: () => ListUsersRequestOrder,
@@ -598,6 +599,17 @@ var IdentityLookupRequest;
     Desc: "desc"
   };
 })(IdentityLookupRequest || (IdentityLookupRequest = {}));
+var IndexFailure;
+((IndexFailure2) => {
+  IndexFailure2.Code = {
+    SourceUnavailable: "SOURCE_UNAVAILABLE",
+    TextIndexFailed: "TEXT_INDEX_FAILED",
+    EmbeddingFailed: "EMBEDDING_FAILED",
+    IndexingFailed: "INDEXING_FAILED",
+    VectorLimitExceeded: "VECTOR_LIMIT_EXCEEDED",
+    Internal: "INTERNAL"
+  };
+})(IndexFailure || (IndexFailure = {}));
 var ModelDataVersionResponse;
 ((ModelDataVersionResponse2) => {
   ModelDataVersionResponse2.ChangeType = {
@@ -4114,7 +4126,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user, organization, or client. Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
+   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user or identity entity (in any namespace). Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
    *
    * @param {Vectros.TokenRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4331,7 +4343,7 @@ var ComplianceClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Submits a right-to-erasure request for a single end-subject (a user, client, or organization). 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 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.
    *
    * @param {Vectros.ErasureRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4640,7 +4652,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.
+   * 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.
    *
    * @param {Vectros.IngestDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4966,25 +4978,29 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/documents/{id}");
   }
   /**
-   * Finds documents of a given type by field value. Supported fields: `externalId` (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. Results are paginated: set `limit` for the page size and feed the returned `nextCursor` back as `startFrom` to fetch the next page. The response is a `{data, nextCursor}` envelope. Requires the `documents:r` scope.
+   * Finds documents of a given type by field value. Supported fields: `externalId` (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. `type`'s schema resolves with basedOn-aware shadowing: your own `userId`- or `scope`-owned variant if you have one, otherwise the shared base — for a scoped credential the owner is always your own token identity; `userId`/`scope` here only apply as an explicit owner selector for a root API key. Results are paginated: set `limit` for the page size and feed the returned `nextCursor` back as `startFrom` to fetch the next page. The response is a `{data, nextCursor}` envelope. Requires the `documents:r` scope.
    *
    * @param {Vectros.LookupDocumentsRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   *
    * @example
    *     await client.documents.lookupDocuments({
    *         type: "invoice",
    *         field: "po_number",
    *         value: "PO-1001",
    *         prefix: "PO-2024",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         userId: "550e8400-e29b-41d4-a716-446655440000",
+   *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    *     })
    */
   lookupDocuments(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__lookupDocuments(request, requestOptions));
   }
   async __lookupDocuments(request, requestOptions) {
-    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, order } = request;
+    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, order, userId, scope } = request;
     const _queryParams = {
       type: type_,
       field,
@@ -4994,7 +5010,9 @@ var DocumentsClient = class {
       prefix,
       startFrom,
       limit,
-      order: order != null ? order : void 0
+      order: order != null ? order : void 0,
+      userId,
+      scope
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -5020,11 +5038,16 @@ var DocumentsClient = class {
       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
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_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/documents/lookup");
   }
@@ -5392,7 +5415,7 @@ var FoldersClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/folders");
   }
   /**
-   * Creates a folder to organize your documents and records. If `parentFolderId` is omitted, the folder is created under your context's default root folder. Folder creation is idempotent by (slug + parent): if a folder with the same slug already exists under the same parent, that existing folder 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 folder was returned) tells the two apart. To overwrite an existing folder's mutable fields instead of returning it unchanged, set `?upsert=true` (this also requires the `folders:u` scope). Requires the `folders:c` scope.
+   * Creates a folder to organize your documents and records. If `parentFolderId` is omitted, the folder is created under your context's default root folder. Folder creation is idempotent by (slug + parent): if a folder with the same slug already exists under the same parent, that existing folder 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 folder was returned) tells the two apart. To overwrite an existing folder's mutable fields instead of returning it unchanged, set `?upsert=true` (this also requires the `folders:u` scope). Requires the `folders:c` scope to create. Being returned the existing folder on a collision is a read of that folder's data and additionally requires the `folders:r` scope — a credential holding `folders:c` alone receives a `400` ("already exists") on collision instead of the folder.
    *
    * @param {Vectros.CreateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5850,7 +5873,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/entities/{namespace}");
   }
   /**
-   * Creates a new entity in the given namespace. This call is idempotent on `externalId` within the namespace: if an entity with the same `externalId` already exists, the existing record is returned instead of creating a duplicate (`created: false`, HTTP 200). To overwrite an existing entity's content instead of returning it unchanged, set `?upsert=true` (also requires the `entities:u:<namespace>` scope). The namespace must be entity-backed (`org`/`client`, or registered via `POST /v1/namespaces`). Requires the `entities:c:<namespace>` scope.
+   * Creates a new entity in the given namespace. This call is idempotent on `externalId` within the namespace: if an entity with the same `externalId` already exists, the existing record is returned instead of creating a duplicate (`created: false`, HTTP 200). To overwrite an existing entity's content instead of returning it unchanged, set `?upsert=true` (also requires the `entities:u:<namespace>` scope). The namespace must be entity-backed (`org`/`client`, or registered via `POST /v1/namespaces`). Requires the `entities:c:<namespace>` scope to create. Being returned the existing entity on a collision is a read of that entity's data and additionally requires the `entities:r:<namespace>` scope — a credential holding `entities:c:<namespace>` alone receives a `400` ("already in use") on collision instead of the entity.
    *
    * @param {Vectros.CreateEntityRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6294,7 +6317,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces/{namespace}");
   }
   /**
-   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
+   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`, `specificityRank`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
    *
    * @param {Vectros.UpdateNamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6307,7 +6330,8 @@ var IdentityClient = class {
    *     await client.identity.updateNamespace({
    *         namespace: "team",
    *         body: {
-   *             namespace: "team"
+   *             namespace: "team",
+   *             specificityRank: 1500
    *         }
    *     })
    */
@@ -6472,7 +6496,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces");
   }
   /**
-   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
+   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Also requires `specificityRank`, an explicit, account-unique position in the specificity order used to break recordType schema-resolution ties. Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
    *
    * @param {Vectros.NamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6483,7 +6507,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.registerNamespace({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         specificityRank: 1500
    *     })
    */
   registerNamespace(request, requestOptions) {
@@ -6600,7 +6625,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users");
   }
   /**
-   * Creates a user identity in your account. The operation is idempotent on `externalId`: if a user with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing user was returned) tells the two apart. To overwrite an existing user's mutable fields (email, status, payload, schema binding) instead of returning it unchanged, set `?upsert=true` (this also requires the `users:u` scope). Requires the `users:c` scope.
+   * Creates a user identity in your account. The operation is idempotent on `externalId`: if a user with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing user was returned) tells the two apart. To overwrite an existing user's mutable fields (email, status, payload, schema binding) instead of returning it unchanged, set `?upsert=true` (this also requires the `users:u` scope). Requires the `users:c` scope to create. Being returned the existing user on a collision is a read of that user's data and additionally requires the `users:r` scope — a credential holding `users:c` alone receives a `400` ("already exists") on collision instead of the user.
    *
    * @param {Vectros.CreateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7471,7 +7496,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/records");
   }
   /**
-   * Creates a new record of a given type. The `payload` is validated against that type's schema before the record is stored. Identify the type by sending `typeName`, `schemaId`, or both (they must agree); if you send only `schemaId`, the type is taken from that schema. Optionally supply an `externalId` to make the create idempotent — if a record with the same `externalId` already exists in your context, that existing record 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 record was returned) tells the two apart. To overwrite an existing record's content instead of returning it unchanged, set `?upsert=true` (this also requires the `records:u:<type>` scope). Requires the `records:c:<type>` scope.
+   * Creates a new record of a given type. The `payload` is validated against that type's schema before the record is stored. Identify the type by sending `typeName`, `schemaId`, or both (they must agree); if you send only `schemaId`, the type is taken from that schema. Optionally supply an `externalId` to make the create idempotent — if a record with the same `externalId` already exists in your context, that existing record 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 record was returned) tells the two apart. To overwrite an existing record's content instead of returning it unchanged, set `?upsert=true` (this also requires the `records:u:<type>` scope). Requires the `records:c:<type>` scope to create. Being returned the existing record on a collision is a read of that record's data and additionally requires the `records:r:<type>` scope — a credential holding `records:c:<type>` alone receives a `400` ("already exists") on collision instead of the record.
    *
    * @param {Vectros.CreateRecordRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8062,6 +8087,8 @@ var SchemasClient = class {
    * @param {Vectros.ListSchemasRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   *
    * @example
    *     await client.schemas.listSchemas({
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
@@ -8108,16 +8135,21 @@ var SchemasClient = class {
       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
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_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/schemas");
   }
   /**
-   * Defines a new record type with optional field definitions, validation rules, and lookup indexes. Idempotent by `typeName` within the same ownership scope: re-creating an existing `typeName` returns the existing schema rather than failing. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing schema was returned) tells the two apart. To reconcile an existing schema to the submitted shape instead of returning it unchanged, set `?upsert=true` (this also requires the `schemas:w` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:w` scope.
+   * Defines a new record type with optional field definitions, validation rules, and lookup indexes. Idempotent by `typeName` within the same ownership scope: re-creating an existing `typeName` returns the existing schema rather than failing. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing schema was returned) tells the two apart. To reconcile an existing schema to the submitted shape instead of returning it unchanged, set `?upsert=true` (this also requires the `schemas:u` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:c` scope to create. Being returned the existing schema on a collision is a read of that schema's data and additionally requires the `schemas:r` scope — a credential holding `schemas:c` alone receives a `400` ("already in use") on collision instead of the schema.
    *
    * @param {Vectros.CreateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8261,7 +8293,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:w` 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. Requires the `schemas:u` scope.
    *
    * @param {Vectros.UpdateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8330,7 +8362,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. Requires the `schemas:w` 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. 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.
    *
    * @param {Vectros.DeleteSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8627,8 +8659,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.10.0" : "dev",
-  sdk: true ? "0.35.0" : "dev"
+  mcpServer: true ? "0.12.0" : "dev",
+  sdk: true ? "0.37.0" : "dev"
 };
 
 // src/log.ts
@@ -8832,31 +8864,45 @@ async function consumeStream(stream, onProgress) {
 }
 
 // src/tools/errors.ts
+function asErrorBody(body) {
+  if (body && typeof body === "object") return body;
+  return void 0;
+}
 function toolError(toolName, err, docPointer) {
   let summary = `${toolName} failed`;
   let detail = String(err);
+  let errorCode;
+  let requestId;
   if (err instanceof StreamError) {
     summary = `${toolName} stream error`;
     detail = err.message;
   } else if (err instanceof Error) {
     const e = err;
     detail = e.message;
+    const body = asErrorBody(e.body);
+    if (body) {
+      if (typeof body.message === "string" && body.message.trim().length > 0) detail = body.message;
+      if (typeof body.errorCode === "string" && body.errorCode.length > 0) errorCode = body.errorCode;
+      if (typeof body.requestId === "string" && body.requestId.length > 0) requestId = body.requestId;
+    }
     if (e.statusCode) {
-      summary = `${toolName} failed: HTTP ${e.statusCode}`;
+      summary = `${toolName} failed: HTTP ${e.statusCode}${errorCode ? ` (${errorCode})` : ""}`;
     } else if (e.name && e.name !== "Error") {
       summary = `${toolName} failed: ${e.name}`;
     }
   }
-  const pointer = docPointer ? `
+  const trailer = (errorCode ? `
+errorCode: ${errorCode}` : "") + (requestId ? `
+requestId: ${requestId}` : "") + (docPointer ? `
 
-See: ${docPointer}` : "";
+See: ${docPointer}` : "");
   return {
     isError: true,
     content: [
       {
         type: "text",
         text: `${summary}
-${detail}${pointer}`
+${detail}${trailer}`
       }
     ]
   };
@@ -8933,7 +8979,7 @@ 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 leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:\"OR\".",
+  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).',
   inputSchema,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
@@ -9126,14 +9172,14 @@ var record_query_default = recordQuery;
 var import_zod3 = require("zod");
 
 // src/tools/resolve-external-id.ts
-function validateSelector(sel, entity) {
+function validateSelector(sel, entity, fieldName) {
   const hasId = sel.id !== void 0 && sel.id !== "";
   const hasExt = sel.externalId !== void 0 && sel.externalId !== "";
   if (hasId && hasExt) {
-    return `Provide either id or externalId (not both) to identify the ${entity}.`;
+    return `Provide either ${fieldName} or externalId (not both) to identify the ${entity}.`;
   }
   if (!hasId && !hasExt) {
-    return `Provide id, or externalId + type, to identify the ${entity}.`;
+    return `Provide ${fieldName}, or externalId + type, to identify the ${entity}.`;
   }
   if (hasExt && (sel.type === void 0 || sel.type === "")) {
     return "type is required when selecting by externalId (externalId is unique within a type).";
@@ -9141,7 +9187,7 @@ function validateSelector(sel, entity) {
   return void 0;
 }
 async function resolveRecordIdByExternalId(client, sel) {
-  const err = validateSelector(sel, "record");
+  const err = validateSelector(sel, "record", "id");
   if (err) return { error: err };
   if (sel.id) return { id: sel.id };
   const page = await client.records.lookupRecordsByBody({
@@ -9157,7 +9203,7 @@ async function resolveRecordIdByExternalId(client, sel) {
   return { id: items[0].id };
 }
 async function resolveDocumentIdByExternalId(client, sel) {
-  const err = validateSelector(sel, "document");
+  const err = validateSelector(sel, "document", "documentId");
   if (err) return { error: err };
   if (sel.id) return { id: sel.id };
   const page = await client.documents.lookupDocumentsByBody({
@@ -9185,7 +9231,7 @@ var inputSchema3 = {
 var recordGet = ({ client, log }) => ({
   name: "record_get",
   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.",
+  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,
   handler: async (args) => {
     const id = args.id;
@@ -9223,7 +9269,7 @@ var import_zod4 = require("zod");
 var inputSchema4 = {
   type: import_zod4.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_zod4.z.record(import_zod4.z.string(), import_zod4.z.unknown()).describe(
-    "The record payload \u2014 a JSON object of field\u2192value, validated against the type schema. Call list_schemas to learn required fields, types, and enum values."
+    "The record payload \u2014 a JSON object of field\u2192value, validated against the type schema. Call list_schemas to learn required fields, types, and enum values. Every number must fall within the signed 64-bit range (a value outside it, or with >38 significant digits, is refused with a 400 naming the field) \u2014 send a larger whole number (e.g. a big external id) as a STRING, which stores it exactly and supports exact-match lookup."
   ),
   externalId: import_zod4.z.string().optional().describe(
     "Stable caller-supplied id. Immutable; unique per type. Re-creating with the same externalId returns the existing record (idempotent) \u2014 use it to make creates safely retryable."
@@ -9241,7 +9287,7 @@ var inputSchema4 = {
 var recordCreate = ({ client, log }) => ({
   name: "record_create",
   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.",
+  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: inputSchema4,
   handler: async (args) => {
     const type = args.type;
@@ -9599,7 +9645,7 @@ function isNotAvailable(err) {
 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`.",
+  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: inputSchema10,
   handler: async (args) => {
     const documentId = args.documentId;
@@ -9933,7 +9979,7 @@ var inputSchema15 = {
 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.",
+  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: inputSchema15,
   handler: async (args) => {
     try {
@@ -10032,7 +10078,7 @@ var inputSchema18 = {
 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, and (for scoped keys) allowedActions + dataScope. Use this when the user asks 'what can you do here?' or 'what tenant am I in?'. Calls GET /v1/ping under the hood. Backend may still be rolling out the extended /v1/ping response shape \u2014 until then this tool returns a minimal shape; richer fields appear automatically as backend ships.",
+  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 reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Use this when the user asks 'what can you do here?' or 'what tenant am I in?'. Calls GET /v1/ping under the hood.",
   inputSchema: inputSchema18,
   handler: async () => {
     try {
@@ -10130,7 +10176,7 @@ var inputSchema19 = {
     "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_zod18.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."
+    '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_zod18.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)."
@@ -10139,12 +10185,12 @@ var inputSchema19 = {
     "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_zod18.z.record(import_zod18.z.string(), import_zod18.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."
+    "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_zod18.z.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
   storeText: import_zod18.z.boolean().optional().describe(
-    "Whether the document's text is retained after indexing (default true). Applies to BOTH modes and is fixed at ingest time. Text mode: the ingested body is always retained (this flag is effectively always true \u2014 the body is the document). File mode: true keeps the extracted text retrievable via document_get(includeText:true) and usable by document_ask; false discards the extracted text once indexing completes \u2014 search still works and the original file remains downloadable, but includeText returns textAvailable:false and document_ask is unavailable."
+    "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_zod18.z.string().min(1).optional().describe(
@@ -10161,7 +10207,7 @@ var inputSchema19 = {
 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). 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 defaults to true and is fixed at ingest: in file mode, false discards the extracted text after indexing (search + file download keep working; text retrieval and document_ask do not). Text-mode bodies are always retained.",
+  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: inputSchema19,
   handler: async (args) => {
     const title = args.title;
@@ -10198,6 +10244,14 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
         )
       );
     }
+    if (text && args.storeText !== void 0) {
+      return toolError(
+        "document_ingest",
+        new Error(
+          "`storeText` is not supported with `text` \u2014 a text-ingested body is the document itself and is always retained; the text path has no storeText control. Omit it (text mode), or use `filePath` mode where storeText:false discards the uploaded file's extracted text after indexing."
+        )
+      );
+    }
     const common = {
       folderId: args.folderId,
       payload: args.payload,
@@ -10502,7 +10556,7 @@ var identityResource = ({ log, apiKey, environment }) => ({
   name: "identity",
   uri: "vectros://identity",
   title: "Current identity (tenant + principal scope)",
-  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, environment, principalType, principalKeyId, and (for scoped keys) allowedActions + dataScope. Until backend ships the extended /v1/ping response, returns a minimal derived shape; richer fields appear automatically as backend rolls out.",
+  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }). The /v1/ping backing call ships this extended shape today.",
   mimeType: "application/json",
   read: async () => {
     const identity = await resolveIdentity({ log, apiKey, environment });