@vectros-ai/mcp-server 0.5.2 → 0.6.0

package/dist/cli.js

@@ -504,10 +504,18 @@ var DocumentRequest;
     Text: "TEXT",
     None: "NONE"
   };
+  DocumentRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
 })(DocumentRequest || (DocumentRequest = {}));
 var DocumentResponse;
 ((DocumentResponse2) => {
   DocumentResponse2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
+  DocumentResponse2.IndexStatus = {
     PendingUpload: "PENDING_UPLOAD",
     Uploaded: "UPLOADED",
     Extracting: "EXTRACTING",
@@ -2861,7 +2869,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` may set only `orgId` and `clientId`; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
+   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope). You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` may set only `orgId` and `clientId`; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
    *
    * @param {Vectros.CreateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -2883,7 +2891,10 @@ var AuthClient = class {
     return HttpResponsePromise.fromPromise(this.__createAccessProfile(request, requestOptions));
   }
   async __createAccessProfile(request, requestOptions) {
-    const { contextId, body: _body } = request;
+    const { contextId, upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -2898,7 +2909,7 @@ var AuthClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -2993,9 +3004,9 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/app-contexts");
   }
   /**
-   * Creates a new app context. This call is idempotent by `contextId`: if an app context with the same `contextId` already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The reserved `contextId` value `vectros-admin` cannot be created through this endpoint; it is provisioned automatically for your account. Requires the `app-contexts:c` scope.
+   * Creates a new app context. This call is idempotent by `contextId`: if an app context with the same `contextId` already exists, the existing app context is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing context was returned) tells the two apart. To overwrite an existing context's `name`/`description` instead of returning it unchanged, set `?upsert=true` (this also requires the `app-contexts:u` scope). The reserved `contextId` value `vectros-admin` cannot be created through this endpoint; it is provisioned automatically for your account. Requires the `app-contexts:c` scope.
    *
-   * @param {Vectros.AppContextRequest} request
+   * @param {Vectros.CreateAppContextRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
@@ -3004,14 +3015,20 @@ var AuthClient = class {
    *
    * @example
    *     await client.auth.createAppContext({
-   *         contextId: "myapp",
-   *         name: "My Internal App"
+   *         body: {
+   *             contextId: "myapp",
+   *             name: "My Internal App"
+   *         }
    *     })
    */
   createAppContext(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createAppContext(request, requestOptions));
   }
   async __createAppContext(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -3026,9 +3043,9 @@ var AuthClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -3124,7 +3141,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a new role under the given app context. This call is idempotent by `roleId`: if a role with the same `roleId` already exists, the existing role is returned (with status 200) instead of creating a duplicate. If you use a scoped credential, the role's scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
+   * Creates a new role under the given app context. This call is idempotent by `roleId`: if a role with the same `roleId` already exists, the existing role is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing role was returned) tells the two apart. To overwrite an existing role's `name`/`description`/`scopes` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope). If you use a scoped credential, the role's scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
    *
    * @param {Vectros.CreateRoleRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3150,7 +3167,10 @@ var AuthClient = class {
     return HttpResponsePromise.fromPromise(this.__createRole(request, requestOptions));
   }
   async __createRole(request, requestOptions) {
-    const { contextId, body: _body } = request;
+    const { contextId, upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -3165,7 +3185,7 @@ var AuthClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -4649,23 +4669,30 @@ 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. 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.
    *
-   * @param {Vectros.DocumentRequest} request
+   * @param {Vectros.IngestDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.documents.ingestDocument({
-   *         title: "Patient Intake Form \u2014 Jane Doe"
+   *         body: {
+   *             title: "Patient Intake Form \u2014 Jane Doe"
+   *         }
    *     })
    */
   ingestDocument(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__ingestDocument(request, requestOptions));
   }
   async __ingestDocument(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -4680,9 +4707,9 @@ var DocumentsClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -4696,6 +4723,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -4962,7 +4991,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/documents/{id}");
   }
   /**
-   * Finds documents of a given type by a schema-declared lookup field. The document must be bound to a schema (via `schemaId`) that declares the field as a lookup field. 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. 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.
@@ -5257,12 +5286,13 @@ 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. Requires the `documents:c` scope.
+   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata).
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -5275,6 +5305,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__uploadDocument(request, requestOptions));
   }
   async __uploadDocument(request, requestOptions) {
+    const { upsert, ..._body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -5289,9 +5323,9 @@ var DocumentsClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -5305,6 +5339,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -5383,23 +5419,30 @@ 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. 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.
    *
-   * @param {Vectros.FolderRequest} request
+   * @param {Vectros.CreateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.folders.createFolder({
-   *         name: "Patient Records 2024"
+   *         body: {
+   *             name: "Patient Records 2024"
+   *         }
    *     })
    */
   createFolder(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createFolder(request, requestOptions));
   }
   async __createFolder(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -5414,9 +5457,9 @@ var FoldersClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -5430,6 +5473,8 @@ var FoldersClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -5838,23 +5883,30 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/clients");
   }
   /**
-   * Creates a new client identity in your account. This call is idempotent on `externalId`: if a client with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. Requires the `clients:c` scope.
+   * Creates a new client identity in your account. This call is idempotent on `externalId`: if a client 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 client was returned) tells the two apart. To overwrite an existing client's content instead of returning it unchanged, set `?upsert=true` (this also requires the `clients:u` scope). Requires the `clients:c` scope.
    *
-   * @param {Vectros.ClientRequest} request
+   * @param {Vectros.CreateClientRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.createClient({
-   *         externalId: "patient_789"
+   *         body: {
+   *             externalId: "patient_789"
+   *         }
    *     })
    */
   createClient(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createClient(request, requestOptions));
   }
   async __createClient(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -5869,9 +5921,9 @@ var IdentityClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -5885,6 +5937,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -6273,23 +6327,30 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/orgs");
   }
   /**
-   * Creates a new organization in your account. This call is idempotent on `externalId`: if an organization with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. Requires the `orgs:c` scope.
+   * Creates a new organization in your account. This call is idempotent on `externalId`: if an organization 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 organization was returned) tells the two apart. To overwrite an existing organization's content instead of returning it unchanged, set `?upsert=true` (this also requires the `orgs:u` scope). Requires the `orgs:c` scope.
    *
-   * @param {Vectros.OrgRequest} request
+   * @param {Vectros.CreateOrgRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.createOrg({
-   *         externalId: "clinic_001"
+   *         body: {
+   *             externalId: "clinic_001"
+   *         }
    *     })
    */
   createOrg(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createOrg(request, requestOptions));
   }
   async __createOrg(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6304,9 +6365,9 @@ var IdentityClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6320,6 +6381,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -6694,23 +6757,30 @@ 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. 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.
    *
-   * @param {Vectros.UserRequest} request
+   * @param {Vectros.CreateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.createUser({
-   *         externalId: "usr_12345"
+   *         body: {
+   *             externalId: "usr_12345"
+   *         }
    *     })
    */
   createUser(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createUser(request, requestOptions));
   }
   async __createUser(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6725,9 +6795,9 @@ var IdentityClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6741,6 +6811,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -7558,9 +7630,9 @@ 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. 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.
    *
-   * @param {Vectros.RecordRequest} request
+   * @param {Vectros.CreateRecordRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
@@ -7569,19 +7641,25 @@ var RecordsClient = class {
    *
    * @example
    *     await client.records.createRecord({
-   *         typeName: "intake_form",
-   *         schemaId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
-   *         payload: {
-   *             "first_name": "Jane",
-   *             "email": "jane@example.com"
-   *         },
-   *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+   *         body: {
+   *             typeName: "intake_form",
+   *             schemaId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+   *             payload: {
+   *                 "first_name": "Jane",
+   *                 "email": "jane@example.com"
+   *             },
+   *             folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+   *         }
    *     })
    */
   createRecord(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createRecord(request, requestOptions));
   }
   async __createRecord(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -7596,9 +7674,9 @@ var RecordsClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -8194,43 +8272,50 @@ var SchemasClient = class {
     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. 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:w` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:w` scope.
    *
-   * @param {Vectros.SchemaRequest} request
+   * @param {Vectros.CreateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.schemas.createSchema({
-   *         typeName: "intake_form",
-   *         displayName: "Client Intake Form",
-   *         description: "Captures initial client information",
-   *         fields: [{
-   *                 fieldId: "first_name",
-   *                 fieldType: "string",
-   *                 required: true,
-   *                 searchable: true
-   *             }, {
-   *                 fieldId: "email",
-   *                 fieldType: "string",
-   *                 required: true
-   *             }],
-   *         lookupFields: [{
-   *                 fieldName: "email",
-   *                 unique: true
-   *             }],
-   *         capabilities: {
-   *             "auditHistory": true
-   *         },
-   *         allowedSurfaces: ["record"]
+   *         body: {
+   *             typeName: "intake_form",
+   *             displayName: "Client Intake Form",
+   *             description: "Captures initial client information",
+   *             fields: [{
+   *                     fieldId: "first_name",
+   *                     fieldType: "string",
+   *                     required: true,
+   *                     searchable: true
+   *                 }, {
+   *                     fieldId: "email",
+   *                     fieldType: "string",
+   *                     required: true
+   *                 }],
+   *             lookupFields: [{
+   *                     fieldName: "email",
+   *                     unique: true
+   *                 }],
+   *             capabilities: {
+   *                 "auditHistory": true
+   *             },
+   *             allowedSurfaces: ["record"]
+   *         }
    *     })
    */
   createSchema(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__createSchema(request, requestOptions));
   }
   async __createSchema(request, requestOptions) {
+    const { upsert, body: _body } = request;
+    const _queryParams = {
+      upsert
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -8245,9 +8330,9 @@ var SchemasClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -8261,6 +8346,8 @@ var SchemasClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -8695,8 +8782,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.5.2" : "dev",
-  sdk: true ? "0.30.0" : "dev"
+  mcpServer: true ? "0.6.0" : "dev",
+  sdk: true ? "0.32.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -8936,6 +9023,32 @@ ${detail}${pointer}`
 // src/tools/hybrid_search.ts
 var MCP_DEFAULT_LIMIT = 3;
 var MCP_MAX_LIMIT = 10;
+var MCP_RESPONSE_CHAR_BUDGET = 24e3;
+var SNIPPET_MAX_CHARS = 160;
+var INTERNAL_METADATA_KEYS = /* @__PURE__ */ new Set(["tenantId", "owner_id", "model_type", "rootFolderId", "folderId"]);
+function trimMetadata(md) {
+  if (!md || typeof md !== "object" || Array.isArray(md)) return md;
+  const out = {};
+  for (const [k, v] of Object.entries(md)) {
+    if (!INTERNAL_METADATA_KEYS.has(k)) out[k] = v;
+  }
+  return out;
+}
+function reshapeHit(hit, includeContext) {
+  const out = { ...hit };
+  if ("metadata" in out) out.metadata = trimMetadata(out.metadata);
+  const chunk = typeof hit.chunkText === "string" ? hit.chunkText : void 0;
+  const ctx = typeof hit.contextText === "string" ? hit.contextText : void 0;
+  if (includeContext) {
+    if (chunk && ctx && ctx.includes(chunk)) delete out.chunkText;
+  } else {
+    delete out.contextText;
+  }
+  if ((out.snippet == null || out.snippet === "") && chunk) {
+    out.snippet = chunk.length > SNIPPET_MAX_CHARS ? chunk.slice(0, SNIPPET_MAX_CHARS) + "\u2026" : chunk;
+  }
+  return out;
+}
 var inputSchema = {
   query: import_zod.z.string().min(1, "query must be non-empty").describe("Natural-language or keyword query."),
   mode: import_zod.z.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("HYBRID (BM25 + dense, default), TEXT (BM25 only), or SEMANTIC (dense only)."),
@@ -8950,7 +9063,9 @@ var inputSchema = {
   rootFolderId: import_zod.z.string().optional().describe("Scope to content under this folder AND all its descendants (subtree-root folder id)."),
   // Content narrowing.
   contentTypes: import_zod.z.array(import_zod.z.enum(["documents", "records"])).optional().describe('Narrow to content types. ["documents"] or ["records"]; omit for unified (both).'),
-  typeName: import_zod.z.string().optional().describe('Restrict record hits to this schema type (e.g. "patient"). No-op for documents.'),
+  typeName: import_zod.z.string().optional().describe(
+    'Restrict hits to this schema type (e.g. "patient", "runbook"). Applies to BOTH documents and records \u2014 combine with contentTypes to scope within one content type. Untyped content never matches.'
+  ),
   filters: import_zod.z.record(import_zod.z.unknown()).optional().describe(
     'Field-level metadata filters (AND-combined). Value = scalar (equality), array (OR-set), or operator map: $eq/$ne/$gt/$gte/$lt/$lte (scalar) or $in/$nin (array). e.g. {"status":"open"} or {"price":{"$gte":100,"$lte":500}}.'
   ),
@@ -8965,6 +9080,9 @@ var inputSchema = {
   minSimilarity: import_zod.z.number().min(0).max(1).optional().describe("Minimum semantic similarity (0.0\u20131.0); results below are excluded."),
   minTextRelevance: import_zod.z.number().min(0).max(1).optional().describe("Minimum relative keyword (BM25) relevance (0.0\u20131.0); the keyword-leg analogue of minSimilarity."),
   uniqueDocuments: import_zod.z.boolean().optional().describe("When true, return at most one chunk per source document."),
+  includeContext: import_zod.z.boolean().optional().describe(
+    "Include the broader passage (contextText) around each matched chunk. Off by default to keep the result compact \u2014 each hit returns its matched chunkText plus a short snippet. Turn this on only when you need more surrounding context inline; for a full deep read, fetch the source with document_get."
+  ),
   requireComplete: import_zod.z.boolean().optional().describe(
     "When true, fail closed (HTTP 503) if a search backend is unavailable rather than silently returning partial/degraded results. Default false (degrade to the surviving engine; the result still flags degraded)."
   )
@@ -8972,7 +9090,7 @@ var inputSchema = {
 var hybridSearch = ({ client, log }) => ({
   name: "hybrid_search",
   title: "Hybrid search",
-  description: "Search the partner tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to 10 results (default 3) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), 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.",
+  description: `Search the partner tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to 10 results (default 3) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), 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). textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:"OR".`,
   inputSchema,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
@@ -8999,13 +9117,30 @@ var hybridSearch = ({ client, log }) => ({
         uniqueDocuments: args.uniqueDocuments,
         requireComplete: args.requireComplete
       });
+      const hits = Array.isArray(
+        result.results
+      ) ? result.results : [];
+      const includeContext = args.includeContext ?? false;
+      let shaped = hits.map((h) => reshapeHit(h, includeContext));
+      const textLegEmpty = mode !== "SEMANTIC" && hits.length > 0 && hits.every((h) => !(Number(h.textScore) > 0));
+      const envelope = {
+        ...result,
+        results: shaped
+      };
+      if (textLegEmpty) envelope.textLegEmpty = true;
+      let text = JSON.stringify(envelope, null, 2);
+      while (shaped.length > 1 && text.length > MCP_RESPONSE_CHAR_BUDGET) {
+        shaped = shaped.slice(0, -1);
+        envelope.results = shaped;
+        envelope.truncated = true;
+        envelope.returnedResults = shaped.length;
+        text = JSON.stringify(envelope, null, 2);
+      }
       log.debug(
-        { tool: "hybrid_search", mode, limit, returned: result.results?.length },
+        { tool: "hybrid_search", mode, limit, returned: shaped.length, textLegEmpty },
         "hybrid_search ok"
       );
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
+      return { content: [{ type: "text", text }] };
     } catch (err) {
       log.warn({ tool: "hybrid_search", err: String(err) }, "hybrid_search failed");
       return toolError("hybrid_search", err);
@@ -9040,7 +9175,9 @@ var MCP_MAX_LIMIT2 = 10;
 var inputSchema2 = {
   type: import_zod2.z.string().min(1, "type (record type) is required").describe('Record type / schema name (e.g. "patient", "clinical_note").'),
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
-  field: import_zod2.z.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
+  field: import_zod2.z.string().optional().describe(
+    'Lookup mode: name of the lookup-indexed field to query by. `externalId` is always queryable \u2014 e.g. `{type:"control", field:"externalId", value:"ctrl-scoped-key"}` finds the record you created under that externalId. (record_get / record_update also accept externalId directly.)'
+  ),
   value: import_zod2.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`."),
   from: import_zod2.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
   to: import_zod2.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
@@ -9135,19 +9272,77 @@ var record_query_default = recordQuery;
 
 // src/tools/record_get.ts
 var import_zod3 = require("zod");
+
+// src/tools/resolve-external-id.ts
+function validateSelector(sel, entity) {
+  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}.`;
+  }
+  if (!hasId && !hasExt) {
+    return `Provide id, 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).";
+  }
+  return void 0;
+}
+async function resolveRecordIdByExternalId(client, sel) {
+  const err = validateSelector(sel, "record");
+  if (err) return { error: err };
+  if (sel.id) return { id: sel.id };
+  const page = await client.records.lookupRecordsByBody({
+    type: sel.type,
+    field: "externalId",
+    value: sel.externalId,
+    limit: 1
+  });
+  const items = pageItems(page);
+  if (items.length === 0) {
+    return { error: `No record of type '${sel.type}' with externalId '${sel.externalId}'.` };
+  }
+  return { id: items[0].id };
+}
+async function resolveDocumentIdByExternalId(client, sel) {
+  const err = validateSelector(sel, "document");
+  if (err) return { error: err };
+  if (sel.id) return { id: sel.id };
+  const page = await client.documents.lookupDocumentsByBody({
+    type: sel.type,
+    field: "externalId",
+    value: sel.externalId,
+    limit: 1
+  });
+  const items = pageItems(page);
+  if (items.length === 0) {
+    return { error: `No document of type '${sel.type}' with externalId '${sel.externalId}'.` };
+  }
+  return { id: items[0].id };
+}
+
+// src/tools/record_get.ts
 var MAX_PAYLOAD_CHARS = 32e3;
 var inputSchema3 = {
-  id: import_zod3.z.string().min(1, "id is required").describe("The Vectros record id (e.g. from record_query or hybrid_search).")
+  id: import_zod3.z.string().optional().describe("The Vectros record id (e.g. from record_query or hybrid_search). Provide this OR externalId+type."),
+  externalId: import_zod3.z.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `id`. Requires `type` (externalId is unique within a type). Resolves to the record without a manual record_query lookup first."
+  ),
+  type: import_zod3.z.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type).")
 };
 var recordGet = ({ client, log }) => ({
   name: "record_get",
-  title: "Get a record by id",
-  description: "Fetch a single structured record by its Vectros id, including the full payload. Use after record_query / hybrid_search surfaces an id and you need the complete record. Very large payloads are truncated to protect the agent context window.",
+  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.",
   inputSchema: inputSchema3,
   handler: async (args) => {
     const id = args.id;
+    const externalId = args.externalId;
+    const type = args.type;
     try {
-      const record = await client.records.getRecord({ id });
+      const resolved = await resolveRecordIdByExternalId(client, { id, externalId, type });
+      if ("error" in resolved) return toolError("record_get", new Error(resolved.error));
+      const record = await client.records.getRecord({ id: resolved.id });
       const out = { ...record };
       if (record.payload !== void 0) {
         const json = JSON.stringify(record.payload);
@@ -9159,12 +9354,12 @@ var recordGet = ({ client, log }) => ({
         }
       }
       log.debug(
-        { tool: "record_get", id, truncated: out.payloadTruncated === true },
+        { tool: "record_get", id: resolved.id, externalId, truncated: out.payloadTruncated === true },
         "record_get ok"
       );
       return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
     } catch (err) {
-      log.warn({ tool: "record_get", id, err: String(err) }, "record_get failed");
+      log.warn({ tool: "record_get", id, externalId, type, err: String(err) }, "record_get failed");
       return toolError("record_get", err);
     }
   }
@@ -9199,15 +9394,17 @@ var recordCreate = ({ client, log }) => ({
     const type = args.type;
     try {
       const created = await client.records.createRecord({
-        typeName: type,
-        payload: args.fields,
-        externalId: args.externalId,
-        indexMode: args.indexMode,
-        status: args.status,
-        folderId: args.folderId,
-        userId: args.userId,
-        orgId: args.orgId,
-        clientId: args.clientId
+        body: {
+          typeName: type,
+          payload: args.fields,
+          externalId: args.externalId,
+          indexMode: args.indexMode,
+          status: args.status,
+          folderId: args.folderId,
+          userId: args.userId,
+          orgId: args.orgId,
+          clientId: args.clientId
+        }
       });
       log.debug({ tool: "record_create", type, id: created.id }, "record_create ok");
       return { content: [{ type: "text", text: JSON.stringify(created, null, 2) }] };
@@ -9222,7 +9419,11 @@ var record_create_default = recordCreate;
 // src/tools/record_update.ts
 var import_zod5 = require("zod");
 var inputSchema5 = {
-  id: import_zod5.z.string().min(1, "id is required").describe("The Vectros record id to update."),
+  id: import_zod5.z.string().optional().describe("The Vectros record id to update. Provide this OR externalId+type."),
+  externalId: import_zod5.z.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `id` (requires `type`). Updates the record you created under that externalId without a manual record_query lookup first."
+  ),
+  type: import_zod5.z.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   fields: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.unknown()).describe(
     "Field\u2192value changes DEEP-MERGED into the existing payload: keys you send overwrite (recursing into nested objects), a key set to `null` is deleted, and unspecified fields are preserved."
   ),
@@ -9233,23 +9434,27 @@ var inputSchema5 = {
 };
 var recordUpdate = ({ client, log }) => ({
   name: "record_update",
-  title: "Update a record",
-  description: "Update a record by id. The provided `fields` are DEEP-MERGED into the existing payload (unspecified fields are preserved; a field set to `null` is deleted). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Use `status` to archive without deleting. Requires the key to allow records:u.",
+  title: "Update a record by id or externalId",
+  description: "Update a record \u2014 select it by its Vectros `id` OR by your own `externalId` + `type` (the same key you passed to record_create, resolved for you). The provided `fields` are DEEP-MERGED into the existing payload (unspecified fields are preserved; a field set to `null` is deleted). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Use `status` to archive without deleting. Requires the key to allow records:u.",
   inputSchema: inputSchema5,
   handler: async (args) => {
     const id = args.id;
+    const externalId = args.externalId;
+    const type = args.type;
     const fields = args.fields;
     const status = args.status;
     const expectedVersion = args.expectedVersion;
     try {
+      const resolved = await resolveRecordIdByExternalId(client, { id, externalId, type });
+      if ("error" in resolved) return toolError("record_update", new Error(resolved.error));
       const body = { payload: fields };
       if (status !== void 0) body.status = status;
       if (expectedVersion !== void 0) body.expectedVersion = expectedVersion;
-      const updated = await client.records.patchRecord({ id, body });
-      log.debug({ tool: "record_update", id }, "record_update ok");
+      const updated = await client.records.patchRecord({ id: resolved.id, body });
+      log.debug({ tool: "record_update", id: resolved.id, externalId }, "record_update ok");
       return { content: [{ type: "text", text: JSON.stringify(updated, null, 2) }] };
     } catch (err) {
-      log.warn({ tool: "record_update", id, err: String(err) }, "record_update failed");
+      log.warn({ tool: "record_update", id, externalId, type, err: String(err) }, "record_update failed");
       return toolError("record_update", err);
     }
   }
@@ -9516,7 +9721,11 @@ var list_schemas_default = listSchemas;
 var import_zod10 = require("zod");
 var MAX_TEXT_CHARS = 32e3;
 var inputSchema10 = {
-  documentId: import_zod10.z.string().min(1, "documentId is required").describe("The document ID returned by document_ingest or hybrid_search."),
+  documentId: import_zod10.z.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
+  externalId: import_zod10.z.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `documentId` (requires `type`). Fetches the document you ingested under that externalId without a manual lookup first."
+  ),
+  type: import_zod10.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   includeText: import_zod10.z.boolean().optional().describe(
     "If true, fetch and include the document text (capped at ~8K tokens, truncated: true flag if cut). Default false \u2014 metadata only. For larger documents, prefer `document_ask` over dumping text into context."
   ),
@@ -9536,13 +9745,18 @@ function isNotAvailable(err) {
 var documentGet = ({ client, log }) => ({
   name: "document_get",
   title: "Get document metadata (and optionally text)",
-  description: "Fetch metadata for a single document by id. Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). If the document was ingested without `storeText: true`, text is unavailable \u2014 `textAvailable: false` flag is set and the agent should use `document_ask` for question-driven extraction instead. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns full DocumentResponse from the SDK.",
+  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). If the document was ingested without `storeText: true`, text is unavailable \u2014 `textAvailable: false` flag is set and the agent should use `document_ask` for question-driven extraction instead. 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`.",
   inputSchema: inputSchema10,
   handler: async (args) => {
-    const id = args.documentId;
+    const documentId = args.documentId;
+    const externalId = args.externalId;
+    const type = args.type;
     const includeText = args.includeText ?? false;
     const includeDownloadUrl = args.includeDownloadUrl ?? false;
     try {
+      const resolved = await resolveDocumentIdByExternalId(client, { id: documentId, externalId, type });
+      if ("error" in resolved) return toolError("document_get", new Error(resolved.error));
+      const id = resolved.id;
       const doc = await client.documents.getDocument({ id });
       let extra = {};
       if (includeText) {
@@ -9589,7 +9803,7 @@ var documentGet = ({ client, log }) => ({
         ]
       };
     } catch (err) {
-      log.warn({ tool: "document_get", id, err: String(err) }, "document_get failed");
+      log.warn({ tool: "document_get", documentId, externalId, type, err: String(err) }, "document_get failed");
       return toolError("document_get", err);
     }
   }
@@ -9704,13 +9918,23 @@ var document_query_default = documentQuery;
 // src/tools/document_update.ts
 var import_zod12 = require("zod");
 var inputSchema12 = {
-  documentId: import_zod12.z.string().min(1, "documentId is required").describe("The Vectros document id to update."),
+  documentId: import_zod12.z.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
+  externalId: import_zod12.z.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `documentId` (requires `type`). Updates the document you ingested under that externalId without a manual lookup first."
+  ),
+  type: import_zod12.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   title: import_zod12.z.string().optional().describe("New title. Omit to keep the current title."),
   fields: import_zod12.z.record(import_zod12.z.string(), import_zod12.z.unknown()).optional().describe(
     "Typed-payload field\u2192value changes DEEP-MERGED into the existing payload (a field set to `null` is deleted; unspecified fields preserved). Omit to leave the payload unchanged."
   ),
+  text: import_zod12.z.string().optional().describe(
+    "New raw text body. Supplying it re-ingests the document body and re-queues it for indexing, so the search index reflects the edit (text-ingested documents only \u2014 not file-backed ones). Omit to leave the stored text unchanged. This is the in-place alternative to re-ingesting with upsert:true."
+  ),
   folderId: import_zod12.z.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
   storeText: import_zod12.z.boolean().optional().describe("Whether the raw text is stored + retrievable."),
+  status: import_zod12.z.enum(["ACTIVE", "ARCHIVED"]).optional().describe(
+    "Lifecycle status. `ARCHIVED` soft-retracts the document \u2014 it is pulled from search and recall but kept and recoverable; set it back to `ACTIVE` to re-index and restore it. The way to retire superseded content when the credential has no delete authority. Omit to leave unchanged."
+  ),
   userId: import_zod12.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
   orgId: import_zod12.z.string().optional().describe("Reassign the owning org (Vectros UUID)."),
   clientId: import_zod12.z.string().optional().describe("Reassign the associated client (Vectros UUID)."),
@@ -9721,33 +9945,41 @@ var inputSchema12 = {
 var documentUpdate = ({ client, log }) => ({
   name: "document_update",
   title: "Update a document",
-  description: "Update a document by id. `fields` are DEEP-MERGED into the existing typed payload (unspecified fields preserved; a field set to `null` is deleted); title/folderId/ownership are updated when provided and preserved otherwise. Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Requires the key to allow documents:u.",
+  description: 'Update a document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). `fields` are DEEP-MERGED into the existing typed payload (unspecified fields preserved; a field set to `null` is deleted); title/folderId/status/ownership are updated when provided and preserved otherwise. Supply `text` to re-ingest and re-index the document body in place (text documents only). Set `status: "ARCHIVED"` to soft-retract a document (pulled from search, kept and recoverable) and `status: "ACTIVE"` to restore it. Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Requires the key to allow documents:u.',
   inputSchema: inputSchema12,
   handler: async (args) => {
     const documentId = args.documentId;
+    const externalId = args.externalId;
+    const type = args.type;
     const title = args.title;
     const fields = args.fields;
+    const text = args.text;
     const folderId = args.folderId;
     const storeText = args.storeText;
+    const status = args.status;
     const userId = args.userId;
     const orgId = args.orgId;
     const clientId = args.clientId;
     const expectedVersion = args.expectedVersion;
     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 (storeText !== void 0) body.storeText = storeText;
+      if (status !== void 0) body.status = status;
       if (userId !== void 0) body.userId = userId;
       if (orgId !== void 0) body.orgId = orgId;
       if (clientId !== void 0) body.clientId = clientId;
       if (expectedVersion !== void 0) body.expectedVersion = expectedVersion;
       const updated = await client.documents.patchDocument({
-        id: documentId,
+        id: resolved.id,
         body
       });
-      log.debug({ tool: "document_update", documentId }, "document_update ok");
+      log.debug({ tool: "document_update", documentId: resolved.id, externalId }, "document_update ok");
       return { content: [{ type: "text", text: JSON.stringify(updated, null, 2) }] };
     } catch (err) {
       log.warn({ tool: "document_update", documentId, err: String(err) }, "document_update failed");
@@ -9765,7 +9997,7 @@ var inputSchema13 = {
 var documentDelete = ({ client, log }) => ({
   name: "document_delete",
   title: "Delete a document",
-  description: "Permanently delete a document by id (removes it and its indexed content). Requires the key to allow documents:d \u2014 a key without it gets a permission error.",
+  description: 'Permanently delete a document by id (removes it and its indexed content). Requires the key to allow documents:d \u2014 a key without it gets a permission error. To archive without deleting, use document_update to set status: "ARCHIVED" instead (recoverable, and needs no delete authority).',
   inputSchema: inputSchema13,
   handler: async (args) => {
     const documentId = args.documentId;
@@ -9849,13 +10081,15 @@ var folderCreate = ({ client, log }) => ({
   handler: async (args) => {
     try {
       const folder = await client.folders.createFolder({
-        name: args.name,
-        description: args.description,
-        parentFolderId: args.parentId,
-        slug: args.slug,
-        userId: args.userId,
-        orgId: args.orgId,
-        clientId: args.clientId
+        body: {
+          name: args.name,
+          description: args.description,
+          parentFolderId: args.parentId,
+          slug: args.slug,
+          userId: args.userId,
+          orgId: args.orgId,
+          clientId: args.clientId
+        }
       });
       log.debug({ tool: "folder_create", id: folder.id, name: folder.name }, "folder_create ok");
       return { content: [{ type: "text", text: JSON.stringify(folder, null, 2) }] };
@@ -10043,6 +10277,9 @@ var inputSchema19 = {
   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."
   ),
+  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)."
+  ),
   schemaId: import_zod18.z.string().optional().describe(
     "Bind this document to a record schema. When set, `payload` is validated against the schema and its lookup fields become directly queryable via document_query (records parity). Resolve a schema id from its type via list_schemas. Omit for an untyped document."
   ),
@@ -10068,13 +10305,14 @@ 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 the partner 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 (status: PENDING_INDEX); poll with `document_get` to confirm INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate). 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 (set false to skip storing the text body).",
+  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 (set false to skip storing the text body).",
   inputSchema: inputSchema19,
   handler: async (args) => {
     const title = args.title;
     const text = args.text;
     const filePath = args.filePath;
     const schemaId = args.schemaId;
+    const upsert = args.upsert;
     const indexMode = args.indexMode ?? (schemaId ? void 0 : "HYBRID");
     if (!text && !filePath) {
       return toolError(
@@ -10109,11 +10347,14 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       if (text) {
         const storeText = args.storeText ?? true;
         const result = await client.documents.ingestDocument({
-          title,
-          text,
-          indexMode,
-          storeText,
-          ...common
+          upsert,
+          body: {
+            title,
+            text,
+            indexMode,
+            storeText,
+            ...common
+          }
         });
         log.debug(
           { tool: "document_ingest", mode: "text", id: result?.id, indexMode },
@@ -10143,6 +10384,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       const fileName = (0, import_node_path.basename)(safePath);
       const fileType = args.fileType ?? inferMimeType(safePath);
       const upload = await client.documents.uploadDocument({
+        upsert,
         fileName,
         fileType,
         indexMode,
@@ -10181,8 +10423,8 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
             text: JSON.stringify(
               {
                 ...upload,
-                status: "PENDING_INDEX",
-                _note: "File uploaded; indexing is asynchronous. Poll document_get(id) until status is INDEXED."
+                indexStatus: "PENDING_INDEX",
+                _note: "File uploaded; indexing is asynchronous. Poll document_get(id) until indexStatus is INDEXED."
               },
               null,
               2
@@ -10479,6 +10721,14 @@ function zodTypeToJsonSchema(schema) {
 
 // src/server.ts
 var DEFAULT_ENVIRONMENT = "https://api.vectros.ai";
+function formatArgError(tool, error) {
+  const unknownKeys = error.issues.filter((i) => i.code === "unrecognized_keys").flatMap((i) => i.keys);
+  if (unknownKeys.length > 0) {
+    const valid = Object.keys(tool.inputSchema).join(", ");
+    return `Unknown argument(s): ${unknownKeys.join(", ")}. Valid arguments for ${tool.name}: ${valid}. Pass only these \u2014 an unrecognized argument is rejected, not ignored.`;
+  }
+  return `Invalid arguments: ${error.message}`;
+}
 var VectrosMCPServer = class {
   server;
   log;
@@ -10568,7 +10818,11 @@ var VectrosMCPServer = class {
           name: t.name,
           title: t.title,
           description: t.description,
-          inputSchema: zodShapeToJsonSchema(t.inputSchema)
+          // additionalProperties:false advertises strict argument validation to the
+          // MCP client (a well-behaved client rejects an unknown key before the call).
+          // The server enforces it too (z.object(...).strict() below) so a raw JSON-RPC
+          // call that skips client validation is still rejected — belt and suspenders.
+          inputSchema: { ...zodShapeToJsonSchema(t.inputSchema), additionalProperties: false }
         }))
       })
     );
@@ -10578,9 +10832,9 @@ var VectrosMCPServer = class {
       if (!tool) {
         result = toolError(req.params.name ?? "unknown", new Error("No such tool."));
       } else {
-        const parsed = import_zod22.z.object(tool.inputSchema).safeParse(req.params.arguments ?? {});
+        const parsed = import_zod22.z.object(tool.inputSchema).strict().safeParse(req.params.arguments ?? {});
         if (!parsed.success) {
-          result = toolError(tool.name, new Error(`Invalid arguments: ${parsed.error.message}`));
+          result = toolError(tool.name, new Error(formatArgError(tool, parsed.error)));
         } else {
           try {
             result = await tool.handler(