dexkit 0.8.0 → 0.10.0

data/guides/llm/FORM.md

@@ -10,58 +10,80 @@ All examples below build on this form unless noted otherwise:
 
 ```ruby
 class OnboardingForm < Dex::Form
+  description "Employee onboarding"
   model User
 
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-  attribute :department, :string
-  attribute :start_date, :date
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :department, :string
+  field :start_date, :date
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: true
-  validates :first_name, :last_name, :department, presence: true
-  validates :start_date, presence: true
+  validates :email, uniqueness: true
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    attribute :postal_code, :string
-    attribute :country, :string
-
-    validates :street, :city, :country, presence: true
+    field :street, :string
+    field :city, :string
+    field :postal_code, :string
+    field :country, :string
+    field? :apartment, :string
   end
 
   nested_many :documents do
-    attribute :document_type, :string
-    attribute :document_number, :string
-
-    validates :document_type, :document_number, presence: true
+    field :document_type, :string
+    field :document_number, :string
   end
 end
 ```
 
 ---
 
-## Defining Forms
+## Declaring Fields
 
-Forms use ActiveModel under the hood. Attributes are declared with `attribute` (same as ActiveModel::Attributes).
+### `field` — required
+
+Declares a required field. Auto-adds presence validation. Unconditional `validates :attr, presence: true` deduplicates with it; scoped or conditional presence validators do not make the field optional outside those cases.
 
 ```ruby
-class ProfileForm < Dex::Form
-  attribute :name, :string
-  attribute :age, :integer
-  attribute :bio, :string
-  attribute :active, :boolean, default: true
-  attribute :born_on, :date
-end
+field :name, :string
+field :email, :string, desc: "Work email"
+field :currency, :string, default: "USD"
+```
+
+### `field?` — optional
+
+Declares an optional field. Defaults to `nil` unless overridden.
+
+```ruby
+field? :notes, :string
+field? :priority, :integer, default: 0
 ```
 
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `desc:` | Human-readable description (for introspection and JSON Schema) |
+| `default:` | Default value (forwarded to ActiveModel) |
+
 ### Available types
 
 `:string`, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:time`.
 
+### `attribute` escape hatch
+
+Raw ActiveModel `attribute` is still available. Not tracked in field registry, no auto-presence, not in exports.
+
+### Boolean fields
+
+`field :active, :boolean` checks for `nil` (not `blank?`), so `false` is valid.
+
 ### `model(klass)`
 
 Declares the backing model class. Used by:
@@ -93,11 +115,11 @@ normalizes :name, :email, with: -> { _1&.strip.presence }   # multiple attrs
 
 ## Validation
 
-Full ActiveModel validation DSL:
+Full ActiveModel validation DSL. Required fields auto-validate presence — no need to add `validates :name, presence: true` when using `field :name, :string`.
 
 ```ruby
-validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :name, length: { minimum: 2, maximum: 100 }
 validates :role, inclusion: { in: %w[admin user] }
 validates :email, uniqueness: true                    # checks database
 validate :custom_validation_method
@@ -111,6 +133,15 @@ form.errors[:email]      # => ["can't be blank"]
 form.errors.full_messages # => ["Email can't be blank"]
 ```
 
+### Contextual requirements
+
+Use `field?` with an explicit validation context:
+
+```ruby
+field? :published_at, :datetime
+validates :published_at, presence: true, on: :publish
+```
+
 ### ValidationError
 
 ```ruby
@@ -121,6 +152,94 @@ error.form     # => the form instance
 
 ---
 
+## Ambient Context
+
+Auto-fill fields from `Dex.context` – same DSL as Operation and Event:
+
+```ruby
+class Order::Form < Dex::Form
+  field :locale, :string
+  field :currency, :string
+
+  context :locale                       # shorthand: field name = context key
+  context currency: :default_currency   # explicit: field name → context key
+end
+
+Dex.with_context(locale: "en", default_currency: "USD") do
+  form = Order::Form.new
+  form.locale    # => "en"
+  form.currency  # => "USD"
+end
+```
+
+Explicit values always win. Context references must point to declared fields or attributes.
+
+---
+
+## Registry & Export
+
+### Description
+
+```ruby
+class OnboardingForm < Dex::Form
+  description "Employee onboarding"
+end
+
+OnboardingForm.description  # => "Employee onboarding"
+```
+
+### Registry
+
+```ruby
+Dex::Form.registry  # => #<Set: {OnboardingForm, ...}>
+```
+
+### Class-level `to_h`
+
+```ruby
+OnboardingForm.to_h
+# => {
+#   name: "OnboardingForm",
+#   description: "Employee onboarding",
+#   fields: {
+#     first_name: { type: :string, required: true },
+#     email: { type: :string, required: true },
+#     notes: { type: :string, required: false },
+#     ...
+#   },
+#   nested: {
+#     address: { type: :one, fields: { ... }, nested: { ... } },
+#     documents: { type: :many, fields: { ... } }
+#   }
+# }
+```
+
+### `to_json_schema`
+
+```ruby
+OnboardingForm.to_json_schema
+# => {
+#   "$schema": "https://json-schema.org/draft/2020-12/schema",
+#   type: "object",
+#   title: "OnboardingForm",
+#   description: "Employee onboarding",
+#   properties: { email: { type: "string" }, ... },
+#   required: ["first_name", "last_name", "email", ...],
+#   additionalProperties: false
+# }
+```
+
+### Global export
+
+```ruby
+Dex::Form.export(format: :json_schema)
+# => [{ ... OnboardingForm schema ... }, ...]
+```
+
+Bulk export returns top-level named forms only. Nested helper classes generated by `nested_one` and `nested_many` stay embedded in their parent export instead of appearing as separate entries.
+
+---
+
 ## Nested Forms
 
 ### `nested_one`
@@ -129,9 +248,9 @@ One-to-one nested form. Automatically coerces Hash input.
 
 ```ruby
 nested_one :address do
-  attribute :street, :string
-  attribute :city, :string
-  validates :street, :city, presence: true
+  field :street, :string
+  field :city, :string
+  field? :apartment, :string
 end
 ```
 
@@ -152,9 +271,8 @@ One-to-many nested form. Handles Array, Rails numbered Hash, and `_destroy`.
 
 ```ruby
 nested_many :documents do
-  attribute :document_type, :string
-  attribute :document_number, :string
-  validates :document_type, :document_number, presence: true
+  field :document_type, :string
+  field :document_number, :string
 end
 ```
 
@@ -190,7 +308,7 @@ Override the auto-generated constant name:
 
 ```ruby
 nested_one :address, class_name: "HomeAddress" do
-  attribute :street, :string
+  field :street, :string
 end
 # Creates MyForm::HomeAddress instead of MyForm::Address
 ```
@@ -224,7 +342,7 @@ validates :email, uniqueness: true
 | `model:` | Explicit model class | `uniqueness: { model: User }` |
 | `attribute:` | Column name if different | `uniqueness: { attribute: :email }` |
 | `scope:` | Scoped uniqueness | `uniqueness: { scope: :tenant_id }` |
-| `case_sensitive:` | Case-insensitive check | `uniqueness: { case_sensitive: false }` |
+| `case_sensitive:` | Case-insensitive check (`LOWER()` on ActiveRecord, case-insensitive regex on Mongoid) | `uniqueness: { case_sensitive: false }` |
 | `conditions:` | Extra query conditions | `uniqueness: { conditions: -> { where(active: true) } }` |
 | `message:` | Custom error message | `uniqueness: { message: "already registered" }` |
 
@@ -237,7 +355,7 @@ validates :email, uniqueness: true
 
 ### Record exclusion
 
-When `form.record` is persisted, the current record is excluded from the uniqueness check (for updates).
+When `form.record` is persisted, the current record is excluded from the uniqueness check (for updates) on both ActiveRecord and Mongoid-backed forms.
 
 ---
 
@@ -306,7 +424,7 @@ form.to_hash  # alias for to_h
 
 ### Controller pattern
 
-Strong parameters (`permit`) are not required — the form's attribute declarations are the whitelist. Just `require` the top-level key:
+Strong parameters (`permit`) are not required — the form's field declarations are the whitelist. Just `require` the top-level key:
 
 ```ruby
 class OnboardingController < ApplicationController
@@ -405,33 +523,34 @@ A form spanning User, Employee, and Address — the core reason form objects exi
 
 ```ruby
 class OnboardingForm < Dex::Form
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-  attribute :department, :string
-  attribute :position, :string
-  attribute :start_date, :date
+  description "Employee onboarding"
+
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :department, :string
+  field :position, :string
+  field :start_date, :date
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: { model: User }
-  validates :first_name, :last_name, :department, :position, presence: true
-  validates :start_date, presence: true
+  validates :email, uniqueness: { model: User }
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    attribute :postal_code, :string
-    attribute :country, :string
-
-    validates :street, :city, :country, presence: true
+    field :street, :string
+    field :city, :string
+    field :postal_code, :string
+    field :country, :string
+    field? :apartment, :string
   end
 
   nested_many :documents do
-    attribute :document_type, :string
-    attribute :document_number, :string
-
-    validates :document_type, :document_number, presence: true
+    field :document_type, :string
+    field :document_number, :string
   end
 
   def self.for(user)
@@ -484,23 +603,38 @@ Forms are standard ActiveModel objects. Test them with plain Minitest — no spe
 
 ```ruby
 class OnboardingFormTest < Minitest::Test
-  def test_validates_required_fields
+  def test_required_fields_validated
     form = OnboardingForm.new
     assert form.invalid?
     assert form.errors[:email].any?
     assert form.errors[:first_name].any?
   end
 
+  def test_optional_fields_allowed_blank
+    form = OnboardingForm.new(
+      first_name: "Alice", last_name: "Smith",
+      email: "alice@example.com", department: "Eng",
+      position: "Dev", start_date: Date.today, locale: "en"
+    )
+    assert form.valid?
+    assert_nil form.notes
+  end
+
   def test_normalizes_email
     form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ")
     assert_equal "alice@example.com", form.email
   end
 
+  def test_context_fills_locale
+    form = Dex.with_context(locale: "en") { OnboardingForm.new }
+    assert_equal "en", form.locale
+  end
+
   def test_nested_validation_propagation
     form = OnboardingForm.new(
       first_name: "Alice", last_name: "Smith",
       email: "alice@example.com", department: "Eng",
-      position: "Developer", start_date: Date.today,
+      position: "Developer", start_date: Date.today, locale: "en",
       address: { street: "", city: "", country: "" }
     )
     assert form.invalid?
@@ -516,5 +650,12 @@ class OnboardingFormTest < Minitest::Test
     assert_equal "Alice", h[:first_name]
     assert_equal "123 Main", h[:address][:street]
   end
+
+  def test_json_schema_export
+    schema = OnboardingForm.to_json_schema
+    assert_equal "object", schema[:type]
+    assert_includes schema[:required], "first_name"
+    refute_includes schema[:required], "notes"
+  end
 end
 ```

data/guides/llm/OPERATION.md

@@ -95,7 +95,7 @@ prop? :note, String                       # optional (nilable, default: nil)
 
 ### _Ref(Model)
 
-Accepts model instances or IDs, coerces IDs via `Model.find(id)`. With `lock: true`, uses `Model.lock.find(id)` (SELECT FOR UPDATE). Instances pass through without re-locking. In serialization (recording, async), stores model ID only. IDs are treated as strings in JSON Schema – this supports integer PKs, UUIDs, and Mongoid BSON::ObjectId equally.
+Accepts model instances or IDs, coerces IDs via `Model.find(id)`. With `lock: true`, uses `Model.lock.find(id)` (SELECT FOR UPDATE) – requires a model that responds to `.lock` (ActiveRecord). Mongoid documents do not support row locks and raise `ArgumentError` at declaration time. Instances pass through without re-locking. In serialization (recording, async), stores model ID only via `id.as_json`, so Mongoid BSON::ObjectId values are safe in ActiveJob payloads too. IDs are treated as strings in JSON Schema – this supports integer PKs, UUIDs, and Mongoid BSON::ObjectId equally.
 
 Outside the class body (e.g., in tests), use `Dex::RefType.new(Model)` instead of `_Ref(Model)`.
 
@@ -264,7 +264,7 @@ info = Order::Place.explain(product: product, customer: customer, quantity: 2)
 #   transaction: { enabled: true },
 #   rescue_from: { "Stripe::CardError" => :card_declined },
 #   callbacks: { before: 1, after: 2, around: 0 },
-#   pipeline: [:result, :guard, :once, :lock, :record, :transaction, :rescue, :callback],
+#   pipeline: [:trace, :result, :guard, :once, :lock, :record, :transaction, :rescue, :callback],
 #   callable: true
 # }
 ```
@@ -408,11 +408,11 @@ end
 
 ## Transactions
 
-Operations run inside database transactions by default. All changes roll back on error. Nested operations share the outer transaction.
+Operations run inside database transactions when Dex has an active transaction adapter. ActiveRecord is auto-detected. In Mongoid-only apps, no adapter is active, so transactions are automatically disabled – but `after_commit` still works (callbacks fire immediately after success). If you need Mongoid transactions, use `Mongoid.transaction` directly inside `perform`.
 
 ```ruby
 transaction false        # disable
-transaction :mongoid     # adapter override (default: auto-detect AR → Mongoid)
+transaction :active_record  # explicit adapter
 ```
 
 Child classes can re-enable: `transaction true`.
@@ -433,7 +433,7 @@ end
 Callbacks are always deferred — they run after the outermost operation boundary succeeds:
 
 - **Transactional operations:** deferred until the DB transaction commits.
-- **Non-transactional operations:** queued in memory, flushed after the operation pipeline completes successfully.
+- **Non-transactional operations (including Mongoid-only):** queued in memory, flushed after the operation pipeline completes successfully.
 - **Nested operations:** callbacks queue up and flush once at the outermost successful boundary.
 - **On error (`error!` or exception):** queued callbacks are discarded.
 
@@ -441,13 +441,11 @@ Multiple blocks run in registration order.
 
 **ActiveRecord:** requires Rails 7.2+ (`after_all_transactions_commit`).
 
-**Mongoid:** deferred across nested Dex operations. Ambient `Mongoid.transaction` blocks opened outside Dex are not detected — callbacks will fire immediately in that case.
-
 ---
 
 ## Advisory Locking
 
-Mutual exclusion via database advisory locks (requires `with_advisory_lock` gem). Wraps **outside** the transaction.
+Mutual exclusion via database advisory locks (requires `with_advisory_lock` gem). Wraps **outside** the transaction. ActiveRecord-only; Mongoid-only apps get a clear `LoadError`.
 
 ```ruby
 advisory_lock { "pay:#{charge_id}" }    # dynamic key from props
@@ -483,8 +481,12 @@ Props serialize/deserialize automatically (Date, Time, BigDecimal, Symbol, `_Ref
 Record execution to database. Requires `Dex.configure { |c| c.record_class = OperationRecord }`.
 
 ```ruby
-create_table :operation_records do |t|
+create_table :operation_records, id: :string do |t|
   t.string :name, null: false  # operation class name
+  t.string :trace_id           # shared trace / correlation ID
+  t.string :actor_type         # root actor type
+  t.string :actor_id           # root actor ID
+  t.jsonb :trace               # full trace snapshot
   t.jsonb :params              # serialized props (nil = not captured)
   t.jsonb :result              # serialized return value
   t.string :status, null: false # pending/running/completed/error/failed
@@ -500,6 +502,8 @@ end
 add_index :operation_records, :name
 add_index :operation_records, :status
 add_index :operation_records, [:name, :status]
+add_index :operation_records, :trace_id
+add_index :operation_records, [:actor_type, :actor_id]
 ```
 
 Control per-operation:
@@ -510,12 +514,40 @@ record result: false      # params only
 record params: false      # result only
 ```
 
-All outcomes are recorded — success (`completed`), business errors (`error`), and exceptions (`failed`). Recording runs outside the operation's own transaction so error records survive its rollbacks. Records still participate in ambient transactions (e.g., an outer operation's transaction). Missing columns silently skipped.
+All outcomes are recorded — success (`completed`), business errors (`error`), and exceptions (`failed`). Recording runs outside the operation's own transaction so error records survive its rollbacks. Records still participate in ambient transactions (e.g., an outer operation's transaction). Dex validates the configured record model before use and raises if required attributes are missing.
+
+Required attributes by feature:
+
+- Core recording: `name`, `status`, `error_code`, `error_message`, `error_details`, `performed_at`
+- Params capture: `params` unless `record params: false`
+- Result capture: `result` unless `record result: false`
+- Async record jobs: `params`
+- `once`: `once_key`, plus `once_key_expires_at` when `expires_in:` is used
+
+Trace columns (`id`, `trace_id`, `actor_type`, `actor_id`, `trace`) are recommended for tracing. Dex persists them when present, omits them when missing.
+
+Untyped results are sanitized to JSON-safe values before persistence: Hash keys round-trip as strings, and objects fall back to `as_json`/`to_s` under `"_dex_value"`.
 
 Status values: `pending` (async enqueued), `running` (async executing), `completed` (success), `error` (business error via `error!`), `failed` (unhandled exception).
 
 When both async and recording are enabled, dexkit automatically stores only the record ID in the job payload instead of full params.
 
+## Execution tracing
+
+Every operation call gets an `op_...` execution ID and joins a fiber-local trace shared across operations, handlers, and async jobs.
+
+```ruby
+Dex::Trace.start(actor: { type: :user, id: current_user.id }) do
+  Order::Place.call(product: product, customer: customer, quantity: 2)
+end
+
+Dex::Trace.trace_id   # => "tr_..."
+Dex::Trace.current    # => [{ type: :actor, ... }, { type: :operation, ... }]
+Dex::Trace.to_s       # => "user:42 > Order::Place(op_2nFg7K)"
+```
+
+Tracing is always on – no opt-in needed. Async operations serialize and restore the trace automatically. When recording is enabled, `trace_id`, `actor_type`, `actor_id`, and `trace` are persisted alongside the usual record fields.
+
 ---
 
 ## Idempotency (once)
@@ -569,12 +601,12 @@ ChargeOrder.clear_once!("webhook-123")    # by raw string key
 
 Clearing is idempotent — clearing a non-existent key is a no-op. After clearing, the next call executes normally.
 
-**Pipeline position:** result → **once** → lock → record → transaction → rescue → guard → callback. The once check runs before locking and recording, so duplicate calls short-circuit early.
+**Pipeline position:** trace → result → guard → **once** → lock → record → transaction → rescue → callback. The once check runs before locking and recording, so duplicate calls short-circuit early.
 
 **Requirements:**
 
 - Record backend must be configured (`Dex.configure { |c| c.record_class = OperationRecord }`)
-- The record table must have `once_key` and `once_key_expires_at` columns (see Recording schema above)
+- The record backend must satisfy the Recording requirements above, and `once` additionally requires `once_key` plus `once_key_expires_at` when `expires_in:` is used
 - `once` cannot be declared with `record false` — raises `ArgumentError`
 - Only one `once` declaration per operation
 
@@ -586,11 +618,10 @@ Clearing is idempotent — clearing a non-existent key is a no-op. After clearin
 # config/initializers/dexkit.rb
 Dex.configure do |config|
   config.record_class = OperationRecord  # model for recording (default: nil)
-  config.transaction_adapter = nil        # auto-detect (default); or :active_record / :mongoid
 end
 ```
 
-All DSL methods validate arguments at declaration time — typos and wrong types raise `ArgumentError` immediately (e.g., `error "string"`, `async priority: 5`, `transaction :redis`).
+All DSL methods validate arguments at declaration time — typos and wrong types raise `ArgumentError` immediately (e.g., `error "string"`, `async priority: 5`, `transaction :redis`). Only `:active_record` is a valid transaction adapter.
 
 ---
 
@@ -598,22 +629,20 @@ All DSL methods validate arguments at declaration time — typos and wrong types
 
 ```ruby
 # test/test_helper.rb
-require "dex/test_helpers"
+require "dex/operation/test_helpers"
 
 class Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 end
 ```
 
 Not autoloaded — stays out of production. TestLog and stubs are auto-cleared in `setup`.
 
-For Mongoid-backed operation tests, run against a MongoDB replica set (MongoDB transactions require it).
-
 ### Subject & Execution
 
 ```ruby
 class CreateUserTest < Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 
   testing CreateUser  # default for all helpers
 
@@ -778,7 +807,7 @@ Each entry has: `name`, `operation_class`, `params`, `result` (Ok/Err), `duratio
 
 ```ruby
 class CreateUserTest < Minitest::Test
-  include Dex::TestHelpers
+  include Dex::Operation::TestHelpers
 
   testing CreateUser
 

data/guides/llm/QUERY.md

@@ -10,12 +10,17 @@ All examples below build on this query unless noted otherwise:
 
 ```ruby
 class UserSearch < Dex::Query
+  description "Search and filter users"
+
   scope { User.all }
 
   prop? :name,   String
   prop? :role,   _Array(String)
   prop? :age_min, Integer
   prop? :status, String
+  prop? :tenant, String
+
+  context tenant: :current_tenant
 
   filter :name,    :contains
   filter :role,    :in
@@ -71,6 +76,51 @@ prop? :age_min, Integer              # optional integer
 
 Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_params`, `param_key`.
 
+### Description
+
+```ruby
+class UserSearch < Dex::Query
+  description "Search and filter users"
+end
+```
+
+### Context
+
+Same `context` DSL as Operation and Event. Auto-fills props from `Dex.with_context`:
+
+```ruby
+class UserSearch < Dex::Query
+  prop? :tenant, String
+  context tenant: :current_tenant
+end
+
+# In a controller around_action:
+Dex.with_context(current_tenant: current_tenant) do
+  UserSearch.call(name: "ali")  # tenant auto-filled
+end
+```
+
+Identity shorthand: `context :locale` maps prop `:locale` to context key `:locale`.
+
+Explicit values always win over ambient context. Inheritance merges parent + child mappings.
+
+---
+
+## Registry & Export
+
+Queries extend `Registry` — same API as Operation, Event, and Form:
+
+```ruby
+Dex::Query.registry                     # => Set of all named Query subclasses
+UserSearch.description                   # => "Search and filter users"
+
+UserSearch.to_h                          # => { name:, description:, props:, filters:, sorts:, context: }
+UserSearch.to_json_schema                # => JSON Schema (Draft 2020-12)
+
+Dex::Query.export(format: :hash)         # => sorted array of all query to_h
+Dex::Query.export(format: :json_schema)  # => sorted array of all query to_json_schema
+```
+
 ---
 
 ## Filters
@@ -91,7 +141,7 @@ Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_para
 | `:in` | `IN (values)` | `filter :roles, :in, column: :role` |
 | `:not_in` | `NOT IN (values)` | `filter :roles, :not_in, column: :role` |
 
-String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope.
+String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope, and Mongoid association scopes/proxies are normalized to `Mongoid::Criteria` automatically.
 
 ### Column Mapping
 
@@ -159,7 +209,7 @@ Only one default per class. Applied when no sort is provided.
 
 ### `.call`
 
-Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`):
+Returns a queryable scope (`ActiveRecord::Relation` or `Mongoid::Criteria`). Association scopes like `current_user.posts` work too:
 
 ```ruby
 users = UserSearch.call(name: "ali", role: %w[admin], sort: "-name")