@vectros-ai/cli 0.23.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,104 @@
 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
+
+- **`vectros provider-config <create|list|get|update|delete>`** manages your bring-your-own-model provider
+  configs (owner-gated). `create` and `list` take `--tenant test|live`; `get`, `update` and `delete` address a
+  config by its id. The provider credential is read from `--api-key-secret-file <path>` (`-` for stdin); there is
+  no flag that takes the credential on the command line. `update` is a partial patch: an omitted field, including
+  `--api-key-secret-file`, keeps the stored value.
+- **`vectros domains <register|list|delete|verify>`** manages domain ownership verification by DNS TXT record
+  (owner-gated) — the proof of control that `issuers register --restricted-to-domain` and webhook targets rely on.
+  `register` prints the exact TXT record to publish and the `verify` command to run next; registering a domain you
+  already hold returns a `409`. `verify` performs one DNS lookup per call and never polls. Domains are shared
+  across your live and test tenants, so none of the four verbs take `--tenant`. A verified domain that a webhook
+  uses is re-checked periodically; `list` and `verify` report a domain whose re-checks keep failing as
+  `REVOKED`.
+
+### Changed
+
+- **`vectros --version` reports SDK 0.46.0 and blueprints 0.20.1.**
+
+### Fixed
+
+- **`issuers update --clear-restricted-to-domain` is described as the platform applies it.** The platform refuses
+  to clear a domain scope unless the registration already holds the unrestricted `(issuer, audience)` pair, which
+  a registration created scoped to a domain does not. To get an unrestricted issuer, `issuers delete` the scoped
+  registration, register one without `--restricted-to-domain`, and `issuers verify` it. A context holds one
+  active issuer, and the delete is refused once any user has been created or matched through the issuer; in that
+  case register the new issuer under a different app context. The README, the flag's help and the hints shown for
+  a blank `--restricted-to-domain` state this.
+
 ## 0.23.0 — 2026-09-22
 
 ### Added

package/README.md

@@ -11,8 +11,10 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`vectros blueprint-test`** — apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.
 - **`vectros context`** — create, list, and destroy app contexts.
 - **`vectros issuers`** — register, update, delete, and inspect third-party IdP issuers (token-exchange trust anchors) for a context.
+- **`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.
@@ -198,18 +200,18 @@ the result (the app-context + each schema are readable back, and the freshly
 minted `ssk_*` authenticates as a scoped key with the requested actions), then
 **tears down** what it created — schemas, the AccessProfile, seed records, and
 the key. Teardown is *created-only*: anything that already existed before the run
-is left untouched, so it's safe to point at a shared staging tenant.
+is left untouched, so it can be pointed at a tenant other people use.
 
 ```bash
-# Apply → assert → teardown against staging (sign in first, or pass --token).
-vectros blueprint-test ./my-thing.blueprint.yaml --env staging
+# Apply → assert → teardown against your test tenant (sign in first, or pass --token).
+vectros blueprint-test ./my-thing.blueprint.yaml --tenant test
 
 # Leave the provisioned graph in place to inspect it.
 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
@@ -223,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 |
@@ -231,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`).
@@ -262,7 +264,7 @@ vectros issuers verify auth0-prod --context my-app --idp-token-file ./idp-token.
 | Subcommand | Flags | Notes |
 |---|---|---|
 | `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--captured-claim <name>` (repeatable), `--restricted-to-domain <domain>`, `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. `--captured-claim` names additional OIDC claims to capture beyond the email claim on every successful token exchange, stored as your tenant's golden identity-provider-asserted copy for that user; omit it to capture nothing beyond email. At most 20 names of at most 64 characters, no duplicates. `--jwks-uri`/`--userinfo-uri` must be `https://` — an `http://` value is refused with 400. A tenant may hold at most 50 registrations at once; registering past that cap is also refused with 400. A `--self-signup-policy` naming a role that authors, updates, or deletes scripts (`scripts:c`/`u`/`d`) is refused — a self-signup role may still read or execute scripts. `--restricted-to-domain` scopes the registration to a domain already verified for your account (verified once, in the developer portal): a token then matches only when its `hd` claim equals that domain, so the registration is never blocked by an unrelated registration of the same issuer and audience. Google Workspace emits `hd` natively; other identity providers need a claims-mapping rule that emits a claim named exactly `hd`, otherwise none of their tokens will match. An unverified domain is refused with 400; a value that is not a DNS name (including a blank one) is refused locally. `register` never changes an existing registration, so when the response does not carry the requested scope (an existing `--issuer-id` with a different one, or a platform that predates the field) it fails with exit 1 and names `issuers update`, which does apply it; a repeat with the same scope is still an idempotent success. |
-| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--restricted-to-domain <domain>`, `--clear-restricted-to-domain`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. `--sub-claim` is refused with 400 once any user has ever bound through this issuer — supplying the value it already has is still a no-op. `--userinfo-uri` must be `https://`, same as at registration. Omitting `--restricted-to-domain` leaves the stored scope UNCHANGED; `--clear-restricted-to-domain` removes it, and a blank `--restricted-to-domain ''` is refused locally rather than read as a clear. The two are mutually exclusive, and a new domain must already be verified for your account. The platform can refuse to clear a scope (for example when another registration already holds the unrestricted `(issuer, audience)` pair); its message says why. ⚠️ Scoping an existing issuer stops matching every token that carries no matching `hd` claim, including those of users who signed in before. |
+| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--restricted-to-domain <domain>`, `--clear-restricted-to-domain`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. `--sub-claim` is refused with 400 once any user has ever bound through this issuer — supplying the value it already has is still a no-op. `--userinfo-uri` must be `https://`, same as at registration. Omitting `--restricted-to-domain` leaves the stored scope UNCHANGED; `--clear-restricted-to-domain` removes it, and a blank `--restricted-to-domain ''` is refused locally rather than read as a clear. The two are mutually exclusive, and a new domain must already be verified for your account. From platform 0.45.0 the platform refuses to clear the scope unless the registration already holds the unrestricted `(issuer, audience)` pair, which a registration created scoped to a domain normally does not, since it never proved control of that pair. To get an unrestricted issuer instead, `delete` the scoped registration, `register` a new one without `--restricted-to-domain`, and `verify` it. A context holds one active issuer, and `delete` is refused once any user has been created or matched through the issuer; in that case register the new issuer under a different app context. ⚠️ Scoping an existing issuer stops matching every token that carries no matching `hd` claim, including those of users who signed in before. |
 | `delete <issuerId>` | `--context <contextId>` (required), `--force`, `--tenant test\|live` | Re-types the issuer id to confirm (mirrors `context destroy`); `--force` skips the prompt and is required when stdin isn't a TTY. Refused server-side while any user was ever created or matched through this issuer. |
 | `list` | `--context <contextId>` (required), `--tenant test\|live` | Every issuer registered in that context. `--context` has no default — an issuer read is confined to the context you name; there's no tenant-wide "every issuer in every context" view. |
 | `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies, captured claims and `restrictedToDomain`. |
@@ -273,6 +275,93 @@ challenge of a `pending_verification` registration (the claim, the one-time valu
 instructions and the exact `verify` command; a registration made without `--restricted-to-domain` starts that way on
 platform 0.45.0 and later, and `register` exits `0` because a pending issuer is its expected result.
 
+## `vectros provider-config` — BYOM tenant-level provider configs
+
+Manage per-tenant "bring your own model" provider configs — a customer-supplied inference
+endpoint + credential the platform can route to, instead of (or alongside) Vectros's own
+platform-billed models. A tenant may hold more than one, each independently selected by its
+`alias`. There is no SDK support for this route (it is a dev-portal-only surface, like
+`vectros context`) — every verb here calls the owner-gated developer route directly.
+
+```bash
+vectros provider-config create --tenant live --alias primary \
+  --provider-type ANTHROPIC_NATIVE \
+  --waiver-type byo-model-inference:customer-key \
+  --api-key-secret-file ./anthropic-key.txt
+vectros provider-config list --tenant live
+vectros provider-config get pc_abc123
+vectros provider-config update pc_abc123 --status DISABLED
+vectros provider-config delete pc_abc123   # re-types the id to confirm
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `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 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
+command line is visible in shell history and the process list. Pass `--api-key-secret-file
+<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
+
+Prove control of a domain via a DNS TXT record — the same proof-of-control a `vectros issuers
+register --restricted-to-domain` scope, or a webhook target, is checked against. Verification is
+Account-level (shared across your live and test tenants), so none of these commands take
+`--tenant`.
+
+```bash
+vectros domains register --domain example.com
+# → prints the TXT record to publish and the exact verify command
+vectros domains list
+vectros domains verify dom_abc123
+vectros domains delete dom_abc123   # re-types the id to confirm
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `register` | `--domain <domain>` (required) | NOT idempotent — registering a domain you already hold 409s, naming the existing id/status and (if still pending) the `verify` command to run instead. Prints the exact DNS TXT record to publish. |
+| `list` | | Every domain registered for your account, across both tenants. |
+| `verify <id>` | | Performs ONE DNS TXT lookup and reports `VERIFIED`, `FAILED` (never proved) or `REVOKED` (proved once, since lost) — always safe to re-run, never polls for you (the platform's TXT lookup can only succeed once your DNS provider has actually propagated the record). Exit `0` verified, `1` not verified — the platform reports `200` either way, so the exit code (not the HTTP status) is what a script should branch on. |
+| `delete <id>` | `--force` | Re-types the id to confirm; refused server-side (`409`) while any active webhook still references the domain. |
+
+All four accept `--json`, plus the common auth flags (`--base-url`, `--token`). A blueprint can
+only REFERENCE an already-verified domain (as `issuers`' `restrictedToDomain` already does) — it
+cannot declare/register one.
+
+A verified domain that a webhook uses is re-checked periodically. After repeated consecutive failed
+re-checks it becomes `REVOKED` and the webhooks that use it are suspended; `verify` on a `REVOKED`
+domain restores it to `VERIFIED` once the TXT record is published again, and each suspended webhook is
+then re-enabled individually.
+
 ## `vectros namespace` — scope-namespace registrations
 
 Register and inspect the namespaces a `scope:<namespace>` value can belong
@@ -299,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
@@ -319,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`/`acceptLink` for you to deliver yourself. |
+| `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.
@@ -455,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 |
 |---|---|---|
@@ -470,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.
@@ -488,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
@@ -516,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
@@ -545,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.