command_tower 0.17.0 → 0.18.0

data/app/workflows/command_tower/workflows/messaging/inbox.rb

@@ -26,12 +26,26 @@ module CommandTower
             result = CommandTower::Services::Messaging::Inbox::List.call(user:, limit:, offset:, scope:)
             return result_or_failure(result) unless result.success?
 
-            payload = result.data[:items].map { |item| CommandTower::Serializers::Messaging::Inbox::ItemSerializer.serialize(item) }
+            payload = result.data[:items].map { |item| CommandTower::Serializers::Messaging::Inbox::EntrySerializer.serialize(item) }
             meta = CommandTower::Serializers::Messaging::Inbox::PaginationMetaSerializer.serialize(result.data[:pagination])
             success(payload:, meta:, http_status: :ok)
           end
         end
 
+        class ConversationWorkflow < BaseWorkflow
+          def call(user:, key:, scope:, around: nil, before_id: nil, after_id: nil, limit: nil)
+            result = CommandTower::Services::Messaging::Inbox::Conversation.call(
+              user:, key:, scope:, around:, before_id:, after_id:, limit:,
+            )
+            return result_or_failure(result) unless result.success?
+
+            success(
+              payload: CommandTower::Serializers::Messaging::Inbox::ConversationSerializer.serialize(result.data[:conversation]),
+              http_status: :ok,
+            )
+          end
+        end
+
         class ShowWorkflow < BaseWorkflow
           def call(user:, inbox_item_id:)
             result = CommandTower::Services::Messaging::Inbox::Show.call(user:, inbox_item_id:)

data/config/routes.rb

@@ -64,6 +64,7 @@ CommandTower::Engine.routes.draw do
 
     resources :inbox, only: [:index, :show, :destroy], controller: "inbox" do
       collection do
+        get :conversation
         get :unread_count, path: "unread-count"
         post "bulk/read", action: :bulk_read
         post "bulk/unread", action: :bulk_unread

data/db/migrate/20261010000001_add_inbox_presentation_snapshot_to_messaging_communications.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddInboxPresentationSnapshotToMessagingCommunications < ActiveRecord::Migration[7.2]
+  def change
+    add_column :messaging_communications, :inbox_presentation_snapshot, :json
+  end
+end

data/db/migrate/20261010000002_add_conversation_identity_to_messaging_communications.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class AddConversationIdentityToMessagingCommunications < ActiveRecord::Migration[7.2]
+  def change
+    add_column :messaging_communications, :conversation_key, :string, limit: 128
+    add_column :messaging_communications, :conversation_title, :string
+    add_index :messaging_communications, %i[user_id conversation_key],
+              name: "index_messaging_communications_on_user_and_conversation_key"
+  end
+end

data/docs/authorization.md

@@ -2,7 +2,7 @@
 
 Authorization establishes **permission** after authentication. Failed authorization returns `403`.
 
-Host `rbac_groups.yml` is a **required integration step** (Step 4) — see [Host integration](host_integration_guide.md#step-4--host-rbac-required). 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**.
+Host `rbac_groups.yml` is a **required integration step** — see [Bootstrap — RBAC](bootstrap/09-rbac.md). 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)
 

data/docs/bootstrap/00-ownership.md

@@ -0,0 +1,77 @@
+# 00 — Ownership
+
+## Purpose
+
+Know what CommandTower owns vs what the host owns **before** you generate a Rails app. Wrong ownership here produces forked platform code and duplicate schema.
+
+## Prerequisites
+
+Read [`README.md`](README.md). This step is conceptual; no files yet.
+
+## Engine vs host
+
+CommandTower is a **mountable Rails engine**. The host is a Rails API application that:
+
+- Depends on the `command_tower` gem
+- Runs install/migrate/doctor **inside Compose**
+- Mounts the engine
+- Configures secrets, RBAC composition, and feature gates
+- Adds **product** routes, workflows, and schema
+
+The engine owns:
+
+- CommandTower-owned schema (users, sessions, JWT-related tables, Me/Auth, messaging platform tables, and the rest of the engine `db/migrate`)
+- Platform HTTP under the mount
+- Workflow / service / serializer framework
+- Default entity catalog (`lib/command_tower/authorization/default.yml`)
+- Shared FactoryBot definitions
+
+The host owns:
+
+- `Dockerfile`, `docker-compose.yml`, `Makefile`
+- Product schema, product routes, product workflows
+- `config/initializers/command_tower.rb` after generate
+- `config/rbac_groups.yml` (grants of **CT entity names** plus host-owned entities)
+- Secrets in Compose / env
+- Feature-gate choices
+- Messaging catalogs and adapter credentials (optional)
+
+## Schema (AD-SCH-01)
+
+CommandTower is the **sole authoring authority** for CommandTower-owned schema. Hosts must **not** manually write, edit, or copy-paste CommandTower schema migrations.
+
+Hosts install copies via `command_tower:install` / `command_tower:install:migrations`, then `db:migrate`. Installed `*.command_tower.rb` files are an **execution context**, not a second authoring home.
+
+Contract: [`../initializing.md`](../initializing.md).
+
+## Workflow layer
+
+Meaningful business behavior enters through a **workflow**. Controllers, jobs, and scheduled tasks do not call services as a full business action. Workflows do not call other workflows (extract a shared sequence). See [`../architecture.md`](../architecture.md).
+
+Do not invent a parallel “manager” layer.
+
+## Dummy `rails_app` is not a product template
+
+[`../../rails_app/`](../../rails_app/) is the **in-engine dummy host** used to develop and test the gem. Later steps cite its initializer and `rbac_groups.yml` for **shape**.
+
+Do not copy `rails_app/` as a new product. Do not copy this gem’s [`docker-compose.yaml`](../../docker-compose.yaml) (`mysql:latest`, engine ports) — that file is for **engine development**, not a product host.
+
+This tree writes **generic** Makefile / Compose templates in [`01-docker-make-compose.md`](01-docker-make-compose.md).
+
+## Docker-only
+
+No Ruby or Rails on the host OS. See the README **Docker-only** section. Step 01 exists so `rails new` never runs on the Mac.
+
+## What a platform-proof host is
+
+Enough to:
+
+1. Boot in Compose
+2. Pass `make doctor`
+3. Register, log in, and receive **200** from `GET /me` as a `member`
+
+Product domain, Solid Queue workers, SMS/Pushover adapters, and admin RBAC bundles are **not** required to finish this manual.
+
+## Stop
+
+You can explain engine vs host, AD-SCH-01, and why Docker exists before `rails new`. Next: [`01-docker-make-compose.md`](01-docker-make-compose.md).

data/docs/bootstrap/01-docker-make-compose.md

@@ -0,0 +1,267 @@
+# 01 — Docker, Make, Compose
+
+## Purpose
+
+Author the local toolchain **before** any Rails app exists. After this step you can `make help` and `make build` on an empty repository. Ruby is only inside the image.
+
+## Prerequisites
+
+- Docker Desktop (or equivalent) with the Compose plugin
+- Make
+- Git
+- Empty (or nearly empty) host repository
+
+Do **not** install Ruby, Bundler, or Rails on the Mac.
+
+## Files the host creates
+
+| File | Role |
+|------|------|
+| `Dockerfile` | Ruby image: Bundler, MariaDB client, Node (asset/JS tooling if needed) |
+| `docker-compose.yml` | `api`, MariaDB **10.11+**, Redis |
+| `Makefile` | Operator surface: `build`, `rails-new`, `rails`, `migrate`, `doctor`, … |
+| `.dockerignore` | Keep the build context small |
+| `.env` (gitignored) | Local secrets later ([`04-secrets-and-env.md`](04-secrets-and-env.md)); create a stub if Compose interpolates vars |
+
+The database in **this recipe** is MariaDB 10.11+ with `utf8mb4` / `utf8mb4_unicode_ci`. That is a host choice documented here. Do not copy the gem’s engine-dev compose (`mysql:latest`).
+
+Redis is required for CommandTower cache/features that expect it. Optional `worker` is only if the host uses Solid Queue (add after the app exists).
+
+## Procedure
+
+### 1. `.dockerignore`
+
+```
+.git
+log
+tmp
+.env
+coverage
+vendor/bundle
+node_modules
+.DS_Store
+```
+
+### 2. `Dockerfile`
+
+Use an MRI image CommandTower’s doctor accepts (Rails **>= 7 and < 9**). A current floor that matches engine CI is Ruby **4.0.x** and Rails **8.1**. Do not freeze an older patch than the gem you will pin in step 03.
+
+The image must **bind Puma on `0.0.0.0`**. Binding `127.0.0.1` inside the container is not reachable from the Mac.
+
+```dockerfile
+FROM ruby:4.0.1
+
+ENV RAILS_LOG_TO_STDOUT=1
+ENV BUNDLE_PATH=/usr/local/bundle
+ENV BUNDLE_JOBS=4
+
+RUN apt-get update -qq && apt-get install --no-install-recommends -y \
+    build-essential \
+    git \
+    default-libmysqlclient-dev \
+    default-mysql-client \
+    libyaml-dev \
+    pkg-config \
+    redis-tools \
+  && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Gemfile does not exist until `make rails-new`. Copy the context; install gems when present.
+COPY . .
+RUN if [ -f Gemfile ]; then bundle install; fi
+
+EXPOSE 3000
+CMD ["bundle", "exec", "bin/rails", "server", "-b", "0.0.0.0", "-p", "3000"]
+```
+
+Until [`02-create-the-rails-app.md`](02-create-the-rails-app.md) runs, there is **no** `Gemfile`. That is expected. `make build` still produces an image with Ruby, Bundler, and the MariaDB client. `make rails-new` uses that image.
+
+After `rails new` you will have a Gemfile; rebuild so `bundle install` during image build caches gems. Day-to-day `make bundle` still refreshes gems in the running volume.
+
+### 3. `docker-compose.yml`
+
+```yaml
+services:
+  api:
+    build: .
+    working_dir: /app
+    command: bundle exec bin/rails server -b 0.0.0.0 -p 3000
+    volumes:
+      - .:/app
+      - bundle_cache:/usr/local/bundle
+    ports:
+      - "3000:3000"
+    environment:
+      RAILS_ENV: development
+      DATABASE_URL: mysql2://app:app@db:3306/app_development
+      REDIS_URL: redis://redis:6379/0
+      SECRET_KEY_BASE: ${SECRET_KEY_BASE:-dev-secret-key-base-change-me}
+      SIGNUP_SESSION_JWT_SECRET: ${SIGNUP_SESSION_JWT_SECRET:-dev-signup-session-change-me}
+      PASSWORD_RECOVERY_SESSION_JWT_SECRET: ${PASSWORD_RECOVERY_SESSION_JWT_SECRET:-dev-password-recovery-change-me}
+      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-http://localhost:8081,http://localhost:8082,http://localhost:19006}
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_started
+    stdin_open: true
+    tty: true
+
+  db:
+    image: mariadb:10.11
+    environment:
+      MARIADB_ROOT_PASSWORD: root
+      MARIADB_DATABASE: app_development
+      MARIADB_USER: app
+      MARIADB_PASSWORD: app
+    ports:
+      - "3306:3306"
+    volumes:
+      - mariadb_data:/var/lib/mysql
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  bundle_cache:
+  mariadb_data:
+```
+
+Rename `app_development` / user / password to product names when you have them. Keep utf8mb4.
+
+`command:` (and the Dockerfile `CMD`) must use `-b 0.0.0.0`. Without it, `make server` is not reachable from the Mac or from an Expo app on the host OS.
+
+Published port **3000** is this recipe’s default for a single local API. The frontend `HostConfig` API origin must use the **same** host-published port. A second Command Tower API on this machine publishes a different host port. Engine-dev compose in this gem uses different ports; ignore it.
+
+`CORS_ALLOWED_ORIGINS` in the sample (`8081`, `8082`, `19006`) is one web product’s origins. A second local web app uses its own Expo port. Change that origin, this API’s published port, and `config.application.url` (step 08) together. The list is consumed in [`11-auth-client-path.md`](11-auth-client-path.md). `curl` on the Mac does not need CORS.
+
+### 4. `Makefile`
+
+Generic operator surface. `COMPOSE` is the only Compose invocation.
+
+```makefile
+.PHONY: help build bundle setup fresh rebuild rails-new rails db-prepare migrate doctor \
+	bash console runner server s halt down down-v rspec test spec rubocop
+
+COMPOSE := docker compose
+API    := $(COMPOSE) run --rm api
+API_T  := $(COMPOSE) run --rm -T api
+
+help:
+	@echo "build       Build the api image"
+	@echo "bundle      bundle install in the container"
+	@echo "setup       build + db-prepare"
+	@echo "fresh       down-v + setup"
+	@echo "rebuild     build --no-cache + bundle"
+	@echo "rails-new   rails new (API) inside the container"
+	@echo "rails       Forward to bin/rails (ARGS=...)"
+	@echo "db-prepare  db:prepare"
+	@echo "migrate     db:migrate"
+	@echo "doctor      command_tower:doctor"
+	@echo "bash        Shell in api"
+	@echo "console     rails console"
+	@echo "runner      rails runner CMD='...'"
+	@echo "server / s  Foreground api server"
+	@echo "halt        Stop compose"
+	@echo "down        compose down"
+	@echo "down-v      compose down -v (destroys DB volume)"
+	@echo "rspec/test  rspec"
+	@echo "spec        rspec SPEC=path"
+	@echo "rubocop     rubocop"
+
+build:
+	$(COMPOSE) build api
+
+bundle:
+	$(API) bundle install
+
+setup: build db-prepare
+
+fresh: down-v setup
+
+rebuild:
+	$(COMPOSE) build --no-cache api
+	$(MAKE) bundle
+
+# Chicken-and-egg: image has Ruby; Gemfile may not exist yet.
+# Doctor accepts Rails >= 7 and < 9. Prefer 8.1 to match current engine CI.
+RAILS_NEW_VERSION ?= ~> 8.1.0
+rails-new:
+	$(API) bash -lc 'gem install rails -v "$(RAILS_NEW_VERSION)" --no-document && rails new . --api --database=mysql --skip-git --force'
+
+rails:
+	$(COMPOSE) run --rm -e SKIP_MOUNT -e SKIP_CONFIGURE -e FORCE api bundle exec bin/rails $(ARGS)
+
+db-prepare:
+	$(API) bundle exec bin/rails db:prepare
+
+migrate:
+	$(API) bundle exec bin/rails db:migrate
+
+doctor:
+	$(API) bundle exec bin/rails command_tower:doctor
+
+bash:
+	$(COMPOSE) run --rm api bash
+
+console:
+	$(API) bundle exec bin/rails console
+
+runner:
+	$(API) bundle exec bin/rails runner "$(CMD)"
+
+server s:
+	$(COMPOSE) up api
+
+halt:
+	$(COMPOSE) stop
+
+down:
+	$(COMPOSE) down
+
+down-v:
+	$(COMPOSE) down -v
+
+rspec test:
+	$(API_T) bundle exec rspec
+
+spec:
+	$(API_T) bundle exec rspec $(SPEC)
+
+rubocop:
+	$(API_T) bundle exec rubocop
+```
+
+`rails-new` installs the Rails **gem inside the ephemeral container** and writes the app onto the mounted `/app`. That is still Docker-only: the Mac never runs `gem` or `rails`.
+
+After the app exists, prefer `make rails ARGS='…'` over re-running `rails-new`.
+
+Flags such as `SKIP_MOUNT=1` belong on the Make line. The `rails` recipe forwards `SKIP_MOUNT`, `SKIP_CONFIGURE`, and `FORCE` into the container:
+
+```bash
+SKIP_MOUNT=1 make rails ARGS='command_tower:install'
+```
+
+### 5. Build
+
+```bash
+make help
+make build
+```
+
+`make build` may warn that `Gemfile` is missing. That is expected until step 02.
+
+## Stop
+
+`make help` prints the operator surface. `make build` produces an `api` image with Ruby. There is still no Rails application. Next: [`02-create-the-rails-app.md`](02-create-the-rails-app.md).

data/docs/bootstrap/02-create-the-rails-app.md

@@ -0,0 +1,75 @@
+# 02 — Create the Rails app
+
+## Purpose
+
+Generate a Rails **8.1 API** application **inside the Compose image**. The host OS never receives a `rails` binary.
+
+## Prerequisites
+
+- [`01-docker-make-compose.md`](01-docker-make-compose.md) complete: `make build` works
+- Working directory is the host repository (already contains Dockerfile / Compose / Makefile)
+
+## Files this step creates (inside the container, onto the mount)
+
+Rails’ `rails new .` writes `Gemfile`, `config/`, `app/`, `bin/`, and the rest of a standard API app into the current directory.
+
+`--force` is required because Dockerfile, Compose, and Makefile already exist.
+
+## Procedure
+
+```bash
+make rails-new
+```
+
+That target (from step 01) runs in the `api` service:
+
+```text
+gem install rails -v "~> 8.1.0" --no-document
+rails new . --api --database=mysql --skip-git --force
+```
+
+Both commands run **in the container**. `--skip-git` avoids nesting a repo; you already have Git on the host. `--database=mysql` matches MariaDB via the `mysql2` adapter.
+
+If `rails new` overwrites `Dockerfile`, `docker-compose.yml`, or `Makefile`, **restore the files from step 01**. Rails generators are not the source of the host toolchain. Confirm `command:` / `CMD` still bind `-b 0.0.0.0`.
+
+Then add host gems CommandTower does not replace. In `Gemfile` (keep `mysql2` and `puma` from `rails new`):
+
+```ruby
+gem "rack-cors"
+```
+
+`command_tower` (step 03) already depends on `redis`. You do not need a second Redis gem unless the host uses Redis for its own cache.
+
+Set `config/database.yml` so development points at the `db` service, not `localhost` on the Mac:
+
+```yaml
+development:
+  adapter: mysql2
+  encoding: utf8mb4
+  collation: utf8mb4_unicode_ci
+  url: <%= ENV.fetch("DATABASE_URL") %>
+```
+
+Leave test until you add a test database; `db:prepare` can create it later.
+
+Local mail for verify/reset codes (Compose-mounted `tmp/` is visible on the Mac):
+
+```ruby
+# config/environments/development.rb
+config.action_mailer.perform_deliveries = true
+config.action_mailer.delivery_method = :file
+config.action_mailer.file_settings = { location: Rails.root.join("tmp/mails") }
+```
+
+Then:
+
+```bash
+make build
+make bundle
+```
+
+Do not run `rails new` on the Mac. Do not `brew install ruby` to make this step “easier.”
+
+## Stop
+
+`Gemfile` exists, `bin/rails` exists **in the repo** (executed only via `make rails`). Dockerfile/Compose from step 01 are still the operator toolchain. `make bundle` succeeds. Next: [`03-pin-the-gem.md`](03-pin-the-gem.md).

data/docs/bootstrap/03-pin-the-gem.md

@@ -0,0 +1,53 @@
+# 03 — Pin the CommandTower gem
+
+## Purpose
+
+Depend on released CommandTower from **RubyGems** (or a git tag). Path pins are maintainer Local mode, not the committed default for a new host.
+
+## Prerequisites
+
+- [`02-create-the-rails-app.md`](02-create-the-rails-app.md): `make bundle` works
+- You know the CommandTower version (or git tag) this host should adopt
+
+## Files the host edits
+
+`Gemfile` — add:
+
+```ruby
+gem "command_tower"
+```
+
+Pin when you need a floor:
+
+```ruby
+gem "command_tower", "~> X.Y"
+```
+
+Git tag (only if your org does not publish the gem to the RubyGems source the host uses):
+
+```ruby
+gem "command_tower", git: "https://github.com/<org>/command_tower.git", tag: "vX.Y.Z"
+```
+
+**Path pins** (`path: "../command_tower"`) are for engine maintainers iterating locally. They are not the default a new product host commits. If you use a path pin in a workspace, do not document it as the production pin.
+
+## Procedure
+
+1. Add the gem line.
+2. Refresh lockfile **in the container**:
+
+```bash
+make bundle
+```
+
+3. Rebuild if the image copies `Gemfile` / `Gemfile.lock` at build time:
+
+```bash
+make build
+```
+
+Do not run `bundle install` on the Mac.
+
+## Stop
+
+`Gemfile.lock` lists `command_tower`. `make bundle` succeeds. Next: [`04-secrets-and-env.md`](04-secrets-and-env.md).

data/docs/bootstrap/04-secrets-and-env.md

@@ -0,0 +1,59 @@
+# 04 — Secrets and env
+
+## Purpose
+
+Give Compose the secrets CommandTower **doctor** requires. Without them, install may succeed and doctor will fail.
+
+## Prerequisites
+
+- [`03-pin-the-gem.md`](03-pin-the-gem.md)
+- Compose file from [`01-docker-make-compose.md`](01-docker-make-compose.md)
+
+## Files the host creates / edits
+
+| File | Role |
+|------|------|
+| `.env` (gitignored) | Local values interpolated by Compose |
+| `.env.example` (committed, no secrets) | Names only |
+| `docker-compose.yml` `environment:` | Already stubbed in step 01 |
+
+Required (names match [`../initializing.md`](../initializing.md)):
+
+| Secret | Typical env | Used for |
+|--------|-------------|----------|
+| JWT HMAC | `SECRET_KEY_BASE` (or `config.jwt.hmac_secret`) | Access tokens |
+| Signup-session JWT | `SIGNUP_SESSION_JWT_SECRET` | Email verification / signup session |
+| Password-recovery JWT | `PASSWORD_RECOVERY_SESSION_JWT_SECRET` | Password reset session |
+
+Doctor checks these. Failures abort with remediation text.
+
+`.env.example`:
+
+```
+SECRET_KEY_BASE=
+SIGNUP_SESSION_JWT_SECRET=
+PASSWORD_RECOVERY_SESSION_JWT_SECRET=
+```
+
+Generate long random values for `.env`. Do not commit `.env`. Do not reuse production secrets in development.
+
+The initializer generated in step 05 can read these via `ENV.fetch`. You do not need a complete initializer yet.
+
+Optional later: SMTP, SMS, Pushover credentials — [`13-optional.md`](13-optional.md) and [`../messaging_integration_guide.md`](../messaging_integration_guide.md). Not required for `GET /me`.
+
+This step is **local** env for Compose. Production secret distribution is out of scope ([README](README.md#this-is-not-deployment)).
+
+## Procedure
+
+1. Create `.env` with three distinct secrets.
+2. Confirm `docker-compose.yml` passes them into `api`.
+3. Recreate the api container if it was already running:
+
+```bash
+make halt
+make build
+```
+
+## Stop
+
+Compose interpolates the three secrets into `api`. Next: [`05-install-migrate-doctor.md`](05-install-migrate-doctor.md).

data/docs/bootstrap/05-install-migrate-doctor.md

@@ -0,0 +1,74 @@
+# 05 — Install, migrate, doctor
+
+## Purpose
+
+Copy engine migrations, generate the initializer (and default mount unless skipped), migrate, and run doctor. **Invocation is Make.** The contract for flags and schema is [`../initializing.md`](../initializing.md) — do not treat this page as a second copy of that contract.
+
+## Prerequisites
+
+- [`04-secrets-and-env.md`](04-secrets-and-env.md)
+- Database service healthy (`make` recipes that run Rails will start `depends_on`)
+
+## Files this step creates
+
+| File | Role |
+|------|------|
+| `db/migrate/*command_tower.rb` | Installed copies of engine migrations (do not hand-edit) |
+| `config/initializers/command_tower.rb` | Generated unless `SKIP_CONFIGURE=1` |
+| Engine mount in `config/routes.rb` | Unless `SKIP_MOUNT=1` or `--skip-routes` |
+
+`command_tower:install` does **not** run `db:migrate`. Installing and migrating stay separate on purpose.
+
+## Procedure
+
+If the host will own `GET /api/healthz` (or any route that must be declared **before** the engine mount), skip the generator mount and add routes in [`06-mount-and-health.md`](06-mount-and-health.md):
+
+```bash
+make rails ARGS='command_tower:install' SKIP_MOUNT=1
+```
+
+Otherwise:
+
+```bash
+make rails ARGS='command_tower:install'
+```
+
+Then:
+
+```bash
+make db-prepare
+make migrate
+make doctor
+```
+
+`db-prepare` creates the development database if needed. `migrate` applies host and CommandTower migrations.
+
+Existing customized hosts (initializer and mount already present):
+
+```bash
+make rails ARGS='command_tower:install' SKIP_CONFIGURE=1
+make migrate
+make doctor
+```
+
+`FORCE=1` overwrites `config/initializers/command_tower.rb` — do not use it after you have customized the initializer unless you intend to regenerate.
+
+The **task name** inside the container is `bin/rails command_tower:install`. Operators never type that on the Mac.
+
+### What install does (summary)
+
+1. `command_tower:install:migrations` — copies engine migrations with `*.command_tower.rb` scope.
+2. `rails g command_tower:configure` unless skipped — initializer + mount.
+3. Prints next steps.
+
+Full flag table: [`../initializing.md`](../initializing.md).
+
+Doctor checks Rails compatibility, engine baseline migrations, host-installed copies, JWT / session secrets, and messaging adapter names. It does **not** probe Redis/SMTP connectivity.
+
+## In-engine dummy
+
+Generated initializer shape: [`../../rails_app/config/initializers/command_tower.rb`](../../rails_app/config/initializers/command_tower.rb). That file is a dummy-host example, not a product dump.
+
+## Stop
+
+Install is idempotent if re-run. Migrations applied. `make doctor` exits 0 (or you have a documented doctor failure you will fix in steps 08–10). Next: [`06-mount-and-health.md`](06-mount-and-health.md).