docs: Update docs on default pagination behavior. (#2226)

Author: Torkan

documentation/topics/advanced/pagination.livemd

@@ -13,6 +13,10 @@ Ash has built-in support for two kinds of pagination: `offset` and `keyset`. You
 
 Pagination support is configured on a per-action basis. A single action can support both kinds of pagination if desired, but typically you would use one or the other. Read actions generated with `defaults [:read]` support both offset and keyset pagination, for other `read` actions you have to configure the [`pagination` section](https://hexdocs.pm/ash/dsl-ash-resource.html#actions-read-pagination).
 
+> ### Default Pagination Type
+>
+> When an action supports both pagination types, the behavior depends on your application configuration. See the ["Default Pagination Behavior"](#default-pagination-behavior-when-both-types-are-supported) section below for details on how Ash determines which type to use.
+
 > ### Check the updated query return type!
 >
 > Pagination will modify the return type of calling the query action.
@@ -895,9 +899,31 @@ last_page.more?
 false
 ```
 
-### Actions supporting both offset and keyset pagination
+### Default Pagination Behavior When Both Types Are Supported
+
+When an action supports both `offset` and `keyset` pagination (such as default read actions), Ash uses the following logic to determine which pagination type to use:
+
+**1. Explicit pagination parameters take precedence:**
+- If `after` or `before` is provided → keyset pagination
+- If `offset` is provided → offset pagination
+
+**2. Configuration-based default for ambiguous cases:**
+Ash is configured to use keyset-pagination by default when installed with `mix igniter.install ash`, or the homepage installer.
+
+#### Practical Examples
 
-If an action supports both offset and keyset pagination (e.g. default read actions), offset pagination is used by default when page options only contain `limit`. However, the records will have the keyset in the metadata, so keyset pagination can be performed on next pages.
+Regardless of configuration, the records will have keyset metadata, so you can always transition between pagination types:
+
+```elixir
+# By default, this uses keyset pagination
+%{results: [_, last]} = Ash.read!(Post, page: [limit: 2])
+
+# Explicitly use keyset pagination for the next page
+Ash.read!(Post, page: [limit: 2, after: last.__metadata__.keyset])
+
+# Explicitly use offset pagination
+Ash.read!(Post, page: [limit: 2, offset: 2])
+```
 
 ```elixir
 %Ash.Page.Offset{results: [_, last]} = Domain.list_posts!(page: [limit: 2])

documentation/topics/development/backwards-compatibility-config.md

@@ -33,7 +33,7 @@ config :ash, include_embedded_source_by_default?: false
 ### Old Behavior
 
 When working with embedded types, the `__source__` constraint is populated with
-the original changeset. This can be very costly in terms of memory when working with 
+the original changeset. This can be very costly in terms of memory when working with
 large sets of embedded resources.
 
 ### New Behavior
@@ -66,14 +66,16 @@ config :ash, default_page_type: :keyset
 
 ### Old Behavior
 
-When an action supports `offset` and `keyset` pagination, and a page is requested
-with only `limit` set, i.e `page: [limit: 10]`, you would get back an `%Ash.Page.Offset{}`.
+When an action supports both `offset` and `keyset` pagination, and a page is requested
+with only `limit` set (i.e., `page: [limit: 10]`), Ash defaulted to offset pagination
+and returned an `%Ash.Page.Offset{}`.
 
 ### New Behavior
 
-Now we will return a `%Ash.Page.Keyset{}` choosing it whenever it is ambiguous.
-You can always force returning an `%Ash.Page.Offset{}` by providing the offset option,
-i.e `page: [offset: 0]`
+With the current default configuration, Ash will now return an `%Ash.Page.Keyset{}` when the pagination
+type is ambiguous (only `limit` is provided).
+
+For detailed pagination behavior documentation, see the [pagination guide](/documentation/topics/advanced/pagination.livemd#default-pagination-behavior-when-both-types-are-supported).
 
 ## policies.no_filter_static_forbidden_reads?
 
@@ -172,15 +174,15 @@ reverse order. This was missed for `Ash.Query`. Meaning if you had something lik
 
 ```elixir
 read :read do
-  prepare fn query, _ -> 
-    Ash.Query.after_action(query, fn query, results -> 
+  prepare fn query, _ ->
+    Ash.Query.after_action(query, fn query, results ->
       IO.puts("hook 1")
       {:ok, results}
     end)
   end
 
-  prepare fn query, _ -> 
-    Ash.Query.after_action(query, fn query, results -> 
+  prepare fn query, _ ->
+    Ash.Query.after_action(query, fn query, results ->
       IO.puts("hook 2")
       {:ok, results}
     end)