command_tower 0.16.0 → 0.18.0

data/docs/bootstrap/13-optional.md

@@ -0,0 +1,50 @@
+# 13 — Optional (messaging, tests, client-version compatibility)
+
+## Purpose
+
+After `GET /me` works, add platform extras **only if the product needs them**. A platform-proof host may skip this file and run [`14-sanity-checks.md`](14-sanity-checks.md).
+
+## Prerequisites
+
+- [`12-smoke-check.md`](12-smoke-check.md) passed
+
+Do not start here. Messaging and CVC assume install, RBAC, and gates already exist.
+
+## Messaging
+
+When the host **emits** notifications or uses phone/Pushover:
+
+- Catalog, channel policy, adapters, credentials: [`../messaging_integration_guide.md`](../messaging_integration_guide.md)
+- Admin announcements: [`../admin_workspace.md`](../admin_workspace.md)
+
+Complete steps 00–12 first. This bootstrap tree does not duplicate the messaging guide.
+
+## Host tests
+
+Shared FactoryBot definitions ship with the gem. In the host test boot path:
+
+```ruby
+require "command_tower/testing"
+CommandTower::Testing.install!
+```
+
+Then `FactoryBot.modify` as needed. Contract: [`../testing.md`](../testing.md).
+
+Run specs **in Compose**:
+
+```bash
+make rspec
+make spec SPEC=spec/path/to/file_spec.rb
+```
+
+Do not run `rspec` on the Mac.
+
+## Client-version compatibility (CVC)
+
+If the frontend must block incompatible native/web builds, register CVC in the host (registry / initializer). Frontend recovery UX is a client concern; the backend must serve the compatibility contract the client expects.
+
+Follow the gem’s registry comments and [`../extending.md`](../extending.md) for `config.registry` patterns. Do not invent a parallel version table.
+
+## Stop
+
+Either you skipped this step, or messaging/tests/CVC point at specialty docs and run via Make. Next: [`14-sanity-checks.md`](14-sanity-checks.md).

data/docs/bootstrap/14-sanity-checks.md

@@ -0,0 +1,44 @@
+# 14 — Sanity checks
+
+## Purpose
+
+Stop condition for **local** bootstrap. This is not a production launch checklist.
+
+## Prerequisites
+
+- Steps 00–12 complete
+- Step 13 only if you opted in
+
+## Checks
+
+Run inside Compose (Make wrappers from [`01-docker-make-compose.md`](01-docker-make-compose.md)):
+
+| Check | Command | Expect |
+|-------|---------|--------|
+| Doctor | `make doctor` | Exit 0 |
+| Server | `make server` | API listens on the Compose port |
+| Me smoke | [`12-smoke-check.md`](12-smoke-check.md) | `GET /me` **200** |
+| Host specs (if you added them) | `make rspec` | Pass |
+| RuboCop (if you added it) | `make rubocop` | Pass |
+
+401 vs 403 vs 404: still [`12-smoke-check.md`](12-smoke-check.md).
+
+## Not this manual
+
+Do not treat the following as remaining bootstrap steps:
+
+- Production deploys, systemd, reverse proxies, LXC
+- Production secret distribution
+- Multi-host clustering
+- App-store / frontend release (see the Command Tower **frontend** bootstrap tree)
+
+## After this tree
+
+- Product routes and workflows: [`../extending.md`](../extending.md), [`../architecture.md`](../architecture.md)
+- HTTP you did not smoke: [`../api_reference.md`](../api_reference.md)
+- Gem upgrades: [`../upgrades/README.md`](../upgrades/README.md)
+- Command Tower frontend on this API: [Local FE↔BE join](../../../artifacts/COMMANDTOWER_LOCAL_JOIN.md)
+
+## Stop
+
+Doctor is green and `GET /me` is **200**. Local Command Tower backend bootstrap is complete.

data/docs/bootstrap/README.md

@@ -0,0 +1,90 @@
+# Bootstrap a new Command Tower backend host
+
+Bring up a new Rails API host that **mounts** CommandTower, in order.
+
+This directory is the host bring-up authority. Specialty contracts stay in sibling docs (`initializing`, `authorization`, `api_reference`, `extending`). This tree owns **order**, **which files the host authors** (including Docker and Make), and **how to invoke Rails** — always inside Compose.
+
+Do **not** copy another product host’s tree. Do **not** copy [`../docker-compose.yaml`](../docker-compose.yaml) from this gem (that file is for **engine development**). The dummy app under [`../../rails_app/`](../../rails_app/) is an in-engine example for initializer and RBAC shape, not a product template.
+
+## Docker-only
+
+Every Ruby/Rails action runs inside Docker Compose.
+
+**Host-machine tools:** Docker, the Docker Compose plugin, Make, Git. That is the entire local toolchain.
+
+Do **not** run on the Mac (or any unsandboxed host OS):
+
+- `gem install rails`
+- `rails new`
+- `bundle`
+- `bin/rails` / `bin/rake`
+- `rspec` / `rubocop`
+
+Those names appear in this tree as **task names** inside the container, always invoked as `make …`.
+
+**Chicken-and-egg:** author `Dockerfile`, `docker-compose.yml`, and `Makefile` **first** ([`01-docker-make-compose.md`](01-docker-make-compose.md)). `make build` produces a Ruby image. `make rails-new` runs `rails new` **in that image**. Only then pin the gem and install CommandTower.
+
+## This is not deployment
+
+This manual is **local bring-up**. It ends when the host runs in Compose and passes the checks in [`14-sanity-checks.md`](14-sanity-checks.md): `make doctor` and `GET /me` **200** for a member user.
+
+It does **not** cover production deploys, systemd, reverse proxies, LXC, or how secrets are distributed in production. Do not add a deploy step to this tree without a separate decision.
+
+## How to read
+
+1. Follow **Implementation order** below. That list is the only sequence.
+2. Open one numbered file per step. Later files assume earlier steps exist.
+3. Each step states purpose, prerequisites, files to create, the procedure (`make` only), and the stop condition.
+4. For field contracts, follow the linked specialty doc. Do not treat this tree as a second copy of those contracts.
+
+A **platform-proof** host is: Docker/Make, Rails API in the container, CommandTower installed, `host_key`, host RBAC grants, feature gates, register → login → `GET /me`. Product domain and messaging adapters are optional ([`13-optional.md`](13-optional.md)).
+
+Attaching a Command Tower **frontend** is a separate step after this tree: [Local FE↔BE join](../../../artifacts/COMMANDTOWER_LOCAL_JOIN.md).
+
+## Implementation order
+
+| Step | File | What you do |
+|------|------|-------------|
+| 00 | [`00-ownership.md`](00-ownership.md) | Engine vs host; schema; Docker-only; dummy is not a product template |
+| 01 | [`01-docker-make-compose.md`](01-docker-make-compose.md) | Dockerfile, Compose, Makefile, `.dockerignore` |
+| 02 | [`02-create-the-rails-app.md`](02-create-the-rails-app.md) | `make rails-new` (Rails 8 API) inside the container |
+| 03 | [`03-pin-the-gem.md`](03-pin-the-gem.md) | `gem "command_tower"` from RubyGems (or git tag) |
+| 04 | [`04-secrets-and-env.md`](04-secrets-and-env.md) | JWT / signup-session / password-recovery secrets in Compose |
+| 05 | [`05-install-migrate-doctor.md`](05-install-migrate-doctor.md) | `command_tower:install`, migrate, doctor |
+| 06 | [`06-mount-and-health.md`](06-mount-and-health.md) | Engine mount path; host healthz |
+| 07 | [`07-execution-bases.md`](07-execution-bases.md) | Inherit CommandTower controller/job bases |
+| 08 | [`08-initializer.md`](08-initializer.md) | `host_key`, cookies if needed, email knobs |
+| 09 | [`09-rbac.md`](09-rbac.md) | Host `rbac_groups.yml` grants CT entity names |
+| 10 | [`10-roles-and-gates.md`](10-roles-and-gates.md) | Default `member`; enable login / verify / reset gates |
+| 11 | [`11-auth-client-path.md`](11-auth-client-path.md) | Bearer vs cookie+CSRF |
+| 12 | [`12-smoke-check.md`](12-smoke-check.md) | Register → login → `GET /me` **200** |
+| 13 | [`13-optional.md`](13-optional.md) | Optional: messaging, host tests, client-version compatibility |
+| 14 | [`14-sanity-checks.md`](14-sanity-checks.md) | Stop: doctor + Me smoke; not deployment |
+
+Step 13 is optional after 12.
+
+## File index
+
+Same files as the table. Filename numbers match the order list. If you add, remove, or reorder a step, change this README and the filenames together.
+
+## Specialty docs this tree does not replace
+
+| Need | Doc |
+|------|-----|
+| Attach a Command Tower frontend locally | [`../../../artifacts/COMMANDTOWER_LOCAL_JOIN.md`](../../../artifacts/COMMANDTOWER_LOCAL_JOIN.md) |
+| What `command_tower:install` does, flags, schema, doctor | [`../initializing.md`](../initializing.md) |
+| Layer map, workflow rule | [`../architecture.md`](../architecture.md) |
+| Extension points | [`../extending.md`](../extending.md) |
+| HTTP catalog | [`../api_reference.md`](../api_reference.md) |
+| Route areas | [`../controllers.md`](../controllers.md) |
+| RBAC | [`../authorization.md`](../authorization.md), [`../authentication_authorization_guide.md`](../authentication_authorization_guide.md) |
+| Cookie / CSRF | [`../cookie_authentication_guide.md`](../cookie_authentication_guide.md) |
+| Messaging | [`../messaging_integration_guide.md`](../messaging_integration_guide.md) |
+| Testing factories | [`../testing.md`](../testing.md) |
+| Admin Workspace | [`../admin_workspace.md`](../admin_workspace.md) |
+| Principal capabilities | [`../principal_capabilities.md`](../principal_capabilities.md) |
+| Audit registry | [`../audit.md`](../audit.md) |
+| Eventing | [`../eventing.md`](../eventing.md) |
+| Release upgrades | [`../upgrades/README.md`](../upgrades/README.md) |
+
+Older entry: [`../host_integration_guide.md`](../host_integration_guide.md) is a pointer here.

data/docs/cookie_authentication_guide.md

@@ -37,6 +37,17 @@ end
 | CSRF `same_site` / `secure` / `path` / `domain` | `nil` (inherit JWT cookie) |
 | CSRF `ttl` | `7.days` |
 
+### Two web apps on one hostname
+
+The browser keys `ct_jwt` and `ct_csrf` by hostname. The port is not part of that key. Two Command Tower web apps on `localhost` overwrite each other’s session. Logout expires both cookies, so a shared CSRF name still logs the other app out on its next POST.
+
+A second product sets both names. The frontend `session.csrfCookieName` matches `csrf.cookie_name`. Leave `header_name` as `X-CSRF-Token`. A host that runs alone keeps `ct_jwt` and `ct_csrf`.
+
+```ruby
+config.jwt.cookie.name = "other_jwt"
+config.jwt.cookie.csrf.cookie_name = "other_csrf"
+```
+
 ## Token extraction order
 
 1. `Authorization: Bearer <token>` header (wins when present)

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).
 
@@ -19,6 +19,7 @@ Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor:
 | Model reopen | Product associations / behavior |
 | Initializers | Configuration, including `config.registry.audit.event`, `config.registry.admin_workspace.tool`, and `config.registry.principal_capabilities.capability` |
 | Notification catalogs / channel policy | Host-owned messaging customization |
+| `app/views/command_tower/messaging/rendering/**` | Host override of generic and/or per-`notification_type_key` rendered Email/SMS/Pushover/Push templates — see [messaging_integration_guide.md](messaging_integration_guide.md#rendering-template-overrides) |
 
 ## Internal platform — do not extend
 
@@ -28,7 +29,7 @@ Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor:
 | ServiceBase | Shared service framework |
 | Serializers | Platform response shaping |
 | Deserializers | Platform request trust boundary |
-| Messaging execution pipeline | Handoff / execution / accept internals |
+| Messaging execution pipeline | Handoff / execution / accept internals, including `Messaging::Rendering::ChannelRenderer` / `TemplateResolver` Ruby classes — hosts customize rendering by dropping ERB views (above), never by reopening or calling these classes |
 | RequestContext | Framework request context |
 | JWT primitives | Token issue / validate plumbing |
 | Internal framework plumbing | Envelope renderer, workflow base mechanics, etc. |
@@ -41,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,250 +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.
-
-## 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