command_tower 0.4.0 → 0.11.0

data/docs/host_integration_guide.md

@@ -0,0 +1,249 @@
+# Host Integration Guide
+
+**Start here** for integrating CommandTower into a new Rails host.
+
+This page owns the **order of operations**. It does not replace specialty docs: install details stay in [Initializing](initializing.md), HTTP contracts in [API reference](api_reference.md), boundaries in [Extending](extending.md).
+
+`command_tower:doctor` green means secrets/migrations look sane. It does **not** prove Me/Auth authorization works.
+
+## Prerequisites
+
+- A Rails host application (engine is mounted into the host)
+- `gem "command_tower"` in the host Gemfile (path, git, or released gem)
+- Host-owned database (and any host Redis/job stack your app already uses)
+
+## Step 1 — Install
+
+Follow [Initializing](initializing.md):
+
+```bash
+bundle install
+bin/rails command_tower:install
+bin/rails db:migrate
+bin/rails command_tower:doctor
+```
+
+That copies CT migrations, generates `config/initializers/command_tower.rb` (unless skipped), and mounts `CommandTower::Engine` (unless skipped).
+
+## Step 2 — Secrets and initializer
+
+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`)
+
+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).
+
+### Email / SMTP
+
+CommandTower owns ActionMailer delivery for engine mailers (email verification, password reset, messaging channel mail).
+
+| Environment | Delivery |
+|-------------|----------|
+| `test` | `:test` (in-memory `ActionMailer::Base.deliveries`; no external SMTP) |
+| development / production | `:smtp` unless the host explicitly sets `config.email.delivery_method` |
+
+Non-secret knobs live on `config.email.*` (defaults: `smtp.gmail.com`, port `587`, `plain`, STARTTLS auto). Secrets come from Credential Resolution:
+
+- `config.credentials.smtp.user_name` / `password`, or
+- ENV `GMAIL_USER_NAME` / `GMAIL_PASSWORD`
+
+`SmtpActionMailerBridge` merges resolved credentials into `action_mailer.smtp_settings` at the end of `CommandTower.configure`. Missing credentials fail at send when `raise_delivery_errors` is true. `From` uses the resolved SMTP username when present.
+
+Doctor does **not** probe SMTP connectivity.
+
+## Step 3 — Confirm mount path
+
+Ensure routes include something like:
+
+```ruby
+mount CommandTower::Engine => "/"   # or "/api"
+```
+
+Engine paths below are **relative to that mount**. Route area index: [Controllers](controllers.md).
+
+## Step 3b — Inherit execution-boundary bases
+
+Greenfield hosts should inherit CommandTower bases so Execution Context is established automatically:
+
+```ruby
+class ApplicationController < CommandTower::ApplicationController
+end
+
+class ApplicationJob < CommandTower::ApplicationJob
+end
+```
+
+Unauthenticated host endpoints (for example health checks) still receive HTTP `execution_uuid` / `correlation_id`. Successful authentication enriches the **same** context with `user_id` / `effective_user_id`.
+
+Workflows and services consume `CommandTower::Current` (or `execution_context`); they do not establish a new execution. For Rake/console, use `CommandTower.with_execution(source: :rake) { ... }`.
+
+`Auth::RequestContext` is JWT request/response transport, not Execution Context. Details: [Extending — Execution Context](extending.md#execution-context).
+
+Lifecycle and semantic events: [Eventing](eventing.md).
+
+If superclass inheritance is technically blocked, include `CommandTower::Execution::HttpBoundary` / `JobBoundary` on the host bases. That is an escape hatch, not the preferred contract.
+
+## Step 4 — Host RBAC (required)
+
+AuthorizeRequest **fails closed**. CommandTower ships **CT-owned** entity definitions (Me, session, inbox, Admin Workspace capabilities, …) and the platform full-access role (`owner`) in `lib/command_tower/authorization/default.yml`. CommandTower does **not** ship an operational `admin` role.
+
+The host YAML (default `config/rbac_groups.yml`) is a **second source**. Composition is additive. Hosts:
+
+1. Define product roles (typically `member`).
+2. **Grant names** of already-defined CT entities to those roles.
+3. Optionally define **host-owned** entities for **host** controllers.
+4. Deliberately compose operational Admin roles (least privilege or a broad host-owned `admin`).
+
+Do **not** copy CommandTower controller/entity blocks into the host file. Do **not** redefine `owner` or CT entity names. A host **may** define an `admin` group as host policy. Conflicts fail at boot (no last-write-wins).
+
+Dummy host grants-only example: [`rails_app/config/rbac_groups.yml`](../rails_app/config/rbac_groups.yml).
+
+```ruby
+CommandTower.configure do |c|
+  c.authorization.rbac_group_path = Rails.root.join("config/rbac_groups.yml")
+  c.authorization.default_membership_role = "member" # optional; nil disables
+end
+```
+
+`default_membership_role` is validated against the **composed** graph at boot. Unknown names fail configuration finalization.
+
+More: [Authorization](authorization.md), [Authentication & authorization guide](authentication_authorization_guide.md).
+
+Product audit names (later) register additively:
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.audit.event :wager_placed do |event|
+    event.allowed_changes = %i[status]
+    event.user_history = true
+  end
+end
+```
+
+Do **not** redefine CommandTower-owned audit names. Audit rows persist in CommandTower after `command_tower:install:migrations` and `db:migrate`. See [Audit](audit.md).
+
+Admin Workspace tools register additively (navigation metadata, not a dispatcher):
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.admin_workspace.tool :host_example do |tool|
+    tool.label = "Example"
+    tool.description = "Short launcher explanation of what this tool does."
+    tool.route = "/admin/example"
+    tool.group = :product
+    tool.sort_order = 300
+    tool.required_entity = :host_example_entity
+  end
+end
+```
+
+Do **not** redefine CommandTower-owned tool ids (`users`, `audit`, `messaging`). Hosts own copy for host tools (`description` soft ≤100 / hard ≤160). Manifest: [Admin Workspace](admin_workspace.md).
+
+Principal capabilities register additively (frontend-projectable ids, not a dump of all entities):
+
+```ruby
+CommandTower.configure do |c|
+  c.registry.principal_capabilities.capability :host_example do |capability|
+    capability.required_entity = :host_example_entity
+  end
+end
+```
+
+Do **not** redefine CommandTower-owned capability ids (`admin_workspace`, `admin_users`, `admin_impersonation`, `admin_audit_events`, `admin_messaging_announcements`). Projection: [Principal capabilities](principal_capabilities.md). Grant `admin_impersonation` only to roles that should start impersonation of visible users. Dummy `admin` does not include it.
+
+## Step 5 — Roles on users
+
+RBAC YAML defines what a role **may** do. Users still need that role assigned.
+
+- Specs and the dummy pattern use role name **`member`** for Me/Auth surfaces (including entity `principal_capabilities`).
+- When `authorization.default_membership_role` is set (for example `"member"`), register assigns that role **in the same transaction** as user create. Failure rolls back the user.
+- When it is `nil`, register does not attach roles. Hosts may assign via product logic, ops (`command_tower:users:create`), or other host workflows.
+- Installing CommandTower does **not** grant operational Admin access. Hosts must deliberately grant Admin entities.
+- Admin announcements need a host role that includes `admin_messaging_announcements`.
+- Admin Workspace manifest needs a host role that includes `admin_workspace`. Tool visibility still depends on each tool's `required_entity`.
+- `GET /auth/principal-capabilities` needs entity `principal_capabilities` on the caller’s roles (grant on `member` like session/me). Possessed Admin projectables still depend on the Admin entity grants above.
+- A host may define a broad `admin` role that grants many Admin entities — that is host policy, not a CommandTower default.
+## Step 6 — Enable feature gates you need
+
+When a gate is off, the route is **not drawn** → **404**.
+
+| Capability | Config |
+|------------|--------|
+| Plain-text login | `config.login.plain_text.enable = true` |
+| Email verification routes | `config.login.plain_text.email_verify = true` |
+| Password reset routes | `config.login.plain_text.password_reset = true` |
+| Email availability | `config.signup_session.email_availability = true` |
+| Username availability | `config.username.realtime_username_check = true` |
+
+Full gate list: [API reference — Feature gates](api_reference.md#feature-gates).
+
+## Step 7 — Choose auth client path
+
+- **API / mobile:** `Authorization: Bearer <jwt>` (default)
+- **Browser / SPA cookies:** enable `config.jwt.cookie` (+ CSRF as needed) — [Cookie authentication](cookie_authentication_guide.md)
+
+Engine HTTP success/error bodies use the application envelope `{ data, meta, errors }`. Host provisional helpers (`authenticate_user!`) can differ — [Authentication](authentication.md).
+
+## Step 8 — Smoke check
+
+With gates and RBAC in place (paths relative to your mount):
+
+1. `POST /auth/register` (always drawn) — with `default_membership_role` configured, the user is created **and** assigned that role in one transaction.
+2. `POST /auth/plain-text/login` (if enabled) — receive `data.token`.
+3. `GET /me` with Bearer token — expect **200** and envelope `data` (account payload).
+
+If you get **401**, authn failed. If you get **403**, fix Steps 4–5 before debugging clients.
+
+Contracts: [API reference](api_reference.md).
+
+## Step 9 — Messaging (when needed)
+
+Host owns:
+
+- Notification catalog / types
+- `platform_enabled_channels` / channel policy
+- Adapter credentials (email / SMS / Pushover)
+
+Emit from a **host product workflow** via `Communications::Produce` / `ProduceMany` — not by bypassing workflows. See [Messaging](messaging_integration_guide.md) and [Extending](extending.md).
+
+Phone/Pushover routes are always drawn; missing product readiness returns **503** capability errors.
+
+## Step 10 — Host tests
+
+```ruby
+require "command_tower/testing"
+CommandTower::Testing.install!
+```
+
+Details: [Testing](testing.md). Prefer `spec/requests/` patterns in the gem as HTTP contract proof.
+
+## Done when
+
+- Doctor passes for secrets/migrations
+- Host `rbac_groups.yml` maps Me/Auth entities
+- Users who should use Me surfaces have the host `member` (or equivalent) role
+- Needed feature gates are enabled
+- `GET /me` returns **200** with a Bearer token for a member user
+
+## Common failures
+
+| Symptom | Likely cause |
+|---------|----------------|
+| Doctor green, `GET /me` is **403** | Missing host RBAC YAML or user lacks `member` (Steps 4–5) |
+| `POST /auth/plain-text/login` is **404** | `login.plain_text.enable?` off (Step 6) |
+| Password-reset / availability **404** | Matching feature gate off |
+| Phone / Pushover **503** | Capability / adapters not ready (Step 9) |
+| Confused error JSON on host controllers | Provisional `authenticate_user!` vs engine envelope (Step 7) |
+
+## Related
+
+- [Initializing](initializing.md)
+- [Extending](extending.md)
+- [API reference](api_reference.md)
+- [Authentication & authorization guide](authentication_authorization_guide.md)
+- [Messaging](messaging_integration_guide.md)
+- [README](../README.md)

data/docs/initializing.md

@@ -0,0 +1,169 @@
+# Initializing CommandTower
+
+CommandTower is a Rails engine. The install flow below gets the engine **mounted, migrated, and doctor-checked**. That alone is not a fully usable Me/Auth host — complete RBAC, feature gates, and a smoke check via the [Host integration guide](host_integration_guide.md).
+
+Back to [README](../README.md).
+
+## Quick start
+
+```bash
+# Gemfile: gem "command_tower"  (or path/git source)
+bundle install
+
+bin/rails command_tower:install
+bin/rails db:migrate
+bin/rails command_tower:doctor
+```
+
+`command_tower:install` does **not** run `db:migrate`. Installing and migrating stay separate on purpose.
+
+### After install
+
+Continue with [Host integration](host_integration_guide.md):
+
+1. Host `rbac_groups.yml` product role that **grants** CT-owned Me/Auth entity names (required — otherwise authenticated Me/Auth calls **403**)
+2. Set `authorization.default_membership_role` (for example `"member"`) or assign roles some other supported way
+3. Enable feature gates you need (login, reset, availability, …)
+4. Smoke-check `GET /me` with a Bearer token
+5. Wire messaging catalog/adapters when you emit or use phone/Pushover
+
+### What `command_tower:install` does
+
+1. Runs Rails-native `command_tower:install:migrations` (copies engine migrations into the host `db/migrate/` with `*.command_tower.rb` scope).
+2. Runs `rails g command_tower:configure` unless skipped (creates initializer; mounts the engine).
+3. Prints next steps.
+
+### Flags / environment
+
+| Variable | Effect |
+|----------|--------|
+| `SKIP_CONFIGURE=1` | Migrations only (existing custom initializer / mount) |
+| `SKIP_MOUNT=1` | Generate initializer but do not mount routes |
+| `FORCE=1` | Overwrite an existing `config/initializers/command_tower.rb` |
+
+Examples:
+
+```bash
+SKIP_CONFIGURE=1 bin/rails command_tower:install
+SKIP_MOUNT=1 bin/rails command_tower:install
+FORCE=1 bin/rails command_tower:install
+```
+
+## Configure generator (optional)
+
+Prefer `command_tower:install` for greenfield hosts. The generator remains available:
+
+```bash
+bin/rails generate command_tower:configure
+bin/rails generate command_tower:configure --skip-routes
+bin/rails generate command_tower:configure --force
+```
+
+The generator:
+
+1. Adds `config/initializers/command_tower.rb` when missing (or overwrites with `--force`).
+2. Mounts `CommandTower::Engine` unless `--skip-routes` or already mounted.
+
+Dummy-host example initializer (engine development): [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
+
+## Database migrations
+
+CommandTower is the **sole authoring authority** for CommandTower-owned schema (`db/migrate` inside the gem). Hosts must **not** manually write, edit, or copy-paste CommandTower schema migrations (**AD-SCH-01**).
+
+### Fresh host install
+
+Handled by `command_tower:install` (step 1). Equivalent migration-only command:
+
+```bash
+bin/rails command_tower:install:migrations
+bin/rails db:migrate
+```
+
+`command_tower:install:migrations` is the standard Rails engine task (wrapper around `railties:install:migrations`). Re-running installation is **idempotent**: already-installed CommandTower migrations are skipped.
+
+Rails may **retimestamp** newly copied host files. That is normal. Do not hand-edit installed `*.command_tower.rb` files.
+
+### Upgrade workflow
+
+1. Bump/release the CommandTower gem dependency in the host.
+2. Run `bin/rails command_tower:install:migrations` (or `SKIP_CONFIGURE=1 bin/rails command_tower:install`).
+3. Run `bin/rails db:migrate`.
+4. Optionally run `bin/rails command_tower:doctor`.
+
+Do not re-run configure on hosts that already customize the initializer unless you intend to regenerate it (`FORCE=1`).
+
+### Adding future migrations
+
+1. Author the migration **only** in CommandTower `db/migrate/`.
+2. Release / bump the gem in the host.
+3. Install + migrate as above.
+
+Installed host copies are an **execution context**, not a second authoring home.
+
+## Configuration
+
+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`
+
+Optional / feature-gated:
+
+- Messaging SMS / Pushover adapters and credential resolution (`config.credentials.*` or ENV)
+- Cookie + CSRF JWT modes
+- Admin enablement, application URL, welcome content hooks
+
+The generated initializer documents available options via class_composer. Defaults live in CommandTower; do not duplicate them unnecessarily in the host.
+
+## Doctor
+
+```bash
+bin/rails command_tower:doctor
+```
+
+Checks Rails version compatibility, engine baseline migrations, host-installed migration copies, JWT / session secrets, and messaging adapter names. Failures abort with remediation text; warnings print but allow success.
+
+Doctor does **not** probe Redis/SMTP connectivity.
+
+## Host vs CommandTower responsibilities
+
+| Concern | Owner |
+|---------|--------|
+| Author CT schema migrations | CommandTower |
+| Install / run migrations | Host (via engine tasks + `db:migrate`) |
+| Product configuration / secrets | Host initializer + ENV |
+| Dual-author CT schema in the host | **Forbidden** |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `users already exists` on migrate | Database not empty / stale `schema.rb` load — migrate an empty DB, or dump schema after a clean migrate |
+| Install copies nothing new | Already installed — expected idempotency |
+| Missing tables after install | You installed but did not `db:migrate` |
+| Doctor fails on JWT default | Set `config.jwt.hmac_secret` from a real secret |
+| Accidental public engine mount | Use `SKIP_MOUNT=1` / `--skip-routes`, or mount at the path your product needs |
+
+## Existing customized hosts
+
+If the host already has a bespoke initializer and mount:
+
+```bash
+SKIP_CONFIGURE=1 bin/rails command_tower:install
+# same as: bin/rails command_tower:install:migrations
+bin/rails db:migrate
+```
+
+Do not run `rails g command_tower:configure` unless you intentionally want stock scaffolding.
+
+## Test suite factories
+
+Shared FactoryBot definitions ship with the gem. In the host test boot path:
+
+```ruby
+require "command_tower/testing"
+CommandTower::Testing.install!
+```
+
+Then extend with `FactoryBot.modify` as needed. See [Testing with CommandTower](testing.md).

data/docs/messaging_integration_guide.md

@@ -0,0 +1,87 @@
+# Messaging with CommandTower
+
+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).
+
+## Current surfaces
+
+| Concern | Path / entry |
+|---------|----------------|
+| User inbox (consume) | Engine `/me/inbox*` — see [API reference](api_reference.md#me-inbox) |
+| Preferences | Engine `/me/preferences*` — see [API reference](api_reference.md#preferences) |
+| Phone / Pushover endpoints | Engine `/me/phone*`, `/me/pushover*` (503 when capability unavailable) |
+| Single-recipient emit | `CommandTower::Services::Messaging::Communications::Produce` |
+| Multi-recipient emit | `CommandTower::Services::Messaging::Communications::ProduceMany` |
+| Admin cohort announce | Engine `POST /admin/messaging/announcements` |
+| Host ops announce | Host-owned rake/job (product-specific; not part of the gem) |
+
+Authentication uses JWT bearer or cookie session as documented in [Authentication](authentication.md). Me Inbox authorization requires host RBAC entities (dummy host uses a `member` role mapping). Admin announcements use entity `admin_messaging_announcements` (engine `default.yml` admin group).
+
+## Produce (single recipient)
+
+Call from a **product workflow**, not from a controller service bypass:
+
+```ruby
+CommandTower::Services::Messaging::Communications::Produce.call(
+  user: user,
+  notification_type_key: "welcome",
+  host_event_identity: "welcome/#{user.id}/#{SecureRandom.uuid}",
+  title: "Welcome",
+  body: "Thanks for joining.",
+  platform_enabled_channels: [:inbox, :email],
+  metadata: { source: "onboarding" } # optional
+)
+```
+
+| Kwarg | Required |
+|-------|----------|
+| `user` | yes (`User`) |
+| `notification_type_key` | yes (`String`) |
+| `host_event_identity` | yes (`String`) |
+| `title` | yes |
+| `body` | yes |
+| `platform_enabled_channels` | yes (`Array`) |
+| `metadata` | no (`Hash`) |
+
+## ProduceMany (multi recipient)
+
+| Kwarg | Required / notes |
+|-------|------------------|
+| `user_ids` | yes (`Array` of integer ids) |
+| `notification_type_key` | yes |
+| `campaign_identity` | yes — fan-out builds `host_event_identity` as `"#{campaign_identity}/#{user.id}"` |
+| `title`, `body` | yes |
+| `platform_enabled_channels` | yes |
+| `metadata` | optional |
+| `execution_mode` | optional, default `:async`; `:sync` capped at **25** recipients |
+
+Admin announcements HTTP is a product path over ProduceMany (async/sync, audience selection). Contract: [API reference — Admin messaging](api_reference.md#admin-messaging).
+
+## Me Inbox HTTP (summary)
+
+| Concern | Contract |
+|---------|----------|
+| List | `GET /me/inbox?limit=&offset=&scope=` — meta `{ limit, offset, totalCount }` |
+| Detail / open / archive / delete | `/me/inbox/:id` (+ `open`, `archive`) |
+| Bulk | `POST /me/inbox/bulk/{read,unread,archive,restore,delete}` with body `ids` |
+| Unread | `GET /me/inbox/unread-count` |
+
+Pagination detail: [pagination.md](pagination.md). Full catalog: [api_reference.md](api_reference.md#me-inbox).
+
+## Host responsibilities
+
+- Notification catalog content (registered into CommandTower notification types)
+- `platform_enabled_channels` / channel policy injection
+- Messaging adapter credentials (email / SMS / Pushover) via initializer or ENV
+- Host product roles that grant CT-owned Me inbox/preferences/phone/pushover entities (and `admin` if used)
+- Product-specific operational tooling (announce rake tasks, welcome copy)
+
+## Related
+
+- [Controllers / routes](controllers.md)
+- [API reference](api_reference.md)
+- [Extending](extending.md) — Produce from host workflows; Do-Not-Extend
+- [Initializing](initializing.md) — configuration and doctor
+- [Pagination](pagination.md)
+- [README](../README.md)

data/docs/models.md

@@ -0,0 +1,55 @@
+# CommandTower Models
+
+Core models live in the root / CommandTower namespaces and support authentication, authorization, and messaging ledger associations.
+
+Back to [README](../README.md).
+
+## User
+
+`User` is the primary identity model for host applications.
+
+It underpins [Authentication](authentication.md) and [Authorization](authorization.md), and participates in messaging via associations such as `messaging_communications`.
+
+Sensitive session invalidation uses the user’s verifier token — see [Sensitive changes](sensitive_routes.md).
+
+### Reopening `User` in the host
+
+Prefer services/workflows for new behavior. When you must reopen the class:
+
+```ruby
+require CommandTower::Engine.root.join("app", "models", "user.rb")
+
+class User
+  def self.my_class_method; end
+  def my_instance_method; end
+end
+```
+
+## UserSecret
+
+`UserSecret` backs validation and recovery-related secrets (for example plain-text email validation flows). It complements [Sensitive changes](sensitive_routes.md).
+
+### Reopening `UserSecret` in the host
+
+```ruby
+require CommandTower::Engine.root.join("app", "models", "user_secret.rb")
+
+class UserSecret
+  def self.my_class_method; end
+  def my_instance_method; end
+end
+```
+
+## Messaging models
+
+Engine-owned messaging persistence (communications, endpoints, preferences, and related records) ships with CommandTower. Prefer platform services/workflows for mutations; do not dual-author schema in the host ([Initializing](initializing.md)).
+
+## Audit ledger
+
+`CommandTower::Audit::Event` is the append-only platform ledger (`command_tower_audit_events`). Only `CommandTower::Audit::Persistence::Subscriber` writes rows. There are no foreign keys to users. Envelope `changes` persist as `change_set`. See [Audit](audit.md).
+
+## Related
+
+- [Architecture](architecture.md)
+- [Sensitive changes](sensitive_routes.md)
+- [Testing](testing.md) — shared factories for CT-owned models

data/docs/pagination.md

@@ -0,0 +1,47 @@
+# Pagination
+
+CommandTower exposes live HTTP list contracts that return pagination metadata: **Me Inbox**, **audit event lists** (`GET /me/audit-events`, `GET /admin/audit-events`), and **Admin Users** (`GET /admin/users`). These lists reuse the Inbox `limit` / `offset` / `totalCount` contract.
+
+Back to [README](../README.md).
+
+## Me Inbox list contract
+
+`GET /me/inbox` accepts query parameters:
+
+| Param | Default | Notes |
+|-------|---------|--------|
+| `limit` | `50` | Max `100` |
+| `offset` | `0` | |
+| `scope` | `"inbox"` | `"inbox"` or `"archived"` |
+
+Success envelope `meta`:
+
+```json
+{
+  "limit": 50,
+  "offset": 0,
+  "totalCount": 123
+}
+```
+
+`data` is an array of inbox items. Full route table: [API reference — Me Inbox](api_reference.md#me-inbox).
+
+Deserializer: `CommandTower::Deserializers::Messaging::Inbox::ListDeserializer`.
+
+## Global pagination config
+
+`CommandTower.config.pagination.limit` defaults to **10**. That value is a generic configuration default for pagination helpers — it is **not** the Me Inbox HTTP default (Inbox uses 50).
+
+```ruby
+CommandTower.configure do |c|
+  c.pagination.limit = 50
+end
+```
+
+There is no `pagination=true` / `page` / `cursor` query API on current engine HTTP surfaces. Admin audit list uses the same limit/offset contract as Inbox.
+
+## Related
+
+- [API reference](api_reference.md)
+- [Messaging](messaging_integration_guide.md)
+- [Controllers](controllers.md)