docs(cli): setupDatabase.php を canonical、initSQLite.php を legacy として明文化する (#294)

docs/deployment/server-install.md

@@ -30,13 +30,15 @@ Then create the sample database tables. For MySQL, use the general setup command
 php cli/setupDatabase.php --env=.env --yes
 ```
 
-For SQLite3 fallback, initialize the SQLite file explicitly:
+For SQLite3 fallback, the same canonical installer works once `NENE_DB_TYPE=SQLite3` is in your `.env`:
 
 ```sh
-php cli/initSQLite.php
+php cli/setupDatabase.php --env=.env --yes
 ```
 
-Both commands are safe to run more than once. They create the current sample `users` and `todos` tables when missing and insert the default `admin` sample user only when that user does not already exist.
+The legacy `cli/initSQLite.php` script remains available for older deployment scripts (see `docs/development/cli.md`).
+
+The setup command is idempotent: it creates the current sample `users` and `todos` tables when missing and inserts the default `admin` sample user only when that user does not already exist.
 
 ## Requirements
 
@@ -213,23 +215,25 @@ The browser health endpoint returns the same idea through the NeNe JSON envelope
 
 When no database environment variables are provided, NeNe can fall back to SQLite-oriented defaults.
 
-When you intentionally use `NENE_DB_TYPE=SQLite3`, initialize the SQLite sample data from the repository root:
+For the SQLite case, use the same canonical installer as MySQL with `NENE_DB_TYPE=SQLite3` in your env file:
 
 ```sh
-php cli/initSQLite.php
+php cli/setupDatabase.php --env=.env --yes
 ```
 
-This creates the SQLite database file under `data/`, creates the `users` and `todos` tables, and inserts the default `admin` sample user. You can also use the general setup command with an env file that sets `NENE_DB_TYPE=SQLite3`:
+This creates the SQLite database file under `data/`, creates the `users` and `todos` tables, and inserts the default `admin` sample user. It is idempotent — re-running it is safe.
+
+`cli/initSQLite.php` is the older SQLite-only path that predates the general installer. It is kept for backwards compatibility, but new deployment guides should prefer `cli/setupDatabase.php` (see `docs/development/cli.md` for the canonical vs legacy split). If you do use the legacy path:
 
 ```sh
-php cli/setupDatabase.php --env=.env --yes
+php cli/initSQLite.php --yes
 ```
 
-The SQLite database file is a generated runtime artifact and is not committed to Git. If the sample login stops matching the expected `admin / admin` credentials, move the old file aside and initialize it again:
+The SQLite database file is a generated runtime artifact and is not committed to Git. If the sample login stops matching the expected `admin / admin` credentials, move the old file aside and re-install:
 
 ```sh
 mv data/nene.db data/nene.db.bak
-php cli/initSQLite.php
+php cli/setupDatabase.php --env=.env --yes
 ```
 
 SQLite is useful for a very small sample deployment or quick hosting verification. MySQL is recommended once the application stores real service data.

docs/development/cli.md

@@ -0,0 +1,75 @@
+# CLI Tools
+
+NeNe ships two command-line scripts under `cli/`. This page describes when to use each one.
+
+## `cli/setupDatabase.php` (canonical)
+
+```sh
+php cli/setupDatabase.php [--env=.env] [--yes] [--help]
+```
+
+The canonical installer for both **MySQL** and **SQLite** runtimes. Reads `NENE_DB_TYPE` (default `SQLite3` when no env is loaded) to decide which adapter to use, then calls `Nene\Xion\DatabaseInstaller::install()` to create the sample tables (`users`, `todos`) and insert the default `admin` development account.
+
+Options:
+
+- `--env=PATH` — load a dotenv-style file before NeNe initializes configuration. Process environment variables take priority over the file. When `PATH` is explicitly passed and does not exist, the script exits with an error rather than silently falling back to the process environment.
+- `--yes` — skip the interactive confirmation prompt. Required for CI / non-interactive deployment.
+- `--help` — show usage and exit.
+
+Recommended one-liner for first-run deployment:
+
+```sh
+php cli/setupDatabase.php --env=.env --yes
+```
+
+Or via the Composer shortcut:
+
+```sh
+composer setup
+```
+
+The script is **idempotent** — running it again on an installed database is a no-op (CREATE TABLE IF NOT EXISTS + INSERT WHERE NOT EXISTS). It also prints a final health summary (`Health: API=OK DB=OK Schema=OK`) so deployment scripts can grep for the result.
+
+For `--yes` + bad DB credentials, the script exits non-zero with a clear error (e.g. `Database setup failed: SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for ... failed`).
+
+## `cli/initSQLite.php` (legacy)
+
+```sh
+php cli/initSQLite.php [--yes] [--help]
+```
+
+Older, SQLite-only initializer that predates `setupDatabase.php`. It hard-codes the SQLite adapter and embeds its own copy of the schema, so it does not honor `NENE_DB_TYPE` and is not used by `composer setup`.
+
+Kept for backwards compatibility with existing deployment scripts. New deployment guides should use `cli/setupDatabase.php` instead, even for the SQLite case:
+
+```sh
+NENE_DB_TYPE=SQLite3 php cli/setupDatabase.php --env=.env --yes
+```
+
+If you do invoke `cli/initSQLite.php` directly, the `--yes` and `--help` flags work the same way as for `setupDatabase.php`.
+
+## When to use which
+
+| Scenario | Use |
+| --- | --- |
+| Standard deployment (MySQL or SQLite) | `php cli/setupDatabase.php --env=.env --yes` (or `composer setup`) |
+| CI / Ansible / Docker provisioning | same as above, `--yes` is essential |
+| Existing scripts that already call `cli/initSQLite.php` | keep working; migrate to `setupDatabase.php` at the next maintenance window |
+| Fresh contributor running locally | `composer setup` (shortest) |
+| Reset and reinstall sample data | `setupDatabase.php` is idempotent; just re-run it. Soft-delete the existing rows first if you want a clean slate, or `docker compose down -v` to drop the MySQL volume entirely. |
+
+## Schema source-of-truth (three sites)
+
+Both scripts pull from independent copies of the CREATE TABLE statements:
+
+- `docker/mysql/init/001_schema.sql` — MySQL container's first-boot init.
+- `cli/initSQLite.php` — embedded SQLite DDL (legacy path).
+- `class/xion/DatabaseInstaller.php` — embedded MySQL + SQLite DDL (canonical path used by `cli/setupDatabase.php`).
+
+When you add or alter a table, **edit all three** in the same change. CI does not enforce parity. See `docs/development/docker.md` "Schema Parity Between SQLite and MySQL" for the full rationale and the table-set comparison commands.
+
+## Related
+
+- `docs/deployment/server-install.md` — full deployment walkthrough.
+- `docs/development/docker.md` — local Docker setup, including `NENE_*` environment variables.
+- `composer.json` — `setup`, `test`, `test:http`, `analyze`, `format`, `check` shortcuts.