@vectros-ai/cli 0.14.0 → 0.16.0

package/AUTHORING.md

@@ -49,14 +49,24 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
 
 1. **Structural** — the file parses against the blueprint schema (readable
    `path: message` errors, e.g. `schemas[0].fields[1]: Required`).
-2. **Scope gate** — the requested `allowedActions` are data-plane only. This is
-   the trust boundary: control-plane scopes (`keys`, `profiles`,
-   `users`, `admin`, …) and the `*` wildcard are **hard-rejected, no override**.
-   A forked or hand-written blueprint gets the *identical* gate a bundled one
-   does — it can never escalate.
+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). Any
+   requested `capabilities` are checked the same way, against their own,
+   separate allowlist — see "Capabilities" below. A forked or hand-written
+   blueprint gets the *identical* gates a bundled one does — it can never
+   escalate.
 3. **Lint** — semantic checks: duplicate `fieldId`, a `lookupField` naming a
    field that doesn't exist, a `seed` for a typeName with no schema (errors);
-   `enumValues` on an incompatible type, and the dataScope null-sentinel nudge
+   `enumValues` on an incompatible type, the dataScope null-sentinel nudge,
+   and a role/`accessProfile` clause that omits `dataScope` **entirely** on
+   an owner-scoped read/write action — a stronger nudge than the null-
+   sentinel one, since it means unconstrained reach across every owner, not
+   just a narrower gap in an existing constraint. Say so explicitly with
+   `dataScope: {}` when a shared/tenant-wide resource is what you intend
    (warnings — they print but don't fail).
 
 `validate` accepts a file path **or** a bundled blueprint name.
@@ -154,18 +164,120 @@ accessProfile:
   # owners' records, not shared/seed data. Keys are userId + namespaced scopes
   # (scope:org, scope:client, ...):
   # dataScope: { "scope:org": [<org-uuid>, null] }
+  # Omitting dataScope ENTIRELY is different from an empty dataScope: {} —
+  # both mean "every owner", but only {} says so on purpose. `validate` warns
+  # on the omitted-key form so an author who meant "my own org" and forgot
+  # the key notices before minting; write dataScope: {} to say the reach is
+  # deliberate.
+  # capabilities: [member-lifecycle]
+  # A SEPARATE gated dimension from allowedActions — named platform effects a
+  # resource:ops verb can't express (e.g. creating/removing an identity in
+  # your tenant). Only 'member-lifecycle' is admitted today; every other name
+  # is hard-rejected, same posture as the scope gate. See "Capabilities" below.
+
+roles:
+  # Optional. Reusable, identity-agnostic access rules — DISTINCT from
+  # accessProfile (which scopes only the blueprint's own service-principal
+  # key). A role is provisioned but bound to no one by `bootstrap`; bind it
+  # afterward with `vectros access grant --principal <p> --context <c> --role
+  # <roleId>`, or let a human self-enroll with `vectros join <context> --role
+  # <roleId>`. Each roleId maps to an ORDERED LIST of clauses — a record is
+  # accessible when ANY clause grants it, and within one clause every
+  # dataScope dimension must match (the same allowedActions/dataScope/
+  # capabilities shape as accessProfile, three-part, evaluated per-clause):
+  editor:
+    - allowedActions: [records:cru, records:d, search:r, schemas:r]
+      dataScope: {}   # explicit marker for tenant-wide (unscoped) reach
+  member:
+    - allowedActions: [records:r, search:r]
+      dataScope: { userId: ['${{ self.userId }}'] }   # self-scoped: only your own records
 
 servicePrincipal:
   externalId: my-thing-sp   # stable; the principal the profile + key bind to
   displayName: My Thing
 
 seed:
-  - typeName: thing
+  - surface: record          # 'record' | 'document' — the seed's own discriminator
+    typeName: thing
     externalId: seed-welcome   # stable → idempotent; re-apply converges
     fields: { title: "Hello" }
     # Seeds are illustrative sample data. They're applied by default; provision a
     # production context with `bootstrap --no-seed` to skip them (schemas + key
     # still apply).
+
+issuers:
+  - issuerId: auth0-prod       # your slug; 3-31 chars, lowercase letter first
+    issuer: "https://your-tenant.us.auth0.com/"
+    jwksUri: "https://your-tenant.us.auth0.com/.well-known/jwks.json"
+    audience: "https://api.your-app.example.com"   # globally unique per (issuer, audience)
+    contextId: mcp             # MUST equal this blueprint's own contextId (above)
+    # Optional trusted third-party IdP issuers (BYO-IdP token exchange). Applied
+    # in the BOOTSTRAP-token phase, alongside app-context/service-principal
+    # creation — NOT the same phase as schemas/accessProfile/roles above (see
+    # BLUEPRINT_FIELD_PHASES, exported by @vectros-ai/blueprints). Registration
+    # is create-once: re-applying an already-registered issuerId leaves it
+    # unchanged — there's no update, so an edited jwksUri/audience on a live
+    # issuer won't take effect via re-apply.
+    #
+    # Each entry's contextId must equal the blueprint's own contextId. An issuer
+    # is a trust anchor — whoever controls its jwksUri can mint identities your
+    # tenant accepts — so a blueprint may only attach one to the context it
+    # actually provisions. One IdP account serving several contexts needs one
+    # entry per context anyway, because (issuer, audience) must be unique; put
+    # each in that context's own blueprint.
+
+namespaces:
+  - namespace: team           # 2-32 chars, lowercase letter first; reserved names
+                               # (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
+                               # one for this context's own callers.
+    specificityRank: 500      # 0..1_000_000, unique among this blueprint's namespaces
+    entityBacked: true        # optional
+    membershipRecordType: thing   # MUST be a typeName this blueprint declares in
+                                   # schemas: above — membership can only resolve
+                                   # over a record type the blueprint itself ships,
+                                   # never one that merely already exists in the
+                                   # target context. membershipTargetField required
+                                   # alongside it.
+    membershipTargetField: userId
+    membershipLevelField: level        # optional; membershipLevels required alongside it
+    membershipLevels: [admin, viewer]
+    # Registered in the SAME bootstrap-token phase as issuers, before schemas.
+    # Always owned by this blueprint's own contextId (above) — there is no
+    # tenant-wide option, since the platform confines namespace registration to
+    # the credential's own context unconditionally, even for a tenant-wide
+    # request. Registration is create-once, NOT idempotent server-side: a
+    # re-apply matching every declared field converges silently, but one that
+    # disagrees with what's already registered fails the apply rather than
+    # silently overwriting it.
+
+identities:
+  team:                       # local name — referenced elsewhere as ${{ identities.team }}
+    kind: org                 # 'user', or an entity namespace (org/client/one you registered)
+    externalId: acme-team     # your stable id; resolution is idempotent by this value
+    displayName: Acme Team    # optional (users: folded into payload.displayName instead —
+                               # a user has no first-class `name` field)
+    metadata: { plan: pro }   # optional JSON object, merged into the principal's payload
+    # A declared name must match letters/digits/underscore, not starting with a
+    # digit (demoOrg, not demo-org) — the same grammar '${{ identities.<name> }}'
+    # itself can match. A name outside it is rejected as a parse error at
+    # declare time (validate/plan), not silently accepted. Every declared
+    # identity is ensure-exist'd (idempotent by
+    # externalId), whether or not anything below references it, in its OWN
+    # creds-bearing pass — tenant-wide, under the bootstrap credential, BEFORE
+    # either loader phase (not in BLUEPRINT_FIELD_PHASES for that reason).
+    # Reference the resolved principal id anywhere one is valid — a schema's
+    # userId/scopes, an accessProfile/role dataScope or identityOverrides,
+    # seed-record ownership — e.g.:
+    #   identityOverrides: { "scope:org": "${{ identities.team }}" }
+    # Only the WHOLE id can be referenced (no '${{ identities.team.externalId }}'
+    # property access), and every reference must name an identity declared here
+    # — both checked OFFLINE at validate/plan, never deferred to a live apply.
 ```
 
 YAML or JSON are both accepted (chosen by extension). The bundled library is
@@ -284,13 +396,29 @@ reference Y", add the reference field to `lookupFields` as an equality lookup
 ### The scope gate — what you can and can't request
 
 The gate allows only **data-plane** resources:
-`records`, `schemas`, `search`, `documents`, `folders`, `inference`.
+`records`, `schemas`, `search`, `documents`, `folders`, `inference`, `entities`
+(per-namespace identity-entity CRUD — `org`/`client`/any namespace you
+registered — ownership-gated the same way as `records`; it grants no
+authority over the namespace *registry* itself, which stays root-key-only).
 Operations are `c|r|u|d`, combinable (`records:cru`), with a per-resource
 wildcard (`records:*`). Anything else — control-plane resources or the bare
 `*` — is rejected, and there is **intentionally no override flag**. This is
 *why* it's safe to apply a blueprint you didn't write: the binary is the trust
 boundary, not the file.
 
+### Capabilities (`granted_capabilities`) — a separate, equally-gated dimension
+
+An `accessProfile` or role clause may also declare `capabilities: [...]` —
+named platform effects (like creating or removing an identity in your tenant)
+that a `resource:ops` scope token can't express. This rides its own field,
+separate from `allowedActions`, and has its own allowlist: **only
+`member-lifecycle` is admitted today.** Every other capability name —
+including ones the platform's own registry recognizes — is refused, the same
+fail-closed, deliberately-narrow posture as the scope gate above. `validate`,
+`plan`, `blueprint-test` and `bootstrap` all report a rejected capability the
+same way they report a rejected scope: nothing mints, and the CLI exits
+non-zero.
+
 ### The idempotency contract
 
 Re-applying a blueprint **converges, never duplicates**, because everything has
@@ -306,6 +434,21 @@ but fails on every re-apply with an "already exists" error instead of the
 existing record. Request `:r` alongside `:c` on every resource your blueprint
 creates (the bundled blueprints all do this — see the example above).
 
+**One qualification to "converges, never duplicates": a NEW key mint bound to
+a pre-existing service principal is not silent.** If `servicePrincipal.externalId`
+resolves to an identity that already existed in the tenant before this run —
+ordinarily true on a routine same-machine re-apply, since the earlier run's
+local key record already names that same principal — `bootstrap` proceeds as
+usual. But the FIRST time a new machine (no local key record for the blueprint's
+`contextId`) applies a blueprint whose service principal already exists, it
+refuses by default and asks for confirmation: interactively, a y/N prompt;
+non-interactively (`--yes`, or no TTY), it requires `--confirm-existing-principal`
+and otherwise exits with an error rather than minting silently. This is
+deliberate — the platform cannot tell an intentional second-machine setup apart
+from a blueprint's `externalId` colliding with an unrelated identity, so it asks
+rather than guessing either way. `--rotate` is exempt only when the local
+record already names the same principal being rotated.
+
 ## Distribution
 
 - **Bundled** — reviewed, versioned blueprints shipped in the library

package/CHANGELOG.md

@@ -3,6 +3,216 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.16.0
+
+### Added
+
+- **A blueprint's `accessProfile` and role clauses can now declare
+  `capabilities: [...]`** — the platform's `granted_capabilities` field,
+  a grant dimension separate from `allowedActions` for named effects that
+  reach across a partition boundary (e.g. creating/removing an identity in
+  your tenant) which no `resource:ops` verb can express. Gated the same way
+  `allowedActions` is: only `member-lifecycle` is admitted, fail-closed,
+  every other name (including ones the platform's own registry recognizes)
+  is refused before anything mints. `vectros blueprint validate`/`plan` and
+  `bootstrap` all report a capability grant/rejection the same way they
+  already report a scope grant/rejection.
+
+- **`bootstrap` now flags when a mint binds to a principal that already existed in your
+  tenant before this run**, and the outcome summary always reports whether the service
+  principal was newly created or reconciled. This surfaces the one collision shape the
+  platform itself can't tell apart from an intentional one (e.g. re-applying a blueprint
+  from a second machine): a blueprint's declared `servicePrincipal.externalId` matching an
+  existing, unrelated identity in your tenant. Interactively, you're prompted to confirm
+  before the key mints; non-interactively (`--yes`, or no TTY) the run refuses by default
+  and requires the new `--confirm-existing-principal` flag to proceed, so an unexpected
+  collision fails a CI run loudly instead of silently minting a credential bound to the
+  wrong identity. Never triggered by `--rotate` or an ordinary same-machine re-apply — both
+  are exempted as already-informed operator intent.
+
+- **The bootstrap scope gate now admits `profiles:c:self`.** The platform's
+  `profiles:c`/`u`/`d` accept an optional qualifier confining WHICH principal
+  the grant may act on — a literal `usr_<id>`, or the bare `self` sentinel,
+  which the platform resolves from the caller's own bound identity, never
+  from anything a blueprint declares. A role clause (or the bootstrap
+  `accessProfile`) may now grant `profiles:c:self` to let a credential create
+  an access profile for itself. A bare, unqualified `profiles:c`, and a
+  literal `profiles:c:usr_<id>` naming another principal, still hard-reject —
+  only the platform-resolved `self` form is admitted.
+
+- **`vectros blueprint validate`/`plan` now warns when a role or the
+  `accessProfile` clause has NO `dataScope` key at all on a read/update/delete
+  action against `records`/`documents`/`entities`.** The existing null-sentinel
+  warning already caught a *narrower* dataScope gap; this catches the more
+  dangerous case of no constraint whatsoever, which grants reach across every
+  owner in the tenant — not "my own org", whatever the author may have
+  intended. Advisory only (`exit 0`): a deliberately shared/tenant-wide
+  resource (declared with `dataScope: {}`) is unaffected.
+
+- **Top-level `namespaces[]`** registers a blueprint's own namespaces via
+  `POST /v1/namespaces`, in the same bootstrap-token phase as `issuers`.
+  Every registration is unconditionally owned by the blueprint's own
+  context — there is no tenant-wide option, since the platform confines
+  namespace registration to the caller's own context unconditionally, even
+  for a `contextId: null` request. Registration is not idempotent
+  server-side; a re-apply matching the existing declaration converges
+  silently, one that disagrees throws rather than being swallowed.
+
+### Fixed
+
+- **`key issue`/`list`/`get`/`revoke`/`rotate` can now target the test tenant
+  via `--tenant test`**, matching `bootstrap`/`join`/`context`. Previously
+  none of the five accepted it, so a key minted into the test tenant (e.g. by
+  `bootstrap --tenant test`) could be discovered via `key list --all-contexts`
+  (which spans both tenants) but never individually fetched, revoked, rotated,
+  or re-issued — there was no way to reach it at all. `--tenant` is refused in
+  combination with `--all-contexts`, which already spans both tenants on its
+  own.
+
+- **`bootstrap` (and `blueprint-test`) now work for a blueprint whose `issuers:`
+  target a non-`default` app context** — previously every such blueprint failed
+  registration with an authorization error, even though the same blueprint's
+  schemas/roles/access profile provisioned fine. The bootstrap credential now
+  re-mints itself, pinned to the blueprint's own context, specifically to
+  register issuers — closing the gap left once the platform started requiring
+  an issuer registration to be confined to the context it targets. No blueprint
+  authoring change needed; existing `issuers:` entries behave the same, they
+  just no longer fail for any context other than `default`.
+
+- **`blueprint-test` now also registers and reads back each declared `namespaces[]` entry**,
+  the same assert-readback proof `issuers`/schemas/roles already get. Its teardown is honest
+  about what it can and can't undo: a namespace registration is never deleted — namespace
+  deletion requires a root API key, which the harness never holds — and is reported as a
+  permanent skip rather than a silently-attempted step. Issuer teardown may now report a failed
+  step rather than a silent success, too: the platform refuses (`409`) to delete an issuer that
+  has ever completed a real token exchange during the run.
+
+- **The blueprint format reference showed an `issuers:` entry that no longer validates.**
+  `AUTHORING.md`'s "the format, field by field" example declared one `contextId` for the
+  blueprint and a different one inside `issuers[0]`. As of `@vectros-ai/blueprints` 0.13.0
+  an issuer must target the blueprint's own app context, so copying that example produced a
+  blueprint `vectros blueprint validate` rejects. The example now matches, and the reference
+  states the constraint where the field is introduced rather than leaving you to discover it
+  from a validation error.
+
+- **The bootstrap scope gate now admits `profiles:r`/`profiles:u`/`profiles:d`** —
+  read is disclosure-only and cannot widen anything; update/delete are bounded by
+  a platform-enforced check that a write to an AccessProfile can never grant more
+  scope than the requesting credential already holds, so they can only
+  redistribute or revoke access, never manufacture new reach. A bare, unqualified
+  `profiles:c` (creating a profile for an arbitrary, caller-chosen principal
+  name) and every `users:*` verb stay rejected — see the `profiles:c:self`
+  entry above for the one qualified exception. This unblocks any blueprint
+  role that reads or manages its own app-context's membership — previously
+  the gate refused the whole role outright the moment it named any
+  `profiles:*` scope.
+
+- **`bootstrap --tenant test`, `join --tenant test`, and `key issue|rotate
+  --to-keyring` no longer silently activate over a live credential.** Storing
+  a freshly-minted (or re-joined) test-tenant key used to make it the
+  machine's active identity unconditionally, exactly like a live-tenant run —
+  flipping what `vectros keyring show --format raw` (and anything that
+  resolves through it with no explicit `--alias`, including the MCP server)
+  authenticates as, with no warning. `key issue|rotate --to-keyring` has no
+  `--tenant` flag of its own; it now classifies the tenant from the minted
+  secret's own prefix. All three commands now activate unless doing so would
+  displace a currently-active LIVE credential, in which case the key is
+  stored (or the re-join still counts as a successful join) without switching
+  to it, and the terminal says so explicitly — naming whether that was the
+  safety default or an explicit `--no-activate`, never the wrong reason.
+  `bootstrap`/`join` also take `--activate` to force activation over a live
+  credential explicitly; `key issue|rotate --to-keyring` has no such flag
+  today — run `vectros switch <alias>` afterward if you want that key active.
+
+- **`keyring list`'s human-readable table now shows a `tenant` (test/live)
+  column and drops `env` (staging/production).** `env` is an internal-team
+  concern an external developer's CLI never surfaces; `tenant` is the
+  distinction every user actually holds two credentials side by side over, and
+  previously the only way to see it was to run `doctor` instead or hope the
+  alias happened to carry a `.test` suffix. `--json` output is UNCHANGED —
+  still metadata-only, no per-entry secret read, no `tenant` field — because
+  resolving every entry's secret from the OS credential store (what showing
+  tenant requires) is real per-invocation cost a script relying on `--json`'s
+  established speed should not silently start paying.
+
+### Changed
+
+- **Internal:** the exact `@vectros-ai/blueprints` dependency pin was updated so a clean
+  `npm ci` resolves. No behaviour change.
+
+### Security
+
+- **`@napi-rs/keyring` is now pinned to an exact version** (was `^1.3.0`). The
+  Linux/Windows fail-closed guarantee behind `keyring remove`/`prune` rests on
+  an upstream behavioural contract — a locked credential store must make
+  `findCredentials()` throw, not return an empty list — that this package does
+  not otherwise verify at install time. A future bump of this dependency should
+  be treated as a security review of that contract against the new release, not
+  a routine version update (see the comment at its enforcement site,
+  `os-keychain.ts`, for exactly what would break).
+
+## 0.15.0
+
+### Added
+
+- **`bootstrap` can register trusted third-party IdP issuers via a blueprint's
+  new `issuers:` block** (requires `@vectros-ai/blueprints` 0.12.0+). Each entry
+  (`issuerId`, `issuer`, `jwksUri`, `audience`, `contextId`, optional `subClaim`/
+  `emailClaim`) is applied in the bootstrap-token phase — alongside app-context
+  and service-principal creation — using the same owner-only authority that
+  creates the app context itself, never an ordinary partner-grantable scope.
+  `vectros blueprint plan` names this phase explicitly in the preview.
+
+- **`vectros blueprint-test` now verifies a declared `issuers:` entry actually
+  registered and is readable back**, the same live-credential proof it already
+  gives schemas and roles. One limitation, surfaced explicitly in the run's
+  report rather than silently: the platform has no way to remove a registered
+  issuer yet, so (unlike every other resource `blueprint-test` provisions)
+  issuer registrations are not torn down after the test run.
+
+### Fixed
+
+- **`key rotate` no longer silently mints a second key when `--name` defaults
+  to `'default'` and the real key you meant to rotate is named something
+  else** (e.g. a `bootstrap`-minted key, which is never named `'default'`).
+  It now refuses when the default name matches no active key but another
+  active key already exists for the same principal/context, naming the
+  other key(s) so you can re-run with the right `--name` — or `--force-new`
+  to mint a new one alongside them anyway. Previously this minted an
+  unrelated key with no error or warning, leaving the original — possibly
+  the reason you were rotating — still active.
+
+- **`bootstrap --blueprint <file>` now accepts `--set name=value` / `--values
+  <file>`** for a file blueprint's declared `inputs:`, matching what `vectros
+  blueprint validate`/`plan` already supported. Previously there was no way
+  to apply a blueprint with a required, no-default input via `bootstrap` at
+  all — the flags simply didn't exist on that command. Supplying either flag
+  against a bundled or `--blank` blueprint (which have no `inputs:` to set)
+  is now a clear usage error rather than a silent no-op.
+
+- **The bootstrap scope gate no longer treats `entities` (identity-entity
+  CRUD — `org`/`client`/any namespace you registered) as control-plane.**
+  It's ordinary tenant data, ownership-gated the same way as `records` —
+  creating or reading an entity grants no additional access by itself. This
+  had blocked provisioning any blueprint role that manages its own
+  entities (e.g. a user creating their own org). The namespace *registry*
+  itself (registering a new namespace type) is unaffected and stays
+  root-key-only, correctly rejected by the gate as before.
+
+- **The displayed/stored environment (`whoami`, `keyring list`/`doctor`, `blueprint-test`'s
+  banner) now reflects the base URL a command actually resolved and sent requests to, not
+  a hidden flag default.** The two diverge whenever `VECTROS_API_BASE_URL`/`--base-url`
+  alone selects the environment (the common shape when targeting staging without also
+  passing `--env staging`) — previously this echoed the wrong environment label next to a
+  key or session that was actually minted/used against a different one.
+
+### Changed
+
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.39.0` (the
+  trusted BYO-IdP issuer registry and RFC 8693 token exchange, `exists-by-email`, and the
+  scoped-token TTL cap narrowed to 1 hour). The CLI bundles the SDK into its published
+  binary, so this is a rebuild against its current version.
+
 ## 0.14.0
 
 ### Security

package/README.md

@@ -8,6 +8,11 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`vectros bootstrap`** — provision a least-privilege MCP credential (+ optional blueprint).
 - **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`), creds-free.
 - **`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 identity`** — manage tenant-wide principals (users, orgs, clients, and namespaces you register).
+- **`vectros role`** — define reusable, context-scoped access rules.
+- **`vectros access`** — bind principals to contexts, and inspect what a binding grants.
+- **`vectros key`** — issue, list, revoke, and rotate scoped API keys (`ssk_*`).
 - **`vectros keyring`** — hold several identities on one machine, pick which is active, and let other tools resolve keys from one place.
 
 ```bash
@@ -58,6 +63,11 @@ npx -y @vectros-ai/cli bootstrap --help
 ```
 
 Re-running is idempotent; `--rotate` revokes + re-mints just this machine's key.
+On a machine with no local record of a prior mint (e.g. an ephemeral CI
+container re-running `--yes` for the first time) against a blueprint whose
+service principal already exists in the tenant, `--yes` alone isn't enough —
+add `--confirm-existing-principal` to make that expected case explicit and
+non-interactive; see AUTHORING.md's "idempotency contract" for why.
 
 A bundled blueprint ships with **sample seed records** so the credential works
 the moment it's minted. For a **production** context that's synthetic clutter:
@@ -110,6 +120,163 @@ Exit `0` = applied and every assertion passed; `1` = an assertion failed or appl
 errored; `2` = no credential, or the blueprint requested control-plane scope.
 The app-context is intentionally **not** deleted (it's idempotent and reused).
 
+## `vectros context` — app contexts
+
+A context is the namespace all data (records, documents, schemas, roles, access
+profiles) lives in — the unit `bootstrap`/`blueprint-test` provision into.
+`vectros context` manages contexts directly, outside of a blueprint.
+
+```bash
+vectros context create my-app --name "My App"   # idempotent — re-running converges
+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
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `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. |
+
+All four accept `--json` for machine-readable output, plus the common auth
+flags (`--base-url`, `--token`).
+
+## `vectros identity` — tenant-wide 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.
+
+```bash
+vectros identity create --type user --external-id alice@example.com --email alice@example.com
+vectros identity create --type org --external-id acme-inc --name "Acme Inc"
+vectros identity list --type user
+vectros identity get --type org --id <vectrosId>
+vectros identity delete --type org --id <vectrosId>
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create` | `--type <user\|namespace>` (required), `--external-id <id>` (required — your stable idempotency key) | 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>` | 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. |
+| `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) | |
+
+`create`/`list`/`get` 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
+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.
+
+```bash
+vectros role create --context my-app --role-id editor --name Editor \
+  --actions records:cru,search:r
+vectros role create --context my-app --role-id own-org --name "Own org" \
+  --actions records:r --data-scope '{"scope:org":["<orgId>", null]}'
+vectros role list --context my-app
+vectros role get --context my-app --role-id editor
+vectros role delete --context my-app --role-id editor
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--description <text>` | Idempotent by `roleId`. `--data-scope` confines the clause to owned data — a JSON map of ownership dimension → allowed values, ANDed across keys (e.g. `{"userId":["${{ self.userId }}"]}`, or `{"scope:org":["<orgId>", null]}` — the `null` entry additionally admits scope-less/tenant-shared records). Keys must be `userId` or `scope:<namespace>` (the legacy flat `orgId`/`clientId` keys are rejected server-side). |
+| `list` | `--context <c>` (required) | |
+| `get` | `--context <c>`, `--role-id <id>` (both required) | |
+| `delete` | `--context <c>`, `--role-id <id>` (both required) | No cascade — any access profile still referencing the role fails to mint (not silently downgraded) until reassigned. |
+
+`create`/`list`/`get` accept `--json`; `delete` does not.
+
+## `vectros access` — bind principals to contexts
+
+The binding layer between an identity and a context: `access grant` joins a
+principal to a context via a Role reference (`--role`) **or** inline actions
+(`--actions`) — never both. A later `vectros key issue` mints a credential
+that authenticates *as* the bound principal and can never exceed this
+binding.
+
+```bash
+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 get --principal me --context my-app
+vectros access explain --principal me --context my-app
+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.
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `grant` | `--principal <p>`, `--context <c>` (required); exactly one of `--role <roleId>` / `--actions <csv>`; `--scope <ns:value>` (repeatable), `--identity-overrides <json>` | Idempotent **upsert** — re-granting an existing binding updates it to the newly-declared shape (role/actions/overrides), it does not no-op. `--scope`/`--identity-overrides` extend the principal's stamped identity (e.g. `--scope org:<id>` → `scope:org`) — a credential can only stamp ownership its identity carries, so granting write access to org-scoped data requires that scope on the profile. When both are given, `--identity-overrides` wins on key conflicts. |
+| `revoke` | `--principal <p>`, `--context <c>` (required) | |
+| `list` | Exactly one of `--context <c>` / `--principal <p>` | `--context` lists the context's members; `--principal` lists every context that principal is bound to. |
+| `get` | `--principal <p>`, `--context <c>` (required) | |
+| `explain` | `--principal <p>`, `--context <c>` (required) | Resolves the binding's clauses (following its role, if bound via one) and renders a concrete **access matrix** — a canned set of record-ownership archetypes (yours alone, another user's, org-shared, scope-less, …) evaluated against the clauses. A client-side preview for authoring-time sanity, not the platform's own evaluator: it models READ reachability only — a `c`/`u`/`d` action shown as granted is advisory, not a guarantee a specific write will succeed, since the platform's write rule (a clause must explicitly name a dimension to place a value into it) diverges from its read rule (an unmentioned dimension never narrows reads). |
+
+`grant`/`list`/`get`/`explain` accept `--json`; `revoke` does not.
+
+## `vectros key` — the scoped API key (`ssk_*`) lifecycle
+
+Mint, inspect, revoke, and rotate the scoped keys (`ssk_*`) that authenticate
+as a principal already bound to a context (`vectros access grant` first — a
+key can never exceed its profile). The raw secret is disclosed **exactly
+once**, on `issue`/`rotate`; if you lose it, `key rotate` mints a fresh one.
+
+```bash
+vectros key issue --principal usr_<id> --context my-app                  # print the secret (default)
+vectros key issue --principal usr_<id> --context my-app --to-keyring     # store it instead
+vectros key list                                                         # keys in the default context
+vectros key list --all-contexts                                         # every key, every context (owner-only)
+vectros key get <keyId>
+vectros key revoke <keyId>
+vectros key rotate --principal usr_<id> --context my-app                 # revoke + re-mint the same tuple
+```
+
+`--principal` here is `usr_<userId>` **or a bare user id** (the leading `usr_`
+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
+does resolve `--as me`.
+
+A minted secret has exactly two destinations, and the flags for choosing one
+are shared by `issue` and `rotate`:
+
+| Flag | Meaning |
+|---|---|
+| `--format human\|raw\|env\|json` (default `human`) | Print the secret — `raw` = bare secret only, `env` = a `VECTROS_API_KEY=...` line, `json` = the full key object. |
+| `--to-keyring` | Store the secret in this machine's keyring instead of printing it (the desktop/MCP path). Mutually exclusive with an explicit `--format raw\|env\|json`. |
+| `--alias <name>` | Keyring entry name for `--to-keyring` (defaults to the context id). |
+| `--no-activate` | With `--to-keyring`, store the entry without making it the active identity. |
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `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`. |
+| `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`
+accept `--json`, `revoke` does not.
+
 ## `vectros keyring` — one home for your keys
 
 A machine can hold several Vectros identities (one per context or principal).
@@ -188,9 +355,35 @@ Blueprints are **untrusted input** (agent- or community-authored) and the
 CLI runs under an elevated ephemeral bridge token. So the trust boundary is
 **this binary, not the blueprint**: a hardcoded **scope gate** bounds every
 mint to a data-plane allowlist (`records` / `schemas` / `search` / `documents`
-/ `folders` / `inference`). Any control-plane scope (keys / profiles / users /
-billing / admin) or `*` wildcard **hard-rejects** — the CLI mints nothing and
-exits non-zero. There is intentionally **no override flag**.
+/ `folders` / `inference` / `entities`). Most control-plane scope (keys /
+app-contexts / users / billing / admin / namespaces) or a `*` wildcard
+**hard-rejects** — the CLI mints nothing and exits non-zero. There is
+intentionally **no override flag**.
+
+**One narrow, deliberate exception:** `profiles` (which configures who has
+access to what — control-plane by nature) admits its `r`/`u`/`d` operations,
+because the platform enforces an unconditional check that a write to an
+AccessProfile can never grant more scope than the requesting credential
+already holds — those verbs can only disclose or redistribute access, never
+manufacture new reach. `profiles:c` (creating a profile for an arbitrary,
+caller-chosen principal name) still hard-rejects — **except** `profiles:c:self`,
+which the platform resolves from the credential's own identity at request
+time, never from anything the blueprint declares; a bare `profiles:c` or a
+literal `profiles:c:usr_<id>` naming another principal still hard-rejects,
+same as every other control-plane scope.
+
+### Capabilities (`granted_capabilities`) — a separate, equally-gated dimension
+
+A blueprint's `accessProfile` and role clauses may also declare
+`capabilities: [...]` — named platform effects (like creating or removing an
+identity in your tenant) that reach across a partition boundary in a way no
+`resource:ops` verb can express. This rides a field entirely separate from
+`allowedActions`, and it has its own allowlist: **only `member-lifecycle` is
+admitted today.** Every other capability name — including ones the platform's
+own registry recognizes — is refused, the same fail-closed, deliberately-widen
+posture as the scope gate above. `vectros blueprint validate`/`plan` and
+`bootstrap` all report a rejected capability the same way they report a
+rejected scope: nothing mints, and the CLI exits non-zero.
 
 ## Rate limits