command_tower 0.15.0 → 0.17.0

data/app/views/command_tower/email_verification_mailer/verify_email.html.erb

@@ -1,11 +1,12 @@
-<table width="100%" cellpadding="0" cellspacing="0" border="0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: #f5f7fa; padding: 40px 20px;">
+<% theme = CommandTower::EmailTheme::Resolver.resolve -%>
+<table width="100%" cellpadding="0" cellspacing="0" border="0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: <%= theme[:canvas_background] %>; padding: 40px 20px;">
   <tr>
     <td align="center">
-      <table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: #ffffff; border-radius: 12px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); overflow: hidden;">
+      <table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: <%= theme[:surface_background] %>; border-radius: 12px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); overflow: hidden;">
         <!-- Header -->
         <tr>
-          <td style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 40px 30px; text-align: center;">
-            <h1 style="margin: 0; color: #ffffff; font-size: 28px; font-weight: 600; letter-spacing: -0.5px;">
+          <td style="background: <%= theme[:accent] %>; padding: 40px 30px; text-align: center;">
+            <h1 style="margin: 0; color: <%= theme[:text_on_accent] %>; font-size: 28px; font-weight: 600; letter-spacing: -0.5px;">
               Welcome to <%= CommandTower.config.app.communication_name %>!
             </h1>
           </td>
@@ -14,44 +15,44 @@
         <!-- Content -->
         <tr>
           <td style="padding: 40px 30px;">
-            <p style="margin: 0 0 20px 0; color: #4a5568; font-size: 16px; line-height: 1.6;">
-              Hello <strong style="color: #2d3748;"><%= @user.full_name %></strong>,
+            <p style="margin: 0 0 20px 0; color: <%= theme[:body_text] %>; font-size: 16px; line-height: 1.6;">
+              Hello <strong style="color: <%= theme[:primary_text] %>;"><%= @user.full_name %></strong>,
             </p>
 
-            <p style="margin: 0 0 30px 0; color: #4a5568; font-size: 16px; line-height: 1.6;">
+            <p style="margin: 0 0 30px 0; color: <%= theme[:body_text] %>; font-size: 16px; line-height: 1.6;">
               Thank you for joining us! To complete your registration and verify your email address, please use the verification code below:
             </p>
 
             <!-- Verification Code Box -->
             <table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 30px 0;">
               <tr>
-                <td align="center" style="padding: 30px; background: linear-gradient(135deg, #f6f8fb 0%, #e9ecef 100%); border-radius: 8px; border: 2px dashed #cbd5e0;">
-                  <div style="font-size: 36px; font-weight: 700; letter-spacing: 8px; color: #667eea; font-family: 'Courier New', monospace; text-align: center;">
+                <td align="center" style="padding: 30px; background-color: <%= theme[:canvas_background] %>; border-radius: 8px; border: 2px dashed <%= theme[:surface_border] %>;">
+                  <div style="font-size: 36px; font-weight: 700; letter-spacing: 8px; color: <%= theme[:accent] %>; font-family: 'Courier New', monospace; text-align: center;">
                     <%= @code %>
                   </div>
-                  <p style="margin: 15px 0 0 0; color: #718096; font-size: 12px; text-transform: uppercase; letter-spacing: 1px;">
+                  <p style="margin: 15px 0 0 0; color: <%= theme[:muted_text] %>; font-size: 12px; text-transform: uppercase; letter-spacing: 1px;">
                     Verification Code
                   </p>
                 </td>
               </tr>
             </table>
 
-            <p style="margin: 30px 0 20px 0; color: #718096; font-size: 14px; line-height: 1.6;">
-              <strong style="color: #4a5568;">Important:</strong> This code will expire in <%= CommandTower.config.login.plain_text.email_verify.verify_code_link_valid_for.inspect %>. If you didn't request this code, please ignore this email.
+            <p style="margin: 30px 0 20px 0; color: <%= theme[:muted_text] %>; font-size: 14px; line-height: 1.6;">
+              <strong style="color: <%= theme[:body_text] %>;">Important:</strong> This code will expire in <%= CommandTower.config.login.plain_text.email_verify.verify_code_link_valid_for.inspect %>. If you didn't request this code, please ignore this email.
             </p>
           </td>
         </tr>
 
         <!-- Footer -->
         <tr>
-          <td style="padding: 30px; background-color: #f7fafc; border-top: 1px solid #e2e8f0;">
-            <p style="margin: 0 0 15px 0; color: #4a5568; font-size: 14px; text-align: center; line-height: 1.6;">
+          <td style="padding: 30px; background-color: <%= theme[:canvas_background] %>; border-top: 1px solid <%= theme[:surface_border] %>;">
+            <p style="margin: 0 0 15px 0; color: <%= theme[:body_text] %>; font-size: 14px; text-align: center; line-height: 1.6;">
               Best regards,<br>
-              <strong style="color: #667eea;"><%= CommandTower.config.app.communication_name %> Team</strong>
+              <strong style="color: <%= theme[:accent] %>;"><%= CommandTower.config.app.communication_name %> Team</strong>
             </p>
 
             <p style="margin: 0; text-align: center;">
-              <a href="<%= CommandTower.config.app.composed_url %>" target="_blank" style="color: #667eea; text-decoration: none; font-size: 14px; font-weight: 500;">
+              <a href="<%= CommandTower.config.app.composed_url %>" target="_blank" style="color: <%= theme[:primary_action] %>; text-decoration: none; font-size: 14px; font-weight: 500;">
                 Visit <%= CommandTower.config.app.communication_name %>
               </a>
             </p>
@@ -63,7 +64,7 @@
       <table width="600" cellpadding="0" cellspacing="0" border="0" style="margin-top: 20px;">
         <tr>
           <td style="text-align: center; padding: 20px 0;">
-            <p style="margin: 0; color: #a0aec0; font-size: 12px; line-height: 1.5;">
+            <p style="margin: 0; color: <%= theme[:muted_text] %>; font-size: 12px; line-height: 1.5;">
               This is an automated message. Please do not reply to this email.
             </p>
           </td>

data/app/views/command_tower/messaging/rendering/email.html.erb

@@ -1,21 +1,22 @@
-<table width="100%" cellpadding="0" cellspacing="0" border="0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: #f4f5f7; padding: 32px 16px;">
+<% theme = CommandTower::EmailTheme::Resolver.resolve -%>
+<table width="100%" cellpadding="0" cellspacing="0" border="0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: <%= theme[:canvas_background] %>; padding: 32px 16px;">
   <tr>
     <td align="center">
-      <table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: #ffffff; border: 1px solid #e2e8f0; border-radius: 8px; overflow: hidden;">
+      <table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: <%= theme[:surface_background] %>; border: 1px solid <%= theme[:surface_border] %>; border-radius: 8px; overflow: hidden;">
         <tr>
           <td style="padding: 28px 28px 8px 28px;">
-            <h1 style="margin: 0; color: #1a202c; font-size: 22px; font-weight: 600; line-height: 1.35;">
+            <h1 style="margin: 0; color: <%= theme[:primary_text] %>; font-size: 22px; font-weight: 600; line-height: 1.35;">
               <%= h.call(title) %>
             </h1>
           </td>
         </tr>
         <tr>
           <td style="padding: 8px 28px 28px 28px;">
-            <p style="margin: 0; color: #4a5568; font-size: 16px; line-height: 1.6; white-space: pre-wrap;">
+            <p style="margin: 0; color: <%= theme[:body_text] %>; font-size: 16px; line-height: 1.6; white-space: pre-wrap;">
 <%= h.call(body) %></p>
             <% if deep_link -%>
             <p style="margin: 24px 0 0 0;">
-              <a href="<%= h.call(deep_link) %>" style="color: #2b6cb0; font-size: 14px; text-decoration: underline;">
+              <a href="<%= h.call(deep_link) %>" style="color: <%= theme[:primary_action] %>; font-size: 14px; text-decoration: underline;">
                 <%= h.call(deep_link) %>
               </a>
             </p>

data/app/views/command_tower/password_reset_mailer/reset_password.html.erb

@@ -1,11 +1,12 @@
-<table width="100%" cellpadding="0" cellspacing="0" border="0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: #f5f7fa; padding: 40px 20px;">
+<% theme = CommandTower::EmailTheme::Resolver.resolve -%>
+<table width="100%" cellpadding="0" cellspacing="0" border="0" style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: <%= theme[:canvas_background] %>; padding: 40px 20px;">
   <tr>
     <td align="center">
-      <table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: #ffffff; border-radius: 12px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); overflow: hidden;">
+      <table width="600" cellpadding="0" cellspacing="0" border="0" style="background-color: <%= theme[:surface_background] %>; border-radius: 12px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); overflow: hidden;">
         <!-- Header -->
         <tr>
-          <td style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 40px 30px; text-align: center;">
-            <h1 style="margin: 0; color: #ffffff; font-size: 28px; font-weight: 600; letter-spacing: -0.5px;">
+          <td style="background: <%= theme[:accent] %>; padding: 40px 30px; text-align: center;">
+            <h1 style="margin: 0; color: <%= theme[:text_on_accent] %>; font-size: 28px; font-weight: 600; letter-spacing: -0.5px;">
               Reset Your Password
             </h1>
           </td>
@@ -14,22 +15,22 @@
         <!-- Content -->
         <tr>
           <td style="padding: 40px 30px;">
-            <p style="margin: 0 0 20px 0; color: #4a5568; font-size: 16px; line-height: 1.6;">
-              Hello <strong style="color: #2d3748;"><%= @user.full_name %></strong>,
+            <p style="margin: 0 0 20px 0; color: <%= theme[:body_text] %>; font-size: 16px; line-height: 1.6;">
+              Hello <strong style="color: <%= theme[:primary_text] %>;"><%= @user.full_name %></strong>,
             </p>
 
-            <p style="margin: 0 0 30px 0; color: #4a5568; font-size: 16px; line-height: 1.6;">
+            <p style="margin: 0 0 30px 0; color: <%= theme[:body_text] %>; font-size: 16px; line-height: 1.6;">
               We received a request to reset your password for your <%= CommandTower.config.app.communication_name %> account. Click the button below to reset your password:
             </p>
 
             <!-- Reset Token Box -->
             <table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 30px 0;">
               <tr>
-                <td align="center" style="padding: 30px; background: linear-gradient(135deg, #f6f8fb 0%, #e9ecef 100%); border-radius: 8px; border: 2px dashed #cbd5e0;">
-                  <div style="font-size: 18px; font-weight: 600; color: #667eea; font-family: 'Courier New', monospace; text-align: center; word-break: break-all; padding: 10px;">
+                <td align="center" style="padding: 30px; background-color: <%= theme[:canvas_background] %>; border-radius: 8px; border: 2px dashed <%= theme[:surface_border] %>;">
+                  <div style="font-size: 18px; font-weight: 600; color: <%= theme[:accent] %>; font-family: 'Courier New', monospace; text-align: center; word-break: break-all; padding: 10px;">
                     <%= @token %>
                   </div>
-                  <p style="margin: 15px 0 0 0; color: #718096; font-size: 12px; text-transform: uppercase; letter-spacing: 1px;">
+                  <p style="margin: 15px 0 0 0; color: <%= theme[:muted_text] %>; font-size: 12px; text-transform: uppercase; letter-spacing: 1px;">
                     Reset Token
                   </p>
                 </td>
@@ -42,30 +43,30 @@
                 <td align="center" style="padding: 15px 0;">
                   <% reset_url = "#{CommandTower.config.app.composed_url}#{@reset_password_path}?token=#{@token}" %>
                   <% reset_url += "&email=#{CGI.escape(@email)}" if @require_email %>
-                  <a href="<%= reset_url %>" style="display: inline-block; padding: 14px 32px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: #ffffff; text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; text-align: center;">
+                  <a href="<%= reset_url %>" style="display: inline-block; padding: 14px 32px; background-color: <%= theme[:primary_action] %>; color: <%= theme[:text_on_accent] %>; text-decoration: none; border-radius: 8px; font-weight: 600; font-size: 16px; text-align: center;">
                     Reset Password
                   </a>
                 </td>
               </tr>
             </table>
 
-            <p style="margin: 30px 0 20px 0; color: #718096; font-size: 14px; line-height: 1.6;">
-              <strong style="color: #4a5568;">Important:</strong> This link will expire in <%= CommandTower.config.login.plain_text.password_reset.token_valid_for.inspect %>. If you didn't request a password reset, please ignore this email. Your password will remain unchanged.
+            <p style="margin: 30px 0 20px 0; color: <%= theme[:muted_text] %>; font-size: 14px; line-height: 1.6;">
+              <strong style="color: <%= theme[:body_text] %>;">Important:</strong> This link will expire in <%= CommandTower.config.login.plain_text.password_reset.token_valid_for.inspect %>. If you didn't request a password reset, please ignore this email. Your password will remain unchanged.
             </p>
 
-            <p style="margin: 20px 0 0 0; color: #718096; font-size: 14px; line-height: 1.6;">
+            <p style="margin: 20px 0 0 0; color: <%= theme[:muted_text] %>; font-size: 14px; line-height: 1.6;">
               If the button above doesn't work, copy and paste the reset token above into the password reset form on our website.
             </p>
 
             <!-- Alternative Reset URL Link -->
             <table width="100%" cellpadding="0" cellspacing="0" border="0" style="margin: 30px 0 0 0;">
               <tr>
-                <td align="center" style="padding: 20px; background-color: #f7fafc; border-radius: 8px; border: 1px solid #e2e8f0;">
-                  <p style="margin: 0 0 10px 0; color: #4a5568; font-size: 14px; font-weight: 600;">
+                <td align="center" style="padding: 20px; background-color: <%= theme[:canvas_background] %>; border-radius: 8px; border: 1px solid <%= theme[:surface_border] %>;">
+                  <p style="margin: 0 0 10px 0; color: <%= theme[:body_text] %>; font-size: 14px; font-weight: 600;">
                     Or visit the reset password page directly:
                   </p>
-                  <p style="margin: 0; color: #667eea; font-size: 14px; word-break: break-all;">
-                    <a href="<%= CommandTower.config.app.composed_url %><%= @reset_password_path %>" style="color: #667eea; text-decoration: underline;">
+                  <p style="margin: 0; color: <%= theme[:primary_action] %>; font-size: 14px; word-break: break-all;">
+                    <a href="<%= CommandTower.config.app.composed_url %><%= @reset_password_path %>" style="color: <%= theme[:primary_action] %>; text-decoration: underline;">
                       <%= CommandTower.config.app.composed_url %><%= @reset_password_path %>
                     </a>
                   </p>
@@ -77,14 +78,14 @@
 
         <!-- Footer -->
         <tr>
-          <td style="padding: 30px; background-color: #f7fafc; border-top: 1px solid #e2e8f0;">
-            <p style="margin: 0 0 15px 0; color: #4a5568; font-size: 14px; text-align: center; line-height: 1.6;">
+          <td style="padding: 30px; background-color: <%= theme[:canvas_background] %>; border-top: 1px solid <%= theme[:surface_border] %>;">
+            <p style="margin: 0 0 15px 0; color: <%= theme[:body_text] %>; font-size: 14px; text-align: center; line-height: 1.6;">
               Best regards,<br>
-              <strong style="color: #667eea;"><%= CommandTower.config.app.communication_name %> Team</strong>
+              <strong style="color: <%= theme[:accent] %>;"><%= CommandTower.config.app.communication_name %> Team</strong>
             </p>
 
             <p style="margin: 0; text-align: center;">
-              <a href="<%= CommandTower.config.app.composed_url %>" target="_blank" style="color: #667eea; text-decoration: none; font-size: 14px; font-weight: 500;">
+              <a href="<%= CommandTower.config.app.composed_url %>" target="_blank" style="color: <%= theme[:primary_action] %>; text-decoration: none; font-size: 14px; font-weight: 500;">
                 Visit <%= CommandTower.config.app.communication_name %>
               </a>
             </p>
@@ -96,7 +97,7 @@
       <table width="600" cellpadding="0" cellspacing="0" border="0" style="margin-top: 20px;">
         <tr>
           <td style="text-align: center; padding: 20px 0;">
-            <p style="margin: 0; color: #a0aec0; font-size: 12px; line-height: 1.5;">
+            <p style="margin: 0; color: <%= theme[:muted_text] %>; font-size: 12px; line-height: 1.5;">
               This is an automated message. Please do not reply to this email.
             </p>
           </td>

data/app/workflows/command_tower/workflows/auth/plain_text/login_workflow.rb

@@ -5,6 +5,8 @@ module CommandTower
     module Auth
       module PlainText
         class LoginWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          include CommandTower::Workflows::ClientCompatibility::RecommendationMeta
+
           retry_strategy :none
 
           def call(input:, request_context: nil)
@@ -24,6 +26,7 @@ module CommandTower
                   token_expires_at: data[:expires_at]
                 ),
                 http_status: :created,
+                meta: client_compatibility_meta,
                 response_effects: {
                   set_token: { token: data[:token], expires_at: data[:expires_at] },
                   ensure_csrf_cookie: { rotate: csrf_rotate_on_login? }

data/app/workflows/command_tower/workflows/auth/session/show_workflow.rb

@@ -5,6 +5,8 @@ module CommandTower
     module Auth
       module Session
         class ShowWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          include CommandTower::Workflows::ClientCompatibility::RecommendationMeta
+
           retry_strategy :none
 
           def call(current_user:, auth_context:)
@@ -30,6 +32,7 @@ module CommandTower
                 actor: auth_context.actor_user
               ),
               http_status: :ok,
+              meta: client_compatibility_meta,
               response_effects: response_effects
             )
           end

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/me/error_mapping.rb

@@ -33,7 +33,8 @@ module CommandTower
             :too_many_requests
           when CommandTower::Errors::Account::SmsCapabilityUnavailableError,
                CommandTower::Errors::Account::PushoverCapabilityUnavailableError,
-               CommandTower::Errors::Account::PushCapabilityUnavailableError
+               CommandTower::Errors::Account::PushCapabilityUnavailableError,
+               CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError
             :service_unavailable
           when CommandTower::Errors::Account::PhoneVerificationSendFailedError,
                CommandTower::Errors::Account::PushoverProviderUnavailableError

data/app/workflows/command_tower/workflows/me/experience_states/complete_workflow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module ExperienceStates
+        class CompleteWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, experience_key:, scope_type:, scope_identifier:, version:, auth_context: nil)
+            result = CommandTower::Services::Account::ExperienceStates::Complete.call(
+              user: current_user,
+              experience_key:,
+              scope_type:,
+              scope_identifier:,
+              version:,
+            )
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            if result.data[:created]
+              audit(
+                :experience_state_completed,
+                affected_user: current_user,
+                changes: {},
+                scope_class: :host,
+                host_context: {
+                  type: scope_type,
+                  identifier: scope_identifier,
+                },
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_view(result.data[:experience_state]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/experience_states/list_workflow.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module ExperienceStates
+        class ListWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(current_user:, auth_context: nil)
+            result = CommandTower::Services::Account::ExperienceStates::List.call(user: current_user)
+            unless result.success?
+              error = result.errors.first
+              return failure(
+                errors: result.errors,
+                http_status: CommandTower::Workflows::Me::ErrorMapping.http_status_for(error),
+              )
+            end
+
+            success(
+              payload: WorkflowSupport.serialize_collection(result.data[:experience_states]),
+              http_status: :ok,
+              response_effects: WorkflowSupport.expire_header_effects(auth_context),
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/experience_states/workflow_support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      module ExperienceStates
+        module WorkflowSupport
+          module_function
+
+          def expire_header_effects(auth_context)
+            return if auth_context.nil?
+
+            { set_expire_header: auth_context.token_expires_at }
+          end
+
+          def serialize_view(state)
+            CommandTower::Serializers::Me::ExperienceStates::ExperienceStateSerializer.serialize(state)
+          end
+
+          def serialize_collection(states)
+            CommandTower::Serializers::Me::ExperienceStates::ExperienceStateSerializer.serialize_collection(states)
+          end
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -111,6 +111,9 @@ CommandTower::Engine.routes.draw do
     patch "push/:id", to: "push#update"
     put "push/:id", to: "push#update"
     delete "push/:id", to: "push#destroy"
+
+    get "experience-states", to: "experience_states#index"
+    post "experience-states/complete", to: "experience_states#complete"
   end
 
   namespace :admin do

data/db/migrate/20260906180000_create_user_experience_states.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateUserExperienceStates < ActiveRecord::Migration[7.2]
+  def change
+    create_table :user_experience_states do |t|
+      t.timestamps
+      t.references :user, null: false, foreign_key: true
+      t.string :host_key, null: false, limit: 128
+      t.string :experience_key, null: false, limit: 128
+      t.string :scope_type, null: false, limit: 128
+      t.string :scope_identifier, null: false, limit: 128
+      t.string :version, null: false, limit: 128
+      t.datetime :completed_at, null: false
+    end
+
+    add_index :user_experience_states,
+              %i[user_id host_key experience_key scope_type scope_identifier version],
+              unique: true,
+              name: "index_user_experience_states_unique"
+
+    add_index :user_experience_states,
+              %i[user_id host_key],
+              name: "index_user_experience_states_on_user_host"
+  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`.
@@ -447,6 +458,27 @@ There is **no** `POST /me/push/verification`. Create and replace call `Endpoints
 
 ---
 
+## Experience states
+
+Durable completion facts for host-composed experiences. CommandTower stores opaque identity keys only — no League / Season / Tenant semantics and no presentation instructions such as `showWelcome`.
+
+`config.application.host_key` is **server-bound**. The client must not supply `hostKey` / `host_key`. When `host_key` is blank, both routes return **503** `experience_states_host_unconfigured`.
+
+| Method | Path | Body | Notes |
+|--------|------|------|--------|
+| `GET` | `/me/experience-states` | — | `{ experienceStates: [...] }` — **completed rows only** for the configured host |
+| `POST` | `/me/experience-states/complete` | `experienceKey`/`experience_key`, `scopeType`/`scope_type`, `scopeIdentifier`/`scope_identifier`, `version` (snake or camelCase) | Idempotent complete; returns the durable fact |
+
+**Fact fields:** `hostKey`, `experienceKey`, `scopeType`, `scopeIdentifier`, `version`, `completedAt`. Never `showWelcome` / applicability / presentation instructions.
+
+**RBAC:** `me_experience_states` (`index`, `complete`). Grant explicitly on host roles (dummy host `member` includes it).
+
+**Audit:** first durable creation emits `experience_state_completed` (opaque `host_context` type/identifier). Idempotent replay does not emit again.
+
+**Spec:** `spec/requests/command_tower/me/experience_states_spec.rb`.
+
+---
+
 ## Admin Workspace
 
 ### `GET /admin/workspace`

data/docs/controllers.md

@@ -21,6 +21,7 @@ This page is an **index** of route areas. Detailed request/response contracts li
 | Phone | `/me/phone*` | Phone endpoint + verification |
 | Pushover | `/me/pushover*` | Pushover endpoint lifecycle + verification |
 | Push | `/me/push*` | Expo push endpoint collection (register / replace / revoke) |
+| Experience states | `/me/experience-states*` | Durable completed experience-state facts (list / complete) |
 | Admin messaging | `/admin/messaging/announcements` | Cohort announcements |
 
 Exact paths depend on where the host mounts the engine.

data/docs/extending.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. |