@vectros-ai/cli 0.23.0 → 0.25.0

package/dist/cli.mjs

@@ -523,7 +523,7 @@ var require_graceful_fs = __commonJS({
     function patch(fs5) {
       polyfills(fs5);
       fs5.gracefulify = patch;
-      fs5.createReadStream = createReadStream2;
+      fs5.createReadStream = createReadStream3;
       fs5.createWriteStream = createWriteStream;
       var fs$readFile = fs5.readFile;
       fs5.readFile = readFile4;
@@ -733,7 +733,7 @@ var require_graceful_fs = __commonJS({
           }
         });
       }
-      function createReadStream2(path4, options) {
+      function createReadStream3(path4, options) {
         return new fs5.ReadStream(path4, options);
       }
       function createWriteStream(path4, options) {
@@ -1639,6 +1639,7 @@ __export(api_exports, {
   ContentTooLargeError: () => ContentTooLargeError,
   DocumentContextEvent: () => DocumentContextEvent,
   DocumentLookupRequest: () => DocumentLookupRequest,
+  DocumentPatchRequest: () => DocumentPatchRequest,
   DocumentRequest: () => DocumentRequest,
   DocumentResponse: () => DocumentResponse,
   DoneEvent: () => DoneEvent,
@@ -1982,6 +1983,13 @@ var DocumentLookupRequest;
     Desc: "desc"
   };
 })(DocumentLookupRequest || (DocumentLookupRequest = {}));
+var DocumentPatchRequest;
+((DocumentPatchRequest2) => {
+  DocumentPatchRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
+})(DocumentPatchRequest || (DocumentPatchRequest = {}));
 var FileUploadRequest;
 ((FileUploadRequest2) => {
   FileUploadRequest2.IndexMode = {
@@ -1994,6 +2002,7 @@ var FileUploadRequest;
 var documents_exports = {};
 __export(documents_exports, {
   DocumentLookupRequest: () => DocumentLookupRequest,
+  DocumentPatchRequest: () => DocumentPatchRequest,
   FileUploadRequest: () => FileUploadRequest,
   LookupDocumentsRequestOrder: () => LookupDocumentsRequestOrder
 });
@@ -4040,7 +4049,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.
@@ -4658,6 +4667,7 @@ var AuthClient = class {
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.PaymentRequiredError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -4707,6 +4717,8 @@ var AuthClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 402:
+          throw new PaymentRequiredError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 429:
@@ -5742,7 +5754,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.
@@ -6552,7 +6564,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 the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
+   * Submits 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.
@@ -6615,7 +6627,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, and reports of dangling references and shared rows that were 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.
@@ -6858,7 +6870,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents");
   }
   /**
-   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the `documents:r` scope — a credential holding `documents:c` alone receives a `400` ("already exists") on collision instead of the document.
+   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the `documents:r` scope — a credential holding `documents:c` alone receives a `400` ("already exists") on collision instead of the document. Supplying `externalId` WITHOUT `schemaId` is refused (`400`) unless you also pass `confirmUntyped=true` — externalId uniqueness is scoped per schema, so omitting `schemaId` by mistake would otherwise silently create a separate untyped document instead of targeting the typed one you likely meant.
    *
    * @param {Vectros.IngestDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6878,10 +6890,11 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__ingestDocument(request, requestOptions));
   }
   async __ingestDocument(request, requestOptions) {
-    const { upsert, allowClear, body: _body } = request;
+    const { upsert, allowClear, confirmUntyped, body: _body } = request;
     const _queryParams = {
       upsert,
-      allowClear
+      allowClear,
+      confirmUntyped
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -7116,7 +7129,7 @@ var DocumentsClient = class {
   /**
    * Partially updates a document using an RFC 7386 JSON Merge Patch. The `payload` object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to `null` is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (`title`, `folderId`, `schemaId`, ownership) are set when present and left unchanged when omitted; sending a top-level field as `null` is rejected. Supplying `text` re-ingests the document body (same as PUT). `indexMode`, `externalId`, and `storeText` (text retention is fixed at ingest) are immutable and rejected if present. The merged result is validated against the bound schema. Pass `expectedVersion` for optimistic concurrency (409 on conflict). Requires the `documents:u` scope.
    *
-   * @param {Vectros.PatchDocumentRequest} request
+   * @param {Vectros.DocumentPatchRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
@@ -7127,17 +7140,14 @@ var DocumentsClient = class {
    *
    * @example
    *     await client.documents.patchDocument({
-   *         id: "id",
-   *         body: {
-   *             title: "Patient Intake Form \u2014 Jane Doe"
-   *         }
+   *         id: "id"
    *     })
    */
   patchDocument(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__patchDocument(request, requestOptions));
   }
   async __patchDocument(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, ..._body } = request;
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -7509,7 +7519,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/versions");
   }
   /**
-   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL for the SAME existing document, targeting a newly-staged object rather than the document's current one — your PUT lands there first, and the document only adopts it once the upload is validated (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata). **Your PUT to `uploadUrl` MUST include the header named in the response's `requiredHeaderName`, set to `requiredHeaderValue` exactly.** It is a signed part of the presigned request — the PUT never reaches this service either way, so neither failure uses this API's JSON error shape. Omitting it, or sending a different value, invalidates the request's signature and S3 rejects it with a 403 `SignatureDoesNotMatch`. Sending it correctly makes the URL single-use: `requiredHeaderName` is always `If-None-Match` and `requiredHeaderValue` is always `*` — a create, a recovery upload for a document whose earlier file is missing, and a re-upload ALL target a freshly-minted, never-written key, so the same S3 conditional-write precondition applies uniformly (S3's own documented conditional-write behavior): a replay after the object already exists (from your own completed PUT, or anyone else's) fails with `412 Precondition Failed`; a replay after the object was deleted and never re-created finds an absent key again and can succeed — single-use is a property of the object's existence, not a one-time token. **Either precondition can also fail with `409 Conflict` if your PUT genuinely races a concurrent delete on the same object.** Whichever of `412` or `409` you receive, the remedy is the same: call this endpoint again for a fresh URL rather than retrying the same PUT — a fresh call always targets a new key, so it is never subject to whatever raced the previous one.
+   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL for the SAME existing document, targeting a newly-staged object rather than the document's current one — your PUT lands there first, and the document only adopts it once the upload is validated (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata). **Your PUT to `uploadUrl` MUST include the header named in the response's `requiredHeaderName`, set to `requiredHeaderValue` exactly.** It is a signed part of the presigned request — the PUT never reaches this service either way, so neither failure uses this API's JSON error shape. Omitting it, or sending a different value, invalidates the request's signature and S3 rejects it with a 403 `SignatureDoesNotMatch`. Sending it correctly makes the URL single-use: `requiredHeaderName` is always `If-None-Match` and `requiredHeaderValue` is always `*` — a create, a recovery upload for a document whose earlier file is missing, and a re-upload ALL target a freshly-minted, never-written key, so the same S3 conditional-write precondition applies uniformly (S3's own documented conditional-write behavior): a replay after the object already exists (from your own completed PUT, or anyone else's) fails with `412 Precondition Failed`; a replay after the object was deleted and never re-created finds an absent key again and can succeed — single-use is a property of the object's existence, not a one-time token. **Either precondition can also fail with `409 Conflict` if your PUT genuinely races a concurrent delete on the same object.** Whichever of `412` or `409` you receive, the remedy is the same: call this endpoint again for a fresh URL rather than retrying the same PUT — a fresh call always targets a new key, so it is never subject to whatever raced the previous one. Supplying `externalId` WITHOUT `schemaId` is refused (`400`) unless you also pass `confirmUntyped=true` — externalId uniqueness is scoped per schema, so omitting `schemaId` by mistake would otherwise silently create a separate untyped document instead of targeting the typed one you likely meant.
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7528,9 +7538,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__uploadDocument(request, requestOptions));
   }
   async __uploadDocument(request, requestOptions) {
-    const { upsert, ..._body } = request;
+    const { upsert, confirmUntyped, ..._body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      confirmUntyped
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -9435,6 +9446,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:
@@ -9574,6 +9587,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:
@@ -11871,7 +11886,7 @@ var RenderHintsSchema = z.object({
   helpText: 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: z.boolean().optional()
 }).strict();
@@ -12546,7 +12561,11 @@ var BlueprintIssuerSchema = z.object({
    * actually scoped. An unverified domain fails the apply with the platform's `400`.
    *
    * Omit to register a domain-less issuer. Omitting it on a re-apply leaves an existing scope
-   * unchanged; removing a scope is `vectros issuers update --clear-restricted-to-domain`.
+   * unchanged. On platform 0.45.0 and later a scope is removed only from a registration that
+   * already holds the unrestricted `(issuer, audience)` pair, which one created with a domain
+   * normally does not (`vectros issuers update --clear-restricted-to-domain` is refused for it):
+   * replace it with a new issuer declared without `restrictedToDomain` and verify that, under a
+   * different app context if the old issuer has served users.
    */
   restrictedToDomain: z.string().regex(RESTRICTED_DOMAIN_RE, {
     message: "restrictedToDomain must be a lowercase DNS name such as 'acme.com' \u2014 letters, digits and dashes in dot-separated labels, at least two labels, no scheme, path, port or uppercase; write an internationalized domain in its punycode (xn--\u2026) form"
@@ -13526,7 +13545,8 @@ var BlueprintSchema = 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: z.array(BlueprintNamespaceSchema).optional(),
   /**
@@ -15660,7 +15680,7 @@ async function devRouteError(res, action) {
 }
 function formatCliError(err, opts) {
   const info = extractServerError(err);
-  const actionable = renderActionableError(info);
+  const actionable = renderActionableError(info, opts.notFoundHint);
   const block = actionable ?? `  \u2716 ${opts.action}: ${info.message}
 `;
   const debug = opts.debug ?? Boolean(process.env.VECTROS_MCP_DEBUG);
@@ -15674,7 +15694,7 @@ function formatCliError(err, opts) {
   }
   return block;
 }
-function renderActionableError(info) {
+function renderActionableError(info, notFoundHint) {
   const msg = info.message;
   switch (info.errorCode) {
     case "SESSION_REFRESH_REQUIRED":
@@ -15712,7 +15732,7 @@ function renderActionableError(info) {
   }
   if (info.statusCode === 404) {
     return `  \u2716 ${msg}
-    Check the id \u2014 'vectros context list' enumerates the contexts you can reach.
+    Check the id \u2014 ${notFoundHint ?? "'vectros context list' enumerates the contexts you can reach."}
 `;
   }
   if (/migration-locked|cannot be (changed|modified)|immutable/i.test(msg) && /schema|field|lookup|type/i.test(msg)) {
@@ -16490,6 +16510,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",
@@ -16497,9 +16536,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 {
@@ -16515,31 +16552,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);
@@ -17051,6 +17111,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;
@@ -17191,7 +17252,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;
@@ -17786,15 +17847,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,
@@ -17835,6 +17887,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) {
@@ -18343,14 +18404,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" : "";
@@ -18905,9 +18966,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
@@ -19063,7 +19123,7 @@ var CryptoFileSecretStore = class {
   async setSecret(ref, secret) {
     const key = await this.encryptionKey();
     const iv = randomBytes2(IV_LEN);
-    const cipher = createCipheriv(ALGO, key, iv);
+    const cipher = 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]);
@@ -19086,7 +19146,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 = createDecipheriv(ALGO, key, iv);
+      const decipher = createDecipheriv(ALGO, key, iv, { authTagLength: TAG_LEN });
       decipher.setAuthTag(tag);
       return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8");
     } catch {
@@ -19270,8 +19330,8 @@ async function withIndexLock(dir, fn, timings = LOCK_OPTS) {
       // sections are ~1ms, so in practice the holder is gone before the first tick
       // and nothing is ever detected. (The probe that observed the no-op ran at
       // stale:2000 with the section artificially held open — a configuration we do
-      // not ship. A measurement in a config you don't ship is not evidence:
-      // CONVENTIONS 78, whose first worked example is this very comment.) The
+      // not ship, and a measurement taken in a configuration you don't ship is not
+      // evidence about the configuration you do.) The
       // honest shape: our release runs unconditionally, and after a stale-break
       // collision it CAN remove a successor's fresh lock — one more route to two
       // writers at once, on top of the rmdir race below. The backstop for both is
@@ -19286,7 +19346,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
@@ -21119,7 +21179,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(
@@ -21228,7 +21288,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}'
 `);
@@ -21459,6 +21521,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}
@@ -21830,7 +21898,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}'
 `);
@@ -21963,7 +22033,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;
@@ -22316,10 +22386,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
@@ -22335,8 +22409,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:
@@ -22423,8 +22499,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 }} /
@@ -22536,7 +22614,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}'
 `);
@@ -22670,6 +22750,89 @@ ${BLUEPRINT_HELP}
 // src/program.ts
 import { Command, Option } from "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) {
@@ -22698,6 +22861,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 = {}) {
@@ -22705,7 +22899,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;
     }
@@ -23111,51 +23308,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";
@@ -23451,14 +23603,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) {
@@ -23511,7 +23662,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,
@@ -23521,8 +23672,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
         }
@@ -23559,7 +23712,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}'
 `);
@@ -23588,7 +23741,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(
@@ -23628,7 +23781,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)}
@@ -23850,11 +24003,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;
@@ -24233,10 +24388,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;
@@ -24313,12 +24475,12 @@ function parseRestrictedToDomain(raw) {
   const domain = raw.trim();
   if (domain.length === 0) {
     throw new Error(
-      "--restricted-to-domain must be a non-blank domain (e.g. 'acme.com'). To remove the scope from an existing issuer, use --clear-restricted-to-domain."
+      "--restricted-to-domain must be a non-blank domain (e.g. 'acme.com'). To remove the scope from an existing issuer, use --clear-restricted-to-domain (the platform refuses that unless the registration already holds the unrestricted (issuer, audience) pair)."
     );
   }
   if (!isRestrictedToDomainName(domain.toLowerCase())) {
     throw new Error(
-      `--restricted-to-domain must be a DNS name such as 'acme.com' \u2014 letters, digits and dashes in dot-separated labels, at least two labels, no scheme, path or port (write an internationalized domain in its punycode xn-- form); got '${domain}'. To remove the scope from an existing issuer, use --clear-restricted-to-domain.`
+      `--restricted-to-domain must be a DNS name such as 'acme.com' \u2014 letters, digits and dashes in dot-separated labels, at least two labels, no scheme, path or port (write an internationalized domain in its punycode xn-- form); got '${domain}'. To remove the scope from an existing issuer, use --clear-restricted-to-domain (the platform refuses that unless the registration already holds the unrestricted (issuer, audience) pair).`
     );
   }
   return domain;
@@ -24771,30 +24933,555 @@ ${renderIssuer(issuer)}
   });
 }
 
-// src/commands/namespace.ts
-function renderNamespace(n) {
-  return formatKeyValues([
-    ["namespace", n.namespace],
-    ["contextId", n.contextId ?? "(tenant-wide)"],
-    ["entityBacked", n.entityBacked === void 0 ? void 0 : String(n.entityBacked)],
-    ["reserved", n.reserved === void 0 ? void 0 : String(n.reserved)],
-    ["specificityRank", n.specificityRank === void 0 ? void 0 : String(n.specificityRank)],
-    ["defaultSchemaId", n.defaultSchemaId],
-    ["createdAt", n.createdAt]
-  ]);
+// src/commands/provider-config.ts
+import { createReadStream as createReadStream2 } from "fs";
+import * as readline6 from "readline/promises";
+var PROVIDER_TYPES = ["ANTHROPIC_NATIVE", "OPENAI_COMPATIBLE"];
+var BILLING_MODES = ["CUSTOMER_DIRECT"];
+var STATUSES = ["ACTIVE", "DISABLED"];
+var MAX_SECRET_BYTES = 8 * 1024;
+async function readBoundedSecret(stream) {
+  try {
+    return await readAllFrom(stream, MAX_SECRET_BYTES);
+  } catch (err) {
+    if (err instanceof TokenTooLargeError) {
+      throw new Error(
+        `the input is larger than ${MAX_SECRET_BYTES / 1024} KB, which no API key is; nothing was read further and nothing was sent.`
+      );
+    }
+    throw err;
+  }
 }
-async function runNamespaceList(opts, deps = {}) {
-  return withAuth({ ...opts, context: opts.context }, deps, async (auth) => {
-    const client = auth.client;
-    try {
-      const rows = await drainPages(
-        (startFrom) => client.identity.listNamespaces({
-          limit: PAGE_LIMIT,
-          ...opts.context ? { contextId: opts.context } : {},
-          ...startFrom ? { startFrom } : {}
-        })
+function fileFailureReason2(err) {
+  switch (err?.code) {
+    case "ENOENT":
+      return "no such file.";
+    case "EISDIR":
+      return "that is a directory.";
+    case "EACCES":
+    case "EPERM":
+      return "permission denied.";
+    default:
+      return "it could not be read.";
+  }
+}
+async function resolveApiKeySecret(fileFlag, deps, mode) {
+  const isTty = deps.isTty ?? Boolean(process.stdin.isTTY);
+  const readStdin = deps.readStdin ?? (() => readBoundedSecret(process.stdin));
+  const readTextFile = deps.readTextFile ?? ((path4) => readBoundedSecret(createReadStream2(path4)));
+  let raw;
+  if (fileFlag !== void 0 && fileFlag !== "-") {
+    if (looksLikeCredential(fileFlag)) {
+      throw new Error(
+        "--api-key-secret-file takes the PATH of a file holding the secret, but the value given looks like a secret (or is too long to be a path). Save it to a file and pass that path (for a file in this directory, write ./name), or pipe it on stdin with --api-key-secret-file -."
       );
-      if (opts.json) {
+    }
+    try {
+      raw = await readTextFile(fileFlag);
+    } catch (err) {
+      const name = safeBaseName(fileFlag);
+      throw new Error(
+        `could not read the file given to --api-key-secret-file${name ? ` (${name})` : ""}: ${fileFailureReason2(err)}`
+      );
+    }
+  } else if (fileFlag === "-") {
+    if (isTty) {
+      throw new Error(
+        "stdin is a terminal, so --api-key-secret-file - would have you paste the secret where it is displayed. Pipe it instead (some-command | vectros provider-config \u2026), or save it to a file and pass --api-key-secret-file <path>."
+      );
+    }
+    raw = await readStdin();
+  } else if (mode === "required" && !isTty) {
+    process.stderr.write("  \u2026 no --api-key-secret-file given: reading the secret from stdin.\n");
+    raw = await readStdin();
+  } else if (mode === "required") {
+    throw new Error(
+      "apiKeySecret is required. Save it to a file and pass --api-key-secret-file <path>, or pipe it on stdin (some-command | vectros provider-config create \u2026)."
+    );
+  } else {
+    return void 0;
+  }
+  const secret = raw.trim();
+  if (secret.length === 0) throw new Error("the secret is empty.");
+  return secret;
+}
+function renderProviderConfig(c) {
+  return formatKeyValues([
+    ["id", c.id],
+    ["tenantId", c.tenantId],
+    ["alias", c.alias],
+    ["providerType", c.providerType],
+    ["endpoint", c.endpoint],
+    ["declaredProcessingRegion", c.declaredProcessingRegion],
+    ["defaultProviderModelId", c.defaultProviderModelId],
+    ["waiverType", c.waiverType],
+    ["billingMode", c.billingMode],
+    ["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}').`;
+}
+var NOT_FOUND_HINT = "'vectros provider-config list --tenant <test|live>' enumerates configs in a tenant.";
+async function runProviderConfigCreate(opts, deps = {}) {
+  if (!PROVIDER_TYPES.includes(opts.providerType)) {
+    process.stderr.write(`  \u2716 ${invalidEnum("--provider-type", opts.providerType, PROVIDER_TYPES)}
+`);
+    return 2;
+  }
+  const billingModeProblem = billingModeError(opts.billingMode);
+  if (billingModeProblem !== void 0) {
+    process.stderr.write(`  \u2716 ${billingModeProblem}
+`);
+    return 2;
+  }
+  if (opts.status !== void 0 && !STATUSES.includes(opts.status)) {
+    process.stderr.write(`  \u2716 ${invalidEnum("--status", opts.status, STATUSES)}
+`);
+    return 2;
+  }
+  let apiKeySecret;
+  try {
+    apiKeySecret = await resolveApiKeySecret(opts.apiKeySecretFile, deps, "required");
+  } catch (err) {
+    process.stderr.write(`  \u2716 ${formatError(err)}
+`);
+    return 2;
+  }
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const tenantId = requireTenantId(auth);
+      const res = await fetchImpl(`${auth.baseUrl.replace(/\/$/, "")}/developer/provider-configs`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${auth.cognitoToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+          tenantId,
+          alias: opts.alias,
+          providerType: opts.providerType,
+          endpoint: opts.endpoint,
+          declaredProcessingRegion: opts.declaredProcessingRegion,
+          defaultProviderModelId: opts.defaultProviderModelId,
+          apiKeySecret,
+          waiverType: opts.waiverType,
+          billingMode: opts.billingMode ?? "CUSTOMER_DIRECT",
+          status: opts.status
+        })
+      });
+      if (!res.ok) throw await devRouteError(res, "provider-config create");
+      const config = await res.json();
+      if (opts.json) {
+        process.stdout.write(`${formatJson(config)}
+`);
+        return 0;
+      }
+      process.stdout.write(`
+  \u2714 provider config '${opts.alias}' created
+${renderProviderConfig(config)}
+`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "provider-config create failed" }));
+      return 1;
+    }
+  });
+}
+async function runProviderConfigList(opts, deps = {}) {
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const tenantId = requireTenantId(auth);
+      const url = `${auth.baseUrl.replace(/\/$/, "")}/developer/provider-configs?tenantId=${encodeURIComponent(tenantId)}`;
+      const res = await fetchImpl(url, { method: "GET", headers: { Authorization: `Bearer ${auth.cognitoToken}` } });
+      if (!res.ok) throw await devRouteError(res, "provider-config list");
+      const rows = await res.json();
+      if (opts.json) {
+        process.stdout.write(`${formatJson(rows)}
+`);
+        return 0;
+      }
+      process.stdout.write(
+        "\n" + formatTable(rows, [
+          { header: "id", get: (c) => c.id },
+          { header: "alias", get: (c) => c.alias },
+          { header: "provider type", get: (c) => c.providerType },
+          { header: "billing mode", get: (c) => c.billingMode },
+          { header: "status", get: (c) => c.status }
+        ]) + "\n"
+      );
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "provider-config list failed" }));
+      return 1;
+    }
+  });
+}
+async function runProviderConfigGet(opts, deps = {}) {
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const url = `${auth.baseUrl.replace(/\/$/, "")}/developer/provider-configs/${encodeURIComponent(opts.id)}`;
+      const res = await fetchImpl(url, { method: "GET", headers: { Authorization: `Bearer ${auth.cognitoToken}` } });
+      if (!res.ok) throw await devRouteError(res, "provider-config get");
+      const config = await res.json();
+      if (opts.json) {
+        process.stdout.write(`${formatJson(config)}
+`);
+        return 0;
+      }
+      process.stdout.write(`
+${renderProviderConfig(config)}
+`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "provider-config get failed", notFoundHint: NOT_FOUND_HINT }));
+      return 1;
+    }
+  });
+}
+async function runProviderConfigUpdate(opts, deps = {}) {
+  if (opts.providerType !== void 0 && !PROVIDER_TYPES.includes(opts.providerType)) {
+    process.stderr.write(`  \u2716 ${invalidEnum("--provider-type", opts.providerType, PROVIDER_TYPES)}
+`);
+    return 2;
+  }
+  const billingModeProblem = billingModeError(opts.billingMode);
+  if (billingModeProblem !== void 0) {
+    process.stderr.write(`  \u2716 ${billingModeProblem}
+`);
+    return 2;
+  }
+  if (opts.status !== void 0 && !STATUSES.includes(opts.status)) {
+    process.stderr.write(`  \u2716 ${invalidEnum("--status", opts.status, STATUSES)}
+`);
+    return 2;
+  }
+  let apiKeySecret;
+  try {
+    apiKeySecret = await resolveApiKeySecret(opts.apiKeySecretFile, deps, "optional");
+  } catch (err) {
+    process.stderr.write(`  \u2716 ${formatError(err)}
+`);
+    return 2;
+  }
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const url = `${auth.baseUrl.replace(/\/$/, "")}/developer/provider-configs/${encodeURIComponent(opts.id)}`;
+      const res = await fetchImpl(url, {
+        method: "PUT",
+        headers: { Authorization: `Bearer ${auth.cognitoToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+          alias: opts.alias,
+          providerType: opts.providerType,
+          endpoint: opts.endpoint,
+          declaredProcessingRegion: opts.declaredProcessingRegion,
+          defaultProviderModelId: opts.defaultProviderModelId,
+          apiKeySecret,
+          waiverType: opts.waiverType,
+          billingMode: opts.billingMode,
+          status: opts.status
+        })
+      });
+      if (!res.ok) throw await devRouteError(res, "provider-config update");
+      const config = await res.json();
+      if (opts.json) {
+        process.stdout.write(`${formatJson(config)}
+`);
+        return 0;
+      }
+      process.stdout.write(`
+  \u2714 provider config '${opts.id}' updated
+${renderProviderConfig(config)}
+`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "provider-config update failed", notFoundHint: NOT_FOUND_HINT }));
+      return 1;
+    }
+  });
+}
+async function runProviderConfigDelete(opts, deps = {}) {
+  const { id } = opts;
+  if (!opts.force) {
+    const isTty = deps.isTty ?? Boolean(process.stdin.isTTY);
+    if (!isTty) {
+      process.stderr.write(
+        `  \u2716 provider-config delete needs an interactive confirmation.
+    Re-run with --force to delete '${id}' without a prompt.
+`
+      );
+      return 2;
+    }
+    const promptCtx = deps.createPrompt ? deps.createPrompt() : (() => {
+      const rl = readline6.createInterface({ input: process.stdin, output: process.stdout });
+      return { prompt: (q) => rl.question(q), close: () => rl.close() };
+    })();
+    try {
+      process.stdout.write(
+        `
+  \u26A0 Deleting provider config '${id}' removes it permanently. Any inference call that resolves
+    a provider by this config's alias starts failing immediately. To disable it instead (reversible),
+    run \`vectros provider-config update ${id} --status DISABLED\`.
+
+`
+      );
+      const typed = await promptCtx.prompt(`  Type the config id ('${id}') to confirm: `);
+      if (typed.trim() !== id) {
+        process.stderr.write(`  \u2716 Confirmation did not match \u2014 nothing deleted.
+`);
+        return 1;
+      }
+    } finally {
+      promptCtx.close();
+    }
+  }
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const url = `${auth.baseUrl.replace(/\/$/, "")}/developer/provider-configs/${encodeURIComponent(id)}`;
+      const res = await fetchImpl(url, { method: "DELETE", headers: { Authorization: `Bearer ${auth.cognitoToken}` } });
+      if (!res.ok) throw await devRouteError(res, "provider-config delete");
+      if (opts.json) {
+        process.stdout.write(`${formatJson({ id, deleted: true })}
+`);
+        return 0;
+      }
+      process.stdout.write(`
+  \u2714 provider config '${id}' deleted
+`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "provider-config delete failed", notFoundHint: NOT_FOUND_HINT }));
+      return 1;
+    }
+  });
+}
+
+// src/commands/domains.ts
+import * as readline7 from "readline/promises";
+function renderDomainVerifyResult(d) {
+  return formatKeyValues([
+    ["id", d.id],
+    ["domain", d.domain],
+    ["status", d.status]
+  ]);
+}
+var NOT_FOUND_HINT2 = "'vectros domains list' enumerates your registered domains.";
+async function runDomainsRegister(opts, deps = {}) {
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const res = await fetchImpl(`${auth.baseUrl.replace(/\/$/, "")}/developer/domains`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${auth.cognitoToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ domain: opts.domain })
+      });
+      if (res.status === 409) {
+        const raw = await res.text().catch(() => "");
+        let message = "Domain already registered";
+        let existingId;
+        let existingStatus;
+        try {
+          const parsed = JSON.parse(raw);
+          if (typeof parsed.message === "string" && parsed.message.trim()) message = parsed.message.trim();
+          if (typeof parsed.id === "string") existingId = parsed.id;
+          if (typeof parsed.status === "string") existingStatus = parsed.status;
+        } catch {
+        }
+        if (opts.json) {
+          process.stdout.write(`${formatJson({ message, id: existingId, status: existingStatus })}
+`);
+          return 1;
+        }
+        process.stderr.write(
+          `  \u2716 ${message}${existingId ? ` (id: ${existingId}${existingStatus ? `, status: ${existingStatus}` : ""})` : ""}
+` + (existingStatus === "PENDING" && existingId ? `    Still pending verification. Run: vectros domains verify ${existingId}
+` : "    Run `vectros domains list` to find it.\n")
+        );
+        return 1;
+      }
+      if (!res.ok) throw await devRouteError(res, "domains register");
+      const result = await res.json();
+      if (opts.json) {
+        process.stdout.write(`${formatJson(result)}
+`);
+        return 0;
+      }
+      process.stdout.write(
+        `
+  \u2714 domain '${result.domain ?? opts.domain}' registered (id: ${result.id ?? "?"}, status: ${result.status ?? "PENDING"})
+
+  ${result.instructions ?? `Add a DNS TXT record: _vectros-verify.${result.domain ?? opts.domain} \u2192 "${result.verificationToken ?? ""}"`}
+
+  Once the record is published, run:
+    vectros domains verify ${result.id ?? "<id>"}
+`
+      );
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "domains register failed" }));
+      return 1;
+    }
+  });
+}
+async function runDomainsList(opts, deps = {}) {
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const res = await fetchImpl(`${auth.baseUrl.replace(/\/$/, "")}/developer/domains`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${auth.cognitoToken}` }
+      });
+      if (!res.ok) throw await devRouteError(res, "domains list");
+      const rows = await res.json();
+      if (opts.json) {
+        process.stdout.write(`${formatJson(rows)}
+`);
+        return 0;
+      }
+      process.stdout.write(
+        "\n" + formatTable(rows, [
+          { header: "id", get: (d) => d.id },
+          { header: "domain", get: (d) => d.domain },
+          { header: "status", get: (d) => d.status },
+          { header: "verified at", get: (d) => d.verifiedAt }
+        ]) + "\n"
+      );
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "domains list failed" }));
+      return 1;
+    }
+  });
+}
+async function runDomainsDelete(opts, deps = {}) {
+  const { id } = opts;
+  if (!opts.force) {
+    const isTty = deps.isTty ?? Boolean(process.stdin.isTTY);
+    if (!isTty) {
+      process.stderr.write(
+        `  \u2716 domains delete needs an interactive confirmation.
+    Re-run with --force to delete '${id}' without a prompt.
+`
+      );
+      return 2;
+    }
+    const promptCtx = deps.createPrompt ? deps.createPrompt() : (() => {
+      const rl = readline7.createInterface({ input: process.stdin, output: process.stdout });
+      return { prompt: (q) => rl.question(q), close: () => rl.close() };
+    })();
+    try {
+      process.stdout.write(
+        `
+  \u26A0 Deleting domain '${id}' removes its proof-of-control record. The platform refuses this while
+    any active webhook still references it \u2014 disable or delete those first if this fails.
+
+`
+      );
+      const typed = await promptCtx.prompt(`  Type the domain id ('${id}') to confirm: `);
+      if (typed.trim() !== id) {
+        process.stderr.write(`  \u2716 Confirmation did not match \u2014 nothing deleted.
+`);
+        return 1;
+      }
+    } finally {
+      promptCtx.close();
+    }
+  }
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const res = await fetchImpl(`${auth.baseUrl.replace(/\/$/, "")}/developer/domains/${encodeURIComponent(id)}`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${auth.cognitoToken}` }
+      });
+      if (!res.ok) throw await devRouteError(res, "domains delete");
+      if (opts.json) {
+        process.stdout.write(`${formatJson({ id, deleted: true })}
+`);
+        return 0;
+      }
+      process.stdout.write(`
+  \u2714 domain '${id}' deleted
+`);
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "domains delete failed", notFoundHint: NOT_FOUND_HINT2 }));
+      return 1;
+    }
+  });
+}
+async function runDomainsVerify(opts, deps = {}) {
+  return withAuth({ ...opts, provisioning: true }, deps, async (auth) => {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+      const res = await fetchImpl(
+        `${auth.baseUrl.replace(/\/$/, "")}/developer/domains/${encodeURIComponent(opts.id)}/verify`,
+        { method: "POST", headers: { Authorization: `Bearer ${auth.cognitoToken}` } }
+      );
+      if (!res.ok) throw await devRouteError(res, "domains verify");
+      const result = await res.json();
+      const verified = result.verified === true && result.status === "VERIFIED";
+      if (opts.json) {
+        process.stdout.write(`${formatJson(result)}
+`);
+        return verified ? 0 : 1;
+      }
+      if (!verified) {
+        process.stderr.write(
+          `  \u2716 domain '${result.domain ?? opts.id}' is not verified (status: ${result.status ?? "(none)"}).
+    Check the DNS TXT record is published, allow time for it to propagate, then re-run this command.
+`
+        );
+        return 1;
+      }
+      process.stdout.write(
+        `
+  \u2714 domain '${result.domain ?? opts.id}' verified.
+${renderDomainVerifyResult(result)}
+`
+      );
+      return 0;
+    } catch (err) {
+      process.stderr.write(formatCliError(err, { action: "domains verify failed", notFoundHint: NOT_FOUND_HINT2 }));
+      return 1;
+    }
+  });
+}
+
+// src/commands/namespace.ts
+function renderNamespace(n) {
+  return formatKeyValues([
+    ["namespace", n.namespace],
+    ["contextId", n.contextId ?? "(tenant-wide)"],
+    ["entityBacked", n.entityBacked === void 0 ? void 0 : String(n.entityBacked)],
+    ["reserved", n.reserved === void 0 ? void 0 : String(n.reserved)],
+    ["specificityRank", n.specificityRank === void 0 ? void 0 : String(n.specificityRank)],
+    ["defaultSchemaId", n.defaultSchemaId],
+    ["createdAt", n.createdAt]
+  ]);
+}
+async function runNamespaceList(opts, deps = {}) {
+  return withAuth({ ...opts, context: opts.context }, deps, async (auth) => {
+    const client = auth.client;
+    try {
+      const rows = await drainPages(
+        (startFrom) => client.identity.listNamespaces({
+          limit: PAGE_LIMIT,
+          ...opts.context ? { contextId: opts.context } : {},
+          ...startFrom ? { startFrom } : {}
+        })
+      );
+      if (opts.json) {
         process.stdout.write(`${formatJson(rows)}
 `);
         return 0;
@@ -24875,7 +25562,7 @@ ${renderNamespace(ns)}
 
 // src/commands/scripts.ts
 import { readFile as readFile3 } from "fs/promises";
-import * as readline6 from "readline/promises";
+import * as readline8 from "readline/promises";
 var SOURCE_MAX_BYTES = 3e5;
 var INPUT_CONTRACT_MAX_BYTES = 5e4;
 var utf8Bytes2 = (s) => new TextEncoder().encode(s).length;
@@ -25094,7 +25781,7 @@ async function runScriptsDelete(opts, deps = {}) {
       return 2;
     }
     const promptCtx = deps.createPrompt ? deps.createPrompt() : (() => {
-      const rl = readline6.createInterface({ input: process.stdin, output: process.stdout });
+      const rl = readline8.createInterface({ input: process.stdin, output: process.stdout });
       return { prompt: (q) => rl.question(q), close: () => rl.close() };
     })();
     try {
@@ -26077,15 +26764,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_")) {
@@ -26155,7 +26841,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({
@@ -26166,7 +26852,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
         }
@@ -26253,9 +26941,9 @@ function emitJoined(opts) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  cli: true ? "0.23.0" : "dev",
-  sdk: true ? "0.45.0" : "dev",
-  blueprints: true ? "0.20.0" : "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})`;
@@ -26340,6 +27028,8 @@ function buildProgram(deps = {}) {
   registerRoleCommands(program, deps);
   registerContextCommands(program, deps);
   registerIssuersCommands(program, deps);
+  registerProviderConfigCommands(program, deps);
+  registerDomainsCommands(program, deps);
   registerNamespaceCommands(program, deps);
   registerScriptsCommands(program, deps);
   registerAssumeCommand(program, deps);
@@ -26461,7 +27151,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) => {
@@ -26550,7 +27240,10 @@ function registerIssuersCommands(program, deps) {
   ).option("--clear-captured-claims", "capture nothing beyond the email claim (sends an empty list; XOR --captured-claim)").option(
     "--restricted-to-domain <domain>",
     "scope the registration to a domain already verified for your account; a token with no matching 'hd' claim then stops matching \u2014 omit to leave unchanged. Refused on a registration that is pending verification: verify it first"
-  ).option("--clear-restricted-to-domain", "remove the domain scope (XOR --restricted-to-domain)").option("--tenant <tenant>", "tenant the context lives in: 'test' or 'live' (default live)");
+  ).option(
+    "--clear-restricted-to-domain",
+    "remove the domain scope (XOR --restricted-to-domain). Refused unless the registration already holds the unrestricted (issuer, audience) pair, which one created scoped to a domain normally does not; see the README"
+  ).option("--tenant <tenant>", "tenant the context lives in: 'test' or 'live' (default live)");
   addCommonAuthOptions(update).action(
     async (issuerId, flags) => {
       const tenant = parseTenantFlag(flags.tenant);
@@ -26611,6 +27304,89 @@ 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; 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;
+      process.exitCode = await runProviderConfigCreate(
+        {
+          ...toCommonOptions(flags),
+          alias: flags.alias,
+          providerType: flags.providerType,
+          endpoint: flags.endpoint,
+          declaredProcessingRegion: flags.declaredProcessingRegion,
+          defaultProviderModelId: flags.defaultProviderModelId,
+          apiKeySecretFile: flags.apiKeySecretFile,
+          waiverType: flags.waiverType,
+          billingMode: flags.billingMode,
+          status: flags.status,
+          tenant
+        },
+        deps
+      );
+    }
+  );
+  const list = providerConfig.command("list").description("List provider configs in one tenant.").option("--tenant <tenant>", "tenant to read: 'test' or 'live' (default live)");
+  addCommonAuthOptions(list).action(async (flags) => {
+    const tenant = parseTenantFlag(flags.tenant);
+    if (tenant === TENANT_FLAG_INVALID) return;
+    process.exitCode = await runProviderConfigList({ ...toCommonOptions(flags), tenant }, deps);
+  });
+  const get = providerConfig.command("get").description("Show one provider config's metadata (no secret \u2014 the platform never returns it).").argument("<id>");
+  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 (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) => {
+      process.exitCode = await runProviderConfigUpdate(
+        {
+          ...toCommonOptions(flags),
+          id,
+          alias: flags.alias,
+          providerType: flags.providerType,
+          endpoint: flags.endpoint,
+          declaredProcessingRegion: flags.declaredProcessingRegion,
+          defaultProviderModelId: flags.defaultProviderModelId,
+          apiKeySecretFile: flags.apiKeySecretFile,
+          waiverType: flags.waiverType,
+          billingMode: flags.billingMode,
+          status: flags.status
+        },
+        deps
+      );
+    }
+  );
+  const del = providerConfig.command("delete").description("Delete a provider config.").argument("<id>").option("--force", "skip the interactive confirmation (required when stdin is not a TTY)");
+  addCommonAuthOptions(del).action(async (id, flags) => {
+    process.exitCode = await runProviderConfigDelete(
+      { ...toCommonOptions(flags), id, force: Boolean(flags.force) },
+      deps
+    );
+  });
+}
+function registerDomainsCommands(program, deps) {
+  const domains = program.command("domains").description("Manage account-level domain ownership verification (DNS TXT proof-of-control).");
+  const register = domains.command("register").description("Register a domain and start DNS TXT verification (not idempotent \u2014 a repeat --domain 409s).").requiredOption("--domain <domain>", "the domain to prove control of (e.g. example.com)");
+  addCommonAuthOptions(register).action(async (flags) => {
+    process.exitCode = await runDomainsRegister({ ...toCommonOptions(flags), domain: flags.domain }, deps);
+  });
+  const list = domains.command("list").description("List domains registered for this account (both tenants share this list).");
+  addCommonAuthOptions(list).action(async (flags) => {
+    process.exitCode = await runDomainsList(toCommonOptions(flags), deps);
+  });
+  const del = domains.command("delete").description("Deregister a domain (refused while any active webhook still references it).").argument("<id>").option("--force", "skip the interactive confirmation (required when stdin is not a TTY)");
+  addCommonAuthOptions(del).action(async (id, flags) => {
+    process.exitCode = await runDomainsDelete({ ...toCommonOptions(flags), id, force: Boolean(flags.force) }, deps);
+  });
+  const verify = domains.command("verify").description("Perform one DNS TXT lookup and report VERIFIED/FAILED \u2014 always re-runnable, never polls.").argument("<id>");
+  addCommonAuthOptions(verify).action(async (id, flags) => {
+    process.exitCode = await runDomainsVerify({ ...toCommonOptions(flags), id }, deps);
+  });
+}
 function registerNamespaceCommands(program, deps) {
   const namespace = program.command("namespace").description("Manage scope-namespace registrations (whether scope:<namespace> values resolve to identity entities).");
   const register = namespace.command("register").description("Register a new scope namespace (NOT idempotent \u2014 a repeat name 400s).").argument("<name>", "namespace name: 2-32 chars, a lowercase letter first, then lowercase/digit/dash/underscore").requiredOption("--context <c>", "app context to own this registration").requiredOption("--specificity-rank <n>", "position in the account specificity order (integer 0-1000000, unique)").option("--entity-backed", "values must resolve to an identity entity (create via `identity create --type <name>`)").option("--default-schema-id <id>", "default record schema bound to entities in this namespace");
@@ -26845,12 +27621,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,
@@ -26861,11 +27640,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
@@ -26885,20 +27667,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,