db-model-router 1.0.2 → 1.0.3

package/README.md

@@ -2,6 +2,20 @@
 
 A database-agnostic REST API generator for Node.js. Works with Express or ultimate-express (a high-performance drop-in replacement). Define a model, get a full CRUD API with filtering, pagination, and bulk operations — backed by any of 9 supported databases.
 
+## Build a REST API with AI
+
+This library is designed to be driven by an AI assistant. Give it a prompt like this:
+
+```
+Use db-model-router to build a REST API for a task management app with postgres.
+I need: users (name, email, password_hash), projects (name, description, owner_id → users),
+and tasks (title, status, priority, project_id → projects, assignee_id → users).
+Scaffold the project, write the migrations, generate models and routes with parent-child
+relationships for projects.tasks, and make sure everything runs.
+```
+
+For the LLM skill reference, see [SKILL.md](./docs/SKILL.md).
+
 ## Supported Adapters
 
 | Adapter                                       | Module Key    | Driver                   | Install                                                                |
@@ -55,6 +69,143 @@ npm install db-model-router @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
 
 Both `express` and `ultimate-express` are optional peer dependencies. The library auto-detects which one is installed (preferring `ultimate-express` when both are present). All database drivers are also optional peer dependencies, so your `node_modules` stays lean.
 
+## Quick Start
+
+The fastest way to start a new project:
+
+```bash
+# Scaffold a project interactively
+npx db-model-router init
+
+# Or fully non-interactive from a schema file
+db-model-router init --from dbmr.schema.json --yes --no-install
+db-model-router generate --from dbmr.schema.json
+```
+
+After scaffolding:
+
+```bash
+# 1. Edit .env with your database credentials
+# 2. Start developing
+npm run dev
+```
+
+## Schema-Driven Workflow
+
+Instead of running multiple CLI commands manually, you can define your entire project in a single `dbmr.schema.json` file and let the CLI generate everything from it.
+
+### The Schema File
+
+`dbmr.schema.json` is a declarative JSON file that describes your adapter, framework, tables, columns, relationships, and options — all in one place:
+
+```json
+{
+  "adapter": "postgres",
+  "framework": "express",
+  "options": {
+    "session": "redis",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true
+  },
+  "tables": {
+    "users": {
+      "columns": {
+        "name": "required|string",
+        "email": "required|string",
+        "age": "integer",
+        "is_deleted": "boolean"
+      },
+      "pk": "id",
+      "unique": ["email"],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      }
+    },
+    "posts": {
+      "columns": {
+        "title": "required|string",
+        "body": "string",
+        "user_id": "required|integer"
+      },
+      "pk": "id",
+      "unique": ["id"]
+    }
+  },
+  "relationships": [
+    { "parent": "users", "child": "posts", "foreignKey": "user_id" }
+  ]
+}
+```
+
+Table entries support these fields:
+
+| Field        | Required | Description                                                    |
+| ------------ | -------- | -------------------------------------------------------------- |
+| `columns`    | Yes      | Object mapping column names to Column_Rule strings             |
+| `pk`         | No       | Primary key column name (defaults to `"id"`)                   |
+| `unique`     | No       | Array of unique constraint columns (defaults to `[pk]`)        |
+| `softDelete` | No       | Column name used for soft-delete                               |
+| `timestamps` | No       | Object with `created_at` and `modified_at` column name mapping |
+
+Column rules use the format `(required|)?(string|integer|numeric|boolean|object)` — e.g. `"required|string"`, `"integer"`, `"object"`.
+
+### Unified CLI: `db-model-router`
+
+The `db-model-router` command is the unified entry point with five subcommands:
+
+```bash
+db-model-router <subcommand> [flags]
+```
+
+| Subcommand | Description                                                         |
+| ---------- | ------------------------------------------------------------------- |
+| `init`     | Scaffold a new project (optionally from a schema file)              |
+| `inspect`  | Introspect a live database and produce a `dbmr.schema.json`         |
+| `generate` | Generate models, routes, tests, and OpenAPI spec from the schema    |
+| `doctor`   | Validate schema, check dependencies, verify generated files in sync |
+| `diff`     | Preview what changes regeneration would make (read-only)            |
+
+#### Universal Flags
+
+All subcommands accept these flags:
+
+| Flag           | Description                                                 |
+| -------------- | ----------------------------------------------------------- |
+| `--yes`        | Accept all defaults, suppress interactive prompts           |
+| `--json`       | Output machine-readable JSON instead of human-readable text |
+| `--dry-run`    | Preview actions without writing files or running commands   |
+| `--no-install` | Skip `npm install` (applies to commands that would run it)  |
+| `--help`       | Show usage information for the subcommand                   |
+
+#### Quick Workflow Example
+
+```bash
+# 1. Introspect an existing database into a schema file
+db-model-router inspect --type postgres --env .env
+
+# 2. (Optional) Edit dbmr.schema.json to add relationships, tweak columns, etc.
+
+# 3. Generate all artifacts from the schema
+db-model-router generate --from dbmr.schema.json
+
+# 4. Check everything is in sync
+db-model-router doctor --from dbmr.schema.json
+
+# 5. Preview what a regeneration would change
+db-model-router diff --from dbmr.schema.json
+```
+
+Or start a brand-new project from a schema file:
+
+```bash
+# Scaffold project + generate everything in one go
+db-model-router init --from dbmr.schema.json --yes --no-install
+db-model-router generate --from dbmr.schema.json
+```
+
 ## MySQL Example
 
 ### 1. Connect
@@ -109,13 +260,14 @@ app.use("/users", route(users));
 app.listen(3000);
 ```
 
-This creates 8 endpoints:
+This creates 9 endpoints:
 
 | Method | Path         | Description                     |
 | ------ | ------------ | ------------------------------- |
 | GET    | `/users/:id` | Get one record by PK            |
 | POST   | `/users/add` | Insert a single record          |
 | PUT    | `/users/:id` | Update a single record          |
+| PATCH  | `/users/:id` | Partial update a single record  |
 | DELETE | `/users/:id` | Delete a single record          |
 | GET    | `/users/`    | List with pagination            |
 | POST   | `/users/`    | Bulk insert (`{ data: [...] }`) |
@@ -274,207 +426,6 @@ The model and route APIs remain identical across all adapters. See the individua
 - [Redis](./docs/adapters/redis.md)
 - [DynamoDB](./docs/adapters/dynamodb.md)
 
-## CLI Tools
-
-Three CLI commands are included to scaffold models, routes, and full apps from an existing database.
-
-### generate-app
-
-The fastest way to go from database to running API. Scaffolds a complete Express REST API project in a single command — introspects your database, generates models and routes (including parent-child relationships), and creates the app entry point, middleware, environment config, and project structure.
-
-```bash
-# Full app from MySQL
-db-model-router-generate-app --type mysql --env .env
-
-# SQLite3 into a specific directory
-db-model-router-generate-app --type sqlite3 --database ./myapp.db --output ./my-api
-
-# Postgres with specific tables and relationships
-db-model-router-generate-app --type postgres --env .env --tables users,posts,posts.comments
-```
-
-Options:
-
-| Option       | Description                                                                     |
-| ------------ | ------------------------------------------------------------------------------- |
-| `--type`     | Database type (mysql, postgres, sqlite3, mssql, oracle, cockroachdb) [required] |
-| `--output`   | Output directory (default: current directory)                                   |
-| `--host`     | Database host                                                                   |
-| `--port`     | Database port                                                                   |
-| `--database` | Database name or file path                                                      |
-| `--user`     | Database user                                                                   |
-| `--password` | Database password                                                               |
-| `--schema`   | Schema name (postgres only)                                                     |
-| `--tables`   | Comma-separated tables, supports `parent.child` notation for relationships      |
-| `--env`      | Path to .env file for DB connection                                             |
-
-Generated project structure:
-
-```
-my-api/
-  app.js              # Express app with init(), db.connect(), middleware, error handler, health check
-  .env.example         # Pre-filled environment template for your DB type
-  .gitignore           # node_modules, .env, *.db
-  middleware/
-    logger.js          # Request logger (method, URL, status, response time)
-  models/
-    users.js           # Auto-generated from DB introspection
-    posts.js
-    index.js
-  routes/
-    users.js           # Auto-generated route files
-    posts.js
-    index.js
-    openapi.json       # OpenAPI 3.0 spec
-  migrations/
-    README.md          # Placeholder for migration scripts
-  sessions/
-    README.md          # Placeholder for session config
-```
-
-When `--tables` includes parent-child notation (e.g., `posts.comments`), the routes directory also includes scoped child route files and nested route mounting — see [Parent-Child Relationships](#parent-child-relationships-foreign-keys) below.
-
-To start the generated app:
-
-```bash
-cp .env.example .env   # edit with your DB credentials
-npm install
-node app.js
-```
-
-### generate-model
-
-Connects to your database, introspects all tables, and generates model files with validation rules, primary keys, unique constraints, and auto-detected options (safeDelete, timestamps). This is called automatically by `generate-app`, but can be used standalone.
-
-```bash
-# Basic usage
-db-model-router-generate-model --type mysql --host localhost --database mydb --user root --password secret
-
-# Using an .env file
-db-model-router-generate-model --type postgres --env .env --output ./src/models
-
-# SQLite3
-db-model-router-generate-model --type sqlite3 --database ./myapp.db --output ./models
-
-# Only specific tables
-db-model-router-generate-model --type mysql --env .env --tables users,posts,comments
-```
-
-Options:
-
-| Option       | Description                                                                   |
-| ------------ | ----------------------------------------------------------------------------- |
-| `--type`     | Database type (mysql, postgres, sqlite3, mssql, oracle, cockroachdb)          |
-| `--host`     | Database host (default: localhost)                                            |
-| `--port`     | Database port                                                                 |
-| `--database` | Database name (or file path for sqlite3)                                      |
-| `--user`     | Database user                                                                 |
-| `--password` | Database password                                                             |
-| `--schema`   | Schema name (postgres only, default: public)                                  |
-| `--output`   | Output directory (default: ./models)                                          |
-| `--tables`   | Comma-separated list of tables to generate (supports `parent.child` notation) |
-| `--env`      | Path to .env file to load                                                     |
-
-Auto-detection:
-
-- Columns with `DEFAULT` values are marked as optional (not `required`)
-- Timestamp columns (`created_at`, `updated_at`, `modified_at`, `createdAt`, etc.) are excluded from the model structure and added to the option object
-- Soft-delete columns (`is_deleted`, `deleted`, `is_active`, `archived`, etc.) are excluded from the structure and set as `safeDelete` in the option
-- Multi-column unique indexes are correctly grouped for the unique constraint parameter
-
-Generated output:
-
-```
-models/
-  users.js          # model(db, "users", {...}, "user_id", ["email"], { safeDelete: "is_deleted", ... })
-  posts.js          # model(db, "posts", {...}, "post_id", ["post_id"])
-  index.js          # exports { users, posts }
-```
-
-### generate-route
-
-Generates Express route files for each model. If models don't exist yet, it auto-generates them first. Also generates an OpenAPI 3.0 spec (`openapi.json`) from the model metadata. This is called automatically by `generate-app`, but can be used standalone.
-
-```bash
-# From existing models
-db-model-router-generate-route --models ./models --output ./routes
-
-# Auto-generate models + routes in one step
-db-model-router-generate-route --type mysql --env .env --models ./models --output ./routes
-
-# SQLite3 one-liner
-db-model-router-generate-route --type sqlite3 --database ./myapp.db
-```
-
-Options:
-
-| Option       | Description                                                                |
-| ------------ | -------------------------------------------------------------------------- |
-| `--models`   | Path to models directory (default: ./models)                               |
-| `--output`   | Output directory for routes (default: ./routes)                            |
-| `--type`     | Database type — triggers model generation if models are missing            |
-| `--host`     | Database host (passed to model generation)                                 |
-| `--port`     | Database port (passed to model generation)                                 |
-| `--database` | Database name or file path (passed to model generation)                    |
-| `--user`     | Database user (passed to model generation)                                 |
-| `--password` | Database password (passed to model generation)                             |
-| `--schema`   | Schema name (passed to model generation)                                   |
-| `--tables`   | Comma-separated tables, supports `parent.child` notation for relationships |
-| `--env`      | Path to .env file (passed to model generation)                             |
-
-#### Parent-Child Relationships (Foreign Keys)
-
-Use dot notation in `--tables` to declare parent-child relationships. This works in `generate-route`, `generate-app`, and `generate-model`. The generator creates nested routes that automatically scope child queries by the parent's foreign key.
-
-```bash
-# Declare that comments belong to posts
-db-model-router-generate-route --type mysql --env .env --tables users,posts,posts.comments
-
-# Same via generate-app
-db-model-router-generate-app --type mysql --env .env --tables users,posts,posts.comments
-```
-
-The FK column is derived by convention: `<parent_singular>_id` (e.g., `posts.comments` → `post_id`).
-
-This generates:
-
-```
-routes/
-  users.js                        # route(users)
-  posts.js                        # route(posts)
-  comments.js                     # route(comments)  — direct access
-  comments_child_of_posts.js      # route(comments, { post_id: "params.post_id" })  — scoped
-  index.js                        # mounts all routes
-  openapi.json                    # OpenAPI 3.0 spec
-```
-
-The generated `index.js` mounts both nested and top-level routes:
-
-```js
-// Nested: GET /api/posts/:post_id/comments — returns only comments for that post
-router.use("/posts/:post_id/comments", commentsChildRoute);
-
-// Direct: GET /api/comments — returns all comments
-router.use("/comments", commentsRoute);
-```
-
-The child route file uses payload override to scope every query:
-
-```js
-// comments_child_of_posts.js
-module.exports = route(comments, { post_id: "params.post_id" });
-```
-
-#### Generated output (without relationships)
-
-```
-routes/
-  users.js          # route(users)
-  posts.js          # route(posts)
-  index.js          # express.Router() mounting all routes at /users, /posts, etc.
-  openapi.json      # OpenAPI 3.0 spec
-```
-
 ## Environment Setup (Docker)
 
 A `docker-compose.yml` is included for running all supported databases locally:

package/docs/SKILL.md

@@ -1,15 +1,45 @@
+---
+name: db-model-router
+description: Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API. Works with express or ultimate-express.
+---
+
 # db-model-router — LLM Skill Reference
 
-Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API.
+Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API. Works with `express` or `ultimate-express`.
+
+## LLM Workflow (follow this order)
+
+1. **Scaffold**: `db-model-router-init --framework express --database postgres --session redis --rateLimiting --helmet --logger` (all flags → zero prompts)
+2. **Migrations**: Write SQL/JS migration files into `migrations/` for the user's schema, then `npm run migrate`
+3. **Generate models**: `db-model-router-generate-model --type postgres --env .env --output ./models`
+4. **Generate routes + tests**: `db-model-router-generate-route --models ./models --output ./routes --tables users,posts,posts.comments`
+5. **Run**: `npm run dev`
+
+Step 1 creates the project. Step 2 defines the schema. Steps 3-4 introspect the DB and generate models, routes, tests, and OpenAPI spec. Step 5 starts the server.
 
 ## Install
 
 ```bash
-npm install db-model-router <driver>
+npm install db-model-router <framework> <driver>
 ```
 
+Frameworks: `express` or `ultimate-express` (auto-detected, prefers ultimate-express)
 Drivers: `mysql2`, `pg`, `better-sqlite3`, `mongodb`, `mssql`, `oracledb`, `ioredis`, `@aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb`
 
+## Adapters
+
+| Module Key    | Driver                                           | Default Port |
+| ------------- | ------------------------------------------------ | ------------ |
+| `mysql`       | mysql2                                           | 3306         |
+| `postgres`    | pg                                               | 5432         |
+| `sqlite3`     | better-sqlite3                                   | —            |
+| `mongodb`     | mongodb                                          | 27017        |
+| `mssql`       | mssql                                            | 1433         |
+| `cockroachdb` | pg                                               | 26257        |
+| `oracle`      | oracledb                                         | 1521         |
+| `redis`       | ioredis                                          | 6379         |
+| `dynamodb`    | @aws-sdk/client-dynamodb + @aws-sdk/lib-dynamodb | —            |
+
 ## Init → Connect → Model → Route
 
 ```js
@@ -42,12 +72,12 @@ app.use("/users", route(users));
 
 ## model(db, table, structure, pk, unique, option)
 
-| Param     | Type            | Description                                                                                                           |
-| --------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
-| structure | `{col: "rule"}` | Types: `string\|integer\|numeric\|object`. Prefix `required\|` for NOT NULL. Exclude PK, timestamps, soft-delete cols |
-| pk        | string          | Primary key column. Default `"id"`                                                                                    |
-| unique    | string[]        | Columns for upsert conflict resolution                                                                                |
-| option    | object          | `{ safeDelete, created_at, modified_at }` — column names or null                                                      |
+| Param     | Type            | Description                                                                                                                    |
+| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| structure | `{col: "rule"}` | Types: `string\|integer\|numeric\|boolean\|object`. Prefix `required\|` for NOT NULL. Exclude PK, timestamps, soft-delete cols |
+| pk        | string          | Primary key column. Default `"id"`                                                                                             |
+| unique    | string[]        | Columns for upsert conflict resolution                                                                                         |
+| option    | object          | `{ safeDelete, created_at, modified_at }` — column names or null                                                               |
 
 ## Model Methods (all async)
 
@@ -83,14 +113,22 @@ Structure: `[OR_groups[AND_conditions[col, op, val]]]`
 Ops: `= != < > <= >= like not like in not in`
 
 ```js
+// AND: age > 25 AND type = 1
 [
   [
     ["age", ">", 25],
     ["type", "=", 1],
   ],
-][([["name", "=", "A"]], [["name", "=", "B"]])][[["type", "in", [1, 2, 3]]]][ // AND // OR // IN
+][
+  // OR: name = "A" OR name = "B"
+  ([["name", "=", "A"]], [["name", "=", "B"]])
+][
+  // IN
+  [["type", "in", [1, 2, 3]]]
+][
+  // LIKE (auto-wraps with %)
   [["name", "like", "Ali"]]
-]; // LIKE %Ali%
+];
 ```
 
 ## route(model, override?)
@@ -100,14 +138,14 @@ Generates Express Router with 9 endpoints:
 | Method | Path   | Action                           |
 | ------ | ------ | -------------------------------- |
 | GET    | `/:pk` | Get by PK                        |
-| POST   | `/:id` | Insert single                    |
-| PUT    | `/:id` | Update single (PK from URL)      |
-| PATCH  | `/:id` | Partial update                   |
-| DELETE | `/:id` | Delete single                    |
+| POST   | `/add` | Insert single                    |
+| PUT    | `/:pk` | Update single (PK from URL)      |
+| PATCH  | `/:pk` | Partial update (PK from URL)     |
+| DELETE | `/:pk` | Delete single                    |
 | GET    | `/`    | List (page, size, sort, filters) |
 | POST   | `/`    | Bulk insert `{data:[...]}`       |
 | PUT    | `/`    | Bulk update `{data:[...]}`       |
-| DELETE | `/`    | Bulk delete `{data:[...]}`       |
+| DELETE | `/`    | Bulk delete                      |
 
 **Payload override** (multi-tenancy): `route(m, { tenant_id: "user.tenant_id" })` — maps cols to `req` paths via lodash.get.
 
@@ -115,13 +153,65 @@ Generates Express Router with 9 endpoints:
 
 ## CLI Tools
 
-### generate-app (full scaffold)
+### db-model-router-init (interactive project scaffold)
+
+Scaffolds a complete Express-based REST API project from scratch. Supports both interactive prompts and fully non-interactive CLI flags.
 
 ```bash
-db-model-router-generate-app --type mysql --env .env [--output ./dir] [--tables users,posts,posts.comments]
+# Interactive (prompts for everything)
+npx db-model-router-init
+
+# Fully non-interactive (LLM-friendly — no prompts)
+db-model-router-init --framework express --database postgres --session redis --rateLimiting --helmet --logger
+
+# Partial flags — only prompts for missing values
+db-model-router-init --database mysql --session memory
 ```
 
-Creates: `app.js`, `models/`, `routes/`, `middleware/logger.js`, `.env.example`, `.gitignore`, `migrations/`, `sessions/`, `openapi.json`
+Flags: `--framework <name>`, `--database <name>` (or `--db`), `--session <type>`, `--rateLimiting`, `--helmet`, `--logger`, `--help`
+
+When all 6 options are provided, runs with zero prompts.
+
+Prompts (for missing values): framework (`ultimate-express`|`express`), database (9 options), session (`memory`|`redis`|`database`), rate limiting (y/n), helmet (y/n), logger (y/n).
+
+If no `package.json` exists, runs `npm init` first. After prompts: generates files, updates `package.json`, runs `npm install`.
+
+Generated structure:
+
+```
+app.js, .env, .env.example, .gitignore, migrate.js, add_migration.js,
+middleware/logger.js, migrations/{timestamp}_create_migrations_table.sql|.js
+```
+
+Session migration (`{timestamp}_create_sessions_table.sql`) generated only for SQL databases with `session=database`.
+
+Scripts added: `start` (node app.js), `dev` (nodemon app.js), `test`, `migrate` (node migrate.js), `add_migration` (node add_migration.js).
+
+Dependencies always included: `db-model-router`, `dotenv`, selected framework, database driver(s), `express-session`. DevDeps: `nodemon`.
+Conditional: `connect-redis` + `ioredis` (session=redis), `express-rate-limit`, `helmet`, `express-mung` (logger).
+
+#### Environment Variables by Database
+
+| Database    | Variables                                                                   |
+| ----------- | --------------------------------------------------------------------------- |
+| mysql       | `PORT=3000 DB_HOST DB_PORT=3306 DB_NAME DB_USER DB_PASS`                    |
+| postgres    | `PORT=3000 DB_HOST DB_PORT=5432 DB_NAME DB_USER DB_PASS`                    |
+| cockroachdb | `PORT=3000 DB_HOST DB_PORT=26257 DB_NAME DB_USER DB_PASS`                   |
+| sqlite3     | `PORT=3000 DB_NAME=./data.db`                                               |
+| mongodb     | `PORT=3000 DB_HOST DB_PORT=27017 DB_NAME DB_USER DB_PASS`                   |
+| mssql       | `PORT=3000 DB_HOST DB_PORT=1433 DB_NAME DB_USER DB_PASS`                    |
+| oracle      | `PORT=3000 DB_HOST DB_PORT=1521 DB_NAME DB_USER DB_PASS`                    |
+| redis       | `PORT=3000 DB_HOST DB_PORT=6379 DB_PASS`                                    |
+| dynamodb    | `PORT=3000 AWS_REGION AWS_ENDPOINT AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY` |
+
+When `session=redis` and database ≠ redis: adds `REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASS`.
+
+#### Migration Infrastructure
+
+- `migrate.js` — reads `migrations/` dir, diffs against `_migrations` tracking table, executes pending in order
+- `add_migration.js` — creates timestamped empty migration (`.sql` for SQL, `.js` for NoSQL)
+- Tracking table `_migrations`: `{id, filename, executed_at, checksum}` (SQL) or equivalent collection/hash/table (NoSQL)
+- Timestamp format: `YYYYMMDDHHMMSS`
 
 ### generate-model (DB introspection → model files)
 
@@ -129,15 +219,28 @@ Creates: `app.js`, `models/`, `routes/`, `middleware/logger.js`, `.env.example`,
 db-model-router-generate-model --type <db> --env .env [--output ./models] [--tables t1,t2] [--schema public]
 ```
 
-Auto-detects: PK, unique indexes, DEFAULT→optional, timestamp cols, soft-delete cols.
+Options: `--type`, `--host`, `--port`, `--database`, `--user`, `--password`, `--schema`, `--output`, `--tables`, `--env`
+
+Auto-detects: PK, unique indexes, DEFAULT→optional, timestamp cols (`created_at`, `updated_at`, `modified_at`, `createdAt`, etc.), soft-delete cols (`is_deleted`, `deleted`, `is_active`, `archived`, etc.). Multi-column unique indexes correctly grouped.
 
-### generate-route (model files → route files + OpenAPI)
+### generate-route (model files → route files + tests + OpenAPI)
 
 ```bash
 db-model-router-generate-route --models ./models --output ./routes [--tables posts,posts.comments]
 ```
 
-Dot notation `parent.child` creates nested routes: `parent/:parent_id/child` with FK scoping via `<parent_singular>_id`.
+Options: `--models`, `--output`, `--type`, `--host`, `--port`, `--database`, `--user`, `--password`, `--schema`, `--tables`, `--env`
+
+Generates:
+
+- Route files for each model
+- `index.js` mounting all routes on an Express Router
+- `openapi.json` (OpenAPI 3.0 spec)
+- Test files in `tests/` directory for all routes and methods (uses `supertest` + `assert`)
+
+Dot notation `parent.child` creates nested routes: `parent/:parent_id/child` with FK scoping via `<parent_singular>_id`. Also generates child route test files.
+
+Generated test files cover all 8 CRUD endpoints per table: GET by ID, POST add, PUT update, DELETE, list, bulk insert, bulk update, bulk delete.
 
 ## Connection Configs
 
@@ -192,7 +295,7 @@ db.connect({ region, endpoint, accessKeyId, secretAccessKey });
 ## Rules
 
 1. `init()` before `db.connect()`. Don't destructure `db` before `init()`.
-2. `modelStructure` excludes: PK col, timestamp cols, soft-delete cols.
+2. `model structure` excludes: PK col, timestamp cols, soft-delete cols.
 3. `update()`/`patch()` require PK in payload. `upsert()` PK is optional.
 4. `findOne()` returns `false` on no match. `byId()` returns `null`.
 5. Bulk ops wrap in `{ data: [...] }`. Single ops use flat object.
@@ -200,3 +303,72 @@ db.connect({ region, endpoint, accessKeyId, secretAccessKey });
 7. `safeDelete` makes `remove()` soft-delete; all reads auto-filter deleted rows.
 8. `list()` defaults: page=0, size=30. `sort` array: `["-col"]` for DESC.
 9. CommonJS only (`require`). Use dynamic `import()` for ESM.
+10. `db-model-router-init` for new projects (interactive). `generate-model` + `generate-route` for existing databases. Or use the unified `db-model-router` CLI with a `dbmr.schema.json` file.
+11. `generate-route` auto-generates test files alongside routes. Tests use `supertest`.
+
+## Schema-Driven Workflow (Unified CLI)
+
+The `db-model-router` command is the unified CLI entry point. It uses a single `dbmr.schema.json` file as the source of truth for all code generation.
+
+### LLM Workflow (schema-driven)
+
+1. **Inspect** (existing DB): `db-model-router inspect --type postgres --env .env` → writes `dbmr.schema.json`
+2. **Edit** `dbmr.schema.json` — add relationships, tweak columns, set options
+3. **Generate**: `db-model-router generate --from dbmr.schema.json` → models, routes, tests, OpenAPI
+4. **Doctor**: `db-model-router doctor --from dbmr.schema.json` → validate schema + check sync
+5. **Run**: `npm run dev`
+
+Or for new projects: `db-model-router init --from dbmr.schema.json --yes`
+
+### Subcommands
+
+| Subcommand | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| `init`     | Scaffold project (optionally from schema file via `--from`) |
+| `inspect`  | Introspect live DB → produce `dbmr.schema.json`             |
+| `generate` | Generate models/routes/tests/OpenAPI from schema            |
+| `doctor`   | Validate schema, check deps, verify files in sync           |
+| `diff`     | Preview changes regeneration would make (read-only)         |
+
+### Universal Flags
+
+All subcommands accept: `--yes`, `--json`, `--dry-run`, `--no-install`, `--help`.
+
+- `--yes`: suppress prompts, accept defaults
+- `--json`: machine-readable JSON output only
+- `--dry-run`: preview without writing files
+- `--no-install`: skip `npm install`
+
+### dbmr.schema.json Format
+
+```json
+{
+  "adapter": "postgres",
+  "framework": "express",
+  "options": {
+    "session": "redis",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true
+  },
+  "tables": {
+    "users": {
+      "columns": {
+        "name": "required|string",
+        "email": "required|string",
+        "age": "integer"
+      },
+      "pk": "id",
+      "unique": ["email"],
+      "softDelete": "is_deleted",
+      "timestamps": { "created_at": "created_at", "modified_at": "updated_at" }
+    }
+  },
+  "relationships": [
+    { "parent": "users", "child": "posts", "foreignKey": "user_id" }
+  ]
+}
+```
+
+Fields per table: `columns` (required), `pk` (default `"id"`), `unique` (default `[pk]`), `softDelete`, `timestamps`.
+Column rules: `(required|)?(string|integer|numeric|boolean|object)`.