@vectros-ai/cli 0.20.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
@@ -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,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,204 @@
 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

package/README.md

@@ -13,6 +13,8 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`vectros namespace`** — register a new scope namespace, and list/get existing ones.
 - **`vectros identity`** — manage tenant-wide principals (users, orgs, clients, and namespaces you register).
 - **`vectros role`** — define reusable, context-scoped access rules.
+- **`vectros scripts`** — push, list, inspect, and delete the versioned script source a trigger
+  fires, or your own app executes directly.
 - **`vectros assume`** — switch identity namespace values on your own token, per a role's `assumable` grant.
 - **`vectros access`** — bind principals to contexts, and inspect what a binding grants.
 - **`vectros key`** — issue, list, revoke, and rotate scoped API keys (`ssk_*`).
@@ -162,7 +164,8 @@ requires hand-authoring a blueprint and re-running a full apply.
 vectros issuers register --context my-app --issuer-id auth0-prod \
   --issuer https://your-tenant.us.auth0.com/ \
   --jwks-uri https://your-tenant.us.auth0.com/.well-known/jwks.json \
-  --audience https://api.your-app.example.com
+  --audience https://api.your-app.example.com \
+  --captured-claim name --captured-claim phone_number
 vectros issuers list --context my-app
 vectros issuers get primary --context my-app
 vectros issuers update primary --context my-app --status suspended
@@ -171,11 +174,11 @@ vectros issuers delete primary --context my-app   # re-types the id to confirm
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. |
-| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--tenant test\|live` | Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. |
+| `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--captured-claim <name>` (repeatable), `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. `--captured-claim` names additional OIDC claims to capture beyond the email claim on every successful token exchange, stored as your tenant's golden identity-provider-asserted copy for that user; omit it to capture nothing beyond email. At most 20 names of at most 64 characters, no duplicates. |
+| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. |
 | `delete <issuerId>` | `--context <contextId>` (required), `--force`, `--tenant test\|live` | Re-types the issuer id to confirm (mirrors `context destroy`); `--force` skips the prompt and is required when stdin isn't a TTY. Refused server-side while any user was ever created or matched through this issuer. |
 | `list` | `--context <contextId>` (required), `--tenant test\|live` | Every issuer registered in that context. `--context` has no default — an issuer read is confined to the context you name; there's no tenant-wide "every issuer in every context" view. |
-| `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies. |
+| `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies and captured claims. |
 
 All five accept `--json`, plus the common auth flags (`--base-url`, `--token`).
 
@@ -252,6 +255,8 @@ vectros role create --context my-app --role-id own-org --name "Own org" \
   --actions records:r --data-scope '{"scope:org":["<orgId>", null]}'
 vectros role create --context my-app --role-id hr-admin --name "HR Admin" \
   --actions records:cru --assumable '{"scope:org":["org_engineering", "org_sales"]}'
+vectros role create --context my-app --role-id delegator --name Delegator \
+  --actions profiles:c --assignable-role editor --assignable-role own-org
 vectros role list --context my-app
 vectros role get --context my-app --role-id editor
 vectros role delete --context my-app --role-id editor
@@ -259,13 +264,65 @@ vectros role delete --context my-app --role-id editor
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--assumable <json>`, `--description <text>` | Idempotent by `roleId`. `--data-scope` confines the clause to owned data — a JSON map of ownership dimension → allowed values, ANDed across keys (e.g. `{"userId":["${{ self.userId }}"]}`, or `{"scope:org":["<orgId>", null]}` — the `null` entry additionally admits scope-less/tenant-shared records). Keys must be `userId` or `scope:<namespace>` (the legacy flat `orgId`/`clientId` keys are rejected server-side). `--assumable` is a SEPARATE, role-level grant — a JSON map of `scope:<namespace>` → allowed values naming which values a holder of this role may switch into via `vectros assume`; holding broad `--data-scope` reach in a namespace does not by itself grant assuming any value in it. |
-| `list` | `--context <c>` (required) | |
-| `get` | `--context <c>`, `--role-id <id>` (both required) | Also shows the role's `assumable` grant, if any is set. |
-| `delete` | `--context <c>`, `--role-id <id>` (both required) | No cascade — any access profile still referencing the role fails to mint (not silently downgraded) until reassigned. |
+| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--assumable <json>`, `--assignable-role <roleId>` (repeatable), `--description <text>`, `--tenant test\|live` | Idempotent by `roleId`. `--assignable-role` restricts WHICH named roles this clause may compose into a delegated AccessProfile — orthogonal to `--data-scope`, which bounds data reach rather than role composition. Omit it for no restriction; the platform rejects an empty list, so there is no way to spell "compose nothing". Once a clause carries the restriction it can compose only the roles it names, so name every roleId it still needs before adding the flag. `access explain` reports the restriction for clauses that carry one. `--data-scope` confines the clause to owned data — a JSON map of ownership dimension → allowed values, ANDed across keys (e.g. `{"userId":["${{ self.userId }}"]}`, or `{"scope:org":["<orgId>", null]}` — the `null` entry additionally admits scope-less/tenant-shared records). Keys must be `userId` or `scope:<namespace>` (the legacy flat `orgId`/`clientId` keys are rejected server-side). `--assumable` is a SEPARATE, role-level grant — a JSON map of `scope:<namespace>` → allowed values naming which values a holder of this role may switch into via `vectros assume`; holding broad `--data-scope` reach in a namespace does not by itself grant assuming any value in it. |
+| `list` | `--context <c>` (required); `--tenant test\|live` | Add `--tenant test` to read a context that lives in the test tenant — a blueprint applied there is otherwise unreadable. |
+| `get` | `--context <c>`, `--role-id <id>` (both required); `--tenant test\|live` | Also shows the role's `assumable` grant, if any is set. |
+| `delete` | `--context <c>`, `--role-id <id>` (both required); `--tenant test\|live` | No cascade — any access profile still referencing the role fails to mint (not silently downgraded) until reassigned. |
 
 `create`/`list`/`get` accept `--json`; `delete` does not.
 
+## `vectros scripts` — the script source a trigger fires, or your app runs directly
+
+A stored script has two consumers, and this is how the source gets there for both. A **trigger rule**
+names it in `scriptRef` and runs it under the trigger's own grant; that `scriptRef` is validated when
+the rule is DECLARED rather than when it fires, so a script has to exist before any rule can name it.
+**Your own app** runs a stored version directly through `POST /v1/scripts/execute`, under its own
+credential, committing everything the script wrote as a single transaction.
+
+Direct execution is separately granted: the calling role needs `scripts:x`, and without it the call
+is a `403` that cannot say the missing grant is the reason. The platform accepts it bare (every
+script in the context) or qualified to one name (`scripts:x:create-case`). A **blueprint** may use
+only the qualified form — its scope gate refuses a bare `scripts:x` and there is no wildcard — so a
+blueprint that ships a script grants exactly the one it ships. See *The scope gate* below, and
+[`AUTHORING.md`](./AUTHORING.md) for where that grant goes in a blueprint.
+
+```bash
+vectros scripts push notify-assignee --context my-app --source-file ./notify.js
+vectros scripts push notify-assignee --context my-app --source-file ./notify.js --if-changed
+vectros scripts list --context my-app                        # every script, newest first
+vectros scripts list --context my-app --name notify-assignee # every version of one name
+vectros scripts get 3b1c9f2e7a5d… --context my-app           # one version, with its source
+vectros scripts delete 3b1c9f2e7a5d… --context my-app        # ONE version (prompts)
+vectros scripts delete 3b1c9f2e7a5d… --context my-app --force  # ...or skip the prompt, e.g. in CI
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `push` | `--context <c>`, `--source-file <path>` (both required); `--input-contract <text>` or `--input-contract-file <path>`, `--if-changed`, `--tenant <test\|live>` | **Always stores a new version by default** — pushing is not idempotent, and each push gets the next server-assigned version number, which the output reports. `--if-changed` reads the current version first and pushes only on a genuine difference; use it where the same push re-runs, e.g. in CI. `--source-file` is capped at 300,000 UTF-8 bytes and the input contract at 50,000, both checked locally so an oversized push fails immediately instead of sending the body. The input contract is descriptive only — nothing validates a firing against it. Nothing parses the source either, so a syntax error surfaces the first time the version runs. |
+| `list` | `--context <c>` (required); `--name <name>`, `--tenant <test\|live>` | With `--name`, every version of that name, oldest first; without, every script in the context, newest first. The human view shows a byte count instead of the source — a listing would otherwise print the full text of every version. `--json` includes the source. |
+| `get` | `--context <c>` (required) + the version id; `--tenant <test\|live>` | Shows one version, including its full source. Version ids are opaque — a deterministic hex string, not a prefixed or random id — so copy them from `scripts list`. |
+| `delete` | `--context <c>` (required) + the version id; `--force`, `--tenant <test\|live>` | Deletes ONE version; other versions of the same name are untouched. **Irreversible — the stored source is the only copy** — so it asks you to type the version id back before proceeding. `--force` skips that, and is REQUIRED in a non-interactive shell rather than the prompt being silently waived there. `--json` emits `{id, deleted}` on stdout; the warning always goes to stderr, so it stays visible without breaking a pipe. ⚠️ Deleting a name's LATEST version reuses its identity — the next push of that name recomputes the same version number and the same id, so a pinned reference silently resolves to different source. |
+
+There is no `scripts update` — a stored version is immutable, and the platform's update route always
+rejects. Supersede a version by pushing a new one.
+
+`--context` is required on all four. Scripts are context-scoped and a trigger resolves its
+`scriptRef` inside its own context, so a defaulted context would push where nobody asked and leave
+the rule that wanted it still unresolvable. `--tenant` defaults to `live`; pass `--tenant test` to
+reach the versions a `blueprint-test --tenant test` run created.
+
+⚠️ **`delete` is not reference-checked.** Nothing verifies whether a trigger rule still points at the
+version being removed, and the two outcomes differ: a rule pinned to that version fails on every
+subsequent firing, while a rule on `version: latest` silently resolves to the PREVIOUS version and
+carries on running older code with nothing to indicate it. This CLI has no verb that lists trigger
+rules, so it cannot answer that question for you — check against the API before removing a version a
+rule may still use.
+
+A blueprint can ship a script instead of pushing one — see `scripts:` in
+[`@vectros-ai/blueprints`](https://www.npmjs.com/package/@vectros-ai/blueprints). An apply is
+convergent (an unchanged source pushes nothing) and never deletes: removing a `scripts:` entry
+leaves every version in place, which is why this command group exists to remove one deliberately.
+
 ## `vectros assume` — switch identity namespace values on your own token
 
 Re-mints your own verb token with one or more `identity.<namespace>` values
@@ -283,7 +340,7 @@ vectros assume --context my-app --scope org:org_sales
 |---|---|
 | `--context <c>` (required), `--scope <ns:value>` (repeatable, at least one required) | Each `--scope` becomes one `scope:<namespace>` entry in the request. No artificial cap on how many namespaces you name — the platform requires a SINGLE role to jointly grant the whole combination and rejects an unsatisfiable one itself. |
 
-Prints the re-minted `access_token`/`expires_in` (accepts `--json`) — there
+Prints the re-minted `access_token`/`expires_in`, plus the resolved `identity` and `allowedActions` the platform returns alongside it — what you actually assumed, without decoding the token (accepts `--json`) — there
 is no `--to-keyring` here, since the result 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 the keyring is built to hold.
@@ -313,11 +370,11 @@ shares this grammar.
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `grant` | `--principal <p>`, `--context <c>` (required); exactly one of `--role <roleId>` (repeatable — 2+ compose additively) / `--actions <csv>`; `--scope <ns:value>` (repeatable), `--identity-overrides <json>` | Idempotent **upsert** — re-granting an existing binding updates it to the newly-declared shape (role(s)/actions/overrides), it does not no-op. Repeating `--role` composes: `--role case-handler --role hr-admin` grants each role's own clauses, concatenated in the order given — never merged, so each clause keeps meaning exactly what its own author wrote. `--scope`/`--identity-overrides` extend the principal's stamped identity (e.g. `--scope org:<id>` → `scope:org`) — a credential can only stamp ownership its identity carries, so granting write access to org-scoped data requires that scope on the profile. When both are given, `--identity-overrides` wins on key conflicts. |
-| `revoke` | `--principal <p>`, `--context <c>` (required) | |
-| `list` | Exactly one of `--context <c>` / `--principal <p>` | `--context` lists the context's members; `--principal` lists every context that principal is bound to. |
-| `get` | `--principal <p>`, `--context <c>` (required) | |
-| `explain` | `--principal <p>`, `--context <c>` (required) | Resolves the binding's clauses (following every referenced role and concatenating their clauses, if bound via one or more) and renders a concrete **access matrix** — a canned set of record-ownership archetypes (yours alone, another user's, org-shared, scope-less, …) evaluated against the clauses. A client-side preview for authoring-time sanity, not the platform's own evaluator: it models READ reachability only — a `c`/`u`/`d` action shown as granted is advisory, not a guarantee a specific write will succeed, since the platform's write rule (a clause must explicitly name a dimension to place a value into it) diverges from its read rule (an unmentioned dimension never narrows reads). |
+| `grant` | `--principal <p>`, `--context <c>` (required); exactly one of `--role <roleId>` (repeatable — 2+ compose additively) / `--actions <csv>`; `--scope <ns:value>` (repeatable), `--identity-overrides <json>`, `--tenant test\|live` | Idempotent **upsert** — re-granting an existing binding updates it to the newly-declared shape (role(s)/actions/overrides), it does not no-op. Repeating `--role` composes: `--role case-handler --role hr-admin` grants each role's own clauses, concatenated in the order given — never merged, so each clause keeps meaning exactly what its own author wrote. `--scope`/`--identity-overrides` extend the principal's stamped identity (e.g. `--scope org:<id>` → `scope:org`) — a credential can only stamp ownership its identity carries, so granting write access to org-scoped data requires that scope on the profile. When both are given, `--identity-overrides` wins on key conflicts. |
+| `revoke` | `--principal <p>`, `--context <c>` (required); `--tenant test\|live` | |
+| `list` | Exactly one of `--context <c>` / `--principal <p>`; `--tenant test\|live` | `--context` lists the context's members; `--principal` lists every context that principal is bound to. |
+| `get` | `--principal <p>`, `--context <c>` (required); `--tenant test\|live` | |
+| `explain` | `--principal <p>`, `--context <c>` (required); `--tenant test\|live` | Resolves the binding's clauses (following every referenced role and concatenating their clauses, if bound via one or more) and renders a concrete **access matrix** — a canned set of record-ownership archetypes (yours alone, another user's, org-shared, scope-less, …) evaluated against the clauses. A client-side preview for authoring-time sanity, not the platform's own evaluator: it models READ reachability only — a `c`/`u`/`d` action shown as granted is advisory, not a guarantee a specific write will succeed, since the platform's write rule (a clause must explicitly name a dimension to place a value into it) diverges from its read rule (an unmentioned dimension never narrows reads). |
 
 `grant`/`list`/`get`/`explain` accept `--json`; `revoke` does not.
 
@@ -473,11 +530,11 @@ CLI runs under an elevated ephemeral bridge token. So the trust boundary is
 **this binary, not the blueprint**: a hardcoded **scope gate** bounds every
 mint to a data-plane allowlist (`records` / `schemas` / `search` / `documents`
 / `folders` / `inference` / `entities`). Most control-plane scope (keys /
-app-contexts / users / billing / admin / namespaces) or a `*` wildcard
-**hard-rejects** — the CLI mints nothing and exits non-zero. There is
+app-contexts / users / billing / admin / namespaces / triggers) or a
+`*` wildcard **hard-rejects** — the CLI mints nothing and exits non-zero. There is
 intentionally **no override flag**.
 
-**One narrow, deliberate exception:** `profiles` (which configures who has
+**Two narrow, deliberate exceptions. The first:** `profiles` (which configures who has
 access to what — control-plane by nature) admits its `r`/`u`/`d` operations,
 because the platform enforces an unconditional check that a write to an
 AccessProfile can never grant more scope than the requesting credential
@@ -495,6 +552,16 @@ requires. A literal-qualified `profiles:c:usr_<id>` naming another principal
 still hard-rejects regardless of `member-lifecycle`, same as every other
 control-plane scope.
 
+**The second exception:** `scripts:x:<script-name>` — execute one named script — is admitted, so a
+blueprint that ships a script in its `scripts:` block can also grant permission to run it. Execution
+consults no data scope at all, and every write the script makes is still checked one by one against
+the caller's own permissions, so this widens *what can be composed*, never *what data is reachable*.
+Everything else on the resource still hard-rejects: a bare `scripts:x`, because it would mean "run
+every script in this context, including ones added later that your reviewer never saw"; `scripts:x:*`,
+because there is **no wildcard form** — the qualifier is compared to the script name exactly, so such
+a grant would store cleanly and then refuse every execution; and `scripts:c`, authoring, which stays
+a design-time admin surface. `triggers` is unchanged.
+
 ### Capabilities (`granted_capabilities`) — a separate, equally-gated dimension
 
 A blueprint's `accessProfile` and role clauses may also declare