@rawsql-ts/ztd-cli 0.17.0 → 0.19.0

package/README.md

@@ -1,366 +1,532 @@
-# @rawsql-ts/ztd-cli
-
-Scaffold **Zero Table Dependency (ZTD)** projects and keep DDL-derived test types in sync.
-
-`@rawsql-ts/ztd-cli` does **not** execute SQL by itself. It provides an adapter-neutral core that scaffolds a ZTD-ready development environment.  
-To actually run ZTD tests, you plug in a database adapter (driver-specific) and a DBMS-specific testkit (for example, `@rawsql-ts/adapter-node-pg` plus `@rawsql-ts/testkit-postgres` for Postgres).
-
-## Install
-
-```bash
-pnpm add -D @rawsql-ts/ztd-cli
-```
-
-To run ZTD-style tests, install:
-
-* a **database adapter** (driver-specific) to execute SQL, and
-* a **DBMS-specific testkit** to handle fixture resolution, query rewriting, and result validation.
-
-For Postgres, the typical ZTD setup is:
-`@rawsql-ts/adapter-node-pg` (driver adapter) +
-`@rawsql-ts/testkit-postgres` (Postgres-specific testkit).
-
-If you run `npx ztd init`, the CLI will install the Postgres driver/testkit stack plus `@rawsql-ts/sql-contract`, and it will always prompt you to select a validator backend (Zod or ArkType). The wizard keeps the required workflow documented in the recipes under `docs/recipes/` (e.g., `docs/recipes/sql-contract.md`, `docs/recipes/validation-zod.md`, and `docs/recipes/validation-arktype.md`), so the implementation path stays centralized and version-controlled.
-
-Then use the CLI through `npx ztd` or the installed `ztd` bin.
-
-## Getting Started (Fast Path)
-
-1. Initialize a ZTD layout:
-
-   ```bash
-   npx ztd init
-   ```
-
-   For tutorials and greenfield projects, we recommend the optional SQL client seam:
-
-  ```bash
-  npx ztd init --with-sqlclient
-  ```
-
-  Use `--with-sqlclient` when you want a minimal `SqlClient` boundary for repositories. Skip it if your project
-  already has a database abstraction (Prisma, Drizzle, Kysely, custom adapters) to avoid duplicating layers.
-
-  ```bash
-  npx ztd init --with-app-interface
-  ```
-
-  Use `--with-app-interface` to append the application interface guidance block to `AGENTS.md` without generating the ZTD layout or touching other files.
-
-  ```bash
-  npx ztd init --yes
-  ```
-
-  Use `--yes` to overwrite existing scaffold files without prompting (useful for non-interactive runs).
-
-2. Put your schema into `ztd/ddl/`:
-
-   - Edit the starter file (default): `ztd/ddl/public.sql`, or
-   - Pull from a live Postgres database: `npx ztd ddl pull` (Postgres only; uses `pg_dump`)
-
-3. Generate test types (`TestRowMap`) from DDL:
-
-   ```bash
-   npx ztd ztd-config
-   # or keep it updated while you edit SQL:
-   npx ztd ztd-config --watch
-   ```
-
-   This step writes files under `tests/generated/`. Treat everything in that directory as generated output: never edit it and never commit it. If you clone the repo into a clean environment and TypeScript reports missing modules under `tests/generated/`, rerun `npx ztd ztd-config`.
-
-4. Write tests using the generated test types + the driver wiring:
-
-   - `tests/generated/ztd-row-map.generated.ts` (generated test types; authoritative `TestRowMap`)
-   - `tests/support/testkit-client.ts` (driver wiring helper)
-
-If you already have a database, the most common loop is:
-`ztd ddl pull` -> edit `ztd/ddl/*.sql` -> `ztd ztd-config --watch` -> write tests.
-
-At this point, you can write deterministic DB tests without creating tables or running migrations.
-
-You can introduce ZTD incrementally; existing tests and ORMs can remain untouched.
-
-## What `ztd init` Generates
-
-- `ztd/ddl/<schema>.sql` (starter schema files you can edit or replace; the default schema is `public.sql`)
-- `tests/generated/ztd-row-map.generated.ts` (auto-generated `TestRowMap`, the canonical test type contract; do not commit)
-- `tests/support/testkit-client.ts` (auto-generated helper that boots a database client, wires a driver, and shares fixtures across the suite)
-- `ztd.config.json` (CLI defaults and resolver hints: `dialect`, `ddlDir`, `testsDir`, `ddlLint`, plus `ddl.defaultSchema`/`ddl.searchPath` for resolving unqualified tables)
-- `tests/generated/ztd-layout.generated.ts` (generated layout snapshot; do not commit)
-- `tests/support/global-setup.ts` (shared test setup used by the generated testkit client)
-- `README.md` describing the workflow and commands
-- `AGENTS.md` (copied from the package template unless the project already has one; `--with-app-interface` adds the application interface guidance block at the end)
-- `ztd/AGENTS.md` and `ztd/README.md` (folder-specific instructions that describe the new schema/domain layout)
-- `src/db/sql-client.ts` (optional; generated only with `--with-sqlclient`)
-- `src/sql/views/README.md` + `src/sql/jobs/README.md` (SQL file structure)
-- `src/repositories/views/README.md` + `src/repositories/tables/README.md` (repository structure)
-- `src/jobs/README.md` (job runner structure)
-- Example view SQL/repository and job SQL/runner files for the sample schema
-
-The resulting project follows the "DDL -> ztd-config -> tests" flow so you can regenerate everything from SQL-first artifacts.
-
-## Commands
-
-### `ztd init`
-
-Creates a ZTD-ready project layout (DDL folder, config, generated layout, and test support stubs). It does not connect to your database.
-
-Use `--with-sqlclient` to scaffold a minimal repository-facing SQL client for tutorials and new projects. It is opt-in
-to avoid colliding with existing database layers. If you use `pg`, adapt `client.query(...)` so it returns a plain row
-array (`T[]`) that satisfies the generated `SqlClient` interface.
-
-Use `--with-app-interface` to append the application interface guidance block to `AGENTS.md`. This documentation-only option leaves every other file untouched, making it easy to apply the guidance to existing repositories without rerunning the full layout generator.
-
-### `ztd ztd-config`
-
-Reads every `.sql` file under the configured DDL directory and produces the generated artifacts under `tests/generated/`:
-- `tests/generated/ztd-row-map.generated.ts`
-- `tests/generated/ztd-layout.generated.ts`
-
-- The row map exports `TestRowMap` plus table-specific test-row interfaces.
-- `--watch` overwrites only the `tests/generated/` outputs (no other folders are touched during the watch cycle).
-- Pass `--default-schema` or `--search-path` to update the `ddl.defaultSchema`/`ddl.searchPath` block in `ztd.config.json` so the CLI and drivers resolve unqualified tables the same way.
-- Never edit `tests/generated/` by hand. Rerun `npx ztd ztd-config` whenever schema/layout inputs change.
-
-### `ztd ddl ...`
-
-Every `ztd ddl` subcommand targets the shared DDL directory defined in `ztd.config.json` (default `ztd/ddl/`).
-
-### `ztd ddl pull`
-
-Fetches the schema via `pg_dump`, normalizes the DDL, and writes one file per schema under `ztd/ddl/<schema>.sql` (no `schemas/` subdirectory so each namespace lives at the DDL root).
-
-- Output is deterministic: it drops headers/`SET` statements, sorts objects, and ensures each schema file ends with a clean newline so diffs stay stable.
-- You can scope the pull with `--schema <name>` (repeatable) or `--table <schema.table>` (repeatable).
-
-Connection resolution (in order):
-
-1. `DATABASE_URL`
-2. CLI overrides (`--url` / `--db-*` flags)
-3. A `connection` block in `ztd.config.json`
-
- A sample `connection` block looks like:
-
- ```json
- {
-   "connection": {
-     "host": "db.example",
-     "port": 5432,
-     "user": "app",
-     "password": "secret",
-     "database": "app_db"
-   }
- }
- ```
-
-Unqualified table references are treated as belonging to the `public` schema by default, so `users` is interpreted as `public.users`. If your project relies on a different namespace, update the `ddl.defaultSchema`/`ddl.searchPath` block in `ztd.config.json` so the CLI and downstream tests agree on how unqualified names are resolved.
-
- > **Note:** `ztd ddl` commands that contact your database depend on the `pg_dump` executable. Ensure `pg_dump` is installed and reachable via your `PATH` (Windows users can add `C:\Program Files\PostgreSQL\<version>\bin` or open a shell that already exposes `pg_dump`), or pass `--pg-dump-path <path>` / set `PG_DUMP_PATH` to the absolute path before running the command. When authentication fails the CLI echoes the target host/port/database/user so you know what credential set to double-check.
-
-On Windows, register the executable for future PowerShell sessions:
-
-```powershell
-setx PG_DUMP_PATH "C:\Program Files\PostgreSQL\18\bin\pg_dump.exe"
-```
-
-Open a new PowerShell window after running this command so the updated environment variable is available to `ztd` commands.
-
-### `ztd ddl gen-entities`
-
-Reads the DDL directory and generates `entities.ts` (optional reference for helpers). Use it when you want TypeScript helpers for ad-hoc schema inspection without replacing `TestRowMap` as the source of truth.
-
-### `ztd ddl diff`
-
-Diffs the local DDL snapshot against a live Postgres database. It uses the shared DDL directory, respects configured extensions, and outputs a human-readable plan with `pg_dump`.
-
-### `ztd lint`
-
-Lint SQL files before writing ZTD tests so syntax and analysis issues surface immediately.
-
-```bash
-npx ztd lint path/to/query.sql
-```
-
-- Accepts a single `.sql` file, glob pattern, or directory (directories expand to `**/*.sql`).
-- Resolves `ZTD_LINT_DATABASE_URL` or `DATABASE_URL` for the database connection. When no URL is configured, it loads `@testcontainers/postgresql` (if installed) to spin up a temporary Postgres container.
-- Dynamically loads the registered adapter (for example `@rawsql-ts/adapter-node-pg` plus `@rawsql-ts/testkit-postgres`) so the rewritten statement is inspected through the fixture pipeline before it runs.
-- Executes each rewritten query using `PREPARE ... AS ...` (falling back to `EXPLAIN`) so Postgres (or your adapter) performs the same parsing/type resolution used in tests.
-- Reports the file path, location, error code/message/detail/hint, and a caret-marked excerpt to make fixes actionable before running tests.
-- Override the database image with `ZTD_LINT_DB_IMAGE` (default `postgres:16-alpine`), or supply a URL to reuse an existing server instead of a container.
-- If the adapter is missing, the command stops early with an error that points you at the adapter package to install or instructs you to set `DATABASE_URL`.
-
-## ZTD Testing
-
-The generated `tests/support/testkit-client.ts` is a stub. Replace `createTestkitClient` with a factory that returns an object conforming to `SqlClient` (defined in `src/db/sql-client.ts`). Use it to wire your preferred adapter (for example a Postgres adapter, a mock data source, or a fixture helper) before running the repository tests.
-
-ZTD rewrites every statement into a fixture-friendly shape and expects your adapter to execute the rewritten SQL using the metadata under `tests/generated/ztd-row-map.generated.ts`. The CLI avoids bundling a driver so you can choose whatever stack fits your project; install the necessary adapter package and point it at the generated row map before executing DB-backed suites.
-
-### SQL rewrite logging
-
-If you need to inspect the rewritten SQL, add logging inside your adapter or within `tests/support/testkit-client.ts`. There is no built-in logger in the template, but you can guard logging with environment variables such as:
-
-- `ZTD_SQL_LOG=1` or `true`: log the raw SQL plus the rewritten statement.
-- `ZTD_SQL_LOG_PARAMS=1` or `true`: include query parameters in the emitted logs.
-
-Add any adapter-specific options or helpers to control logging per call (for example, guard logging with your own `ZtdSqlLogOptions` type) so the test outputs remain deterministic when logging is disabled.
-
-## Benchmark summary
-
-### Purpose
-
-This benchmark executes the same repository implementation with two different supporting stacks: the Traditional schema/migration workflow (schema setup + seed + query + cleanup) and the ZTD fixture-backed workflow (repository query → rewrite → fixture materialization). The comparison highlights:
-
-- End-to-end wall-clock time including runner startup.
-- DB execution time and SQL count so Traditional’s higher SQL volume is explicit.
-- ZTD rewrite and fixture breakdowns so the internal costs of the testkit-postgres pipeline are visible.
-- Parallelism effects, runner startup costs, and where the break-even point lies as suite size grows.
-
-### Assumptions and environment
-
-This benchmark compares ZTD-style repository tests against a traditional migration-based workflow while exercising the same repository methods. All numbers are measured with the test runner included unless stated otherwise.
-
-#### Environment (measured run)
-
-- Node.js: v22.14.0
-- OS: Windows 10 (build 26100)
-- CPU: AMD Ryzen 7 7800X3D (16 logical cores)
-- Database: PostgreSQL 18.1 (containerized; `testcontainers`)
-- Parallel workers: 4
-- Report date: 2025-12-20
-
-#### Benchmark shape
-
-- Repository test cases: 3 (`customer_summary`, `product_ranking`, `sales_summary`)
-- Each test performs: 1 repository call (1 SQL execution per test case)
-- The Traditional workflow wraps every repository execution with migration, seeding, and cleanup SQL, whereas the ZTD workflow captures the same query, feeds it to the testkit-postgres adapter, and replays the rewritten/select-only statements backed by fixtures.
-- Suite sizes shown in the report:
-  - 3 tests (baseline)
-  - 30 tests (the same 3 cases repeated to approximate a larger suite)
-
-The 30-test suite exists to show how runner overhead amortizes as the number of executed tests grows, while keeping the tested SQL and data constant.
-
-#### What is included / excluded
-
-- **Runner-included runs (main comparison):** wall-clock time including `pnpm` + `vitest` startup and test execution.
-- **Steady-state section:** measures incremental cost per iteration after the runner is warm (first iteration excluded), to approximate watch/CI-like “many tests per single runner invocation.”
-- **Container startup:** excluded (the Postgres container is shared across runs).
-
-#### Fairness / bias notes (important)
-
-This benchmark intentionally measures the **Traditional** workflow under favorable assumptions:
-
-- **Traditional SQL construction cost is treated as zero**: queries are hard-coded raw SQL strings (no ORM/query-builder generation time).
-- **Traditional migration/DDL generation cost is treated as zero**: schema/migration SQL is also written directly (no ORM schema DSL or migration generation time).
-
-In contrast, the **ZTD** benchmark includes the repository layer’s normal SQL usage:
-
-- **ZTD includes SQL construction time as exercised by the repository layer** (i.e., whatever the test code does to produce the SQL text), in addition to rewrite/fixture overhead.
-
-Because real-world ORM workflows usually add both query generation and migration generation overhead on top of what is measured here, this setup should be interpreted as a **lower bound for Traditional** and a relatively conservative comparison against ZTD.
-
-### Results (runner included)
-
-#### End-to-end runtime
-
-| Suite size | Scenario | Workers | Avg Total (ms) | Avg Startup (ms) | Avg Execution (ms) | Startup % | Avg ms/test | Avg SQL Count | Avg DB (ms) |
-| ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
-| 3 | Traditional | 1 | 1951.08 | 1013.22 | 937.86 | 51.8% | 650.36 | 36 | 123.06 |
-| 3 | Traditional | 4 | 1301.56 | 967.02 | 334.54 | 74.3% | 433.85 | 36 | 39.06 |
-| 3 | ZTD | 1 | 2283.66 | 979.91 | 1303.74 | 42.9% | 761.22 | 3 | 11.34 |
-| 3 | ZTD | 4 | 1430.64 | 957.75 | 472.89 | 66.9% | 476.88 | 3 | 3.81 |
-| 30 | Traditional | 1 | 3085.48 | 1018.71 | 2066.77 | 33.0% | 102.85 | 360 | 1009.85 |
-| 30 | Traditional | 4 | 1788.35 | 996.66 | 791.68 | 55.8% | 59.61 | 360 | 392.83 |
-| 30 | ZTD | 1 | 2480.84 | 957.91 | 1522.94 | 38.6% | 82.69 | 30 | 44.82 |
-| 30 | ZTD | 4 | 1507.46 | 944.57 | 562.88 | 62.7% | 50.25 | 30 | 17.69 |
-
-### What this shows
-- **Small suites (3 tests) are dominated by runner startup.** At this scale, Traditional is faster (both serial and 4-worker), because fixed startup overhead and per-test harness work overwhelm ZTD’s per-test savings.
-- **As suite size grows (30 tests), ZTD becomes faster end-to-end.**
-  - Serial: ZTD 2480.84 ms vs Traditional 3085.48 ms
-  - 4 workers: ZTD 1507.46 ms vs Traditional 1788.35 ms
-- **Parallel execution helps both approaches**, but the improvement is constrained by startup overhead:
-  - With 4 workers, the startup share rises (more of the total becomes fixed runner cost), so scaling is not linear.
-
-### Break-even intuition (where ZTD starts to win)
-
-From these results, the practical break-even is **between 3 and 30 tests** under the current environment and runner-included setup.
-
-Why:
-- Traditional has high per-test DB work (many SQL statements + significant DB time).
-- ZTD has low per-test DB work (few SQL statements), but adds rewrite + fixture overhead.
-- Once the suite is large enough that **execution dominates startup**, ZTD’s reduced DB work overtakes its rewrite/fixture costs.
-
-### ZTD cost structure (what is expensive)
-
-ZTD’s incremental work per test is primarily:
-- **SQL-to-ZTD rewrite time**
-- **Fixture materialization time**
-- **DB query time** (typically small compared to Traditional)
-
-A concrete view is easiest in the steady-state section below, where the runner is warm.
-
-### Steady-state (runner warm) incremental cost
-
-This approximates watch/CI iterations where the runner has already started (first repetition excluded as warmup).
-
-| Suite | Workers | Avg incremental time per iteration (ms) | Avg SQL Count | Avg DB time (ms) | Avg rewrite (ms) | Avg fixture (ms) |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: |
-| Traditional (30 tests) | 1 | 1260.20 | 360 | 1039.98 | - | - |
-| ZTD (30 tests) | 1 | 93.73 | 30 | 30.08 | 32.00 | 20.42 |
-| ZTD (30 tests) | 4 | 91.14 | 30 | 29.95 | 30.75 | 19.40 |
-
-### What this shows
-- Traditional steady-state is dominated by DB time (~1040 ms out of ~1260 ms).
-- ZTD steady-state is dominated by **rewrite (~31 ms) + fixture (~20 ms)**; DB time is ~30 ms.
-- Parallelism has limited impact in ZTD steady-state here because the per-iteration work is already small and may be bounded by coordination / shared overheads.
-
-### Conclusion
-
-- **Runner included (realistic)**:
-  - For very small suites, startup dominates and Traditional can be faster.
-  - For larger suites, ZTD wins end-to-end due to dramatically lower DB work and SQL count.
-- **Parallel execution matters**, but it mainly reduces the execution portion; runner startup becomes the limiting floor.
-- **ZTD’s main costs are rewrite and fixture preparation**, not DB time. This is good news: optimizing rewrite/fixture logic is the highest-leverage path for further speedups.
-
-To regenerate the report, run:
-
-```bash
-pnpm ztd:bench
-```
-
-The report is written to `tmp/bench/report.md`.
-
-## Concepts (Why ZTD?)
-
-### What is ZTD?
-
-Zero Table Dependency (ZTD) keeps your tests aligned with a real database engine without ever creating or mutating physical tables during the test run.
-
-- Application CRUD statements are rewritten into fixture-backed `SELECT` queries.
-- Schema changes are expressed via SQL files (DDL) and their generated row map.
-- Tests consume fixtures + types, not a live mutable schema, which keeps the suite deterministic and safe for automated code generation.
-
-### Schema resolution (`defaultSchema` / `searchPath`)
-
-Application SQL can omit schema qualifiers (for example, `SELECT ... FROM users`). Drivers resolve those references using the `ddl.defaultSchema` and `ddl.searchPath` settings in `ztd.config.json` before matching fixtures / DDL metadata.
-
-## Glossary
-
-- **DDL**: SQL files that define schema objects (tables, enums, indexes, etc.).
-- **Row map (`TestRowMap`)**: Generated TypeScript types describing test rows for each table from DDL.
-- **Fixture**: Static rows used by the driver to answer queries deterministically.
-- **Driver**: The package that connects to your database engine and runs the rewrite + fixture pipeline (for example, `@rawsql-ts/testkit-postgres` plus `@rawsql-ts/adapter-node-pg`).
-
-## AI Coding Workflow (Optional)
-
-1. Update the relevant `ztd/ddl/<schema>.sql` file (for example, `ztd/ddl/public.sql`) with the desired schema.
-2. Run `npx ztd ztd-config` (or `--watch`) to regenerate the generated outputs under `tests/generated/`.
-3. Use the row map + fixtures to write repositories, tests, and fixtures.
-4. Run tests through the testkit-postgres stack (`@rawsql-ts/testkit-postgres` + `@rawsql-ts/adapter-node-pg`) (or another driver) since `ztd-cli` itself never executes SQL.
-5. When generating code with an AI tool, feed it `tests/generated/ztd-row-map.generated.ts`, `tests/generated/ztd-layout.generated.ts`, `ztd.config.json`, and any AGENTS guidance so it can respect the ZTD contract.
-
-## AGENTS.md
-
-`ztd init` copies the AGENTS template from this package into the project root, preferring `AGENTS.md` unless a file already exists (then it falls back to `AGENTS_ztd.md`). The template explains the conventions for AI agents, including which testkit to use, how to treat `tests/generated/ztd-row-map.generated.ts`, and how to avoid mutating schema files. Keep the generated AGENTS file in version control so every future AI assistant receives the same guidance.
-
-`ztd init` also creates `ztd/AGENTS.md` and `ztd/README.md` so contributors always see the canonical DDL, enum, and domain-spec guidance inside the new layout.
+# @rawsql-ts/ztd-cli
+
+![npm version](https://img.shields.io/npm/v/@rawsql-ts/ztd-cli)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+SQL-first CLI for **Zero Table Dependency (ZTD)** workflows, schema inspection, and migration SQL artifact generation.
+
+`ztd-cli` helps scaffold ZTD projects, keep DDL-derived test types in sync, inspect explicit database targets when needed, and generate reviewable SQL artifacts without silently owning runtime or deployment databases. ZTD keeps tests aligned with a real database engine without creating or mutating physical application tables during the test run.
+
+`ztd-cli` does **not** execute SQL by itself. To run ZTD tests, plug in a database adapter and a DBMS-specific testkit such as `@rawsql-ts/adapter-node-pg` + `@rawsql-ts/testkit-postgres` for Postgres.
+
+## Database Ownership Model
+
+`ztd-cli` owns only the ZTD test database, not the application or deployment database.
+
+| Setting / action | Owned by `ztd-cli` | Typical use |
+|---|---|---|
+| `ZTD_TEST_DATABASE_URL` | Yes (implicit) | ZTD tests, internal verification, perf workflows |
+| `DATABASE_URL` | No | Application runtime, CI/CD, deployment tooling |
+| `--url` / complete `--db-*` | No (explicit only) | Non-ZTD target inspection such as `ddl pull`, `ddl diff` |
+
+- `ztd-cli` does not read `DATABASE_URL` automatically — it is not a `ztd-cli` default target.
+- Any non-ZTD database target must be passed explicitly via `--url` or `--db-*`.
+- `ztd-cli` may generate migration SQL artifacts, but it does not apply them.
+
+## Features
+
+- Project scaffolding with `ztd init` (DDL folder, config, test stubs)
+- DDL-to-TypeScript type generation (`TestRowMap`)
+- QuerySpec scaffold generation from SQL assets (`ztd model-gen`) via ZTD-owned inspection or explicit-target inspection
+- Schema pull from an explicit target Postgres database via `pg_dump`
+- DDL diff against an explicit target database for inspection
+- SQL linting with fixture-backed validation
+- Deterministic test specification evidence export (JSON / Markdown)
+- Human-readable test documentation export for ZTD test assets
+- Watch mode for continuous regeneration
+- Validator selection (Zod or ArkType) during init
+- Global machine-readable mode via `--output json`
+- Runtime command introspection via `ztd describe`
+- Dry-run support for write-capable commands such as `init`, `ztd-config`, `model-gen`, and `ddl *`
+- Optional raw JSON request payloads for automation on selected commands
+- `query uses` powered by the reusable `@rawsql-ts/sql-grep-core` engine
+
+## Installation
+
+```bash
+npm install -D @rawsql-ts/ztd-cli
+```
+
+## Getting Started with AI
+
+If you are using an AI coding agent, start with a short prompt that sets only the minimum project shape and domain language. You do **not** need to explain package-manager setup in that prompt — the agent handles `npm install` or `pnpm install` automatically.
+
+Example prompt:
+
+```text
+I want to build a WebAPI application with @rawsql-ts/ztd-cli.
+Use Docker and Postgres.
+Start from the webapi scaffold.
+Model three tables: sales, sale_lines, and products.
+Keep domain, application, presentation, and persistence concerns separated.
+Prepare the initial DDL, scaffold the ZTD project, and explain what was created.
+Do not apply migrations automatically.
+```
+
+What a prompt at this level should usually guarantee:
+
+* a `webapi`-shaped project layout
+* starter DDL under `ztd/ddl/`
+* initial smoke tests and generated-type workflow via `ztd-config`
+* separation between app-facing layers and ZTD-owned persistence assets
+* README / CONTEXT / AGENTS guidance that tells the next actor where to keep working
+
+What it does **not** guarantee by itself:
+
+* production-ready DDL review
+* finalized API boundaries, DTOs, or SQL contracts
+* migration application or deployment execution
+* non-ZTD target inspection unless the caller explicitly passes `--url` or `--db-*`
+
+For a typical `webapi` scaffold, the generated directory shape looks like this:
+
+```text
+src/
+  domain/
+  application/
+  presentation/
+    http/
+  infrastructure/
+    db/
+    telemetry/
+    persistence/
+      repositories/
+        views/
+        tables/
+  sql/
+  catalog/
+    specs/
+    runtime/
+ztd/
+  ddl/
+tests/
+  support/
+  generated/
+.ztd/
+  agents/
+```
+
+How to read that layout:
+
+* `src/domain`, `src/application`, and `src/presentation/http` are where generic WebAPI work should begin.
+* `src/infrastructure/persistence`, `src/sql`, `src/catalog`, and `ztd/ddl` are the ZTD-owned persistence side.
+* `tests/generated` is generated output. Recreate it with `ztd ztd-config` instead of editing it manually.
+* `.ztd/agents` contains managed AI guidance so a later prompt such as "WebAPI化して" does not accidentally jump straight into persistence-specific rules.
+
+## Choose The Right Happy Path
+
+`ztd-cli` has two valid happy paths, and they answer different questions:
+
+* `Published package mode` validates what a normal npm consumer sees in a standalone project.
+* `Local-source developer mode` validates unreleased changes from a local `rawsql-ts` checkout without publishing first.
+
+Use `Published package mode` when you want to check the real package-consumer experience. Use `Local-source developer mode` when you want to dogfood unpublished changes. A published-package failure does not automatically mean the local-source developer path is broken, and a local-source-only workaround should not be presented as the default npm user flow.
+
+For pre-release work inside this monorepo, use the repository-root verification command `pnpm verify:published-package-mode` to pack artifacts and smoke-test the standalone `ztd-cli` flow before publishing. See [Published-Package Verification Before Release](../../docs/guide/published-package-verification.md).
+
+## Happy Path Quickstart (Published Package Mode)
+
+A complete copy-paste sequence to reach a green test run. Choose the **demo** workflow during `ztd init` to get a working example immediately.
+
+### Prerequisites
+
+* Node.js 20+
+* npm, pnpm, or yarn
+
+### Steps
+
+```bash
+# 1. Create a new project (skip if you already have one)
+mkdir my-ztd-project && cd my-ztd-project
+npm init -y
+
+# 2. Install ztd-cli and the test runner
+npm install -D @rawsql-ts/ztd-cli vitest typescript
+
+# 3. Scaffold a ZTD project
+#    Select: workflow → "demo", validator → "Zod (recommended)"
+npx ztd init
+```
+
+After `ztd init` you should see:
+
+| Path                              | Purpose                                                         |
+| --------------------------------- | --------------------------------------------------------------- |
+| `ztd/ddl/public.sql`              | Sample or starter DDL for the default schema                    |
+| `ztd.config.json`                 | CLI defaults for DDL and test layout metadata                   |
+| `tests/smoke.test.ts`             | Minimal smoke test                                              |
+| `tests/smoke.validation.test.ts`  | Validator integration smoke test                                |
+| `tests/support/testkit-client.ts` | Driver wiring placeholder                                       |
+| `src/catalog/specs/`              | Spec and runtime files for the smoke contract                   |
+| `CONTEXT.md`                      | Agent-focused project invariants and recommended command usage  |
+| `.ztd/agents/manifest.json`       | Managed AI guidance index with security notices and entrypoints |
+
+```bash
+# 4. Generate test types from the demo DDL
+npx ztd ztd-config
+```
+
+After `ztd-config` you should see:
+
+| Path                                       | Purpose                                  |
+| ------------------------------------------ | ---------------------------------------- |
+| `tests/generated/ztd-row-map.generated.ts` | Authoritative `TestRowMap` (do not edit) |
+| `tests/generated/ztd-layout.generated.ts`  | Layout metadata for the test harness     |
+
+```bash
+# 5. Run the smoke tests
+npx vitest run
+```
+
+All smoke tests should pass. You now have a working ZTD project.
+
+### Next steps
+
+* Replace the demo DDL with your own schema, or inspect an explicit target with `npx ztd ddl pull --url <target>`
+* Re-run `npx ztd ztd-config` whenever DDL changes (or use `--watch`)
+* Install visible AGENTS files only if you want them in the repo: `npx ztd agents install`
+* Wire a real driver in `tests/support/testkit-client.ts` (see [adapter-node-pg](../adapters/adapter-node-pg) for Postgres)
+* Write domain tests against generated `TestRowMap` types
+
+> **Tip:** For a non-interactive setup (CI, scripts), use `npx ztd init --yes` with explicit flags. See [Commands](#commands) for details.
+
+## Happy Path Quickstart (Local-Source Developer Mode)
+
+Use this mode when you need to dogfood unreleased `rawsql-ts` changes from a local checkout. This is the supported path for validating new CLI behavior before package publication.
+
+### Prerequisites
+
+* A local `rawsql-ts` checkout
+* Node.js 20+
+* `pnpm`
+* A throwaway project outside any `pnpm` workspace
+
+### Steps
+
+```bash
+# 1. Build the CLI from the local checkout
+pnpm -C "<LOCAL_SOURCE_ROOT>" --filter @rawsql-ts/ztd-cli build
+
+# 2. Create a standalone throwaway app outside the monorepo
+mkdir /tmp/my-ztd-dogfood && cd /tmp/my-ztd-dogfood
+
+# 3. Scaffold from local source
+node "<LOCAL_SOURCE_ROOT>/packages/ztd-cli/dist/index.js" init \
+  --workflow empty \
+  --validator zod \
+  --local-source-root "<LOCAL_SOURCE_ROOT>"
+
+# 4. Install the scaffolded dependencies
+pnpm install --ignore-workspace
+
+# 5. Generate test types from the DDL
+npx ztd ztd-config
+
+# 6. Continue the normal loop
+pnpm typecheck
+pnpm test
+```
+
+Use this path for pre-release dogfooding and unpublished dependency combinations. Use the published-package quickstart above when validating the end-user npm experience.
+
+## Quick Reference
+
+```bash
+# Common workflow loop
+ZTD_TEST_DATABASE_URL=postgres://... npx ztd ztd-config  # Regenerate types from DDL
+ZTD_TEST_DATABASE_URL=postgres://... npx vitest run      # Run tests
+npx ztd ddl pull --url postgres://...                    # Inspect an explicit target (optional)
+npx ztd ztd-config --watch                               # Keep types updated while editing DDL
+```
+
+## Agent-Friendly Automation
+
+`ztd-cli` keeps the human-oriented CLI, but also exposes a machine-readable path for agents and scripts.
+
+Reference docs:
+
+* [ztd-cli Agent Interface](../../docs/guide/ztd-cli-agent-interface.md)
+* [ztd-cli Describe Schema](../../docs/guide/ztd-cli-describe-schema.md)
+
+### Global JSON mode
+
+```bash
+npx ztd --output json describe
+npx ztd --output json describe command model-gen
+npx ztd --output json query uses column public.users.email --format json
+```
+
+Use global `--output json` when you want command envelopes on stdout and structured diagnostics on stderr.
+
+### Dry-run safety rails
+
+Use `--dry-run` before commands that would write files:
+
+```bash
+npx ztd init --dry-run --workflow demo --validator zod
+npx ztd ztd-config --dry-run
+npx ztd model-gen src/sql/users/list.sql --sql-root src/sql --out src/catalog/specs/list.spec.ts --dry-run
+npx ztd ddl pull --url postgres://... --out ztd/ddl --dry-run
+npx ztd ddl diff --url postgres://... --out artifacts/schema.diff --dry-run
+npx ztd ddl gen-entities --out src/entities.ts --dry-run
+```
+
+### JSON request payloads
+
+Selected commands accept `--json <payload>` to reduce flag-by-flag construction in automation. Prefix the value with `@` to load JSON from a file.
+
+```bash
+npx ztd init --dry-run --json '{"workflow":"demo","validator":"zod","withSqlclient":true}'
+npx ztd ztd-config --output json --json '{"ddlDir":"ztd/ddl","extensions":".sql,.ddl","dryRun":true}'
+npx ztd ddl pull --output json --json '{"url":"postgres://example:example@127.0.0.1:5432/app_db","out":"ztd/ddl","schema":["public"],"dryRun":true}'
+npx ztd model-gen src/sql/users/list.sql --json '{"sqlRoot":"src/sql","probeMode":"ztd","dryRun":true}'
+npx ztd check contract --json '{"format":"json","strict":true}'
+npx ztd query uses column --json '{"target":"public.users.email","format":"json","summaryOnly":true}'
+npx ztd lint --json '{"path":"src/sql/**/*.sql"}'
+```
+
+## Recommended Backend Happy Path
+
+For backend work, split the loop into **ZTD-owned** work and **explicit-target inspection** work instead of mixing them from the start.
+
+| Step                                                                                               | Primary actor | Phase                      | Why                                                                                                                                                       |
+| -------------------------------------------------------------------------------------------------- | ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Choose the PostgreSQL version and test DB bootstrap                                                | AI / Human    | ZTD-owned                  | Fix the ZTD-owned test database first so generated files, tests, and docs all refer to the same environment.                                              |
+| Draft the DDL in `ztd/ddl/*.sql`                                                                   | AI / Human    | ZTD-owned                  | Treat DDL as the source of truth. Prefer application-owned identifiers/timestamps in the initial loop so tests do not depend on sequences or DB defaults. |
+| Run `ztd init --workflow empty`                                                                    | CLI           | ZTD-owned                  | Scaffold folders, config, and test placeholders mechanically.                                                                                             |
+| Run `ztd ztd-config`                                                                               | CLI           | ZTD-owned                  | Regenerate `TestRowMap` directly from DDL without applying migrations.                                                                                    |
+| Write SQL assets under `src/sql` using named params                                                | AI / Human    | ZTD-owned                  | Keep the handwritten SQL authoritative while matching the default `model-gen` policy.                                                                     |
+| Implement QuerySpecs, repositories, and ZTD tests                                                  | AI / Human    | ZTD-owned                  | Contract semantics, DTO shape, and query boundaries still require judgment.                                                                               |
+| Run `vitest` against an empty Postgres instance                                                    | CLI           | ZTD-owned                  | ZTD should stay green before any physical app tables exist.                                                                                               |
+| Run `ztd model-gen --probe-mode ztd` against your local DDL snapshot                               | CLI           | ZTD-owned                  | This keeps QuerySpec scaffolding inside the zero-migration inner loop as long as the referenced schema is represented in `ztd/ddl/*.sql`.                 |
+| Inspect a non-ZTD database target only when you need deployed metadata                             | Human / CLI   | Explicit-target inspection | This is where `ddl pull`, `ddl diff`, explicit-target inspection, E2E setup, and migration artifact preparation begin.                                    |
+| Run `ztd model-gen --probe-mode live` only when local DDL is intentionally not the source of truth | CLI           | Explicit-target inspection | Use explicit-target inspection for objects missing from local DDL or when you explicitly want deployed metadata.                                          |
+
+Use this split to classify repetition:
+
+* Repeated CLI retries caused by missing flags, missing paths, or boilerplate setup usually belong in docs or CLI automation.
+* Repeated AI retries caused by contract shape, nullability, naming, or domain semantics usually indicate design choices that should stay reviewable.
+* Prefer the ZTD-owned loop by default. If a task is impossible there because the required metadata is not represented in local DDL, treat it as an explicit-target inspection concern instead of forcing migrations into the inner loop.
+
+## Commands
+
+Most write-capable commands support `--dry-run` and `--json <payload>` for automation. Run `npx ztd describe command <name>` for per-command details.
+
+| Command | Description |
+|---------|-------------|
+| `ztd init` | Create a ZTD-ready project layout (DDL folder, config, test stubs). Flags: `--yes`, `--workflow <pg_dump\|empty\|demo>`, `--validator <zod\|arktype>`, `--with-sqlclient`, `--with-app-interface`, `--local-source-root <path>` |
+| `ztd agents install` | Materialize visible `AGENTS.md` files from the managed templates |
+| `ztd agents status` | Report internal/visible AGENTS state and drift signals |
+| `ztd ztd-config` | Generate `TestRowMap` and layout from DDL files. Flags: `--watch`, `--quiet` |
+| `ztd model-gen <sql-file>` | Generate QuerySpec DTO types and rowMapping by inspecting DDL or an explicit target. Flags: `--probe-mode <ztd\|live>`, `--import-style <package\|relative>`, `--import-from`, `--describe-output`, `--debug-probe` |
+| `ztd ddl pull` | Inspect schema state from an explicit target Postgres database via `pg_dump`. Flag: `--pg-dump-shell` |
+| `ztd ddl diff` | Compare local DDL snapshot against an explicit target database. Flag: `--pg-dump-shell` |
+| `ztd ddl gen-entities` | Generate `entities.ts` for ad-hoc schema inspection |
+| `ztd lint <path>` | Lint SQL files with fixture-backed validation |
+| `ztd evidence --mode specification` | Export executable specification evidence from SQL catalogs and test files |
+| `ztd check contract` | Validate contract consistency |
+| `ztd describe` | List command descriptions and machine-readable capability metadata |
+| `ztd describe command <name>` | Describe one command in detail, including dry-run and JSON support |
+| `ztd --output json <command>` | Emit a versioned JSON envelope for supported commands |
+| `ztd query uses table <schema.table>` | Find catalog SQL statements that use a table target |
+| `ztd query uses column <schema.table>.<col>` | Find catalog SQL statements that use a column target. Flags: `--sql-root`, `--exclude-generated`, `--any-schema`, `--any-table`, `--view <impact\|detail>` |
+
+### Introspection examples
+
+```bash
+npx ztd describe
+npx ztd describe command init
+npx ztd --output json describe command model-gen
+```
+
+## Impact Investigation
+
+Use `ztd query uses` before renaming or deleting catalog-facing SQL assets. The command is strict by default and never broadens matching unless you opt in with relaxed flags.
+
+* `impact` (default) — aggregated "used or not, and by which queries?" view
+* `--view detail` — edit-ready locations and snippets for refactoring
+* `--exclude-generated` — omit `src/catalog/specs/generated` when those scaffolds add noise
+* `--any-schema` / `--any-table` — relaxed matching (drops confidence to `low`)
+
+```bash
+# Strict
+npx ztd query uses table public.users
+npx ztd query uses column public.users.email --view detail
+npx ztd query uses table public.sale_lines --exclude-generated
+
+# Relaxed
+npx ztd query uses column users.email --any-schema --format json
+```
+
+Output includes `confidence`, `notes` (why confidence dropped), `source` (AST vs fallback), and `statement_fingerprint` (stable across whitespace changes). Static column analysis does not guarantee semantic identity.
+
+For the full JSON schema and output field reference, see `npx ztd query uses column public.users.email --format json`.
+
+## What is ZTD?
+
+Zero Table Dependency rewrites application CRUD statements into fixture-backed SELECT queries, so tests consume fixtures and generated types instead of a live mutable schema.
+
+* Schema changes are expressed via SQL files (DDL)
+* `ztd-config` generates TypeScript types from those DDL files
+* Tests run deterministically without creating or mutating physical tables
+
+The typical loop: edit `ztd/ddl/*.sql` -> `ZTD_TEST_DATABASE_URL=... ztd ztd-config --watch` -> write tests. Use `ddl pull` only when you intentionally inspect an explicit target.
+
+## After DDL/Schema Changes
+
+When your database schema evolves, regenerate test types and re-run tests. Here is the standard workflow and common patterns.
+
+### Standard workflow
+
+```bash
+# 1. Update DDL files in ztd/ddl/
+#    Edit manually, or inspect an explicit target:
+npx ztd ddl pull --url postgres://...
+
+# 2. Regenerate test types
+npx ztd ztd-config
+
+# 3. Fix compile errors (if any) in tests and specs
+#    Generated TestRowMap shapes may have changed
+
+# 4. Re-run tests
+npx vitest run
+
+# 5. (Optional) Lint SQL files against the new schema
+npx ztd lint src/sql/
+```
+
+### Common patterns
+
+#### Add a column
+
+1. Add the column to your DDL file (`ztd/ddl/*.sql`)
+2. Run `npx ztd ztd-config` — the new column appears in `TestRowMap`
+3. Update fixtures in tests to include the new column (if required by NOT NULL)
+4. Run `npx vitest run`
+
+#### Rename a column
+
+1. Rename the column in the DDL file
+2. Run `npx ztd ztd-config` — old name disappears, new name appears in `TestRowMap`
+3. Update all references: SQL files, `rowMapping` column maps, fixtures, and specs
+4. Run `npx vitest run` to catch any remaining references via compile errors
+
+#### Add a new table
+
+1. Add the CREATE TABLE to a DDL file (new file or existing)
+2. Run `npx ztd ztd-config` — new table type appears in `TestRowMap`
+3. Write SQL queries and tests for the new table
+4. Run `npx vitest run`
+
+#### Drop a column or table
+
+1. Remove from DDL
+2. Run `npx ztd ztd-config` — the removed type/column disappears
+3. Compile errors guide you to all affected code
+4. Remove or update references, then run `npx vitest run`
+
+### Troubleshooting
+
+| Symptom                             | Cause                                      | Fix                                                                                                       |
+| ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `TestRowMap` not updated            | Forgot to run `ztd-config`                 | Run `npx ztd ztd-config`                                                                                  |
+| Compile errors after `ztd-config`   | Schema shape changed                       | Update fixtures, specs, and column maps to match new shape                                                |
+| `ztd-config` fails to parse DDL     | Unsupported SQL syntax                     | Simplify the DDL or check for dialect-specific constructs                                                 |
+| Tests pass but SQL fails at runtime | DDL and an explicit target are out of sync | Run `npx ztd ddl diff --url <target>` to compare, then `npx ztd ddl pull --url <target>` to inspect again |
+
+> **Tip:** Use `npx ztd ztd-config --watch` during development to regenerate types automatically when DDL files change.
+
+## QuerySpec Workflow
+
+`ztd model-gen` is designed for SQL asset files under `src/sql/` and assumes **named parameters** (`:name`).
+
+Important context:
+
+* `:name` is an intentional project-level SQL asset convention, not native PostgreSQL syntax.
+* Before inspection, `model-gen` binds named parameters to PostgreSQL placeholders such as `$1`, `$2` and runs a metadata-only wrapper query.
+* `--probe-mode ztd` uses `ZTD_TEST_DATABASE_URL` for the ZTD-owned inspection path.
+* `--probe-mode live` is the explicit-target inspection path. Pass `--url` or a complete `--db-*` flag set.
+* `ztd-cli` does not read `DATABASE_URL` automatically for either path.
+* `--probe-mode ztd` still rewrites the inspection through your DDL snapshot so physical app tables are not required. It uses `ztd.config.json` (`ddlDir`, `ddl.defaultSchema`, `ddl.searchPath`) unless you override the directory with `--ddl-dir`.
+
+```text
+1. Write SQL in src/sql/ using named parameters such as :customerId
+2. Prefer the ZTD-first command during the inner loop:
+   - `ztd model-gen src/sql/my_query.sql --probe-mode ztd --out src/catalog/specs/my-query.spec.ts`
+   - Or validate only: `ztd model-gen src/sql/my_query.sql --probe-mode ztd --out src/catalog/specs/my-query.spec.ts --dry-run`
+3. Use explicit-target inspection only when local DDL is not the source of truth:
+   - `ztd model-gen src/sql/my_query.sql --probe-mode live --out src/catalog/specs/my-query.spec.ts`
+4. Review the generated types, rowMapping key, nullability, and normalization
+5. Run ZTD tests to confirm the contract
+```
+
+Example SQL asset:
+
+```sql
+select
+  p.id as product_id,
+  p.name as product_name,
+  p.price as list_price
+from public.products p
+where p.id = :product_id
+```
+
+Example generated scaffold excerpt:
+
+```ts
+export const getProductSpec: QuerySpec<{ product_id: unknown }, GetProductRow> = {
+  id: 'product.getProduct',
+  sqlFile: 'product/get_product.sql',
+  params: { shape: 'named', example: { product_id: null } },
+  output: {
+    mapping: getProductMapping,
+    example: {
+      productId: 0,
+      productName: '',
+      listPrice: '',
+    },
+  },
+};
+```
+
+Notes:
+
+* SQL asset files should use named parameters (`:name`). `model-gen` rewrites them to `$1`, `$2` before inspection. Positional placeholders are rejected by default (`--allow-positional` for legacy SQL).
+* `--probe-mode ztd` (recommended) uses `ZTD_TEST_DATABASE_URL` and your DDL snapshot — no physical app tables needed. Unqualified names resolve via `ddl.defaultSchema` / `ddl.searchPath` in `ztd.config.json`.
+* `--probe-mode live` (default for backward compatibility) is for schema objects not yet in local DDL, or when you want metadata from an explicit target.
+* The generated file is a starting point. Review nullability, rowMapping key, and example values before committing.
+* Run `--describe-output` to inspect the artifact contract without connecting to PostgreSQL. Use `--dry-run` to validate without writing files.
+
+### Optional-condition SQL
+
+For optional filters, prefer keeping the condition in the SQL file itself (`where (:param is null or col = :param)`) before reaching for string-built query assembly. See [ztd-cli SSSQL Authoring](../../docs/guide/ztd-cli-sssql-authoring.md) and [What Is SSSQL?](../../docs/guide/sssql-overview.md) for the full pattern.
+
+## Telemetry Philosophy
+
+`ztd-cli` telemetry is opt-in investigation tooling for dogfooding, debugging, and optimization. It is intentionally outside the default happy path, it must not become mandatory for published-package usage, and production embedding/export stays optional and off by default.
+
+Read the full guidance in [ztd-cli Telemetry Philosophy](../../docs/guide/ztd-cli-telemetry-philosophy.md), [ztd-cli Telemetry Policy](../../docs/guide/ztd-cli-telemetry-policy.md), [ztd-cli Telemetry Export Modes](../../docs/guide/ztd-cli-telemetry-export-modes.md), [Telemetry Dogfooding Scenarios](../../docs/dogfooding/telemetry-dogfooding.md), [SQL Debug Recovery Dogfooding](../../docs/dogfooding/sql-debug-recovery.md), and [Test Documentation Dogfooding](../../docs/dogfooding/test-documentation.md).
+
+## Further Reading
+
+* [Feature Index](../../docs/guide/feature-index.md) — at-a-glance list of easy-to-miss capabilities
+* [SQL Tool Happy Paths](../../docs/guide/sql-tool-happy-paths.md) — choose between query plan, perf, query uses, and telemetry based on the problem shape
+* [ztd-cli SSSQL Authoring](../../docs/guide/ztd-cli-sssql-authoring.md) — keep optional-condition requests on the SQL-first path
+* [Local-Source Dogfooding](../../docs/guide/ztd-local-source-dogfooding.md) — local-source quick start, workspace drift, and import mismatches
+* [Postgres Pitfalls](../../docs/guide/postgres-pitfalls.md) — common Postgres-specific surprises
+* [Spec-Change Scenarios](../../docs/guide/spec-change-scenarios.md) — condensed digest of common schema changes
+* [Mapping vs Validation Pipeline](../../docs/recipes/mapping-vs-validation.md) — avoid coerce/validator conflicts
+
+## Glossary
+
+| Term           | Description                                                                     |
+| -------------- | ------------------------------------------------------------------------------- |
+| **DDL**        | SQL files defining schema objects (tables, enums, indexes)                      |
+| **TestRowMap** | Generated TypeScript types describing test rows for each table                  |
+| **Fixture**    | Static rows used by the driver to answer queries deterministically              |
+| **Driver**     | Package connecting to your DB engine and running the rewrite + fixture pipeline |
+
+## License
+
+MIT