@vectros-ai/cli 0.16.0 → 0.19.0

package/AUTHORING.md

@@ -87,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
@@ -174,6 +198,16 @@ accessProfile:
   # 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
@@ -247,14 +281,20 @@ namespaces:
     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.
-    # 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.
+    # 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 }}
@@ -267,10 +307,15 @@ identities:
     # 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).
+    # 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.:

package/CHANGELOG.md

@@ -3,6 +3,197 @@
 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

package/README.md

@@ -9,11 +9,13 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`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 issuers`** — inspect registered third-party IdP issuers (token-exchange trust anchors) for a context.
 - **`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.
+- **`vectros join`** — enroll a principal in a context and keep the resulting credential in the keyring, in one step.
 
 ```bash
 npx -y @vectros-ai/cli bootstrap          # provision a credential
@@ -144,6 +146,26 @@ vectros context destroy my-app                  # irreversible — asks you to r
 All four accept `--json` for machine-readable output, plus the common auth
 flags (`--base-url`, `--token`).
 
+## `vectros issuers` — registered third-party IdP issuers
+
+Read the third-party identity-provider registrations a context trusts for
+[RFC 8693 token exchange](https://www.rfc-editor.org/rfc/rfc8693) — the
+`issuer`/`jwksUri`/`audience` a blueprint's `issuers[]` entries register, plus
+any self-signup policy attached to one. Read-only: registering an issuer is
+done through a blueprint (`bootstrap`/`blueprint-test`), not this command.
+
+```bash
+vectros issuers list --context my-app
+vectros issuers get primary --context my-app
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `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. |
+
+Both accept `--json`, 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
@@ -158,6 +180,8 @@ 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>
+vectros identity invite --context my-app --role editor --email bob@example.com \
+  --accept-url https://my-app.example.com/accept
 ```
 
 | Subcommand | Flags | Notes |
@@ -169,8 +193,9 @@ vectros identity delete --type org --id <vectrosId>
 | `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) | |
+| `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. |
 
-`create`/`list`/`get` accept `--json`; `delete` does not.
+`create`/`list`/`get`/`invite` accept `--json`; `delete` does not.
 
 ## `vectros role` — reusable, context-scoped access rules
 
@@ -194,7 +219,7 @@ vectros role delete --context my-app --role-id editor
 |---|---|---|
 | `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) | |
+| `get` | `--context <c>`, `--role-id <id>` (both required) | Also shows the role's `assumable` grant (which values, per namespace, a holder of this role may become via `POST /v1/auth/token/assume`), if any is set. `role create` has no `--assumable` flag today — author it via a blueprint's `roleAssumable:` block or a direct API call. |
 | `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.
@@ -224,14 +249,42 @@ 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. |
+| `grant` | `--principal <p>`, `--context <c>` (required); exactly one of `--role <roleId>` (repeatable — 2+ compose additively) / `--actions <csv>`; `--scope <ns:value>` (repeatable), `--identity-overrides <json>` | Idempotent **upsert** — re-granting an existing binding updates it to the newly-declared shape (role(s)/actions/overrides), it does not no-op. Repeating `--role` composes: `--role case-handler --role hr-admin` grants each role's own clauses, concatenated in the order given — never merged, so each clause keeps meaning exactly what its own author wrote. `--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). |
+| `explain` | `--principal <p>`, `--context <c>` (required) | Resolves the binding's clauses (following every referenced role and concatenating their clauses, if bound via one or more) 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 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
+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.
+
+```bash
+vectros join my-app --role editor                       # enroll "me" via a role
+vectros join my-app --role case-handler --role hr-admin  # compose 2+ roles additively
+vectros join my-app --actions records:cru,search:r --scope org:<orgId>
+vectros join my-app --as usr_<id> --role editor --alias teammate
+```
+
+| Flag | Notes |
+|---|---|
+| `--role <roleId>` | Repeatable — 2+ compose additively, same semantics as `access grant --role`. XOR with `--actions`. |
+| `--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). |
+| `--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
+when the local secret is missing does it rotate to obtain a fresh one.
+
 ## `vectros key` — the scoped API key (`ssk_*`) lifecycle
 
 Mint, inspect, revoke, and rotate the scoped keys (`ssk_*`) that authenticate
@@ -368,9 +421,15 @@ 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.
+time, never from anything the blueprint declares, and **except a bare
+`profiles:c` on a clause that also declares the `member-lifecycle` capability**
+(see Capabilities, below) — that combination is admitted because
+`member-lifecycle` already grants unbounded principal-creation reach, so
+gating bare `profiles:c` behind it adds no further technical bound but keeps
+the same explicit, fail-closed opt-in signal every other admission here
+requires. A literal-qualified `profiles:c:usr_<id>` naming another principal
+still hard-rejects regardless of `member-lifecycle`, same as every other
+control-plane scope.
 
 ### Capabilities (`granted_capabilities`) — a separate, equally-gated dimension
 

package/THIRD-PARTY-NOTICES.md

@@ -1,11 +1,11 @@
 # Third-party notices
 
 `@vectros-ai/cli` compiles the following third-party packages directly into its
-published binary (`dist/cli.js`). Their licenses require that these notices travel
-with the code, so they are reproduced in full below.
+published bundle. Their licenses require that these notices travel with the code,
+so they are reproduced in full below.
 
-This file is GENERATED by `pipelines/third_party_notices.mjs` from the `noExternal`
-lists in `packages/*/tsup.config.ts`. Do not edit it by hand — run
+This file is GENERATED by `pipelines/third_party_notices.mjs` from `packages/cli/tsup.config.ts`'s
+`noExternal` list. Do not edit it by hand — run
 `node pipelines/third_party_notices.mjs --write`. CI fails if it is stale, because a
 notices file that silently drifts is worse than none: it asserts a compliance that
 nobody checked.