@vectros-ai/cli 0.24.0 → 0.26.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,13 +50,15 @@ 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: Required`).
 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**.
    `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).
+   as `profiles:c:self` (create a profile for yourself) or as a bare
+   `profiles:c` on a clause that also declares the `member-lifecycle`
+   capability; a bare `profiles:c` without it, and `profiles:c:usr_<id>` naming
+   another principal, hard-reject.
    `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
@@ -95,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
@@ -109,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])
@@ -119,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
@@ -162,13 +168,13 @@ 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
+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 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.
@@ -301,10 +307,11 @@ namespaces:
                                # (user, record, document, entity, self, tenant,
                                # context, scope, versions, lookup) are rejected.
                                # org/client are NOT in that set -- reserved namespace
-                               # names, not built-ins, registered like any other. They
-                               # already exist tenant-wide at rank 1000/2000 (below) --
-                               # pick a different specificityRank, and note a
-                               # context-owned registration shadows the tenant-wide
+                               # names, not built-ins, registered like any other.
+                               # Signup does not register them. An older account may
+                               # still hold tenant-wide rows at rank 1000/2000 (below),
+                               # so pick a different specificityRank there; a
+                               # context-owned registration shadows a tenant-wide
                                # one for this context's own callers.
     specificityRank: 500      # 0..1_000_000, unique among this blueprint's namespaces
     entityBacked: true        # optional
@@ -364,6 +371,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
@@ -421,7 +438,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 }
 ```
 
@@ -549,8 +565,9 @@ 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
+and re-run `vectros bootstrap`, or run `vectros blueprint apply --prune`, and its rule and
+access profile are deleted, so a trigger you removed cannot keep acting.
+`vectros blueprint apply` without `--prune` deletes nothing. 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.
 

package/CHANGELOG.md

@@ -3,6 +3,113 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 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
+
+- **⚠️ BREAKING: `vectros provider-config create|update` no longer have `--platform-token-factor` and
+  `--platform-output-weight`, and `PLATFORM_BILLED` is no longer a billing mode.** A provider you configure bills you
+  directly, so `CUSTOMER_DIRECT` is the only mode, and `--billing-mode` is optional on `create` and defaults to it. A
+  script that passes either removed flag stops with commander's `unknown option` error (exit 1).
+  `--billing-mode PLATFORM_BILLED` stops locally (exit 2, nothing sent) with a message that the mode is retired, and any
+  other value is refused locally with a message that the mode must be `CUSTOMER_DIRECT`. The key-value output of `get`,
+  `create` and `update` no longer lists the two rates. **Migration:** delete the two flags from your scripts; for a
+  `PLATFORM_BILLED` config that already exists, `vectros provider-config update <id> --billing-mode CUSTOMER_DIRECT`
+  moves it to the only supported mode.
+
+### Added
+
+- **`vectros identity create|list|get|delete|invite` accept `--tenant test|live`**, as `identity list-all`, `context`,
+  `key` and the other tenant-aware verbs do.
+
+### Changed
+
+- **`vectros blueprint --help`, `AUTHORING.md` and the comments `vectros blueprint init` writes into the scaffold state what the scope gate enforces.** They say a
+  bare `profiles:c` is accepted only when the same clause declares the `member-lifecycle` capability (and is rejected
+  without it, and as `profiles:c:usr_<id>` always), that `scripts:x:<script-name>` is admitted, and that
+  `member-lifecycle` and `delegate-principal-stamp` are the two capabilities the gate admits. The scaffold's content is
+  otherwise the same.
+- **`vectros provider-config` help and README state what the platform accepts for a config you set up yourself
+  (platform 0.47.0 and later).** Such a config takes only `--billing-mode CUSTOMER_DIRECT`, the
+  `byo-model-inference:customer-key` waiver type and a plain `https://` endpoint on port 443; the platform refuses any
+  other waiver type and any other port with a `400`. On `update` only a change to one of these is refused; a value the
+  config already holds is accepted. Changing an endpoint's host needs `--api-key-secret-file` again. An account owner
+  signs the risk waiver in the developer portal (Model Providers); the CLI does not sign it. An account that has accepted
+  the Business Associate Agreement with Vectros in the developer portal also needs an owner to attest each config in the
+  portal before a call can use it; the CLI does not attest configs.
+- **`vectros provider-config create --alias` and `update --alias` state the alias rule (platform 0.47.0 and later).** A
+  new or changed alias is 1 to 64 lowercase letters, digits, `-` or `_`; the platform answers `400` with the rule
+  otherwise. An alias a config already holds is accepted. `update --provider-type` help also states that changing the
+  type of an existing config needs `--endpoint` stated in the same command (`--endpoint ''` means the provider's
+  default); the platform answers `400` otherwise.
+- **`vectros context destroy` says a blueprint's service principal stays.** The teardown covers the context's own data;
+  the service principal a blueprint bootstrap created is tenant-wide, so it is left in place. The command's help names `identity delete`, and its success output names `identity list-all` and `identity delete`
+  (with `--tenant test` for a test-tenant context) for the cleanup.
+- **`vectros --version` reports SDK 0.47.0.**
+- **The bundled `@vectros-ai/blueprints` is 0.20.2** (documentation and comments only; behaviour is unchanged).
+- **Source comments state their rules themselves.** Comments that pointed at internal design documents now
+  say what the rule is, so the source maps that ship with the package read on their own. No behavior changes.
+
+### Fixed
+
+- **`vectros access grant --actions` and `vectros join --actions` work.** Both sent an empty `roleIds` list next to the
+  inline actions, and the platform answers that with `400` ("'roleIds' must name at least one role when present"), so
+  only `--role` worked. The request now carries `roleIds` only when you pass `--role`, and `scopes` only when you pass
+  `--actions`.
+- **`--principal me` (and `join --as me`, `access explain --principal me`) resolve your own principal in the tenant you
+  target (needs platform 0.47.0 or later).** Your principal in the test tenant has a
+  different id from your live user, so `access grant --principal me --tenant test` can now join you to your own context.
+  On an earlier platform the live tenant behaves as before and the test tenant typically stops with a message that names
+  `vectros identity list-all --tenant test` and the flag to pass the id with. The "your user id" line of `whoami`, which
+  shows the live tenant, uses the same lookup.
+- **A login session that has expired or been revoked says so and exits 2.** A command that needs sign-in says the session has expired or was revoked and names `vectros login`;
+  it exited 1 with the raw `token endpoint HTTP 400` response. The "no credential" message names the same command.
+- **A refresh token the sign-in service rotates is kept,** so the next command finds its session valid.
+- **`vectros bootstrap` and `blueprint apply` check for an existing service principal before creating anything.** A
+  refusal leaves nothing behind and a re-run starts clean; the plan preview lists the principal before the context. If
+  creating the context then fails (for example a plan limit), the principal this run created stays, and the re-run asks
+  you to confirm using it: pass `--confirm-existing-principal`.
+
 ## 0.24.0 — 2026-10-01
 
 ### Added

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).
@@ -14,7 +16,7 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`vectros provider-config`** — create, list, get, update, and delete BYOM (bring-your-own-model) tenant-level provider configs.
 - **`vectros domains`** — register a domain, list your registrations, and prove DNS TXT ownership.
 - **`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 identity`** — manage principals: users (tenant-wide) and identity entities in the namespaces you register (`org`, `client`, or your own).
 - **`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.
@@ -210,8 +212,8 @@ 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 blueprint requested control-plane scope.
+Exit `0` = applied and every assertion passed; `1` = an assertion failed, apply
+errored, or the blueprint could not be read; `2` = no credential, or the scope gate or the capability gate refused the blueprint.
 The app-context is intentionally **not** deleted (it's idempotent and reused).
 
 ## `vectros context` — app contexts
@@ -225,7 +227,7 @@ vectros context create my-app --name "My App"   # idempotent — re-running conv
 vectros context list                            # every context in the tenant
 vectros context list --mine                     # only contexts you hold an access profile in
 vectros context get my-app
-vectros context destroy my-app                  # irreversible — asks you to re-type the id
+vectros context destroy my-app                  # irreversible — asks you to re-type the id (a blueprint's service principal stays: see `identity delete`)
 ```
 
 | Subcommand | Flags | Notes |
@@ -233,7 +235,7 @@ vectros context destroy my-app                  # irreversible — asks you to r
 | `create <contextId>` | `--name <name>` (defaults to the id), `--tenant test\|live` | Idempotent by `contextId`; re-running converges. |
 | `list` | `--mine`, `--tenant test\|live` | Default lists every context in the tenant; `--mine` narrows to contexts you hold an active access profile in. |
 | `get <contextId>` | `--tenant test\|live` | |
-| `destroy <contextId>` | `--force`, `--tenant test\|live` | **Irreversible.** Permanently erases the context and ALL of its records, documents, folders, schemas, roles, and access profiles, and revokes its scoped keys up front. Interactively you must re-type the context id to confirm; `--force` skips the prompt and is **required** when stdin is not a TTY (scripts/CI). Reports `status: purging` — the teardown itself runs asynchronously. |
+| `destroy <contextId>` | `--force`, `--tenant test\|live` | **Irreversible.** Permanently erases the context and ALL of its records, documents, folders, schemas, roles, and access profiles, and revokes its scoped keys up front. Interactively you must re-type the context id to confirm; `--force` skips the prompt and is **required** when stdin is not a TTY (scripts/CI). Reports `status: purging` — the teardown itself runs asynchronously. A blueprint's service principal belongs to the whole tenant and is NOT removed; delete it with `identity delete` (find it with `identity list-all`). |
 
 All four accept `--json` for machine-readable output, plus the common auth
 flags (`--base-url`, `--token`).
@@ -285,7 +287,7 @@ platform-billed models. A tenant may hold more than one, each independently sele
 
 ```bash
 vectros provider-config create --tenant live --alias primary \
-  --provider-type ANTHROPIC_NATIVE --billing-mode CUSTOMER_DIRECT \
+  --provider-type ANTHROPIC_NATIVE \
   --waiver-type byo-model-inference:customer-key \
   --api-key-secret-file ./anthropic-key.txt
 vectros provider-config list --tenant live
@@ -296,10 +298,10 @@ vectros provider-config delete pc_abc123   # re-types the id to confirm
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `create` | `--alias`, `--provider-type ANTHROPIC_NATIVE\|OPENAI_COMPATIBLE`, `--billing-mode PLATFORM_BILLED\|CUSTOMER_DIRECT`, `--waiver-type`, `--api-key-secret-file <path>` (all required); `--endpoint`, `--declared-processing-region`, `--default-provider-model-id`, `--platform-token-factor`, `--platform-output-weight` (required together, only under `PLATFORM_BILLED`), `--status`, `--tenant test\|live` | NOT idempotent — a repeat `--alias` in the same tenant 400s. `--endpoint` is required for `OPENAI_COMPATIBLE` (no default — every self-hosted deployment is a distinct URL) and an optional override for `ANTHROPIC_NATIVE`; it must be an `https://` URL whose host resolves to a public address. `--status ACTIVE` (the default) requires the tenant already hold a granted waiver for `--waiver-type`. |
+| `create` | `--alias`, `--provider-type ANTHROPIC_NATIVE\|OPENAI_COMPATIBLE`, `--waiver-type`, `--api-key-secret-file <path>` (all required); `--billing-mode CUSTOMER_DIRECT` (optional: the default, and the only value), `--endpoint`, `--declared-processing-region`, `--default-provider-model-id`, `--status`, `--tenant test\|live` | NOT idempotent — a repeat `--alias` in the same tenant 400s. `--alias` is 1 to 64 lowercase letters, digits, `-` or `_`; the platform refuses anything else with a `400` (callers must send it exactly, the match is case-sensitive). `--endpoint` is required for `OPENAI_COMPATIBLE` (no default — every self-hosted deployment is a distinct URL) and an optional override for `ANTHROPIC_NATIVE`; it must be an `https://` URL whose host resolves to a public address. `--status ACTIVE` (the default) requires the tenant already hold a granted waiver for `--waiver-type`. |
 | `list` | `--tenant test\|live` | Every config in one tenant — there is no combined test+live view. |
 | `get <id>` | | One config's metadata. The secret is never returned by the platform, on this or any other verb. |
-| `update <id>` | Same fields as `create` except `--tenant`, all optional | Partial update — an omitted field (`--api-key-secret-file` included) leaves the stored value unchanged. Switching `--billing-mode CUSTOMER_DIRECT` clears the platform pricing fields server-side regardless of what else is sent. |
+| `update <id>` | Same fields as `create` except `--tenant`, all optional | Partial update — an omitted field leaves the stored value unchanged. A new `--alias` must follow the same rule as on `create`; an alias the config already holds is accepted, so a config created before the rule keeps working. Changing `--provider-type` of an existing config needs `--endpoint` stated in the same command (`--endpoint ''` means the provider's default); without it the platform answers `400`, because a stored endpoint would otherwise keep overriding the Anthropic default. One exception to the omitted-field rule: `--endpoint` naming a different host also needs `--api-key-secret-file` (the platform answers `400` rather than send the stored key to a new host). |
 | `delete <id>` | `--force` | Re-types the id to confirm (mirrors `issuers delete`); `--force` skips the prompt and is required when stdin is not a TTY. |
 
 **There is deliberately no `--api-key-secret <value>` flag** — a live provider credential on the
@@ -307,6 +309,28 @@ command line is visible in shell history and the process list. Pass `--api-key-s
 <path>` (`-` for stdin instead of a file), the same shape `issuers verify
 --idp-token-file` already uses for a different live credential.
 
+**Billing mode.** `CUSTOMER_DIRECT` (your provider bills you) is the only billing mode: Vectros does not bill
+for a model provider you configure. `--billing-mode PLATFORM_BILLED` is refused locally as retired, and the old
+`--platform-token-factor` and `--platform-output-weight` flags no longer exist (the CLI reports them as unknown
+options). A script that passed `--billing-mode CUSTOMER_DIRECT` keeps working, and the flag may be left out.
+
+**What the platform accepts for a config you set up yourself (platform 0.47.0 and later).** An account that sets a
+config up itself is refused by the platform with a `400` for anything but `--billing-mode CUSTOMER_DIRECT`, the
+`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. 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
+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
+configs.
+
 All five accept `--json`, plus the common auth flags (`--base-url`, `--token`).
 
 ## `vectros domains` — domain ownership verification
@@ -366,13 +390,18 @@ No `update`/`delete` — both routes require a genuine root API key on the
 platform side, which this CLI never holds, so neither could ever succeed
 here. All three subcommands accept `--json`.
 
-## `vectros identity` — tenant-wide principals
+## `vectros identity` — principals
 
 Manage the principals a context's access profiles and roles reference: users
 (the one fixed principal surface, `--type user`) and namespaced identity
 entities (`org`, `client`, or any namespace you registered, via `--type
-<namespace>`). Identities are **tenant-wide and orthogonal to context** — a
-blueprint or role *references* one by id, it never creates one.
+<namespace>`). Users, and entities in a tenant-wide namespace, are **tenant-wide**:
+`context destroy` leaves them in place. An entity in a namespace registered to one
+context (a blueprint registers its namespaces to its own context by default) belongs
+to that context and is erased with it. A blueprint can declare identities in its
+`identities:` block; apply ensures every declared identity exists (created under the bootstrap credential,
+before the context's own credentials), and where an entity lives follows its namespace, as above. A role
+references an identity by id.
 
 ```bash
 vectros identity create --type user --external-id alice@example.com --email alice@example.com
@@ -386,22 +415,22 @@ vectros identity invite --context my-app --role editor --email bob@example.com \
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `create` | `--type <user\|namespace>` (required), `--external-id <id>` (required — your stable idempotency key) | Idempotent, upsert-by-`externalId`. |
+| `create` | `--type <user\|namespace>` (required), `--external-id <id>` (required — your stable idempotency key), `--tenant test\|live` | Idempotent, upsert-by-`externalId`. |
 | | `--type user` only: `--email <email>`, `--service` (mint a SERVICE principal; default HUMAN) | `--name`/`--scope` are rejected for `--type user`. |
 | | entity namespaces only: `--name <name>`, `--scope <ns:value>` (repeatable, up to 2 parent ownership edges) | `--email`/`--service` are rejected for an entity namespace. |
 | | both: `--metadata <json>` | Free-form JSON object. |
-| `list` | `--type <user\|namespace>` (required), `--external-id <id>` (filter), `--limit <n>` | Scoped to your own context — see `list-all` below for a user created but never granted access anywhere. Omit `--limit` and the CLI drains every page for the complete set; pass `--limit` (1–100) and it returns exactly one page of that size instead. |
+| `list` | `--type <user\|namespace>` (required), `--external-id <id>` (filter), `--limit <n>`, `--tenant test\|live` | Scoped to your own context — see `list-all` below for a user created but never granted access anywhere. Omit `--limit` and the CLI drains every page for the complete set; pass `--limit` (1–100) and it returns exactly one page of that size instead. |
 | `list-all` | `--external-id <id>` (filter), `--tenant test\|live`, `--limit <n>` | **Users only, and requires an account owner login.** Lists every user in the tenant, regardless of app-context access — for recovering a user `identity list` can never show you: one created but not (yet) granted access anywhere, so no context-scoped view can ever reach it, and a `create` retry with the same `--external-id` just collides with the same invisible row. Find it here by `--external-id`, then grant it access or `identity delete` it with an ordinary credential. |
-| `get` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required) | `--id` is the Vectros-assigned id from `create`/`list`, not the `--external-id`. |
-| `delete` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required) | |
-| `invite` | `--context <c>`, `--role <roleId>`, `--email <e>` (all required); `--first-name <n>`, `--accept-url <url>`, `--no-send-email` | Onboards a person into a context by email (`POST /v1/users/invite`) — no root key required, your `vectros login` session already carries enough scope. `--role` is an existing Role's own id (no separate lookup). `--accept-url` is required unless `--no-send-email` is given, in which case the response carries the raw `inviteToken` (and an `acceptLink` when you passed `--accept-url`) for you to deliver yourself. Whenever it is supplied, the accept URL must be an `https://` URL with a domain-name host, never an IP literal. |
+| `get` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required), `--tenant test\|live` | `--id` is the Vectros-assigned id from `create`/`list`, not the `--external-id`. |
+| `delete` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required), `--tenant test\|live` | The way to remove the service principal a blueprint bootstrap created: `context destroy` removes the context's data but leaves that principal, because principals belong to the whole tenant. Find its id with `identity list-all`, and delete it only if nothing else uses it. |
+| `invite` | `--context <c>`, `--role <roleId>`, `--email <e>` (all required); `--first-name <n>`, `--accept-url <url>`, `--no-send-email`, `--tenant test\|live` | Onboards a person into a context by email (`POST /v1/users/invite`) — no root key required, your `vectros login` session already carries enough scope. `--role` is an existing Role's own id (no separate lookup). `--accept-url` is required unless `--no-send-email` is given, in which case the response carries the raw `inviteToken` (and an `acceptLink` when you passed `--accept-url`) for you to deliver yourself. Whenever it is supplied, the accept URL must be an `https://` URL with a domain-name host, never an IP literal. |
 
 `create`/`list`/`list-all`/`get`/`invite` accept `--json`; `delete` does not.
 
 ## `vectros role` — reusable, context-scoped access rules
 
 A Role is a reusable, identity-agnostic scope rule bound to a principal later
-via `vectros access grant --role <roleId>` — the same rule can be shared
+via `vectros access grant --principal <p> --context <c> --role <roleId>` — the same rule can be shared
 across many principals. `role create` builds a **single-clause** role from a
 flat `--actions` list; author a multi-clause role (several rules unioned
 together) in a blueprint's `roles:` block instead.
@@ -514,15 +543,27 @@ 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.
+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>`.
 
 | Subcommand | Flags | Notes |
 |---|---|---|
@@ -537,7 +578,7 @@ shares this grammar.
 ## `vectros join` — enroll and keep the credential, in one step
 
 `join` is a **composition verb**: everything it does already exists as a
-discrete command (`access grant`, `key issue`, `keyring add`) — `join` runs
+discrete command (`access grant`, then `key issue --to-keyring`) — `join` runs
 them in order against one context and records the outcome as a keyring
 entry, so `vectros switch <alias>` (and the MCP server / recall hook) can act
 as that principal from then on.
@@ -555,11 +596,12 @@ vectros join my-app --as usr_<id> --role editor --alias teammate
 | `--actions <csv>` | Inline single-clause grant. XOR with `--role`. |
 | `--as me\|usr_<id>` (default `me`) | Which principal to enroll — `me` resolves to your own signed-in user. |
 | `--scope <ns:value>` | Repeatable. Places the member under a scope for this context (an identity override on the profile) so their key can WRITE that scope's data. |
-| `--alias <name>` | Keyring entry name (defaults to the context id). |
+| `--alias <name>` | Keyring entry name (defaults to the context id; with `--tenant test` the entry is stored as `<alias>.test`). |
+| `--tenant test\|live` (default `live`) | Which tenant the context lives in. |
 | `--activate` / `--no-activate` | Force (or skip) making the freshly-stored key this machine's active identity. |
 
 Re-joining an alias whose secret is still held locally is idempotent: it
-re-grants (a no-op upsert) and re-activates without churning the key. Only
+re-grants (a no-op upsert) and re-activates without churning the key (a `--tenant test` join does not displace an active live identity unless you pass `--activate`). Only
 when the local secret is missing does it rotate to obtain a fresh one.
 
 ## `vectros key` — the scoped API key (`ssk_*`) lifecycle
@@ -583,7 +625,8 @@ vectros key rotate --principal usr_<id> --context my-app                 # revok
 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`), or grant/issue via `vectros join`, which
+--type user` (or `vectros whoami`; both show your live tenant, and for the test tenant
+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
@@ -601,7 +644,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`
@@ -612,7 +655,7 @@ accept `--json`, `revoke` does not.
 A machine can hold several Vectros identities (one per context or principal).
 The keyring stores them as named entries plus one **active** pointer, so you can
 switch between them without re-issuing keys. `vectros join <context>` adds an
-entry and activates it; `vectros key issue`/`key rotate` add one when passed
+entry and activates it (a `--tenant test` join keeps an active live identity unless you pass `--activate`); `vectros key issue`/`key rotate` add one when passed
 `--to-keyring` (which stores the new secret instead of printing it); `vectros switch
 <alias>` flips the active one.
 
@@ -623,6 +666,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
 ```