@vectros-ai/cli 0.24.0 → 0.25.0

package/AUTHORING.md

@@ -55,8 +55,10 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
    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
@@ -301,10 +303,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
@@ -549,8 +552,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,73 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 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

@@ -14,7 +14,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.
@@ -211,7 +211,7 @@ 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.
+errored; `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 +225,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 +233,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 +285,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 +296,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 +307,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.
+
+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 +388,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 +413,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.
@@ -522,7 +549,7 @@ vectros access revoke --principal usr_<id> --context my-app
 
 `--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 +564,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 +582,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 +611,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 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
@@ -612,7 +641,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.