command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,51 @@
+# Authentication
+
+Authentication establishes **who** is calling. Failed authentication returns `401`.
+
+## Engine controllers
+
+Modern engine controllers use the authentication boundary:
+
+```ruby
+# via AuthenticationBoundary
+before_action :authenticate_request!
+```
+
+Token extraction checks `Authorization: Bearer {token}` first, then an HttpOnly cookie when cookie auth is enabled. Failures use the application envelope (`{ data, meta, errors }`).
+
+## Host controllers (provisional)
+
+```ruby
+before_action :authenticate_user!
+# current_user is set when authentication succeeds
+```
+
+Failure JSON may still use older `Schema::Error` shapes — not identical to the engine envelope. See the deep guide.
+
+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 |
+|------|-------|
+| Full authn + RBAC design | [Authentication & authorization guide](authentication_authorization_guide.md) |
+| Cookie / CORS / CSRF | [Cookie authentication](cookie_authentication_guide.md) |
+| HTTP contracts | [API reference](api_reference.md) |
+| Session invalidation | [Sensitive changes](sensitive_routes.md) |
+| Authorization (RBAC) | [Authorization](authorization.md) |
+
+Back to [README](../README.md).

data/docs/authentication_authorization_guide.md

@@ -0,0 +1,154 @@
+# Authentication & Authorization Guide
+
+Deep guide for JWT authn, session boundaries, RBAC, and how Engine vs host helpers differ.
+
+Quick starts: [authentication.md](authentication.md), [authorization.md](authorization.md). HTTP catalog: [api_reference.md](api_reference.md). Cookies: [cookie_authentication_guide.md](cookie_authentication_guide.md).
+
+## Authn vs authz
+
+| Concern | Meaning | Typical failure |
+|---------|---------|-----------------|
+| **Authentication** | Who is calling | `401` |
+| **Authorization** | Are they allowed to perform this action | `403` |
+
+Keep them separate. Authenticate first; authorize after `current_user` is established.
+
+## Engine HTTP boundaries
+
+Modern engine controllers use concerns:
+
+- `CommandTower::Auth::AuthenticationBoundary` → `authenticate_request!`
+- `CommandTower::Auth::AuthorizationBoundary` → `authorize_request!`
+
+Failures render the application **envelope** (`{ data, meta, errors }`) via `render_application_result`.
+
+Email verification controllers call `authenticate_request!(bypass_email_validation: true)` so unverified users can complete verification.
+
+### Host provisional helpers
+
+`CommandTower::ApplicationController` still exposes:
+
+```ruby
+before_action :authenticate_user!
+before_action :authorize_user!
+```
+
+Hosts may use these on host controllers. Failure shapes can still use older `Schema::Error::*` JSON — **not** identical to the engine envelope. Prefer aligning new host JSON APIs to the envelope yourself, or call into workflows that return `WorkflowResult`.
+
+## Token transport
+
+1. **Bearer** — `Authorization: Bearer <jwt>` (primary)
+2. **Cookie** — optional HttpOnly JWT when `config.jwt.cookie.enabled` (see cookie guide)
+3. **Signup session** — `Authorization: Signup <token>` for availability checks
+4. **Password recovery session** — `Authorization: Recovery <token>` for password-reset send
+
+Default JWT TTL: **7 days** (`config.jwt.ttl`).
+
+### Verifier token
+
+JWTs embed a `verifier_token` claim bound to `User#verifier_token`. Rotation invalidates outstanding tokens. See [sensitive_routes.md](sensitive_routes.md).
+
+Authenticated password change (`PATCH /me/password`) rotates the verifier. Browser `POST /auth/logout` clears cookie transport only.
+
+## Primary auth HTTP flows
+
+Paths are engine-relative. Full request/response shapes: [api_reference.md](api_reference.md).
+
+| Flow | Endpoints |
+|------|-----------|
+| Register | `POST /auth/register` |
+| Login | `POST /auth/plain-text/login` (gate: `login.plain_text.enable?`) |
+| 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` |
+| Signup session | `POST /auth/signup-session` → availability GETs |
+| Email verification | `POST /auth/email-verification/{send,verify}` |
+| Password recovery | `POST /auth/password-recovery-session` → `POST /auth/password-reset/{send,validate,reset}` |
+
+There is **no** `GET /user`, `POST /user/modify`, `POST /auth/login` (without `plain-text`), or `POST /auth/password/change` on the modern engine.
+
+## Session boundaries
+
+### Signup session
+
+1. `POST /auth/signup-session` → `signupSessionToken`
+2. Call gated availability endpoints with `Authorization: Signup …`
+
+Used by email/username availability. Missing/invalid/expired session → `401` with `signup_session_*` codes.
+
+### Password recovery session
+
+1. `POST /auth/password-recovery-session` → `recoverySessionToken`
+2. `POST /auth/password-reset/send` requires `Authorization: Recovery …`
+
+Validate/reset use the emailed reset token in the body (public). See [password_reset_workflow.md](password_reset_workflow.md).
+
+## RBAC
+
+### Engine defaults
+
+`lib/command_tower/authorization/default.yml`:
+
+- **`owner`** — `entities: true` (full access). Explicit top-level authority; distinct from host operational Admin roles.
+
+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 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` — **`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
+class Host::ThingsController < ApplicationController
+  before_action :authenticate_user!
+  before_action :authorize_user!
+
+  def show
+    # Prefer one workflow + envelope-compatible render for new APIs
+  end
+end
+```
+
+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
+
+```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
+```
+
+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
+
+When email verification is required, authenticated requests may receive **412** `email_verification_required` until verified. Verification endpoints bypass that gate. See [email_verification_workflow.md](email_verification_workflow.md).
+
+## Related
+
+- [API reference](api_reference.md)
+- [Cookie authentication](cookie_authentication_guide.md)
+- [Sensitive changes](sensitive_routes.md)
+- [Initializing](initializing.md)
+- [Messaging](messaging_integration_guide.md)
+- [README](../README.md)

data/docs/authorization.md

@@ -0,0 +1,55 @@
+# Authorization (RBAC)
+
+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). 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)
+
+```ruby
+# Order matters: authorize depends on current_user from authentication
+before_action :authenticate_user!
+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` — 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)
+
+`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) |
+
+Back to [README](../README.md).

data/docs/change_password_workflow.md

@@ -0,0 +1,67 @@
+# Authenticated Password Change Workflow
+
+Authenticated password change lets a signed-in user replace their password by proving knowledge of the current password. On success, CommandTower rotates `verifier_token` in the same transaction as the password digest update, invalidating **all** existing JWT sessions (including the caller’s). The API does **not** re-issue a JWT; hosts must clear local auth and send the user through Sign In again.
+
+This is distinct from [password recovery](password_reset_workflow.md), which is public and recovery-session/token-based.
+
+## Purpose and orchestration
+
+| Item | Value |
+|------|--------|
+| Route | `PATCH /me/password` (engine-relative) |
+| Auth | Authentication + authorization boundaries |
+| Controller | `CommandTower::Me::PasswordController#update` |
+| Workflow | `CommandTower::Workflows::Me::ChangePasswordWorkflow` (`ApplicationWorkflow`, `retry_strategy :none`) |
+| Service | `CommandTower::Services::Me::ChangePassword` |
+| Deserializer | `CommandTower::Deserializers::Me::ChangePasswordDeserializer` |
+| Serializer | `CommandTower::Serializers::Me::ChangePasswordResponseSerializer` |
+| Feature gate | Route always drawn (not constrained in `routes.rb`) |
+
+**Boundary:** The controller deserializes input and runs **one** workflow. The workflow orchestrates the change-password service and maps failures to HTTP status. It does not implement password rules itself.
+
+## Request
+
+```json
+{
+  "current_password": "string",
+  "password": "string",
+  "password_confirmation": "string"
+}
+```
+
+## Success (200)
+
+Serialized success payload (message only). Response effects include `clear_token: true` so cookie/header sessions are cleared. No JWT, verifier, or password material is returned.
+
+## Service flow (under the workflow)
+
+1. Authenticate `current_password`
+2. Confirm `password` matches `password_confirmation`
+3. Enforce configured password length bounds
+4. In one DB transaction: persist new password digest → `reset_verifier_token!`
+5. On failure: typed application errors → workflow HTTP mapping
+
+## Failures
+
+| Condition | Typical status |
+|-----------|----------------|
+| Missing / invalid JWT | 401 |
+| Validation / bad current password / confirmation | 4xx via Me error mapping |
+| Unexpected infra failure | 5xx |
+
+## Contrast with recovery reset
+
+| | Authenticated change | Forgot / reset |
+|--|----------------------|----------------|
+| Proof | Current password | Recovery session + reset token |
+| Route | `PATCH /me/password` | `POST /auth/password-recovery-session` + `/auth/password-reset/*` |
+| Auth | JWT | Public (+ recovery session) |
+| Verifier | Rotated | See recovery guide |
+| Post-success | All JWTs invalid; host → Sign In | Host-defined |
+
+## Related
+
+- [Sensitive changes](sensitive_routes.md)
+- [API reference](api_reference.md)
+- [Password reset workflow](password_reset_workflow.md)
+- [Extending](extending.md)

data/docs/controllers.md

@@ -0,0 +1,41 @@
+# Controllers and routes
+
+CommandTower exposes platform HTTP through `CommandTower::Engine` routes. Hosts typically mount the engine (for example at `/api`) via the configure generator or a custom mount.
+
+This page is an **index** of route areas. Detailed request/response contracts live in the [API reference](api_reference.md).
+
+## Route areas
+
+| Area | Prefix (engine-relative) | Purpose |
+|------|--------------------------|---------|
+| 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 |
+| Admin messaging | `/admin/messaging/announcements` | Cohort announcements |
+
+Exact paths depend on where the host mounts the engine.
+
+## Controllers
+
+Engine controllers are transport adapters: authenticate/authorize as required, deserialize, run **exactly one** workflow, render the application envelope. See [Architecture](architecture.md).
+
+## 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
+- [README](../README.md)
+
+HTTP request specs for the engine live under `spec/requests/`.