@i4ctime/q-ring 0.12.0 → 0.13.1

package/dist/index.js

@@ -42,7 +42,7 @@ import {
   tunnelList,
   tunnelRead,
   verifyAuditChain
-} from "./chunk-5TQNDJT3.js";
+} from "./chunk-Z7UJFHVE.js";
 
 // src/cli/commands.ts
 import { Command, Help } from "commander";
@@ -191,7 +191,40 @@ function importDotenv(filePathOrContent, options = {}) {
 
 // src/utils/prompt.ts
 import { createInterface } from "readline";
+async function confirm(message, { assumeYes = false } = {}) {
+  if (assumeYes) return true;
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "Confirmation required but stdin is not a terminal. Pass --yes to proceed non-interactively."
+    );
+  }
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    terminal: true
+  });
+  const answer = await new Promise((resolve) => {
+    rl.question(`${message} [y/N] `, resolve);
+  });
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
 async function promptSecret(message) {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) {
+    let data = "";
+    stdin.setEncoding("utf8");
+    for await (const chunk of stdin) {
+      data += chunk;
+    }
+    const value = data.replace(/\r?\n$/, "");
+    if (value.length === 0) {
+      throw new Error(
+        "No value provided: stdin is not a terminal and was empty. Pipe the value in, or pass it as an argument."
+      );
+    }
+    return value;
+  }
   const rl = createInterface({
     input: process.stdin,
     output: process.stderr,
@@ -199,7 +232,6 @@ async function promptSecret(message) {
   });
   return new Promise((resolve) => {
     process.stderr.write(message);
-    const stdin = process.stdin;
     const wasRaw = stdin.isRaw;
     if (stdin.isTTY && stdin.setRawMode) {
       stdin.setRawMode(true);
@@ -234,6 +266,11 @@ function wantsJsonOutput(program2, cmd) {
   const g = program2.opts();
   return !!g.json;
 }
+function emitJson(program2, cmd, data) {
+  if (!wantsJsonOutput(program2, cmd)) return false;
+  process.stdout.write(JSON.stringify({ ok: true, data }, null, 2) + "\n");
+  return true;
+}
 function safeStr(s) {
   return s == null ? "" : `${s}`;
 }
@@ -360,17 +397,36 @@ function registerSecretsCommands(program2) {
     const payload = wantsJsonOutput(program2, cmd) ? { ok: true, data: { key, value } } : { key, value };
     process.stdout.write(JSON.stringify(payload) + "\n");
   });
-  program2.command("delete <key>").alias("rm").description("Remove a secret from the keyring").option("-g, --global", "Delete from global scope only").option("-p, --project", "Delete from project scope only").option("--project-path <path>", "Explicit project path").action((key, cmd) => {
+  program2.command("has <key>").description(
+    "Check whether a secret exists (exit 0 if present, 1 if not) \u2014 decay-aware"
+  ).option("-g, --global", "Look only in global scope").option("-p, --project", "Look only in project scope").option("--team <id>", "Look only in team scope").option("--org <id>", "Look only in org scope").option("--project-path <path>", "Explicit project path").option("-q, --quiet", "No output, exit code only (for scripts)").action((key, cmd) => {
     const opts = buildOpts(cmd);
+    const exists = hasSecret(key, opts);
+    if (!cmd.quiet) {
+      if (wantsJsonOutput(program2, cmd)) {
+        console.log(JSON.stringify({ ok: true, data: { key, exists } }));
+      } else {
+        console.log(exists ? "true" : "false");
+      }
+    }
+    if (!exists) process.exitCode = 1;
+  });
+  program2.command("delete <key>").alias("rm").description("Remove a secret from the keyring").option("-g, --global", "Delete from global scope only").option("-p, --project", "Delete from project scope only").option("--project-path <path>", "Explicit project path").option("-y, --yes", "Skip the confirmation prompt").option("--json", "Output as JSON").action(async (key, cmd) => {
+    const opts = buildOpts(cmd);
+    if (!await confirm(`Delete secret ${key}?`, { assumeYes: cmd.yes })) {
+      console.error(c.dim("Aborted."));
+      process.exitCode = 1;
+      return;
+    }
     const deleted = deleteSecret(key, opts);
-    if (deleted) {
-      console.log(`${SYMBOLS.check} ${c.green("deleted")} ${c.bold(key)}`);
-    } else {
+    if (!deleted) {
       console.error(c.red(`${SYMBOLS.cross} Secret "${key}" not found`));
       process.exit(1);
     }
+    if (emitJson(program2, cmd, { key, deleted: true })) return;
+    console.log(`${SYMBOLS.check} ${c.green("deleted")} ${c.bold(key)}`);
   });
-  program2.command("list").alias("ls").description("List all secrets with quantum status indicators").option("-g, --global", "List global scope only").option("-p, --project", "List project scope only").option("--team <id>", "List team scope only").option("--org <id>", "List org scope only").option("--project-path <path>", "Explicit project path").option("--show-decay", "Show decay/expiry status").option("-t, --tag <tag>", "Filter by tag").option("--expired", "Show only expired secrets").option("--stale", "Show only stale secrets (75%+ decay)").option("-f, --filter <pattern>", "Glob pattern on key name").action((cmd) => {
+  program2.command("list").alias("ls").description("List all secrets with quantum status indicators").option("-g, --global", "List global scope only").option("-p, --project", "List project scope only").option("--team <id>", "List team scope only").option("--org <id>", "List org scope only").option("--project-path <path>", "Explicit project path").option("--show-decay", "Show decay/expiry status").option("-t, --tag <tag>", "Filter by tag").option("--expired", "Show only expired secrets").option("--stale", "Show only stale secrets (75%+ decay)").option("-f, --filter <pattern>", "Glob pattern on key name").option("--json", "Output as JSON").action((cmd) => {
     const opts = buildOpts(cmd);
     let entries = listSecrets(opts);
     if (cmd.tag) {
@@ -389,6 +445,22 @@ function registerSecretsCommands(program2) {
     if (cmd.filter) {
       entries = filterSecretsByKeyGlob(entries, cmd.filter);
     }
+    if (emitJson(
+      program2,
+      cmd,
+      entries.map((e) => ({
+        key: safeStr(e.key),
+        scope: safeStr(e.scope),
+        type: e.envelope?.states ? "superposition" : "collapsed",
+        environments: e.envelope?.states ? Object.keys(e.envelope.states).map(safeStr) : void 0,
+        tags: safeArr(e.envelope?.meta.tags),
+        accessCount: safeNum(e.envelope?.meta.accessCount),
+        entangledCount: safeNum(e.envelope?.meta.entangled?.length),
+        decay: e.decay ?? null
+      }))
+    )) {
+      return;
+    }
     if (entries.length === 0) {
       console.log(c.dim("No secrets found"));
       return;
@@ -434,7 +506,7 @@ function registerSecretsCommands(program2) {
     }
     console.log();
   });
-  program2.command("inspect <key>").description("Show full quantum state of a secret").option("-g, --global", "Inspect global scope only").option("-p, --project", "Inspect project scope only").option("--project-path <path>", "Explicit project path").action((key, cmd) => {
+  program2.command("inspect <key>").description("Show full quantum state of a secret").option("-g, --global", "Inspect global scope only").option("-p, --project", "Inspect project scope only").option("--project-path <path>", "Explicit project path").option("--json", "Output as JSON").action((key, cmd) => {
     const opts = buildOpts(cmd);
     const result = getEnvelope(key, opts);
     if (!result) {
@@ -443,6 +515,26 @@ function registerSecretsCommands(program2) {
     }
     const { envelope, scope } = result;
     const decay = checkDecay(envelope);
+    if (emitJson(program2, cmd, {
+      key: safeStr(key),
+      scope: safeStr(scope),
+      type: envelope.states ? "superposition" : "collapsed",
+      environments: envelope.states ? Object.keys(envelope.states).map(safeStr) : void 0,
+      defaultEnv: envelope.defaultEnv ? safeStr(envelope.defaultEnv) : void 0,
+      createdAt: safeStr(envelope.meta.createdAt),
+      updatedAt: safeStr(envelope.meta.updatedAt),
+      accessCount: safeNum(envelope.meta.accessCount),
+      lastAccessedAt: envelope.meta.lastAccessedAt ? safeStr(envelope.meta.lastAccessedAt) : void 0,
+      description: envelope.meta.description ? safeStr(envelope.meta.description) : void 0,
+      tags: safeArr(envelope.meta.tags),
+      entangled: (envelope.meta.entangled ?? []).map((l) => ({
+        service: safeStr(l.service),
+        key: safeStr(l.key)
+      })),
+      decay
+    })) {
+      return;
+    }
     const safeScope = safeStr(scope);
     const createdAt = safeStr(envelope.meta.createdAt);
     const updatedAt = safeStr(envelope.meta.updatedAt);
@@ -511,7 +603,7 @@ function registerSecretsCommands(program2) {
     });
     process.stdout.write(output + "\n");
   });
-  program2.command("import <file>").description("Import secrets from a .env file").option("-g, --global", "Import to global scope").option("-p, --project", "Import to project scope").option("--project-path <path>", "Explicit project path").option("-e, --env <env>", "Environment context").option("--skip-existing", "Skip keys that already exist").option("--dry-run", "Preview what would be imported without saving").action((file, cmd) => {
+  program2.command("import <file>").description("Import secrets from a .env file").option("-g, --global", "Import to global scope").option("-p, --project", "Import to project scope").option("--project-path <path>", "Explicit project path").option("-e, --env <env>", "Environment context").option("--skip-existing", "Skip keys that already exist").option("--dry-run", "Preview what would be imported without saving").option("--json", "Output as JSON").action((file, cmd) => {
     const opts = buildOpts(cmd);
     const result = importDotenv(file, {
       scope: opts.scope,
@@ -520,6 +612,9 @@ function registerSecretsCommands(program2) {
       skipExisting: cmd.skipExisting,
       dryRun: cmd.dryRun
     });
+    if (emitJson(program2, cmd, { file, dryRun: !!cmd.dryRun, ...result })) {
+      return;
+    }
     if (cmd.dryRun) {
       console.log(
         `
@@ -989,7 +1084,7 @@ ${c.bold("  Recent Activity:")} (last ${context.recentActions.length})`
     }
     console.log();
   });
-  program2.command("check").description("Validate project secrets against .q-ring.json manifest").option("--project-path <path>", "Project path (defaults to cwd)").action((cmd) => {
+  program2.command("check").description("Validate project secrets against .q-ring.json manifest").option("--project-path <path>", "Project path (defaults to cwd)").option("--json", "Output as JSON").action((cmd) => {
     const projectPath = cmd.projectPath ?? process.cwd();
     const config = readProjectConfig(projectPath);
     if (!config?.secrets || Object.keys(config.secrets).length === 0) {
@@ -1003,49 +1098,58 @@ ${c.bold("  Recent Activity:")} (last ${context.recentActions.length})`
       );
       process.exit(1);
     }
-    console.log(
-      c.bold(`
-  ${SYMBOLS.shield} Project secret manifest check
-`)
-    );
-    let present = 0;
-    let missing = 0;
-    let expiredCount = 0;
-    let staleCount = 0;
+    const statuses = [];
     for (const [key, manifest] of Object.entries(config.secrets)) {
       const result = getEnvelope(key, { projectPath, source: "cli" });
       if (!result) {
-        if (manifest.required !== false) {
-          missing++;
-          console.log(
-            `  ${c.red(SYMBOLS.cross)} ${c.bold(key)} ${c.red("MISSING")} ${manifest.description ? c.dim(`\u2014 ${manifest.description}`) : ""}`
-          );
-        } else {
-          console.log(
-            `  ${c.dim(SYMBOLS.cross)} ${c.bold(key)} ${c.dim("optional, not set")} ${manifest.description ? c.dim(`\u2014 ${manifest.description}`) : ""}`
-          );
-        }
+        statuses.push({
+          key,
+          status: manifest.required !== false ? "missing" : "optional-not-set",
+          description: manifest.description
+        });
         continue;
       }
       const decay = checkDecay(result.envelope);
-      if (decay.isExpired) {
-        expiredCount++;
-        console.log(
-          `  ${c.red(SYMBOLS.warning)} ${c.bold(key)} ${c.bgRed(c.white(" EXPIRED "))} ${manifest.description ? c.dim(`\u2014 ${manifest.description}`) : ""}`
-        );
-      } else if (decay.isStale) {
-        staleCount++;
-        console.log(
-          `  ${c.yellow(SYMBOLS.warning)} ${c.bold(key)} ${c.yellow(`stale (${decay.lifetimePercent}%)`)} ${manifest.description ? c.dim(`\u2014 ${manifest.description}`) : ""}`
-        );
+      statuses.push({
+        key,
+        status: decay.isExpired ? "expired" : decay.isStale ? "stale" : "ok",
+        description: manifest.description,
+        ...decay.isStale && !decay.isExpired ? { lifetimePercent: decay.lifetimePercent } : {}
+      });
+    }
+    const present = statuses.filter((s) => s.status === "ok").length;
+    const missing = statuses.filter((s) => s.status === "missing").length;
+    const expiredCount = statuses.filter((s) => s.status === "expired").length;
+    const staleCount = statuses.filter((s) => s.status === "stale").length;
+    const total = Object.keys(config.secrets).length;
+    if (emitJson(program2, cmd, {
+      projectPath,
+      secrets: statuses,
+      summary: { total, present, missing, expired: expiredCount, stale: staleCount },
+      ready: missing === 0
+    })) {
+      if (missing > 0) process.exitCode = 1;
+      return;
+    }
+    console.log(
+      c.bold(`
+  ${SYMBOLS.shield} Project secret manifest check
+`)
+    );
+    for (const s of statuses) {
+      const desc = s.description ? c.dim(`\u2014 ${s.description}`) : "";
+      if (s.status === "missing") {
+        console.log(`  ${c.red(SYMBOLS.cross)} ${c.bold(s.key)} ${c.red("MISSING")} ${desc}`);
+      } else if (s.status === "optional-not-set") {
+        console.log(`  ${c.dim(SYMBOLS.cross)} ${c.bold(s.key)} ${c.dim("optional, not set")} ${desc}`);
+      } else if (s.status === "expired") {
+        console.log(`  ${c.red(SYMBOLS.warning)} ${c.bold(s.key)} ${c.bgRed(c.white(" EXPIRED "))} ${desc}`);
+      } else if (s.status === "stale") {
+        console.log(`  ${c.yellow(SYMBOLS.warning)} ${c.bold(s.key)} ${c.yellow(`stale (${s.lifetimePercent}%)`)} ${desc}`);
       } else {
-        present++;
-        console.log(
-          `  ${c.green(SYMBOLS.check)} ${c.bold(key)} ${c.green("OK")} ${manifest.description ? c.dim(`\u2014 ${manifest.description}`) : ""}`
-        );
+        console.log(`  ${c.green(SYMBOLS.check)} ${c.bold(s.key)} ${c.green("OK")} ${desc}`);
       }
     }
-    const total = Object.keys(config.secrets).length;
     console.log(
       `
   ${c.bold(`${total} declared`)}  ${c.green(`${present} present`)}  ${c.yellow(`${staleCount} stale`)}  ${c.red(`${expiredCount} expired`)}  ${c.red(`${missing} missing`)}`
@@ -1069,10 +1173,11 @@ ${c.bold("  Recent Activity:")} (last ${context.recentActions.length})`
     console.log();
     if (missing > 0) process.exit(1);
   });
-  program2.command("env").description("Show detected environment (wavefunction collapse context)").option("--project-path <path>", "Project path for detection").action((cmd) => {
+  program2.command("env").description("Show detected environment (wavefunction collapse context)").option("--project-path <path>", "Project path for detection").option("--json", "Output as JSON").action((cmd) => {
     const result = collapseEnvironment({
       projectPath: cmd.projectPath ?? process.cwd()
     });
+    if (emitJson(program2, cmd, { environment: result })) return;
     if (result) {
       console.log(
         `${SYMBOLS.zap} ${c.bold("Collapsed environment:")} ${envBadge(result.env)} ${c.dim(`(source: ${result.source})`)}`
@@ -1087,9 +1192,14 @@ ${c.bold("  Recent Activity:")} (last ${context.recentActions.length})`
   });
   program2.command("env:generate").description(
     "Generate a .env file from the project manifest (.q-ring.json)"
-  ).option("--project-path <path>", "Project path (defaults to cwd)").option("-o, --output <file>", "Output file path (defaults to stdout)").option("-e, --env <env>", "Force environment for superposition collapse").action((cmd) => {
+  ).option("--project-path <path>", "Project path (defaults to cwd)").option("-o, --output <file>", "Output file path (defaults to stdout)").option("-e, --env <env>", "Force environment for superposition collapse").option("-y, --yes", "Overwrite an existing output file without asking").action(async (cmd) => {
     const projectPath = cmd.projectPath ?? process.cwd();
     const config = readProjectConfig(projectPath);
+    if (cmd.output && existsSync(cmd.output) && !await confirm(`Overwrite existing ${cmd.output}?`, { assumeYes: cmd.yes })) {
+      console.error(c.dim("Aborted."));
+      process.exitCode = 1;
+      return;
+    }
     if (!config?.secrets || Object.keys(config.secrets).length === 0) {
       console.error(
         c.red(`${SYMBOLS.cross} No secrets manifest found in .q-ring.json`)
@@ -1150,7 +1260,7 @@ ${c.bold("  Recent Activity:")} (last ${context.recentActions.length})`
   ).option("--tags <tags>", "Comma-separated tags for all secrets").option(
     "--hook-exec <cmd>",
     "Shell command to run when any of these secrets change"
-  ).option("-g, --global", "Global scope").option("-p, --project", "Project scope").option("--project-path <path>", "Explicit project path").action(async (name, cmd) => {
+  ).option("-g, --global", "Global scope").option("-p, --project", "Project scope").option("--project-path <path>", "Explicit project path").option("-y, --yes", "Skip confirmation when overwriting existing secrets").action(async (name, cmd) => {
     const opts = buildOpts(cmd);
     const prefix = name.toUpperCase().replace(/[^A-Z0-9]/g, "_");
     const tags = cmd.tags?.split(",").map((t) => t.trim()) ?? [
@@ -1163,6 +1273,15 @@ ${c.bold("  Recent Activity:")} (last ${context.recentActions.length})`
     } else {
       keyNames = [`${prefix}_API_KEY`, `${prefix}_API_SECRET`];
     }
+    const existing = keyNames.filter((k) => hasSecret(k, opts));
+    if (existing.length > 0 && !await confirm(
+      `${existing.length} secret(s) already exist and will be overwritten with generated values: ${existing.join(", ")}. Continue?`,
+      { assumeYes: cmd.yes }
+    )) {
+      console.error(c.dim("Aborted."));
+      process.exitCode = 1;
+      return;
+    }
     console.log(`
 ${SYMBOLS.zap} ${c.bold(`Setting up service: ${name}`)}
 `);
@@ -1440,8 +1559,9 @@ ${c.dim(`format: ${cmd.format} | entropy: ~${entropy} bits`)}`
       process.exit(1);
     }
   });
-  tunnel.command("list").alias("ls").description("List active tunnels").action(() => {
+  tunnel.command("list").alias("ls").description("List active tunnels").option("--json", "Output as JSON").action((cmd) => {
     const tunnels = tunnelList();
+    if (emitJson(program2, cmd, { tunnels })) return;
     if (tunnels.length === 0) {
       console.log(c.dim("No active tunnels"));
       return;
@@ -1502,7 +1622,7 @@ ${SYMBOLS.package} ${c.green("packed")} ${secrets.length} secret(s)`
       );
     }
   });
-  tp.command("unpack [bundle]").description("Unpack and import secrets from an encrypted bundle").option("-g, --global", "Import to global scope").option("-p, --project", "Import to project scope").option("--project-path <path>", "Explicit project path").option("--dry-run", "Show what would be imported without saving").action(async (bundle, cmd) => {
+  tp.command("unpack [bundle]").description("Unpack and import secrets from an encrypted bundle").option("-g, --global", "Import to global scope").option("-p, --project", "Import to project scope").option("--project-path <path>", "Explicit project path").option("--dry-run", "Show what would be imported without saving").option("-y, --yes", "Overwrite existing secrets without asking").action(async (bundle, cmd) => {
     if (!bundle) {
       const chunks = [];
       for await (const chunk of process.stdin) {
@@ -1513,28 +1633,9 @@ ${SYMBOLS.package} ${c.green("packed")} ${secrets.length} secret(s)`
     const passphrase = await promptSecret(
       `${SYMBOLS.lock} Enter passphrase for decryption: `
     );
+    let payload;
     try {
-      const payload = teleportUnpack(bundle, passphrase);
-      if (cmd.dryRun) {
-        console.log(
-          `
-${SYMBOLS.package} ${c.bold("Would import")} (${payload.secrets.length} secrets):
-`
-        );
-        for (const s of payload.secrets) {
-          console.log(
-            `  ${SYMBOLS.key} ${c.bold(s.key)} ${c.dim(`[${s.scope ?? "global"}]`)}`
-          );
-        }
-        return;
-      }
-      const opts = buildOpts(cmd);
-      for (const s of payload.secrets) {
-        setSecret(s.key, s.value, opts);
-      }
-      console.log(
-        `${SYMBOLS.check} ${c.green("imported")} ${payload.secrets.length} secret(s) from teleport bundle`
-      );
+      payload = teleportUnpack(bundle, passphrase);
     } catch {
       console.error(
         c.red(
@@ -1543,6 +1644,35 @@ ${SYMBOLS.package} ${c.bold("Would import")} (${payload.secrets.length} secrets)
       );
       process.exit(1);
     }
+    if (cmd.dryRun) {
+      console.log(
+        `
+${SYMBOLS.package} ${c.bold("Would import")} (${payload.secrets.length} secrets):
+`
+      );
+      for (const s of payload.secrets) {
+        console.log(
+          `  ${SYMBOLS.key} ${c.bold(s.key)} ${c.dim(`[${s.scope ?? "global"}]`)}`
+        );
+      }
+      return;
+    }
+    const opts = buildOpts(cmd);
+    const existing = payload.secrets.map((s) => s.key).filter((k) => hasSecret(k, opts));
+    if (existing.length > 0 && !await confirm(
+      `${existing.length} existing secret(s) will be overwritten: ${existing.join(", ")}. Continue?`,
+      { assumeYes: cmd.yes }
+    )) {
+      console.error(c.dim("Aborted."));
+      process.exitCode = 1;
+      return;
+    }
+    for (const s of payload.secrets) {
+      setSecret(s.key, s.value, opts);
+    }
+    console.log(
+      `${SYMBOLS.check} ${c.green("imported")} ${payload.secrets.length} secret(s) from teleport bundle`
+    );
   });
 }
 
@@ -1557,8 +1687,11 @@ function registerValidationCommands(program2) {
   ).option(
     "--manifest",
     "Only validate manifest-declared secrets (with --all)"
-  ).option("--list-providers", "List all available providers").action(async (key, cmd) => {
+  ).option("--list-providers", "List all available providers").option("--json", "Output as JSON").action(async (key, cmd) => {
     if (cmd.listProviders) {
+      if (emitJson(program2, cmd, { providers: registry2.listProviders() })) {
+        return;
+      }
       console.log(
         c.bold(`
   ${SYMBOLS.shield} Available validation providers
@@ -1588,11 +1721,15 @@ function registerValidationCommands(program2) {
           entries = entries.filter((e) => manifestKeys.has(e.key));
         }
       }
-      console.log(c.bold(`
+      const jsonMode = wantsJsonOutput(program2, cmd);
+      if (!jsonMode) {
+        console.log(c.bold(`
   ${SYMBOLS.shield} Validating secrets
 `));
+      }
       let validated = 0;
       let skipped = 0;
+      const jsonResults = [];
       for (const entry of entries) {
         const value2 = getSecret(entry.key, { ...opts, scope: entry.scope });
         if (!value2) {
@@ -1606,12 +1743,26 @@ function registerValidationCommands(program2) {
           continue;
         }
         validated++;
+        if (jsonMode) {
+          jsonResults.push({
+            key: entry.key,
+            status: result2.status,
+            provider: result2.provider,
+            latencyMs: result2.latencyMs,
+            message: result2.status !== "valid" ? result2.message : void 0
+          });
+          continue;
+        }
         const icon2 = result2.status === "valid" ? c.green(SYMBOLS.check) : result2.status === "invalid" ? c.red(SYMBOLS.cross) : c.yellow(SYMBOLS.warning);
         const statusText = result2.status === "valid" ? c.green("valid") : result2.status === "invalid" ? c.red("invalid") : c.yellow("error");
         console.log(
           `  ${icon2} ${c.bold(entry.key.padEnd(24))} ${statusText}  ${c.dim(`(${result2.provider}, ${result2.latencyMs}ms)`)}${result2.status !== "valid" ? ` ${c.dim("\u2014 " + result2.message)}` : ""}`
         );
       }
+      if (jsonMode) {
+        emitJson(program2, cmd, { results: jsonResults, validated, skipped });
+        return;
+      }
       console.log(
         `
   ${c.dim(`${validated} validated, ${skipped} skipped (no provider)`)}
@@ -1627,6 +1778,15 @@ function registerValidationCommands(program2) {
     const envelope = getEnvelope(key, opts);
     const provHint = envelope?.envelope.meta.provider ?? cmd.provider;
     const result = await validateSecret(value, { provider: provHint });
+    if (emitJson(program2, cmd, {
+      key,
+      status: result.status,
+      provider: result.provider,
+      latencyMs: result.latencyMs,
+      message: result.message
+    })) {
+      return;
+    }
     const icon = result.status === "valid" ? c.green(SYMBOLS.check) : result.status === "invalid" ? c.red(SYMBOLS.cross) : result.status === "error" ? c.yellow(SYMBOLS.warning) : c.dim("\u25CB");
     console.log(
       `
@@ -1639,7 +1799,7 @@ function registerValidationCommands(program2) {
   });
   program2.command("rotate <key>").description(
     "Attempt issuer-native rotation of a secret via its provider"
-  ).option("-g, --global", "Global scope").option("-p, --project", "Project scope").option("--project-path <path>", "Explicit project path").option("--provider <name>", "Force a specific provider").action(async (key, cmd) => {
+  ).option("-g, --global", "Global scope").option("-p, --project", "Project scope").option("--project-path <path>", "Explicit project path").option("--provider <name>", "Force a specific provider").option("--json", "Output as JSON").action(async (key, cmd) => {
     const opts = buildOpts(cmd);
     const value = getSecret(key, opts);
     if (!value) {
@@ -1653,6 +1813,16 @@ function registerValidationCommands(program2) {
         ...opts,
         scope: opts.scope ?? "global"
       });
+    }
+    if (emitJson(program2, cmd, {
+      key,
+      rotated: !!(result.rotated && result.newValue),
+      provider: result.provider,
+      message: result.message
+    })) {
+      return;
+    }
+    if (result.rotated && result.newValue) {
       console.log(
         `${SYMBOLS.check} ${c.green("Rotated")} ${c.bold(key)} via ${result.provider}`
       );
@@ -2173,15 +2343,23 @@ function registerToolingCommands(program2) {
   program2.command("scan [dir]").description("Scan a codebase for hardcoded secrets").option(
     "--fix",
     "Auto-replace hardcoded secrets with process.env references and store in q-ring"
-  ).option("-g, --global", "Store fixed secrets in global scope").option("-p, --project", "Store fixed secrets in project scope").option("--project-path <path>", "Explicit project path").action((dir, cmd) => {
+  ).option("-g, --global", "Store fixed secrets in global scope").option("-p, --project", "Store fixed secrets in project scope").option("--project-path <path>", "Explicit project path").option("--json", "Output as JSON").action((dir, cmd) => {
     const targetDir = dir ?? process.cwd();
     const fixMode = cmd.fix === true;
-    console.log(
-      `
+    const jsonMode = wantsJsonOutput(program2, cmd);
+    if (!jsonMode) {
+      console.log(
+        `
   ${SYMBOLS.eye} Scanning ${c.bold(targetDir)} for secrets...${fixMode ? c.yellow(" [--fix mode]") : ""}
 `
-    );
+      );
+    }
     const results = scanCodebase(targetDir);
+    if (jsonMode && !fixMode) {
+      emitJson(program2, cmd, { dir: targetDir, findings: results });
+      if (results.length > 0) process.exitCode = 1;
+      return;
+    }
     if (results.length === 0) {
       console.log(
         `  ${c.green(SYMBOLS.check)} No hardcoded secrets found. Awesome!
@@ -2202,6 +2380,14 @@ function registerToolingCommands(program2) {
         projectPath: opts.projectPath
       });
       const fixedCount = lintResults.filter((r) => r.fixed).length;
+      if (jsonMode) {
+        emitJson(program2, cmd, {
+          dir: targetDir,
+          findings: results,
+          fixed: fixedCount
+        });
+        return;
+      }
       console.log(
         `  ${c.green(SYMBOLS.check)} Fixed ${fixedCount} secrets \u2014 replaced with process.env references and stored in q-ring.
 `
@@ -2227,13 +2413,17 @@ function registerToolingCommands(program2) {
   ).option(
     "--fix",
     "Replace hardcoded secrets with process.env references and store in q-ring"
-  ).option("-g, --global", "Store fixed secrets in global scope").option("-p, --project", "Store fixed secrets in project scope").option("--project-path <path>", "Explicit project path").action((files, cmd) => {
+  ).option("-g, --global", "Store fixed secrets in global scope").option("-p, --project", "Store fixed secrets in project scope").option("--project-path <path>", "Explicit project path").option("--json", "Output as JSON").action((files, cmd) => {
     const opts = buildOpts(cmd);
     const results = lintFiles(files, {
       fix: cmd.fix,
       scope: opts.scope,
       projectPath: opts.projectPath
     });
+    if (emitJson(program2, cmd, { files, findings: results })) {
+      if (results.some((r) => !r.fixed)) process.exitCode = 1;
+      return;
+    }
     if (results.length === 0) {
       console.log(
         `
@@ -2267,7 +2457,7 @@ function registerToolingCommands(program2) {
     }
   });
   program2.command("status").description("Launch the quantum status dashboard in your browser").option("--port <port>", "Port to serve on", "9876").option("--no-open", "Don't auto-open the browser").action(async (cmd) => {
-    const { startDashboardServer } = await import("./dashboard-6XKC5BL4.js");
+    const { startDashboardServer } = await import("./dashboard-2IGUR7PA.js");
     const { exec } = await import("child_process");
     const { platform } = await import("os");
     const port = Number(cmd.port);
@@ -2303,9 +2493,10 @@ function registerAuditCommands(program2) {
   program2.command("audit").description("View the audit log (observer effect)").option("-k, --key <key>", "Filter by key").option(
     "-a, --action <action>",
     "Filter by action (read, write, delete, etc.)"
-  ).option("-n, --limit <n>", "Number of events to show", parseInt, 20).option("--anomalies", "Detect access anomalies").action((cmd) => {
+  ).option("-n, --limit <n>", "Number of events to show", parseInt, 20).option("--anomalies", "Detect access anomalies").option("--json", "Output as JSON").action((cmd) => {
     if (cmd.anomalies) {
       const anomalies = detectAnomalies(cmd.key);
+      if (emitJson(program2, cmd, { anomalies })) return;
       if (anomalies.length === 0) {
         console.log(`${SYMBOLS.shield} ${c.green("No anomalies detected")}`);
         return;
@@ -2326,6 +2517,7 @@ ${SYMBOLS.warning} ${c.bold(c.yellow(`${anomalies.length} anomaly/anomalies dete
       action: cmd.action,
       limit: cmd.limit
     });
+    if (emitJson(program2, cmd, { events })) return;
     if (events.length === 0) {
       console.log(c.dim("No audit events found"));
       return;
@@ -2349,8 +2541,12 @@ ${SYMBOLS.warning} ${c.bold(c.yellow(`${anomalies.length} anomaly/anomalies dete
     }
     console.log();
   });
-  program2.command("audit:verify").description("Verify the integrity of the audit hash chain").action(() => {
+  program2.command("audit:verify").description("Verify the integrity of the audit hash chain").option("--json", "Output as JSON").action((cmd) => {
     const result = verifyAuditChain();
+    if (emitJson(program2, cmd, result)) {
+      if (!result.intact && result.totalEvents > 0) process.exitCode = 1;
+      return;
+    }
     if (result.totalEvents === 0) {
       console.log(c.dim("  No audit events to verify"));
       return;
@@ -2391,42 +2587,58 @@ ${SYMBOLS.warning} ${c.bold(c.yellow(`${anomalies.length} anomaly/anomalies dete
       console.log(output);
     }
   });
-  program2.command("health").description("Check the health of all secrets").option("-g, --global", "Check global scope only").option("-p, --project", "Check project scope only").option("--project-path <path>", "Explicit project path").action((cmd) => {
+  program2.command("health").description("Check the health of all secrets").option("-g, --global", "Check global scope only").option("-p, --project", "Check project scope only").option("--project-path <path>", "Explicit project path").option("--json", "Output as JSON").action((cmd) => {
     const opts = buildOpts(cmd);
     const entries = listSecrets(opts);
-    if (entries.length === 0) {
-      console.log(c.dim("No secrets to check"));
-      return;
-    }
-    console.log(c.bold(`
-  ${SYMBOLS.shield} Secret health report
-`));
+    const expiredKeys = [];
+    const staleKeys = [];
     let healthy = 0;
-    let stale = 0;
-    let expired = 0;
     let noDecay = 0;
     for (const entry of entries) {
       if (!entry.decay || !entry.decay.timeRemaining) {
         noDecay++;
-        continue;
-      }
-      if (entry.decay.isExpired) {
-        expired++;
-        console.log(
-          `  ${c.red(SYMBOLS.cross)} ${c.bold(entry.key)} ${c.bgRed(c.white(" EXPIRED "))}`
-        );
+      } else if (entry.decay.isExpired) {
+        expiredKeys.push(entry.key);
       } else if (entry.decay.isStale) {
-        stale++;
-        console.log(
-          `  ${c.yellow(SYMBOLS.warning)} ${c.bold(entry.key)} ${c.yellow(`stale (${entry.decay.lifetimePercent}%, ${entry.decay.timeRemaining} left)`)}`
-        );
+        staleKeys.push({
+          key: entry.key,
+          lifetimePercent: entry.decay.lifetimePercent,
+          timeRemaining: entry.decay.timeRemaining
+        });
       } else {
         healthy++;
       }
     }
+    if (emitJson(program2, cmd, {
+      total: entries.length,
+      healthy,
+      noDecay,
+      expired: expiredKeys,
+      stale: staleKeys,
+      anomalies: entries.length === 0 ? [] : detectAnomalies()
+    })) {
+      return;
+    }
+    if (entries.length === 0) {
+      console.log(c.dim("No secrets to check"));
+      return;
+    }
+    console.log(c.bold(`
+  ${SYMBOLS.shield} Secret health report
+`));
+    for (const key of expiredKeys) {
+      console.log(
+        `  ${c.red(SYMBOLS.cross)} ${c.bold(key)} ${c.bgRed(c.white(" EXPIRED "))}`
+      );
+    }
+    for (const s of staleKeys) {
+      console.log(
+        `  ${c.yellow(SYMBOLS.warning)} ${c.bold(s.key)} ${c.yellow(`stale (${s.lifetimePercent}%, ${s.timeRemaining} left)`)}`
+      );
+    }
     console.log(
       `
-  ${c.green(`${SYMBOLS.check} ${healthy} healthy`)}  ${c.yellow(`${SYMBOLS.warning} ${stale} stale`)}  ${c.red(`${SYMBOLS.cross} ${expired} expired`)}  ${c.dim(`${noDecay} no decay`)}`
+  ${c.green(`${SYMBOLS.check} ${healthy} healthy`)}  ${c.yellow(`${SYMBOLS.warning} ${staleKeys.length} stale`)}  ${c.red(`${SYMBOLS.cross} ${expiredKeys.length} expired`)}  ${c.dim(`${noDecay} no decay`)}`
     );
     const anomalies = detectAnomalies();
     if (anomalies.length > 0) {
@@ -2590,8 +2802,9 @@ function registerHookCommands(program2) {
     if (cmd.keyPattern) console.log(c.dim(`  pattern: ${cmd.keyPattern}`));
     if (cmd.tag) console.log(c.dim(`  tag: ${cmd.tag}`));
   });
-  hook.command("list").alias("ls").description("List all registered hooks").action(() => {
+  hook.command("list").alias("ls").description("List all registered hooks").option("--json", "Output as JSON").action((cmd) => {
     const hooks = listHooks();
+    if (emitJson(program2, cmd, { hooks })) return;
     if (hooks.length === 0) {
       console.log(c.dim("No hooks registered"));
       return;
@@ -2815,9 +3028,16 @@ function registerAgentCommands(program2) {
     remember(key, value);
     console.log(`${SYMBOLS.check} ${c.green("remembered")} ${c.bold(key)}`);
   });
-  program2.command("recall [key]").description("Retrieve a value from agent memory, or list all keys").action((key) => {
+  program2.command("recall [key]").description("Retrieve a value from agent memory, or list all keys").option("--json", "Output as JSON (list mode only)").action((key, cmd) => {
     if (!key) {
       const entries = listMemory();
+      if (emitJson(
+        program2,
+        cmd,
+        entries.map((e) => ({ key: e.key, updatedAt: e.updatedAt }))
+      )) {
+        return;
+      }
       if (entries.length === 0) {
         console.log(c.dim("Agent memory is empty."));
         return;
@@ -2842,8 +3062,17 @@ ${SYMBOLS.zap} ${c.bold("Agent Memory")} (${entries.length} entries)
       console.log(safeStr(value));
     }
   });
-  program2.command("forget <key>").description("Delete a key from agent memory").option("--all", "Clear all agent memory").action((key, cmd) => {
+  program2.command("forget <key>").description("Delete a key from agent memory").option("--all", "Clear all agent memory").option("-y, --yes", "Skip the confirmation prompt").action(async (key, cmd) => {
     if (cmd.all) {
+      const count = listMemory().length;
+      if (!await confirm(
+        `Clear ALL agent memory (${count} entr${count === 1 ? "y" : "ies"})? This cannot be undone.`,
+        { assumeYes: cmd.yes }
+      )) {
+        console.error(c.dim("Aborted."));
+        process.exitCode = 1;
+        return;
+      }
       clearMemory();
       console.log(`${SYMBOLS.check} ${c.yellow("cleared")} all agent memory`);
       return;
@@ -2857,13 +3086,10 @@ ${SYMBOLS.zap} ${c.bold("Agent Memory")} (${entries.length} entries)
   });
   program2.command("analyze").description(
     "Analyze secret usage patterns and provide optimization suggestions"
-  ).option("-g, --global", "Global scope only").option("-p, --project", "Project scope only").option("--project-path <path>", "Explicit project path").action((cmd) => {
+  ).option("-g, --global", "Global scope only").option("-p, --project", "Project scope only").option("--project-path <path>", "Explicit project path").option("--json", "Output as JSON").action((cmd) => {
     const opts = buildOpts(cmd);
     const entries = listSecrets({ ...opts, silent: true });
     const audit = queryAudit({ limit: 1e3 });
-    console.log(`
-${SYMBOLS.zap} ${c.bold("Secret Usage Analysis")}
-`);
     const accessMap = /* @__PURE__ */ new Map();
     for (const e of audit) {
       if (e.action === "read" && e.key) {
@@ -2871,6 +3097,39 @@ ${SYMBOLS.zap} ${c.bold("Secret Usage Analysis")}
       }
     }
     const sorted = [...accessMap.entries()].sort((a, b) => b[1] - a[1]);
+    const neverAccessed = entries.filter((e) => {
+      const count = e.envelope?.meta.accessCount ?? 0;
+      return count === 0;
+    });
+    const jsonExpired = entries.filter((e) => e.decay?.isExpired);
+    const jsonStale = entries.filter(
+      (e) => e.decay?.isStale && !e.decay?.isExpired
+    );
+    const jsonNoRotation = entries.filter(
+      (e) => !e.envelope?.meta.rotationFormat && !e.decay?.isExpired
+    );
+    if (emitJson(program2, cmd, {
+      mostAccessed: sorted.slice(0, 5).map(([key, reads]) => ({ key, reads })),
+      neverAccessed: neverAccessed.map((e) => e.key),
+      expired: jsonExpired.map((e) => e.key),
+      stale: jsonStale.map((e) => ({
+        key: e.key,
+        timeRemaining: e.decay?.timeRemaining ?? null
+      })),
+      summary: {
+        total: entries.length,
+        active: entries.length - jsonExpired.length,
+        expired: jsonExpired.length,
+        stale: jsonStale.length,
+        neverAccessed: neverAccessed.length,
+        withRotationConfig: entries.length - jsonNoRotation.length
+      }
+    })) {
+      return;
+    }
+    console.log(`
+${SYMBOLS.zap} ${c.bold("Secret Usage Analysis")}
+`);
     if (sorted.length > 0) {
       console.log(`  ${c.bold("Most accessed:")}`);
       for (const [key, count] of sorted.slice(0, 5)) {
@@ -2878,10 +3137,6 @@ ${SYMBOLS.zap} ${c.bold("Secret Usage Analysis")}
       }
       console.log();
     }
-    const neverAccessed = entries.filter((e) => {
-      const count = e.envelope?.meta.accessCount ?? 0;
-      return count === 0;
-    });
     if (neverAccessed.length > 0) {
       console.log(
         `  ${c.bold("Never accessed:")} ${c.yellow(neverAccessed.length.toString())} secrets`
@@ -3033,8 +3288,9 @@ function registerSecurityCommands(program2) {
       )
     );
   });
-  program2.command("approvals").description("List all approval tokens with verification status").action(() => {
+  program2.command("approvals").description("List all approval tokens with verification status").option("--json", "Output as JSON").action((cmd) => {
     const approvals = listApprovals();
+    if (emitJson(program2, cmd, { approvals })) return;
     if (approvals.length === 0) {
       console.log(c.dim("  No approvals found"));
       return;
@@ -3115,6 +3371,290 @@ ${SYMBOLS.lock} Approval Tokens
   });
 }
 
+// src/cli/commands/doctor.ts
+import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5, rmSync } from "fs";
+import { join as join3, delimiter } from "path";
+import { homedir } from "os";
+function auditDir() {
+  return process.env.QRING_AUDIT_DIR ?? join3(homedir(), ".config", "q-ring");
+}
+function checkNode() {
+  const major = Number(process.versions.node.split(".")[0]);
+  return {
+    name: "node runtime",
+    status: major >= 18 ? "ok" : "fail",
+    detail: `v${process.versions.node}${major >= 18 ? "" : " \u2014 q-ring requires Node >= 18"}`
+  };
+}
+async function checkKeyringBackend() {
+  try {
+    const { Entry } = await import("@napi-rs/keyring");
+    const probe = new Entry("q-ring-doctor-probe", "PROBE");
+    probe.setPassword("ok");
+    const read = probe.getPassword();
+    probe.deletePassword();
+    if (read !== "ok") {
+      return {
+        name: "keyring backend",
+        status: "fail",
+        detail: "probe round-trip returned unexpected value"
+      };
+    }
+    return {
+      name: "keyring backend",
+      status: "ok",
+      detail: "write/read/delete round-trip succeeded"
+    };
+  } catch (err) {
+    return {
+      name: "keyring backend",
+      status: "fail",
+      detail: `${err instanceof Error ? err.message : String(err)} \u2014 on headless Linux, install and unlock a Secret Service (e.g. gnome-keyring)`
+    };
+  }
+}
+function checkAuditLog() {
+  const dir = auditDir();
+  try {
+    const probeFile = join3(dir, ".doctor-probe");
+    writeFileSync5(probeFile, "ok");
+    rmSync(probeFile);
+  } catch (err) {
+    return {
+      name: "audit log",
+      status: "fail",
+      detail: `${dir} not writable: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const chain = verifyAuditChain();
+  if (chain.totalEvents === 0) {
+    return { name: "audit log", status: "ok", detail: `${dir} writable, no events yet` };
+  }
+  if (!chain.intact) {
+    return {
+      name: "audit log",
+      status: "fail",
+      detail: `hash chain BROKEN at event #${chain.brokenAt} (${chain.validEvents}/${chain.totalEvents} valid) \u2014 see qring audit:verify`
+    };
+  }
+  return {
+    name: "audit log",
+    status: "ok",
+    detail: `${dir} writable, chain intact (${chain.totalEvents} events)`
+  };
+}
+function checkManifest(projectPath) {
+  const manifestPath = join3(projectPath, ".q-ring.json");
+  if (!existsSync4(manifestPath)) {
+    return {
+      name: "project manifest",
+      status: "warn",
+      detail: `no .q-ring.json in ${projectPath} (optional \u2014 run qring wizard or /qring-setup-project)`
+    };
+  }
+  try {
+    const config = JSON.parse(readFileSync6(manifestPath, "utf8"));
+    const declared = Object.keys(config.secrets ?? {}).length;
+    const hasPolicy = !!config.policy;
+    return {
+      name: "project manifest",
+      status: "ok",
+      detail: `${declared} secret(s) declared${hasPolicy ? ", policy present" : ""}`
+    };
+  } catch (err) {
+    return {
+      name: "project manifest",
+      status: "fail",
+      detail: `.q-ring.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
+function checkPolicy() {
+  const summary = getPolicySummary();
+  const active = [
+    summary.hasMcpPolicy && "mcp",
+    summary.hasExecPolicy && "exec",
+    summary.hasSecretPolicy && "secrets"
+  ].filter(Boolean);
+  return {
+    name: "governance policy",
+    status: "ok",
+    detail: active.length ? `active: ${active.join(", ")}` : 'none configured (add a "policy" section to .q-ring.json to enable)'
+  };
+}
+function checkMcpBinary() {
+  const exts = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      if (existsSync4(join3(dir, `qring-mcp${ext}`))) {
+        return {
+          name: "qring-mcp binary",
+          status: "ok",
+          detail: `found at ${join3(dir, `qring-mcp${ext}`)}`
+        };
+      }
+    }
+  }
+  return {
+    name: "qring-mcp binary",
+    status: "warn",
+    detail: "not on PATH \u2014 editor MCP configs that spawn `qring-mcp` will fail; install globally (pnpm add -g @i4ctime/q-ring)"
+  };
+}
+function registerDoctorCommand(program2) {
+  program2.command("doctor").description("Diagnose the q-ring installation (keyring, audit, manifest, MCP)").option("--project-path <path>", "Project path (defaults to cwd)").option("--json", "Output as JSON").action(async (cmd) => {
+    const projectPath = cmd.projectPath ?? process.cwd();
+    const checks = [
+      checkNode(),
+      await checkKeyringBackend(),
+      checkAuditLog(),
+      checkManifest(projectPath),
+      checkPolicy(),
+      checkMcpBinary()
+    ];
+    const failed = checks.filter((r) => r.status === "fail").length;
+    const warned = checks.filter((r) => r.status === "warn").length;
+    if (emitJson(program2, cmd, {
+      version: PACKAGE_VERSION,
+      projectPath,
+      checks,
+      healthy: failed === 0
+    })) {
+      if (failed > 0) process.exitCode = 1;
+      return;
+    }
+    console.log(c.bold(`
+  ${SYMBOLS.shield} qring doctor \u2014 v${PACKAGE_VERSION}
+`));
+    for (const r of checks) {
+      const icon = r.status === "ok" ? c.green(SYMBOLS.check) : r.status === "warn" ? c.yellow(SYMBOLS.warning) : c.red(SYMBOLS.cross);
+      console.log(`  ${icon} ${c.bold(r.name.padEnd(18))} ${c.dim(r.detail)}`);
+    }
+    console.log();
+    if (failed > 0) {
+      console.log(`  ${c.red(`${failed} check(s) failed`)}${warned ? c.dim(`, ${warned} warning(s)`) : ""}
+`);
+      process.exitCode = 1;
+    } else if (warned > 0) {
+      console.log(`  ${c.yellow(`${warned} warning(s)`)} ${c.dim("\u2014 everything critical is healthy")}
+`);
+    } else {
+      console.log(`  ${c.green("All checks passed.")}
+`);
+    }
+  });
+}
+
+// src/cli/commands/completion.ts
+function collect(cmd) {
+  return {
+    name: cmd.name(),
+    aliases: cmd.aliases(),
+    description: cmd.description(),
+    options: cmd.options.map((o) => ({ flag: o.long ?? o.short ?? "", description: o.description ?? "" })).filter((o) => o.flag.startsWith("--")),
+    subcommands: cmd.commands.filter((s) => s.name() !== "help").map((s) => collect(s))
+  };
+}
+var sanitize = (s) => s.replace(/['"`$\\]/g, "").replace(/[:[\]]/g, " ").replace(/\s+/g, " ").trim();
+function bashScript(cmds) {
+  const names = cmds.flatMap((x) => [x.name, ...x.aliases]).join(" ");
+  const cases = cmds.map((x) => {
+    const label = [x.name, ...x.aliases].join("|");
+    const opts = [...x.options.map((o) => o.flag), "--json"].join(" ");
+    const subs = x.subcommands.map((s) => s.name).join(" ");
+    const subCase = subs ? `
+      if [ "$COMP_CWORD" -eq 2 ]; then COMPREPLY=( $(compgen -W "${subs}" -- "$cur") ); return; fi` : "";
+    return `    ${label})${subCase}
+      opts="${opts}" ;;`;
+  }).join("\n");
+  return `# bash completion for qring \u2014 generated by \`qring completion bash\`
+_qring_completions() {
+  local cur cmd opts
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  cmd="\${COMP_WORDS[1]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${names}" -- "$cur") )
+    return
+  fi
+  opts="--json --help"
+  case "$cmd" in
+${cases}
+  esac
+  case "$cur" in
+    -*) COMPREPLY=( $(compgen -W "$opts --help" -- "$cur") ) ;;
+  esac
+}
+complete -o default -F _qring_completions qring
+`;
+}
+function zshScript(cmds) {
+  const items = cmds.map((x) => `    '${x.name}:${sanitize(x.description)}'`).join("\n");
+  const cases = cmds.map((x) => {
+    const label = [x.name, ...x.aliases].join("|");
+    const words = [
+      ...x.subcommands.map((s) => s.name),
+      ...x.options.map((o) => o.flag),
+      "--json"
+    ].join(" ");
+    return `    ${label}) compadd -- ${words} ;;`;
+  }).join("\n");
+  return `#compdef qring
+# zsh completion for qring \u2014 generated by \`qring completion zsh\`
+_qring() {
+  local -a commands
+  commands=(
+${items}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case $words[2] in
+${cases}
+  esac
+}
+_qring "$@"
+`;
+}
+function fishScript(cmds) {
+  const lines = [
+    "# fish completion for qring \u2014 generated by `qring completion fish`",
+    "complete -c qring -f"
+  ];
+  const allNames = cmds.flatMap((x) => [x.name, ...x.aliases]);
+  for (const x of cmds) {
+    for (const name of [x.name, ...x.aliases]) {
+      lines.push(
+        `complete -c qring -n "not __fish_seen_subcommand_from ${allNames.join(" ")}" -a ${name} -d "${sanitize(x.description)}"`
+      );
+    }
+    for (const s of x.subcommands) {
+      lines.push(
+        `complete -c qring -n "__fish_seen_subcommand_from ${x.name}" -a ${s.name} -d "${sanitize(s.description)}"`
+      );
+    }
+    for (const o of [...x.options, { flag: "--json", description: "Output as JSON" }]) {
+      lines.push(
+        `complete -c qring -n "__fish_seen_subcommand_from ${x.name}" -l ${o.flag.slice(2)} -d "${sanitize(o.description)}"`
+      );
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+function registerCompletionCommand(program2) {
+  program2.command("completion <shell>").description("Print a shell completion script (bash, zsh, fish)").action((shell) => {
+    const cmds = program2.commands.filter((s) => s.name() !== "help" && s.name() !== "completion").map((s) => collect(s));
+    if (shell === "bash") process.stdout.write(bashScript(cmds));
+    else if (shell === "zsh") process.stdout.write(zshScript(cmds));
+    else if (shell === "fish") process.stdout.write(fishScript(cmds));
+    else {
+      console.error(c.red(`Unknown shell "${shell}" \u2014 expected bash, zsh, or fish`));
+      process.exitCode = 1;
+    }
+  });
+}
+
 // src/cli/commands.ts
 var COMMAND_GROUPS = [
   {
@@ -3123,6 +3663,7 @@ var COMMAND_GROUPS = [
     commands: [
       "set",
       "get",
+      "has",
       "delete",
       "list",
       "inspect",
@@ -3154,7 +3695,7 @@ var COMMAND_GROUPS = [
   {
     name: "Dev Tooling",
     symbol: SYMBOLS.zap,
-    commands: ["exec", "scan", "lint", "status"]
+    commands: ["exec", "scan", "lint", "status", "doctor", "completion"]
   },
   {
     name: "Audit & Health",
@@ -3296,10 +3837,21 @@ function createProgram() {
   registerHookCommands(program2);
   registerAgentCommands(program2);
   registerSecurityCommands(program2);
+  registerDoctorCommand(program2);
+  registerCompletionCommand(program2);
   return program2;
 }
 
 // src/index.ts
 var program = createProgram();
-program.parse();
+try {
+  await program.parseAsync();
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(c.red(`${SYMBOLS.cross} ${message}`));
+  if (process.env.QRING_DEBUG && err instanceof Error && err.stack) {
+    console.error(c.dim(err.stack));
+  }
+  process.exitCode = 1;
+}
 //# sourceMappingURL=index.js.map