command_tower 0.16.0 → 0.18.0

data/app/workflows/command_tower/workflows/client_compatibility/evaluate_workflow.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module ClientCompatibility
+      # Orchestrates one HTTP request's client-version-compatibility check.
+      # Maps the pure `Services::ClientCompatibility::Evaluate` projection to
+      # a `WorkflowResult`, and is the only layer (along with the boundary)
+      # allowed to place recommendation metadata onto `CommandTower::Current`
+      # — `Evaluate` itself never touches `Current` (authority §10, §13).
+      class EvaluateWorkflow < CommandTower::Workflows::ApplicationWorkflow
+        retry_strategy :none
+
+        APP_VERSION_HEADER = "X-App-Version"
+        PLATFORM_HEADER = "X-Client-Platform"
+
+        def call(request:, controller_class:, action_name:)
+          decision = CommandTower::Services::ClientCompatibility::Evaluate.call(
+            app_version_header: request.headers[APP_VERSION_HEADER],
+            platform_header: request.headers[PLATFORM_HEADER],
+            controller_class: controller_class,
+            action_name: action_name
+          )
+
+          mode = CommandTower.config.registry.client_compatibility.mode
+          enforced = mode == :enforce
+          blocked = enforced && decision.incompatible?
+
+          log_decision(decision, mode:, enforced:, blocked:)
+          stash_recommendation!(decision)
+
+          if blocked
+            return failure(
+              errors: [CommandTower::Errors::ClientUpdateRequiredError.new(details: details_for(decision))],
+              http_status: :upgrade_required
+            )
+          end
+
+          success(payload: { decision: decision })
+        end
+
+        private
+
+        def stash_recommendation!(decision)
+          return unless decision.recommendation_projection
+
+          CommandTower::Current.client_compatibility_recommendation = decision.recommendation_projection
+        end
+
+        def details_for(decision)
+          {
+            platform: decision.platform&.to_s,
+            scope: decision.scope&.to_s,
+            currentVersion: decision.current_version,
+            minimumVersion: decision.effective_minimum,
+            recovery: decision.recovery&.to_s,
+            updateUrl: decision.update_url
+          }.compact
+        end
+
+        # Structured (non-audit) decision log via the semantic `command_tower.log.*`
+        # event contract (authority §20). Workflows must not write lifecycle
+        # observation directly to `Rails.logger` — `publish_event` routes
+        # through `CommandTower::Logging::Subscriber` like every other
+        # semantic log line.
+        def log_decision(decision, mode:, enforced:, blocked:)
+          payload = {
+            message: "client_compatibility.evaluated",
+            mode: mode,
+            enforced: enforced,
+            platform: decision.platform,
+            app_version: decision.current_version,
+            matched_entities: decision.matched_entity_names,
+            decision: decision.decision,
+            http_status: blocked ? 426 : nil
+          }.compact
+
+          publish_event(category: :log, name: blocked ? :warn : :info, payload:)
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/client_compatibility/recommendation_meta.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module ClientCompatibility
+      # Shared sequence fragment: reads the recommendation projection that
+      # `EvaluateWorkflow` stashed on `Current` (never written by `Evaluate`
+      # itself) and shapes it into `WorkflowResult.meta`. Included only by
+      # Login and Session::Show — recommended-update guidance is deliberately
+      # not attached to every success envelope (authority §13).
+      module RecommendationMeta
+        extend ActiveSupport::Concern
+
+        private
+
+        def client_compatibility_meta
+          recommendation = CommandTower::Current.client_compatibility_recommendation
+          return {} if recommendation.blank?
+
+          { clientCompatibility: recommendation }
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/messaging/communications/produce_recipient_workflow.rb

@@ -15,7 +15,9 @@ module CommandTower
             title:,
             body:,
             platform_enabled_channels:,
-            metadata: nil
+            metadata: nil,
+            conversation_key: nil,
+            conversation_title: nil
           )
             user = User.find_by(id: user_id)
             unless user
@@ -34,6 +36,8 @@ module CommandTower
               body:,
               metadata:,
               platform_enabled_channels:,
+              conversation_key:,
+              conversation_title:,
             )
 
             unless result.success?

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/api_reference.md

@@ -338,8 +338,8 @@ Pagination for list: query `limit` (default **50**, max **100**), `offset` (defa
 | Method | Path | Notes |
 |--------|------|--------|
 | `GET` | `/me/inbox` | List — `data` array of items; pagination meta |
-| `GET` | `/me/inbox/:id` | Detail (+ `body`, `metadata`, `notificationTypeKey`) |
-| `POST` | `/me/inbox/:id/open` | Detail |
+| `GET` | `/me/inbox/:id` | Detail (+ `body`, `metadata`, `notificationTypeKey`, `content`) |
+| `POST` | `/me/inbox/:id/open` | Detail (+ `content`) |
 | `PATCH` | `/me/inbox/:id/archive` | Item |
 | `DELETE` | `/me/inbox/:id` | `data: null` |
 | `GET` | `/me/inbox/unread-count` | `{ count }` |
@@ -349,6 +349,17 @@ Pagination for list: query `limit` (default **50**, max **100**), `offset` (defa
 | `POST` | `/me/inbox/bulk/restore` | same |
 | `POST` | `/me/inbox/bulk/delete` | same |
 
+**`content` (detail only, response-only — `inbox_document_v1`):** rendered at read from the item's `Communication`, never persisted; absent from list items. Shape: `{ schema: "inbox_document_v1", blocks: [...] }`. Allowlisted block types:
+
+| Block | Fields | Notes |
+|-------|--------|-------|
+| `paragraph` | `text` (string) | |
+| `cta` | `label` (string), `href` (string) | `href` must be `http(s)` or a custom scheme (e.g. `pickem://...`); `javascript:`/`data:`/`vbscript:`, schemeless, blank, and unparsable hrefs are rejected — the `cta` block is simply omitted, never an error |
+
+Generic (default) rendering: one `paragraph` block from `communication.body` (omitted if blank — `blocks` can legitimately be `[]`), plus one `cta` block if `metadata.deep_link` is a safe href (label from `metadata.cta_label`, default `"Open"`).
+
+Hosts may override the document per `notificationTypeKey` with an `inbox_document.json.erb` view at `app/views/command_tower/messaging/rendering/<notification_type_key>/inbox_document.json.erb` (same lookup convention as [`messaging_integration_guide.md`](messaging_integration_guide.md#rendering-template-overrides)). Any failure resolving or rendering that template (missing file, malformed JSON, wrong `schema`/`blocks` shape, or a raising template) fails open to the generic document — the Inbox read path never 500s on a bad type template. A valid envelope with one invalid/unknown block strips only that block; if stripping empties `blocks`, the generic document is used instead.
+
 **List item fields:** `id`, `title`, `status`, `read`, `viewedAt`, `createdAt`, `updatedAt`.
 
 **Errors:** `401` / `403` / `422`; show/open may return `404` `not_found`.

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).