@vectros-ai/cli 0.19.0 → 0.21.0

package/AUTHORING.md

@@ -54,7 +54,11 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
    `namespaces` and the `*` wildcard are **hard-rejected, no override**.
    `profiles` is a narrower exception — `r`/`u`/`d` are admitted, and `c` only
    when qualified `profiles:c:self` (create a profile for yourself; a bare
-   `profiles:c`, or one naming another principal, still hard-rejects). Any
+   `profiles:c`, or one naming another principal, still hard-rejects).
+   `scripts` is the other — `scripts:x:<script-name>` (execute one named
+   script) is admitted, and nothing else on that resource is: a bare
+   `scripts:x`, a wildcard `scripts:x:*`, and `scripts:c` (authoring) all
+   hard-reject. Any
    requested `capabilities` are checked the same way, against their own,
    separate allowlist — see "Capabilities" below. A forked or hand-written
    blueprint gets the *identical* gates a bundled one does — it can never
@@ -69,6 +73,16 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
    `dataScope: {}` when a shared/tenant-wide resource is what you intend
    (warnings — they print but don't fail).
 
+   A schema may also declare `expectedScopeDims` — the ownership dimensions
+   its records are typically scoped by, e.g. `expectedScopeDims: [org,
+   client]`. Purely advisory (never sent to the platform, never runtime-
+   enforced): it lets the lint warn when a role/`accessProfile` clause grants
+   `r`/`u`/`d` on that typeName (via a type-qualified action like
+   `records:r:case`) but its `dataScope` names only SOME of the declared
+   dims — reads never require full-dimension coverage the way creates do, so
+   a clause naming one of two declared dims silently leaves the other
+   unconstrained. Omit the field entirely and this lint never fires.
+
 `validate` accepts a file path **or** a bundled blueprint name.
 
 ### 3. `plan` — preview before you mint
@@ -196,8 +210,9 @@ accessProfile:
   # capabilities: [member-lifecycle]
   # A SEPARATE gated dimension from allowedActions — named platform effects a
   # resource:ops verb can't express (e.g. creating/removing an identity in
-  # your tenant). Only 'member-lifecycle' is admitted today; every other name
-  # is hard-rejected, same posture as the scope gate. See "Capabilities" below.
+  # your tenant). 'member-lifecycle' and 'delegate-principal-stamp' are
+  # admitted today; every other name is hard-rejected, same posture as the
+  # scope gate. See "Capabilities" below.
   #
   # Instead of allowedActions (+ optional dataScope/capabilities), accessProfile
   # may declare `roleIds: [<roleId>, ...]` — one or more roles declared below,
@@ -287,7 +302,7 @@ namespaces:
     # Registered in the SAME bootstrap-token phase as issuers, before schemas.
     # Owned by this blueprint's own contextId (above) by default. `tenantWide: true` opts
     # out of that, but declaring it is not enough on its own: the applying credential must
-    # separately hold OWNER-only authority, and `bootstrap`/`apply` refuse to even request
+    # separately hold OWNER-only authority, and `vectros bootstrap` refuses to even request
     # it without the explicit `--allow-tenant-wide-namespaces` flag — a blueprint cannot make
     # this happen by itself. Registration is create-once, NOT idempotent server-side: a
     # re-apply matching every declared field converges silently, but one that disagrees
@@ -438,6 +453,90 @@ so if you seed a referencing record, seed its target first. To query "which X
 reference Y", add the reference field to `lookupFields` as an equality lookup
 (there is no reverse-reference index on this surface).
 
+### Scripts and triggers — code a record write runs
+
+A blueprint can ship the code an event runs, and the rule that runs it. Two
+top-level blocks, applied in-context and in this order (`scripts` first —
+a rule's `scriptRef` is checked when the rule is *declared*, not when it fires,
+so a rule naming a script with no versions is refused outright):
+
+```yaml
+schemas:
+  - typeName: intake
+    displayName: Intake
+    # A schema fires triggers only when it opts in. Default is false.
+    capabilities: { triggersEnabled: true }
+    fields:
+      - { fieldId: status, fieldType: string, inline: true }   # `inline` = projectable
+
+scripts:
+  notify-assignee:
+    source: |
+      export default function (input) {
+        return { notified: input.recordId };
+      }
+
+triggers:
+  on-intake-update:
+    firingSource: { schemaName: intake, event: UPDATE }
+    # A script this blueprint ships is always `latest` — a pin is rejected at authoring time.
+    scriptRef: { name: notify-assignee, version: latest }
+    fields: [status]
+    allowedActions: [records:r:intake, records:u:intake]
+    dataScope: { "scope:org": ["${{ input.scope.org }}"] }
+    manifest: [records.get, records.update]
+```
+
+Four things to get right, because each is a refusal rather than a warning:
+
+- **`fields` is required.** It names the record fields projected into the
+  script's `input.record` (and, on an `UPDATE`, `input.previous`). `fields: []`
+  is the explicit "project nothing" declaration — required rather than defaulted
+  so that projecting nothing is something you state. An entry may name only a
+  field the schema keeps **inline** (`inline: true`, `filterable: true`, or a
+  lookup field) and never one marked `sensitive`. `validate` checks this against
+  the schema in the same blueprint, so you see it before an apply starts.
+- **A rule that declares any `fields` must be able to read what it fires on** —
+  its grant needs a `records:r` clause covering the firing schema's type, and
+  that clause may not carry a *literal* `dataScope` constraint. A
+  `${{ input.* }}` placeholder is fine, because it resolves to the firing
+  record's own value.
+- **The schema must opt in** with `capabilities.triggersEnabled: true`, or the
+  rule is refused at `plan` time rather than created and silently never fired.
+- **The grant is live authority.** A trigger's `allowedActions`/`dataScope`, or
+  the roles its `roleIds` composes, are what the script actually executes under
+  — author them as narrowly as any other credential's. `${{ self.* }}`,
+  `${{ under.self.* }}` and `${{ member.* }}` are rejected inside a trigger's
+  grant: they resolve against the trigger principal's identity, not yours.
+
+**Shipping a script does not make it runnable.** A `scripts:` entry provisions
+the source; the two consumers reach it differently. A **trigger** names it in
+`scriptRef` and runs it under the trigger's own grant — nothing further needed.
+**Your app calling `POST /v1/scripts/execute` needs an explicit grant**, and the
+role that calls it must carry `scripts:x:<script-name>`, qualified to that one
+name:
+
+```yaml
+roles:
+  case-handler:
+    - allowedActions: [scripts:x:create-case]
+      dataScope:
+        scope:org: ['${{ member.scope.org }}']
+```
+
+Omit it and the call is a 403 that cannot tell you the grant is what's missing.
+See *The scope gate* for why the bare and wildcard forms are refused.
+
+**Triggers are the one block an apply reconciles by absence.** Remove an entry
+and re-apply, and its rule and access profile are deleted, so a trigger you
+removed cannot keep acting. Its service principal is kept, so re-adding the same
+trigger reattaches to one identity. Removing a `scripts:` entry deletes nothing
+— see *The idempotency contract*, below, for why.
+
+Full field grammar, including the byte caps on `source` and
+`declaredInputContract` and the `manifest` verb vocabulary:
+[`@vectros-ai/blueprints`](https://www.npmjs.com/package/@vectros-ai/blueprints).
+
 ### The scope gate — what you can and can't request
 
 The gate allows only **data-plane** resources:
@@ -446,20 +545,44 @@ The gate allows only **data-plane** resources:
 registered — ownership-gated the same way as `records`; it grants no
 authority over the namespace *registry* itself, which stays root-key-only).
 Operations are `c|r|u|d`, combinable (`records:cru`), with a per-resource
-wildcard (`records:*`). Anything else — control-plane resources or the bare
+wildcard (`records:*`). Anything else — control-plane resources and the bare
 `*` — is rejected, and there is **intentionally no override flag**. This is
 *why* it's safe to apply a blueprint you didn't write: the binary is the trust
 boundary, not the file.
 
+**One exception on `scripts`, because a blueprint that ships a script has to be
+able to grant permission to run it.** `scripts:x:<script-name>` is admitted.
+Everything else on that resource is not:
+
+| Grant | Verdict |
+|---|---|
+| `scripts:x:create-case` | **admitted** — execute that one script |
+| `scripts:x` (bare) | rejected — it would mean "run every script in this context, including ones added later that your reviewer never saw" |
+| `scripts:x:*` | rejected — **there is no wildcard form.** The qualifier is compared to the script name exactly, so a `*` matches nothing: the grant would store cleanly and then refuse every execution, with no error able to say why |
+| `scripts:c` (authoring) | rejected — creating a script is a design-time admin surface, and a blueprint ships its source rather than granting the ability to write one |
+| `triggers:*` | rejected — unchanged |
+
+Execution consults no data scope, so this widens **what can be composed**, never
+**what data is reachable**: every write the script makes is still checked, one
+by one, against the caller's own permissions. A credential holding only
+`scripts:x:<name>` runs the script and is refused on its first write.
+
+If your blueprint declares a `scripts:` block, `validate` also checks each
+`scripts:x:<name>` grant against the names you actually ship, and refuses a
+grant that names something else. That check exists here because it cannot exist
+anywhere else: the platform stores a misspelled grant without complaint, and
+the resulting 403 at execution time deliberately cannot tell you the name was
+wrong.
+
 ### Capabilities (`granted_capabilities`) — a separate, equally-gated dimension
 
 An `accessProfile` or role clause may also declare `capabilities: [...]` —
 named platform effects (like creating or removing an identity in your tenant)
 that a `resource:ops` scope token can't express. This rides its own field,
-separate from `allowedActions`, and has its own allowlist: **only
-`member-lifecycle` is admitted today.** Every other capability name —
-including ones the platform's own registry recognizes — is refused, the same
-fail-closed, deliberately-narrow posture as the scope gate above. `validate`,
+separate from `allowedActions`, and has its own allowlist: **`member-lifecycle`
+and `delegate-principal-stamp` are admitted today.** Every other capability
+name — including ones the platform's own registry recognizes — is refused,
+the same fail-closed, deliberately-narrow posture as the scope gate above. `validate`,
 `plan`, `blueprint-test` and `bootstrap` all report a rejected capability the
 same way they report a rejected scope: nothing mints, and the CLI exits
 non-zero.
@@ -494,6 +617,24 @@ from a blueprint's `externalId` colliding with an unrelated identity, so it asks
 rather than guessing either way. `--rotate` is exempt only when the local
 record already names the same principal being rotated.
 
+**A second qualification, and a different KIND of one: a `scripts:` entry is not
+idempotent server-side.** Every push of a script name stores a genuinely new,
+immutable version — there is no update, and no create-or-return. Convergence
+here is the loader's doing, not the platform's: it reads the name's current
+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
+with `vectros scripts delete`.
+
 ## Distribution
 
 - **Bundled** — reviewed, versioned blueprints shipped in the library

package/CHANGELOG.md

@@ -3,6 +3,345 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.21.0 — 2026-09-07
+
+### Added
+
+- **`vectros bootstrap --blueprint` provisions a blueprint's `scripts` block**, before the triggers
+  that reference them. A trigger's `scriptRef` is checked when the rule is DECLARED, not when it
+  fires, so the ordering is what makes a blueprint shipping both work at all — the other way round,
+  the trigger is refused for naming a script that does not exist yet, after the apply has already
+  minted that trigger's service principal and access profile.
+
+  **A re-apply pushes nothing when the source has not changed.** Pushing a script is not
+  idempotent — every push stores a new, server-numbered version — so an apply reads the name's
+  current version first and stores a new one only when `source` or `declaredInputContract` actually
+  differs. Without that, every apply of an unedited blueprint would mint a version and silently
+  re-point every `version: latest` rule at code identical to what it was already running. Editing
+  the source pushes exactly one new version, which `latest` rules then pick up. A concurrent push
+  from another apply is re-read rather than blindly retried, so two runners applying the same
+  blueprint converge instead of storing the same source twice.
+
+  **Removing a `scripts` entry does NOT delete the script** — the deliberate asymmetry with
+  triggers, which an apply does reconcile by absence. A script carries no record of which blueprint
+  pushed it, so an apply cannot tell one it created from one pushed by hand; the delete would be
+  unrecoverable, since the stored source is the only copy, and would break any trigger still
+  referencing it. An unreferenced script version is inert — it fires nothing and grants nothing — so
+  it is left in place. `blueprint plan` states this every time, including when the blueprint declares
+  no scripts at all, which is exactly the plan you see after removing the last one.
+
+- **`vectros scripts <push|list|get|delete>`** — manage script objects outside a full apply, which
+  previously had no route at all short of raw HTTP.
+
+  - `scripts push <name> --source-file <path> --context <ctx>` stores a new version and reports its
+    number. It always pushes, matching the platform: `--if-changed` opts into the convergent
+    behaviour instead, which is what a CI job re-running the same push wants. Name grammar and both
+    byte caps are checked locally, so a bad push exits 2 naming the field instead of sending 300 KB
+    to earn a rejection. `--input-contract` / `--input-contract-file` supply the optional contract.
+  - `scripts list --context <ctx> [--name <name>]` — every version of one name, or all scripts. The
+    human view shows a byte count rather than the source, so listing a much-edited script does not
+    dump hundreds of kilobytes into a terminal; `--json` carries the source for a machine consumer.
+  - `scripts get <id> --context <ctx>` shows one version including its full source.
+  - `scripts delete <id> --context <ctx>` removes ONE version, leaving other versions of the name
+    alone — and warns that nothing checked whether a trigger still referenced it. That warning is
+    the point: a rule pinned to the deleted version fails on every firing, while a rule on `latest`
+    silently falls back to the previous version and keeps running older code.
+
+  There is no `scripts update`: a stored version is immutable and the update route always rejects.
+  `--context` is required on all four, since a trigger resolves its `scriptRef` inside its own
+  context and a defaulted one would push where nobody asked.
+
+- **`blueprint-test` tears down the script versions a run pushed**, by id, after the trigger teardown
+  so a rule never briefly outlives the script it names. A version the run did not push — the source
+  already matched what the blueprint declares — is reported as skipped and left alone.
+
+- **`blueprint-test` tears down trigger rules it created.** The harness deletes what a run
+  provisions, and triggers were the one resource it could not reach — so testing a blueprint with a
+  `triggers:` block left the rule behind, and because a schema will not delete while a rule fires
+  off it, the leak kept the schema alive and the next run failed against it. Deletion is
+  created-only and requires TWO independent factors, mirroring what `bootstrap` already does when it
+  reconciles a trigger away: the rule must be absent from the pre-run snapshot AND carry this
+  blueprint's own `provisionedBy` marker. A rule that pre-existed, one another blueprint provisioned,
+  one created directly through the API, or any rule at all when the snapshot could not be read, is
+  reported and left in place. Each rule's access profile goes with it — that is where its declared
+  authority lives — while its service principal is kept, so re-adding the same trigger reattaches to
+  one identity.
+
+- **Blueprint trigger `fields` and schema field `inline` are provisioned.** A trigger rule declares
+  which record fields it projects into its script's `input.record` (and, on an `UPDATE` firing,
+  `input.previous`); `vectros bootstrap --blueprint` forwards that declaration, and forwards a
+  schema field's `inline` flag, which is what makes a field projectable at all. `blueprint plan`
+  now names the projected fields per trigger — this is the record data that leaves storage on every
+  firing, so an operator approving a plan should see it — and spells out a trigger that projects
+  nothing rather than omitting the line. Requires `@vectros-ai/blueprints` ≥ 0.18.0.
+
+- **`assume` shows the identity you actually got.** `POST /v1/auth/token/assume` now returns a
+  `resolvedScope` alongside the re-minted token — the same plaintext data baked into the token's own
+  compressed `scope` claim, resolved server-side — so the human view reports the resolved `identity`
+  and `allowedActions` instead of leaving you to decode the token. Switching `identity` is the whole
+  point of assuming, so this is the direct answer to the question the command was run to ask. The
+  rows are omitted entirely against a backend that returns no `resolvedScope`, rather than rendered
+  as empty: on this command an em dash would read as "you assumed nothing". `--json` already carried
+  the field verbatim.
+
+- **`role create --assignable-role <roleId>`** (repeatable) — restrict which named roles the new
+  role's clause may compose into a delegated AccessProfile. Omit for no restriction; the platform
+  rejects an empty list, so the flag has no "compose nothing" spelling and omitting it leaves the
+  clause byte-identical to one authored before this release. Validated locally against the platform's
+  roleId grammar, 20-entry cap and no-duplicates rule, so a bad list exits 2 naming the offending
+  entry instead of round-tripping to a `400`.
+
+- **`access explain` reports a clause's `assignableRoles`**, in both the human and `--json` views,
+  for clauses that carry one. Reported alongside the access matrix rather than folded into it: the
+  restriction bounds role composition, not data reach, so narrowing the matrix on it would be wrong.
+  A blueprint can declare the same restriction via `assignableRoles` on a role or `accessProfile`
+  clause (`@vectros-ai/blueprints` ≥ 0.18.0), which `vectros bootstrap --blueprint` forwards.
+
+- **`issuers register` / `issuers update` accept `--captured-claim <name>`** (repeatable) — additional
+  OIDC claim names, beyond the email claim, to capture from that issuer's tokens on every successful
+  token exchange and store as your tenant's golden identity-provider-asserted copy for the signed-in
+  user. `issuers update` also gains `--clear-captured-claims`, which sends an explicit empty list
+  (capture nothing beyond email) — distinct from omitting the flag, which leaves the stored value
+  unchanged. Mutually exclusive with `--captured-claim`. The list is bounds-checked locally (20
+  entries, 64 characters each, no duplicates), so a bad list exits 2 naming the offending entry
+  rather than round-tripping to a `400`. `issuers get` renders the captured names, and `issuers
+  list` gains a `captured claims` column.
+  A blueprint can declare the same thing via `issuers[].capturedClaims` (`@vectros-ai/blueprints`
+  ≥ 0.18.0), which `vectros bootstrap --blueprint` now forwards and reconciles when re-applied.
+
+- **Blueprint `identityProjectionClaims` is applied.** A blueprint declaring the new top-level block
+  (`@vectros-ai/blueprints` ≥ 0.18.0) has it set on the app context during the bootstrap phase,
+  alongside the context create — that is the only phase whose credential carries the platform
+  provisioning capability the field requires. Declaring it selects which captured identity-provider
+  claim names are projected, read-only, onto access profiles in that context. A blueprint that does
+  not declare it sends nothing, leaving any existing declaration untouched. **It applies only when this
+  blueprint CREATES the context**: the platform sets the declaration on a true create, so a context
+  created separately beforehand never receives it, and re-applying against an existing context does
+  not change it in either direction — edit an existing context's
+  declaration through the platform API.
+
+- **Blueprint `triggers:` provisioning.** `vectros bootstrap --blueprint` now provisions each declared trigger:
+  a dedicated service principal, a context-scoped AccessProfile carrying the trigger's declared
+  grant, and the trigger rule itself. A trigger's real declared grant is attached only after the
+  trigger rule is confirmed created — a failed apply never leaves a principal holding meaningful
+  authority with nothing referencing it. `blueprint plan` renders each trigger's firing schema/
+  event, script reference, and manifest (or `(none)` when absent) alongside the principal/profile
+  steps it provisions. Requires `@vectros-ai/blueprints` ≥ 0.18.0. A schema's
+  `capabilities.triggersEnabled` is now applied along with `auditHistory` — it is the opt-in a schema
+  must declare before a trigger may fire on its records, and a blueprint declaring a trigger against
+  a schema without it is refused at `plan` time rather than creating a rule that never fires.
+- **Removing a trigger from a blueprint now de-provisions it.** Triggers are the one resource
+  `vectros bootstrap --blueprint` reconciles by *absence* as well as presence: a trigger this blueprint previously
+  provisioned and no longer declares has its rule and its access profile deleted, so a trigger you
+  removed cannot keep acting under a grant that outlived it. Its service principal is kept, so
+  re-adding the same trigger later reattaches to the same identity. Triggers created outside this
+  blueprint — by hand, or by a different blueprint sharing the app context — are never touched.
+  Ownership is established from **two** independent pieces of evidence, both of which must agree: the
+  trigger rule's own `provisionedBy` marker (which `vectros bootstrap --blueprint` stamps, and which the platform refuses to
+  re-point once set) and the service principal the rule names. Neither alone is sufficient, because
+  each is writable with a different scope; requiring both means no single credential can make one
+  blueprint's apply delete another principal's grant. A trigger whose two factors disagree, or whose
+  principal cannot be read, is left in place and reported rather than deleted. Each de-provisioned
+  trigger is named individually in the apply output, and `blueprint plan` states the behaviour in
+  its legend. No other resource is ever deleted by an apply.
+
+### Changed
+
+- **A refusal caused by suspension is reported as one.** `POST
+  /v1/admin/keys/scoped` now answers with a `409` when the access profile or the user it names is
+  suspended, and the CLI renders that distinctly: no credential — root included — mints against a
+  suspended profile, so the remedy the `403` text points at (re-issue a broader credential) is
+  actively wrong here. Reactivate the profile, then retry. The developer scoped-token route answers
+  every refusal with one uniform `404`, and a suspended member is one of them; since every
+  credential-bearing verb mints through that route, the CLI names suspension among the causes rather
+  than reporting only that the context was not found.
+
+- **The scope gate names `scripts` and `triggers` as control-plane.** Both were already refused for
+  a blueprint-issued role — they are not data-plane resources — and the refusal now says so, rather
+  than reading as an unrecognized resource that the allowlist might be widened for. Script authoring
+  and trigger declaration are deliberately admin-shaped surfaces. No scope that passed the gate
+  before is refused.
+
+- **Two blueprints may not declare a trigger of the same name in one app context.** The second apply
+  is rejected with a `400`. A trigger fires real code under a real grant, so one blueprint quietly
+  re-pointing another's rule is not something an apply does. Rename one of the triggers, or move it
+  to its own app context.
+
+### Fixed
+
+- **`role` and `access` accept `--tenant`, so a blueprint applied to the test tenant can be verified.**
+  Every sibling verb (`context`, `issuers`, `scripts`, `key`, `identity`) already took the flag; these
+  two did not, and they are the ones that read back roles and access bindings. Omitting it fell back
+  to the live tenant and failed with *"Context not found"* — a message naming two possible causes,
+  neither of which was the real one. A blueprint apply's most security-relevant output was the one
+  part that could not be read back from the tenant it was written to.
+- **A failed token mint no longer aborts the process.** `role` and `access` now set the exit code and
+  return rather than exiting mid-flight, which on Windows could trip a native assertion in Node's HTTP
+  stack and replace the command's real exit code with `127` — the code a shell uses for "command not
+  found". Anything branching on exit status read a refused request as a missing binary. If you script
+  against another verb and see `127` from a request that clearly reached the server, that is this bug
+  and not a missing binary; re-run and read the printed error, which is accurate.
+
+- **A blueprint can now grant `scripts:x:<script-name>`, so a blueprint that ships a script can also
+  grant permission to run it.** The scope gate classified `scripts` as control-plane by resource, so
+  the grant was refused outright and a blueprint could ship a script's source with no way to
+  authorize its execution. That reasoning is correct for `scripts:c` — authoring is a design-time,
+  admin-shaped surface, and it is unchanged — but it does not carry to execution, which consults no
+  data scope at all and whose writes are still checked one by one against the caller's own
+  permissions. The grant widens what can be composed, never what data is reachable.
+
+  Qualified to a script name only. A bare `scripts:x` is still rejected: execution gates on the verb
+  and the name, so an unqualified grant would mean "may run every script in this context, including
+  ones added later". `scripts:*` and `scripts:x:*` are rejected too — **there is no wildcard form.**
+  The qualifier is compared to the script name exactly, so a `*` matches nothing: such a grant would
+  store cleanly and then refuse every execution, with no error able to explain why.
+- **`blueprint validate`/`plan` now catch a misspelled script grant.** If your blueprint declares a
+  `scripts:` block, each `scripts:x:<name>` grant is checked against the names you actually ship, and
+  the refusal names the role and lists what is shipped. Nothing downstream can catch this: the
+  platform stores a wrong name without complaint and the execution-time 403 deliberately cannot say
+  the name is the problem.
+
+## 0.20.0 — 2026-08-27
+
+### Added
+
+- **The capability gate now admits `delegate-principal-stamp`**, alongside the
+  existing `member-lifecycle`. Grantable on an `accessProfile` or role clause's
+  `capabilities: [...]`, same as before — a blueprint can now let an admin
+  role create a membership-shaped record on behalf of a known third-party
+  user, once the clause authorizing the write also explicitly names `userId`
+  in its own `dataScope` (the capability itself may be granted on a
+  different clause of the same role, e.g. via a separately-composed
+  `roleIds` entry — only the write's own verb + `userId` admission must be
+  co-located). Bounded by the SAME app context and record type the clause's
+  `dataScope` already confines the write to — unlike `delegate-mint`/
+  `forensic-read`/`context-directory-read`, this is not tenant-wide, and
+  (like `member-lifecycle`) it is self-signup-eligible.
+- **`vectros identity list-all`** — lists every user in the tenant, for the one
+  recovery case `identity list` can't reach: a user created but never granted
+  access anywhere (the gap between creating a principal and binding it to a
+  context). `identity list` is scoped to the caller's own context by design —
+  a user with no access grant at all is invisible there no matter how many
+  times a create is retried, since a retry with the same `--external-id` just
+  collides with the same invisible row. `list-all` authenticates with your own
+  login session (an account owner) instead of a context-scoped credential, so
+  it can see every user regardless of context. Supports `--external-id`,
+  `--tenant`, `--limit`, and `--json`, matching `identity list`'s conventions.
+- **`vectros blueprint validate`/`plan`: new advisory lint —
+  `partial-datascope-dimension-coverage`** (needs `@vectros-ai/blueprints` ≥
+  0.17.0). Warns when a role/`accessProfile` clause grants `r`/`u`/`d` on a
+  typeName (e.g. `records:r:case`) whose schema declares
+  `expectedScopeDims`, but the clause's `dataScope` names only SOME of those
+  dims — the missing dimension(s) are silently unconstrained for that grant,
+  since reads (unlike creates) never require full-dimension `dataScope`
+  coverage. Opt-in: a schema with no `expectedScopeDims` declared never
+  trips it, and it never fires on an untyped (bare `records:r`) grant.
+  Never runtime-enforced — pure authoring-time visibility into a choice
+  that's easy to make by omission rather than intent.
+- **`bootstrap`/`blueprint-test` now catch a FRESH (first-apply) seed index
+  failure, not just a re-apply's.** A seed create's response always carries
+  `PENDING_INDEX` on a first apply (indexing runs async, after the
+  response), so the existing `seedIndexFailures` summary previously only
+  ever saw a terminal `FAILED` on a later idempotent re-apply — a
+  newly-bootstrapped demo whose seeds failed to index looked silently empty
+  in search/RAG until the operator happened to re-run bootstrap. Every seed
+  still `PENDING_INDEX` after seeding is now re-checked with a bounded,
+  concurrent, best-effort poll (default: 3 attempts, 500ms apart, ≤ ~1.5s
+  added to the happy path) and folded into the same run-summary warning if
+  it settles to `FAILED` within the bound. Deliberately NOT a guarantee — a
+  seed still `PENDING_INDEX` when the bound is exhausted stays silent, so a
+  genuinely slow index (reconcile/quarantine can stall for minutes) never
+  turns a one-shot provisioning command into an unbounded wait.
+- **`vectros issuers` gains `register`/`update`/`delete`** — previously
+  read-only (`list`/`get`). Closes the gap where adding a second IdP, or
+  editing one issuer's `selfSignupPolicies` after initial setup, required
+  hand-authoring a blueprint `issuers:` block and re-running a full apply.
+  `register` is idempotent by issuer id (a repeat returns the existing
+  registration unchanged, not an error); `update` only ever sends the safe,
+  mutable fields (`subClaim`/`emailClaim`/`userinfoUri`/`status`/
+  `selfSignupPolicies`) — trust-anchor fields stay immutable via this route,
+  matching the platform; `delete` uses the same re-type-the-id confirmation
+  as `context destroy` (`--force` for non-interactive use), and is refused
+  server-side while any user is bound through the issuer. All three accept
+  `--tenant test|live` (like their `list`/`get` siblings) so a context
+  living in the `test` tenant is reachable, not just `live`.
+- **New `vectros namespace` command group: `register`/`list`/`get`.**
+  Registering a brand-new scope namespace (e.g. a `practice`/`team` entity
+  dimension) was blueprint-apply-only before this; there was also no way to
+  discover which namespaces already exist without already knowing their
+  names. `register --entity-backed` is what makes a namespace a real
+  identity-entity dimension that `identity create --type <name>` can create
+  entities in. No `update`/`delete` verbs — both are gated to a genuine root
+  API key on the platform side with no provisioning-capability door, so
+  neither could ever succeed for any credential the CLI holds (documented in
+  the command's own module header).
+- **`role create` gains `--assumable <json>`** — a role-level `vectros
+  assume` entitlement grant (JSON map of `scope:<namespace>` → allowed
+  values), previously blueprint-`roleAssumable:`-only. Independent of
+  `--data-scope`: holding broad data-scope reach in a namespace does not by
+  itself grant assuming any value in it.
+- **New `vectros assume --context <c> --scope <ns:value>...`** — re-mints
+  the caller's own verb token with one or more `identity.<namespace>` values
+  switched (`POST /v1/auth/token/assume`), for a caller whose role
+  explicitly grants assuming those values. The CLI's first standalone
+  command reaching this endpoint; entitlement is checked live against the
+  caller's current roles, never a copy frozen into a token at mint time. No
+  `--to-keyring` — the response is an ephemeral bearer token with the same
+  remaining lifetime as the verb token this command itself mints to make the
+  call, not a durable secret.
+
+### Changed
+
+- **`runLoader`'s `provisioned` is now REQUIRED — the self-provisioning
+  fallback is gone.** Internal hardening only, no CLI-facing behavior
+  change: every real caller (`vectros bootstrap`, `blueprint-test`) already
+  always ran `provisionContext` first and passed the result in, so the
+  fallback branch was dead in production. Removing it makes the
+  `provisionContext` → (apply-time identity resolution) → `runLoader`
+  ordering structurally required instead of convention-enforced — a future
+  caller can no longer reproduce the ordering bug the original fix
+  closed by skipping the split. `allowTenantWideNamespaces` and
+  `confirmExistingPrincipal` moved with it: both now live only on
+  `provisionContext`'s own input, where their actual checks have run since
+  that original fix — `runLoader`'s own copies of both parameters were already dead
+  plumbing before this change.
+- **Apply-time identity resolution now REQUIRES `provisionContext`'s result.**
+  Internal hardening only, no CLI-facing behavior change. Closes the other
+  half of the ordering gap above: `runLoader` already required
+  `provisionContext`'s output, but the step between them — resolving a
+  blueprint's declared `identities:` — took a bare client with nothing tying
+  it to `provisionContext` having run first, so a caller could still
+  reproduce the original ordering bug (a non-`user` identity in a namespace
+  the same blueprint also registers racing that registration) with no
+  compiler signal. It now derives which client to use internally instead of
+  each caller doing so independently.
+
+### Fixed
+
+- **`bootstrap`'s post-merge hint is now blueprint-specific, and `--client
+  code` always shows the `claude mcp add` command.** The restart hint used to
+  read "list my tasks" / "add a task to …" for EVERY blueprint (a leftover
+  from when only `task-management` existed) — it now names the actual
+  blueprint applied. The `claude mcp add` line (the idiomatic Claude Code
+  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
+  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
+  something else mid-poll (a concurrent cleanup, a manual delete of the
+  crash remnant) used to throw a raw `ENOENT` out of `setSecret`; it now
+  restarts salt creation instead, since nothing was ever encrypted under an
+  empty salt in the first place. Also fixed an order-dependent assumption
+  in two `keyring prune` tests (they now pin the processing order they
+  depend on, so a future ordering change fails with a diagnosable message
+  instead of a confusing downstream one).
+
+### Changed
+
+- Bundled `@vectros-ai/sdk` refreshed to the current release's staging build.
+
 ## 0.19.0 — 2026-08-27
 
 ### Added