docs: correct CLI docs drift (query JSON, install, filenames, create_database, sidebar)

apps/docs/src/content/docs/cli/generate.md

@@ -72,6 +72,8 @@ Validation errors are raised for conflicting, chained, or cyclic rename mappings
 
 With `--dryrun`, the command prints the migration plan (operations with risk levels and SQL) without writing any files. Useful for previewing changes before committing.
 
+Plans for objects in a database lead with a `create_database` operation (`CREATE DATABASE IF NOT EXISTS`, risk `safe`), so a single new table reports `operationCount: 2` — the `create_database` plus the `create_table`. The `CREATE DATABASE` is idempotent and a no-op if the database already exists.
+
 ### Codegen integration
 
 If the codegen plugin is configured with `runOnGenerate: true` (the default), `chkit generate` automatically runs codegen after writing migration artifacts. A codegen failure causes `generate` to fail.
@@ -130,8 +132,9 @@ chkit generate --rename-column analytics.events.old_name=new_name
   "scope": { "enabled": false },
   "mode": "plan",
   "operationCount": 2,
-  "riskSummary": { "safe": 1, "caution": 1, "danger": 0 },
+  "riskSummary": { "safe": 2, "caution": 0, "danger": 0 },
   "operations": [
+    { "type": "create_database", "key": "database:default", "risk": "safe", "sql": "CREATE DATABASE IF NOT EXISTS default;" },
     { "type": "create_table", "key": "default.users", "risk": "safe", "sql": "CREATE TABLE ..." }
   ],
   "renameSuggestions": []
@@ -145,11 +148,11 @@ chkit generate --rename-column analytics.events.old_name=new_name
   "command": "generate",
   "schemaVersion": 1,
   "scope": { "enabled": false },
-  "migrationFile": "./chkit/migrations/0001_add_users_table.sql",
+  "migrationFile": "./chkit/migrations/20260604104251_add_users_table.sql",
   "snapshotFile": "./chkit/meta/snapshot.json",
   "definitionCount": 3,
   "operationCount": 2,
-  "riskSummary": { "safe": 1, "caution": 1, "danger": 0 }
+  "riskSummary": { "safe": 2, "caution": 0, "danger": 0 }
 }
 ```
 

apps/docs/src/content/docs/cli/migrate.md

@@ -123,7 +123,7 @@ chkit migrate --apply --table analytics.events
   "schemaVersion": 1,
   "mode": "plan",
   "scope": { "enabled": false },
-  "pending": ["0004_add_column.sql", "0005_create_index.sql"]
+  "pending": ["20260604104251_add_column.sql", "20260604105133_create_index.sql"]
 }
 ```
 
@@ -136,7 +136,7 @@ chkit migrate --apply --table analytics.events
   "mode": "execute",
   "scope": { "enabled": false },
   "applied": [
-    { "name": "0004_add_column.sql", "appliedAt": "2025-06-15T10:30:00.000Z", "checksum": "a1b2c3..." }
+    { "name": "20260604104251_add_column.sql", "appliedAt": "2025-06-15T10:30:00.000Z", "checksum": "a1b2c3..." }
   ]
 }
 ```
@@ -151,7 +151,7 @@ chkit migrate --apply --table analytics.events
   "scope": { "enabled": false },
   "error": "Checksum mismatch detected on applied migrations",
   "checksumMismatches": [
-    { "name": "0002_init.sql", "expected": "abc123...", "actual": "def456..." }
+    { "name": "20260604090000_init.sql", "expected": "abc123...", "actual": "def456..." }
   ]
 }
 ```
@@ -165,10 +165,10 @@ chkit migrate --apply --table analytics.events
   "mode": "execute",
   "scope": { "enabled": false },
   "error": "Blocked destructive migration execution. Re-run with --allow-destructive or set safety.allowDestructive=true after review.",
-  "destructiveMigrations": ["0005_drop_old_table.sql"],
+  "destructiveMigrations": ["20260605112000_drop_old_table.sql"],
   "destructiveOperations": [
     {
-      "migration": "0005_drop_old_table.sql",
+      "migration": "20260605112000_drop_old_table.sql",
       "type": "drop_table",
       "key": "default.old_table",
       "risk": "danger",

apps/docs/src/content/docs/cli/plugin.md

@@ -2,7 +2,7 @@
 title: "chkit plugin"
 description: "List installed plugins or run plugin commands."
 sidebar:
-  order: 10
+  order: 11
 ---
 
 Lists registered plugins, lists a plugin's commands, or runs a specific plugin command.

apps/docs/src/content/docs/cli/query.md

@@ -2,7 +2,7 @@
 title: "chkit query"
 description: "Run a SQL query against the configured ClickHouse target."
 sidebar:
-  order: 9
+  order: 10
 ---
 
 Executes an ad-hoc SQL query against the configured target and prints the result.
@@ -67,17 +67,33 @@ chkit query "SELECT count() FROM users" --json
 
 ## JSON output
 
+`--json` prints the raw ClickHouse result envelope (the `JSON` format), not a chkit-specific wrapper:
+
 ```json
 {
-  "command": "query",
-  "schemaVersion": 1,
-  "rowCount": 1,
-  "rows": [
+  "meta": [
+    { "name": "count()", "type": "UInt64" }
+  ],
+  "data": [
     { "count()": "42" }
-  ]
+  ],
+  "rows": 1,
+  "statistics": {
+    "elapsed": 0.000773,
+    "rows_read": 1,
+    "bytes_read": 1
+  }
 }
 ```
 
+- `meta` — column names and ClickHouse types.
+- `data` — the result rows.
+- `rows` — the row **count** (a number), not the rows array.
+- `statistics` — server-side timing and read counters.
+- `query_id` — present when the executor reports it.
+
+There is no `rowCount`, `command`, or `schemaVersion` field; the row count lives in `rows`.
+
 ## Related commands
 
 - [`chkit status`](/cli/status/) — show migration state

apps/docs/src/content/docs/cli/status.md

@@ -60,7 +60,7 @@ chkit status --json
   "total": 5,
   "applied": 3,
   "pending": 2,
-  "pendingMigrations": ["0004_add_column.sql", "0005_create_index.sql"],
+  "pendingMigrations": ["20260604104251_add_column.sql", "20260604105133_create_index.sql"],
   "checksumMismatchCount": 0,
   "checksumMismatches": []
 }

packages/cli/README.md

@@ -19,9 +19,11 @@ Define your ClickHouse schema in TypeScript, generate migrations automatically,
 ## Install
 
 ```bash
-bun add -d chkit
+bun add -d chkit @chkit/core
 ```
 
+`@chkit/core` provides the `table()` / schema DSL your `*.schema.ts` files import, so it is required alongside the CLI.
+
 ## Usage
 
 ```bash