@vectros-ai/cli 0.24.0 → 0.25.0

package/dist/cli.js

@@ -1614,7 +1614,7 @@ var require_proper_lockfile = __commonJS({
 // src/cli-bootstrap.ts
 var readline2 = __toESM(require("readline/promises"));
 
-// node_modules/@vectros-ai/sdk/dist/index.mjs
+// ../../node_modules/@vectros-ai/sdk/dist/index.mjs
 var __defProp2 = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -4044,7 +4044,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/jwks");
   }
   /**
-   * Returns a page of per-subject PHI read-access rows: who read which subject's PHI, when, against which record, and whether any sensitive value was actually revealed in plaintext. Metadata only — never the PHI itself. This is the disclosure-accounting surface from which a covered entity derives its HIPAA §164.528 accounting of disclosures. Provide at least one query axis: a subject (`subjectType` + `subjectId`) within a `contextId` for the primary accounting query; `resourceId` within a `contextId` for 'who read this record'; `callerKeyId` for 'what did this credential read' (account-wide forensic); or `contextId` alone to enumerate a whole context. `from`/`to` bound the time window. Results are scoped to your account, derived from your token — never from input. Requires the `access-log:r` scope.
+   * Returns a page of per-subject PHI read-access rows: who read which subject's PHI, when, against which record, and whether any sensitive value was actually revealed in plaintext. Metadata only — never the PHI itself. Rows exist only where read-access logging is enabled. Provide at least one query axis: a subject (`subjectType` + `subjectId`) within a `contextId` for the primary accounting query; `resourceId` within a `contextId` for 'who read this record'; `callerKeyId` for 'what did this credential read' (account-wide forensic); or `contextId` alone to enumerate a whole context. `from`/`to` bound the time window. Results are scoped to your account, derived from your token — never from input. Requires the `access-log:r` scope.
    *
    * @param {Vectros.GetAccessLogRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5749,7 +5749,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers/{issuerId}");
   }
   /**
-   * Updates the mutable fields of a registered issuer: `subClaim`, `emailClaim`, `userinfoUri`, `capturedClaims`, `restrictedToDomain` (a new non-blank value must already be a VERIFIED domain for your account; an empty string clears it back to domain-less; see `IssuerUpdateRequest.restrictedToDomain` for the full semantics), `status` (`active`/`suspended` — a registration awaiting verification (`pending_verification`) accepts no status change until it is verified; a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and `selfSignupPolicies`. Fields omitted from the body are left unchanged (partial update). `issuer`, `jwksUri`, `audience`, and `contextId` are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. **`subClaim` is identity-determining, not merely cosmetic**: it names which verified JWT claim is read as the federated user's identifier, so changing it on an issuer that already has bound users would silently re-identify (or, under self-signup, orphan) every one of them — changing it is therefore refused once any user has bound through this issuer, the same guard `DELETE` already applies, and is only free before the first real login. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.
+   * Updates the mutable fields of a registered issuer: `subClaim`, `emailClaim`, `userinfoUri`, `capturedClaims`, `restrictedToDomain` (a new non-blank value must already be a VERIFIED domain for your account; an empty string clears it where permitted; see `IssuerUpdateRequest.restrictedToDomain` for the full semantics), `status` (`active`/`suspended` — a registration awaiting verification (`pending_verification`) accepts no status change until it is verified; a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and `selfSignupPolicies`. Fields omitted from the body are left unchanged (partial update). `issuer`, `jwksUri`, `audience`, and `contextId` are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. **`subClaim` is identity-determining, not merely cosmetic**: it names which verified JWT claim is read as the federated user's identifier, so changing it on an issuer that already has bound users would silently re-identify (or, under self-signup, orphan) every one of them — changing it is therefore refused once any user has bound through this issuer, the same guard `DELETE` already applies, and is only free before the first real login. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.
    *
    * @param {Vectros.IssuerUpdateRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6559,7 +6559,7 @@ var ComplianceClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Submits a right-to-erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure removes exactly the data the subject solely owns across the declared contexts, plus its identity and lookup rows when all contexts are covered. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
+   * Submits an erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure deletes the records, documents, folders and record schemas the subject solely owns across the declared contexts (and, for a user, its access profiles there), plus its identity and lookup rows when all contexts are covered. Rows co-owned with another owner scope or principal are kept; read-access log entries are not erased. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
    *
    * @param {Vectros.ErasureRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6622,7 +6622,7 @@ var ComplianceClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/erasure-requests");
   }
   /**
-   * Polls an erasure request by id. While the job is still running this returns its status only; once it completes, the response also includes the verifiable completion certificate (which contexts were swept, per-context deletion counts, whether the identity was kept, and reports of dangling references and shared rows left intact). Requires a root API key.
+   * Polls an erasure request by id. While the job is still running this returns its status only; once it completes, the response also includes the completion certificate (which contexts were swept, per-context deletion counts, whether the identity was kept, and reports of dangling references and shared rows left intact). Requires a root API key.
    *
    * @param {Vectros.GetErasureRequestRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9441,6 +9441,8 @@ var InferenceClient = class {
           throw new PaymentRequiredError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 413:
+          throw new ContentTooLargeError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -9580,6 +9582,8 @@ var InferenceClient = class {
           throw new PaymentRequiredError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 413:
+          throw new ContentTooLargeError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         case 500:
@@ -11877,7 +11881,7 @@ var RenderHintsSchema = import_zod.z.object({
   helpText: import_zod.z.string().optional(),
   // Marks this field as the record's headline (display) field — the linked
   // primary column in the records list + the title on the detail view. At most
-  // one per schema (the platform takes the first by order). Format passthrough →
+  // one per schema (the platform stores the hint and does not enforce one; the reference UI uses the first by order). Format passthrough →
   // SchemaRequest.renderHints[fieldId].displayField.
   displayField: import_zod.z.boolean().optional()
 }).strict();
@@ -13536,7 +13540,8 @@ var BlueprintSchema = import_zod.z.object({
    * alongside app-context/service-principal creation and issuers, BEFORE
    * schemas/seed (an `entityBacked` namespace's entities, and an
    * `allowedSurfaces: ['entity']` schema, both need the registration to
-   * already exist). `org`/`client` need no entry — they exist already.
+   * already exist). `org`/`client` are registered the same way as any other
+   * namespace: signup does not register them, so declare an entry for each you use.
    */
   namespaces: import_zod.z.array(BlueprintNamespaceSchema).optional(),
   /**
@@ -16500,6 +16505,25 @@ async function clearSession(baseDir) {
     return false;
   }
 }
+var TokenEndpointError = class extends Error {
+  status;
+  /** The OAuth `error` field of a JSON error body (e.g. `invalid_grant`), when there is one. */
+  oauthError;
+  constructor(status, text) {
+    super(`token endpoint HTTP ${status}${text ? ` \u2014 ${stripControlCharacters(text, 500)}` : ""}`);
+    this.name = "TokenEndpointError";
+    this.status = status;
+    this.oauthError = oauthErrorOf(text);
+  }
+};
+function oauthErrorOf(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return typeof parsed.error === "string" ? parsed.error : void 0;
+  } catch {
+    return void 0;
+  }
+}
 async function postToken(config, body, fetchImpl) {
   const res = await fetchImpl(tokenEndpoint(config), {
     method: "POST",
@@ -16507,9 +16531,7 @@ async function postToken(config, body, fetchImpl) {
     body: body.toString()
   });
   const text = await res.text().catch(() => "");
-  if (!res.ok) {
-    throw new Error(`token endpoint HTTP ${res.status}${text ? ` \u2014 ${stripControlCharacters(text, 500)}` : ""}`);
-  }
+  if (!res.ok) throw new TokenEndpointError(res.status, text);
   try {
     return JSON.parse(text);
   } catch {
@@ -16525,31 +16547,54 @@ async function refreshTokens(config, refreshToken, fetchImpl = fetch) {
 
 // src/auth-context.ts
 var COGNITO_TOKEN_ENV = "VECTROS_BOOTSTRAP_TOKEN";
+function loginCommandFor(env) {
+  return env === "staging" ? "vectros login --env staging" : "vectros login";
+}
 var MissingCredentialError = class extends Error {
-  constructor() {
+  constructor(env) {
     super(
-      `No credential found. Set ${COGNITO_TOKEN_ENV} or pass --token (generate a token in the developer portal, or run \`vectros login\` once it ships).`
+      `No credential found. Run \`${loginCommandFor(env)}\` to sign in, or set ${COGNITO_TOKEN_ENV} or pass --token (generate a token in the developer portal).`
     );
     this.name = "MissingCredentialError";
   }
 };
+var SessionExpiredError = class extends Error {
+  constructor(env) {
+    super(
+      `Your Vectros login session has expired or was revoked. Run \`${loginCommandFor(env)}\` to sign in again.`
+    );
+    this.name = "SessionExpiredError";
+  }
+};
 function resolveCognitoTokenSync(explicit) {
   if (explicit && explicit.trim()) return explicit.trim();
   const fromEnv = process.env[COGNITO_TOKEN_ENV];
   if (fromEnv && fromEnv.trim()) return fromEnv.trim();
   return void 0;
 }
-async function resolveCognitoToken(env, explicit) {
+async function resolveCognitoToken(env, explicit, deps = { readSession, refreshTokens, saveSession }) {
   const sync = resolveCognitoTokenSync(explicit);
   if (sync) return sync;
-  const session = await readSession();
+  const session = await deps.readSession();
   if (session && session.env === env) {
     const config = resolveCognitoConfig(env);
-    const tokens = await refreshTokens(config, session.refreshToken);
+    let tokens;
+    try {
+      tokens = await deps.refreshTokens(config, session.refreshToken);
+    } catch (err) {
+      if (err instanceof TokenEndpointError && err.oauthError === "invalid_grant") throw new SessionExpiredError(env);
+      throw err;
+    }
+    if (tokens.refresh_token && tokens.refresh_token !== session.refreshToken) {
+      const stored = await deps.readSession().catch(() => void 0);
+      if (stored?.refreshToken === session.refreshToken) {
+        await deps.saveSession({ ...session, refreshToken: tokens.refresh_token }).catch(() => void 0);
+      }
+    }
     const bearer = tokens.id_token ?? tokens.access_token;
     if (bearer) return bearer;
   }
-  throw new MissingCredentialError();
+  throw new MissingCredentialError(env);
 }
 async function resolveAuthContext(opts) {
   const baseUrl = envToBaseUrl(opts.env, opts.baseUrl ?? process.env.VECTROS_API_BASE_URL);
@@ -17061,6 +17106,7 @@ function keyNameFor(pack, machineId) {
 }
 
 // src/identity-resolver.ts
+var IDENTITIES_TO_ENSURE_HEADING = "  Identities to ensure (idempotent by external id; a non-user entity lives with its namespace):";
 function userPayload(decl) {
   const meta = decl.metadata;
   if (decl.displayName === void 0) return meta;
@@ -17201,7 +17247,7 @@ async function withAuth(opts, deps, body) {
       log
     });
   } catch (err) {
-    if (err instanceof MissingCredentialError || err instanceof InvalidBaseUrlError || err instanceof InvalidCognitoRegionError) {
+    if (err instanceof MissingCredentialError || err instanceof SessionExpiredError || err instanceof InvalidBaseUrlError || err instanceof InvalidCognitoRegionError) {
       process.stderr.write(`  \u2716 ${err.message}
 `);
       return 2;
@@ -17796,15 +17842,6 @@ async function provisionContext(client, input) {
   const { blueprint, allowTenantWideNamespaces = false, readExistingKey, confirmExistingPrincipal, log } = input;
   assertBlueprintGates(blueprint);
   assertTenantWideNamespacesAllowed(blueprint, allowTenantWideNamespaces);
-  const ctxResp = await client.auth.createAppContext({
-    body: {
-      contextId: blueprint.contextId,
-      name: contextNameOf(blueprint),
-      ...blueprint.identityProjectionClaims === void 0 ? {} : { identityProjectionClaims: blueprint.identityProjectionClaims }
-    }
-  });
-  const contextAction = actionOf(ctxResp.created);
-  log.debug({ component: "loader", contextId: blueprint.contextId, contextAction }, "app-context ensured");
   const user = await client.identity.createUser({
     body: {
       externalId: blueprint.servicePrincipal.externalId,
@@ -17845,6 +17882,15 @@ async function provisionContext(client, input) {
       "existing-principal collision confirmed (or unwired) \u2014 proceeding with any further write to this principal"
     );
   }
+  const ctxResp = await client.auth.createAppContext({
+    body: {
+      contextId: blueprint.contextId,
+      name: contextNameOf(blueprint),
+      ...blueprint.identityProjectionClaims === void 0 ? {} : { identityProjectionClaims: blueprint.identityProjectionClaims }
+    }
+  });
+  const contextAction = actionOf(ctxResp.created);
+  log.debug({ component: "loader", contextId: blueprint.contextId, contextAction }, "app-context ensured");
   const needsContextPinnedBootstrap = (blueprint.namespaces ?? []).length > 0;
   const ctxBootstrapClient = needsContextPinnedBootstrap ? input.remintBootstrapForContext ? await input.remintBootstrapForContext(blueprint.contextId) : client : void 0;
   if (ctxBootstrapClient && input.remintBootstrapForContext) {
@@ -18353,14 +18399,14 @@ function renderPlanDataScope(ds) {
 function buildPlan(blueprint, opts = {}) {
   const steps = [];
   const projection = blueprint.identityProjectionClaims?.length ? `, identity projection: [${blueprint.identityProjectionClaims.join(", ")}]` : blueprint.identityProjectionClaims ? ", identity projection: disabled (empty list)" : "";
-  steps.push({
-    kind: "context",
-    summary: `context '${blueprint.contextId}' (${contextNameOf(blueprint)}${projection})`
-  });
   steps.push({
     kind: "principal",
     summary: `principal '${blueprint.servicePrincipal.externalId}' (SERVICE)`
   });
+  steps.push({
+    kind: "context",
+    summary: `context '${blueprint.contextId}' (${contextNameOf(blueprint)}${projection})`
+  });
   for (const ns of blueprint.namespaces ?? []) {
     const ownerNote = ns.tenantWide ? "TENANT-WIDE \u2014 visible to every context" : `owned by '${blueprint.contextId}'`;
     const entityNote = ns.entityBacked ? ", entity-backed" : "";
@@ -18915,9 +18961,8 @@ var OsKeychainSecretStore = class {
    * enumeration, and `deleteCredential` on a nonexistent ref returns the same
    * meaningless `false` as Linux. So the `.some(c => c.account === ref)` comparison
    * is sound on both measured platforms. Still unmeasured: a CI lane that runs this
-   * against the real Windows store on every MR — the dev-machine probe is a point
-   * measurement, not a regression gate. (Tracked internally; this file ships to
-   * public npm, so no tracker number here.)
+   * against the real Windows store on every change — the dev-machine probe is a point
+   * measurement, not a regression gate.
    *
    * ⚠️ THIS METHOD'S FAIL-CLOSED GUARANTEE IS AN UPSTREAM BEHAVIOURAL CONTRACT, NOT
    * SOMETHING THIS CODE ENFORCES. `@napi-rs/keyring` is pinned to an EXACT version
@@ -19073,7 +19118,7 @@ var CryptoFileSecretStore = class {
   async setSecret(ref, secret) {
     const key = await this.encryptionKey();
     const iv = (0, import_node_crypto3.randomBytes)(IV_LEN);
-    const cipher = (0, import_node_crypto3.createCipheriv)(ALGO, key, iv);
+    const cipher = (0, import_node_crypto3.createCipheriv)(ALGO, key, iv, { authTagLength: TAG_LEN });
     const enc = Buffer.concat([cipher.update(secret, "utf8"), cipher.final()]);
     const tag = cipher.getAuthTag();
     const blob = Buffer.concat([iv, tag, enc]);
@@ -19096,7 +19141,7 @@ var CryptoFileSecretStore = class {
       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_crypto3.createDecipheriv)(ALGO, key, iv);
+      const decipher = (0, import_node_crypto3.createDecipheriv)(ALGO, key, iv, { authTagLength: TAG_LEN });
       decipher.setAuthTag(tag);
       return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8");
     } catch {
@@ -19296,7 +19341,7 @@ async function withIndexLock(dir, fn, timings = LOCK_OPTS) {
       // judged: two waiters can both condemn one crash remnant, and the second's
       // already-decided rmdir destroys the first's FRESH lock. Nothing freezes.
       //
-      // MEASURED against this exact config (probes recorded in the MR):
+      // MEASURED against this exact config (probe results below):
       //     real OS processes, no injection : 0/25 and 1/25 (two independent runs)
       //     in-process, 5 waiters           : ~3% per round
       //     rival's rmdir lagged one turn   : 19/25
@@ -21129,7 +21174,7 @@ async function resolveBridgeCognitoToken(args, prompt, isTty, resolveCognito = r
   }
   if (!isTty) {
     throw new Error(
-      "No bridge token: set VECTROS_BOOTSTRAP_TOKEN, pass --token, or run `vectros login` first (required in non-interactive mode)."
+      `No bridge token: set VECTROS_BOOTSTRAP_TOKEN, pass --token, or run \`${loginCommandFor(args.env)}\` first (required in non-interactive mode).`
     );
   }
   process.stdout.write(
@@ -21238,7 +21283,9 @@ ${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");
+      process.stdout.write(`
+${IDENTITIES_TO_ENSURE_HEADING}
+`);
       for (const [name, decl] of declaredIdentities) {
         process.stdout.write(`    ~ ${name} (${decl.kind}) \u2014 external id '${decl.externalId}'
 `);
@@ -21469,6 +21516,12 @@ ${codeAddHint}`);
     }
     return finishApply();
   } catch (err) {
+    if (err instanceof SessionExpiredError) {
+      process.stderr.write(`
+  \u2716 ${err.message}
+`);
+      return 2;
+    }
     if (err instanceof LostKeyError) {
       process.stderr.write(`
   \u2716 ${err.message}
@@ -21840,7 +21893,9 @@ ${renderPlan(blueprint, buildPlan(blueprint, { noSeed, noKey: true }), { prune:
     process.stdout.write(applySeedNotice(blueprint, args.seed));
     const declaredIdentities = Object.entries(blueprint.identities ?? {});
     if (declaredIdentities.length > 0) {
-      process.stdout.write("\n  Identities to ensure (tenant-wide, idempotent by external id):\n");
+      process.stdout.write(`
+${IDENTITIES_TO_ENSURE_HEADING}
+`);
       for (const [name, decl] of declaredIdentities) {
         process.stdout.write(`    ~ ${name} (${decl.kind}) \u2014 external id '${decl.externalId}'
 `);
@@ -21973,7 +22028,7 @@ function reportApplyError(err) {
   If this is expected (a re-apply of a blueprint you manage), re-run with --confirm-existing-principal
   (with --yes in a pipeline, where it is standing consent), or confirm at the prompt.
   If you don't recognize this identity, investigate the blueprint's servicePrincipal.externalId first.
-  Only the app-context and the principal lookup had run; no grant or anything else was changed.
+  Only the principal lookup had run; no context, grant or anything else was created or changed.
 `
     );
     return 3;
@@ -22326,10 +22381,14 @@ schemas:
 accessProfile:
   # SCOPE GATE: data-plane only (records/schemas/search/documents/folders/inference/entities),
   # PLUS profiles:r/u/d (bounded by the platform to redistributing access you already have,
-  # never granting more) and profiles:c:self (create a profile for yourself only \u2014 the
-  # platform resolves "self" from the caller, not from anything you declare here). A bare
-  # profiles:c, or profiles:c:usr_<id> naming another principal, is HARD-REJECTED \u2014 by
-  # design, no override. Same for keys/users/admin/namespaces/*.
+  # never granting more), profiles:c:self (create a profile for yourself only \u2014 the
+  # platform resolves "self" from the caller, not from anything you declare here) and
+  # scripts:x:<script-name> (run one named script that this blueprint ships; there is no bare
+  # or wildcard form).
+  # A bare profiles:c is accepted ONLY when this same clause also declares the
+  # member-lifecycle capability (see "capabilities" below); without it, and always for
+  # profiles:c:usr_<id> naming another principal, it is REJECTED \u2014 no override. Every other
+  # control-plane resource (keys/users/admin/namespaces/triggers/...) and "*" is REJECTED the same way.
   # Ops: c|r|u|d, combinable (records:cru). Prefer the narrowest set (least privilege).
   allowedActions: [records:r, records:c, records:u, search:r, schemas:r]
   # dataScope binds the key to specific owners. Include null to ALSO see
@@ -22345,8 +22404,10 @@ accessProfile:
   # above) unless every owner genuinely sharing every record is what you want.
   dataScope: {}
   # capabilities is a SEPARATE gated dimension from allowedActions \u2014 named platform
-  # effects a resource:ops verb can't express. Only 'member-lifecycle' is admitted
-  # today; every other name is HARD-REJECTED, same posture as the scope gate above.
+  # effects a resource:ops verb can't express. Only 'member-lifecycle' and
+  # 'delegate-principal-stamp' are admitted today; every other name is REJECTED, same
+  # posture as the scope gate above. 'member-lifecycle' is also what lets this clause
+  # carry a bare profiles:c.
   # capabilities: [member-lifecycle]
 
 servicePrincipal:
@@ -22433,8 +22494,10 @@ Usage:
 
 <file|name> is a path to your own blueprint (YAML .yaml/.yml or JSON .json) OR
 the name of a bundled blueprint. The same scope gate that protects bundled
-blueprints applies to file blueprints \u2014 a forked or hand-written blueprint can
-never request control-plane access.
+blueprints applies to file blueprints: beyond data-plane access, a forked or
+hand-written blueprint can request only a short allowlist of narrow exceptions
+(profiles:r/u/d, profiles:c:self, a bare profiles:c beside member-lifecycle,
+scripts:x:<script-name>); every other control-plane scope is rejected.
 
 A blueprint may declare a top-level 'inputs:' block and reference its values
 with \${{ inputs.<name> }} (and the built-ins \${{ vectros.context }} /
@@ -22546,7 +22609,9 @@ ${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");
+    process.stdout.write(`
+${IDENTITIES_TO_ENSURE_HEADING}
+`);
     for (const [name, decl] of declaredIdentities) {
       process.stdout.write(`    ~ ${name} (${decl.kind}) \u2014 external id '${decl.externalId}'
 `);
@@ -22680,6 +22745,89 @@ ${BLUEPRINT_HELP}
 // src/program.ts
 var import_commander = require("commander");
 
+// src/dev-api.ts
+var DeveloperApiError = class extends Error {
+  statusCode;
+  /** The platform's error body, when it answered with one (its message, request id and error code). */
+  body;
+  constructor(message, statusCode, body) {
+    super(message);
+    this.name = "DeveloperApiError";
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+};
+async function fetchDeveloperUsersPage(opts) {
+  const { cognitoToken, apiBaseUrl, tenant, startFrom, limit, fetchImpl = fetch } = opts;
+  const base = apiBaseUrl.replace(/\/$/, "");
+  let url = `${base}/developer/users?tenant=${encodeURIComponent(tenant)}`;
+  if (startFrom) url += `&startFrom=${encodeURIComponent(startFrom)}`;
+  if (limit !== void 0) url += `&limit=${encodeURIComponent(String(limit))}`;
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${cognitoToken}` }
+    });
+  } catch (err) {
+    throw new DeveloperApiError(
+      `Request to /developer/users failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    const hint = res.status === 403 ? " (this command requires an account owner login \u2014 sign in as the owner and retry)" : "";
+    throw new DeveloperApiError(
+      `GET /developer/users failed: HTTP ${res.status}${hint}${body ? ` \u2014 ${body}` : ""}`,
+      res.status
+    );
+  }
+  let parsed;
+  try {
+    parsed = await res.json();
+  } catch {
+    throw new DeveloperApiError("GET /developer/users returned a non-JSON body");
+  }
+  const data = Array.isArray(parsed.data) ? parsed.data : [];
+  const nextCursor = typeof parsed.nextCursor === "string" ? parsed.nextCursor : null;
+  return { data, nextCursor };
+}
+async function fetchDeveloperMe(opts) {
+  const { cognitoToken, apiBaseUrl, tenant, fetchImpl = fetch } = opts;
+  const url = `${apiBaseUrl.replace(/\/$/, "")}/developer/me?tenant=${encodeURIComponent(tenant)}`;
+  let res;
+  try {
+    res = await fetchImpl(url, { method: "GET", headers: { Authorization: `Bearer ${cognitoToken}` } });
+  } catch (err) {
+    throw new DeveloperApiError(
+      `Request to /developer/me failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    const failure = await devRouteError(res, "GET /developer/me");
+    throw new DeveloperApiError(
+      `GET /developer/me failed: HTTP ${res.status}`,
+      res.status,
+      failure.body
+    );
+  }
+  let parsed;
+  try {
+    parsed = await res.json();
+  } catch {
+    throw new DeveloperApiError("GET /developer/me returned a non-JSON body");
+  }
+  if (typeof parsed.principalId !== "string" || typeof parsed.userId !== "string") {
+    throw new DeveloperApiError("GET /developer/me returned no principal");
+  }
+  return {
+    principalId: parsed.principalId,
+    userId: parsed.userId,
+    tenantId: typeof parsed.tenantId === "string" ? parsed.tenantId : void 0
+  };
+}
+
 // src/self-principal.ts
 var PRINCIPAL_PREFIX_USER = "usr_";
 function emailFromJwt(token) {
@@ -22708,6 +22856,37 @@ async function resolveSelfPrincipal(client, cognitoToken) {
   if (!match?.id) return null;
   return { principalId: `${PRINCIPAL_PREFIX_USER}${match.id}`, userId: match.id, email };
 }
+async function resolveSelfPrincipalForTenant(auth, fetchImpl) {
+  const tenant = auth.tenant ?? "live";
+  let me;
+  try {
+    me = await fetchDeveloperMe({
+      cognitoToken: auth.cognitoToken,
+      apiBaseUrl: auth.baseUrl,
+      tenant,
+      ...fetchImpl ? { fetchImpl } : {}
+    });
+  } catch (err) {
+    if (err instanceof DeveloperApiError && err.statusCode !== void 0) {
+      if (err.body?.errorCode === "SESSION_REFRESH_REQUIRED") throw new SessionExpiredError(auth.env ?? "production");
+      throw err;
+    }
+    if (tenant === "test") throw err;
+    return resolveSelfPrincipal(auth.client, auth.cognitoToken);
+  }
+  if (me === null) return null;
+  const forThisTenant = Boolean(auth.tenantId && me.tenantId && me.tenantId === auth.tenantId);
+  if (forThisTenant && me.principalId.startsWith(PRINCIPAL_PREFIX_USER)) {
+    return { principalId: me.principalId, userId: me.userId, email: emailFromJwt(auth.cognitoToken) ?? "" };
+  }
+  return tenant === "live" ? resolveSelfPrincipal(auth.client, auth.cognitoToken) : null;
+}
+function selfPrincipalUnresolvedMessage(tenant, flag) {
+  if (tenant === "test") {
+    return `Could not resolve your own user id in the test tenant: the platform did not report one for this login. Find it with \`vectros identity list-all --tenant test\` (an owner login) and pass ${flag} usr_<id> explicitly.`;
+  }
+  return `Could not resolve your own user id from your login. Pass ${flag} usr_<id> explicitly (find the id with \`vectros identity list --type user\`).`;
+}
 
 // src/commands/whoami.ts
 async function runWhoami(options, deps = {}) {
@@ -22715,7 +22894,10 @@ async function runWhoami(options, deps = {}) {
     const { identity, baseUrl } = auth;
     let self2 = null;
     try {
-      self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
+      self2 = await resolveSelfPrincipalForTenant(
+        { ...auth, client: auth.client },
+        deps.fetchImpl
+      );
     } catch {
       self2 = null;
     }
@@ -23121,51 +23303,6 @@ ${list}
   });
 }
 
-// src/dev-api.ts
-var DeveloperApiError = class extends Error {
-  statusCode;
-  constructor(message, statusCode) {
-    super(message);
-    this.name = "DeveloperApiError";
-    this.statusCode = statusCode;
-  }
-};
-async function fetchDeveloperUsersPage(opts) {
-  const { cognitoToken, apiBaseUrl, tenant, startFrom, limit, fetchImpl = fetch } = opts;
-  const base = apiBaseUrl.replace(/\/$/, "");
-  let url = `${base}/developer/users?tenant=${encodeURIComponent(tenant)}`;
-  if (startFrom) url += `&startFrom=${encodeURIComponent(startFrom)}`;
-  if (limit !== void 0) url += `&limit=${encodeURIComponent(String(limit))}`;
-  let res;
-  try {
-    res = await fetchImpl(url, {
-      method: "GET",
-      headers: { Authorization: `Bearer ${cognitoToken}` }
-    });
-  } catch (err) {
-    throw new DeveloperApiError(
-      `Request to /developer/users failed: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    const hint = res.status === 403 ? " (this command requires an account owner login \u2014 sign in as the owner and retry)" : "";
-    throw new DeveloperApiError(
-      `GET /developer/users failed: HTTP ${res.status}${hint}${body ? ` \u2014 ${body}` : ""}`,
-      res.status
-    );
-  }
-  let parsed;
-  try {
-    parsed = await res.json();
-  } catch {
-    throw new DeveloperApiError("GET /developer/users returned a non-JSON body");
-  }
-  const data = Array.isArray(parsed.data) ? parsed.data : [];
-  const nextCursor = typeof parsed.nextCursor === "string" ? parsed.nextCursor : null;
-  return { data, nextCursor };
-}
-
 // src/commands/identity.ts
 function isUserDimension(type) {
   return type === "user";
@@ -23461,14 +23598,13 @@ function assertPrincipalShape(principal) {
   }
 }
 var SELF_PRINCIPAL_ALIAS = "me";
-async function resolvePrincipalArg(raw, auth) {
+async function resolvePrincipalArg(raw, auth, deps) {
   if (raw !== SELF_PRINCIPAL_ALIAS) return raw;
-  const self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
-  if (!self2) {
-    throw new Error(
-      "Could not resolve your own user id from your login. Pass --principal usr_<id> explicitly (find the id with `vectros identity list --type user`)."
-    );
-  }
+  const self2 = await resolveSelfPrincipalForTenant(
+    { ...auth, client: auth.client },
+    deps.fetchImpl
+  );
+  if (!self2) throw new Error(selfPrincipalUnresolvedMessage(auth.tenant, "--principal"));
   return self2.principalId;
 }
 function roleSummary(p) {
@@ -23521,7 +23657,7 @@ async function runAccessGrant(opts, deps = {}) {
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
-      const principal = await resolvePrincipalArg(opts.principal, auth);
+      const principal = await resolvePrincipalArg(opts.principal, auth, deps);
       const scopes = hasActions ? [{ allowed_actions: splitCsv(opts.actions) }] : void 0;
       const profile = await client.auth.createAccessProfile({
         contextId: opts.context,
@@ -23531,8 +23667,10 @@ async function runAccessGrant(opts, deps = {}) {
           // Always send the plural `roleIds`, even for a single
           // `--role`: it is a strict superset of the deprecated singular
           // `roleId` (equivalent to `roleIds: ["<value>"]`), and the platform
-          // reads it uniformly regardless of how many roles compose.
-          roleIds: opts.role,
+          // reads it uniformly regardless of how many roles compose. With
+          // `--actions` there is no role: omit `roleIds` (the platform refuses an
+          // empty list next to inline `scopes`).
+          roleIds: hasRole ? opts.role : void 0,
           scopes,
           identityOverrides
         }
@@ -23569,7 +23707,7 @@ async function runAccessRevoke(opts, deps = {}) {
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
-      const principal = await resolvePrincipalArg(opts.principal, auth);
+      const principal = await resolvePrincipalArg(opts.principal, auth, deps);
       await client.auth.deleteAccessProfile({ contextId: opts.context, principalId: principal });
       process.stdout.write(`  \u2714 Revoked ${principal} from '${opts.context}'
 `);
@@ -23598,7 +23736,7 @@ async function runAccessList(opts, deps = {}) {
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
-      const principal = opts.principal ? await resolvePrincipalArg(opts.principal, auth) : void 0;
+      const principal = opts.principal ? await resolvePrincipalArg(opts.principal, auth, deps) : void 0;
       const rows = opts.context ? await drainPages(
         (startFrom) => client.auth.listAccessProfiles({ contextId: opts.context, startFrom, limit: PAGE_LIMIT })
       ) : await drainPages(
@@ -23638,7 +23776,7 @@ async function runAccessGet(opts, deps = {}) {
   return withAuth(opts, deps, async (auth) => {
     const client = auth.client;
     try {
-      const principal = await resolvePrincipalArg(opts.principal, auth);
+      const principal = await resolvePrincipalArg(opts.principal, auth, deps);
       const p = await client.auth.getAccessProfile({ contextId: opts.context, principalId: principal });
       if (opts.json) {
         process.stdout.write(`${formatJson(p)}
@@ -23860,11 +23998,13 @@ async function runAccessExplain(opts, deps = {}) {
     try {
       let principal = opts.principal;
       if (principal === SELF_PRINCIPAL_ALIAS2) {
-        const self2 = await resolveSelfPrincipal(auth.client, auth.cognitoToken);
+        const self2 = await resolveSelfPrincipalForTenant(
+          { ...auth, client: auth.client },
+          deps.fetchImpl
+        );
         if (!self2) {
-          process.stderr.write(
-            "  \u2716 Could not resolve your own user id from your login. Pass --principal usr_<id> explicitly.\n"
-          );
+          process.stderr.write(`  \u2716 ${selfPrincipalUnresolvedMessage(auth.tenant, "--principal")}
+`);
           return 1;
         }
         principal = self2.principalId;
@@ -24243,10 +24383,17 @@ async function runContextDestroy(opts, deps = {}) {
 `);
         return 0;
       }
+      const tenantFlag = auth.tenant === "test" ? " --tenant test" : "";
       process.stdout.write(
         `
   \u2714 teardown of '${contextId}' started \u2014 the context and its contents are being
     deleted asynchronously (it reports status 'purging' until the drain completes)
+
+  Not removed: a service principal a blueprint bootstrap created for this context (the
+  externalId in the blueprint's servicePrincipal) belongs to the whole tenant, so it stays. To clean it up
+  when it exists and nothing else uses it:
+    vectros identity list-all${tenantFlag}
+    vectros identity delete --type user --id <id>${tenantFlag}
 `
       );
       return 0;
@@ -24785,7 +24932,7 @@ ${renderIssuer(issuer)}
 var import_node_fs5 = require("fs");
 var readline6 = __toESM(require("readline/promises"));
 var PROVIDER_TYPES = ["ANTHROPIC_NATIVE", "OPENAI_COMPATIBLE"];
-var BILLING_MODES = ["PLATFORM_BILLED", "CUSTOMER_DIRECT"];
+var BILLING_MODES = ["CUSTOMER_DIRECT"];
 var STATUSES = ["ACTIVE", "DISABLED"];
 var MAX_SECRET_BYTES = 8 * 1024;
 async function readBoundedSecret(stream) {
@@ -24864,12 +25011,17 @@ function renderProviderConfig(c) {
     ["defaultProviderModelId", c.defaultProviderModelId],
     ["waiverType", c.waiverType],
     ["billingMode", c.billingMode],
-    ["platformTokenFactor", c.platformTokenFactor],
-    ["platformOutputWeight", c.platformOutputWeight],
     ["status", c.status],
     ["createdAt", c.createdAt]
   ]);
 }
+function billingModeError(value) {
+  if (value === void 0 || BILLING_MODES.includes(value)) return void 0;
+  if (value === "PLATFORM_BILLED") {
+    return "--billing-mode PLATFORM_BILLED is retired: a provider you configure bills you directly, so CUSTOMER_DIRECT is the only billing mode.";
+  }
+  return invalidEnum("--billing-mode", value, BILLING_MODES);
+}
 function invalidEnum(flag, value, allowed) {
   return `${flag} must be one of ${allowed.join(", ")} (got '${value}').`;
 }
@@ -24880,8 +25032,9 @@ async function runProviderConfigCreate(opts, deps = {}) {
 `);
     return 2;
   }
-  if (!BILLING_MODES.includes(opts.billingMode)) {
-    process.stderr.write(`  \u2716 ${invalidEnum("--billing-mode", opts.billingMode, BILLING_MODES)}
+  const billingModeProblem = billingModeError(opts.billingMode);
+  if (billingModeProblem !== void 0) {
+    process.stderr.write(`  \u2716 ${billingModeProblem}
 `);
     return 2;
   }
@@ -24890,19 +25043,6 @@ async function runProviderConfigCreate(opts, deps = {}) {
 `);
     return 2;
   }
-  if (opts.billingMode === "PLATFORM_BILLED") {
-    if (opts.platformTokenFactor === void 0 || opts.platformOutputWeight === void 0) {
-      process.stderr.write(
-        "  \u2716 --platform-token-factor and --platform-output-weight are required when --billing-mode PLATFORM_BILLED.\n"
-      );
-      return 2;
-    }
-  } else if (opts.platformTokenFactor !== void 0 || opts.platformOutputWeight !== void 0) {
-    process.stderr.write(
-      "  \u2716 --platform-token-factor/--platform-output-weight only apply with --billing-mode PLATFORM_BILLED.\n"
-    );
-    return 2;
-  }
   let apiKeySecret;
   try {
     apiKeySecret = await resolveApiKeySecret(opts.apiKeySecretFile, deps, "required");
@@ -24927,9 +25067,7 @@ async function runProviderConfigCreate(opts, deps = {}) {
           defaultProviderModelId: opts.defaultProviderModelId,
           apiKeySecret,
           waiverType: opts.waiverType,
-          billingMode: opts.billingMode,
-          platformTokenFactor: opts.platformTokenFactor,
-          platformOutputWeight: opts.platformOutputWeight,
+          billingMode: opts.billingMode ?? "CUSTOMER_DIRECT",
           status: opts.status
         })
       });
@@ -25010,8 +25148,9 @@ async function runProviderConfigUpdate(opts, deps = {}) {
 `);
     return 2;
   }
-  if (opts.billingMode !== void 0 && !BILLING_MODES.includes(opts.billingMode)) {
-    process.stderr.write(`  \u2716 ${invalidEnum("--billing-mode", opts.billingMode, BILLING_MODES)}
+  const billingModeProblem = billingModeError(opts.billingMode);
+  if (billingModeProblem !== void 0) {
+    process.stderr.write(`  \u2716 ${billingModeProblem}
 `);
     return 2;
   }
@@ -25044,8 +25183,6 @@ async function runProviderConfigUpdate(opts, deps = {}) {
           apiKeySecret,
           waiverType: opts.waiverType,
           billingMode: opts.billingMode,
-          platformTokenFactor: opts.platformTokenFactor,
-          platformOutputWeight: opts.platformOutputWeight,
           status: opts.status
         })
       });
@@ -26622,15 +26759,14 @@ async function runBlueprintTest(fileOrName, opts, deps = {}) {
 
 // src/commands/join.ts
 var SELF_ALIAS = "me";
-async function resolvePrincipal(as, auth) {
+async function resolvePrincipal(as, auth, deps) {
   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`)."
-      );
-    }
+    const self2 = await resolveSelfPrincipalForTenant(
+      { ...auth, client: auth.client },
+      deps.fetchImpl
+    );
+    if (!self2) throw new Error(selfPrincipalUnresolvedMessage(auth.tenant, "--as"));
     return self2.principalId;
   }
   if (!raw.startsWith("usr_")) {
@@ -26700,7 +26836,7 @@ async function runJoin(opts, deps = {}) {
     const client = auth.client;
     try {
       const tenantId = requireTenantId(auth);
-      const principalId = await resolvePrincipal(opts.as, auth);
+      const principalId = await resolvePrincipal(opts.as, auth, deps);
       const userId = normalizePrincipalUserId(principalId);
       const scopes = hasActions ? [{ allowed_actions: splitCsv(opts.actions) }] : void 0;
       await client.auth.createAccessProfile({
@@ -26711,7 +26847,9 @@ async function runJoin(opts, deps = {}) {
           // Always send the plural `roleIds`, even for a single
           // `--role`: a strict superset of the deprecated singular `roleId`,
           // read uniformly by the platform regardless of how many compose.
-          roleIds: opts.role,
+          // With `--actions` there is no role: omit `roleIds` (the platform
+          // refuses an empty list next to inline `scopes`).
+          roleIds: hasRole ? opts.role : void 0,
           scopes,
           identityOverrides
         }
@@ -26798,9 +26936,9 @@ function emitJoined(opts) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.24.0" : "dev",
-  sdk: true ? "0.46.0" : "dev",
-  blueprints: true ? "0.20.1" : "dev"
+  cli: true ? "0.25.0" : "dev",
+  sdk: true ? "0.47.0" : "dev",
+  blueprints: true ? "0.20.2" : "dev"
 };
 function formatBuildInfo() {
   return `vectros ${BUILD_INFO.cli} (sdk ${BUILD_INFO.sdk}, blueprints ${BUILD_INFO.blueprints})`;
@@ -26837,18 +26975,6 @@ function parseTenantFlag(raw) {
   }
   return raw;
 }
-var NUMBER_FLAG_INVALID = /* @__PURE__ */ Symbol("parseOptionalNumberFlag:invalid");
-function parseOptionalNumberFlag(flag, raw) {
-  if (raw === void 0) return void 0;
-  const n = Number(raw);
-  if (!Number.isFinite(n)) {
-    process.stderr.write(`  \u2716 ${flag} must be a number (got '${raw}')
-`);
-    process.exitCode = 2;
-    return NUMBER_FLAG_INVALID;
-  }
-  return n;
-}
 function toCommonOptions(flags) {
   return {
     env: flags.env,
@@ -27020,7 +27146,7 @@ function registerContextCommands(program, deps) {
     );
   });
   const destroy = context.command("destroy").description(
-    "Permanently destroy an app context and ALL of its data (irreversible; asks for confirmation)."
+    "Permanently destroy an app context and ALL of its data (irreversible; asks for confirmation). A blueprint's service principal belongs to the whole tenant and is NOT removed: delete it with 'identity delete'."
   ).argument("<contextId>", "the app context to destroy").option("--force", "skip the interactive confirmation (required when stdin is not a TTY)").option("--tenant <tenant>", "tenant the context lives in: 'test' or 'live' (default live)");
   addCommonAuthOptions(destroy).action(
     async (contextId, flags) => {
@@ -27175,15 +27301,11 @@ function registerIssuersCommands(program, deps) {
 }
 function registerProviderConfigCommands(program, deps) {
   const providerConfig = program.command("provider-config").description("Manage BYOM (bring-your-own-model) tenant-level provider configs.");
-  const create = providerConfig.command("create").description("Create a new BYOM provider config (not idempotent \u2014 a repeat --alias 400s).").requiredOption("--alias <alias>", "operator-facing name used to select this config; unique per tenant").requiredOption("--provider-type <type>", "'ANTHROPIC_NATIVE' or 'OPENAI_COMPATIBLE'").option("--endpoint <url>", "required for OPENAI_COMPATIBLE (no default); an optional override for ANTHROPIC_NATIVE").option("--declared-processing-region <region>", "customer-asserted, free-text, Vectros-unverified transparency field").option("--default-provider-model-id <id>", "convenience default only \u2014 a per-request model id, when the caller supplies one, always takes precedence").requiredOption("--api-key-secret-file <path>", "path to a file holding the provider credential ('-' for stdin) \u2014 never pass the secret as a bare flag value").requiredOption("--waiver-type <type>", "the waiver code this config is entitled under (e.g. byo-model-inference:customer-key)").requiredOption("--billing-mode <mode>", "'PLATFORM_BILLED' or 'CUSTOMER_DIRECT'").option("--platform-token-factor <n>", "required when --billing-mode PLATFORM_BILLED; refused otherwise").option("--platform-output-weight <n>", "required when --billing-mode PLATFORM_BILLED; refused otherwise").option("--status <status>", "'ACTIVE' or 'DISABLED' (default ACTIVE) \u2014 ACTIVE requires the tenant already hold a granted waiver for --waiver-type").option("--tenant <tenant>", "tenant to create the config in: 'test' or 'live' (default live)");
+  const create = providerConfig.command("create").description("Create a new BYOM provider config (not idempotent \u2014 a repeat --alias 400s).").requiredOption("--alias <alias>", "operator-facing name used to select this config; unique per tenant; 1-64 lowercase letters, digits, - or _").requiredOption("--provider-type <type>", "'ANTHROPIC_NATIVE' or 'OPENAI_COMPATIBLE'").option("--endpoint <url>", "required for OPENAI_COMPATIBLE (no default); an optional override for ANTHROPIC_NATIVE; https on port 443").option("--declared-processing-region <region>", "customer-asserted, free-text, Vectros-unverified transparency field").option("--default-provider-model-id <id>", "convenience default only \u2014 a per-request model id, when the caller supplies one, always takes precedence").requiredOption("--api-key-secret-file <path>", "path to a file holding the provider credential ('-' for stdin) \u2014 never pass the secret as a bare flag value").requiredOption("--waiver-type <type>", "the waiver code this config is entitled under; the platform accepts byo-model-inference:customer-key for a config you set up yourself").option("--billing-mode <mode>", "only 'CUSTOMER_DIRECT' (your provider bills you), which is also the default; 'PLATFORM_BILLED' is retired").option("--status <status>", "'ACTIVE' or 'DISABLED' (default ACTIVE) \u2014 ACTIVE requires the tenant already hold a granted waiver for --waiver-type").option("--tenant <tenant>", "tenant to create the config in: 'test' or 'live' (default live)");
   addCommonAuthOptions(create).action(
     async (flags) => {
       const tenant = parseTenantFlag(flags.tenant);
       if (tenant === TENANT_FLAG_INVALID) return;
-      const platformTokenFactor = parseOptionalNumberFlag("--platform-token-factor", flags.platformTokenFactor);
-      if (platformTokenFactor === NUMBER_FLAG_INVALID) return;
-      const platformOutputWeight = parseOptionalNumberFlag("--platform-output-weight", flags.platformOutputWeight);
-      if (platformOutputWeight === NUMBER_FLAG_INVALID) return;
       process.exitCode = await runProviderConfigCreate(
         {
           ...toCommonOptions(flags),
@@ -27195,8 +27317,6 @@ function registerProviderConfigCommands(program, deps) {
           apiKeySecretFile: flags.apiKeySecretFile,
           waiverType: flags.waiverType,
           billingMode: flags.billingMode,
-          platformTokenFactor,
-          platformOutputWeight,
           status: flags.status,
           tenant
         },
@@ -27214,13 +27334,9 @@ function registerProviderConfigCommands(program, deps) {
   addCommonAuthOptions(get).action(async (id, flags) => {
     process.exitCode = await runProviderConfigGet({ ...toCommonOptions(flags), id }, deps);
   });
-  const update = providerConfig.command("update").description("Patch a provider config (partial update \u2014 an omitted field is left unchanged).").argument("<id>").option("--alias <alias>", "rename this config (still unique per tenant)").option("--provider-type <type>", "'ANTHROPIC_NATIVE' or 'OPENAI_COMPATIBLE'").option("--endpoint <url>", "update the provider endpoint").option("--declared-processing-region <region>", "update the transparency field").option("--default-provider-model-id <id>", "update the convenience default model id").option("--api-key-secret-file <path>", "rotate the provider credential from a file ('-' for stdin); omit to leave the stored secret unchanged").option("--waiver-type <type>", "update the waiver code this config is entitled under").option("--billing-mode <mode>", "'PLATFORM_BILLED' or 'CUSTOMER_DIRECT' \u2014 switching to CUSTOMER_DIRECT clears the platform pricing fields server-side").option("--platform-token-factor <n>", "update the platform pricing factor (PLATFORM_BILLED only)").option("--platform-output-weight <n>", "update the platform pricing weight (PLATFORM_BILLED only)").option("--status <status>", "'ACTIVE' or 'DISABLED' \u2014 activating requires a granted waiver for this config's waiverType");
+  const update = providerConfig.command("update").description("Patch a provider config (partial update \u2014 an omitted field is left unchanged).").argument("<id>").option("--alias <alias>", "rename this config (unique per tenant); the platform refuses a new alias that is not 1-64 lowercase letters, digits, - or _ (an alias the config already holds is accepted)").option("--provider-type <type>", "'ANTHROPIC_NATIVE' or 'OPENAI_COMPATIBLE'; changing the type of an existing config needs --endpoint stated in the same command (--endpoint '' means the provider's default), or the platform answers 400").option("--endpoint <url>", "update the provider endpoint; https on port 443; changing the host needs --api-key-secret-file again; '' clears it (the provider's default), which also changes the host").option("--declared-processing-region <region>", "update the transparency field").option("--default-provider-model-id <id>", "update the convenience default model id").option("--api-key-secret-file <path>", "rotate the provider credential from a file ('-' for stdin); omit to leave the stored secret unchanged (required when --endpoint changes the host)").option("--waiver-type <type>", "update the waiver code this config is entitled under; the platform refuses a change to anything but byo-model-inference:customer-key (a value the config already holds is accepted)").option("--billing-mode <mode>", "only 'CUSTOMER_DIRECT' (your provider bills you); 'PLATFORM_BILLED' is retired. Omit it to leave the stored mode unchanged").option("--status <status>", "'ACTIVE' or 'DISABLED' \u2014 activating requires a granted waiver for this config's waiverType");
   addCommonAuthOptions(update).action(
     async (id, flags) => {
-      const platformTokenFactor = parseOptionalNumberFlag("--platform-token-factor", flags.platformTokenFactor);
-      if (platformTokenFactor === NUMBER_FLAG_INVALID) return;
-      const platformOutputWeight = parseOptionalNumberFlag("--platform-output-weight", flags.platformOutputWeight);
-      if (platformOutputWeight === NUMBER_FLAG_INVALID) return;
       process.exitCode = await runProviderConfigUpdate(
         {
           ...toCommonOptions(flags),
@@ -27233,8 +27349,6 @@ function registerProviderConfigCommands(program, deps) {
           apiKeySecretFile: flags.apiKeySecretFile,
           waiverType: flags.waiverType,
           billingMode: flags.billingMode,
-          platformTokenFactor,
-          platformOutputWeight,
           status: flags.status
         },
         deps
@@ -27502,12 +27616,15 @@ function dimensionOption() {
   ).makeOptionMandatory();
 }
 function registerIdentityCommands(program, deps) {
-  const identity = program.command("identity").description("Manage tenant-wide principals (users + namespaced entities) \u2014 reference, never embed.");
-  const create = identity.command("create").description("Create (idempotent by externalId) a principal.").addOption(dimensionOption()).requiredOption("--external-id <id>", "your stable id for the principal (idempotency key)").option("--name <name>", "display name (entity namespaces only, not --type user)").option("--email <email>", "email (user only)").option("--service", "user only: mint a SERVICE principal (default HUMAN)").option("--scope <ns:value>", "entity only: a parent ownership edge (repeatable, \u22642, e.g. org:<id>)", collect, []).option("--metadata <json>", "JSON object of metadata");
+  const identity = program.command("identity").description("Manage principals: users (tenant-wide) and namespaced entities (an entity lives with its namespace) \u2014 reference, never embed.");
+  const create = identity.command("create").description("Create (idempotent by externalId) a principal.").addOption(dimensionOption()).requiredOption("--external-id <id>", "your stable id for the principal (idempotency key)").option("--name <name>", "display name (entity namespaces only, not --type user)").option("--email <email>", "email (user only)").option("--service", "user only: mint a SERVICE principal (default HUMAN)").option("--scope <ns:value>", "entity only: a parent ownership edge (repeatable, \u22642, e.g. org:<id>)", collect, []).option("--metadata <json>", "JSON object of metadata").option("--tenant <tenant>", "tenant to target: 'test' or 'live' (default live)");
   addCommonAuthOptions(create).action(
     async (flags) => {
+      const tenant = parseTenantFlag(flags.tenant);
+      if (tenant === TENANT_FLAG_INVALID) return;
       process.exitCode = await runIdentityCreate({
         ...toCommonOptions(flags),
+        tenant,
         type: flags.type,
         externalId: flags.externalId,
         name: flags.name,
@@ -27518,11 +27635,14 @@ function registerIdentityCommands(program, deps) {
       }, deps);
     }
   );
-  const list = identity.command("list").description("List principals of a dimension (optionally filtered).").addOption(dimensionOption()).option("--external-id <id>", "filter to a stable id").option("--limit <n>", "page size (1\u2013100)", (v) => Number.parseInt(v, 10));
+  const list = identity.command("list").description("List principals of a dimension (optionally filtered).").addOption(dimensionOption()).option("--external-id <id>", "filter to a stable id").option("--limit <n>", "page size (1\u2013100)", (v) => Number.parseInt(v, 10)).option("--tenant <tenant>", "tenant to target: 'test' or 'live' (default live)");
   addCommonAuthOptions(list).action(
     async (flags) => {
+      const tenant = parseTenantFlag(flags.tenant);
+      if (tenant === TENANT_FLAG_INVALID) return;
       process.exitCode = await runIdentityList({
         ...toCommonOptions(flags),
+        tenant,
         type: flags.type,
         externalId: flags.externalId,
         limit: flags.limit
@@ -27542,20 +27662,30 @@ function registerIdentityCommands(program, deps) {
       );
     }
   );
-  const get = identity.command("get").description("Show one principal by its Vectros id.").addOption(dimensionOption()).requiredOption("--id <vectrosId>", "the Vectros-assigned id (from create/list)");
+  const get = identity.command("get").description("Show one principal by its Vectros id.").addOption(dimensionOption()).requiredOption("--id <vectrosId>", "the Vectros-assigned id (from create/list)").option("--tenant <tenant>", "tenant to target: 'test' or 'live' (default live)");
   addCommonAuthOptions(get).action(async (flags) => {
-    process.exitCode = await runIdentityGet({ ...toCommonOptions(flags), type: flags.type, id: flags.id }, deps);
+    const tenant = parseTenantFlag(flags.tenant);
+    if (tenant === TENANT_FLAG_INVALID) return;
+    process.exitCode = await runIdentityGet({ ...toCommonOptions(flags), tenant, type: flags.type, id: flags.id }, deps);
   });
-  const del = identity.command("delete").description("Delete a principal by its Vectros id.").addOption(dimensionOption()).requiredOption("--id <vectrosId>", "the Vectros-assigned id");
+  const del = identity.command("delete").description("Delete a principal by its Vectros id.").addOption(dimensionOption()).requiredOption("--id <vectrosId>", "the Vectros-assigned id").option("--tenant <tenant>", "tenant to target: 'test' or 'live' (default live)");
   addAuthOptions(del).action(async (flags) => {
-    process.exitCode = await runIdentityDelete({ ...toCommonOptions(flags), type: flags.type, id: flags.id }, deps);
+    const tenant = parseTenantFlag(flags.tenant);
+    if (tenant === TENANT_FLAG_INVALID) return;
+    process.exitCode = await runIdentityDelete(
+      { ...toCommonOptions(flags), tenant, type: flags.type, id: flags.id },
+      deps
+    );
   });
-  const invite = identity.command("invite").description("Onboard a person into a context by email (POST /v1/users/invite) \u2014 no root key required.").requiredOption("--context <contextId>", "the app context the invitee will operate in").requiredOption("--role <roleId>", "an existing Role in that context; the invitee inherits its scopes").requiredOption("--email <email>", "the invitee's email address").option("--first-name <name>", "personalizes the invitation email greeting").option("--accept-url <url>", "your accept-invite landing page (required unless --no-send-email)").option("--no-send-email", "skip platform delivery; the response carries the raw inviteToken/acceptLink instead");
+  const invite = identity.command("invite").description("Onboard a person into a context by email (POST /v1/users/invite) \u2014 no root key required.").requiredOption("--context <contextId>", "the app context the invitee will operate in").requiredOption("--role <roleId>", "an existing Role in that context; the invitee inherits its scopes").requiredOption("--email <email>", "the invitee's email address").option("--first-name <name>", "personalizes the invitation email greeting").option("--accept-url <url>", "your accept-invite landing page (required unless --no-send-email)").option("--no-send-email", "skip platform delivery; the response carries the raw inviteToken/acceptLink instead").option("--tenant <tenant>", "tenant to target: 'test' or 'live' (default live)");
   addCommonAuthOptions(invite).action(
     async (flags) => {
+      const tenant = parseTenantFlag(flags.tenant);
+      if (tenant === TENANT_FLAG_INVALID) return;
       process.exitCode = await runIdentityInvite(
         {
           ...toCommonOptions(flags),
+          tenant,
           context: flags.context,
           role: flags.role,
           email: flags.email,