@carllee1983/dbcli 1.39.2 → 1.41.0

package/dist/core.d.ts

@@ -86,6 +86,8 @@ export interface ColumnSchema {
 export interface TableSchema {
 	/** Table name */
 	name: string;
+	/** Exact database schema/catalog namespace, when reliably available */
+	schema?: string;
 	/** Array of columns in the table */
 	columns: ColumnSchema[];
 	/** Approximate row count (if available) */
@@ -98,6 +100,7 @@ export interface TableSchema {
 	foreignKeys?: Array<{
 		name: string;
 		columns: string[];
+		refSchema?: string;
 		refTable: string;
 		refColumns: string[];
 	}>;

package/dist/core.mjs

@@ -13434,6 +13434,7 @@ var COMMAND_CAPABILITY_KEYS = Object.freeze([
   "schemaSingle",
   "schemaFullScan",
   "query",
+  "lint",
   "queryOutput",
   "queryLimitGuard",
   "q",
@@ -13482,6 +13483,7 @@ var SQL_BASE = {
   schemaSingle: cap("supported", "readonly", "Reads a single table schema."),
   schemaFullScan: cap("supported", "readonly", "Full scan, refresh, and reset are supported."),
   query: cap("supported", "readonly", "Runs SQL through permission and blacklist guards."),
+  lint: cap("supported", "readonly", "Statically analyzes SQL without connecting to the database."),
   queryOutput: cap("supported", "readonly", "table/json/csv output is supported."),
   queryLimitGuard: cap("supported", "readonly", "Query-only auto-limit and size guard are supported."),
   q: cap("supported", "readonly", "Saved SQL snippets allow SELECT/WITH only."),
@@ -13511,6 +13513,7 @@ var ENGINE_CAPABILITIES = Object.freeze({
   mariadb: Object.freeze(SQL_BASE),
   mongodb: Object.freeze({
     ...SQL_BASE,
+    lint: cap("unsupported", "none", "Static lint accepts SQL connections only."),
     schemaSingle: cap("limited", "readonly", "MongoDB schema is sampled from documents."),
     schemaFullScan: cap("limited", "readonly", "Full scan is sampled and document-oriented."),
     query: cap("limited", "readonly", "Uses JSON filter or aggregation syntax, not SQL."),
@@ -13529,6 +13532,7 @@ var ENGINE_CAPABILITIES = Object.freeze({
   }),
   redis: Object.freeze({
     ...SQL_BASE,
+    lint: cap("unsupported", "none", "Static lint accepts SQL connections only."),
     schemaSingle: cap("limited", "readonly", "Per-key synthetic schema only."),
     schemaFullScan: cap("unsupported", "none", "Redis has no full schema cache scan."),
     query: cap("limited", "readonly", "Runs allow-listed Redis commands."),
@@ -13547,6 +13551,7 @@ var ENGINE_CAPABILITIES = Object.freeze({
   }),
   elasticsearch: Object.freeze({
     ...SQL_BASE,
+    lint: cap("unsupported", "none", "Static lint accepts SQL connections only."),
     schemaSingle: cap("limited", "readonly", "Schema flattens index mappings."),
     schemaFullScan: cap("supported", "readonly", "Full scan iterates non-system indices."),
     query: cap("limited", "readonly", "Uses JSON DSL or Lucene query strings with an index."),
@@ -14437,6 +14442,10 @@ function fixDoubleEncodedUtf8(str) {
 }
 
 // src/adapters/postgresql-adapter.ts
+function quoteIdentifier(identifier) {
+  return `"${identifier.replaceAll('"', '""')}"`;
+}
+
 class PostgreSQLAdapter {
   pool = null;
   client = null;
@@ -14522,6 +14531,7 @@ class PostgreSQLAdapter {
     try {
       const query = `
         SELECT
+          n.nspname as schema_name,
           c.relname as table_name,
           c.reltuples::bigint as estimated_rows,
           CASE c.relkind
@@ -14541,6 +14551,7 @@ class PostgreSQLAdapter {
       const result = await this.execute(query);
       return result.rows.map((row) => ({
         name: row.table_name,
+        schema: row.schema_name,
         columns: [],
         columnCount: row.column_count,
         rowCount: Math.max(0, row.estimated_rows || 0),
@@ -14569,9 +14580,15 @@ class PostgreSQLAdapter {
             SELECT EXISTS(
               SELECT 1 FROM information_schema.table_constraints tc
               JOIN information_schema.key_column_usage kcu
-                ON tc.constraint_name = kcu.constraint_name
-              WHERE tc.table_name = $1
-                AND tc.table_schema = 'public'
+                ON tc.constraint_catalog = kcu.constraint_catalog
+                AND tc.constraint_schema = kcu.constraint_schema
+                AND tc.constraint_name = kcu.constraint_name
+              WHERE tc.table_catalog = c.table_catalog
+                AND tc.table_schema = c.table_schema
+                AND tc.table_name = c.table_name
+                AND kcu.table_catalog = c.table_catalog
+                AND kcu.table_schema = c.table_schema
+                AND kcu.table_name = c.table_name
                 AND tc.constraint_type = 'PRIMARY KEY'
                 AND kcu.column_name = c.column_name
             )
@@ -14594,8 +14611,12 @@ class PostgreSQLAdapter {
           c.column_name as name,
           array_agg(e.enumlabel ORDER BY e.enumsortorder) as enum_values
         FROM information_schema.columns c
-        JOIN pg_type t ON t.typname = c.udt_name
-        JOIN pg_enum e ON e.enumtypid = t.oid
+        JOIN pg_catalog.pg_type AS enum_type
+          ON enum_type.typname = c.udt_name
+        JOIN pg_catalog.pg_namespace AS enum_schema
+          ON enum_schema.oid = enum_type.typnamespace
+          AND enum_schema.nspname = c.udt_schema
+        JOIN pg_catalog.pg_enum AS e ON e.enumtypid = enum_type.oid
         WHERE c.table_name = $1
           AND c.table_schema = 'public'
         GROUP BY c.column_name
@@ -14608,17 +14629,40 @@ class PostgreSQLAdapter {
       }
       const fkQuery = `
         SELECT
-          tc.constraint_name as name,
-          array_agg(kcu.column_name) as columns,
-          ccu.table_name as ref_table,
-          array_agg(ccu.column_name) as ref_columns
-        FROM information_schema.table_constraints AS tc
-        JOIN information_schema.key_column_usage AS kcu
-          ON tc.table_name = kcu.table_name AND tc.constraint_name = kcu.constraint_name
-        JOIN information_schema.constraint_column_usage AS ccu
-          ON ccu.constraint_name = tc.constraint_name
-        WHERE tc.table_name = $1 AND tc.constraint_type = 'FOREIGN KEY'
-        GROUP BY tc.constraint_name, ccu.table_name
+          constraint_info.conname as name,
+          array_agg(source_column.attname ORDER BY source_key.ordinality) as columns,
+          referenced_schema.nspname as ref_schema,
+          referenced_table.relname as ref_table,
+          array_agg(referenced_column.attname ORDER BY source_key.ordinality) as ref_columns
+        FROM pg_catalog.pg_constraint AS constraint_info
+        JOIN pg_catalog.pg_class AS source_table
+          ON source_table.oid = constraint_info.conrelid
+        JOIN pg_catalog.pg_namespace AS source_schema
+          ON source_schema.oid = source_table.relnamespace
+        JOIN pg_catalog.pg_class AS referenced_table
+          ON referenced_table.oid = constraint_info.confrelid
+        JOIN pg_catalog.pg_namespace AS referenced_schema
+          ON referenced_schema.oid = referenced_table.relnamespace
+        JOIN LATERAL unnest(constraint_info.conkey) WITH ORDINALITY
+          AS source_key(attnum, ordinality) ON TRUE
+        JOIN LATERAL unnest(constraint_info.confkey) WITH ORDINALITY
+          AS referenced_key(attnum, ordinality)
+          ON referenced_key.ordinality = source_key.ordinality
+        JOIN pg_catalog.pg_attribute AS source_column
+          ON source_column.attrelid = constraint_info.conrelid
+          AND source_column.attnum = source_key.attnum
+        JOIN pg_catalog.pg_attribute AS referenced_column
+          ON referenced_column.attrelid = constraint_info.confrelid
+          AND referenced_column.attnum = referenced_key.attnum
+        WHERE constraint_info.contype = 'f'
+          AND source_table.relname = $1
+          AND source_schema.nspname = 'public'
+        GROUP BY
+          constraint_info.oid,
+          constraint_info.conname,
+          referenced_schema.nspname,
+          referenced_table.relname
+        ORDER BY constraint_info.oid
       `;
       const fkResult = await this.execute(fkQuery, [tableName]);
       const fkResults = fkResult.rows;
@@ -14646,36 +14690,49 @@ class PostgreSQLAdapter {
       const indexResult = await this.execute(indexQuery, [tableName]);
       const indexResults = indexResult.rows;
       const estimateQuery = `
-        SELECT reltuples::bigint as estimated_rows
-        FROM pg_class
-        WHERE relname = $1
+        SELECT source_table.reltuples::bigint as estimated_rows
+        FROM pg_catalog.pg_class AS source_table
+        JOIN pg_catalog.pg_namespace AS source_schema
+          ON source_schema.oid = source_table.relnamespace
+        WHERE source_table.relname = $1
+          AND source_schema.nspname = 'public'
       `;
       const estimateResult = await this.execute(estimateQuery, [
         tableName
       ]);
       const estimateResults = estimateResult.rows;
       const pkQuery = `
-        SELECT array_agg(a.attname) as columns
-        FROM (
-          SELECT a.attname
-          FROM pg_index i
-          JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
-          WHERE i.indisprimary AND i.indrelid = $1::regclass
-          ORDER BY a.attnum
-        ) a
+        SELECT
+          array_agg(primary_key_column.attname ORDER BY primary_key.ordinality) as columns
+        FROM pg_catalog.pg_index AS index_info
+        JOIN pg_catalog.pg_class AS source_table
+          ON source_table.oid = index_info.indrelid
+        JOIN pg_catalog.pg_namespace AS source_schema
+          ON source_schema.oid = source_table.relnamespace
+        JOIN LATERAL unnest(index_info.indkey) WITH ORDINALITY
+          AS primary_key(attnum, ordinality) ON TRUE
+        JOIN pg_catalog.pg_attribute AS primary_key_column
+          ON primary_key_column.attrelid = source_table.oid
+          AND primary_key_column.attnum = primary_key.attnum
+        WHERE index_info.indisprimary
+          AND source_table.relname = $1
+          AND source_schema.nspname = 'public'
       `;
       const pkResult = await this.execute(pkQuery, [tableName]);
       const pkResults = pkResult.rows;
-      const countResult = await this.execute(`SELECT COUNT(*) as count FROM "${tableName}"`);
+      const qualifiedTableName = `${quoteIdentifier("public")}.${quoteIdentifier(tableName)}`;
+      const countResult = await this.execute(`SELECT COUNT(*) as count FROM ${qualifiedTableName}`);
       const primaryKeyArray = Array.isArray(pkResults[0]?.columns) ? pkResults[0].columns : [];
       const safeForeignKeys = fkResults.map((fk) => ({
         name: fk.name,
         columns: Array.isArray(fk.columns) ? fk.columns : [],
+        refSchema: fk.ref_schema,
         refTable: fk.ref_table,
         refColumns: Array.isArray(fk.ref_columns) ? fk.ref_columns : []
       }));
       const schema = {
         name: tableName,
+        schema: "public",
         columns: columns.map((col) => ({
           name: col.name,
           type: col.type,
@@ -21757,7 +21814,7 @@ function parseEnvPassword(content) {
   return match?.[1] != null ? match[1].trim() : null;
 }
 var configModule = {
-  async read(path, connectionName) {
+  async read(path, connectionName, options = {}) {
     const effectiveConnectionName = connectionName ?? _globalConnectionName;
     try {
       const binding = await readProjectBinding(path);
@@ -21801,23 +21858,27 @@ var configModule = {
               resolvedConnection.password = legacyPassword;
             }
             let schema = (v2Config.schemas ?? {})[resolved.name] ?? v2Config.schema;
-            try {
-              const { SchemaLayeredLoader: SchemaLayeredLoader2 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
-              const loader = new SchemaLayeredLoader2(storagePath, { connectionName: resolved.name });
-              const { cache, index } = await loader.initialize();
-              if (index && Object.keys(index.tables).length > 0) {
-                const layeredSchema = {};
-                for (const tableName of Object.keys(index.tables)) {
-                  const s = await cache.getTableSchema(tableName);
-                  if (s)
-                    layeredSchema[tableName] = s;
-                }
-                if (Object.keys(layeredSchema).length > 0) {
-                  schema = layeredSchema;
+            if (options.loadLayeredSchema !== false) {
+              try {
+                const { SchemaLayeredLoader: SchemaLayeredLoader2 } = await Promise.resolve().then(() => (init_schema_loader(), exports_schema_loader));
+                const loader = new SchemaLayeredLoader2(storagePath, {
+                  connectionName: resolved.name
+                });
+                const { cache, index } = await loader.initialize();
+                if (index && Object.keys(index.tables).length > 0) {
+                  const layeredSchema = {};
+                  for (const tableName of Object.keys(index.tables)) {
+                    const s = await cache.getTableSchema(tableName);
+                    if (s)
+                      layeredSchema[tableName] = s;
+                  }
+                  if (Object.keys(layeredSchema).length > 0) {
+                    schema = layeredSchema;
+                  }
                 }
+              } catch {
+                console.warn("Warning: Failed to load layered schema cache, falling back to config.json");
               }
-            } catch {
-              console.warn("Warning: Failed to load layered schema cache, falling back to config.json");
             }
             return DbcliConfigSchema.parse({
               connection: resolvedConnection,
@@ -21943,7 +22004,7 @@ DBCLI_PASSWORD=${password}
 };
 
 // src/utils/redaction.ts
-var SQL_SUBCOMMANDS = new Set(["query", "export"]);
+var SQL_SUBCOMMANDS = new Set(["query", "export", "lint"]);
 var REDACTED_VALUE_FLAGS = new Set([
   "--where",
   "--set",
@@ -21954,21 +22015,101 @@ var REDACTED_VALUE_FLAGS = new Set([
   "--use",
   "--password",
   "--token",
-  "--secret"
+  "--secret",
+  "--bulk"
+]);
+var KEEP_VALUE_FLAGS = new Set([
+  "--format",
+  "--conn-name",
+  "--min-severity",
+  "--output",
+  "--limit",
+  "--collection",
+  "--index"
 ]);
-var KEEP_VALUE_FLAGS = new Set(["--format", "--conn-name"]);
+var LINT_BOOLEAN_FLAGS = new Set(["--no-schema", "--recovery"]);
+function optionParts(token) {
+  const equals = token.indexOf("=");
+  return equals === -1 ? { name: token, inlineValue: undefined } : { name: token.slice(0, equals), inlineValue: token.slice(equals + 1) };
+}
+function findSensitiveSubcommand(argv) {
+  for (let index = 1;index < argv.length; index++) {
+    const token = argv[index];
+    if (token.startsWith("--")) {
+      const { name, inlineValue } = optionParts(token);
+      if (inlineValue === undefined && (REDACTED_VALUE_FLAGS.has(name) || KEEP_VALUE_FLAGS.has(name))) {
+        index++;
+      }
+      continue;
+    }
+    if (SQL_SUBCOMMANDS.has(token))
+      return { index, command: token };
+  }
+  return null;
+}
+function sensitiveArgvValues(argv) {
+  const sensitiveCommand = findSensitiveSubcommand(argv);
+  const values = new Set;
+  let capturedSingleSql = false;
+  let afterEndOfOptions = false;
+  for (let index = 0;index < argv.length; index++) {
+    const token = argv[index];
+    if (!afterEndOfOptions && token === "--") {
+      afterEndOfOptions = true;
+      continue;
+    }
+    if (!afterEndOfOptions && token.startsWith("--")) {
+      const { name, inlineValue } = optionParts(token);
+      if (REDACTED_VALUE_FLAGS.has(name)) {
+        const value = inlineValue ?? argv[index + 1];
+        if (value) {
+          values.add(value);
+          if (name === "--bulk") {
+            for (const item of value.split(",")) {
+              values.add(item);
+              if (item.startsWith("@") && item.length > 1) {
+                values.add(item.slice(1));
+              }
+            }
+          }
+        }
+        if (inlineValue === undefined)
+          index++;
+      } else if (inlineValue === undefined && KEEP_VALUE_FLAGS.has(name)) {
+        index++;
+      } else if (sensitiveCommand?.command === "lint" && LINT_BOOLEAN_FLAGS.has(name)) {
+        continue;
+      } else if (!sensitiveCommand || index < sensitiveCommand.index) {
+        continue;
+      } else {
+        values.add(token);
+        capturedSingleSql = true;
+      }
+      continue;
+    }
+    if (sensitiveCommand && index > sensitiveCommand.index && (sensitiveCommand.command === "lint" || !capturedSingleSql)) {
+      values.add(token);
+      capturedSingleSql = true;
+    }
+  }
+  return Array.from(values).sort((left, right) => right.length - left.length);
+}
 function redactArgv(argv) {
   if (argv.length === 0)
     return "<unknown>";
-  const out = [argv[0]];
-  if (argv.length === 1)
-    return out.join(" ");
-  const sub = argv[1];
-  out.push(sub);
-  for (let i = 2;i < argv.length; i++) {
+  const sensitiveCommand = findSensitiveSubcommand(argv);
+  const out = [];
+  let redactedSingleSql = false;
+  let afterEndOfOptions = false;
+  for (let i = 0;i < argv.length; i++) {
     const tok = argv[i];
-    if (tok.startsWith("--")) {
-      const [name, inlineValue] = tok.split("=");
+    if (!afterEndOfOptions && tok === "--") {
+      out.push(tok);
+      afterEndOfOptions = true;
+      continue;
+    }
+    if (!afterEndOfOptions && tok.startsWith("--")) {
+      const { name, inlineValue } = optionParts(tok);
       if (REDACTED_VALUE_FLAGS.has(name)) {
         out.push(`${name} <redacted>`);
         if (inlineValue === undefined)
@@ -21980,23 +22121,37 @@ function redactArgv(argv) {
           out.push(tok);
         } else {
           out.push(name);
-          if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+          if (i + 1 < argv.length) {
             out.push(argv[++i]);
           }
         }
         continue;
       }
-      out.push(tok);
-      continue;
+      if (sensitiveCommand?.command === "lint" && LINT_BOOLEAN_FLAGS.has(name)) {
+        out.push(tok);
+        continue;
+      }
+      if (!sensitiveCommand || i < sensitiveCommand.index) {
+        out.push(tok);
+        continue;
+      }
     }
-    if (i === 2 && SQL_SUBCOMMANDS.has(sub)) {
+    if (sensitiveCommand && i > sensitiveCommand.index && (sensitiveCommand.command === "lint" || !redactedSingleSql)) {
       out.push("<sql>");
+      redactedSingleSql = true;
       continue;
     }
     out.push(tok);
   }
   return out.join(" ");
 }
+function redactArgvSensitiveText(text, argv) {
+  let redacted = text;
+  for (const value of sensitiveArgvValues(argv)) {
+    redacted = redacted.split(value).join("<redacted>");
+  }
+  return redacted;
+}
 function redactSensitive(text) {
   return text.replace(/\b(password|token|apiKey|secret|key|token|auth|credential|pass|pwd|sid)([:=]|\s+)([^\s"';,]+)/gi, "$1$2<redacted>");
 }
@@ -22042,6 +22197,7 @@ async function writeAuditEntry(config, commandName, options, outcome) {
     if (outcome.error) {
       errorMessage = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
       errorMessage = redactSensitive(errorMessage);
+      errorMessage = redactArgvSensitiveText(errorMessage, process.argv);
     }
     const entry = {
       engine,

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.37.1",
+  "version": "1.41.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.39.2",
+  "version": "1.41.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {

package/plugins/dbcli-agent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "1.39.2",
+  "version": "1.41.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/plugins/dbcli-agent/INSTALL.md

@@ -78,8 +78,13 @@ used by Gemini/Antigravity-style agents.
 
 ## Cursor
 
-Cursor can install plugins from Cursor Agent chat when the plugin is available
-in Cursor's plugin marketplace:
+> **Current status: manual install.** `dbcli-agent` is not yet indexed in
+> Cursor's plugin marketplace, so `/add-plugin dbcli-agent` in Cursor Agent chat
+> will not find it. Use one of the manual fallbacks below. The `/add-plugin`
+> command only works once the plugin has been indexed (see the submission steps
+> that follow).
+
+Once the plugin is indexed, Cursor can install it from Cursor Agent chat:
 
 ```text
 /add-plugin dbcli-agent
@@ -93,18 +98,22 @@ This repository includes Cursor plugin metadata at:
 .cursor-plugin/plugin.json
 ```
 
-For Cursor marketplace review/indexing:
+To get `/add-plugin` working, submit the repo for Cursor marketplace
+review/indexing:
 
 1. Push this repository to GitHub and keep it public.
 2. Keep the single-plugin layout at the repository root:
    `.cursor-plugin/plugin.json` plus `skills/dbcli/`.
-3. Confirm the manifest name is lowercase kebab-case (`dbcli-agent`) and that
-   `category`, `tags`, `homepage`, `repository`, and `skills` are present.
-4. Submit the repository URL to the Cursor plugin team for review/indexing.
-   The Cursor plugin template currently points submitters to the Cursor
-   community Slack or `kniparko@anysphere.com`.
-5. After indexing, users can install from Cursor Agent chat with
-   `/add-plugin dbcli-agent` or by searching the Cursor plugin marketplace.
+3. Confirm the manifest name is lowercase kebab-case (`dbcli-agent`), the skill
+   files carry YAML frontmatter, `README.md` exists at the repo root, and all
+   manifest paths are relative with no `..` or absolute paths.
+4. Submit the repository at <https://cursor.com/marketplace/publish>. This is the
+   current channel — the marketplace launched with Cursor 2.5 (2026-02-17) and
+   every plugin is manually reviewed and must be open source. Do **not** email
+   `kniparko@anysphere.com`; that address came from an older plugin template and
+   is not the submission path.
+5. After the plugin is reviewed and listed, users can install from Cursor Agent
+   chat with `/add-plugin dbcli-agent` or by searching the Cursor marketplace.
 
 The repo also keeps an instruction-file fallback for projects that want to
 vendor the dbcli rule and reference directly.

package/plugins/dbcli-agent/skills/dbcli/SKILL.md

@@ -45,7 +45,7 @@ takes a full JSON filter and is exempt.)
 
 Slow-query diagnosis has three canonical paths (pick by what you already know):
 
-- Known slow SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `guide missing-index-for "<SQL>"`
+- Known slow SQL → `skill tasks plan diagnose-slow-query --param query="<SQL>"` → `lint "<SQL>"` → `guide missing-index-for "<SQL>"`
 - Known hot table → `skill tasks plan analyze-table-perf --param table=<table>`
 - Whole-environment scan → `report --section perf` → `guide slow-query`
 
@@ -54,7 +54,7 @@ afterwards add only the `@diag/*` it does not cover (`missing-indexes`, `locks`,
 `table-sizes`). Once you have a specific slow statement, `explain --analyze "<SQL>"` shows its plan.
 
 **On failure:** pass `--recovery` to `query` / `q` / `insert` / `update` / `delete` /
-`export` / `schema` / `inspect`. The command emits a `RecoveryEnvelope` to stdout and saves
+`export` / `schema` / `inspect` / `lint` / `diff --against-orm`. The command emits a `RecoveryEnvelope` to stdout and saves
 it to `.dbcli/last-recovery.json`; then `dbcli recover` inspects it and `dbcli recover --apply`
 runs the saved plan under risk gating. Multi-turn `--next`, connection branching, and the
 post-apply verify probe are documented in reference.md §Recovery Cookbook.
@@ -81,12 +81,16 @@ The plan is an ordered list of dbcli commands with rationale and risk labels. Ex
 one at a time — task plans do **not** override blacklist, schema, dry-run, or confirmation
 requirements.
 
-Builtin packs: `diagnose-slow-query` (targets a specific SQL), `analyze-table-perf` (targets
-a specific table; `dbcli inspect` auto-suggests it for the hottest table in recent audit
-activity), `audit-permissions`, `safe-backfill`, `schema-drift-review`, `connection-health`.
-Review/verify packs: `pr-database-review`, `migration-review`, `safe-backfill-verify`,
-`slow-endpoint-investigation`. All are read-only `plan-only` — pick the pack matching the
-situation, and run any index/DDL proposal through `migration-review` before writing.
+Builtin packs (SQL — postgres/mysql): `diagnose-slow-query` (targets a specific SQL),
+`analyze-table-perf` (targets a specific table; `dbcli inspect` auto-suggests it for the
+hottest table in recent audit activity), `audit-permissions`, `safe-backfill`,
+`schema-drift-review`, `orm-drift-review` (ORM definition vs cached DB schema),
+`connection-health`. Review/verify packs: `pr-database-review`,
+`migration-review`, `safe-backfill-verify`, `slow-endpoint-investigation`. MongoDB packs:
+`mongo-safe-backfill` (dry-run–previewed backfill), `mongo-schema-drift-review` (sampled
+dot-path drift). All are read-only `plan-only` — pick the pack matching the situation, and
+run any index/DDL proposal through `migration-review` before writing. Redis/Elasticsearch
+have no packs yet — lead with `guide` / `report` there.
 
 Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
 `.dbcli/tasks/` (local override).
@@ -101,9 +105,9 @@ in **How to use dbcli** still applies.
 | DB-backed feature | `blacklist list` → `schema <object>` → `queries suggest <intent>` |
 | DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
-| ORM or migration work | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column` (preview SQL) → `diff --against <snapshot>` |
+| ORM or migration work | `schema --format json` → `diff --against-orm <orm-schema>` → review error-level drift → proposals via `migrate` (dry-run) → `migration-review` task pack → `diff --against <snapshot>` after applying. |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
-| Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
+| Slow endpoint or query | `report --section perf` → task pack `analyze-table-perf` → `lint "<query>"` → `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
 | Safe data backfill | `blacklist list` → `schema <object>` → count/scope query → `update … --dry-run` → read-back or snippet `--verify`. |
 | Environment validation | `status --format json` → `doctor --format json` → `inspect --for-agent --no-connect`. |
 
@@ -121,9 +125,13 @@ dbcli q @<name> --param k=v --format html > report.html
 dbcli export "<SQL>" --format html --output report.html
 dbcli audit tail --for-agent --n 10
 dbcli diff --snapshot <name>
+dbcli diff --against-orm prisma/schema.prisma --format json
+dbcli diff --against-orm "migrations/*.sql" --format markdown
+dbcli skill tasks plan orm-drift-review --param orm_path=prisma/schema.prisma --format json
 dbcli report --section perf --format json
 dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
 dbcli guide missing-index-for "<query>" --format json
+dbcli lint "<SQL>" --format json
 dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
 dbcli inspect --for-agent --no-connect --format json
 ```
@@ -290,6 +298,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
 | `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. Supports `--recovery`. |
 | `explain` | query-only+ | **(v1.23)** Read-only query plan with annotations. SQL only. Single query, `@saved-query`, `@file.sql`, or `--bulk @glob/*`. `--analyze` (EXPLAIN ANALYZE / MariaDB ANALYZE SELECT), `--format markdown\|json\|table`. |
+| `lint` | n/a | Static SQL anti-pattern advisor (no DB connection). 9 rules incl. schema-aware implicit-cast / NOT IN-nullable checks via the layered `.dbcli/schemas/` cache; global `--use <conn>` selects a named cache. Findings carry rewrite drafts + guarded `explain` verify commands (`--analyze` only for proven read-only SQL) — report-only, never executes. `--format text\|json\|markdown`, `--min-severity`, `--no-schema`, `--bulk`. Supports `--recovery`. |
 | `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
 | `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. Supports `--verify` to run assertions. |
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
@@ -298,7 +307,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `export` | query-only+ | SQL, MongoDB, or **(v1.22)** Elasticsearch (DSL `--index` or whole-index scroll). Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
-| `diff` | query-only+ | SQL only. Save/compare schema snapshots. |
+| `diff` | query-only+ | SQL only. Save/compare schema snapshots. **(P1b)** `--against-orm <path>` compares a Prisma schema / DDL file / normalized JSON against the local schema cache (no DB connection): categorized drift (`missing_in_db` = error, `missing_in_orm` = warn, `mismatch` per tolerance table, `unmanaged`) with dry-run `migrate` proposals; exit 1 on error-level drift. `--orm-format prisma\|ddl\|json`, `--ignore <globs>`, `--format json\|table\|markdown`. |
 | `snapshot` | query-only+ | **(v1.25)** SQL only. Capture a result fingerprint (`rowCount` + per-column null/distinct/min/max/sum + order-independent checksum). `--out` (default `.dbcli/snapshots/snap-<ts>.json`), `--rows`, `--stdout`, `--format`, `--no-limit`. Baseline for `assert --against`. |
 | `assert` | query-only+ | **(v1.25)** SQL only. Verify an invariant; exit 1 on failure unless `--no-fail`. `--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`, `--vs <query> --compare rows\|value` (reconcile), `--against <snapshot> --tolerance <pct>`. |
 | `verification` | n/a | Inspect and manage local verification artifacts. `list` / `show <id-or-path>` / `summary` are read-only; `prune` is dry-run by default and deletes only with `--execute --force`. Reads `<cwd>/.dbcli/verification/`; no DB connection, no audit writes. |
@@ -318,7 +327,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 
 `--use <name>` on any subcommand (including `status` / `doctor`) targets a v2 connection
 without changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `update`,
-`delete`, `export`, `schema`, and `inspect` (see **On failure** above).
+`delete`, `export`, `schema`, `inspect`, `lint`, and `diff --against-orm` (see **On failure** above).
 
 **Write & query flag semantics** (SQL/Mongo `insert`/`update`):