command_tower 0.17.0 → 0.18.0

data/docs/bootstrap/06-mount-and-health.md

@@ -0,0 +1,53 @@
+# 06 — Mount and health
+
+## Purpose
+
+Mount CommandTower where the product needs it, and keep a host health endpoint **outside** the engine when you skipped the generator mount.
+
+## Prerequisites
+
+- [`05-install-migrate-doctor.md`](05-install-migrate-doctor.md)
+
+## Files the host edits
+
+`config/routes.rb`
+
+## Procedure
+
+### Default (generator mounted)
+
+`command_tower:install` without `SKIP_MOUNT` typically mounts:
+
+```ruby
+mount CommandTower::Engine => "/api"
+```
+
+or at `/`, depending on generator defaults. Confirm the file. Engine routes then live under that prefix (`GET /api/me` vs `GET /me`).
+
+Use **one** mount. Do not mount the engine twice.
+
+### Host-owned healthz (`SKIP_MOUNT=1`)
+
+Declare host routes **before** the engine so health checks never depend on engine routing:
+
+```ruby
+Rails.application.routes.draw do
+  get "/api/healthz", to: "health#show"
+
+  mount CommandTower::Engine => "/api"
+end
+```
+
+`HealthController#show` is host-owned (liveness). Keep it trivial.
+
+If the engine is mounted at `/`, a host `/healthz` still belongs **before** the mount.
+
+### Accidental public mount
+
+If you mounted at `/` and needed `/api`, or the generator mounted when you needed to skip: fix `config/routes.rb` by hand. Re-running configure with `FORCE=1` is not the tool for route cleanup.
+
+More on mount mistakes: [`../initializing.md`](../initializing.md) troubleshooting.
+
+## Stop
+
+`config/routes.rb` has exactly one engine mount at the prefix your API and frontend will call. Host `healthz` (if any) is declared before that mount. Next: [`07-execution-bases.md`](07-execution-bases.md).

data/docs/bootstrap/07-execution-bases.md

@@ -0,0 +1,38 @@
+# 07 — Execution-boundary bases
+
+## Purpose
+
+Host controllers and jobs inherit CommandTower bases so authentication, request context, envelope rendering, and job execution stay on the platform path.
+
+## Prerequisites
+
+- [`06-mount-and-health.md`](06-mount-and-health.md)
+
+## Files the host edits
+
+| File | Inherit |
+|------|---------|
+| `app/controllers/application_controller.rb` | `CommandTower::ApplicationController` |
+| `app/jobs/application_job.rb` | `CommandTower::ApplicationJob` |
+
+## Procedure
+
+Replace the default `ActionController::API` / `ActiveJob::Base` superclasses:
+
+```ruby
+class ApplicationController < CommandTower::ApplicationController
+end
+```
+
+```ruby
+class ApplicationJob < CommandTower::ApplicationJob
+end
+```
+
+Host controllers then subclass `ApplicationController` as usual. Do not subclass `ActionController::API` for product JSON that should share CommandTower auth and envelope behavior.
+
+Background work invokes **workflows** (via CommandTower job helpers), not services as a full business action. See [`../architecture.md`](../architecture.md).
+
+## Stop
+
+`ApplicationController` and `ApplicationJob` inherit CommandTower bases. Next: [`08-initializer.md`](08-initializer.md).

data/docs/bootstrap/08-initializer.md

@@ -0,0 +1,90 @@
+# 08 — Initializer
+
+## Purpose
+
+Set **host_key**, secrets, local mail, and (when the client is Command Tower frontend on web) cookies. The generated file documents every class_composer option; do not uncomment the world.
+
+## Prerequisites
+
+- [`07-execution-bases.md`](07-execution-bases.md)
+- Secrets from [`04-secrets-and-env.md`](04-secrets-and-env.md) already in Compose
+
+## Files the host edits
+
+`config/initializers/command_tower.rb` (created by install)
+
+In-engine dummy for **shape**: [`../../rails_app/config/initializers/command_tower.rb`](../../rails_app/config/initializers/command_tower.rb). Copy **intent** (host_key, secrets, later RBAC/gates), not the dummy’s engine-dev values as a product identity.
+
+## Procedure
+
+### `host_key` (required)
+
+Server-bound host/product identity for CT-generic user-scoped state (experience states). **Not** client-supplied.
+
+```ruby
+CommandTower.configure do |config|
+  config.application.host_key = "your_product"
+end
+```
+
+Blank `host_key` → Me experience-state routes return **503**.
+
+The dummy sets `config.application.host_key = "command_tower"`. A product host uses its **own** key.
+
+### Secrets
+
+Prefer ENV already injected by Compose:
+
+```ruby
+config.jwt.hmac_secret = ENV.fetch("SECRET_KEY_BASE")
+config.signup_session.jwt_secret = ENV.fetch("SIGNUP_SESSION_JWT_SECRET")
+config.password_recovery_session.jwt_secret = ENV.fetch("PASSWORD_RECOVERY_SESSION_JWT_SECRET")
+```
+
+Exact setter names are in the generated initializer comments and [`../initializing.md`](../initializing.md). Match those names; do not invent parallel keys.
+
+### Cookies / CSRF (required for Command Tower frontend on web)
+
+Command Tower frontend `defaultSessionStrategy()` is **cookie + CSRF on web** and Bearer on native. If this API will serve that web client, enable cookies **now**. Curl-only smoke in [`12-smoke-check.md`](12-smoke-check.md) can still send `Authorization: Bearer`.
+
+Contract and defaults: [`../cookie_authentication_guide.md`](../cookie_authentication_guide.md). Local HTTP Compose:
+
+```ruby
+config.jwt.cookie.enabled = true
+config.jwt.cookie.secure = false
+config.jwt.cookie.same_site = :lax
+config.jwt.cookie.csrf.enabled = true
+```
+
+Do not set `secure = true` on `http://localhost`. Leave `domain` nil (host-only). Defaults are `ct_jwt` and `ct_csrf`. Full field table stays in the cookie guide.
+
+A browser stores those cookies by hostname. The port is not part of the key, so two web apps on `localhost` share one `ct_jwt` and one `ct_csrf`. Logout expires both cookies. A second product on the same hostname sets both names, and that host’s frontend `session.csrfCookieName` matches the CSRF name. The header stays `X-CSRF-Token`. A host that runs alone leaves the defaults.
+
+```ruby
+config.jwt.cookie.name = "other_jwt"
+config.jwt.cookie.csrf.cookie_name = "other_csrf"
+```
+
+If the only client is Bearer (`curl`, native-only), leave cookies disabled.
+
+### Email / SMTP
+
+Step 02 already set `:file` delivery in `development.rb`. In the initializer, set the public app URL used in mail links (frontend origin, not the API port):
+
+```ruby
+config.application.url = "http://localhost:8081"
+```
+
+`8081` is one product’s Expo port. Use the port this host’s web app actually publishes, and put that same origin in `CORS_ALLOWED_ORIGINS` (step 01). Production SMTP is out of this manual’s deployment scope.
+
+### What not to do
+
+- Do not duplicate CommandTower default hashes “for completeness”
+- Do not set `FORCE=1` and regenerate after customizing
+- Do not fork engine internals because a comment looked optional
+
+RBAC default role and feature gates are steps 09–10.
+
+## Stop
+
+`host_key` is a real product string. JWT and session secrets resolve from ENV. Cookie + CSRF are on if a CT frontend web client will call this API. Next: [`09-rbac.md`](09-rbac.md).

data/docs/bootstrap/09-rbac.md

@@ -0,0 +1,83 @@
+# 09 — RBAC
+
+## Purpose
+
+Give authenticated users a **product role** that **grants CommandTower entity names**. Without this, login can succeed and `GET /me` returns **403**.
+
+## Prerequisites
+
+- [`08-initializer.md`](08-initializer.md)
+
+## Files the host creates
+
+`config/rbac_groups.yml` — host-owned composition.
+
+CommandTower ships **entity definitions** in `lib/command_tower/authorization/default.yml` (inside the gem). Hosts **grant those names**. Hosts may add host-owned entities for host controllers.
+
+In-engine dummy for **shape**: [`../../rails_app/config/rbac_groups.yml`](../../rails_app/config/rbac_groups.yml). Use it to see a `member` grant list and that Admin bundles are **host policy**. Do not copy dummy-only entities (`dummy_admin_example`) into a product host.
+
+Contract: [`../authorization.md`](../authorization.md), [`../authentication_authorization_guide.md`](../authentication_authorization_guide.md).
+
+## Procedure
+
+### 1. Author `member` (minimum for Me)
+
+Grant the Me/Auth entity names your smoke path needs. A typical starting `member` (from the dummy, minus product-specific extras you do not want yet):
+
+```yaml
+groups:
+  member:
+    description: Standard authenticated application user
+    entities:
+      - email_verification_send
+      - email_verification_verify
+      - session
+      - me
+      - profile
+      - me_name
+      - me_password
+      - me_account
+      - me_inbox
+      - me_audit_events
+      - me_preferences
+      - me_phone
+      - me_phone_verification_send
+      - me_phone_verification_verify
+      - me_pushover
+      - me_pushover_verification
+      - me_push
+      - me_experience_states
+      - principal_capabilities
+```
+
+Trim unused Me surfaces if you want a thinner first grant (you **must** keep `me` and `session` for the smoke in [`12-smoke-check.md`](12-smoke-check.md)). Missing `me` → **403** on `GET /me`.
+
+### 2. `default_membership_role`
+
+In `config/initializers/command_tower.rb`:
+
+```ruby
+config.authorization.default_membership_role = "member"
+```
+
+New users then receive `member` without a manual assign. If you omit this, you must assign roles some other supported way before Me works.
+
+### 3. Admin roles (not required to finish bootstrap)
+
+Do **not** auto-grant new Admin capabilities to a generic Admin role. CommandTower does not ship an accumulating operational `admin` role. `owner` (`entities: true`) is full-access and distinct from host Admin bundles.
+
+If you add Admin later, copy the **pattern** from the dummy (`audit_operator`, `operations_admin`, …): explicit entity lists on a host role. See [`../admin_workspace.md`](../admin_workspace.md).
+
+The frontend workspace and user detail call these entities. Grant each one the role should have:
+
+- `admin_workspace`
+- `admin_users`
+- `admin_audit_events`
+- `admin_messaging_announcements`
+- `admin_impersonation`
+
+`admin_impersonation` is what shows Impersonate. The frontend does not add a route for it.
+
+## Stop
+
+`config/rbac_groups.yml` exists with a `member` group that grants `me` (and the rest you need). `default_membership_role` is `"member"` (or you have a documented assign path). Next: [`10-roles-and-gates.md`](10-roles-and-gates.md).

data/docs/bootstrap/10-roles-and-gates.md

@@ -0,0 +1,62 @@
+# 10 — Roles and feature gates
+
+## Purpose
+
+Assign the default membership role (if you did not in step 09) and **enable** the HTTP gates the smoke path needs. Gates default **off** → **404**.
+
+## Prerequisites
+
+- [`09-rbac.md`](09-rbac.md)
+
+## Files the host edits
+
+`config/initializers/command_tower.rb`
+
+Opening a `with_*` block typically sets its enable flag. Still set `enable` / `enabled` explicitly so a later comment-uncomment does not leave you on the default **off** path.
+
+## Procedure
+
+### Default role
+
+```ruby
+config.authorization.default_membership_role = "member"
+```
+
+### Login / verify / reset (minimum for Me + CT frontend guest screens)
+
+```ruby
+config.login.with_plain_text do |plain_text_config|
+  plain_text_config.enable = true
+
+  plain_text_config.with_email_verify do |email_verify_config|
+    email_verify_config.enable = true
+    # Curl smoke (step 12) can login before the user verifies.
+    # 0.minutes → GET /me is 412 until email is verified.
+    email_verify_config.verify_email_required_within = 7.days
+  end
+
+  plain_text_config.with_password_reset do |password_reset_config|
+    password_reset_config.enabled = true
+  end
+end
+```
+
+### Availability (CT frontend signup)
+
+If the guest signup screen checks username/email availability, enable those gates or the client sees **404**:
+
+```ruby
+config.username.with_realtime_username_check do |realtime_username_check_config|
+  realtime_username_check_config.enable = true
+end
+
+config.signup_session.email_availability.enable = true
+```
+
+Leave Admin and messaging gates off until you need those routes.
+
+Do not use role-**name** checks in host code for authorization. Use entity grants / `allow_everything`. See [`../authorization.md`](../authorization.md).
+
+## Stop
+
+Plain-text login is **on**. Register → login → `GET /me` is not **404**. Next: [`11-auth-client-path.md`](11-auth-client-path.md).

data/docs/bootstrap/11-auth-client-path.md

@@ -0,0 +1,57 @@
+# 11 — Auth client path
+
+## Purpose
+
+Pick **one** client authentication mode and configure the host to match. Mixing a cookie+CSRF frontend with cookies disabled will fail in the browser. `curl` can still send Bearer on the same host.
+
+## Prerequisites
+
+- [`10-roles-and-gates.md`](10-roles-and-gates.md)
+- `gem "rack-cors"` from [`02-create-the-rails-app.md`](02-create-the-rails-app.md) if a browser will call this API
+
+## Two supported modes
+
+| Mode | Client sends | Host initializer |
+|------|----------------|------------------|
+| Bearer | `Authorization: Bearer <jwt>` | Cookie JWT disabled |
+| Cookie + CSRF | HttpOnly JWT cookie + CSRF header/cookie | Cookie + CSRF **enabled** (step 08) |
+
+Command Tower **frontend** on web uses `defaultSessionStrategy()` → cookie + CSRF. Native uses Bearer. Enable cookies when that web client exists; keep Bearer working for `curl` and native.
+
+Contract: [`../cookie_authentication_guide.md`](../cookie_authentication_guide.md).
+
+Do not invent a third session store. Do not put JWTs in `localStorage` as a “simpler cookie.”
+
+## Procedure
+
+1. If the client is Command Tower frontend on web: cookies + CSRF already on from step 08 (`secure = false` on HTTP localhost).
+2. If Bearer-only: leave cookies disabled; step 12 uses `Authorization`.
+3. If a **browser on another origin** calls the API, add host CORS. CommandTower does not ship CORS.
+
+`config/initializers/cors.rb`:
+
+```ruby
+allowed_origins = ENV.fetch(
+  "CORS_ALLOWED_ORIGINS",
+  "http://localhost:8081,http://localhost:8082,http://localhost:19006"
+).split(",").map(&:strip).reject(&:empty?)
+
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+  allow do
+    origins(*allowed_origins)
+    resource "*",
+             headers: :any,
+             methods: %i[get post put patch delete options head],
+             credentials: true,
+             expose: ["X-Authorization-Expire", "X-Authorization-Reset"]
+  end
+end
+```
+
+`credentials: true` requires an **explicit origin list**, not `*`. Compose already passes `CORS_ALLOWED_ORIGINS` from step 01. The sample origins `8081`, `8082`, and `19006` belong to one web product. Add the origin this Expo web app actually uses, and keep it aligned with `config.application.url` and the API’s published port.
+
+Attaching a Command Tower frontend: [Local FE↔BE join](../../../artifacts/COMMANDTOWER_LOCAL_JOIN.md).
+
+## Stop
+
+You can state which mode the smoke will use. CORS exists if a browser will call this API. Next: [`12-smoke-check.md`](12-smoke-check.md).

data/docs/bootstrap/12-smoke-check.md

@@ -0,0 +1,81 @@
+# 12 — Smoke check (`GET /me`)
+
+## Purpose
+
+Prove the host is a usable Me/Auth API: register, log in, call `GET /me`, receive **200**.
+
+## Prerequisites
+
+- Steps 00–11
+- API listening: `make server` (or `make s`) — Puma bound on `0.0.0.0` (step 01)
+
+Prefix every path with your engine mount (`/api` if you mounted there). Examples below assume mount at `/api` and host port **3000**.
+
+HTTP catalog (full contract): [`../api_reference.md`](../api_reference.md). This page is the **happy path only**.
+
+## Procedure
+
+Run `curl` **on the Mac** against the published Compose port. That is HTTP, not Ruby on the host.
+
+Login succeeds with **201** (not 200). Register succeeds with **201** and **no** token.
+
+### 1. Register
+
+```bash
+curl -sS -X POST http://localhost:3000/api/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "first_name": "Ada",
+    "last_name": "Lovelace",
+    "username": "ada1",
+    "email": "ada@example.com",
+    "password": "password12",
+    "password_confirmation": "password12"
+  }'
+```
+
+Expect **201**. No JWT. If email verification is required immediately (`verify_email_required_within = 0.minutes`), either verify using the code in `tmp/mails` or raise the grace period (step 10).
+
+If you already have a user in the database, skip to login.
+
+### 2. Login
+
+```bash
+curl -sS -X POST http://localhost:3000/api/auth/plain-text/login \
+  -H "Content-Type: application/json" \
+  -d '{"identifier": "ada@example.com", "password": "password12"}'
+```
+
+Expect **201** and `data.token`. Cookie mode also sets `Set-Cookie` for `ct_jwt` (and `ct_csrf` when CSRF is on).
+
+### 3. Me
+
+```bash
+TOKEN='<paste data.token>'
+curl -sS -H "Authorization: Bearer ${TOKEN}" http://localhost:3000/api/me
+```
+
+Expect **200** and a Me payload.
+
+Cookie mode: omit `Authorization`, send `-b cookies.txt` after login with `-c cookies.txt`, and on mutating requests add `-H "X-CSRF-Token: …"` from the CSRF cookie. `GET /me` still needs the JWT cookie.
+
+## How to read failures
+
+| Status | Meaning |
+|--------|---------|
+| **401** | Not authenticated — missing/invalid token or cookie |
+| **403** | Authenticated but **not authorized** — RBAC grant missing (`me` not on the user’s role) |
+| **404** | Feature gate off or wrong path/mount |
+| **412** | Email verification required — grace period elapsed; verify or raise `verify_email_required_within` |
+| **503** | Often blank `host_key` on experience-state routes; fix step 08 |
+| Connection refused | Compose `command` not binding `0.0.0.0`, or published port mismatch |
+
+Do not “fix” 403 by disabling RBAC. Grant `me` on `member`.
+
+## After `GET /me`
+
+Attaching a Command Tower frontend is **not** this file. Follow [Local FE↔BE join](../../../artifacts/COMMANDTOWER_LOCAL_JOIN.md).
+
+## Stop
+
+`GET /me` is **200** for a `member` user. Optional extras: [`13-optional.md`](13-optional.md). Required wrap-up: [`14-sanity-checks.md`](14-sanity-checks.md).

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)