@carllee1983/dbcli 1.44.1 → 1.45.0

package/dist/cli.mjs

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.44.1",
+    version: "1.45.0",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {
@@ -125,6 +125,7 @@ var init_package = __esm(() => {
       "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",
+      "contract:check": "bun run scripts/check-cli-contract.ts",
       "skill:check": "bun run scripts/check-skill-parity.ts",
       "platform:check": "bun run scripts/check-platform-parity.ts",
       "agent-core:check": "bun run scripts/check-agent-core-purity.ts",
@@ -2409,6 +2410,308 @@ var init_version_check = __esm(() => {
   STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 });
 
+// src/agent-core/errors.ts
+var ConfigError;
+var init_errors = __esm(() => {
+  ConfigError = class ConfigError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ConfigError";
+      if (Error.captureStackTrace)
+        Error.captureStackTrace(this, ConfigError);
+    }
+  };
+});
+
+// src/utils/errors.ts
+var EnvParseError;
+var init_errors2 = __esm(() => {
+  init_errors();
+  EnvParseError = class EnvParseError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "EnvParseError";
+      if (Error.captureStackTrace) {
+        Error.captureStackTrace(this, EnvParseError);
+      }
+    }
+  };
+});
+
+// src/core/config-mutation-guard.ts
+function assertConfigMutationApproved() {
+  if (process.env.DBCLI_AGENT_MODE !== "1")
+    return;
+  throw new ConfigError("Agent mode blocks configuration, permission, and credential changes. A human or administrator must run the approved workflow outside agent mode.");
+}
+var init_config_mutation_guard = __esm(() => {
+  init_errors2();
+});
+
+// src/core/config-integrity.ts
+import { createHash, randomUUID } from "crypto";
+import { chmod, lstat, mkdir, rename, unlink } from "fs/promises";
+import { dirname, join, resolve } from "path";
+function integrityPath(storagePath, recordName = INTEGRITY_FILE) {
+  return join(storagePath, recordName);
+}
+function hash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function protectedPath(storagePath, protectedFileName) {
+  return resolve(join(storagePath, protectedFileName));
+}
+function anchorPathFor(protectedFilePath) {
+  const anchorDirectory = process.env.DBCLI_CONFIG_INTEGRITY_ANCHOR_DIR?.trim();
+  if (!anchorDirectory)
+    return null;
+  const key = createHash("sha256").update(protectedFilePath).digest("hex");
+  return join(resolve(anchorDirectory), `${key}.json`);
+}
+async function bestEffortSecureMode(path, mode) {
+  try {
+    await chmod(path, mode);
+  } catch {}
+}
+async function assertAgentReadableFile(path, description = "config") {
+  if (process.env.DBCLI_AGENT_MODE !== "1")
+    return;
+  try {
+    const fileStat = await lstat(path);
+    if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+      throw new ConfigError(`Agent mode refuses a non-regular ${description} file: ${path}. Run the human/admin setup workflow to provision it.`);
+    }
+    if ((fileStat.mode & 18) !== 0) {
+      throw new ConfigError(`Agent mode refuses a group/world-writable config: ${path}. Run the human/admin setup workflow to secure it.`);
+    }
+  } catch (error) {
+    if (error instanceof ConfigError)
+      throw error;
+    throw new ConfigError(`Agent mode refuses an unreadable ${description} file: ${path}`);
+  }
+}
+async function writeProtectedFileWithIntegrity(storagePath, protectedFileName, protectedContent, recordName) {
+  await mkdir(storagePath, { recursive: true });
+  const protectedFilePath = protectedPath(storagePath, protectedFileName);
+  const localPath = integrityPath(storagePath, recordName);
+  const anchorPath = anchorPathFor(protectedFilePath);
+  const record = {
+    version: 1,
+    configSha256: hash(protectedContent),
+    updatedAt: new Date().toISOString(),
+    targetPath: protectedFilePath
+  };
+  const recordContent = JSON.stringify(record, null, 2);
+  const suffix = `${process.pid}-${randomUUID()}`;
+  const protectedTemporary = `${protectedFilePath}.tmp-${suffix}`;
+  const localTemporary = `${localPath}.tmp-${suffix}`;
+  const anchorTemporary = anchorPath ? `${anchorPath}.tmp-${suffix}` : null;
+  const published = [];
+  try {
+    const [protectedSnapshot, localSnapshot, anchorSnapshot] = await Promise.all([
+      snapshot(protectedFilePath),
+      snapshot(localPath),
+      anchorPath ? snapshot(anchorPath) : Promise.resolve(null)
+    ]);
+    await Bun.write(protectedTemporary, protectedContent);
+    await Bun.write(localTemporary, recordContent);
+    if (anchorPath && anchorTemporary) {
+      await mkdir(dirname(anchorPath), { recursive: true });
+      await Bun.write(anchorTemporary, recordContent);
+    }
+    const publish = async (temporary, previous) => {
+      await rename(temporary, previous.path);
+      published.push(previous);
+    };
+    if (anchorTemporary && anchorPath) {
+      await publish(anchorTemporary, anchorSnapshot ?? { path: anchorPath, content: null });
+    }
+    await publish(localTemporary, localSnapshot);
+    await publish(protectedTemporary, protectedSnapshot);
+  } catch (error) {
+    for (const publishedFile of published.reverse()) {
+      await restore(publishedFile).catch(() => {
+        return;
+      });
+    }
+    throw error;
+  } finally {
+    await unlink(protectedTemporary).catch(() => {
+      return;
+    });
+    await unlink(localTemporary).catch(() => {
+      return;
+    });
+    if (anchorTemporary)
+      await unlink(anchorTemporary).catch(() => {
+        return;
+      });
+  }
+  if (anchorPath) {
+    await bestEffortSecureMode(dirname(anchorPath), 448);
+    await bestEffortSecureMode(anchorPath, 384);
+  }
+  await bestEffortSecureMode(storagePath, 448);
+  await bestEffortSecureMode(protectedFilePath, 384);
+  await bestEffortSecureMode(localPath, 384);
+}
+async function snapshot(path) {
+  const file = Bun.file(path);
+  return { path, content: await file.exists() ? await file.text() : null };
+}
+async function restore(snapshot2) {
+  if (snapshot2.content === null) {
+    await unlink(snapshot2.path).catch(() => {
+      return;
+    });
+    return;
+  }
+  const temporary = `${snapshot2.path}.rollback-${process.pid}-${randomUUID()}`;
+  await Bun.write(temporary, snapshot2.content);
+  await rename(temporary, snapshot2.path);
+}
+async function writeConfigWithIntegrity(storagePath, configContent) {
+  await writeProtectedFileWithIntegrity(storagePath, "config.json", configContent, INTEGRITY_FILE);
+}
+async function writeBindingWithIntegrity(projectPath, bindingContent) {
+  await writeProtectedFileWithIntegrity(projectPath, "config.json", bindingContent, ".binding-integrity.json");
+}
+async function assertIntegrityRecord(storagePath, configContent, recordName, protectedFileName, description, options = {}) {
+  if (process.env.DBCLI_AGENT_MODE !== "1")
+    return;
+  const configPath = protectedPath(storagePath, protectedFileName);
+  await assertAgentReadableFile(configPath, description);
+  const verifyRecord = async (path, label) => {
+    const file = Bun.file(path);
+    if (!await file.exists()) {
+      throw new ConfigError(`Agent mode refuses a missing ${label}: ${path}`);
+    }
+    let record;
+    try {
+      await assertAgentReadableFile(path, label);
+      record = await file.json();
+    } catch (error) {
+      if (error instanceof ConfigError)
+        throw error;
+      throw new ConfigError(`Agent mode refuses an unreadable ${label}: ${path}`);
+    }
+    if (record.version !== 1 || typeof record.configSha256 !== "string" || record.configSha256 !== hash(configContent) || record.targetPath !== undefined && record.targetPath !== configPath) {
+      throw new ConfigError(`Agent mode detected direct ${description} tampering or an out-of-band edit: ${configPath}`);
+    }
+  };
+  const anchorPath = anchorPathFor(configPath);
+  if (anchorPath)
+    await verifyRecord(anchorPath, "detached config integrity anchor");
+  const localPath = integrityPath(storagePath, recordName);
+  const localExists = await Bun.file(localPath).exists();
+  if (localExists) {
+    await verifyRecord(localPath, "config integrity record");
+  } else if (options.requireRecord && !anchorPath) {
+    throw new ConfigError(`Agent mode refuses a missing config integrity record: ${localPath}`);
+  }
+}
+async function assertConfigIntegrity(storagePath, configContent, options) {
+  await assertIntegrityRecord(storagePath, configContent, INTEGRITY_FILE, "config.json", "config", options);
+}
+async function assertBindingIntegrity(projectPath, bindingContent, options) {
+  await assertIntegrityRecord(projectPath, bindingContent, ".binding-integrity.json", "config.json", "project binding", options);
+}
+var INTEGRITY_FILE = ".config-integrity.json";
+var init_config_integrity = __esm(() => {
+  init_errors2();
+});
+
+// src/core/config-binding.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdir as mkdir2, unlink as unlink2 } from "fs/promises";
+import { homedir } from "os";
+import { basename, join as join2, resolve as resolve2 } from "path";
+function getDbcliConfigHome() {
+  const configuredHome = process.env.DBCLI_CONFIG_HOME?.trim();
+  if (configuredHome)
+    return configuredHome;
+  return join2(process.env.HOME?.trim() || homedir(), ".config", "dbcli");
+}
+function isProjectConfigBinding(raw) {
+  if (typeof raw !== "object" || raw === null)
+    return false;
+  const candidate = raw;
+  return candidate.version === 3 && typeof candidate.binding === "object" && candidate.binding !== null && candidate.binding.type === "home-storage" && typeof candidate.binding.storagePath === "string" && candidate.binding.storagePath.length > 0 && typeof candidate.binding.projectPath === "string" && candidate.binding.projectPath.length > 0 && typeof candidate.binding.createdAt === "string" && candidate.binding.createdAt.length > 0;
+}
+function getDbcliHomeRoot() {
+  return getDbcliConfigHome();
+}
+function getGlobalConfigPath() {
+  return getDbcliHomeRoot();
+}
+function isGlobalConfigPath(path) {
+  return resolve2(path) === resolve2(getGlobalConfigPath());
+}
+function getProjectStoragePath(projectPath) {
+  const normalizedProjectPath = resolve2(projectPath);
+  const projectName = basename(normalizedProjectPath) || "project";
+  const hash2 = createHash2("sha1").update(normalizedProjectPath).digest("hex").slice(0, 12);
+  return join2(getDbcliHomeRoot(), "projects", `${projectName}-${hash2}`);
+}
+async function readProjectBinding(projectPath) {
+  const configFile = Bun.file(join2(projectPath, BINDING_FILE_NAME));
+  if (!await configFile.exists())
+    return null;
+  try {
+    await assertAgentReadableFile(join2(projectPath, BINDING_FILE_NAME), "project binding");
+    const content = await configFile.text();
+    const raw = JSON.parse(content);
+    if (!isProjectConfigBinding(raw))
+      return null;
+    await assertBindingIntegrity(projectPath, content, { requireRecord: true });
+    return raw;
+  } catch (error) {
+    if (error instanceof ConfigError)
+      throw error;
+    return null;
+  }
+}
+async function resolveConfigStoragePath(path) {
+  const binding = await readProjectBinding(path);
+  return binding?.binding.storagePath ?? path;
+}
+async function writeProjectBinding(projectPath, storagePath = getProjectStoragePath(projectPath)) {
+  assertConfigMutationApproved();
+  const binding = {
+    version: 3,
+    binding: {
+      type: "home-storage",
+      storagePath,
+      projectPath: resolve2(projectPath),
+      createdAt: new Date().toISOString()
+    }
+  };
+  await mkdir2(projectPath, { recursive: true });
+  await mkdir2(storagePath, { recursive: true });
+  const content = JSON.stringify(binding, null, 2);
+  await writeBindingWithIntegrity(projectPath, content);
+  return binding;
+}
+async function migrateLegacyProjectEnvLocal(projectPath, storagePath = getProjectStoragePath(projectPath)) {
+  assertConfigMutationApproved();
+  const projectEnvPath = join2(projectPath, ".env.local");
+  const projectEnvFile = Bun.file(projectEnvPath);
+  if (!await projectEnvFile.exists())
+    return;
+  const storageEnvPath = join2(storagePath, ".env.local");
+  await mkdir2(storagePath, { recursive: true });
+  if (!await Bun.file(storageEnvPath).exists()) {
+    await Bun.file(storageEnvPath).write(await projectEnvFile.text());
+  }
+  await unlink2(projectEnvPath);
+}
+var BINDING_FILE_NAME = "config.json";
+var init_config_binding = __esm(() => {
+  init_config_mutation_guard();
+  init_config_integrity();
+  init_errors2();
+});
+
 // src/utils/config-path.ts
 function resolveConfigPath(command, options, fallback = ".dbcli") {
   for (let current = command;current; current = current.parent ?? undefined) {
@@ -2420,11 +2723,25 @@ function resolveConfigPath(command, options, fallback = ".dbcli") {
       }
     }
   }
+  if (typeof options?.config === "string" && options.config.length > 0 && options.config !== fallback) {
+    return options.config;
+  }
+  for (let current = command;current; current = current.parent ?? undefined) {
+    const source = current.getOptionValueSource("global");
+    if (source && source !== "default" && current.opts().global === true) {
+      return getGlobalConfigPath();
+    }
+  }
+  if (options?.global === true)
+    return getGlobalConfigPath();
   if (typeof options?.config === "string" && options.config.length > 0) {
     return options.config;
   }
   return fallback;
 }
+var init_config_path = __esm(() => {
+  init_config_binding();
+});
 
 // resources/lang/en/messages.json
 var messages_default;
@@ -2445,6 +2762,7 @@ var init_messages = __esm(() => {
       connection_success: "\u2713 Database connection successful",
       connection_failed: "\u2717 Database connection failed",
       config_saved: "Configuration saved to .dbcli",
+      config_saved_global: "Global configuration saved to {path}",
       config_exists_overwrite: "Configuration file .dbcli already exists. Overwrite? (y/n): ",
       cancelled: "Cancelled. Configuration not changed.",
       skip_test_env_ref: "Skipping connection test in env-ref mode",
@@ -2728,6 +3046,7 @@ var init_messages2 = __esm(() => {
       connection_success: "\u2713 \u8CC7\u6599\u5EAB\u9023\u63A5\u6210\u529F",
       connection_failed: "\u2717 \u8CC7\u6599\u5EAB\u9023\u63A5\u5931\u6557",
       config_saved: "\u914D\u7F6E\u5DF2\u4FDD\u5B58\u81F3 .dbcli",
+      config_saved_global: "\u5168\u57DF\u8A2D\u5B9A\u5DF2\u5132\u5B58\u81F3 {path}",
       config_exists_overwrite: "\u914D\u7F6E\u6A94\u6848 .dbcli \u5DF2\u5B58\u5728\u3002\u662F\u5426\u8986\u84CB\uFF1F (y/n)\uFF1A",
       cancelled: "\u5DF2\u53D6\u6D88\u3002\u914D\u7F6E\u672A\u66F4\u6539\u3002",
       skip_test_env_ref: "\u8DF3\u904E\u9023\u7DDA\u6E2C\u8A66\uFF08\u74B0\u5883\u8B8A\u6578\u53C3\u7167\u6A21\u5F0F\uFF09",
@@ -3516,7 +3835,7 @@ function getErrorMap() {
   return overrideErrorMap;
 }
 var overrideErrorMap;
-var init_errors = __esm(() => {
+var init_errors3 = __esm(() => {
   init_en();
   overrideErrorMap = en_default;
 });
@@ -3618,7 +3937,7 @@ var makeIssue = (params) => {
   };
 }, EMPTY_PATH, INVALID, DIRTY = (value) => ({ status: "dirty", value }), OK = (value) => ({ status: "valid", value }), isAborted = (x) => x.status === "aborted", isDirty = (x) => x.status === "dirty", isValid = (x) => x.status === "valid", isAsync = (x) => typeof Promise !== "undefined" && x instanceof Promise;
 var init_parseUtil = __esm(() => {
-  init_errors();
+  init_errors3();
   init_en();
   EMPTY_PATH = [];
   INVALID = Object.freeze({
@@ -4186,7 +4505,7 @@ var handleResult = (ctx, result) => {
 }) => custom((data) => data instanceof cls, params), stringType, numberType, nanType, bigIntType, booleanType, dateType, symbolType, undefinedType, nullType, anyType, unknownType, neverType, voidType, arrayType, objectType, strictObjectType, unionType, discriminatedUnionType, intersectionType, tupleType, recordType, mapType, setType, functionType, lazyType, literalType, enumType, nativeEnumType, promiseType, effectsType, optionalType, nullableType, preprocessType, pipelineType, ostring = () => stringType().optional(), onumber = () => numberType().optional(), oboolean = () => booleanType().optional(), coerce, NEVER;
 var init_types = __esm(() => {
   init_ZodError();
-  init_errors();
+  init_errors3();
   init_errorUtil();
   init_parseUtil();
   init_util();
@@ -7101,7 +7420,7 @@ __export(exports_external, {
   BRAND: () => BRAND
 });
 var init_external = __esm(() => {
-  init_errors();
+  init_errors3();
   init_parseUtil();
   init_typeAliases();
   init_util();
@@ -7122,7 +7441,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, RedisMaskRuleSchema, RedisConfigSchema, AuditRotationConfigSchema, AuditConfigSchema, DbcliConfigSchema, SqlNamedConnectionSchema, MongoDBNamedConnectionSchema, RedisNamedConnectionSchema, ElasticsearchNamedConnectionSchema, NamedConnectionSchema, DbcliConfigV2Schema;
+var EnvRefSchema, StringOrEnvRef, NumberOrEnvRef, OptStringOrEnvRef, OptNumberOrEnvRef, MongoDBConnectionConfigSchema, SqlConnectionConfigSchema, RedisConnectionConfigSchema, ElasticsearchConnectionConfigSchema, ConnectionConfigSchema, PermissionSchema, EnvironmentLabelSchema, MetadataSchema, BlacklistConfigSchema, RedisMaskRuleSchema, RedisConfigSchema, AuditRotationConfigSchema, AuditConfigSchema, DbcliConfigSchema, SqlNamedConnectionSchema, MongoDBNamedConnectionSchema, RedisNamedConnectionSchema, ElasticsearchNamedConnectionSchema, NamedConnectionSchema, DbcliConfigV2Schema;
 var init_validation = __esm(() => {
   init_zod();
   EnvRefSchema = exports_external.object({
@@ -7178,6 +7497,7 @@ var init_validation = __esm(() => {
     ElasticsearchConnectionConfigSchema
   ]);
   PermissionSchema = exports_external.enum(["query-only", "read-write", "data-admin", "admin"]).default("query-only");
+  EnvironmentLabelSchema = exports_external.string().trim().transform((value) => value || undefined).optional();
   MetadataSchema = exports_external.object({
     createdAt: exports_external.string().datetime().optional(),
     version: exports_external.string().default("1.0"),
@@ -7217,19 +7537,23 @@ var init_validation = __esm(() => {
   });
   SqlNamedConnectionSchema = SqlConnectionConfigSchema.extend({
     permission: PermissionSchema,
-    envFile: exports_external.string().optional()
+    envFile: exports_external.string().optional(),
+    environment: EnvironmentLabelSchema
   });
   MongoDBNamedConnectionSchema = MongoDBConnectionConfigSchema.extend({
     permission: PermissionSchema,
-    envFile: exports_external.string().optional()
+    envFile: exports_external.string().optional(),
+    environment: EnvironmentLabelSchema
   });
   RedisNamedConnectionSchema = RedisConnectionConfigSchema.extend({
     permission: PermissionSchema,
-    envFile: exports_external.string().optional()
+    envFile: exports_external.string().optional(),
+    environment: EnvironmentLabelSchema
   });
   ElasticsearchNamedConnectionSchema = ElasticsearchConnectionConfigSchema.extend({
     permission: PermissionSchema,
-    envFile: exports_external.string().optional()
+    envFile: exports_external.string().optional(),
+    environment: EnvironmentLabelSchema
   });
   NamedConnectionSchema = exports_external.union([
     SqlNamedConnectionSchema,
@@ -7255,34 +7579,6 @@ var init_validation = __esm(() => {
   });
 });
 
-// src/agent-core/errors.ts
-var ConfigError;
-var init_errors2 = __esm(() => {
-  ConfigError = class ConfigError extends Error {
-    constructor(message) {
-      super(message);
-      this.name = "ConfigError";
-      if (Error.captureStackTrace)
-        Error.captureStackTrace(this, ConfigError);
-    }
-  };
-});
-
-// src/utils/errors.ts
-var EnvParseError;
-var init_errors3 = __esm(() => {
-  init_errors2();
-  EnvParseError = class EnvParseError extends Error {
-    constructor(message) {
-      super(message);
-      this.name = "EnvParseError";
-      if (Error.captureStackTrace) {
-        Error.captureStackTrace(this, EnvParseError);
-      }
-    }
-  };
-});
-
 // src/agent-core/env-loader.ts
 import { readFile } from "fs/promises";
 function parseEnvContent(content) {
@@ -7321,7 +7617,7 @@ async function loadEnvFile(filePath) {
   }
 }
 var init_env_loader = __esm(() => {
-  init_errors2();
+  init_errors();
 });
 
 // src/core/env-loader.ts
@@ -7329,123 +7625,129 @@ var init_env_loader2 = __esm(() => {
   init_env_loader();
 });
 
-// src/core/config-binding.ts
-import { createHash } from "crypto";
-import { mkdir, unlink } from "fs/promises";
-import { homedir } from "os";
-import { basename, join as join2, resolve as resolve2 } from "path";
-function isProjectConfigBinding(raw) {
-  if (typeof raw !== "object" || raw === null)
-    return false;
-  const candidate = raw;
-  return candidate.version === 3 && typeof candidate.binding === "object" && candidate.binding !== null && candidate.binding.type === "home-storage" && typeof candidate.binding.storagePath === "string" && candidate.binding.storagePath.length > 0 && typeof candidate.binding.projectPath === "string" && candidate.binding.projectPath.length > 0 && typeof candidate.binding.createdAt === "string" && candidate.binding.createdAt.length > 0;
-}
-function getDbcliHomeRoot() {
-  return DBCLI_HOME_ROOT;
-}
-function getProjectStoragePath(projectPath) {
-  const normalizedProjectPath = resolve2(projectPath);
-  const projectName = basename(normalizedProjectPath) || "project";
-  const hash = createHash("sha1").update(normalizedProjectPath).digest("hex").slice(0, 12);
-  return join2(getDbcliHomeRoot(), "projects", `${projectName}-${hash}`);
-}
-async function readProjectBinding(projectPath) {
-  const configFile = Bun.file(join2(projectPath, BINDING_FILE_NAME));
-  if (!await configFile.exists())
-    return null;
-  try {
-    const raw = JSON.parse(await configFile.text());
-    return isProjectConfigBinding(raw) ? raw : null;
-  } catch {
-    return null;
+// src/utils/levenshtein-distance.ts
+function levenshteinDistance(a, b) {
+  const lenA = a.length;
+  const lenB = b.length;
+  const dp = [];
+  for (let i = 0;i <= lenB; i++) {
+    const row = [];
+    for (let j = 0;j <= lenA; j++) {
+      row[j] = 0;
+    }
+    dp[i] = row;
   }
-}
-async function resolveConfigStoragePath(path2) {
-  const binding = await readProjectBinding(path2);
-  return binding?.binding.storagePath ?? path2;
-}
-async function writeProjectBinding(projectPath, storagePath = getProjectStoragePath(projectPath)) {
-  const binding = {
-    version: 3,
-    binding: {
-      type: "home-storage",
-      storagePath,
-      projectPath: resolve2(projectPath),
-      createdAt: new Date().toISOString()
+  for (let i = 0;i <= lenB; i++) {
+    const row = dp[i];
+    if (row !== undefined) {
+      row[0] = i;
+    }
+  }
+  for (let j = 0;j <= lenA; j++) {
+    const firstRow = dp[0];
+    if (firstRow !== undefined) {
+      firstRow[j] = j;
     }
-  };
-  await mkdir(projectPath, { recursive: true });
-  await mkdir(storagePath, { recursive: true });
-  await Bun.file(join2(projectPath, BINDING_FILE_NAME)).write(JSON.stringify(binding, null, 2));
-  return binding;
-}
-async function migrateLegacyProjectEnvLocal(projectPath, storagePath = getProjectStoragePath(projectPath)) {
-  const projectEnvPath = join2(projectPath, ".env.local");
-  const projectEnvFile = Bun.file(projectEnvPath);
-  if (!await projectEnvFile.exists())
-    return;
-  const storageEnvPath = join2(storagePath, ".env.local");
-  await mkdir(storagePath, { recursive: true });
-  if (!await Bun.file(storageEnvPath).exists()) {
-    await Bun.file(storageEnvPath).write(await projectEnvFile.text());
   }
-  await unlink(projectEnvPath);
+  for (let i = 1;i <= lenB; i++) {
+    const currentRow = dp[i];
+    const prevRow = dp[i - 1];
+    if (!currentRow || !prevRow)
+      continue;
+    for (let j = 1;j <= lenA; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        currentRow[j] = prevRow[j - 1] ?? 0;
+      } else {
+        const sub = (prevRow[j - 1] ?? 0) + 1;
+        const ins = (currentRow[j - 1] ?? 0) + 1;
+        const del = (prevRow[j] ?? 0) + 1;
+        currentRow[j] = Math.min(sub, ins, del);
+      }
+    }
+  }
+  return dp[lenB]?.[lenA] ?? 0;
 }
-var BINDING_FILE_NAME = "config.json", DBCLI_HOME_ROOT;
-var init_config_binding = __esm(() => {
-  DBCLI_HOME_ROOT = join2(homedir(), ".config", "dbcli");
-});
 
 // src/core/config-v2.ts
-import { join as join3 } from "path";
-import { mkdir as mkdir2, rename } from "fs/promises";
+import { join as join4 } from "path";
 function detectConfigVersion(raw) {
   if (typeof raw === "object" && raw !== null && "version" in raw && raw.version === 2 && "connections" in raw) {
     return 2;
   }
   return 1;
 }
+function assertExplicitProductionSelection(resolved, requestedName) {
+  if (resolved.environment !== "production")
+    return;
+  if (requestedName?.trim() === resolved.name)
+    return;
+  throw new ConfigError(`\u9023\u7DDA '${resolved.name}' \u6A19\u8A18\u70BA production\uFF0C\u5FC5\u9808\u660E\u78BA\u4F7F\u7528 --use ${resolved.name}\uFF08\u6216\u8A2D\u5B9A DBCLI_CONNECTION=${resolved.name}\uFF09\u624D\u80FD\u57F7\u884C\u3002`);
+}
+function assertProductionDefaultConfirmation(name2, environment, confirmation) {
+  if (environment !== "production")
+    return;
+  if (confirmation === name2)
+    return;
+  throw new ConfigError(`\u9023\u7DDA '${name2}' \u6A19\u8A18\u70BA production\u3002\u82E5\u8981\u8B8A\u66F4\u9810\u8A2D\u9023\u7DDA\uFF0C\u8ACB\u52A0\u5165 --confirm-production ${name2}\u3002`);
+}
+function findSimilarConnectionNames(requestedName, availableNames) {
+  const requested = requestedName.toLowerCase();
+  const distanceLimit = Math.max(2, Math.floor(requested.length / 3));
+  return availableNames.map((name2) => {
+    const candidate = name2.toLowerCase();
+    const distance = levenshteinDistance(requested, candidate);
+    return {
+      name: name2,
+      distance,
+      isSimilar: candidate.includes(requested) || requested.includes(candidate) || distance <= distanceLimit
+    };
+  }).filter(({ isSimilar }) => isSimilar).sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name)).slice(0, 3).map(({ name: name2 }) => name2);
+}
+function connectionNotFoundMessage(requestedName, availableNames) {
+  const suggestions = findSimilarConnectionNames(requestedName, availableNames);
+  const suggestion = suggestions.length > 0 ? ` \u4F60\u662F\u5426\u8981\u4F7F\u7528\uFF1A${suggestions.join("\u3001")}\uFF1F` : "";
+  return `\u9023\u7DDA '${requestedName}' \u4E0D\u5B58\u5728\u3002${suggestion} \u53EF\u7528\u9023\u7DDA\uFF1A${availableNames.join(", ")}`;
+}
 function resolveConnection(config, name2) {
   const connectionName = name2 ?? config.default;
   const conn = config.connections[connectionName];
   if (!conn) {
-    const available = Object.keys(config.connections).join(", ");
-    throw new ConfigError(`\u9023\u7DDA '${connectionName}' \u4E0D\u5B58\u5728\u3002\u53EF\u7528\u9023\u7DDA\uFF1A${available}`);
+    throw new ConfigError(connectionNotFoundMessage(connectionName, Object.keys(config.connections)));
   }
-  const { permission, envFile, ...connectionFields } = conn;
+  const { permission, envFile, environment, ...connectionFields } = conn;
   return {
     name: connectionName,
     connection: connectionFields,
     permission,
-    envFile
+    envFile,
+    environment
   };
 }
 async function loadConnectionEnv(resolved, basePath) {
   if (resolved.envFile) {
-    const envPath = join3(basePath, resolved.envFile);
+    const envPath = join4(basePath, resolved.envFile);
     await loadEnvFile(envPath);
   }
 }
 async function readV2Config(path2) {
   const storagePath = await resolveConfigStoragePath(path2);
-  const configPath = join3(storagePath, "config.json");
+  const configPath = join4(storagePath, "config.json");
   const file = Bun.file(configPath);
   if (!await file.exists()) {
     throw new ConfigError(`\u627E\u4E0D\u5230 V2 \u8A2D\u5B9A\u6A94\uFF1A${configPath}`);
   }
+  await assertAgentReadableFile(configPath);
   const content = await file.text();
+  await assertConfigIntegrity(storagePath, content, { requireRecord: true });
   const raw = JSON.parse(content);
   return DbcliConfigV2Schema.parse(raw);
 }
 async function writeV2Config(path2, config) {
+  assertConfigMutationApproved();
   DbcliConfigV2Schema.parse(config);
   const storagePath = await resolveConfigStoragePath(path2);
-  const configPath = join3(storagePath, "config.json");
-  const tmpPath = `${configPath}.tmp`;
-  await mkdir2(storagePath, { recursive: true });
   const json = JSON.stringify(config, null, 2);
-  await Bun.write(tmpPath, json);
-  await rename(tmpPath, configPath);
+  await writeConfigWithIntegrity(storagePath, json);
 }
 async function patchConnectionSchema(dbcliPath, connectionName, schema, metadataUpdate) {
   const storagePath = await resolveConfigStoragePath(dbcliPath);
@@ -7465,7 +7767,9 @@ async function patchConnectionSchema(dbcliPath, connectionName, schema, metadata
 }
 var init_config_v2 = __esm(() => {
   init_validation();
-  init_errors3();
+  init_errors2();
+  init_config_mutation_guard();
+  init_config_integrity();
   init_env_loader2();
   init_config_binding();
 });
@@ -7480,15 +7784,26 @@ function trimAppliedLimit(rows, limit) {
 }
 
 // src/agent-core/connection-selector.ts
+function normalizeSelector(value, source) {
+  if (value === undefined)
+    return;
+  const normalized = value.trim();
+  if (normalized === "") {
+    throw new Error(`${source} connection selector cannot be empty`);
+  }
+  return normalized;
+}
 function resolveConnectionSelector(inputs) {
-  if (inputs.root !== undefined && inputs.command !== undefined && inputs.root !== inputs.command) {
-    throw new Error(`Conflicting connection selectors: root value '${inputs.root}' does not match command value '${inputs.command}'`);
+  const root = normalizeSelector(inputs.root, "Root");
+  const command = normalizeSelector(inputs.command, "Command");
+  if (root !== undefined && command !== undefined && root !== command) {
+    throw new Error(`Conflicting connection selectors: root value '${root}' does not match command value '${command}'`);
   }
-  const explicit = inputs.command ?? inputs.root;
+  const explicit = command ?? root;
   if (explicit !== undefined)
     return explicit;
   const environment = inputs.environment?.trim();
-  return environment ? environment : undefined;
+  return environment || undefined;
 }
 function parseConnectionNames(selector) {
   const names = selector.split(",").map((name2) => name2.trim());
@@ -7518,14 +7833,14 @@ function resolveEnvRef(value, fieldName, env = process.env) {
   return resolved;
 }
 var init_env_ref = __esm(() => {
-  init_errors2();
+  init_errors();
 });
 
 // src/agent-core/public.ts
 var init_public = __esm(() => {
   init_env_loader();
   init_env_ref();
-  init_errors2();
+  init_errors();
 });
 
 // node_modules/lru-cache/dist/esm/node/index.min.js
@@ -8165,16 +8480,16 @@ var init_index_min = __esm(() => {
 });
 
 // src/utils/schema-path.ts
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 function resolveSchemaPath(dbcliPath, connectionName) {
   if (!connectionName)
-    return join4(dbcliPath, "schemas");
-  return join4(dbcliPath, "schemas", connectionName);
+    return join5(dbcliPath, "schemas");
+  return join5(dbcliPath, "schemas", connectionName);
 }
 var init_schema_path = () => {};
 
 // src/core/schema-cache.ts
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 
 class SchemaCacheManager {
   cache;
@@ -8200,13 +8515,13 @@ class SchemaCacheManager {
   }
   async initialize() {
     try {
-      const indexPath = join5(this.schemaRoot, "index.json");
+      const indexPath = join6(this.schemaRoot, "index.json");
       const indexFile = Bun.file(indexPath);
       if (await indexFile.exists()) {
         const indexContent = await indexFile.text();
         this.index = JSON.parse(indexContent);
       }
-      const hotPath = join5(this.schemaRoot, "hot-schemas.json");
+      const hotPath = join6(this.schemaRoot, "hot-schemas.json");
       const hotFile = Bun.file(hotPath);
       if (await hotFile.exists()) {
         const hotContent = await hotFile.text();
@@ -8239,7 +8554,7 @@ class SchemaCacheManager {
       return null;
     }
     try {
-      const filePath = join5(this.schemaRoot, tableInfo.file);
+      const filePath = join6(this.schemaRoot, tableInfo.file);
       const file = Bun.file(filePath);
       if (!await file.exists()) {
         console.error(`Cold table file not found: ${tableInfo.file} for table ${tableName}`);
@@ -8294,12 +8609,12 @@ var init_schema_cache = __esm(() => {
 });
 
 // src/core/schema-index.ts
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 class SchemaIndexBuilder {
   static async loadIndex(dbcliPath, connectionName) {
     try {
-      const indexPath = join6(resolveSchemaPath(dbcliPath, connectionName), "index.json");
+      const indexPath = join7(resolveSchemaPath(dbcliPath, connectionName), "index.json");
       const file = Bun.file(indexPath);
       if (!await file.exists()) {
         return null;
@@ -8346,7 +8661,7 @@ class SchemaIndexBuilder {
     try {
       const schemasDir = resolveSchemaPath(dbcliPath, connectionName);
       await this.ensureDir(schemasDir);
-      const indexPath = join6(schemasDir, "index.json");
+      const indexPath = join7(schemasDir, "index.json");
       const indexFile = Bun.file(indexPath);
       await indexFile.write(JSON.stringify(index, null, 2));
     } catch (error) {
@@ -8392,7 +8707,7 @@ var exports_schema_loader = {};
 __export(exports_schema_loader, {
   SchemaLayeredLoader: () => SchemaLayeredLoader
 });
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 
 class SchemaLayeredLoader {
   dbcliPath;
@@ -8459,7 +8774,7 @@ class SchemaLayeredLoader {
   }
   async ensureDirectories() {
     const base = resolveSchemaPath(this.dbcliPath, this.connectionName);
-    const dirs = [base, join7(base, "cold")];
+    const dirs = [base, join8(base, "cold")];
     for (const dir of dirs) {
       try {
         const dirFile = Bun.file(dir);
@@ -8507,7 +8822,7 @@ __export(exports_config, {
   getGlobalConnectionName: () => getGlobalConnectionName,
   configModule: () => configModule
 });
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { mkdir as mkdir3 } from "fs/promises";
 function assertNoConnectionSelectorOnV1(connectionName) {
   if (connectionName === undefined)
@@ -8528,7 +8843,7 @@ async function getSchemaIsolationConnectionName(dbcliPath) {
     const isDirectory = stat?.isDirectory() ?? false;
     if (!isDirectory)
       return;
-    const configJsonPath = join8(storagePath, "config.json");
+    const configJsonPath = join9(storagePath, "config.json");
     const configFile = Bun.file(configJsonPath);
     if (!await configFile.exists())
       return;
@@ -8576,10 +8891,12 @@ function parseEnvPassword(content) {
 var _globalConnectionName, DEFAULT_CONFIG, configModule;
 var init_config = __esm(() => {
   init_validation();
-  init_errors3();
+  init_errors2();
   init_config_v2();
   init_config_binding();
   init_public();
+  init_config_mutation_guard();
+  init_config_integrity();
   DEFAULT_CONFIG = {
     connection: {
       system: "postgresql",
@@ -8607,9 +8924,9 @@ var init_config = __esm(() => {
         const binding = await readProjectBinding(path2);
         const storagePath = await resolveConfigStoragePath(path2);
         if (binding) {
-          const storageConfigExists = await Bun.file(join8(storagePath, "config.json")).exists();
+          const storageConfigExists = await Bun.file(join9(storagePath, "config.json")).exists();
           if (!storageConfigExists) {
-            throw new ConfigError(`Bound dbcli config not found: ${join8(storagePath, "config.json")}`);
+            throw new ConfigError(`Bound dbcli config not found: ${join9(storagePath, "config.json")}`);
           }
         }
         let isDirectory = false;
@@ -8620,17 +8937,20 @@ var init_config = __esm(() => {
           isDirectory = false;
         }
         if (isDirectory) {
-          const configPath = join8(storagePath, "config.json");
+          const configPath = join9(storagePath, "config.json");
           const configFile = Bun.file(configPath);
           const configExists = await configFile.exists();
           if (configExists) {
+            await assertAgentReadableFile(configPath);
             const content = await configFile.text();
+            await assertConfigIntegrity(storagePath, content, { requireRecord: true });
             const config = JSON.parse(content);
             if (detectConfigVersion(config) === 2) {
               const v2Config = DbcliConfigV2Schema.parse(config);
               const resolved = resolveConnection(v2Config, effectiveConnectionName);
+              assertExplicitProductionSelection(resolved, effectiveConnectionName);
               await loadConnectionEnv(resolved, storagePath);
-              const envLocalPath = join8(storagePath, ".env.local");
+              const envLocalPath = join9(storagePath, ".env.local");
               const envLocalFile = Bun.file(envLocalPath);
               let legacyPassword = null;
               if (await envLocalFile.exists()) {
@@ -8667,7 +8987,7 @@ var init_config = __esm(() => {
                   console.warn("Warning: Failed to load layered schema cache, falling back to config.json");
                 }
               }
-              return DbcliConfigSchema.parse({
+              const parsedConfig = DbcliConfigSchema.parse({
                 connection: resolvedConnection,
                 permission: resolved.permission,
                 schema,
@@ -8676,10 +8996,15 @@ var init_config = __esm(() => {
                 audit: v2Config.audit,
                 redis: v2Config.redis
               });
+              return {
+                ...parsedConfig,
+                effectiveConnectionName: resolved.name,
+                ...resolved.environment && { effectiveEnvironment: resolved.environment }
+              };
             }
             assertNoConnectionSelectorOnV1(effectiveConnectionName);
             const resolvedConfig = resolveEnvReferences(config, process.env);
-            const envPath = join8(storagePath, ".env.local");
+            const envPath = join9(storagePath, ".env.local");
             const envFile = Bun.file(envPath);
             if (await envFile.exists()) {
               const envContent = await envFile.text();
@@ -8694,12 +9019,18 @@ var init_config = __esm(() => {
         const file = Bun.file(path2);
         const exists = await file.exists();
         if (exists) {
+          if (process.env.DBCLI_AGENT_MODE === "1") {
+            throw new ConfigError(`Agent mode refuses legacy single-file config: ${path2}. Run the human/admin migration workflow to move it to V2 home storage first.`);
+          }
           assertNoConnectionSelectorOnV1(effectiveConnectionName);
           const content = await file.text();
           const raw = JSON.parse(content);
           const resolved = resolveEnvReferences(raw, process.env);
           return DbcliConfigSchema.parse(resolved);
         }
+        if (process.env.DBCLI_AGENT_MODE === "1") {
+          throw new ConfigError(`Agent mode refuses a missing config: ${path2}. Run the human/admin setup workflow to provision it.`);
+        }
         return { ...DEFAULT_CONFIG };
       } catch (error) {
         if (error instanceof ConfigError)
@@ -8741,6 +9072,7 @@ var init_config = __esm(() => {
     },
     async write(path2, config) {
       try {
+        assertConfigMutationApproved();
         this.validate(config);
         const storagePath = await resolveConfigStoragePath(path2);
         let isDirectory = false;
@@ -8754,9 +9086,8 @@ var init_config = __esm(() => {
           await mkdir3(storagePath, { recursive: true });
           const hasEnvReferences = isEnvReference(config.connection.password);
           if (hasEnvReferences) {
-            const configPath = join8(storagePath, "config.json");
             const configJson = JSON.stringify(config, null, 2);
-            await Bun.file(configPath).write(configJson);
+            await writeConfigWithIntegrity(storagePath, configJson);
           } else {
             const password = config.connection.password;
             const configWithoutPassword = {
@@ -8767,11 +9098,10 @@ var init_config = __esm(() => {
               }
             };
             delete configWithoutPassword.connection.password;
-            const configPath = join8(storagePath, "config.json");
             const configJson = JSON.stringify(configWithoutPassword, null, 2);
-            await Bun.file(configPath).write(configJson);
+            await writeConfigWithIntegrity(storagePath, configJson);
             if (password) {
-              const envPath = join8(storagePath, ".env.local");
+              const envPath = join9(storagePath, ".env.local");
               const envContent = `# Database Credentials - DO NOT commit to git
 
 DBCLI_PASSWORD=${password}
@@ -9888,7 +10218,7 @@ var init_parser = __esm(() => {
 
 // src/core/saved-queries/loader.ts
 import { readdir } from "fs/promises";
-import { join as join9, relative, sep } from "path";
+import { join as join10, relative, sep } from "path";
 async function loadSnippets(opts) {
   const builtin = await walkAndParse(opts.builtinDir, "builtin");
   const shared = await walkAndParse(opts.sharedDir, "shared");
@@ -9955,7 +10285,7 @@ async function collectFiles(root) {
   async function walk(dir) {
     const entries = await readdir(dir, { withFileTypes: true });
     for (const e of entries) {
-      const full = join9(dir, e.name);
+      const full = join10(dir, e.name);
       if (e.isDirectory())
         await walk(full);
       else
@@ -9978,23 +10308,23 @@ var init_loader = __esm(() => {
 });
 
 // src/core/saved-queries/snippet-paths.ts
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 function resolveBuiltinDir() {
   return packageAssetPath("snippets");
 }
 function resolveSnippetDirs(workspaceRoot) {
   return {
     builtinDir: resolveBuiltinDir(),
-    sharedDir: join10(workspaceRoot, ".dbcli-shared", "queries"),
-    localDir: join10(workspaceRoot, ".dbcli", "queries")
+    sharedDir: join11(workspaceRoot, ".dbcli-shared", "queries"),
+    localDir: join11(workspaceRoot, ".dbcli", "queries")
   };
 }
 function snippetKeyToFile(workspaceRoot, key, source) {
   const rel = key.replace(/^@/, "") + ".sql";
   if (source === "builtin")
-    return join10(resolveBuiltinDir(), rel);
+    return join11(resolveBuiltinDir(), rel);
   const dir = source === "shared" ? ".dbcli-shared/queries" : ".dbcli/queries";
-  return join10(workspaceRoot, dir, rel);
+  return join11(workspaceRoot, dir, rel);
 }
 var init_snippet_paths = __esm(() => {
   init_package_root();
@@ -10426,6 +10756,7 @@ var init_skill = __esm(() => {
   init_package_root();
   init_esm();
   init_context();
+  init_config_path();
   REFERENCE_SOURCE_PATH = packageAssetPath("reference.md");
   SUPPORTED_PLATFORMS = [
     "claude",
@@ -10469,6 +10800,7 @@ var init_upgrade = __esm(() => {
   init_esm();
   init_colors();
   init_version_check();
+  init_config_path();
   init_skill();
   init_message_loader();
   init_package();
@@ -10639,7 +10971,7 @@ function parseEnvDatabase(env) {
   return null;
 }
 var init_env_parser = __esm(() => {
-  init_errors3();
+  init_errors2();
 });
 
 // node_modules/@inquirer/core/dist/lib/key.js
@@ -12052,13 +12384,13 @@ var PromisePolyfill;
 var init_promise_polyfill = __esm(() => {
   PromisePolyfill = class PromisePolyfill extends Promise {
     static withResolver() {
-      let resolve3;
+      let resolve4;
       let reject;
       const promise = new Promise((res, rej) => {
-        resolve3 = res;
+        resolve4 = res;
         reject = rej;
       });
-      return { promise, resolve: resolve3, reject };
+      return { promise, resolve: resolve4, reject };
     }
   };
 });
@@ -12097,7 +12429,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve3, reject } = PromisePolyfill.withResolver();
+    const { promise, resolve: resolve4, reject } = PromisePolyfill.withResolver();
     const cancel = () => reject(new CancelPromptError);
     if (signal) {
       const abort = () => reject(new AbortPromptError({ cause: signal.reason }));
@@ -12128,7 +12460,7 @@ function createPrompt(view) {
           try {
             const nextView = view(config, (value) => {
               if (effectsSettled) {
-                resolve3(value);
+                resolve4(value);
               } else {
                 pendingDone = { value };
               }
@@ -12151,7 +12483,7 @@ function createPrompt(view) {
           if (pendingDone !== null) {
             const { value } = pendingDone;
             pendingDone = null;
-            resolve3(value);
+            resolve4(value);
           }
         });
       };
@@ -12267,7 +12599,7 @@ var init_dist7 = __esm(() => {
 
 // src/utils/prompts.ts
 async function readLineFromStdin(prompt = "") {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     if (prompt) {
       process.stdout.write(prompt);
     }
@@ -12282,12 +12614,12 @@ async function readLineFromStdin(prompt = "") {
         process.stdin.pause();
         process.stdin.removeListener("data", onData);
         process.stdin.removeListener("end", onEnd);
-        resolve3((lines[0] ?? "").trim());
+        resolve4((lines[0] ?? "").trim());
       }
     };
     const onEnd = () => {
       process.stdin.removeListener("data", onData);
-      resolve3(data.trim());
+      resolve4(data.trim());
     };
     process.stdin.on("data", onData);
     process.stdin.on("end", onEnd);
@@ -15073,13 +15405,13 @@ var init_adapters = __esm(() => {
 });
 
 // src/commands/init.ts
-import { join as join12 } from "path";
-import { mkdir as mkdir4 } from "fs/promises";
+import { join as join14 } from "path";
+import { mkdir as mkdir5 } from "fs/promises";
 async function checkOverwrite(configPath, shouldPrompt, force) {
   const storagePath = await resolveConfigStoragePath(configPath);
   const fileExists = await Bun.file(configPath).exists();
-  const dirConfigExists = await Bun.file(join12(configPath, "config.json")).exists();
-  const storageConfigExists = await Bun.file(join12(storagePath, "config.json")).exists();
+  const dirConfigExists = await Bun.file(join14(configPath, "config.json")).exists();
+  const storageConfigExists = await Bun.file(join14(storagePath, "config.json")).exists();
   if (!fileExists && !dirConfigExists && !storageConfigExists || force)
     return true;
   if (shouldPrompt) {
@@ -15094,7 +15426,7 @@ async function checkOverwrite(configPath, shouldPrompt, force) {
 }
 async function handleRemove(configPath, name2) {
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join12(storagePath, "config.json"));
+  const configFile = Bun.file(join14(storagePath, "config.json"));
   if (!await configFile.exists()) {
     throw new Error(t("init.config_not_found"));
   }
@@ -15130,7 +15462,7 @@ async function handleRename(configPath, renameArg) {
     throw new Error(t("init.rename_invalid_format"));
   }
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join12(storagePath, "config.json"));
+  const configFile = Bun.file(join14(storagePath, "config.json"));
   if (!await configFile.exists()) {
     throw new Error(t("init.config_not_found"));
   }
@@ -15155,10 +15487,11 @@ async function handleRename(configPath, renameArg) {
   console.log(t_vars("init.connection_renamed", { oldName, newName }));
 }
 async function writeV2InitConfig(configPath, connectionName, connection, permission, envFile) {
-  const storagePath = getProjectStoragePath(configPath);
-  const configJsonPath = join12(storagePath, "config.json");
+  const globalConfig = isGlobalConfigPath(configPath);
+  const storagePath = globalConfig ? configPath : getProjectStoragePath(configPath);
+  const configJsonPath = join14(storagePath, "config.json");
   const configFile = Bun.file(configJsonPath);
-  const projectConfigFile = Bun.file(join12(configPath, "config.json"));
+  const projectConfigFile = Bun.file(join14(configPath, "config.json"));
   let existingV2 = null;
   if (await configFile.exists()) {
     const raw = JSON.parse(await configFile.text());
@@ -15272,9 +15605,11 @@ async function writeV2InitConfig(configPath, connectionName, connection, permiss
     }
   };
   await writeV2Config(storagePath, v2Config);
-  await migrateLegacyProjectEnvLocal(configPath, storagePath);
-  await writeProjectBinding(configPath, storagePath);
-  console.log(t("init.config_saved"));
+  if (!globalConfig) {
+    await migrateLegacyProjectEnvLocal(configPath, storagePath);
+    await writeProjectBinding(configPath, storagePath);
+  }
+  console.log(globalConfig ? t_vars("init.config_saved_global", { path: join14(configPath, "config.json") }) : t("init.config_saved"));
 }
 async function initCommandHandler(options, command) {
   const configPath = resolveConfigPath(command);
@@ -15286,7 +15621,8 @@ async function initCommandHandler(options, command) {
     await handleRename(configPath, options.rename);
     return;
   }
-  const isV2Init = !!(options.connName || options.envFile);
+  const isGlobalConfig = isGlobalConfigPath(configPath);
+  const isV2Init = !!(options.connName || options.envFile || isGlobalConfig);
   const connectionName = options.connName || "default";
   const existingConfig = await configModule.read(configPath);
   const isUsingEnvRefs = options.useEnvRefs;
@@ -15370,11 +15706,13 @@ async function initCommandHandler(options, command) {
       await writeV2InitConfig(configPath, connectionName, configForWrite, permission2, options.envFile);
       return;
     }
-    const storagePath2 = getProjectStoragePath(configPath);
-    await mkdir4(storagePath2, { recursive: true });
+    const storagePath2 = isGlobalConfig ? configPath : getProjectStoragePath(configPath);
+    await mkdir5(storagePath2, { recursive: true });
     await configModule.write(storagePath2, newConfig2);
-    await migrateLegacyProjectEnvLocal(configPath, storagePath2);
-    await writeProjectBinding(configPath, storagePath2);
+    if (!isGlobalConfig) {
+      await migrateLegacyProjectEnvLocal(configPath, storagePath2);
+      await writeProjectBinding(configPath, storagePath2);
+    }
     console.log(t("init.config_saved"));
     return;
   }
@@ -15484,11 +15822,13 @@ async function initCommandHandler(options, command) {
     await writeV2InitConfig(configPath, connectionName, configForWrite, permission, options.envFile);
     return;
   }
-  const storagePath = getProjectStoragePath(configPath);
-  await mkdir4(storagePath, { recursive: true });
+  const storagePath = isGlobalConfig ? configPath : getProjectStoragePath(configPath);
+  await mkdir5(storagePath, { recursive: true });
   await configModule.write(storagePath, newConfig);
-  await migrateLegacyProjectEnvLocal(configPath, storagePath);
-  await writeProjectBinding(configPath, storagePath);
+  if (!isGlobalConfig) {
+    await migrateLegacyProjectEnvLocal(configPath, storagePath);
+    await writeProjectBinding(configPath, storagePath);
+  }
   console.log(t("init.config_saved"));
 }
 async function handleMongoDBInit(ctx) {
@@ -15569,11 +15909,14 @@ async function handleMongoDBInit(ctx) {
     connection: mongoConfig,
     permission
   });
-  const storagePath = getProjectStoragePath(configPath);
-  await mkdir4(storagePath, { recursive: true });
+  const globalConfig = isGlobalConfigPath(configPath);
+  const storagePath = globalConfig ? configPath : getProjectStoragePath(configPath);
+  await mkdir5(storagePath, { recursive: true });
   await configModule.write(storagePath, newConfig);
-  await migrateLegacyProjectEnvLocal(configPath, storagePath);
-  await writeProjectBinding(configPath, storagePath);
+  if (!globalConfig) {
+    await migrateLegacyProjectEnvLocal(configPath, storagePath);
+    await writeProjectBinding(configPath, storagePath);
+  }
   console.log(t("init.config_saved"));
 }
 var VALID_PERMISSIONS, initCommand;
@@ -15585,6 +15928,7 @@ var init_init = __esm(() => {
   init_config_v2();
   init_prompts();
   init_adapters();
+  init_config_path();
   init_config_binding();
   VALID_PERMISSIONS = ["query-only", "read-write", "data-admin", "admin"];
   initCommand = new Command("init").description("Initialize dbcli configuration with .env parsing and interactive prompts").option("--host <host>", "Database host").option("--port <port>", "Database port").option("--user <user>", "Database user").option("--password <password>", "Database password").option("--name <name>", "Database name").option("--system <system>", "Database system (postgresql, mysql, mariadb, mongodb, redis, elasticsearch)").option("--cloud-id <id>", "Elasticsearch Cloud ID").option("--api-key <key>", "Elasticsearch API Key").option("--uri <uri>", "MongoDB connection URI (mongodb://user:pass@host:27017/db?authSource=admin)").option("--auth-source <authSource>", "MongoDB auth database (default: admin when user/password are set)").option("--permission <permission>", "Permission level (query-only, read-write, data-admin, admin)", "query-only").option("--use-env-refs", "Store env var references in config instead of actual values (for CI/CD or multi-env)", false).option("--env-host <var>", "Env var name for host (with --use-env-refs)").option("--env-port <var>", "Env var name for port (with --use-env-refs)").option("--env-user <var>", "Env var name for user (with --use-env-refs)").option("--env-password <var>", "Env var name for password (with --use-env-refs)").option("--env-database <var>", "Env var name for database (with --use-env-refs)").option("--skip-test", "Skip database connection test").option("--no-interactive", "Non-interactive mode (requires all values via flags)").option("--force", "Skip overwrite confirmation if .dbcli exists").option("--conn-name <name>", "Connection name (creates v2 multi-connection config)").option("--env-file <path>", "Path to env file for this connection").option("--remove <name>", "Remove a named connection").option("--rename <names>", "Rename a connection (format: old:new)").action(async (options) => {
@@ -15776,7 +16120,7 @@ var require_utils = __commonJS((exports, module) => {
       state[info.set] = info.to;
     }
   }
-  function readState(line) {
+  function readState2(line) {
     let code = codeRegex(true);
     let controlChars = code.exec(line);
     let state = {};
@@ -15979,7 +16323,7 @@ var require_utils = __commonJS((exports, module) => {
     let output = [];
     for (let i = 0;i < input.length; i++) {
       let line = rewindState(state, input[i]);
-      state = readState(line);
+      state = readState2(line);
       let temp = Object.assign({}, state);
       output.push(unwindState(temp, line));
     }
@@ -17672,6 +18016,7 @@ var init_list = __esm(() => {
   init_adapters();
   init_formatters();
   init_config();
+  init_config_path();
   init_validation();
   init_connection_selector();
   ALLOWED_FORMATS = ["table", "json"];
@@ -17853,7 +18198,7 @@ class AtomicFileWriter {
 }
 
 // src/core/schema-writer.ts
-import { join as join13 } from "path";
+import { join as join15 } from "path";
 
 class SchemaWriter {
   dbcliPath;
@@ -17874,7 +18219,7 @@ class SchemaWriter {
         hotSchemas[item.table] = tableSchema;
       }
     }
-    await this.writer.writeJSON(join13(schemaRoot, "hot-schemas.json"), hotSchemas);
+    await this.writer.writeJSON(join15(schemaRoot, "hot-schemas.json"), hotSchemas);
     const coldGroups = {};
     for (const item of mapping.cold) {
       if (!coldGroups[item.file]) {
@@ -17885,10 +18230,10 @@ class SchemaWriter {
         coldGroups[item.file][item.table] = tableSchema;
       }
     }
-    const coldDir = join13(schemaRoot, "cold");
+    const coldDir = join15(schemaRoot, "cold");
     await this.ensureDir(coldDir);
     for (const [fileName, tables] of Object.entries(coldGroups)) {
-      const filePath = join13(schemaRoot, fileName);
+      const filePath = join15(schemaRoot, fileName);
       await this.writer.writeJSON(filePath, tables);
     }
   }
@@ -17928,6 +18273,8 @@ var init_error_recovery = () => {};
 var init_schema_updater = __esm(() => {
   init_concurrent_lock();
   init_error_recovery();
+  init_config_mutation_guard();
+  init_config_integrity();
 });
 
 // src/core/column-index.ts
@@ -18432,8 +18779,8 @@ var init_artifact = __esm(() => {
 });
 
 // src/core/verification/artifact-writer.ts
-import { mkdir as mkdir5, writeFile, link, unlink as unlink2 } from "fs/promises";
-import { join as join14 } from "path";
+import { mkdir as mkdir6, writeFile as writeFile2, link, unlink as unlink4 } from "fs/promises";
+import { join as join16 } from "path";
 function pad(n, len = 2) {
   return String(n).padStart(len, "0");
 }
@@ -18450,12 +18797,12 @@ function verificationArtifactFilename(artifact) {
   return `verification-${timeStamp(artifact.createdAt)}-${shortId(artifact.id)}.json`;
 }
 async function writeVerificationArtifact(storageDir, artifact) {
-  const dir = join14(storageDir, VERIFICATION_DIR_RELATIVE);
-  await mkdir5(dir, { recursive: true });
-  const target = join14(dir, verificationArtifactFilename(artifact));
+  const dir = join16(storageDir, VERIFICATION_DIR_RELATIVE);
+  await mkdir6(dir, { recursive: true });
+  const target = join16(dir, verificationArtifactFilename(artifact));
   const tmp = `${target}.${process.pid}.tmp`;
   try {
-    await writeFile(tmp, JSON.stringify(artifact, null, 2), "utf8");
+    await writeFile2(tmp, JSON.stringify(artifact, null, 2), "utf8");
     try {
       await link(tmp, target);
     } catch (e) {
@@ -18465,7 +18812,7 @@ async function writeVerificationArtifact(storageDir, artifact) {
       throw e;
     }
   } finally {
-    await unlink2(tmp).catch(() => {});
+    await unlink4(tmp).catch(() => {});
   }
   return target;
 }
@@ -18712,8 +19059,8 @@ var init_assert_artifact = __esm(() => {
 });
 
 // src/core/verification/reader.ts
-import { lstat, readdir as readdir2, readFile as readFile2 } from "fs/promises";
-import { join as join15, isAbsolute, resolve as resolve3, sep as sep2 } from "path";
+import { lstat as lstat2, readdir as readdir2, readFile as readFile2 } from "fs/promises";
+import { join as join17, isAbsolute, resolve as resolve4, sep as sep2 } from "path";
 function isArtifactFilename(name2) {
   return /^verification-.*\.json$/.test(name2);
 }
@@ -18797,7 +19144,7 @@ function validateVerificationArtifact(value) {
   return value;
 }
 async function readVerificationArtifacts(storageRoot) {
-  const storageDir = join15(storageRoot, VERIFICATION_DIR_RELATIVE);
+  const storageDir = join17(storageRoot, VERIFICATION_DIR_RELATIVE);
   let names;
   try {
     names = await readdir2(storageDir);
@@ -18810,9 +19157,9 @@ async function readVerificationArtifacts(storageRoot) {
   const artifacts = [];
   const invalid = [];
   for (const filename of names.filter(isArtifactFilename)) {
-    const path4 = join15(storageDir, filename);
+    const path4 = join17(storageDir, filename);
     try {
-      const stats = await lstat(path4);
+      const stats = await lstat2(path4);
       if (!stats.isFile()) {
         throw new Error("artifact path is not a regular file");
       }
@@ -18894,15 +19241,15 @@ function looksLikePath(selector) {
 }
 function findVerificationArtifact(input, selector) {
   if (looksLikePath(selector)) {
-    const resolved = resolve3(selector);
-    const root = resolve3(input.storageDir);
+    const resolved = resolve4(selector);
+    const root = resolve4(input.storageDir);
     if (resolved !== root && !resolved.startsWith(root + sep2)) {
       throw new VerificationArtifactSelectionError(`Path is outside the verification directory: ${resolved}`);
     }
-    const hit = input.artifacts.find((r) => resolve3(r.path) === resolved);
+    const hit = input.artifacts.find((r) => resolve4(r.path) === resolved);
     if (hit)
       return hit;
-    const bad = input.invalid.find((r) => resolve3(r.path) === resolved);
+    const bad = input.invalid.find((r) => resolve4(r.path) === resolved);
     if (bad) {
       throw new VerificationArtifactSelectionError(`Artifact at ${bad.filename} is invalid: ${bad.error}`);
     }
@@ -18939,8 +19286,8 @@ var init_reader = __esm(() => {
 });
 
 // src/core/verification/retention.ts
-import { lstat as lstat2, unlink as unlink3 } from "fs/promises";
-import { basename as basename3, resolve as resolve4, sep as sep3 } from "path";
+import { lstat as lstat3, unlink as unlink5 } from "fs/promises";
+import { basename as basename3, resolve as resolve5, sep as sep3 } from "path";
 function parseOlderThanDays(raw) {
   const match = /^(\d+)d$/.exec(raw);
   if (!match) {
@@ -18996,22 +19343,22 @@ function boundError2(message) {
   return single.length <= 200 ? single : single.slice(0, 199) + "\u2026";
 }
 function isInsideStorageDir(storageDir, candidatePath) {
-  const base = resolve4(storageDir);
-  const resolved = resolve4(candidatePath);
+  const base = resolve5(storageDir);
+  const resolved = resolve5(candidatePath);
   return resolved === base || resolved.startsWith(base + sep3);
 }
 function hasArtifactFilename(candidatePath) {
   return /^verification-.*\.json$/.test(basename3(candidatePath));
 }
 async function safeDeleteCandidate(storageDir, candidate) {
-  const resolved = resolve4(candidate.path);
+  const resolved = resolve5(candidate.path);
   if (!isInsideStorageDir(storageDir, resolved))
     return { ok: false, reason: "outside-storage-dir" };
   if (!hasArtifactFilename(resolved))
     return { ok: false, reason: "filename-mismatch" };
   let stats;
   try {
-    stats = await lstat2(resolved);
+    stats = await lstat3(resolved);
   } catch (e) {
     if (e.code === "ENOENT")
       return { ok: false, reason: "missing" };
@@ -19020,7 +19367,7 @@ async function safeDeleteCandidate(storageDir, candidate) {
   if (!stats.isFile())
     return { ok: false, reason: "not-regular-file" };
   try {
-    await unlink3(resolved);
+    await unlink5(resolved);
     return { ok: true };
   } catch (e) {
     if (e.code === "ENOENT")
@@ -19037,7 +19384,7 @@ async function pruneVerificationArtifacts(storageRoot, criteria, options) {
   if (criteria.includeInvalid) {
     for (const r of read.invalid) {
       try {
-        const stats = await lstat2(r.path);
+        const stats = await lstat3(r.path);
         invalidMtimes.set(r.path, stats.mtimeMs);
       } catch {}
     }
@@ -19290,8 +19637,8 @@ var init_core = __esm(() => {
 
 // src/core/audit/lock.ts
 import { hostname } from "os";
-import { dirname as dirname3 } from "path";
-import { mkdir as mkdir6, open, rm } from "fs/promises";
+import { dirname as dirname5 } from "path";
+import { mkdir as mkdir7, open as open2, rm } from "fs/promises";
 
 class AuditLockManager {
   auditFilePath;
@@ -19320,7 +19667,7 @@ class AuditLockManager {
         return true;
       }
       const waitTime = Math.min(backoffMs, LOCK_BACKOFF_MAX_MS);
-      await new Promise((resolve5) => setTimeout(resolve5, waitTime));
+      await new Promise((resolve6) => setTimeout(resolve6, waitTime));
       backoffMs = Math.min(backoffMs * 1.5, LOCK_BACKOFF_MAX_MS);
     }
   }
@@ -19349,7 +19696,7 @@ class AuditLockManager {
   }
   async tryAcquireLock(operationName) {
     try {
-      await mkdir6(dirname3(this.lockPath), { recursive: true });
+      await mkdir7(dirname5(this.lockPath), { recursive: true });
       const lockFile = Bun.file(this.lockPath);
       if (await lockFile.exists()) {
         const lockContent = await lockFile.json();
@@ -19367,7 +19714,7 @@ class AuditLockManager {
         timestamp: Date.now(),
         hostname: hostname()
       };
-      const handle = await open(this.lockPath, "wx");
+      const handle = await open2(this.lockPath, "wx");
       try {
         await handle.writeFile(JSON.stringify(lockData), "utf8");
       } finally {
@@ -19383,7 +19730,7 @@ var LOCK_RETRY_BUDGET_MS = 200, LOCK_BACKOFF_START_MS = 5, LOCK_BACKOFF_MAX_MS =
 var init_lock = () => {};
 
 // src/utils/jsonl-rotation.ts
-import { rename as rename2 } from "fs/promises";
+import { rename as rename3 } from "fs/promises";
 function shouldRotate(stats, thresholds, nextLineByteLength) {
   const bytesAfter = stats.currentSizeBytes + nextLineByteLength;
   const entriesAfter = stats.currentEntryCount + 1;
@@ -19391,7 +19738,7 @@ function shouldRotate(stats, thresholds, nextLineByteLength) {
 }
 async function rotate(currentPath, previousPath) {
   try {
-    await rename2(currentPath, previousPath);
+    await rename3(currentPath, previousPath);
   } catch {}
 }
 var init_jsonl_rotation = () => {};
@@ -19402,9 +19749,9 @@ var init_rotation = __esm(() => {
 });
 
 // src/core/audit/logger.ts
-import { appendFile, mkdir as mkdir7, readFile as readFile3, stat } from "fs/promises";
-import { join as join16 } from "path";
-import { randomUUID } from "crypto";
+import { appendFile, mkdir as mkdir8, readFile as readFile3, stat as stat2 } from "fs/promises";
+import { join as join18 } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
 
 class AuditLogger {
   auditDir;
@@ -19429,8 +19776,8 @@ class AuditLogger {
     this.enabled = opts.enabled;
     this.maxBytes = opts.rotation.maxBytes;
     this.maxEntries = opts.rotation.maxEntries;
-    this.auditDir = join16(opts.storagePath, ".dbcli", "audit");
-    this.auditFilePath = join16(this.auditDir, `${opts.connectionName}.jsonl`);
+    this.auditDir = join18(opts.storagePath, ".dbcli", "audit");
+    this.auditFilePath = join18(this.auditDir, `${opts.connectionName}.jsonl`);
     this.previousFilePath = `${this.auditFilePath}.1`;
     this.sessionIdService = opts.sessionIdService;
     this.lockManager = opts.lockManager ?? new AuditLockManager(this.auditFilePath);
@@ -19451,12 +19798,12 @@ class AuditLogger {
     try {
       const sessionId = await this.sessionIdService.resolve();
       this.cachedSessionId = sessionId;
-      await mkdir7(this.auditDir, { recursive: true });
+      await mkdir8(this.auditDir, { recursive: true });
       if (!this.writerInitialized) {
         await this.syncCountersFromDisk();
         this.writerInitialized = true;
       }
-      const id = randomUUID();
+      const id = randomUUID2();
       const ts = new Date().toISOString();
       const enriched = {
         ...entry,
@@ -19528,7 +19875,7 @@ class AuditLogger {
   }
   async syncCountersFromDisk() {
     try {
-      const s = await stat(this.auditFilePath);
+      const s = await stat2(this.auditFilePath);
       this.currentSizeBytes = s.size;
       const raw = await readFile3(this.auditFilePath, "utf8");
       this.currentEntryCount = raw.split(`
@@ -19556,17 +19903,17 @@ var init_logger2 = __esm(() => {
 });
 
 // src/core/audit/session-id.ts
-import { mkdir as mkdir8, readFile as readFile4, rename as rename3, stat as stat2, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir9, readFile as readFile4, rename as rename4, stat as stat3, writeFile as writeFile3 } from "fs/promises";
 import { randomBytes as randomBytes2 } from "crypto";
-import { dirname as dirname4, join as join17 } from "path";
+import { dirname as dirname6, join as join19 } from "path";
 function generateSessionId(pid, nowMs) {
   const random = randomBytes2(3).toString("hex");
   return `${pid}-${nowMs}-${random}`;
 }
 async function readSessionIdFile(storagePath) {
-  const target = join17(storagePath, LAST_SESSION_ID_RELATIVE);
+  const target = join19(storagePath, LAST_SESSION_ID_RELATIVE);
   try {
-    await stat2(target);
+    await stat3(target);
   } catch {
     return null;
   }
@@ -19586,12 +19933,12 @@ async function readSessionIdFile(storagePath) {
   }
 }
 async function writeSessionIdFile(storagePath, payload) {
-  const target = join17(storagePath, LAST_SESSION_ID_RELATIVE);
+  const target = join19(storagePath, LAST_SESSION_ID_RELATIVE);
   const tmp = `${target}.tmp`;
   try {
-    await mkdir8(dirname4(target), { recursive: true });
-    await writeFile2(tmp, JSON.stringify(payload, null, 2), "utf8");
-    await rename3(tmp, target);
+    await mkdir9(dirname6(target), { recursive: true });
+    await writeFile3(tmp, JSON.stringify(payload, null, 2), "utf8");
+    await rename4(tmp, target);
   } catch {}
 }
 
@@ -19686,7 +20033,8 @@ async function getAuditLogger(config, configPath, connectionName) {
 }
 async function writeAuditEntry(config, commandName, options, outcome) {
   try {
-    const logger = await getAuditLogger(config, options.config || ".dbcli", typeof options.connectionName === "string" ? options.connectionName : undefined);
+    const connectionName = typeof options.connectionName === "string" && options.connectionName || config.effectiveConnectionName || getGlobalConnectionName() || "default";
+    const logger = await getAuditLogger(config, options.config || ".dbcli", connectionName);
     const engine = config.connection?.system || "postgresql";
     const target = outcome.target || getOperationTarget(engine, commandName, options, outcome.sql);
     let tier = getEngineCapability(engine, commandName).tier;
@@ -19709,7 +20057,11 @@ async function writeAuditEntry(config, commandName, options, outcome) {
       ...outcome.sql && { redacted_sql: redactSql(outcome.sql) },
       ...errorMessage && { error: errorMessage },
       ...outcome.recovery_ref && { recovery_ref: outcome.recovery_ref },
-      metadata: outcome.metadata
+      metadata: {
+        ...outcome.metadata ?? {},
+        connection_name: connectionName,
+        environment: config.effectiveEnvironment ?? null
+      }
     };
     const result = await logger.write(entry);
     return "success" in result ? result.id : null;
@@ -19729,49 +20081,6 @@ var init_integration_helper = __esm(() => {
   _loggers = new Map;
 });
 
-// src/utils/levenshtein-distance.ts
-function levenshteinDistance(a, b) {
-  const lenA = a.length;
-  const lenB = b.length;
-  const dp = [];
-  for (let i = 0;i <= lenB; i++) {
-    const row = [];
-    for (let j2 = 0;j2 <= lenA; j2++) {
-      row[j2] = 0;
-    }
-    dp[i] = row;
-  }
-  for (let i = 0;i <= lenB; i++) {
-    const row = dp[i];
-    if (row !== undefined) {
-      row[0] = i;
-    }
-  }
-  for (let j2 = 0;j2 <= lenA; j2++) {
-    const firstRow = dp[0];
-    if (firstRow !== undefined) {
-      firstRow[j2] = j2;
-    }
-  }
-  for (let i = 1;i <= lenB; i++) {
-    const currentRow = dp[i];
-    const prevRow = dp[i - 1];
-    if (!currentRow || !prevRow)
-      continue;
-    for (let j2 = 1;j2 <= lenA; j2++) {
-      if (b.charAt(i - 1) === a.charAt(j2 - 1)) {
-        currentRow[j2] = prevRow[j2 - 1] ?? 0;
-      } else {
-        const sub = (prevRow[j2 - 1] ?? 0) + 1;
-        const ins = (currentRow[j2 - 1] ?? 0) + 1;
-        const del = (prevRow[j2] ?? 0) + 1;
-        currentRow[j2] = Math.min(sub, ins, del);
-      }
-    }
-  }
-  return dp[lenB]?.[lenA] ?? 0;
-}
-
 // src/utils/error-suggester.ts
 async function suggestTableName(errorMessage, adapter) {
   try {
@@ -21356,14 +21665,14 @@ var init_render_markdown = __esm(() => {
 });
 
 // src/core/recovery/last-envelope.ts
-import { writeFile as writeFile3, readFile as readFile5, rename as rename4, mkdir as mkdir9, stat as stat3 } from "fs/promises";
-import { dirname as dirname5, join as join18 } from "path";
-import { randomUUID as randomUUID2 } from "crypto";
+import { writeFile as writeFile4, readFile as readFile5, rename as rename5, mkdir as mkdir10, stat as stat4 } from "fs/promises";
+import { dirname as dirname7, join as join20 } from "path";
+import { randomUUID as randomUUID3 } from "crypto";
 function sanitizeCommandSummary(argv) {
   return redactArgv(argv);
 }
-async function writeLastEnvelope(cwd, envelope, argv, now = () => new Date, id = randomUUID2(), auditRef) {
-  const target = join18(cwd, LAST_ENVELOPE_PATH);
+async function writeLastEnvelope(cwd, envelope, argv, now = () => new Date, id = randomUUID3(), auditRef) {
+  const target = join20(cwd, LAST_ENVELOPE_PATH);
   const tmp = `${target}.tmp`;
   const payload = {
     schemaVersion: 1,
@@ -21375,15 +21684,15 @@ async function writeLastEnvelope(cwd, envelope, argv, now = () => new Date, id =
     envelope
   };
   try {
-    await mkdir9(dirname5(target), { recursive: true });
-    await writeFile3(tmp, JSON.stringify(payload, null, 2), "utf8");
-    await rename4(tmp, target);
+    await mkdir10(dirname7(target), { recursive: true });
+    await writeFile4(tmp, JSON.stringify(payload, null, 2), "utf8");
+    await rename5(tmp, target);
   } catch {}
 }
 async function readLastEnvelope(cwd) {
-  const target = join18(cwd, LAST_ENVELOPE_PATH);
+  const target = join20(cwd, LAST_ENVELOPE_PATH);
   try {
-    await stat3(target);
+    await stat4(target);
   } catch {
     return null;
   }
@@ -21395,9 +21704,9 @@ async function readLastEnvelope(cwd) {
   }
 }
 async function readLastEnvelopeRaw(cwd) {
-  const target = join18(cwd, LAST_ENVELOPE_PATH);
+  const target = join20(cwd, LAST_ENVELOPE_PATH);
   try {
-    await stat3(target);
+    await stat4(target);
   } catch {
     return null;
   }
@@ -21420,13 +21729,13 @@ var init_last_envelope = __esm(() => {
 
 // src/core/recovery/emit.ts
 import { writeFileSync, mkdirSync, renameSync, writeSync } from "fs";
-import { dirname as dirname6, join as join19 } from "path";
-import { randomUUID as randomUUID3 } from "crypto";
+import { dirname as dirname8, join as join21 } 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();
-  const envelopeId = options.envelopeId ?? randomUUID3();
+  const envelopeId = options.envelopeId ?? randomUUID4();
   writeLastEnvelopeSync(cwd, envelope, argv, envelopeId, options.auditRef);
   writeSync(1, renderJson(envelope, { brief: options.brief === true }) + `
 `);
@@ -21437,7 +21746,7 @@ function buildArgvFromProcess() {
   return ["dbcli", ...userArgs];
 }
 function writeLastEnvelopeSync(cwd, envelope, argv, id, auditRef) {
-  const target = join19(cwd, LAST_ENVELOPE_PATH);
+  const target = join21(cwd, LAST_ENVELOPE_PATH);
   const tmp = `${target}.tmp`;
   const payload = {
     schemaVersion: 1,
@@ -21449,7 +21758,7 @@ function writeLastEnvelopeSync(cwd, envelope, argv, id, auditRef) {
     envelope
   };
   try {
-    mkdirSync(dirname6(target), { recursive: true });
+    mkdirSync(dirname8(target), { recursive: true });
     writeFileSync(tmp, JSON.stringify(payload, null, 2), "utf8");
     renameSync(tmp, target);
   } catch {}
@@ -22193,8 +22502,8 @@ function renderStep2(r) {
 var NEXT_SCHEMA_VERSION = 1, STEP_RESULT_SUMMARY_FIELD_CAP = 4096;
 
 // src/core/recovery/next-step-schema.ts
-import { stat as stat4 } from "fs/promises";
-import { resolve as resolve5 } from "path";
+import { stat as stat5 } from "fs/promises";
+import { resolve as resolve6 } from "path";
 function summarizeZodError(err) {
   return err.issues.map((iss) => {
     const path4 = iss.path.join(".") || "<root>";
@@ -22213,9 +22522,9 @@ async function loadStepResultSummary(arg, cwd) {
   }
   let raw;
   if (arg.startsWith("@")) {
-    const path4 = resolve5(cwd, arg.slice(1));
+    const path4 = resolve6(cwd, arg.slice(1));
     try {
-      await stat4(path4);
+      await stat5(path4);
     } catch {
       return { ok: false, reason: `--result @<file>: ${path4} not readable.` };
     }
@@ -22880,6 +23189,7 @@ var init_schema = __esm(() => {
   init_validation();
   init_connection_selector();
   init_error_suggester();
+  init_config_path();
   ALLOWED_FORMATS2 = ["table", "json"];
   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").addOption(createConnectionSelectorOption()).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("--sample-method <method>", 'MongoDB only: "random" (default, uses $sample) or "natural" (uses find().limit()). Ignored on SQL connections.', "random").option("--recovery", "On failure, emit a structured recovery envelope to stdout (suppresses human stderr message)", false).action(schemaAction);
 });
@@ -22937,14 +23247,14 @@ var init_html_formatter = __esm(() => {
 });
 
 // src/utils/opener.ts
-import open2 from "open";
+import open3 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 open2(target);
+    await open3(target);
   } catch (err) {
     console.error(`[Opener] Failed to open ${target}:`, err);
   }
@@ -23369,7 +23679,7 @@ var init_query_size_guard = __esm(() => {
 // src/commands/query.ts
 import crypto3 from "crypto";
 import { tmpdir } from "os";
-import { join as join20 } from "path";
+import { join as join22 } from "path";
 function requireSqlConnection2(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
@@ -23680,7 +23990,7 @@ async function presentSingleResult(query, options, execution, tableCellLimit) {
       } : {}
     });
     if (options.ui) {
-      const tempPath = join20(tmpdir(), `dbcli-query-${Date.now()}.html`);
+      const tempPath = join22(tmpdir(), `dbcli-query-${Date.now()}.html`);
       await Bun.write(tempPath, html);
       await openInBrowser(tempPath);
     } else {
@@ -23893,6 +24203,7 @@ var init_query = __esm(() => {
   init_query_executor();
   init_config();
   init_blacklist_validator();
+  init_config_path();
   init_validation();
   init_applied_limit();
   init_integration_helper();
@@ -24335,6 +24646,7 @@ var ALLOWED_FORMATS4;
 var init_plan = __esm(() => {
   init_query_risk_analyzer();
   init_config();
+  init_config_path();
   init_validation();
   init_integration_helper();
   ALLOWED_FORMATS4 = ["text", "json"];
@@ -24438,7 +24750,7 @@ __export(exports_q_mongo, {
   qMongoBranch: () => qMongoBranch
 });
 import { tmpdir as tmpdir2 } from "os";
-import { join as join21 } from "path";
+import { join as join23 } from "path";
 async function qMongoBranch(snippet, prepared, options, config) {
   const collection = options.collection ?? prepared.execHints?.collection;
   if (!collection) {
@@ -24470,7 +24782,7 @@ async function qMongoBranch(snippet, prepared, options, config) {
         ...securityNotification ? { securityNotification } : {}
       });
       if (options.ui) {
-        const tempPath = join21(tmpdir2(), `dbcli-report-${Date.now()}.html`);
+        const tempPath = join23(tmpdir2(), `dbcli-report-${Date.now()}.html`);
         await Bun.write(tempPath, html);
         await openInBrowser(tempPath);
       } else {
@@ -24511,7 +24823,7 @@ var init_q_mongo = __esm(() => {
 // src/commands/q.ts
 import crypto4 from "crypto";
 import { tmpdir as tmpdir3 } from "os";
-import { join as join22 } from "path";
+import { join as join24 } from "path";
 function formatDryRun(input) {
   const lines = ["Dry-run preview (no execution):"];
   if (input.family === "es") {
@@ -24612,7 +24924,7 @@ async function qCommand(name2, options, command) {
           ...securityNotification ? { securityNotification } : {}
         });
         if (options.ui) {
-          const tempPath = join22(tmpdir3(), `dbcli-report-${Date.now()}.html`);
+          const tempPath = join24(tmpdir3(), `dbcli-report-${Date.now()}.html`);
           await Bun.write(tempPath, html);
           await openInBrowser(tempPath);
         } else {
@@ -24840,6 +25152,7 @@ var init_q = __esm(() => {
   init_message_loader();
   init_adapters();
   init_config();
+  init_config_path();
   init_blacklist_validator();
   init_blacklist();
   init_permission_guard();
@@ -25060,8 +25373,8 @@ var exports_queries_rename = {};
 __export(exports_queries_rename, {
   queriesRename: () => queriesRename
 });
-import { rename as rename5, mkdir as mkdir10 } from "fs/promises";
-import { dirname as dirname7 } from "path";
+import { rename as rename6, mkdir as mkdir11 } from "fs/promises";
+import { dirname as dirname9 } from "path";
 async function queriesRename(oldName, newName, options = {}) {
   if (!oldName.startsWith("@") || !newName.startsWith("@")) {
     throw new Error(`Both names must start with '@'`);
@@ -25082,8 +25395,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 mkdir10(dirname7(dstWithSuffix), { recursive: true });
-    await rename5(v.query.file, dstWithSuffix);
+    await mkdir11(dirname9(dstWithSuffix), { recursive: true });
+    await rename6(v.query.file, dstWithSuffix);
     await rewriteFrontmatterName(dstWithSuffix, newName.slice(1));
     console.log(`renamed ${v.query.file} \u2192 ${dstWithSuffix}`);
   }
@@ -25108,8 +25421,8 @@ var exports_queries_copy = {};
 __export(exports_queries_copy, {
   queriesCopy: () => queriesCopy
 });
-import { mkdir as mkdir11, copyFile } from "fs/promises";
-import { dirname as dirname8, basename as basename4 } from "path";
+import { mkdir as mkdir12, copyFile } from "fs/promises";
+import { dirname as dirname10, basename as basename4 } from "path";
 async function queriesCopy(src, dst, options = {}) {
   if (!src.startsWith("@") || !dst.startsWith("@")) {
     throw new Error(`Both names must start with '@'`);
@@ -25127,7 +25440,7 @@ async function queriesCopy(src, dst, options = {}) {
   }
   for (const v of variants) {
     const dstFile = mapEngineSuffix(v.query.file, snippetKeyToFile(cwd, dst, "local"));
-    await mkdir11(dirname8(dstFile), { recursive: true });
+    await mkdir12(dirname10(dstFile), { recursive: true });
     await copyFile(v.query.file, dstFile);
     console.log(`copied ${v.query.file} \u2192 ${dstFile}`);
   }
@@ -25145,21 +25458,21 @@ var exports_queries_import = {};
 __export(exports_queries_import, {
   queriesImport: () => queriesImport
 });
-import { stat as stat5, mkdir as mkdir12, copyFile as copyFile2 } from "fs/promises";
-import { basename as basename5, join as join23, extname } from "path";
+import { stat as stat6, mkdir as mkdir13, copyFile as copyFile2 } from "fs/promises";
+import { basename as basename5, join as join25, extname as extname2 } from "path";
 async function queriesImport(filePath, options = {}) {
   const cwd = options.cwd ?? process.cwd();
-  if (extname(filePath) !== ".sql") {
+  if (extname2(filePath) !== ".sql") {
     throw new Error(`Expected .sql file, got ${filePath}`);
   }
-  await stat5(filePath);
+  await stat6(filePath);
   const text2 = await Bun.file(filePath).text();
   const baseName = options.as ? options.as.replace(/^@/, "") : basename5(filePath, ".sql").replace(/\.(postgres|mysql)$/, "");
   const key = "@" + baseName;
   parseSavedQuery({ key, file: filePath, source: "local", text: text2 });
-  const targetDir = join23(cwd, ".dbcli/queries");
-  await mkdir12(targetDir, { recursive: true });
-  const target = join23(targetDir, basename5(filePath));
+  const targetDir = join25(cwd, ".dbcli/queries");
+  await mkdir13(targetDir, { recursive: true });
+  const target = join25(targetDir, basename5(filePath));
   if (await Bun.file(target).exists()) {
     if (!options.force) {
       const ok = await dist_default4({ message: `Overwrite ${target}?`, default: false });
@@ -25180,7 +25493,7 @@ var exports_queries_export = {};
 __export(exports_queries_export, {
   queriesExport: () => queriesExport
 });
-import { writeFile as writeFile4 } from "fs/promises";
+import { writeFile as writeFile5 } from "fs/promises";
 async function queriesExport(name2, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const dirs = resolveSnippetDirs(cwd);
@@ -25201,7 +25514,7 @@ async function queriesExport(name2, options = {}) {
   }
   const text2 = await Bun.file(chosen[0].query.file).text();
   if (options.output) {
-    await writeFile4(options.output, text2, "utf8");
+    await writeFile5(options.output, text2, "utf8");
     console.log(`wrote ${options.output}`);
   } else {
     process.stdout.write(text2);
@@ -25212,12 +25525,12 @@ var init_queries_export = __esm(() => {
 });
 
 // src/commands/queries.ts
-import { mkdir as mkdir13, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname9 } from "path";
+import { mkdir as mkdir14, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname11 } from "path";
 import { spawn } from "child_process";
-async function deriveEngine() {
+async function deriveEngine(command) {
   try {
-    const cfg = await configModule.read(resolveConfigPath(undefined, {}));
+    const cfg = await configModule.read(resolveConfigPath(command));
     if (cfg.connection) {
       return mapSystemToEngine(cfg.connection.system);
     }
@@ -25279,10 +25592,10 @@ function matchesFolded(r, opts) {
     return false;
   return true;
 }
-async function queriesShow(name2, options) {
+async function queriesShow(name2, options, command) {
   const map = await loadSnippets(resolveSnippetDirs(process.cwd()));
   try {
-    const engine = await deriveEngine();
+    const engine = await deriveEngine(command);
     const snippet = resolveByName(map, name2, engine);
     if (options.format === "json") {
       console.log(JSON.stringify({ ...snippetToJson(snippet), sql: snippet.query.sqlBody.trim() }, null, 2));
@@ -25321,8 +25634,8 @@ async function queriesNew(name2, options) {
     process.exit(1);
     return;
   }
-  await mkdir13(dirname9(file), { recursive: true });
-  await writeFile5(file, scaffold(name2), "utf8");
+  await mkdir14(dirname11(file), { recursive: true });
+  await writeFile6(file, scaffold(name2), "utf8");
   console.log(`Created ${file}`);
   if (source === "shared")
     console.log(t("queries.first_run_hint"));
@@ -25383,7 +25696,7 @@ async function queriesCheck(options) {
     console.log(`\u2713 ${total} snippets parsed successfully`);
   }
 }
-async function queriesSearch(keywords, options) {
+async function queriesSearch(keywords, options, command) {
   const query = keywords.join(" ").trim();
   if (!query) {
     console.error(t("queries.search_no_keywords"));
@@ -25408,7 +25721,7 @@ async function queriesSearch(keywords, options) {
   if (options.engine && options.engine !== "all") {
     engineFilter = options.engine;
   } else if (!options.engine) {
-    const inferred = await deriveEngineOrNull();
+    const inferred = await deriveEngineOrNull(command);
     if (inferred)
       engineFilter = inferred;
     else
@@ -25431,9 +25744,9 @@ async function queriesSearch(keywords, options) {
   }
   renderSearchTable(hits, options.includeInternal === true);
 }
-async function deriveEngineOrNull() {
+async function deriveEngineOrNull(command) {
   try {
-    const cfg = await configModule.read(resolveConfigPath(undefined, {}));
+    const cfg = await configModule.read(resolveConfigPath(command));
     if (cfg.connection) {
       return mapSystemToEngine(cfg.connection.system);
     }
@@ -25466,7 +25779,7 @@ function renderSearchTable(hits, includeScore) {
   for (const r of rows)
     console.log(fmt(r));
 }
-async function queriesSuggest(intent, options) {
+async function queriesSuggest(intent, options, command) {
   const map = await loadSnippets(resolveSnippetDirs(process.cwd()));
   const folded = [...map.entries()].map(([key, variants]) => foldVariants(key, variants));
   const availableIntents = collectIntentPrefixes(folded);
@@ -25492,7 +25805,7 @@ async function queriesSuggest(intent, options) {
   if (options.engine && options.engine !== "all") {
     engineFilter = options.engine;
   } else if (!options.engine) {
-    const inferred = await deriveEngineOrNull();
+    const inferred = await deriveEngineOrNull(command);
     if (inferred)
       engineFilter = inferred;
     else
@@ -25561,9 +25874,9 @@ function scaffold(name2) {
 }
 async function openInEditor(file) {
   const editor = process.env.EDITOR || "vi";
-  await new Promise((resolve6, reject) => {
+  await new Promise((resolve7, reject) => {
     const child = spawn(editor, [file], { stdio: "inherit" });
-    child.on("exit", (code) => code === 0 ? resolve6() : reject(new Error(`Editor exited with ${code}`)));
+    child.on("exit", (code) => code === 0 ? resolve7() : reject(new Error(`Editor exited with ${code}`)));
   });
 }
 var INTENT_RE_CLI, queriesCommand;
@@ -25571,6 +25884,7 @@ var init_queries = __esm(() => {
   init_esm();
   init_message_loader();
   init_config();
+  init_config_path();
   init_saved_queries();
   init_fold();
   init_search();
@@ -25580,8 +25894,8 @@ var init_queries = __esm(() => {
   queriesCommand.command("list").description(t("queries.list_description")).option("--format <type>", "Output format: table, json, csv", "table").option("--tag <tag>", "Filter by tag").option("--engine <engine>", "Filter by engine: postgres | mysql").option("--source <source>", "Filter by source: local | shared").action(async (options) => {
     await queriesList(options);
   });
-  queriesCommand.command("show <name>").description(t("queries.show_description")).option("--format <type>", "Output format: table, json, csv", "table").action(async (name2, options) => {
-    await queriesShow(name2, options);
+  queriesCommand.command("show <name>").description(t("queries.show_description")).option("--format <type>", "Output format: table, json, csv", "table").action(async (name2, options, command) => {
+    await queriesShow(name2, options, command);
   });
   queriesCommand.command("new <name>").description(t("queries.new_description")).option("--local", "Create under .dbcli/queries (gitignored) instead of .dbcli-shared/").option("--edit", "Open the created file in $EDITOR").action(async (name2, options) => {
     await queriesNew(name2, options);
@@ -25637,11 +25951,11 @@ var init_queries = __esm(() => {
       process.exit(1);
     }
   });
-  queriesCommand.command("search [keywords...]").description(t("queries.search_description")).option("--format <type>", "Output format: table, json", "table").option("--engine <engine>", "Filter: postgres | mysql | redis | elasticsearch | all").option("--source <source>", "Filter: local | shared | builtin | all").option("--limit <n>", "Max results (default 10)").option("--include-internal", "Show ranking score").action(async (keywords, options) => {
-    await queriesSearch(keywords, options);
+  queriesCommand.command("search [keywords...]").description(t("queries.search_description")).option("--format <type>", "Output format: table, json", "table").option("--engine <engine>", "Filter: postgres | mysql | redis | elasticsearch | all").option("--source <source>", "Filter: local | shared | builtin | all").option("--limit <n>", "Max results (default 10)").option("--include-internal", "Show ranking score").action(async (keywords, options, command) => {
+    await queriesSearch(keywords, options, command);
   });
-  queriesCommand.command("suggest [intent]").description(t("queries.suggest_description")).option("--format <type>", "Output format: table, json", "table").option("--engine <engine>", "Filter: postgres | mysql | redis | elasticsearch | all").option("--source <source>", "Filter: local | shared | builtin | all").action(async (intent, options) => {
-    await queriesSuggest(intent, options);
+  queriesCommand.command("suggest [intent]").description(t("queries.suggest_description")).option("--format <type>", "Output format: table, json", "table").option("--engine <engine>", "Filter: postgres | mysql | redis | elasticsearch | all").option("--source <source>", "Filter: local | shared | builtin | all").action(async (intent, options, command) => {
+    await queriesSuggest(intent, options, command);
   });
 });
 
@@ -26723,6 +27037,7 @@ var init_dml_plan4 = __esm(() => {
   init_query_risk_analyzer();
   init_config();
   init_plan();
+  init_config_path();
   init_validation();
   init_dml_plan_sql();
   init_dml_plan();
@@ -27003,6 +27318,7 @@ var init_insert = __esm(() => {
   init_permission_guard();
   init_blacklist_validator();
   init_blacklist();
+  init_config_path();
   init_dml_plan4();
   init_integration_helper();
 });
@@ -27305,6 +27621,7 @@ var init_update = __esm(() => {
   init_permission_guard();
   init_blacklist_validator();
   init_blacklist();
+  init_config_path();
   init_dml_plan4();
   init_integration_helper();
 });
@@ -27591,6 +27908,7 @@ var init_delete = __esm(() => {
   init_permission_guard();
   init_blacklist_validator();
   init_blacklist();
+  init_config_path();
   init_dml_plan4();
   init_integration_helper();
 });
@@ -28012,6 +28330,7 @@ var init_export = __esm(() => {
   init_query_executor();
   init_config();
   init_prompts();
+  init_config_path();
   init_blacklist_validator();
   init_applied_limit();
   init_integration_helper();
@@ -28037,15 +28356,15 @@ var init_types6 = __esm(() => {
 });
 
 // src/core/agent-tasks/task-paths.ts
-import { join as join24 } from "path";
+import { join as join26 } from "path";
 function resolveBuiltinDir2() {
   return packageAssetPath("tasks");
 }
 function resolveAgentTaskDirs(workspaceRoot) {
   return {
     builtinDir: resolveBuiltinDir2(),
-    sharedDir: join24(workspaceRoot, ".dbcli-shared", "tasks"),
-    localDir: join24(workspaceRoot, ".dbcli", "tasks")
+    sharedDir: join26(workspaceRoot, ".dbcli-shared", "tasks"),
+    localDir: join26(workspaceRoot, ".dbcli", "tasks")
   };
 }
 var init_task_paths = __esm(() => {
@@ -28192,7 +28511,7 @@ var init_parser2 = __esm(() => {
 
 // src/core/agent-tasks/loader.ts
 import { readdir as readdir3 } from "fs/promises";
-import { join as join25, relative as relative2, sep as sep4 } from "path";
+import { join as join27, relative as relative2, sep as sep4 } from "path";
 async function loadAgentTasks(opts, flags) {
   const errors3 = [];
   const builtin = await walkAndParse2(opts.builtinDir, "builtin", errors3);
@@ -28249,7 +28568,7 @@ async function safeCollectMd(root) {
       return;
     }
     for (const e of entries) {
-      const full = join25(dir, e.name);
+      const full = join27(dir, e.name);
       if (e.isDirectory())
         await walk(full);
       else
@@ -28760,9 +29079,19 @@ function getOrInitBlacklist(config) {
     columns: config.blacklist.columns ? { ...config.blacklist.columns } : {}
   };
 }
-async function blacklistList(configPath) {
+async function blacklistList(configPath, format = "text") {
   const config = await configModule.read(configPath);
   const blacklist = getOrInitBlacklist(config);
+  const audit = auditBlacklistPatterns(blacklist);
+  if (format === "json") {
+    const result = {
+      tables: blacklist.tables,
+      columns: blacklist.columns,
+      warnings: audit.warnings
+    };
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
   console.log(t("blacklist.list_title"));
   console.log("\u2500".repeat(40));
   if (blacklist.tables.length === 0 && Object.keys(blacklist.columns).length === 0) {
@@ -28781,7 +29110,6 @@ async function blacklistList(configPath) {
   } else {
     console.log(`${t("blacklist.columns_label")}: {}`);
   }
-  const audit = auditBlacklistPatterns(blacklist);
   for (const w2 of audit.warnings) {
     console.error(`\u26A0  blacklist.columns["${w2.collection}"]: '${w2.raw}' is ignored on mongo connections (${w2.reason}).`);
   }
@@ -28871,12 +29199,15 @@ var init_blacklist2 = __esm(() => {
   init_esm();
   init_message_loader();
   init_config();
+  init_validation();
   VALID_TABLE_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
   VALID_COLUMN_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
   blacklistCommand = new Command("blacklist").description(t("blacklist.description"));
-  blacklistCommand.command("list").description(t("blacklist.list_title")).option("--config <path>", "Path to .dbcli config file", DEFAULT_CONFIG_PATH).action(async (options) => {
+  blacklistCommand.command("list").description(t("blacklist.list_title")).option("--config <path>", "Path to .dbcli config file", DEFAULT_CONFIG_PATH).option("--format <type>", "Output format: text, json", "text").action(async (options) => {
     try {
-      await blacklistList(options.config || DEFAULT_CONFIG_PATH);
+      const format = options.format || "text";
+      validateFormat(format, ["text", "json"], "blacklist list");
+      await blacklistList(options.config || DEFAULT_CONFIG_PATH, format);
     } catch (error) {
       console.error(error.message);
       process.exit(1);
@@ -81115,7 +81446,7 @@ ${fence}`;
 
 // src/commands/diff.ts
 import crypto9 from "crypto";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 function requireSqlConnection8(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
@@ -81142,7 +81473,7 @@ async function expandOrmPaths(inputs) {
   const expanded = new Set;
   for (const path4 of paths) {
     if (!hasGlobMagic(path4)) {
-      expanded.add(resolve6(path4));
+      expanded.add(resolve7(path4));
       continue;
     }
     const matches = await Array.fromAsync(new Bun.Glob(path4).scan({
@@ -81154,7 +81485,7 @@ async function expandOrmPaths(inputs) {
       throw new Error(`ORM schema glob matched no files: ${path4}`);
     }
     for (const match of matches)
-      expanded.add(resolve6(match));
+      expanded.add(resolve7(match));
   }
   return [...expanded].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
 }
@@ -81490,6 +81821,7 @@ var ALLOWED_FORMATS8, statusCommand;
 var init_status2 = __esm(() => {
   init_esm();
   init_config();
+  init_config_path();
   init_validation();
   ALLOWED_FORMATS8 = ["text", "json"];
   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) => {
@@ -81601,7 +81933,7 @@ var init_collect_snippets = __esm(() => {
 });
 
 // src/core/inspect/collect-schema-cache.ts
-import { join as join26 } from "path";
+import { join as join28 } from "path";
 async function collectSchemaCache(opts) {
   const warnings = [];
   if (opts.system && !SQL_SYSTEMS2.includes(opts.system)) {
@@ -81611,7 +81943,7 @@ async function collectSchemaCache(opts) {
     };
   }
   const root = resolveSchemaPath(opts.dbcliPath, opts.connectionName);
-  const indexPath = join26(root, "index.json");
+  const indexPath = join28(root, "index.json");
   const file = Bun.file(indexPath);
   if (!await file.exists()) {
     return { section: { available: false }, warnings };
@@ -81693,7 +82025,7 @@ var SAMPLE_SIZE = 10;
 // src/core/inspect/collect-version.ts
 async function collectVersion(adapter, timeoutMs) {
   const probe = adapter.getServerVersion().then((v) => typeof v === "string" && v !== "unknown" ? v : null, () => null);
-  const timeout = new Promise((resolve7) => setTimeout(() => resolve7(null), timeoutMs));
+  const timeout = new Promise((resolve8) => setTimeout(() => resolve8(null), timeoutMs));
   return Promise.race([probe, timeout]);
 }
 
@@ -81881,7 +82213,7 @@ function buildHints(snap, ctx = {}) {
 }
 
 // src/core/inspect/collector.ts
-import { join as join27 } from "path";
+import { join as join29 } from "path";
 async function collectInspect(opts) {
   const warnings = [];
   let config = null;
@@ -81923,7 +82255,7 @@ async function collectInspect(opts) {
       probeError = err;
       return "error";
     });
-    const timer = new Promise((resolve7) => setTimeout(() => resolve7("timeout"), probeTimeout));
+    const timer = new Promise((resolve8) => setTimeout(() => resolve8("timeout"), probeTimeout));
     const outcome = await Promise.race([probe, timer]);
     if (outcome === "timeout") {
       warnings.push(`probe: timed out after ${probeTimeout}ms`);
@@ -81965,11 +82297,11 @@ async function collectInspect(opts) {
   return { ...snapWithoutSuggestions, suggestedCommands, hints, warnings };
 }
 async function hasConfig(configPath) {
-  if (await Bun.file(join27(configPath, "config.json")).exists())
+  if (await Bun.file(join29(configPath, "config.json")).exists())
     return true;
   if (await Bun.file(configPath).exists()) {
-    const stat6 = await Bun.file(configPath).stat().catch(() => null);
-    return stat6?.isFile() === true;
+    const stat7 = await Bun.file(configPath).stat().catch(() => null);
+    return stat7?.isFile() === true;
   }
   return false;
 }
@@ -82132,6 +82464,7 @@ var ALLOWED_FORMATS9, inspectCommand;
 var init_inspect2 = __esm(() => {
   init_esm();
   init_message_loader();
+  init_config_path();
   init_validation();
   init_inspect();
   init_config();
@@ -82311,7 +82644,7 @@ async function runDiagnostic(input) {
     const indexParams = family === "es" && prepared.execHints?.index ? [prepared.execHints.index] : [];
     return input.adapter.execute(prepared.driver.sql, family === "sql" ? prepared.driver.values : indexParams);
   })();
-  const timer = new Promise((resolve7) => setTimeout(() => resolve7("timeout"), input.timeoutMs));
+  const timer = new Promise((resolve8) => setTimeout(() => resolve8("timeout"), input.timeoutMs));
   let outcome;
   let errorMessage2 = null;
   try {
@@ -82617,6 +82950,7 @@ var ALLOWED_FORMATS10, reportCommand;
 var init_report2 = __esm(() => {
   init_esm();
   init_message_loader();
+  init_config_path();
   init_validation();
   init_config();
   init_integration_helper();
@@ -83058,6 +83392,7 @@ var ALLOWED_FORMATS11, guideCommand;
 var init_guide2 = __esm(() => {
   init_esm();
   init_message_loader();
+  init_config_path();
   init_validation();
   init_config();
   init_integration_helper();
@@ -83946,6 +84281,7 @@ var FORMATS, CONFIDENCES;
 var init_guide_missing_index = __esm(() => {
   init_adapters();
   init_config();
+  init_config_path();
   init_saved_queries();
   init_missing_index();
   init_parse_sql();
@@ -84249,6 +84585,7 @@ var init_explain3 = __esm(() => {
   init_esm();
   init_adapters();
   init_config();
+  init_config_path();
   init_runner2();
   init_bulk_runner();
   init_explain2();
@@ -85049,9 +85386,9 @@ function relationBindings(statement) {
   const bindings = [];
   for (const item of statement.from) {
     const source = item;
-    const join28 = typeof source.join === "string" ? source.join.toUpperCase() : "";
-    const nullExtendsPrevious = join28.startsWith("RIGHT") || join28.startsWith("FULL");
-    const nullExtendsCurrent = join28.startsWith("LEFT") || join28.startsWith("FULL");
+    const join30 = typeof source.join === "string" ? source.join.toUpperCase() : "";
+    const nullExtendsPrevious = join30.startsWith("RIGHT") || join30.startsWith("FULL");
+    const nullExtendsCurrent = join30.startsWith("LEFT") || join30.startsWith("FULL");
     if (nullExtendsPrevious) {
       for (const binding of bindings)
         binding.nullExtended = true;
@@ -86220,6 +86557,7 @@ var init_lint = __esm(() => {
   init_context2();
   init_saved_queries();
   init_integration_helper();
+  init_config_path();
   FORMATS2 = ["text", "json", "markdown"];
   SEVERITIES = ["info", "warn", "error"];
   SQL_SYSTEMS5 = ["postgresql", "mysql", "mariadb"];
@@ -86245,9 +86583,9 @@ var init_lint = __esm(() => {
 });
 
 // src/core/result-snapshot/fingerprint.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 function sha256(input) {
-  return createHash2("sha256").update(input).digest("hex");
+  return createHash3("sha256").update(input).digest("hex");
 }
 function isNumeric(values) {
   return values.length > 0 && values.every((v) => typeof v === "number");
@@ -86366,7 +86704,7 @@ var init_serializer = __esm(() => {
 });
 
 // src/commands/snapshot.ts
-import { join as join28 } from "path";
+import { join as join30 } from "path";
 function requireSqlConnection9(connection) {
   if (!SQL_SYSTEMS6.includes(connection.system)) {
     throw new Error(`snapshot currently supports SQL engines only, got: ${connection.system}`);
@@ -86379,13 +86717,14 @@ function pad2(n) {
 function defaultSnapshotPath() {
   const d = new Date;
   const stamp = `${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
-  return join28(".dbcli", "snapshots", `snap-${stamp}.json`);
+  return join30(".dbcli", "snapshots", `snap-${stamp}.json`);
 }
 var ALLOWED_FORMATS12, SQL_SYSTEMS6, snapshotCommand;
 var init_snapshot = __esm(() => {
   init_esm();
   init_adapters();
   init_config();
+  init_config_path();
   init_validation();
   init_blacklist_validator();
   init_query_executor();
@@ -86630,6 +86969,7 @@ var init_assert = __esm(() => {
   init_esm();
   init_adapters();
   init_config();
+  init_config_path();
   init_validation();
   init_blacklist_validator();
   init_query_executor();
@@ -88676,6 +89016,7 @@ var init_verify2 = __esm(() => {
   init_esm();
   init_adapters();
   init_config();
+  init_config_path();
   init_blacklist_validator();
   init_query_executor();
   init_query_risk_analyzer();
@@ -89104,11 +89445,11 @@ var init_envelope_schema = __esm(() => {
 });
 
 // src/commands/recover.ts
-import { stat as stat6 } from "fs/promises";
-import { resolve as resolve7 } from "path";
+import { stat as stat7 } from "fs/promises";
+import { resolve as resolve8 } from "path";
 async function resolveApplySource(opts) {
   if (opts.from !== undefined) {
-    const path5 = resolve7(opts.cwd, opts.from);
+    const path5 = resolve8(opts.cwd, opts.from);
     let raw;
     try {
       raw = await Bun.file(path5).text();
@@ -89128,7 +89469,7 @@ async function resolveApplySource(opts) {
       }
       const saved2 = r3.value;
       try {
-        await stat6(saved2.cwd);
+        await stat7(saved2.cwd);
       } catch {
         throw new RecoverCliError(`--from ${opts.from}: saved cwd '${saved2.cwd}' no longer exists.`, EXIT_CODE.malformed);
       }
@@ -89162,7 +89503,7 @@ async function resolveApplySource(opts) {
   }
   const saved = r.value;
   try {
-    await stat6(saved.cwd);
+    await stat7(saved.cwd);
   } catch {
     throw new RecoverCliError(`Auto-saved ${LAST_ENVELOPE_PATH} references cwd '${saved.cwd}' that no longer exists.`, EXIT_CODE.malformed);
   }
@@ -89364,13 +89705,13 @@ Verification artifact: ${verificationArtifactPath}`);
 });
 
 // src/commands/audit.ts
-import { rm as rm3, stat as stat7 } from "fs/promises";
-import { join as join29 } from "path";
+import { rm as rm3, stat as stat8 } from "fs/promises";
+import { join as join31 } from "path";
 async function resolveAuditPaths(configPath, config) {
   const storagePath = await resolveConfigStoragePath(configPath);
   const connName = config.effectiveConnectionName || getGlobalConnectionName() || "default";
-  const auditDir = join29(storagePath, ".dbcli", "audit");
-  const auditFile = join29(auditDir, `${connName}.jsonl`);
+  const auditDir = join31(storagePath, ".dbcli", "audit");
+  const auditFile = join31(auditDir, `${connName}.jsonl`);
   return { auditDir, connectionName: connName, auditFile };
 }
 function isAuditDisabled(config) {
@@ -89519,7 +89860,7 @@ function renderHealthTable(h) {
 `);
 }
 function readLineFromStdinWithStderrPrompt(prompt) {
-  return new Promise((resolve8) => {
+  return new Promise((resolve9) => {
     process.stderr.write(prompt);
     const chunks = [];
     let data = "";
@@ -89532,12 +89873,12 @@ function readLineFromStdinWithStderrPrompt(prompt) {
         process.stdin.pause();
         process.stdin.removeListener("data", onData);
         process.stdin.removeListener("end", onEnd);
-        resolve8((lines[0] ?? "").trim());
+        resolve9((lines[0] ?? "").trim());
       }
     };
     const onEnd = () => {
       process.stdin.removeListener("data", onData);
-      resolve8(data.trim());
+      resolve9(data.trim());
     };
     process.stdin.on("data", onData);
     process.stdin.on("end", onEnd);
@@ -89546,7 +89887,7 @@ function readLineFromStdinWithStderrPrompt(prompt) {
 }
 async function statAuditFile(file) {
   try {
-    const s = await stat7(file);
+    const s = await stat8(file);
     const entries = (await readEntries(file)).length;
     return { entries, size: formatBytes(s.size) };
   } catch {
@@ -89557,6 +89898,7 @@ var ALLOWED_FORMATS18, DEFAULT_TAIL_N = 10, MAX_TAIL_N = 1e4, SHORT_ID_LEN = 8,
 var init_audit = __esm(() => {
   init_esm();
   init_message_loader();
+  init_config_path();
   init_validation();
   init_config();
   init_config_binding();
@@ -89796,8 +90138,62 @@ var init_audit = __esm(() => {
   });
 });
 
+// src/utils/runtime-info.ts
+import { join as join32, normalize, relative as relative3, sep as sep5 } from "path";
+function normalized(path5) {
+  return normalize(path5).replaceAll("\\", "/");
+}
+function isWithin(child, parent) {
+  const rel = relative3(parent, child);
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep5}`) && !rel.startsWith("/");
+}
+function inferRuntimeSource(launcherPath, packageRoot) {
+  const launcher = normalized(launcherPath);
+  const root = normalized(packageRoot);
+  if (launcher.includes("/.bunx/") || launcher.includes("/bunx/") || root.includes("/.bun/install/cache/")) {
+    return "bunx";
+  }
+  if (isWithin(launcher, `${root}/src`) || isWithin(launcher, `${root}/scripts`)) {
+    return "workspace";
+  }
+  if (isWithin(launcher, `${root}/dist`))
+    return "installed";
+  return "unknown";
+}
+async function collectRuntimeInfo(packageVersion) {
+  const packageRoot = findPackageRoot();
+  const launcherPath = process.argv[1] ?? "unknown";
+  let packageFileVersion = null;
+  try {
+    const packageFile = Bun.file(join32(packageRoot, "package.json"));
+    if (await packageFile.exists()) {
+      const parsed = await packageFile.json();
+      if (typeof parsed.version === "string" && parsed.version.length > 0) {
+        packageFileVersion = parsed.version;
+      }
+    }
+  } catch {}
+  const versions = process.versions;
+  const runtimeName = versions.bun ? "bun" : versions.node ? "node" : "other";
+  const runtimeVersion = versions[runtimeName] ?? "unknown";
+  return {
+    executablePath: process.execPath,
+    launcherPath,
+    packageRoot,
+    packageVersion,
+    packageFileVersion,
+    runtimeName,
+    runtimeVersion,
+    source: inferRuntimeSource(launcherPath, packageRoot),
+    versionMismatch: packageFileVersion !== null && packageFileVersion !== packageVersion
+  };
+}
+var init_runtime_info = __esm(() => {
+  init_package_root();
+});
+
 // src/commands/doctor.ts
-import { join as join30 } from "path";
+import { join as join33 } from "path";
 import { resolveSrv as resolveSrv2 } from "dns/promises";
 function requireSqlConnection12(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
@@ -89805,6 +90201,87 @@ function requireSqlConnection12(connection) {
   }
   return connection;
 }
+function safeSqlIdentifier(value) {
+  return /^[A-Za-z_][A-Za-z0-9_$]*(?:\.[A-Za-z_][A-Za-z0-9_$]*)*$/.test(value) ? value : null;
+}
+function boundedSampleCommands(system, table) {
+  if (system === "mongodb") {
+    const collection = shellQuote(table);
+    const query = shellQuote("{}");
+    return {
+      dryRun: `dbcli schema ${collection} --format json`,
+      apply: `dbcli query ${query} --collection ${collection} --limit 100 --format json`
+    };
+  }
+  if (system === "elasticsearch") {
+    const index = shellQuote(table);
+    const query = shellQuote('{"query":{"match_all":{}}}');
+    return {
+      dryRun: `dbcli schema ${index} --format json`,
+      apply: `dbcli query ${query} --collection ${index} --limit 100 --format json`
+    };
+  }
+  const identifier = safeSqlIdentifier(table);
+  if (!identifier) {
+    return {
+      dryRun: `dbcli schema ${shellQuote(table)} --format json`
+    };
+  }
+  const sql = `SELECT * FROM ${identifier} LIMIT 100`;
+  const command = shellQuote(sql);
+  return {
+    dryRun: `dbcli plan ${command} --format json`,
+    apply: `dbcli query ${command} --format json`
+  };
+}
+function buildDoctorRemediationPlan(results) {
+  const steps = [];
+  for (const result of results) {
+    if (result.label === "Blacklist completeness" && result.status === "warn") {
+      const prefix = "Consider protecting: ";
+      const candidates = result.message.startsWith(prefix) ? result.message.slice(prefix.length).split(", ").filter(Boolean) : [];
+      for (const candidate of candidates) {
+        const [table, column] = candidate.split(".");
+        if (!table || !column)
+          continue;
+        steps.push({
+          kind: "blacklist-candidate",
+          status: "candidate",
+          rationale: `Sensitive-looking column '${candidate}' is not currently protected.`,
+          dryRun: `dbcli schema ${shellQuote(table)} --format json`,
+          apply: `dbcli blacklist column add ${shellQuote(candidate)}`,
+          requiresHumanConfirmation: true
+        });
+      }
+    }
+    if (result.label === "Schema cache" && result.status === "warn") {
+      steps.push({
+        kind: "schema-refresh",
+        status: "candidate",
+        rationale: result.message,
+        dryRun: "dbcli schema --format json",
+        apply: "dbcli schema --refresh",
+        requiresHumanConfirmation: true
+      });
+    }
+    if (result.label === "Large tables" && result.status === "warn") {
+      const target = result.details?.system ?? "postgresql";
+      const tables = Array.isArray(result.details?.largeTables) ? result.details.largeTables.filter((table) => typeof table === "object" && table !== null && typeof table.name === "string") : [];
+      const candidates = tables.length > 0 ? tables : result.message.replace(/^Large tables:\s*/, "").split(/,\s+(?=[^,]+\s+\([\d.]+M rows\))/).map((entry) => ({ name: entry.replace(/\s+\([\d.]+M rows\)$/, "") }));
+      for (const table of candidates) {
+        const commands = boundedSampleCommands(target, table.name);
+        steps.push({
+          kind: "bounded-sample",
+          status: "candidate",
+          rationale: `${table.name} is large. Review a bounded sample only after confirming blacklist coverage.${commands.apply ? "" : " The identifier needs manual review before a sample query can be generated safely."}`,
+          ...commands,
+          requiresHumanConfirmation: true
+        });
+      }
+    }
+  }
+  return steps;
+}
 function resolveSchemaLastUpdated(indexJson, configMetadata) {
   if (indexJson && typeof indexJson === "object") {
     const idx = indexJson;
@@ -89869,7 +90346,7 @@ async function collectMongoDoctorResults(config) {
     results.push(runDoctorChecks.checkLargeTables(collections.map((coll) => ({
       name: coll.name,
       estimatedRowCount: coll.estimatedRowCount
-    }))));
+    })), "mongodb"));
     results.push({
       group: "Connection & Data",
       label: "Collections",
@@ -89919,7 +90396,7 @@ async function collectElasticsearchDoctorResults(config) {
     if (config.blacklistedColumns) {
       results.push(runDoctorChecks.checkBlacklistCompleteness(tableColumns, config.blacklistedColumns));
     }
-    results.push(runDoctorChecks.checkLargeTables(tables));
+    results.push(runDoctorChecks.checkLargeTables(tables, "elasticsearch"));
     const lastUpdated = config.metadata?.schemaLastUpdated ?? null;
     results.push(runDoctorChecks.checkSchemaCacheFreshness(lastUpdated));
   } catch (error) {
@@ -89945,9 +90422,11 @@ var init_doctor = __esm(() => {
   init_message_loader();
   init_validation();
   init_config_v2();
+  init_config_path();
   init_config_binding();
   init_package();
   init_schema_path();
+  init_runtime_info();
   init_config();
   init_integration_helper();
   ALLOWED_FORMATS19 = ["text", "json"];
@@ -89968,6 +90447,33 @@ var init_doctor = __esm(() => {
     "credit_card"
   ];
   runDoctorChecks = {
+    checkRuntime(info) {
+      const fileVersion = info.packageFileVersion ?? "unavailable";
+      const versionMismatch = info.versionMismatch ? ` (bundle/package mismatch: runtime=${info.packageVersion}, package.json=${fileVersion})` : "";
+      return {
+        group: "Environment",
+        label: "Runtime identity",
+        status: info.versionMismatch ? "warn" : "pass",
+        message: `source=${info.source}; runtime=${info.runtimeName} ${info.runtimeVersion}; ` + `executable=${info.executablePath}; launcher=${info.launcherPath}; ` + `package=${info.packageVersion}${versionMismatch}`,
+        details: {
+          source: info.source,
+          runtimeName: info.runtimeName,
+          runtimeVersion: info.runtimeVersion,
+          executablePath: info.executablePath,
+          launcherPath: info.launcherPath,
+          packageRoot: info.packageRoot,
+          packageVersion: info.packageVersion,
+          packageFileVersion: info.packageFileVersion,
+          versionMismatch: info.versionMismatch
+        },
+        ...info.versionMismatch && {
+          remediation: {
+            command: "dbcli upgrade",
+            risk: "interactive"
+          }
+        }
+      };
+    },
     checkBunVersion(current, required) {
       const passes = compareSemver(current, required) >= 0;
       return {
@@ -90003,12 +90509,18 @@ var init_doctor = __esm(() => {
       }
     },
     async checkConfigExists(configPath, existsFn) {
-      const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join30(configPath, "config.json")).exists();
+      const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join33(configPath, "config.json")).exists();
       return {
         group: "Configuration",
         label: "Config exists",
         status: exists ? "pass" : "error",
-        message: exists ? `Config found: ${configPath}` : `No config found at ${configPath}. Run "dbcli init" first.`
+        message: exists ? `Config found: ${configPath}` : `No config found at ${configPath}. Run "dbcli init" first.`,
+        ...!exists && {
+          remediation: {
+            command: "dbcli init",
+            risk: "interactive"
+          }
+        }
       };
     },
     checkBlacklistCompleteness(tableColumns, blacklistedColumns) {
@@ -90139,7 +90651,7 @@ var init_doctor = __esm(() => {
         }
       }
     },
-    checkLargeTables(tables) {
+    checkLargeTables(tables, system = "postgresql") {
       const large = tables.filter((t2) => (t2.estimatedRowCount ?? 0) > 1e6);
       if (large.length === 0) {
         return {
@@ -90154,13 +90666,17 @@ var init_doctor = __esm(() => {
         group: "Connection & Data",
         label: "Large tables",
         status: "warn",
-        message: `Large tables: ${list}`
+        message: `Large tables: ${list}`,
+        details: {
+          system,
+          largeTables: large.map(({ name: name2, estimatedRowCount }) => ({ name: name2, estimatedRowCount }))
+        }
       };
     },
     async checkV2Config(configPath) {
       const results = [];
       const storagePath = await resolveConfigStoragePath(configPath);
-      const configFile = Bun.file(join30(storagePath, "config.json"));
+      const configFile = Bun.file(join33(storagePath, "config.json"));
       if (!await configFile.exists())
         return results;
       let raw;
@@ -90200,7 +90716,7 @@ var init_doctor = __esm(() => {
       }
       for (const [name2, conn] of Object.entries(config.connections)) {
         if (conn.envFile) {
-          const envPath = join30(storagePath, conn.envFile);
+          const envPath = join33(storagePath, conn.envFile);
           const exists = await Bun.file(envPath).exists();
           results.push({
             group: "Configuration",
@@ -90234,7 +90750,7 @@ var init_doctor = __esm(() => {
 `);
     }
   };
-  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) => {
+  doctorCommand = new Command("doctor").description("Run diagnostic checks on dbcli configuration, environment, and connection").option("--format <type>", "Output format: text, json", "text").option("--remediation", "Include a non-mutating, human-confirmed remediation plan", false).action(async (options) => {
     validateFormat(options.format, ALLOWED_FORMATS19, "doctor");
     const logger = getLogger();
     const results = [];
@@ -90242,6 +90758,7 @@ var init_doctor = __esm(() => {
     const storagePath = await resolveConfigStoragePath(configPath);
     const bunVersion = process.versions.bun ?? "unknown";
     const requiredBun = package_default.engines?.bun?.replace(">=", "") ?? "1.3.3";
+    results.push(runDoctorChecks.checkRuntime(await collectRuntimeInfo(package_default.version)));
     results.push(runDoctorChecks.checkBunVersion(bunVersion, requiredBun));
     results.push(await runDoctorChecks.checkLatestVersion(package_default.version));
     const configExists = await runDoctorChecks.checkConfigExists(storagePath);
@@ -90303,13 +90820,13 @@ var init_doctor = __esm(() => {
                 tableColumns.set(t2.name, t2.columns.map((c2) => c2.name));
               }
               results.push(runDoctorChecks.checkBlacklistCompleteness(tableColumns, blacklistedColumns));
-              results.push(runDoctorChecks.checkLargeTables(tables));
+              results.push(runDoctorChecks.checkLargeTables(tables, config.connection.system));
             } catch {
               logger.debug("Could not list tables for blacklist/large table check");
             }
             try {
               const schemaConnName = await getSchemaIsolationConnectionName(configPath);
-              const indexPath = join30(resolveSchemaPath(storagePath, schemaConnName), "index.json");
+              const indexPath = join33(resolveSchemaPath(storagePath, schemaConnName), "index.json");
               const indexFile = Bun.file(indexPath);
               let indexParsed = null;
               if (await indexFile.exists()) {
@@ -90352,7 +90869,8 @@ var init_doctor = __esm(() => {
       });
     } catch {}
     if (options.format === "json") {
-      console.log(JSON.stringify({ results, hasError }, null, 2));
+      const remediation = options.remediation ? buildDoctorRemediationPlan(results) : undefined;
+      console.log(JSON.stringify({ results, hasError, ...remediation && { remediation } }, null, 2));
     } else {
       console.log(runDoctorChecks.formatTextOutput(results, package_default.version));
     }
@@ -90417,9 +90935,9 @@ function flattenCommandTree(root) {
 }
 
 // src/commands/completion.ts
-import { join as join31 } from "path";
+import { join as join34 } from "path";
 import { homedir as homedir3 } from "os";
-import { mkdir as mkdir14 } from "fs/promises";
+import { mkdir as mkdir15 } from "fs/promises";
 function resolveHome() {
   return process.env.HOME ?? homedir3();
 }
@@ -90669,11 +91187,11 @@ function getInstallPath2(shell) {
   const home = resolveHome();
   switch (shell) {
     case "bash":
-      return join31(home, ".bashrc");
+      return join34(home, ".bashrc");
     case "zsh":
-      return join31(home, ".zshrc");
+      return join34(home, ".zshrc");
     case "fish":
-      return join31(home, ".config", "fish", "completions", "dbcli.fish");
+      return join34(home, ".config", "fish", "completions", "dbcli.fish");
     default:
       throw new Error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
   }
@@ -90691,8 +91209,8 @@ function detectShell() {
 async function installCompletion(shell, script) {
   const targetPath = getInstallPath2(shell);
   if (shell === "fish") {
-    const dir = join31(resolveHome(), ".config", "fish", "completions");
-    await mkdir14(dir, { recursive: true });
+    const dir = join34(resolveHome(), ".config", "fish", "completions");
+    await mkdir15(dir, { recursive: true });
     await Bun.file(targetPath).write(script);
     console.log(colors.success(`\u2713 Fish completion installed to ${targetPath}`));
     return;
@@ -90853,24 +91371,24 @@ var init_types11 = __esm(() => {
 
 // src/core/repl/input-classifier.ts
 function classifyInput(raw) {
-  const normalized = raw.trim();
-  if (normalized === "") {
-    return { type: "empty", raw, normalized };
+  const normalized2 = raw.trim();
+  if (normalized2 === "") {
+    return { type: "empty", raw, normalized: normalized2 };
   }
-  if (normalized.startsWith(META_PREFIX)) {
-    const cmdName = (normalized.split(/\s+/)[0] ?? "").slice(1);
+  if (normalized2.startsWith(META_PREFIX)) {
+    const cmdName = (normalized2.split(/\s+/)[0] ?? "").slice(1);
     if (metaCommandNames.includes(cmdName)) {
-      return { type: "meta", raw, normalized };
+      return { type: "meta", raw, normalized: normalized2 };
     }
   }
-  const firstWord = (normalized.split(/\s+/)[0] ?? "").toUpperCase();
+  const firstWord = (normalized2.split(/\s+/)[0] ?? "").toUpperCase();
   if (sqlKeywordSet.has(firstWord)) {
-    return { type: "sql", raw, normalized };
+    return { type: "sql", raw, normalized: normalized2 };
   }
-  if (normalized.endsWith(SQL_TERMINATOR)) {
-    return { type: "sql", raw, normalized };
+  if (normalized2.endsWith(SQL_TERMINATOR)) {
+    return { type: "sql", raw, normalized: normalized2 };
   }
-  return { type: "command", raw, normalized };
+  return { type: "command", raw, normalized: normalized2 };
 }
 var META_PREFIX = ".", SQL_TERMINATOR = ";", sqlKeywordSet, metaCommandNames;
 var init_input_classifier = __esm(() => {
@@ -91106,7 +91624,7 @@ function isKnownCommand(name2, commandNames) {
 
 // src/core/repl/history-manager.ts
 import { existsSync as existsSync2, readFileSync, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
-import { dirname as dirname10 } from "path";
+import { dirname as dirname12 } from "path";
 
 class HistoryManager {
   filePath;
@@ -91133,7 +91651,7 @@ class HistoryManager {
     return this.entries;
   }
   async save() {
-    const dir = dirname10(this.filePath);
+    const dir = dirname12(this.filePath);
     if (!existsSync2(dir)) {
       mkdirSync2(dir, { recursive: true });
     }
@@ -91676,7 +92194,7 @@ var init_command_registry = __esm(() => {
 
 // src/commands/shell.ts
 import { createInterface as createInterface3 } from "readline";
-import { join as join32 } from "path";
+import { join as join35 } from "path";
 import { homedir as homedir4 } from "os";
 function requireSqlConnection13(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
@@ -91866,10 +92384,11 @@ var init_shell3 = __esm(() => {
   init_adapters();
   init_repl_engine();
   init_completer();
+  init_config_path();
   init_message_loader();
   init_es_shell();
   import_picocolors5 = __toESM(require_picocolors(), 1);
-  HISTORY_PATH = join32(homedir4(), ".dbcli_history");
+  HISTORY_PATH = join35(homedir4(), ".dbcli_history");
   shellCommand = new Command("shell").description("Interactive database shell with auto-completion and syntax highlighting").option("--sql", "SQL-only mode (skip dbcli command parsing)").action(async (options, command) => {
     const configPath = resolveConfigPath(command);
     await runShell(options, configPath);
@@ -92480,8 +92999,8 @@ function requireSqlConnection14(connection) {
   }
   return connection;
 }
-async function runDDL(operation, opts) {
-  const configPath = resolveConfigPath(undefined, opts);
+async function runDDL(operation, opts, command) {
+  const configPath = resolveConfigPath(command, opts);
   const config = await configModule.read(configPath);
   if (!config.connection) {
     throw new Error('Run "dbcli init" to configure database connection');
@@ -92551,8 +93070,9 @@ var init_migrate = __esm(() => {
   init_adapters();
   init_ddl2();
   init_ddl_executor();
+  init_config_path();
   migrateCommand = new Command("migrate").description(t("migrate.description"));
-  addExecOpts(migrateCommand.command("create <table>").description(t("migrate.create_description")).option("--column <spec...>", 'Column definitions (e.g., "id:serial:pk" "name:varchar(50):not-null")')).action(async (table, opts) => {
+  addExecOpts(migrateCommand.command("create <table>").description(t("migrate.create_description")).option("--column <spec...>", 'Column definitions (e.g., "id:serial:pk" "name:varchar(50):not-null")')).action(async (table, opts, command) => {
     try {
       const specs = opts.column || [];
       if (specs.length === 0) {
@@ -92560,19 +93080,19 @@ var init_migrate = __esm(() => {
         process.exit(1);
       }
       const columns = specs.map(parseColumnSpec);
-      await runDDL({ kind: "createTable", table, columns }, opts);
+      await runDDL({ kind: "createTable", table, columns }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("drop <table>").description(t("migrate.drop_description"))).action(async (table, opts) => {
+  addExecOpts(migrateCommand.command("drop <table>").description(t("migrate.drop_description"))).action(async (table, opts, command) => {
     try {
-      await runDDL({ kind: "dropTable", table }, opts);
+      await runDDL({ kind: "dropTable", table }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("add-column <table> <column> <type>").description(t("migrate.add_column_description")).option("--nullable", "Allow NULL values").option("--default <value>", "Default value").option("--unique", "Add UNIQUE constraint")).action(async (table, column, type, opts) => {
+  addExecOpts(migrateCommand.command("add-column <table> <column> <type>").description(t("migrate.add_column_description")).option("--nullable", "Allow NULL values").option("--default <value>", "Default value").option("--unique", "Add UNIQUE constraint")).action(async (table, column, type, opts, command) => {
     try {
       await runDDL({
         kind: "addColumn",
@@ -92584,19 +93104,19 @@ var init_migrate = __esm(() => {
           default: opts.default,
           unique: opts.unique
         }
-      }, opts);
+      }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("drop-column <table> <column>").description(t("migrate.drop_column_description"))).action(async (table, column, opts) => {
+  addExecOpts(migrateCommand.command("drop-column <table> <column>").description(t("migrate.drop_column_description"))).action(async (table, column, opts, command) => {
     try {
-      await runDDL({ kind: "dropColumn", table, column }, opts);
+      await runDDL({ kind: "dropColumn", table, column }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("alter-column <table> <column>").description(t("migrate.alter_column_description")).option("--type <type>", "Change column type").option("--rename <name>", "Rename column").option("--set-default <value>", "Set default value").option("--drop-default", "Remove default value").option("--set-nullable", "Allow NULL").option("--drop-nullable", "Disallow NULL")).action(async (table, column, opts) => {
+  addExecOpts(migrateCommand.command("alter-column <table> <column>").description(t("migrate.alter_column_description")).option("--type <type>", "Change column type").option("--rename <name>", "Rename column").option("--set-default <value>", "Set default value").option("--drop-default", "Remove default value").option("--set-nullable", "Allow NULL").option("--drop-nullable", "Disallow NULL")).action(async (table, column, opts, command) => {
     try {
       await runDDL({
         kind: "alterColumn",
@@ -92610,30 +93130,30 @@ var init_migrate = __esm(() => {
           setNullable: opts.setNullable,
           dropNullable: opts.dropNullable
         }
-      }, opts);
+      }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("add-index <table>").description(t("migrate.add_index_description")).requiredOption("--columns <cols>", "Comma-separated column names").option("--unique", "Create unique index").option("--type <type>", "Index type (btree, hash, gin, gist)").option("--name <name>", "Custom index name")).action(async (table, opts) => {
+  addExecOpts(migrateCommand.command("add-index <table>").description(t("migrate.add_index_description")).requiredOption("--columns <cols>", "Comma-separated column names").option("--unique", "Create unique index").option("--type <type>", "Index type (btree, hash, gin, gist)").option("--name <name>", "Custom index name")).action(async (table, opts, command) => {
     try {
       const columns = opts.columns.split(",").map((c2) => c2.trim());
       await runDDL({
         kind: "addIndex",
         index: { table, columns, unique: opts.unique, type: opts.type, name: opts.name }
-      }, opts);
+      }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("drop-index <index>").description(t("migrate.drop_index_description")).option("--table <table>", "Table name (required for MySQL/MariaDB)")).action(async (indexName, opts) => {
+  addExecOpts(migrateCommand.command("drop-index <index>").description(t("migrate.drop_index_description")).option("--table <table>", "Table name (required for MySQL/MariaDB)")).action(async (indexName, opts, command) => {
     try {
-      await runDDL({ kind: "dropIndex", indexName, table: opts.table }, opts);
+      await runDDL({ kind: "dropIndex", indexName, table: opts.table }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("add-constraint <table>").description(t("migrate.add_constraint_description")).option("--fk <column>", "Foreign key column").option("--references <table.column>", "Referenced table.column").option("--on-delete <action>", "ON DELETE action (cascade, set null, restrict, no action)").option("--unique <columns>", "Unique constraint columns (comma-separated)").option("--check <expression>", "Check constraint expression").option("--name <name>", "Custom constraint name")).action(async (table, opts) => {
+  addExecOpts(migrateCommand.command("add-constraint <table>").description(t("migrate.add_constraint_description")).option("--fk <column>", "Foreign key column").option("--references <table.column>", "Referenced table.column").option("--on-delete <action>", "ON DELETE action (cascade, set null, restrict, no action)").option("--unique <columns>", "Unique constraint columns (comma-separated)").option("--check <expression>", "Check constraint expression").option("--name <name>", "Custom constraint name")).action(async (table, opts, command) => {
     try {
       let type;
       let op;
@@ -92677,35 +93197,35 @@ var init_migrate = __esm(() => {
         process.exit(1);
         return;
       }
-      await runDDL(op, opts);
+      await runDDL(op, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("drop-constraint <table> <constraint>").description(t("migrate.drop_constraint_description"))).action(async (table, constraintName, opts) => {
+  addExecOpts(migrateCommand.command("drop-constraint <table> <constraint>").description(t("migrate.drop_constraint_description"))).action(async (table, constraintName, opts, command) => {
     try {
-      await runDDL({ kind: "dropConstraint", table, constraintName }, opts);
+      await runDDL({ kind: "dropConstraint", table, constraintName }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("add-enum <name> <values...>").description(t("migrate.add_enum_description"))).action(async (name2, values, opts) => {
+  addExecOpts(migrateCommand.command("add-enum <name> <values...>").description(t("migrate.add_enum_description"))).action(async (name2, values, opts, command) => {
     try {
-      await runDDL({ kind: "addEnum", definition: { name: name2, values } }, opts);
+      await runDDL({ kind: "addEnum", definition: { name: name2, values } }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("alter-enum <name>").description(t("migrate.alter_enum_description")).requiredOption("--add-value <value>", "Value to add")).action(async (name2, opts) => {
+  addExecOpts(migrateCommand.command("alter-enum <name>").description(t("migrate.alter_enum_description")).requiredOption("--add-value <value>", "Value to add")).action(async (name2, opts, command) => {
     try {
-      await runDDL({ kind: "alterEnum", name: name2, addValue: opts.addValue }, opts);
+      await runDDL({ kind: "alterEnum", name: name2, addValue: opts.addValue }, opts, command);
     } catch (e) {
       handleError(e);
     }
   });
-  addExecOpts(migrateCommand.command("drop-enum <name>").description(t("migrate.drop_enum_description"))).action(async (name2, opts) => {
+  addExecOpts(migrateCommand.command("drop-enum <name>").description(t("migrate.drop_enum_description"))).action(async (name2, opts, command) => {
     try {
-      await runDDL({ kind: "dropEnum", name: name2 }, opts);
+      await runDDL({ kind: "dropEnum", name: name2 }, opts, command);
     } catch (e) {
       handleError(e);
     }
@@ -92713,12 +93233,13 @@ var init_migrate = __esm(() => {
 });
 
 // src/commands/use.ts
-import { join as join33 } from "path";
-async function switchDefault(configPath, name2, config) {
-  if (!config.connections[name2]) {
-    const available = Object.keys(config.connections).join(", ");
-    throw new ConfigError(`${t_vars("init.connection_not_found", { name: name2 })}. ${t("use.available")}: ${available}`);
+import { join as join36 } from "path";
+async function switchDefault(configPath, name2, config, options = {}) {
+  const connection = config.connections[name2];
+  if (!connection) {
+    throw new ConfigError(connectionNotFoundMessage(name2, Object.keys(config.connections)));
   }
+  assertProductionDefaultConfirmation(name2, connection.environment, options.confirmProduction);
   const updated = {
     ...config,
     default: name2
@@ -92731,12 +93252,31 @@ function listConnectionsForDisplay(config) {
     const host = typeof conn.host === "object" ? `\${${conn.host.$env}}` : conn.host;
     const port = typeof conn.port === "object" ? `\${${conn.port.$env}}` : conn.port;
     const db = typeof conn.database === "object" ? `\${${conn.database.$env}}` : conn.database;
-    return `${marker} ${name2.padEnd(12)} ${conn.system.padEnd(12)} ${host}:${port}/${db}`;
+    const environment = conn.environment ? ` [${conn.environment}]` : "";
+    return `${marker} ${name2.padEnd(12)}${environment} ${conn.system.padEnd(12)} ${host}:${port}/${db}`;
+  });
+}
+function listConnectionIdentities(config) {
+  return Object.entries(config.connections).map(([name2, conn]) => {
+    const host = typeof conn.host === "string" && conn.host.length > 0 ? conn.host : null;
+    const database = typeof conn.database === "string" && conn.database.length > 0 ? conn.database : null;
+    return {
+      name: name2,
+      environment: conn.environment ?? null,
+      permission: conn.permission,
+      system: conn.system,
+      server: {
+        host,
+        port: host !== null && typeof conn.port === "number" ? conn.port : null
+      },
+      database,
+      isDefault: name2 === config.default
+    };
   });
 }
 async function ensureV2Config(configPath) {
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join33(storagePath, "config.json"));
+  const configFile = Bun.file(join36(storagePath, "config.json"));
   const legacyFile = Bun.file(configPath);
   if (!await configFile.exists() && !await legacyFile.exists()) {
     throw new ConfigError(t("init.config_not_found"));
@@ -92772,19 +93312,30 @@ async function ensureV2Config(configPath) {
     throw new ConfigError(t("use.requires_v2"));
   }
 }
-var useCommand;
+var ALLOWED_FORMATS20, useCommand;
 var init_use = __esm(() => {
   init_esm();
   init_config_v2();
   init_config();
-  init_errors3();
+  init_errors2();
+  init_config_path();
   init_message_loader();
   init_config_binding();
-  useCommand = new Command("use").description("Switch or display the default database connection (v2 config)").argument("[name]", "Connection name to switch to").option("--list", "List all connections").action(async (name2, options) => {
+  init_validation();
+  ALLOWED_FORMATS20 = ["text", "json"];
+  useCommand = new Command("use").description("Switch or display the default database connection (v2 config)").argument("[name]", "Connection name to switch to").option("--list", "List all connections").option("--format <format>", "Output format: text (default) or json", "text").option("--confirm-production <name>", "Confirm changing the persisted default to this production connection by repeating its name").action(async (name2, options) => {
     try {
+      validateFormat(String(options.format), ALLOWED_FORMATS20, "use");
       const configPath = resolveConfigPath(useCommand);
       const config = await ensureV2Config(configPath);
+      if (name2 && !options.list && options.format === "json") {
+        throw new ConfigError("--format json is only supported with --list");
+      }
       if (options.list || !name2) {
+        if (options.format === "json") {
+          console.log(JSON.stringify({ connections: listConnectionIdentities(config) }, null, 2));
+          return;
+        }
         if (!name2) {
           console.log(t_vars("use.current", { name: config.default }));
         }
@@ -92794,7 +93345,9 @@ var init_use = __esm(() => {
         }
         return;
       }
-      await switchDefault(configPath, name2, config);
+      await switchDefault(configPath, name2, config, {
+        confirmProduction: typeof options.confirmProduction === "string" ? options.confirmProduction : undefined
+      });
       console.log(t_vars("use.switched", { name: name2 }));
     } catch (error) {
       if (error instanceof Error) {
@@ -92881,8 +93434,8 @@ var init_sql_metadata = __esm(() => {
 });
 
 // src/proxy/events.ts
-import { appendFile as appendFile2, mkdir as mkdir15, readFile as readFile8, stat as stat8 } from "fs/promises";
-import { dirname as dirname11 } from "path";
+import { appendFile as appendFile2, mkdir as mkdir16, readFile as readFile8, stat as stat9 } from "fs/promises";
+import { dirname as dirname13 } from "path";
 function hasSql(e) {
   return e.type === "query_observed" || e.type === "query_completed" || e.type === "query_errored";
 }
@@ -92921,7 +93474,7 @@ class EventWriter {
   }
   async writeInternal(event) {
     if (!this.dirEnsured) {
-      await mkdir15(dirname11(this.path), { recursive: true });
+      await mkdir16(dirname13(this.path), { recursive: true });
       this.dirEnsured = true;
     }
     if (!this.initialized) {
@@ -92943,7 +93496,7 @@ class EventWriter {
   }
   async syncCountersFromDisk() {
     try {
-      const s = await stat8(this.path);
+      const s = await stat9(this.path);
       this.currentSizeBytes = s.size;
       const raw = await readFile8(this.path, "utf8");
       this.currentEntryCount = raw.split(`
@@ -93850,7 +94403,7 @@ function renderAnalysisText(report, top) {
 }
 
 // src/commands/proxy.ts
-import { join as join34 } from "path";
+import { join as join37 } from "path";
 function parseHostPort(value) {
   const idx = value.lastIndexOf(":");
   if (idx <= 0 || idx === value.length - 1) {
@@ -93890,7 +94443,7 @@ function resolveProxyConfig(input) {
 }
 async function runProxy(subcommandEngine, options, command) {
   try {
-    validateFormat(options.format ?? "text", ALLOWED_FORMATS20, "proxy");
+    validateFormat(options.format ?? "text", ALLOWED_FORMATS21, "proxy");
     const redact = options.redact ?? "none";
     if (!ALLOWED_REDACT.includes(redact)) {
       throw new Error(`Invalid --redact "${redact}". Allowed: none, literals`);
@@ -93913,7 +94466,7 @@ async function runProxy(subcommandEngine, options, command) {
       target: options.target,
       connection
     });
-    const eventsPath = options.events ?? join34(".dbcli", "proxy", "events.jsonl");
+    const eventsPath = options.events ?? join37(".dbcli", "proxy", "events.jsonl");
     const slowMs = Number(options.slowMs ?? 1000);
     if (!Number.isFinite(slowMs) || slowMs < 0) {
       throw new Error(`Invalid --slow-ms "${options.slowMs}". Expected a non-negative number`);
@@ -93945,12 +94498,12 @@ async function runProxy(subcommandEngine, options, command) {
 ` + `Press Ctrl+C to stop.
 `);
     }
-    await new Promise((resolve8) => {
+    await new Promise((resolve9) => {
       const shutdown = () => {
         process.removeListener("SIGINT", shutdown);
         process.removeListener("SIGTERM", shutdown);
         server.stop();
-        resolve8();
+        resolve9();
       };
       process.on("SIGINT", shutdown);
       process.on("SIGTERM", shutdown);
@@ -93962,7 +94515,7 @@ async function runProxy(subcommandEngine, options, command) {
   }
 }
 function addCommonOptions(cmd) {
-  return cmd.option("--listen <host:port>", "Local proxy listen address (required)").option("--target <host:port>", "Upstream DB target (optional when config provides host/port)").option("--events <path>", "Event JSONL path", join34(".dbcli", "proxy", "events.jsonl")).option("--slow-ms <number>", "Threshold (ms); queries at/above it get slow:true in the event + a terminal warning", "1000").option("--redact <mode>", "SQL redaction: none | literals", "none").option("--format <format>", "Runtime status output: text | json", "text");
+  return cmd.option("--listen <host:port>", "Local proxy listen address (required)").option("--target <host:port>", "Upstream DB target (optional when config provides host/port)").option("--events <path>", "Event JSONL path", join37(".dbcli", "proxy", "events.jsonl")).option("--slow-ms <number>", "Threshold (ms); queries at/above it get slow:true in the event + a terminal warning", "1000").option("--redact <mode>", "SQL redaction: none | literals", "none").option("--format <format>", "Runtime status output: text | json", "text");
 }
 function parseNonNegInt(value, flag, fallback) {
   if (value === undefined)
@@ -93980,7 +94533,7 @@ async function runAnalyze(options) {
     const top = parseNonNegInt(options.top, "top", 20);
     const slowMs = parseNonNegInt(options.slowMs, "slow-ms", 1000);
     const nPlusOne = parseNonNegInt(options.nPlusOne, "n-plus-one", 10);
-    const eventsPath = options.events ?? join34(".dbcli", "proxy", "events.jsonl");
+    const eventsPath = options.events ?? join37(".dbcli", "proxy", "events.jsonl");
     const { events, malformedLines, files } = await readEvents(eventsPath, {
       includeRotated: options.includeRotated !== false
     });
@@ -94007,16 +94560,17 @@ async function runAnalyze(options) {
     process.exit(1);
   }
 }
-var SUPPORTED, ALLOWED_FORMATS20, ALLOWED_REDACT, proxyCommand, ANALYZE_FORMATS;
+var SUPPORTED, ALLOWED_FORMATS21, ALLOWED_REDACT, proxyCommand, ANALYZE_FORMATS;
 var init_proxy = __esm(() => {
   init_esm();
   init_config();
+  init_config_path();
   init_validation();
   init_server();
   init_event_reader();
   init_analyze();
   SUPPORTED = ["mysql", "mariadb", "postgresql"];
-  ALLOWED_FORMATS20 = ["text", "json"];
+  ALLOWED_FORMATS21 = ["text", "json"];
   ALLOWED_REDACT = ["none", "literals"];
   proxyCommand = new Command().name("proxy").description("Local development observability proxy for MySQL/MariaDB/PostgreSQL (observe-only)");
   proxyCommand.enablePositionalOptions();
@@ -94026,7 +94580,7 @@ var init_proxy = __esm(() => {
     });
   }
   ANALYZE_FORMATS = ["json", "text"];
-  proxyCommand.command("analyze").description("Analyze a proxy event log offline (no DB connection)").option("--events <path>", "Event JSONL path", join34(".dbcli", "proxy", "events.jsonl")).option("--format <format>", "Output format: json | text", "json").option("--top <number>", "Rows shown in text + suggestedCommands depth", "20").option("--slow-ms <number>", "Slow-query threshold (ms) for slowCount", "1000").option("--n-plus-one <number>", "Min repeats per (session,fingerprint) to flag N+1", "10").option("--no-include-rotated", "Do not merge the rotated <events>.1 segment").action(async (options) => {
+  proxyCommand.command("analyze").description("Analyze a proxy event log offline (no DB connection)").option("--events <path>", "Event JSONL path", join37(".dbcli", "proxy", "events.jsonl")).option("--format <format>", "Output format: json | text", "json").option("--top <number>", "Rows shown in text + suggestedCommands depth", "20").option("--slow-ms <number>", "Slow-query threshold (ms) for slowCount", "1000").option("--n-plus-one <number>", "Min repeats per (session,fingerprint) to flag N+1", "10").option("--no-include-rotated", "Do not merge the rotated <events>.1 segment").action(async (options) => {
     await runAnalyze(options);
   });
   addCommonOptions(proxyCommand).action(async (options, command) => {
@@ -94034,6 +94588,264 @@ var init_proxy = __esm(() => {
   });
 });
 
+// src/core/backfill-artifact.ts
+import { createHash as createHash4 } from "crypto";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireIdentifier(value, label) {
+  if (typeof value !== "string" || !/^[A-Za-z_][A-Za-z0-9_$.]*$/.test(value)) {
+    throw new Error(`${label} must be a SQL identifier containing only letters, numbers, _, $, or .`);
+  }
+  return value;
+}
+function sqlLiteral(value, targetSystem) {
+  if (value === null)
+    return "NULL";
+  if (typeof value === "string") {
+    if (targetSystem === "mysql" || targetSystem === "mariadb") {
+      const hex = Buffer.from(value, "utf8").toString("hex");
+      return `CONVERT(UNHEX('${hex}') USING utf8mb4)`;
+    }
+    return `'${value.replaceAll("'", "''")}'`;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("Source rows cannot contain non-finite numbers");
+    return String(value);
+  }
+  if (typeof value === "boolean")
+    return value ? "TRUE" : "FALSE";
+  throw new Error("Source row values must be strings, finite numbers, booleans, or null");
+}
+function stripSqlCommentsAndStrings(sql) {
+  let result = "";
+  let index = 0;
+  while (index < sql.length) {
+    const current = sql[index];
+    const next = sql[index + 1];
+    if (current === "-" && next === "-") {
+      index += 2;
+      while (index < sql.length && sql[index] !== `
+`)
+        index += 1;
+      result += `
+`;
+      continue;
+    }
+    if (current === "/" && next === "*") {
+      index += 2;
+      while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/"))
+        index += 1;
+      index += 2;
+      result += " ";
+      continue;
+    }
+    if (current === "'") {
+      index += 1;
+      while (index < sql.length) {
+        if (sql[index] === "'" && sql[index + 1] === "'") {
+          index += 2;
+          continue;
+        }
+        if (sql[index] === "'") {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      result += " ";
+      continue;
+    }
+    result += current;
+    index += 1;
+  }
+  return result;
+}
+function assertReadOnlyVerifyQuery(query) {
+  const normalized2 = stripSqlCommentsAndStrings(query).trim();
+  if (!/^SELECT\b/i.test(normalized2) || /;/.test(normalized2)) {
+    throw new Error("verifyQuery must be a single plain read-only SELECT statement");
+  }
+  if (/\b(?:INSERT|UPDATE|DELETE|MERGE|UPSERT|REPLACE|TRUNCATE|DROP|ALTER|CREATE|GRANT|REVOKE|RENAME|INTO|LOCK|CALL|DO|FOR\s+(?:UPDATE|SHARE|NO\s+KEY\s+UPDATE|KEY\s+SHARE))\b/i.test(normalized2)) {
+    throw new Error("verifyQuery must not contain a write or DDL statement");
+  }
+  return query.trim();
+}
+function parseBackfillSourceManifest(raw) {
+  if (!isRecord2(raw))
+    throw new Error("Source manifest must be a JSON object");
+  const table = requireIdentifier(raw.table, "table");
+  if (!Array.isArray(raw.keyColumns) || raw.keyColumns.length === 0) {
+    throw new Error("keyColumns must be a non-empty array");
+  }
+  const keyColumns = raw.keyColumns.map((column) => requireIdentifier(column, "keyColumns entry"));
+  if (new Set(keyColumns).size !== keyColumns.length) {
+    throw new Error("keyColumns must not contain duplicates");
+  }
+  if (!Array.isArray(raw.rows) || raw.rows.length === 0) {
+    throw new Error("rows must be a non-empty array");
+  }
+  if (raw.rows.length > MAX_SOURCE_ROWS) {
+    throw new Error(`rows exceeds the bounded maximum of ${MAX_SOURCE_ROWS}`);
+  }
+  const rows = raw.rows.map((row, index) => {
+    if (!isRecord2(row))
+      throw new Error(`rows[${index}] must be an object`);
+    for (const key of keyColumns) {
+      if (!(key in row))
+        throw new Error(`rows[${index}] is missing key column '${key}'`);
+    }
+    return row;
+  });
+  if (typeof raw.verifyQuery !== "string" || raw.verifyQuery.trim() === "") {
+    throw new Error("verifyQuery must be a non-empty string");
+  }
+  if (typeof raw.expect !== "string" || raw.expect.trim() === "") {
+    throw new Error("expect must be a non-empty string");
+  }
+  if (raw.rollbackHint !== undefined && typeof raw.rollbackHint !== "string") {
+    throw new Error("rollbackHint must be a string when provided");
+  }
+  return {
+    table,
+    keyColumns,
+    rows,
+    verifyQuery: assertReadOnlyVerifyQuery(raw.verifyQuery),
+    expect: raw.expect.trim(),
+    rollbackHint: raw.rollbackHint
+  };
+}
+function generateBackfillSql(manifest, targetSystem = "postgresql") {
+  return manifest.rows.map((row, index) => {
+    const setColumns = Object.keys(row).filter((column) => !manifest.keyColumns.includes(column));
+    if (setColumns.length === 0)
+      throw new Error(`rows[${index}] has no non-key columns to update`);
+    const set = setColumns.map((column) => `${requireIdentifier(column, `rows[${index}] column`)} = ${sqlLiteral(row[column], targetSystem)}`).join(", ");
+    const where = manifest.keyColumns.map((column) => {
+      const value = row[column];
+      return value === null ? `${column} IS NULL` : `${column} = ${sqlLiteral(value, targetSystem)}`;
+    }).join(" AND ");
+    return `UPDATE ${manifest.table} SET ${set} WHERE ${where}`;
+  });
+}
+function compareBackfillIdentities(source, target) {
+  const differences = [];
+  for (const field of ["environment", "system", "database"]) {
+    if (source[field] !== target[field])
+      differences.push(`${field}: ${String(source[field])} -> ${String(target[field])}`);
+  }
+  if (source.server.host !== target.server.host || source.server.port !== target.server.port) {
+    differences.push(`server: ${source.server.host ?? "unknown"}:${source.server.port ?? "unknown"} -> ${target.server.host ?? "unknown"}:${target.server.port ?? "unknown"}`);
+  }
+  return differences;
+}
+function buildBackfillArtifact(input) {
+  if (!SQL_TARGET_SYSTEMS.has(input.targetIdentity.system)) {
+    throw new Error(`Source-to-SQL backfill artifacts require a SQL target connection; '${input.targetIdentity.system}' is not supported`);
+  }
+  const statements = generateBackfillSql(input.manifest, input.targetIdentity.system);
+  const target = input.targetIdentity.name;
+  const targetArg = shellQuote(target);
+  const tableArg = shellQuote(input.manifest.table);
+  const planCommand2 = (sql) => `dbcli --use ${targetArg} plan ${shellQuote(sql)} --format json`;
+  const lastStatement = statements[statements.length - 1];
+  return {
+    schemaVersion: BACKFILL_ARTIFACT_SCHEMA_VERSION,
+    kind: "source-to-sql-backfill",
+    createdAt: (input.now ?? new Date).toISOString(),
+    source: {
+      path: input.sourcePath,
+      sha256: createHash4("sha256").update(input.sourceContent).digest("hex"),
+      rowCount: input.manifest.rows.length
+    },
+    table: input.manifest.table,
+    sourceIdentity: input.sourceIdentity,
+    targetIdentity: input.targetIdentity,
+    identityDiff: compareBackfillIdentities(input.sourceIdentity, input.targetIdentity),
+    statements: statements.map((sql) => ({ sql, planCommand: planCommand2(sql) })),
+    preflight: [
+      `dbcli --use ${targetArg} blacklist list --format json`,
+      `dbcli --use ${targetArg} schema ${tableArg} --format json`,
+      ...statements.map(planCommand2)
+    ],
+    readBack: {
+      query: input.manifest.verifyQuery,
+      expect: input.manifest.expect,
+      command: `dbcli --use ${targetArg} verify safe-backfill --table ${tableArg} ` + `--query ${shellQuote(lastStatement)} --verify-query ${shellQuote(input.manifest.verifyQuery)} ` + `--expect ${shellQuote(input.manifest.expect)} --after-write --format json`
+    },
+    rollbackHint: input.manifest.rollbackHint ?? "Capture the prior values before applying this artifact; rollback is a separately reviewed UPDATE with its own verify rollback preflight.",
+    execution: {
+      mode: "dry-run",
+      requiresHumanConfirmation: true,
+      note: "This artifact never executes database writes. Review each plan and apply SQL only through an explicitly human-confirmed workflow."
+    }
+  };
+}
+var BACKFILL_ARTIFACT_SCHEMA_VERSION = 1, MAX_SOURCE_ROWS = 1000, SQL_TARGET_SYSTEMS;
+var init_backfill_artifact = __esm(() => {
+  SQL_TARGET_SYSTEMS = new Set(["postgresql", "mysql", "mariadb"]);
+});
+
+// src/commands/backfill.ts
+import { dirname as dirname14, resolve as resolve9 } from "path";
+import { mkdir as mkdir17 } from "fs/promises";
+function identityFor(config, name2) {
+  const connection = config.connections[name2];
+  if (!connection) {
+    throw new Error(`Connection '${name2}' was not found. Available connections: ${Object.keys(config.connections).join(", ")}`);
+  }
+  const host = typeof connection.host === "string" && connection.host.length > 0 ? connection.host : null;
+  const database = typeof connection.database === "string" && connection.database.length > 0 ? connection.database : null;
+  return {
+    name: name2,
+    environment: connection.environment ?? null,
+    permission: connection.permission,
+    system: connection.system,
+    server: {
+      host,
+      port: host !== null && typeof connection.port === "number" ? connection.port : null
+    },
+    database
+  };
+}
+var backfillCommand;
+var init_backfill = __esm(() => {
+  init_esm();
+  init_config_v2();
+  init_config_path();
+  init_backfill_artifact();
+  backfillCommand = new Command("backfill").description("Generate reviewable source-to-SQL backfill artifacts; never executes writes");
+  backfillCommand.command("artifact").description("Build a dry-run backfill artifact from a bounded JSON source catalog and two named connections").requiredOption("--source <path>", "JSON source catalog with table, keyColumns, rows, verifyQuery, and expect").requiredOption("--source-use <name>", "Named source connection used to identify the catalog environment").requiredOption("--target-use <name>", "Named target connection for generated SQL").option("--out <path>", "Write artifact JSON to this path").option("--stdout", "Print artifact JSON instead of writing it", false).action(async (options, command) => {
+    const configPath = resolveConfigPath(command);
+    const config = await readV2Config(configPath);
+    const sourcePath = resolve9(options.source);
+    const sourceContent = await Bun.file(sourcePath).text();
+    let raw;
+    try {
+      raw = JSON.parse(sourceContent);
+    } catch {
+      throw new Error(`Source catalog is not valid JSON: ${sourcePath}`);
+    }
+    const artifact2 = buildBackfillArtifact({
+      manifest: parseBackfillSourceManifest(raw),
+      sourcePath,
+      sourceContent,
+      sourceIdentity: identityFor(config, options.sourceUse),
+      targetIdentity: identityFor(config, options.targetUse)
+    });
+    if (options.stdout) {
+      console.log(JSON.stringify(artifact2, null, 2));
+      return;
+    }
+    const out = resolve9(options.out ?? `.dbcli/backfills/${artifact2.source.sha256.slice(0, 12)}.json`);
+    await mkdir17(dirname14(out), { recursive: true });
+    await Bun.write(out, JSON.stringify(artifact2, null, 2) + `
+`);
+    console.log(JSON.stringify({ path: out, artifact: artifact2 }, null, 2));
+  });
+});
+
 // src/program.ts
 var exports_program = {};
 __export(exports_program, {
@@ -94082,7 +94894,7 @@ function hasLongOption(rawArgs, option) {
   return false;
 }
 function buildProgram() {
-  const program2 = new Command().name("dbcli").description("Database CLI for AI agents").version(package_default.version).option("--no-color", "Disable colored output").option("-v, --verbose", "Increase verbosity (-v verbose, -vv debug)", (_, prev) => prev + 1, 0).option("-q, --quiet", "Suppress non-essential output").option("--config <path>", "Path to .dbcli config file", ".dbcli").addOption(createConnectionSelectorOption()).enablePositionalOptions();
+  const program2 = new Command().name("dbcli").description("Database CLI for AI agents").version(package_default.version).option("--no-color", "Disable colored output").option("-v, --verbose", "Increase verbosity (-v verbose, -vv debug)", (_, prev) => prev + 1, 0).option("-q, --quiet", "Suppress non-essential output").option("--config <path>", "Path to .dbcli config file", ".dbcli").option("--global", "Use the user-global connection registry (~/.config/dbcli)", false).addOption(createConnectionSelectorOption()).enablePositionalOptions();
   program2.addCommand(initCommand);
   program2.addCommand(listCommand);
   program2.addCommand(schemaCommand);
@@ -94171,6 +94983,7 @@ function buildProgram() {
   program2.addCommand(verificationCommand);
   program2.addCommand(verifyCommand);
   program2.addCommand(proxyCommand);
+  program2.addCommand(backfillCommand);
   return program2;
 }
 var init_program = __esm(() => {
@@ -94213,6 +95026,7 @@ var init_program = __esm(() => {
   init_migrate();
   init_use();
   init_proxy();
+  init_backfill();
   init_connection_selector();
   init_cli_error();
   init_package();
@@ -94226,9 +95040,121 @@ init_version_check();
 init_skill();
 init_config();
 init_connection_selector();
+init_config_path();
+
+// src/utils/cli-output.ts
+var HUMAN_FORMATS = new Set(["text", "table"]);
+function isMachineReadableCommand(actionCommand, rootCommand) {
+  for (let current = actionCommand;current; current = current.parent ?? undefined) {
+    const options = current.opts();
+    if (options.forAgent === true || options.recovery === true)
+      return true;
+    if (typeof options.format === "string" && !HUMAN_FORMATS.has(options.format))
+      return true;
+  }
+  if (rootCommand) {
+    const options = rootCommand.opts();
+    if (options.forAgent === true || options.recovery === true)
+      return true;
+    if (typeof options.format === "string" && !HUMAN_FORMATS.has(options.format))
+      return true;
+  }
+  return false;
+}
+
+// src/utils/update-hint-state.ts
+import { mkdir as mkdir4, open, rename as rename2, stat, unlink as unlink3, writeFile } from "fs/promises";
+import { dirname as dirname4, extname, join as join13 } from "path";
+var MAX_SESSIONS = 32;
+function defaultCliSessionKey() {
+  const explicit = process.env.DBCLI_SESSION_ID || process.env.TERM_SESSION_ID;
+  if (explicit)
+    return explicit;
+  return `ppid:${process.ppid ?? process.pid}`;
+}
+function statePath(configPath) {
+  const looksLikeFile = extname(configPath) !== "" && !configPath.endsWith(".dbcli");
+  const directory = looksLikeFile ? dirname4(configPath) : configPath;
+  return join13(directory, "update-hints.json");
+}
+async function withHintStateLock(path3, work) {
+  const lockPath = `${path3}.lock`;
+  for (let attempt = 0;attempt < 20; attempt += 1) {
+    try {
+      const handle = await open(lockPath, "wx");
+      try {
+        return await work();
+      } finally {
+        await handle.close().catch(() => {
+          return;
+        });
+        await unlink3(lockPath).catch(() => {
+          return;
+        });
+      }
+    } catch (error) {
+      const code = error.code;
+      if (code !== "EEXIST")
+        return null;
+      try {
+        const age = Date.now() - (await stat(lockPath)).mtimeMs;
+        if (age > 1e4)
+          await unlink3(lockPath);
+      } catch {}
+      await Bun.sleep(5);
+    }
+  }
+  return null;
+}
+async function readState(path3) {
+  try {
+    const file = Bun.file(path3);
+    if (!await file.exists())
+      return { version: 1, sessions: {} };
+    const raw = await file.json();
+    if (raw.version !== 1 || !raw.sessions || typeof raw.sessions !== "object") {
+      return { version: 1, sessions: {} };
+    }
+    return { version: 1, sessions: raw.sessions };
+  } catch {
+    return { version: 1, sessions: {} };
+  }
+}
+async function writeState(path3, state) {
+  try {
+    await mkdir4(dirname4(path3), { recursive: true });
+    const temporary = `${path3}.tmp-${process.pid}`;
+    await writeFile(temporary, JSON.stringify(state, null, 2), "utf8");
+    await rename2(temporary, path3);
+  } catch {}
+}
+async function claimUpdateHint(configPath, kind, sessionKey, value) {
+  const path3 = statePath(configPath);
+  await mkdir4(dirname4(path3), { recursive: true }).catch(() => {
+    return;
+  });
+  const claimed = await withHintStateLock(path3, async () => {
+    const state = await readState(path3);
+    const current = state.sessions[sessionKey];
+    if (current?.[kind] !== undefined)
+      return false;
+    state.sessions[sessionKey] = {
+      ...current ?? {},
+      [kind]: value,
+      updatedAt: new Date().toISOString()
+    };
+    const entries = Object.entries(state.sessions).sort((a, b) => a[1].updatedAt.localeCompare(b[1].updatedAt)).slice(-MAX_SESSIONS);
+    state.sessions = Object.fromEntries(entries);
+    await writeState(path3, state);
+    return true;
+  });
+  return claimed === true;
+}
+
+// src/cli.ts
 init_program();
 init_cli_error();
-import { join as join35 } from "path";
+import { join as join38 } from "path";
 import { writeSync as writeSync2 } from "fs";
 import { format } from "util";
 function installSynchronousRedirectedStdout() {
@@ -94269,13 +95195,65 @@ function installSynchronousRedirectedStdout() {
 }
 installSynchronousRedirectedStdout();
 var _bgVersionCheckResult;
+var _bgVersionCheckContext = null;
 function shouldSkipBackgroundChecks() {
   return process.env.DBCLI_NO_UPDATE_CHECK === "1" || process.env.DBCLI_NO_UPDATE_CHECK === "true" || false;
 }
 var QUIET_OUTPUT_COMMANDS = new Set(["upgrade", "completion"]);
 var program2 = buildProgram();
+function misplacedConnectionSelectorHint() {
+  const rawArgs = process.argv.slice(2);
+  let commandName;
+  let commandIndex = -1;
+  for (let index = 0;index < rawArgs.length; index += 1) {
+    const token = rawArgs[index];
+    if (token === "--")
+      break;
+    if (token === "--config" || token === "--use") {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--config=") || token.startsWith("--use=") || token.startsWith("-")) {
+      continue;
+    }
+    commandName = token;
+    commandIndex = index;
+    break;
+  }
+  const command = program2.commands.find((candidate) => candidate.name() === commandName);
+  if (!command || command.options.some((option) => option.long === "--use"))
+    return;
+  const misplacedOptionIndex = rawArgs.findIndex((token, index) => index > commandIndex && (token === "--use" || token.startsWith("--use=")));
+  if (misplacedOptionIndex === -1)
+    return;
+  const commandPath = [command.name()];
+  let currentCommand = command;
+  for (const token of rawArgs.slice(commandIndex + 1, misplacedOptionIndex)) {
+    const child = currentCommand.commands.find((candidate) => candidate.name() === token);
+    if (!child)
+      continue;
+    commandPath.push(child.name());
+    currentCommand = child;
+  }
+  return `Hint: Place --use before the command: dbcli --use <connection> ${commandPath.join(" ")}`;
+}
+function configureConnectionSelectorHints(command) {
+  command.configureOutput({
+    outputError: (message, write) => {
+      const hint = /unknown option '--use(?:'|=)/.test(message) ? misplacedConnectionSelectorHint() : undefined;
+      write(hint ? `${message}${hint}
+` : message);
+    }
+  });
+  for (const child of command.commands)
+    configureConnectionSelectorHints(child);
+}
+configureConnectionSelectorHints(program2);
 program2.hook("preAction", (thisCommand, actionCommand) => {
+  _bgVersionCheckResult = undefined;
+  _bgVersionCheckContext = null;
   const opts = thisCommand.opts();
+  const machineOutput = isMachineReadableCommand(actionCommand, thisCommand);
   setGlobalConnectionName(resolveConnectionSelector({
     root: opts.use,
     command: actionCommand.opts().use,
@@ -94293,13 +95271,18 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
     level = 2 /* VERBOSE */;
   }
   setGlobalLogger(createLogger(level));
-  if (!opts.quiet && !QUIET_OUTPUT_COMMANDS.has(actionCommand.name()) && !shouldSkipBackgroundChecks()) {
-    const configPath = resolveConfigPath(actionCommand);
+  const configPath = resolveConfigPath(actionCommand);
+  _bgVersionCheckContext = {
+    configPath,
+    sessionKey: defaultCliSessionKey(),
+    machineOutput
+  };
+  if (!opts.quiet && !QUIET_OUTPUT_COMMANDS.has(actionCommand.name()) && !machineOutput && !shouldSkipBackgroundChecks()) {
     (async () => {
       try {
         let cache = null;
         try {
-          const cacheFile = Bun.file(join35(configPath, "version-check.json"));
+          const cacheFile = Bun.file(join38(configPath, "version-check.json"));
           if (await cacheFile.exists()) {
             cache = await cacheFile.json();
           }
@@ -94313,14 +95296,15 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
   }
 });
 program2.hook("postAction", async (thisCommand, actionCommand) => {
-  if (_bgVersionCheckResult?.hasUpdate) {
+  const context = _bgVersionCheckContext;
+  if (_bgVersionCheckResult?.hasUpdate && context && !context.machineOutput && !thisCommand.opts().quiet && !QUIET_OUTPUT_COMMANDS.has(actionCommand.name()) && await claimUpdateHint(context.configPath, "update", context.sessionKey, _bgVersionCheckResult.latestVersion)) {
     process.stderr.write(formatUpdateHint(_bgVersionCheckResult.latestVersion) + `
 `);
   }
   const isQuietOutput = QUIET_OUTPUT_COMMANDS.has(actionCommand.name()) || actionCommand.name() === "skill";
-  if (!thisCommand.opts().quiet && !isQuietOutput && !shouldSkipBackgroundChecks()) {
+  if (!thisCommand.opts().quiet && !isQuietOutput && !context?.machineOutput && !shouldSkipBackgroundChecks()) {
     const outdatedSkills = await checkSkillUpdates();
-    if (outdatedSkills.length > 0) {
+    if (outdatedSkills.length > 0 && context && await claimUpdateHint(context.configPath, "skill", context.sessionKey, outdatedSkills.slice().sort().join(","))) {
       process.stderr.write(formatSkillUpdateReminder(outdatedSkills) + `
 `);
     }