@vectros-ai/cli 0.12.0 → 0.13.0

package/dist/cli.js

@@ -4043,7 +4043,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/admin/access-log");
   }
   /**
-   * Lists all of your scoped API keys (`ssk_*`) across both your live and test environments. Revoked keys are excluded. Requires the `keys:r` scope.
+   * Lists your scoped API keys (`ssk_*`) in your credential's own environment — a live key lists live keys, a test key lists test keys. Revoked keys are excluded. Requires the `keys:r` scope.
    *
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
@@ -4426,7 +4426,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. 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` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; 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, and applies the same `identityOverrides` bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). 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` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; 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.
@@ -4844,7 +4844,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. 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:u` scope.
+   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its `identityOverrides` are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (`sk_`) is exempt. Requires the `profiles:u` scope.
    *
    * @param {Vectros.UpdateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4917,7 +4917,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. Requires the `profiles:d` scope.
+   * Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries `identityOverrides`, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no `identityOverrides` is unaffected, and a root API key (`sk_`) is exempt. Requires the `profiles:d` scope.
    *
    * @param {Vectros.DeleteAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5771,7 +5771,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/token");
   }
   /**
-   * Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in the same context rotates the token and resends the invitation rather than creating a duplicate. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). When `sendEmail` is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the `admin:users` scope.
+   * Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in the same context rotates the token and resends the invitation rather than creating a duplicate — this requires the `users:r` and `users:u` scopes in addition to `users:c`, because resending rotates a credential on an existing invitation and invalidates any link already sent. Without them the collision returns 409 instead, with no invitation details and no change to the outstanding invitation. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). When `sendEmail` is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the `users:c` scope.
    *
    * @param {Vectros.CreateInviteRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5842,7 +5842,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/invite");
   }
   /**
-   * Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when `sendEmail` is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Requires the `admin:users` scope.
+   * Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when `sendEmail` is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Because this rotates a credential on an existing invitation, it requires the `users:c`, `users:r` and `users:u` scopes.
    *
    * @param {Vectros.CreateInviteRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6176,7 +6176,7 @@ var DocumentsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-   *         startFrom: "doc_prev123"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listDocuments(request = {}, requestOptions) {
@@ -6486,6 +6486,7 @@ var DocumentsClient = class {
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -6533,6 +6534,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -6563,7 +6566,7 @@ var DocumentsClient = class {
    *         field: "po_number",
    *         value: "PO-1001",
    *         prefix: "PO-2024",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    *     })
@@ -6939,7 +6942,7 @@ var FoldersClient = class {
    *         parentFolderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
-   *         startFrom: "fld_prev123"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listFolders(request = {}, requestOptions) {
@@ -7116,6 +7119,7 @@ var FoldersClient = class {
    * @param {Vectros.UpdateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -7160,6 +7164,8 @@ var FoldersClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -7242,6 +7248,7 @@ var FoldersClient = class {
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -7289,6 +7296,8 @@ var FoldersClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -7376,7 +7385,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.listEntities({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listEntities(request, requestOptions) {
@@ -8140,7 +8150,7 @@ var IdentityClient = class {
    * @example
    *     await client.identity.listUsers({
    *         externalId: "usr_12345",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl",
    *         type: "person_v1",
    *         field: "team",
    *         value: "engineering",
@@ -8321,11 +8331,12 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/{id}");
   }
   /**
-   * Updates mutable fields on an existing user (such as email, status, payload, or schema binding). The `type` field is immutable after creation. This endpoint also activates an invited user: a PUT that moves a PENDING user to ACTIVE and carries `inviteToken`, `externalSubject`, and `emailVerifiedAttestation=true` completes the invitation. Requires the `users:u` scope.
+   * Updates mutable fields on an existing user (such as email, status, payload, or schema binding). The `type` field is immutable after creation, and `email` cannot be changed while an invitation to that user is still outstanding — revoke the invitation, or invite the new address instead. This endpoint also activates an invited user: a PUT that moves a PENDING user to ACTIVE and carries `inviteToken`, `externalSubject`, and `emailVerifiedAttestation=true` completes the invitation. Requires the `users:u` scope.
    *
    * @param {Vectros.UpdateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -8370,6 +8381,8 @@ var IdentityClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -9017,7 +9030,7 @@ var RecordsClient = class {
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listRecords(request = {}, requestOptions) {
@@ -9205,6 +9218,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -9253,6 +9267,8 @@ var RecordsClient = 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 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -9334,6 +9350,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -9384,6 +9401,8 @@ var RecordsClient = 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 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -9401,7 +9420,15 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/records/{id}");
   }
   /**
-   * Finds records by the value of a lookup field declared on the type's schema. Provide exactly one lookup mode: `value` (exact match), `from`+`to` (inclusive range, ascending by value), or `prefix` (string fields only, ascending). Range and prefix lookups are not supported on a sensitive field, because its value is stored as a blind index and has no sortable order. An exact-`value` lookup on a sensitive field is also rejected on this GET endpoint — the value must not appear in the URL — so use the `POST /v1/records/lookup` body variant for sensitive fields. Results are paginated: set `limit` for the page size and pass the returned `nextCursor` back as `startFrom` for the next page. Requires the `records:r:<type>` scope.
+   * Finds records by the value of a lookup field declared on the type's schema. Provide exactly one lookup mode: `value` (exact match), `from`+`to` (inclusive range, ascending by value), or `prefix` (string fields only, ascending). Range and prefix lookups are not supported on a sensitive field, because its value is stored as a blind index and has no sortable order. An exact-`value` lookup on a sensitive field is also rejected on this GET endpoint — the value must not appear in the URL — so use the `POST /v1/records/lookup` body variant for sensitive fields.
+   *
+   * A `value` lookup can additionally be narrowed to a window of the lookup field's **sort key** using `sortFrom` and/or `sortTo` (inclusive) — for example, one session's records created since a timestamp. The sort key is whatever the schema declares as that lookup's `sortBy` (`createdAt` by default, `lastUpdated`, or another field), and bounds are given in that field's own units — epoch milliseconds for the two timestamp options. **Records that have no value for the sorted field are never included in a bounded window** — they are ordered ahead of every record that does have one, and a `sortFrom`/`sortTo` window only ever selects from records carrying a value. The sorted field does not have to be `required`.
+   *
+   * Narrowing is available on any lookup field your schema declares for fast equality lookup, and on `externalId` — which is always ordered by creation time, so its bounds are epoch milliseconds whatever the schema says. It is rejected (`400`) for a field declared with `rangeEnabled`, for a field declared beyond the schema's fast-lookup budget, for a lookup whose `sortBy` names a sensitive field (a sensitive value is stored as a blind index and has no order), and for a window whose start is after its end. Ownership fields are not lookup fields on this endpoint at all — see the `field` parameter.
+   *
+   * While paging a narrowed lookup, keep every other parameter identical. The cursor is valid only for the exact query that returned it — changing `order`, `sortFrom`, `sortTo`, or dropping them altogether, is rejected rather than silently resumed at a position that means something different in the new query.
+   *
+   * Results are paginated: set `limit` for the page size and pass the returned `nextCursor` back as `startFrom` for the next page. **Keep paging until `nextCursor` is null** — a page can come back empty or shorter than `limit` while more results remain, so an empty page is not the end of the results. Requires the `records:r:<type>` scope.
    *
    * @param {Vectros.LookupRecordsRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9413,22 +9440,40 @@ var RecordsClient = class {
    *         type: "intake_form",
    *         field: "email",
    *         value: "jane@example.com",
+   *         values: ["open"],
    *         prefix: "jane",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   lookupRecords(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__lookupRecords(request, requestOptions));
   }
   async __lookupRecords(request, requestOptions) {
-    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, includePayload, order } = request;
+    const {
+      type: type_,
+      field,
+      value,
+      values,
+      from: from_,
+      to,
+      prefix,
+      sortFrom,
+      sortTo,
+      startFrom,
+      limit,
+      includePayload,
+      order
+    } = request;
     const _queryParams = {
       type: type_,
       field,
       value,
+      values,
       from: from_,
       to,
       prefix,
+      sortFrom,
+      sortTo,
       startFrom,
       limit,
       includePayload,
@@ -9472,7 +9517,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/records/lookup");
   }
   /**
-   * Body-based equivalent of `GET /v1/records/lookup`. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of in the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects an exact-value lookup on a sensitive field and directs you here. Non-sensitive exact-value, range (`from`+`to`), and prefix lookups also work here. Returns the same `{data, nextCursor}` envelope and uses the same pagination as the GET variant. Requires the `records:r:<type>` scope.
+   * Body-based equivalent of `GET /v1/records/lookup`. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of in the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects an exact-value lookup on a sensitive field and directs you here. Non-sensitive exact-value, range (`from`+`to`), and prefix lookups also work here, as does narrowing a `value` lookup by the field's sort key with `sortFrom`/`sortTo` — see the GET variant for what the sort key is and when narrowing by it is available. Returns the same `{data, nextCursor}` envelope and uses the same pagination as the GET variant; keep paging until `nextCursor` is null rather than stopping on an empty page. Requires the `records:r:<type>` scope.
    *
    * @param {Vectros.RecordLookupRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9667,7 +9712,7 @@ var SchemasClient = class {
    *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         surface: "document",
    *         recordType: "intake_form",
-   *         startFrom: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listSchemas(request = {}, requestOptions) {
@@ -9871,6 +9916,7 @@ var SchemasClient = class {
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -9919,6 +9965,8 @@ var SchemasClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -10185,7 +10233,7 @@ var logging;
   logging2.ConsoleLogger = ConsoleLogger;
 })(logging || (logging = {}));
 
-// ../blueprints/dist/index.mjs
+// node_modules/@vectros-ai/blueprints/dist/index.mjs
 var import_zod = require("zod");
 var import_zod2 = require("zod");
 var CONTEXT_ID_RE = /^[a-z][a-z0-9-]{2,30}$/;
@@ -10289,19 +10337,63 @@ var BlueprintFieldDefSchema = import_zod.z.object({
 var BlueprintLookupFieldSchema = import_zod.z.union([
   import_zod.z.string().min(1),
   import_zod.z.object({
-    fieldName: import_zod.z.string().min(1),
+    // A lookup field declares either ONE field (fieldName) or 2-3 fields
+    // matched together (fieldNames) — never both, never neither. `.strict()`
+    // below only rejects unknown KEYS; it does not enforce this combination,
+    // so the `.superRefine()` after it carries the actual rule.
+    fieldName: import_zod.z.string().min(1).optional(),
+    // Composite (conjunctive) lookup: match on all of these fields at once —
+    // "every record where `status` is `open` AND `area` is `billing`", exact,
+    // in a stable order. Order is significant and locked at create: a query
+    // may match a leading run of the list (the first field alone, the first
+    // two together, …) but never a later field alone — declare a separate
+    // lookup for that. Record-only: the schema's `allowedSurfaces` must be
+    // exactly `['record']` (checked at the schema level below) — the
+    // platform's composite index has no document/user/entity reader yet.
+    fieldNames: import_zod.z.array(import_zod.z.string().min(1)).min(2).max(3).optional(),
+    // Not available on a composite (`fieldNames`) lookup — checked below.
     unique: import_zod.z.boolean().optional(),
     // Opt this field into ordered range + prefix lookups (from/to/prefix) on
     // top of exact match. Billed at the range-index rate; not valid on a
-    // sensitive field (a blind index is not orderable). Locked at create.
+    // sensitive field (a blind index is not orderable), and — like `unique`
+    // — not available on a composite lookup: it is an exact-match index over
+    // its fields; declare the range lookup separately. Locked at create.
     rangeEnabled: import_zod.z.boolean().optional(),
     // Sort key for the exact-match index: 'createdAt' (default), 'lastUpdated',
-    // or a declared field on this schema. Locked at create.
+    // or a declared field on this schema. Locked at create. Valid on a
+    // composite lookup too — it orders WITHIN a group when a query supplies
+    // fewer values than the lookup declares, not across the whole result.
     sortBy: import_zod.z.string().min(1).optional(),
     // Opt a field past the fixed fast-index budget into a higher-cost
     // secondary index. No effect on a field that fits within the budget.
     allowOverflow: import_zod.z.boolean().optional()
-  }).strict()
+  }).strict().superRefine((lf, ctx) => {
+    const hasFieldName = lf.fieldName !== void 0;
+    const hasFieldNames = lf.fieldNames !== void 0;
+    if (hasFieldName === hasFieldNames) {
+      ctx.addIssue({
+        code: import_zod.z.ZodIssueCode.custom,
+        message: "a lookup field declares either 'fieldName' (one field) or 'fieldNames' (2-3 fields matched together), never both and never neither"
+      });
+      return;
+    }
+    if (hasFieldNames) {
+      if (lf.unique !== void 0) {
+        ctx.addIssue({
+          code: import_zod.z.ZodIssueCode.custom,
+          path: ["unique"],
+          message: "'unique' is not available on a composite ('fieldNames') lookup"
+        });
+      }
+      if (lf.rangeEnabled !== void 0) {
+        ctx.addIssue({
+          code: import_zod.z.ZodIssueCode.custom,
+          path: ["rangeEnabled"],
+          message: "'rangeEnabled' is not available on a composite ('fieldNames') lookup"
+        });
+      }
+    }
+  })
 ]);
 var BlueprintCapabilitiesSchema = import_zod.z.object({
   auditHistory: import_zod.z.boolean().optional()
@@ -10339,7 +10431,21 @@ var BlueprintSchemaSchema = import_zod.z.object({
   // hop); immutable once set. Mirrors the `basedOn` field on the platform's
   // schema-create request.
   basedOn: import_zod.z.string().min(1).optional()
-}).strict();
+}).strict().superRefine((schema, ctx) => {
+  const hasComposite = (schema.lookupFields ?? []).some(
+    (lf) => typeof lf === "object" && lf.fieldNames !== void 0
+  );
+  if (!hasComposite) return;
+  const surfaces = schema.allowedSurfaces;
+  const isRecordOnly = surfaces === void 0 || surfaces.length === 1 && surfaces[0] === "record";
+  if (!isRecordOnly) {
+    ctx.addIssue({
+      code: import_zod.z.ZodIssueCode.custom,
+      path: ["allowedSurfaces"],
+      message: `schema '${schema.typeName}': a composite ('fieldNames') lookup requires allowedSurfaces to be exactly ['record'] \u2014 the platform's composite index has no document/user/entity reader yet`
+    });
+  }
+});
 var BlueprintAccessProfileSchema = import_zod.z.object({
   // Validated structurally here; the SCOPE GATE (in @vectros-ai/cli) is
   // what enforces the data-plane-only security boundary.
@@ -12278,9 +12384,10 @@ var secondBrain = {
       // Lookup shapes are MIGRATION-LOCKED once the schema is live (a field cannot
       // flip equality↔range later), so each is chosen on purpose:
       //   • `source` — EQUALITY, sorted by `lastUpdated`: enumerate notes from one
-      //     source, most-recently-touched first. `lastUpdated` is always present, so
-      //     the sort never drops a note (sorting an equality lookup by an OPTIONAL
-      //     field would silently exclude rows that lack it).
+      //     source, most-recently-touched first. A platform timestamp is the natural
+      //     choice for "most recently touched" and is always present, so every note
+      //     has a position. (Sorting by an OPTIONAL payload field is also fine — notes
+      //     lacking it are ordered ahead of those that have it, never dropped.)
       //   • `status` — EQUALITY: "show archived notes".
       //   • `capturedAt` — RANGE: ordered `from`/`to`/`prefix` ("captured in 2026-06").
       // `externalId` has a built-in first-class finder — look it up directly, never
@@ -13402,7 +13509,16 @@ function toSdkFields(blueprint, schemaIndex) {
 function toLookupDefs(lookupFields) {
   return lookupFields?.map((lf) => {
     if (typeof lf === "string") return { fieldName: lf };
-    const def = { fieldName: lf.fieldName };
+    const hasFieldName = lf.fieldName !== void 0;
+    const hasFieldNames = lf.fieldNames !== void 0;
+    if (hasFieldName === hasFieldNames) {
+      throw new Error(
+        `Internal error: lookupField resolved to ${hasFieldName ? "both fieldName and fieldNames" : "neither fieldName nor fieldNames"} \u2014 @vectros-ai/blueprints' parseBlueprint should have refused this before the loader ever saw it.`
+      );
+    }
+    const def = {};
+    if (lf.fieldName !== void 0) def.fieldName = lf.fieldName;
+    if (lf.fieldNames !== void 0) def.fieldNames = lf.fieldNames;
     if (lf.unique !== void 0) def.unique = lf.unique;
     if (lf.rangeEnabled !== void 0) def.rangeEnabled = lf.rangeEnabled;
     if (lf.sortBy !== void 0) def.sortBy = lf.sortBy;
@@ -13665,7 +13781,7 @@ function buildPlan(blueprint, opts = {}) {
     summary: `principal '${blueprint.servicePrincipal.externalId}' (SERVICE)`
   });
   for (const s of blueprint.schemas) {
-    const lookups = toLookupDefs(s.lookupFields)?.map((l) => l.fieldName) ?? [];
+    const lookups = toLookupDefs(s.lookupFields)?.map((l) => l.fieldNames ? `(${l.fieldNames.join("+")})` : l.fieldName) ?? [];
     const lookupNote = lookups.length ? ` lookup: [${lookups.join(", ")}]` : "";
     const surfaceNote = s.allowedSurfaces ? ` surfaces: [${s.allowedSurfaces.join(", ")}]` : "";
     const sensitive = s.fields.filter((f) => f.sensitive).map((f) => f.fieldId);
@@ -14257,10 +14373,121 @@ ${formatCliError(err, { action: "Bootstrap failed" })}`);
 // src/cli-blueprint.ts
 var import_promises3 = require("fs/promises");
 
+// src/scope-grammar.ts
+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}$/;
+var SCOPE_NAMESPACE_MIN_LENGTH = 2;
+var SCOPE_NAMESPACE_MAX_LENGTH = 32;
+var SCOPE_VALUE_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+var SCOPE_VALUE_MIN_LENGTH = 1;
+var SCOPE_VALUE_MAX_LENGTH = 128;
+function valueGrammarError(value) {
+  if (!SCOPE_VALUE_RE.test(value)) {
+    return `'${value}' is not a valid scope value \u2014 ${SCOPE_VALUE_MIN_LENGTH}-${SCOPE_VALUE_MAX_LENGTH} characters, starting with a letter or digit and continuing with letters, digits, '_' or '-'. A value may not contain a colon.`;
+  }
+  return null;
+}
+function namespaceGrammarError(ns) {
+  if (FORBIDDEN_SCOPE_NAMESPACES.has(ns)) {
+    return `'${ns}' is a reserved namespace and cannot be used as an ownership scope`;
+  }
+  if (!SCOPE_NAMESPACE_RE.test(ns)) {
+    return `'${ns}' is not a valid namespace \u2014 lowercase, ${SCOPE_NAMESPACE_MIN_LENGTH}-${SCOPE_NAMESPACE_MAX_LENGTH} characters, starting with a letter and continuing with letters, digits, '_' or '-'`;
+  }
+  return null;
+}
+function assertScopeEntries(entries, flag) {
+  if (!entries?.length) return;
+  for (const raw of entries) {
+    const sep = raw.indexOf(":");
+    if (sep <= 0 || sep === raw.length - 1) {
+      throw new Error(`${flag} must be '<namespace>:<value>' (e.g. 'org:6ba7...'); got '${raw}'.`);
+    }
+    const nsError = namespaceGrammarError(raw.slice(0, sep));
+    if (nsError) throw new Error(`${flag} namespace ${nsError}`);
+    const valError = valueGrammarError(raw.slice(sep + 1));
+    if (valError) throw new Error(`${flag} value ${valError}`);
+  }
+}
+function assertIdentityOverrideValues(overrides, flag) {
+  if (!overrides) return;
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!key.startsWith("scope:")) continue;
+    const error = valueGrammarError(typeof value === "string" ? value : String(value));
+    if (error) throw new Error(`${flag} '${key}' value ${error}`);
+  }
+}
+function placeholderScopeNamespace(value) {
+  const m = /^\$\{\{\s*(?:under\.)?self\.scope\.([^\s}]+)\s*\}\}$/.exec(value);
+  return m ? m[1] : null;
+}
+var SELF_PLACEHOLDER_RE = /^\$\{\{\s*self\.(?:userId|partnerUserId|scope\.[a-z][a-z0-9_-]{1,31})\s*\}\}$/;
+var UNDER_SELF_PLACEHOLDER_RE = /^\$\{\{\s*under\.self\.(?:userId|partnerUserId|scope\.[a-z][a-z0-9_-]{1,31})\s*\}\}$/;
+
 // src/lint.ts
 var ENUM_COMPATIBLE_TYPES = /* @__PURE__ */ new Set(["enum", "string", "string[]"]);
-function lookupFieldName(lf) {
-  return typeof lf === "string" ? lf : lf.fieldName;
+var BUILT_IN_SORT_BY = /* @__PURE__ */ new Set(["createdAt", "lastUpdated"]);
+function lookupFieldNames(lf) {
+  if (typeof lf === "string") return [lf];
+  if (lf.fieldNames !== void 0) return lf.fieldNames;
+  return lf.fieldName !== void 0 ? [lf.fieldName] : [];
+}
+function compositeLegFindings(schema, lf, fieldsById, rangeEnabledFieldNames) {
+  const findings = [];
+  const id = `[${lf.fieldNames.join(", ")}]`;
+  const seenLegs = /* @__PURE__ */ new Set();
+  for (const leg of lf.fieldNames) {
+    if (seenLegs.has(leg)) {
+      findings.push({
+        severity: "error",
+        rule: "lookup-composite-repeated-leg",
+        message: `schema '${schema.typeName}': composite lookupField ${id} repeats the leg '${leg}'. Each leg occupies its own position in the sort key, so a repeat doubles the key cost of every row to express a conjunction of a field with itself.`
+      });
+    }
+    seenLegs.add(leg);
+    const field = fieldsById.get(leg);
+    if (!field) continue;
+    if (field.fieldType === "array" || field.fieldType === "object") {
+      findings.push({
+        severity: "error",
+        rule: "lookup-composite-leg-multi-valued",
+        message: `schema '${schema.typeName}': composite lookupField ${id} uses '${leg}' as a leg, but it is declared '${field.fieldType}'. A leg occupies one sort-key position and holds one value \u2014 a multi-valued or structured field would index only one rendering and the conjunction would return a subset while appearing complete. Use a scalar field as a leg.`
+      });
+    }
+    if (field.fieldType === "reference" && field.cardinality === "many") {
+      findings.push({
+        severity: "error",
+        rule: "lookup-composite-leg-multi-valued",
+        message: `schema '${schema.typeName}': composite lookupField ${id} uses '${leg}' as a leg, but it is a reference with cardinality 'many'. One sort-key position holds one value, so a multi-valued leg would index only one target and the conjunction would silently return a subset. Use a cardinality 'one' reference, or a scalar field.`
+      });
+    }
+    if (rangeEnabledFieldNames.has(leg)) {
+      findings.push({
+        severity: "error",
+        rule: "lookup-composite-leg-range-enabled",
+        message: `schema '${schema.typeName}': composite lookupField ${id} uses '${leg}' as a leg, but '${leg}' has its own lookupField declaring rangeEnabled \u2014 that stores it as an ordered row keyed on its own value, not an equality index. A leg is matched exactly. Declare the composite over non-range fields, and keep the range lookup as its own declaration.`
+      });
+    }
+    if (lf.sortBy !== void 0 && leg === lf.sortBy) {
+      findings.push({
+        severity: "error",
+        rule: "lookup-composite-leg-is-sortby",
+        message: `schema '${schema.typeName}': composite lookupField ${id} cannot use '${leg}' as both a leg and its sortBy target. Within a fixed tuple every matching record has the same value for that leg, so the sort payload would be constant and a sortFrom/sortTo window would return either everything or nothing \u2014 at double the sort-key cost. Sort by a different field, 'createdAt', or 'lastUpdated'.`
+      });
+    }
+  }
+  return findings;
 }
 function lintBlueprint(bp) {
   const findings = [];
@@ -14268,6 +14495,7 @@ function lintBlueprint(bp) {
   for (const schema of bp.schemas) {
     typeNames.add(schema.typeName);
     const fieldIds = /* @__PURE__ */ new Set();
+    const fieldsById = /* @__PURE__ */ new Map();
     for (const f of schema.fields) {
       if (fieldIds.has(f.fieldId)) {
         findings.push({
@@ -14277,6 +14505,7 @@ function lintBlueprint(bp) {
         });
       }
       fieldIds.add(f.fieldId);
+      fieldsById.set(f.fieldId, f);
       if (f.enumValues && f.enumValues.length > 0 && !ENUM_COMPATIBLE_TYPES.has(f.fieldType)) {
         findings.push({
           severity: "warning",
@@ -14285,14 +14514,35 @@ function lintBlueprint(bp) {
         });
       }
     }
+    const rangeEnabledFieldNames = /* @__PURE__ */ new Set();
     for (const lf of schema.lookupFields ?? []) {
-      const name = lookupFieldName(lf);
-      if (!fieldIds.has(name)) {
-        findings.push({
-          severity: "error",
-          rule: "lookup-field-unknown",
-          message: `schema '${schema.typeName}': lookupField '${name}' is not a declared field.`
-        });
+      if (typeof lf !== "string" && lf.fieldName !== void 0 && lf.rangeEnabled) {
+        rangeEnabledFieldNames.add(lf.fieldName);
+      }
+    }
+    for (const lf of schema.lookupFields ?? []) {
+      for (const name of lookupFieldNames(lf)) {
+        if (!fieldIds.has(name)) {
+          findings.push({
+            severity: "error",
+            rule: "lookup-field-unknown",
+            message: `schema '${schema.typeName}': lookupField '${name}' is not a declared field.`
+          });
+        }
+      }
+      if (typeof lf !== "string" && lf.fieldNames !== void 0) {
+        findings.push(
+          ...compositeLegFindings(schema, { fieldNames: lf.fieldNames, sortBy: lf.sortBy }, fieldsById, rangeEnabledFieldNames)
+        );
+      }
+      if (typeof lf !== "string" && lf.sortBy !== void 0) {
+        if (!BUILT_IN_SORT_BY.has(lf.sortBy) && !fieldIds.has(lf.sortBy)) {
+          findings.push({
+            severity: "warning",
+            rule: "lookup-sortby-unknown-field",
+            message: `schema '${schema.typeName}': lookupField sortBy '${lf.sortBy}' is not a declared field (nor 'createdAt'/'lastUpdated'). The platform does not reject this \u2014 it silently treats the sort target as an untyped field no record ever populates, which usually isn't what was intended. Likely a typo.`
+          });
+        }
       }
     }
   }
@@ -14308,6 +14558,10 @@ function lintBlueprint(bp) {
   const ds = bp.accessProfile.dataScope;
   if (ds) {
     for (const [key, values] of Object.entries(ds)) {
+      for (const value of values) {
+        const bad = placeholderFinding("accessProfile", key, value);
+        if (bad) findings.push(bad);
+      }
       if (values.length > 0 && !values.includes(null)) {
         findings.push({
           severity: "warning",
@@ -14331,6 +14585,10 @@ function lintBlueprint(bp) {
       const cds = clause.dataScope;
       if (!cds) return;
       for (const [key, values] of Object.entries(cds)) {
+        for (const value of values) {
+          const bad = placeholderFinding(`role '${roleId}' clause ${i}`, key, value);
+          if (bad) findings.push(bad);
+        }
         if (values.length > 0 && !values.includes(null)) {
           findings.push({
             severity: "warning",
@@ -14344,6 +14602,28 @@ function lintBlueprint(bp) {
   return findings;
 }
 var ROLE_ID_RE = /^[a-z][a-z0-9-]{2,30}$/;
+var PLACEHOLDER_SHAPED_RE = /^\s*\$\{\{.*\}\}\s*$/s;
+var RECOGNIZED_PLACEHOLDER_RES = [/^\$\{\{\s*any\s*\}\}$/, SELF_PLACEHOLDER_RE, UNDER_SELF_PLACEHOLDER_RE];
+var BLUEPRINT_TOKEN_RE = /^\s*\$\{\{\s*(identities|inputs|vectros|ns)\./;
+function placeholderFinding(where, key, value) {
+  if (typeof value !== "string" || !PLACEHOLDER_SHAPED_RE.test(value)) return null;
+  if (BLUEPRINT_TOKEN_RE.test(value)) return null;
+  if (RECOGNIZED_PLACEHOLDER_RES.some((re) => re.test(value))) {
+    const ns = placeholderScopeNamespace(value);
+    const nsError = ns === null ? null : namespaceGrammarError(ns);
+    if (nsError === null) return null;
+    return {
+      severity: "error",
+      rule: "datascope-unknown-placeholder",
+      message: `${where}: dataScope.${key} value '${value}' names a namespace the platform rejects \u2014 ${nsError}. It will be rejected at apply.`
+    };
+  }
+  return {
+    severity: "error",
+    rule: "datascope-unknown-placeholder",
+    message: `${where}: dataScope.${key} value '${value}' is not a placeholder the platform recognizes \u2014 it will be rejected at apply. Valid: \${{ any }}, \${{ self.userId }}, \${{ self.scope.<namespace> }}, \${{ under.self.userId }}, \${{ under.self.scope.<namespace> }}. Spelling is exact and lowercase; use a plain value for a literal owner id.`
+  };
+}
 function lintPasses(findings) {
   return !findings.some((f) => f.severity === "error");
 }
@@ -14747,11 +15027,14 @@ function parseScopeOverrides(scopes) {
       throw new Error(`--scope must be '<namespace>:<value>' (e.g. 'org:6ba7...'); got '${raw}'.`);
     }
     const ns = raw.slice(0, sep);
+    const value = raw.slice(sep + 1);
+    const valueError = valueGrammarError(value);
+    if (valueError) throw new Error(`--scope value ${valueError}`);
     const key = `scope:${ns}`;
     if (Object.prototype.hasOwnProperty.call(out, key)) {
       throw new Error(`--scope sets namespace '${ns}' more than once \u2014 a scope override takes at most one value per namespace.`);
     }
-    out[key] = raw.slice(sep + 1);
+    out[key] = value;
   }
   if (Object.keys(out).length > 2) {
     throw new Error("--scope allows at most two distinct namespaces.");
@@ -15096,6 +15379,7 @@ async function createIdentity(client, opts, payload) {
       }
     });
   }
+  assertScopeEntries(opts.scope, "--scope");
   return client.identity.createEntity({
     namespace: opts.type,
     body: {
@@ -15301,6 +15585,7 @@ async function runAccessGrant(opts, deps = {}) {
         ...parseScopeOverrides(opts.scope) ?? {},
         ...opts.identityOverrides ? parseJsonObjectFlag("--identity-overrides", opts.identityOverrides) : {}
       };
+      assertIdentityOverrideValues(identityOverrides, "--identity-overrides");
     } catch (err) {
       process.stderr.write(`  \u2716 ${formatError(err)}
 `);
@@ -15453,30 +15738,21 @@ ${renderProfile(p)}
 
 // src/commands/access-explain.ts
 var SELF = /* @__PURE__ */ Symbol("self");
+var ANY = /* @__PURE__ */ Symbol("any");
+var UNDER_SELF = /* @__PURE__ */ Symbol("under.self");
 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 === DIM_WILDCARD) return true;
   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*\}\}$/;
+var DIM_WILDCARD = "*";
+var ANY_TOKEN_RE = /^\$\{\{\s*any\s*\}\}$/;
 function normalizeClauses(raw) {
   const out = [];
   for (const c of raw) {
@@ -15492,7 +15768,9 @@ function normalizeClauses(raw) {
       dataScope[dim] = values.map((val) => {
         if (val === null) return null;
         const s = String(val);
-        return SELF_TOKEN_RE2.test(s) ? SELF : s;
+        if (ANY_TOKEN_RE.test(s)) return ANY;
+        if (UNDER_SELF_PLACEHOLDER_RE.test(s)) return UNDER_SELF;
+        return SELF_PLACEHOLDER_RE.test(s) ? SELF : s;
       });
       if (!isRecognizedOwnershipKey(k)) unrecognizedDims.push(k);
     }
@@ -15500,6 +15778,38 @@ function normalizeClauses(raw) {
   }
   return out;
 }
+function recordTypesOf(actions) {
+  if (actions.includes("*")) return "all";
+  const types = /* @__PURE__ */ new Set();
+  let sawRecordsAction = false;
+  let sawUntyped = false;
+  for (const action of actions) {
+    const parts = action.split(":");
+    if (parts[0] !== "records") continue;
+    if (!(parts[1] ?? "").includes("r")) continue;
+    if (parts.length >= 3) {
+      const type = parts.slice(2).join(":");
+      if (type === "") continue;
+      if (type === "*") continue;
+      if (type.endsWith(":*")) {
+        const stripped = type.slice(0, -2);
+        if (stripped === "" || stripped.includes(":")) continue;
+        sawRecordsAction = true;
+        types.add(stripped);
+        continue;
+      }
+      if (type.includes(":")) continue;
+      sawRecordsAction = true;
+      types.add(type);
+    } else {
+      sawRecordsAction = true;
+      sawUntyped = true;
+    }
+  }
+  if (!sawRecordsAction) return null;
+  if (sawUntyped) return "all";
+  return [...types].sort();
+}
 function buildArchetypes(clauses) {
   const rows = [
     { label: "a record you own alone (private)", owners: { user: SELF } },
@@ -15510,8 +15820,13 @@ function buildArchetypes(clauses) {
     if (c.unrecognizedDims.length > 0) continue;
     for (const [dim, values] of Object.entries(c.dataScope)) {
       if (dim === "user") continue;
+      if (dim === DIM_WILDCARD) continue;
       const set = scopeDims.get(dim) ?? /* @__PURE__ */ new Set();
-      for (const v of values) if (v !== null) set.add(v);
+      set.add(SELF);
+      for (const v of values) {
+        if (v === null || v === ANY || v === UNDER_SELF) continue;
+        set.add(v);
+      }
       scopeDims.set(dim, set);
     }
   }
@@ -15530,19 +15845,42 @@ function buildArchetypes(clauses) {
   rows.push({ label: "no owner values at all (tenant-shared)", owners: {} });
   return rows;
 }
+function listAdmits(allowed, recordValue) {
+  return allowed.some((a) => {
+    if (a === null) return recordValue === void 0;
+    if (a === SELF) return recordValue === SELF;
+    if (a === ANY) return recordValue !== void 0;
+    if (a === UNDER_SELF) return false;
+    return recordValue === a;
+  });
+}
 function clauseMatches(clause, arch) {
   if (clause.unrecognizedDims.length > 0) return false;
+  const wildcard = clause.dataScope[DIM_WILDCARD];
   for (const [dim, allowed] of Object.entries(clause.dataScope)) {
-    const recordValue = arch.owners[dim];
-    const ok = allowed.some((a) => {
-      if (a === null) return recordValue === void 0;
-      if (a === SELF) return recordValue === SELF;
-      return recordValue === a;
-    });
-    if (!ok) return false;
+    if (dim === DIM_WILDCARD) continue;
+    if (!listAdmits(allowed, arch.owners[dim])) return false;
+  }
+  if (wildcard) {
+    let carriesAny = false;
+    for (const [dim, value] of Object.entries(arch.owners)) {
+      carriesAny = true;
+      if (dim in clause.dataScope) continue;
+      if (!listAdmits(wildcard, value)) return false;
+    }
+    if (!carriesAny && !listAdmits(wildcard, void 0)) return false;
   }
   return true;
 }
+function undecidableDims(clauses) {
+  const dims = /* @__PURE__ */ new Set();
+  for (const c of clauses) {
+    for (const [dim, values] of Object.entries(c.dataScope)) {
+      if (values.includes(UNDER_SELF)) dims.add(dim);
+    }
+  }
+  return [...dims];
+}
 function explainClauses(clauses) {
   const archetypes = buildArchetypes(clauses);
   return archetypes.map((arch) => {
@@ -15554,15 +15892,34 @@ function explainClauses(clauses) {
         for (const a of c.actions) actions.add(a);
       }
     });
-    return { archetype: arch.label, clauses: matched, actions: [...actions] };
+    const recordTypes = recordTypesOf([...actions]);
+    return {
+      archetype: arch.label,
+      clauses: matched,
+      actions: [...actions],
+      ...recordTypes !== null ? { recordTypes } : {}
+    };
   });
 }
 function renderDataScope(ds) {
   const entries = Object.entries(ds);
   if (entries.length === 0) return "(unscoped \u2014 all data in the context)";
-  return entries.map(
-    ([dim, values]) => `${dim}:[${values.map((v) => v === SELF ? "self" : v === null ? "null" : v).join(", ")}]`
-  ).join(" AND ");
+  return entries.map(([dim, values]) => {
+    const shown = values.map((v) => {
+      if (v === SELF) return "self";
+      if (v === ANY) return "any";
+      if (v === UNDER_SELF) return "under-self";
+      if (v === null) return "null";
+      return v;
+    });
+    const label = dim === DIM_WILDCARD ? "* (every other dimension)" : dim;
+    return `${label}:[${shown.join(", ")}]`;
+  }).join(" AND ");
+}
+function renderRecordTypes(recordTypes) {
+  if (recordTypes === void 0) return "\u2014";
+  if (recordTypes === "all") return "all types";
+  return recordTypes.join(", ");
 }
 var SELF_PRINCIPAL_ALIAS2 = "me";
 async function runAccessExplain(opts, deps = {}) {
@@ -15590,6 +15947,7 @@ async function runAccessExplain(opts, deps = {}) {
       }
       const clauses = normalizeClauses(rawClauses);
       const rows = explainClauses(clauses);
+      const undecidable = undecidableDims(clauses);
       if (opts.json) {
         process.stdout.write(
           `${formatJson({
@@ -15606,7 +15964,10 @@ async function runAccessExplain(opts, deps = {}) {
               ...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."
+            // Present only when a clause uses `${{ under.self.* }}`: those rows are UNDECIDED
+            // offline, not denied, and a consumer reading a blank cell as a denial would be wrong.
+            ...undecidable.length > 0 ? { undecidableDims: undecidable } : {},
+            note: "This preview models READ reachability, not write authorization: a `c`/`u`/`d` verb shown granted for a row may not actually be able to create/update a record with that exact ownership shape, because the platform requires a clause to explicitly name a dimension to place a value into it, while an unmentioned dimension never narrows reads. matrix[].recordTypes is the `records:` reach of that row's grant, separate from the ownership archetype: \"all\" reaches every type, an array names the type(s), absent means no `records:` action grants this row. Search/RAG visibility is a separate, still-unmodeled narrowing bounded per row by the same clause's typed read grants. Client-side preview; the platform decides at request time."
           })}
 `
         );
@@ -15634,8 +15995,19 @@ async function runAccessExplain(opts, deps = {}) {
         "\n" + formatTable(rows, [
           { header: "record owned by\u2026", get: (r) => r.archetype },
           { header: "granted?", get: (r) => r.clauses.length ? `via clause ${r.clauses.join(", ")}` : "NO" },
-          { header: "actions", get: (r) => r.actions.length ? r.actions.join(", ") : "\u2014" }
-        ]) + "\n\n  NOTE: this matrix models the OWNERSHIP dimensions only. Per-type qualifiers narrow further:\n  a `records:<ops>:<type>` action reaches only that type, and search/RAG visibility is bounded\n  per row by the SAME clause's typed read grants \u2014 a row shown with `search:r` is searchable\n  only for the content types that clause can read.\n  Preview only \u2014 computed client-side from the documented matching rules; the platform decides at request time.\n"
+          { header: "actions", get: (r) => r.actions.length ? r.actions.join(", ") : "\u2014" },
+          // The ownership "granted?" cell says nothing about WHICH record types — a clause can be
+          // ownership-unscoped and still type-restricted (a curated shared-KB clause with no owner
+          // dimension, readable only for a few named types, never others). Surface the actual
+          // `records:` reach per row instead of leaving it to a footnote.
+          { header: "record types", get: (r) => renderRecordTypes(r.recordTypes) }
+        ]) + (undecidable.length > 0 ? `
+
+  \u26A0 UNDECIDED offline: ${undecidable.join(", ")}
+  A clause matching on \`\${{ under.self.* }}\` needs the parent graph, which only the server has,
+  so rows granted through it are shown as NO above. Read those cells as "cannot tell here",
+  NOT as a denial \u2014 the matrix under-reports this clause.
+` : "") + '\n\n  \u26A0 READ ONLY: "granted?"/"actions" model whether a row can be READ, not whether a c/u/d\n  verb shown there can actually WRITE that row\'s exact shape \u2014 the platform requires a clause\n  to name a dimension to place a value into it, while reads are never narrowed by a dimension a\n  clause omits. A create/update verb next to a row is advisory: it names which records exist to\n  act on, not that a specific write will succeed.\n\n\n  NOTE: this matrix models the OWNERSHIP dimensions only \u2014 "granted?" says a row\'s ownership\n  shape matches a clause, and "record types" (above) says which `records:` types that grant\n  actually reaches; "all" reaches every type, "\u2014" means no `records:` action grants this row at\n  all. Search/RAG visibility is a separate, still-unmodeled narrowing: it is bounded per row by\n  the SAME clause\'s typed read grants \u2014 a row shown with `search:r` is searchable only for the\n  content types that clause can read.\n  Preview only \u2014 computed client-side from the documented matching rules; the platform decides at request time.\n'
       );
       return 0;
     } catch (err) {
@@ -18374,9 +18746,9 @@ function emitJoined(alias, context, principalId, role, keyId, reused) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.12.0" : "dev",
-  sdk: true ? "0.37.0" : "dev",
-  blueprints: true ? "0.9.0" : "dev"
+  cli: true ? "0.13.0" : "dev",
+  sdk: true ? "0.38.0" : "dev",
+  blueprints: true ? "0.10.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros ${BUILD_INFO.cli} (sdk ${BUILD_INFO.sdk}, blueprints ${BUILD_INFO.blueprints})`;