Document getNbPages() where the docs teach the page count

llms-full.txt labelled $page->total as the page count; it is the item
count. The tutorial notes said the page count was unavailable.

Author: koriym

docs/ja/MediaQuery.md

@@ -107,11 +107,12 @@ interface UserListInterface
 }
 ```
 
-実行結果の`Pages`は、配列アクセスでページを取得したり`count()`で全体の件数を取得することができます。
+実行結果の`Pages`は、配列アクセスでページを、`count()`で全体の件数を、`getNbPages()`で総ページ数を取得できます。
 
 ```php
 $userList = $injector->getInstance(UserListInterface::class);
 $pages = $userList();
 $page = $pages[1];
 $total = count($pages);
+$nbPages = $pages->getNbPages();
 ```

docs/llms-full.txt

@@ -84,7 +84,7 @@ Every row of this table is a valid return type on a `#[DbQuery]` method.
 | `AffectedRows`                    | UPDATE/DELETE | Exposes `->count` (int) and `->isAffected(): bool`.                   |
 | `InsertedRow`                     | INSERT    | Exposes `->values` (resolved params) and `->id` (?string lastInsertId).   |
 | custom `X implements PostQueryInterface` | SELECT or DML | Polymorphic dispatch — framework calls `X::fromContext($context)`. SELECT pre-hydrates rows on `$context->rows`; DML leaves `$context->rows = []`. |
-| `Pages` (with `#[Pager]`)         | SELECT    | Lazy paginator. Index access executes `LIMIT`/`OFFSET`; `count()` does `COUNT`. |
+| `Pages` (with `#[Pager]`)         | SELECT    | Lazy paginator. Index access executes `LIMIT`/`OFFSET`; `count()` does `COUNT`, and `getNbPages()` divides it by `perPage`. |
 
 How dispatch is decided:
 
@@ -400,10 +400,11 @@ interface ProductRepository
 
 $pages = $repo->list();
 count($pages);         // → COUNT query
+$pages->getNbPages();  // → number of pages, from the same COUNT (memoized)
 $page = $pages[1];     // → SELECT with LIMIT/OFFSET, rows hydrated to Product
 $page->data;           // items
 $page->current;        // int
-$page->total;          // int (total pages)
+$page->total;          // int (total item count)
 $page->hasNext;        // bool
 $page->hasPrevious;    // bool
 (string) $page;        // rendered pager HTML

docs/reference.md

@@ -610,8 +610,9 @@ interface ProductRepository
 }
 
 $pages = $productRepo->getProducts();
-$count = count($pages);  // COUNT query を実行
-$page = $pages[1];       // LIMIT/OFFSET 付き SELECT を実行
+$count = count($pages);          // COUNT query を実行
+$nbPages = $pages->getNbPages(); // 総ページ数。件数を取ってceilする必要はない
+$page = $pages[1];               // LIMIT/OFFSET 付き SELECT を実行
 
 // Page object properties:
 // $page->data          // このページの item

docs/tutorial/README.ja.md

@@ -1333,7 +1333,7 @@ first stats row=MyBlog\ArticleStats commentCount=2 excerpt='Updated body.'
 
 ### 解説
 
-- `count($pages)` は **総アイテム数** (= COUNT クエリの結果)。総ページ数ではないので注意。
+- `count($pages)` は **総アイテム数** (= COUNT クエリの結果)。総ページ数は `$pages->getNbPages()` で取る (同じ COUNT を使い回す)。
 - `$pages[1]` でページ1にアクセス → SELECT に LIMIT/OFFSET が付いて実行される (lazy)。
 - `$page->data` は Article のリスト (`@return Pages<Article>` のおかげで hydration が効く)。
 - `#[DbQuery(factory: ArticleStatsFactory::class)]` と `#[Pager]` を併用した場合、1.1 以降は `$page->data` の各行も `ArticleStatsFactory` で作られる。

docs/tutorial/README.md

@@ -1331,7 +1331,7 @@ first stats row=MyBlog\ArticleStats commentCount=2 excerpt='Updated body.'
 
 ### Explanation
 
-- `count($pages)` returns the **total item count** from the COUNT query, not the number of pages.
+- `count($pages)` returns the **total item count** from the COUNT query, not the number of pages. For the page count call `$pages->getNbPages()`, which reuses the same COUNT.
 - `$pages[1]` accesses page 1 and lazily executes SELECT with LIMIT/OFFSET.
 - `$page->data` contains a list of `Article` objects because of `@return Pages<Article>`.
 - With `#[DbQuery(factory: ArticleStatsFactory::class)]` and `#[Pager]` together, Ray.MediaQuery 1.1+ builds each row in `$page->data` through `ArticleStatsFactory`.