command_tower 0.10.0 → 0.11.0

data/docs/authentication_authorization_guide.md

@@ -61,6 +61,7 @@ Paths are engine-relative. Full request/response shapes: [api_reference.md](api_
 | Session | `GET /auth/session` |
 | Logout | `POST /auth/logout` |
 | Current account | `GET /me`, `GET /profile` |
+| Principal capabilities | `GET /auth/principal-capabilities` |
 | Name | `PATCH /me/name` |
 | Password change | `PATCH /me/password` |
 | Identity policy | `GET /auth/identity-policy` |
@@ -92,25 +93,24 @@ Validate/reset use the emailed reset token in the body (public). See [password_r
 
 `lib/command_tower/authorization/default.yml`:
 
-- **`owner`** — `entities: true` (full access)
-- **`admin`** — entity `admin_messaging_announcements` on `Admin::Messaging::AnnouncementsController#create`
+- **`owner`** — `entities: true` (full access). Explicit top-level authority; distinct from host operational Admin roles.
 
-There are no engine default roles named `admin-read-only`, `admin-without-impersonation`, or impersonation APIs.
+There is **no** CommandTower operational `admin` role. Admin capabilities are CT-owned **entities** (`admin_workspace`, `admin_users`, `admin_impersonation`, `admin_audit_events`, `admin_messaging_announcements`, …) that hosts grant to their own roles. Impersonation start is `admin_impersonation`; it is not included in dummy `admin` / `operations_admin`. Nested impersonation is forbidden at HTTP **418** while overlaying (workflow nested 403 if reached). Stop is a session primitive (`DELETE /auth/impersonation-session`), not an Admin Users mutation. Other Admin resource endpoints return **418** `admin_unavailable_during_impersonation` during overlay except `GET /admin/workspace` (tools disabled).
 
 ### Host RBAC file (required for Me/Auth)
 
-`AuthorizeRequest` fails closed when controller actions lack entity mappings. Hosts must supply RBAC YAML (default path `config/rbac_groups.yml`):
+`AuthorizeRequest` fails closed when the caller’s roles do not grant the CT-owned entity for the action. CommandTower ships those entity definitions. Hosts supply `config/rbac_groups.yml` with **product roles** that grant entity **names** (default path already `config/rbac_groups.yml`):
 
 ```ruby
 CommandTower.configure do |c|
   c.authorization.rbac_group_path = Rails.root.join("config/rbac_groups.yml")
+  c.authorization.default_membership_role = "member"
 end
 ```
 
-Dummy host example: `rails_app/config/rbac_groups.yml` — defines a **`member`** group and entities for session, me, profile, inbox, preferences, phone, pushover, email verification. Do not redefine groups that already exist in `default.yml` (for example `admin`); add entities and attach them carefully.
-
-Admin announcements: assign users the `admin` role (or another role that includes `admin_messaging_announcements`).
+Dummy host example: `rails_app/config/rbac_groups.yml` — **`member`** grants session, me, profile, inbox, preferences, phone, pushover, email verification; operator roles grant selected Admin entities; a host-owned **`admin`** may deliberately grant a broad Admin bundle. Do not redefine `owner` or copy CT controller/entity blocks. Hosts may define an `admin` role as host policy.
 
+Admin announcements: assign users a host role that includes `admin_messaging_announcements` (for example a host `admin` or `messaging_operator`).
 ### Host controller recipe
 
 ```ruby
@@ -124,17 +124,21 @@ class Host::ThingsController < ApplicationController
 end
 ```
 
-Map host controllers to RBAC entities the same way engine controllers are mapped in the dummy host file.
+Map host controllers to **host-owned** RBAC entities in the host YAML. Grant CT-owned entity names to product roles; do not copy engine controller mappings.
 
 ## Engine admin HTTP
 
-Only:
-
 ```http
+GET  /admin/workspace
+GET  /admin/users
+GET  /admin/users/:id
+POST /admin/users/:id/impersonation-sessions
+GET  /admin/audit-events
 POST /admin/messaging/announcements
+DELETE /auth/impersonation-session
 ```
 
-No SchemaHelper admin user list, attribute modify, role assign, or impersonate routes. User administration is host/ops (`command_tower:users:create`, host tooling, etc.).
+Impersonation is a session overlay, not a User mutation and not an Admin Workspace tool. There is no role-assign or attribute-modify admin surface.
 
 ## Email verification gate
 

data/docs/authorization.md

@@ -2,7 +2,7 @@
 
 Authorization establishes **permission** after authentication. Failed authorization returns `403`.
 
-Host `rbac_groups.yml` is a **required integration step** (Step 4) — see [Host integration](host_integration_guide.md#step-4--host-rbac-required). Without it, authenticated Me/Auth calls fail closed.
+Host `rbac_groups.yml` is a **required integration step** (Step 4) — see [Host integration](host_integration_guide.md#step-4--host-rbac-required). CommandTower ships CT-owned entity definitions. Hosts grant those names to product roles; they must not copy CT controller mappings. Without a host role that grants Me/Auth entities, authenticated calls return **403**.
 
 ## Quick usage (host provisional)
 
@@ -14,20 +14,41 @@ before_action :authorize_user!
 
 Engine controllers use `authorize_request!` instead (AuthorizationBoundary) and return the application envelope on failure.
 
+## Capability ownership vs role composition
+
+**Platform owns capabilities.** CommandTower defines RBAC entities (Me/Auth surfaces and Admin capabilities such as `admin_workspace`, `admin_users`, `admin_impersonation`, `admin_audit_events`, `admin_messaging_announcements`).
+
+**Hosts own privilege bundles.** Operational/admin roles are host-defined groups that grant selected CT entities (and optional host entities). Installing CommandTower does **not** automatically grant operational Admin access.
+
 ## Roles and host mapping
 
 Engine defaults in `lib/command_tower/authorization/default.yml`:
 
-- `owner` — full access (`entities: true`)
-- `admin` — `admin_messaging_announcements` only
+- `owner` — explicit full access (`entities: true`). Distinct from host-defined operational Admin roles.
+- CT-owned **entities** for Me, session, profile, inbox, preferences, phone, Pushover, email verification, admin announcements, admin audit events, Admin Users, impersonation start, and the Admin Workspace manifest
+- **No** CommandTower operational `admin` role. New Admin entities require explicit host grants and must not accumulate into a platform Admin bundle.
+
+Hosts grant `admin_impersonation` explicitly. Dummy `admin` / `operations_admin` do **not** include it; `impersonation_operator` does. `owner` keeps `entities: true`.
+
+Stop / return-to-self (`DELETE /auth/impersonation-session`) is a session primitive: it authenticates the administrator JWT and does not authorize `admin_impersonation` on the effective (target) user.
+
+While overlaying, Admin resource endpoints other than `GET /admin/workspace` return **418** `admin_unavailable_during_impersonation`. Workspace remains allowed so the operator can see disabled tiles. Impersonation start consumes Admin Resource Scoping as the sole target-visibility contract.
+
+Hosts define product roles (for example `member`, `audit_operator`, or a deliberate host-owned `admin`) that **grant entity names**. See dummy host `rails_app/config/rbac_groups.yml`. Do not redefine `owner` or CT **entity** identifiers. A host may define a broad `admin` role as **host policy**; that is allowed. Composition is additive; conflicts fail at boot.
+
+Optional: `config.authorization.default_membership_role = "member"` assigns that composed role atomically on register.
+
+## Principal capabilities (FE projection)
 
-Hosts **must** map Me/Auth controller actions in host YAML (`CommandTower.config.authorization.rbac_group_path`, default `config/rbac_groups.yml`) or authorization fails closed. See dummy host `rails_app/config/rbac_groups.yml` (`member` entities).
+`GET /auth/principal-capabilities` returns possessed **frontend-projectable** ids from effective entity grants ∩ `config.registry.principal_capabilities`. Groups compose privilege; they are never the FE gating contract. See [Principal capabilities](principal_capabilities.md).
 
 ## Where to go next
 
 | Need | Guide |
 |------|-------|
 | Full RBAC entities, roles, failure shapes | [Authentication & authorization guide](authentication_authorization_guide.md) |
+| Frontend-projectable capability ids | [Principal capabilities](principal_capabilities.md) |
+| Admin Workspace least privilege | [Admin Workspace](admin_workspace.md) |
 | Authentication | [Authentication](authentication.md) |
 | Install / config | [Initializing](initializing.md) |
 

data/docs/controllers.md

@@ -8,11 +8,15 @@ This page is an **index** of route areas. Detailed request/response contracts li
 
 | Area | Prefix (engine-relative) | Purpose |
 |------|--------------------------|---------|
-| Auth session | `/auth/*` | Login, logout, session, register, signup-session, identity policy, availability |
+| Auth session | `/auth/*` | Login, logout, session, register, signup-session, identity policy, principal-capabilities, availability |
 | Email verification | `/auth/email-verification/*` | Send / verify email codes |
 | Password recovery | `/auth/password-recovery-session`, `/auth/password-reset/*` | Forgot / reset password |
 | Me / profile | `/me`, `/profile`, `/me/name`, `/me/password` | Account reads and updates |
 | Inbox | `/me/inbox*` | User inbox consume (list, open, archive, bulk ops) |
+| Audit events | `/me/audit-events`, `/admin/audit-events` | User and admin audit history reads (masked) |
+| Admin Users | `/admin/users` | Read-only Admin user list/show |
+| Impersonation | `/admin/users/:id/impersonation-sessions`, `/auth/impersonation-session` | Start overlay; stop / return-to-self |
+| Admin Workspace | `/admin/workspace` | RBAC-filtered admin tool manifest |
 | Preferences | `/me/preferences*` | Notification preferences |
 | Phone | `/me/phone*` | Phone endpoint + verification |
 | Pushover | `/me/pushover*` | Pushover endpoint lifecycle + verification |
@@ -27,6 +31,8 @@ Engine controllers are transport adapters: authenticate/authorize as required, d
 ## Related
 
 - [API reference](api_reference.md) — endpoint catalog
+- [Principal capabilities](principal_capabilities.md) — FE-projectable possession projection
+- [Admin Workspace](admin_workspace.md) — registry and manifest
 - [Messaging](messaging_integration_guide.md) — messaging surfaces summary
 - [Extending](extending.md) — host extension boundaries
 - [Initializing](initializing.md) — mount and configure

data/docs/eventing.md

@@ -0,0 +1,179 @@
+# Eventing
+
+CommandTower publishes internal events on **one** Rails-native network: `ActiveSupport::Notifications`. Hosts and platform code do not invent a second bus.
+
+Logging is a **consumer** of that network. CommandTower supplies structured Hash fields to `Rails.logger`. The host Rails logger/formatter/tagged/broadcast configuration owns the final representation. CommandTower does not JSON-encode log lines.
+
+**Event emission is exhaustive; log materialization is selective.** Lifecycle started/completed pairs always publish. **Workflow** completed success/deferred logs to Rails `info` by default (`ApplicationWorkflow` declares `log_lifecycle!`). **Service** completed success stays quiet unless the service class opts in. `started` never materializes. Envelope `log_lifecycle` means “success may be materialized,” not “emit only when true.” Subscribers must not `const_get(subject)`.
+
+Audit persistence is a **raising** subscriber on `command_tower.audit.*` (not on lifecycle, and not the logging subscriber). **Audit authoring** (`audit(...)`, registered policy, structured emission) is documented in [Audit](audit.md).
+
+## Grammar
+
+Instrument names are the subscription keys:
+
+```text
+command_tower.<category>.<name...>
+```
+
+- `command_tower` is the platform prefix. Hosts do **not** prepend it themselves.
+- `category` is one token: `\A[a-z][a-z0-9_]*\z`. Categories are **extensible**, not a closed enum.
+- `name` is one or more tokens of the same shape, joined by `.`.
+
+Do **not** publish a generic `command_tower.event` name and dispatch on `payload[:type]`.
+
+Do **not** use `ActiveSupport::Subscriber#attach_to` as the taxonomy driver. That convention is reversed `event.namespace` (for example `sql.active_record`). CommandTower names are `command_tower.<category>.<name...>`. Subscribe with the full string or a prefix regexp.
+
+### Lifecycle (automatic)
+
+| Instrument name |
+|-----------------|
+| `command_tower.lifecycle.workflow.started` |
+| `command_tower.lifecycle.workflow.completed` |
+| `command_tower.lifecycle.service.started` |
+| `command_tower.lifecycle.service.completed` |
+
+Every `ApplicationWorkflow` `.call` / `call_from_job` invocation and every `ServiceBase` Interactor invocation emits one started/completed pair. Nested workflow→service shares `execution_uuid` and emits four events (two pairs).
+
+### Semantic (deliberate)
+
+```text
+command_tower.<category>.<name...>
+```
+
+Example: `command_tower.audit.wager_transition` via **registered** `audit(:wager_transition, ...)` — see [Audit](audit.md). Generic scalar `publish_event` remains available for non-audit categories; nested audit `changes` require `audit(...)` / `Events.publish_audit`.
+
+```ruby
+publish_event(category: :messaging, name: :welcome_produce_failed, payload: { code: "x" })
+```
+
+`publish_event` is on `CommandTower::Execution::ContextAccess` (workflows and services inherit it). It delegates to `CommandTower::Events.publish`. Do not include a separate Eventing module.
+
+## Subscribe
+
+Rails 8.1 Fanout matches the **full instrument string**.
+
+Exact:
+
+```ruby
+ActiveSupport::Notifications.subscribe("command_tower.lifecycle.workflow.completed") { |*args| }
+```
+
+Broad (lifecycle category):
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\Acommand_tower\.lifecycle(?:\.|\z)/) { |*args| }
+```
+
+## Envelope
+
+Payload is a frozen Hash of scalars (and frozen arrays of scalars). Never `CommandTower::Current`, User, request, AuthContext, JWT, cookies, or exception objects.
+
+| Field | When |
+|-------|------|
+| `event_uuid` | every event (new UUID at publish; **not** `execution_uuid`) |
+| `subject` | class name string |
+| `layer` | `:workflow` / `:service` (lifecycle only) |
+| `execution_uuid`, `correlation_id`, `request_id`, `causation_id`, `source` | Execution Context snapshot |
+| `user_id`, `effective_user_id`, `originating_administrator_id`, `impersonation_active` | snapshot |
+| `outcome` | completed only: `:success` / `:deferred` / `:failure` / `:error` |
+| `duration_ms` | completed only (monotonic clock from matching started) |
+| `error_class`, `error_codes` | completed failure/error; codes only, no messages/PII |
+| caller keys | semantic publish only; unsafe objects are dropped |
+
+`event_uuid` ≠ `execution_uuid`. There is no parent/child event graph. Nested work shares `execution_uuid` only.
+
+The snapshot is taken at publish time and is frozen against later `Current` mutation.
+
+## Publisher
+
+```ruby
+CommandTower::Events.publish(category:, name:, payload: {}, subject: nil, layer: nil)
+CommandTower::Events.snapshot
+```
+
+`publish` builds the instrument name, merges snapshot + `event_uuid` + sanitized caller payload, then calls `ActiveSupport::Notifications.instrument` **without a block**. Business work is **not** yielded to `instrument`.
+
+## Subscriber failure (Rails-native)
+
+CommandTower uses ASN as a **synchronous** event network. `Events.publish` does **not** wrap `instrument` in `rescue StandardError`.
+
+> CommandTower preserves Rails-native synchronous `ActiveSupport::Notifications` publication semantics. Subscriber failure policy belongs to the subscriber/capability consuming the event. Best-effort consumers must protect their own failure boundary. Correctness-sensitive subscriber semantics are defined by the owning capability.
+
+The generic publisher does **not** impose either policy.
+
+| Consumer | Policy owner |
+|----------|----------------|
+| Logging subscriber | **This slice** — best-effort; rescues materialization failures |
+| Metrics subscriber | future (likely self-protecting) |
+| Audit subscriber | later phase (may be correctness-sensitive) |
+| Other semantic subscribers | owning capability |
+
+The logging subscriber (`CommandTower::Logging::Subscriber` < `ActiveSupport::LogSubscriber`) subscribes with prefix regexes (not `attach_to`) to:
+
+- `command_tower.lifecycle.*`
+- `command_tower.log.*`
+- `command_tower.messaging.*`
+
+It does **not** subscribe to `audit` or `metric`. It calls `Rails.logger` with a Hash. Host formatters decide text vs JSON vs tagged output.
+
+### Lifecycle Rails logs
+
+`ApplicationWorkflow` declares `log_lifecycle!`, so workflow **completed** success/deferred materializes at `info` by default. Services stay quiet unless they opt in. Use `disable_lifecycle_logging!` on a workflow subclass to suppress its completed success line.
+
+```ruby
+class NoisyService < ApplicationService
+  log_lifecycle!
+end
+
+class QuietWorkflow < ApplicationWorkflow
+  disable_lifecycle_logging!
+end
+```
+
+`lifecycle_loggable?` walks superclasses when unset. `log_lifecycle:` is passed into `Events.around_execution` as a **boolean scalar**. `started` is never materialized.
+
+### Severity and materialization
+
+| Event | Materialize? | Level when materialized |
+|-------|----------------|-------------------------|
+| lifecycle started | **no** (even with opt-in — completed has outcome/duration) | — |
+| lifecycle completed success / deferred | only if `payload[:log_lifecycle]` | `info` |
+| lifecycle completed failure | **always** | payload `log_level` or `:info` |
+| lifecycle completed error | **always** | `error` |
+| `command_tower.log.<level>` | **always** | that level |
+| `command_tower.messaging.*` | unchanged (3.3) | payload `log_level` or `:info` |
+
+Authorization (`Authorize::Validate`) success diagnostics (“No Authorization required”, “User Roles”, per-role Authorized/Reason) publish `command_tower.log.debug`. Denial publishes `command_tower.log.warn`.
+
+### Events are comprehensive. Logs are projections.
+
+ASN payloads remain full Execution Context snapshots (`event_uuid`, nils, `layer`, `log_lifecycle`, duplicate identity fields). The logging subscriber **projects** a new Hash for `Rails.logger`. It does not mutate the canonical payload and does not define the event contract.
+
+**Core log fields** (when present): `event`, `subject`, `execution_uuid`, `correlation_id`, lifecycle `outcome`, `duration_ms`.
+
+**Conditional:** `user_id` when present; `request_id` when present and different from `correlation_id`; `source` when not `:http`; `causation_id` / `originating_administrator_id` when present; `effective_user_id` when different from `user_id`; `impersonation_active` only when `true`; `error_class` / `error_codes` when present.
+
+**Omitted from ordinary logs:** nils; `event_uuid`; `layer`; `log_lifecycle`; payload `log_level` (Rails severity already carries level); default `impersonation_active: false`; HTTP `source`.
+
+Semantic events (`command_tower.messaging.*`, `command_tower.log.*`) keep the same common context plus remaining safe scalar fields (`message`, `channel`, `provider`, `attempt`, …). Host formatters still own JSON / tags / LGTM representation; CommandTower does not promise a Rails JSON schema.
+
+`ApplicationError#log_level` is copied onto completed failure events as a scalar.
+
+`log_debug` / `log_info` / `log_warn` / `log_error` publish `command_tower.log.*`. Messaging OperationLoggers publish `command_tower.messaging.*`. Delivery LogAdapters remain a **transport** (`Rails.logger.info` of a send), not observation.
+
+Direct `Rails.logger` remains allowed for JWT decode/authenticate, boot/lib/controllers, and LogAdapters. Workflows/services must not write lifecycle observation directly.
+
+A raising **logging** subscriber does not fail the business action. A raising **non-logging** test/audit subscriber still surfaces through `Events.publish`.
+
+Emission and consumption remain separate: logger silence / level skips **materialization**, never ASN publication.
+
+Architecture specs guard these seams: one `CommandTower::Current`, kernel-owned lifecycle, `Events.publish` as the ASN publisher, curated log projection, and an explicit `Rails.logger` allowlist in JWT/LogAdapter infrastructure.
+
+## Kernel behavior (when subscribers do not raise)
+
+- `ApplicationWorkflow.call`: unexpected `StandardError` still becomes InternalError **after** completed `outcome: :error`. `validate_retry_strategy!` stays outside instrumentation.
+- `call_from_job` / `invoke_for_job`: still **re-raise** after completed `outcome: :error`.
+- Services: Interactor success → `:success`; `Interactor::Failure` → `:failure` then re-raise; unexpected exception → `:error` then re-raise. Services have no deferred outcome.
+
+Do not wrap instance `#call` in addition to class entry (duplicate pairs). Do not also wrap `ApplicationService.call` (the Interactor `around` is the service pair).

data/docs/extending.md

@@ -17,7 +17,7 @@ Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor:
 | `Communications::Produce` / `ProduceMany` | Sending messaging |
 | `FactoryBot.modify` | Extend shared factories |
 | Model reopen | Product associations / behavior |
-| Initializers | Configuration |
+| Initializers | Configuration, including `config.registry.audit.event`, `config.registry.admin_workspace.tool`, and `config.registry.principal_capabilities.capability` |
 | Notification catalogs / channel policy | Host-owned messaging customization |
 
 ## Internal platform — do not extend
@@ -97,8 +97,39 @@ Do not create one Messaging workflow per message type. Do not call the messaging
 
 No DoubleFloor Me (or other product) source is required to use the platform.
 
+## Execution Context
+
+Greenfield hosts inherit CommandTower-owned execution-boundary bases so HTTP and jobs establish ambient context automatically:
+
+```ruby
+class ApplicationController < CommandTower::ApplicationController
+end
+
+class ApplicationJob < CommandTower::ApplicationJob
+end
+```
+
+`CommandTower::Current` is the single `CurrentAttributes` bag (`execution_uuid`, `correlation_id`, `request_id`, `source`, identity scalars). Workflows and services **read** it (`execution_context`); they do not mint a new execution per call.
+
+`CommandTower::Auth::RequestContext` remains the HTTP request/response JWT transport handle. It is not Execution Context.
+
+Rake/console (and other non-HTTP/job entry points) wrap work with:
+
+```ruby
+CommandTower.with_execution(source: :rake) do
+  # ...
+end
+```
+
+Nested `with_execution` shares the outer context. Do not wrap `db:migrate` or doctor.
+
+If a host **cannot** change `ApplicationController` / `ApplicationJob` superclasses, include `CommandTower::Execution::HttpBoundary` / `CommandTower::Execution::JobBoundary` as a compatibility escape hatch. Do not include those modules into every `ActionController` or `ActiveJob::Base`.
+
+Automatic workflow/service lifecycle notifications are emitted by CommandTower kernels. Logging is a subscriber: emission is exhaustive; materialization is selective; log records are curated projections. The host owns format. See [Eventing](eventing.md).
+
 ## Related
 
+- [Eventing](eventing.md)
 - [Architecture](architecture.md)
 - [Controllers](controllers.md)
 - [Sensitive changes](sensitive_routes.md)

data/docs/host_integration_guide.md

@@ -37,6 +37,24 @@ Re-run `bin/rails command_tower:doctor`. Details: [Initializing — Configuratio
 
 Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
 
+### Email / SMTP
+
+CommandTower owns ActionMailer delivery for engine mailers (email verification, password reset, messaging channel mail).
+
+| Environment | Delivery |
+|-------------|----------|
+| `test` | `:test` (in-memory `ActionMailer::Base.deliveries`; no external SMTP) |
+| development / production | `:smtp` unless the host explicitly sets `config.email.delivery_method` |
+
+Non-secret knobs live on `config.email.*` (defaults: `smtp.gmail.com`, port `587`, `plain`, STARTTLS auto). Secrets come from Credential Resolution:
+
+- `config.credentials.smtp.user_name` / `password`, or
+- ENV `GMAIL_USER_NAME` / `GMAIL_PASSWORD`
+
+`SmtpActionMailerBridge` merges resolved credentials into `action_mailer.smtp_settings` at the end of `CommandTower.configure`. Missing credentials fail at send when `raise_delivery_errors` is true. `From` uses the resolved SMTP username when present.
+
+Doctor does **not** probe SMTP connectivity.
+
 ## Step 3 — Confirm mount path
 
 Ensure routes include something like:
@@ -47,35 +65,108 @@ mount CommandTower::Engine => "/"   # or "/api"
 
 Engine paths below are **relative to that mount**. Route area index: [Controllers](controllers.md).
 
+## Step 3b — Inherit execution-boundary bases
+
+Greenfield hosts should inherit CommandTower bases so Execution Context is established automatically:
+
+```ruby
+class ApplicationController < CommandTower::ApplicationController
+end
+
+class ApplicationJob < CommandTower::ApplicationJob
+end
+```
+
+Unauthenticated host endpoints (for example health checks) still receive HTTP `execution_uuid` / `correlation_id`. Successful authentication enriches the **same** context with `user_id` / `effective_user_id`.
+
+Workflows and services consume `CommandTower::Current` (or `execution_context`); they do not establish a new execution. For Rake/console, use `CommandTower.with_execution(source: :rake) { ... }`.
+
+`Auth::RequestContext` is JWT request/response transport, not Execution Context. Details: [Extending — Execution Context](extending.md#execution-context).
+
+Lifecycle and semantic events: [Eventing](eventing.md).
+
+If superclass inheritance is technically blocked, include `CommandTower::Execution::HttpBoundary` / `JobBoundary` on the host bases. That is an escape hatch, not the preferred contract.
+
 ## Step 4 — Host RBAC (required)
 
-AuthorizeRequest **fails closed**. Without host entity mappings, authenticated calls to `/me`, `/auth/session`, inbox, etc. return **403**.
+AuthorizeRequest **fails closed**. CommandTower ships **CT-owned** entity definitions (Me, session, inbox, Admin Workspace capabilities, …) and the platform full-access role (`owner`) in `lib/command_tower/authorization/default.yml`. CommandTower does **not** ship an operational `admin` role.
+
+The host YAML (default `config/rbac_groups.yml`) is a **second source**. Composition is additive. Hosts:
+
+1. Define product roles (typically `member`).
+2. **Grant names** of already-defined CT entities to those roles.
+3. Optionally define **host-owned** entities for **host** controllers.
+4. Deliberately compose operational Admin roles (least privilege or a broad host-owned `admin`).
 
-The configure generator does **not** create this file.
+Do **not** copy CommandTower controller/entity blocks into the host file. Do **not** redefine `owner` or CT entity names. A host **may** define an `admin` group as host policy. Conflicts fail at boot (no last-write-wins).
 
-1. Copy and adapt the dummy host file: [`rails_app/config/rbac_groups.yml`](../rails_app/config/rbac_groups.yml) → host `config/rbac_groups.yml`.
-2. Keep a host group such as `member` with entities for session, me, profile, inbox, preferences, phone, pushover, email verification.
-3. Do **not** redefine engine groups that already exist in `default.yml` (`owner`, `admin`).
-4. Point config at the file if needed:
+Dummy host grants-only example: [`rails_app/config/rbac_groups.yml`](../rails_app/config/rbac_groups.yml).
 
 ```ruby
 CommandTower.configure do |c|
   c.authorization.rbac_group_path = Rails.root.join("config/rbac_groups.yml")
+  c.authorization.default_membership_role = "member" # optional; nil disables
 end
 ```
 
-(Default path is already `config/rbac_groups.yml`.)
+`default_membership_role` is validated against the **composed** graph at boot. Unknown names fail configuration finalization.
 
 More: [Authorization](authorization.md), [Authentication & authorization guide](authentication_authorization_guide.md).
 
+Product audit names (later) register additively:
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.audit.event :wager_placed do |event|
+    event.allowed_changes = %i[status]
+    event.user_history = true
+  end
+end
+```
+
+Do **not** redefine CommandTower-owned audit names. Audit rows persist in CommandTower after `command_tower:install:migrations` and `db:migrate`. See [Audit](audit.md).
+
+Admin Workspace tools register additively (navigation metadata, not a dispatcher):
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.admin_workspace.tool :host_example do |tool|
+    tool.label = "Example"
+    tool.description = "Short launcher explanation of what this tool does."
+    tool.route = "/admin/example"
+    tool.group = :product
+    tool.sort_order = 300
+    tool.required_entity = :host_example_entity
+  end
+end
+```
+
+Do **not** redefine CommandTower-owned tool ids (`users`, `audit`, `messaging`). Hosts own copy for host tools (`description` soft ≤100 / hard ≤160). Manifest: [Admin Workspace](admin_workspace.md).
+
+Principal capabilities register additively (frontend-projectable ids, not a dump of all entities):
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.principal_capabilities.capability :host_example do |capability|
+    capability.required_entity = :host_example_entity
+  end
+end
+```
+
+Do **not** redefine CommandTower-owned capability ids (`admin_workspace`, `admin_users`, `admin_impersonation`, `admin_audit_events`, `admin_messaging_announcements`). Projection: [Principal capabilities](principal_capabilities.md). Grant `admin_impersonation` only to roles that should start impersonation of visible users. Dummy `admin` does not include it.
+
 ## Step 5 — Roles on users
 
 RBAC YAML defines what a role **may** do. Users still need that role assigned.
 
-- Specs and the dummy pattern use role name **`member`** for Me/Auth surfaces.
-- Engine register does **not** automatically attach `member`. Hosts must assign roles via product logic, ops (`command_tower:users:create`), or host hooks after account creation.
-- Admin announcements need a role that includes `admin_messaging_announcements` (engine `admin` group, or an equivalent host mapping).
-
+- Specs and the dummy pattern use role name **`member`** for Me/Auth surfaces (including entity `principal_capabilities`).
+- When `authorization.default_membership_role` is set (for example `"member"`), register assigns that role **in the same transaction** as user create. Failure rolls back the user.
+- When it is `nil`, register does not attach roles. Hosts may assign via product logic, ops (`command_tower:users:create`), or other host workflows.
+- Installing CommandTower does **not** grant operational Admin access. Hosts must deliberately grant Admin entities.
+- Admin announcements need a host role that includes `admin_messaging_announcements`.
+- Admin Workspace manifest needs a host role that includes `admin_workspace`. Tool visibility still depends on each tool's `required_entity`.
+- `GET /auth/principal-capabilities` needs entity `principal_capabilities` on the caller’s roles (grant on `member` like session/me). Possessed Admin projectables still depend on the Admin entity grants above.
+- A host may define a broad `admin` role that grants many Admin entities — that is host policy, not a CommandTower default.
 ## Step 6 — Enable feature gates you need
 
 When a gate is off, the route is **not drawn** → **404**.
@@ -101,7 +192,7 @@ Engine HTTP success/error bodies use the application envelope `{ data, meta, err
 
 With gates and RBAC in place (paths relative to your mount):
 
-1. `POST /auth/register` (always drawn) — create a user, then **assign `member`** (Step 5) if not done by host logic.
+1. `POST /auth/register` (always drawn) — with `default_membership_role` configured, the user is created **and** assigned that role in one transaction.
 2. `POST /auth/plain-text/login` (if enabled) — receive `data.token`.
 3. `GET /me` with Bearer token — expect **200** and envelope `data` (account payload).
 

data/docs/initializing.md

@@ -21,8 +21,8 @@ bin/rails command_tower:doctor
 
 Continue with [Host integration](host_integration_guide.md):
 
-1. Host `rbac_groups.yml` (required — otherwise authenticated Me/Auth calls **403**)
-2. Assign host roles (for example `member`) on users
+1. Host `rbac_groups.yml` product role that **grants** CT-owned Me/Auth entity names (required — otherwise authenticated Me/Auth calls **403**)
+2. Set `authorization.default_membership_role` (for example `"member"`) or assign roles some other supported way
 3. Enable feature gates you need (login, reset, availability, …)
 4. Smoke-check `GET /me` with a Bearer token
 5. Wire messaging catalog/adapters when you emit or use phone/Pushover

data/docs/messaging_integration_guide.md

@@ -74,7 +74,7 @@ Pagination detail: [pagination.md](pagination.md). Full catalog: [api_reference.
 - Notification catalog content (registered into CommandTower notification types)
 - `platform_enabled_channels` / channel policy injection
 - Messaging adapter credentials (email / SMS / Pushover) via initializer or ENV
-- Host `rbac_groups.yml` entities for Me inbox/preferences/phone/pushover (and admin if used)
+- Host product roles that grant CT-owned Me inbox/preferences/phone/pushover entities (and `admin` if used)
 - Product-specific operational tooling (announce rake tasks, welcome copy)
 
 ## Related

data/docs/models.md

@@ -44,6 +44,10 @@ end
 
 Engine-owned messaging persistence (communications, endpoints, preferences, and related records) ships with CommandTower. Prefer platform services/workflows for mutations; do not dual-author schema in the host ([Initializing](initializing.md)).
 
+## Audit ledger
+
+`CommandTower::Audit::Event` is the append-only platform ledger (`command_tower_audit_events`). Only `CommandTower::Audit::Persistence::Subscriber` writes rows. There are no foreign keys to users. Envelope `changes` persist as `change_set`. See [Audit](audit.md).
+
 ## Related
 
 - [Architecture](architecture.md)

data/docs/pagination.md

@@ -1,6 +1,6 @@
 # Pagination
 
-CommandTower exposes one live HTTP list contract that returns pagination metadata: **Me Inbox**.
+CommandTower exposes live HTTP list contracts that return pagination metadata: **Me Inbox**, **audit event lists** (`GET /me/audit-events`, `GET /admin/audit-events`), and **Admin Users** (`GET /admin/users`). These lists reuse the Inbox `limit` / `offset` / `totalCount` contract.
 
 Back to [README](../README.md).
 
@@ -38,7 +38,7 @@ CommandTower.configure do |c|
 end
 ```
 
-There is no engine admin list endpoint and no `pagination=true` / `page` / `cursor` query API on current engine HTTP surfaces.
+There is no `pagination=true` / `page` / `cursor` query API on current engine HTTP surfaces. Admin audit list uses the same limit/offset contract as Inbox.
 
 ## Related