@vectros-ai/cli 0.10.0 → 0.12.0

package/AUTHORING.md

@@ -244,6 +244,13 @@ principal's `externalId`, the per-machine key name, and each seed record's
 `externalId`. Bump `version` when you evolve a blueprint. (Note: schema
 `typeName` is immutable after first apply.)
 
+**Pair `:r` with every `:c` you request.** Being handed back an existing item
+on a re-apply collision is a read of that item, not part of create authority —
+so a `records:c`-only `accessProfile.allowedActions` converges on first apply
+but fails on every re-apply with an "already exists" error instead of the
+existing record. Request `:r` alongside `:c` on every resource your blueprint
+creates (the bundled blueprints all do this — see the example above).
+
 ## Distribution
 
 - **Bundled** — reviewed, versioned blueprints shipped in the library

package/CHANGELOG.md

@@ -3,6 +3,47 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.12.0
+
+### Added
+
+- **Blueprints can declare `basedOn` on a schema.** A blueprint schema may now set
+  `basedOn: <schemaId>` to mark itself as a customization of an existing same-named
+  schema in the context; the loader forwards it to `createSchema`. Previously a
+  blueprint declaring `basedOn` would fail blueprint validation outright (an
+  unrecognized field); now it's accepted and forwarded. No bundled blueprint uses
+  this yet — it's forward-looking plumbing for a blueprint author (or a re-apply
+  into a context that already has a same-named hand-authored schema) who would
+  otherwise hit a `400` with no escape.
+
+### Changed
+
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.37.0`
+  (additive `basedOn` schema customization, `specificityRank` on namespaces, and
+  search/RAG response fields) and the bundled `@vectros-ai/blueprints` to `0.9.0`.
+  The CLI bundles both into its published binary, so this is a rebuild against
+  their current versions.
+
+## 0.11.0
+
+### Fixed
+
+- **`access explain` no longer previews access that the platform denies.** A clause keyed on an
+  unrecognized ownership dimension — a retired `orgId`/`clientId`, or an invalid
+  `scope:<namespace>` — now shows as granting nothing, matching how the server evaluates it,
+  instead of appearing to grant records the credential cannot actually reach. The dead clause is
+  shown explicitly rather than silently dropped.
+
+### Changed
+
+- **Clearer errors for expired sessions and rate limits.** When a command fails because your
+  login has expired, the CLI now tells you to run `vectros login` and retry; a rate-limited
+  request tells you to wait and retry. Failures that carry a typed error code surface it on the
+  support line alongside the request id.
+- **`bootstrap` warns when seeded sample data could not be indexed.** If a seed record or document
+  is stored but not (fully) searchable, the run summary now says so — and why — instead of
+  reporting it as fully seeded.
+
 ## 0.10.0
 
 ### Changed (breaking)

package/dist/cli.js

@@ -1649,6 +1649,7 @@ __export(api_exports, {
   FileUploadRequest: () => FileUploadRequest,
   ForbiddenError: () => ForbiddenError,
   IdentityLookupRequest: () => IdentityLookupRequest,
+  IndexFailure: () => IndexFailure,
   InternalServerError: () => InternalServerError,
   ListEntitiesRequestOrder: () => ListEntitiesRequestOrder,
   ListUsersRequestOrder: () => ListUsersRequestOrder,
@@ -2170,6 +2171,17 @@ var IdentityLookupRequest;
     Desc: "desc"
   };
 })(IdentityLookupRequest || (IdentityLookupRequest = {}));
+var IndexFailure;
+((IndexFailure2) => {
+  IndexFailure2.Code = {
+    SourceUnavailable: "SOURCE_UNAVAILABLE",
+    TextIndexFailed: "TEXT_INDEX_FAILED",
+    EmbeddingFailed: "EMBEDDING_FAILED",
+    IndexingFailed: "INDEXING_FAILED",
+    VectorLimitExceeded: "VECTOR_LIMIT_EXCEEDED",
+    Internal: "INTERNAL"
+  };
+})(IndexFailure || (IndexFailure = {}));
 var ModelDataVersionResponse;
 ((ModelDataVersionResponse2) => {
   ModelDataVersionResponse2.ChangeType = {
@@ -5686,7 +5698,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user, organization, or client. Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
+   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user or identity entity (in any namespace). Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
    *
    * @param {Vectros.TokenRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5903,7 +5915,7 @@ var ComplianceClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Submits a right-to-erasure request for a single end-subject (a user, client, or organization). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
+   * Submits a right-to-erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
    *
    * @param {Vectros.ErasureRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6212,7 +6224,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents");
   }
   /**
-   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope.
+   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the `documents:r` scope — a credential holding `documents:c` alone receives a `400` ("already exists") on collision instead of the document.
    *
    * @param {Vectros.IngestDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6538,25 +6550,29 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/documents/{id}");
   }
   /**
-   * Finds documents of a given type by field value. Supported fields: `externalId` (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. Results are paginated: set `limit` for the page size and feed the returned `nextCursor` back as `startFrom` to fetch the next page. The response is a `{data, nextCursor}` envelope. Requires the `documents:r` scope.
+   * Finds documents of a given type by field value. Supported fields: `externalId` (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. `type`'s schema resolves with basedOn-aware shadowing: your own `userId`- or `scope`-owned variant if you have one, otherwise the shared base — for a scoped credential the owner is always your own token identity; `userId`/`scope` here only apply as an explicit owner selector for a root API key. Results are paginated: set `limit` for the page size and feed the returned `nextCursor` back as `startFrom` to fetch the next page. The response is a `{data, nextCursor}` envelope. Requires the `documents:r` scope.
    *
    * @param {Vectros.LookupDocumentsRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   *
    * @example
    *     await client.documents.lookupDocuments({
    *         type: "invoice",
    *         field: "po_number",
    *         value: "PO-1001",
    *         prefix: "PO-2024",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         userId: "550e8400-e29b-41d4-a716-446655440000",
+   *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    *     })
    */
   lookupDocuments(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__lookupDocuments(request, requestOptions));
   }
   async __lookupDocuments(request, requestOptions) {
-    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, order } = request;
+    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, order, userId, scope } = request;
     const _queryParams = {
       type: type_,
       field,
@@ -6566,7 +6582,9 @@ var DocumentsClient = class {
       prefix,
       startFrom,
       limit,
-      order: order != null ? order : void 0
+      order: order != null ? order : void 0,
+      userId,
+      scope
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -6592,11 +6610,16 @@ var DocumentsClient = class {
       return { data: _response.body, rawResponse: _response.rawResponse };
     }
     if (_response.error.reason === "status-code") {
-      throw new VectrosError({
-        statusCode: _response.error.statusCode,
-        body: _response.error.body,
-        rawResponse: _response.rawResponse
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/lookup");
   }
@@ -6964,7 +6987,7 @@ var FoldersClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/folders");
   }
   /**
-   * Creates a folder to organize your documents and records. If `parentFolderId` is omitted, the folder is created under your context's default root folder. Folder creation is idempotent by (slug + parent): if a folder with the same slug already exists under the same parent, that existing folder is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing folder was returned) tells the two apart. To overwrite an existing folder's mutable fields instead of returning it unchanged, set `?upsert=true` (this also requires the `folders:u` scope). Requires the `folders:c` scope.
+   * Creates a folder to organize your documents and records. If `parentFolderId` is omitted, the folder is created under your context's default root folder. Folder creation is idempotent by (slug + parent): if a folder with the same slug already exists under the same parent, that existing folder is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing folder was returned) tells the two apart. To overwrite an existing folder's mutable fields instead of returning it unchanged, set `?upsert=true` (this also requires the `folders:u` scope). Requires the `folders:c` scope to create. Being returned the existing folder on a collision is a read of that folder's data and additionally requires the `folders:r` scope — a credential holding `folders:c` alone receives a `400` ("already exists") on collision instead of the folder.
    *
    * @param {Vectros.CreateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7422,7 +7445,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/entities/{namespace}");
   }
   /**
-   * Creates a new entity in the given namespace. This call is idempotent on `externalId` within the namespace: if an entity with the same `externalId` already exists, the existing record is returned instead of creating a duplicate (`created: false`, HTTP 200). To overwrite an existing entity's content instead of returning it unchanged, set `?upsert=true` (also requires the `entities:u:<namespace>` scope). The namespace must be entity-backed (`org`/`client`, or registered via `POST /v1/namespaces`). Requires the `entities:c:<namespace>` scope.
+   * Creates a new entity in the given namespace. This call is idempotent on `externalId` within the namespace: if an entity with the same `externalId` already exists, the existing record is returned instead of creating a duplicate (`created: false`, HTTP 200). To overwrite an existing entity's content instead of returning it unchanged, set `?upsert=true` (also requires the `entities:u:<namespace>` scope). The namespace must be entity-backed (`org`/`client`, or registered via `POST /v1/namespaces`). Requires the `entities:c:<namespace>` scope to create. Being returned the existing entity on a collision is a read of that entity's data and additionally requires the `entities:r:<namespace>` scope — a credential holding `entities:c:<namespace>` alone receives a `400` ("already in use") on collision instead of the entity.
    *
    * @param {Vectros.CreateEntityRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7866,7 +7889,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces/{namespace}");
   }
   /**
-   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
+   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`, `specificityRank`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
    *
    * @param {Vectros.UpdateNamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7879,7 +7902,8 @@ var IdentityClient = class {
    *     await client.identity.updateNamespace({
    *         namespace: "team",
    *         body: {
-   *             namespace: "team"
+   *             namespace: "team",
+   *             specificityRank: 1500
    *         }
    *     })
    */
@@ -8044,7 +8068,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces");
   }
   /**
-   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
+   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Also requires `specificityRank`, an explicit, account-unique position in the specificity order used to break recordType schema-resolution ties. Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
    *
    * @param {Vectros.NamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8055,7 +8079,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.registerNamespace({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         specificityRank: 1500
    *     })
    */
   registerNamespace(request, requestOptions) {
@@ -8172,7 +8197,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users");
   }
   /**
-   * Creates a user identity in your account. The operation is idempotent on `externalId`: if a user with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing user was returned) tells the two apart. To overwrite an existing user's mutable fields (email, status, payload, schema binding) instead of returning it unchanged, set `?upsert=true` (this also requires the `users:u` scope). Requires the `users:c` scope.
+   * Creates a user identity in your account. The operation is idempotent on `externalId`: if a user with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing user was returned) tells the two apart. To overwrite an existing user's mutable fields (email, status, payload, schema binding) instead of returning it unchanged, set `?upsert=true` (this also requires the `users:u` scope). Requires the `users:c` scope to create. Being returned the existing user on a collision is a read of that user's data and additionally requires the `users:r` scope — a credential holding `users:c` alone receives a `400` ("already exists") on collision instead of the user.
    *
    * @param {Vectros.CreateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9043,7 +9068,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/records");
   }
   /**
-   * Creates a new record of a given type. The `payload` is validated against that type's schema before the record is stored. Identify the type by sending `typeName`, `schemaId`, or both (they must agree); if you send only `schemaId`, the type is taken from that schema. Optionally supply an `externalId` to make the create idempotent — if a record with the same `externalId` already exists in your context, that existing record is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing record was returned) tells the two apart. To overwrite an existing record's content instead of returning it unchanged, set `?upsert=true` (this also requires the `records:u:<type>` scope). Requires the `records:c:<type>` scope.
+   * Creates a new record of a given type. The `payload` is validated against that type's schema before the record is stored. Identify the type by sending `typeName`, `schemaId`, or both (they must agree); if you send only `schemaId`, the type is taken from that schema. Optionally supply an `externalId` to make the create idempotent — if a record with the same `externalId` already exists in your context, that existing record is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing record was returned) tells the two apart. To overwrite an existing record's content instead of returning it unchanged, set `?upsert=true` (this also requires the `records:u:<type>` scope). Requires the `records:c:<type>` scope to create. Being returned the existing record on a collision is a read of that record's data and additionally requires the `records:r:<type>` scope — a credential holding `records:c:<type>` alone receives a `400` ("already exists") on collision instead of the record.
    *
    * @param {Vectros.CreateRecordRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9634,6 +9659,8 @@ var SchemasClient = class {
    * @param {Vectros.ListSchemasRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   *
    * @example
    *     await client.schemas.listSchemas({
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
@@ -9680,16 +9707,21 @@ var SchemasClient = class {
       return { data: _response.body, rawResponse: _response.rawResponse };
     }
     if (_response.error.reason === "status-code") {
-      throw new VectrosError({
-        statusCode: _response.error.statusCode,
-        body: _response.error.body,
-        rawResponse: _response.rawResponse
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/schemas");
   }
   /**
-   * Defines a new record type with optional field definitions, validation rules, and lookup indexes. Idempotent by `typeName` within the same ownership scope: re-creating an existing `typeName` returns the existing schema rather than failing. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing schema was returned) tells the two apart. To reconcile an existing schema to the submitted shape instead of returning it unchanged, set `?upsert=true` (this also requires the `schemas:w` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:w` scope.
+   * Defines a new record type with optional field definitions, validation rules, and lookup indexes. Idempotent by `typeName` within the same ownership scope: re-creating an existing `typeName` returns the existing schema rather than failing. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing schema was returned) tells the two apart. To reconcile an existing schema to the submitted shape instead of returning it unchanged, set `?upsert=true` (this also requires the `schemas:u` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:c` scope to create. Being returned the existing schema on a collision is a read of that schema's data and additionally requires the `schemas:r` scope — a credential holding `schemas:c` alone receives a `400` ("already in use") on collision instead of the schema.
    *
    * @param {Vectros.CreateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9833,7 +9865,7 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/schemas/{id}");
   }
   /**
-   * Updates a record schema. Fields you omit are preserved; `typeName` is immutable and cannot be changed. Collection fields (`fields`, `lookupFields`, `renderHints`, `capabilities`) are replaced in full when supplied. Requires the `schemas:w` scope.
+   * Updates a record schema. Fields you omit are preserved; `typeName` is immutable and cannot be changed. Collection fields (`fields`, `lookupFields`, `renderHints`, `capabilities`) are replaced in full when supplied. Requires the `schemas:u` scope.
    *
    * @param {Vectros.UpdateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9902,7 +9934,7 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/schemas/{id}");
   }
   /**
-   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. Requires the `schemas:w` scope.
+   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. A lineage base (a schema other schemas declare `basedOn`) also cannot be deleted while any such variant still exists — delete the variant schema(s) first. Requires the `schemas:d` scope.
    *
    * @param {Vectros.DeleteSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -10299,7 +10331,14 @@ var BlueprintSchemaSchema = import_zod.z.object({
   // With a scoped token these must be consistent with the profile's dataScope
   // (a cross-consistency lint is deferred to the lint slice).
   userId: import_zod.z.string().min(1).optional(),
-  scopes: import_zod.z.array(import_zod.z.string().min(1)).max(2).optional()
+  scopes: import_zod.z.array(import_zod.z.string().min(1)).max(2).optional(),
+  // The id of an existing schema this one is a CUSTOMIZATION of, when a schema
+  // named `typeName` already exists in this context — required in that case,
+  // and must be omitted when this create is the first schema under that name
+  // (it becomes that name's shared base). Must point directly at the base (one
+  // hop); immutable once set. Mirrors the `basedOn` field on the platform's
+  // schema-create request.
+  basedOn: import_zod.z.string().min(1).optional()
 }).strict();
 var BlueprintAccessProfileSchema = import_zod.z.object({
   // Validated structurally here; the SCOPE GATE (in @vectros-ai/cli) is
@@ -12480,19 +12519,21 @@ function extractServerError(err) {
     const statusCode = typeof e.statusCode === "number" ? e.statusCode : void 0;
     let serverMessage;
     let requestId;
+    let errorCode;
     if (e.body && typeof e.body === "object") {
       const b = e.body;
       if (typeof b.message === "string" && b.message.trim()) serverMessage = b.message.trim();
       if (typeof b.requestId === "string" && b.requestId.trim()) requestId = b.requestId.trim();
+      if (typeof b.errorCode === "string" && b.errorCode.trim()) errorCode = b.errorCode.trim();
     } else if (typeof e.body === "string" && e.body.trim()) {
       serverMessage = e.body.trim();
     }
-    if (serverMessage) return { statusCode, message: serverMessage, requestId };
+    if (serverMessage) return { statusCode, message: serverMessage, requestId, errorCode };
     const message = typeof e.message === "string" ? e.message : "";
     const isSdkEnvelope = /\nStatus code:/.test(message);
-    if (message && !isSdkEnvelope) return { statusCode, message, requestId };
-    if (statusCode) return { statusCode, message: `HTTP ${statusCode}`, requestId };
-    if (message) return { statusCode, message, requestId };
+    if (message && !isSdkEnvelope) return { statusCode, message, requestId, errorCode };
+    if (statusCode) return { statusCode, message: `HTTP ${statusCode}`, requestId, errorCode };
+    if (message) return { statusCode, message, requestId, errorCode };
   }
   return { message: String(err) };
 }
@@ -12503,15 +12544,17 @@ async function devRouteError(res, action) {
   const raw = await res.text().catch(() => "");
   let message;
   let requestId;
+  let errorCode;
   try {
     const parsed = JSON.parse(raw);
     if (typeof parsed.message === "string" && parsed.message.trim()) message = parsed.message.trim();
     if (typeof parsed.requestId === "string" && parsed.requestId.trim()) requestId = parsed.requestId.trim();
+    if (typeof parsed.errorCode === "string" && parsed.errorCode.trim()) errorCode = parsed.errorCode.trim();
   } catch {
   }
   const err = new Error(`${action}: HTTP ${res.status}`);
   err.statusCode = res.status;
-  err.body = { message: message ?? `HTTP ${res.status}`, requestId };
+  err.body = { message: message ?? `HTTP ${res.status}`, requestId, errorCode };
   return err;
 }
 function formatCliError(err, opts) {
@@ -12520,14 +12563,28 @@ function formatCliError(err, opts) {
   const block = actionable ?? `  \u2716 ${opts.action}: ${info.message}
 `;
   const debug = opts.debug ?? Boolean(process.env.VECTROS_MCP_DEBUG);
-  if (debug && info.requestId) {
-    return `${block}    (requestId: ${info.requestId} \u2014 quote this to support)
+  if (debug && (info.requestId || info.errorCode)) {
+    const parts = [
+      info.errorCode ? `errorCode: ${info.errorCode}` : null,
+      info.requestId ? `requestId: ${info.requestId}` : null
+    ].filter(Boolean);
+    return `${block}    (${parts.join(", ")} \u2014 quote this to support)
 `;
   }
   return block;
 }
 function renderActionableError(info) {
   const msg = info.message;
+  switch (info.errorCode) {
+    case "SESSION_REFRESH_REQUIRED":
+      return `  \u2716 Your session has expired.
+    Run 'vectros login' to re-authenticate, then retry.
+`;
+    case "RATE_LIMITED":
+      return `  \u2716 ${msg}
+    You're being rate-limited \u2014 wait a moment and retry.
+`;
+  }
   if (/scoped-key limit reached/i.test(msg)) {
     const plan = /plan '([^']+)'/i.exec(msg)?.[1];
     const count = /\((\d+) active keys\)/i.exec(msg)?.[1];
@@ -13076,8 +13133,13 @@ var KNOWN_CONTROL_PLANE_RESOURCES = [
   "users",
   "billing",
   "admin",
-  "clients",
-  "orgs"
+  // Identity/compartment provisioning. The flat `orgs`/`clients` resources were
+  // folded into the generic `entities` (per-namespace) + `namespaces` surfaces,
+  // which is what the API now scopes on — so those are the current spellings a
+  // pack could name. (Cosmetic: any non-data-plane resource hard-rejects whether
+  // or not it is listed here; this list only sharpens the error message.)
+  "entities",
+  "namespaces"
 ];
 var VALID_OPS = /* @__PURE__ */ new Set(["c", "r", "u", "d"]);
 var DATA_PLANE_SET = new Set(DATA_PLANE_ALLOWLIST);
@@ -13434,7 +13496,8 @@ async function runLoader(client, input) {
       capabilities: toCapabilities(s.capabilities),
       active: s.active,
       userId: s.userId,
-      scopes: s.scopes
+      scopes: s.scopes,
+      basedOn: s.basedOn
     };
     const resp = await ctxClient.schemas.createSchema({ upsert: true, body: schemaBody });
     if (resp.id) schemaIds[s.typeName] = resp.id;
@@ -13524,6 +13587,21 @@ async function runLoader(client, input) {
   let seededCount = 0;
   const seededRecordIds = [];
   const seededDocumentIds = [];
+  const seedIndexFailures = [];
+  const noteIfIndexFailed = (created, rec, surface) => {
+    if (created.indexStatus !== "FAILED") return;
+    seedIndexFailures.push({
+      externalId: rec.externalId,
+      typeName: rec.typeName,
+      surface,
+      code: created.indexFailure?.code,
+      message: created.indexFailure?.message
+    });
+    log.warn(
+      { component: "loader", typeName: rec.typeName, externalId: rec.externalId, code: created.indexFailure?.code },
+      "seed stored but failed to index"
+    );
+  };
   for (const rec of skipSeed ? [] : blueprint.seed ?? []) {
     const schemaId = schemaIds[rec.typeName];
     if (!schemaId) {
@@ -13544,6 +13622,7 @@ async function runLoader(client, input) {
         }
       });
       if (created.id) seededDocumentIds.push(created.id);
+      noteIfIndexFailed(created, rec, "document");
     } else {
       const created = await ctxClient.records.createRecord({
         body: {
@@ -13555,6 +13634,7 @@ async function runLoader(client, input) {
         }
       });
       if (created.id) seededRecordIds.push(created.id);
+      noteIfIndexFailed(created, rec, "record");
     }
     seededCount++;
   }
@@ -13573,7 +13653,8 @@ async function runLoader(client, input) {
     roleIds,
     seededCount,
     seededRecordIds,
-    seededDocumentIds
+    seededDocumentIds,
+    seedIndexFailures
   };
 }
 function buildPlan(blueprint, opts = {}) {
@@ -13828,6 +13909,17 @@ function seedSummaryLine(opts) {
   return opts.seededCount ? `  \u2714 Seeded ${opts.seededCount} record(s)
 ` : "";
 }
+function seedIndexWarningBlock(failures) {
+  if (failures.length === 0) return "";
+  const lines = failures.map((f) => {
+    const reason = f.message ?? f.code ?? "indexing failed";
+    return `      \u2022 ${f.typeName}/${f.externalId} (${f.surface}): ${reason}
+`;
+  });
+  return `  \u26A0 ${failures.length} seed(s) stored but not fully searchable:
+` + lines.join("") + `    They're stored and retrievable by id, but won't appear in search until the issue above is resolved.
+`;
+}
 function reconcileTally(items, noun) {
   if (items.length === 0) return null;
   const created = items.filter((i) => i.action === "created").length;
@@ -14084,7 +14176,7 @@ ${renderPlan(blueprint, planSteps)}
         noSeed,
         declinedInteractively: seedDeclinedInteractively,
         seededCount: result.seededCount
-      })
+      }) + seedIndexWarningBlock(result.seedIndexFailures)
     );
     const entry = buildVectrosServerEntry({ apiKey: result.rawKey, apiBaseUrl: baseUrl });
     const isCode = args.client === "code";
@@ -15365,6 +15457,25 @@ function canonicalDim(key) {
   if (key === "userId" || key === "partnerUserId") return "user";
   return key;
 }
+var FORBIDDEN_SCOPE_NAMESPACES = /* @__PURE__ */ new Set([
+  "user",
+  "record",
+  "document",
+  "entity",
+  "self",
+  "tenant",
+  "context",
+  "scope",
+  "versions",
+  "lookup"
+]);
+var SCOPE_NAMESPACE_RE = /^[a-z][a-z0-9_-]{1,31}$/;
+function isRecognizedOwnershipKey(key) {
+  if (key === "userId" || key === "partnerUserId") return true;
+  if (!key.startsWith("scope:")) return false;
+  const ns = key.slice("scope:".length);
+  return !FORBIDDEN_SCOPE_NAMESPACES.has(ns) && SCOPE_NAMESPACE_RE.test(ns);
+}
 var SELF_TOKEN_RE2 = /^\$\{\{\s*self\.[a-zA-Z.]+\s*\}\}$/;
 function normalizeClauses(raw) {
   const out = [];
@@ -15374,15 +15485,18 @@ function normalizeClauses(raw) {
     const actions = obj.allowed_actions ?? obj.allowedActions ?? [];
     const ds = obj.data_scope ?? obj.dataScope ?? {};
     const dataScope = {};
+    const unrecognizedDims = [];
     for (const [k, v] of Object.entries(ds)) {
+      const dim = canonicalDim(k);
       const values = Array.isArray(v) ? v : [v];
-      dataScope[canonicalDim(k)] = values.map((val) => {
+      dataScope[dim] = values.map((val) => {
         if (val === null) return null;
         const s = String(val);
         return SELF_TOKEN_RE2.test(s) ? SELF : s;
       });
+      if (!isRecognizedOwnershipKey(k)) unrecognizedDims.push(k);
     }
-    out.push({ actions: Array.isArray(actions) ? actions.map(String) : [], dataScope });
+    out.push({ actions: Array.isArray(actions) ? actions.map(String) : [], dataScope, unrecognizedDims });
   }
   return out;
 }
@@ -15393,6 +15507,7 @@ function buildArchetypes(clauses) {
   ];
   const scopeDims = /* @__PURE__ */ new Map();
   for (const c of clauses) {
+    if (c.unrecognizedDims.length > 0) continue;
     for (const [dim, values] of Object.entries(c.dataScope)) {
       if (dim === "user") continue;
       const set = scopeDims.get(dim) ?? /* @__PURE__ */ new Set();
@@ -15416,6 +15531,7 @@ function buildArchetypes(clauses) {
   return rows;
 }
 function clauseMatches(clause, arch) {
+  if (clause.unrecognizedDims.length > 0) return false;
   for (const [dim, allowed] of Object.entries(clause.dataScope)) {
     const recordValue = arch.owners[dim];
     const ok = allowed.some((a) => {
@@ -15481,7 +15597,14 @@ async function runAccessExplain(opts, deps = {}) {
             context: opts.context,
             via,
             identityOverrides: profile.identityOverrides,
-            clauses: clauses.map((c, i) => ({ n: i + 1, actions: c.actions, dataScope: renderDataScope(c.dataScope) })),
+            clauses: clauses.map((c, i) => ({
+              n: i + 1,
+              actions: c.actions,
+              dataScope: renderDataScope(c.dataScope),
+              // Present only on a dead clause — an unrecognized dim the platform
+              // denies (a retired key or a bad scope:<ns>); the matrix omits it.
+              ...c.unrecognizedDims.length > 0 ? { grantsNothing: true, unrecognizedDims: c.unrecognizedDims } : {}
+            })),
             matrix: rows,
             note: "Ownership dimensions only: per-type action qualifiers narrow further, and search/RAG visibility is bounded per row by the same clause's typed read grants. Client-side preview; the platform decides at request time."
           })}
@@ -15500,6 +15623,12 @@ async function runAccessExplain(opts, deps = {}) {
       clauses.forEach((c, i) => {
         process.stdout.write(`    ${i + 1}. [${c.actions.join(", ")}]  where ${renderDataScope(c.dataScope)}
 `);
+        if (c.unrecognizedDims.length > 0) {
+          process.stdout.write(
+            `       \u2716 grants nothing \u2014 unrecognized dimension${c.unrecognizedDims.length > 1 ? "s" : ""}: ${c.unrecognizedDims.join(", ")} (the platform denies a clause keyed on any dim that is not userId or a valid scope:<namespace>)
+`
+          );
+        }
       });
       process.stdout.write(
         "\n" + formatTable(rows, [
@@ -18245,9 +18374,9 @@ function emitJoined(alias, context, principalId, role, keyId, reused) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.10.0" : "dev",
-  sdk: true ? "0.35.0" : "dev",
-  blueprints: true ? "0.8.0" : "dev"
+  cli: true ? "0.12.0" : "dev",
+  sdk: true ? "0.37.0" : "dev",
+  blueprints: true ? "0.9.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros ${BUILD_INFO.cli} (sdk ${BUILD_INFO.sdk}, blueprints ${BUILD_INFO.blueprints})`;