@vectros-ai/cli 0.22.0 → 0.23.0

package/AUTHORING.md

@@ -5,9 +5,10 @@ A **blueprint** is a versioned, reviewed bundle for one use case: a schema set
 data, all with stable identifiers so applying it twice converges instead of
 duplicating. `vectros bootstrap --blueprint <file>` applies it to provision a
 ready-to-use data model + a narrow `ssk_*` scoped key — no root key, no manual
-admin steps.
+admin steps. `vectros blueprint apply <file> --tenant test|live` applies the same
+blueprint WITHOUT minting a key, for re-applying a change from CI.
 
-This guide is the authoring loop. Everything here except `bootstrap` is
+This guide is the authoring loop. Everything here except `bootstrap` and `blueprint apply` is
 **creds-free and offline** — you can iterate on a blueprint with no account.
 
 > The examples use the bare `vectros` binary — install it once with
@@ -22,10 +23,11 @@ vectros blueprint init my-thing        # 1. scaffold a starter
 vectros blueprint validate ./my-thing.blueprint.yaml   # 2. structural + scope-gate + lint (offline)
 vectros blueprint plan     ./my-thing.blueprint.yaml   # 3. preview what it provisions (offline)
 vectros blueprint-test     ./my-thing.blueprint.yaml --env staging  # 4. prove it live (creds; auto-teardown)
-vectros bootstrap --blueprint ./my-thing.blueprint.yaml # 5. apply for real (needs a bridge token)
+vectros bootstrap --blueprint ./my-thing.blueprint.yaml # 5. apply for real + mint a key (needs a bridge token)
+vectros blueprint apply ./my-thing.blueprint.yaml --tenant test  # 5'. apply for real, no key (CI: add --yes --confirm-existing-principal)
 ```
 
-Steps 1–3 are **creds-free and offline**. Step 4 (`blueprint-test`) and step 5 (`bootstrap`) hit a live
+Steps 1–3 are **creds-free and offline**. Step 4 (`blueprint-test`) and step 5 (`bootstrap` / `blueprint apply`) hit a live
 environment — sign in once first with `vectros login` (`vectros whoami` shows the active session;
 `vectros logout` clears it), or pass `--token`.
 
@@ -93,7 +95,7 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 
 ```
   Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
-    + schema 'thing' (2 fields, HYBRID) lookup: [externalId]
+    + schema 'thing' (1 field, HYBRID) lookup: [title]
     + context 'mcp' (MCP — my-thing)
     + principal 'my-thing-sp' (SERVICE)
     + profile scopes [records:r, records:c, records:u, search:r, schemas:r] (data-plane ✓)
@@ -107,7 +109,7 @@ sharing an action set can still carry different `dataScope`:
 
 ```
   Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
-    + schema 'thing' (2 fields, HYBRID) lookup: [externalId]
+    + schema 'thing' (1 field, HYBRID) lookup: [title]
     + context 'mcp' (MCP — my-thing)
     + principal 'my-thing-sp' (SERVICE)
     + role 'case-handler' (1 clause, actions [records:cru])
@@ -132,6 +134,16 @@ config snippet to stdout instead of merging it into your client's config file. T
 touching your account, stop at `blueprint plan` (offline) — `bootstrap`, with or without `--no-merge`,
 always applies.
 
+**`vectros blueprint apply`** is the same pipeline without the key. `--tenant test|live` is required (no default);
+it prints the account, tenant and context it is pointed at before anything changes and asks (with no terminal,
+`--yes` is required). It **deletes nothing unless `--prune` is passed**: with it, a trigger the file no longer
+declares is removed when its stored `provisionedBy` marker equals this blueprint's `name` (read from the file) and
+its principal's external id is the one this blueprint would derive. Those are stored markers, not verified
+identities, so a blueprint that reuses another's `name` and omits some of its triggers will remove them. An
+existing service principal needs `--confirm-existing-principal` (standing consent in a pipeline). It writes the
+blueprint's sample `seed` records **only when you pass `--seed`**, in either tenant (the opposite of `bootstrap`,
+which seeds unless `--no-seed`); `--no-seed` is refused on `apply`.
+
 **Provisioning a production context — `--no-seed`.** A blueprint's `seed`
 records are illustrative sample data: handy for a getting-started or demo
 context, but synthetic clutter in a context that will hold real data. Pass
@@ -184,9 +196,10 @@ schemas:
         filterable: false       # available as a query filter
         validation: { minLength: 1, maxLength: 200 }   # server-enforced (ValidationRules)
         renderHints: { label: Title, widget: text, order: 1, displayField: true }   # UI hints (displayField = the headline column)
-      - fieldId: externalId
-        fieldType: string
-        required: true
+      # No `externalId` field: it is a first-class identifier the platform reserves. A seed
+      # sets its externalId at the TOP LEVEL of the seed (see `seed:` below), never as a
+      # schema field and never inside `fields`; declaring it makes the first seeded
+      # provision fail with "Required field 'externalId' cannot be empty."
     lookupFields: [title]        # extra O(1) exact-match lookup indexes (max 10);
                                  # object form { fieldName, unique?, rangeEnabled?,
                                  # sortBy?, allowOverflow? } for constraints/range, or
@@ -250,9 +263,9 @@ seed:
     typeName: thing
     externalId: seed-welcome   # stable → idempotent; re-apply converges
     fields: { title: "Hello" }
-    # Seeds are illustrative sample data. They're applied by default; provision a
-    # production context with `bootstrap --no-seed` to skip them (schemas + key
-    # still apply).
+    # Seeds are illustrative sample data. `bootstrap` applies them by default (pass
+    # `--no-seed` for a production context: schemas + key still apply); `blueprint
+    # apply` writes them only when you pass `--seed`.
 
 issuers:
   - issuerId: auth0-prod       # your slug; 3-31 chars, lowercase letter first
@@ -264,9 +277,17 @@ issuers:
     # in the BOOTSTRAP-token phase, alongside app-context/service-principal
     # creation — NOT the same phase as schemas/accessProfile/roles above (see
     # BLUEPRINT_FIELD_PHASES, exported by @vectros-ai/blueprints). Registration
-    # is create-once: re-applying an already-registered issuerId leaves it
-    # unchanged — there's no update, so an edited jwksUri/audience on a live
-    # issuer won't take effect via re-apply.
+    # is idempotent by issuerId, and a re-apply reconciles the editable fields
+    # (subClaim, emailClaim, userinfoUri, restrictedToDomain, selfSignupPolicies,
+    # capturedClaims). The trust-anchor fields (issuer, jwksUri, audience, contextId)
+    # are immutable: editing one on a registered issuer fails the apply with a
+    # 400, and rotating one means deleting the issuer and registering it again.
+    #
+    # On platform 0.45.0 and later an issuer without restrictedToDomain starts
+    # pending_verification and accepts no token until you prove you control the
+    # identity provider with `vectros issuers verify`. bootstrap still exits 0 and
+    # ends its output with the challenge and that command (--require-verified-issuers
+    # turns a pending issuer into exit 4). A restrictedToDomain issuer is active at once.
     #
     # Each entry's contextId must equal the blueprint's own contextId. An issuer
     # is a trust anchor — whoever controls its jwksUri can mint identities your
@@ -637,7 +658,7 @@ one, the loader checks who pushed the current version:
   under a different name instead, or coordinate with whoever owns it.
 - **no owner recorded** (hand-authored via `vectros scripts push`, or pushed
   before this check existed) — refused unless the OPERATOR re-runs
-  `bootstrap` with `--allow-script-adoption`. This is deliberately a
+  `bootstrap` (or `blueprint apply`) with `--allow-script-adoption`. This is deliberately a
   human-supplied CLI flag, never something a blueprint's own YAML/JSON can
   set — the blueprint is untrusted input, and "I already own this name" is not
   something it gets to assert for itself. A successful adopting push reports

package/CHANGELOG.md

@@ -3,6 +3,129 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.23.0 — 2026-09-22
+
+### Added
+
+- **`vectros blueprint apply <file|name> --tenant test|live`** provisions a blueprint into a tenant WITHOUT minting a
+  key: the same credential, gates and loader as `vectros bootstrap`, with no scoped key created, no keyring opened
+  and no MCP client config touched, so a CI runner can re-apply a changed blueprint (a key is named per machine, so
+  a fresh runner would otherwise mint a new one every run). `--tenant` is required (no default), the account, tenant,
+  context and API are printed before anything changes, and with no terminal `--yes` is required (exit `2`).
+  **Deletion is opt-in:** nothing is deleted unless `--prune` is passed, and then only triggers whose stored
+  `provisionedBy` marker equals the blueprint's `name` and whose principal's external id is the one that blueprint
+  would derive, and which the file no longer declares. Those are stored markers, not verified identities, and the
+  name is read from the blueprint file after any input substitution, so `--set` and `--values` can change it. A
+  matched trigger that cannot be removed makes `apply` exit `1`. An existing service principal needs
+  `--confirm-existing-principal` with `--yes` or with no terminal (at a terminal it asks; standing consent in a
+  pipeline); every run that proceeds prints which principal it reused and why. **Sample seed records are opt-in:**
+  unlike `bootstrap`, `apply` writes none unless `--seed` is passed, in either tenant, and never asks; the plan and the
+  summary say whether they will be or were written, and `--no-seed` is refused with exit `2`
+  (`apply does not seed by default: pass --seed to write the sample records`). Exit codes `0` to `3`,
+  and `4` under `--require-verified-issuers`. The flags shared with `bootstrap` come from one table with a parity
+  test; key- and client-related flags are refused with a pointer to `bootstrap`. `bootstrap` itself is unchanged
+  except in what it prints: a trigger row with no blueprint marker, which it never deleted, is now reported as
+  "left in place" instead of "could NOT be removed … still live".
+
+- **`vectros issuers verify <issuerId> --context <ctx>`** answers a `pending_verification` issuer's
+  challenge (platform 0.45.0 and later). A registration made without `restrictedToDomain` accepts no
+  token until you prove you control the identity provider: add an admin-controlled rule there that
+  puts the registration's one-time value in the claim it names, sign in once, and send the resulting
+  JWT. The JWT goes in `--idp-token-file <path>` (or `-`, or piped on stdin) or `--idp-token <jwt>`,
+  never `--token`, which stays your Vectros credential; a value on the command line is visible in your
+  shell history and the process list, so the flag warns. The token is checked once and never printed or
+  stored. Exit `0` verified, `1` the request did not report success (the platform's message, and the `issuers get`
+  command to check where the registration stands before retrying: a timeout can leave it verified), `2` a bad
+  input, reported before any request is made. A value given to `--idp-token-file` that looks like a token is
+  refused without being repeated, input over 64 KB is refused, `--idp-token-file -` is refused on a terminal,
+  and a mistyped flag or command carrying a token is redacted in the parser's error. Every command it prints for you to run carries the same `--tenant`,
+  `--env` and `--base-url` you gave it.
+- **`issuers register` and `issuers get` show a pending registration's challenge**: the claim, the
+  one-time value and its expiry, how to add the rule at Auth0, Okta, Microsoft Entra ID or Keycloak, and
+  the exact `verify` command. `register` exits `0`, since a pending issuer is its expected result. An
+  issuer whose challenge already expired while pending is reported as unverifiable, with the delete
+  command, instead of instructions that cannot work. Nothing prints on a platform that predates the
+  challenge.
+- **`vectros bootstrap` handles an issuer that needs verification.** A finished apply exits `0`; the
+  summary says `pending verification` beside the issuer, and the apply's last output, on stderr, is the
+  challenge and the `verify` command. `--require-verified-issuers` exits `4` instead, after the apply
+  completed (a one-line notice follows the challenge), for a pipeline that must not go green over an issuer that cannot yet sign anyone in. The
+  exit codes are now documented in `bootstrap --help`. The plan preview says up front that an issuer
+  without `restrictedToDomain` will start pending, and `vectros blueprint-test` treats a pending issuer
+  as a pass and says so.
+- **`vectros bootstrap` applies a blueprint issuer's `restrictedToDomain`** (new in
+  `@vectros-ai/blueprints` 0.20.0, which this release requires). The plan lists the domain, it is
+  sent when the issuer is registered and again on a re-apply, and a blueprint that leaves it out
+  never clears a scope set another way. An unverified domain fails the apply with the platform's
+  `400`. The apply also fails, before any schema, profile, role or key is written, when the
+  platform's response does not carry a declared domain: a platform that predates the field ignores
+  it, and carrying on would report success for an issuer that accepts more tokens than the blueprint
+  says. `vectros blueprint-test` checks the same on its readback.
+- **`issuers register` and `issuers update` accept `--restricted-to-domain <domain>`.** Scopes the
+  registration to a domain already verified for your account (verified once, in the developer
+  portal): a token then matches only when its `hd` claim equals that domain, so the registration is
+  never blocked by an unrelated registration of the same issuer and audience. Google Workspace emits
+  `hd` natively; other identity providers need a claims-mapping rule that emits a claim named
+  exactly `hd`, otherwise none of their tokens will match. An unverified domain is refused by the
+  platform with `400`. `issuers register` never changes an existing registration, so when its
+  response does not carry the requested scope (an existing `--issuer-id` with a different one, or a
+  platform that predates the field) it now fails with exit `1` and names `issuers update`, which
+  applies it; a repeat with the same scope is still an idempotent success. `issuers get`,
+  `register` and `update` now show `restrictedToDomain`, and `issuers list` gains a
+  `restricted to domain` column; `--json` output already carried the field.
+- **`issuers update --clear-restricted-to-domain`** removes the domain scope. It is a separate flag
+  because an empty domain is the way the platform spells "remove the scope": a blank
+  `--restricted-to-domain ''` (an unset shell variable, say) is refused with exit `2` instead of
+  being read as a clear, as is any value that is not a DNS name, and the two flags are mutually
+  exclusive. Omitting both leaves the stored scope unchanged. The platform can refuse to clear a
+  scope, for example when another registration already holds the unrestricted `(issuer, audience)`
+  pair; its message says why.
+
+### Changed
+
+- `vectros blueprint plan` ends with both ways to apply (`blueprint apply`, no key; `bootstrap`, which also mints one),
+  and, for a blueprint that declares sample records, says that `bootstrap` writes them unless `--no-seed` while
+  `blueprint apply` writes them only with `--seed`.
+  Every plan now states how a trigger is judged to belong to a blueprint (a stored marker, not a verified identity),
+  and a plan for `apply` says nothing is deleted unless `--prune` is passed. The existing-principal refusal says what
+  is about to happen when no key is minted (the principal's grants are rewritten).
+- Built against the 0.45.0 SDK (`@vectros-ai/sdk`), which adds `verifyIssuer` and the
+  `pending_verification` status with its challenge fields.
+
+### Security
+
+- **`vectros login`'s local callback listener now completes sign-in only on a `GET /callback` carrying that
+  sign-in's own one-time `state`; every other request is ignored and the CLI keeps waiting for the real
+  redirect.** An identity-provider error redirect that arrives without a `state` is also ignored — Amazon
+  Cognito's own error redirects often omit one — and in that case the browser tab says to return to the
+  terminal, the CLI prints one notice, and waits until its timeout: press Ctrl+C and run `vectros login`
+  again. An error the sign-in page reports is shown with control and invisible formatting characters removed
+  and its length capped, and an error code that is not a plain OAuth token is not printed. This does not
+  protect against a program on your machine that can read the `state` out of the process list, where the
+  browser launcher receives the sign-in URL.
+- **The text of a failed sign-in, or of a failed session refresh, is stripped of control characters and capped.**
+  When the token endpoint answers with an error, its response text is now stripped and capped at 500
+  characters wherever the message is built, so it applies to every command that refreshes your session (every
+  authenticated command), not only `vectros login`. Every `login failed:` line is also stripped (line breaks
+  removed) and capped at 1000 characters, whatever the source (a network error, a file error).
+- **Not covered here:** error text that comes from the Vectros API, and the values other commands print (names
+  of keys, roles, contexts), is printed as received. This entry changes only the sign-in flow and the token
+  endpoint's failure text. The plan preview that `vectros blueprint apply` and `bootstrap` print now uses the
+  same, stronger stripping for the issuer fields it shows.
+
+### Fixed
+
+- The re-apply note in the plan preview listed only some of the issuer fields that reconcile. It now
+  names all of them, including `restrictedToDomain` and `capturedClaims`.
+- `AUTHORING.md` said issuer registration is create-once with no update. A re-apply reconciles the
+  editable issuer fields and rejects an edited trust-anchor field (`issuer`, `jwksUri`, `audience`,
+  `contextId`) with the platform's `400`; the text now says so.
+- **`vectros blueprint init`'s scaffold no longer fails on its first seeded provision.** In CLI 0.22.0 and earlier the
+  generated blueprint declared `externalId` as a required schema field, which the platform reserves, so applying it
+  with its seed (`vectros bootstrap`, or `vectros blueprint apply --seed`) stopped with `Required field 'externalId'
+  cannot be empty.` The scaffold and the authoring guide's example now leave the field out; a seed sets its
+  `externalId` at the top level only. A blueprint you scaffolded earlier still needs the field deleted by hand.
+
 ## 0.22.0 — 2026-09-17
 
 ### Changed
@@ -171,7 +294,7 @@ This project adheres to [Semantic Versioning](https://semver.org).
   process stage** (`src/base-url.ts`'s doc comment, `src/scope-gate.ts` x3 — a backend method
   name and two sibling-package references, one of them also a monorepo path —
   `THIRD-PARTY-NOTICES.md`'s generation note naming an internal build-script path, and
-  `src/harness.ts`'s "the Tier-2 panel caught three times" wording) — found by a post-merge
+  `src/harness.ts`'s comment naming an internal review process) — found by a post-merge
   audit. All reworded to describe the mechanism/sibling generically, keeping the substantive
   rationale; no behavioral change.
 

package/README.md

@@ -6,7 +6,8 @@
 The Vectros provisioning CLI — the `vectros` binary:
 
 - **`vectros bootstrap`** — provision a least-privilege MCP credential (+ optional blueprint).
-- **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`), creds-free.
+- **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`, creds-free), and
+  **`apply`** one into a tenant without minting a key (for CI).
 - **`vectros blueprint-test`** — apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.
 - **`vectros context`** — create, list, and destroy app contexts.
 - **`vectros issuers`** — register, update, delete, and inspect third-party IdP issuers (token-exchange trust anchors) for a context.
@@ -73,7 +74,28 @@ On a machine with no local record of a prior mint (e.g. an ephemeral CI
 container re-running `--yes` for the first time) against a blueprint whose
 service principal already exists in the tenant, `--yes` alone isn't enough —
 add `--confirm-existing-principal` to make that expected case explicit and
-non-interactive; see AUTHORING.md's "idempotency contract" for why.
+non-interactive; see AUTHORING.md's "idempotency contract" for why. For a CI re-apply that has no use for the
+key, `vectros blueprint apply` (below) is the better fit.
+
+**An issuer that needs verification.** A blueprint's `issuers` entry registered without `restrictedToDomain` starts
+`pending_verification` on platform 0.45.0 and later: it accepts no token until you prove you control the identity
+provider, which takes a real login there after someone adds a claim rule, so no bootstrap can finish it. A finished
+apply is still a successful apply and exits `0`. The summary says `pending verification` next to the issuer, and the
+apply's last output, on stderr, is the challenge (the claim, the one-time value and its expiry), how to add the rule
+at Auth0, Okta, Microsoft Entra ID or Keycloak, and the exact `vectros issuers verify` command that finishes it.
+Re-running bootstrap shows the same challenge until the issuer is verified, then says nothing about it. If the
+challenge has expired while the issuer was still pending it can never be verified: the output says so, and names
+the delete command and the re-run; nothing is deleted for you. Pass `--require-verified-issuers` to make a pending
+issuer exit `4` instead (the apply itself still completes, and a one-line notice of the exit code follows the
+challenge), for a pipeline that must not go green over an issuer that cannot yet sign anyone in. Domain-scoped issuers (`restrictedToDomain`) are active at once and never pending.
+
+Exit codes: `0` applied (also `--help`, and answering no at "Apply this plan?"); `1` failed: a bad flag, an
+unknown or malformed blueprint, a missing or invalid `--set` input, a declared issuer scope the platform did not
+apply, or any error while applying (the message says what did and did not run); `2` refused by a gate: the scope
+gate or the capability gate rejected the blueprint, an identity it references could not be resolved, or it declares
+a tenant-wide namespace without the opt-in (the message says what, if anything, was already provisioned); `3` a
+confirmation it did not get (an existing service principal, a key that cannot be recovered); `4` applied in full with
+`--require-verified-issuers` and an issuer still pending verification.
 
 A bundled blueprint ships with **sample seed records** so the credential works
 the moment it's minted. For a **production** context that's synthetic clutter:
@@ -82,9 +104,9 @@ scoped key — but creates no sample records, leaving the context clean for real
 data. (Interactively, a blueprint with seeds asks before adding them.) This
 differs from `--blank`, which is credential-only and drops the schemas too.
 
-## `vectros blueprint` — authoring (creds-free)
+## `vectros blueprint` — authoring (creds-free), then `apply`
 
-Author and inspect blueprints without an account. You'll run these repeatedly,
+Author and inspect blueprints without an account (everything here except `apply`, which is the next section and needs credentials). You'll run these repeatedly,
 so install once and drop the `npx` prefix (`npm i -g @vectros-ai/cli`, or prefix
 each command with `npx -y @vectros-ai/cli`). The inner loop:
 
@@ -92,18 +114,82 @@ each command with `npx -y @vectros-ai/cli`). The inner loop:
 vectros blueprint init my-thing                      # scaffold a commented YAML starter
 #   …edit ./my-thing.blueprint.yaml…
 vectros blueprint validate ./my-thing.blueprint.yaml # structural + scope-gate + lint
-vectros blueprint plan     ./my-thing.blueprint.yaml # preview what bootstrap would provision
-vectros bootstrap --blueprint ./my-thing.blueprint.yaml   # apply it
+vectros blueprint plan     ./my-thing.blueprint.yaml # preview what bootstrap or apply would provision
+vectros blueprint apply ./my-thing.blueprint.yaml --tenant test   # provision it, no key (see below)
+vectros bootstrap --blueprint ./my-thing.blueprint.yaml           # provision it AND mint a key for your MCP client
 ```
 
 - `init` — write a starter (`--from <bundled>` copies an exemplar; `--out`, `--force`).
 - `validate` — structural parse → scope gate → linter. Accepts a file **or** a bundled name.
 - `plan` — validate, then a terraform-style preview; mints nothing.
 - `list` — the bundled library.
+- `apply` — provision a blueprint into a tenant, minting no key; needs credentials (next section).
 
 Full guide: [AUTHORING.md](./AUTHORING.md). Format reference:
 [`@vectros-ai/blueprints`](https://www.npmjs.com/package/@vectros-ai/blueprints).
 
+## `vectros blueprint apply` — provision a blueprint, mint no key
+
+```bash
+vectros blueprint apply ./my-thing.blueprint.yaml --tenant test
+# a CI re-apply, from a machine that has never seen this context:
+vectros blueprint apply ./my-thing.blueprint.yaml --tenant live --yes --confirm-existing-principal
+```
+
+`apply` runs the same pipeline as `vectros bootstrap` (the same credential, the same scope and capability gates,
+the same loader) with the key step switched off: the context, its service principal and access profile, schemas,
+roles, issuers, triggers and scripts are created or reconciled (and, only if you pass `--seed`, the blueprint's sample
+seed records are written), but **no scoped key is minted,
+nothing is written to a keyring, and no MCP client config is touched**. (Short-lived bootstrap tokens are minted
+to call the platform, as with `bootstrap`; none is a scoped key.) That is what makes it fit for re-applying
+a changed blueprint from CI: a key is named per machine, so a fresh runner would name (and mint) a new one on every
+run. Use `bootstrap` when you also want the credential.
+
+- **The target is explicit.** `--tenant test|live` is required; there is no default, so a run never lands on
+  `live` by omission. Before it changes anything `apply` prints the account, tenant, context and API it is
+  pointed at, then the plan (which has no key step), then asks to proceed.
+- **It never runs unattended without `--yes`.** With no terminal, `--yes` is required (exit `2`, before anything
+  is read).
+- **Deletion is opt-in.** `apply` deletes nothing unless you pass `--prune`. With it, each trigger in the context
+  whose stored `provisionedBy` marker equals this blueprint's `name` and whose principal's external id is the one
+  this blueprint would derive, and which the file no longer declares, is removed (the rule and its access profile;
+  the principal is kept). Both are **stored markers, not verified identities**, and the name comes from the
+  blueprint **file** (after any `${{ inputs.* }}` substitution, so `--set` and `--values` can change it): the scope gate bounds what a blueprint may grant, not what it may delete, so a blueprint that
+  reuses another one's `name` and omits some of its triggers will remove them. Rows with no marker are left
+  alone and reported; another blueprint's rows are left alone. If a removal it matched fails (a failed read or
+  delete), `apply` exits `1` and names the trigger that may still be live. Without `--prune` the summary says
+  undeclared triggers were left in place. (Apply still replaces an access profile's scopes and a role's rules in
+  place, as `bootstrap` does.)
+- **An existing service principal needs `--confirm-existing-principal`** (with `--yes`, or with no terminal),
+  which is every apply once the principal exists, on any machine: `apply` never reads a local key record, so a
+  machine that ran `bootstrap` is not exempt. It lets `apply` rewrite that principal's access profile, and covers the
+  blueprint's own service principal only (the principals a blueprint's triggers use are ensured without this check,
+  as with `bootstrap`). In a pipeline this flag is standing consent: it also waves through a blueprint whose
+  `servicePrincipal.externalId` collides with an unrelated identity, so keep the blueprint's source reviewed. Every
+  run that proceeds prints which principal it reused (id, external id, created time) and why.
+- **Sample seed records are opt-in: `apply` writes none unless you pass `--seed`,** in either tenant, and never asks.
+  This is the opposite of `bootstrap` (which seeds unless `--no-seed`) on purpose: a blueprint's seeds are
+  illustrative, not real data, and a re-apply from a pipeline must not write them by omission. When the blueprint
+  declares sample records (or you pass `--seed`), the plan and the summary say plainly whether they will be or were
+  written. `--no-seed` is refused here, because a flag that does nothing invites drift:
+  `apply does not seed by default: pass --seed to write the sample records`.
+- **Exit codes:** `0` applied (also `--help`, and declining the confirmation); `1` failed while applying, or
+  `--prune` could not remove a trigger it matched (steps earlier in the plan may already have been applied; a re-run
+  converges); `2` refused, before anything was changed (a usage error, no `--yes` without a terminal, no credential,
+  an unknown or malformed blueprint, a missing `--set` input, an invalid base URL, the scope or capability gate, a
+  tenant-wide namespace without the opt-in), or, after the context and principal were provisioned, an identity the
+  blueprint references that could not be resolved; `3` an existing principal was not confirmed; `4` applied in full
+  but `--require-verified-issuers` was given and an issuer is pending verification.
+
+Flags it shares with `bootstrap` (`--set`, `--values`, `--allow-tenant-wide-namespaces`,
+`--allow-script-adoption`, `--require-verified-issuers`, `--token`, `--base-url`) behave the same. `--tenant`,
+`--yes` and `--confirm-existing-principal` are shared but behave as described above (`--tenant` is required here,
+`--yes` is required without a terminal, and the principal flag applies to every re-apply). The flags that concern a
+key or your MCP client (`--rotate`, `--client`, `--no-merge`, `--activate`, `--no-activate`, `--use-scoped-token`,
+`--test`) belong to `bootstrap` and are refused with a pointer; the blueprint is an argument, not `--blueprint`, and
+there is no `--blank`. A script pushed onto an existing hand-authored name (`--allow-script-adoption`) is checked
+when the scripts are pushed, partway through, not up front. `vectros blueprint apply --help` lists everything.
+
 ## `vectros blueprint-test` — verify it actually provisions (creds-required)
 
 `validate`/`plan` check a blueprint statically; `blueprint-test` proves it
@@ -170,17 +256,22 @@ vectros issuers list --context my-app
 vectros issuers get primary --context my-app
 vectros issuers update primary --context my-app --status suspended
 vectros issuers delete primary --context my-app   # re-types the id to confirm
+vectros issuers verify auth0-prod --context my-app --idp-token-file ./idp-token.txt
 ```
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--captured-claim <name>` (repeatable), `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. `--captured-claim` names additional OIDC claims to capture beyond the email claim on every successful token exchange, stored as your tenant's golden identity-provider-asserted copy for that user; omit it to capture nothing beyond email. At most 20 names of at most 64 characters, no duplicates. `--jwks-uri`/`--userinfo-uri` must be `https://` — an `http://` value is refused with 400. A tenant may hold at most 50 registrations at once; registering past that cap is also refused with 400. A `--self-signup-policy` naming a role that authors, updates, or deletes scripts (`scripts:c`/`u`/`d`) is refused — a self-signup role may still read or execute scripts. |
-| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. `--sub-claim` is refused with 400 once any user has ever bound through this issuer — supplying the value it already has is still a no-op. `--userinfo-uri` must be `https://`, same as at registration. |
+| `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--captured-claim <name>` (repeatable), `--restricted-to-domain <domain>`, `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. `--captured-claim` names additional OIDC claims to capture beyond the email claim on every successful token exchange, stored as your tenant's golden identity-provider-asserted copy for that user; omit it to capture nothing beyond email. At most 20 names of at most 64 characters, no duplicates. `--jwks-uri`/`--userinfo-uri` must be `https://` — an `http://` value is refused with 400. A tenant may hold at most 50 registrations at once; registering past that cap is also refused with 400. A `--self-signup-policy` naming a role that authors, updates, or deletes scripts (`scripts:c`/`u`/`d`) is refused — a self-signup role may still read or execute scripts. `--restricted-to-domain` scopes the registration to a domain already verified for your account (verified once, in the developer portal): a token then matches only when its `hd` claim equals that domain, so the registration is never blocked by an unrelated registration of the same issuer and audience. Google Workspace emits `hd` natively; other identity providers need a claims-mapping rule that emits a claim named exactly `hd`, otherwise none of their tokens will match. An unverified domain is refused with 400; a value that is not a DNS name (including a blank one) is refused locally. `register` never changes an existing registration, so when the response does not carry the requested scope (an existing `--issuer-id` with a different one, or a platform that predates the field) it fails with exit 1 and names `issuers update`, which does apply it; a repeat with the same scope is still an idempotent success. |
+| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--restricted-to-domain <domain>`, `--clear-restricted-to-domain`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. `--sub-claim` is refused with 400 once any user has ever bound through this issuer — supplying the value it already has is still a no-op. `--userinfo-uri` must be `https://`, same as at registration. Omitting `--restricted-to-domain` leaves the stored scope UNCHANGED; `--clear-restricted-to-domain` removes it, and a blank `--restricted-to-domain ''` is refused locally rather than read as a clear. The two are mutually exclusive, and a new domain must already be verified for your account. The platform can refuse to clear a scope (for example when another registration already holds the unrestricted `(issuer, audience)` pair); its message says why. ⚠️ Scoping an existing issuer stops matching every token that carries no matching `hd` claim, including those of users who signed in before. |
 | `delete <issuerId>` | `--context <contextId>` (required), `--force`, `--tenant test\|live` | Re-types the issuer id to confirm (mirrors `context destroy`); `--force` skips the prompt and is required when stdin isn't a TTY. Refused server-side while any user was ever created or matched through this issuer. |
 | `list` | `--context <contextId>` (required), `--tenant test\|live` | Every issuer registered in that context. `--context` has no default — an issuer read is confined to the context you name; there's no tenant-wide "every issuer in every context" view. |
-| `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies and captured claims. |
+| `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies, captured claims and `restrictedToDomain`. |
+| `verify <issuerId>` | `--context <contextId>` (required); `--idp-token-file <path>` (or `-` for stdin), `--idp-token <jwt>`, `--tenant test\|live` | Proves you control the identity provider, activating a `pending_verification` registration (0.45.0+): send a JWT from a real login that carries the registration's one-time value in the claim it names. The JWT can also be piped on stdin, and is checked once and never printed or stored. It is NOT `--token`, which stays your Vectros credential; prefer `--idp-token-file` or stdin, since a value on the command line is visible in your shell history and the process list. Exit `0` verified, `1` this request did not report success (the message says why; `issuers get` shows where the registration stands, which is worth a look before retrying, because a timeout can leave it verified), `2` a bad input (no network is touched). `--idp-token-file` takes a path: a value that looks like a token is refused without being repeated, and so is anything over 64 KB. Given only a pipe, it reads the token from stdin and says so on stderr; `--idp-token-file -` is for a pipe and is refused on a terminal, where a pasted token would be displayed. The provider's OpenID Connect discovery document must list exactly the `jwksUri` you registered. |
 
-All five accept `--json`, plus the common auth flags (`--base-url`, `--token`).
+All six accept `--json`, plus the common auth flags (`--base-url`, `--token`). `register` and `get` print the
+challenge of a `pending_verification` registration (the claim, the one-time value, its expiry) with the same provider
+instructions and the exact `verify` command; a registration made without `--restricted-to-domain` starts that way on
+platform 0.45.0 and later, and `register` exits `0` because a pending issuer is its expected result.
 
 ## `vectros namespace` — scope-namespace registrations