@carllee1983/dbcli 1.19.1 → 1.20.1

package/dist/cli.mjs

@@ -2161,6 +2161,38 @@ var init_messages = __esm(() => {
       snippet_not_found: "Snippet not found: {name}",
       dry_run_header: "Dry-run preview (no execution):"
     },
+    audit: {
+      description: "Inspect, look up, clear, or check the health of the audit log",
+      tail: {
+        description: "Show recent audit entries (default: last 10 from current connection)"
+      },
+      show: {
+        description: "Look up a single audit entry by id (UUID prefix >=4) or --recovery-ref"
+      },
+      clear: {
+        description: "Delete audit log files (.jsonl + .jsonl.1) for the current connection",
+        prompt_header: "About to clear audit log for connection '{conn}':",
+        prompt_file_line: "  {file}       \u2014 {entries} entries, {size}",
+        prompt_continue: "Continue? [y/N] ",
+        requires_tty_or_yes: "Cannot prompt for confirmation in non-interactive session. Use --yes to clear without prompt.",
+        summary_cleared: "Cleared {count} entries from '{conn}'.",
+        summary_nothing: "Nothing to clear.",
+        summary_failed: "Failed to clear: {message}."
+      },
+      health: {
+        description: "Show AuditLogger health snapshot (size, entries, lock state, last write)"
+      },
+      disabled_hint: "Audit is disabled (audit.enabled = false in .dbcli). Use 'dbcli audit health' for details.",
+      no_entries: "No audit entries.",
+      show_no_match: "No audit entry matches '{prefix}'.",
+      show_ambiguous: "Ambiguous prefix '{prefix}': matches {count} entries. Please use a longer prefix.",
+      show_prefix_too_short: "Prefix must be at least 4 characters.",
+      show_recovery_no_match: "No audit entry has recovery_ref '{ref}'.",
+      show_recovery_ambiguous: "Multiple entries reference recovery_ref '{ref}': matches {count}. This should be rare; inspect file directly.",
+      show_mutex_violation: "Provide either <id> argument or --recovery-ref, not both.",
+      n_capped_warning: "--n value {requested} exceeds max {max}; capped to {max}.",
+      n_must_be_positive: "--n must be a positive integer."
+    },
     queries: {
       description: "Manage saved query snippets",
       list_description: "List saved snippets",
@@ -2411,6 +2443,38 @@ var init_messages2 = __esm(() => {
       snippet_not_found: "\u627E\u4E0D\u5230\u7247\u6BB5\uFF1A{name}",
       dry_run_header: "Dry-run \u9810\u89BD\uFF08\u4E0D\u6703\u57F7\u884C\uFF09\uFF1A"
     },
+    audit: {
+      description: "\u6AA2\u8996\u3001\u67E5\u8A62\u3001\u6E05\u7A7A\u6216\u6AA2\u67E5 audit log \u5065\u5EB7\u72C0\u614B",
+      tail: {
+        description: "\u986F\u793A\u6700\u8FD1\u7684 audit \u7D00\u9304\uFF08\u9810\u8A2D\uFF1A\u7576\u524D\u9023\u7DDA\u6700\u5F8C 10 \u7B46\uFF09"
+      },
+      show: {
+        description: "\u4F9D id\uFF08UUID \u524D\u7DB4 \u22654 \u78BC\uFF09\u6216 --recovery-ref \u67E5\u8A62\u55AE\u7B46 audit \u7D00\u9304"
+      },
+      clear: {
+        description: "\u522A\u9664\u7576\u524D\u9023\u7DDA\u7684 audit log \u6A94\u6848\uFF08.jsonl \u8207 .jsonl.1\uFF09",
+        prompt_header: "\u5373\u5C07\u6E05\u7A7A\u9023\u7DDA '{conn}' \u7684 audit log\uFF1A",
+        prompt_file_line: "  {file}       \u2014 {entries} \u7B46\uFF0C{size}",
+        prompt_continue: "\u78BA\u8A8D\u57F7\u884C\uFF1F[y/N] ",
+        requires_tty_or_yes: "\u975E\u4E92\u52D5 session \u7121\u6CD5\u986F\u793A\u78BA\u8A8D\u63D0\u793A\u3002\u8ACB\u4F7F\u7528 --yes \u76F4\u63A5\u6E05\u7A7A\u3002",
+        summary_cleared: "\u5DF2\u5F9E '{conn}' \u6E05\u9664 {count} \u7B46 audit \u7D00\u9304\u3002",
+        summary_nothing: "\u6C92\u6709\u53EF\u6E05\u9664\u7684\u5167\u5BB9\u3002",
+        summary_failed: "\u6E05\u9664\u5931\u6557\uFF1A{message}\u3002"
+      },
+      health: {
+        description: "\u986F\u793A AuditLogger \u5065\u5EB7\u72C0\u614B\uFF08\u6A94\u6848\u5927\u5C0F\u3001\u7B46\u6578\u3001lock \u72C0\u614B\u3001\u6700\u5F8C\u5BEB\u5165\u7D50\u679C\uFF09"
+      },
+      disabled_hint: "Audit \u5DF2\u505C\u7528\uFF08.dbcli \u4E2D audit.enabled = false\uFF09\u3002\u57F7\u884C `dbcli audit health` \u67E5\u770B\u8A73\u60C5\u3002",
+      no_entries: "\u6C92\u6709 audit \u7D00\u9304\u3002",
+      show_no_match: "\u627E\u4E0D\u5230\u7B26\u5408 '{prefix}' \u7684 audit \u7D00\u9304\u3002",
+      show_ambiguous: "\u524D\u7DB4 '{prefix}' \u4E0D\u5920\u7CBE\u78BA\uFF1A\u5339\u914D\u5230 {count} \u7B46\u7D00\u9304\uFF0C\u8ACB\u6539\u7528\u66F4\u9577\u7684\u524D\u7DB4\u3002",
+      show_prefix_too_short: "\u524D\u7DB4\u81F3\u5C11\u9700 4 \u500B\u5B57\u5143\u3002",
+      show_recovery_no_match: "\u6C92\u6709\u4EFB\u4F55 audit \u7D00\u9304\u7684 recovery_ref \u70BA '{ref}'\u3002",
+      show_recovery_ambiguous: "\u6709 {count} \u7B46\u7D00\u9304\u7684 recovery_ref \u70BA '{ref}'\uFF0C\u9019\u61C9\u5C6C\u7F55\u898B\u60C5\u6CC1\uFF1B\u8ACB\u76F4\u63A5\u6AA2\u8996\u6A94\u6848\u3002",
+      show_mutex_violation: "\u8ACB\u64C7\u4E00\u63D0\u4F9B <id> \u53C3\u6578\u6216 --recovery-ref\uFF0C\u5169\u8005\u4E0D\u53EF\u540C\u6642\u4F7F\u7528\u3002",
+      n_capped_warning: "--n \u503C {requested} \u8D85\u904E\u4E0A\u9650 {max}\uFF0C\u5DF2\u81EA\u52D5\u7E2E\u6E1B\u70BA {max}\u3002",
+      n_must_be_positive: "--n \u5FC5\u9808\u70BA\u6B63\u6574\u6578\u3002"
+    },
     queries: {
       description: "\u7BA1\u7406\u5DF2\u4FDD\u5B58\u7684\u67E5\u8A62\u7247\u6BB5",
       list_description: "\u5217\u51FA\u6240\u6709\u7247\u6BB5",
@@ -6776,7 +6840,9 @@ __export(exports_validation, {
   DbcliConfigV2Schema: () => DbcliConfigV2Schema,
   DbcliConfigSchema: () => DbcliConfigSchema,
   ConnectionConfigSchema: () => ConnectionConfigSchema,
-  BlacklistConfigSchema: () => BlacklistConfigSchema
+  BlacklistConfigSchema: () => BlacklistConfigSchema,
+  AuditRotationConfigSchema: () => AuditRotationConfigSchema,
+  AuditConfigSchema: () => AuditConfigSchema
 });
 function validateFormat(value, allowedFormats, commandName) {
   if (!allowedFormats.includes(value)) {
@@ -6784,7 +6850,7 @@ function validateFormat(value, allowedFormats, commandName) {
     throw new Error(`Invalid format "${value}" for ${commandName}. Allowed: ${allowed}`);
   }
 }
-var EnvRefSchema, StringOrEnvRef, NumberOrEnvRef, OptStringOrEnvRef, OptNumberOrEnvRef, MongoDBConnectionConfigSchema, SqlConnectionConfigSchema, RedisConnectionConfigSchema, ElasticsearchConnectionConfigSchema, ConnectionConfigSchema, PermissionSchema, MetadataSchema, BlacklistConfigSchema, DbcliConfigSchema, SqlNamedConnectionSchema, MongoDBNamedConnectionSchema, RedisNamedConnectionSchema, ElasticsearchNamedConnectionSchema, NamedConnectionSchema, DbcliConfigV2Schema;
+var EnvRefSchema, StringOrEnvRef, NumberOrEnvRef, OptStringOrEnvRef, OptNumberOrEnvRef, MongoDBConnectionConfigSchema, SqlConnectionConfigSchema, RedisConnectionConfigSchema, ElasticsearchConnectionConfigSchema, ConnectionConfigSchema, PermissionSchema, MetadataSchema, BlacklistConfigSchema, AuditRotationConfigSchema, AuditConfigSchema, DbcliConfigSchema, SqlNamedConnectionSchema, MongoDBNamedConnectionSchema, RedisNamedConnectionSchema, ElasticsearchNamedConnectionSchema, NamedConnectionSchema, DbcliConfigV2Schema;
 var init_validation = __esm(() => {
   init_zod();
   EnvRefSchema = exports_external.object({
@@ -6850,12 +6916,24 @@ var init_validation = __esm(() => {
     tables: exports_external.array(exports_external.string()).default([]),
     columns: exports_external.record(exports_external.array(exports_external.string())).default({})
   }).optional().default({ tables: [], columns: {} });
+  AuditRotationConfigSchema = exports_external.object({
+    max_bytes: exports_external.number().int().positive().default(10485760),
+    max_entries: exports_external.number().int().positive().default(1000)
+  }).optional().default({ max_bytes: 10485760, max_entries: 1000 });
+  AuditConfigSchema = exports_external.object({
+    enabled: exports_external.boolean().default(true),
+    rotation: AuditRotationConfigSchema
+  }).optional().default({
+    enabled: true,
+    rotation: { max_bytes: 10485760, max_entries: 1000 }
+  });
   DbcliConfigSchema = exports_external.object({
     connection: ConnectionConfigSchema,
     permission: PermissionSchema,
     schema: exports_external.record(exports_external.any()).optional().default({}),
     metadata: MetadataSchema,
-    blacklist: BlacklistConfigSchema
+    blacklist: BlacklistConfigSchema,
+    audit: AuditConfigSchema
   });
   SqlNamedConnectionSchema = SqlConnectionConfigSchema.extend({
     permission: PermissionSchema,
@@ -6888,7 +6966,8 @@ var init_validation = __esm(() => {
     schema: exports_external.record(exports_external.any()).optional().default({}),
     schemas: exports_external.record(exports_external.record(exports_external.any())).optional().default({}),
     metadata: MetadataSchema,
-    blacklist: BlacklistConfigSchema
+    blacklist: BlacklistConfigSchema,
+    audit: AuditConfigSchema
   }).refine((config) => (config.default in config.connections), {
     message: "Default connection must exist in connections",
     path: ["default"]
@@ -8043,6 +8122,13 @@ var init_schema_loader = __esm(() => {
 });
 
 // src/core/config.ts
+var exports_config = {};
+__export(exports_config, {
+  setGlobalConnectionName: () => setGlobalConnectionName,
+  getSchemaIsolationConnectionName: () => getSchemaIsolationConnectionName,
+  getGlobalConnectionName: () => getGlobalConnectionName,
+  configModule: () => configModule
+});
 import { join as join7 } from "path";
 function setGlobalConnectionName(name) {
   _globalConnectionName = name;
@@ -8131,7 +8217,11 @@ var init_config = __esm(() => {
     metadata: {
       version: "1.0"
     },
-    blacklist: { tables: [], columns: {} }
+    blacklist: { tables: [], columns: {} },
+    audit: {
+      enabled: true,
+      rotation: { max_bytes: 10485760, max_entries: 1000 }
+    }
   };
   configModule = {
     async read(path, connectionName) {
@@ -8201,7 +8291,8 @@ var init_config = __esm(() => {
                 permission: resolved.permission,
                 schema,
                 metadata: v2Config.metadata,
-                blacklist: v2Config.blacklist
+                blacklist: v2Config.blacklist,
+                audit: v2Config.audit
               });
             }
             const resolvedConfig = resolveEnvReferences(config, process.env, undefined, false);
@@ -20672,6 +20763,7 @@ var init_capabilities = __esm(() => {
     "init",
     "use",
     "list",
+    "schema",
     "schemaSingle",
     "schemaFullScan",
     "query",
@@ -20696,18 +20788,27 @@ var init_capabilities = __esm(() => {
     "completion",
     "upgrade",
     "recover",
-    "skill"
+    "skill",
+    "auditTail",
+    "auditShow",
+    "auditClear",
+    "auditHealth"
   ]);
   ENGINE_INDEPENDENT = {
     completion: cap("not-applicable", "none", "Shell completion is engine-independent."),
     upgrade: cap("not-applicable", "local-write", "Package update checks are engine-independent."),
     recover: cap("not-applicable", "dry-run", "Recovery operates on saved envelopes and gated command steps."),
-    skill: cap("not-applicable", "local-write", "Skill and task-pack generation are engine-independent.")
+    skill: cap("not-applicable", "local-write", "Skill and task-pack generation are engine-independent."),
+    auditTail: cap("supported", "readonly", "Reads JSONL audit entries; never writes to engines."),
+    auditShow: cap("supported", "readonly", "Looks up a single audit entry by id prefix or recovery_ref."),
+    auditHealth: cap("supported", "readonly", "Renders AuditLogger.getHealth() snapshot."),
+    auditClear: cap("supported", "local-write", "Removes <conn>.jsonl + .jsonl.1 from local disk; never touches DB.")
   };
   SQL_BASE = {
     init: cap("supported", "interactive", "SQL connection initialization is supported."),
     use: cap("supported", "local-write", "V2 config supports named SQL connections."),
     list: cap("supported", "readonly", "Lists relational tables."),
+    schema: cap("supported", "readonly", "Unified schema command (single-table or full scan)."),
     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."),
@@ -24225,6 +24326,507 @@ var init_blacklist = __esm(() => {
   };
 });
 
+// src/core/audit/lock.ts
+import { hostname } from "os";
+import { dirname } from "path";
+import { mkdir as mkdir2, open, rm } from "fs/promises";
+
+class AuditLockManager {
+  auditFilePath;
+  lockPath;
+  lockAcquiredAt = null;
+  constructor(auditFilePath) {
+    this.auditFilePath = auditFilePath;
+    this.lockPath = `${auditFilePath}.lock`;
+  }
+  getLockfilePath() {
+    return this.lockPath;
+  }
+  isLockHeld() {
+    return this.lockAcquiredAt !== null;
+  }
+  async acquireLock(operationName = "audit-write") {
+    const startTime = Date.now();
+    let backoffMs = LOCK_BACKOFF_START_MS;
+    while (true) {
+      const elapsed = Date.now() - startTime;
+      if (elapsed > LOCK_RETRY_BUDGET_MS) {
+        return false;
+      }
+      if (await this.tryAcquireLock(operationName)) {
+        this.lockAcquiredAt = Date.now();
+        return true;
+      }
+      const waitTime = Math.min(backoffMs, LOCK_BACKOFF_MAX_MS);
+      await new Promise((resolve2) => setTimeout(resolve2, waitTime));
+      backoffMs = Math.min(backoffMs * 1.5, LOCK_BACKOFF_MAX_MS);
+    }
+  }
+  async releaseLock() {
+    if (!this.lockAcquiredAt)
+      return false;
+    try {
+      await rm(this.lockPath, { force: true });
+      this.lockAcquiredAt = null;
+      return true;
+    } catch {
+      this.lockAcquiredAt = null;
+      return false;
+    }
+  }
+  async withLock(operation, operationName = "audit-write") {
+    const acquired = await this.acquireLock(operationName);
+    if (!acquired) {
+      return { skipped: "lock-budget-exhausted" };
+    }
+    try {
+      return await operation();
+    } finally {
+      await this.releaseLock();
+    }
+  }
+  async tryAcquireLock(operationName) {
+    try {
+      await mkdir2(dirname(this.lockPath), { recursive: true });
+      const lockFile = Bun.file(this.lockPath);
+      if (await lockFile.exists()) {
+        const lockContent = await lockFile.json();
+        const lockAge = Date.now() - lockContent.timestamp;
+        const staleLockThresholdMs = LOCK_RETRY_BUDGET_MS * STALE_LOCK_MULTIPLIER;
+        if (lockAge > staleLockThresholdMs) {
+          await rm(this.lockPath, { force: true });
+        } else {
+          return false;
+        }
+      }
+      const lockData = {
+        pid: process.pid,
+        operation: operationName,
+        timestamp: Date.now(),
+        hostname: hostname()
+      };
+      const handle = await open(this.lockPath, "wx");
+      try {
+        await handle.writeFile(JSON.stringify(lockData), "utf8");
+      } finally {
+        await handle.close();
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+var LOCK_RETRY_BUDGET_MS = 200, LOCK_BACKOFF_START_MS = 5, LOCK_BACKOFF_MAX_MS = 50, STALE_LOCK_MULTIPLIER = 10;
+var init_lock = () => {};
+
+// src/core/audit/rotation.ts
+import { rename } from "fs/promises";
+function shouldRotate(stats, thresholds, nextLineByteLength) {
+  const bytesAfter = stats.currentSizeBytes + nextLineByteLength;
+  const entriesAfter = stats.currentEntryCount + 1;
+  return bytesAfter >= thresholds.maxBytes || entriesAfter > thresholds.maxEntries;
+}
+async function rotate(currentPath, previousPath) {
+  try {
+    await rename(currentPath, previousPath);
+  } catch {}
+}
+var init_rotation = () => {};
+
+// src/core/audit/logger.ts
+import { appendFile, mkdir as mkdir3, readFile, stat } from "fs/promises";
+import { join as join10 } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+
+class AuditLogger {
+  auditDir;
+  auditFilePath;
+  previousFilePath;
+  enabled;
+  maxBytes;
+  maxEntries;
+  sessionIdService;
+  lockManager;
+  writerInitialized = false;
+  currentSizeBytes = 0;
+  currentEntryCount = 0;
+  lastWrite = null;
+  lastError = null;
+  warnedOnceThisProcess = false;
+  cachedSessionId = null;
+  lastRotatedAt;
+  lastRotatedPrevious;
+  writeChain = Promise.resolve();
+  constructor(opts) {
+    this.enabled = opts.enabled;
+    this.maxBytes = opts.rotation.maxBytes;
+    this.maxEntries = opts.rotation.maxEntries;
+    this.auditDir = join10(opts.storagePath, ".dbcli", "audit");
+    this.auditFilePath = join10(this.auditDir, `${opts.connectionName}.jsonl`);
+    this.previousFilePath = `${this.auditFilePath}.1`;
+    this.sessionIdService = opts.sessionIdService;
+    this.lockManager = opts.lockManager ?? new AuditLockManager(this.auditFilePath);
+  }
+  async write(entry) {
+    const writeOp = this.writeChain.then(() => this.writeInternal(entry));
+    this.writeChain = writeOp.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return writeOp;
+  }
+  async writeInternal(entry) {
+    if (!this.enabled) {
+      return { skipped: "disabled" };
+    }
+    try {
+      const sessionId = await this.sessionIdService.resolve();
+      this.cachedSessionId = sessionId;
+      await mkdir3(this.auditDir, { recursive: true });
+      if (!this.writerInitialized) {
+        await this.syncCountersFromDisk();
+        this.writerInitialized = true;
+      }
+      const id = randomUUID2();
+      const ts = new Date().toISOString();
+      const enriched = {
+        ...entry,
+        id,
+        ts,
+        session_id: sessionId
+      };
+      const line = JSON.stringify(enriched) + `
+`;
+      const lineBytes = Buffer.byteLength(line, "utf8");
+      const lockResult = await this.lockManager.withLock(async () => {
+        let rotated = false;
+        if (shouldRotate({
+          currentSizeBytes: this.currentSizeBytes,
+          currentEntryCount: this.currentEntryCount
+        }, { maxBytes: this.maxBytes, maxEntries: this.maxEntries }, lineBytes)) {
+          await rotate(this.auditFilePath, this.previousFilePath);
+          this.lastRotatedAt = new Date().toISOString();
+          this.lastRotatedPrevious = this.previousFilePath;
+          this.currentSizeBytes = 0;
+          this.currentEntryCount = 0;
+          rotated = true;
+        }
+        await appendFile(this.auditFilePath, line, { encoding: "utf8" });
+        this.currentSizeBytes += lineBytes;
+        this.currentEntryCount += 1;
+        return { rotated };
+      }, "audit-write");
+      if (lockResult !== null && typeof lockResult === "object" && "skipped" in lockResult) {
+        this.handleFailure("lock-budget-exhausted");
+        return { skipped: "lock-budget-exhausted" };
+      }
+      this.lastWrite = { ts, success: true };
+      return { success: true, rotated: lockResult.rotated, id };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.handleFailure(message);
+      return { skipped: "write-failed", error: message };
+    }
+  }
+  getHealth() {
+    return {
+      enabled: this.enabled,
+      writerInitialized: this.writerInitialized,
+      currentFile: this.auditFilePath,
+      currentSizeBytes: this.currentSizeBytes,
+      currentEntryCount: this.currentEntryCount,
+      rotationUsage: {
+        bytes: {
+          current: this.currentSizeBytes,
+          max: this.maxBytes,
+          pct: this.maxBytes > 0 ? this.currentSizeBytes / this.maxBytes * 100 : 0
+        },
+        entries: {
+          current: this.currentEntryCount,
+          max: this.maxEntries,
+          pct: this.maxEntries > 0 ? this.currentEntryCount / this.maxEntries * 100 : 0
+        }
+      },
+      lock: { state: this.lockManager.isLockHeld() ? "held" : "free" },
+      lastWrite: this.lastWrite,
+      lastError: this.lastError,
+      sessionId: this.cachedSessionId,
+      rotation: {
+        lastRotatedAt: this.lastRotatedAt,
+        previousFile: this.lastRotatedPrevious
+      }
+    };
+  }
+  async syncCountersFromDisk() {
+    try {
+      const s = await stat(this.auditFilePath);
+      this.currentSizeBytes = s.size;
+      const raw = await readFile(this.auditFilePath, "utf8");
+      this.currentEntryCount = raw.split(`
+`).filter(Boolean).length;
+    } catch {
+      this.currentSizeBytes = 0;
+      this.currentEntryCount = 0;
+    }
+  }
+  handleFailure(message) {
+    const ts = new Date().toISOString();
+    this.lastError = { ts, message };
+    this.lastWrite = { ts, success: false, error: message };
+    if (!this.warnedOnceThisProcess) {
+      process.stderr.write(`${WARN_PREFIX} warning: audit write failed (${message}); subsequent failures suppressed this process.
+`);
+      this.warnedOnceThisProcess = true;
+    }
+  }
+}
+var WARN_PREFIX = "[dbcli audit]";
+var init_logger = __esm(() => {
+  init_lock();
+  init_rotation();
+});
+
+// src/core/audit/session-id.ts
+import { mkdir as mkdir4, readFile as readFile2, rename as rename2, stat as stat2, writeFile } from "fs/promises";
+import { randomBytes } from "crypto";
+import { dirname as dirname2, join as join11 } from "path";
+function generateSessionId(pid, nowMs) {
+  const random = randomBytes(3).toString("hex");
+  return `${pid}-${nowMs}-${random}`;
+}
+async function readSessionIdFile(storagePath) {
+  const target = join11(storagePath, LAST_SESSION_ID_RELATIVE);
+  try {
+    await stat2(target);
+  } catch {
+    return null;
+  }
+  try {
+    const raw = await readFile2(target, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.sessionId === "string" && typeof parsed.pid === "number" && typeof parsed.createdAt === "string") {
+      return {
+        sessionId: parsed.sessionId,
+        pid: parsed.pid,
+        createdAt: parsed.createdAt
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeSessionIdFile(storagePath, payload) {
+  const target = join11(storagePath, LAST_SESSION_ID_RELATIVE);
+  const tmp = `${target}.tmp`;
+  try {
+    await mkdir4(dirname2(target), { recursive: true });
+    await writeFile(tmp, JSON.stringify(payload, null, 2), "utf8");
+    await rename2(tmp, target);
+  } catch {}
+}
+
+class SessionIdService {
+  storagePath;
+  cached = null;
+  constructor(storagePath) {
+    this.storagePath = storagePath;
+  }
+  async resolve() {
+    if (this.cached !== null)
+      return this.cached;
+    const fromEnv = process.env.DBCLI_SESSION_ID;
+    if (fromEnv && fromEnv.length > 0) {
+      this.cached = fromEnv;
+      return fromEnv;
+    }
+    const saved = await readSessionIdFile(this.storagePath);
+    if (saved && saved.pid === process.pid) {
+      this.cached = saved.sessionId;
+      return saved.sessionId;
+    }
+    const id = generateSessionId(process.pid, Date.now());
+    await writeSessionIdFile(this.storagePath, {
+      sessionId: id,
+      pid: process.pid,
+      createdAt: new Date().toISOString()
+    });
+    this.cached = id;
+    return id;
+  }
+  reset() {
+    this.cached = null;
+  }
+}
+var LAST_SESSION_ID_RELATIVE = ".dbcli/last-session-id";
+var init_session_id = () => {};
+
+// src/utils/redaction.ts
+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 tok = argv[i];
+    if (tok.startsWith("--")) {
+      const [name, inlineValue] = tok.split("=");
+      if (REDACTED_VALUE_FLAGS.has(name)) {
+        out.push(`${name} <redacted>`);
+        if (inlineValue === undefined)
+          i++;
+        continue;
+      }
+      if (KEEP_VALUE_FLAGS.has(name)) {
+        if (inlineValue !== undefined) {
+          out.push(tok);
+        } else {
+          out.push(name);
+          if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+            out.push(argv[++i]);
+          }
+        }
+        continue;
+      }
+      out.push(tok);
+      continue;
+    }
+    if (i === 2 && SQL_SUBCOMMANDS.has(sub)) {
+      out.push("<sql>");
+      continue;
+    }
+    out.push(tok);
+  }
+  return out.join(" ");
+}
+function redactSensitive(text2) {
+  return text2.replace(/\b(password|token|apiKey|secret|key|token|auth|credential|pass|pwd|sid)([:=]|\s+)([^\s"';,]+)/gi, "$1$2<redacted>");
+}
+function redactSql(sql) {
+  const redacted = sql.replace(/(['"])(?:(?!\1|\\).|\\.)*\1/g, "'?'").replace(/\b\d+(\.\d+)?\b/g, "0");
+  return redactSensitive(redacted);
+}
+var SQL_SUBCOMMANDS, REDACTED_VALUE_FLAGS, KEEP_VALUE_FLAGS;
+var init_redaction = __esm(() => {
+  SQL_SUBCOMMANDS = new Set(["query", "export"]);
+  REDACTED_VALUE_FLAGS = new Set([
+    "--where",
+    "--set",
+    "--data",
+    "--param",
+    "--param-file",
+    "--config",
+    "--use",
+    "--password",
+    "--token",
+    "--secret"
+  ]);
+  KEEP_VALUE_FLAGS = new Set(["--format", "--conn-name"]);
+});
+
+// src/utils/engine-hints.ts
+var exports_engine_hints = {};
+__export(exports_engine_hints, {
+  getOperationTarget: () => getOperationTarget,
+  extractTableName: () => extractTableName
+});
+function extractTableName(sql) {
+  const match = sql.match(TABLE_NAME_RE);
+  return match ? match[1] ?? null : null;
+}
+function getOperationTarget(system, command, options, sql) {
+  if (system === "mongodb") {
+    return options.collection || "<unknown-collection>";
+  }
+  if (system === "elasticsearch") {
+    return options.index || options.collection || "<unknown-index>";
+  }
+  if (system === "redis") {
+    return options.table || options.key || "<unknown-key>";
+  }
+  if (sql) {
+    const table = extractTableName(sql);
+    if (table)
+      return table;
+  }
+  return options.table || "<unknown-target>";
+}
+var TABLE_NAME_RE;
+var init_engine_hints = __esm(() => {
+  TABLE_NAME_RE = /\b(?:FROM|INTO|UPDATE)\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i;
+});
+
+// src/core/audit/integration-helper.ts
+async function getAuditLogger(config, configPath) {
+  const storagePath = await resolveConfigStoragePath(configPath);
+  const connName = config.effectiveConnectionName || getGlobalConnectionName() || "default";
+  const key = `${storagePath}:${connName}`;
+  if (!_loggers.has(key)) {
+    if (!_sessionIdService) {
+      _sessionIdService = new SessionIdService(storagePath);
+    }
+    _loggers.set(key, new AuditLogger({
+      storagePath,
+      connectionName: connName,
+      enabled: config.audit?.enabled ?? true,
+      rotation: {
+        maxBytes: config.audit?.rotation?.max_bytes ?? 10485760,
+        maxEntries: config.audit?.rotation?.max_entries ?? 1000
+      },
+      sessionIdService: _sessionIdService
+    }));
+  }
+  return _loggers.get(key);
+}
+async function writeAuditEntry(config, commandName, options, outcome) {
+  try {
+    const logger = await getAuditLogger(config, options.config || ".dbcli");
+    const engine = config.connection?.system || "postgresql";
+    const target = outcome.target || getOperationTarget(engine, commandName, options, outcome.sql);
+    let tier = getEngineCapability(engine, commandName).tier;
+    if (options.dryRun || options.plan) {
+      tier = "dry-run";
+    }
+    let errorMessage;
+    if (outcome.error) {
+      errorMessage = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+      errorMessage = redactSensitive(errorMessage);
+    }
+    const entry = {
+      engine,
+      command: commandName,
+      side_effect_tier: tier,
+      target,
+      success: outcome.success,
+      redacted_query: redactArgv(process.argv),
+      ...outcome.sql && { redacted_sql: redactSql(outcome.sql) },
+      ...errorMessage && { error: errorMessage },
+      ...outcome.recovery_ref && { recovery_ref: outcome.recovery_ref },
+      metadata: outcome.metadata
+    };
+    const result = await logger.write(entry);
+    return "success" in result ? result.id : null;
+  } catch {
+    return null;
+  }
+}
+var _sessionIdService = null, _loggers;
+var init_integration_helper = __esm(() => {
+  init_logger();
+  init_session_id();
+  init_config_binding();
+  init_config();
+  init_capabilities();
+  init_redaction();
+  init_engine_hints();
+  _loggers = new Map;
+});
+
 // src/core/recovery/types.ts
 var RECOVERY_SCHEMA_VERSION = 1, RECOVERY_CODES, SchemaCacheMissingError, RECOVERY_CODE_METADATA;
 var init_types3 = __esm(() => {
@@ -25417,8 +26019,9 @@ var init_render_markdown = __esm(() => {
 });
 
 // src/core/recovery/last-envelope.ts
-import { writeFile, readFile, rename, mkdir as mkdir2, stat } from "fs/promises";
-import { dirname, join as join10 } from "path";
+import { writeFile as writeFile2, readFile as readFile3, rename as rename3, mkdir as mkdir5, stat as stat3 } from "fs/promises";
+import { dirname as dirname3, join as join12 } from "path";
+import { randomUUID as randomUUID3 } from "crypto";
 function sanitizeCommandSummary(argv) {
   if (argv.length === 0)
     return "<unknown>";
@@ -25431,13 +26034,13 @@ function sanitizeCommandSummary(argv) {
     const tok = argv[i];
     if (tok.startsWith("--")) {
       const [name, inlineValue] = tok.split("=");
-      if (REDACTED_VALUE_FLAGS.has(name)) {
+      if (REDACTED_VALUE_FLAGS2.has(name)) {
         out.push(`${name} <redacted>`);
         if (inlineValue === undefined)
           i++;
         continue;
       }
-      if (KEEP_VALUE_FLAGS.has(name)) {
+      if (KEEP_VALUE_FLAGS2.has(name)) {
         if (inlineValue !== undefined) {
           out.push(tok);
         } else {
@@ -25451,7 +26054,7 @@ function sanitizeCommandSummary(argv) {
       out.push(tok);
       continue;
     }
-    if (i === 2 && SQL_SUBCOMMANDS.has(sub)) {
+    if (i === 2 && SQL_SUBCOMMANDS2.has(sub)) {
       out.push("<sql>");
       continue;
     }
@@ -25459,46 +26062,48 @@ function sanitizeCommandSummary(argv) {
   }
   return out.join(" ");
 }
-async function writeLastEnvelope(cwd, envelope, argv, now = () => new Date) {
-  const target = join10(cwd, LAST_ENVELOPE_PATH);
+async function writeLastEnvelope(cwd, envelope, argv, now = () => new Date, id = randomUUID3(), auditRef) {
+  const target = join12(cwd, LAST_ENVELOPE_PATH);
   const tmp = `${target}.tmp`;
   const payload = {
     schemaVersion: 1,
+    id,
+    ...auditRef !== undefined && { audit_ref: auditRef },
     savedAt: now().toISOString(),
     command: sanitizeCommandSummary(argv),
     cwd,
     envelope
   };
   try {
-    await mkdir2(dirname(target), { recursive: true });
-    await writeFile(tmp, JSON.stringify(payload, null, 2), "utf8");
-    await rename(tmp, target);
+    await mkdir5(dirname3(target), { recursive: true });
+    await writeFile2(tmp, JSON.stringify(payload, null, 2), "utf8");
+    await rename3(tmp, target);
   } catch {}
 }
 async function readLastEnvelope(cwd) {
-  const target = join10(cwd, LAST_ENVELOPE_PATH);
+  const target = join12(cwd, LAST_ENVELOPE_PATH);
   try {
-    await stat(target);
+    await stat3(target);
   } catch {
     return null;
   }
   try {
-    const raw = await readFile(target, "utf8");
+    const raw = await readFile3(target, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
   }
 }
 async function readLastEnvelopeRaw(cwd) {
-  const target = join10(cwd, LAST_ENVELOPE_PATH);
+  const target = join12(cwd, LAST_ENVELOPE_PATH);
   try {
-    await stat(target);
+    await stat3(target);
   } catch {
     return null;
   }
   let raw;
   try {
-    raw = await readFile(target, "utf8");
+    raw = await readFile3(target, "utf8");
   } catch {
     return null;
   }
@@ -25508,10 +26113,10 @@ async function readLastEnvelopeRaw(cwd) {
     return { __malformedJson: true, raw };
   }
 }
-var LAST_ENVELOPE_PATH = ".dbcli/last-recovery.json", SQL_SUBCOMMANDS, REDACTED_VALUE_FLAGS, KEEP_VALUE_FLAGS;
+var LAST_ENVELOPE_PATH = ".dbcli/last-recovery.json", SQL_SUBCOMMANDS2, REDACTED_VALUE_FLAGS2, KEEP_VALUE_FLAGS2;
 var init_last_envelope = __esm(() => {
-  SQL_SUBCOMMANDS = new Set(["query", "export"]);
-  REDACTED_VALUE_FLAGS = new Set([
+  SQL_SUBCOMMANDS2 = new Set(["query", "export"]);
+  REDACTED_VALUE_FLAGS2 = new Set([
     "--where",
     "--set",
     "--data",
@@ -25520,17 +26125,19 @@ var init_last_envelope = __esm(() => {
     "--config",
     "--use"
   ]);
-  KEEP_VALUE_FLAGS = new Set(["--format"]);
+  KEEP_VALUE_FLAGS2 = new Set(["--format"]);
 });
 
 // src/core/recovery/emit.ts
 import { writeFileSync as writeFileSync2, mkdirSync, renameSync } from "fs";
-import { dirname as dirname2, join as join11 } from "path";
+import { dirname as dirname4, join as join13 } from "path";
+import { randomUUID as randomUUID4 } from "crypto";
 function emitRecoveryEnvelope(error, ctx, options = {}) {
   const envelope = classifyError(error, ctx);
   const cwd = options.cwd ?? process.cwd();
   const argv = options.argv ?? buildArgvFromProcess();
-  writeLastEnvelopeSync(cwd, envelope, argv);
+  const envelopeId = options.envelopeId ?? randomUUID4();
+  writeLastEnvelopeSync(cwd, envelope, argv, envelopeId, options.auditRef);
   process.stdout.write(renderJson(envelope, { brief: options.brief === true }) + `
 `);
   process.exit(options.exitCode ?? 1);
@@ -25539,18 +26146,20 @@ function buildArgvFromProcess() {
   const userArgs = process.argv.slice(2);
   return ["dbcli", ...userArgs];
 }
-function writeLastEnvelopeSync(cwd, envelope, argv) {
-  const target = join11(cwd, LAST_ENVELOPE_PATH);
+function writeLastEnvelopeSync(cwd, envelope, argv, id, auditRef) {
+  const target = join13(cwd, LAST_ENVELOPE_PATH);
   const tmp = `${target}.tmp`;
   const payload = {
     schemaVersion: 1,
+    id,
+    ...auditRef !== undefined && { audit_ref: auditRef },
     savedAt: new Date().toISOString(),
     command: sanitizeCommandSummary(argv),
     cwd,
     envelope
   };
   try {
-    mkdirSync(dirname2(target), { recursive: true });
+    mkdirSync(dirname4(target), { recursive: true });
     writeFileSync2(tmp, JSON.stringify(payload, null, 2), "utf8");
     renameSync(tmp, target);
   } catch {}
@@ -26278,7 +26887,7 @@ function renderStep2(r) {
 var NEXT_SCHEMA_VERSION = 1, STEP_RESULT_SUMMARY_FIELD_CAP = 4096;
 
 // src/core/recovery/next-step-schema.ts
-import { stat as stat2 } from "fs/promises";
+import { stat as stat4 } from "fs/promises";
 import { resolve as resolve2 } from "path";
 function summarizeZodError(err) {
   return err.issues.map((iss) => {
@@ -26300,7 +26909,7 @@ async function loadStepResultSummary(arg, cwd) {
   if (arg.startsWith("@")) {
     const path3 = resolve2(cwd, arg.slice(1));
     try {
-      await stat2(path3);
+      await stat4(path3);
     } catch {
       return { ok: false, reason: `--result @<file>: ${path3} not readable.` };
     }
@@ -27430,7 +28039,7 @@ var init_parser = __esm(() => {
 
 // src/core/saved-queries/loader.ts
 import { readdir } from "fs/promises";
-import { join as join14, relative, sep } from "path";
+import { join as join16, relative, sep } from "path";
 async function loadSnippets(opts) {
   const builtin = await walkAndParse(opts.builtinDir, "builtin");
   const shared = await walkAndParse(opts.sharedDir, "shared");
@@ -27497,7 +28106,7 @@ async function collectFiles(root) {
   async function walk(dir) {
     const entries = await readdir(dir, { withFileTypes: true });
     for (const e of entries) {
-      const full = join14(dir, e.name);
+      const full = join16(dir, e.name);
       if (e.isDirectory())
         await walk(full);
       else
@@ -27581,23 +28190,23 @@ var init_runner = __esm(() => {
 });
 
 // src/core/saved-queries/snippet-paths.ts
-import { join as join15 } from "path";
+import { join as join17 } from "path";
 function resolveBuiltinDir() {
   return packageAssetPath("snippets");
 }
 function resolveSnippetDirs(workspaceRoot) {
   return {
     builtinDir: resolveBuiltinDir(),
-    sharedDir: join15(workspaceRoot, ".dbcli-shared", "queries"),
-    localDir: join15(workspaceRoot, ".dbcli", "queries")
+    sharedDir: join17(workspaceRoot, ".dbcli-shared", "queries"),
+    localDir: join17(workspaceRoot, ".dbcli", "queries")
   };
 }
 function snippetKeyToFile(workspaceRoot, key, source) {
   const rel = key.replace(/^@/, "") + ".sql";
   if (source === "builtin")
-    return join15(resolveBuiltinDir(), rel);
+    return join17(resolveBuiltinDir(), rel);
   const dir = source === "shared" ? ".dbcli-shared/queries" : ".dbcli/queries";
-  return join15(workspaceRoot, dir, rel);
+  return join17(workspaceRoot, dir, rel);
 }
 var init_snippet_paths = __esm(() => {
   init_package_root();
@@ -27660,7 +28269,7 @@ var exports_queries_delete = {};
 __export(exports_queries_delete, {
   queriesDelete: () => queriesDelete
 });
-import { rm } from "fs/promises";
+import { rm as rm2 } from "fs/promises";
 async function queriesDelete(name, options = {}) {
   if (!name.startsWith("@")) {
     throw new Error(`Snippet name must start with '@' (got '${name}')`);
@@ -27685,7 +28294,7 @@ async function queriesDelete(name, options = {}) {
       return;
   }
   for (const v of localVariants) {
-    await rm(v.query.file, { force: true });
+    await rm2(v.query.file, { force: true });
     console.log(`deleted ${v.query.file}`);
   }
 }
@@ -27699,8 +28308,8 @@ var exports_queries_rename = {};
 __export(exports_queries_rename, {
   queriesRename: () => queriesRename
 });
-import { rename as rename2, mkdir as mkdir3 } from "fs/promises";
-import { dirname as dirname4 } from "path";
+import { rename as rename4, mkdir as mkdir6 } from "fs/promises";
+import { dirname as dirname6 } from "path";
 async function queriesRename(oldName, newName, options = {}) {
   if (!oldName.startsWith("@") || !newName.startsWith("@")) {
     throw new Error(`Both names must start with '@'`);
@@ -27721,8 +28330,8 @@ async function queriesRename(oldName, newName, options = {}) {
   for (const v of local) {
     const dst = snippetKeyToFile(cwd, newName, "local");
     const dstWithSuffix = preserveEngineSuffix(v.query.file, dst);
-    await mkdir3(dirname4(dstWithSuffix), { recursive: true });
-    await rename2(v.query.file, dstWithSuffix);
+    await mkdir6(dirname6(dstWithSuffix), { recursive: true });
+    await rename4(v.query.file, dstWithSuffix);
     await rewriteFrontmatterName(dstWithSuffix, newName.slice(1));
     console.log(`renamed ${v.query.file} \u2192 ${dstWithSuffix}`);
   }
@@ -27747,8 +28356,8 @@ var exports_queries_copy = {};
 __export(exports_queries_copy, {
   queriesCopy: () => queriesCopy
 });
-import { mkdir as mkdir4, copyFile } from "fs/promises";
-import { dirname as dirname5, basename as basename2 } from "path";
+import { mkdir as mkdir7, copyFile } from "fs/promises";
+import { dirname as dirname7, basename as basename2 } from "path";
 async function queriesCopy(src, dst, options = {}) {
   if (!src.startsWith("@") || !dst.startsWith("@")) {
     throw new Error(`Both names must start with '@'`);
@@ -27766,7 +28375,7 @@ async function queriesCopy(src, dst, options = {}) {
   }
   for (const v of variants) {
     const dstFile = mapEngineSuffix(v.query.file, snippetKeyToFile(cwd, dst, "local"));
-    await mkdir4(dirname5(dstFile), { recursive: true });
+    await mkdir7(dirname7(dstFile), { recursive: true });
     await copyFile(v.query.file, dstFile);
     console.log(`copied ${v.query.file} \u2192 ${dstFile}`);
   }
@@ -27784,21 +28393,21 @@ var exports_queries_import = {};
 __export(exports_queries_import, {
   queriesImport: () => queriesImport
 });
-import { stat as stat3, mkdir as mkdir5, copyFile as copyFile2 } from "fs/promises";
-import { basename as basename3, join as join17, extname } from "path";
+import { stat as stat5, mkdir as mkdir8, copyFile as copyFile2 } from "fs/promises";
+import { basename as basename3, join as join19, extname } from "path";
 async function queriesImport(filePath, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   if (extname(filePath) !== ".sql") {
     throw new Error(`Expected .sql file, got ${filePath}`);
   }
-  await stat3(filePath);
+  await stat5(filePath);
   const text2 = await Bun.file(filePath).text();
   const baseName = options.as ? options.as.replace(/^@/, "") : basename3(filePath, ".sql").replace(/\.(postgres|mysql)$/, "");
   const key = "@" + baseName;
   parseSavedQuery({ key, file: filePath, source: "local", text: text2 });
-  const targetDir = join17(cwd, ".dbcli/queries");
-  await mkdir5(targetDir, { recursive: true });
-  const target = join17(targetDir, basename3(filePath));
+  const targetDir = join19(cwd, ".dbcli/queries");
+  await mkdir8(targetDir, { recursive: true });
+  const target = join19(targetDir, basename3(filePath));
   if (await Bun.file(target).exists()) {
     if (!options.force) {
       const ok = await dist_default6({ message: `Overwrite ${target}?`, default: false });
@@ -27819,7 +28428,7 @@ var exports_queries_export = {};
 __export(exports_queries_export, {
   queriesExport: () => queriesExport
 });
-import { writeFile as writeFile2 } from "fs/promises";
+import { writeFile as writeFile3 } from "fs/promises";
 async function queriesExport(name, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const dirs = resolveSnippetDirs(cwd);
@@ -27840,7 +28449,7 @@ async function queriesExport(name, options = {}) {
   }
   const text2 = await Bun.file(chosen[0].query.file).text();
   if (options.output) {
-    await writeFile2(options.output, text2, "utf8");
+    await writeFile3(options.output, text2, "utf8");
     console.log(`wrote ${options.output}`);
   } else {
     process.stdout.write(text2);
@@ -27923,17 +28532,17 @@ var init_collect_snippets = __esm(() => {
 });
 
 // src/core/inspect/collect-schema-cache.ts
-import { join as join21 } from "path";
+import { join as join23 } from "path";
 async function collectSchemaCache(opts) {
   const warnings = [];
-  if (opts.system && !SQL_SYSTEMS.includes(opts.system)) {
+  if (opts.system && !SQL_SYSTEMS2.includes(opts.system)) {
     return {
       section: { available: false, unavailable: true, reason: "schema cache is sql-only" },
       warnings
     };
   }
   const root = resolveSchemaPath(opts.dbcliPath, opts.connectionName);
-  const indexPath = join21(root, "index.json");
+  const indexPath = join23(root, "index.json");
   const file = Bun.file(indexPath);
   if (!await file.exists()) {
     return { section: { available: false }, warnings };
@@ -27960,11 +28569,11 @@ async function collectSchemaCache(opts) {
     };
   }
 }
-var STALE_AFTER_MS, SQL_SYSTEMS;
+var STALE_AFTER_MS, SQL_SYSTEMS2;
 var init_collect_schema_cache = __esm(() => {
   init_schema_path();
   STALE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
-  SQL_SYSTEMS = ["postgresql", "mysql", "mariadb"];
+  SQL_SYSTEMS2 = ["postgresql", "mysql", "mariadb"];
 });
 
 // src/core/inspect/collect-objects.ts
@@ -28024,7 +28633,7 @@ function suggestCommands(snap, options = {}) {
   if (!snap.system)
     return ["dbcli init"];
   const out = [];
-  const isSql = SQL_SYSTEMS2.includes(snap.system);
+  const isSql = SQL_SYSTEMS3.includes(snap.system);
   if (isSql && (!snap.schemaCache.available || snap.schemaCache.stale)) {
     out.push("dbcli schema --refresh");
   }
@@ -28039,13 +28648,13 @@ function suggestCommands(snap, options = {}) {
   const cap2 = options.brief ? 1 : 5;
   return out.slice(0, cap2);
 }
-var SQL_SYSTEMS2;
+var SQL_SYSTEMS3;
 var init_suggest_commands = __esm(() => {
-  SQL_SYSTEMS2 = ["postgresql", "mysql", "mariadb"];
+  SQL_SYSTEMS3 = ["postgresql", "mysql", "mariadb"];
 });
 
 // src/core/inspect/collector.ts
-import { join as join22 } from "path";
+import { join as join24 } from "path";
 async function collectInspect(opts) {
   const warnings = [];
   let config = null;
@@ -28121,11 +28730,11 @@ async function collectInspect(opts) {
   return { ...snapWithoutSuggestions, suggestedCommands, warnings };
 }
 async function hasConfig(configPath) {
-  if (await Bun.file(join22(configPath, "config.json")).exists())
+  if (await Bun.file(join24(configPath, "config.json")).exists())
     return true;
   if (await Bun.file(configPath).exists()) {
-    const stat4 = await Bun.file(configPath).stat().catch(() => null);
-    return stat4?.isFile() === true;
+    const stat6 = await Bun.file(configPath).stat().catch(() => null);
+    return stat6?.isFile() === true;
   }
   return false;
 }
@@ -28247,16 +28856,16 @@ function renderMarkdown2(snap, options = {}) {
 function requireSchemaCacheOrThrow(section, system) {
   if (!system)
     return;
-  if (!SQL_SYSTEMS3.includes(system))
+  if (!SQL_SYSTEMS4.includes(system))
     return;
   if (section.available === true)
     return;
   throw new SchemaCacheMissingError(`Schema cache unavailable for ${system} connection; run 'dbcli schema --refresh' to populate it.`);
 }
-var SQL_SYSTEMS3;
+var SQL_SYSTEMS4;
 var init_require_schema_cache = __esm(() => {
   init_recovery();
-  SQL_SYSTEMS3 = ["postgresql", "mysql", "mariadb"];
+  SQL_SYSTEMS4 = ["postgresql", "mysql", "mariadb"];
 });
 
 // src/core/inspect/index.ts
@@ -28273,6 +28882,125 @@ var init_inspect = __esm(() => {
   init_collector();
 });
 
+// src/core/audit/reader.ts
+import { readFile as readFile4, readdir as readdir3 } from "fs/promises";
+async function readSingle(path5) {
+  let raw;
+  try {
+    raw = await readFile4(path5, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return [];
+    throw err;
+  }
+  const lines = raw.split(`
+`).filter(Boolean);
+  const out = [];
+  for (let i = 0;i < lines.length; i++) {
+    try {
+      out.push(JSON.parse(lines[i]));
+    } catch {
+      if (i === lines.length - 1) {
+        process.stderr.write(`${WARN_PREFIX2} skipping truncated last line in ${path5}
+`);
+        continue;
+      }
+      throw new Error(`${WARN_PREFIX2} corrupted line ${i + 1} in ${path5}. Run \`dbcli audit clear\` to reset.`);
+    }
+  }
+  return out;
+}
+async function readEntries(auditFilePath, opts) {
+  if (opts?.include_rotated === true) {
+    const rotated = await readSingle(`${auditFilePath}.1`);
+    const current = await readSingle(auditFilePath);
+    return rotated.concat(current);
+  }
+  return readSingle(auditFilePath);
+}
+async function discoverConnections(auditDir) {
+  let entries;
+  try {
+    entries = await readdir3(auditDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return [];
+    throw err;
+  }
+  const map = new Map;
+  for (const e of entries) {
+    if (!e.isFile())
+      continue;
+    if (!(e.name.endsWith(".jsonl") || e.name.endsWith(".jsonl.1")))
+      continue;
+    const conn = e.name.replace(/\.jsonl(?:\.1)?$/, "");
+    const full = `${auditDir}/${e.name}`;
+    const list = map.get(conn) ?? [];
+    list.push(full);
+    map.set(conn, list);
+  }
+  for (const files of map.values()) {
+    files.sort((a, b) => Number(b.endsWith(".jsonl.1")) - Number(a.endsWith(".jsonl.1")));
+  }
+  return Array.from(map.entries()).map(([connection, files]) => ({ connection, files })).sort((a, b) => a.connection.localeCompare(b.connection));
+}
+function tailEntries(entries, n) {
+  if (n <= 0)
+    return [];
+  return entries.slice().sort((a, b) => a.ts.localeCompare(b.ts)).slice(-n);
+}
+function mergeByTimestamp(byConn) {
+  const flat = [];
+  for (const [connection, entries] of byConn) {
+    for (const entry of entries)
+      flat.push({ connection, entry });
+  }
+  flat.sort((a, b) => {
+    const t2 = a.entry.ts.localeCompare(b.entry.ts);
+    return t2 !== 0 ? t2 : a.connection.localeCompare(b.connection);
+  });
+  return flat;
+}
+var WARN_PREFIX2 = "[dbcli audit]";
+var init_reader = () => {};
+
+// src/core/audit/recent.ts
+var exports_recent = {};
+__export(exports_recent, {
+  shouldEmbedRecent: () => shouldEmbedRecent,
+  loadRecentAudit: () => loadRecentAudit,
+  RECENT_AUDIT_DEFAULT_N: () => RECENT_AUDIT_DEFAULT_N
+});
+function shouldEmbedRecent(opts) {
+  return opts.forAgent === true || opts.format === "json";
+}
+function briefifyForRecent(entry) {
+  return {
+    id: entry.id,
+    ts: entry.ts,
+    command: entry.command,
+    target: entry.target,
+    success: entry.success
+  };
+}
+async function loadRecentAudit(config, configPath, n = RECENT_AUDIT_DEFAULT_N) {
+  try {
+    if (config.audit?.enabled === false)
+      return [];
+    const logger = await getAuditLogger(config, configPath);
+    const auditFile = logger.getHealth().currentFile;
+    const entries = await readEntries(auditFile, { include_rotated: true });
+    return tailEntries(entries, n).map(briefifyForRecent);
+  } catch {
+    return [];
+  }
+}
+var RECENT_AUDIT_DEFAULT_N = 5;
+var init_recent = __esm(() => {
+  init_integration_helper();
+  init_reader();
+});
+
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
@@ -28291,7 +29019,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.19.1",
+  version: "1.20.1",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -28341,6 +29069,7 @@ var package_default = {
     "test:unit": "bun test tests/unit tests/core",
     "test:integration": "bun test tests/integration",
     "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
+    "docs:check": "bun run scripts/check-user-docs.ts",
     typecheck: "tsc --noEmit --pretty false",
     "test:perf": "bun test ./tests/perf/*.bench.ts",
     lint: "eslint src tests --ext .ts --max-warnings=0",
@@ -28741,7 +29470,8 @@ async function writeV2InitConfig(configPath, connectionName, connection, permiss
         schema: v1Config.schema || {},
         schemas: { default: v1Config.schema || {} },
         metadata: v1Config.metadata || { version: "1.0" },
-        blacklist: v1Config.blacklist || { tables: [], columns: {} }
+        blacklist: v1Config.blacklist || { tables: [], columns: {} },
+        audit: v1Config.audit
       };
     }
   } else if (await projectConfigFile.exists()) {
@@ -28760,7 +29490,8 @@ async function writeV2InitConfig(configPath, connectionName, connection, permiss
         schema: v1Config.schema || {},
         schemas: { default: v1Config.schema || {} },
         metadata: v1Config.metadata || { version: "1.0" },
-        blacklist: v1Config.blacklist || { tables: [], columns: {} }
+        blacklist: v1Config.blacklist || { tables: [], columns: {} },
+        audit: v1Config.audit
       };
     } else {
       const v1Config = await configModule.read(configPath);
@@ -28776,7 +29507,8 @@ async function writeV2InitConfig(configPath, connectionName, connection, permiss
         schema: v1Config.schema || {},
         schemas: { default: v1Config.schema || {} },
         metadata: v1Config.metadata || { version: "1.0" },
-        blacklist: v1Config.blacklist || { tables: [], columns: {} }
+        blacklist: v1Config.blacklist || { tables: [], columns: {} },
+        audit: v1Config.audit
       };
     }
   } else {
@@ -28797,7 +29529,8 @@ async function writeV2InitConfig(configPath, connectionName, connection, permiss
           schema: v1Config.schema || {},
           schemas: { default: v1Config.schema || {} },
           metadata: v1Config.metadata || { version: "1.0" },
-          blacklist: v1Config.blacklist || { tables: [], columns: {} }
+          blacklist: v1Config.blacklist || { tables: [], columns: {} },
+          audit: v1Config.audit
         };
       }
     }
@@ -28824,7 +29557,11 @@ async function writeV2InitConfig(configPath, connectionName, connection, permiss
     schema: {},
     schemas: {},
     metadata: { version: "1.0", createdAt: new Date().toISOString() },
-    blacklist: { tables: [], columns: {} }
+    blacklist: { tables: [], columns: {} },
+    audit: {
+      enabled: true,
+      rotation: { max_bytes: 10485760, max_entries: 1000 }
+    }
   };
   await writeV2Config(storagePath, v2Config);
   await migrateLegacyProjectEnvLocal(configPath, storagePath);
@@ -29482,6 +30219,7 @@ async function elasticsearchListBranch(config, format, includeSystem) {
 }
 
 // src/commands/schema.ts
+import crypto from "crypto";
 init_message_loader();
 init_adapters();
 init_config();
@@ -30155,15 +30893,17 @@ function rowsOf(result) {
 init_schema_loader();
 
 // src/commands/schema.ts
+init_integration_helper();
 init_validation();
 var ALLOWED_FORMATS2 = ["table", "json"];
 var schemaCommand = new Command().name("schema").description("Display table schema, scan database schema, or refresh existing schema with detected changes").argument("[table]", "Optional: table name to inspect (if omitted, scans all tables)").option("--format <format>", "Output format: table (default) or json", "table").option("--config <path>", "Path to .dbcli config file", ".dbcli").option("--refresh", "Refresh schema by detecting changes from database", false).option("--reset", "Clear all existing schema data and re-fetch from database", false).option("--force", "Skip confirmation when updating schema data", false).option("--sample-size <n>", "MongoDB only: number of documents to sample for schema inference (default 50, max 1000). Ignored on SQL connections.").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(schemaAction);
 async function schemaAction(table, options, command) {
+  let config;
   try {
     validateFormat(options.format, ALLOWED_FORMATS2, "schema");
     const configPath = resolveConfigPath(command, options);
     const storagePath = await resolveConfigStoragePath(configPath);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       console.error("Database not configured. Run: dbcli init");
       process.exit(1);
@@ -30219,6 +30959,10 @@ Key: ${schema.name}`);
             console.log(`  ${col.name}: ${col.type}`);
           }
         }
+        await writeAuditEntry(config, "schema", options, {
+          success: true,
+          target: table
+        });
       } finally {
         await redisAdapter.disconnect();
       }
@@ -30232,9 +30976,17 @@ Key: ${schema.name}`);
           if (!esAdapter.getTableSchema)
             throw new Error("Elasticsearch adapter does not implement getTableSchema");
           await handleSingleTableSchema(esAdapter, table, options.format, inferenceOptions);
+          await writeAuditEntry(config, "schema", options, {
+            success: true,
+            target: table
+          });
           return;
         }
         await handleFullDatabaseScan(esAdapter, config, options, connectionName, existingSchemaCount, storagePath, inferenceOptions);
+        await writeAuditEntry(config, "schema", options, {
+          success: true,
+          target: "*"
+        });
         return;
       } finally {
         await esAdapter.disconnect();
@@ -30252,13 +31004,30 @@ Key: ${schema.name}`);
       } else {
         await handleFullDatabaseScan(adapter, config, options, connectionName, existingSchemaCount, storagePath, inferenceOptions);
       }
+      await writeAuditEntry(config, "schema", options, {
+        success: true,
+        target: table ?? "*"
+      });
     } finally {
       await adapter.disconnect();
     }
   } catch (error) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
+      envelopeId = crypto.randomUUID();
+    }
+    if (config) {
+      auditId = await writeAuditEntry(config, "schema", options, {
+        success: false,
+        target: table ?? "*",
+        error,
+        ...envelopeId && { recovery_ref: envelopeId }
+      });
+    }
+    if (envelopeId !== undefined) {
       const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-      emitRecoveryEnvelope2(error, { operation: "schema", table });
+      emitRecoveryEnvelope2(error, { operation: "schema", table }, { envelopeId, auditRef: auditId ?? undefined });
     }
     if (error instanceof Error) {
       console.error(t_vars("errors.message", { message: error.message }));
@@ -30496,6 +31265,7 @@ async function writeSchema(configPath, config, connectionName) {
 // src/commands/query.ts
 init_message_loader();
 init_adapters();
+import crypto2 from "crypto";
 
 // src/formatters/html-formatter.ts
 init_package_root();
@@ -30513,14 +31283,14 @@ async function generateHtmlReport(payload) {
 }
 
 // src/utils/opener.ts
-import open from "open";
+import open2 from "open";
 async function openInBrowser(target) {
   if (process.env.DBCLI_NO_OPEN === "1" || false) {
     console.log(`[Opener] DBCLI_NO_OPEN is set. Skipping browser launch for: ${target}`);
     return;
   }
   try {
-    await open(target);
+    await open2(target);
   } catch (err) {
     console.error(`[Opener] Failed to open ${target}:`, err);
   }
@@ -30528,7 +31298,7 @@ async function openInBrowser(target) {
 
 // src/commands/query.ts
 import { tmpdir } from "os";
-import { join as join13 } from "path";
+import { join as join15 } from "path";
 
 // src/core/query-executor.ts
 init_permission_guard();
@@ -30596,20 +31366,30 @@ async function getAllTablesFromAdapter(adapter) {
   }
 }
 
+// src/core/query-executor.ts
+init_engine_hints();
+
 // src/core/limits.ts
 var DEFAULT_QUERY_ONLY_LIMIT = 1000;
 
 // src/core/query-executor.ts
+init_integration_helper();
+
 class QueryExecutor {
   adapter;
   permission;
   blacklistValidator;
-  constructor(adapter, permission, blacklistValidator) {
+  config;
+  options;
+  constructor(adapter, permission, blacklistValidator, config, options = {}) {
     this.adapter = adapter;
     this.permission = permission;
     this.blacklistValidator = blacklistValidator;
+    this.config = config;
+    this.options = options;
   }
   async execute(sql, options) {
+    const start = performance.now();
     try {
       const classification = enforcePermission(sql, this.permission);
       if (classification.isDangerous && this.permission === "admin") {
@@ -30627,7 +31407,6 @@ class QueryExecutor {
           this.blacklistValidator.checkTableBlacklist(classification.type, tableName, []);
         }
       }
-      const start = performance.now();
       const resultData = await this.adapter.execute(executeSql);
       const executionTimeMs = Math.round(performance.now() - start);
       const rows = resultData.rows;
@@ -30662,8 +31441,28 @@ class QueryExecutor {
           ...securityNotification ? { securityNotification } : {}
         }
       };
+      if (this.config) {
+        await writeAuditEntry(this.config, "query", this.options, {
+          success: true,
+          sql,
+          metadata: {
+            rows_affected: affectedRows,
+            execution_ms: executionTimeMs
+          }
+        });
+      }
       return result;
     } catch (error) {
+      if (this.config) {
+        await writeAuditEntry(this.config, "query", this.options, {
+          success: false,
+          sql,
+          error,
+          metadata: {
+            execution_ms: Math.round(performance.now() - start)
+          }
+        });
+      }
       if (error instanceof PermissionError) {
         throw error;
       }
@@ -30685,25 +31484,6 @@ class QueryExecutor {
     }
   }
 }
-function extractTableName(sql) {
-  const match = sql.match(/\bFROM\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
-  if (match) {
-    return match[1] ?? null;
-  }
-  const insertMatch = sql.match(/\bINSERT\s+INTO\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
-  if (insertMatch) {
-    return insertMatch[1] ?? null;
-  }
-  const updateMatch = sql.match(/\bUPDATE\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
-  if (updateMatch) {
-    return updateMatch[1] ?? null;
-  }
-  const deleteMatch = sql.match(/\bDELETE\s+FROM\s+["'`]?([a-zA-Z_][a-zA-Z0-9_]*)["'`]?/i);
-  if (deleteMatch) {
-    return deleteMatch[1] ?? null;
-  }
-  return null;
-}
 function inferColumnType(value) {
   if (value === null || value === undefined) {
     return "null";
@@ -30728,6 +31508,7 @@ init_config();
 init_permission_guard();
 init_blacklist();
 init_validation();
+init_integration_helper();
 function requireSqlConnection2(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
@@ -30736,6 +31517,7 @@ function requireSqlConnection2(connection) {
 }
 var ALLOWED_FORMATS3 = ["table", "json", "csv"];
 async function queryCommand(sql, options, command) {
+  let config;
   try {
     if (!sql || sql.trim() === "") {
       throw new Error("SQL query required");
@@ -30745,7 +31527,7 @@ async function queryCommand(sql, options, command) {
     }
     sql = sql.trim();
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       throw new Error('Run "dbcli init" first');
     }
@@ -30758,7 +31540,8 @@ async function queryCommand(sql, options, command) {
     if (config.connection.system === "elasticsearch") {
       return await elasticsearchQueryBranch(sql, options, config);
     }
-    const mainTable = extractMainTable(sql);
+    const { extractTableName: extractTableName2 } = await Promise.resolve().then(() => (init_engine_hints(), exports_engine_hints));
+    const mainTable = extractTableName2(sql);
     if (mainTable && config.schema && !options.noLimit) {
       const tableSchema = config.schema[mainTable];
       if (tableSchema) {
@@ -30774,7 +31557,7 @@ async function queryCommand(sql, options, command) {
     try {
       const blacklistManager = new BlacklistManager(config);
       const blacklistValidator = new BlacklistValidator(blacklistManager);
-      const executor3 = new QueryExecutor(adapter, config.permission, blacklistValidator);
+      const executor3 = new QueryExecutor(adapter, config.permission, blacklistValidator, config, options);
       const autoLimit = !options.noLimit;
       const result = await executor3.execute(sql, {
         autoLimit,
@@ -30792,7 +31575,7 @@ async function queryCommand(sql, options, command) {
           rows: result.rows
         });
         if (options.ui) {
-          const tempPath = join13(tmpdir(), `dbcli-query-${Date.now()}.html`);
+          const tempPath = join15(tmpdir(), `dbcli-query-${Date.now()}.html`);
           await Bun.write(tempPath, html);
           await openInBrowser(tempPath);
         } else {
@@ -30809,11 +31592,27 @@ async function queryCommand(sql, options, command) {
       await adapter.disconnect();
     }
   } catch (error) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
+      envelopeId = crypto2.randomUUID();
+    }
+    if (config) {
+      auditId = await writeAuditEntry(config, "query", options, {
+        success: false,
+        sql,
+        error,
+        ...envelopeId && { recovery_ref: envelopeId }
+      });
+    }
+    if (envelopeId !== undefined) {
       const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
       emitRecoveryEnvelope2(error, {
         operation: "query",
-        table: extractMainTable(sql) ?? undefined
+        table: (await Promise.resolve().then(() => (init_engine_hints(), exports_engine_hints))).extractTableName(sql) ?? undefined
+      }, {
+        envelopeId,
+        auditRef: auditId ?? undefined
       });
     }
     if (error instanceof BlacklistError) {
@@ -30834,21 +31633,17 @@ async function queryCommand(sql, options, command) {
     process.exit(1);
   }
 }
-function extractMainTable(sql) {
-  const match = sql.match(/\bFROM\s+[`"']?(\w+)[`"']?/i);
-  return match?.[1] ?? null;
-}
-var SQL_PATTERN = /^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE)\b/i;
 async function mongoQueryBranch(queryStr, options, config) {
   const collection = options.collection;
   const format = options.format ?? "table";
+  if (!collection) {
+    throw new Error("MongoDB \u67E5\u8A62\u9700\u8981\u6307\u5B9A --collection <name>");
+  }
+  const SQL_PATTERN = /^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE)\b/i;
   if (SQL_PATTERN.test(queryStr)) {
     throw new Error(`\u9019\u662F MongoDB \u9023\u7DDA\uFF0C\u8ACB\u4F7F\u7528 JSON filter \u8A9E\u6CD5\u3002
 \u7BC4\u4F8B\uFF1Adbcli query '{"field": "value"}' --collection <name>`);
   }
-  if (!collection) {
-    throw new Error("MongoDB \u67E5\u8A62\u9700\u8981\u6307\u5B9A --collection <name>");
-  }
   try {
     JSON.parse(queryStr);
   } catch {
@@ -30881,8 +31676,18 @@ async function mongoQueryBranch(queryStr, options, config) {
   }
   const mongoAdapter = AdapterFactory.createMongoDBAdapter(config.connection);
   await mongoAdapter.connect();
+  const start = performance.now();
   try {
     const result = await mongoAdapter.execute(queryStr, [collection], effectiveLimit !== undefined ? { limit: effectiveLimit } : undefined);
+    const executionTimeMs = Math.round(performance.now() - start);
+    await writeAuditEntry(config, "query", options, {
+      success: true,
+      target: collection,
+      metadata: {
+        rows_affected: result.rows.length,
+        execution_ms: executionTimeMs
+      }
+    });
     const columnNames = result.rows[0] ? Object.keys(result.rows[0]) : [];
     const filterResult = blacklistValidator.filterColumns(collection, result.rows, columnNames);
     const queryResult = {
@@ -30894,8 +31699,8 @@ async function mongoQueryBranch(queryStr, options, config) {
     const output = formatter.format(queryResult, {
       format
     });
-    const securityNote = blacklistValidator.buildSecurityNotification(collection, filterResult.omittedColumns);
     console.log(output);
+    const securityNote = blacklistValidator.buildSecurityNotification(collection, filterResult.omittedColumns);
     if (securityNote) {
       console.log(`
 \u2139 ${securityNote}`);
@@ -30909,15 +31714,24 @@ async function redisQueryBranch(command, options, config) {
   const { enforceRedisPermission: enforceRedisPermission2 } = await Promise.resolve().then(() => (init_permission_guard(), exports_permission_guard));
   const head = command.trim().split(/\s+/)[0]?.toUpperCase() ?? "";
   if (head === "KEYS" && options.recovery !== true) {
-    console.error('\u26A0 Warning: "KEYS" command is dangerous on production servers as it blocks the main thread.');
-    console.error('  Please use "SCAN" instead for better performance and safety.');
-    console.error("  For more info: https://redis.io/commands/keys/");
+    console.error('\u26A0 Warning: "KEYS" command is dangerous on production servers.');
   }
   enforceRedisPermission2(command, config.permission);
   const redisAdapter = AdapterFactory.createRedisAdapter(config.connection);
   await redisAdapter.connect();
+  const start = performance.now();
   try {
     const result = await redisAdapter.execute(command);
+    const executionTimeMs = Math.round(performance.now() - start);
+    const target = command.trim().split(/\s+/)[1] || "<unknown-key>";
+    await writeAuditEntry(config, "query", options, {
+      success: true,
+      target,
+      metadata: {
+        rows_affected: result.rows.length,
+        execution_ms: executionTimeMs
+      }
+    });
     const columnNames = result.rows[0] ? Object.keys(result.rows[0]) : ["value"];
     const queryResult = {
       rows: result.rows,
@@ -30949,23 +31763,28 @@ async function elasticsearchQueryBranch(queryStr, options, config) {
   if (options.noLimit) {
     effectiveLimit = 1e4;
     console.error("Elasticsearch --no-limit is capped at size 10000; for more rows use saved-query with search_after.");
-  } else if (typeof options.limit === "number") {
-    effectiveLimit = options.limit;
   } else {
-    effectiveLimit = DEFAULT_QUERY_ONLY_LIMIT;
-    if (config.permission === "query-only") {
-      console.error(`Query-only mode: auto-limiting to ${effectiveLimit} rows`);
-    }
+    effectiveLimit = options.limit || DEFAULT_QUERY_ONLY_LIMIT;
   }
   const blacklistManager = new BlacklistManager(config);
   const blacklistValidator = new BlacklistValidator(blacklistManager);
   blacklistValidator.checkTableBlacklist("SELECT", indexName, []);
   const esAdapter = AdapterFactory.createElasticsearchAdapter(config.connection);
   await esAdapter.connect();
+  const start = performance.now();
   try {
     const result = await esAdapter.execute(queryStr, [indexName], {
       limit: effectiveLimit
     });
+    const executionTimeMs = Math.round(performance.now() - start);
+    await writeAuditEntry(config, "query", options, {
+      success: true,
+      target: indexName,
+      metadata: {
+        rows_affected: result.rows.length,
+        execution_ms: executionTimeMs
+      }
+    });
     const columnNames = result.rows[0] ? Object.keys(result.rows[0]) : [];
     const filterResult = blacklistValidator.filterColumns(indexName, result.rows, columnNames);
     const queryResult = {
@@ -30977,11 +31796,12 @@ async function elasticsearchQueryBranch(queryStr, options, config) {
     const output = formatter.format(queryResult, {
       format
     });
-    const securityNote = blacklistValidator.buildSecurityNotification(indexName, filterResult.omittedColumns);
     console.log(output);
-    if (securityNote)
+    const securityNote = blacklistValidator.buildSecurityNotification(indexName, filterResult.omittedColumns);
+    if (securityNote) {
       console.log(`
 \u2139 ${securityNote}`);
+    }
   } finally {
     await esAdapter.disconnect();
   }
@@ -31338,8 +32158,10 @@ function buildSuggestedCommands(facts, gap) {
 // src/commands/plan.ts
 init_config();
 init_validation();
+init_integration_helper();
 var ALLOWED_FORMATS4 = ["text", "json"];
 async function planCommand(sql, options, command) {
+  let config;
   try {
     if (!sql || sql.trim() === "") {
       throw new Error("SQL statement required");
@@ -31347,7 +32169,7 @@ async function planCommand(sql, options, command) {
     const format = options.format ?? "text";
     validateFormat(format, ALLOWED_FORMATS4, "plan");
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       throw new Error('Run "dbcli init" first');
     }
@@ -31363,7 +32185,25 @@ async function planCommand(sql, options, command) {
       }
     });
     console.log(formatPlanResult(result, format));
+    if (config) {
+      await writeAuditEntry(config, "plan", { ...options, plan: true }, {
+        success: true,
+        sql,
+        target: result.targetTables[0] || "*",
+        metadata: {
+          decision: result.decision,
+          risk_factors: result.riskFactors.map((f) => f.code)
+        }
+      });
+    }
   } catch (error) {
+    if (config) {
+      await writeAuditEntry(config, "plan", { ...options, plan: true }, {
+        success: false,
+        sql,
+        error
+      });
+    }
     console.error(error.message);
     process.exit(1);
   }
@@ -31400,12 +32240,15 @@ function formatPlanText(result) {
 init_message_loader();
 init_adapters();
 init_config();
+import crypto3 from "crypto";
 init_blacklist();
 init_permission_guard();
+init_engine_hints();
+init_integration_helper();
 init_saved_queries();
 init_strategies();
 import { tmpdir as tmpdir2 } from "os";
-import { join as join16 } from "path";
+import { join as join18 } from "path";
 function formatDryRun(input) {
   const lines = ["Dry-run preview (no execution):"];
   if (input.family === "es") {
@@ -31430,12 +32273,14 @@ function formatDryRun(input) {
 `);
 }
 async function qCommand(name, options, command) {
+  let config;
+  let targetNameForAudit = name;
   try {
     if (!name?.startsWith("@")) {
       throw new Error(`Snippet name must start with '@' (got '${name}')`);
     }
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection)
       throw new Error('Run "dbcli init" first');
     const engine = mapSystemToEngine(config.connection.system);
@@ -31459,12 +32304,19 @@ async function qCommand(name, options, command) {
         values: prepared.driver.values,
         execHints: prepared.execHints
       }));
+      await writeAuditEntry(config, "q", options, {
+        success: true,
+        target: name,
+        sql: prepared.driver.sql,
+        metadata: { dry_run: true }
+      });
       return;
     }
     const blacklistManager = new BlacklistManager(config);
     const blacklistValidator = new BlacklistValidator(blacklistManager);
     const family = engineFamily(engine);
     const targetName = family === "sql" ? extractTableName(prepared.rewrittenSql) ?? "" : family === "es" ? prepared.execHints?.index ?? "" : "";
+    targetNameForAudit = targetName || name;
     if (family !== "redis" && targetName) {
       blacklistValidator.checkTableBlacklist("SELECT", targetName);
     }
@@ -31486,12 +32338,21 @@ async function qCommand(name, options, command) {
           rows: filtered.filteredRows
         });
         if (options.ui) {
-          const tempPath = join16(tmpdir2(), `dbcli-report-${Date.now()}.html`);
+          const tempPath = join18(tmpdir2(), `dbcli-report-${Date.now()}.html`);
           await Bun.write(tempPath, html);
           await openInBrowser(tempPath);
         } else {
           console.log(html);
         }
+        await writeAuditEntry(config, "q", options, {
+          success: true,
+          target: targetName || name,
+          sql: prepared.driver.sql,
+          metadata: {
+            rows_affected: filtered.filteredRows.length,
+            execution_ms: executionTimeMs
+          }
+        });
         return;
       }
       const formatter = new QueryResultFormatter;
@@ -31510,11 +32371,20 @@ async function qCommand(name, options, command) {
         }
       }, { format: options.format ?? "table" });
       console.log(out);
+      await writeAuditEntry(config, "q", options, {
+        success: true,
+        target: targetName || name,
+        sql: prepared.driver.sql,
+        metadata: {
+          rows_affected: filtered.filteredRows.length,
+          execution_ms: executionTimeMs
+        }
+      });
     } finally {
       await adapter.disconnect();
     }
   } catch (error) {
-    await handleQError(error, name, options.recovery === true);
+    await handleQError(error, targetNameForAudit, options, config);
   }
 }
 function parseCliParams(list) {
@@ -31537,14 +32407,24 @@ async function readParamFile(path4) {
   }
   return parsed;
 }
-async function handleQError(error, snippetName, useRecovery) {
-  if (useRecovery) {
-    const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-    emitRecoveryEnvelope2(error, {
-      operation: "q",
-      snippet: snippetName
+async function handleQError(error, snippetName, options, config) {
+  let auditId = null;
+  let envelopeId;
+  if (options.recovery === true) {
+    envelopeId = crypto3.randomUUID();
+  }
+  if (config) {
+    auditId = await writeAuditEntry(config, "q", options, {
+      success: false,
+      target: snippetName,
+      error,
+      ...envelopeId && { recovery_ref: envelopeId }
     });
   }
+  if (envelopeId !== undefined) {
+    const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
+    emitRecoveryEnvelope2(error, { operation: "q", snippet: snippetName }, { envelopeId, auditRef: auditId ?? undefined });
+  }
   if (error instanceof SavedQueryError) {
     console.error(error.message);
     process.exit(1);
@@ -31568,8 +32448,8 @@ async function handleQError(error, snippetName, useRecovery) {
 // src/commands/queries.ts
 init_message_loader();
 init_config();
-import { mkdir as mkdir6, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname6 } from "path";
+import { mkdir as mkdir9, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname8 } from "path";
 import { spawn as spawn2 } from "child_process";
 init_saved_queries();
 init_fold();
@@ -31817,8 +32697,8 @@ async function queriesNew(name, options) {
     process.exit(1);
     return;
   }
-  await mkdir6(dirname6(file), { recursive: true });
-  await writeFile3(file, scaffold(name), "utf8");
+  await mkdir9(dirname8(file), { recursive: true });
+  await writeFile4(file, scaffold(name), "utf8");
   console.log(`Created ${file}`);
   if (source === "shared")
     console.log(t("queries.first_run_hint"));
@@ -32136,6 +33016,7 @@ queriesCommand.command("suggest [intent]").description(t("queries.suggest_descri
 // src/commands/insert.ts
 init_message_loader();
 init_adapters();
+import crypto4 from "crypto";
 
 // src/core/data-executor.ts
 init_permission_guard();
@@ -32441,7 +33322,695 @@ function previewDelete(collection, filter) {
   return `db.${collection}.deleteMany(${pretty(filter)})`;
 }
 
+// src/commands/dml-plan.ts
+init_config();
+init_validation();
+
+// src/core/dml-plan-sql.ts
+var IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertIdentifier(value, role) {
+  if (!value || !IDENTIFIER_RE.test(value)) {
+    throw new Error(`Invalid ${role} identifier: ${JSON.stringify(value)}. ` + `${role === "table" ? "Table" : "Column"} names must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+  }
+}
+function normalizeTable(table) {
+  if (!table || table.trim() === "") {
+    throw new Error("Table name required for plan SQL");
+  }
+  const trimmed = table.trim();
+  assertIdentifier(trimmed, "table");
+  return trimmed;
+}
+function normalizeColumns(data, role) {
+  const keys = Object.keys(data);
+  if (keys.length === 0) {
+    throw new Error(role === "data" ? "INSERT plan requires at least one column in --data" : "UPDATE plan requires at least one column in --set");
+  }
+  for (const key of keys) {
+    assertIdentifier(key, "column");
+  }
+  return keys;
+}
+function normalizeWhere(where) {
+  const keys = Object.keys(where);
+  if (keys.length === 0) {
+    throw new Error("WHERE clause is required for plan SQL");
+  }
+  for (const key of keys) {
+    assertIdentifier(key, "column");
+  }
+  return keys;
+}
+function buildInsertPlanSql(table, data) {
+  const t2 = normalizeTable(table);
+  const columns = normalizeColumns(data, "data");
+  const placeholders = columns.map(() => "?").join(", ");
+  return `INSERT INTO ${t2} (${columns.join(", ")}) VALUES (${placeholders})`;
+}
+function buildUpdatePlanSql(table, set, where) {
+  const t2 = normalizeTable(table);
+  const setCols = normalizeColumns(set, "set");
+  const whereCols = normalizeWhere(where);
+  const setClause = setCols.map((col) => `${col} = ?`).join(", ");
+  const whereClause = whereCols.map((col) => `${col} = ?`).join(" AND ");
+  return `UPDATE ${t2} SET ${setClause} WHERE ${whereClause}`;
+}
+function buildDeletePlanSql(table, where) {
+  const t2 = normalizeTable(table);
+  const whereCols = normalizeWhere(where);
+  const whereClause = whereCols.map((col) => `${col} = ?`).join(" AND ");
+  return `DELETE FROM ${t2} WHERE ${whereClause}`;
+}
+
+// src/utils/where-parser.ts
+function parseWhereClause(whereClause) {
+  if (!whereClause || whereClause.trim() === "") {
+    throw new Error("WHERE clause cannot be empty");
+  }
+  const conditions = {};
+  const andParts = whereClause.split(/\s+AND\s+/i);
+  for (const part of andParts) {
+    const match = part.match(/^(\w+)\s*=\s*(.+)$/);
+    if (!match) {
+      throw new Error(`Cannot parse WHERE clause: "${part}". Use format "column=value" or "col1=val1 AND col2=val2"`);
+    }
+    const column = match[1];
+    const valueStr = match[2];
+    if (valueStr === undefined || column === undefined) {
+      throw new Error(`Cannot parse WHERE clause: "${part}". Use format "column=value" or "col1=val1 AND col2=val2"`);
+    }
+    const trimmed = valueStr.trim();
+    const isFullyQuoted = trimmed.length >= 2 && (trimmed.startsWith("'") && trimmed.endsWith("'") || trimmed.startsWith('"') && trimmed.endsWith('"'));
+    if (!isFullyQuoted && /\s+AND\s*$/i.test(trimmed)) {
+      throw new Error(`Cannot parse WHERE clause: "${part}". Use format "column=value" or "col1=val1 AND col2=val2"`);
+    }
+    const stripped = isFullyQuoted ? trimmed.slice(1, -1) : trimmed;
+    let value = stripped;
+    if (stripped !== "" && !isNaN(Number(stripped))) {
+      value = Number(stripped);
+    }
+    if (stripped === "true")
+      value = true;
+    else if (stripped === "false")
+      value = false;
+    else if (stripped === "null")
+      value = null;
+    conditions[column] = value;
+  }
+  return conditions;
+}
+
+// src/core/mongo/dml-plan.ts
+init_permission_guard();
+var MONGO_UPDATE_OPERATOR_ALLOWLIST = new Set(["$set", "$unset"]);
+var MONGO_BROAD_FILTER_OPERATORS = new Set([
+  "$regex",
+  "$in",
+  "$nin",
+  "$gt",
+  "$gte",
+  "$lt",
+  "$lte",
+  "$ne",
+  "$exists",
+  "$or",
+  "$and",
+  "$nor",
+  "$not",
+  "$expr",
+  "$text"
+]);
+function permissionSql(operation) {
+  if (operation === "insert")
+    return "INSERT INTO dummy";
+  if (operation === "update")
+    return "UPDATE dummy";
+  return "DELETE FROM dummy";
+}
+function broadOperation(operation) {
+  if (operation === "insert")
+    return "INSERT";
+  if (operation === "update")
+    return "UPDATE";
+  return "DELETE";
+}
+function pushFactor2(factors, code, severity, message) {
+  if (factors.some((f) => f.code === code && f.message === message))
+    return;
+  factors.push({ code, severity, message });
+}
+function decide2(factors) {
+  if (factors.some((f) => f.severity === "block"))
+    return "BLOCK";
+  if (factors.some((f) => f.severity === "warn"))
+    return "WARN";
+  return "ALLOW";
+}
+function extractMongoWrittenFields(setDoc) {
+  const fields = new Set;
+  const operators = [];
+  let hasUnsupportedOperator = false;
+  const hasAnyOperator = Object.keys(setDoc).some((k) => k.startsWith("$"));
+  if (!hasAnyOperator) {
+    for (const k of Object.keys(setDoc))
+      fields.add(k);
+    return { fields: Array.from(fields), operators: [], hasUnsupportedOperator: false };
+  }
+  for (const [op, payload] of Object.entries(setDoc)) {
+    operators.push(op);
+    if (!MONGO_UPDATE_OPERATOR_ALLOWLIST.has(op)) {
+      hasUnsupportedOperator = true;
+      continue;
+    }
+    if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+      for (const k of Object.keys(payload))
+        fields.add(k);
+    }
+  }
+  return { fields: Array.from(fields), operators, hasUnsupportedOperator };
+}
+function hasIdEquality(where) {
+  if (!("_id" in where))
+    return false;
+  const value = where._id;
+  if (value === null || value === undefined)
+    return false;
+  if (typeof value === "object")
+    return false;
+  return true;
+}
+function hasNonIdEquality(where) {
+  for (const [key, value] of Object.entries(where)) {
+    if (key === "_id")
+      continue;
+    if (key.startsWith("$"))
+      continue;
+    if (value === null)
+      continue;
+    if (typeof value === "object")
+      continue;
+    return true;
+  }
+  return false;
+}
+function hasBroadFilter(where) {
+  for (const [key, value] of Object.entries(where)) {
+    if (MONGO_BROAD_FILTER_OPERATORS.has(key))
+      return true;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const inner of Object.keys(value)) {
+        if (MONGO_BROAD_FILTER_OPERATORS.has(inner))
+          return true;
+      }
+    }
+  }
+  return false;
+}
+function applyPermission(operation, context, factors) {
+  const permResult = checkPermission(permissionSql(operation), context.permission);
+  if (!permResult.allowed) {
+    pushFactor2(factors, "permission_denied", "block", permResult.reason);
+  }
+}
+function applyTableBlacklist(target, context, factors) {
+  const blacklisted = (context.blacklist.tables ?? []).map((t2) => t2.toLowerCase());
+  if (blacklisted.includes(target.toLowerCase())) {
+    pushFactor2(factors, "table_blacklisted", "block", `Target collection ${target} is blacklisted.`);
+  }
+}
+function applyColumnBlacklist(target, fields, context, factors) {
+  const columns = context.blacklist.columns ?? {};
+  const lower = target.toLowerCase();
+  let blacklistedFields = [];
+  for (const [t2, cols] of Object.entries(columns)) {
+    if (t2.toLowerCase() === lower) {
+      blacklistedFields = cols;
+      break;
+    }
+  }
+  if (blacklistedFields.length === 0)
+    return;
+  for (const field of fields) {
+    if (blacklistedFields.includes(field)) {
+      pushFactor2(factors, "blacklisted_column", "block", `MongoDB write would touch blacklisted field ${target}.${field}.`);
+    }
+  }
+}
+function applySchemaCoverage(target, context, factors) {
+  const schemaTables = Object.keys(context.schema);
+  if (schemaTables.length === 0) {
+    pushFactor2(factors, "schema_cache_missing", "warn", "Schema cache is missing for the selected connection.");
+    return;
+  }
+  const known = schemaTables.some((t2) => t2.toLowerCase() === target.toLowerCase());
+  if (!known) {
+    pushFactor2(factors, "schema_table_unknown", "warn", `Target collection ${target} is missing from schema cache.`);
+  }
+}
+function buildRecommendations2(factors) {
+  const out = new Set;
+  const codes = new Set(factors.map((f) => f.code));
+  if (codes.has("nonsql_filter_empty")) {
+    out.add("Add an _id equality filter before executing this MongoDB write.");
+  }
+  if (codes.has("nonsql_missing_id")) {
+    out.add("Prefer an _id equality filter before executing this MongoDB write.");
+  }
+  if (codes.has("nonsql_filter_broad")) {
+    out.add("Narrow the filter to an _id equality or a tightly bounded condition.");
+  }
+  if (codes.has("nonsql_unsupported_operator")) {
+    out.add("Restrict the update document to $set / $unset for planner-safe writes.");
+  }
+  if (codes.has("permission_denied")) {
+    out.add("Switch to a connection with sufficient permission only if the operation is intended.");
+  }
+  if (codes.has("table_blacklisted") || codes.has("blacklisted_column")) {
+    out.add("Review blacklist rules before accessing sensitive data.");
+  }
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown")) {
+    out.add("Refresh schema cache for the target collection before executing.");
+  }
+  out.add("Use --dry-run on the actual write command.");
+  return Array.from(out);
+}
+function buildSuggestedCommands2(target, factors) {
+  const codes = new Set(factors.map((f) => f.code));
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown")) {
+    return [`dbcli schema ${target} --format json`];
+  }
+  return [];
+}
+var analyzeMongoDmlRisk = (intent, context) => {
+  const factors = [];
+  applyPermission(intent.operation, context, factors);
+  applyTableBlacklist(intent.target, context, factors);
+  if (intent.operation === "insert") {
+    applyColumnBlacklist(intent.target, Object.keys(intent.data), context, factors);
+  } else if (intent.operation === "update") {
+    const { fields, hasUnsupportedOperator } = extractMongoWrittenFields(intent.set);
+    if (hasUnsupportedOperator) {
+      pushFactor2(factors, "nonsql_unsupported_operator", "block", "MongoDB update uses an operator outside the MVP allowlist ($set, $unset).");
+    }
+    applyColumnBlacklist(intent.target, fields, context, factors);
+    const where = intent.where ?? {};
+    if (Object.keys(where).length === 0) {
+      pushFactor2(factors, "nonsql_filter_empty", "block", "MongoDB update filter is empty and would match every document.");
+    } else if (!hasIdEquality(where)) {
+      if (hasBroadFilter(where)) {
+        pushFactor2(factors, "nonsql_filter_broad", "warn", "MongoDB update filter uses a broad operator and may match multiple documents.");
+      } else if (hasNonIdEquality(where)) {
+        pushFactor2(factors, "nonsql_missing_id", "warn", "MongoDB update filter does not use _id and may match multiple documents.");
+      } else {
+        pushFactor2(factors, "nonsql_filter_broad", "warn", "MongoDB update filter is not an _id equality and may match multiple documents.");
+      }
+    }
+  } else {
+    const where = intent.where ?? {};
+    if (Object.keys(where).length === 0) {
+      pushFactor2(factors, "nonsql_filter_empty", "block", "MongoDB delete filter is empty and would match every document.");
+    } else if (!hasIdEquality(where)) {
+      if (hasBroadFilter(where)) {
+        pushFactor2(factors, "nonsql_filter_broad", "warn", "MongoDB delete filter uses a broad operator and may match multiple documents.");
+      } else if (hasNonIdEquality(where)) {
+        pushFactor2(factors, "nonsql_missing_id", "warn", "MongoDB delete filter does not use _id and may match multiple documents.");
+      } else {
+        pushFactor2(factors, "nonsql_filter_broad", "warn", "MongoDB delete filter is not an _id equality and may match multiple documents.");
+      }
+    }
+  }
+  applySchemaCoverage(intent.target, context, factors);
+  return {
+    decision: decide2(factors),
+    operation: broadOperation(intent.operation),
+    targetTables: [intent.target],
+    riskFactors: factors,
+    recommendations: buildRecommendations2(factors),
+    suggestedCommands: buildSuggestedCommands2(intent.target, factors)
+  };
+};
+
+// src/core/redis/dml-plan.ts
+init_permission_guard();
+function permissionSql2(operation) {
+  if (operation === "insert")
+    return "INSERT INTO dummy";
+  if (operation === "update")
+    return "UPDATE dummy";
+  return "DELETE FROM dummy";
+}
+function broadOperation2(operation) {
+  if (operation === "insert")
+    return "INSERT";
+  if (operation === "update")
+    return "UPDATE";
+  return "DELETE";
+}
+function pushFactor3(factors, code, severity, message) {
+  if (factors.some((f) => f.code === code && f.message === message))
+    return;
+  factors.push({ code, severity, message });
+}
+function decide3(factors) {
+  if (factors.some((f) => f.severity === "block"))
+    return "BLOCK";
+  if (factors.some((f) => f.severity === "warn"))
+    return "WARN";
+  return "ALLOW";
+}
+function classifyKey(target) {
+  if (target === "*")
+    return "all";
+  if (target.includes("*") || target.includes("?") || /\[.+\]/.test(target))
+    return "pattern";
+  return "single";
+}
+function applyPermission2(operation, context, factors) {
+  const result = checkPermission(permissionSql2(operation), context.permission);
+  if (!result.allowed) {
+    pushFactor3(factors, "permission_denied", "block", result.reason);
+  }
+}
+function applyTableBlacklist2(target, context, factors) {
+  const blacklisted = (context.blacklist.tables ?? []).map((t2) => t2.toLowerCase());
+  if (blacklisted.includes(target.toLowerCase())) {
+    pushFactor3(factors, "table_blacklisted", "block", `Redis key ${target} is blacklisted.`);
+  }
+}
+function applyColumnBlacklist2(target, fields, context, factors) {
+  const columns = context.blacklist.columns ?? {};
+  const lower = target.toLowerCase();
+  let blacklistedFields = [];
+  for (const [t2, cols] of Object.entries(columns)) {
+    if (t2.toLowerCase() === lower) {
+      blacklistedFields = cols;
+      break;
+    }
+  }
+  if (blacklistedFields.length === 0)
+    return;
+  for (const field of fields) {
+    if (blacklistedFields.includes(field)) {
+      pushFactor3(factors, "blacklisted_column", "block", `Redis write would touch blacklisted field ${target}.${field}.`);
+    }
+  }
+}
+function redisSchemaKeyMatches(schemaKey, target) {
+  const lowerKey = schemaKey.toLowerCase();
+  const lowerTarget = target.toLowerCase();
+  if (lowerKey === lowerTarget)
+    return true;
+  if (!lowerKey.includes("*") && !lowerKey.includes("?"))
+    return false;
+  const pattern = lowerKey.split("").map((ch) => {
+    if (ch === "*")
+      return ".*";
+    if (ch === "?")
+      return ".";
+    return ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${pattern}$`).test(lowerTarget);
+}
+function applySchemaCoverage2(target, context, factors) {
+  const tables = Object.keys(context.schema);
+  if (tables.length === 0) {
+    pushFactor3(factors, "schema_cache_missing", "warn", "Schema/key metadata is missing for the selected Redis connection.");
+    return;
+  }
+  const known = tables.some((t2) => redisSchemaKeyMatches(t2, target));
+  if (!known) {
+    pushFactor3(factors, "schema_table_unknown", "warn", `Redis key namespace ${target} is missing from cached metadata.`);
+  }
+}
+function buildRecommendations3(factors) {
+  const out = new Set;
+  const codes = new Set(factors.map((f) => f.code));
+  if (codes.has("nonsql_key_pattern_broad")) {
+    out.add("Specify a concrete single key instead of a wildcard pattern.");
+  }
+  if (codes.has("nonsql_overwrite_unknown")) {
+    out.add("Provide --set field information so the planner can verify the write target.");
+  }
+  if (codes.has("permission_denied")) {
+    out.add("Switch to a connection with sufficient permission only if the operation is intended.");
+  }
+  if (codes.has("table_blacklisted") || codes.has("blacklisted_column")) {
+    out.add("Review blacklist rules before accessing sensitive data.");
+  }
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown")) {
+    out.add("Refresh schema cache for the target Redis namespace before executing.");
+  }
+  out.add("Use --dry-run on the actual write command.");
+  return Array.from(out);
+}
+function buildSuggestedCommands3(target, factors) {
+  const codes = new Set(factors.map((f) => f.code));
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown")) {
+    return [`dbcli schema ${target} --format json`];
+  }
+  return [];
+}
+var analyzeRedisDmlRisk = (intent, context) => {
+  const factors = [];
+  applyPermission2(intent.operation, context, factors);
+  applyTableBlacklist2(intent.target, context, factors);
+  const keyClass = classifyKey(intent.target);
+  if (keyClass === "all") {
+    pushFactor3(factors, "nonsql_key_pattern_broad", "block", 'Redis key "*" matches every key and is unsafe for planner-level writes.');
+  } else if (keyClass === "pattern") {
+    pushFactor3(factors, "nonsql_key_pattern_broad", "warn", `Redis target ${intent.target} contains wildcard characters and may match multiple keys.`);
+  }
+  if (intent.operation === "insert") {
+    applyColumnBlacklist2(intent.target, Object.keys(intent.data), context, factors);
+  } else if (intent.operation === "update") {
+    const fields = Object.keys(intent.set);
+    if (fields.length === 0) {
+      pushFactor3(factors, "nonsql_overwrite_unknown", "warn", "Redis update has no field information and overwrite impact cannot be verified.");
+    }
+    applyColumnBlacklist2(intent.target, fields, context, factors);
+  }
+  applySchemaCoverage2(intent.target, context, factors);
+  return {
+    decision: decide3(factors),
+    operation: broadOperation2(intent.operation),
+    targetTables: [intent.target],
+    riskFactors: factors,
+    recommendations: buildRecommendations3(factors),
+    suggestedCommands: buildSuggestedCommands3(intent.target, factors)
+  };
+};
+
+// src/core/elasticsearch/dml-plan.ts
+init_permission_guard();
+function permissionSql3(operation) {
+  if (operation === "insert")
+    return "INSERT INTO dummy";
+  if (operation === "update")
+    return "UPDATE dummy";
+  return "DELETE FROM dummy";
+}
+function broadOperation3(operation) {
+  if (operation === "insert")
+    return "INSERT";
+  if (operation === "update")
+    return "UPDATE";
+  return "DELETE";
+}
+function pushFactor4(factors, code, severity, message) {
+  if (factors.some((f) => f.code === code && f.message === message))
+    return;
+  factors.push({ code, severity, message });
+}
+function decide4(factors) {
+  if (factors.some((f) => f.severity === "block"))
+    return "BLOCK";
+  if (factors.some((f) => f.severity === "warn"))
+    return "WARN";
+  return "ALLOW";
+}
+function hasIdEquality2(where) {
+  if (!where)
+    return false;
+  if (!("_id" in where))
+    return false;
+  const value = where._id;
+  if (value === null || value === undefined)
+    return false;
+  if (typeof value === "object")
+    return false;
+  return true;
+}
+function applyPermission3(operation, context, factors) {
+  const result = checkPermission(permissionSql3(operation), context.permission);
+  if (!result.allowed) {
+    pushFactor4(factors, "permission_denied", "block", result.reason);
+  }
+}
+function applyTableBlacklist3(target, context, factors) {
+  const blacklisted = (context.blacklist.tables ?? []).map((t2) => t2.toLowerCase());
+  if (blacklisted.includes(target.toLowerCase())) {
+    pushFactor4(factors, "table_blacklisted", "block", `Elasticsearch index ${target} is blacklisted.`);
+  }
+}
+function applyColumnBlacklist3(target, fields, context, factors) {
+  const columns = context.blacklist.columns ?? {};
+  const lower = target.toLowerCase();
+  let blacklistedFields = [];
+  for (const [t2, cols] of Object.entries(columns)) {
+    if (t2.toLowerCase() === lower) {
+      blacklistedFields = cols;
+      break;
+    }
+  }
+  if (blacklistedFields.length === 0)
+    return;
+  for (const field of fields) {
+    if (blacklistedFields.includes(field)) {
+      pushFactor4(factors, "blacklisted_column", "block", `Elasticsearch write would touch blacklisted field ${target}.${field}.`);
+    }
+  }
+}
+function applySchemaCoverage3(target, context, factors) {
+  const tables = Object.keys(context.schema);
+  if (tables.length === 0) {
+    pushFactor4(factors, "schema_cache_missing", "warn", "Schema cache is missing for the selected Elasticsearch connection.");
+    return;
+  }
+  const known = tables.some((t2) => t2.toLowerCase() === target.toLowerCase());
+  if (!known) {
+    pushFactor4(factors, "schema_table_unknown", "warn", `Target index ${target} is missing from schema cache.`);
+  }
+}
+function buildRecommendations4(factors) {
+  const out = new Set;
+  const codes = new Set(factors.map((f) => f.code));
+  if (codes.has("nonsql_missing_id")) {
+    out.add("Add an _id equality filter (or include _id in the document) before executing.");
+  }
+  if (codes.has("nonsql_unsupported_bulk")) {
+    out.add("Use a document-level write instead of a bulk or by-query operation.");
+  }
+  if (codes.has("permission_denied")) {
+    out.add("Switch to a connection with sufficient permission only if the operation is intended.");
+  }
+  if (codes.has("table_blacklisted") || codes.has("blacklisted_column")) {
+    out.add("Review blacklist rules before accessing sensitive data.");
+  }
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown")) {
+    out.add("Refresh schema cache for the target index before executing.");
+  }
+  out.add("Use --dry-run on the actual write command.");
+  return Array.from(out);
+}
+function buildSuggestedCommands4(target, factors) {
+  const codes = new Set(factors.map((f) => f.code));
+  if (codes.has("schema_cache_missing") || codes.has("schema_table_unknown")) {
+    return [`dbcli schema ${target} --format json`];
+  }
+  return [];
+}
+var analyzeElasticsearchDmlRisk = (intent, context) => {
+  const factors = [];
+  applyPermission3(intent.operation, context, factors);
+  applyTableBlacklist3(intent.target, context, factors);
+  if (intent.operation === "insert") {
+    const fields = Object.keys(intent.data);
+    applyColumnBlacklist3(intent.target, fields, context, factors);
+    if (intent.data._id === undefined || intent.data._id === null || intent.data._id === "") {
+      pushFactor4(factors, "nonsql_missing_id", "warn", "Elasticsearch insert has no _id; auto-id generation will make later correlation harder.");
+    }
+  } else if (intent.operation === "update") {
+    applyColumnBlacklist3(intent.target, Object.keys(intent.set), context, factors);
+    if (!hasIdEquality2(intent.where)) {
+      pushFactor4(factors, "nonsql_missing_id", "block", "Elasticsearch update requires _id in --where for planner-safe document-level update.");
+    }
+  } else {
+    if (!hasIdEquality2(intent.where)) {
+      pushFactor4(factors, "nonsql_missing_id", "block", "Elasticsearch delete requires _id in --where for planner-safe document-level deletion.");
+    }
+  }
+  applySchemaCoverage3(intent.target, context, factors);
+  return {
+    decision: decide4(factors),
+    operation: broadOperation3(intent.operation),
+    targetTables: [intent.target],
+    riskFactors: factors,
+    recommendations: buildRecommendations4(factors),
+    suggestedCommands: buildSuggestedCommands4(intent.target, factors)
+  };
+};
+
+// src/commands/dml-plan.ts
+var ALLOWED_FORMATS5 = ["text", "json"];
+var SQL_SYSTEMS = new Set(["postgresql", "mysql", "mariadb"]);
+function buildPlanSqlForIntent(intent) {
+  if (intent.operation === "insert") {
+    return buildInsertPlanSql(intent.target, intent.data);
+  }
+  if (intent.operation === "update") {
+    if (!intent.where || Object.keys(intent.where).length === 0) {
+      throw new Error("WHERE clause is required for SQL update plan");
+    }
+    return buildUpdatePlanSql(intent.target, intent.set, intent.where);
+  }
+  if (!intent.where || Object.keys(intent.where).length === 0) {
+    throw new Error("WHERE clause is required for SQL delete plan");
+  }
+  return buildDeletePlanSql(intent.target, intent.where);
+}
+async function runDmlPlanAnalysis(intent, options, command) {
+  try {
+    const format = options.format ?? "text";
+    validateFormat(format, ALLOWED_FORMATS5, "plan");
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection) {
+      throw new Error('Run "dbcli init" to configure database connection');
+    }
+    const system = config.connection.system;
+    const schema = config.schema ?? {};
+    const blacklist = config.blacklist ?? { tables: [], columns: {} };
+    if (SQL_SYSTEMS.has(system)) {
+      const planSql = buildPlanSqlForIntent(intent);
+      const schemaTableCount = Object.keys(schema).length;
+      const result = analyzeQueryRisk({
+        sql: planSql,
+        permission: config.permission,
+        blacklist,
+        schemaLookup: {
+          tables: schema,
+          cacheAvailable: schemaTableCount > 0
+        }
+      });
+      console.log(formatPlanResult(result, format));
+      return;
+    }
+    const context = {
+      permission: config.permission,
+      blacklist,
+      schema
+    };
+    if (system === "mongodb") {
+      console.log(formatPlanResult(analyzeMongoDmlRisk(intent, context), format));
+      return;
+    }
+    if (system === "redis") {
+      console.log(formatPlanResult(analyzeRedisDmlRisk(intent, context), format));
+      return;
+    }
+    if (system === "elasticsearch") {
+      console.log(formatPlanResult(analyzeElasticsearchDmlRisk(intent, context), format));
+      return;
+    }
+    throw new Error(`--plan does not support connection system "${system}" yet`);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
 // src/commands/insert.ts
+init_integration_helper();
 function requireSqlConnection3(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
@@ -32467,6 +34036,7 @@ function isStdinAvailable() {
   }
 }
 async function insertCommand(table, options, command) {
+  let config;
   try {
     if (!table || table.trim() === "") {
       throw new Error("Table name required");
@@ -32493,10 +34063,24 @@ async function insertCommand(table, options, command) {
       throw new Error('JSON must be an object (e.g. {"name":"Alice","email":"a@b.com"})');
     }
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       throw new Error('Run "dbcli init" to configure database connection');
     }
+    if (options.plan) {
+      if (options.dryRun) {
+        console.error("--plan cannot be used with --dry-run");
+        process.exit(1);
+        return;
+      }
+      await runDmlPlanAnalysis({ operation: "insert", target: table, data }, { format: options.format, config: options.config }, command);
+      await writeAuditEntry(config, "insert", options, {
+        success: true,
+        target: table,
+        metadata: { plan: true }
+      });
+      return;
+    }
     if (config.connection.system === "redis") {
       enforcePermission("INSERT INTO dummy", config.permission);
       const blacklistManager = new BlacklistManager(config);
@@ -32512,6 +34096,11 @@ async function insertCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "insert", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: 0, dry_run: true }
+        });
         return;
       }
       const adapter2 = AdapterFactory.createRedisAdapter(config.connection);
@@ -32525,6 +34114,11 @@ async function insertCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "insert", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: result.affectedRows }
+        });
         return;
       } finally {
         await adapter2.disconnect();
@@ -32538,6 +34132,11 @@ async function insertCommand(table, options, command) {
         timestamp: new Date().toISOString(),
         error: "Elasticsearch \u4E0D\u652F\u63F4 insert \u6307\u4EE4\uFF1B\u76EE\u524D\u8ACB\u4F7F\u7528\u5916\u90E8\u5DE5\u5177\uFF08\u5982 curl \u6216 Kibana DevTools\uFF09\u9032\u884C\u6587\u4EF6\u5BEB\u5165"
       };
+      await writeAuditEntry(config, "insert", options, {
+        success: false,
+        target: table,
+        error: new Error("Elasticsearch does not support insert command")
+      });
       console.log(JSON.stringify(output, null, 2));
       process.exit(1);
     }
@@ -32556,6 +34155,11 @@ async function insertCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "insert", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: 0, dry_run: true }
+        });
         return;
       }
       const adapter2 = AdapterFactory.createMongoDBAdapter(config.connection);
@@ -32570,6 +34174,11 @@ async function insertCommand(table, options, command) {
           lastInsertId: result.lastInsertId
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "insert", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: result.affectedRows }
+        });
         return;
       } finally {
         await adapter2.disconnect();
@@ -32596,6 +34205,18 @@ async function insertCommand(table, options, command) {
         ...result.error && { error: result.error }
       };
       console.log(JSON.stringify(output, null, 2));
+      await writeAuditEntry(config, "insert", options, {
+        success: result.status === "success",
+        target: table,
+        ...result.sql && { sql: result.sql },
+        metadata: {
+          rows_affected: result.rows_affected,
+          ...options.dryRun && { dry_run: true }
+        },
+        ...result.status === "error" && {
+          error: new Error(result.error ?? "insert failed")
+        }
+      });
       if (result.status === "error") {
         process.exit(1);
       }
@@ -32603,14 +34224,23 @@ async function insertCommand(table, options, command) {
       await adapter.disconnect();
     }
   } catch (error) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
-      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-      emitRecoveryEnvelope2(error, {
-        operation: "insert",
-        table,
-        writeOperation: "INSERT"
+      envelopeId = crypto4.randomUUID();
+    }
+    if (config) {
+      auditId = await writeAuditEntry(config, "insert", options, {
+        success: false,
+        target: table,
+        error,
+        ...envelopeId && { recovery_ref: envelopeId }
       });
     }
+    if (envelopeId !== undefined) {
+      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
+      emitRecoveryEnvelope2(error, { operation: "insert", table, writeOperation: "INSERT" }, { envelopeId, auditRef: auditId ?? undefined });
+    }
     if (error instanceof BlacklistError) {
       const output2 = {
         status: "error",
@@ -32645,61 +34275,32 @@ async function insertCommand(table, options, command) {
 // src/commands/update.ts
 init_message_loader();
 init_adapters();
+import crypto5 from "crypto";
 init_config();
 init_permission_guard();
 init_blacklist();
+init_integration_helper();
 function requireSqlConnection4(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-function parseWhereClause(whereClause) {
-  if (!whereClause || whereClause.trim() === "") {
-    throw new Error("WHERE clause cannot be empty");
-  }
-  const conditions = {};
-  const andParts = whereClause.split(/\s+AND\s+/i);
-  for (const part of andParts) {
-    const match = part.match(/^(\w+)\s*=\s*(.+)$/);
-    if (!match) {
-      throw new Error(`Cannot parse WHERE clause: "${part}". Use format "column=value" or "col1=val1 AND col2=val2"`);
-    }
-    const column = match[1];
-    const valueStr = match[2];
-    if (valueStr === undefined || column === undefined) {
-      throw new Error(`Cannot parse WHERE clause: "${part}". Use format "column=value" or "col1=val1 AND col2=val2"`);
-    }
-    const trimmed = valueStr.trim();
-    const stripped = trimmed.startsWith("'") && trimmed.endsWith("'") || trimmed.startsWith('"') && trimmed.endsWith('"') ? trimmed.slice(1, -1) : trimmed;
-    let value = stripped;
-    if (stripped !== "" && !isNaN(Number(stripped))) {
-      value = Number(stripped);
-    }
-    if (stripped === "true")
-      value = true;
-    else if (stripped === "false")
-      value = false;
-    else if (stripped === "null")
-      value = null;
-    conditions[column] = value;
-  }
-  return conditions;
-}
 async function updateCommand(table, options, command) {
+  let config;
   try {
     if (!table || table.trim() === "") {
       throw new Error("Table name required");
     }
     table = table.trim();
-    if (!options.where || options.where.trim() === "") {
+    if (!options.plan && (!options.where || options.where.trim() === "")) {
       throw new Error('UPDATE requires --where clause (e.g. --where "id=1")');
     }
     if (!options.set || options.set.trim() === "") {
       throw new Error(`UPDATE requires --set flag with JSON data (e.g. --set '{"name":"Bob"}')`);
     }
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       throw new Error('Run "dbcli init" to configure database connection');
     }
@@ -32712,6 +34313,45 @@ async function updateCommand(table, options, command) {
     if (!setData || typeof setData !== "object" || Array.isArray(setData)) {
       throw new Error('JSON in --set must be an object (e.g. {"name":"Bob","email":"b@example.com"})');
     }
+    if (options.plan) {
+      if (options.dryRun) {
+        console.error("--plan cannot be used with --dry-run");
+        process.exit(1);
+        return;
+      }
+      const rawWhere = options.where ?? "";
+      let whereForPlan = null;
+      if (rawWhere.trim() !== "") {
+        try {
+          const parsed = JSON.parse(rawWhere);
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            whereForPlan = parsed;
+          }
+        } catch {
+          whereForPlan = null;
+        }
+        if (whereForPlan === null) {
+          try {
+            whereForPlan = parseWhereClause(rawWhere);
+          } catch {
+            whereForPlan = {};
+          }
+        }
+      }
+      await runDmlPlanAnalysis({
+        operation: "update",
+        target: table,
+        set: setData,
+        where: whereForPlan,
+        rawWhere
+      }, { format: options.format, config: options.config }, command);
+      await writeAuditEntry(config, "update", options, {
+        success: true,
+        target: table,
+        metadata: { plan: true }
+      });
+      return;
+    }
     if (config.connection?.system === "redis") {
       enforcePermission("UPDATE dummy", config.permission);
       const blacklistManager = new BlacklistManager(config);
@@ -32726,6 +34366,11 @@ async function updateCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "update", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: 0, dry_run: true }
+        });
         return;
       }
       const adapter2 = AdapterFactory.createRedisAdapter(config.connection);
@@ -32739,6 +34384,11 @@ async function updateCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "update", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: result.affectedRows }
+        });
         return;
       } finally {
         await adapter2.disconnect();
@@ -32752,6 +34402,11 @@ async function updateCommand(table, options, command) {
         timestamp: new Date().toISOString(),
         error: "Elasticsearch \u4E0D\u652F\u63F4 update \u6307\u4EE4\uFF1B\u76EE\u524D\u8ACB\u4F7F\u7528\u5916\u90E8\u5DE5\u5177\uFF08\u5982 curl \u6216 Kibana DevTools\uFF09\u9032\u884C\u6587\u4EF6\u66F4\u65B0"
       };
+      await writeAuditEntry(config, "update", options, {
+        success: false,
+        target: table,
+        error: new Error("Elasticsearch does not support update command")
+      });
       console.log(JSON.stringify(output, null, 2));
       process.exit(1);
     }
@@ -32791,6 +34446,11 @@ async function updateCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "update", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: 0, dry_run: true }
+        });
         return;
       }
       const adapter2 = AdapterFactory.createMongoDBAdapter(config.connection);
@@ -32804,6 +34464,11 @@ async function updateCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "update", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: result.affectedRows }
+        });
         return;
       } finally {
         await adapter2.disconnect();
@@ -32836,6 +34501,18 @@ async function updateCommand(table, options, command) {
         ...result.error && { error: result.error }
       };
       console.log(JSON.stringify(output, null, 2));
+      await writeAuditEntry(config, "update", options, {
+        success: result.status === "success",
+        target: table,
+        ...result.sql && { sql: result.sql },
+        metadata: {
+          rows_affected: result.rows_affected,
+          ...options.dryRun && { dry_run: true }
+        },
+        ...result.status === "error" && {
+          error: new Error(result.error ?? "update failed")
+        }
+      });
       if (result.status === "error") {
         process.exit(1);
       }
@@ -32843,14 +34520,23 @@ async function updateCommand(table, options, command) {
       await adapter.disconnect();
     }
   } catch (error) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
-      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-      emitRecoveryEnvelope2(error, {
-        operation: "update",
-        table,
-        writeOperation: "UPDATE"
+      envelopeId = crypto5.randomUUID();
+    }
+    if (config) {
+      auditId = await writeAuditEntry(config, "update", options, {
+        success: false,
+        target: table,
+        error,
+        ...envelopeId && { recovery_ref: envelopeId }
       });
     }
+    if (envelopeId !== undefined) {
+      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
+      emitRecoveryEnvelope2(error, { operation: "update", table, writeOperation: "UPDATE" }, { envelopeId, auditRef: auditId ?? undefined });
+    }
     if (error instanceof BlacklistError) {
       const output2 = {
         status: "error",
@@ -32885,57 +34571,70 @@ async function updateCommand(table, options, command) {
 // src/commands/delete.ts
 init_message_loader();
 init_adapters();
+import crypto6 from "crypto";
 init_config();
 init_permission_guard();
 init_blacklist();
+init_integration_helper();
 function requireSqlConnection5(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-function parseWhereClause2(whereClause) {
-  if (!whereClause || whereClause.trim() === "") {
-    throw new Error('DELETE requires --where clause (e.g. --where "id=1")');
-  }
-  const conditions = {};
-  const andParts = whereClause.split(/\s+AND\s+/i);
-  for (const part of andParts) {
-    const match = part.match(/^(\w+)\s*=\s*(.+)$/);
-    if (!match || !match[1] || !match[2]) {
-      throw new Error(`Cannot parse WHERE clause: "${part}". Use format "column=value" or "col1=val1 AND col2=val2"`);
-    }
-    const column = match[1];
-    const trimmed = match[2].trim();
-    const stripped = trimmed.startsWith("'") && trimmed.endsWith("'") || trimmed.startsWith('"') && trimmed.endsWith('"') ? trimmed.slice(1, -1) : trimmed;
-    let value = stripped;
-    if (stripped !== "" && !isNaN(Number(stripped))) {
-      value = Number(stripped);
-    }
-    if (stripped === "true")
-      value = true;
-    else if (stripped === "false")
-      value = false;
-    else if (stripped === "null")
-      value = null;
-    conditions[column] = value;
-  }
-  return conditions;
-}
 async function deleteCommand(table, options, command) {
+  let config;
   try {
     if (!table || table.trim() === "") {
       throw new Error("Table name required");
     }
     table = table.trim();
-    if (!options.where || options.where.trim() === "") {
+    if (!options.plan && (!options.where || options.where.trim() === "")) {
       throw new Error('DELETE requires --where clause (e.g. --where "id=1")');
     }
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       throw new Error('Run "dbcli init" to configure database connection');
     }
+    if (options.plan) {
+      if (options.dryRun) {
+        console.error("--plan cannot be used with --dry-run");
+        process.exit(1);
+        return;
+      }
+      const rawWhere = options.where ?? "";
+      let whereForPlan = null;
+      if (rawWhere.trim() !== "") {
+        try {
+          const parsed = JSON.parse(rawWhere);
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            whereForPlan = parsed;
+          }
+        } catch {
+          whereForPlan = null;
+        }
+        if (whereForPlan === null) {
+          try {
+            whereForPlan = parseWhereClause(rawWhere);
+          } catch {
+            whereForPlan = {};
+          }
+        }
+      }
+      await runDmlPlanAnalysis({
+        operation: "delete",
+        target: table,
+        where: whereForPlan,
+        rawWhere
+      }, { format: options.format, config: options.config }, command);
+      await writeAuditEntry(config, "delete", options, {
+        success: true,
+        target: table,
+        metadata: { plan: true }
+      });
+      return;
+    }
     if (config.permission !== "data-admin" && config.permission !== "admin") {
       throw new PermissionError(t("delete.admin_only"), {
         type: "DELETE",
@@ -32953,7 +34652,7 @@ async function deleteCommand(table, options, command) {
       try {
         filter = JSON.parse(options.where);
       } catch {
-        filter = parseWhereClause2(options.where);
+        filter = parseWhereClause(options.where);
       }
       if (options.dryRun) {
         const output = {
@@ -32964,6 +34663,11 @@ async function deleteCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "delete", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: 0, dry_run: true }
+        });
         return;
       }
       const adapter2 = AdapterFactory.createRedisAdapter(config.connection);
@@ -32977,6 +34681,11 @@ async function deleteCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "delete", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: result.affectedRows }
+        });
         return;
       } finally {
         await adapter2.disconnect();
@@ -32990,6 +34699,11 @@ async function deleteCommand(table, options, command) {
         timestamp: new Date().toISOString(),
         error: "Elasticsearch \u4E0D\u652F\u63F4 delete \u6307\u4EE4\uFF1B\u76EE\u524D\u8ACB\u4F7F\u7528\u5916\u90E8\u5DE5\u5177\uFF08\u5982 curl \u6216 Kibana DevTools\uFF09\u9032\u884C\u6587\u4EF6\u522A\u9664"
       };
+      await writeAuditEntry(config, "delete", options, {
+        success: false,
+        target: table,
+        error: new Error("Elasticsearch does not support delete command")
+      });
       console.log(JSON.stringify(output, null, 2));
       process.exit(1);
     }
@@ -33001,7 +34715,7 @@ async function deleteCommand(table, options, command) {
       try {
         filter = JSON.parse(options.where);
       } catch {
-        filter = parseWhereClause2(options.where);
+        filter = parseWhereClause(options.where);
       }
       if (options.dryRun) {
         const output = {
@@ -33012,6 +34726,11 @@ async function deleteCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "delete", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: 0, dry_run: true }
+        });
         return;
       }
       const adapter2 = AdapterFactory.createMongoDBAdapter(config.connection);
@@ -33025,6 +34744,11 @@ async function deleteCommand(table, options, command) {
           timestamp: new Date().toISOString()
         };
         console.log(JSON.stringify(output, null, 2));
+        await writeAuditEntry(config, "delete", options, {
+          success: true,
+          target: table,
+          metadata: { rows_affected: result.affectedRows }
+        });
         return;
       } finally {
         await adapter2.disconnect();
@@ -33032,7 +34756,7 @@ async function deleteCommand(table, options, command) {
     }
     let whereConditions;
     try {
-      whereConditions = parseWhereClause2(options.where);
+      whereConditions = parseWhereClause(options.where);
     } catch (error) {
       throw new Error(`WHERE clause parsing failed: ${error.message}`);
     }
@@ -33057,6 +34781,18 @@ async function deleteCommand(table, options, command) {
         ...result.error && { error: result.error }
       };
       console.log(JSON.stringify(output, null, 2));
+      await writeAuditEntry(config, "delete", options, {
+        success: result.status === "success",
+        target: table,
+        ...result.sql && { sql: result.sql },
+        metadata: {
+          rows_affected: result.rows_affected,
+          ...options.dryRun && { dry_run: true }
+        },
+        ...result.status === "error" && {
+          error: new Error(result.error ?? "delete failed")
+        }
+      });
       if (result.status === "error") {
         process.exit(1);
       }
@@ -33064,14 +34800,23 @@ async function deleteCommand(table, options, command) {
       await adapter.disconnect();
     }
   } catch (error) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
-      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-      emitRecoveryEnvelope2(error, {
-        operation: "delete",
-        table,
-        writeOperation: "DELETE"
+      envelopeId = crypto6.randomUUID();
+    }
+    if (config) {
+      auditId = await writeAuditEntry(config, "delete", options, {
+        success: false,
+        target: table,
+        error,
+        ...envelopeId && { recovery_ref: envelopeId }
       });
     }
+    if (envelopeId !== undefined) {
+      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
+      emitRecoveryEnvelope2(error, { operation: "delete", table, writeOperation: "DELETE" }, { envelopeId, auditRef: auditId ?? undefined });
+    }
     if (error instanceof BlacklistError) {
       const output2 = {
         status: "error",
@@ -33106,17 +34851,21 @@ async function deleteCommand(table, options, command) {
 // src/commands/export.ts
 init_message_loader();
 init_adapters();
+import crypto7 from "crypto";
 init_config();
 init_permission_guard();
 init_blacklist();
+init_integration_helper();
+init_engine_hints();
 function requireSqlConnection6(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-var SQL_PATTERN2 = /^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE)\b/i;
+var SQL_PATTERN = /^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE)\b/i;
 async function exportCommand(sql, options, command) {
+  let config;
   try {
     if (!sql || sql.trim() === "") {
       throw new Error("Query required");
@@ -33126,7 +34875,7 @@ async function exportCommand(sql, options, command) {
     }
     sql = sql.trim();
     const configPath = resolveConfigPath(command, options);
-    const config = await configModule.read(configPath);
+    config = await configModule.read(configPath);
     if (!config.connection) {
       throw new Error('Run "dbcli init" first');
     }
@@ -33182,18 +34931,39 @@ async function exportCommand(sql, options, command) {
       } else {
         console.log(formatted);
       }
+      await writeAuditEntry(config, "export", options, {
+        success: true,
+        target: extractTableName(sql) ?? "*",
+        sql,
+        metadata: {
+          rows_affected: result.rowCount,
+          output_format: options.format,
+          ...options.output && { output_file: options.output }
+        }
+      });
     } finally {
       await adapter.disconnect();
     }
   } catch (error) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
-      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-      const m = sql.match(/\bFROM\s+[`"']?(\w+)[`"']?/i);
-      emitRecoveryEnvelope2(error, {
-        operation: "export",
-        table: m?.[1]
+      envelopeId = crypto7.randomUUID();
+    }
+    const m = sql.match(/\bFROM\s+[`"']?(\w+)[`"']?/i);
+    if (config) {
+      auditId = await writeAuditEntry(config, "export", options, {
+        success: false,
+        target: m?.[1] ?? "*",
+        sql,
+        error,
+        ...envelopeId && { recovery_ref: envelopeId }
       });
     }
+    if (envelopeId !== undefined) {
+      const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
+      emitRecoveryEnvelope2(error, { operation: "export", table: m?.[1] }, { envelopeId, auditRef: auditId ?? undefined });
+    }
     if (error instanceof PermissionError) {
       console.error(t_vars("errors.permission_denied", { required: error.requiredPermission }));
       console.error(`   Operation: ${error.classification.type}`);
@@ -33214,17 +34984,7 @@ async function exportCommand(sql, options, command) {
 }
 async function redisExportBranch(command, options, config) {
   const { enforceRedisPermission: enforceRedisPermission2 } = await Promise.resolve().then(() => (init_permission_guard(), exports_permission_guard));
-  try {
-    enforceRedisPermission2(command, config.permission);
-  } catch (error) {
-    if (error instanceof PermissionError) {
-      console.error(t_vars("errors.permission_denied", { required: error.requiredPermission }));
-      console.error(`   Operation: ${error.classification.type}`);
-      console.error(`   Message: ${error.message}`);
-      process.exit(1);
-    }
-    throw error;
-  }
+  enforceRedisPermission2(command, config.permission);
   const redisAdapter = AdapterFactory.createRedisAdapter(config.connection);
   await redisAdapter.connect();
   try {
@@ -33255,12 +35015,22 @@ async function redisExportBranch(command, options, config) {
     } else {
       console.log(formatted);
     }
+    const target = command.trim().split(/\s+/)[1] || "<unknown-key>";
+    await writeAuditEntry(config, "export", options, {
+      success: true,
+      target,
+      metadata: {
+        rows_affected: result.rowCount ?? result.rows.length ?? 0,
+        output_format: options.format,
+        ...options.output && { output_file: options.output }
+      }
+    });
   } finally {
     await redisAdapter.disconnect();
   }
 }
 async function mongoExportBranch(query, options, config) {
-  if (SQL_PATTERN2.test(query)) {
+  if (SQL_PATTERN.test(query)) {
     console.error("\u9019\u662F MongoDB \u9023\u7DDA\uFF0C\u8ACB\u4F7F\u7528 JSON filter \u6216 aggregation pipeline\u3002");
     console.error(`\u7BC4\u4F8B\uFF1Adbcli export '{"status":"open"}' --collection orders --format jsonl`);
     process.exit(1);
@@ -33318,6 +35088,15 @@ async function mongoExportBranch(query, options, config) {
     if (securityNote) {
       console.error(`\u2139 ${securityNote}`);
     }
+    await writeAuditEntry(config, "export", options, {
+      success: true,
+      target: collection,
+      metadata: {
+        rows_affected: filterResult.filteredRows.length,
+        output_format: options.format,
+        ...options.output && { output_file: options.output }
+      }
+    });
   } finally {
     await adapter.disconnect();
   }
@@ -33380,6 +35159,11 @@ import * as path4 from "path";
 import { homedir as homedir2 } from "os";
 var SKILL_SOURCE_PATH = packageAssetPath("SKILL.md");
 var REFERENCE_SOURCE_PATH = packageAssetPath("reference.md");
+function resolveSkillSource(lang) {
+  if (lang === "zh-TW")
+    return packageAssetPath("SKILL.zh-TW.md");
+  return packageAssetPath("SKILL.md");
+}
 var SUPPORTED_PLATFORMS = [
   "claude",
   "gemini",
@@ -33390,9 +35174,11 @@ var SUPPORTED_PLATFORMS = [
 ];
 async function skillCommand(_program, options) {
   try {
-    const skillFile = Bun.file(SKILL_SOURCE_PATH);
+    const lang = options.lang ?? "en";
+    const skillSourcePath = resolveSkillSource(lang);
+    const skillFile = Bun.file(skillSourcePath);
     if (!await skillFile.exists()) {
-      throw new Error(`Skill source not found: ${SKILL_SOURCE_PATH}`);
+      throw new Error(`Skill source not found: ${skillSourcePath}`);
     }
     const refFile = Bun.file(REFERENCE_SOURCE_PATH);
     if (!await refFile.exists()) {
@@ -33480,15 +35266,15 @@ async function ensureDir(dirPath) {
     await $`mkdir -p ${dirPath}`.quiet();
   } catch {
     try {
-      const { mkdir: mkdir7 } = await import("fs/promises");
-      await mkdir7(dirPath, { recursive: true });
+      const { mkdir: mkdir10 } = await import("fs/promises");
+      await mkdir10(dirPath, { recursive: true });
     } catch {
       throw new Error(`Cannot create directory: ${dirPath}`);
     }
   }
 }
 function registerSkillCommand(program2) {
-  return program2.command("skill").description(t("skill.description")).option("--install <platform>", "Install to platform directory (claude, gemini, copilot, cursor, codex, windsurf)").option("--output <path>", "Write skill to file instead of stdout").action(async (options) => {
+  return program2.command("skill").description(t("skill.description")).option("--install <platform>", "Install to platform directory (claude, gemini, copilot, cursor, codex, windsurf)").option("--output <path>", "Write skill to file instead of stdout").addOption(new Option("--lang <lang>", "Source language for SKILL content").choices(["en", "zh-TW"]).default("en")).action(async (options) => {
     try {
       await skillCommand(program2, options);
     } catch (error) {
@@ -33512,15 +35298,15 @@ class AgentTaskError extends Error {
 }
 // src/core/agent-tasks/task-paths.ts
 init_package_root();
-import { join as join19 } from "path";
+import { join as join21 } from "path";
 function resolveBuiltinDir2() {
   return packageAssetPath("tasks");
 }
 function resolveAgentTaskDirs(workspaceRoot) {
   return {
     builtinDir: resolveBuiltinDir2(),
-    sharedDir: join19(workspaceRoot, ".dbcli-shared", "tasks"),
-    localDir: join19(workspaceRoot, ".dbcli", "tasks")
+    sharedDir: join21(workspaceRoot, ".dbcli-shared", "tasks"),
+    localDir: join21(workspaceRoot, ".dbcli", "tasks")
   };
 }
 // src/core/agent-tasks/parser.ts
@@ -33658,7 +35444,7 @@ function parseSteps(value, input) {
 }
 // src/core/agent-tasks/loader.ts
 import { readdir as readdir2 } from "fs/promises";
-import { join as join20, relative as relative2, sep as sep2 } from "path";
+import { join as join22, relative as relative2, sep as sep2 } from "path";
 async function loadAgentTasks(opts, flags) {
   const errors3 = [];
   const builtin = await walkAndParse2(opts.builtinDir, "builtin", errors3);
@@ -33715,7 +35501,7 @@ async function safeCollectMd(root) {
       return;
     }
     for (const e of entries) {
-      const full = join20(dir, e.name);
+      const full = join22(dir, e.name);
       if (e.isDirectory())
         await walk(full);
       else
@@ -34303,11 +36089,11 @@ function requireSqlConnection7(connection) {
   }
   return connection;
 }
-var ALLOWED_FORMATS5 = ["json", "table"];
+var ALLOWED_FORMATS6 = ["json", "table"];
 var checkCommand = new Command().name("check").description("Run data health checks on tables").argument("[table]", "Table to check (omit for --all)").option("--all", "Check all tables (skips huge tables unless --include-large)", false).option("--include-large", "Include huge tables in --all scan", false).option("--checks <types>", "Comma-separated checks: nulls,duplicates,orphans,emptyStrings", undefined).option("--sample <number>", "Sample size for large tables (default: 10000)", "10000").option("--format <format>", "Output format: json (default) or table", "json").option("--config <path>", "Path to .dbcli config file", ".dbcli").action(checkAction);
 async function checkAction(table, options) {
   try {
-    validateFormat(options.format, ALLOWED_FORMATS5, "check");
+    validateFormat(options.format, ALLOWED_FORMATS6, "check");
     const config = await configModule.read(options.config);
     if (!config.connection) {
       console.error("Database not configured. Run: dbcli init");
@@ -34440,7 +36226,7 @@ function requireSqlConnection8(connection) {
   }
   return connection;
 }
-var ALLOWED_FORMATS6 = ["json", "table"];
+var ALLOWED_FORMATS7 = ["json", "table"];
 function compareSnapshots(before, after) {
   const beforeTables = new Set(Object.keys(before.tables));
   const afterTables = new Set(Object.keys(after.tables));
@@ -34534,7 +36320,7 @@ function compareSnapshots(before, after) {
 var diffCommand = new Command().name("diff").description("Compare schema snapshots to detect changes").option("--snapshot <path>", "Save current schema snapshot to file").option("--against <path>", "Compare current schema against a snapshot file").option("--format <format>", "Output format: json (default) or table", "json").option("--config <path>", "Path to .dbcli config file", ".dbcli").action(diffAction);
 async function diffAction(options) {
   try {
-    validateFormat(options.format, ALLOWED_FORMATS6, "diff");
+    validateFormat(options.format, ALLOWED_FORMATS7, "diff");
     if (!options.snapshot && !options.against) {
       console.error("Specify --snapshot <path> to save, or --against <path> to compare");
       process.exit(1);
@@ -34643,10 +36429,10 @@ Schema diff (${beforeSnapshot.createdAt} -> ${currentSnapshot.createdAt}):`);
 // src/commands/status.ts
 init_config();
 init_validation();
-var ALLOWED_FORMATS7 = ["text", "json"];
+var ALLOWED_FORMATS8 = ["text", "json"];
 var statusCommand = new Command("status").description("Show current configuration status (safe for AI agents, no credentials exposed)").option("--format <type>", "Output format: text, json", "json").action(async (options) => {
   try {
-    validateFormat(options.format, ALLOWED_FORMATS7, "status");
+    validateFormat(options.format, ALLOWED_FORMATS8, "status");
     const configPath = resolveConfigPath(statusCommand);
     const config = await configModule.read(configPath);
     if (!config.connection) {
@@ -34681,16 +36467,21 @@ var statusCommand = new Command("status").description("Show current configuratio
 
 // src/commands/inspect.ts
 init_message_loader();
+import crypto8 from "crypto";
 init_validation();
 init_inspect();
-var ALLOWED_FORMATS8 = ["json", "markdown"];
+init_config();
+init_integration_helper();
+var ALLOWED_FORMATS9 = ["json", "markdown"];
 var inspectCommand = new Command().name("inspect").description(t("inspect.description")).option("--format <format>", "Output format: json (default) or markdown", "json").option("--brief", "Trim samples / intents / commands for compact output", false).option("--for-agent", "Shortcut for --format json --brief", false).option("--no-connect", "Skip the database connect + version probe").option("--probe-timeout <ms>", "Hard timeout for cheap version/object probe (default 1500)", (v) => parseInt(v, 10), 1500).option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).option("--require-schema-cache", "Throw SCHEMA_CACHE_MISSING (recovery code) when the active SQL connection has no usable schema cache", false).action(async (options, command) => {
+  let config;
   try {
     const forAgent = options.forAgent === true;
     const format = forAgent ? "json" : options.format;
     const brief = forAgent || options.brief === true;
-    validateFormat(format, ALLOWED_FORMATS8, "inspect");
+    validateFormat(format, ALLOWED_FORMATS9, "inspect");
     const configPath = resolveConfigPath(command, options);
+    config = await configModule.read(configPath);
     const snap = await collectInspect({
       workspace: process.cwd(),
       configPath,
@@ -34702,12 +36493,40 @@ var inspectCommand = new Command().name("inspect").description(t("inspect.descri
       const { requireSchemaCacheOrThrow: requireSchemaCacheOrThrow2 } = await Promise.resolve().then(() => (init_inspect(), exports_inspect));
       requireSchemaCacheOrThrow2(snap.schemaCache, snap.system ?? null);
     }
+    if (config) {
+      const { shouldEmbedRecent: shouldEmbedRecent2, loadRecentAudit: loadRecentAudit2 } = await Promise.resolve().then(() => (init_recent(), exports_recent));
+      if (shouldEmbedRecent2({ forAgent, format })) {
+        snap.audit_recent = await loadRecentAudit2(config, configPath);
+      }
+    }
     const out = format === "markdown" ? renderMarkdown2(snap, { brief }) : renderJson2(snap, { brief });
     console.log(out);
+    if (config) {
+      await writeAuditEntry(config, "inspect", options, {
+        success: true,
+        target: "*"
+      });
+    }
   } catch (err) {
+    let auditId = null;
+    let envelopeId;
     if (options.recovery === true) {
+      envelopeId = crypto8.randomUUID();
+    }
+    if (config) {
+      auditId = await writeAuditEntry(config, "inspect", options, {
+        success: false,
+        target: "*",
+        error: err,
+        ...envelopeId && { recovery_ref: envelopeId }
+      });
+    }
+    if (envelopeId !== undefined) {
       const { emitRecoveryEnvelope: emitRecoveryEnvelope2 } = await Promise.resolve().then(() => (init_recovery(), exports_recovery));
-      emitRecoveryEnvelope2(err, { operation: "inspect" });
+      emitRecoveryEnvelope2(err, { operation: "inspect" }, {
+        envelopeId,
+        auditRef: auditId ?? undefined
+      });
     }
     console.error(err.message);
     process.exit(1);
@@ -34717,6 +36536,8 @@ var inspectCommand = new Command().name("inspect").description(t("inspect.descri
 // src/commands/report.ts
 init_message_loader();
 init_validation();
+init_config();
+init_integration_helper();
 
 // src/core/report/types.ts
 var REPORT_SCHEMA_VERSION = 1;
@@ -34971,10 +36792,10 @@ function finalize(input) {
     context: input.context,
     sections: input.sections,
     warnings: input.warnings,
-    suggestedCommands: buildSuggestedCommands2(input.context, input.sections)
+    suggestedCommands: buildSuggestedCommands5(input.context, input.sections)
   };
 }
-function buildSuggestedCommands2(context, sections) {
+function buildSuggestedCommands5(context, sections) {
   if (!context.system)
     return ["dbcli init"];
   const out = ["dbcli inspect --format json"];
@@ -35092,7 +36913,7 @@ function formatCell(value) {
   return String(value);
 }
 // src/commands/report.ts
-var ALLOWED_FORMATS9 = ["json", "markdown"];
+var ALLOWED_FORMATS10 = ["json", "markdown"];
 function parseSections(value) {
   const parts = value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
   for (const p of parts) {
@@ -35103,12 +36924,14 @@ function parseSections(value) {
   return parts;
 }
 var reportCommand = new Command().name("report").description(t("report.description")).option("--format <format>", "Output format: json (default) or markdown", "json").option("--section <list>", `Comma-separated subset of [${ALLOWED_SECTIONS.join(", ")}] (default: all)`, parseSections).option("--brief", "Trim evidence rows for compact output", false).option("--for-agent", "Shortcut for --format json --brief", false).option("--no-connect", "Emit context-only snapshot (skip diagnostics)").option("--per-snippet-timeout <ms>", "Hard timeout per diagnostic snippet (default 3000)", (v) => parseInt(v, 10), 3000).option("--max-rows-per-evidence <n>", "Cap rows kept per evidence (default 50)", (v) => parseInt(v, 10), 50).option("--probe-timeout <ms>", "Inspect probe timeout for cheap version/object check (default 1500)", (v) => parseInt(v, 10), 1500).action(async (options, command) => {
+  let config;
   try {
     const forAgent = options.forAgent === true;
     const format = forAgent ? "json" : options.format;
     const brief = forAgent || options.brief === true;
-    validateFormat(format, ALLOWED_FORMATS9, "report");
+    validateFormat(format, ALLOWED_FORMATS10, "report");
     const configPath = resolveConfigPath(command, options);
+    config = await configModule.read(configPath);
     const snap = await collectReport({
       workspace: process.cwd(),
       configPath,
@@ -35121,7 +36944,23 @@ var reportCommand = new Command().name("report").description(t("report.descripti
     });
     const out = format === "markdown" ? renderMarkdown3(snap, { brief }) : renderJson3(snap, { brief });
     console.log(out);
+    if (config) {
+      await writeAuditEntry(config, "report", options, {
+        success: true,
+        target: "*",
+        metadata: {
+          sections: options.section || ALLOWED_SECTIONS
+        }
+      });
+    }
   } catch (err) {
+    if (config) {
+      await writeAuditEntry(config, "report", options, {
+        success: false,
+        target: "*",
+        error: err
+      });
+    }
     console.error(err.message);
     process.exit(1);
   }
@@ -35130,6 +36969,8 @@ var reportCommand = new Command().name("report").description(t("report.descripti
 // src/commands/guide.ts
 init_message_loader();
 init_validation();
+init_config();
+init_integration_helper();
 
 // src/core/guide/types.ts
 var GUIDE_SCHEMA_VERSION = 1;
@@ -35471,7 +37312,7 @@ function renderGoalList() {
 `);
 }
 // src/commands/guide.ts
-var ALLOWED_FORMATS10 = ["json", "markdown"];
+var ALLOWED_FORMATS11 = ["json", "markdown"];
 function parseGoal(value) {
   const normalized = value.trim();
   if (!ALLOWED_GOALS.includes(normalized)) {
@@ -35480,11 +37321,12 @@ function parseGoal(value) {
   return normalized;
 }
 var guideCommand = new Command().name("guide").description(t("guide.description")).argument("[goal]", `Guide goal ID; one of [${ALLOWED_GOALS.join(", ")}]`).option("--format <format>", "Output format: json (default) or markdown", "json").option("--brief", "Trim rationale/expects for compact output", false).option("--for-agent", "Shortcut for --format json --brief", false).option("--list", "List available guide goals and exit", false).option("--probe", "Refresh inspect context via live probe (default: cache-first)", false).option("--probe-timeout <ms>", "Inspect probe timeout for cheap version/object check (default 1500)", (v) => parseInt(v, 10), 1500).action(async (goal, options, command) => {
+  let config;
   try {
     const forAgent = options.forAgent === true;
     const format = forAgent ? "json" : options.format;
     const brief = forAgent || options.brief === true;
-    validateFormat(format, ALLOWED_FORMATS10, "guide");
+    validateFormat(format, ALLOWED_FORMATS11, "guide");
     if (options.list === true) {
       if (format === "markdown") {
         console.log(renderGoalList());
@@ -35503,6 +37345,7 @@ var guideCommand = new Command().name("guide").description(t("guide.description"
     }
     const validated = parseGoal(goal);
     const configPath = resolveConfigPath(command, options);
+    config = await configModule.read(configPath);
     const snap = await collectGuide({
       workspace: process.cwd(),
       configPath,
@@ -35511,9 +37354,28 @@ var guideCommand = new Command().name("guide").description(t("guide.description"
       brief,
       probeTimeoutMs: options.probeTimeout
     });
+    if (config) {
+      const { shouldEmbedRecent: shouldEmbedRecent2, loadRecentAudit: loadRecentAudit2 } = await Promise.resolve().then(() => (init_recent(), exports_recent));
+      if (shouldEmbedRecent2({ forAgent, format })) {
+        snap.audit_recent = await loadRecentAudit2(config, configPath);
+      }
+    }
     const out = format === "markdown" ? renderMarkdown4(snap, { brief }) : renderJson4(snap, { brief });
     console.log(out);
+    if (config) {
+      await writeAuditEntry(config, "guide", options, {
+        success: true,
+        target: goal
+      });
+    }
   } catch (err) {
+    if (config) {
+      await writeAuditEntry(config, "guide", options, {
+        success: false,
+        target: goal || "*",
+        error: err
+      });
+    }
     console.error(err.message);
     process.exit(1);
   }
@@ -35523,7 +37385,7 @@ var guideCommand = new Command().name("guide").description(t("guide.description"
 init_message_loader();
 init_validation();
 init_recovery();
-var ALLOWED_FORMATS11 = ["json", "markdown"];
+var ALLOWED_FORMATS12 = ["json", "markdown"];
 function parseCode(value) {
   const normalized = value.trim();
   if (!RECOVERY_CODES.includes(normalized)) {
@@ -35559,7 +37421,7 @@ var recoveryCommand = new Command().name("recovery").description(t("recovery.des
     const forAgent = options.forAgent === true;
     const format = forAgent ? "json" : options.format;
     const brief = forAgent || options.brief === true;
-    validateFormat(format, ALLOWED_FORMATS11, "recovery");
+    validateFormat(format, ALLOWED_FORMATS12, "recovery");
     if (options.list === true) {
       if (format === "markdown") {
         console.log(renderCodeList());
@@ -35600,7 +37462,7 @@ var recoveryCommand = new Command().name("recovery").description(t("recovery.des
 // src/commands/recover.ts
 init_recovery();
 init_last_envelope();
-import { stat as stat4 } from "fs/promises";
+import { stat as stat6 } from "fs/promises";
 import { resolve as resolve4 } from "path";
 
 // src/core/recovery/envelope-schema.ts
@@ -35652,6 +37514,8 @@ var recoveryEnvelopeSchema = exports_external.object({
 }).strict();
 var savedRecoveryEnvelopeSchema = exports_external.object({
   schemaVersion: exports_external.literal(1),
+  id: exports_external.string().optional(),
+  audit_ref: exports_external.string().optional(),
   savedAt: exports_external.string().min(1),
   command: exports_external.string(),
   cwd: exports_external.string().min(1),
@@ -35682,7 +37546,7 @@ function looksLikeSavedEnvelope(x) {
 // src/commands/recover.ts
 init_next_step_schema();
 init_validation();
-var ALLOWED_FORMATS12 = ["json", "markdown"];
+var ALLOWED_FORMATS13 = ["json", "markdown"];
 var ALLOWED_TIERS = ["readonly-cmd", "write-cmd"];
 
 class RecoverCliError extends Error {
@@ -35716,7 +37580,7 @@ async function resolveApplySource(opts) {
       }
       const saved2 = r3.value;
       try {
-        await stat4(saved2.cwd);
+        await stat6(saved2.cwd);
       } catch {
         throw new RecoverCliError(`--from ${opts.from}: saved cwd '${saved2.cwd}' no longer exists.`, EXIT_CODE.malformed);
       }
@@ -35750,7 +37614,7 @@ async function resolveApplySource(opts) {
   }
   const saved = r.value;
   try {
-    await stat4(saved.cwd);
+    await stat6(saved.cwd);
   } catch {
     throw new RecoverCliError(`Auto-saved ${LAST_ENVELOPE_PATH} references cwd '${saved.cwd}' that no longer exists.`, EXIT_CODE.malformed);
   }
@@ -35824,7 +37688,7 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
     }
     const explicitFormat = options.format;
     const format = explicitFormat ?? (options.apply === true || options.next === true ? "json" : "markdown");
-    validateFormat(format, ALLOWED_FORMATS12, "recover");
+    validateFormat(format, ALLOWED_FORMATS13, "recover");
     let allowWrite = "none";
     if (options.next !== true) {
       const allowWriteRaw = options.allowWrite;
@@ -35839,15 +37703,32 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
       from: options.from,
       cwd: process.cwd()
     });
+    let audit_recent = [];
+    if (format === "json" && options.next !== true) {
+      try {
+        const { configModule: configModule2 } = await Promise.resolve().then(() => (init_config(), exports_config));
+        const configPath = `${process.cwd()}/.dbcli`;
+        const config = await configModule2.read(configPath);
+        if (config) {
+          const { loadRecentAudit: loadRecentAudit2 } = await Promise.resolve().then(() => (init_recent(), exports_recent));
+          audit_recent = await loadRecentAudit2(config, configPath);
+        }
+      } catch {
+        audit_recent = [];
+      }
+    }
     if (options.next === true) {
       const result2 = await runNext(options, source);
-      const out2 = format === "markdown" ? renderNextMarkdown(result2) : renderNextJson(result2);
-      console.log(out2);
+      const out = format === "markdown" ? renderNextMarkdown(result2) : renderNextJson(result2);
+      console.log(out);
       return;
     }
     if (options.apply !== true) {
-      const out2 = format === "markdown" ? renderMarkdown(source.envelope) : renderJson(source.envelope);
-      console.log(out2);
+      if (format === "markdown") {
+        console.log(renderMarkdown(source.envelope));
+      } else {
+        console.log(JSON.stringify({ ...source.envelope, audit_recent }, null, 2));
+      }
       return;
     }
     const noVerify = options.verify === false;
@@ -35856,8 +37737,11 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
       cwd: source.cwd,
       source: { kind: source.kind, path: source.path }
     }, { allowWrite, noVerify });
-    const out = format === "markdown" ? renderApplyMarkdown(result) : renderApplyJson(result);
-    console.log(out);
+    if (format === "markdown") {
+      console.log(renderApplyMarkdown(result));
+    } else {
+      console.log(JSON.stringify({ ...result, audit_recent }, null, 2));
+    }
     process.exit(exitCodeFor(result.finalStatus));
   } catch (err) {
     if (err instanceof RecoverCliError) {
@@ -35869,6 +37753,440 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
   }
 });
 
+// src/commands/audit.ts
+import { rm as rm3, stat as stat7 } from "fs/promises";
+import { join as join25 } from "path";
+init_message_loader();
+init_validation();
+init_config();
+init_config_binding();
+init_reader();
+init_integration_helper();
+var ALLOWED_FORMATS14 = ["table", "json"];
+var DEFAULT_TAIL_N = 10;
+var MAX_TAIL_N = 1e4;
+var SHORT_ID_LEN = 8;
+var MISSING_PLACEHOLDER = "\u2014";
+var PREFIX_MIN = 4;
+async function resolveAuditPaths(configPath, config) {
+  const storagePath = await resolveConfigStoragePath(configPath);
+  const connName = config.effectiveConnectionName || getGlobalConnectionName() || "default";
+  const auditDir = join25(storagePath, ".dbcli", "audit");
+  const auditFile = join25(auditDir, `${connName}.jsonl`);
+  return { auditDir, connectionName: connName, auditFile };
+}
+function isAuditDisabled(config) {
+  return config?.audit?.enabled === false;
+}
+function emitDisabledAndExit0() {
+  console.error(t("audit.disabled_hint"));
+  process.exit(0);
+}
+function parseTailN(raw) {
+  const requested = typeof raw === "number" ? raw : parseInt(String(raw ?? ""), 10);
+  if (!Number.isFinite(requested) || !Number.isInteger(requested) || requested <= 0) {
+    console.error(t("audit.n_must_be_positive"));
+    process.exit(1);
+  }
+  if (requested > MAX_TAIL_N) {
+    console.error(t_vars("audit.n_capped_warning", {
+      requested: String(requested),
+      max: String(MAX_TAIL_N)
+    }));
+    return MAX_TAIL_N;
+  }
+  return requested;
+}
+function briefify(entry) {
+  return {
+    ts: entry.ts,
+    command: entry.command,
+    target: entry.target,
+    success: entry.success
+  };
+}
+function shortId(id) {
+  if (!id)
+    return MISSING_PLACEHOLDER;
+  return id.length <= SHORT_ID_LEN ? id : id.slice(0, SHORT_ID_LEN);
+}
+function renderTable(rows, headers) {
+  const allRows = [headers, ...rows];
+  const widths = headers.map((_, col) => Math.max(...allRows.map((r) => (r[col] ?? "").length)));
+  const fmt = (r) => r.map((cell, i) => (cell ?? "").padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+  const sep3 = widths.map((w) => "-".repeat(w)).join("  ").trimEnd();
+  return [fmt(headers), sep3, ...rows.map(fmt)].join(`
+`);
+}
+function renderTailTable(entries) {
+  const headers = ["ts", "command", "target", "tier", "success", "id", "recovery_ref"];
+  const rows = entries.map((e) => [
+    e.ts,
+    e.command,
+    e.target,
+    e.side_effect_tier,
+    String(e.success),
+    shortId(e.id),
+    shortId(e.recovery_ref)
+  ]);
+  return renderTable(rows, headers);
+}
+function renderTailAllTable(envelopes) {
+  const headers = ["connection", "ts", "command", "target", "tier", "success", "id", "recovery_ref"];
+  const rows = envelopes.map(({ connection, entry: e }) => [
+    connection,
+    e.ts,
+    e.command,
+    e.target,
+    e.side_effect_tier,
+    String(e.success),
+    shortId(e.id),
+    shortId(e.recovery_ref)
+  ]);
+  return renderTable(rows, headers);
+}
+function briefifyShow(entry) {
+  const { metadata, redacted_query, ...rest } = entry;
+  return rest;
+}
+function renderEntryTable(entry) {
+  const lines = [];
+  if (entry.id !== undefined)
+    lines.push(`Id:                ${entry.id}`);
+  if (entry.ts !== undefined)
+    lines.push(`Ts:                ${entry.ts}`);
+  if (entry.session_id !== undefined)
+    lines.push(`Session id:        ${entry.session_id}`);
+  if (entry.engine !== undefined)
+    lines.push(`Engine:            ${entry.engine}`);
+  if (entry.command !== undefined)
+    lines.push(`Command:           ${entry.command}`);
+  if (entry.side_effect_tier !== undefined)
+    lines.push(`Side effect tier:  ${entry.side_effect_tier}`);
+  if (entry.target !== undefined)
+    lines.push(`Target:            ${entry.target}`);
+  if (entry.success !== undefined)
+    lines.push(`Success:           ${entry.success}`);
+  if (entry.recovery_ref !== undefined)
+    lines.push(`Recovery ref:      ${entry.recovery_ref}`);
+  if (entry.redacted_query !== undefined)
+    lines.push(`Redacted query:    ${entry.redacted_query}`);
+  if (entry.redacted_sql !== undefined)
+    lines.push(`Redacted SQL:      ${entry.redacted_sql}`);
+  if (entry.error !== undefined)
+    lines.push(`Error:             ${entry.error}`);
+  if (entry.metadata !== undefined)
+    lines.push(`Metadata:          ${JSON.stringify(entry.metadata)}`);
+  return lines.join(`
+`);
+}
+function renderShowResult(hit, opts) {
+  if (opts.format === "json") {
+    const entryView = opts.brief ? briefifyShow(hit.entry) : hit.entry;
+    const payload = opts.all ? { connection: hit.connection, entry: entryView } : entryView;
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    if (opts.all)
+      console.log(`Connection: ${hit.connection}`);
+    console.log(renderEntryTable(opts.brief ? briefifyShow(hit.entry) : hit.entry));
+  }
+}
+function briefifyHealth(h) {
+  return { enabled: h.enabled, lastWrite: h.lastWrite, rotationUsage: h.rotationUsage };
+}
+function formatBytes(n) {
+  if (n < 1024)
+    return `${n} B`;
+  if (n < 1024 * 1024)
+    return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+function renderHealthTable(h) {
+  const sizePct = Math.round(h.rotationUsage.bytes.pct);
+  const entriesPct = Math.round(h.rotationUsage.entries.pct);
+  const lastWrite = h.lastWrite ? `${h.lastWrite.ts} (${h.lastWrite.success ? "success" : "failed"}${h.lastWrite.error ? `: ${h.lastWrite.error}` : ""})` : MISSING_PLACEHOLDER;
+  const lastError = h.lastError ? `${h.lastError.ts} ${h.lastError.message}` : MISSING_PLACEHOLDER;
+  const lastRotation = h.rotation.lastRotatedAt ? `${h.rotation.lastRotatedAt} (${h.rotation.previousFile ?? MISSING_PLACEHOLDER})` : MISSING_PLACEHOLDER;
+  return [
+    `Enabled:        ${h.enabled}`,
+    `File:           ${h.currentFile}`,
+    `Size:           ${formatBytes(h.currentSizeBytes)} / ${formatBytes(h.rotationUsage.bytes.max)} (${sizePct}%)`,
+    `Entries:        ${h.currentEntryCount} / ${h.rotationUsage.entries.max} (${entriesPct}%)`,
+    `Lock:           ${h.lock.state}${h.lock.heldByPid !== undefined ? ` (pid ${h.lock.heldByPid})` : ""}`,
+    `Last write:     ${lastWrite}`,
+    `Last error:     ${lastError}`,
+    `Session id:     ${h.sessionId ?? MISSING_PLACEHOLDER}`,
+    `Last rotation:  ${lastRotation}`
+  ].join(`
+`);
+}
+function readLineFromStdinWithStderrPrompt(prompt) {
+  return new Promise((resolve5) => {
+    process.stderr.write(prompt);
+    const chunks = [];
+    let data = "";
+    const onData = (chunk) => {
+      chunks.push(chunk);
+      data = Buffer.concat(chunks).toString();
+      const lines = data.split(`
+`);
+      if (lines.length > 1) {
+        process.stdin.pause();
+        process.stdin.removeListener("data", onData);
+        process.stdin.removeListener("end", onEnd);
+        resolve5((lines[0] ?? "").trim());
+      }
+    };
+    const onEnd = () => {
+      process.stdin.removeListener("data", onData);
+      resolve5(data.trim());
+    };
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.resume();
+  });
+}
+async function statAuditFile(file) {
+  try {
+    const s = await stat7(file);
+    const entries = (await readEntries(file)).length;
+    return { entries, size: formatBytes(s.size) };
+  } catch {
+    return null;
+  }
+}
+var auditCommand = new Command("audit").description(t("audit.description"));
+auditCommand.command("tail").description(t("audit.tail.description")).option("--n <number>", `Number of recent entries to show (1..${MAX_TAIL_N})`, String(DEFAULT_TAIL_N)).option("--all", "Merge entries across all connections", false).option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim each entry to ts/command/target/success", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
+  const forAgent = options.forAgent === true;
+  const format = forAgent ? "json" : options.format;
+  const briefSource = command.getOptionValueSource("brief");
+  const briefExplicit = briefSource !== undefined && briefSource !== "default";
+  const brief = briefExplicit ? options.brief === true : forAgent;
+  validateFormat(format, ALLOWED_FORMATS14, "audit tail");
+  const n = parseTailN(options.n);
+  const configPath = resolveConfigPath(command, options);
+  const config = await configModule.read(configPath);
+  if (isAuditDisabled(config))
+    emitDisabledAndExit0();
+  const { auditDir, auditFile } = await resolveAuditPaths(configPath, config);
+  if (options.all === true) {
+    const conns = await discoverConnections(auditDir);
+    const byConn = new Map;
+    for (const c of conns) {
+      const merged = [];
+      for (const f of c.files) {
+        const part = await readEntries(f);
+        merged.push(...part);
+      }
+      byConn.set(c.connection, merged);
+    }
+    const envelopes = mergeByTimestamp(byConn).slice(-n);
+    if (format === "json") {
+      const payload = envelopes.map((e) => ({
+        connection: e.connection,
+        entry: brief ? briefify(e.entry) : e.entry
+      }));
+      console.log(JSON.stringify(payload, null, 2));
+    } else if (envelopes.length === 0) {
+      console.error(t("audit.no_entries"));
+    } else {
+      console.log(renderTailAllTable(envelopes));
+    }
+    return;
+  }
+  const entries = await readEntries(auditFile, { include_rotated: true });
+  const tail = tailEntries(entries, n);
+  if (format === "json") {
+    const payload = brief ? tail.map(briefify) : tail;
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (tail.length === 0) {
+    console.error(t("audit.no_entries"));
+  } else {
+    console.log(renderTailTable(tail));
+  }
+});
+auditCommand.command("show [id]").description(t("audit.show.description")).option("--all", "Search across all connections", false).option("--recovery-ref <ref>", "Look up by entry.recovery_ref (exact match)").option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim metadata + redacted_query", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (id, options, command) => {
+  if (id && options.recoveryRef) {
+    console.error(t("audit.show_mutex_violation"));
+    process.exit(1);
+  }
+  if (!id && !options.recoveryRef) {
+    console.error(t("audit.show_mutex_violation"));
+    process.exit(1);
+  }
+  const forAgent = options.forAgent === true;
+  const format = forAgent ? "json" : options.format;
+  const briefSource = command.getOptionValueSource("brief");
+  const briefExplicit = briefSource !== undefined && briefSource !== "default";
+  const brief = briefExplicit ? options.brief === true : forAgent;
+  validateFormat(format, ALLOWED_FORMATS14, "audit show");
+  const configPath = resolveConfigPath(command, options);
+  const config = await configModule.read(configPath);
+  if (isAuditDisabled(config))
+    emitDisabledAndExit0();
+  const { auditDir, auditFile, connectionName } = await resolveAuditPaths(configPath, config);
+  const all = options.all === true;
+  if (options.recoveryRef) {
+    const ref = String(options.recoveryRef);
+    const matches2 = [];
+    if (all) {
+      const conns = await discoverConnections(auditDir);
+      for (const c of conns) {
+        for (const f of c.files) {
+          for (const e of await readEntries(f)) {
+            if (e.recovery_ref === ref)
+              matches2.push({ connection: c.connection, entry: e });
+          }
+        }
+      }
+    } else {
+      for (const e of await readEntries(auditFile, { include_rotated: true })) {
+        if (e.recovery_ref === ref)
+          matches2.push({ connection: connectionName, entry: e });
+      }
+    }
+    if (matches2.length === 0) {
+      console.error(t_vars("audit.show_recovery_no_match", { ref }));
+      process.exit(1);
+    }
+    if (matches2.length > 1) {
+      console.error(t_vars("audit.show_recovery_ambiguous", {
+        ref,
+        count: String(matches2.length)
+      }));
+      process.exit(1);
+    }
+    renderShowResult(matches2[0], { all, format, brief });
+    return;
+  }
+  const lookup = String(id);
+  if (lookup.length < PREFIX_MIN) {
+    console.error(t("audit.show_prefix_too_short"));
+    process.exit(1);
+  }
+  const matches = [];
+  if (all) {
+    const conns = await discoverConnections(auditDir);
+    for (const c of conns) {
+      for (const f of c.files) {
+        for (const e of await readEntries(f)) {
+          if (e.id === lookup || e.id.startsWith(lookup))
+            matches.push({ connection: c.connection, entry: e });
+        }
+      }
+    }
+  } else {
+    for (const e of await readEntries(auditFile, { include_rotated: true })) {
+      if (e.id === lookup || e.id.startsWith(lookup))
+        matches.push({ connection: connectionName, entry: e });
+    }
+  }
+  if (matches.length === 0) {
+    console.error(t_vars("audit.show_no_match", { prefix: lookup }));
+    process.exit(1);
+  }
+  if (matches.length > 1) {
+    console.error(t_vars("audit.show_ambiguous", {
+      prefix: lookup,
+      count: String(matches.length)
+    }));
+    process.exit(1);
+  }
+  renderShowResult(matches[0], { all, format, brief });
+});
+auditCommand.command("clear").description(t("audit.clear.description")).option("--yes", "Skip confirmation prompt and delete immediately", false).action(async (options, command) => {
+  const configPath = resolveConfigPath(command, options);
+  const config = await configModule.read(configPath);
+  const { auditFile, connectionName } = await resolveAuditPaths(configPath, config);
+  const rotatedFile = `${auditFile}.1`;
+  const lockFile = `${auditFile}.lock`;
+  const currentInfo = await statAuditFile(auditFile);
+  const rotatedInfo = await statAuditFile(rotatedFile);
+  if (currentInfo === null && rotatedInfo === null) {
+    process.stderr.write(t("audit.clear.summary_nothing") + `
+`);
+    process.exit(0);
+  }
+  if (options.yes !== true) {
+    if (!process.stdin.isTTY) {
+      console.error(t("audit.clear.requires_tty_or_yes"));
+      process.exit(1);
+    }
+    process.stderr.write(t_vars("audit.clear.prompt_header", { conn: connectionName }) + `
+`);
+    if (currentInfo) {
+      process.stderr.write(t_vars("audit.clear.prompt_file_line", {
+        file: auditFile,
+        entries: String(currentInfo.entries),
+        size: currentInfo.size
+      }) + `
+`);
+    }
+    if (rotatedInfo) {
+      process.stderr.write(t_vars("audit.clear.prompt_file_line", {
+        file: rotatedFile,
+        entries: String(rotatedInfo.entries),
+        size: rotatedInfo.size
+      }) + `
+`);
+    }
+    const answer = await readLineFromStdinWithStderrPrompt(t("audit.clear.prompt_continue"));
+    const lower = answer.toLowerCase();
+    const proceed = lower === "y" || lower === "yes";
+    if (!proceed) {
+      process.stderr.write(t("audit.clear.summary_nothing") + `
+`);
+      process.exit(0);
+    }
+  }
+  let cleared = 0;
+  try {
+    if (currentInfo)
+      cleared += currentInfo.entries;
+    if (rotatedInfo)
+      cleared += rotatedInfo.entries;
+    await rm3(auditFile, { force: true });
+    await rm3(rotatedFile, { force: true });
+    await rm3(lockFile, { force: true });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(t_vars("audit.clear.summary_failed", { message: msg }) + `
+`);
+    process.exit(1);
+  }
+  process.stderr.write(t_vars("audit.clear.summary_cleared", {
+    count: String(cleared),
+    conn: connectionName
+  }) + `
+`);
+  process.exit(0);
+});
+auditCommand.command("health").description(t("audit.health.description")).option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim to enabled / lastWrite / rotationUsage", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
+  const forAgent = options.forAgent === true;
+  const format = forAgent ? "json" : options.format;
+  const briefSource = command.getOptionValueSource("brief");
+  const briefExplicit = briefSource !== undefined && briefSource !== "default";
+  const brief = briefExplicit ? options.brief === true : forAgent;
+  validateFormat(format, ALLOWED_FORMATS14, "audit health");
+  const configPath = resolveConfigPath(command, options);
+  const config = await configModule.read(configPath);
+  const logger = await getAuditLogger(config, configPath);
+  const health = logger.getHealth();
+  if (format === "json") {
+    const payload = brief ? briefifyHealth(health) : health;
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (brief) {
+    const sizePct = Math.round(health.rotationUsage.bytes.pct);
+    const entriesPct = Math.round(health.rotationUsage.entries.pct);
+    const lastWriteLine = health.lastWrite ? `${health.lastWrite.ts} (${health.lastWrite.success ? "success" : "failed"})` : MISSING_PLACEHOLDER;
+    console.log(`Enabled:        ${health.enabled}`);
+    console.log(`Last write:     ${lastWriteLine}`);
+    console.log(`Rotation usage: ${sizePct}% bytes, ${entriesPct}% entries`);
+  } else {
+    console.log(renderHealthTable(health));
+  }
+});
+
 // src/commands/doctor.ts
 init_colors();
 init_config();
@@ -35880,7 +38198,8 @@ init_config_v2();
 init_config_binding();
 init_schema_path();
 init_config();
-import { join as join23 } from "path";
+init_integration_helper();
+import { join as join26 } from "path";
 import { resolveSrv as resolveSrv2 } from "dns/promises";
 function requireSqlConnection9(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
@@ -35888,7 +38207,7 @@ function requireSqlConnection9(connection) {
   }
   return connection;
 }
-var ALLOWED_FORMATS13 = ["text", "json"];
+var ALLOWED_FORMATS15 = ["text", "json"];
 var SENSITIVE_PATTERNS = [
   "password",
   "passwd",
@@ -35960,7 +38279,7 @@ var runDoctorChecks = {
     }
   },
   async checkConfigExists(configPath, existsFn) {
-    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join23(configPath, "config.json")).exists();
+    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join26(configPath, "config.json")).exists();
     return {
       group: "Configuration",
       label: "Config exists",
@@ -36117,7 +38436,7 @@ var runDoctorChecks = {
   async checkV2Config(configPath) {
     const results = [];
     const storagePath = await resolveConfigStoragePath(configPath);
-    const configFile = Bun.file(join23(storagePath, "config.json"));
+    const configFile = Bun.file(join26(storagePath, "config.json"));
     if (!await configFile.exists())
       return results;
     let raw;
@@ -36157,7 +38476,7 @@ var runDoctorChecks = {
     }
     for (const [name, conn] of Object.entries(config.connections)) {
       if (conn.envFile) {
-        const envPath = join23(storagePath, conn.envFile);
+        const envPath = join26(storagePath, conn.envFile);
         const exists = await Bun.file(envPath).exists();
         results.push({
           group: "Configuration",
@@ -36302,7 +38621,7 @@ async function collectElasticsearchDoctorResults(config) {
   return results;
 }
 var doctorCommand = new Command("doctor").description("Run diagnostic checks on dbcli configuration, environment, and connection").option("--format <type>", "Output format: text, json", "text").action(async (options) => {
-  validateFormat(options.format, ALLOWED_FORMATS13, "doctor");
+  validateFormat(options.format, ALLOWED_FORMATS15, "doctor");
   const logger = getLogger();
   const results = [];
   const configPath = resolveConfigPath(doctorCommand);
@@ -36376,7 +38695,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
           }
           try {
             const schemaConnName = await getSchemaIsolationConnectionName(configPath);
-            const indexPath = join23(resolveSchemaPath(storagePath, schemaConnName), "index.json");
+            const indexPath = join26(resolveSchemaPath(storagePath, schemaConnName), "index.json");
             const indexFile = Bun.file(indexPath);
             let indexParsed = null;
             if (await indexFile.exists()) {
@@ -36407,6 +38726,17 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
     }
   }
   const hasError = results.some((r) => r.status === "error");
+  try {
+    const config = await configModule.read(configPath);
+    await writeAuditEntry(config, "doctor", options, {
+      success: !hasError,
+      target: "*",
+      metadata: {
+        error_count: results.filter((r) => r.status === "error").length,
+        warn_count: results.filter((r) => r.status === "warn").length
+      }
+    });
+  } catch {}
   if (options.format === "json") {
     console.log(JSON.stringify({ results, hasError }, null, 2));
   } else {
@@ -36419,7 +38749,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
 
 // src/commands/completion.ts
 init_colors();
-import { join as join24 } from "path";
+import { join as join27 } from "path";
 import { homedir as homedir3 } from "os";
 function extractCommands(program2) {
   return program2.commands.map((cmd) => ({
@@ -36521,11 +38851,11 @@ function getInstallPath2(shell) {
   const home = homedir3();
   switch (shell) {
     case "bash":
-      return join24(home, ".bashrc");
+      return join27(home, ".bashrc");
     case "zsh":
-      return join24(home, ".zshrc");
+      return join27(home, ".zshrc");
     case "fish":
-      return join24(home, ".config", "fish", "completions", "dbcli.fish");
+      return join27(home, ".config", "fish", "completions", "dbcli.fish");
     default:
       throw new Error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
   }
@@ -36545,7 +38875,7 @@ var MARKER_END = "# <<< dbcli completion <<<";
 async function installCompletion(shell, script) {
   const targetPath = getInstallPath2(shell);
   if (shell === "fish") {
-    const dir = join24(homedir3(), ".config", "fish", "completions");
+    const dir = join27(homedir3(), ".config", "fish", "completions");
     await Bun.$`mkdir -p ${dir}`.quiet();
     await Bun.file(targetPath).write(script);
     console.log(colors.success(`\u2713 Fish completion installed to ${targetPath}`));
@@ -36778,7 +39108,7 @@ ${t("upgrade.failed")}`));
 init_config();
 init_adapters();
 import { createInterface as createInterface2 } from "readline";
-import { join as join25 } from "path";
+import { join as join28 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/core/repl/types.ts
@@ -37123,7 +39453,7 @@ function isKnownCommand(name) {
 
 // src/core/repl/history-manager.ts
 import { existsSync, readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2 } from "fs";
-import { dirname as dirname8 } from "path";
+import { dirname as dirname10 } from "path";
 var DEFAULT_MAX = 1000;
 
 class HistoryManager {
@@ -37151,7 +39481,7 @@ class HistoryManager {
     return this.entries;
   }
   async save() {
-    const dir = dirname8(this.filePath);
+    const dir = dirname10(this.filePath);
     if (!existsSync(dir)) {
       mkdirSync2(dir, { recursive: true });
     }
@@ -37509,7 +39839,7 @@ function requireSqlConnection10(connection) {
   }
   return connection;
 }
-var HISTORY_PATH = join25(homedir4(), ".dbcli_history");
+var HISTORY_PATH = join28(homedir4(), ".dbcli_history");
 var MONGO_COMPLETION_EAGER_THRESHOLD = 20;
 async function populateMongoColumns(mongoAdapter, collectionNames, threshold = MONGO_COMPLETION_EAGER_THRESHOLD) {
   const columnsByTable = {};
@@ -38496,7 +40826,7 @@ init_config();
 init_errors();
 init_message_loader();
 init_config_binding();
-import { join as join26 } from "path";
+import { join as join29 } from "path";
 async function switchDefault(configPath, name, config) {
   if (!config.connections[name]) {
     const available = Object.keys(config.connections).join(", ");
@@ -38519,7 +40849,7 @@ function listConnectionsForDisplay(config) {
 }
 async function ensureV2Config(configPath) {
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join26(storagePath, "config.json"));
+  const configFile = Bun.file(join29(storagePath, "config.json"));
   const legacyFile = Bun.file(configPath);
   if (!await configFile.exists() && !await legacyFile.exists()) {
     throw new ConfigError(t("init.config_not_found"));
@@ -38544,7 +40874,8 @@ async function ensureV2Config(configPath) {
         schema: v1Config.schema || {},
         schemas: { default: v1Config.schema || {} },
         metadata: v1Config.metadata || { version: "1.0" },
-        blacklist: v1Config.blacklist || { tables: [], columns: {} }
+        blacklist: v1Config.blacklist || { tables: [], columns: {} },
+        audit: v1Config.audit
       };
     }
     return readV2Config(storagePath);
@@ -38582,7 +40913,7 @@ var useCommand = new Command("use").description("Switch or display the default d
 
 // src/cli.ts
 init_config();
-import { join as join27 } from "path";
+import { join as join30 } from "path";
 var _bgVersionCheckResult;
 function shouldSkipBackgroundChecks() {
   return process.env.DBCLI_NO_UPDATE_CHECK === "1" || process.env.DBCLI_NO_UPDATE_CHECK === "true" || false;
@@ -38611,7 +40942,7 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
       try {
         let cache = null;
         try {
-          const cacheFile = Bun.file(join27(configPath, "version-check.json"));
+          const cacheFile = Bun.file(join30(configPath, "version-check.json"));
           if (await cacheFile.exists()) {
             cache = await cacheFile.json();
           }
@@ -38659,7 +40990,7 @@ program2.command("plan <sql>").description("Analyze SQL risk without executing")
 program2.command("q <name>").description(t("q.description")).option("--format <type>", "Output format: table, json, csv, html", "table").option("--ui", "Show interactive dashboard in browser", false).option("--no-limit", "Disable size guard wrap (LIMIT 1000)").option("--dry-run", "Show final SQL + bind values; do not execute").option("--param <kv>", "Pass parameter as key=value (repeatable)", (val, prev = []) => prev.concat([val]), []).option("--param-file <path>", "JSON file containing param values").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (name, options, command) => {
   await qCommand(name, options, command);
 });
-program2.command("insert <table>").description(t("insert.description")).option("--data <json>", "JSON object to insert").option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
+program2.command("insert <table>").description(t("insert.description")).option("--data <json>", "JSON object to insert").option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--plan", "Analyze risk without connecting or executing").option("--format <type>", "Output format for --plan: text or json", "text").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
   try {
     await insertCommand(table, options, command);
   } catch (error) {
@@ -38671,7 +41002,7 @@ program2.command("insert <table>").description(t("insert.description")).option("
     process.exit(1);
   }
 });
-program2.command("update <table>").description(t("update.description")).option("--where <condition>", 'WHERE clause (required, e.g. "id=1")').option("--set <json>", `JSON with fields to update (required, e.g. '{"name":"Bob"}')`).option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
+program2.command("update <table>").description(t("update.description")).option("--where <condition>", 'WHERE clause (required, e.g. "id=1")').option("--set <json>", `JSON with fields to update (required, e.g. '{"name":"Bob"}')`).option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--plan", "Analyze risk without connecting or executing").option("--format <type>", "Output format for --plan: text or json", "text").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
   try {
     await updateCommand(table, options, command);
   } catch (error) {
@@ -38683,7 +41014,7 @@ program2.command("update <table>").description(t("update.description")).option("
     process.exit(1);
   }
 });
-program2.command("delete <table>").description(t("delete.description")).option("--where <condition>", 'WHERE clause (required, e.g. "id=1")').option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
+program2.command("delete <table>").description(t("delete.description")).option("--where <condition>", 'WHERE clause (required, e.g. "id=1")').option("--dry-run", "Show generated SQL without executing").option("--force", "Skip confirmation prompt").option("--plan", "Analyze risk without connecting or executing").option("--format <type>", "Output format for --plan: text or json", "text").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(async (table, options, command) => {
   try {
     await deleteCommand(table, options, command);
   } catch (error) {
@@ -38721,6 +41052,7 @@ program2.addCommand(reportCommand);
 program2.addCommand(guideCommand);
 program2.addCommand(recoveryCommand);
 program2.addCommand(recoverCommand);
+program2.addCommand(auditCommand);
 program2.addCommand(doctorCommand);
 program2.addCommand(completionCommand);
 program2.addCommand(upgradeCommand);