@vectros-ai/cli 0.21.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
@@ -625,14 +646,47 @@ version and compares the stored `source` and `declaredInputContract` against
 what the blueprint declares, and pushes only on a real difference. So a re-apply
 of an unedited blueprint writes nothing, and editing `source` stores exactly one
 new version, which every `version: latest` rule then picks up. The apply summary
-reports which of the two happened per script.
-
-Two consequences worth planning for. A concurrent apply of the same blueprint
-can collide on one script name; the loader re-reads and retries once, so two
-runners applying identical content converge rather than storing it twice, but a
-sustained collision fails the apply and asks you to re-run. And **removing a
-`scripts:` entry does not delete anything** — every stored version stays, because
-a script carries no record of which blueprint pushed it. Remove one deliberately
+reports which of `created` (no prior version) / `superseded` (this blueprint's
+own prior version, replaced) / `adopted` (see below) / `unchanged` happened per
+script.
+
+**A THIRD qualification: pushing onto a name that already has a version is
+gated on OWNING it.** A script name is a flat, per-context namespace shared
+with every other blueprint and every hand-pushed script, so before superseding
+one, the loader checks who pushed the current version:
+- **owned by a different blueprint** — refused outright, no override. Ship
+  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` (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
+  `adopted`, distinct from an ordinary `superseded`.
+
+  **Know before you rely on this: adoption is safe for an account owner,
+  and refused for a Dev Portal sub-user adopting someone else's hand-push.**
+  The platform's own authorization still applies underneath this flag, and it
+  resolves caller identity differently for the two shapes. An account owner
+  always authenticates as the same identity regardless of which login session
+  minted the token, so adopting a script you (the owner) hand-pushed earlier —
+  or one nobody's identity is recorded against at all — succeeds. A distinct
+  team member (a sub-user) resolves to their own, different identity, and the
+  platform refuses to supersede an unmarked name pushed by anyone else — so
+  one sub-user cannot adopt a script a DIFFERENT sub-user hand-pushed, even
+  with this flag. If you hit that, either have the original pusher run the
+  adopting apply, or push the script under the account owner's own login
+  first.
+- **owned by this SAME blueprint, or the name is brand new** — no flag needed;
+  this is the ordinary re-apply / first-push path.
+
+Two more consequences worth planning for. A concurrent apply of the same
+blueprint can collide on one script name; the loader re-reads and retries once,
+so two runners applying identical content converge rather than storing it
+twice, but a sustained collision fails the apply and asks you to re-run. And
+**removing a `scripts:` entry does not delete anything** — every stored version
+stays, because there is no second, principal-shaped factor to safely gate a
+DELETE the way a trigger row's provenance marker does. Remove one deliberately
 with `vectros scripts delete`.
 
 ## Distribution

package/CHANGELOG.md

@@ -3,6 +3,315 @@
 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
+
+- **⚠️ BREAKING: `vectros bootstrap --blueprint` now refuses to push a script version onto a name it
+  cannot show it owns.** Previously, a blueprint declaring `scripts:` could push a new version onto
+  ANY existing script name in the target context — including one it never declared, hand-authored, or
+  belonging to a different blueprint — with no error. If a pre-existing trigger rule referenced that
+  name via `version: 'latest'` (the only form a blueprint-shipped script may use), the newly pushed
+  code would run under that rule's own, unrelated grant from its very next firing. An apply that used
+  to succeed against such a name now refuses before minting anything: a name already owned by a
+  DIFFERENT blueprint refuses unconditionally (push under a different name instead); a name with no
+  ownership marker at all (hand-authored, or pushed before this marker existed) refuses unless the new
+  `--allow-script-adoption` flag is passed, reporting the outcome as `adopted` rather than
+  `superseded`. **This is a MINOR bump, not a patch, for the same reason as the entry above:** an
+  operator or CI pipeline that did nothing wrong and passed no new flag can now see an apply that
+  previously succeeded fail instead. A blueprint re-applying onto a name it already owns, or shipping
+  a brand-new name, is unaffected either way. See `AUTHORING.md`'s *idempotency contract* section for
+  the full behavior.
+- **⚠️ BREAKING: `--no-merge` no longer implies an unattended run.** `--no-merge`'s documented
+  purpose is only to change where the resulting config goes (printed vs. merged into your
+  client's config file) — it still mints/reconciles the same real state either way — but both
+  the "Apply this plan?" confirmation and the seed-data opt-out prompt used to treat it as an
+  implicit `--yes`, so an operator (or a script) that had been relying on `--no-merge` alone to
+  run without either prompt will now be asked, if the session is interactive. **This is a MINOR
+  bump, not a patch, for the same reason as `@vectros-ai/blueprints`' own bump below: narrowing
+  an UNATTENDED-RUN contract is a breaking change for a script or wrapper that passes no new
+  flag, arguably a sharper break than narrowing an input contract, since the caller did nothing
+  wrong and gets no error — it just now blocks on a prompt it never used to see.** Pass `--yes`
+  explicitly if you need `--no-merge` to keep running unattended; a genuinely non-interactive
+  session (no TTY — the common case for CI) is unaffected either way, since neither prompt ever
+  fires there. The help text is corrected to say so.
+
+### Security
+
+- **`vectros login`'s persisted Cognito refresh token could be POSTed to an attacker-controlled
+  host.** `VECTROS_COGNITO_DOMAIN` (and `VECTROS_COGNITO_REGION`, interpolated into the default
+  domain) were read verbatim from the environment and never validated — unlike the partner-API base
+  URL, which already goes through the same credential-exfil guard (`validateBaseUrl`). A developer
+  with an env var influenced by a repo-scoped config they never read as executable (a `.envrc`, a
+  devcontainer, a CI variable, an `.mcp.json` snippet) could have their long-lived Cognito refresh
+  token — and, on the interactive flow, the authorization code + PKCE verifier — sent to that host
+  on the very next creds-bearing command, with no prompt and no warning.
+
+  The Cognito domain now goes through `validateBaseUrl` too, extended with an allow-list entry for
+  the two exact Cognito hosted-UI hosts this CLI actually talks to (the Cognito domain is never a
+  `vectros.ai` host, so it needed its own entry rather than the partner-API allow-list unchanged —
+  and a broad `*.amazoncognito.com` suffix was deliberately rejected as too wide: that apex is
+  AWS's shared namespace for every Cognito user pool of every AWS customer, not a Vectros-owned
+  one); `VECTROS_COGNITO_REGION` is checked against an AWS-region shape before it is ever interpolated
+  into a URL. Only affects anyone who has run `vectros login` and does not use
+  `--token`/`VECTROS_BOOTSTRAP_TOKEN`.
+
+  **This narrows the vector; it does not close it against an attacker with unconstrained
+  environment control.** `VECTROS_ALLOW_INSECURE_BASE_URL=1` still opts out of the new allow-list
+  (loudly — a warning is logged), same as the pre-existing partner-API base-url guard it mirrors —
+  so an attacker able to set `VECTROS_COGNITO_DOMAIN` can, in principle, also set that opt-out
+  variable in the same reach. The fix protects the common case (an env var landing without the
+  reach to also flip a second, differently-named one) but is not a guarantee against an attacker
+  who already controls the whole environment.
+- **A blueprint-authored free-text field with no character-set constraint could forge a fake
+  extra line, hide/reorder text, or otherwise misrepresent what `vectros bootstrap --blueprint`'s
+  pre-apply plan preview AND its identity-disclosure/confirmation prompt show an operator before
+  they approve a real mint** — a raw newline/CR, an ANSI escape sequence, a Unicode line/paragraph
+  separator, a bidi-override/isolate/mark character, or an invisible/zero-width character embedded
+  in a value like a role's `allowedActions`/`dataScope`, a declared identity's `externalId`
+  (printed immediately before the "Apply this plan?" gate), or a blueprint's own `name`/
+  `contextName` could make the rendered plan (or the confirmation prompt itself) show something
+  other than what would actually be provisioned. **A separate, stronger check now also closes the
+  HOMOGLYPH class for an issuer's `issuer`/`jwksUri`/`userinfoUri`** — a Unicode look-alike domain
+  (e.g. a Cyrillic character standing in for a Latin one), invisible to any character blocklist —
+  by requiring those three fields to be printable-ASCII `https://` URLs whose AUTHORITY contains
+  only letters, digits, dot, dash, and an optional port (no userinfo, no percent-encoding, no
+  non-ASCII host); an internationalized domain must be supplied in its already-punycode (`xn--…`)
+  form. `http://` is explicitly rejected — the platform hard-refuses a non-`https` issuer at
+  registration, so accepting it here would repeat this ecosystem's own "lints clean, then 400s at
+  apply" anti-pattern for the exact field this check exists to catch problems in beforehand.
+
+  Requires **`@vectros-ai/blueprints@0.19.0`** (a MINOR bump, not patch — this narrows what the
+  library accepts, which is a breaking change for a validation library's published contract, even
+  though this repo's own blueprints are unaffected; see that package's own CHANGELOG entry for the
+  full field list, the named residuals of the URL check — a trailing-dot host and a bare IPv4
+  literal still pass, a bracketed IPv6 literal is rejected as an accepted side effect — and,
+  importantly, what is deliberately NOT covered — length is still unbounded, and the homoglyph
+  class stays open for non-URL fields like `name`/`contextName`/`fieldId`, since no enumerable
+  blocklist can close it there the way a positive URL-authority grammar can for a URL). The schema
+  closes both classes at parse time, once, for every current and future rendered surface, rather
+  than requiring each renderer to sanitize its own inputs. This preview's own per-field
+  sanitization (`jwksUri`/`userinfoUri`/`issuer`/`capturedClaims`, added in the previous entry
+  below) stays in place as a second line of defense for a caller that reaches `buildPlan` without
+  going through the parser — which is how every bundled/first-party blueprint (`--blueprint
+  task-management`, etc.) is loaded today.
+- **The plan preview for `vectros bootstrap --blueprint` omitted an issuer's trust-anchor
+  fields.** `jwksUri` (whoever controls it can mint identities the platform accepts) and, when
+  set, `userinfoUri` (fetched with the presented token as bearer) were never rendered — an
+  operator approving the plan for a pack declaring a malicious issuer saw its context and a
+  self-signup policy count, never the field that actually decides trust. Both are now always
+  disclosed, and a self-signup policy is now listed by its actual `signupType→roleId` pairing
+  instead of a bare count, matching the standard the preview already applies to captured
+  identity-provider claims.
+
+### Fixed
+
+- **A degraded credential store (file-backed, not your OS keychain) now warns — at write time,
+  and now at read time too — for BOTH ways this can be a fixable install accident, not just
+  one.** Previously: the optional `@napi-rs/keyring` package loading but being BROKEN (a
+  version/ABI mismatch, a corrupt native binary, an unrecognised module shape) already warned;
+  but the package being entirely ABSENT was always treated as an ordinary, nothing-to-fix
+  platform limitation — even on a platform/arch this CLI ships a prebuilt native binary for,
+  where the only way to end up without it is an npm install that silently skipped the optional
+  dependency. Both throw the identical `MODULE_NOT_FOUND` error, so telling them apart needed a
+  new check: whether a prebuilt is actually known to exist for the current `process.platform`/
+  `process.arch`, read from `@napi-rs/keyring`'s own published platform matrix — consulted
+  regardless of what the underlying failure looks like, not only for a recognised
+  `MODULE_NOT_FOUND`-shaped error (a genuinely-unsupported platform's own failure can carry no
+  error code at all, and every other error/code was previously treated as an install accident
+  unconditionally, which produced permanent, un-fixable "try reinstalling" noise on exactly the
+  platforms this feature must stay silent on). Now, a write about to land in the weaker store,
+  or a read of an entry already stamped for the OS keychain, prints one warning naming the
+  actual cause and the remedy on EITHER fixable path — install failure or silent absence —
+  while a genuinely-unsupported platform/arch stays quiet, whatever shape its failure takes.
+  **One accepted, disclosed residual:** this can't distinguish glibc from musl on Linux — `arm`
+  and `riscv64` each have a real GNU-libc prebuilt (so a glibc machine there is fully covered),
+  but neither has a MUSL prebuilt, and this check cannot tell the two libcs apart. A musl
+  machine on `arm`/`riscv64` will still get an unnecessary warning naming a remedy that won't
+  help — a false positive, the direction this control is meant to err in, not a silent miss.
+- **`bootstrap --rotate` could no longer recover once the local key record it needs was itself
+  the thing missing.** `--rotate` revoked a prior key only by a `keyId` read from this machine's
+  own local record — so when that record was lost (the exact situation `--rotate` exists to
+  recover from), nothing was revoked, the subsequent mint hit the same already-exists response,
+  and the CLI re-threw the identical error telling the caller to run `--rotate` — which they just
+  had. `--rotate` now falls back to resolving the key to revoke server-side (listing this
+  principal's active keys in the context and matching by name) when no local record exists. The
+  error message for the case that still can't be resolved now points at `vectros key list` /
+  `vectros key revoke` instead of repeating the same `--rotate` advice a second time.
+- **Any verb (not just credential minting) could abort the whole process with a native Windows
+  crash instead of the CLI's own exit code.** Every verb ended with `process.exit(await
+  runVerb(...))`; on Windows, a `fetch` still settling when `process.exit()` runs races libuv and
+  aborts the process, printing an `Assertion failed` line and replacing the real exit code with
+  `127` — which reads to a script, CI job, or wrapping agent as "command not found" rather than as
+  the CLI's own, already-printed, correctly-diagnosed failure (a bad `--context`, a suspended
+  member, an expired/invalid bearer, and so on). Every verb now sets `process.exitCode` and lets
+  the event loop drain naturally instead of hard-exiting, the same idiom `role`/`access` already
+  used for their own top-level exit.
+
+  **A related hazard was introduced by this conversion itself, and closed in the same pass —
+  not a pre-existing bug.** A shared helper, `parseTenantFlag()`, validates `--tenant` for 24 call
+  sites (`role`, `access`, `scripts`, `issuers`, `key`, `identity list-all`) and used to call
+  `process.exit(2)` directly: an unconditional stop from any call-stack depth, so no released
+  version could ever fall through past it. Converting the helper to the same `process.exitCode`
+  idiom broke that guarantee, because `exitCode` only unwinds the helper's own stack frame — a
+  caller that didn't check it after calling the helper would silently continue into the real
+  command with an invalid `--tenant` (defaulting to the **live** tenant, since `undefined` is also
+  this helper's valid "no `--tenant` given" result). All 24 call sites were audited and given an
+  explicit check immediately after the call, so no release ever shipped the fall-through — but it
+  is why this entry calls it out as a hazard of the refactor, not a latent defect the refactor
+  happened to discover.
+
+- **Eight source comments named internal backend classes/methods, or an internal gotcha filename,
+  by name** (`src/commands/issuers.ts`, `src/loader.ts` x3, `src/scope-gate.ts`, `src/scope-grammar.ts`,
+  `src/keyring.ts`, `src/os-keychain.ts`). This package has no GitHub source mirror, but `dist/`'s
+  sourcemaps embed the original source comments verbatim, so all eight shipped in every npm
+  tarball. Reworded to describe the mechanism without the identifier; no behavioral change.
+
+- **Six more shipped sources named a sibling package by monorepo-relative path or an internal
+  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 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.
+
+- **`scripts delete`'s pre-delete warning no longer claims the platform doesn't check whether a
+  live trigger rule still references the version being deleted.** The platform now refuses that
+  delete (409, naming the offending rule) instead of silently allowing it; the warning described
+  the older, unguarded behavior. No behavior changed — the delete itself already surfaced whatever
+  the platform returned either way; only the pre-emptive warning text was stale.
+
+### Docs
+
+- **`vectros issuers register`/`update`'s flag tables now document three refusal conditions
+  those commands can hit.** `--jwks-uri`/`--userinfo-uri` must be `https://` (an `http://` value
+  is refused with 400); a tenant is capped at 50 registered issuers; and a `--self-signup-policy`
+  naming a role that authors, updates, or deletes scripts is refused. No behavior changed — the
+  CLI already surfaced whatever the platform returned; the tables just didn't mention these yet.
+
 ## 0.21.0 — 2026-09-07
 
 ### Added
@@ -326,7 +635,7 @@ This project adheres to [Semantic Versioning](https://semver.org).
   install path) used to print only on `--no-merge` / a declined / a failed
   merge — a successful auto-merge silently hid it; it's now shown there too.
 - Scrubbed internal issue/MR references, review-process citations, and
-  backend class names out of `packages/cli`'s comments — visible in the
+  backend class names out of this package's comments — visible in the
   published npm package's sourcemaps to anyone who reads mapped source.
   Comment-only; no behavior change.
 - **Keyring secret-store hardening.** A 0-byte salt file removed by