@vectros-ai/cli 0.20.0 → 0.22.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
@@ -298,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
@@ -449,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:
@@ -457,11 +545,35 @@ 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: [...]` —
@@ -505,6 +617,57 @@ 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 `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` 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
 
 - **Bundled** — reviewed, versioned blueprints shipped in the library

package/CHANGELOG.md

@@ -3,6 +3,390 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 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 "the Tier-2 panel caught three times" wording) — 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
+
+- **`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
@@ -128,7 +512,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