command_tower 0.3.1 → 0.10.0

data/docs/initializing.md

@@ -0,0 +1,169 @@
+# Initializing CommandTower
+
+CommandTower is a Rails engine. The install flow below gets the engine **mounted, migrated, and doctor-checked**. That alone is not a fully usable Me/Auth host — complete RBAC, feature gates, and a smoke check via the [Host integration guide](host_integration_guide.md).
+
+Back to [README](../README.md).
+
+## Quick start
+
+```bash
+# Gemfile: gem "command_tower"  (or path/git source)
+bundle install
+
+bin/rails command_tower:install
+bin/rails db:migrate
+bin/rails command_tower:doctor
+```
+
+`command_tower:install` does **not** run `db:migrate`. Installing and migrating stay separate on purpose.
+
+### After install
+
+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
+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
+
+### What `command_tower:install` does
+
+1. Runs Rails-native `command_tower:install:migrations` (copies engine migrations into the host `db/migrate/` with `*.command_tower.rb` scope).
+2. Runs `rails g command_tower:configure` unless skipped (creates initializer; mounts the engine).
+3. Prints next steps.
+
+### Flags / environment
+
+| Variable | Effect |
+|----------|--------|
+| `SKIP_CONFIGURE=1` | Migrations only (existing custom initializer / mount) |
+| `SKIP_MOUNT=1` | Generate initializer but do not mount routes |
+| `FORCE=1` | Overwrite an existing `config/initializers/command_tower.rb` |
+
+Examples:
+
+```bash
+SKIP_CONFIGURE=1 bin/rails command_tower:install
+SKIP_MOUNT=1 bin/rails command_tower:install
+FORCE=1 bin/rails command_tower:install
+```
+
+## Configure generator (optional)
+
+Prefer `command_tower:install` for greenfield hosts. The generator remains available:
+
+```bash
+bin/rails generate command_tower:configure
+bin/rails generate command_tower:configure --skip-routes
+bin/rails generate command_tower:configure --force
+```
+
+The generator:
+
+1. Adds `config/initializers/command_tower.rb` when missing (or overwrites with `--force`).
+2. Mounts `CommandTower::Engine` unless `--skip-routes` or already mounted.
+
+Dummy-host example initializer (engine development): [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
+
+## Database migrations
+
+CommandTower is the **sole authoring authority** for CommandTower-owned schema (`db/migrate` inside the gem). Hosts must **not** manually write, edit, or copy-paste CommandTower schema migrations (**AD-SCH-01**).
+
+### Fresh host install
+
+Handled by `command_tower:install` (step 1). Equivalent migration-only command:
+
+```bash
+bin/rails command_tower:install:migrations
+bin/rails db:migrate
+```
+
+`command_tower:install:migrations` is the standard Rails engine task (wrapper around `railties:install:migrations`). Re-running installation is **idempotent**: already-installed CommandTower migrations are skipped.
+
+Rails may **retimestamp** newly copied host files. That is normal. Do not hand-edit installed `*.command_tower.rb` files.
+
+### Upgrade workflow
+
+1. Bump/release the CommandTower gem dependency in the host.
+2. Run `bin/rails command_tower:install:migrations` (or `SKIP_CONFIGURE=1 bin/rails command_tower:install`).
+3. Run `bin/rails db:migrate`.
+4. Optionally run `bin/rails command_tower:doctor`.
+
+Do not re-run configure on hosts that already customize the initializer unless you intend to regenerate it (`FORCE=1`).
+
+### Adding future migrations
+
+1. Author the migration **only** in CommandTower `db/migrate/`.
+2. Release / bump the gem in the host.
+3. Install + migrate as above.
+
+Installed host copies are an **execution context**, not a second authoring home.
+
+## Configuration
+
+Required for production-ready hosts:
+
+- `config.jwt.hmac_secret` — typically `SECRET_KEY_BASE` / `Rails.application.secret_key_base`
+- `config.signup_session.jwt_secret` — or `SIGNUP_SESSION_JWT_SECRET`
+- `config.password_recovery_session.jwt_secret` — or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`
+
+Optional / feature-gated:
+
+- Messaging SMS / Pushover adapters and credential resolution (`config.credentials.*` or ENV)
+- Cookie + CSRF JWT modes
+- Admin enablement, application URL, welcome content hooks
+
+The generated initializer documents available options via class_composer. Defaults live in CommandTower; do not duplicate them unnecessarily in the host.
+
+## Doctor
+
+```bash
+bin/rails command_tower:doctor
+```
+
+Checks Rails version compatibility, engine baseline migrations, host-installed migration copies, JWT / session secrets, and messaging adapter names. Failures abort with remediation text; warnings print but allow success.
+
+Doctor does **not** probe Redis/SMTP connectivity.
+
+## Host vs CommandTower responsibilities
+
+| Concern | Owner |
+|---------|--------|
+| Author CT schema migrations | CommandTower |
+| Install / run migrations | Host (via engine tasks + `db:migrate`) |
+| Product configuration / secrets | Host initializer + ENV |
+| Dual-author CT schema in the host | **Forbidden** |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `users already exists` on migrate | Database not empty / stale `schema.rb` load — migrate an empty DB, or dump schema after a clean migrate |
+| Install copies nothing new | Already installed — expected idempotency |
+| Missing tables after install | You installed but did not `db:migrate` |
+| Doctor fails on JWT default | Set `config.jwt.hmac_secret` from a real secret |
+| Accidental public engine mount | Use `SKIP_MOUNT=1` / `--skip-routes`, or mount at the path your product needs |
+
+## Existing customized hosts
+
+If the host already has a bespoke initializer and mount:
+
+```bash
+SKIP_CONFIGURE=1 bin/rails command_tower:install
+# same as: bin/rails command_tower:install:migrations
+bin/rails db:migrate
+```
+
+Do not run `rails g command_tower:configure` unless you intentionally want stock scaffolding.
+
+## Test suite factories
+
+Shared FactoryBot definitions ship with the gem. In the host test boot path:
+
+```ruby
+require "command_tower/testing"
+CommandTower::Testing.install!
+```
+
+Then extend with `FactoryBot.modify` as needed. See [Testing with CommandTower](testing.md).

data/docs/messaging_integration_guide.md

@@ -0,0 +1,87 @@
+# Messaging with CommandTower
+
+CommandTower owns modern messaging **platform** surfaces. Hosts supply product content, channel policy, and adapter credentials.
+
+Complete install and host RBAC first: [Host integration](host_integration_guide.md) (Steps 1–8 before emitting or wiring phone/Pushover).
+
+## Current surfaces
+
+| Concern | Path / entry |
+|---------|----------------|
+| User inbox (consume) | Engine `/me/inbox*` — see [API reference](api_reference.md#me-inbox) |
+| Preferences | Engine `/me/preferences*` — see [API reference](api_reference.md#preferences) |
+| Phone / Pushover endpoints | Engine `/me/phone*`, `/me/pushover*` (503 when capability unavailable) |
+| Single-recipient emit | `CommandTower::Services::Messaging::Communications::Produce` |
+| Multi-recipient emit | `CommandTower::Services::Messaging::Communications::ProduceMany` |
+| Admin cohort announce | Engine `POST /admin/messaging/announcements` |
+| Host ops announce | Host-owned rake/job (product-specific; not part of the gem) |
+
+Authentication uses JWT bearer or cookie session as documented in [Authentication](authentication.md). Me Inbox authorization requires host RBAC entities (dummy host uses a `member` role mapping). Admin announcements use entity `admin_messaging_announcements` (engine `default.yml` admin group).
+
+## Produce (single recipient)
+
+Call from a **product workflow**, not from a controller service bypass:
+
+```ruby
+CommandTower::Services::Messaging::Communications::Produce.call(
+  user: user,
+  notification_type_key: "welcome",
+  host_event_identity: "welcome/#{user.id}/#{SecureRandom.uuid}",
+  title: "Welcome",
+  body: "Thanks for joining.",
+  platform_enabled_channels: [:inbox, :email],
+  metadata: { source: "onboarding" } # optional
+)
+```
+
+| Kwarg | Required |
+|-------|----------|
+| `user` | yes (`User`) |
+| `notification_type_key` | yes (`String`) |
+| `host_event_identity` | yes (`String`) |
+| `title` | yes |
+| `body` | yes |
+| `platform_enabled_channels` | yes (`Array`) |
+| `metadata` | no (`Hash`) |
+
+## ProduceMany (multi recipient)
+
+| Kwarg | Required / notes |
+|-------|------------------|
+| `user_ids` | yes (`Array` of integer ids) |
+| `notification_type_key` | yes |
+| `campaign_identity` | yes — fan-out builds `host_event_identity` as `"#{campaign_identity}/#{user.id}"` |
+| `title`, `body` | yes |
+| `platform_enabled_channels` | yes |
+| `metadata` | optional |
+| `execution_mode` | optional, default `:async`; `:sync` capped at **25** recipients |
+
+Admin announcements HTTP is a product path over ProduceMany (async/sync, audience selection). Contract: [API reference — Admin messaging](api_reference.md#admin-messaging).
+
+## Me Inbox HTTP (summary)
+
+| Concern | Contract |
+|---------|----------|
+| List | `GET /me/inbox?limit=&offset=&scope=` — meta `{ limit, offset, totalCount }` |
+| Detail / open / archive / delete | `/me/inbox/:id` (+ `open`, `archive`) |
+| Bulk | `POST /me/inbox/bulk/{read,unread,archive,restore,delete}` with body `ids` |
+| Unread | `GET /me/inbox/unread-count` |
+
+Pagination detail: [pagination.md](pagination.md). Full catalog: [api_reference.md](api_reference.md#me-inbox).
+
+## Host responsibilities
+
+- 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)
+- Product-specific operational tooling (announce rake tasks, welcome copy)
+
+## Related
+
+- [Controllers / routes](controllers.md)
+- [API reference](api_reference.md)
+- [Extending](extending.md) — Produce from host workflows; Do-Not-Extend
+- [Initializing](initializing.md) — configuration and doctor
+- [Pagination](pagination.md)
+- [README](../README.md)

data/docs/models.md

@@ -0,0 +1,51 @@
+# CommandTower Models
+
+Core models live in the root / CommandTower namespaces and support authentication, authorization, and messaging ledger associations.
+
+Back to [README](../README.md).
+
+## User
+
+`User` is the primary identity model for host applications.
+
+It underpins [Authentication](authentication.md) and [Authorization](authorization.md), and participates in messaging via associations such as `messaging_communications`.
+
+Sensitive session invalidation uses the user’s verifier token — see [Sensitive changes](sensitive_routes.md).
+
+### Reopening `User` in the host
+
+Prefer services/workflows for new behavior. When you must reopen the class:
+
+```ruby
+require CommandTower::Engine.root.join("app", "models", "user.rb")
+
+class User
+  def self.my_class_method; end
+  def my_instance_method; end
+end
+```
+
+## UserSecret
+
+`UserSecret` backs validation and recovery-related secrets (for example plain-text email validation flows). It complements [Sensitive changes](sensitive_routes.md).
+
+### Reopening `UserSecret` in the host
+
+```ruby
+require CommandTower::Engine.root.join("app", "models", "user_secret.rb")
+
+class UserSecret
+  def self.my_class_method; end
+  def my_instance_method; end
+end
+```
+
+## Messaging models
+
+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)).
+
+## Related
+
+- [Architecture](architecture.md)
+- [Sensitive changes](sensitive_routes.md)
+- [Testing](testing.md) — shared factories for CT-owned models

data/docs/pagination.md

@@ -0,0 +1,47 @@
+# Pagination
+
+CommandTower exposes one live HTTP list contract that returns pagination metadata: **Me Inbox**.
+
+Back to [README](../README.md).
+
+## Me Inbox list contract
+
+`GET /me/inbox` accepts query parameters:
+
+| Param | Default | Notes |
+|-------|---------|--------|
+| `limit` | `50` | Max `100` |
+| `offset` | `0` | |
+| `scope` | `"inbox"` | `"inbox"` or `"archived"` |
+
+Success envelope `meta`:
+
+```json
+{
+  "limit": 50,
+  "offset": 0,
+  "totalCount": 123
+}
+```
+
+`data` is an array of inbox items. Full route table: [API reference — Me Inbox](api_reference.md#me-inbox).
+
+Deserializer: `CommandTower::Deserializers::Messaging::Inbox::ListDeserializer`.
+
+## Global pagination config
+
+`CommandTower.config.pagination.limit` defaults to **10**. That value is a generic configuration default for pagination helpers — it is **not** the Me Inbox HTTP default (Inbox uses 50).
+
+```ruby
+CommandTower.configure do |c|
+  c.pagination.limit = 50
+end
+```
+
+There is no engine admin list endpoint and no `pagination=true` / `page` / `cursor` query API on current engine HTTP surfaces.
+
+## Related
+
+- [API reference](api_reference.md)
+- [Messaging](messaging_integration_guide.md)
+- [Controllers](controllers.md)

data/docs/password_reset_workflow.md

@@ -0,0 +1,82 @@
+# Password Reset (Forgot Password) Workflow
+
+Public password recovery for users who cannot authenticate. Flow uses a **password-recovery session** plus gated **password-reset** endpoints. Detailed schemas live here and are summarized in the [API reference](api_reference.md).
+
+## Purpose and orchestration
+
+| Step | Route | Workflow |
+|------|-------|----------|
+| Create recovery session | `POST /auth/password-recovery-session` | `Workflows::Auth::PasswordRecoverySession::CreateWorkflow` |
+| Send reset email | `POST /auth/password-reset/send` | `Workflows::Auth::PasswordReset::SendWorkflow` |
+| Validate token | `POST /auth/password-reset/validate` | `Workflows::Auth::PasswordReset::ValidateWorkflow` |
+| Reset password | `POST /auth/password-reset/reset` | `Workflows::Auth::PasswordReset::ResetWorkflow` |
+
+All listed workflows inherit `ApplicationWorkflow` with `retry_strategy :none`. Controllers under `CommandTower::Auth::PasswordReset::*` and password-recovery-session authenticate the recovery session where required, deserialize, run **one** workflow, and render `WorkflowResult`.
+
+**Feature gate:** `CommandTower.config.login.plain_text.password_reset?` (reset endpoints). Recovery session creation is part of the public recovery path.
+
+**Boundary:** Controllers own transport + recovery-session auth. Workflows orchestrate rate limits and password-reset services. Services own email/token capability details. Do not call messaging execution internals from hosts — see [extending.md](extending.md).
+
+## High-level characteristics
+
+- **No user JWT**; `password-reset/send` requires a valid **password-recovery session**; `validate` / `reset` are public and use the emailed reset `token` in the body
+- Email-based identification; responses avoid user enumeration where designed to
+- Secure, time-limited reset tokens
+- Rate limiting via password-recovery rate-limit services
+
+## Endpoints (engine-relative)
+
+### 1. Create password-recovery session
+
+`POST /auth/password-recovery-session`
+
+Establishes the recovery session used by subsequent reset calls. See request specs under `spec/requests/` for exact payload/envelope.
+
+### 2. Send reset email
+
+`POST /auth/password-reset/send`
+
+**Auth:** Password-recovery session  
+
+**Body (typical):** `{ "email": "string" }`  
+
+**Workflow:** `SendWorkflow` → rate-limit check → `Services::Auth::PasswordReset::Send`
+
+### 3. Validate token
+
+`POST /auth/password-reset/validate`
+
+**Auth:** Public (reset token in body)
+
+**Body (typical):** `{ "token": "string" }` (optional `email` when config requires it)
+
+**Workflow:** `ValidateWorkflow`
+
+### 4. Reset password
+
+`POST /auth/password-reset/reset`
+
+**Auth:** Public (reset token in body)
+
+**Body (typical):** token + new password fields (`passwordConfirmation` / `password_confirmation`)
+
+**Workflow:** `ResetWorkflow`
+
+Success behavior and verifier rotation differ from authenticated [change password](change_password_workflow.md) — treat recovery success per product policy (often force Sign In).
+
+## Errors
+
+Failures return the standard application envelope via `render_application_result`. Status mapping uses Auth identity/password-reset error helpers. Validation failures from deserializers typically surface as `422 Unprocessable Entity`.
+
+## Security notes
+
+- Never log passwords, raw tokens, or recovery-session secrets
+- Prefer HTTPS in production
+- Respect rate limits; do not probe for account existence in client UX
+
+## Related
+
+- [Change password workflow](change_password_workflow.md)
+- [API reference](api_reference.md)
+- [Initializing](initializing.md) — secrets / feature config
+- [Extending](extending.md)

data/docs/sensitive_routes.md

@@ -0,0 +1,47 @@
+# Sensitive changes and session invalidation
+
+CommandTower JWTs are bound to the authenticated user’s **verifier token**. When the verifier rotates, previously issued access tokens that carried the old verifier no longer authenticate (`401`).
+
+This is the platform mechanism behind “logout everywhere” and post-password-change session invalidation.
+
+## Verifier token on `User`
+
+Each `User` may store:
+
+- `verifier_token` — opaque string embedded in JWTs at issue time
+- `verifier_token_last_reset` — timestamp of the last rotation
+
+API:
+
+```ruby
+user.reset_verifier_token!    # generates a new token, updates timestamp, returns the value
+user.retreive_verifier_token! # returns existing token or creates one (historical spelling)
+```
+
+Authentication compares the verifier claim in the JWT to the user’s current `verifier_token`. A mismatch fails authentication.
+
+## When the platform rotates the verifier
+
+| Event | Behavior |
+|-------|----------|
+| Authenticated password change (`PATCH /me/password`) | Rotates verifier so prior tokens fail |
+| Host / ops call `user.reset_verifier_token!` | Explicit revoke-all-sessions |
+
+There is no engine HTTP admin “mutate user with `verifier_token: true`” route. `UserAttributes::Mutate` may still exist for internal/host use; do not assume a public SchemaHelper admin path.
+
+Browser `POST /auth/logout` clears cookie/session transport for that client; it does **not** by itself rotate `verifier_token` for all devices. Use verifier rotation when all outstanding JWTs must die.
+
+## Host guidance
+
+- Treat password changes and explicit “revoke all sessions” as **sensitive** operations that should rotate the verifier.
+- Do not expose `verifier_token` in API payloads (platform serializers omit it).
+- Prefer platform workflows/services for password change rather than hand-editing password digests without rotation.
+- `UserSecret` backs related validation/recovery secrets; see [Models](models.md).
+
+## Related
+
+- [Change password workflow](change_password_workflow.md)
+- [Authentication](authentication.md) / [Authentication & authorization guide](authentication_authorization_guide.md)
+- [Cookie authentication](cookie_authentication_guide.md)
+- [Models](models.md)
+- [README](../README.md)

data/docs/testing.md

@@ -0,0 +1,74 @@
+# Testing with CommandTower
+
+CommandTower ships FactoryBot definitions for engine-owned models. Hosts load
+them explicitly in the test suite — there is no production Railtie and
+FactoryBot is not a runtime gem dependency.
+
+Back to [README](../README.md). See also [Initializing](initializing.md).
+
+## Setup
+
+```ruby
+# spec/rails_helper.rb (after Rails is loaded)
+require "command_tower/testing"
+
+CommandTower::Testing.install! # preferred
+# CommandTower::Testing.load_factories! # factories-only / advanced
+```
+
+Call `install!` **before** any host `FactoryBot.modify` blocks so shared
+factories exist when you extend them.
+
+## Extending factories
+
+Hosts must not redefine CommandTower base factories. Use `FactoryBot.modify`:
+
+```ruby
+FactoryBot.modify do
+  factory :user do
+    roles { ["member"] }
+
+    trait :operator do
+      roles { %w[member operator] }
+    end
+  end
+end
+```
+
+## Packaging and evolution
+
+Factory files live under `spec/factories/**` inside the gem and are included in
+the gemspec. Adding or changing a shared factory is a normal CommandTower gem
+bump — hosts pick it up on upgrade.
+
+`CommandTower::Testing.load_factories!` is idempotent (safe to call more than
+once). It loads each factory file under `CommandTower::Engine.root/spec/factories`
+explicitly; it does not append to global `FactoryBot.definition_file_paths`.
+
+## Responsibilities
+
+| Owner | Responsibility |
+|-------|----------------|
+| CommandTower | Base factories for CT-owned models; Testing API; packaging |
+| Host | `install!` in the test boot path; product traits via `FactoryBot.modify` |
+
+## Factory invariant
+
+Base factories construct **persistent model state only**. They must not invoke
+Services, Workflows, ApplicationWorkflows, or external adapters. Endpoint
+ciphertext uses `SecretBox` / `Fingerprinter` (crypto helpers).
+
+For endpoint factories in environments where
+`COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET` is unset, you may call:
+
+```ruby
+CommandTower::Testing.ensure_endpoint_secret!
+```
+
+(SecretBox already falls back to a non-production test secret outside production.)
+
+## Contributors vs hosts
+
+This guide is the **host Testing API**. Contributors working inside the CommandTower
+repository also follow workspace test standards (`.cursor/rules/testing.mdc`) and
+architecture guards under `spec/architecture/`.

data/docs/upgrades/0.10.0.md

@@ -0,0 +1,58 @@
+# Upgrade: CommandTower 0.10.0
+
+**From:** `0.5.0` (and earlier SchemaHelper-era hosts on `main`)  
+**To:** `0.10.0`
+
+This document summarizes **all changes from `main` through the `0.10.0` release** (committed work on `schematizing` plus the modern platform working tree). It is the durable upgrade / change SST for hosts. For a sequenced blank-host path, use [Host integration](../host_integration_guide.md).
+
+## Breaking / host-impact
+
+| Change | Host impact |
+|--------|-------------|
+| SchemaHelper Admin / User / legacy Inbox HTTP removed | No `GET /user`, `/user/modify`, `/admin/modify*`, legacy blast/message SchemaHelper routes |
+| Modern response envelope | Engine HTTP returns `{ data, meta, errors }` via `render_application_result` |
+| Current-user path | Use `GET /me` (and `GET /profile`); not `GET /user` |
+| Login path | `POST /auth/plain-text/login` when `login.plain_text.enable?` (route absent → **404** if gate off) |
+| Password change | `PATCH /me/password` (rotates verifier; does not re-issue JWT) |
+| Host RBAC required | Without host `rbac_groups.yml` entity mappings, Me/Auth calls **403** (fail-closed) |
+| Feature gates | Login, email verify, password reset, availability routes are config-gated |
+| Schema ownership (**AD-SCH-01**) | CT authors migrations; hosts install via `command_tower:install` / `install:migrations` then `db:migrate` |
+| Admin HTTP | Only `POST /admin/messaging/announcements` (no SchemaHelper user admin) |
+
+## Platform capabilities in 0.10.0
+
+- **Auth:** register, plain-text login, logout, session, identity policy, signup session, email/username availability, email verification, password-recovery session + password reset
+- **Me:** account show, profile, name, password, inbox (list/detail/bulk), preferences, phone, Pushover
+- **Messaging emit:** `Communications::Produce` / `ProduceMany` from host workflows
+- **Install:** `command_tower:install`, configure generator, `command_tower:doctor`
+- **Testing:** `CommandTower::Testing.install!` shared factories
+- **Architecture:** Controller → Workflow → Service; Engine uses `authenticate_request!` / `authorize_request!`
+
+## Documentation
+
+- Canonical HTTP catalog: [API reference](../api_reference.md)
+- Host start-here: [Host integration](../host_integration_guide.md)
+- Install SST: [Initializing](../initializing.md)
+- Auth/cookie/RBAC guides refreshed to modern routes
+- Messaging and pagination aligned to Inbox + Produce contracts
+
+## Upgrade checklist (existing hosts)
+
+1. Bump gem to `0.10.0` and run `bin/rails command_tower:install:migrations` (or `SKIP_CONFIGURE=1 bin/rails command_tower:install`) then `bin/rails db:migrate`.
+2. Set JWT + signup/recovery session secrets; run `bin/rails command_tower:doctor`.
+3. Copy/adapt [`rails_app/config/rbac_groups.yml`](../../rails_app/config/rbac_groups.yml) into the host; do not redefine engine `owner` / `admin` groups.
+4. Ensure users who need Me surfaces have the host `member` role (or equivalent).
+5. Enable feature gates you rely on (`login.plain_text.enable`, password reset, email verify, availability).
+6. Point clients at modern paths (`/me`, `/auth/plain-text/login`, envelope parsing).
+7. Smoke: Bearer login → `GET /me` returns **200** (not **403**).
+8. If emitting messages: catalog, channels, adapters; call Produce from host workflows.
+
+New hosts: follow [Host integration](../host_integration_guide.md) end-to-end.
+
+## Related
+
+- [Initializing](../initializing.md)
+- [Extending](../extending.md)
+- [Messaging](../messaging_integration_guide.md)
+- [Authentication & authorization guide](../authentication_authorization_guide.md)
+- [README](../../README.md)

data/docs/upgrades/README.md

@@ -0,0 +1,9 @@
+# Upgrades
+
+Host-facing upgrade / change summaries for CommandTower releases.
+
+| Version | Summary |
+|---------|---------|
+| [0.10.0](0.10.0.md) | Modern Auth/Me/Messaging platform; SchemaHelper removal; host RBAC required |
+
+New hosts should start with [Host integration](../host_integration_guide.md).

data/lib/command_tower/authorization/default.yml

@@ -5,38 +5,10 @@ groups:
     entities: true
   admin:
     description: |
-      This group defines permissions for Admin Read and Write operations. Users with this role will have
-      the ability to view and update other users states.
+      Platform admin role for modern Engine admin surfaces (e.g. messaging announcements).
     entities:
-      - admin
-      - message-blast
-  admin-without-impersonation:
-    description: |
-      This group defines permissions for Admin Read and Write operations. Users with this role will have
-      the ability to view and update other users states. However, impersonation is not permitted with this role
-    entities:
-      - admin-without-impersonate
-      - message-blast
-  admin-read-only:
-    description: |
-      This group defines permissions for Admin Read interface only.
-    entities:
-      - read-admin
-      - message-blast-read-only
+      - admin_messaging_announcements
 entities:
-  - name: message-blast
-    controller: CommandTower::Inbox::MessageBlastController
-  - name: message-blast-read-only
-    controller: CommandTower::Inbox::MessageBlastController
-    only: metadata
-  - name: read-admin
-    controller: CommandTower::AdminController
-    only: show
-  - name: admin
-    controller: CommandTower::AdminController
-  - name: admin-without-impersonate
-    controller: CommandTower::AdminController
-    except: impersonate
-
-
-
+  - name: admin_messaging_announcements
+    controller: CommandTower::Admin::Messaging::AnnouncementsController
+    only: create