command_tower 0.15.0 → 0.17.0

data/lib/command_tower/configuration/registry/inbox_presentations/presentation_definition.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module InboxPresentations
+        class PresentationDefinition
+          include ClassComposer::Generator
+
+          add_composer :composer_class,
+            desc: "String class name of the registered presentation composer " \
+                  "(`.call(communication:, recipient_id:) -> Hash`), resolved via `.constantize` " \
+                  "at InboxDocumentRenderer render time — never at registration time",
+            allowed: String,
+            default: ""
+
+          # Explicit output projection (Rich Messaging corrective slice —
+          # ServiceResult/context leak fix). `InboxDocumentRenderer#presentation_block`
+          # slices the composer's raw result down to exactly these keys before
+          # it ever reaches `content.blocks[].data` — every other key (declared
+          # `ApplicationService` inputs, incidental intermediate context state,
+          # or anything else a composer happens to set) is dropped
+          # unconditionally, regardless of whether the composer is an
+          # `ApplicationService` or a plain Hash-returning class. This is a
+          # declared allow-list owned by the registration, not an inference
+          # from `ServiceResult`/`ApplicationService` argument metadata.
+          add_composer :output_keys,
+            desc: "Array of Symbol keys that are the ONLY keys copied from the composer's " \
+                  "result onto the Inbox wire (`content.blocks[].data`) — every other " \
+                  "context/result key (composer inputs, intermediate state, anything else) " \
+                  "is dropped at render time, regardless of composer shape",
+            allowed: Array,
+            default: []
+
+          attr_accessor :owner, :id
+
+          def validate_definition!(key:)
+            self.id = key.to_s
+            self.owner = owner&.to_sym || :host
+            self.composer_class = require_present_string!(composer_class, field: "composer_class", key:)
+            self.output_keys = require_present_output_keys!(output_keys, key:)
+          end
+
+          private
+
+          def require_present_string!(value, field:, key:)
+            text = value.to_s.strip
+            if text.empty?
+              raise CommandTower::InboxPresentations::InvalidPresentationDefinitionError,
+                "inbox presentation #{key} is missing #{field}"
+            end
+
+            text
+          end
+
+          def require_present_output_keys!(value, key:)
+            keys = Array(value).map { |entry| entry.to_s.strip }
+            if keys.empty? || keys.any?(&:empty?)
+              raise CommandTower::InboxPresentations::InvalidPresentationDefinitionError,
+                "inbox presentation #{key} is missing output_keys"
+            end
+
+            keys.map(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/current.rb

@@ -15,5 +15,6 @@ module CommandTower
     attribute :impersonation_activity_recorded, default: false
     attribute :remote_ip
     attribute :user_agent
+    attribute :client_compatibility_recommendation
   end
 end

data/lib/command_tower/engine.rb

@@ -22,12 +22,15 @@ module CommandTower
         # ensure defaults are instantiated and all variables are assigned
         CommandTower.config.class_composer_assign_defaults!(children: true)
         CommandTower::CredentialResolution::SmtpActionMailerBridge.apply!
+        CommandTower.config.registry.client_compatibility.apply_env_overlay!
 
         unless Rails.env.test?
           CommandTower.config.impersonation.validate!
           CommandTower.config.registry.audit.finalize!
           CommandTower.config.registry.admin_workspace.finalize!
           CommandTower.config.registry.principal_capabilities.finalize!
+          CommandTower.config.registry.client_compatibility.finalize!
+          CommandTower.config.registry.inbox_presentations.finalize!
           CommandTower.config.admin_scope.finalize!
           # Now that we can confirm all variables are defined, freeze all objects an their children
           CommandTower.config.class_composer_freeze_objects!(behavior: :raise, children: true)
@@ -62,6 +65,7 @@ module CommandTower
         entities = CommandTower::Authorization::Entity.entities
         CommandTower.config.registry.admin_workspace.validate_required_entities!(entities)
         CommandTower.config.registry.principal_capabilities.validate_required_entities!(entities)
+        CommandTower.config.registry.client_compatibility.validate!(entities)
         CommandTower.config.admin_scope.validate_scoped_tools!
       end
       CommandTower::Logging::Subscriber.attach!

data/lib/command_tower/inbox_presentations.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  # Rich Messaging Slice 2.5 — registry of registered Inbox presentation
+  # capabilities (semantic keys such as `pickem.make_picks`) mapped to a
+  # trusted, host- or CommandTower-owned composer class. See
+  # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_PRESENTATION_AUTHORITY.md
+  # Part I and
+  # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md §9.
+  module InboxPresentations
+    class Error < CommandTower::Error; end
+
+    class UnregisteredCapabilityError < Error; end
+    class DuplicateCapabilityError < Error; end
+    class InvalidKeyError < Error; end
+    class InvalidPresentationDefinitionError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end

data/lib/command_tower/install/baseline.rb

@@ -15,6 +15,7 @@ module CommandTower
         20260817000001_add_scope_columns_to_command_tower_audit_events.rb
         20260817000003_create_command_tower_impersonation_sessions.rb
         20260826140000_add_deleted_at_to_users.rb
+        20260906180000_create_user_experience_states.rb
       ].freeze
 
       module_function

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.15.0"
+  VERSION = "0.17.0"
 end

data/spec/factories/user_experience_states.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :user_experience_state, class: "CommandTower::UserExperienceState" do
+    user
+    host_key { "command_tower" }
+    experience_key { "welcome" }
+    scope_type { "example_scope" }
+    sequence(:scope_identifier) { |n| n.to_s }
+    version { "v1" }
+    completed_at { Time.current }
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -211,6 +211,7 @@ files:
 - app/controllers/command_tower/auth/username/availability_controller.rb
 - app/controllers/command_tower/me/account_controller.rb
 - app/controllers/command_tower/me/audit_events_controller.rb
+- app/controllers/command_tower/me/experience_states_controller.rb
 - app/controllers/command_tower/me/inbox_controller.rb
 - app/controllers/command_tower/me/name_controller.rb
 - app/controllers/command_tower/me/password_controller.rb
@@ -230,6 +231,7 @@ files:
 - app/controllers/concerns/command_tower/auth/invalid_credentials_deserializer_renderer.rb
 - app/controllers/concerns/command_tower/auth/password_recovery_session_boundary.rb
 - app/controllers/concerns/command_tower/auth/signup_session_boundary.rb
+- app/controllers/concerns/command_tower/execution/client_compatibility_boundary.rb
 - app/controllers/concerns/command_tower/execution/http_boundary.rb
 - app/deserializers/command_tower/deserializers/admin/messaging/create_announcement_deserializer.rb
 - app/deserializers/command_tower/deserializers/admin/scope_parameter.rb
@@ -254,6 +256,7 @@ files:
 - app/deserializers/command_tower/deserializers/intervention/envelope_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/change_password_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/delete_account_deserializer.rb
+- app/deserializers/command_tower/deserializers/me/experience_states/complete_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/phone_verification/verify_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/push/token_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/pushover/credentials_deserializer.rb
@@ -262,6 +265,7 @@ files:
 - app/deserializers/command_tower/deserializers/messaging/inbox.rb
 - app/deserializers/command_tower/deserializers/messaging/preferences/show_deserializer.rb
 - app/deserializers/command_tower/deserializers/messaging/preferences/update_deserializer.rb
+- app/errors/command_tower/errors/account/experience_states_host_unconfigured_error.rb
 - app/errors/command_tower/errors/account/phone_already_verified_error.rb
 - app/errors/command_tower/errors/account/phone_missing_error.rb
 - app/errors/command_tower/errors/account/phone_verification_code_invalid_error.rb
@@ -306,6 +310,7 @@ files:
 - app/errors/command_tower/errors/auth/signup_session_rate_limit_error.rb
 - app/errors/command_tower/errors/auth/verification_code_invalid_error.rb
 - app/errors/command_tower/errors/auth/verification_send_failed_error.rb
+- app/errors/command_tower/errors/client_update_required_error.rb
 - app/errors/command_tower/errors/continuation_exhausted_error.rb
 - app/errors/command_tower/errors/forbidden_error.rb
 - app/errors/command_tower/errors/internal_error.rb
@@ -338,6 +343,7 @@ files:
 - app/models/command_tower/messaging/endpoint_pushover_credential.rb
 - app/models/command_tower/messaging/inbox_item.rb
 - app/models/command_tower/messaging/notification_preference.rb
+- app/models/command_tower/user_experience_state.rb
 - app/models/user.rb
 - app/models/user_secret.rb
 - app/serializers/command_tower/serializers/admin/messaging/announcement_response_serializer.rb
@@ -369,6 +375,7 @@ files:
 - app/serializers/command_tower/serializers/me/account_serializer.rb
 - app/serializers/command_tower/serializers/me/change_password_response_serializer.rb
 - app/serializers/command_tower/serializers/me/delete_account_response_serializer.rb
+- app/serializers/command_tower/serializers/me/experience_states/experience_state_serializer.rb
 - app/serializers/command_tower/serializers/me/push_serializer.rb
 - app/serializers/command_tower/serializers/me/pushover_serializer.rb
 - app/serializers/command_tower/serializers/messaging/inbox.rb
@@ -404,6 +411,7 @@ files:
 - app/services/command_tower/clients/transport/request.rb
 - app/services/command_tower/clients/transport/response.rb
 - app/services/command_tower/clients/url.rb
+- app/services/command_tower/email_theme/resolver.rb
 - app/services/command_tower/identity/phone/normalizer.rb
 - app/services/command_tower/identity/phone_verification/sms_configuration.rb
 - app/services/command_tower/identity/phone_verification/sms_transport.rb
@@ -587,11 +595,14 @@ files:
 - app/services/command_tower/messaging/recipient_readiness/recipient_result.rb
 - app/services/command_tower/messaging/recipient_readiness/unknown_channel_error.rb
 - app/services/command_tower/messaging/rendering/channel_renderer.rb
+- app/services/command_tower/messaging/rendering/inbox_document.rb
+- app/services/command_tower/messaging/rendering/inbox_document_renderer.rb
 - app/services/command_tower/messaging/rendering/render_error.rb
 - app/services/command_tower/messaging/rendering/rendered_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_push_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_pushover_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_sms_payload.rb
+- app/services/command_tower/messaging/rendering/template_resolver.rb
 - app/services/command_tower/secrets.rb
 - app/services/command_tower/secrets/cleanse.rb
 - app/services/command_tower/secrets/generate.rb
@@ -599,6 +610,8 @@ files:
 - app/services/command_tower/service_base.rb
 - app/services/command_tower/service_logging.rb
 - app/services/command_tower/services/account/clear_phone.rb
+- app/services/command_tower/services/account/experience_states/complete.rb
+- app/services/command_tower/services/account/experience_states/list.rb
 - app/services/command_tower/services/account/phone_verification/send.rb
 - app/services/command_tower/services/account/phone_verification/verify.rb
 - app/services/command_tower/services/account/push/check_self_test_rate_limit.rb
@@ -653,6 +666,7 @@ files:
 - app/services/command_tower/services/auth/signup_session/validate.rb
 - app/services/command_tower/services/auth/tombstone_user.rb
 - app/services/command_tower/services/auth/username_availability.rb
+- app/services/command_tower/services/client_compatibility/evaluate.rb
 - app/services/command_tower/services/impersonation/create.rb
 - app/services/command_tower/services/impersonation/end.rb
 - app/services/command_tower/services/impersonation/record_activity.rb
@@ -730,6 +744,8 @@ files:
 - app/workflows/command_tower/workflows/auth/signup_session/authenticate_workflow.rb
 - app/workflows/command_tower/workflows/auth/signup_session/create_workflow.rb
 - app/workflows/command_tower/workflows/auth/username_availability_workflow.rb
+- app/workflows/command_tower/workflows/client_compatibility/evaluate_workflow.rb
+- app/workflows/command_tower/workflows/client_compatibility/recommendation_meta.rb
 - app/workflows/command_tower/workflows/impersonation/error_mapping.rb
 - app/workflows/command_tower/workflows/impersonation/start_workflow.rb
 - app/workflows/command_tower/workflows/impersonation/stop_workflow.rb
@@ -738,6 +754,9 @@ files:
 - app/workflows/command_tower/workflows/me/delete_account_workflow.rb
 - app/workflows/command_tower/workflows/me/error_mapping.rb
 - app/workflows/command_tower/workflows/me/error_status.rb
+- app/workflows/command_tower/workflows/me/experience_states/complete_workflow.rb
+- app/workflows/command_tower/workflows/me/experience_states/list_workflow.rb
+- app/workflows/command_tower/workflows/me/experience_states/workflow_support.rb
 - app/workflows/command_tower/workflows/me/phone_verification/send_workflow.rb
 - app/workflows/command_tower/workflows/me/phone_verification/verify_workflow.rb
 - app/workflows/command_tower/workflows/me/push/create_workflow.rb
@@ -774,6 +793,7 @@ files:
 - db/migrate/20260817000001_add_scope_columns_to_command_tower_audit_events.rb
 - db/migrate/20260817000003_create_command_tower_impersonation_sessions.rb
 - db/migrate/20260826140000_add_deleted_at_to_users.rb
+- db/migrate/20260906180000_create_user_experience_states.rb
 - docs/admin_workspace.md
 - docs/api_reference.md
 - docs/architecture.md
@@ -804,6 +824,8 @@ files:
 - docs/upgrades/0.13.1.md
 - docs/upgrades/0.14.0.md
 - docs/upgrades/0.15.0.md
+- docs/upgrades/0.16.0.md
+- docs/upgrades/0.17.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb
@@ -826,6 +848,8 @@ files:
 - lib/command_tower/authorization/effective_entity_grants.rb
 - lib/command_tower/authorization/entity.rb
 - lib/command_tower/authorization/role.rb
+- lib/command_tower/client_compatibility.rb
+- lib/command_tower/client_compatibility/version.rb
 - lib/command_tower/configuration/account_deletion/config.rb
 - lib/command_tower/configuration/admin/config.rb
 - lib/command_tower/configuration/admin_scope/config.rb
@@ -838,6 +862,7 @@ files:
 - lib/command_tower/configuration/credentials/smtp.rb
 - lib/command_tower/configuration/credentials/twilio.rb
 - lib/command_tower/configuration/email/config.rb
+- lib/command_tower/configuration/email_theme/config.rb
 - lib/command_tower/configuration/identity/config.rb
 - lib/command_tower/configuration/identity/phone_verification.rb
 - lib/command_tower/configuration/impersonation/config.rb
@@ -861,7 +886,15 @@ files:
 - lib/command_tower/configuration/registry/admin_workspace/tool_definition.rb
 - lib/command_tower/configuration/registry/audit/config.rb
 - lib/command_tower/configuration/registry/audit/event_definition.rb
+- lib/command_tower/configuration/registry/client_compatibility/binding_definition.rb
+- lib/command_tower/configuration/registry/client_compatibility/config.rb
+- lib/command_tower/configuration/registry/client_compatibility/contract_definition.rb
+- lib/command_tower/configuration/registry/client_compatibility/entity_requirement_definition.rb
+- lib/command_tower/configuration/registry/client_compatibility/minimum_overrides.rb
+- lib/command_tower/configuration/registry/client_compatibility/platform_definition.rb
 - lib/command_tower/configuration/registry/config.rb
+- lib/command_tower/configuration/registry/inbox_presentations/config.rb
+- lib/command_tower/configuration/registry/inbox_presentations/presentation_definition.rb
 - lib/command_tower/configuration/registry/principal_capabilities/capability_definition.rb
 - lib/command_tower/configuration/registry/principal_capabilities/config.rb
 - lib/command_tower/configuration/signup_session/config.rb
@@ -884,6 +917,7 @@ files:
 - lib/command_tower/impersonation/apply_overlay.rb
 - lib/command_tower/impersonation/clear_overlay_for_audit.rb
 - lib/command_tower/impersonation/establish_identity.rb
+- lib/command_tower/inbox_presentations.rb
 - lib/command_tower/install/baseline.rb
 - lib/command_tower/install/doctor.rb
 - lib/command_tower/intervention/severity.rb
@@ -915,6 +949,7 @@ files:
 - spec/factories/messaging.rb
 - spec/factories/role.rb
 - spec/factories/user.rb
+- spec/factories/user_experience_states.rb
 - spec/factories/user_secret.rb
 homepage: https://github.com/matt-taylor/command_tower
 licenses: