command_tower 0.17.0 → 0.18.0

data/docs/extending.md

@@ -2,7 +2,7 @@
 
 How hosts customize and integrate with CommandTower **without forking platform internals**.
 
-**New host?** Start with [Host integration](host_integration_guide.md).
+**New host?** Start with [Bootstrap a new host](bootstrap/README.md).
 
 Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor: [initializing.md](initializing.md). Testing API: [testing.md](testing.md). HTTP catalog: [api_reference.md](api_reference.md).
 
@@ -42,11 +42,11 @@ Full install narrative: [initializing.md](initializing.md).
 
 | Surface | Notes |
 |---------|--------|
-| `bin/rails command_tower:install` | Migrations + optional configure |
+| `command_tower:install` (`make rails ARGS='command_tower:install'`) | Task name inside the container; migrations + optional configure |
 | `SKIP_CONFIGURE=1` | Migrations only |
 | `SKIP_MOUNT=1` | Initializer without mount |
 | `FORCE=1` | Overwrite initializer |
-| `rails g command_tower:configure` | `--skip-routes`, `--force` |
+| `command_tower:configure` (`make rails ARGS='generate command_tower:configure'`) | `--skip-routes`, `--force` |
 
 ## Mounting and configuration
 

data/docs/host_integration_guide.md

@@ -1,285 +1,7 @@
 # Host Integration Guide
 
-**Start here** for integrating CommandTower into a new Rails host.
+The new-host manual lives in [`bootstrap/README.md`](bootstrap/README.md).
 
-This page owns the **order of operations**. It does not replace specialty docs: install details stay in [Initializing](initializing.md), HTTP contracts in [API reference](api_reference.md), boundaries in [Extending](extending.md).
+That directory is the bring-up authority: implementation order, Docker-only Make wrappers, one file per step, and an explicit note that the manual is **local bring-up** (not deployment).
 
-`command_tower:doctor` green means secrets/migrations look sane. It does **not** prove Me/Auth authorization works.
-
-## Prerequisites
-
-- A Rails host application (engine is mounted into the host)
-- `gem "command_tower"` in the host Gemfile (path, git, or released gem)
-- Host-owned database (and any host Redis/job stack your app already uses)
-
-## Step 1 — Install
-
-Follow [Initializing](initializing.md):
-
-```bash
-bundle install
-bin/rails command_tower:install
-bin/rails db:migrate
-bin/rails command_tower:doctor
-```
-
-That copies CT migrations, generates `config/initializers/command_tower.rb` (unless skipped), and mounts `CommandTower::Engine` (unless skipped).
-
-## Step 2 — Secrets and initializer
-
-In the host initializer, set at least:
-
-- `config.jwt.hmac_secret`
-- `config.signup_session.jwt_secret` (or `SIGNUP_SESSION_JWT_SECRET`)
-- `config.password_recovery_session.jwt_secret` (or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`)
-- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (for example experience states). Not client-supplied. Blank values cause Me experience-state routes to return **503** `experience_states_host_unconfigured`.
-
-Re-run `bin/rails command_tower:doctor`. Details: [Initializing — Configuration](initializing.md#configuration).
-
-Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb) (sets `host_key` to `"command_tower"`).
-
-### Email / SMTP
-
-CommandTower owns ActionMailer delivery for engine mailers (email verification, password reset, messaging channel mail).
-
-| Environment | Delivery |
-|-------------|----------|
-| `test` | `:test` (in-memory `ActionMailer::Base.deliveries`; no external SMTP) |
-| development / production | `:smtp` unless the host explicitly sets `config.email.delivery_method` |
-
-Non-secret knobs live on `config.email.*` (defaults: `smtp.gmail.com`, port `587`, `plain`, STARTTLS auto). Secrets come from Credential Resolution:
-
-- `config.credentials.smtp.user_name` / `password`, or
-- ENV `GMAIL_USER_NAME` / `GMAIL_PASSWORD`
-
-`SmtpActionMailerBridge` merges resolved credentials into `action_mailer.smtp_settings` at the end of `CommandTower.configure`. Missing credentials fail at send when `raise_delivery_errors` is true. `From` uses the resolved SMTP username when present.
-
-Doctor does **not** probe SMTP connectivity.
-
-## Step 3 — Confirm mount path
-
-Ensure routes include something like:
-
-```ruby
-mount CommandTower::Engine => "/"   # or "/api"
-```
-
-Engine paths below are **relative to that mount**. Route area index: [Controllers](controllers.md).
-
-## Step 3b — Inherit execution-boundary bases
-
-Greenfield hosts should inherit CommandTower bases so Execution Context is established automatically:
-
-```ruby
-class ApplicationController < CommandTower::ApplicationController
-end
-
-class ApplicationJob < CommandTower::ApplicationJob
-end
-```
-
-Unauthenticated host endpoints (for example health checks) still receive HTTP `execution_uuid` / `correlation_id`. Successful authentication enriches the **same** context with `user_id` / `effective_user_id`.
-
-Workflows and services consume `CommandTower::Current` (or `execution_context`); they do not establish a new execution. For Rake/console, use `CommandTower.with_execution(source: :rake) { ... }`.
-
-`Auth::RequestContext` is JWT request/response transport, not Execution Context. Details: [Extending — Execution Context](extending.md#execution-context).
-
-Lifecycle and semantic events: [Eventing](eventing.md).
-
-If superclass inheritance is technically blocked, include `CommandTower::Execution::HttpBoundary` / `JobBoundary` on the host bases. That is an escape hatch, not the preferred contract.
-
-## Step 4 — Host RBAC (required)
-
-AuthorizeRequest **fails closed**. CommandTower ships **CT-owned** entity definitions (Me, session, inbox, Admin Workspace capabilities, …) and the platform full-access role (`owner`) in `lib/command_tower/authorization/default.yml`. CommandTower does **not** ship an operational `admin` role.
-
-The host YAML (default `config/rbac_groups.yml`) is a **second source**. Composition is additive. Hosts:
-
-1. Define product roles (typically `member`).
-2. **Grant names** of already-defined CT entities to those roles.
-3. Optionally define **host-owned** entities for **host** controllers.
-4. Deliberately compose operational Admin roles (least privilege or a broad host-owned `admin`).
-
-Do **not** copy CommandTower controller/entity blocks into the host file. Do **not** redefine `owner` or CT entity names. A host **may** define an `admin` group as host policy. Conflicts fail at boot (no last-write-wins).
-
-Dummy host grants-only example: [`rails_app/config/rbac_groups.yml`](../rails_app/config/rbac_groups.yml).
-
-```ruby
-CommandTower.configure do |c|
-  c.authorization.rbac_group_path = Rails.root.join("config/rbac_groups.yml")
-  c.authorization.default_membership_role = "member" # optional; nil disables
-end
-```
-
-`default_membership_role` is validated against the **composed** graph at boot. Unknown names fail configuration finalization.
-
-More: [Authorization](authorization.md), [Authentication & authorization guide](authentication_authorization_guide.md).
-
-Product audit names (later) register additively:
-
-```ruby
-CommandTower.configure do |c|
-  c.registry.audit.event :wager_placed do |event|
-    event.allowed_changes = %i[status]
-    event.user_history = true
-  end
-end
-```
-
-Do **not** redefine CommandTower-owned audit names. Audit rows persist in CommandTower after `command_tower:install:migrations` and `db:migrate`. See [Audit](audit.md).
-
-Admin Workspace tools register additively (navigation metadata, not a dispatcher):
-
-```ruby
-CommandTower.configure do |c|
-  c.registry.admin_workspace.tool :host_example do |tool|
-    tool.label = "Example"
-    tool.description = "Short launcher explanation of what this tool does."
-    tool.route = "/admin/example"
-    tool.group = :product
-    tool.sort_order = 300
-    tool.required_entity = :host_example_entity
-  end
-end
-```
-
-Do **not** redefine CommandTower-owned tool ids (`users`, `audit`, `messaging`). Hosts own copy for host tools (`description` soft ≤100 / hard ≤160). Manifest: [Admin Workspace](admin_workspace.md).
-
-Principal capabilities register additively (frontend-projectable ids, not a dump of all entities):
-
-```ruby
-CommandTower.configure do |c|
-  c.registry.principal_capabilities.capability :host_example do |capability|
-    capability.required_entity = :host_example_entity
-  end
-end
-```
-
-Do **not** redefine CommandTower-owned capability ids (`admin_workspace`, `admin_users`, `admin_impersonation`, `admin_audit_events`, `admin_messaging_announcements`). Projection: [Principal capabilities](principal_capabilities.md). Grant `admin_impersonation` only to roles that should start impersonation of visible users. Dummy `admin` does not include it.
-
-## Step 5 — Roles on users
-
-RBAC YAML defines what a role **may** do. Users still need that role assigned.
-
-- Specs and the dummy pattern use role name **`member`** for Me/Auth surfaces (including entity `principal_capabilities`).
-- When `authorization.default_membership_role` is set (for example `"member"`), register assigns that role **in the same transaction** as user create. Failure rolls back the user.
-- When it is `nil`, register does not attach roles. Hosts may assign via product logic, ops (`command_tower:users:create`), or other host workflows.
-- Installing CommandTower does **not** grant operational Admin access. Hosts must deliberately grant Admin entities.
-- Admin announcements need a host role that includes `admin_messaging_announcements`.
-- Admin Workspace manifest needs a host role that includes `admin_workspace`. Tool visibility still depends on each tool's `required_entity`.
-- `GET /auth/principal-capabilities` needs entity `principal_capabilities` on the caller’s roles (grant on `member` like session/me). Possessed Admin projectables still depend on the Admin entity grants above.
-- A host may define a broad `admin` role that grants many Admin entities — that is host policy, not a CommandTower default.
-## Step 6 — Enable feature gates you need
-
-When a gate is off, the route is **not drawn** → **404**.
-
-| Capability | Config |
-|------------|--------|
-| Plain-text login | `config.login.plain_text.enable = true` |
-| Email verification routes | `config.login.plain_text.email_verify = true` |
-| Password reset routes | `config.login.plain_text.password_reset = true` |
-| Email availability | `config.signup_session.email_availability = true` |
-| Username availability | `config.username.realtime_username_check = true` |
-
-Full gate list: [API reference — Feature gates](api_reference.md#feature-gates).
-
-## Step 7 — Choose auth client path
-
-- **API / mobile:** `Authorization: Bearer <jwt>` (default)
-- **Browser / SPA cookies:** enable `config.jwt.cookie` (+ CSRF as needed) — [Cookie authentication](cookie_authentication_guide.md)
-
-Engine HTTP success/error bodies use the application envelope `{ data, meta, errors }`. Host provisional helpers (`authenticate_user!`) can differ — [Authentication](authentication.md).
-
-## Step 8 — Smoke check
-
-With gates and RBAC in place (paths relative to your mount):
-
-1. `POST /auth/register` (always drawn) — with `default_membership_role` configured, the user is created **and** assigned that role in one transaction.
-2. `POST /auth/plain-text/login` (if enabled) — receive `data.token`.
-3. `GET /me` with Bearer token — expect **200** and envelope `data` (account payload).
-
-If you get **401**, authn failed. If you get **403**, fix Steps 4–5 before debugging clients.
-
-Contracts: [API reference](api_reference.md).
-
-## Step 9 — Messaging (when needed)
-
-Host owns:
-
-- Notification catalog / types
-- `platform_enabled_channels` / channel policy
-- Adapter credentials (email / SMS / Pushover)
-
-Emit from a **host product workflow** via `Communications::Produce` / `ProduceMany` — not by bypassing workflows. See [Messaging](messaging_integration_guide.md) and [Extending](extending.md).
-
-Phone/Pushover routes are always drawn; missing product readiness returns **503** capability errors.
-
-## Step 10 — Host tests
-
-```ruby
-require "command_tower/testing"
-CommandTower::Testing.install!
-```
-
-Details: [Testing](testing.md). Prefer `spec/requests/` patterns in the gem as HTTP contract proof.
-
-## Step 11 — Client version compatibility (optional)
-
-CommandTower can gate or warn on stale client app versions per platform, ahead of every request (before authn/authz). It is entirely opt-in: an untouched registry is a no-op, and the shipped CommandTower-owned catalog is empty by design.
-
-```ruby
-CommandTower.configure do |c|
-  c.registry.client_compatibility.mode = :observe # or :enforce; default observe
-
-  c.registry.client_compatibility.platform :web do |platform|
-    platform.minimum = "1.0.0"      # required; MAJOR.MINOR.PATCH[.prerelease]
-    platform.recommended = "1.2.0"  # optional; non-blocking upgrade guidance
-    # platform.update_url is forbidden on :web (web recovery is "reload", not a store)
-  end
-
-  c.registry.client_compatibility.platform :ios do |platform|
-    platform.minimum = "2.0.0"
-    platform.update_url = "https://apps.apple.com/app/id..."
-  end
-
-  # Optional: a capability-scoped floor stricter than the platform-global minimum,
-  # bound to an existing RBAC entity (see Step 4).
-  c.registry.client_compatibility.entity :some_host_entity do |entity|
-    entity.minimum.ios = "2.1.0"
-  end
-end
-```
-
-- Canonical platforms are `web` | `ios` | `android`. Configure only what your app ships — `android` unconfigured never fails boot on its own.
-- Zero configured platforms while otherwise opted in (non-default `mode`, any `entity`/`client_contract`/`bind`) fails boot fast; a completely untouched registry does not.
-- `X-App-Version` / `X-Client-Platform` request headers drive evaluation — never User-Agent, never an allowlist.
-- Every controller runs the check via `before_action :evaluate_client_compatibility!` on `CommandTower::ApplicationController`. Exempt a controller with `skip_before_action :evaluate_client_compatibility!`.
-- Process-level ENV overlays may only **raise** an already-configured platform's minimum, never lower it or configure a platform the host didn't enable: `COMMAND_TOWER_CLIENT_COMPATIBILITY_MODE=observe|enforce`, `COMMAND_TOWER_CLIENT_COMPATIBILITY_MINIMUM_WEB|IOS|ANDROID=<version>`.
-- In `:observe` mode nothing is ever blocked — decisions are logged only. In `:enforce` mode, an incompatible or unparseable identity renders HTTP `426` with a `client_update_required` error envelope.
-- Recommended-update guidance (when a client is compatible but below `recommended`) is surfaced only in `meta.clientCompatibility` on login and session-show responses — never on every response.
-
-## Done when
-
-- Doctor passes for secrets/migrations
-- Host `rbac_groups.yml` maps Me/Auth entities
-- Users who should use Me surfaces have the host `member` (or equivalent) role
-- Needed feature gates are enabled
-- `GET /me` returns **200** with a Bearer token for a member user
-
-## Common failures
-
-| Symptom | Likely cause |
-|---------|----------------|
-| Doctor green, `GET /me` is **403** | Missing host RBAC YAML or user lacks `member` (Steps 4–5) |
-| `POST /auth/plain-text/login` is **404** | `login.plain_text.enable?` off (Step 6) |
-| Password-reset / availability **404** | Matching feature gate off |
-| Phone / Pushover **503** | Capability / adapters not ready (Step 9) |
-| Confused error JSON on host controllers | Provisional `authenticate_user!` vs engine envelope (Step 7) |
-
-## Related
-
-- [Initializing](initializing.md)
-- [Extending](extending.md)
-- [API reference](api_reference.md)
-- [Authentication & authorization guide](authentication_authorization_guide.md)
-- [Messaging](messaging_integration_guide.md)
-- [README](../README.md)
+Do not treat this page as a second checklist. Follow the bootstrap README.

data/docs/initializing.md

@@ -1,31 +1,38 @@
 # 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).
+CommandTower is a Rails engine. This page is the **install / flags / schema / doctor contract**. A new host does not start here — follow [Bootstrap a new host](bootstrap/README.md) (Docker + Make, in order). That alone is not a fully usable Me/Auth host; bootstrap continues through RBAC, feature gates, and `GET /me`.
+
+Ruby/Rails runs **inside Compose**. Operator commands below are `make …`. `bin/rails command_tower:install` is the **task name** inside the container, not a host-machine command.
 
 Back to [README](../README.md).
 
 ## Quick start
 
-```bash
-# Gemfile: gem "command_tower"  (or path/git source)
-bundle install
+New hosts: [Bootstrap](bootstrap/README.md) (author Docker/Make first, then `make rails-new`, then pin the gem). After the gem is pinned:
 
-bin/rails command_tower:install
-bin/rails db:migrate
-bin/rails command_tower:doctor
+```bash
+make rails ARGS='command_tower:install'
+make migrate
+make doctor
 ```
 
 `command_tower:install` does **not** run `db:migrate`. Installing and migrating stay separate on purpose.
 
+If the host owns `/api/healthz` (or any route that must sit **before** the engine mount):
+
+```bash
+SKIP_MOUNT=1 make rails ARGS='command_tower:install'
+```
+
 ### After install
 
-Continue with [Host integration](host_integration_guide.md):
+Continue with [Bootstrap](bootstrap/README.md) from the RBAC / gates / smoke steps:
 
-1. Host `rbac_groups.yml` product role that **grants** CT-owned Me/Auth entity names (required — otherwise authenticated Me/Auth calls **403**)
+1. Host `rbac_groups.yml` product role that **grants** CT-owned Me/Auth entity names (required — otherwise authenticated Me/Auth calls **403**) — [`bootstrap/09-rbac.md`](bootstrap/09-rbac.md)
 2. Set `authorization.default_membership_role` (for example `"member"`) or assign roles some other supported way
 3. Enable feature gates you need (login, reset, availability, …)
-4. Smoke-check `GET /me` with a Bearer token
-5. Wire messaging catalog/adapters when you emit or use phone/Pushover
+4. Smoke-check `GET /me` — [`bootstrap/12-smoke-check.md`](bootstrap/12-smoke-check.md)
+5. Wire messaging catalog/adapters when you emit or use phone/Pushover — [`bootstrap/13-optional.md`](bootstrap/13-optional.md)
 
 ### What `command_tower:install` does
 
@@ -41,22 +48,24 @@ Continue with [Host integration](host_integration_guide.md):
 | `SKIP_MOUNT=1` | Generate initializer but do not mount routes |
 | `FORCE=1` | Overwrite an existing `config/initializers/command_tower.rb` |
 
-Examples:
+Examples (Make; flags enter the container via the `rails` recipe in [`bootstrap/01-docker-make-compose.md`](bootstrap/01-docker-make-compose.md)):
 
 ```bash
-SKIP_CONFIGURE=1 bin/rails command_tower:install
-SKIP_MOUNT=1 bin/rails command_tower:install
-FORCE=1 bin/rails command_tower:install
+SKIP_CONFIGURE=1 make rails ARGS='command_tower:install'
+SKIP_MOUNT=1 make rails ARGS='command_tower:install'
+FORCE=1 make rails ARGS='command_tower:install'
 ```
 
+Task names inside the container remain `command_tower:install` (and `command_tower:install:migrations`). Do not run `bin/rails` on the Mac.
+
 ## 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
+make rails ARGS='generate command_tower:configure'
+make rails ARGS='generate command_tower:configure --skip-routes'
+make rails ARGS='generate command_tower:configure --force'
 ```
 
 The generator:
@@ -75,8 +84,8 @@ CommandTower is the **sole authoring authority** for CommandTower-owned schema (
 Handled by `command_tower:install` (step 1). Equivalent migration-only command:
 
 ```bash
-bin/rails command_tower:install:migrations
-bin/rails db:migrate
+make rails ARGS='command_tower:install:migrations'
+make 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.
@@ -86,9 +95,9 @@ Rails may **retimestamp** newly copied host files. That is normal. Do not hand-e
 ### 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`.
+2. Run `SKIP_CONFIGURE=1 make rails ARGS='command_tower:install'` (or `make rails ARGS='command_tower:install:migrations'`).
+3. Run `make migrate`.
+4. Optionally run `make doctor`.
 
 Do not re-run configure on hosts that already customize the initializer unless you intend to regenerate it (`FORCE=1`).
 
@@ -120,7 +129,7 @@ The generated initializer documents available options via class_composer. Defaul
 ## Doctor
 
 ```bash
-bin/rails command_tower:doctor
+make 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.
@@ -151,12 +160,12 @@ Doctor does **not** probe Redis/SMTP connectivity.
 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
+SKIP_CONFIGURE=1 make rails ARGS='command_tower:install'
+# same task as: make rails ARGS='command_tower:install:migrations'
+make migrate
 ```
 
-Do not run `rails g command_tower:configure` unless you intentionally want stock scaffolding.
+Do not run `rails g command_tower:configure` unless you intentionally want stock scaffolding (`make rails ARGS='generate command_tower:configure'`).
 
 ## Test suite factories
 

data/docs/messaging_integration_guide.md

@@ -2,7 +2,7 @@
 
 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).
+Complete install and host RBAC first: [Bootstrap a new host](bootstrap/README.md) (through [`12-smoke-check.md`](bootstrap/12-smoke-check.md) before emitting or wiring phone/Pushover).
 
 ## Current surfaces
 

data/docs/principal_capabilities.md

@@ -86,4 +86,4 @@ Me/Auth route gates (`session`, `me`, …) and unimplemented Admin entities are
 - [API reference](api_reference.md#get-authprincipal-capabilities)
 - [Authorization](authorization.md)
 - [Admin Workspace](admin_workspace.md) — tool manifest only; not a UI permission probe
-- [Host integration](host_integration_guide.md)
+- [Bootstrap a new host](bootstrap/README.md)

data/docs/upgrades/0.10.0.md

@@ -3,7 +3,7 @@
 **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).
+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 [Bootstrap a new host](../bootstrap/README.md).
 
 ## Breaking / host-impact
 
@@ -31,15 +31,15 @@ This document summarizes **all changes from `main` through the `0.10.0` release*
 ## Documentation
 
 - Canonical HTTP catalog: [API reference](../api_reference.md)
-- Host start-here: [Host integration](../host_integration_guide.md)
+- Host start-here: [Bootstrap a new host](../bootstrap/README.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`.
+1. Bump gem to `0.10.0` and run `make rails ARGS='command_tower:install:migrations'` (or `SKIP_CONFIGURE=1 make rails ARGS='command_tower:install'`) then `make migrate`.
+2. Set JWT + signup/recovery session secrets; run `make doctor`.
 3. Add host `rbac_groups.yml` with a product role (typically `member`) that **grants** CT-owned entity names; do not redefine engine `owner` or copy CT controller mappings. Operational Admin roles are host-owned.
 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).
@@ -47,7 +47,7 @@ This document summarizes **all changes from `main` through the `0.10.0` release*
 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.
+New hosts: follow [Bootstrap a new host](../bootstrap/README.md) end-to-end.
 
 ## Related
 

data/docs/upgrades/0.11.0.md

@@ -3,7 +3,7 @@
 **From:** `0.10.0`  
 **To:** `0.11.0`
 
-This document summarizes **host-visible changes from `0.10.0` through the `0.11.0` release**. It is the durable upgrade / change SST for hosts already on the Auth/Me/Messaging platform. For a sequenced blank-host path, use [Host integration](../host_integration_guide.md).
+This document summarizes **host-visible changes from `0.10.0` through the `0.11.0` release**. It is the durable upgrade / change SST for hosts already on the Auth/Me/Messaging platform. For a sequenced blank-host path, use [Bootstrap a new host](../bootstrap/README.md).
 
 ## Breaking / host-impact
 
@@ -67,13 +67,13 @@ See dummy composition in `rails_app/config/rbac_groups.yml`.
 - [Audit](../audit.md)
 - [Admin Workspace](../admin_workspace.md)
 - [Principal capabilities](../principal_capabilities.md)
-- Host start-here: [Host integration](../host_integration_guide.md)
+- Host start-here: [Bootstrap a new host](../bootstrap/README.md)
 - Canonical HTTP catalog: [API reference](../api_reference.md)
 
 ## Upgrade checklist (existing 0.10.0 hosts)
 
-1. Bump gem to `0.11.0` and run `bin/rails command_tower:install:migrations` then `bin/rails db:migrate`.
-2. Run `bin/rails command_tower:doctor`.
+1. Bump gem to `0.11.0` and run `make rails ARGS='command_tower:install:migrations'` then `make migrate`.
+2. Run `make doctor`.
 3. Grant `principal_capabilities` (and `me_audit_events` if Account Activity is in product) on host `member` / equivalent.
 4. Explicitly grant Admin entities to **host-owned** operator roles (`admin_workspace`, `admin_users`, `admin_users_update`, `admin_rbac_assignments`, `admin_audit_events`, `admin_impersonation`) — do not assume a platform `admin` role.
 5. Point Admin FE gating at `GET /auth/principal-capabilities`, not `GET /admin/workspace`.
@@ -81,7 +81,7 @@ See dummy composition in `rails_app/config/rbac_groups.yml`.
 7. Smoke: login → `GET /auth/principal-capabilities` **200**; operator with grants → `GET /admin/workspace` **200**; without grants → **403**.
 8. Smoke: start impersonation → Admin routes **418**; `DELETE /auth/impersonation-session` restores actor.
 
-New hosts: follow [Host integration](../host_integration_guide.md) end-to-end (includes 0.10.0 foundations plus this release).
+New hosts: follow [Bootstrap a new host](../bootstrap/README.md) end-to-end (includes 0.10.0 foundations plus this release).
 
 ## Related
 

data/docs/upgrades/0.18.0.md

@@ -0,0 +1,35 @@
+# Upgrade: CommandTower 0.18.0
+
+**From:** `0.17.0`  
+**To:** `0.18.0`
+
+Minor release: inbox conversations. A host can stamp a stable key and title when it produces a message. The inbox list groups those messages. A conversation can be read as a window of at most 5 rendered documents. Accept stores the first presentation node's data so a later read does not recompute it. Two new migrations.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| `Produce` `conversation_key` / `conversation_title` | Optional pair. Both or neither. Stored on the Communication. Not part of the accept fingerprint or metadata. A replay keeps the first pair. A produce with no pair stays null and remains a standalone inbox row. |
+| `GET /me/inbox` | One entry per standalone message or per `conversation_key` in the requested scope. Each entry has `kind` (`message` or `conversation`), `id`, `title`, `preview`, `messageCount`, `unreadCount`, `read`, and `inboxItemIds`. Title and preview come from the latest in-scope member. |
+| `GET /me/inbox/conversation` | Members for `key` and `scope`, oldest first. Does not mark them viewed. `messageCount`, `unreadCount`, and `inboxItemIds` describe the whole scope. `messages` is the rendered slice. |
+| Window params | Optional and mutually exclusive: `around=oldest_unread`, `around=<inbox item id>`, `before`, or `after`, plus `limit`. A window renders at most 5. The first `around` window includes the oldest unread member (or the latest when none are unread), at most 2 older members, then newer members until the total is 5. Omitting the window params returns every member and no `window` key. |
+| Cursor errors | A cursor outside this recipient, key, and scope is `422`. An unknown key stays `404`. `limit` above 5, or combined cursors, is `422`. |
+| `inbox_presentation_snapshot` | Nullable JSON on `messaging_communications`. Accept captures the first presentation node inside the existing transaction. A failed capture stores `{ "v": 1, "omitted": true }`. No presentation node leaves the column null. Inbox detail reads the stored payload. |
+| RBAC | `conversation` is a new action on the existing Me inbox entity. |
+
+## Host actions
+
+1. Bump gem to `0.18.0` (or `>= 0.18.0`).
+2. Install and migrate:
+   - `bundle exec rails command_tower:install:migrations`
+   - `bundle exec rails db:migrate`
+   - New files: `20261010000001_add_inbox_presentation_snapshot_to_messaging_communications`, `20261010000002_add_conversation_identity_to_messaging_communications`.
+3. Pass `conversation_key` and `conversation_title` from Produce only when a message should join a conversation. Existing producers that omit the pair stay standalone. There is no backfill.
+4. If the host copied the Me inbox action list instead of granting the entity, add `conversation`. An entity grant already includes the new action.
+5. If the host parses `GET /me/inbox` items as one row per inbox item, read the grouped entry shape instead.
+
+## Not in this release
+
+- No backfill of historical conversation keys or presentation snapshots. Null stays null.
+- No Conversation table. Grouping is the key column plus the list query.
+- CommandTower frontend conversation feed, windowed scrolling, and narrow-web header. Those ship with the frontend package, not this gem.

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [0.18.0](0.18.0.md) | Inbox conversations: optional Produce identity, grouped list entries, `GET /me/inbox/conversation` window of at most 5, accept-time presentation snapshot |
 | [0.17.0](0.17.0.md) | Client-version-compatibility gating (`observe`/`enforce`); Rich Messaging Inbox `content` documents; host-overridable rendering templates; shared email theming |
 | [0.16.0](0.16.0.md) | Me experience-states (`GET`/`POST complete`); `host_key`; `user_experience_states` migration; `me_experience_states` RBAC |
 | [0.15.0](0.15.0.md) | Me `POST /me/push/test` → Produce (`push_delivery_test`); configurable Expo self-test rate limit composers; `me_push#test` |
@@ -15,4 +16,4 @@ Host-facing upgrade / change summaries for CommandTower releases.
 | [0.11.0](0.11.0.md) | Execution context, audit ledger, Admin Workspace, principal capabilities, impersonation, Admin Users |
 | [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).
+New hosts should start with [Bootstrap a new host](../bootstrap/README.md).

data/lib/command_tower/authorization/default.yml

@@ -33,6 +33,7 @@ entities:
     only:
       - index
       - show
+      - conversation
       - open
       - archive
       - destroy

data/lib/command_tower/install/baseline.rb

@@ -16,6 +16,8 @@ module CommandTower
         20260817000003_create_command_tower_impersonation_sessions.rb
         20260826140000_add_deleted_at_to_users.rb
         20260906180000_create_user_experience_states.rb
+        20261010000001_add_inbox_presentation_snapshot_to_messaging_communications.rb
+        20261010000002_add_conversation_identity_to_messaging_communications.rb
       ].freeze
 
       module_function

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.17.0"
+  VERSION = "0.18.0"
 end