From b7cec4b7a45e244156f69cc92ee736cb61ea547e Mon Sep 17 00:00:00 2001
From: Akihito Koriyama <akihito.koriyama@gmail.com>
Date: Fri, 5 Jun 2026 19:05:04 +0900
Subject: [PATCH] Promote the Feature Reference into a full Manual
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs had a strong feature reference but no manual: it started at "Features"
with no installation, module wiring, or SQL-file conventions, so a reader who
landed on /reference/ could not learn how to bootstrap the library. The only
setup-bearing doc (docs/ja/MediaQuery.md) is thin and unlinked.

Add the missing front sections to docs/reference.md and reposition it as the
Manual:
- Installation (composer require, requirements).
- Setup — both module entry points (MediaQuerySqlModule auto-discovery, the
  recommended path; MediaQueryModule explicit list) plus AuraSqlModule for the
  connection, and resolving the interface from the injector. Verified against
  tests/MediaQuerySqlModuleTest.php.
- SQL Files — location, {queryId}.sql naming, named placeholders, multi-statement.
- Configuration — DSN/connection, module choice, advanced hooks.
- A short "This manual covers" table of contents.

Retitle to "Ray.MediaQuery Manual" (permalink /reference/ kept for link stability)
and update the README link and docs Home card from "Feature Reference" to "Manual".
---
 README.md         |   4 +-
 docs/index.html   |  12 +++---
 docs/reference.md | 106 ++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 110 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 8590971..1bbe01c 100644
--- a/README.md
+++ b/README.md
@@ -106,9 +106,9 @@ $todos = $todoQuery->list();
 
 ## Documentation
 
-- [Documentation Home](https://ray-di.github.io/Ray.MediaQuery/) — tutorial, reference, and AI-oriented docs.
+- [Documentation Home](https://ray-di.github.io/Ray.MediaQuery/) — tutorial, manual, and AI-oriented docs.
 - [Hands-on Tutorial (日本語)](https://ray-di.github.io/Ray.MediaQuery/tutorial/) — 13 chapters using SQLite. ([source](./docs/tutorial/README.ja.md))
-- [Feature Reference](https://ray-di.github.io/Ray.MediaQuery/reference/) — result mapping, factories, parameter handling, pagination, and direct SQL execution. ([source](./docs/reference.md))
+- [Manual](https://ray-di.github.io/Ray.MediaQuery/reference/) — installation, module setup, SQL conventions, result mapping, factories, parameter handling, pagination, and direct SQL execution. ([source](./docs/reference.md))
 - [BDR Pattern Guide](./BDR_PATTERN.md) — architectural approach behind SQL + rich domain objects.
 - [AI-Oriented Reference](https://ray-di.github.io/Ray.MediaQuery/llms-full.txt) — compact reference for coding agents. ([source](./docs/llms-full.txt))
 - [Demo Application](./demo/) — a minimal runnable smoke test of the module wiring; the hands-on tutorial above is the full feature walkthrough.
diff --git a/docs/index.html b/docs/index.html
index 3ac1831..0acbcfb 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -24,10 +24,10 @@ <h2>ハンズオンチュートリアル</h2>
   </article>
 
   <article class="card">
-    <h2>Feature Reference</h2>
-    <p>戻り値マッピング、ファクトリ、パラメータ変換、ページネーション、直接 SQL 実行の詳細。</p>
-    <p class="en" lang="en">Detailed reference for result mapping, factories, parameter handling, pagination, and direct SQL execution.</p>
-    <p><a class="button" href="{{ '/reference/' | relative_url }}">Reference を読む</a></p>
+    <h2>Manual</h2>
+    <p>インストール、モジュール設定、SQL ファイル規約から、戻り値マッピング、ファクトリ、パラメータ変換、ページネーション、直接 SQL 実行までの完全ガイド。</p>
+    <p class="en" lang="en">Complete guide: installation, module setup, SQL conventions, result mapping, factories, parameter handling, pagination, and direct SQL execution.</p>
+    <p><a class="button" href="{{ '/reference/' | relative_url }}">Manual を読む</a></p>
   </article>
 
   <article class="card">
@@ -48,7 +48,7 @@ <h2>GitHub Repository</h2>
 <section class="note">
   <h2>English / 日本語</h2>
   <p>
-    現在の詳しいチュートリアルは日本語版です。README と AI 向けリファレンスは英語で利用できます。<br>
-    <span lang="en">The detailed tutorial is currently available in Japanese. The README and AI-oriented reference are available in English.</span>
+    現在の詳しいチュートリアルは日本語版です。README・Manual・AI 向けリファレンスは英語で利用できます。<br>
+    <span lang="en">The detailed tutorial is currently available in Japanese. The README, Manual, and AI-oriented reference are available in English.</span>
   </p>
 </section>
diff --git a/docs/reference.md b/docs/reference.md
index f93dbe6..e4afc94 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1,14 +1,112 @@
 ---
 layout: default
-title: Ray.MediaQuery Feature Reference
-description: Detailed feature reference for Ray.MediaQuery result mapping, factories, parameter handling, pagination, and direct SQL execution.
+title: Ray.MediaQuery Manual
+description: Ray.MediaQuery user manual — installation, module setup, SQL file conventions, result mapping, factories, parameter handling, pagination, and direct SQL execution.
 lang: en
 permalink: /reference/
 ---
 
-# Ray.MediaQuery Feature Reference
+# Ray.MediaQuery Manual
 
-Detailed reference for Ray.MediaQuery features. For a guided introduction, start with the [hands-on tutorial](https://ray-di.github.io/Ray.MediaQuery/tutorial/).
+The complete guide to using Ray.MediaQuery: install the package, wire the modules, learn the SQL-file conventions, then consult the feature reference. For a guided, build-along introduction, see the [hands-on tutorial](https://ray-di.github.io/Ray.MediaQuery/tutorial/) (Japanese).
+
+This manual covers:
+
+- [Installation](#installation)
+- [Setup](#setup) — wiring the DI modules and getting a query instance
+- [SQL Files](#sql-files) — location, naming, and placeholder conventions
+- [Configuration](#configuration) — connection, module choices, advanced hooks
+- [Features](#features) — result mapping, factories, parameters, pagination, direct SQL
+
+## Installation
+
+```bash
+composer require ray/media-query
+```
+
+Requirements:
+
+- **PHP 8.2+**.
+- A PDO driver for your database (e.g. `pdo_sqlite`, `pdo_mysql`).
+- Ray.MediaQuery builds on [Ray.Di](https://ray-di.github.io/) (dependency injection) and [Ray.AuraSqlModule](https://github.com/ray-di/Ray.AuraSqlModule) (the PDO connection). Both are installed as dependencies.
+
+## Setup
+
+Ray.MediaQuery generates the implementation of your query interfaces at runtime, so setup is just two things: install a MediaQuery module (which discovers/binds the interfaces and points at the SQL directory) and install `AuraSqlModule` (which supplies the database connection). Then resolve the interface from the injector.
+
+### Auto-discovery: `MediaQuerySqlModule` (recommended)
+
+Point the module at the directory of query interfaces and the directory of SQL files. Every interface found under `interfaceDir` is bound automatically.
+
+```php
+use Ray\AuraSqlModule\AuraSqlModule;
+use Ray\Di\AbstractModule;
+use Ray\Di\Injector;
+use Ray\MediaQuery\MediaQuerySqlModule;
+
+final class AppModule extends AbstractModule
+{
+    protected function configure(): void
+    {
+        $this->install(new MediaQuerySqlModule(
+            interfaceDir: __DIR__ . '/Query',  // directory of #[DbQuery] interfaces
+            sqlDir: __DIR__ . '/sql',          // directory of .sql files
+        ));
+        $this->install(new AuraSqlModule('sqlite::memory:'));  // PDO connection (DSN)
+    }
+}
+
+$injector = new Injector(new AppModule());
+$userQuery = $injector->getInstance(UserQueryInterface::class);  // generated implementation
+$user = $userQuery->item('user-123');
+```
+
+### Explicit list: `MediaQueryModule`
+
+When you want to name the interfaces yourself instead of scanning a directory, build a `Queries` list and pass a `DbQueryConfig` for the SQL directory.
+
+```php
+use Ray\MediaQuery\DbQueryConfig;
+use Ray\MediaQuery\MediaQueryModule;
+use Ray\MediaQuery\Queries;
+
+protected function configure(): void
+{
+    $queries = Queries::fromClasses([
+        UserQueryInterface::class,
+        OrderQueryInterface::class,
+    ]);
+    $this->install(new MediaQueryModule($queries, [new DbQueryConfig(__DIR__ . '/sql')]));
+    $this->install(new AuraSqlModule('sqlite::memory:'));
+}
+```
+
+Both modules produce the same result; `MediaQuerySqlModule` is the directory-based shortcut, `MediaQueryModule` is the explicit form. `Queries::fromDir($dir)` is also available if you want a list built from a directory.
+
+## SQL Files
+
+- Save one query per file as `{queryId}.sql` in your `sqlDir`. The id in `#[DbQuery('user_item')]` maps to `sqlDir/user_item.sql`.
+- Placeholders are **named** and bind to method arguments of the same name — `:userId` ← `string $userId`. Binding is by name, so argument order does not matter.
+- A file may hold **multiple statements** separated by `;`; they run in order and the result reflects the **last** statement (see [Result Mapping](#result-mapping--entity-hydration)).
+
+```sql
+-- sql/user_item.sql
+SELECT id, name FROM users WHERE id = :id;
+```
+
+```php
+interface UserQueryInterface
+{
+    #[DbQuery('user_item', type: 'row')]
+    public function item(string $id): User|null;
+}
+```
+
+## Configuration
+
+- **Database connection** — supplied by `AuraSqlModule`. Pass any PDO DSN: `'mysql:host=localhost;dbname=app'`, `'pgsql:host=...;dbname=...'`, `'sqlite::memory:'`, etc. See [Ray.AuraSqlModule](https://github.com/ray-di/Ray.AuraSqlModule) for connection pooling, primary/replica, and per-connection options.
+- **Module choice** — `MediaQuerySqlModule` (directory scan) vs `MediaQueryModule` (explicit `Queries` + `DbQueryConfig`); see [Setup](#setup).
+- **Advanced hooks** — `MediaQuerySqlTemplateModule` / `SqlTemplate` swap the SQL execution template, and `MediaQueryLoggerInterface` exposes query logging. These are optional; the two modules above cover typical applications.
 
 ## Features