@vectros-ai/cli 0.25.0 → 0.27.0

package/AUTHORING.md

@@ -8,7 +8,7 @@ ready-to-use data model + a narrow `ssk_*` scoped key — no root key, no manual
 admin steps. `vectros blueprint apply <file> --tenant test|live` applies the same
 blueprint WITHOUT minting a key, for re-applying a change from CI.
 
-This guide is the authoring loop. Everything here except `bootstrap` and `blueprint apply` is
+This guide is the authoring loop. Everything here except `blueprint-test`, `bootstrap` and `blueprint apply` is
 **creds-free and offline** — you can iterate on a blueprint with no account.
 
 > The examples use the bare `vectros` binary — install it once with
@@ -22,7 +22,7 @@ vectros blueprint init my-thing        # 1. scaffold a starter
 # …edit ./my-thing.blueprint.yaml…
 vectros blueprint validate ./my-thing.blueprint.yaml   # 2. structural + scope-gate + lint (offline)
 vectros blueprint plan     ./my-thing.blueprint.yaml   # 3. preview what it provisions (offline)
-vectros blueprint-test     ./my-thing.blueprint.yaml --env staging  # 4. prove it live (creds; auto-teardown)
+vectros blueprint-test     ./my-thing.blueprint.yaml --tenant test  # 4. prove it live (creds; auto-teardown)
 vectros bootstrap --blueprint ./my-thing.blueprint.yaml # 5. apply for real + mint a key (needs a bridge token)
 vectros blueprint apply ./my-thing.blueprint.yaml --tenant test  # 5'. apply for real, no key (CI: add --yes --confirm-existing-principal)
 ```
@@ -50,7 +50,7 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 `validate` runs three layers and exits non-zero on any failure:
 
 1. **Structural** — the file parses against the blueprint schema (readable
-   `path: message` errors, e.g. `schemas[0].fields[1]: Required`).
+   `path: message` errors, e.g. `schemas[0].fields[1].fieldType: Invalid input: expected string, received undefined`).
 2. **Scope + capability gates** — the requested `allowedActions` are data-plane
    only. This is the trust boundary: `keys`/`users`/`admin`/`app-contexts`/
    `namespaces` and the `*` wildcard are **hard-rejected, no override**.
@@ -97,12 +97,14 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 
 ```
   Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
-    + schema 'thing' (1 field, HYBRID) lookup: [title]
-    + context 'mcp' (MCP — my-thing)
+  ...
     + principal 'my-thing-sp' (SERVICE)
+    + context 'mcp' (MCP — my-thing)
+    + schema 'thing' (1 field, HYBRID) lookup: [title]
     + profile scopes [records:r, records:c, records:u, search:r, schemas:r] (data-plane ✓)
     + key my-thing-<machine> (mint 1 scoped ssk_*)
-    + seed 1 record(s)
+    + seed 1 record
+  6 step(s). This is a preview — nothing was minted.
 ```
 
 **A blueprint whose `accessProfile` composes roles (`roleIds:`) previews every
@@ -111,9 +113,10 @@ sharing an action set can still carry different `dataScope`:
 
 ```
   Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
-    + schema 'thing' (1 field, HYBRID) lookup: [title]
-    + context 'mcp' (MCP — my-thing)
+  ...
     + principal 'my-thing-sp' (SERVICE)
+    + context 'mcp' (MCP — my-thing)
+    + schema 'thing' (1 field, HYBRID) lookup: [title]
     + role 'case-handler' (1 clause, actions [records:cru])
       clause 1: actions [records:cru], dataScope: scope:org=[${{ self.scope.org }}]
     + role 'hr-admin' (1 clause, actions [records:r])
@@ -121,7 +124,8 @@ sharing an action set can still carry different `dataScope`:
       assumable: scope:org=[org_engineering, org_sales]
     + profile via role(s) [case-handler, hr-admin] (composed — each role's own clauses, concatenated in order)
     + key my-thing-<machine> (mint 1 scoped ssk_*)
-    + seed 1 record(s)
+    + seed 1 record
+  8 step(s). This is a preview — nothing was minted.
 ```
 
 A role's `assumable` line only appears when the blueprint's top-level
@@ -164,16 +168,17 @@ everything it created:
 
 ```
 vectros login                                            # sign in once (or pass --token)
-vectros blueprint-test ./my-thing.blueprint.yaml --env staging
+vectros blueprint-test ./my-thing.blueprint.yaml --tenant test
 vectros blueprint-test task-management --keep            # leave the graph in place to inspect it
 ```
 
 Teardown is the default and runs even if an assertion fails. It is **created-only** — a pre-apply
 snapshot means it never deletes a schema or AccessProfile that already existed, so it's safe to point at
-a shared staging tenant. (It does **not** delete the app-context: that's idempotent and reused.) Exit
-`0` = applied + every assertion passed; `1` = an assertion failed or apply errored; `2` = no credential,
-or the blueprint asked for control-plane scope (the same gate `validate` enforces). Run this before you
-ship a blueprint — it catches an unusable or mis-scoped credential that the offline checks can't.
+a tenant other people use. (It does **not** delete the app-context: that's idempotent and reused.) Exit
+`0` = applied + every assertion passed; `1` = an assertion failed, apply errored, or an agent the run created could not be retired or purged; `130`/`143` = stopped by SIGINT (^C) / SIGTERM; `2` = no credential,
+or the blueprint asked for control-plane scope (the same gate `validate` enforces), or an agent name is too long
+to take the run's suffix. Run this before you ship a blueprint — it catches an unusable or mis-scoped credential
+that the offline checks can't. A blueprint that declares `agents:` runs under agent names of its own: see *Agents*.
 
 ## The format, field by field
 
@@ -226,7 +231,7 @@ accessProfile:
   # A SEPARATE gated dimension from allowedActions — named platform effects a
   # resource:ops verb can't express (e.g. creating/removing an identity in
   # your tenant). 'member-lifecycle' and 'delegate-principal-stamp' are
-  # admitted today; every other name is hard-rejected, same posture as the
+  # admitted; every other name is hard-rejected, same posture as the
   # scope gate. See "Capabilities" below.
   #
   # Instead of allowedActions (+ optional dataScope/capabilities), accessProfile
@@ -367,6 +372,16 @@ identities:
 YAML or JSON are both accepted (chosen by extension). The bundled library is
 authored in TypeScript; YAML is the authoring affordance for your own.
 
+### Inputs — values you supply when you install
+
+A blueprint can declare a top-level `inputs:` block (each input has a `type` of `string`, `number` or `boolean`, and may
+have `required`, `default` and `description`) and use the values in any string with `${{ inputs.<name> }}`. The built-ins
+`${{ vectros.context }}` and `${{ vectros.suffix }}` are the blueprint's literal `contextId` and a short stable token derived
+from it. Supply values to `validate`, `plan` and `apply` with `--set name=value` (repeatable) or `--values <file>` (a YAML or
+JSON map); `--set` wins over `--values`, which wins over the declared `default`. An unknown input, a missing value with no
+default, or a value of the wrong type stops the command before any request is sent. Write `$${{` for a literal `${{`. The
+`@vectros-ai/blueprints` README describes the block in full.
+
 ### Choosing lookup indexes — a permanent decision
 
 `lookupFields` are how you reach records *directly* — by exact value, by an
@@ -424,7 +439,6 @@ each tell you "records with this status" or "records with this area", but never
 
 ```yaml
 lookupFields:
-  - externalId
   - { fieldNames: [status, area], sortBy: createdAt, allowOverflow: true }
 ```
 
@@ -562,10 +576,82 @@ 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).
 
+### Agents — stored model definitions
+
+A blueprint can declare the agents it needs. The block needs `formatVersion: 2`, so a CLI that predates the
+format refuses the file instead of misreading it.
+
+```yaml
+formatVersion: 2
+agents:
+  intake-triage:             # the key is the agent's name: 1-64 letters, digits, '_' and '-'
+    description: Summarises a new intake record and flags missing fields.
+    model: claude-sonnet-5-5
+    system: You triage intake records. Be concise.
+    tools:
+      - { name: records_get }
+      - { name: records_create, allowWrites: true }   # a tool that changes data needs allowWrites ...
+    limits: { maxToolCalls: 10, maxWrites: 2 }         # ... and limits.maxWrites of at least 1
+    budget: { maxInferenceCents: 100 }
+```
+
+`apply` and `bootstrap` create each agent in the blueprint's context, after the roles, scripts and triggers and
+before any key is minted, and `plan` lists one step per agent. The write is convergent, and the platform does the
+comparing: a new name is created at version 1, an identical definition writes nothing, and a changed definition
+becomes the next version. Nothing is edited in place, so every earlier version stays readable. The apply summary
+names what it did to each agent (`created at version 1`, `unchanged at version 2`, `version 2 -> 3`, or `adopted`).
+
+- **The applying credential needs `agents:c`**, and `agents:u` and `agents:r` as well whenever the agent already exists, even
+  when its definition is unchanged (the platform checks `u` before it compares, and without `r` it cannot show the existing agent
+  and answers that the name is in use). A re-apply with only `agents:c` is refused, and the error says which scopes are missing.
+  A principal without them gets a `403`, and the apply stops with an error that names the scope and the context.
+  Agents are written before the key, so a refused apply mints none. This is a grant on the credential that applies
+  the blueprint, not something to put in the blueprint's `accessProfile`: `agents` is a control-plane resource, so
+  the scope gate refuses it there.
+- **Each agent is marked as this blueprint's.** Another blueprint's agent of the same name is refused, not rewritten, so two
+  blueprints cannot declare one name, and renaming a blueprint that already created agents strands them: the new name is
+  refused for them. The mark is set once and cannot change. It is the blueprint's own `name`, which the file declares
+  for itself (the same trust as for scripts and triggers): any file that declares `name: X` rewrites the agents marked
+  `X`, so the adoption flag below guards unmarked agents only.
+- **An agent made by hand under the same name is refused unless you pass `--allow-agent-adoption`** (to `apply` or `bootstrap`; a
+  flag only the operator can give, never something the blueprint declares). Adopting marks it as this blueprint's and writes the
+  declared definition as its next version if that differs, so every run that uses the agent's latest version changes; earlier
+  versions stay readable. Nothing is written to a refused agent. Once adopted it is an ordinary managed agent and later applies
+  need no flag. This is how you bring agents you created by hand under a blueprint. It is checked per agent as the agents are
+  written, partway through the apply, so what an earlier agent or section already wrote stays.
+- **Hand edits to a managed agent do not last.** A version written with `vectros agents version` (or the API) on an agent a
+  blueprint declares is replaced by the declared definition at the next apply, as another version. Change the blueprint.
+- **A retired agent that the blueprint still declares fails the apply** (`409`), after the sections before it are written. Restore it
+  with `vectros agents version <id> --restore --file <definition>`, or remove the entry; a purged agent cannot be restored.
+- **Removing an entry deletes nothing.** The agent stays stored and runnable. Retire it deliberately through the
+  API (`DELETE /v1/agents/{id}`); a retired agent keeps its name, so the same name cannot be created again.
+- **`blueprint-test` runs a blueprint that declares agents, under names of their own.** A retired or purged agent keeps
+  its name for good, so the test applies a copy of your blueprint whose agent names carry a suffix unique to the run
+  (`triage` becomes `triage-t1a2b3c4d`; the report lists each), then retires and purges exactly the agents it created,
+  even when an assertion failed. Agents that exist under your declared names are never touched, and the file you wrote is
+  not changed. Because the suffix takes 10 characters, a name can be at most 54 characters long here (exit `2`, before any
+  write). The credential needs `agents:d` as well as the scopes an apply needs; if a retire is refused the agent stays active, the report names the API call that retires it, and the run exits
+  `1` (a teardown failure on any other resource is still reported without changing the exit code). **^C, SIGINT and SIGTERM.** Once the apply has begun, only the agent step has a stop point (a signal during context provisioning or the snapshot ends the run before the apply starts). After the first signal the run writes no further agents and skips
+  the assertions if they have not begun, but the rest of the apply still runs to its end (schemas, roles, the profile, the scoped-key mint,
+  seed records, the index poll), so a request in progress or a long seed delays the stop. Then the same teardown as after a failed run
+  removes what the apply's result lists (never the context, the service principal or namespaces), the report is printed, and the exit
+  code is `130` (SIGINT) or `143` (SIGTERM); a run stopped this way never passes, and these codes win over `1` (the report still names
+  an agent that could not be removed). A step that never answers holds the run until you send the signal again. That second signal starts no
+  teardown: it prints the id of each agent this run created with the calls that retire and erase it, names a create that was sent and never
+  answered, notes that other things the run wrote are not listed, and leaves at once. With `--keep` nothing is torn down. A process manager that
+  follows SIGTERM with SIGKILL after a grace period ends the process wherever it is, and SIGKILL cannot be handled: what was written so far
+  stays. A create of a tracked agent is sent with no client retries, so a single 429 or 5xx fails that create (the run reports it and tears
+  down) instead of being retried; a create that may have gone through is searched for by name. Each run leaves one purged row per declared agent (the name stays reserved), which
+  `agents list --include-retired` shows. With `--keep` the agents stay, under their run names.
+- `authority` is `CALLER` (the default and the only value the platform accepts): a run calls tools with the identity
+  and permissions of whoever starts it, further limited by the tool whitelist.
+
+The same API is available directly as `vectros agents list|get|create|version`; see the README.
+
 ### The scope gate — what you can and can't request
 
 The gate allows only **data-plane** resources:
-`records`, `schemas`, `search`, `documents`, `folders`, `inference`, `entities`
+`records`, `schemas`, `search`, `documents`, `folders`, `inference`, `entities`, `runs`
 (per-namespace identity-entity CRUD — `org`/`client`/any namespace you
 registered — ownership-gated the same way as `records`; it grants no
 authority over the namespace *registry* itself, which stays root-key-only).
@@ -605,7 +691,7 @@ An `accessProfile` or role clause may also declare `capabilities: [...]` —
 named platform effects (like creating or removing an identity in your tenant)
 that a `resource:ops` scope token can't express. This rides its own field,
 separate from `allowedActions`, and has its own allowlist: **`member-lifecycle`
-and `delegate-principal-stamp` are admitted today.** Every other capability
+and `delegate-principal-stamp` are admitted.** Every other capability
 name — including ones the platform's own registry recognizes — is refused,
 the same fail-closed, deliberately-narrow posture as the scope gate above. `validate`,
 `plan`, `blueprint-test` and `bootstrap` all report a rejected capability the
@@ -693,6 +779,11 @@ 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`.
 
+**A FOURTH qualification, and here the platform does the comparing: an `agents:` entry is idempotent server-side,
+and a change adds a version.** For an agent that exists, the loader first makes a plain create call to see the agent's mark and
+version, then an upsert, which compares the declared definition with the stored latest (after defaults are filled in) and writes
+nothing when they are identical. The two versions give the exact outcome. See *Agents*, including `--allow-agent-adoption`.
+
 ## Distribution
 
 - **Bundled** — reviewed, versioned blueprints shipped in the library

package/CHANGELOG.md

@@ -3,6 +3,84 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.27.0 — 2026-11-07
+
+### Added
+
+- **`vectros blueprint apply` and `bootstrap` create the agents of a blueprint's `agents` section** (it needs `formatVersion: 2`), after the
+  roles, scripts and triggers and before any key is minted. `blueprint plan` lists one step per agent (model, tools, limits, budget,
+  prompt size). A new name is created at version 1, an unchanged definition writes nothing, a changed one becomes a new version; the
+  summary says which (`created at version 1`, `unchanged at version 2`, `version 2 -> 3`).
+- **Agents are marked as the blueprint's own.** Another blueprint's agent of the same name is refused, and an agent made by hand is
+  refused unless you pass `--allow-agent-adoption` (adopting it writes the declared definition as a new version, which changes every
+  run that uses the latest version). Removing an entry from the blueprint deletes nothing.
+- **Scopes:** the applying credential needs `agents:c`, and `agents:u` and `agents:r` as well when the agent already exists, even if
+  its definition is unchanged. On a `403` the apply stops, names the agent, scope and context, and mints no key.
+- **`vectros agents list|get|create|version`.** `--context` is required and `--tenant test|live` is accepted. `create` takes a name
+  (1 to 64 letters, digits, `_` or `-`) and a JSON or YAML definition file. `version` takes the agent's id and a file, writes a new
+  version as a full replacement, and takes `--expected-version` (refuse the write if someone else got there first) and `--restore`
+  (bring a retired agent back). `list` takes `--include-retired`; `get` takes the id and `--at-version`. There is no `delete` verb:
+  retire an agent through the API.
+- **A blueprint can grant `runs:c` and `runs:r`.** A trigger cannot be granted `runs`, directly or through a role.
+- **`blueprint validate` and `plan` warn about a schema field named `externalId`, `partnerUserId`, `scopes` or `userId`** (the platform
+  reserves them; exit `0`); a lookup field with one of those names is an error (exit `2`).
+- **A blueprint's names, labels and descriptions with more invisible characters are refused.**
+
+### Changed
+
+- **`vectros --version` reports SDK 0.49.0.**
+- **`apply` and `bootstrap` ask before reusing a trigger's service principal that this blueprint did not mark:** a prompt, or
+  `--confirm-existing-principal` in a pipeline (exit `3` without it, before anything is written). Principals from earlier releases
+  carry no mark, so the first re-apply of a blueprint with triggers needs the confirmation once per trigger; marking needs `users:u`.
+- **`vectros blueprint-test` runs a blueprint with agents.** Agent names get a per-run suffix (a declared name over 54 characters exits
+  `2`), the test retires and purges only the agents it created, and the credential needs `agents:d`. `^C` or SIGTERM during the run
+  tears down what the apply listed and exits `130` or `143`. Each run leaves one purged row per agent, and `--keep` leaves the agents.
+- **Text from blueprint files, agent definitions and the platform reaches the terminal without control, invisible or bidirectional
+  characters,** cut at 200 lines or 20,000 characters (`[truncated]`). YAML parser warnings are no longer printed.
+- **Blueprint validation runs on zod 4.** An integer beyond JavaScript's safe-integer range and `Infinity` are refused, a string length
+  counts characters, and a wrong-typed value stops the checks that depend on it. zod's own messages are reworded (a missing field reads
+  `Invalid input: expected string, received undefined`): match on the field path, not on the text.
+
+## 0.26.0 — 2026-10-25
+
+### Added
+
+- **`vectros whoami --tenant test|live`** shows the session for that tenant (default `live`). The output gains a `tenant type`
+  line and `--json` gains `tenantType`. The test tenant shows your own user id there, which needs platform 0.47.0 or later and
+  shows `—` on an earlier platform. Any other value stops with a usage error (exit 2).
+- **`vectros access list --principal` prints a note on standard error naming the context it searched.** The command searches
+  the `default` context, and depending on the caller the platform may not look beyond it, so an empty result means none in
+  `default`; the note gives the `vectros access get --principal … --context <c>` command to check another. Standard output
+  and `--json` are unchanged. A `2>&1 | jq` pipeline fails on the note; redirect standard error instead.
+
+### Fixed
+
+- **A blueprint file whose trigger `dataScope` uses `${{ input.userId }}` or `${{ input.scope.<namespace> }}` loads in
+  `validate`, `plan`, `apply` and `bootstrap`.** The platform resolves these placeholders against the record that fires the
+  trigger.
+
+### Changed
+
+- **`vectros --version` reports SDK 0.48.0.**
+- **`vectros blueprint apply` stops with the platform's message when another request changes the same item at the same
+  moment.** When apply updates a schema, role or trigger rule, the platform answers `409` (`VERSION_CONFLICT`) instead of
+  overwriting the other change. Run apply again once the other change has finished.
+- **`vectros provider-config create` and `update` stop with the platform's `503` when it cannot store the provider key.**
+  Nothing is saved; run the command again shortly.
+- **The bundled `@vectros-ai/blueprints` is 0.20.3, and the package description covers the whole command set.**
+- **The comments in the shipped code describe the code as it is today.** Behaviour is unchanged, except for the text of the
+  error for a missing Cognito client id.
+
+### Documentation
+
+- **The README documents `vectros login`, `logout`, `whoami` and `switch`, and `vectros keyring prune --dry-run`.**
+- **The README says `vectros blueprint-test` exits `1` for a blueprint that cannot be read, and that
+  `vectros provider-config create` and `update` stop with the platform's `503` when it cannot store the provider key.**
+- **The authoring guide describes the `inputs:` block of a blueprint: its types, `required` and `default`, `--set` and
+  `--values`, and the `vectros.context` and `vectros.suffix` built-ins.**
+- **The authoring guide shows an abbreviated `plan` output, with the steps in the order they run and the closing step count, and
+  uses `--tenant test` for `blueprint-test`.**
+
 ## 0.25.0 — 2026-10-12
 
 ### Breaking changes

package/README.md

@@ -5,6 +5,8 @@
 
 The Vectros provisioning CLI — the `vectros` binary:
 
+- **`vectros login`** / **`logout`** / **`whoami`** — sign in through your browser (`--no-browser` prints the URL instead, for headless machines), clear the stored session, and show the signed-in session for a tenant (`--tenant test|live`, default `live`; `--json`).
+- **`vectros switch <alias>`** — shortcut for `keyring use`.
 - **`vectros bootstrap`** — provision a least-privilege MCP credential (+ optional blueprint).
 - **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`, creds-free), and
   **`apply`** one into a tenant without minting a key (for CI).
@@ -18,6 +20,7 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`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 agents`** — list, inspect, create, and version stored agents (a model, a system prompt, and a tool whitelist).
 - **`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_*`).
@@ -76,7 +79,8 @@ On a machine with no local record of a prior mint (e.g. an ephemeral CI
 container re-running `--yes` for the first time) against a blueprint whose
 service principal already exists in the tenant, `--yes` alone isn't enough —
 add `--confirm-existing-principal` to make that expected case explicit and
-non-interactive; see AUTHORING.md's "idempotency contract" for why. For a CI re-apply that has no use for the
+non-interactive; see AUTHORING.md's "idempotency contract" for why. The same flag covers a trigger's service principal
+that already exists without this blueprint's mark (see the `apply` section below). For a CI re-apply that has no use for the
 key, `vectros blueprint apply` (below) is the better fit.
 
 **An issuer that needs verification.** A blueprint's `issuers` entry registered without `restrictedToDomain` starts
@@ -140,7 +144,7 @@ vectros blueprint apply ./my-thing.blueprint.yaml --tenant live --yes --confirm-
 
 `apply` runs the same pipeline as `vectros bootstrap` (the same credential, the same scope and capability gates,
 the same loader) with the key step switched off: the context, its service principal and access profile, schemas,
-roles, issuers, triggers and scripts are created or reconciled (and, only if you pass `--seed`, the blueprint's sample
+roles, issuers, triggers, scripts and agents are created or reconciled (and, only if you pass `--seed`, the blueprint's sample
 seed records are written), but **no scoped key is minted,
 nothing is written to a keyring, and no MCP client config is touched**. (Short-lived bootstrap tokens are minted
 to call the platform, as with `bootstrap`; none is a scoped key.) That is what makes it fit for re-applying
@@ -164,11 +168,18 @@ run. Use `bootstrap` when you also want the credential.
   place, as `bootstrap` does.)
 - **An existing service principal needs `--confirm-existing-principal`** (with `--yes`, or with no terminal),
   which is every apply once the principal exists, on any machine: `apply` never reads a local key record, so a
-  machine that ran `bootstrap` is not exempt. It lets `apply` rewrite that principal's access profile, and covers the
-  blueprint's own service principal only (the principals a blueprint's triggers use are ensured without this check,
-  as with `bootstrap`). In a pipeline this flag is standing consent: it also waves through a blueprint whose
-  `servicePrincipal.externalId` collides with an unrelated identity, so keep the blueprint's source reviewed. Every
-  run that proceeds prints which principal it reused (id, external id, created time) and why.
+  machine that ran `bootstrap` is not exempt. It lets `apply` rewrite that principal's access profile. The same flag
+  covers a trigger's service principal that already exists and that this blueprint did not mark. A principal created
+  for a trigger is marked with the blueprint's name (a `provisionedBy` key on the principal), so the confirmation
+  is asked only for one that has no mark (an earlier release made it, or someone made it by hand) or carries another
+  blueprint's: the first confirmation marks it as this blueprint's (an overwrite that needs the `users:u` scope in the
+  blueprint's context and is skipped when the principal's payload reads back masked; if the run does not write it, it says
+  why and the next run asks again), and with no
+  terminal and no flag the run stops before it writes a schema, role, profile, trigger, key or seed record. The mark is advisory, a guard against
+  an accidental name collision or a pre-created principal; it does not stop someone who can create principals and
+  copies the format. In a pipeline this flag is standing consent: it also waves through a blueprint whose
+  `servicePrincipal.externalId` or trigger name collides with an unrelated identity, so keep the blueprint's source
+  reviewed. Every run that proceeds prints which principal it reused (id, external id, created time) and why.
 - **Sample seed records are opt-in: `apply` writes none unless you pass `--seed`,** in either tenant, and never asks.
   This is the opposite of `bootstrap` (which seeds unless `--no-seed`) on purpose: a blueprint's seeds are
   illustrative, not real data, and a re-apply from a pipeline must not write them by omission. When the blueprint
@@ -184,13 +195,13 @@ run. Use `bootstrap` when you also want the credential.
   but `--require-verified-issuers` was given and an issuer is pending verification.
 
 Flags it shares with `bootstrap` (`--set`, `--values`, `--allow-tenant-wide-namespaces`,
-`--allow-script-adoption`, `--require-verified-issuers`, `--token`, `--base-url`) behave the same. `--tenant`,
+`--allow-script-adoption`, `--allow-agent-adoption`, `--require-verified-issuers`, `--token`, `--base-url`) behave the same. `--tenant`,
 `--yes` and `--confirm-existing-principal` are shared but behave as described above (`--tenant` is required here,
 `--yes` is required without a terminal, and the principal flag applies to every re-apply). The flags that concern a
 key or your MCP client (`--rotate`, `--client`, `--no-merge`, `--activate`, `--no-activate`, `--use-scoped-token`,
 `--test`) belong to `bootstrap` and are refused with a pointer; the blueprint is an argument, not `--blueprint`, and
-there is no `--blank`. A script pushed onto an existing hand-authored name (`--allow-script-adoption`) is checked
-when the scripts are pushed, partway through, not up front. `vectros blueprint apply --help` lists everything.
+there is no `--blank`. A script pushed onto an existing hand-authored name (`--allow-script-adoption`) and an agent
+that exists with no blueprint mark (`--allow-agent-adoption`) are checked when they are written, partway through, not up front. `vectros blueprint apply --help` lists everything.
 
 ## `vectros blueprint-test` — verify it actually provisions (creds-required)
 
@@ -210,10 +221,17 @@ vectros blueprint-test ./my-thing.blueprint.yaml --tenant test
 vectros blueprint-test task-management --keep
 ```
 
-Exit `0` = applied and every assertion passed; `1` = an assertion failed or apply
-errored; `2` = no credential, or the scope gate or the capability gate refused the blueprint.
+Exit `0` = applied and every assertion passed; `1` = an assertion failed, apply
+errored, the blueprint could not be read, or an agent the run created could not be retired or purged (the one teardown failure that changes the result); `130` = stopped by SIGINT (^C) and `143` = by SIGTERM, after the rest of the apply finishes (no further agents are written; a key mint and seed records still run) and the teardown it still runs (a second signal leaves at once and names the agents that may still be active); `2` = no credential, or the scope gate or the capability gate refused the blueprint,
+or an agent name is too long to take the run's suffix.
 The app-context is intentionally **not** deleted (it's idempotent and reused).
 
+A blueprint that declares `agents` (see [`vectros agents`](#vectros-agents--stored-versioned-agent-definitions)) runs too. Because a retired or purged agent keeps its name for good, the
+test applies a copy of your blueprint whose agent names carry a suffix unique to the run (`triage` runs as `triage-t1a2b3c4d`; the report
+lists each), then retires and purges exactly the agents it created, even when an assertion failed. Agents that exist under your declared names
+are never touched. A name can be at most 54 characters long here, and the credential needs `agents:d` as well as the scopes an apply needs.
+Each run leaves one purged row per declared agent behind, because a name stays reserved; `vectros agents list --include-retired` shows them.
+
 ## `vectros context` — app contexts
 
 A context is the namespace all data (records, documents, schemas, roles, access
@@ -317,13 +335,14 @@ config up itself is refused by the platform with a `400` for anything but `--bil
 `byo-model-inference:customer-key` waiver type, and a plain `https://` endpoint on port 443 (no credentials,
 query or fragment). On `update`, only a **change** to one of those is refused; a value the config already
 holds is accepted. Changing an endpoint's host needs the key again (`--api-key-secret-file`). The key must
-be printable ASCII, at most 4096 characters. A tenant holds at most 25 provider configs.
+be printable ASCII, at most 4096 characters. A tenant holds at most 25 provider configs. If the platform cannot store the key it answers `503`, nothing is saved, and the command stops with that message; run it again shortly.
 
 The CLI does not sign the risk waiver: an account owner signs it in the developer portal, under **Model
 Providers**, for each environment (live or test). A config is usable only while that waiver is in force for
-your account. It is not in force when it is neither signed nor granted to your account, when it was signed
-against a text that has since changed, or when it has been revoked. A waiver that Vectros granted to your tenant,
-for which your tenant has no signed acceptance, is not affected by any of these. The portal shows which of these
+your account. It is not in force when it is neither signed nor granted to your account, when it has been revoked,
+or when Vectros has required a newer version than the one your owner signed (a waiver Vectros granted to your tenant
+without a signature ends then too). A new published version of the waiver changes nothing by itself: the version your owner signed stays in force
+until Vectros requires a newer one, and account owners are told in advance of the date. The portal shows which of these
 applies. An account that has accepted the Business Associate Agreement with Vectros in the developer portal needs one more thing before a call can
 use a config: an account owner attests that config in the developer portal (Model Providers). Until then the
 platform refuses the call with a `403` that says it needs a BAA-holder attestation. The CLI does not attest
@@ -506,6 +525,42 @@ A blueprint can ship a script instead of pushing one — see `scripts:` in
 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 agents` — stored, versioned agent definitions
+
+A stored agent is a named definition of a model, a system prompt, a tool whitelist, per-run limits and a
+spending cap, kept in an app context. Every change writes a new immutable version and the agent always
+points at its newest one; nothing is edited in place. These verbs and a blueprint's `agents:` section
+write through the same API, so use them for an agent no blueprint manages and to read what an apply stored.
+
+```bash
+vectros agents create intake-triage --context my-app --file ./intake-triage.yaml
+vectros agents list --context my-app                              # each agent at its newest version
+vectros agents list --context my-app --include-retired
+vectros agents get 3b1c9f2e7a5d… --context my-app                 # newest version, with its prompt
+vectros agents get 3b1c9f2e7a5d… --context my-app --at-version 1   # an earlier version
+vectros agents version 3b1c9f2e7a5d… --context my-app --file ./intake-triage.yaml --expected-version 1
+```
+
+The definition file is JSON, or YAML for a `.yaml`/`.yml` file, with the fields of a blueprint's `agents` entry:
+`model` (required), `description`, `authority`, `system`, `tools` (`{ name, allowWrites? }`), `limits` and `budget`.
+A key outside that list is refused before anything is sent, because the platform would drop it and store the agent
+without what you meant it to have.
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create` | the agent name; `--context <c>`, `--file <path>` (both required); `--tenant <test\|live>` | Stores version 1. If the name already exists the stored agent is returned **untouched** and nothing is written; the output says so. A retired or purged name is refused (`409`) because the name stays reserved. |
+| `version` | the agent id; `--context <c>`, `--file <path>` (both required); `--expected-version <n>`, `--restore`, `--tenant <test\|live>` | Writes the next version. A **full replacement**: a field the file leaves out takes its default, nothing is carried over from the version before. `--expected-version` refuses the write (`409`) if the agent has a newer version than the one you read. `--restore` brings a **retired** agent back, with the file as its next version; a purged agent cannot be restored. |
+| `list` | `--context <c>` (required); `--include-retired`, `--tenant <test\|live>` | Each agent at its newest version, newest first. Retired agents are left out unless asked for. |
+| `get` | the agent id; `--context <c>` (required); `--at-version <n>`, `--tenant <test\|live>` | One agent, with its prompt and write-enabled tools marked. Ids are opaque: copy them from `agents list`. |
+
+`--context` is required on all four, because an agent belongs to one app context. `create` needs the
+`agents:c` scope on the credential, `version` needs `agents:u`, and `get` needs `agents:r`; `list` needs `agents:r` too, or `runs:c`, which lists each agent's name, version and status without its definition. A `403` names the scope. (A credential that
+can create but not read gets "the name is already in use" for a name that exists; the output says why.)
+There is no `delete`: retiring an agent keeps its name reserved, so it stays a deliberate call to the API.
+
+A blueprint can declare agents instead; see *Agents* in [`AUTHORING.md`](./AUTHORING.md). To bring agents you created by hand
+under a blueprint, apply it once with `--allow-agent-adoption`.
+
 ## `vectros assume` — switch identity namespace values on your own token
 
 Re-mints your own verb token with one or more `identity.<namespace>` values
@@ -541,12 +596,24 @@ vectros access grant --principal me --context my-app --role editor
 vectros access grant --principal usr_<id> --context my-app --actions records:r,search:r \
   --scope org:<orgId>
 vectros access list --context my-app        # who's in this context
-vectros access list --principal me          # which contexts I'm bound to
+vectros access list --principal me          # which contexts I'm bound to (see the note below)
 vectros access get --principal me --context my-app
 vectros access explain --principal me --context my-app
 vectros access revoke --principal usr_<id> --context my-app
 ```
 
+`access list --principal` searches one context, `default`, because the command's token is pinned to it:
+depending on the caller the platform may not look beyond that context, so a grant you hold in another
+context can be missing from the list, and an empty list means no grant in `default`, not no grants
+anywhere. The command says so on standard error, so `--json` output on standard output stays a bare array,
+and it drops the line when a row from another context shows the lookup did span contexts. To see a grant
+in a specific context, run `vectros access get --principal me --context <context-id>` (add `--tenant test`
+for the test tenant), or `vectros access list --context <context-id>` for everyone in it.
+
+The line is also written with `--json`, and there is no switch to turn it off. A script that merges standard
+error into standard output (`2>&1`) will see one extra line and a `2>&1 | jq` pipeline will fail on it;
+redirect standard error (`2>/dev/null`) to drop it.
+
 `--principal` accepts `usr_<userId>`, `key_<keyId>`, or the alias `me` (your
 own signed-in user, resolved from your login) — every `access` subcommand
 shares this grammar. In the **test tenant** your principal has a different id from your live user, so `me` resolves it per tenant: add `--tenant test` and it still works, e.g. `vectros access grant --principal me --context <context-id> --role <role> --tenant test`. This needs platform 0.47.0 or later; on an earlier platform the command typically stops and points you to `vectros identity list-all --tenant test` (an owner login), which shows the id to pass as `--principal usr_<id>`.
@@ -612,7 +679,7 @@ is optional and stripped if present) — narrower than `access`'s grammar: there
 is no `me` alias on any `key` subcommand, and a key never authenticates as a
 `key_*` principal. Look your own id up first with `vectros identity list
 --type user` (or `vectros whoami`; both show your live tenant, and for the test tenant
-use `vectros identity list-all --tenant test`), or grant/issue via `vectros join`, which
+use `vectros whoami --tenant test` or `vectros identity list-all --tenant test`), or grant/issue via `vectros join`, which
 does resolve `--as me`.
 
 A minted secret has exactly two destinations, and the flags for choosing one
@@ -630,7 +697,7 @@ are shared by `issue` and `rotate`:
 | `issue` | `--principal <p>`, `--context <c>` (required); `--name <n>` (default `default`), `--label <l>`, `--tenant test\|live`, destination flags above | Idempotent on `(tenant, context, principal, name)` — re-issuing an existing tuple returns the key **without** the secret (never re-disclosed); the CLI detects that and points you at `rotate`. |
 | `list` | `--principal <p>`, `--context <c>`, `--tenant test\|live` **or** `--all-contexts` (owner-only; spans both tenants, not combinable with `--tenant`) | **The default lists only ONE context's keys** (the token's context — `default`, or `--context`), not your whole account — easy to miss since the active-key limit is tenant-wide across all contexts. `--all-contexts` is the true account-wide view. |
 | `get <keyId>` | `--context <c>`, `--tenant test\|live` | `--context` pins the verb token to the key's context — omit it for a key bound to a non-default context (e.g. one `bootstrap` minted) and the lookup 404s. |
-| `revoke <keyId>` | `--context <c>`, `--tenant test\|live` | Soft-delete; ~5 minutes to take effect (authorizer cache). Same `--context` pinning caveat as `get`. |
+| `revoke <keyId>` | `--context <c>`, `--tenant test\|live` | Soft-delete; it takes about 5 minutes to take effect. Same `--context` pinning caveat as `get`. |
 | `rotate` | `--principal <p>`, `--context <c>` (required); `--name <n>`, `--force-new`, `--tenant test\|live`, destination flags above | Revokes the matching active key (by the exact `(context, principal, name)` tuple), then mints a fresh one — there is no dedicated rotate endpoint. **Default-name guard:** if no key is currently active under `--name` (default `default`) but the principal/context has *other* active keys, `rotate` refuses rather than silently minting an unrelated second key — pass the right `--name` or `--force-new` to proceed anyway. |
 
 `issue`/`rotate` have no `--json` (use `--format json` instead); `list`/`get`
@@ -652,6 +719,7 @@ vectros keyring show                 # the active entry's fields + its key
 vectros keyring show --format raw    # JUST the secret, for scripts (see below)
 vectros keyring doctor               # is the keyring healthy? which keys are live?
 vectros keyring prune                # drop entries whose stored secret is gone
+vectros keyring prune --dry-run      # report what would be removed, remove nothing
 vectros keyring remove <alias>       # drop one entry + its secret
 ```
 
@@ -714,8 +782,8 @@ Blueprints are **untrusted input** (agent- or community-authored) and the
 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 / triggers) or a
+/ `folders` / `inference` / `entities` / `runs`). Most control-plane scope (keys /
+app-contexts / users / billing / admin / namespaces / triggers / agents) or a
 `*` wildcard **hard-rejects** — the CLI mints nothing and exits non-zero. There is
 intentionally **no override flag**.
 
@@ -754,7 +822,7 @@ A blueprint's `accessProfile` and role clauses may also declare
 identity in your tenant) that reach across a partition boundary in a way no
 `resource:ops` verb can express. This rides a field entirely separate from
 `allowedActions`, and it has its own allowlist: **`member-lifecycle` and
-`delegate-principal-stamp` are admitted today.** Every other capability name —
+`delegate-principal-stamp` are admitted.** Every other capability name —
 including ones the platform's own registry recognizes — is refused, the same
 fail-closed, deliberately-widen posture as the scope gate above. `vectros blueprint validate`/`plan` and
 `bootstrap` all report a rejected capability the same way they report a