@vectros-ai/cli 0.7.0 → 0.9.0

package/dist/cli.js

@@ -675,6 +675,10 @@ var ReadAccessLogResponse;
 })(ReadAccessLogResponse || (ReadAccessLogResponse = {}));
 var RecordRequest;
 ((RecordRequest2) => {
+  RecordRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
   RecordRequest2.IndexMode = {
     Hybrid: "HYBRID",
     Semantic: "SEMANTIC",
@@ -684,6 +688,10 @@ var RecordRequest;
 })(RecordRequest || (RecordRequest = {}));
 var RecordResponse;
 ((RecordResponse2) => {
+  RecordResponse2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
   RecordResponse2.IndexStatus = {
     PendingIndex: "PENDING_INDEX",
     Indexed: "INDEXED",
@@ -2306,7 +2314,7 @@ function withNoOpAuthProvider(options) {
     authProvider: new NoOpAuthProvider()
   };
 }
-function handleNonStatusCodeError(error, rawResponse, method, path4) {
+function handleNonStatusCodeError(error, rawResponse, method, path5) {
   switch (error.reason) {
     case "non-json":
       throw new VectrosError({
@@ -2320,7 +2328,7 @@ function handleNonStatusCodeError(error, rawResponse, method, path4) {
         rawResponse
       });
     case "timeout":
-      throw new VectrosTimeoutError(`Timeout exceeded when calling ${method} ${path4}.`, {
+      throw new VectrosTimeoutError(`Timeout exceeded when calling ${method} ${path5}.`, {
         cause: error.cause
       });
     case "unknown":
@@ -3158,7 +3166,7 @@ var AuthClient = class {
    *             roleId: "engineering-member",
    *             name: "Engineering Team Member",
    *             scopes: [{
-   *                     allowed_actions: ["read", "write"]
+   *                     allowed_actions: ["records:cru", "search:r"]
    *                 }]
    *         }
    *     })
@@ -3706,7 +3714,7 @@ var AuthClient = class {
    *             roleId: "engineering-member",
    *             name: "Engineering Team Member",
    *             scopes: [{
-   *                     allowed_actions: ["read", "write"]
+   *                     allowed_actions: ["records:cru", "search:r"]
    *                 }]
    *         }
    *     })
@@ -4609,7 +4617,7 @@ var DocumentsClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Returns a paginated list of your documents, optionally filtered by folder (`folderId`) and/or owner (`userId`, `orgId`, or `clientId`). The response is a `{data, nextCursor}` envelope; pass `nextCursor` back as `startFrom` to fetch the next page. Requires the `documents:r` scope.
+   * Returns a paginated list of your documents, optionally filtered by folder (`folderId`) and/or owner (`userId`, `orgId`, `clientId`, or `scope`). The response is a `{data, nextCursor}` envelope; pass `nextCursor` back as `startFrom` to fetch the next page. Requires the `documents:r` scope.
    *
    * @param {Vectros.ListDocumentsRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4619,6 +4627,7 @@ var DocumentsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         orgId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         clientId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+   *         scope: "group:eng-team",
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         startFrom: "doc_prev123"
    *     })
@@ -4627,11 +4636,12 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__listDocuments(request, requestOptions));
   }
   async __listDocuments(request = {}, requestOptions) {
-    const { userId, orgId, clientId, folderId, startFrom, limit } = request;
+    const { userId, orgId, clientId, scope, folderId, startFrom, limit } = request;
     const _queryParams = {
       userId,
       orgId,
       clientId,
+      scope,
       folderId,
       startFrom,
       limit
@@ -4689,9 +4699,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__ingestDocument(request, requestOptions));
   }
   async __ingestDocument(request, requestOptions) {
-    const { upsert, body: _body } = request;
+    const { upsert, allowClear, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      allowClear
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -4815,7 +4826,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__updateDocument(request, requestOptions));
   }
   async __updateDocument(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, allowClear, body: _body } = request;
+    const _queryParams = {
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -4830,7 +4844,7 @@ var DocumentsClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -7566,7 +7580,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/records/batch");
   }
   /**
-   * Returns a paginated list of records in your account as a `{data, nextCursor}` page. Supply exactly one of `type`, `folderId`, or `recent=true` to choose the mode: `type` lists all records of a single type; `folderId` lists all records in a folder (any type); and `recent=true` returns the account-wide recently-updated feed across all types, newest first. You may combine `type` with `folderId` to list a single type within a folder. The owner filters (`userId`, `orgId`, `clientId`) further narrow the type and folder modes; the `recent` feed is standalone and ignores all filters. Each token only sees the record types it is scoped to read. Requires the `records:r` scope. By default the response returns the indexed projection of each record; set `includePayload=true` to include full payloads.
+   * Returns a paginated list of records in your account as a `{data, nextCursor}` page. Supply exactly one of `type`, `folderId`, or `recent=true` to choose the mode: `type` lists all records of a single type; `folderId` lists all records in a folder (any type); and `recent=true` returns the account-wide recently-updated feed across all types, newest first. You may combine `type` with `folderId` to list a single type within a folder. The owner filters (`userId`, `orgId`, `clientId`, `scope`) further narrow the type and folder modes; the `recent` feed is standalone and ignores all filters. Each token only sees the record types it is scoped to read. Requires the `records:r` scope. By default the response returns the indexed projection of each record; set `includePayload=true` to include full payloads.
    *
    * @param {Vectros.ListRecordsRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7578,6 +7592,7 @@ var RecordsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         orgId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         clientId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+   *         scope: "group:eng-team",
    *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
    *     })
    */
@@ -7585,13 +7600,25 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__listRecords(request, requestOptions));
   }
   async __listRecords(request = {}, requestOptions) {
-    const { type: type_, folderId, userId, orgId, clientId, startFrom, limit, includePayload, recent } = request;
+    const {
+      type: type_,
+      folderId,
+      userId,
+      orgId,
+      clientId,
+      scope,
+      startFrom,
+      limit,
+      includePayload,
+      recent
+    } = request;
     const _queryParams = {
       type: type_,
       folderId,
       userId,
       orgId,
       clientId,
+      scope,
       startFrom,
       limit,
       includePayload,
@@ -7656,9 +7683,10 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__createRecord(request, requestOptions));
   }
   async __createRecord(request, requestOptions) {
-    const { upsert, body: _body } = request;
+    const { upsert, allowClear, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      allowClear
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -7780,7 +7808,10 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__updateRecord(request, requestOptions));
   }
   async __updateRecord(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, allowClear, body: _body } = request;
+    const _queryParams = {
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -7795,7 +7826,7 @@ var RecordsClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -8880,7 +8911,14 @@ var BlueprintAccessProfileSchema = import_zod.z.object({
   // null sentinel (+ ScopeClause). e.g. `{ orgId: ["org_x", null] }` =
   // "org_x's records AND tenant-shared records". Omitting null restricts to
   // the listed owners ONLY (the key will NOT see tenant-level/seed records).
-  dataScope: import_zod.z.record(import_zod.z.array(import_zod.z.union([import_zod.z.string().min(1), import_zod.z.null()]))).optional()
+  dataScope: import_zod.z.record(import_zod.z.array(import_zod.z.union([import_zod.z.string().min(1), import_zod.z.null()]))).optional(),
+  // Optional identity overrides for the service principal's profile — scope
+  // values its key STAMPS onto everything it writes (a credential can only
+  // stamp ownership its identity carries). Keys: `orgId`/`clientId` (or the
+  // namespaced `scope:<ns>` form); values may be `${{ identities.* }}` tokens
+  // (substituted at apply time). e.g. `{ orgId: '${{ identities.team }}' }`
+  // makes every record the service key writes org/team-owned.
+  identityOverrides: import_zod.z.record(import_zod.z.string().min(1)).optional()
 }).strict();
 var BlueprintRoleClauseSchema = import_zod.z.object({
   allowedActions: import_zod.z.array(import_zod.z.string().min(1)).min(1),
@@ -8906,7 +8944,14 @@ var SeedCommonShape = {
    * seeds resolve a `reference` against (across surfaces: a record seed may
    * reference a document seed by its externalId, and vice versa).
    */
-  externalId: import_zod.z.string().min(1)
+  externalId: import_zod.z.string().min(1),
+  /**
+   * Optional scope ownership for the seeded item, as `namespace:value` entries
+   * (≤2, e.g. `['org:${{ identities.team }}']`; tokens substitute at apply
+   * time). `[]` = a private, user-owned item. Omitted = the seeding
+   * credential's full identity (the default).
+   */
+  scopes: import_zod.z.array(import_zod.z.string()).optional()
 };
 var RecordSeedSchema = import_zod.z.object({
   surface: import_zod.z.literal("record"),
@@ -8930,25 +8975,25 @@ var BlueprintSeedRecordSchema = import_zod.z.discriminatedUnion("surface", [
 ]);
 var SELF_TOKEN_RE = /\$\{\{\s*self\.[A-Za-z_]\w*\s*\}\}/;
 function lintSelfTokenPlacement(value, ctx) {
-  const walk = (node, path4, inRoleDataScope) => {
+  const walk = (node, path5, inRoleDataScope) => {
     if (typeof node === "string") {
       if (!inRoleDataScope && SELF_TOKEN_RE.test(node)) {
         ctx.addIssue({
           code: import_zod.z.ZodIssueCode.custom,
-          path: path4,
+          path: path5,
           message: "'${{ self.* }}' is a runtime per-principal placeholder \u2014 it is only valid inside a roles[].dataScope value"
         });
       }
       return;
     }
     if (Array.isArray(node)) {
-      node.forEach((v, i) => walk(v, [...path4, i], inRoleDataScope));
+      node.forEach((v, i) => walk(v, [...path5, i], inRoleDataScope));
       return;
     }
     if (node && typeof node === "object") {
       for (const [k, v] of Object.entries(node)) {
-        const entering = inRoleDataScope || path4.length === 3 && path4[0] === "roles" && k === "dataScope";
-        walk(v, [...path4, k], entering);
+        const entering = inRoleDataScope || path5.length === 3 && path5[0] === "roles" && k === "dataScope";
+        walk(v, [...path5, k], entering);
       }
     }
   };
@@ -8959,13 +9004,13 @@ function lintIdentityRefsDeclared(value, ctx) {
   const declared = new Set(
     value && typeof value === "object" && "identities" in value && value.identities ? Object.keys(value.identities) : []
   );
-  const walk = (node, path4) => {
+  const walk = (node, path5) => {
     if (typeof node === "string") {
       for (const m of node.matchAll(IDENTITY_REF_RE)) {
         if (!declared.has(m[1])) {
           ctx.addIssue({
             code: import_zod.z.ZodIssueCode.custom,
-            path: path4,
+            path: path5,
             message: `'\${{ identities.${m[1]} }}' references an undeclared identity \u2014 add '${m[1]}' to the top-level 'identities' block`
           });
         }
@@ -8973,11 +9018,11 @@ function lintIdentityRefsDeclared(value, ctx) {
       return;
     }
     if (Array.isArray(node)) {
-      node.forEach((v, i) => walk(v, [...path4, i]));
+      node.forEach((v, i) => walk(v, [...path5, i]));
     } else if (node && typeof node === "object") {
       for (const [k, v] of Object.entries(node)) {
-        if (path4.length === 0 && k === "identities") continue;
-        walk(v, [...path4, k]);
+        if (path5.length === 0 && k === "identities") continue;
+        walk(v, [...path5, k]);
       }
     }
   };
@@ -9024,9 +9069,9 @@ var BlueprintSchema = import_zod.z.object({
   lintIdentityRefsDeclared(bp, ctx);
   lintSeedSurfaces(bp, ctx);
 });
-function formatIssuePath(path4) {
+function formatIssuePath(path5) {
   let out = "";
-  for (const seg of path4) {
+  for (const seg of path5) {
     if (typeof seg === "number") out += `[${seg}]`;
     else out += out.length ? `.${seg}` : seg;
   }
@@ -9064,6 +9109,14 @@ function contextNameOf(blueprint) {
   return blueprint.contextName ?? `MCP \u2014 ${blueprint.name}`;
 }
 var IDENTITY_TOKEN_RE = /\$\{\{\s*identities\.([A-Za-z_]\w*)\s*\}\}/g;
+var BlueprintIdentityError = class extends Error {
+  issues;
+  constructor(message, issues = []) {
+    super(message);
+    this.name = "BlueprintIdentityError";
+    this.issues = issues;
+  }
+};
 function collectIdentityReferences(value) {
   const found = /* @__PURE__ */ new Set();
   const walk = (node) => {
@@ -9078,6 +9131,61 @@ function collectIdentityReferences(value) {
   walk(value);
   return [...found];
 }
+function substitute(node, idMap) {
+  if (typeof node === "string") {
+    return node.replace(IDENTITY_TOKEN_RE, (_full, name) => idMap[name]);
+  }
+  if (Array.isArray(node)) return node.map((v) => substitute(v, idMap));
+  if (node && typeof node === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) out[k] = substitute(v, idMap);
+    return out;
+  }
+  return node;
+}
+async function resolveBlueprintIdentities(raw, resolve) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return raw;
+  const { identities: rawIdentities, ...body } = raw;
+  const refs = collectIdentityReferences(body);
+  if (rawIdentities === void 0 && refs.length === 0) return raw;
+  const parsed = IdentitiesDeclSchema.safeParse(rawIdentities ?? {});
+  if (!parsed.success) {
+    throw new BlueprintIdentityError(
+      "Blueprint identities block is invalid",
+      parsed.error.issues.map((i) => ({
+        path: i.path.length ? `identities.${i.path.join(".")}` : "identities",
+        message: i.message
+      }))
+    );
+  }
+  const declared = parsed.data;
+  const undeclared = refs.filter((name) => !(name in declared));
+  if (undeclared.length) {
+    throw new BlueprintIdentityError(
+      `Blueprint references undeclared identities: ${undeclared.join(", ")}`,
+      undeclared.map((name) => ({
+        path: `identities.${name}`,
+        message: `'\${{ identities.${name} }}' is referenced but not declared in the 'identities' block`
+      }))
+    );
+  }
+  const idMap = {};
+  for (const [name, decl] of Object.entries(declared)) {
+    try {
+      const id = await resolve(name, decl);
+      if (typeof id !== "string" || id.length === 0) {
+        throw new Error(`resolver returned a non-string id (${JSON.stringify(id)})`);
+      }
+      idMap[name] = id;
+    } catch (err) {
+      throw new BlueprintIdentityError(
+        `Failed to resolve identity '${name}' (${decl.kind} externalId=${decl.externalId}): ${err instanceof Error ? err.message : String(err)}`,
+        [{ path: `identities.${name}`, message: err instanceof Error ? err.message : String(err) }]
+      );
+    }
+  }
+  return substitute(body, idMap);
+}
 var INPUT_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var InputDeclSchema = import_zod2.z.object({
   type: import_zod2.z.enum(["string", "number", "boolean"]),
@@ -9115,18 +9223,18 @@ var WHOLE_TOKEN_RE = /^\$\{\{\s*([A-Za-z_]\w*)\.([A-Za-z_]\w*)\s*\}\}$/;
 var TOKEN_SCAN_RE = /\$\$\{\{|\$\{\{([\s\S]*?)\}\}|\$\{\{/g;
 var INNER_REF_RE = /^([A-Za-z_]\w*)\.([A-Za-z_]\w*)$/;
 var DEFERRED_NAMESPACES = /* @__PURE__ */ new Set(["self", "identities"]);
-function resolveRef(ns, name, ctx, path4) {
+function resolveRef(ns, name, ctx, path5) {
   if (ns === "inputs") {
     if (!(name in ctx.declared)) {
       ctx.issues.push({
-        path: path4,
+        path: path5,
         message: `unknown input 'inputs.${name}' \u2014 declare it in the top-level 'inputs:' block`
       });
       return void 0;
     }
     if (!(name in ctx.values)) {
       ctx.issues.push({
-        path: path4,
+        path: path5,
         message: `input 'inputs.${name}' has no value \u2014 supply it (--set ${name}=\u2026 or --values) or give it a default`
       });
       return void 0;
@@ -9136,14 +9244,14 @@ function resolveRef(ns, name, ctx, path4) {
   if (ns === "vectros") {
     if (name !== "context" && name !== "suffix") {
       ctx.issues.push({
-        path: path4,
+        path: path5,
         message: `unknown built-in 'vectros.${name}' (available: vectros.context, vectros.suffix)`
       });
       return void 0;
     }
     if (!ctx.builtins) {
       ctx.issues.push({
-        path: path4,
+        path: path5,
         message: `'vectros.${name}' is unavailable: contextId must be a literal string to derive built-ins`
       });
       return void 0;
@@ -9151,12 +9259,12 @@ function resolveRef(ns, name, ctx, path4) {
     return ctx.builtins[name];
   }
   ctx.issues.push({
-    path: path4,
+    path: path5,
     message: `unknown namespace '${ns}' in '\${{ ${ns}.${name} }}' (available: inputs, vectros)`
   });
   return void 0;
 }
-function interpolate(str, ctx, path4) {
+function interpolate(str, ctx, path5) {
   let out = "";
   let last = 0;
   TOKEN_SCAN_RE.lastIndex = 0;
@@ -9167,7 +9275,7 @@ function interpolate(str, ctx, path4) {
       out += "${{";
     } else if (m[0] === "${{" && m[1] === void 0) {
       ctx.issues.push({
-        path: path4,
+        path: path5,
         message: `unterminated token '\${{' \u2014 expected a closing '}}' (escape a literal with '$\${{')`
       });
     } else {
@@ -9175,13 +9283,13 @@ function interpolate(str, ctx, path4) {
       const ref = inner.match(INNER_REF_RE);
       if (!ref) {
         ctx.issues.push({
-          path: path4,
+          path: path5,
           message: `malformed reference '\${{ ${inner} }}' \u2014 expected '\${{ namespace.name }}' (escape a literal with '$\${{')`
         });
       } else if (DEFERRED_NAMESPACES.has(ref[1])) {
         out += m[0];
       } else {
-        const v = resolveRef(ref[1], ref[2], ctx, path4);
+        const v = resolveRef(ref[1], ref[2], ctx, path5);
         if (v !== void 0) out += String(v);
       }
     }
@@ -9190,34 +9298,34 @@ function interpolate(str, ctx, path4) {
   out += str.slice(last);
   return out;
 }
-function substituteValue(val, ctx, path4) {
+function substituteValue(val, ctx, path5) {
   if (typeof val === "string") {
     const whole = val.match(WHOLE_TOKEN_RE);
     if (whole) {
       if (DEFERRED_NAMESPACES.has(whole[1])) return val;
-      const v = resolveRef(whole[1], whole[2], ctx, path4);
+      const v = resolveRef(whole[1], whole[2], ctx, path5);
       return v === void 0 ? val : v;
     }
-    return interpolate(val, ctx, path4);
+    return interpolate(val, ctx, path5);
   }
   if (Array.isArray(val)) {
-    return val.map((v, i) => substituteValue(v, ctx, `${path4}[${i}]`));
+    return val.map((v, i) => substituteValue(v, ctx, `${path5}[${i}]`));
   }
   if (val !== null && typeof val === "object") {
     const out = {};
     for (const [k, v] of Object.entries(val)) {
-      out[k] = substituteValue(v, ctx, path4 ? `${path4}.${k}` : k);
+      out[k] = substituteValue(v, ctx, path5 ? `${path5}.${k}` : k);
     }
     return out;
   }
   return val;
 }
 function coerce(raw, type, name, issues) {
-  const path4 = `inputs.${name}`;
+  const path5 = `inputs.${name}`;
   if (type === "string") {
     if (typeof raw === "string") return raw;
     if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
-    issues.push({ path: path4, message: `expected a string value` });
+    issues.push({ path: path5, message: `expected a string value` });
     return void 0;
   }
   if (type === "number") {
@@ -9225,12 +9333,12 @@ function coerce(raw, type, name, issues) {
     if (typeof raw === "string") {
       const n = Number(raw.trim());
       if (raw.trim() === "" || Number.isNaN(n)) {
-        issues.push({ path: path4, message: `expected a number, got '${raw}'` });
+        issues.push({ path: path5, message: `expected a number, got '${raw}'` });
         return void 0;
       }
       return n;
     }
-    issues.push({ path: path4, message: `expected a number` });
+    issues.push({ path: path5, message: `expected a number` });
     return void 0;
   }
   if (typeof raw === "boolean") return raw;
@@ -9238,10 +9346,10 @@ function coerce(raw, type, name, issues) {
     const t = raw.trim().toLowerCase();
     if (t === "true") return true;
     if (t === "false") return false;
-    issues.push({ path: path4, message: `expected a boolean ('true'|'false'), got '${raw}'` });
+    issues.push({ path: path5, message: `expected a boolean ('true'|'false'), got '${raw}'` });
     return void 0;
   }
-  issues.push({ path: path4, message: `expected a boolean` });
+  issues.push({ path: path5, message: `expected a boolean` });
   return void 0;
 }
 function resolveValues(declared, supplied, issues) {
@@ -9693,9 +9801,20 @@ var DATA_PLANE_ACTIONS = [
   "folders:c"
 ];
 var EDITOR_ACTIONS = [...DATA_PLANE_ACTIONS, "records:d", "documents:d", "folders:d"];
+var MEMBER_SHARED_READ_ACTIONS = [
+  "records:r:control",
+  "records:r:convention",
+  "records:r:gotcha",
+  "records:r:term",
+  "documents:r",
+  "search:r",
+  "inference:r",
+  "schemas:r",
+  "folders:r"
+];
 var agenticSdlc = {
   name: "agentic-sdlc",
-  version: "1.3.0",
+  version: "1.6.0",
   description: "A whole-SDLC system of record for an AI development team \u2014 decisions, designs, references, runbooks, post-mortems (as documents) plus controls, conventions, gotchas, and a glossary (as records), cross-linked and recalled by meaning.",
   contextId: "agentic-sdlc",
   contextName: "Agentic SDLC Knowledge Base",
@@ -10394,6 +10513,173 @@ var agenticSdlc = {
         { fieldName: "updatedOn", rangeEnabled: true },
         "sourceRef"
       ]
+    },
+    {
+      // ISOLATED AGENT MEMORY (the "other half" of the KB). Distinct from the
+      // shared records above — which are the team's GLOBAL, curated knowledge —
+      // `memory` is per-principal: a fact an agent (or the human it works for)
+      // records for ITSELF, isolated by ownership via a `${{ self.userId }}`
+      // role dataScope (the private tier; a team tier keyed on a shared scope is
+      // a deliberate future addition, not baked in this version). Deliberately a
+      // SINGLE flexible type so the recall hook queries ONE typeName; the flavor
+      // is the `kind` field, mirroring the file-memory taxonomy it replaces, so
+      // migration is 1:1. Isolation is enforced by the ROLE (type-scoped
+      // `records:*:memory` actions + owner dataScope), NOT the schema — the
+      // schema is tier-agnostic.
+      typeName: "memory",
+      displayName: "Memory",
+      indexMode: "HYBRID",
+      // keyword on the title + semantic on the body (the recalled fact)
+      fields: [
+        {
+          fieldId: "title",
+          fieldType: "string",
+          required: true,
+          searchable: true,
+          validation: { minLength: 1, maxLength: 200 },
+          description: 'A short handle for the memory (the file-memory "name" slug analog).',
+          renderHints: { label: "Title", widget: "text", order: 1, displayField: true }
+        },
+        {
+          fieldId: "body",
+          fieldType: "string",
+          searchable: true,
+          description: "The memory itself \u2014 the durable fact, retrieved by meaning. The RAG-able body.",
+          renderHints: { label: "Body", widget: "textarea", order: 2 }
+        },
+        {
+          // The flavor of memory — mirrors the file-memory frontmatter `type:` so
+          // a migration maps 1:1. `observation` is the episodic/scratch flavor
+          // (TTL-able when the thread tier lands); the rest are durable.
+          fieldId: "kind",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["user", "feedback", "project", "reference", "observation"],
+          renderHints: { label: "Kind", widget: "select", order: 3 }
+        },
+        {
+          // Structure axis 2 of 4: WHAT the memory is about — the same
+          // subsystem/topic label every curated KB type carries, so one `area`
+          // filter narrows recall across curated + memory content uniformly.
+          fieldId: "area",
+          fieldType: "string",
+          filterable: true,
+          description: `Subsystem/topic the memory applies to (e.g. "auth", "search") \u2014 matches the shared types' area vocabulary.`,
+          renderHints: { label: "Area", widget: "text", order: 4 }
+        },
+        {
+          // Structure axis 3: WHICH FUNCTION recorded it. A small stable ROLE
+          // vocabulary (e.g. "pm", "builder", "reviewer") — not an instance id:
+          // instances are already distinguished by the owning principal (who)
+          // + threadId (which conversation).
+          fieldId: "agent",
+          fieldType: "string",
+          filterable: true,
+          description: 'The agent role that recorded it (e.g. "pm", "builder") \u2014 the function, not the instance.',
+          renderHints: { label: "Agent", widget: "text", order: 5 }
+        },
+        {
+          fieldId: "tags",
+          fieldType: "array",
+          filterable: true,
+          description: 'Freeform labels for filtering recall (e.g. "auth", "testing").',
+          renderHints: { label: "Tags", order: 6 }
+        },
+        {
+          // The reversible supersede pattern shared with the records above — a
+          // memory is retired by a status flip, never hard-deleted, so how the
+          // agent's understanding evolved stays inspectable. Promotion to a
+          // higher tier = supersede here + re-create at the new scope.
+          fieldId: "status",
+          fieldType: "enum",
+          filterable: true,
+          enumValues: ["active", "superseded"],
+          renderHints: { label: "Status", widget: "select", order: 7 }
+        },
+        {
+          // Structure axis 4: WHICH CONVERSATION (episodic slice). The caller's
+          // session/thread identifier — whatever the agent runtime calls it. A
+          // lookup filter WITHIN what the principal owns, NOT an isolation
+          // boundary; sessions of the same principal share trust.
+          fieldId: "threadId",
+          fieldType: "string",
+          filterable: true,
+          description: "Optional conversation/thread id (your runtime's session identifier) \u2014 slices episodic memory within your own store.",
+          renderHints: { label: "Thread", widget: "text", order: 8 }
+        },
+        {
+          fieldId: "updatedOn",
+          fieldType: "date",
+          description: 'ISO-8601 \u2014 when last revised. Range-queryable \u2014 "what did I learn this week".',
+          renderHints: { label: "Updated on", widget: "date", order: 9 }
+        },
+        {
+          // Importance BAND for the always-load pinned set + recall ranking. Coarse bands
+          // (0 normal / 10 pinned / 20 high / 30 critical) — pick a band, not a fiddly
+          // integer, to avoid priority inflation. NULLABLE and set only on the elevated
+          // subset, so the range-index cost lands only on that low-cardinality set (normal
+          // memories write no range row). Orientation enumerates `priority order=desc
+          // limit=X` — the read query IS the cap (overflow falls below the cutoff, never
+          // evicted). MEMORY-ONLY: a pin is a memory that REFERENCES a curated item, it
+          // never pins the curated item in place (pins = always-load; curated KB = recalled
+          // when relevant).
+          fieldId: "priority",
+          fieldType: "number",
+          filterable: true,
+          description: "Importance band (0/10/20/30) for the always-load pinned set + recall ranking. Optional \u2014 set only on elevated memories.",
+          renderHints: { label: "Priority", order: 10 }
+        },
+        {
+          // Opaque provenance — the file / issue / URL this memory is ABOUT (records parity
+          // with the curated types' sourceRef). Not a typed graph edge.
+          fieldId: "sourceRef",
+          fieldType: "string",
+          description: "Provenance: the file path / issue / URL this memory is about.",
+          renderHints: { label: "Source ref", widget: "text", order: 11 }
+        },
+        {
+          // The evolution/promotion trail WITHIN memory (self-ref, SAME owner): the memory
+          // that replaced this one. Pairs with ARCHIVE-retire. Promotion to the curated tier
+          // is copy-up + archive-down with NO shared->private back-reference, so a curated
+          // (shared) artifact never embeds a private memory's id/slug.
+          fieldId: "supersededBy",
+          fieldType: "reference",
+          targetTypeName: "memory",
+          targetSurface: "record",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "The memory that superseded this one (by externalId) \u2014 the evolution trail.",
+          renderHints: { label: "Superseded by", order: 12 }
+        },
+        {
+          // The `[[see-also]]` link between a principal's own memories (self-ref, SAME
+          // owner). One-cardinality in this version (the proven reference shape); a
+          // many-cardinality see-also graph is a later extension.
+          fieldId: "relatedTo",
+          fieldType: "reference",
+          targetTypeName: "memory",
+          targetSurface: "record",
+          targetField: "externalId",
+          cardinality: "one",
+          description: "A related memory (by externalId) \u2014 the see-also link within your own store.",
+          renderHints: { label: "Related to", order: 13 }
+        }
+      ],
+      // externalId is the memory's stable slug (the file-memory `name:`) — the idempotent
+      // upsert key — sent top-level, not declared as a field.
+      // ⚖ LEAN by design: `memory` is the HIGHEST-VOLUME, churniest record here, so it only
+      // carries lookups for fields we ENUMERATE DETERMINISTICLY. `area`/`agent`/`status` are
+      // `filterable` (typed SEARCH metadata — narrow recall without a per-write lookup row),
+      // NOT lookups; `sourceRef` is a plain provenance field. A typical write pays just
+      // `kind` (eq) + `updatedOn` (range); `threadId`/`priority` cost only when set (both
+      // nullable). Contrast the curated types, which carry more lookups because they are
+      // low-volume and repo-synced (`sourceRef` enumeration).
+      lookupFields: [
+        "kind",
+        "threadId",
+        { fieldName: "updatedOn", rangeEnabled: true },
+        { fieldName: "priority", rangeEnabled: true }
+      ]
     }
   ],
   // Least-privilege, data-plane only. The scope of the `ssk_*` key the bootstrap
@@ -10416,7 +10702,41 @@ var agenticSdlc = {
   // owner may permanently remove genuine strays. Still no control-plane action, so
   // the scope gate accepts it as a data-plane-only role.
   roles: {
-    editor: [{ allowedActions: EDITOR_ACTIONS }]
+    // The human curator. NOTE: this role is deliberately UNSCOPED (whole-context),
+    // which includes members' private memory — the trusted-administrator tradeoff,
+    // called out in the bundled guide. Scope it down if your deployment wants
+    // curator access without private-memory visibility.
+    editor: [{ allowedActions: EDITOR_ACTIONS }],
+    // A team member (or their agent) — TWO memory tiers as two UNIONed clauses
+    // (a record is accessible when ANY clause grants it; within one clause every
+    // dataScope dimension must match):
+    //   1) the CURATED shared KB (+ semantic recall). UNSCOPED, but safe: search
+    //      and grounded answers are enforced per row against the per-type action
+    //      qualifier, so recall over this clause admits only the content it grants
+    //      a TYPED read for (the curated record types + documents) — never the
+    //      `memory` type, so a member's recall never returns another principal's
+    //      private memory.
+    //   2) PRIVATE memory: the member's OWN `memory` records, isolated per-request
+    //      by `${{ self.userId }}` (the principal dimension — the stable ownership
+    //      axis, unaffected by the evolution of shared/team scopes).
+    // Team-shared *working* memory (a group-owned tier every member reads and
+    // writes) is a planned addition, intentionally NOT in this version: it rides
+    // the ownership axis for shared scopes, which is being finalized, and this
+    // blueprint avoids baking a shape that is about to change. Bind with
+    // `vectros join agentic-sdlc --role member`; verify a binding with
+    // `vectros access explain --principal me --context agentic-sdlc`.
+    member: [
+      { allowedActions: MEMBER_SHARED_READ_ACTIONS },
+      {
+        // `inference:r` is IN this self-scoped clause (not only clause 1) so a
+        // member's `rag_ask` can ground on its OWN private memory — the read
+        // grant (`records:r:memory`) and the inference capability travel in the
+        // SAME clause, so grounding works regardless of cross-clause admission
+        // semantics. Still self-fenced by dataScope: never another principal's.
+        allowedActions: ["records:cru:memory", "search:r", "inference:r"],
+        dataScope: { userId: ["${{ self.userId }}"] }
+      }
+    ]
   },
   servicePrincipal: {
     externalId: "agentic-sdlc",
@@ -10844,13 +11164,13 @@ async function mintBridgeToken(opts) {
     fetchImpl = fetch
   } = opts;
   const base = apiBaseUrl.replace(/\/$/, "");
-  const path4 = bridgeTokenPath(useScopedToken);
-  const url = `${base}${path4}?ttl=${encodeURIComponent(String(ttlSeconds))}&tenant=${encodeURIComponent(tenant)}`;
+  const path5 = bridgeTokenPath(useScopedToken);
+  const url = `${base}${path5}?ttl=${encodeURIComponent(String(ttlSeconds))}&tenant=${encodeURIComponent(tenant)}`;
   return fetchStToken(
     url,
     cognitoToken,
     fetchImpl,
-    path4,
+    path5,
     (status) => status === 404 && !useScopedToken ? ` (the dedicated ${CLI_BOOTSTRAP_TOKEN_PATH} endpoint may not be deployed yet \u2014 retry with --use-scoped-token for the fallback path)` : ""
   );
 }
@@ -11356,6 +11676,54 @@ async function readPersistedKey(pack, dir = vectrosHomeDir()) {
   }
 }
 
+// src/identity-resolver.ts
+function userPayload(decl) {
+  const meta = decl.metadata;
+  if (decl.displayName === void 0) return meta;
+  return { displayName: decl.displayName, ...meta ?? {} };
+}
+function requireId(id, kind, externalId) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error(`identity ${kind} '${externalId}' create returned no id \u2014 cannot substitute its token.`);
+  }
+  return id;
+}
+function makeIdentityResolver(client, log) {
+  return async (name, decl) => {
+    switch (decl.kind) {
+      case "user": {
+        const u = await client.identity.createUser({
+          body: { externalId: decl.externalId, type: "HUMAN", payload: userPayload(decl) }
+        });
+        const id = requireId(u.id, "user", decl.externalId);
+        log.debug({ component: "identity-resolver", name, kind: "user", externalId: decl.externalId, id }, "identity ensured");
+        return id;
+      }
+      case "org": {
+        const o = await client.identity.createOrg({
+          body: { externalId: decl.externalId, name: decl.displayName, payload: decl.metadata }
+        });
+        const id = requireId(o.id, "org", decl.externalId);
+        log.debug({ component: "identity-resolver", name, kind: "org", externalId: decl.externalId, id }, "identity ensured");
+        return id;
+      }
+      case "client": {
+        const c = await client.identity.createClient({
+          body: { externalId: decl.externalId, name: decl.displayName, payload: decl.metadata }
+        });
+        const id = requireId(c.id, "client", decl.externalId);
+        log.debug({ component: "identity-resolver", name, kind: "client", externalId: decl.externalId, id }, "identity ensured");
+        return id;
+      }
+    }
+  };
+}
+async function resolveApplyTimeIdentities(blueprint, client, log) {
+  const resolver = makeIdentityResolver(client, log);
+  const resolved = await resolveBlueprintIdentities(blueprint, resolver);
+  return parseBlueprint(resolved);
+}
+
 // src/loader.ts
 var LostKeyError = class extends Error {
   constructor(keyName) {
@@ -11447,7 +11815,7 @@ function assertNoUnresolvedIdentities(blueprint) {
   if (hasBlock || refs.length > 0) {
     const detail = hasBlock ? `declares an 'identities' block` : `references ${refs.map((r) => `\${{ identities.${r} }}`).join(", ")}`;
     throw new UnresolvedIdentitiesError(
-      `Blueprint ${detail}, but the CLI loader does not yet resolve identities. Applying it would write literal '\${{ identities.* }}' tokens into ownership/dataScope fields. Remove the identities usage, or wait for identity-resolution support.`
+      `Blueprint ${detail} that reached the loader UNRESOLVED \u2014 apply-time identity resolution did not run before provisioning (an internal wiring error). Applying it would write literal '\${{ identities.* }}' tokens into ownership/dataScope fields. This is a defense-in-depth backstop; resolution happens in the CLI apply orchestrator (resolveApplyTimeIdentities) before the loader.`
     );
   }
 }
@@ -11519,7 +11887,12 @@ async function runLoader(client, input) {
         // to the SDK's loosely-typed Record<string, Record<string,unknown>>.
         data_scope: blueprint.accessProfile.dataScope
       }
-    ]
+    ],
+    // Optional identity overrides — scope values the service key STAMPS onto
+    // everything it writes (e.g. the blueprint's team org, so the curated
+    // knowledge it seeds/writes is org-owned). `${{ identities.* }}` tokens
+    // were substituted before the loader ran.
+    identityOverrides: blueprint.accessProfile.identityOverrides
     // NB: `status` is intentionally omitted — the SDK's body type does not model it
     // and the platform defaults a new profile to 'active' (the only status the loader
     // ever wants). Sending it was redundant.
@@ -11595,7 +11968,9 @@ async function runLoader(client, input) {
           schemaId,
           externalId: rec.externalId,
           // Optional structured payload (the document's `fields`); omitted when absent.
-          payload: rec.fields
+          payload: rec.fields,
+          // Optional scope ownership (`namespace:value` entries; `[]` = private).
+          scopes: rec.scopes
         }
       });
       if (created.id) seededDocumentIds.push(created.id);
@@ -11605,7 +11980,8 @@ async function runLoader(client, input) {
           typeName: rec.typeName,
           schemaId,
           externalId: rec.externalId,
-          payload: rec.fields
+          payload: rec.fields,
+          scopes: rec.scopes
         }
       });
       if (created.id) seededRecordIds.push(created.id);
@@ -11766,7 +12142,6 @@ function validateBlueprint(input) {
   for (const clauses of Object.values(blueprint.roles ?? {})) {
     for (const clause of clauses) assertScopeGate(clause.allowedActions);
   }
-  assertNoUnresolvedIdentities(blueprint);
   return blueprint;
 }
 var BLANK_SLATE = {
@@ -12022,13 +12397,6 @@ ${BOOTSTRAP_HELP}
         process.stderr.write("  Minting nothing.\n");
         return 2;
       }
-      if (err instanceof UnresolvedIdentitiesError) {
-        process.stderr.write(`
-  \u2716 ${err.message}
-  Minting nothing.
-`);
-        return 2;
-      }
       throw err;
     }
     const gate = evaluateScopeGate(blueprint.accessProfile.allowedActions);
@@ -12053,6 +12421,14 @@ ${BOOTSTRAP_HELP}
     process.stdout.write(`
 ${renderPlan(blueprint, planSteps)}
 `);
+    const declaredIdentities = Object.entries(blueprint.identities ?? {});
+    if (declaredIdentities.length > 0) {
+      process.stdout.write("\n  Identities to ensure (tenant-wide, idempotent by external id):\n");
+      for (const [name, decl] of declaredIdentities) {
+        process.stdout.write(`    ~ ${name} (${decl.kind}) \u2014 external id '${decl.externalId}'
+`);
+      }
+    }
     if (!args.yes && !args.print && isTty) {
       const ans = (await promptCtx.prompt("\n  Apply this plan? [y/N]: ")).trim().toLowerCase();
       if (ans !== "y" && ans !== "yes") {
@@ -12077,17 +12453,25 @@ ${renderPlan(blueprint, planSteps)}
     });
     process.stdout.write(`  \u2714 Bootstrap token minted (5-min TTL, ${args.tenant} tenant)
 `);
+    const pingIdentity = deps.resolveIdentity ?? resolveIdentity;
+    const resolveIdentities = deps.resolveApplyTimeIdentities ?? resolveApplyTimeIdentities;
+    const loader = deps.runLoader ?? runLoader;
     const client = new VectrosClient({ token: bridge.token, environment: baseUrl });
-    const identity = await resolveIdentity({ log, apiKey: bridge.token, environment: baseUrl });
+    const identity = await pingIdentity({ log, apiKey: bridge.token, environment: baseUrl });
     const tenantId = identity.tenantId;
     if (!tenantId || typeof tenantId !== "string") {
       throw new Error(
         "Could not resolve tenantId from /v1/ping \u2014 the extended ping (tenant_id) must be deployed for bootstrap."
       );
     }
-    const machineId = await resolveMachineId();
-    const result = await runLoader(client, {
+    const resolvedBlueprint = await resolveIdentities(
       blueprint,
+      client,
+      log
+    );
+    const machineId = await resolveMachineId();
+    const result = await loader(client, {
+      blueprint: resolvedBlueprint,
       tenantId,
       machineId,
       rotate: args.rotate,
@@ -12165,6 +12549,13 @@ ${codeAddHint}`);
 `);
       return 3;
     }
+    if (err instanceof BlueprintIdentityError || err instanceof UnresolvedIdentitiesError) {
+      process.stderr.write(`
+  \u2716 ${err.message}
+  No context or key was provisioned.
+`);
+      return 2;
+    }
     process.stderr.write(`
   \u2716 Bootstrap failed: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -12444,13 +12835,6 @@ async function resolveAndValidate(arg, verb, supplied) {
     }
     throw err;
   }
-  try {
-    assertNoUnresolvedIdentities(blueprint);
-  } catch (err) {
-    process.stderr.write(`  \u2716 ${err instanceof Error ? err.message : String(err)}
-`);
-    return null;
-  }
   const findings = lintBlueprint(blueprint);
   for (const f of findings) {
     const mark = f.severity === "error" ? "\u2716" : "\u26A0";
@@ -12498,6 +12882,14 @@ async function runPlan(args) {
   process.stdout.write(`
 ${renderPlan(blueprint, steps)}
 `);
+  const declaredIdentities = Object.entries(blueprint.identities ?? {});
+  if (declaredIdentities.length > 0) {
+    process.stdout.write("\n  Identities to ensure (tenant-wide, idempotent by external id):\n");
+    for (const [name, decl] of declaredIdentities) {
+      process.stdout.write(`    ~ ${name} (${decl.kind}) \u2014 external id '${decl.externalId}'
+`);
+    }
+  }
   const setEcho = [...args.set].join(" --set ");
   process.stdout.write(
     `
@@ -12696,6 +13088,18 @@ function normalizePrincipalUserId(principal) {
 function splitCsv(csv) {
   return csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
 }
+function parseJsonObjectFlag(flag, raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${flag} is not valid JSON: ${raw}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${flag} must be a JSON object (e.g. '{"userId":["<id>"]}').`);
+  }
+  return parsed;
+}
 
 // src/paginate.ts
 var PAGE_LIMIT = 100;
@@ -13191,6 +13595,23 @@ async function runAccessGrant(opts, deps = {}) {
     process.stderr.write("  \u2716 Provide exactly one of --role <roleId> or --actions <csv>.\n");
     return 2;
   }
+  if (hasActions && splitCsv(opts.actions).length === 0) {
+    process.stderr.write("  \u2716 --actions needs at least one action (an empty/blank list grants nothing).\n");
+    return 2;
+  }
+  let identityOverrides;
+  if (opts.org || opts.identityOverrides) {
+    try {
+      identityOverrides = {
+        ...opts.org ? { orgId: opts.org } : {},
+        ...opts.identityOverrides ? parseJsonObjectFlag("--identity-overrides", opts.identityOverrides) : {}
+      };
+    } catch (err) {
+      process.stderr.write(`  \u2716 ${formatError(err)}
+`);
+      return 2;
+    }
+  }
   if (opts.principal !== SELF_PRINCIPAL_ALIAS) {
     try {
       assertPrincipalShape(opts.principal);
@@ -13207,10 +13628,12 @@ async function runAccessGrant(opts, deps = {}) {
       const scopes = hasActions ? [{ allowed_actions: splitCsv(opts.actions) }] : void 0;
       const profile = await client.auth.createAccessProfile({
         contextId: opts.context,
+        upsert: true,
         body: {
           principalId: principal,
           roleId: opts.role,
-          scopes
+          scopes,
+          identityOverrides
         }
       });
       if (opts.json) {
@@ -13333,6 +13756,166 @@ ${renderProfile(p)}
   });
 }
 
+// src/commands/access-explain.ts
+var SELF = /* @__PURE__ */ Symbol("self");
+function canonicalDim(key) {
+  if (key === "userId" || key === "partnerUserId") return "user";
+  if (key === "orgId") return "scope:org";
+  if (key === "clientId") return "scope:client";
+  return key;
+}
+var SELF_TOKEN_RE2 = /^\$\{\{\s*self\.[a-zA-Z.]+\s*\}\}$/;
+function normalizeClauses(raw) {
+  const out = [];
+  for (const c of raw) {
+    if (!c || typeof c !== "object") continue;
+    const obj = c;
+    const actions = obj.allowed_actions ?? obj.allowedActions ?? [];
+    const ds = obj.data_scope ?? obj.dataScope ?? {};
+    const dataScope = {};
+    for (const [k, v] of Object.entries(ds)) {
+      const values = Array.isArray(v) ? v : [v];
+      dataScope[canonicalDim(k)] = values.map((val) => {
+        if (val === null) return null;
+        const s = String(val);
+        return SELF_TOKEN_RE2.test(s) ? SELF : s;
+      });
+    }
+    out.push({ actions: Array.isArray(actions) ? actions.map(String) : [], dataScope });
+  }
+  return out;
+}
+function buildArchetypes(clauses) {
+  const rows = [
+    { label: "a record you own alone (private)", owners: { user: SELF } },
+    { label: "another user's private record", owners: { user: "someone-else" } }
+  ];
+  const scopeDims = /* @__PURE__ */ new Map();
+  for (const c of clauses) {
+    for (const [dim, values] of Object.entries(c.dataScope)) {
+      if (dim === "user") continue;
+      const set = scopeDims.get(dim) ?? /* @__PURE__ */ new Set();
+      for (const v of values) if (v !== null) set.add(v);
+      scopeDims.set(dim, set);
+    }
+  }
+  for (const [dim, values] of scopeDims) {
+    for (const v of values) {
+      const shown = v === SELF ? `your ${dim.replace("scope:", "")}` : `${dim}=${String(v)}`;
+      rows.push({ label: `yours, shared to ${shown}`, owners: { user: SELF, [dim]: v } });
+      rows.push({ label: `another user's, shared to ${shown}`, owners: { user: "someone-else", [dim]: v } });
+      rows.push({ label: `${shown} only (no user owner)`, owners: { [dim]: v } });
+    }
+    rows.push({
+      label: `another user's, in a DIFFERENT ${dim.replace("scope:", "")}`,
+      owners: { user: "someone-else", [dim]: `other-${dim.replace("scope:", "")}` }
+    });
+  }
+  rows.push({ label: "no owner values at all (tenant-shared)", owners: {} });
+  return rows;
+}
+function clauseMatches(clause, arch) {
+  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;
+  }
+  return true;
+}
+function explainClauses(clauses) {
+  const archetypes = buildArchetypes(clauses);
+  return archetypes.map((arch) => {
+    const matched = [];
+    const actions = /* @__PURE__ */ new Set();
+    clauses.forEach((c, i) => {
+      if (clauseMatches(c, arch)) {
+        matched.push(i + 1);
+        for (const a of c.actions) actions.add(a);
+      }
+    });
+    return { archetype: arch.label, clauses: matched, actions: [...actions] };
+  });
+}
+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 ");
+}
+var SELF_PRINCIPAL_ALIAS2 = "me";
+async function runAccessExplain(opts, deps = {}) {
+  return withAuth(opts, deps, async (auth) => {
+    const client = auth.client;
+    try {
+      let principal = opts.principal;
+      if (principal === SELF_PRINCIPAL_ALIAS2) {
+        const self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
+        if (!self2) {
+          process.stderr.write(
+            "  \u2716 Could not resolve your own user id from your login. Pass --principal usr_<id> explicitly.\n"
+          );
+          return 1;
+        }
+        principal = self2.principalId;
+      }
+      const profile = await client.auth.getAccessProfile({ contextId: opts.context, principalId: principal });
+      let rawClauses = profile.scopes ?? [];
+      let via = "inline scopes";
+      if (profile.roleId) {
+        const role = await client.auth.getRole({ contextId: opts.context, roleId: profile.roleId });
+        rawClauses = role.scopes ?? [];
+        via = `role '${profile.roleId}'`;
+      }
+      const clauses = normalizeClauses(rawClauses);
+      const rows = explainClauses(clauses);
+      if (opts.json) {
+        process.stdout.write(
+          `${formatJson({
+            principal,
+            context: opts.context,
+            via,
+            identityOverrides: profile.identityOverrides,
+            clauses: clauses.map((c, i) => ({ n: i + 1, actions: c.actions, dataScope: renderDataScope(c.dataScope) })),
+            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."
+          })}
+`
+        );
+        return 0;
+      }
+      process.stdout.write(`
+  ${principal} in '${opts.context}' \u2014 via ${via}
+`);
+      if (profile.identityOverrides && Object.keys(profile.identityOverrides).length > 0) {
+        process.stdout.write(`  identity overrides: ${JSON.stringify(profile.identityOverrides)}
+`);
+      }
+      process.stdout.write("\n  Clauses (a record is accessible when ANY clause grants it):\n");
+      clauses.forEach((c, i) => {
+        process.stdout.write(`    ${i + 1}. [${c.actions.join(", ")}]  where ${renderDataScope(c.dataScope)}
+`);
+      });
+      process.stdout.write(
+        "\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"
+      );
+      return 0;
+    } catch (err) {
+      process.stderr.write(`  \u2716 access explain failed: ${formatError(err)}
+`);
+      return 1;
+    }
+  });
+}
+
 // src/commands/role.ts
 function renderRole(r) {
   return formatKeyValues([
@@ -13349,6 +13932,16 @@ async function runRoleCreate(opts, deps = {}) {
     process.stderr.write("  \u2716 --actions must list at least one action (e.g. records:cru,search:r).\n");
     return 2;
   }
+  let dataScope;
+  if (opts.dataScope !== void 0) {
+    try {
+      dataScope = parseJsonObjectFlag("--data-scope", opts.dataScope);
+    } catch (err) {
+      process.stderr.write(`  \u2716 ${formatError(err)}
+`);
+      return 2;
+    }
+  }
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
@@ -13358,7 +13951,11 @@ async function runRoleCreate(opts, deps = {}) {
           roleId: opts.roleId,
           name: opts.name,
           description: opts.description,
-          scopes: [{ allowed_actions: actions }]
+          // data_scope is included only when supplied — the clause wire shape
+          // stays byte-identical for unscoped roles.
+          scopes: [
+            dataScope ? { allowed_actions: actions, data_scope: dataScope } : { allowed_actions: actions }
+          ]
         }
       });
       if (opts.json) {
@@ -13990,7 +14587,12 @@ async function runTeardown(client, blueprint, machineId, snapshot, result) {
   return steps;
 }
 async function runBlueprintHarness(client, input, deps) {
-  const { blueprint, tenantId, machineId, vectrosDir, keep = false, log, remintForContext } = input;
+  const { tenantId, machineId, vectrosDir, keep = false, log, remintForContext } = input;
+  const blueprint = await resolveApplyTimeIdentities(
+    input.blueprint,
+    client,
+    log
+  );
   const remint = remintForContext ?? (async () => client);
   let snapshot;
   if (remintForContext) {
@@ -14164,11 +14766,461 @@ async function runBlueprintTest(fileOrName, opts, deps = {}) {
   });
 }
 
+// src/keyring.ts
+var import_node_fs4 = require("fs");
+var import_node_path5 = __toESM(require("path"));
+var import_node_crypto4 = require("crypto");
+var KEYRING_FILE = "keyring.json";
+var SALT_FILE = "keyring.salt";
+var SECRETS_DIR = "secrets";
+var ALGO = "aes-256-gcm";
+var IV_LEN = 12;
+var TAG_LEN = 16;
+function keyringPath(dir = vectrosHomeDir()) {
+  return import_node_path5.default.join(dir, KEYRING_FILE);
+}
+var CryptoFileSecretStore = class {
+  dir;
+  keyPromise;
+  constructor(dir = vectrosHomeDir()) {
+    this.dir = dir;
+  }
+  secretsDir() {
+    return import_node_path5.default.join(this.dir, SECRETS_DIR);
+  }
+  secretPath(ref) {
+    return import_node_path5.default.join(this.secretsDir(), `${encodeURIComponent(ref)}.enc`);
+  }
+  /** Resolve (and cache) the machine-derived AES key, creating the salt once. */
+  async encryptionKey() {
+    if (!this.keyPromise) {
+      this.keyPromise = (async () => {
+        const machineId = await resolveMachineId(this.dir);
+        const salt = await this.readOrCreateSalt();
+        return (0, import_node_crypto4.scryptSync)(machineId, salt, 32);
+      })();
+    }
+    return this.keyPromise;
+  }
+  async readOrCreateSalt() {
+    const saltPath = import_node_path5.default.join(this.dir, SALT_FILE);
+    try {
+      const existing = await import_node_fs4.promises.readFile(saltPath);
+      if (existing.length >= 16) return existing;
+    } catch {
+    }
+    const salt = (0, import_node_crypto4.randomBytes)(16);
+    await import_node_fs4.promises.mkdir(this.dir, { recursive: true });
+    await import_node_fs4.promises.writeFile(saltPath, salt, { mode: 384 });
+    return salt;
+  }
+  async setSecret(ref, secret) {
+    const key = await this.encryptionKey();
+    const iv = (0, import_node_crypto4.randomBytes)(IV_LEN);
+    const cipher = (0, import_node_crypto4.createCipheriv)(ALGO, key, iv);
+    const enc = Buffer.concat([cipher.update(secret, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const blob = Buffer.concat([iv, tag, enc]);
+    await import_node_fs4.promises.mkdir(this.secretsDir(), { recursive: true });
+    await import_node_fs4.promises.writeFile(this.secretPath(ref), blob.toString("base64"), {
+      encoding: "utf8",
+      mode: 384
+    });
+  }
+  async getSecret(ref) {
+    let blob;
+    try {
+      blob = Buffer.from((await import_node_fs4.promises.readFile(this.secretPath(ref), "utf8")).trim(), "base64");
+    } catch {
+      return void 0;
+    }
+    if (blob.length <= IV_LEN + TAG_LEN) return void 0;
+    try {
+      const key = await this.encryptionKey();
+      const iv = blob.subarray(0, IV_LEN);
+      const tag = blob.subarray(IV_LEN, IV_LEN + TAG_LEN);
+      const enc = blob.subarray(IV_LEN + TAG_LEN);
+      const decipher = (0, import_node_crypto4.createDecipheriv)(ALGO, key, iv);
+      decipher.setAuthTag(tag);
+      return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8");
+    } catch {
+      return void 0;
+    }
+  }
+  async deleteSecret(ref) {
+    try {
+      await import_node_fs4.promises.rm(this.secretPath(ref));
+    } catch {
+    }
+  }
+};
+async function readKeyring(dir = vectrosHomeDir()) {
+  let raw;
+  try {
+    raw = await import_node_fs4.promises.readFile(keyringPath(dir), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return { version: 1, entries: [] };
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Keyring index at ${keyringPath(dir)} is corrupt (invalid JSON). Fix or remove the file.`);
+  }
+  if (!Array.isArray(parsed.entries)) {
+    throw new Error(`Keyring index at ${keyringPath(dir)} is malformed (no entries array). Fix or remove the file.`);
+  }
+  return { version: 1, active: parsed.active, entries: parsed.entries };
+}
+async function writeKeyring(kr, dir = vectrosHomeDir()) {
+  await import_node_fs4.promises.mkdir(dir, { recursive: true });
+  const finalPath = keyringPath(dir);
+  const tmpPath = `${finalPath}.${process.pid}.${(0, import_node_crypto4.randomBytes)(4).toString("hex")}.tmp`;
+  await import_node_fs4.promises.writeFile(tmpPath, `${JSON.stringify(kr, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+  await import_node_fs4.promises.rename(tmpPath, finalPath);
+}
+var Keyring = class {
+  dir;
+  store;
+  constructor(deps = {}) {
+    this.dir = deps.dir ?? vectrosHomeDir();
+    this.store = deps.store ?? new CryptoFileSecretStore(this.dir);
+  }
+  /**
+   * This machine's stable id — used to namespace a scoped-key NAME so each
+   * machine holds its OWN independently-rotatable `ssk_*` under one shared
+   * (idempotent) AccessProfile (see `machine-id.ts`). Resolved from the SAME
+   * dir the secrets live in, so a test keyring rooted at a temp dir stays
+   * self-consistent.
+   */
+  async machineId() {
+    return resolveMachineId(this.dir);
+  }
+  async list() {
+    return (await readKeyring(this.dir)).entries;
+  }
+  async get(alias) {
+    return (await this.list()).find((e) => e.alias === alias);
+  }
+  async activeAlias() {
+    return (await readKeyring(this.dir)).active;
+  }
+  async getActive() {
+    const kr = await readKeyring(this.dir);
+    return kr.active ? kr.entries.find((e) => e.alias === kr.active) : void 0;
+  }
+  /**
+   * Upsert an entry (by alias) and store its secret. Activates it by default —
+   * `join` wants the freshly-created identity to become current.
+   */
+  async add(entry, secret, opts = {}) {
+    const kr = await readKeyring(this.dir);
+    const prior = kr.entries.find((e) => e.alias === entry.alias);
+    await this.store.setSecret(entry.secretRef, secret);
+    if (prior && prior.secretRef !== entry.secretRef) {
+      await this.store.deleteSecret(prior.secretRef);
+    }
+    const entries = kr.entries.filter((e) => e.alias !== entry.alias);
+    entries.push(entry);
+    const active = opts.activate === false ? kr.active : entry.alias;
+    await writeKeyring({ version: 1, active, entries }, this.dir);
+  }
+  /** Point the active alias at an existing entry. Throws if the alias is unknown. */
+  async setActive(alias) {
+    const kr = await readKeyring(this.dir);
+    if (!kr.entries.some((e) => e.alias === alias)) {
+      throw new Error(`No keyring entry named '${alias}'. Run \`vectros keyring list\` to see entries.`);
+    }
+    await writeKeyring({ ...kr, version: 1, active: alias }, this.dir);
+  }
+  /** Remove an entry + its secret. Clears the active pointer if it named this alias. Returns true if removed. */
+  async remove(alias) {
+    const kr = await readKeyring(this.dir);
+    const entry = kr.entries.find((e) => e.alias === alias);
+    if (!entry) return false;
+    await this.store.deleteSecret(entry.secretRef);
+    const entries = kr.entries.filter((e) => e.alias !== alias);
+    const active = kr.active === alias ? void 0 : kr.active;
+    await writeKeyring({ version: 1, active, entries }, this.dir);
+    return true;
+  }
+  /** The raw secret for a named entry (via the secret store), or undefined. */
+  async resolveSecret(alias) {
+    const entry = await this.get(alias);
+    return entry ? this.store.getSecret(entry.secretRef) : void 0;
+  }
+  /** The raw secret for the active entry, or undefined if none is active. */
+  async resolveActiveSecret() {
+    const entry = await this.getActive();
+    return entry ? this.store.getSecret(entry.secretRef) : void 0;
+  }
+};
+
+// src/commands/join.ts
+var SELF_ALIAS = "me";
+async function resolvePrincipal(as, auth) {
+  const raw = as ?? SELF_ALIAS;
+  if (raw === SELF_ALIAS) {
+    const self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
+    if (!self2) {
+      throw new Error(
+        "Could not resolve your own user id from your login. Pass --as usr_<id> explicitly (find it with `vectros identity list --type user`)."
+      );
+    }
+    return self2.principalId;
+  }
+  if (!raw.startsWith("usr_")) {
+    throw new Error(`--as must be 'me' or 'usr_<id>' (got '${raw}').`);
+  }
+  return raw;
+}
+async function issueOrRotateKey(client, tenantId, context, userId, keyName) {
+  const first = await client.auth.createScopedKey({ keyName, tenantId, contextId: context, userId });
+  if (first.rawKey) return first;
+  const existing = (await drainPages(() => client.auth.listScopedKeys())).find(
+    (k) => k.contextId === context && k.userId === userId && k.keyName === keyName && k.status === "active"
+  );
+  if (existing?.keyId) await client.auth.revokeScopedKey({ keyId: existing.keyId });
+  const rotated = await client.auth.createScopedKey({ keyName, tenantId, contextId: context, userId });
+  if (!rotated.rawKey) {
+    throw new Error(
+      "The key already exists and its secret could not be re-minted (the prior key may not have cleared yet). Retry shortly."
+    );
+  }
+  return rotated;
+}
+async function runJoin(opts, deps = {}) {
+  const hasRole = Boolean(opts.role);
+  const hasActions = Boolean(opts.actions);
+  if (hasRole === hasActions) {
+    process.stderr.write("  \u2716 Provide exactly one of --role <roleId> or --actions <csv>.\n");
+    return 2;
+  }
+  if (hasActions && splitCsv(opts.actions).length === 0) {
+    process.stderr.write("  \u2716 --actions needs at least one action (an empty/blank list grants nothing).\n");
+    return 2;
+  }
+  if (opts.as && opts.as !== SELF_ALIAS && !opts.as.startsWith("usr_")) {
+    process.stderr.write(`  \u2716 --as must be 'me' or 'usr_<id>' (got '${opts.as}').
+`);
+    return 2;
+  }
+  const context = opts.contextArg;
+  const alias = opts.alias ?? context;
+  const keyring = deps.keyring ?? new Keyring();
+  return withAuth({ ...opts, context }, deps, async (auth) => {
+    const client = auth.client;
+    try {
+      const tenantId = requireTenantId(auth);
+      const principalId = await resolvePrincipal(opts.as, auth);
+      const userId = normalizePrincipalUserId(principalId);
+      const scopes = hasActions ? [{ allowed_actions: splitCsv(opts.actions) }] : void 0;
+      await client.auth.createAccessProfile({
+        contextId: context,
+        upsert: true,
+        body: {
+          principalId,
+          roleId: opts.role,
+          scopes,
+          identityOverrides: opts.org ? { orgId: opts.org } : void 0
+        }
+      });
+      const existingEntry = await keyring.get(alias);
+      const heldSecret = existingEntry ? await keyring.resolveSecret(alias) : void 0;
+      const canReuse = existingEntry && heldSecret && existingEntry.context === context && existingEntry.principalId === principalId && existingEntry.env === auth.env;
+      if (canReuse && existingEntry) {
+        await keyring.setActive(alias);
+        emitJoined(alias, context, principalId, opts.role, existingEntry.keyId, true);
+        return 0;
+      }
+      if (existingEntry) {
+        process.stdout.write(
+          `
+  \u26A0 Replacing keyring entry '${alias}' (was ${existingEntry.principalId} in '${existingEntry.context}' @ ${existingEntry.env}). Pass --alias to keep both.
+`
+        );
+      }
+      const keyName = keyNameFor(context, await keyring.machineId());
+      const key = await issueOrRotateKey(client, tenantId, context, userId, keyName);
+      if (!key.keyId) {
+        throw new Error(
+          "The minted key has no id \u2014 it could not be recorded or later rotated. Retry, or use `vectros key issue`."
+        );
+      }
+      const entry = {
+        alias,
+        context,
+        principalId,
+        role: opts.role,
+        keyId: key.keyId,
+        env: auth.env,
+        secretRef: key.keyId,
+        createdAt: nowIso()
+      };
+      await keyring.add(entry, key.rawKey, { activate: true });
+      emitJoined(alias, context, principalId, opts.role, entry.keyId, false);
+      return 0;
+    } catch (err) {
+      process.stderr.write(`  \u2716 join failed: ${formatError(err)}
+`);
+      return 1;
+    }
+  });
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function emitJoined(alias, context, principalId, role, keyId, reused) {
+  process.stdout.write(
+    `
+  \u2714 Joined '${context}' as ${principalId}` + (reused ? " (existing key reused)" : "") + "\n" + formatKeyValues([
+      ["alias", alias],
+      ["context", context],
+      ["principal", principalId],
+      ["role", role],
+      ["key id", keyId]
+    ]) + `
+
+  Now active. Use \`vectros switch ${alias}\` to return to it, \`vectros keyring show --format env\` to export the key for the MCP server.
+`
+  );
+}
+
+// src/commands/keyring.ts
+async function runKeyringList(opts, deps = {}) {
+  const keyring = deps.keyring ?? new Keyring();
+  try {
+    const entries = await keyring.list();
+    const active = await keyring.activeAlias();
+    if (opts.json) {
+      process.stdout.write(`${formatJson({ active, entries })}
+`);
+      return 0;
+    }
+    if (entries.length === 0) {
+      process.stdout.write("\n  (no keyring entries yet \u2014 run `vectros join <context>` to add one)\n");
+      return 0;
+    }
+    process.stdout.write(
+      "\n" + formatTable(entries, [
+        { header: "", get: (e) => e.alias === active ? "*" : "" },
+        { header: "alias", get: (e) => e.alias },
+        { header: "context", get: (e) => e.context },
+        { header: "principal", get: (e) => e.principalId },
+        { header: "role", get: (e) => e.role },
+        { header: "env", get: (e) => e.env },
+        { header: "key id", get: (e) => e.keyId }
+      ]) + "\n"
+    );
+    return 0;
+  } catch (err) {
+    process.stderr.write(`  \u2716 keyring list failed: ${formatError(err)}
+`);
+    return 1;
+  }
+}
+async function runKeyringUse(alias, opts, deps = {}) {
+  const keyring = deps.keyring ?? new Keyring();
+  try {
+    await keyring.setActive(alias);
+    if (opts.json) {
+      process.stdout.write(`${formatJson({ active: alias })}
+`);
+      return 0;
+    }
+    process.stdout.write(`
+  \u2714 Active identity is now '${alias}'.
+`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`  \u2716 ${formatError(err)}
+`);
+    return 2;
+  }
+}
+async function runKeyringRemove(alias, opts, deps = {}) {
+  const keyring = deps.keyring ?? new Keyring();
+  try {
+    const removed = await keyring.remove(alias);
+    if (!removed) {
+      process.stderr.write(`  \u2716 No keyring entry named '${alias}'.
+`);
+      return 2;
+    }
+    if (opts.json) {
+      process.stdout.write(`${formatJson({ removed: alias })}
+`);
+      return 0;
+    }
+    process.stdout.write(`
+  \u2714 Removed '${alias}' from the keyring.
+`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`  \u2716 keyring remove failed: ${formatError(err)}
+`);
+    return 1;
+  }
+}
+async function runKeyringShow(opts, deps = {}) {
+  const keyring = deps.keyring ?? new Keyring();
+  try {
+    const entry = opts.alias ? await keyring.get(opts.alias) : await keyring.getActive();
+    if (!entry) {
+      process.stderr.write(
+        opts.alias ? `  \u2716 No keyring entry named '${opts.alias}'.
+` : "  \u2716 No active identity. Run `vectros join <context>` or `vectros switch <alias>`.\n"
+      );
+      return 2;
+    }
+    const secret = await keyring.resolveSecret(entry.alias);
+    if (!secret) {
+      process.stderr.write(
+        `  \u2716 The stored secret for '${entry.alias}' is missing or unreadable. Re-issue it with \`vectros join ${entry.context} --alias ${entry.alias}\`.
+`
+      );
+      return 1;
+    }
+    switch (opts.format) {
+      case "raw":
+        process.stdout.write(`${secret}
+`);
+        return 0;
+      case "env":
+        process.stdout.write(`VECTROS_API_KEY=${secret}
+`);
+        return 0;
+      case "human":
+        process.stdout.write(
+          "\n" + formatKeyValues([
+            ["alias", entry.alias],
+            ["context", entry.context],
+            ["principal", entry.principalId],
+            ["role", entry.role],
+            ["env", entry.env],
+            ["key id", entry.keyId]
+          ]) + `
+
+  VECTROS_API_KEY=${secret}
+  \u26A0 This is a live credential \u2014 treat it like a password.
+`
+        );
+        return 0;
+    }
+  } catch (err) {
+    process.stderr.write(`  \u2716 keyring show failed: ${formatError(err)}
+`);
+    return 1;
+  }
+}
+
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.7.0" : "dev",
-  sdk: true ? "0.33.0" : "dev",
-  blueprints: true ? "0.6.5" : "dev"
+  cli: true ? "0.9.0" : "dev",
+  sdk: true ? "0.34.0" : "dev",
+  blueprints: true ? "0.7.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros ${BUILD_INFO.cli} (sdk ${BUILD_INFO.sdk}, blueprints ${BUILD_INFO.blueprints})`;
@@ -14238,8 +15290,56 @@ function buildProgram(deps = {}) {
   registerAccessCommands(program, deps);
   registerRoleCommands(program, deps);
   registerContextCommands(program, deps);
+  registerJoinCommand(program, deps);
+  registerKeyringCommands(program);
   return program;
 }
+function registerJoinCommand(program, deps) {
+  const join4 = program.command("join").description("Enroll a principal in a context (grant + key) and keep the key in the keyring.").argument("<context>", "the app context to join").option("--role <roleId>", "reference a Role to grant (XOR --actions)").option("--actions <csv>", "inline single-clause actions to grant, comma-separated (XOR --role)").option("--as <principal>", "who to enroll: 'me' (default) or an explicit 'usr_<id>'", "me").option("--org <orgId>", "identity override: the org the member acts under (enables org/team-scoped writes)").option("--alias <name>", "keyring entry name (defaults to the context id)").option("--tenant <tenant>", "target tenant: 'test' or 'live' (default live)");
+  addAuthOptions(join4).action(
+    async (contextArg, flags) => {
+      if (flags.tenant !== void 0 && flags.tenant !== "test" && flags.tenant !== "live") {
+        process.stderr.write(`  \u2716 --tenant must be 'test' or 'live' (got '${flags.tenant}')
+`);
+        process.exit(2);
+      }
+      process.exit(
+        await runJoin(
+          {
+            ...toCommonOptions(flags),
+            contextArg,
+            role: flags.role,
+            actions: flags.actions,
+            as: flags.as,
+            org: flags.org,
+            alias: flags.alias,
+            tenant: flags.tenant
+          },
+          deps
+        )
+      );
+    }
+  );
+}
+function registerKeyringCommands(program) {
+  const KEYRING_SHOW_FORMATS = ["human", "env", "raw"];
+  const keyring = program.command("keyring").description("Inspect and manage the local multi-principal keyring.");
+  keyring.command("list").description("List keyring entries and which one is active.").option("--json", "emit machine-readable JSON").action(async (flags) => {
+    process.exit(await runKeyringList({ json: Boolean(flags.json) }));
+  });
+  keyring.command("use").description("Make an entry the active identity.").argument("<alias>", "the keyring entry to activate").option("--json", "emit machine-readable JSON").action(async (alias, flags) => {
+    process.exit(await runKeyringUse(alias, { json: Boolean(flags.json) }));
+  });
+  keyring.command("show").description("Reveal the active (or a named) entry\u2019s key.").option("--alias <name>", "show this entry instead of the active one").addOption(new import_commander.Option("--format <fmt>", "how to emit the key").choices(KEYRING_SHOW_FORMATS).default("human")).action(async (flags) => {
+    process.exit(await runKeyringShow({ alias: flags.alias, format: flags.format }));
+  });
+  keyring.command("remove").description("Drop an entry and its stored secret.").argument("<alias>", "the keyring entry to remove").option("--json", "emit machine-readable JSON").action(async (alias, flags) => {
+    process.exit(await runKeyringRemove(alias, { json: Boolean(flags.json) }));
+  });
+  program.command("switch").description("Shortcut for `keyring use` \u2014 flip the active identity.").argument("<alias>", "the keyring entry to activate").option("--json", "emit machine-readable JSON").action(async (alias, flags) => {
+    process.exit(await runKeyringUse(alias, { json: Boolean(flags.json) }));
+  });
+}
 function registerContextCommands(program, deps) {
   const context = program.command("context").description("Manage app contexts (the namespace all data lives in).");
   const create = context.command("create").description("Create (idempotent) an app context.").argument("<contextId>", "context id (3-31 chars; lowercase letter + lowercase/digit/dash)").option("--name <name>", "human-readable name").option("--tenant <tenant>", "tenant to create the context in: 'test' or 'live' (default live)");
@@ -14314,7 +15414,10 @@ function registerContextCommands(program, deps) {
 }
 function registerRoleCommands(program, deps) {
   const role = program.command("role").description("Manage context-scoped roles (reusable scope rules; bind via `access grant --role`).");
-  const create = role.command("create").description("Create (idempotent by roleId) a single-clause role from --actions.").requiredOption("--context <c>", "app context").requiredOption("--role-id <id>", "role id (3-31 chars; lowercase letter + lowercase/digit/dash)").requiredOption("--name <name>", "human-readable name").requiredOption("--actions <csv>", "allowed actions, comma-separated (e.g. records:cru,search:r)").option("--description <text>", "free-text description");
+  const create = role.command("create").description("Create (idempotent by roleId) a single-clause role from --actions.").requiredOption("--context <c>", "app context").requiredOption("--role-id <id>", "role id (3-31 chars; lowercase letter + lowercase/digit/dash)").requiredOption("--name <name>", "human-readable name").requiredOption("--actions <csv>", "allowed actions, comma-separated (e.g. records:cru,search:r)").option(
+    "--data-scope <json>",
+    `confine the clause to owned data \u2014 JSON map of dimension \u2192 allowed values, e.g. '{"userId":["\${{ self.userId }}"]}' or '{"scope:org":["<orgId>", null]}'`
+  ).option("--description <text>", "free-text description");
   addCommonAuthOptions(create).action(
     async (flags) => {
       process.exit(
@@ -14324,6 +15427,7 @@ function registerRoleCommands(program, deps) {
           roleId: flags.roleId,
           name: flags.name,
           actions: flags.actions,
+          dataScope: flags.dataScope,
           description: flags.description
         }, deps)
       );
@@ -14344,7 +15448,7 @@ function registerRoleCommands(program, deps) {
 }
 function registerAccessCommands(program, deps) {
   const access2 = program.command("access").description("Manage access bindings: principal \u2194 context \u2194 role/scopes.");
-  const grant = access2.command("grant").description("Bind a principal to a context via a role or inline actions.").requiredOption("--principal <p>", "principal: 'usr_<userId>', 'key_<keyId>', or 'me' (your own user)").requiredOption("--context <c>", "app context").option("--role <roleId>", "reference a Role (XOR --actions)").option("--actions <csv>", "inline single-clause actions, comma-separated (XOR --role)");
+  const grant = access2.command("grant").description("Bind a principal to a context via a role or inline actions.").requiredOption("--principal <p>", "principal: 'usr_<userId>', 'key_<keyId>', or 'me' (your own user)").requiredOption("--context <c>", "app context").option("--role <roleId>", "reference a Role (XOR --actions)").option("--actions <csv>", "inline single-clause actions, comma-separated (XOR --role)").option("--org <orgId>", "identity override: the org this principal acts under (enables org/team-scoped writes)").option("--identity-overrides <json>", "general identity overrides as a JSON object (merged over --org)");
   addCommonAuthOptions(grant).action(
     async (flags) => {
       process.exit(
@@ -14353,7 +15457,9 @@ function registerAccessCommands(program, deps) {
           principal: flags.principal,
           context: flags.context,
           role: flags.role,
-          actions: flags.actions
+          actions: flags.actions,
+          org: flags.org,
+          identityOverrides: flags.identityOverrides
         }, deps)
       );
     }
@@ -14370,6 +15476,12 @@ function registerAccessCommands(program, deps) {
   addCommonAuthOptions(get).action(async (flags) => {
     process.exit(await runAccessGet({ ...toCommonOptions(flags), principal: flags.principal, context: flags.context }, deps));
   });
+  const explain = access2.command("explain").description("Show what a principal\u2019s binding grants: its clauses + a concrete access matrix.").requiredOption("--principal <p>", "principal: 'usr_<userId>', 'key_<keyId>', or 'me' (your own user)").requiredOption("--context <c>", "app context");
+  addCommonAuthOptions(explain).action(async (flags) => {
+    process.exit(
+      await runAccessExplain({ ...toCommonOptions(flags), principal: flags.principal, context: flags.context }, deps)
+    );
+  });
 }
 function dimensionOption() {
   return new import_commander.Option("--type <dim>", "principal dimension").choices(DIMENSIONS).makeOptionMandatory();