command_tower 0.10.0 → 0.11.0

data/docs/admin_workspace.md

@@ -0,0 +1,158 @@
+# Admin Workspace
+
+The Admin Workspace is CommandTower-owned **backend** navigation metadata: one configuration registry, boot-validated composition with host tools, and a RBAC-filtered runtime manifest. It does **not** proxy Audit or Messaging APIs. It does **not** ship a frontend shell (4.6.3+) or Audit Explorer UI (4.7). Do **not** use `GET /admin/workspace` as a generic UI permission probe — use [Principal capabilities](principal_capabilities.md) (`GET /auth/principal-capabilities`) for possessed projectable ids.
+
+## Register (configuration)
+
+Registration is configuration (`class_composer`), the same pattern as `config.registry.audit`. There is no `CommandTower::Admin.register` plugin API.
+
+CommandTower seeds platform tools. Hosts **add** tools. Hosts **cannot** redefine CommandTower-owned ids (`users`, `audit`, `messaging`). Duplicate ids and duplicate `route` values fail. There is no speculative `enabled` flag.
+
+```ruby
+CommandTower.configure do |config|
+  config.registry.admin_workspace.tool :pickem_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
+    tool.icon = "cube"
+  end
+end
+```
+
+Lookup: `CommandTower.config.registry.admin_workspace.fetch(:audit)`.
+
+| Field | Rules |
+|-------|--------|
+| id | DSL name; `/\A[a-z][a-z0-9_]*\z/`; public contract, not a controller class |
+| owner | `:command_tower` (seeded) or `:host` (default) |
+| label | required non-blank string |
+| description | optional plain-text launcher blurb; stripped; empty allowed; **hard max 160** characters (intentional exception vs unbounded `label` — free-form presentation prose). Soft authoring target ≤100. No HTML/Markdown. |
+| route | required frontend path `/\A\/admin(\/[a-z][a-z0-9_-]*)+\z/` (navigation metadata, not an engine API path) |
+| group | required segment token; **open** set |
+| sort_order | required Integer |
+| required_entity | required RBAC entity name; must exist in the composed graph after `Authorization.default_defined!` |
+| icon | optional segment token or nil |
+
+| `scope_required` | optional Boolean (default false); when true, tool APIs require host scope transport |
+| `scope_parameter` | required when `scope_required`; query param key (e.g. `partition`) |
+| `scope_label` | required when `scope_required`; presentation label for FE selector (e.g. `"Partition"`) |
+
+Validate at `validate_definition!`: when `scope_required`, require non-empty `scope_parameter` + `scope_label`.
+
+Hosts configure scope behavior on `CommandTower.config.admin_scope` (see [Resource scoping](#resource-scoping)). CT-owned tools may be extended via `configure_tool(:users)` / `configure_tool(:audit)` in host boot — do not redefine tool ids.
+
+## Resource scoping
+
+Optional **host-defined resource scoping** narrows Admin tool data (Users, Audit, …) after RBAC. CommandTower remains **domain-blind** — it does not know League, Season, or tenant semantics.
+
+```ruby
+CommandTower.configure do |config|
+  config.registry.admin_workspace.configure_tool(:users) do |tool|
+    tool.scope_required = true
+    tool.scope_parameter = "partition"
+    tool.scope_label = "Partition"
+  end
+
+  config.admin_scope.register(:users) do |registration|
+    registration.options = ->(principal:) { [CommandTower::AdminScope::ScopeOption.new(value: "a", label: "A")] }
+    registration.validate = ->(value:, principal:) { true }
+    registration.availability = ->(principal:) { { enabled: true, reason: nil } }
+    registration.narrow_users = ->(relation:, scope_value:, principal:, tool_id:) { relation }
+    registration.narrow_audit = ->(relation:, scope_value:, principal:, tool_id:) { relation }
+    registration.affected_users_in_scope = ->(scope_value:, principal:, tool_id:) { [] }
+  end
+end
+```
+
+| Hook | Purpose |
+|------|---------|
+| `options` | Eager scope choices for manifest (`scopeOptions`) |
+| `availability` | `{ enabled:, reason: }` — disabled tools render non-navigable in FE |
+| `validate` | Authorize requested scope value; fail closed → **403** |
+| `narrow_users` | SQL narrowing for Users list/show |
+| `narrow_audit` | SQL narrowing for host-scoped audit rows |
+| `affected_users_in_scope` | User ids for eligible **global** audit events in scoped admin views |
+
+**HTTP disclosure policy:** missing/malformed/unauthorized scope → **403**; authorized scope + resource absent from narrowed relation (nonexistent **or** out of scope) → **404** (indistinguishable).
+
+Unscoped tools (`scope_required: false`, default) behave exactly as before — no scope query param, no `admin_scope` registration required.
+
+Synthetic proof lives in `rails_app` (`FoundationProof::AdminScope`); Pick'em League adoption is Phase 7 only.
+
+## Seeded CommandTower tools
+
+These routes are **frontend navigation targets**. Shared Admin shell consumes them; capability APIs remain independently authorized.
+
+| id | label | description | route | group | sort_order | required_entity | icon |
+|----|-------|-------------|-------|-------|------------|-----------------|------|
+| `users` | Users | Find and inspect platform user accounts. | `/admin/users` | `operations` | 50 | `admin_users` | `users` |
+| `audit` | Audit | Browse account and administrative audit history. | `/admin/audit` | `operations` | 100 | `admin_audit_events` | `history` |
+| `messaging` | Messaging | Manage platform announcements and administrative messaging. | `/admin/messaging` | `messaging` | 200 | `admin_messaging_announcements` | `megaphone` |
+
+RBAC CRUD, health, and Pick'em product tools are **not** seeded. Impersonation is a session primitive (`POST /admin/users/:id/impersonation-sessions`), not an Admin Workspace tool.
+
+## Boot validation
+
+1. Host `CommandTower.configure` registers tools (mutable).
+2. `after_initialize` — `audit.finalize!`, `admin_workspace.finalize!`, and `principal_capabilities.finalize!`, then freeze config (skipped in test). Stage 1 checks ids, ownership, and typed fields.
+3. `to_prepare` — `Authorization.default_defined!`, then `admin_workspace.validate_required_entities!` and `principal_capabilities.validate_required_entities!`. Stage 2 requires every `required_entity` to exist in `Entity.entities`. RBAC is not available at `after_initialize`.
+
+The same db/install/doctor rake skip paths as audit apply.
+
+## Runtime HTTP
+
+`GET /admin/workspace` (engine-relative; hosts that mount at `/api` use `GET /api/admin/workspace`).
+
+- Authn + authz: entity `admin_workspace` (`WorkspaceController#show`). Hosts must **explicitly grant** that entity to operational roles. `owner` already has `entities: true`. Members without the entity receive **403**.
+- One controller action → `Workflows::Admin::Workspace::ManifestWorkflow` (`retry_strategy :none`) → `Services::Admin::Workspace::Manifest` → `ManifestSerializer`.
+- Include a tool when any of `user.roles` has `Role#allow_everything` **or** includes an entity whose name equals `required_entity`. Do not filter with `role == "admin"`.
+- Host tools appear for `owner` and for **host-owned roles** that grant the host entity. Operational Admin roles are host policy; CommandTower does not ship an accumulating `admin` role.
+- Order: `group` → `sort_order` → `id`.
+- Envelope `data` (no pagination `meta`): `{ tools: [{ id, label, description, route, group, sortOrder, icon, scope?, scopeOptions?, availability? }] }`. Omit `owner`, `required_entity`, and Ruby classes. `icon` may be `null`. `description` is presentation metadata only and does not affect authorization.
+
+When `scope.required` is true, manifest also includes:
+
+| Field | Shape |
+|-------|--------|
+| `scope` | `{ required, parameter, label }` |
+| `scopeOptions` | `[{ value, label }]` when `availability.enabled` |
+| `availability` | `{ enabled, reason }` — `reason` when disabled |
+
+Scope options are **eager** per principal on manifest fetch (no lazy scope endpoint in 5.4).
+
+Capability APIs (`GET /admin/users`, `GET /admin/audit-events`, `POST /admin/messaging/announcements`) remain independently authorized. There is no generic `POST /admin/tools/:id/run`.
+
+While an impersonation overlay is active, `GET /admin/workspace` remains allowed and **disables every projected tool** (`availability.enabled: false`, reason `Admin tools are unavailable while impersonating a user.`). All other `/admin/*` endpoints return **418** `admin_unavailable_during_impersonation`.
+
+## Least privilege
+
+CommandTower owns the Admin **entities**. Hosts compose roles such as:
+
+```yaml
+audit_operator:
+  entities:
+    - admin_workspace
+    - admin_audit_events
+
+messaging_operator:
+  entities:
+    - admin_workspace
+    - admin_messaging_announcements
+```
+
+A host may deliberately define a broad `admin` role that grants many Admin entities — that is host policy, not a CommandTower default. Tool visibility follows granted entities, never role names.
+
+## `/me` vs the manifest vs principal capabilities
+
+`GET /me` remains account self-service flags, `roles`, and existing capabilities. Admin tool **discovery** is **`GET /admin/workspace` only**. Frontend-safe **possession** of projectable Admin (and host) capabilities is **`GET /auth/principal-capabilities`**. Do not copy the tool list onto `/me`, and do not treat the workspace manifest as a permission probe.
+
+## Related
+
+- [API reference](api_reference.md#admin-workspace)
+- [Principal capabilities](principal_capabilities.md)
+- [Authorization](authorization.md)
+- [Audit](audit.md)
+- [Messaging](messaging_integration_guide.md)

data/docs/api_reference.md

@@ -15,13 +15,16 @@ Proof for contracts lives primarily under `spec/requests/command_tower/`.
 3. [Auth endpoints](#auth-endpoints)
 4. [Me and profile](#me-and-profile)
 5. [Me Inbox](#me-inbox)
-6. [Preferences](#preferences)
-7. [Phone](#phone)
-8. [Pushover](#pushover)
-9. [Admin messaging](#admin-messaging)
-10. [Non-HTTP emit APIs](#non-http-emit-apis)
-11. [RBAC overview](#rbac-overview)
-12. [Feature gates](#feature-gates)
+6. [Audit events](#audit-events)
+7. [Preferences](#preferences)
+8. [Phone](#phone)
+9. [Pushover](#pushover)
+10. [Admin Workspace](#admin-workspace)
+11. [Impersonation](#impersonation)
+12. [Admin messaging](#admin-messaging)
+13. [Non-HTTP emit APIs](#non-http-emit-apis)
+14. [RBAC overview](#rbac-overview)
+15. [Feature gates](#feature-gates)
 
 ---
 
@@ -128,10 +131,37 @@ Default JWT TTL is **7 days** (`config.jwt.ttl`).
 | | |
 |--|--|
 | **Auth** | `authenticate_request!` + `authorize_request!` |
-| **Success** | **200** — `data`: `{ user, tokenExpiresAt }` |
+| **Success** | **200** — `data`: `{ user, tokenExpiresAt, impersonation? }` |
 | **Errors** | `401`; `403`; `412` `email_verification_required` when email verification gate applies |
 | **Spec** | `spec/requests/command_tower/auth/session_spec.rb` |
 
+`user` is the **effective** principal (target while overlaying). When an impersonation overlay is active, `impersonation` is present:
+
+```json
+{
+  "active": true,
+  "sessionId": "…",
+  "actorUserId": 1,
+  "actorDisplayName": "Ada Admin",
+  "targetUserId": 42,
+  "idleExpiresAt": "…",
+  "absoluteExpiresAt": "…"
+}
+```
+
+Omit `impersonation` when not overlaying. Clocks are ISO timestamps from the session row. Successful idle refresh may also echo `{ impersonation: { idleExpiresAt, absoluteExpiresAt } }` on that 2xx envelope **meta** only (not on generic success).
+
+### `DELETE /auth/impersonation-session`
+
+| | |
+|--|--|
+| **Auth** | `authenticate_request!` (overlay capture: expired overlays still authenticate the administrator) |
+| **Success** | **200** — `data`: `{ message: "impersonation_ended" }`; `set_token` re-issues the administrator JWT **without** `impersonation_session_id` |
+| **Errors** | `401`; `422` `impersonation_session_missing` |
+| **Spec** | `spec/requests/command_tower/auth/impersonation_session_spec.rb` |
+
+Does **not** authorize `admin_impersonation` on the effective user. Shared frontend persists `X-Authorization-Reset` on native 2xx responses.
+
 ### `POST /auth/signup-session`
 
 | | |
@@ -150,6 +180,17 @@ Default JWT TTL is **7 days** (`config.jwt.ttl`).
 | **Success** | **200** — `data`: password / email / username / verificationCode / phoneVerificationCode policy objects (`minLength`, `maxLength`, `pattern`, …) |
 | **Spec** | `spec/requests/command_tower/auth/identity_policy_spec.rb` |
 
+### `GET /auth/principal-capabilities`
+
+| | |
+|--|--|
+| **Auth** | authenticate + authorize (RBAC entity `principal_capabilities`) |
+| **Success** | **200** — `data`: `{ principalCapabilities: string[] }` (unique, sorted, possessed projectable ids only) |
+| **Errors** | `401`; `403`; `412` `email_verification_required` when email verification gate applies |
+| **Spec** | `spec/requests/command_tower/auth/principal_capabilities_spec.rb` |
+
+Projection is effective entity grants ∩ curated `config.registry.principal_capabilities` (never role/group names). CommandTower seeds `admin_workspace`, `admin_users`, `admin_users_update`, `admin_rbac_assignments`, `admin_audit_events`, `admin_messaging_announcements`, `admin_impersonation`, `me_audit_events`. Hosts may register additive host-owned ids. Distinct from `/me` capabilities and from `GET /admin/workspace` (tool manifest). See [Principal capabilities](principal_capabilities.md).
+
 ### `GET /auth/email/availability`
 
 | | |
@@ -290,7 +331,7 @@ Rotates `verifier_token` (invalidates outstanding sessions). See [change_passwor
 
 ## Me Inbox
 
-All inbox routes: authenticate + authorize. Host must map RBAC entities for inbox controller actions (see dummy host `rails_app/config/rbac_groups.yml`).
+All inbox routes: authenticate + authorize. Host product roles must **grant** the CT-owned `me_inbox` entity (see dummy host `rails_app/config/rbac_groups.yml`).
 
 Pagination for list: query `limit` (default **50**, max **100**), `offset` (default **0**), `scope` (`inbox` \| `archived`, default `inbox`). List `meta`: `{ limit, offset, totalCount }`. See [pagination.md](pagination.md).
 
@@ -316,6 +357,25 @@ Pagination for list: query `limit` (default **50**, max **100**), `offset` (defa
 
 ---
 
+## Audit events
+
+Authenticate + authorize. Host `member` grants CT-owned `me_audit_events`. Engine `admin` grants `admin_audit_events`. Pagination matches Inbox: `limit` (default **50**, max **100**), `offset` (default **0**); list `meta`: `{ limit, offset, totalCount }`. See [pagination.md](pagination.md) and [audit.md](audit.md#reading-audit-history).
+
+Sensitive `changes` from/to are **backend-masked** for both surfaces. Metadata is not masked. The Me controller does not accept a target-user id.
+
+| Method | Path | Notes |
+|--------|------|--------|
+| `GET` | `/me/audit-events` | Caller's `user_history` rows only; optional `eventName`, `occurredAfter`, `occurredBefore`, `subjectType` |
+| `GET` | `/me/audit-events/:id` | Same Me scope; **404** out of scope |
+| `GET` | `/admin/audit-events` | Full ledger (unscoped) or scoped composite when scope param present; plus admin filters |
+| `GET` | `/admin/audit-events/:id` | Full ledger by id; **404** missing or out of scope |
+
+Scoped admin audit: host-scoped rows (`scope_class: host`) matching host context **OR** eligible global rows (`scope_class: global` + registry `global_visible_in_host_scope`) for in-scope affected users. **Legacy** rows excluded. Missing/malformed/unauthorized scope → **403**.
+
+**Specs:** `spec/requests/command_tower/me/audit_events_spec.rb`, `admin/audit/events_spec.rb`, `admin/scoping/audit_events_spec.rb`.
+
+---
+
 ## Preferences
 
 | | Show | Update |
@@ -366,6 +426,104 @@ Errors include `422` (`pushover_already_configured`, `pushover_not_configured`,
 
 ---
 
+## Admin Workspace
+
+### `GET /admin/workspace`
+
+| | |
+|--|--|
+| **Auth** | authenticate + authorize (RBAC entity `admin_workspace`) |
+| **Success** | **200** |
+| **Spec** | `spec/requests/command_tower/admin/workspace_spec.rb` |
+
+No query parameters. Envelope `data` (no pagination `meta`):
+
+```json
+{
+  "tools": [
+    {
+      "id": "audit",
+      "label": "Audit",
+      "description": "Browse account and administrative audit history.",
+      "route": "/admin/audit",
+      "group": "operations",
+      "sortOrder": 100,
+      "icon": "history",
+      "scope": { "required": true, "parameter": "partition", "label": "Partition" },
+      "scopeOptions": [{ "value": "scope-a", "label": "Scope A" }],
+      "availability": { "enabled": true, "reason": null }
+    }
+  ]
+}
+```
+
+Unscoped hosts omit `scope`, `scopeOptions`, and `availability`.
+
+Tools are filtered from the composed RBAC grant graph (`allow_everything` or an entity matching the tool's `required_entity`). `description` is additive presentation metadata (soft authoring ≤100 chars; registry hard max 160). CommandTower seeds `users`, `audit`, and `messaging`. Hosts add tools via `config.registry.admin_workspace.tool`. There is no generic tool execution route. `/me` does not duplicate this list. Do not use this endpoint as a UI permission probe — use [Principal capabilities](principal_capabilities.md).
+
+Registration and boot rules: [Admin Workspace](admin_workspace.md).
+
+### Admin Users
+
+Authenticate + authorize. Host grants CT-owned `admin_users` for list/show. Identity mutations require `admin_users_update` (do not fold writes into `admin_users`). Role assignment requires `admin_rbac_assignments`. Pagination matches Inbox/Audit: `limit` (default **50**, max **100**), `offset` (default **0**); list `meta`: `{ limit, offset, totalCount }`. Free-text `search` filters email / username / first_name / last_name server-side. Safe JSON allowlist only (never password digests / verifier tokens). **No** semantic `audit(...)` on list/show (read-only inspection). Mutations emit workflow-owned `admin_direct` events. See [pagination.md](pagination.md).
+
+When the tool declares `scope_required`, pass the configured scope query param (e.g. `partition=scope-a`). Missing/malformed/unauthorized scope → **403**. Authorized scope + user absent from narrowed relation → **404** (same as nonexistent id).
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/admin/users` | Optional `search`; optional scope param when tool is scoped; ordered by `id` DESC |
+| `GET` | `/admin/users/:id` | **404** when missing or out of scope |
+| `PATCH` | `/admin/users/:id/name` | `{ firstName, lastName }` — both required |
+| `PATCH` | `/admin/users/:id/username` | `{ username }` |
+| `PATCH` | `/admin/users/:id/email` | `{ email }`; clears `emailValidated` when the address changes |
+| `PATCH` | `/admin/users/:id/email-validation` | `{ emailValidated: boolean }` — does not change email |
+| `GET` | `/admin/users/assignable-roles` | Host-sourced assignable catalog (excludes `owner`) |
+| `PATCH` | `/admin/users/:id/roles` | `{ roles: string[] }` — replaces assignable roles; preserves `owner` |
+
+Success **200** `{ data, meta, errors }` where mutation `data` is the same User schema as Show. Catalog `data` is `{ roles: [{ name, description }] }`. Validation **422** `data: null`. Missing `admin_users_update` or `admin_rbac_assignments` **403**. Impersonation overlay **418**.
+
+**Specs:** `spec/requests/command_tower/admin/users_spec.rb`, `spec/requests/command_tower/admin/users/identities_spec.rb`, `spec/requests/command_tower/admin/users/roles_spec.rb`, `spec/requests/command_tower/admin/scoping/users_spec.rb`.
+
+Impersonation start is a separate session primitive (below), not a User mutation.
+
+---
+
+## Impersonation
+
+Impersonation is a **server-authoritative session overlay** on the administrator JWT. `user_id` in the JWT is always the actor. Optional claim `impersonation_session_id` locates `command_tower_impersonation_sessions`. Expiration is row-authoritative (idle + absolute). HTTP activity alone does **not** refresh idle.
+
+`config.impersonation.idle_timeout` default **10 minutes**; `absolute_timeout` default **1 hour**; idle must be less than absolute.
+
+Qualifying workflows declare activity:
+
+```ruby
+class SomeWorkflow < ApplicationWorkflow
+  retry_strategy :none
+  impersonation_activity!
+end
+```
+
+Successful `WorkflowResult` sets a request flag; `HttpBoundary` records one idle refresh after a 2xx response. Do not declare on AuthenticateRequest, Session show, principal-capabilities, workspace manifest, or Logout. 5.5 exemplars: `Profile::ShowWorkflow` (GET, yes), `Me::UpdateNameWorkflow` (PATCH, yes), `Messaging::Preferences::UpdateWorkflow` (PATCH, no).
+
+Web cookie vs native Bearer: start/stop use `response_effects[:set_token]` (`X-Authorization-Reset` + body-adjacent header; cookie when enabled).
+
+### `POST /admin/users/:id/impersonation-sessions`
+
+| | |
+|--|--|
+| **Auth** | authenticate + authorize (`admin_impersonation`) |
+| **Success** | **201** — `data`: `{ id, actorUserId, targetUserId, idleExpiresAt, absoluteExpiresAt }` |
+| **Errors** | `401`; `403` (RBAC); `404` (missing / out of Users scope); `418` (overlay active); `422` self-target |
+| **Spec** | `spec/requests/command_tower/admin/users/impersonation_sessions_spec.rb` |
+
+Target lookup reuses `Services::Admin::Users::Show` with the same scope query param as Users show. Concurrent sessions are allowed. Nested start while an overlay is active is rejected at the Admin prohibition boundary (**418** `admin_unavailable_during_impersonation`); `StartWorkflow` still maps nested start to **403** `nested_impersonation_forbidden` if reached.
+
+Admin resource endpoints other than `GET /admin/workspace` return **418** while overlaying. Workspace remains allowed and disables every tool via `availability`.
+
+Expired product request: overlay present + invalid row → **401** `impersonation_session_expired` **without** clearing the auth cookie. Client may `DELETE /auth/impersonation-session` to return to self.
+
+---
+
 ## Admin messaging
 
 ### `POST /admin/messaging/announcements`
@@ -382,7 +540,7 @@ Errors include `422` (`pushover_already_configured`, `pushover_not_configured`,
 
 **Sync response:** `mode`, `requested`, `campaignIdentity`, `accepted`, `failed`, `skipped`, `failures: [{ userId, errorCode }]`.
 
-Engine admin HTTP is **announcements only**. There is no `/admin` user list, modify, role assign, or impersonate surface.
+Engine admin HTTP includes workspace manifest, announcements, audit events, Users list/show, and impersonation start. There is no role-assign or User-mutation admin surface.
 
 ---
 
@@ -403,10 +561,11 @@ Details: [messaging_integration_guide.md](messaging_integration_guide.md).
 
 Engine defaults (`lib/command_tower/authorization/default.yml`):
 
-- Group `owner` — all entities
-- Group `admin` — entity `admin_messaging_announcements` on `AnnouncementsController#create`
+- Group `owner` — all entities (`entities: true`)
+- CT-owned Admin **entities** `admin_workspace`, `admin_users`, `admin_messaging_announcements`, `admin_audit_events` (and Me/Auth entities)
+- **No** CommandTower operational `admin` role — hosts grant Admin entities deliberately
 
-Hosts **must** supply `rbac_groups.yml` entities for Me / Auth / session surfaces (fail-closed). The dummy host file `rails_app/config/rbac_groups.yml` shows a `member` mapping pattern.
+Hosts **must** supply `rbac_groups.yml` **product roles** that grant CT-owned Me / Auth / session entity names (fail-closed). Operational Admin roles are host-owned (least privilege or a deliberate broad host `admin`). The dummy host file `rails_app/config/rbac_groups.yml` shows grants-only `member` plus operator examples. Do not copy CT controller/entity definitions into the host file.
 
 Configure via `CommandTower.configure { |c| c.authorization.rbac_group_path = ... }`. Deep guide: [authentication_authorization_guide.md](authentication_authorization_guide.md). Quick start: [authorization.md](authorization.md).
 
@@ -424,7 +583,7 @@ When a gate is off, the route is **not drawn** → **404**.
 | Email verification send/verify | `login.plain_text.email_verify?` |
 | Password reset send/validate/reset | `login.plain_text.password_reset?` |
 
-Always drawn (not route-gated): register, logout, session, signup-session, identity-policy, password-recovery-session, Me/profile/inbox/preferences/phone/pushover, admin announcements. Phone/Pushover use **503** capability errors when product adapters are unavailable.
+Always drawn (not route-gated): register, logout, session, signup-session, identity-policy, principal-capabilities, password-recovery-session, Me/profile/inbox/audit-events/preferences/phone/pushover, admin workspace, admin announcements, admin audit-events. Phone/Pushover use **503** capability errors when product adapters are unavailable.
 
 ---
 
@@ -435,4 +594,6 @@ Always drawn (not route-gated): register, logout, session, signup-session, ident
 - [Sensitive changes](sensitive_routes.md)
 - [Pagination](pagination.md)
 - [Messaging](messaging_integration_guide.md)
+- [Admin Workspace](admin_workspace.md)
+- [Principal capabilities](principal_capabilities.md)
 - [README](../README.md)

data/docs/architecture.md

@@ -26,5 +26,10 @@ Controller / Job → Workflow → Shared Sequences / Services → Models & Clien
 - Service capability base: [ServiceBase README](../app/services/command_tower/README.md)
 - Install and host ownership: [Initializing](initializing.md)
 - Host extension boundaries: [Extending](extending.md)
+- Eventing: [Eventing](eventing.md)
+- Audit authoring and durable ledger: [Audit](audit.md)
+- Admin Workspace registry and manifest: [Admin Workspace](admin_workspace.md)
+
+Architecture specs under `spec/architecture/` guard Execution Context, canonical ASN publication, kernel-owned lifecycle, logging projection, and approved `Rails.logger` exceptions.
 
 Back to [README](../README.md).

data/docs/audit.md

@@ -0,0 +1,195 @@
+# Audit (authoring contract)
+
+Explicit semantic audit is a first-class CommandTower capability on workflows and services. It is **not** inferred from lifecycle completion, ActiveRecord dirty tracking, routes, or model callbacks.
+
+A workflow or service may emit **zero, one, or many** audit facts. **Workflows are the preferred publication boundary.** Ownership follows the **semantic fact**, not whichever layer executes SQL. Do not emit the same fact from both a workflow and a service.
+
+Registered `command_tower.audit.*` facts persist into **one** CommandTower ledger (`command_tower_audit_events` / `CommandTower::Audit::Event`) through a **synchronous, raising** subscriber.
+
+**Audit persistence is transaction-aware, not transaction-requiring.** `audit(...)` does not create or require a business transaction. If an ActiveRecord transaction is already active, the INSERT joins it and shares commit/rollback. If none is active, the fact persists as a standalone synchronous write. Persistence failure raises: inside a transaction that can roll back the surrounding operation; outside one, only the audit write fails loudly.
+
+Use a transaction when the **business operation itself** requires atomicity. Emit `audit(...)` while that transaction is active when the audit fact must share the operation’s commit/rollback boundary. Otherwise `audit(...)` may persist without an enclosing transaction. An auditable workflow is not automatically a transactional workflow.
+
+Mutation-coupled facts (`role_assigned`, `password_changed`, `phone_verified`) commonly belong inside the mutation’s transaction. Standalone facts (`session_created`, `login_failed`, `session_cleared`, `announcement_produced`, `impersonation_started`, `impersonation_ended`) need not.
+
+Logging remains a separate consumer. Hosts do not install their own audit subscriber; the engine attaches `CommandTower::Audit::Persistence::Subscriber` on boot. Sparse hosts get the table by running `command_tower:install:migrations` then `db:migrate`.
+
+Rows are **append-only**. Application code must not `update` or `destroy` ledger rows. Workflows and services must not `Audit::Event.create!`; only the persistence subscriber writes.
+
+Production publishers for the catalog below **are shipped**. Query APIs read `CommandTower::Audit::Event` through List + Project services; the raw row is not the HTTP contract. Admin Workspace **backend** manifest is shipped (`GET /admin/workspace`). Shared Audit Explorer UI is shipped. Filter-options projection is shipped.
+
+Lifecycle vs audit vs logs: [Eventing](eventing.md).
+
+## Register (configuration)
+
+Registration is configuration (`class_composer`). There is no plugin `register(...)` API. CommandTower and hosts share **one** registry and **one** `command_tower.audit.*` namespace.
+
+CommandTower-owned names are seeded by the engine. Hosts **add** names. Hosts **cannot** redefine CommandTower-owned definitions (boot/runtime fail-fast).
+
+```ruby
+CommandTower.configure do |config|
+  config.registry.audit.event :wager_placed do |event|
+    event.enabled = true
+    event.user_history = true
+    event.label = "Wager placed"
+    event.tags = %w[pickem wager]
+    event.sensitive_fields = []
+    event.allowed_changes = %i[status]
+    event.retention = :permanent # :permanent | :ninety_days | :one_year
+    event.subject_required = true
+    event.affected_user_required = true
+  end
+end
+```
+
+**Policy (registration) owns:** `enabled`, `enablement_configurable`, `user_history`, `label`, `tags`, `sensitive_fields`, `allowed_changes`, `retention`, subject/affected-user required flags, **`global_visible_in_host_scope`** (default false).
+
+**Discovery tags** (`tags`) are presentation metadata used by consumers such as Audit Explorer to help operators find event types in filter-option selectors. Tags are normalized (lowercase, stripped, unique, deterministic). They do **not** affect authorization, event publication, ledger persistence, or server-side audit filtering — there is no `?tag=` ledger filter and tags are not stored on audit rows.
+
+**Runtime `audit(...)` owns:** occurrence name, subject, affected user, `changes`, `metadata`, explicit `attribution_mode` when required, optional **`host_context:`** (`{ type:, identifier: }`), optional **`scope_class:`** (`global` \| `host` \| `legacy`).
+
+Lookup: `CommandTower.config.registry.audit.fetch(:wager_placed)`.
+
+Filter-option projection (scoped catalogs for Explorer):
+
+```text
+GET /me/audit-events/filter-options
+GET /admin/audit-events/filter-options
+```
+
+Projects `{ eventNames: [{ value, label, tags }], subjectTypes: [{ value, label }], attributionModes: […] }` from the live registry. Me includes only `user_history` events and omits attribution modes. `subjectTypes` are unique sorted registry `subject_type` values (blank omitted). Options are not authorization.
+
+CommandTower registration defines both the canonical contract **and** whether publication enablement may be configured. Core facts are mandatory (`enablement_configurable: false`). Hosts cannot disable them. Selected noisy facts (`session_created`, `session_cleared`, `login_failed`) are enablement-configurable. Hosts may change **only** `enabled` via `CommandTower.config.registry.audit.set_enabled!(:login_failed, true)` before `finalize!`. Hosts still cannot `event :session_created`.
+
+```ruby
+CommandTower.config.registry.audit.set_enabled!(:session_created, false)
+CommandTower.config.registry.audit.set_enabled!(:login_failed, true)
+```
+
+## Catalog (CommandTower-owned)
+
+| Event | Default enabled | Enablement configurable |
+|-------|----------------:|------------------------:|
+| `user_registered` | yes | no |
+| `role_assigned` | yes | no |
+| `password_changed` | yes | no |
+| `email_verified` | yes | no |
+| `phone_updated` | yes | no |
+| `phone_cleared` | yes | no |
+| `phone_verified` | yes | no |
+| `announcement_produced` | yes | no |
+| `impersonation_started` | yes | no |
+| `impersonation_ended` | yes | no |
+| `session_created` | yes | yes |
+| `session_cleared` | no | yes |
+| `login_failed` | no | yes |
+
+Sensitive-field / user-history / retention stay on the **registry** for emit-time policy. At INSERT the persistence subscriber copies the **smallest historical snapshot**: `user_history`, `sensitive_fields`, and `retention`. Later registry changes must not unmask historical PII. Read APIs treat a change key as sensitive if it is in the **union** of the row snapshot and the current definition (current may be more restrictive; it cannot unmask). Account-history eligibility is **only** the snapshot `user_history` column. The snapshot does not include `enabled`, `allowed_changes`, or owner. There is no `visibility` column. Retention is stored and **not enforced** as a delete/filter yet.
+
+Invalid names, duplicates, host overrides, and illegal policy (for example sensitive fields not in `allowed_changes`) raise `CommandTower::Audit::*` errors.
+
+## `audit(...)`
+
+Available via `CommandTower::Execution::ContextAccess` on `ApplicationWorkflow` and `ServiceBase`:
+
+```ruby
+audit(
+  :user_email_changed,
+  subject: user,
+  affected_user: user,
+  changes: { email: { from: old_email, to: new_email } },
+  metadata: { reason: "user_request" },
+  attribution_mode: nil,
+  subject_label: nil
+)
+```
+
+Callers do **not** build ASN strings and do **not** `Audit::Event.create!`.
+
+Instrument name: `command_tower.audit.<registered_name>`.
+
+### Changes
+
+Shape: `{ attribute: { from:, to: } }`. Empty `changes: {}` is valid (for example `password_changed`). Keys must be ⊆ registered `allowed_changes`. Extra keys **raise**; they are not dropped.
+
+Nested hashes are published through `CommandTower::Events.publish_audit`. Generic `Events.publish` / `sanitize_payload` still keep only scalars (and arrays of scalars). The ledger column is `change_set` because ActiveRecord reserves `changes` for dirty tracking.
+
+### Disabled events
+
+A registered event with `enabled = false` causes `audit(...)` to **return without emitting**. Disabled events therefore insert **no row**. Unregistered names still fail **before** persistence.
+
+### Attribution
+
+| Mode | When | Actor |
+|------|------|--------|
+| `impersonation` | `Current.impersonation_active` | `originating_administrator_id` |
+| `admin_direct` | explicit keyword | `Current.user_id` |
+| `system` | explicit, or no `Current.user_id` | `nil` |
+| `self_service` | default when actor id equals affected user id | `Current.user_id` |
+
+Do not infer `admin_direct` from routes or from id inequality. `Current.user_id` remains the **effective** user under impersonation.
+
+Lifecycle events `impersonation_started` / `impersonation_ended` record the administrator as actor and the impersonated user as affected. Product mutations executed during an overlay use `attribution_mode: impersonation` automatically from Current.
+
+### Fail-fast
+
+Unregistered names, forbidden change keys, unsafe objects in `changes`/`metadata`, missing required subject/affected user, and invalid attribution **raise**. Malformed audit data is never silently discarded.
+
+## Transaction-aware persistence
+
+```text
+Standalone audit
+  audit(...)
+  → INSERT
+
+Transactional business operation
+  BEGIN
+    mutation
+    audit(...)
+  COMMIT
+```
+
+The outer `BEGIN` exists only when the **business operation** needs atomicity. Audit does not impose it.
+
+## Audit publisher ownership
+
+Workflows are the preferred owners of semantic audit facts because workflows represent canonical business orchestration. New audit publishers should be placed in the owning workflow when that can be done cleanly.
+
+Typical shape:
+
+```text
+orchestrate service mutation
+        ↓
+receive meaningful result
+        ↓
+emit semantic audit fact
+```
+
+Services may emit audit facts when the service uniquely owns the mutation or moving publication upward would require artificial plumbing, result-contract distortion, or transaction gymnastics.
+
+Existing service-owned audit publishers (Phase 4.3) remain supported. Consolidation toward workflow ownership is deferred platform cleanup, not a Phase 4 correctness requirement. Do not reshape service result contracts purely to satisfy audit placement without an explicit architecture decision.
+
+Do not double-emit from workflow and service. Models, controllers, jobs, and callbacks remain inappropriate audit publishers.
+
+## Reading audit history
+
+The ledger is queryable over HTTP. Controllers stay transport-only. Workflows orchestrate; they do **not** query `Audit::Event`. `Services::Audit::Events::List` owns the relation. `Services::Audit::Events::Project` duplicates hashes and masks sensitive `change_set` from/to **before** serialization. Unmasked sensitive values never leave Project toward HTTP. Both user and admin projections mask. There is no unmask permission.
+
+| Surface | Path | RBAC entity | Scope |
+|---------|------|-------------|-------|
+| User | `GET /me/audit-events` | `me_audit_events` | `affected_user_id == current_user.id` **and** snapshot `user_history == true`. Actor identity never grants visibility. The Me controller does not read a target user from params. |
+| Admin | `GET /admin/audit-events` | `admin_audit_events` | Full ledger when unscoped. When tool is scoped: composite host-scoped + eligible global for in-scope users; **legacy excluded**. |
+| User detail | `GET /me/audit-events/:id` | `me_audit_events` | Same Me scope as list. **404** when out of scope or missing. |
+| Admin detail | `GET /admin/audit-events/:id` | `admin_audit_events` | Full ledger by id when unscoped. **404** when missing or out of scope (disclosure-safe). |
+
+**Scope provenance columns:** `scope_class` (`global` \| `host` \| `legacy`), `host_context_type`, `host_context_identifier`. Pre-scope historical rows migrated to **`legacy`** — not bulk-labeled `global`. Legacy rows are **not** eligible for scoped-admin global inclusion.
+
+Pagination matches Inbox: `limit` default **50** (unchanged), max **100**, `offset` default 0, `meta: { limit, offset, totalCount }`. Shared Audit Explorer FE always sends `limit` from Collection pageSize (default **25**). Order is `occurred_at DESC, id DESC`.
+
+User filters: optional `eventName` (singular alias) or `eventNames[]` (exact `action` `IN`), `occurredAfter` / `occurredBefore` (ISO8601), `subjectType` (singular alias) or `subjectTypes[]` (`IN`). Admin adds `affectedUserId`, `actorUserId`, `originatingAdministratorId`, `attributionMode`. Invalid enums/IDs are 422. Free-text / metadata JSON search is **not** supported (deferred).
+
+Masking applies to sensitive **change keys** only (union of row `sensitive_fields` and the current registry for that action if still registered). Metadata is **not** masked: there is no metadata sensitivity grammar today. Phone uses last-four style (`*******1212`); email uses `m***@example.com`; nil stays nil; unknown/malformed values are fully redacted, never raw.
+
+Serializer fields (camelCase), from the projection hash only: `id`, `eventName`, `eventLabel` (optional registry label; may be empty), `occurredAt`, `attributionMode`, `actor.userId`, `affectedUser.userId`, `subject.{type,id,label}`, `impersonationActive`, `originatingAdministratorId`, `changes`, `metadata`. List and show share this serializer. Snapshot internals, `event_uuid`, and execution/correlation IDs are not exposed.
+
+Shared FE product: `@commandtower/frontend/capabilities/audit` (`AuditExplorer` scopes `admin` \| `me`). Account Activity presentation is gated by principal capability `me_audit_events`; Admin Explorer by `admin_audit_events`. Backend RBAC remains authoritative. The Admin Workspace **manifest** (`GET /admin/workspace`) discovers tools; it is not a UI permission probe.

data/docs/authentication.md

@@ -24,6 +24,20 @@ Failure JSON may still use older `Schema::Error` shapes — not identical to the
 
 Configure secrets and JWT options during install — see [Initializing](initializing.md).
 
+## Impersonation (session overlay)
+
+Impersonation is a **CommandTower session primitive**, not a User mutation. The administrator JWT stays the credential (`user_id` is always the actor). An optional `impersonation_session_id` claim locates a server-authoritative `command_tower_impersonation_sessions` row. Product identity (`current_user`, `Current.user_id`) becomes the target while the overlay is valid.
+
+- Start: `POST /admin/users/:id/impersonation-sessions` (RBAC `admin_impersonation`)
+- Stop / return-to-self: `DELETE /auth/impersonation-session` (valid administrator JWT; not `admin_impersonation` on the target)
+- Timeouts: `config.impersonation.idle_timeout` (default 10 minutes) and `config.impersonation.absolute_timeout` (default 1 hour). Idle refresh is **workflow-declared** (`impersonation_activity!`); HTTP activity alone does not refresh idle.
+- Concurrent independent sessions are allowed. Nested impersonation is forbidden.
+- Expired overlay on a product request: `401` `impersonation_session_expired` without clearing the auth cookie.
+- Admin resource endpoints other than `GET /admin/workspace` return **418** `admin_unavailable_during_impersonation` while overlaying. Workspace remains allowed and projects every tool `availability.enabled: false`.
+- Target visibility for start is **only** Phase 5.4 Admin Resource Scoping (`ScopeResolution` + Admin Users Show). Unscoped hosts omit `adminScope`.
+
+See [API reference](api_reference.md#impersonation) and [Authorization](authorization.md).
+
 ## Where to go next
 
 | Need | Guide |