@vectros-ai/cli 0.15.0 → 0.19.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.
@@ -77,6 +87,30 @@ A name must be 2–50 chars: a lowercase letter, then lowercase letters / digits
     + seed 1 record(s)
 ```
 
+**A blueprint whose `accessProfile` composes roles (`roleIds:`) previews every
+composed role's clauses individually**, not flattened, because two clauses
+sharing an action set can still carry different `dataScope`:
+
+```
+  Plan for blueprint 'my-thing' (v1.0.0) → context 'mcp':
+    + schema 'thing' (2 fields, HYBRID) lookup: [externalId]
+    + context 'mcp' (MCP — my-thing)
+    + principal 'my-thing-sp' (SERVICE)
+    + role 'case-handler' (1 clause, actions [records:cru])
+      clause 1: actions [records:cru], dataScope: scope:org=[${{ self.scope.org }}]
+    + role 'hr-admin' (1 clause, actions [records:r])
+      clause 1: actions [records:r], dataScope: (none — unconstrained)
+      assumable: scope:org=[org_engineering, org_sales]
+    + profile via role(s) [case-handler, hr-admin] (composed — each role's own clauses, concatenated in order)
+    + key my-thing-<machine> (mint 1 scoped ssk_*)
+    + seed 1 record(s)
+```
+
+A role's `assumable` line only appears when the blueprint's top-level
+`roleAssumable:` map names that role — it's shown because it's
+security-relevant (what a holder of the role may become via `POST
+/v1/auth/token/assume`), not just that the role was declared.
+
 `bootstrap` shows the same plan and asks for confirmation before minting
 (`--yes` skips the prompt for CI/agents). ⚠️ **`--no-merge` is NOT a dry run** — it still
 mints/reconciles for real; it only changes where the resulting credential goes, printing the MCP
@@ -154,13 +188,51 @@ 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.
+  #
+  # Instead of allowedActions (+ optional dataScope/capabilities), accessProfile
+  # may declare `roleIds: [<roleId>, ...]` — one or more roles declared below,
+  # in `roles:`, composed additively (each role's own clauses, concatenated in
+  # the order listed; a single roleId is equivalent to the platform's
+  # deprecated singular roleId reference). Mutually exclusive with allowedActions; a roleIds-
+  # composed profile has no inline clause of its own, so dataScope/capabilities
+  # are rejected alongside it — author those on the referenced role instead:
+  # accessProfile:
+  #   roleIds: [case-handler, hr-admin]
+
+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
@@ -172,7 +244,7 @@ issuers:
     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: my-thing        # which app context an exchanged token targets
+    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
@@ -180,6 +252,77 @@ issuers:
     # 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]
+    # tenantWide: true          # optional, default false. Requests registration visible to
+    #                           # EVERY context in the account, not just this blueprint's own —
+    #                           # see below.
+    # Registered in the SAME bootstrap-token phase as issuers, before schemas.
+    # Owned by this blueprint's own contextId (above) by default. `tenantWide: true` opts
+    # out of that, but declaring it is not enough on its own: the applying credential must
+    # separately hold OWNER-only authority, and `bootstrap`/`apply` refuse to even request
+    # it without the explicit `--allow-tenant-wide-namespaces` flag — a blueprint cannot make
+    # this happen by itself. 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 —
+    # for a tenant-wide namespace this includes a collision with a DIFFERENT blueprint's
+    # (or a manual) registration of the same name, which always fails rather than being
+    # silently adopted.
+
+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 — under the
+    # bootstrap credential, AFTER the app-context, service principal, and any
+    # namespaces: above are registered, but BEFORE schemas/accessProfile/roles
+    # (not in BLUEPRINT_FIELD_PHASES for that reason). This ordering matters
+    # for a non-'user' kind: an 'org'/'client'/registered-namespace identity is
+    # created IN that namespace, so it can only succeed once the namespace
+    # exists — declare it in namespaces: above (or ensure it's already
+    # registered) before referencing it here with a non-'user' kind.
+    # 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
@@ -308,6 +451,19 @@ wildcard (`records:*`). Anything else — control-plane resources or the bare
 *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
@@ -323,6 +479,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,345 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.19.0 — 2026-08-27
+
+### Added
+
+- **`vectros bootstrap`/`blueprint apply` mint a blueprint's own AccessProfile
+  from `accessProfile.roleIds`** (needs `@vectros-ai/blueprints` ≥ 0.16.0) —
+  the platform's additive role composition, wired end to end. Roles are
+  created BEFORE the AccessProfile mint (reordered from the prior sequence,
+  where nothing depended on the order), so a `roleIds` reference always
+  resolves on first apply. `vectros blueprint plan` previews the composed
+  form (`profile via role(s) [...]`), and the scope gate / footgun lints /
+  `blueprint-test` harness assertions all read the composed action set —
+  every referenced role's own clauses, concatenated in order — for a
+  `roleIds` profile instead of the (now-absent) inline `allowedActions`.
+- **`vectros access grant --role` and `vectros join --role` are now
+  repeatable — 2+ roles compose additively**, sending the platform's
+  `roleIds` (plural) instead of the deprecated singular `roleId`. `access
+  get`/`access list` render the composed role list; `access explain` now
+  fetches and concatenates every referenced role's clauses instead of only
+  the first (a profile composing 2+ roles previously rendered as "no
+  clauses" — the singular `roleId` the old code followed is absent once a
+  profile composes more than one). A single `--role` still round-trips
+  through the deprecated singular field on an older server response.
+- **An already-registered issuer now actually reconciles on a blueprint
+  re-apply** (needs `@vectros-ai/sdk` ≥ 0.41.0 for the
+  platform's `PUT /v1/auth/issuers/{issuerId}`) — `subClaim`/
+  `emailClaim`/`userinfoUri`/`selfSignupPolicies` now apply on re-apply, the
+  same create-then-reconcile shape the AccessProfile mint already used. The
+  trust-anchor/routing-pin fields (`issuer`/`jwksUri`/`audience`/`contextId`)
+  remain immutable via that route (rotating one still needs delete +
+  re-register), and `status` is reconcilable on the platform endpoint but has
+  no field in `BlueprintIssuerSchema` to author — `vectros blueprint plan`'s
+  legend and the apply-outcome summary both say so explicitly rather than
+  overclaiming full reconciliation.
+  **Behavior change:** editing a trust-anchor field (`issuer`/`jwksUri`/
+  `audience`/`contextId`) on an already-registered issuer and re-running
+  `bootstrap` now FAILS the whole run with the platform's 400, instead of
+  the prior silent no-op (the edit was simply never applied). This is the
+  correct direction — the loader stopped lying about it — but it is a
+  disclosed behavior change: a blueprint whose issuer trust anchor
+  drifted from its live registration will now block on re-apply where it
+  previously succeeded quietly.
+- **A blueprint can now declare `issuers[].userinfoUri`** (needs
+  `@vectros-ai/sdk` ≥ 0.41.0, `@vectros-ai/blueprints` ≥ 0.16.0) — the IdP's
+  OIDC userinfo endpoint, used as a fallback email-resolution source when a
+  presented access token doesn't carry the configured `emailClaim` directly.
+  Lets a blueprint declare this server-side fallback instead of requiring a
+  manual `PUT /v1/auth/issuers/{issuerId}` outside blueprint authoring.
+  `vectros issuers get` now renders it alongside the other issuer fields.
+- **`vectros identity invite --context <c> --role <roleId> --email <e>`** —
+  onboards a person into a context (`POST /v1/users/invite`) without a
+  hand-crafted `curl` call. `--role` resolves directly to
+  `accessProfile.roleId` (a Role's id is already its own user-facing
+  identifier — no separate name lookup). `--accept-url` is required unless
+  `--no-send-email` is given, in which case the response's raw
+  `inviteToken`/`acceptLink` let you deliver the invitation yourself.
+  Authorizes exactly like `access grant`/`role create` — an ordinary
+  context-pinned token minted from your `vectros login` session, not a root
+  key. No separate setup needed.
+
+### Fixed
+
+- **`createRole` (the loader's role mint) now sends `upsert: true`** — without
+  it, an already-existing role's `scopes` were silently left unchanged on a
+  blueprint re-apply, so editing a role's `allowedActions`/`dataScope` and
+  re-running `bootstrap` never actually took effect, contradicting
+  `LoaderResult.roleActions`' own documented "reconciled means updated to
+  match" contract (the same false-convergence class this release fixes for
+  issuers). Pre-existing, caught in review while building `roleIds`
+  composition — now more consequential than before, since a `roleIds`-
+  composed AccessProfile ties the blueprint's own automatic service
+  credential to a role's live (previously possibly-stale) scope.
+- **The bootstrap loader's scope gate now admits an unqualified `profiles:c`
+  when the same clause also declares `capabilities: [member-lifecycle]`** —
+  the platform's own documented pattern for a self-signup/admin role that
+  invites without raw tenant-wide `users:*` could not previously be
+  authored through `vectros blueprint apply`/`validate` at all: the gate's
+  action check and its capability check ran fully independently, so a bare
+  `profiles:c` always rejected regardless of what capabilities accompanied
+  it. The exception is narrow and additive — bare form only (a literal
+  qualifier like `profiles:c:usr_<id>` is still rejected unconditionally,
+  since `member-lifecycle`'s own elevation requires the fully unqualified
+  grant and does nothing to bound a literal-principal risk), same clause
+  only (a sibling clause's capability grants no benefit), every
+  pre-existing call site unaffected (the new parameter is optional).
+- **`vectros blueprint validate`/`bootstrap`/`apply` no longer reject `${{ member.scope.<namespace> }}`
+  (and its `:<level>` form) as an unrecognized placeholder.** This is a real, shipped, server-side
+  mechanism — resolved per request from `org_membership`-shaped records, with no dependency on a
+  separate, unimplemented token-select step that `${{ self.scope.<ns> }}` needs — the CLI's local
+  lint simply hadn't been updated to recognize it, so an otherwise-correct blueprint authored
+  against it failed `validate` outright with a false `datascope-unknown-placeholder` error, even
+  though the platform itself would have accepted it. Found building a real org-membership-based
+  blueprint: a role's `${{ self.scope.org }}` dataScope silently granted nothing (an unresolved
+  self-placeholder matches nothing, not everything) because nothing populates that identity value
+  by default — switching to `${{ member.scope.org }}` is the actual fix for an org_membership-based
+  role, and the lint was wrongly in the way of it.
+- **`vectros access explain` now reports `${{ member.scope.<ns>[:<level>] }}` as undecidable** instead
+  of silently mismodeling the clause as an opaque literal string — the clause normalizer had no MEMBER
+  case at all before this. Same treatment `${{ under.self.* }}` already gets, via `undecidableDims`
+  rather than a false match or a silent denial.
+
+### Changed
+
+- **`@vectros-ai/sdk` repinned to the latest available `0.41.0` build** —
+  picks up the additive role composition's `roleIds` on
+  `AccessProfileRequest`/`AccessProfileResponse` and the issuer-update
+  surface (`IssuerUpdateRequest`, `client.auth.updateIssuer`). No other wire
+  shape changed since the prior pin (verified against the published
+  tarballs, not just source ancestry).
+
+## 0.18.0
+
+### Added
+
+- **`vectros blueprint plan` now renders the fully-expanded, effective
+  per-clause `dataScope` for every declared role** (needs
+  `@vectros-ai/blueprints` ≥ 0.15.0) — not just the role's flattened action
+  set. This is the review-legibility mitigation the `fragments:`/
+  `dataScopeRef` sugar requires: a clause referencing a fragment has already
+  been expanded to a literal `dataScope` by the time the CLI sees it, so the
+  plan shows exactly what will be granted, never the DSL indirection that
+  produced it. Two clauses sharing an action set can legitimately carry
+  different `dataScope`, so this is shown per clause, not flattened across
+  the role the way the action set is.
+- **A blueprint's `roleAssumable` map is now wired through
+  apply** — `vectros bootstrap`/`blueprint apply` passes
+  `roleAssumable.<roleId>` straight through to that role's `createRole`
+  call as `assumable`, unchanged. `vectros blueprint plan` discloses the
+  grant per role (a security-relevant fact the operator approving the plan
+  needs to see, same reasoning as the existing capability disclosure), and
+  `vectros role get`'s human view now shows a role's `assumable` grant
+  (`--json` already did — it prints the SDK response verbatim). Needs
+  `@vectros-ai/blueprints` ≥ 0.15.0 and `@vectros-ai/sdk` ≥ 0.41.0 (the
+  first generated SDK build carrying `Role.assumable`).
+
+## 0.17.0
+### Added
+
+- **`vectros issuers list --context <ctx>` and `vectros issuers get <issuerId>
+  --context <ctx>`** — read a tenant's registered token-exchange issuers
+  without hand-minting a bootstrap token first. `GET`/`LIST /v1/auth/issuers`
+  require provisioning capability AND are context-confined for any non-root
+  caller, so `--context` is a required flag, not a default: a provisioning
+  token minted with no context pin resolves to the platform's `default`
+  context and won't see an issuer registered under any other one. Both verbs
+  now mint a single st_* carrying provisioning capability PINNED to
+  `--context` — a shape the CLI's auth seam couldn't produce before this.
+- **A blueprint's `namespaces[]` entry can declare `tenantWide: true`** (needs
+  `@vectros-ai/blueprints` ≥ 0.14.0), requesting the platform's tenant-wide
+  registration form instead of the blueprint's own context. `bootstrap`/`apply`
+  now REFUSE such a blueprint before anything provisions — naming the
+  namespace(s) — unless invoked with the new `--allow-tenant-wide-namespaces`
+  flag: a static, scriptable opt-in, deliberately not an interactive runtime
+  prompt. This is the human-deliberateness check only; whether the request
+  actually succeeds is still decided server-side by an OWNER-gated platform
+  capability the flag has no bearing on — a non-OWNER credential gets the
+  existing clear failure regardless of the flag. An ordinary blueprint (no
+  `tenantWide` namespace) is completely unaffected.
+- **`vectros blueprint plan`'s namespace preview names a `tenantWide` namespace
+  explicitly** (`TENANT-WIDE — visible to every context`, in place of the usual
+  `owned by '<contextId>'`), and its legend gains a carve-out: unlike an
+  ordinary namespace registration (which converges silently on a matching
+  re-apply), a tenant-wide one never adopts an existing registration, even an
+  exact field-for-field match — a collision always fails.
+
+### Changed
+
+- **A namespace-name collision on a `tenantWide` registration is always a hard
+  failure, never adopted.** The existing read-back-and-reconcile behavior for
+  an ordinary, context-owned namespace (a re-apply matching every declared
+  field converges silently) does NOT extend to a tenant-wide one: a tenant-wide
+  row is co-owned by no single blueprint, so a field-for-field match is not
+  evidence it's safe to treat as "this blueprint's" — it could just as easily
+  be a different blueprint's (or a manual) registration that happens to declare
+  the same shape. The platform's 400 propagates as-is on any collision.
+
+### Fixed
+
+- **`bootstrap`/`apply` now register a blueprint's `namespaces[]` BEFORE
+  creating any identity it declares in `identities[]`.** Previously, apply-time
+  identity resolution ran before namespace registration, so a blueprint
+  declaring `identities:` in a namespace it ALSO registers via `namespaces:`
+  could never succeed — creating that identity requires the namespace to
+  already be registered, and the old ordering always raced the identity create
+  ahead of it. The app-context, service principal, and every declared
+  namespace are now fully provisioned first; identity resolution (and
+  everything downstream) runs after. This is a step-ordering change only — an
+  unaffected blueprint (no `identities:` referencing a namespace it also
+  registers) sees no behavior change, and no CLI flag or blueprint schema
+  changed.
+
+## 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