command_tower 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 408a811a73f66bbaa2785653542b4b94e1824381f325f5f60a1cfc06e97a913a
-  data.tar.gz: 84a05525bd6cba9201672711ffee110ad20e856d3a0d278f23994610e57d389e
+  metadata.gz: 9e983f8f191ccb75948cdad73067d1cd43b7b1e5a8a3e0d34fc0130a76c313da
+  data.tar.gz: 5ef89ea100c06425afe3aee6f87b8b71503e4d28be6a4ff6e309af8a5b02c83f
 SHA512:
-  metadata.gz: 1fe68a093c4add78fb8143068ba91c2aad354219aa33ed8f7b80b3c205e0d72025888842364c26034ed1856b7899c2ce05f4d52ee8a4a94c4a7d53d989c04eb5
-  data.tar.gz: f538a68acaffbe712d185ab5fc843b171c2c07d95837e6d81fc3f334b70f6fb6b2d71b4ffeb61805c2c72ada4828dbe68f165fe304bf84ae28c8274b38eb4740
+  metadata.gz: 6555727a8b33efc95493ecdeec48067e39c8ee9eb4f1750c8fd183599a8d41bf1e763d538d379d0be7888697e6f09ca0795ebb643817d5aea2c548c61cd867f6
+  data.tar.gz: ca51dafb697b03848b2509f16660df1e9e349f325a01da7d589300ac7db0ee087df33c08d46194a97e60ae6cbc984de8bcbf1fbc65f41d7bd31f31013d64add4

data/app/controllers/command_tower/me/experience_states_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Me
+    class ExperienceStatesController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+
+      def index
+        result = CommandTower::Workflows::Me::ExperienceStates::ListWorkflow.call(
+          current_user: current_user,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      def complete
+        deserialized = CommandTower::Deserializers::Me::ExperienceStates::CompleteDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        result = CommandTower::Workflows::Me::ExperienceStates::CompleteWorkflow.call(
+          current_user: current_user,
+          experience_key: deserialized.input.experience_key,
+          scope_type: deserialized.input.scope_type,
+          scope_identifier: deserialized.input.scope_identifier,
+          version: deserialized.input.version,
+          auth_context: current_auth_context,
+        )
+        render_application_result(result)
+      end
+
+      private
+
+      def render_deserializer_errors
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [
+              CommandTower::Errors::ValidationError.new(
+                details: { base: "Missing or invalid experience state completion fields" },
+              ),
+            ],
+            http_status: :unprocessable_entity,
+          ),
+        )
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/experience_states/complete_deserializer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      module ExperienceStates
+        class CompleteDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+          Input = Data.define(:experience_key, :scope_type, :scope_identifier, :version)
+
+          MAX_LENGTH = 128
+
+          def call(params)
+            experience_key = extract(params, :experienceKey, :experience_key)
+            scope_type = extract(params, :scopeType, :scope_type)
+            scope_identifier = extract(params, :scopeIdentifier, :scope_identifier)
+            version = extract(params, :version, :Version)
+
+            if [experience_key, scope_type, scope_identifier, version].any?(&:blank?)
+              return failure(errors: { message: "missing_required_fields" })
+            end
+
+            if [experience_key, scope_type, scope_identifier, version].any? { |value| value.length > MAX_LENGTH }
+              return failure(errors: { message: "invalid_field_length" })
+            end
+
+            success(
+              Input.new(
+                experience_key:,
+                scope_type:,
+                scope_identifier:,
+                version:,
+              ),
+            )
+          end
+
+          private
+
+          def extract(params, *keys)
+            keys.each do |key|
+              raw = params[key] || params[key.to_s]
+              next if raw.nil?
+
+              value = raw.to_s.strip
+              return value unless value.empty?
+            end
+            ""
+          end
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/account/experience_states_host_unconfigured_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Account
+      class ExperienceStatesHostUnconfiguredError < CommandTower::Errors::ApplicationError
+        def code
+          "experience_states_host_unconfigured"
+        end
+
+        def message
+          "Experience states are currently unavailable"
+        end
+
+        def log_level
+          :warn
+        end
+      end
+    end
+  end
+end

data/app/models/command_tower/user_experience_state.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  class UserExperienceState < CommandTower::ApplicationRecord
+    self.table_name = "user_experience_states"
+
+    belongs_to :user
+
+    validates :host_key, :experience_key, :scope_type, :scope_identifier, :version, presence: true
+    validates :experience_key,
+              uniqueness: {
+                scope: %i[user_id host_key scope_type scope_identifier version],
+              }
+
+    scope :for_user_and_host, ->(user:, host_key:) { where(user:, host_key:) }
+  end
+end

data/app/serializers/command_tower/serializers/me/experience_states/experience_state_serializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      module ExperienceStates
+        class ExperienceStateSerializer
+          def self.serialize(state)
+            new(state).serialize
+          end
+
+          def self.serialize_collection(states)
+            {
+              experienceStates: Array(states).map { |state| serialize(state) },
+            }
+          end
+
+          def initialize(state)
+            @state = state
+          end
+
+          def serialize
+            {
+              hostKey: @state.host_key,
+              experienceKey: @state.experience_key,
+              scopeType: @state.scope_type,
+              scopeIdentifier: @state.scope_identifier,
+              version: @state.version,
+              completedAt: @state.completed_at&.iso8601,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/experience_states/complete.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module ExperienceStates
+        class Complete < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+          validate :experience_key, is_a: String, required: true
+          validate :scope_type, is_a: String, required: true
+          validate :scope_identifier, is_a: String, required: true
+          validate :version, is_a: String, required: true
+
+          def call
+            host_key = CommandTower.config.application.host_key.to_s
+            if host_key.blank?
+              context.fail!(
+                application_error: CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError.new,
+              )
+              return
+            end
+
+            identity = {
+              user:,
+              host_key:,
+              experience_key:,
+              scope_type:,
+              scope_identifier:,
+              version:,
+            }
+
+            existing = CommandTower::UserExperienceState.find_by(identity)
+            if existing
+              context.experience_state = existing
+              context.created = false
+              return
+            end
+
+            begin
+              created = CommandTower::UserExperienceState.create!(
+                identity.merge(completed_at: Time.current),
+              )
+              context.experience_state = created
+              context.created = true
+            rescue ActiveRecord::RecordNotUnique
+              recovered = CommandTower::UserExperienceState.find_by!(identity)
+              context.experience_state = recovered
+              context.created = false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/account/experience_states/list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Account
+      module ExperienceStates
+        class List < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            host_key = CommandTower.config.application.host_key.to_s
+            if host_key.blank?
+              context.fail!(
+                application_error: CommandTower::Errors::Account::ExperienceStatesHostUnconfiguredError.new,
+              )
+              return
+            end
+
+            context.experience_states = CommandTower::UserExperienceState.for_user_and_host(
+              user:,
+              host_key:,
+            ).order(:completed_at, :id).to_a
+          end
+        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

@@ -447,6 +447,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/host_integration_guide.md

@@ -32,10 +32,11 @@ In the host initializer, set at least:
 - `config.jwt.hmac_secret`
 - `config.signup_session.jwt_secret` (or `SIGNUP_SESSION_JWT_SECRET`)
 - `config.password_recovery_session.jwt_secret` (or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`)
+- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (for example experience states). Not client-supplied. Blank values cause Me experience-state routes to return **503** `experience_states_host_unconfigured`.
 
 Re-run `bin/rails command_tower:doctor`. Details: [Initializing — Configuration](initializing.md#configuration).
 
-Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
+Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb) (sets `host_key` to `"command_tower"`).
 
 ### Email / SMTP
 

data/docs/initializing.md

@@ -107,6 +107,7 @@ Required for production-ready hosts:
 - `config.jwt.hmac_secret` — typically `SECRET_KEY_BASE` / `Rails.application.secret_key_base`
 - `config.signup_session.jwt_secret` — or `SIGNUP_SESSION_JWT_SECRET`
 - `config.password_recovery_session.jwt_secret` — or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`
+- `config.application.host_key` — server-bound host/product identity for CT-generic user-scoped state (experience states). Not client-supplied. Blank → Me experience-state routes return **503**.
 
 Optional / feature-gated:
 

data/docs/upgrades/0.16.0.md

@@ -0,0 +1,30 @@
+# Upgrade: CommandTower 0.16.0
+
+**From:** `0.15.0`  
+**To:** `0.16.0`
+
+Minor release: generic Me experience-state persistence and HTTP (completion facts only). New migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Table `user_experience_states` | Durable completion rows keyed by `user + host_key + experience_key + scope_type + scope_identifier + version` |
+| `config.application.host_key` | **Required** non-blank String for Me experience-states. Server-bound; never client-supplied. Blank → **503** `experience_states_host_unconfigured` |
+| `GET /api/me/experience-states` | Authenticated list of **completed** facts for the current user on this host only |
+| `POST /api/me/experience-states/complete` | Idempotent complete; audit `experience_state_completed` **only on first durable create** |
+| RBAC `me_experience_states` | New entity (`index`, `complete`). Hosts must **explicitly grant** (not auto-added to a generic Admin role) |
+| Audit | Configurable event `experience_state_completed` with opaque `host_context` |
+
+## Host actions
+
+1. Bump gem to `0.16.0` (or `>= 0.16.0`).
+2. Set `config.application.host_key` (e.g. Pick’em `"pickem"`; CT rails_app `"command_tower"`).
+3. Copy engine migrations and migrate: `bundle exec rails command_tower:install:migrations` then `db:migrate`.
+4. Grant RBAC entity `me_experience_states` to the roles/groups that should use Me experience-states (typically `member`).
+
+## Not in this release
+
+- CommandTower frontend experience-states capability / hydrate hooks
+- Host Welcome product composition
+- Push silent-sync / Welcome notification step

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [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 |
 | [0.13.1](0.13.1.md) | Canonical `Intervention::Severity` constants (`blocking`, `warning`, `informational`) |

data/lib/command_tower/authorization/default.yml

@@ -76,6 +76,11 @@ entities:
       - update
       - destroy
       - test
+  - name: me_experience_states
+    controller: CommandTower::Me::ExperienceStatesController
+    only:
+      - index
+      - complete
   - name: me_audit_events
     controller: CommandTower::Me::AuditEventsController
     only:

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

@@ -14,6 +14,11 @@ module CommandTower
           desc: "The default name of the application",
           default_shown: "# Auto Populates to the name of the application"
 
+        add_composer :host_key,
+          allowed: String,
+          default: "",
+          desc: "Server-bound host/product identity for CT-generic user-scoped state. Not client-supplied."
+
         add_composer :communication_name,
           allowed: String,
           dynamic_default: :app_name,

data/lib/command_tower/configuration/registry/audit/config.rb

@@ -265,6 +265,18 @@ module CommandTower
               subject_type: "User",
               affected_user_required: true,
               global_visible_in_host_scope: true
+            },
+            experience_state_completed: {
+              label: "Experience state completed",
+              tags: %w[experience account],
+              enabled: true,
+              enablement_configurable: true,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: false,
+              affected_user_required: true
             }
           }.freeze
 

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.16.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.16.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 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
@@ -254,6 +255,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 +264,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
@@ -338,6 +341,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 +373,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
@@ -599,6 +604,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
@@ -738,6 +745,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 +784,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 +815,7 @@ 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/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb
@@ -915,6 +927,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: