@vectros-ai/cli 0.5.1 → 0.6.4

package/dist/cli.mjs

@@ -2514,6 +2514,7 @@ var AuthClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.createScopedKey({
@@ -2561,6 +2562,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -2637,6 +2640,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.revokeScopedKey({
@@ -2677,6 +2681,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -2832,7 +2838,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.
@@ -2840,6 +2846,7 @@ var AuthClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.createAccessProfile({
@@ -2853,7 +2860,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,
@@ -2868,7 +2878,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,
@@ -2888,6 +2898,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -2961,24 +2973,31 @@ 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}
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @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,
@@ -2993,9 +3012,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,
@@ -3011,6 +3030,8 @@ var AuthClient = class {
           throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3089,7 +3110,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.
@@ -3097,6 +3118,7 @@ var AuthClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.createRole({
@@ -3114,7 +3136,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,
@@ -3129,7 +3154,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,
@@ -3149,6 +3174,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3236,6 +3263,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.updateAccessProfile({
@@ -3283,6 +3311,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3306,6 +3336,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.deleteAccessProfile({
@@ -3347,6 +3378,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3428,6 +3461,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.updateAppContext({
@@ -3475,6 +3509,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3494,6 +3530,7 @@ var AuthClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.deleteAppContext({
@@ -3539,6 +3576,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3626,6 +3665,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.updateRole({
@@ -3677,6 +3717,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -3700,6 +3742,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.deleteRole({
@@ -3741,6 +3784,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4072,6 +4117,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.mintToken({
@@ -4124,6 +4170,8 @@ var AuthClient = class {
           throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4144,6 +4192,7 @@ var AuthClient = class {
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.createInvite({
@@ -4192,6 +4241,8 @@ var AuthClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4211,6 +4262,7 @@ var AuthClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.auth.resendInvite({
@@ -4257,6 +4309,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4279,6 +4333,7 @@ var ComplianceClient = class {
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    * @throws {@link Vectros.NotImplementedError}
    *
    * @example
@@ -4320,6 +4375,8 @@ var ComplianceClient = class {
       switch (_response.error.statusCode) {
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         case 501:
           throw new NotImplementedError(_response.error.body, _response.rawResponse);
         default:
@@ -4400,6 +4457,7 @@ var ComplianceClient = class {
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    * @throws {@link Vectros.NotImplementedError}
    *
    * @example
@@ -4439,6 +4497,8 @@ var ComplianceClient = class {
       switch (_response.error.statusCode) {
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         case 501:
           throw new NotImplementedError(_response.error.body, _response.rawResponse);
         default:
@@ -4578,22 +4638,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,
@@ -4608,9 +4676,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,
@@ -4624,6 +4692,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4698,6 +4770,7 @@ var DocumentsClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.documents.updateDocument({
@@ -4746,6 +4819,8 @@ var DocumentsClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4763,6 +4838,7 @@ var DocumentsClient = class {
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.documents.deleteDocument({
@@ -4801,6 +4877,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4820,6 +4898,7 @@ var DocumentsClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.documents.patchDocument({
@@ -4868,6 +4947,8 @@ var DocumentsClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -4879,7 +4960,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.
@@ -4948,6 +5029,7 @@ var DocumentsClient = class {
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.documents.lookupDocumentsByBody({
@@ -4989,6 +5071,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5171,12 +5255,14 @@ 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; `?upsert=true` requires the `documents:u` scope). Requires the `documents:c` scope.
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.documents.uploadDocument({
@@ -5188,6 +5274,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,
@@ -5202,9 +5292,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,
@@ -5218,6 +5308,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5294,22 +5388,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,
@@ -5324,9 +5426,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,
@@ -5340,6 +5442,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5412,6 +5518,7 @@ var FoldersClient = class {
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.folders.updateFolder({
@@ -5456,6 +5563,8 @@ var FoldersClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5474,6 +5583,7 @@ var FoldersClient = class {
    *
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.folders.deleteFolder({
@@ -5514,6 +5624,8 @@ var FoldersClient = class {
           throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5533,6 +5645,7 @@ var FoldersClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.folders.patchFolder({
@@ -5581,6 +5694,8 @@ var FoldersClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5737,22 +5852,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,
@@ -5767,9 +5890,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,
@@ -5783,6 +5906,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5855,6 +5982,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.updateClient({
@@ -5899,6 +6027,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5916,6 +6046,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.deleteClient({
@@ -5954,6 +6085,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -5971,6 +6104,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.lookupClients({
@@ -6012,6 +6146,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6160,22 +6296,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,
@@ -6190,9 +6334,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,
@@ -6206,6 +6350,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6278,6 +6426,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.updateOrg({
@@ -6322,6 +6471,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6339,6 +6490,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.deleteOrg({
@@ -6377,6 +6529,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6394,6 +6548,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.lookupOrgs({
@@ -6435,6 +6590,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6569,22 +6726,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,
@@ -6599,9 +6764,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,
@@ -6615,6 +6780,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6687,6 +6856,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.updateUser({
@@ -6731,6 +6901,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6748,6 +6920,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.deleteUser({
@@ -6786,6 +6959,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -6803,6 +6978,7 @@ var IdentityClient = class {
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.identity.lookupUsers({
@@ -6844,6 +7020,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -7180,6 +7358,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    * @throws {@link Vectros.NotImplementedError}
    *
    * @example
@@ -7219,6 +7398,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         case 501:
           throw new NotImplementedError(_response.error.body, _response.rawResponse);
         default:
@@ -7238,6 +7419,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    * @throws {@link Vectros.NotImplementedError}
    *
    * @example
@@ -7277,6 +7459,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         case 501:
           throw new NotImplementedError(_response.error.body, _response.rawResponse);
         default:
@@ -7296,6 +7480,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    * @throws {@link Vectros.NotImplementedError}
    *
    * @example
@@ -7335,6 +7520,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         case 501:
           throw new NotImplementedError(_response.error.body, _response.rawResponse);
         default:
@@ -7412,29 +7599,36 @@ 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}
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @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,
@@ -7449,9 +7643,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,
@@ -7467,6 +7661,8 @@ var RecordsClient = class {
           throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -7541,6 +7737,7 @@ var RecordsClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.records.updateRecord({
@@ -7587,6 +7784,8 @@ var RecordsClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -7604,6 +7803,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.records.deleteRecord({
@@ -7642,6 +7842,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -7661,6 +7863,7 @@ var RecordsClient = class {
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.records.patchRecord({
@@ -7712,6 +7915,8 @@ var RecordsClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -7800,6 +8005,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.records.lookupRecordsByBody({
@@ -7841,6 +8047,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -8033,42 +8241,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,
@@ -8083,9 +8299,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,
@@ -8099,6 +8315,10 @@ 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:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -8172,6 +8392,7 @@ var SchemasClient = class {
    *
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.schemas.updateSchema({
@@ -8220,6 +8441,8 @@ var SchemasClient = class {
           throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -8238,6 +8461,7 @@ var SchemasClient = class {
    *
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.schemas.deleteSchema({
@@ -8278,6 +8502,8 @@ var SchemasClient = class {
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
           throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -8359,6 +8585,7 @@ var SearchClient = class {
    *
    * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
    *     await client.search.content({
@@ -8401,6 +8628,8 @@ var SearchClient = class {
           throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
           throw new VectrosError({
             statusCode: _response.error.statusCode,
@@ -8638,11 +8867,36 @@ var BlueprintServicePrincipalSchema = z.object({
   externalId: z.string().min(1),
   displayName: z.string().min(1)
 }).strict();
-var BlueprintSeedRecordSchema = z.object({
+var SeedCommonShape = {
+  /** The schema typeName this seed instantiates (should match a declared schema). */
   typeName: z.string().min(1),
-  externalId: z.string().min(1),
+  /**
+   * Stable, caller-supplied id — the loader's idempotency key AND the value other
+   * seeds resolve a `reference` against (across surfaces: a record seed may
+   * reference a document seed by its externalId, and vice versa).
+   */
+  externalId: z.string().min(1)
+};
+var RecordSeedSchema = z.object({
+  surface: z.literal("record"),
+  ...SeedCommonShape,
+  /** The record payload, validated against the bound schema. */
   fields: z.record(z.unknown())
 }).strict();
+var DocumentSeedSchema = z.object({
+  surface: z.literal("document"),
+  ...SeedCommonShape,
+  /** Human-readable document title — REQUIRED by the text-ingest path. */
+  title: z.string().min(1),
+  /** Raw text content to ingest + index — REQUIRED and non-empty (the platform rejects a blank ingest). */
+  text: z.string().min(1),
+  /** Optional structured payload bound to the schema (the document's `fields`). */
+  fields: z.record(z.unknown()).optional()
+}).strict();
+var BlueprintSeedRecordSchema = z.discriminatedUnion("surface", [
+  RecordSeedSchema,
+  DocumentSeedSchema
+]);
 var SELF_TOKEN_RE = /\$\{\{\s*self\.[A-Za-z_]\w*\s*\}\}/;
 function lintSelfTokenPlacement(value, ctx) {
   const walk = (node, path4, inRoleDataScope) => {
@@ -8698,6 +8952,23 @@ function lintIdentityRefsDeclared(value, ctx) {
   };
   walk(value, []);
 }
+function lintSeedSurfaces(value, ctx) {
+  const bp = value;
+  if (!Array.isArray(bp.seed)) return;
+  const byType = new Map((bp.schemas ?? []).map((s) => [s.typeName, s]));
+  bp.seed.forEach((seed, i) => {
+    const schema = byType.get(seed.typeName);
+    if (!schema) return;
+    const allowed = schema.allowedSurfaces ?? ["record"];
+    if (!allowed.includes(seed.surface ?? "record")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["seed", i, "surface"],
+        message: `seed '${seed.externalId}' uses surface '${seed.surface ?? "record"}', but schema '${seed.typeName}' allows only [${allowed.join(", ")}]`
+      });
+    }
+  });
+}
 var BlueprintSchema = z.object({
   /** Stable blueprint id (the `--blueprint <name>` selector + idempotency key). */
   name: z.string().min(1),
@@ -8720,6 +8991,7 @@ var BlueprintSchema = z.object({
 }).strict().superRefine((bp, ctx) => {
   lintSelfTokenPlacement(bp, ctx);
   lintIdentityRefsDeclared(bp, ctx);
+  lintSeedSurfaces(bp, ctx);
 });
 function formatIssuePath(path4) {
   let out = "";
@@ -9117,6 +9389,7 @@ var taskManagement = {
   },
   seed: [
     {
+      surface: "record",
       typeName: "task",
       externalId: "seed-welcome",
       fields: {
@@ -9344,6 +9617,7 @@ var codingAgentMemory = {
       // Seeded FIRST so the convention below resolves its reference to it — the
       // loader creates seeds in array order, and a reference target must exist when
       // the referencing record is written.
+      surface: "record",
       typeName: "decision",
       externalId: "seed-use-vectros-for-memory",
       fields: {
@@ -9359,6 +9633,7 @@ var codingAgentMemory = {
       // Demonstrates a live typed link at bootstrap: this convention references the
       // decision above by its externalId, so "open the decision behind this rule"
       // works the moment the blueprint is applied.
+      surface: "record",
       typeName: "convention",
       externalId: "seed-record-the-why",
       fields: {
@@ -9373,41 +9648,722 @@ var codingAgentMemory = {
   ]
 };
 var coding_agent_memory_default = codingAgentMemory;
-var secondBrain = {
-  name: "second-brain",
+var agenticSdlc = {
+  name: "agentic-sdlc",
   version: "1.0.0",
-  description: "A personal knowledge base \u2014 capture notes, ideas, and links, then ask them anything.",
-  contextId: "second-brain",
-  contextName: "Second Brain",
+  description: "A whole-SDLC system of record for an AI development team \u2014 decisions, designs, references, runbooks, post-mortems (as documents) plus controls, conventions, gotchas, and a glossary (as records), cross-linked and recalled by meaning.",
+  contextId: "agentic-sdlc",
+  contextName: "Agentic SDLC Knowledge Base",
   schemas: [
+    // ============================ DOCUMENTS ============================
+    // Content-dominant: the markdown body is the artifact; fields are metadata.
+    // Each binds the `document` surface and is ingested via `document_ingest`.
     {
-      typeName: "note",
-      displayName: "Note",
+      // An architecture/product DECISION (an ADR). The body is the prose —
+      // Context / Decision / Consequences — and is what `rag_ask` answers over;
+      // the fields below are filter/sort metadata + the supersede chain. The
+      // anchor of the graph: most other types link back to a decision.
+      typeName: "decision",
+      displayName: "Decision (ADR)",
       indexMode: "HYBRID",
-      // keyword on title + semantic on body — recall by meaning
+      allowedSurfaces: ["document"],
+      // A document carries an INTRINSIC title (the ingest title) + body; the schema
+      // declares only the metadata BEYOND those. (No typed `title` field — that
+      // would duplicate the document's own title.)
       fields: [
         {
-          fieldId: "title",
+          fieldId: "summary",
           fieldType: "string",
-          required: true,
           searchable: true,
-          validation: { minLength: 1, maxLength: 200 },
-          renderHints: { label: "Title", widget: "text", order: 1, section: "Note", displayField: true }
+          description: "A one-paragraph abstract of the decision. The full reasoning is the document body.",
+          renderHints: { label: "Summary", widget: "textarea", order: 2 }
         },
         {
-          fieldId: "body",
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["proposed", "accepted", "superseded", "deprecated"],
+          renderHints: { label: "Status", widget: "select", order: 3 }
+        },
+        {
+          fieldId: "area",
           fieldType: "string",
-          searchable: true,
-          description: "The note itself \u2014 the RAG-able body you ask questions against.",
-          validation: { maxLength: 2e4 },
-          renderHints: { label: "Body", widget: "textarea", order: 2, section: "Note" }
+          filterable: true,
+          description: 'Subsystem the decision applies to (e.g. "search", "auth", "billing").',
+          renderHints: { label: "Area", widget: "text", order: 4 }
         },
         {
           fieldId: "tags",
           fieldType: "array",
           filterable: true,
-          description: 'Freeform string labels for filtering (e.g. "idea", "reading", "work").',
-          renderHints: { label: "Tags", order: 3, section: "Organize" }
+          description: 'Freeform labels (e.g. "security", "schema"). Search-side filter.',
+          renderHints: { label: "Tags", order: 5 }
+        },
+        {
+          // Self-reference (document → document): the decision this one supersedes.
+          fieldId: "supersedes",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The decision this one supersedes (by externalId).",
+          renderHints: { label: "Supersedes", order: 6 }
+        },
+        {
+          fieldId: "date",
+          fieldType: "date",
+          description: "ISO-8601 decision date. Range-queryable / sortable.",
+          renderHints: { label: "Date", widget: "date", order: 7 }
+        }
+      ],
+      lookupFields: ["status", "area", "supersedes", { fieldName: "date", rangeEnabled: true }]
+    },
+    {
+      // A DESIGN doc or spec — the exploration that drives a decision. Distinct
+      // from `decision` (a different browse genre + it links to the decision it
+      // informs). Body = the design narrative.
+      typeName: "design",
+      displayName: "Design",
+      indexMode: "HYBRID",
+      allowedSurfaces: ["document"],
+      // Intrinsic title + body; schema = metadata beyond those (no typed `title`).
+      fields: [
+        {
+          fieldId: "summary",
+          fieldType: "string",
+          searchable: true,
+          description: "A one-paragraph abstract. The full design is the document body.",
+          renderHints: { label: "Summary", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["draft", "active", "implemented", "superseded"],
+          renderHints: { label: "Status", widget: "select", order: 3 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 4 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 5 }
+        },
+        {
+          // Cross-document edge: the decision this design informs/produces.
+          fieldId: "relatedDecision",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The decision this design informs (by externalId).",
+          renderHints: { label: "Related decision", order: 6 }
+        },
+        {
+          // Self-reference: a design supersedes an earlier design/spec.
+          fieldId: "supersedes",
+          fieldType: "reference",
+          targetTypeName: "design",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The design this one supersedes (by externalId).",
+          renderHints: { label: "Supersedes", order: 7 }
+        },
+        {
+          fieldId: "updatedOn",
+          fieldType: "date",
+          description: "ISO-8601 \u2014 when last revised. Range-queryable.",
+          renderHints: { label: "Updated on", widget: "date", order: 8 }
+        }
+      ],
+      lookupFields: ["status", "area", "relatedDecision", "supersedes", { fieldName: "updatedOn", rangeEnabled: true }]
+    },
+    {
+      // A REFERENCE doc — maintained "how it works / how to": guides, onboarding,
+      // API docs, process docs. Body = the prose. Distinct shape: a `category`
+      // (DRY sub-labels — onboarding/api/process are same shape) and `lastReviewed`
+      // (freshness is the whole game for reference material).
+      typeName: "reference",
+      displayName: "Reference",
+      indexMode: "HYBRID",
+      allowedSurfaces: ["document"],
+      // Intrinsic title + body; schema = metadata beyond those (no typed `title`).
+      fields: [
+        {
+          fieldId: "summary",
+          fieldType: "string",
+          searchable: true,
+          description: "A one-paragraph abstract. The full reference is the document body.",
+          renderHints: { label: "Summary", widget: "textarea", order: 2 }
+        },
+        {
+          // The sub-kind, as a filterable field (not a separate schema — these are
+          // the same shape, differing only by label, so a field is the DRY choice).
+          fieldId: "category",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["guide", "onboarding", "api", "process", "other"],
+          renderHints: { label: "Category", widget: "select", order: 3 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 4 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 5 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["active", "superseded"],
+          renderHints: { label: "Status", widget: "select", order: 6 }
+        },
+        {
+          // Optional cross-document edge: the decision behind this reference.
+          fieldId: "relatedDecision",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The decision behind this reference, if any (by externalId).",
+          renderHints: { label: "Related decision", order: 7 }
+        },
+        {
+          // Freshness — "references not reviewed since X". The reference-doc signal.
+          fieldId: "lastReviewed",
+          fieldType: "date",
+          description: "ISO-8601 \u2014 when this reference was last verified current. Range-queryable.",
+          renderHints: { label: "Last reviewed", widget: "date", order: 8 }
+        }
+      ],
+      lookupFields: ["category", "area", "status", "relatedDecision", { fieldName: "lastReviewed", rangeEnabled: true }]
+    },
+    {
+      // A RUNBOOK — a step-by-step operational procedure (deploy, release, recover).
+      // Body = the procedure. Distinct browse genre, and often BORN FROM a
+      // post-mortem (its resolution, codified) — a cross-document edge.
+      typeName: "runbook",
+      displayName: "Runbook",
+      indexMode: "HYBRID",
+      allowedSurfaces: ["document"],
+      // Intrinsic title + body; schema = metadata beyond those (no typed `title`).
+      fields: [
+        {
+          fieldId: "summary",
+          fieldType: "string",
+          searchable: true,
+          description: "When to use this runbook \u2014 the trigger. The steps are the document body.",
+          renderHints: { label: "Summary", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 3 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 4 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["active", "retired"],
+          renderHints: { label: "Status", widget: "select", order: 5 }
+        },
+        {
+          // Cross-document edge: the post-mortem whose resolution this runbook codifies.
+          fieldId: "bornFrom",
+          fieldType: "reference",
+          targetTypeName: "postmortem",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The post-mortem this runbook was codified from (by externalId).",
+          renderHints: { label: "Born from (post-mortem)", order: 6 }
+        },
+        {
+          fieldId: "relatedDecision",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "A decision this runbook implements, if any (by externalId).",
+          renderHints: { label: "Related decision", order: 7 }
+        },
+        {
+          fieldId: "updatedOn",
+          fieldType: "date",
+          description: "ISO-8601 \u2014 when last revised. Range-queryable.",
+          renderHints: { label: "Updated on", widget: "date", order: 8 }
+        }
+      ],
+      lookupFields: ["area", "status", "bornFrom", "relatedDecision", { fieldName: "updatedOn", rangeEnabled: true }]
+    },
+    {
+      // A POST-MORTEM — what broke and the durable lesson. Body = the writeup
+      // (impact / root cause / resolution / lesson). Distinct shape: `severity` +
+      // `occurredOn` (the incident timeline). "Have we hit this before?" lives here.
+      typeName: "postmortem",
+      displayName: "Post-mortem",
+      indexMode: "HYBRID",
+      allowedSurfaces: ["document"],
+      // Intrinsic title + body; schema = metadata beyond those (no typed `title`).
+      fields: [
+        {
+          fieldId: "summary",
+          fieldType: "string",
+          searchable: true,
+          description: "What happened, in brief. The full analysis (impact/root cause/resolution/lesson) is the body.",
+          renderHints: { label: "Summary", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "severity",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["low", "medium", "high", "critical"],
+          renderHints: { label: "Severity", widget: "select", order: 3 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["open", "mitigated", "resolved"],
+          renderHints: { label: "Status", widget: "select", order: 4 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 5 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 6 }
+        },
+        {
+          fieldId: "relatedDecision",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "A decision implicated in or addressed by this incident (by externalId).",
+          renderHints: { label: "Related decision", order: 7 }
+        },
+        {
+          fieldId: "occurredOn",
+          fieldType: "date",
+          description: 'ISO-8601 \u2014 when it happened. Range-queryable \u2014 "incidents this month".',
+          renderHints: { label: "Occurred on", widget: "date", order: 8 }
+        }
+      ],
+      lookupFields: ["severity", "status", "area", "relatedDecision", { fieldName: "occurredOn", rangeEnabled: true }]
+    },
+    // ============================= RECORDS =============================
+    // Structure-dominant: the typed fields are the artifact. Short, exact-queryable.
+    {
+      // A governance CONTROL — a policy/standard/control the codebase must satisfy,
+      // WITH its evidence. The compliance instrument: it records what enforces it
+      // (`evidence`), the runbook that VERIFIES it (cross-surface → document), and
+      // the decision that mandates it. "Which critical controls are active, and how
+      // is each proven?"
+      typeName: "control",
+      displayName: "Control",
+      indexMode: "HYBRID",
+      fields: [
+        {
+          fieldId: "title",
+          fieldType: "string",
+          required: true,
+          searchable: true,
+          validation: { minLength: 1, maxLength: 200 },
+          renderHints: { label: "Title", widget: "text", order: 1, displayField: true }
+        },
+        {
+          fieldId: "statement",
+          fieldType: "string",
+          searchable: true,
+          description: "The requirement \u2014 what must always hold.",
+          renderHints: { label: "Statement", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "rationale",
+          fieldType: "string",
+          searchable: true,
+          description: "Why the control exists \u2014 the risk it prevents.",
+          renderHints: { label: "Rationale", widget: "textarea", order: 3 }
+        },
+        {
+          // The policy → implementation spectrum in one filterable field.
+          fieldId: "kind",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["policy", "standard", "control"],
+          renderHints: { label: "Kind", widget: "select", order: 4 }
+        },
+        {
+          // Ordinal, but EQUALITY (range/prefix order is lexical, so low<critical
+          // would sort alphabetically). Enumerate "all critical controls" by equality.
+          fieldId: "criticality",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["low", "medium", "high", "critical"],
+          renderHints: { label: "Criticality", widget: "select", order: 5 }
+        },
+        {
+          fieldId: "evidence",
+          fieldType: "string",
+          searchable: true,
+          description: "What enforces or proves the control inline (e.g. an architecture test or gate).",
+          renderHints: { label: "Evidence", widget: "textarea", order: 6 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["draft", "active", "retired"],
+          renderHints: { label: "Status", widget: "select", order: 7 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 8 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 9 }
+        },
+        {
+          // Cross-surface edge (record → document): the runbook that proves the control.
+          fieldId: "verifiedBy",
+          fieldType: "reference",
+          targetTypeName: "runbook",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The runbook that verifies this control (by externalId).",
+          renderHints: { label: "Verified by (runbook)", order: 10 }
+        },
+        {
+          // Cross-surface edge (record → document): the decision that mandates it.
+          fieldId: "relatedDecision",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The decision that mandates this control (by externalId).",
+          renderHints: { label: "Related decision", order: 11 }
+        },
+        {
+          fieldId: "reviewedOn",
+          fieldType: "date",
+          description: "ISO-8601 last-reviewed date. Range-queryable.",
+          renderHints: { label: "Reviewed on", widget: "date", order: 12 }
+        }
+      ],
+      lookupFields: [
+        "kind",
+        "criticality",
+        "status",
+        "area",
+        "verifiedBy",
+        "relatedDecision",
+        { fieldName: "reviewedOn", rangeEnabled: true }
+      ]
+    },
+    {
+      // A CONVENTION — a must-follow operating rule the team teaches its agents. The
+      // durable, shareable operating-memory. Distinct fields capture how we actually
+      // write these: the `rule` (imperative), the `why` (rationale), and `howToApply`
+      // (the concrete application) are SEPARATE fields, not one blob — so an agent can
+      // recall the rule, the reasoning, and the how independently.
+      typeName: "convention",
+      displayName: "Convention",
+      indexMode: "HYBRID",
+      fields: [
+        {
+          fieldId: "title",
+          fieldType: "string",
+          required: true,
+          searchable: true,
+          validation: { minLength: 1, maxLength: 200 },
+          renderHints: { label: "Title", widget: "text", order: 1, displayField: true }
+        },
+        {
+          fieldId: "rule",
+          fieldType: "string",
+          searchable: true,
+          description: "The convention itself, stated as an imperative.",
+          renderHints: { label: "Rule", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "why",
+          fieldType: "string",
+          searchable: true,
+          description: "Why it matters \u2014 the trade-off / the antipattern it prevents.",
+          renderHints: { label: "Why", widget: "textarea", order: 3 }
+        },
+        {
+          fieldId: "howToApply",
+          fieldType: "string",
+          searchable: true,
+          description: "How to comply in practice \u2014 the concrete application steps.",
+          renderHints: { label: "How to apply", widget: "textarea", order: 4 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 5 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["active", "retired"],
+          renderHints: { label: "Status", widget: "select", order: 6 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 7 }
+        },
+        {
+          // Cross-surface edge (record → document): the decision that established it.
+          fieldId: "establishedBy",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The decision that established this convention (by externalId).",
+          renderHints: { label: "Established by (decision)", order: 8 }
+        },
+        {
+          fieldId: "updatedOn",
+          fieldType: "date",
+          description: "ISO-8601 \u2014 when last revised. Range-queryable.",
+          renderHints: { label: "Updated on", widget: "date", order: 9 }
+        }
+      ],
+      lookupFields: ["area", "status", "establishedBy", { fieldName: "updatedOn", rangeEnabled: true }]
+    },
+    {
+      // A GOTCHA / sharp edge: a symptom, its cause, and the fix. A tight typed
+      // triple — found by meaning (semantic search on the symptom) + area/status.
+      // The most standalone type; no typed edge.
+      typeName: "gotcha",
+      displayName: "Gotcha",
+      indexMode: "HYBRID",
+      fields: [
+        {
+          fieldId: "symptom",
+          fieldType: "string",
+          required: true,
+          searchable: true,
+          validation: { minLength: 1, maxLength: 500 },
+          renderHints: { label: "Symptom", widget: "textarea", order: 1, displayField: true }
+        },
+        {
+          fieldId: "cause",
+          fieldType: "string",
+          searchable: true,
+          renderHints: { label: "Cause", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "fix",
+          fieldType: "string",
+          searchable: true,
+          renderHints: { label: "Fix", widget: "textarea", order: 3 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 4 }
+        },
+        {
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["active", "resolved"],
+          renderHints: { label: "Status", widget: "select", order: 5 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 6 }
+        },
+        {
+          fieldId: "discoveredOn",
+          fieldType: "date",
+          description: "ISO-8601 \u2014 when first hit. Range-queryable.",
+          renderHints: { label: "Discovered on", widget: "date", order: 7 }
+        }
+      ],
+      lookupFields: ["area", "status", { fieldName: "discoveredOn", rangeEnabled: true }]
+    },
+    {
+      // A glossary TERM — a definition keyed by the term itself. Structure-dominant:
+      // `term` is a UNIQUE exact-lookup key (the showcase of a uniqueness constraint),
+      // `definition` is the RAG body, `aliases` catch alternate names. Links to the
+      // decision that defines/establishes the concept where there is one.
+      typeName: "term",
+      displayName: "Glossary term",
+      indexMode: "HYBRID",
+      fields: [
+        {
+          fieldId: "term",
+          fieldType: "string",
+          required: true,
+          searchable: true,
+          validation: { minLength: 1, maxLength: 200 },
+          renderHints: { label: "Term", widget: "text", order: 1, displayField: true }
+        },
+        {
+          fieldId: "definition",
+          fieldType: "string",
+          searchable: true,
+          description: "What the term means \u2014 the RAG-able body.",
+          renderHints: { label: "Definition", widget: "textarea", order: 2 }
+        },
+        {
+          fieldId: "aliases",
+          fieldType: "array",
+          filterable: true,
+          description: "Alternate names / abbreviations for the same concept.",
+          renderHints: { label: "Aliases", order: 3 }
+        },
+        {
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          renderHints: { label: "Area", widget: "text", order: 4 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          renderHints: { label: "Tags", order: 5 }
+        },
+        {
+          fieldId: "relatedDecision",
+          fieldType: "reference",
+          targetTypeName: "decision",
+          targetSurface: "document",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "A decision that defines or establishes this term (by externalId).",
+          renderHints: { label: "Related decision", order: 6 }
+        },
+        {
+          fieldId: "updatedOn",
+          fieldType: "date",
+          description: "ISO-8601 \u2014 when last revised. Range-queryable.",
+          renderHints: { label: "Updated on", widget: "date", order: 7 }
+        }
+      ],
+      // `term` is a UNIQUE equality lookup — exact "define X" + a one-per-term
+      // guarantee. `area`/`relatedDecision` enumerate; `updatedOn` is the range row.
+      lookupFields: [
+        { fieldName: "term", unique: true },
+        "area",
+        "relatedDecision",
+        { fieldName: "updatedOn", rangeEnabled: true }
+      ]
+    }
+  ],
+  // Least-privilege, data-plane only. r/c/u records + search + schema discovery +
+  // inference:r (grounded recall over the document bodies) + document/folder r/c
+  // (the content artifacts are documents). NO :d — knowledge is superseded/retired
+  // via a status flip, so the trail of how the team's thinking evolved stays intact.
+  accessProfile: {
+    allowedActions: [
+      "records:r",
+      "records:c",
+      "records:u",
+      "search:r",
+      "schemas:r",
+      "inference:r",
+      "documents:r",
+      "documents:c",
+      "folders:r",
+      "folders:c"
+    ]
+  },
+  servicePrincipal: {
+    externalId: "agentic-sdlc",
+    displayName: "Agentic SDLC Knowledge Base"
+  }
+  // No bundled seed in this version: the content artifacts live on the document
+  // surface and the cross-surface graph is populated by the ingest agent
+  // (document_ingest / record_create), not the bootstrap seed step. Production
+  // contexts provision with `vectros bootstrap --no-seed` regardless.
+};
+var agentic_sdlc_default = agenticSdlc;
+var secondBrain = {
+  name: "second-brain",
+  version: "1.0.0",
+  description: "A personal knowledge base \u2014 capture notes, ideas, and links, then ask them anything.",
+  contextId: "second-brain",
+  contextName: "Second Brain",
+  schemas: [
+    {
+      typeName: "note",
+      displayName: "Note",
+      indexMode: "HYBRID",
+      // keyword on title + semantic on body — recall by meaning
+      fields: [
+        {
+          fieldId: "title",
+          fieldType: "string",
+          required: true,
+          searchable: true,
+          validation: { minLength: 1, maxLength: 200 },
+          renderHints: { label: "Title", widget: "text", order: 1, section: "Note", displayField: true }
+        },
+        {
+          fieldId: "body",
+          fieldType: "string",
+          searchable: true,
+          description: "The note itself \u2014 the RAG-able body you ask questions against.",
+          validation: { maxLength: 2e4 },
+          renderHints: { label: "Body", widget: "textarea", order: 2, section: "Note" }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          description: 'Freeform string labels for filtering (e.g. "idea", "reading", "work").',
+          renderHints: { label: "Tags", order: 3, section: "Organize" }
         },
         {
           // An enum (not freeform) so enumeration-by-source is reliable — a
@@ -9468,6 +10424,7 @@ var secondBrain = {
   },
   seed: [
     {
+      surface: "record",
       typeName: "note",
       externalId: "seed-welcome",
       fields: {
@@ -9599,6 +10556,7 @@ var clinicalIntake = {
   },
   seed: [
     {
+      surface: "record",
       typeName: "intake",
       externalId: "seed-synthetic-intake",
       fields: {
@@ -9620,6 +10578,7 @@ var clinical_intake_default = clinicalIntake;
 var BUNDLED_BLUEPRINTS = [
   task_management_default,
   coding_agent_memory_default,
+  agentic_sdlc_default,
   second_brain_default,
   clinical_intake_default
 ];
@@ -10057,7 +11016,8 @@ async function resolveCognitoToken(env, explicit) {
 async function resolveAuthContext(opts) {
   const baseUrl = envToBaseUrl(opts.env, opts.baseUrl ?? process.env.VECTROS_API_BASE_URL);
   const cognitoToken = await resolveCognitoToken(opts.env, opts.token);
-  const bridge = opts.provisioning ? await mintBridgeToken({ cognitoToken, apiBaseUrl: baseUrl }) : await mintContextToken({ cognitoToken, apiBaseUrl: baseUrl, contextId: opts.context ?? "default" });
+  const tenant = opts.tenant ?? "live";
+  const bridge = opts.provisioning ? await mintBridgeToken({ cognitoToken, apiBaseUrl: baseUrl, tenant }) : await mintContextToken({ cognitoToken, apiBaseUrl: baseUrl, contextId: opts.context ?? "default", tenant });
   const client = new VectrosClient({ token: bridge.token, environment: baseUrl });
   const identity = await resolveIdentity({ log: opts.log, apiKey: bridge.token, environment: baseUrl });
   return {
@@ -10067,7 +11027,8 @@ async function resolveAuthContext(opts) {
     baseUrl,
     env: opts.env,
     identity,
-    tenantId: typeof identity.tenantId === "string" ? identity.tenantId : void 0
+    tenantId: typeof identity.tenantId === "string" ? identity.tenantId : void 0,
+    tenant
   };
 }
 
@@ -10391,54 +11352,23 @@ function assertNoUnresolvedIdentities(blueprint) {
     );
   }
 }
-var SchemaReconcileError = class extends Error {
-  constructor(typeName, cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
-    super(
-      `Schema '${typeName}' already exists but could not be reconciled to the blueprint: ${detail}
-If this is a migration-locked attribute (a lookup field's rangeEnabled/sortBy/sensitive, or the schema typeName), it cannot change on an existing schema \u2014 use a new fieldName/typeName for the new shape.`
-    );
-    this.name = "SchemaReconcileError";
-  }
-};
-function isAlreadyExistsError(e) {
-  if (typeof e !== "object" || e === null) return false;
-  const err = e;
-  const status = err.statusCode;
-  const text = `${err.message ?? ""} ${err.body?.message ?? ""}`.toLowerCase();
-  return (status === 409 || status === 400) && text.includes("already exists");
-}
-async function findExistingSchemaId(client, typeName, owner) {
-  let startFrom;
-  for (; ; ) {
-    const page = await client.schemas.listSchemas({
-      userId: owner.userId,
-      orgId: owner.orgId,
-      limit: 100,
-      startFrom
-    });
-    const match = (page.data ?? []).find((s) => s.typeName === typeName);
-    if (match?.id) return match.id;
-    const next = page.nextCursor;
-    if (!next) return void 0;
-    startFrom = next;
-  }
-}
 async function runLoader(client, input) {
-  const { blueprint, tenantId, machineId, rotate = false, vectrosDir, log } = input;
+  const { blueprint, tenantId, machineId, rotate = false, skipSeed = false, vectrosDir, log } = input;
   assertScopeGate(blueprint.accessProfile.allowedActions);
   for (const clauses of Object.values(blueprint.roles ?? {})) {
     for (const clause of clauses) assertScopeGate(clause.allowedActions);
   }
   assertNoUnresolvedIdentities(blueprint);
-  await client.auth.createAppContext({ contextId: blueprint.contextId, name: contextNameOf(blueprint) });
+  await client.auth.createAppContext({ body: { contextId: blueprint.contextId, name: contextNameOf(blueprint) } });
   log.debug({ component: "loader", contextId: blueprint.contextId }, "app-context ensured");
   const user = await client.identity.createUser({
-    externalId: blueprint.servicePrincipal.externalId,
-    type: "SERVICE",
-    // SDK 0.18+ (identity-access rework): UserRequest's free-form attribute bag
-    // was renamed `metadata` → `payload`. Same semantics (arbitrary key/value).
-    payload: { displayName: blueprint.servicePrincipal.displayName }
+    body: {
+      externalId: blueprint.servicePrincipal.externalId,
+      type: "SERVICE",
+      // SDK 0.18+ (identity-access rework): UserRequest's free-form attribute bag
+      // was renamed `metadata` → `payload`. Same semantics (arbitrary key/value).
+      payload: { displayName: blueprint.servicePrincipal.displayName }
+    }
   });
   const userId = user.id;
   if (!userId) {
@@ -10473,23 +11403,9 @@ async function runLoader(client, input) {
       orgId: s.orgId,
       clientId: s.clientId
     };
-    let resp;
-    try {
-      resp = await ctxClient.schemas.createSchema(schemaBody);
-    } catch (e) {
-      if (!isAlreadyExistsError(e)) throw e;
-      if (s.clientId) throw e;
-      const existingId = await findExistingSchemaId(ctxClient, s.typeName, { userId: s.userId, orgId: s.orgId });
-      if (!existingId) throw e;
-      try {
-        resp = await ctxClient.schemas.updateSchema({ id: existingId, body: schemaBody });
-      } catch (ue) {
-        throw new SchemaReconcileError(s.typeName, ue);
-      }
-      log.debug({ component: "loader", typeName: s.typeName, schemaId: existingId }, "schema existed; reconciled to declared shape (update)");
-    }
+    const resp = await ctxClient.schemas.createSchema({ upsert: true, body: schemaBody });
     if (resp.id) schemaIds[s.typeName] = resp.id;
-    log.debug({ component: "loader", typeName: s.typeName, schemaId: resp.id }, "schema ensured");
+    log.debug({ component: "loader", typeName: s.typeName, schemaId: resp.id }, "schema ensured (upsert)");
   }
   const profileBody = {
     principalId: `usr_${userId}`,
@@ -10565,25 +11481,40 @@ async function runLoader(client, input) {
   log.debug({ component: "loader", keyName, keyAction }, "scoped key resolved");
   let seededCount = 0;
   const seededRecordIds = [];
-  for (const rec of blueprint.seed ?? []) {
+  const seededDocumentIds = [];
+  for (const rec of skipSeed ? [] : blueprint.seed ?? []) {
     const schemaId = schemaIds[rec.typeName];
     if (!schemaId) {
       log.warn({ component: "loader", typeName: rec.typeName }, "seed skipped \u2014 no schemaId for typeName");
       continue;
     }
-    const created = await ctxClient.records.createRecord({
-      typeName: rec.typeName,
-      schemaId,
-      // externalId is the FIRST-CLASS RecordRequest field — the platform's idempotency
-      // key AND the value other records resolve a `reference` against. Send it
-      // TOP-LEVEL (never in payload): payload-only leaves the record's first-class
-      // externalId null, so re-apply duplicates seeds (no dedup) and a reference with
-      // the default targetField=externalId can never resolve the target. It is not a
-      // payload field — the bundled schemas correctly do NOT declare one.
-      externalId: rec.externalId,
-      payload: rec.fields
-    });
-    if (created.id) seededRecordIds.push(created.id);
+    if (rec.surface === "document") {
+      const created = await ctxClient.documents.ingestDocument({
+        body: {
+          title: rec.title,
+          text: rec.text,
+          schemaId,
+          externalId: rec.externalId,
+          // Optional structured payload (the document's `fields`); omitted when absent.
+          payload: rec.fields,
+          // Retain the raw text so a seeded document is retrievable via
+          // GET /v1/documents/{id}/text (mirrors the MCP document_ingest default) —
+          // a seed's text IS its content, worth keeping for the getting-started graph.
+          storeText: true
+        }
+      });
+      if (created.id) seededDocumentIds.push(created.id);
+    } else {
+      const created = await ctxClient.records.createRecord({
+        body: {
+          typeName: rec.typeName,
+          schemaId,
+          externalId: rec.externalId,
+          payload: rec.fields
+        }
+      });
+      if (created.id) seededRecordIds.push(created.id);
+    }
     seededCount++;
   }
   return {
@@ -10596,10 +11527,11 @@ async function runLoader(client, input) {
     schemaIds,
     roleIds,
     seededCount,
-    seededRecordIds
+    seededRecordIds,
+    seededDocumentIds
   };
 }
-function buildPlan(blueprint) {
+function buildPlan(blueprint, opts = {}) {
   const steps = [];
   steps.push({ kind: "context", summary: `context '${blueprint.contextId}' (${contextNameOf(blueprint)})` });
   steps.push({
@@ -10631,9 +11563,14 @@ function buildPlan(blueprint) {
     });
   }
   steps.push({ kind: "key", summary: `key ${blueprint.name}-<machine> (mint 1 scoped ssk_*)` });
-  const seedCount = blueprint.seed?.length ?? 0;
-  if (seedCount > 0) {
-    steps.push({ kind: "seed", summary: `seed ${seedCount} record(s)` });
+  const seeds = blueprint.seed ?? [];
+  if (seeds.length > 0 && !opts.noSeed) {
+    const docs = seeds.filter((s) => s.surface === "document").length;
+    const recs = seeds.length - docs;
+    const parts = [];
+    if (recs > 0) parts.push(`${recs} record${recs === 1 ? "" : "s"}`);
+    if (docs > 0) parts.push(`${docs} document${docs === 1 ? "" : "s"}`);
+    steps.push({ kind: "seed", summary: `seed ${parts.join(" + ")}` });
   }
   return steps;
 }
@@ -10757,7 +11694,9 @@ function parseBootstrapArgs(argv) {
     rotate: false,
     useScopedToken: false,
     blankSlate: false,
+    noSeed: false,
     client: "desktop",
+    tenant: "live",
     help: false
   };
   for (let i = 0; i < argv.length; i++) {
@@ -10805,6 +11744,20 @@ function parseBootstrapArgs(argv) {
       case "--blank-slate":
         args.blankSlate = true;
         break;
+      case "--no-seed":
+        args.noSeed = true;
+        break;
+      case "--tenant": {
+        const v = argv[++i];
+        if (v !== "test" && v !== "live") {
+          throw new Error(`--tenant must be 'test' or 'live' (got '${v ?? ""}')`);
+        }
+        args.tenant = v;
+        break;
+      }
+      case "--test":
+        args.tenant = "test";
+        break;
       case "--help":
       case "-h":
         args.help = true;
@@ -10815,11 +11768,26 @@ function parseBootstrapArgs(argv) {
   }
   return args;
 }
+function shouldOfferSeedOptOut(args, blueprint, isTty) {
+  return !args.noSeed && (blueprint.seed?.length ?? 0) > 0 && !args.yes && !args.print && isTty;
+}
+function seedDeclined(answer) {
+  const a = answer.trim().toLowerCase();
+  return a === "n" || a === "no";
+}
+function seedSummaryLine(opts) {
+  if (opts.noSeed) {
+    return opts.declinedInteractively ? "  \u2714 Seeded 0 record(s) \u2014 skipped (you declined sample data)\n" : "  \u2714 Seeded 0 record(s) \u2014 skipped (--no-seed)\n";
+  }
+  return opts.seededCount ? `  \u2714 Seeded ${opts.seededCount} record(s)
+` : "";
+}
 var BOOTSTRAP_HELP = `vectros bootstrap \u2014 provision a least-privilege MCP credential.
 
 Usage:
-  vectros bootstrap [--blueprint <name> | --blank] [--env staging|production]
-                    [--client desktop|code] [--yes] [--print] [--rotate]
+  vectros bootstrap [--blueprint <name> | --blank] [--no-seed] [--env staging|production]
+                    [--tenant test|live | --test] [--client desktop|code]
+                    [--yes] [--print] [--rotate]
                     [--token <t> | env VECTROS_BOOTSTRAP_TOKEN]
                     [--base-url <url>] [--use-scoped-token]
 
@@ -10828,7 +11796,17 @@ Options:
                            OR a path to your own blueprint YAML/JSON (./my.yaml) \u2014 the "copy &
                            own" path. File blueprints get the identical scope gate (no override).
   --blank                  Credential only (read-only data-plane profile, no schemas).
+  --no-seed                Provision the blueprint's schemas, profile and key but SKIP its
+                           sample seed records \u2014 the right choice for a production context
+                           (a blueprint's seeds are illustrative, not real data). Unlike
+                           --blank, the schemas are still created.
   --env staging|production Target environment (default: production).
+  --tenant test|live       Which tenant the minted key scopes to (default: live).
+                           'test' provisions into your isolated test tenant \u2014 a
+                           dry-run before pointing real data at the same blueprint.
+                           The tenant rides the key (ssk_test_* vs ssk_live_*), so
+                           the MCP/client config is otherwise identical.
+  --test                   Shorthand for --tenant test.
   --base-url <url>         Override the API base URL (beats --env + VECTROS_API_BASE_URL).
   --client <desktop|code>  MCP host to configure (default: desktop). 'desktop' merges
                            claude_desktop_config.json (also works for Cursor/Cline);
@@ -10897,6 +11875,21 @@ async function resolveBridgeCognitoToken(args, prompt, isTty, resolveCognito = r
   if (!pasted) throw new Error("No token entered.");
   return pasted;
 }
+function buildRemintForContext(opts) {
+  const mintContext = opts.mintContext ?? mintContextToken;
+  return async (contextId) => {
+    const ctxToken = await mintContext({
+      cognitoToken: opts.cognitoToken,
+      apiBaseUrl: opts.apiBaseUrl,
+      contextId,
+      tenant: opts.tenant
+    });
+    return new VectrosClient({
+      token: ctxToken.token,
+      environment: opts.apiBaseUrl
+    });
+  };
+}
 async function runBootstrapCli(argv, deps = {}) {
   const log = deps.log ?? createLogger2();
   let args;
@@ -10948,7 +11941,20 @@ ${BOOTSTRAP_HELP}
   Blueprint: ${blueprint.name}
   \u2714 Scope gate: [${gate.accepted.join(", ")}] \u2014 all data-plane \u2713
 `);
-    const planSteps = buildPlan(blueprint);
+    let noSeed = args.noSeed;
+    let seedDeclinedInteractively = false;
+    if (shouldOfferSeedOptOut(args, blueprint, isTty)) {
+      const ans = await promptCtx.prompt(
+        `
+  Seed ${blueprint.seed?.length} sample record(s) into this context? [Y/n]
+  (Choose 'n' for a production context \u2014 sample data is illustrative only): `
+      );
+      if (seedDeclined(ans)) {
+        noSeed = true;
+        seedDeclinedInteractively = true;
+      }
+    }
+    const planSteps = buildPlan(blueprint, { noSeed });
     process.stdout.write(`
 ${renderPlan(blueprint, planSteps)}
 `);
@@ -10965,12 +11971,17 @@ ${renderPlan(blueprint, planSteps)}
       isTty,
       deps.resolveCognitoToken
     );
-    const bridge = await mintBridgeToken({
+    const mintBridge = deps.mintBridgeToken ?? mintBridgeToken;
+    const mintContext = deps.mintContextToken ?? mintContextToken;
+    const bridge = await mintBridge({
       cognitoToken,
       apiBaseUrl: baseUrl,
-      useScopedToken: args.useScopedToken
+      useScopedToken: args.useScopedToken,
+      // Tenant rides the key (ssk_test_* vs ssk_live_*), not the base URL.
+      tenant: args.tenant
     });
-    process.stdout.write("  \u2714 Bootstrap token minted (5-min TTL)\n");
+    process.stdout.write(`  \u2714 Bootstrap token minted (5-min TTL, ${args.tenant} tenant)
+`);
     const client = new VectrosClient({ token: bridge.token, environment: baseUrl });
     const identity = await resolveIdentity({ log, apiKey: bridge.token, environment: baseUrl });
     const tenantId = identity.tenantId;
@@ -10985,19 +11996,22 @@ ${renderPlan(blueprint, planSteps)}
       tenantId,
       machineId,
       rotate: args.rotate,
-      remintForContext: async (contextId) => {
-        const ctxToken = await mintContextToken({ cognitoToken, apiBaseUrl: baseUrl, contextId });
-        return new VectrosClient({
-          token: ctxToken.token,
-          environment: baseUrl
-        });
-      },
+      skipSeed: noSeed,
+      remintForContext: buildRemintForContext({
+        cognitoToken,
+        apiBaseUrl: baseUrl,
+        tenant: args.tenant,
+        mintContext
+      }),
       log
     });
     process.stdout.write(
-      `  \u2714 AccessProfile + key (${result.keyAction}) \u2192 ${result.keyName}
-` + (result.seededCount ? `  \u2714 Seeded ${result.seededCount} record(s)
-` : "")
+      `  \u2714 AccessProfile + ${args.tenant} key (${result.keyAction}) \u2192 ${result.keyName}
+` + seedSummaryLine({
+        noSeed,
+        declinedInteractively: seedDeclinedInteractively,
+        seededCount: result.seededCount
+      })
     );
     const entry = buildVectrosServerEntry({ apiKey: result.rawKey, apiBaseUrl: baseUrl });
     const isCode = args.client === "code";
@@ -11208,7 +12222,8 @@ servicePrincipal:
   displayName: ${name}
 
 seed:
-  - typeName: thing
+  - surface: record            # 'record' (createRecord) or 'document' (text-ingest: needs title + text)
+    typeName: thing
     externalId: seed-welcome   # stable \u2192 idempotent; re-apply converges
     fields: { title: "Hello from ${name}" }
 `;
@@ -11556,6 +12571,7 @@ async function withAuth(opts, deps, body) {
       token: opts.token,
       context: opts.context,
       provisioning: opts.provisioning,
+      tenant: opts.tenant,
       useScopedToken: opts.useScopedToken,
       log
     });
@@ -11832,19 +12848,23 @@ async function createIdentity(client, opts, payload) {
   switch (opts.type) {
     case "user":
       return client.identity.createUser({
-        externalId,
-        email: opts.email,
-        type: opts.service ? "SERVICE" : "HUMAN",
-        payload
+        body: {
+          externalId,
+          email: opts.email,
+          type: opts.service ? "SERVICE" : "HUMAN",
+          payload
+        }
       });
     case "org":
-      return client.identity.createOrg({ externalId, name: opts.name, payload });
+      return client.identity.createOrg({ body: { externalId, name: opts.name, payload } });
     case "client":
       return client.identity.createClient({
-        externalId,
-        name: opts.name,
-        orgId: opts.org,
-        payload
+        body: {
+          externalId,
+          name: opts.name,
+          orgId: opts.org,
+          payload
+        }
       });
   }
 }
@@ -12285,8 +13305,10 @@ async function runContextCreate(opts, deps = {}) {
     const client = auth.client;
     try {
       const ctx = await client.auth.createAppContext({
-        contextId: opts.contextId,
-        name: opts.name ?? opts.contextId
+        body: {
+          contextId: opts.contextId,
+          name: opts.name ?? opts.contextId
+        }
       });
       if (opts.json) {
         process.stdout.write(`${formatJson(ctx)}
@@ -12597,23 +13619,22 @@ async function runAssertions(client, deps, blueprint, tenantId, result) {
     }
   }
   for (const rec of blueprint.seed ?? []) {
+    const isDoc = rec.surface === "document";
+    const op = isDoc ? "lookupDocuments" : "lookupRecords";
+    const noun = isDoc ? "document" : "record";
     try {
-      const page = await client.records.lookupRecords({
-        type: rec.typeName,
-        field: "externalId",
-        value: rec.externalId
-      });
+      const page = isDoc ? await client.documents.lookupDocuments({ type: rec.typeName, field: "externalId", value: rec.externalId }) : await client.records.lookupRecords({ type: rec.typeName, field: "externalId", value: rec.externalId });
       const ok = (page.data ?? []).length >= 1;
       assertions.push({
         name: `seed-externalId:${rec.externalId}`,
         ok,
-        detail: ok ? `'${rec.typeName}' seed resolves by externalId '${rec.externalId}'` : `'${rec.typeName}' seed externalId '${rec.externalId}' resolved 0 records \u2014 externalId is not first-class (written only in payload?)`
+        detail: ok ? `'${rec.typeName}' seed resolves by externalId '${rec.externalId}'` : `'${rec.typeName}' seed externalId '${rec.externalId}' resolved 0 ${noun}s \u2014 externalId is not first-class (written only in payload?)`
       });
     } catch (e) {
       assertions.push({
         name: `seed-externalId:${rec.externalId}`,
         ok: false,
-        detail: `lookupRecords(externalId='${rec.externalId}') failed: ${errMsg(e)}`
+        detail: `${op}(externalId='${rec.externalId}') failed: ${errMsg(e)}`
       });
     }
   }
@@ -12671,6 +13692,14 @@ async function runTeardown(client, blueprint, machineId, snapshot, result) {
       steps.push({ step: `delete record ${id}`, ok: false, error: errMsg(e) });
     }
   }
+  for (const id of result.seededDocumentIds) {
+    try {
+      await client.documents.deleteDocument({ id });
+      steps.push({ step: `delete document ${id}`, ok: true });
+    } catch (e) {
+      steps.push({ step: `delete document ${id}`, ok: false, error: errMsg(e) });
+    }
+  }
   const principalId = `usr_${result.servicePrincipalUserId}`;
   if (snapshot.failed) {
     steps.push({ step: `delete access profile ${principalId}`, ok: true, skipped: true, error: "skipped \u2014 pre-apply snapshot failed; cannot prove ownership" });
@@ -12805,7 +13834,7 @@ function renderReport(blueprint, env, report) {
   if (report.applied) {
     const a = report.applied;
     lines.push(
-      `  \u2714 applied \u2014 key ${a.keyName} (${a.keyAction}), ${Object.keys(a.schemaIds).length} schema(s)` + (a.seededCount ? `, ${a.seededCount} seed record(s)` : "")
+      `  \u2714 applied \u2014 key ${a.keyName} (${a.keyAction}), ${Object.keys(a.schemaIds).length} schema(s)` + (a.seededCount ? `, ${a.seededCount} seed(s)` : "")
     );
   } else {
     lines.push(`  \u2716 apply failed \u2014 ${report.error ?? "unknown error"}`);
@@ -12868,7 +13897,10 @@ async function runBlueprintTest(fileOrName, opts, deps = {}) {
         const ctxToken = await mintContextToken({
           cognitoToken: auth.cognitoToken,
           apiBaseUrl: auth.baseUrl,
-          contextId
+          contextId,
+          // Same tenant as the bootstrap token (auth.tenant) — the in-context
+          // load must land in the tenant the run targets.
+          tenant: auth.tenant
         });
         return new VectrosClient({
           token: ctxToken.token,
@@ -12906,9 +13938,9 @@ async function runBlueprintTest(fileOrName, opts, deps = {}) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.5.1" : "dev",
-  sdk: true ? "0.29.9" : "dev",
-  blueprints: true ? "0.5.0" : "dev"
+  cli: true ? "0.6.4" : "dev",
+  sdk: true ? "0.31.0" : "dev",
+  blueprints: true ? "0.6.2" : "dev"
 };
 function formatBuildInfo() {
   return `vectros ${BUILD_INFO.cli} (sdk ${BUILD_INFO.sdk}, blueprints ${BUILD_INFO.blueprints})`;
@@ -12956,10 +13988,21 @@ function buildProgram(deps = {}) {
   addCommonAuthOptions(whoami).action(async (flags) => {
     process.exit(await runWhoami(toCommonOptions(flags), deps));
   });
-  const blueprintTest = program.command("blueprint-test").description("Apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.").argument("<file>", "blueprint file path (./my.yaml) or a bundled blueprint name").option("--keep", "leave the provisioned graph in place (skip teardown) for inspection");
+  const blueprintTest = program.command("blueprint-test").description("Apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.").argument("<file>", "blueprint file path (./my.yaml) or a bundled blueprint name").option("--keep", "leave the provisioned graph in place (skip teardown) for inspection").option("--tenant <tenant>", "target tenant for the run: 'test' or 'live' (default live)");
   addCommonAuthOptions(blueprintTest).action(
     async (file, flags) => {
-      process.exit(await runBlueprintTest(file, { ...toCommonOptions(flags), keep: Boolean(flags.keep) }, deps));
+      if (flags.tenant !== void 0 && flags.tenant !== "test" && flags.tenant !== "live") {
+        process.stderr.write(`  \u2716 --tenant must be 'test' or 'live' (got '${flags.tenant}')
+`);
+        process.exit(2);
+      }
+      process.exit(
+        await runBlueprintTest(
+          file,
+          { ...toCommonOptions(flags), keep: Boolean(flags.keep), tenant: flags.tenant },
+          deps
+        )
+      );
     }
   );
   registerKeyCommands(program, deps);