command_tower 0.16.0 → 0.18.0

data/docs/messaging_integration_guide.md

@@ -2,7 +2,7 @@
 
 CommandTower owns modern messaging **platform** surfaces. Hosts supply product content, channel policy, and adapter credentials.
 
-Complete install and host RBAC first: [Host integration](host_integration_guide.md) (Steps 1–8 before emitting or wiring phone/Pushover).
+Complete install and host RBAC first: [Bootstrap a new host](bootstrap/README.md) (through [`12-smoke-check.md`](bootstrap/12-smoke-check.md) before emitting or wiring phone/Pushover).
 
 ## Current surfaces
 
@@ -59,6 +59,44 @@ CommandTower::Services::Messaging::Communications::Produce.call(
 
 Admin announcements HTTP is a product path over ProduceMany (async/sync, audience selection). Contract: [API reference — Admin messaging](api_reference.md#admin-messaging).
 
+## Rendering template overrides
+
+`ChannelRenderer` resolves each rendered destination (email HTML/text, SMS, Pushover, push) by `notification_type_key` first, falling back to a generic template — and always prefers a **host** view over CommandTower's own engine default for either. Hosts customize by dropping ERB files at this path in their own `app/views/`; they never call `ChannelRenderer` or its internal `TemplateResolver` collaborator directly.
+
+```text
+app/views/command_tower/messaging/rendering/
+  email.html.erb            # optional host override of the generic chrome
+  email.text.erb
+  sms.text.erb
+  push.text.erb
+  pushover.text.erb
+  <notification_type_key>/
+    email.html.erb          # optional type-specific override (only if the key matches [a-z0-9_]+)
+    email.text.erb
+    sms.text.erb
+    push.text.erb
+    pushover.text.erb
+```
+
+Notes:
+
+- `<notification_type_key>` directories only resolve when the key matches `/\A[a-z0-9_]+\z/`. Keys with dots (e.g. legacy `"example.type"`-style keys) or other characters always fall back to generic — they never attempt a type directory, even if one happens to exist on disk.
+- Each rendered destination resolves independently — a type directory can override just `email.html.erb` while every other destination (email text, SMS, Pushover, push) still renders from the generic templates.
+- Generic templates receive the same four locals as before (`title`, `body`, `deep_link`, `h` — an HTML-escaping helper). Type-specific templates additionally receive `metadata` (the communication's metadata Hash) and `notification_type_key`.
+- A missing or failing template (generic or type-specific) surfaces the same way it always has: `RenderError` with code `"render_failed"`.
+
+### Inbox document override (`inbox_document.json.erb`)
+
+The Me Inbox detail `content` field (`inbox_document_v1`, see [api_reference.md](api_reference.md#me-inbox)) is built by a separate collaborator, `InboxDocumentRenderer`, using the **same** type-directory convention and sanitized-key rule as above, resolved through `TemplateResolver.render_type_template`:
+
+```text
+app/views/command_tower/messaging/rendering/
+  <notification_type_key>/
+    inbox_document.json.erb   # optional type-specific inbox content override
+```
+
+This override has **no generic ERB fallback file** — the generic Inbox document is built in pure Ruby from `communication.body`/`metadata`, not from a template. Because of that, the fail-open contract here is stricter than `ChannelRenderer`'s: a missing type template, malformed JSON, an envelope with the wrong `schema` or a non-Array `blocks`, or a template that raises mid-render all fall back silently to the generic document — the Inbox read path never surfaces a `RenderError` and never 500s. A valid envelope with one invalid/unknown block strips only that block, keeping the rest; if stripping empties `blocks`, the generic document is used instead.
+
 ## Me Inbox HTTP (summary)
 
 | Concern | Contract |

data/docs/principal_capabilities.md

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

data/docs/upgrades/0.10.0.md

@@ -3,7 +3,7 @@
 **From:** `0.5.0` (and earlier SchemaHelper-era hosts on `main`)  
 **To:** `0.10.0`
 
-This document summarizes **all changes from `main` through the `0.10.0` release** (committed work on `schematizing` plus the modern platform working tree). It is the durable upgrade / change SST for hosts. For a sequenced blank-host path, use [Host integration](../host_integration_guide.md).
+This document summarizes **all changes from `main` through the `0.10.0` release** (committed work on `schematizing` plus the modern platform working tree). It is the durable upgrade / change SST for hosts. For a sequenced blank-host path, use [Bootstrap a new host](../bootstrap/README.md).
 
 ## Breaking / host-impact
 
@@ -31,15 +31,15 @@ This document summarizes **all changes from `main` through the `0.10.0` release*
 ## Documentation
 
 - Canonical HTTP catalog: [API reference](../api_reference.md)
-- Host start-here: [Host integration](../host_integration_guide.md)
+- Host start-here: [Bootstrap a new host](../bootstrap/README.md)
 - Install SST: [Initializing](../initializing.md)
 - Auth/cookie/RBAC guides refreshed to modern routes
 - Messaging and pagination aligned to Inbox + Produce contracts
 
 ## Upgrade checklist (existing hosts)
 
-1. Bump gem to `0.10.0` and run `bin/rails command_tower:install:migrations` (or `SKIP_CONFIGURE=1 bin/rails command_tower:install`) then `bin/rails db:migrate`.
-2. Set JWT + signup/recovery session secrets; run `bin/rails command_tower:doctor`.
+1. Bump gem to `0.10.0` and run `make rails ARGS='command_tower:install:migrations'` (or `SKIP_CONFIGURE=1 make rails ARGS='command_tower:install'`) then `make migrate`.
+2. Set JWT + signup/recovery session secrets; run `make doctor`.
 3. Add host `rbac_groups.yml` with a product role (typically `member`) that **grants** CT-owned entity names; do not redefine engine `owner` or copy CT controller mappings. Operational Admin roles are host-owned.
 4. Ensure users who need Me surfaces have the host `member` role (or equivalent).
 5. Enable feature gates you rely on (`login.plain_text.enable`, password reset, email verify, availability).
@@ -47,7 +47,7 @@ This document summarizes **all changes from `main` through the `0.10.0` release*
 7. Smoke: Bearer login → `GET /me` returns **200** (not **403**).
 8. If emitting messages: catalog, channels, adapters; call Produce from host workflows.
 
-New hosts: follow [Host integration](../host_integration_guide.md) end-to-end.
+New hosts: follow [Bootstrap a new host](../bootstrap/README.md) end-to-end.
 
 ## Related
 

data/docs/upgrades/0.11.0.md

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

data/docs/upgrades/0.17.0.md

@@ -0,0 +1,33 @@
+# Upgrade: CommandTower 0.17.0
+
+**From:** `0.16.0`  
+**To:** `0.17.0`
+
+Minor release: client-version-compatibility gating, Rich Messaging Inbox content documents, and shared email theming. No new migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| `config.registry.client_compatibility` | Optional per-platform (`web`/`ios`/`android`) minimum/recommended version gating, evaluated on every request ahead of authn/authz via `before_action :evaluate_client_compatibility!`. Untouched registry is a no-op. |
+| `:observe` / `:enforce` modes | `:observe` (default) only logs; `:enforce` renders `426` `client_update_required` for incompatible/unparseable client identity |
+| `meta.clientCompatibility` | Non-blocking upgrade guidance surfaced only on login and session-show responses when a compatible client is below `recommended` |
+| `X-App-Version` / `X-Client-Platform` headers | New request contract driving evaluation — never User-Agent |
+| `GET`/`POST open` `/me/inbox/:id` `content` field | New `inbox_document_v1` field rendered at read time from the `Communication` (never persisted); generic Ruby-built `paragraph`/`cta` blocks, or a host `inbox_document.json.erb` override per `notification_type_key` |
+| `Messaging::Rendering::ChannelRenderer` template resolution | Now resolves per-destination host ERB overrides (`app/views/command_tower/messaging/rendering/**`) before falling back to engine defaults, instead of a single fixed `TEMPLATE_DIR` |
+| `config.email_theme` | New composer for semantic email theme tokens; verification and password-reset mailer views now render through `CommandTower::EmailTheme::Resolver` instead of hardcoded hex colors |
+| `config.registry.inbox_presentations` | New host-owned-only registry (no CommandTower-seeded presentations) supporting Rich Messaging Inbox host customization |
+
+## Host actions
+
+1. Bump gem to `0.17.0` (or `>= 0.17.0`).
+2. No new migration — **`bundle exec rails command_tower:install:migrations` is not required** for this release.
+3. Optional: configure `config.registry.client_compatibility` per platform if you want version gating; leaving it untouched is a no-op.
+4. Optional: customize email theme via `config.email_theme`, or override rendered Messaging templates / `inbox_document.json.erb` per `notification_type_key` under `app/views/command_tower/messaging/rendering/`.
+5. If your host renders `/me/inbox/:id`, expect the new `content` field in detail responses (list items are unaffected).
+
+## Not in this release
+
+- CommandTower frontend client-compatibility banners / upgrade prompts
+- CommandTower-owned Inbox presentation catalog entries (registry remains host-owned-only)
+- `android` platform enforcement examples beyond the documented ENV overlay contract

data/docs/upgrades/0.18.0.md

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

data/docs/upgrades/README.md

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

data/lib/command_tower/authorization/default.yml

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

data/lib/command_tower/client_compatibility/version.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module ClientCompatibility
+    # Strict client-version identity parsing (authority §12).
+    #
+    # `Gem::Version` alone is too permissive: it accepts partial shapes such as
+    # "1" or "1.2". The authority requires the full MAJOR.MINOR.PATCH shape,
+    # with an optional dot-delimited prerelease tail (e.g. "1.2.3.beta.1").
+    # Build metadata (e.g. "+build"), hyphenated prerelease tokens, and any
+    # other malformed shape are rejected as invalid identity — never coerced
+    # into a "valid but low" version.
+    module Version
+      FORMAT = /\A[vV]?\d+\.\d+\.\d+(\.[A-Za-z0-9]+)*\z/
+
+      module_function
+
+      # Returns a normalized (leading "v"/"V" stripped) version string, or nil
+      # when the raw value does not conform to the strict MAJOR.MINOR.PATCH
+      # (+ optional prerelease) shape.
+      def normalize(raw)
+        token = raw.to_s.strip
+        return nil if token.empty?
+        return nil unless token.match?(FORMAT)
+
+        token.sub(/\A[vV]/, "")
+      end
+
+      def valid?(raw)
+        !normalize(raw).nil?
+      end
+
+      # Returns a Gem::Version for a strictly-valid raw value, or nil otherwise.
+      # Callers that need a hard failure on invalid input should check
+      # `valid?`/`normalize` explicitly rather than relying on Gem::Version's
+      # own (looser) parsing.
+      def parse(raw)
+        normalized = normalize(raw)
+        return nil if normalized.nil?
+
+        Gem::Version.new(normalized)
+      end
+    end
+  end
+end

data/lib/command_tower/client_compatibility.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module ClientCompatibility
+    class Error < CommandTower::Error; end
+
+    class HostOverrideError < Error; end
+    class DuplicateContractError < Error; end
+    class DuplicateEntityRequirementError < Error; end
+    class DuplicateBindingError < Error; end
+    class UnknownClientContractError < Error; end
+    class UnboundClientContractError < Error; end
+    class UnknownEntityError < Error; end
+    class InvalidPlatformError < Error; end
+    class InvalidContractIdError < Error; end
+    class InvalidEntityNameError < Error; end
+    class InvalidVersionError < Error; end
+    class InvalidModeError < Error; end
+    class ConflictingRequirementError < Error; end
+    class NoConfiguredPlatformsError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end

data/lib/command_tower/configuration/config.rb

@@ -10,6 +10,7 @@ require "command_tower/configuration/authorization/config"
 require "command_tower/configuration/base"
 require "command_tower/configuration/credentials/config"
 require "command_tower/configuration/email/config"
+require "command_tower/configuration/email_theme/config"
 require "command_tower/configuration/identity/config"
 require "command_tower/configuration/impersonation/config"
 require "command_tower/configuration/jwt/config"
@@ -49,6 +50,11 @@ module CommandTower
         allowed: Configuration::Email::Config,
         default: Configuration::Email::Config.new
 
+      add_composer :email_theme,
+        desc: "Semantic email theme tokens shared by Messaging and (later) auth mail templates",
+        allowed: Configuration::EmailTheme::Config,
+        default: Configuration::EmailTheme::Config.new
+
       add_composer :credentials,
         desc: "Deployment provider credentials (typed per provider under config.credentials.<provider>). Consumed by Credential Resolution. Not provider behavior configuration.",
         allowed: Configuration::Credentials::Config,

data/lib/command_tower/configuration/email_theme/config.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module EmailTheme
+      # Semantic email theme tokens shared by Messaging email templates and,
+      # later, CT-owned auth mail templates. CT-owned, gem-level contract —
+      # see Rich Messaging Strategy §12 (email theme sequence, step A).
+      #
+      # Deliberately holds only visual/color tokens. Product identity
+      # (name/URL) already exists on Configuration::Application::Config and
+      # is composed in by CommandTower::EmailTheme::Resolver, not duplicated
+      # here. Defaults are the current unbranded hex values already
+      # hardcoded in command_tower's generic email.html.erb and Pick'em's
+      # incomplete_wager/email.html.erb, so introducing this contract is a
+      # no-op until a template is switched to consume it.
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :canvas_background,
+          allowed: String,
+          default: "#f4f5f7",
+          desc: "Outer email canvas background color"
+
+        add_composer :surface_background,
+          allowed: String,
+          default: "#ffffff",
+          desc: "Card/surface background color"
+
+        add_composer :surface_border,
+          allowed: String,
+          default: "#e2e8f0",
+          desc: "Card/surface border color"
+
+        add_composer :primary_text,
+          allowed: String,
+          default: "#1a202c",
+          desc: "Headline/primary text color"
+
+        add_composer :body_text,
+          allowed: String,
+          default: "#4a5568",
+          desc: "Body copy text color"
+
+        add_composer :muted_text,
+          allowed: String,
+          default: "#718096",
+          desc: "De-emphasized/secondary text color"
+
+        add_composer :accent,
+          allowed: String,
+          default: "#2b6cb0",
+          desc: "Single flat accent color (collapses any gradient to one value)"
+
+        add_composer :text_on_accent,
+          allowed: String,
+          default: "#ffffff",
+          desc: "Text/icon color rendered on top of the accent color"
+
+        add_composer :primary_action,
+          allowed: String,
+          default: "#2b6cb0",
+          desc: "Link/button primary-action color"
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/registry/client_compatibility/binding_definition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module ClientCompatibility
+        # Host-owned per-platform host-app version bound to a named client
+        # contract. Authority §7.
+        class BindingDefinition
+          include ClassComposer::Generator
+
+          add_composer :web, desc: "Bound host-app version for web", allowed: [String, NilClass], default: nil
+          add_composer :ios, desc: "Bound host-app version for ios", allowed: [String, NilClass], default: nil
+          add_composer :android, desc: "Bound host-app version for android", allowed: [String, NilClass], default: nil
+
+          def for_platform(platform)
+            public_send(platform)
+          end
+
+          def validate!(contract_id:)
+            %i[web ios android].each do |platform|
+              value = public_send(platform)
+              next if value.blank?
+
+              normalized = CommandTower::ClientCompatibility::Version.normalize(value)
+              if normalized.nil?
+                raise CommandTower::ClientCompatibility::InvalidVersionError,
+                  "binding for client contract #{contract_id} has invalid #{platform} #{value.inspect}"
+              end
+
+              public_send("#{platform}=", normalized)
+            end
+
+            self
+          end
+        end
+      end
+    end
+  end
+end