@fiscalmindset/blindfold 0.4.1 → 0.4.3

package/bin/blindfold.ts

@@ -5,7 +5,8 @@
  */
 import { type Argv, parseArgv } from "./cli-shared.ts";
 import { c, bad } from "../src/color.ts";
-import { bannerBox, commandBox, nearest } from "../src/tui.ts";
+import { nearest } from "../src/tui.ts";
+import { renderMainHelp, renderCommandHelp, findCommand } from "../src/help.ts";
 import { handleAuth } from "./cmd-auth.ts";
 import { handleSecrets } from "./cmd-secrets.ts";
 import { handleLifecycle } from "./cmd-lifecycle.ts";
@@ -35,9 +36,21 @@ async function main(): Promise<void> {
   const cmdArgs = ddIdx >= 0 ? raw.slice(ddIdx + 1) : [];
   const argv = parseArgv(ddIdx >= 0 ? raw.slice(0, ddIdx) : raw);
   const cmd = argv._[0] ?? "help";
+
+  // `blindfold help` / `blindfold help <cmd>`
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+    const sub = String(argv._[1] ?? "");
+    console.log(sub && findCommand(sub) ? renderCommandHelp(sub) : renderMainHelp());
+    return;
+  }
+  // `blindfold <cmd> --help` / `-h` → per-command help instead of running it.
+  if ((argv.flags.help || argv.flags.h) && findCommand(cmd)) {
+    console.log(renderCommandHelp(cmd));
+    return;
+  }
+
   const handler = ROUTES[cmd];
   if (handler) await handler(cmd, argv, cmdArgs);
-  else if (cmd === "help" || cmd === "--help" || cmd === "-h") printHelp();
   else printUnknown(cmd);
 }
 
@@ -54,74 +67,6 @@ function printUnknown(cmd: string): void {
   process.exit(1);
 }
 
-function printHelp(): void {
-  const groups: Array<[string, Array<[string, string]>]> = [
-    ["🚀 Get started", [
-      ["signup", "Self-serve: mint a funded Terminal 3 testnet tenant (key generated locally, email-verified)."],
-      ["init", "Guided zero-knowledge setup: .env, build, auth, publish, seed; can auto-start the proxy."],
-      ["doctor", "Show mode + config and run a live tenant health check."],
-      ["credit", "Show the tenant's Terminal 3 token balance (costs nothing)."],
-      ["verify", "Handshake + authenticate against T3 (smoke test)."],
-    ]],
-    ["🔑 Secrets", [
-      ["register", "Seal a secret into the enclave (hidden prompt; never touches disk)."],
-      ["use", "Release a sealed secret into one command as $ENV — never back in your env."],
-      ["export", "CI: release a sealed secret into $GITHUB_ENV (masked in logs)."],
-      ["rotate", "Replace a sealed secret's value (snapshots the old one for rollback)."],
-      ["rollback", "Restore a previous value snapshotted by rotate."],
-      ["versions", "List the snapshots available to roll back to (metadata only)."],
-      ["migrate", "Seal every secret in .env at once, then remove the plaintext lines."],
-    ]],
-    ["🌐 Proxy & serve", [
-      ["proxy", "Run the local sentinel proxy. --auth mints a session token; --socket binds a 0600 unix socket."],
-      ["attest", "Verify the enclave's TDX attestation (Intel root CA). --pin gates seal/proxy on the code measurement."],
-      ["dashboard", "Live HTML dashboard of proxy usage (default :8799)."],
-      ["stats", "CLI summary of proxy usage (stats:clear wipes it)."],
-    ]],
-    ["👥 Team & sharing", [
-      ["grant", "Authorize the contract to call these hosts (e.g. --host api.openai.com)."],
-      ["share", "Let a teammate's agent USE your sealed keys for a host — forward only, no plaintext."],
-      ["revoke", "Remove a teammate's access — immediate and complete."],
-    ]],
-    ["📦 Enclave & admin", [
-      ["publish", "Publish the Rust→WASM contract to your tenant (one-time)."],
-      ["status", "One-glance: mode, tenant health, and sealed secrets."],
-      ["sealed", "List sealed keys — metadata only, never the value."],
-      ["audit", "Verify the ledger hash-chain and reconcile it against the enclave."],
-      ["compat", "Scan this machine for AI agent tools + print the env-var swap for each."],
-      ["update", "Update the global install (from npm, or --from <repo>)."],
-    ]],
-    ["👤 Account", [
-      ["login", "Store existing Terminal 3 credentials (key → OS keychain)."],
-      ["logout", "Remove stored credentials."],
-      ["whoami", "Show tenant, env, and key source (never the value)."],
-    ]],
-    ["🤖 Agent skill", [
-      ["skill", "install [--global|--cursor|--opencode|--cline|--all] / uninstall — the agent skill for your coding agent."],
-    ]],
-  ];
-
-  const out: string[] = [
-    "",
-    bannerBox("🛡️  Blindfold", "Protect your AI agent's API keys with Terminal 3 enclaves. The agent only ever holds a placeholder — the real key is substituted inside the TDX enclave."),
-    "",
-  ];
-  for (const [title, rows] of groups) {
-    out.push(commandBox(title, rows));
-    out.push("");
-  }
-  out.push(
-    c.bold("Quick start"),
-    `  ${c.cyan("blindfold signup --email you@x.com")}   ${c.gray("# create a funded testnet tenant")}`,
-    `  ${c.cyan("blindfold register --name openai_api_key")}`,
-    `  ${c.cyan("blindfold proxy")}                        ${c.gray("# point your agent at http://127.0.0.1:8787")}`,
-    "",
-    `${c.gray("Docs:")} ${c.cyan("https://www.npmjs.com/package/@fiscalmindset/blindfold")}   ${c.gray("·")}   ${c.gray("Run")} ${c.cyan("blindfold <command> --help")} ${c.gray("for details")}`,
-    "",
-  );
-  console.log(out.join("\n"));
-}
-
 main().catch((e) => {
   console.error("✖", (e as Error).message);
   process.exit(1);

package/dist/cli.mjs

@@ -1395,9 +1395,10 @@ function vlen(s) {
   }
   return w;
 }
-function padEnd(s, w) {
+function pad(s, w) {
   return s + " ".repeat(Math.max(0, w - vlen(s)));
 }
+var padEnd = pad;
 function wrapText(text, width) {
   if (width <= 4) return [text];
   const out = [];
@@ -1429,31 +1430,23 @@ function bannerBox(title, subtitle) {
   lines.push(bot);
   return lines.join("\n");
 }
-function commandBox(title, rows) {
+function boxLines(title, lines) {
   const w = termWidth();
   const inner = w - 4;
-  const gap = 2;
-  const longest = rows.reduce((m, [cmd]) => Math.max(m, vlen(cmd)), 0);
-  const cmdW = Math.min(longest, Math.max(10, Math.floor(inner * 0.34)));
-  const descW = Math.max(12, inner - cmdW - gap);
   const prefix = B.tl + B.h + " ";
-  const fill = Math.max(
-    0,
-    w - vlen(prefix) - vlen(title) - 1 - 1
-    /* tr */
-  );
+  const fill = Math.max(0, w - vlen(prefix) - vlen(title) - 2);
   const out = [dim(prefix) + c.bold(title) + dim(" " + B.h.repeat(fill) + B.tr)];
-  for (const [cmd, desc] of rows) {
-    const dLines = wrapText(desc, descW);
-    const cmdCell = padEnd(c.cyan(cmd), cmdW);
-    out.push(dim(B.v) + " " + cmdCell + " ".repeat(gap) + padEnd(dLines[0] ?? "", descW) + " " + dim(B.v));
-    for (let i = 1; i < dLines.length; i++) {
-      out.push(dim(B.v) + " " + " ".repeat(cmdW + gap) + padEnd(dim(dLines[i] ?? ""), descW) + " " + dim(B.v));
-    }
-  }
+  for (const l of lines) out.push(dim(B.v) + " " + pad(l, inner) + " " + dim(B.v));
   out.push(dim(B.bl + B.h.repeat(w - 2) + B.br));
   return out.join("\n");
 }
+function rule(label = "") {
+  const w = termWidth();
+  if (!label) return dim(B.h.repeat(w));
+  const left = B.h + B.h + " ";
+  const fill = Math.max(0, w - vlen(left) - vlen(label) - 1);
+  return dim(left) + c.bold(label) + dim(" " + B.h.repeat(fill));
+}
 function nearest(input, candidates) {
   let best = null;
   let bestD = Infinity;
@@ -1478,6 +1471,270 @@ function editDistance(a, b) {
   return dp[a.length][b.length];
 }
 
+// src/help.ts
+var GROUP_ORDER = [
+  "\u{1F680} Get started",
+  "\u{1F511} Secrets",
+  "\u{1F310} Proxy & serve",
+  "\u{1F465} Team & sharing",
+  "\u{1F4E6} Enclave & admin",
+  "\u{1F464} Account",
+  "\u{1F916} Agent skill"
+];
+var COMMANDS = [
+  // ── Get started ──────────────────────────────────────────────────────────
+  {
+    name: "signup",
+    group: "\u{1F680} Get started",
+    usage: "[--email <addr>] [--first <name>] [--last <name>]",
+    summary: "Self-serve: mint a funded Terminal 3 testnet tenant (key generated locally, email-verified).",
+    flags: [
+      ["--email <addr>", "Email for the tenant; a verification code is sent there. Prompts if omitted."],
+      ["--first <name>", "First name for the profile (default: from the email local-part)."],
+      ["--last <name>", 'Last name for the profile (default: "Tenant").'],
+      ["--otp <code>", "Supply the emailed code non-interactively (for scripts)."]
+    ],
+    examples: ["blindfold signup --email you@example.com"],
+    notes: "Testnet-only. One email binds to one tenant \u2014 Gmail +aliases give fresh identities. Already have credentials? Use `blindfold login`."
+  },
+  {
+    name: "init",
+    group: "\u{1F680} Get started",
+    usage: "[--seed <KV:ENV>]... [--start]",
+    summary: "Guided zero-knowledge setup: .env, build, auth, publish, seed; can auto-start the proxy.",
+    flags: [
+      ["--seed <KV:ENV>", "Seal <ENV>'s value into secret <KV> as the last setup step (repeatable)."],
+      ["--start", "Launch the proxy when setup finishes."]
+    ],
+    examples: ["blindfold init", "blindfold init --seed openai_api_key:OPENAI_API_KEY --start"]
+  },
+  { name: "doctor", group: "\u{1F680} Get started", usage: "", summary: "Show mode + config and run a live tenant health check (handshake + authenticate + me).", examples: ["blindfold doctor"] },
+  {
+    name: "credit",
+    group: "\u{1F680} Get started",
+    usage: "[--json]",
+    aliases: ["balance"],
+    summary: "Show the tenant's Terminal 3 token balance (costs nothing; works even at zero).",
+    flags: [["--json", "Print the raw balance object instead of the formatted view."]],
+    examples: ["blindfold credit"]
+  },
+  { name: "verify", group: "\u{1F680} Get started", usage: "", summary: "Handshake + authenticate against Terminal 3 (a smoke test).", examples: ["blindfold verify"] },
+  // ── Secrets ──────────────────────────────────────────────────────────────
+  {
+    name: "register",
+    group: "\u{1F511} Secrets",
+    usage: "--name <KEY> [--from-env <ENV>]",
+    summary: "Seal a secret into the enclave (one-time). Hidden prompt by default \u2014 never touches disk.",
+    flags: [
+      ["--name <KEY>", "Logical name for the sealed secret (required)."],
+      ["--from-env <ENV>", "Read the value from process.env.<ENV> instead of prompting."]
+    ],
+    examples: ["blindfold register --name openai_api_key", 'echo "$KEY" | blindfold register --name openai_api_key'],
+    notes: "Without --from-env it prompts with no echo (preferred). Piped stdin also works."
+  },
+  {
+    name: "use",
+    group: "\u{1F511} Secrets",
+    usage: "--name <secret> [--as <ENV>] -- <cmd...>   |   --name <secret> --url <https>",
+    summary: "Release a sealed secret into ONE command as $ENV \u2014 never back in your environment.",
+    flags: [
+      ["--name <secret>", "The sealed secret to release (required)."],
+      ["--as <ENV>", "Env var to inject it as. Auto-detected for known tools (gh\u2192GH_TOKEN, psql\u2192PGPASSWORD\u2026)."],
+      ["--url <https>", "Instead of running a command, do a quick authenticated GET to this URL."]
+    ],
+    examples: ["blindfold use --name gh_token -- gh api user", "blindfold use --name openai_api_key --as OPENAI_API_KEY -- node agent.js"]
+  },
+  {
+    name: "export",
+    group: "\u{1F511} Secrets",
+    usage: "--name <secret> [--as <ENV>]",
+    summary: "CI: release a sealed secret into $GITHUB_ENV for later steps (masked in logs).",
+    flags: [["--name <secret>", "The sealed secret to export (required)."], ["--as <ENV>", "Env var name to write (default: the secret name upper-cased)."]],
+    examples: ["blindfold export --name openai_api_key --as OPENAI_API_KEY"]
+  },
+  {
+    name: "rotate",
+    group: "\u{1F511} Secrets",
+    usage: "--name <secret> [--from-env <ENV>]",
+    summary: "Replace a sealed secret's value; snapshots the old one for rollback (fingerprints only).",
+    flags: [["--name <secret>", "The sealed secret to rotate (required)."], ["--from-env <ENV>", "Read the new value from an env var instead of prompting."]],
+    examples: ["blindfold rotate --name stripe_secret_key"]
+  },
+  {
+    name: "rollback",
+    group: "\u{1F511} Secrets",
+    usage: "--name <secret> [--to <fp|iso-ts>]",
+    summary: "Restore a previous value snapshotted by rotate (most recent by default).",
+    flags: [["--name <secret>", "The sealed secret to roll back (required)."], ["--to <fp|iso-ts>", "Target a specific snapshot by fingerprint or timestamp."]],
+    examples: ["blindfold rollback --name stripe_secret_key"]
+  },
+  { name: "versions", group: "\u{1F511} Secrets", usage: "[--name <secret>]", summary: "List the snapshots available to roll back to (metadata only).", flags: [["--name <secret>", "Limit to one secret."]], examples: ["blindfold versions --name stripe_secret_key"] },
+  {
+    name: "migrate",
+    group: "\u{1F511} Secrets",
+    usage: "[--dry-run] [--keep]",
+    summary: "Seal every secret in .env at once, then remove the plaintext lines (backup kept).",
+    flags: [["--dry-run", "Preview what would be sealed, change nothing."], ["--keep", "Comment out the .env lines instead of deleting them."]],
+    examples: ["blindfold migrate --dry-run", "blindfold migrate"],
+    notes: "Skips T3 creds + config (T3N_API_KEY / DID)."
+  },
+  // ── Proxy & serve ────────────────────────────────────────────────────────
+  {
+    name: "proxy",
+    group: "\u{1F310} Proxy & serve",
+    usage: "[--port <n>] [--auth] [--socket [path]]",
+    summary: "Run the local sentinel proxy your agent points at. Substitution happens in the enclave.",
+    flags: [
+      ["--port <n>", "TCP port to listen on (default 8787)."],
+      ["--auth", "Mint a per-session token so only the wrapped agent can use the proxy."],
+      ["--socket [path]", "Bind a 0600 unix-domain socket (only your OS user can connect)."]
+    ],
+    examples: ["blindfold proxy", "blindfold proxy --auth", "blindfold proxy --socket"],
+    notes: "Point your agent at http://127.0.0.1:8787 and send Authorization: Bearer __BLINDFOLD__."
+  },
+  {
+    name: "attest",
+    group: "\u{1F310} Proxy & serve",
+    usage: "[--expect-rtmr3 <b64>] [--pin] [--json]",
+    summary: "Verify the enclave's TDX attestation (chains to Intel's root CA).",
+    flags: [
+      ["--expect-rtmr3 <b64>", "Assert the code measurement equals this value."],
+      ["--pin", "Record the RTMR3 so seal/proxy auto-verify the enclave first."],
+      ["--json", "Machine-readable output."]
+    ],
+    examples: ["blindfold attest", "blindfold attest --pin"]
+  },
+  { name: "dashboard", group: "\u{1F310} Proxy & serve", usage: "[--port <n>]", summary: "Live HTML dashboard of proxy usage (default :8799).", flags: [["--port <n>", "Port for the dashboard (default 8799)."]], examples: ["blindfold dashboard"] },
+  { name: "stats", group: "\u{1F310} Proxy & serve", usage: "", summary: "CLI summary of proxy usage. `stats:clear` wipes the log.", examples: ["blindfold stats", "blindfold stats:clear"] },
+  // ── Team & sharing ───────────────────────────────────────────────────────
+  {
+    name: "grant",
+    group: "\u{1F465} Team & sharing",
+    usage: "--host <host>[,<host2>...]",
+    summary: "Allow the enclave to reach an API's server. Do this once per API before the proxy can call it \u2014 e.g. allow api.openai.com so a sealed OpenAI key can be used.",
+    flags: [["--host <host,...>", "The API hostname(s) to allow, comma-separated. Each grant adds to the list."]],
+    examples: ["blindfold grant --host api.openai.com", "blindfold grant --host api.github.com,api.stripe.com"],
+    notes: "Why it's needed: the enclave refuses to call any host you haven't allowed (deny-by-default). Grant the host of each API whose key you've sealed."
+  },
+  {
+    name: "share",
+    group: "\u{1F465} Team & sharing",
+    usage: "--to <agent-did> --host <host>[,...]",
+    summary: "Let a teammate use your sealed key for an API \u2014 they can make calls but never see the key itself.",
+    flags: [["--to <agent-did>", "The teammate's agent DID (their Terminal 3 identity)."], ["--host <host,...>", "Which API hosts they're allowed to reach through your enclave."]],
+    examples: ["blindfold share --to did:t3n:abc\u2026 --host api.openai.com"]
+  },
+  { name: "revoke", group: "\u{1F465} Team & sharing", usage: "--to <agent-did>", summary: "Take back a teammate's access you granted with `share` \u2014 immediate and complete.", flags: [["--to <agent-did>", "The teammate's agent DID to cut off."]], examples: ["blindfold revoke --to did:t3n:abc\u2026"] },
+  // ── Enclave & admin ──────────────────────────────────────────────────────
+  { name: "publish", group: "\u{1F4E6} Enclave & admin", usage: "[--wasm <path>]", summary: "Publish the Rust\u2192WASM contract to your tenant (one-time).", flags: [["--wasm <path>", "Path to blindfold_proxy.wasm (defaults to the bundled build)."]], examples: ["blindfold publish"] },
+  { name: "status", group: "\u{1F4E6} Enclave & admin", usage: "", summary: "One-glance overview: mode, tenant health, and the list of sealed secrets.", examples: ["blindfold status"] },
+  { name: "sealed", group: "\u{1F4E6} Enclave & admin", usage: "", summary: "List sealed keys \u2014 metadata only (name, byte-length, when, where). Never the value.", examples: ["blindfold sealed"] },
+  { name: "audit", group: "\u{1F4E6} Enclave & admin", usage: "", summary: "Verify the ledger hash-chain and reconcile it against the enclave (flags drift/tampering).", examples: ["blindfold audit"] },
+  { name: "compat", group: "\u{1F4E6} Enclave & admin", usage: "[--json]", summary: "Scan this machine for AI agent tools and print the exact env-var swap for each.", flags: [["--json", "Machine-readable output."]], examples: ["blindfold compat"] },
+  { name: "update", group: "\u{1F4E6} Enclave & admin", usage: "[--from <path>]", aliases: ["upgrade"], summary: "Update the global install (from npm, or a local repo with --from).", flags: [["--from <path>", "Build + install from a local repo checkout instead of npm."]], examples: ["blindfold update"] },
+  // ── Account ──────────────────────────────────────────────────────────────
+  {
+    name: "login",
+    group: "\u{1F464} Account",
+    usage: "[--did <did>] [--key <0x\u2026>] [--env <net>] [--file]",
+    summary: "Store EXISTING Terminal 3 credentials (tenant key \u2192 OS keychain).",
+    flags: [
+      ["--did <did>", "Tenant DID (prompts if omitted)."],
+      ["--key <0x\u2026>", "Tenant key (prompts hidden if omitted)."],
+      ["--env <net>", "testnet (default) or production."],
+      ["--file", "Force a 0600 config file instead of the OS keychain."]
+    ],
+    examples: ["blindfold login", "blindfold login --did did:t3n:\u2026 --env testnet"]
+  },
+  { name: "logout", group: "\u{1F464} Account", usage: "", summary: "Remove stored credentials (keychain entry + config file).", examples: ["blindfold logout"] },
+  { name: "whoami", group: "\u{1F464} Account", usage: "", summary: "Show tenant, env, and key source \u2014 never the value.", examples: ["blindfold whoami"] },
+  // ── Agent skill ──────────────────────────────────────────────────────────
+  {
+    name: "skill",
+    group: "\u{1F916} Agent skill",
+    usage: "install [--global|--cursor|--opencode|--cline|--all]  |  uninstall",
+    summary: "Install the Blindfold agent skill so your coding agent handles secrets safely.",
+    flags: [
+      ["--global", "Install for every Claude Code session on this machine."],
+      ["--cursor / --opencode / --cline", "Install for that agent instead of Claude Code."],
+      ["--all", "Install everywhere at once."]
+    ],
+    examples: ["blindfold skill install", "blindfold skill install --all"]
+  }
+];
+function findCommand(name) {
+  return COMMANDS.find((c2) => c2.name === name || c2.aliases?.includes(name));
+}
+function renderMainHelp() {
+  const w = termWidth();
+  const out = [
+    "",
+    bannerBox("\u{1F6E1}\uFE0F  Blindfold", "Protect your AI agent's API keys with Terminal 3 enclaves. The agent only ever holds a placeholder \u2014 the real key is substituted inside the TDX enclave."),
+    ""
+  ];
+  const nameW = Math.min(12, COMMANDS.reduce((m, cmd) => Math.max(m, vlen(cmd.name)), 0));
+  const descW = Math.max(16, w - 4 - nameW - 2);
+  const fit = (s, max) => s.length > max ? s.slice(0, Math.max(1, max - 1)) + "\u2026" : s;
+  for (const group of GROUP_ORDER) {
+    const cmds = COMMANDS.filter((cmd) => cmd.group === group);
+    const lines = [];
+    for (const [idx, cmd] of cmds.entries()) {
+      if (idx > 0) lines.push("");
+      const dl = wrapText(cmd.summary, descW);
+      lines.push(pad(c.bold(c.cyan(cmd.name)), nameW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) lines.push(pad("", nameW) + "  " + (dl[i] ?? ""));
+      const ex = fit(cmd.examples?.[0] ?? `blindfold ${cmd.name}`, descW - 5);
+      lines.push(pad("", nameW) + "  " + c.gray("e.g. ") + c.green(ex));
+    }
+    out.push(boxLines(group, lines));
+    out.push("");
+  }
+  out.push(
+    c.bold(c.magenta("\u25B6 Quick start")),
+    `  ${c.green("blindfold signup --email you@x.com")}         ${c.gray("# create a funded testnet tenant")}`,
+    `  ${c.green("blindfold register --name openai_api_key")}   ${c.gray("# seal a key (hidden prompt)")}`,
+    `  ${c.green("blindfold proxy")}                            ${c.gray("# point your agent at http://127.0.0.1:8787")}`,
+    "",
+    `${c.gray("Full flags + more examples for any command:")}  ${c.cyan("blindfold <command> --help")}`,
+    `${c.gray("Docs:")} ${c.cyan("npmjs.com/package/@fiscalmindset/blindfold")}`,
+    ""
+  );
+  return out.join("\n");
+}
+function renderCommandHelp(name) {
+  const cmd = findCommand(name);
+  if (!cmd) return renderMainHelp();
+  const w = termWidth();
+  const out = ["", boxLines(`blindfold ${cmd.name}`, wrapText(cmd.summary, w - 4)), ""];
+  out.push(rule("Usage"));
+  out.push("  " + c.cyan(`blindfold ${cmd.name}${cmd.usage ? " " + cmd.usage : ""}`));
+  if (cmd.aliases?.length) out.push("  " + c.gray(`alias: ${cmd.aliases.map((a) => "blindfold " + a).join(", ")}`));
+  out.push("");
+  if (cmd.flags?.length) {
+    out.push(rule("Flags"));
+    const flagW = Math.min(24, cmd.flags.reduce((m, [f]) => Math.max(m, vlen(f)), 0));
+    const dW = Math.max(16, w - 2 - flagW - 2);
+    for (const [flag, desc] of cmd.flags) {
+      const dl = wrapText(desc, dW);
+      out.push("  " + pad(c.yellow(flag), flagW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) out.push("  " + pad("", flagW) + "  " + c.gray(dl[i] ?? ""));
+    }
+    out.push("");
+  }
+  if (cmd.examples?.length) {
+    out.push(rule("Examples"));
+    for (const ex of cmd.examples) out.push("  " + c.cyan(ex));
+    out.push("");
+  }
+  if (cmd.notes) {
+    out.push(rule("Notes"));
+    for (const nl of wrapText(cmd.notes, w - 2)) out.push("  " + c.gray(nl));
+    out.push("");
+  }
+  out.push(c.gray("See all commands: ") + c.cyan("blindfold help"));
+  return out.join("\n");
+}
+
 // bin/cmd-auth.ts
 init_env();
 init_keychain();
@@ -4367,9 +4624,17 @@ async function main() {
   const cmdArgs = ddIdx >= 0 ? raw.slice(ddIdx + 1) : [];
   const argv = parseArgv(ddIdx >= 0 ? raw.slice(0, ddIdx) : raw);
   const cmd = argv._[0] ?? "help";
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+    const sub = String(argv._[1] ?? "");
+    console.log(sub && findCommand(sub) ? renderCommandHelp(sub) : renderMainHelp());
+    return;
+  }
+  if ((argv.flags.help || argv.flags.h) && findCommand(cmd)) {
+    console.log(renderCommandHelp(cmd));
+    return;
+  }
   const handler = ROUTES[cmd];
   if (handler) await handler(cmd, argv, cmdArgs);
-  else if (cmd === "help" || cmd === "--help" || cmd === "-h") printHelp();
   else printUnknown(cmd);
 }
 function printUnknown(cmd) {
@@ -4381,72 +4646,6 @@ function printUnknown(cmd) {
   console.error(c.gray("  Run ") + c.cyan("blindfold help") + c.gray(" to see all commands."));
   process.exit(1);
 }
-function printHelp() {
-  const groups = [
-    ["\u{1F680} Get started", [
-      ["signup", "Self-serve: mint a funded Terminal 3 testnet tenant (key generated locally, email-verified)."],
-      ["init", "Guided zero-knowledge setup: .env, build, auth, publish, seed; can auto-start the proxy."],
-      ["doctor", "Show mode + config and run a live tenant health check."],
-      ["credit", "Show the tenant's Terminal 3 token balance (costs nothing)."],
-      ["verify", "Handshake + authenticate against T3 (smoke test)."]
-    ]],
-    ["\u{1F511} Secrets", [
-      ["register", "Seal a secret into the enclave (hidden prompt; never touches disk)."],
-      ["use", "Release a sealed secret into one command as $ENV \u2014 never back in your env."],
-      ["export", "CI: release a sealed secret into $GITHUB_ENV (masked in logs)."],
-      ["rotate", "Replace a sealed secret's value (snapshots the old one for rollback)."],
-      ["rollback", "Restore a previous value snapshotted by rotate."],
-      ["versions", "List the snapshots available to roll back to (metadata only)."],
-      ["migrate", "Seal every secret in .env at once, then remove the plaintext lines."]
-    ]],
-    ["\u{1F310} Proxy & serve", [
-      ["proxy", "Run the local sentinel proxy. --auth mints a session token; --socket binds a 0600 unix socket."],
-      ["attest", "Verify the enclave's TDX attestation (Intel root CA). --pin gates seal/proxy on the code measurement."],
-      ["dashboard", "Live HTML dashboard of proxy usage (default :8799)."],
-      ["stats", "CLI summary of proxy usage (stats:clear wipes it)."]
-    ]],
-    ["\u{1F465} Team & sharing", [
-      ["grant", "Authorize the contract to call these hosts (e.g. --host api.openai.com)."],
-      ["share", "Let a teammate's agent USE your sealed keys for a host \u2014 forward only, no plaintext."],
-      ["revoke", "Remove a teammate's access \u2014 immediate and complete."]
-    ]],
-    ["\u{1F4E6} Enclave & admin", [
-      ["publish", "Publish the Rust\u2192WASM contract to your tenant (one-time)."],
-      ["status", "One-glance: mode, tenant health, and sealed secrets."],
-      ["sealed", "List sealed keys \u2014 metadata only, never the value."],
-      ["audit", "Verify the ledger hash-chain and reconcile it against the enclave."],
-      ["compat", "Scan this machine for AI agent tools + print the env-var swap for each."],
-      ["update", "Update the global install (from npm, or --from <repo>)."]
-    ]],
-    ["\u{1F464} Account", [
-      ["login", "Store existing Terminal 3 credentials (key \u2192 OS keychain)."],
-      ["logout", "Remove stored credentials."],
-      ["whoami", "Show tenant, env, and key source (never the value)."]
-    ]],
-    ["\u{1F916} Agent skill", [
-      ["skill", "install [--global|--cursor|--opencode|--cline|--all] / uninstall \u2014 the agent skill for your coding agent."]
-    ]]
-  ];
-  const out = [
-    "",
-    bannerBox("\u{1F6E1}\uFE0F  Blindfold", "Protect your AI agent's API keys with Terminal 3 enclaves. The agent only ever holds a placeholder \u2014 the real key is substituted inside the TDX enclave."),
-    ""
-  ];
-  for (const [title, rows] of groups) {
-    out.push(commandBox(title, rows));
-    out.push("");
-  }
-  out.push(
-    c.bold("Quick start"),
-    `  ${c.cyan("blindfold signup --email you@x.com")}   ${c.gray("# create a funded testnet tenant")}`,
-    `  ${c.cyan("blindfold register --name openai_api_key")}`,
-    `  ${c.cyan("blindfold proxy")}                        ${c.gray("# point your agent at http://127.0.0.1:8787")}`,
-    "",
-    `${c.gray("Docs:")} ${c.cyan("https://www.npmjs.com/package/@fiscalmindset/blindfold")}   ${c.gray("\xB7")}   ${c.gray("Run")} ${c.cyan("blindfold <command> --help")} ${c.gray("for details")}`,
-    ""
-  );
-  console.log(out.join("\n"));
-}
 main().catch((e) => {
   console.error("\u2716", e.message);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiscalmindset/blindfold",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "description": "Make any AI agent's API keys un-leakable, by sealing them inside a Terminal 3 TDX enclave.",
   "license": "MIT",

package/src/help.ts

@@ -0,0 +1,277 @@
+/**
+ * Command registry + help renderers. Drives both the grouped `blindfold help`
+ * overview (with per-command usage) and the detailed `blindfold <cmd> --help`
+ * (usage + flags + examples). All output reflows to the terminal width.
+ */
+import { c } from "./color.ts";
+import { termWidth, vlen, wrapText, pad, bannerBox, boxLines, rule } from "./tui.ts";
+
+interface CmdDef {
+  name: string;
+  group: string;
+  usage: string; // args/flags after the command name, e.g. "[--email <addr>]"
+  summary: string;
+  flags?: Array<[string, string]>;
+  examples?: string[];
+  notes?: string;
+  aliases?: string[];
+}
+
+const GROUP_ORDER = [
+  "🚀 Get started",
+  "🔑 Secrets",
+  "🌐 Proxy & serve",
+  "👥 Team & sharing",
+  "📦 Enclave & admin",
+  "👤 Account",
+  "🤖 Agent skill",
+];
+
+export const COMMANDS: CmdDef[] = [
+  // ── Get started ──────────────────────────────────────────────────────────
+  {
+    name: "signup", group: "🚀 Get started",
+    usage: "[--email <addr>] [--first <name>] [--last <name>]",
+    summary: "Self-serve: mint a funded Terminal 3 testnet tenant (key generated locally, email-verified).",
+    flags: [
+      ["--email <addr>", "Email for the tenant; a verification code is sent there. Prompts if omitted."],
+      ["--first <name>", "First name for the profile (default: from the email local-part)."],
+      ["--last <name>", "Last name for the profile (default: \"Tenant\")."],
+      ["--otp <code>", "Supply the emailed code non-interactively (for scripts)."],
+    ],
+    examples: ["blindfold signup --email you@example.com"],
+    notes: "Testnet-only. One email binds to one tenant — Gmail +aliases give fresh identities. Already have credentials? Use `blindfold login`.",
+  },
+  {
+    name: "init", group: "🚀 Get started",
+    usage: "[--seed <KV:ENV>]... [--start]",
+    summary: "Guided zero-knowledge setup: .env, build, auth, publish, seed; can auto-start the proxy.",
+    flags: [
+      ["--seed <KV:ENV>", "Seal <ENV>'s value into secret <KV> as the last setup step (repeatable)."],
+      ["--start", "Launch the proxy when setup finishes."],
+    ],
+    examples: ["blindfold init", "blindfold init --seed openai_api_key:OPENAI_API_KEY --start"],
+  },
+  { name: "doctor", group: "🚀 Get started", usage: "", summary: "Show mode + config and run a live tenant health check (handshake + authenticate + me).", examples: ["blindfold doctor"] },
+  {
+    name: "credit", group: "🚀 Get started", usage: "[--json]", aliases: ["balance"],
+    summary: "Show the tenant's Terminal 3 token balance (costs nothing; works even at zero).",
+    flags: [["--json", "Print the raw balance object instead of the formatted view."]],
+    examples: ["blindfold credit"],
+  },
+  { name: "verify", group: "🚀 Get started", usage: "", summary: "Handshake + authenticate against Terminal 3 (a smoke test).", examples: ["blindfold verify"] },
+
+  // ── Secrets ──────────────────────────────────────────────────────────────
+  {
+    name: "register", group: "🔑 Secrets",
+    usage: "--name <KEY> [--from-env <ENV>]",
+    summary: "Seal a secret into the enclave (one-time). Hidden prompt by default — never touches disk.",
+    flags: [
+      ["--name <KEY>", "Logical name for the sealed secret (required)."],
+      ["--from-env <ENV>", "Read the value from process.env.<ENV> instead of prompting."],
+    ],
+    examples: ["blindfold register --name openai_api_key", "echo \"$KEY\" | blindfold register --name openai_api_key"],
+    notes: "Without --from-env it prompts with no echo (preferred). Piped stdin also works.",
+  },
+  {
+    name: "use", group: "🔑 Secrets",
+    usage: "--name <secret> [--as <ENV>] -- <cmd...>   |   --name <secret> --url <https>",
+    summary: "Release a sealed secret into ONE command as $ENV — never back in your environment.",
+    flags: [
+      ["--name <secret>", "The sealed secret to release (required)."],
+      ["--as <ENV>", "Env var to inject it as. Auto-detected for known tools (gh→GH_TOKEN, psql→PGPASSWORD…)."],
+      ["--url <https>", "Instead of running a command, do a quick authenticated GET to this URL."],
+    ],
+    examples: ["blindfold use --name gh_token -- gh api user", "blindfold use --name openai_api_key --as OPENAI_API_KEY -- node agent.js"],
+  },
+  {
+    name: "export", group: "🔑 Secrets", usage: "--name <secret> [--as <ENV>]",
+    summary: "CI: release a sealed secret into $GITHUB_ENV for later steps (masked in logs).",
+    flags: [["--name <secret>", "The sealed secret to export (required)."], ["--as <ENV>", "Env var name to write (default: the secret name upper-cased)."]],
+    examples: ["blindfold export --name openai_api_key --as OPENAI_API_KEY"],
+  },
+  {
+    name: "rotate", group: "🔑 Secrets", usage: "--name <secret> [--from-env <ENV>]",
+    summary: "Replace a sealed secret's value; snapshots the old one for rollback (fingerprints only).",
+    flags: [["--name <secret>", "The sealed secret to rotate (required)."], ["--from-env <ENV>", "Read the new value from an env var instead of prompting."]],
+    examples: ["blindfold rotate --name stripe_secret_key"],
+  },
+  {
+    name: "rollback", group: "🔑 Secrets", usage: "--name <secret> [--to <fp|iso-ts>]",
+    summary: "Restore a previous value snapshotted by rotate (most recent by default).",
+    flags: [["--name <secret>", "The sealed secret to roll back (required)."], ["--to <fp|iso-ts>", "Target a specific snapshot by fingerprint or timestamp."]],
+    examples: ["blindfold rollback --name stripe_secret_key"],
+  },
+  { name: "versions", group: "🔑 Secrets", usage: "[--name <secret>]", summary: "List the snapshots available to roll back to (metadata only).", flags: [["--name <secret>", "Limit to one secret."]], examples: ["blindfold versions --name stripe_secret_key"] },
+  {
+    name: "migrate", group: "🔑 Secrets", usage: "[--dry-run] [--keep]",
+    summary: "Seal every secret in .env at once, then remove the plaintext lines (backup kept).",
+    flags: [["--dry-run", "Preview what would be sealed, change nothing."], ["--keep", "Comment out the .env lines instead of deleting them."]],
+    examples: ["blindfold migrate --dry-run", "blindfold migrate"],
+    notes: "Skips T3 creds + config (T3N_API_KEY / DID).",
+  },
+
+  // ── Proxy & serve ────────────────────────────────────────────────────────
+  {
+    name: "proxy", group: "🌐 Proxy & serve", usage: "[--port <n>] [--auth] [--socket [path]]",
+    summary: "Run the local sentinel proxy your agent points at. Substitution happens in the enclave.",
+    flags: [
+      ["--port <n>", "TCP port to listen on (default 8787)."],
+      ["--auth", "Mint a per-session token so only the wrapped agent can use the proxy."],
+      ["--socket [path]", "Bind a 0600 unix-domain socket (only your OS user can connect)."],
+    ],
+    examples: ["blindfold proxy", "blindfold proxy --auth", "blindfold proxy --socket"],
+    notes: "Point your agent at http://127.0.0.1:8787 and send Authorization: Bearer __BLINDFOLD__.",
+  },
+  {
+    name: "attest", group: "🌐 Proxy & serve", usage: "[--expect-rtmr3 <b64>] [--pin] [--json]",
+    summary: "Verify the enclave's TDX attestation (chains to Intel's root CA).",
+    flags: [
+      ["--expect-rtmr3 <b64>", "Assert the code measurement equals this value."],
+      ["--pin", "Record the RTMR3 so seal/proxy auto-verify the enclave first."],
+      ["--json", "Machine-readable output."],
+    ],
+    examples: ["blindfold attest", "blindfold attest --pin"],
+  },
+  { name: "dashboard", group: "🌐 Proxy & serve", usage: "[--port <n>]", summary: "Live HTML dashboard of proxy usage (default :8799).", flags: [["--port <n>", "Port for the dashboard (default 8799)."]], examples: ["blindfold dashboard"] },
+  { name: "stats", group: "🌐 Proxy & serve", usage: "", summary: "CLI summary of proxy usage. `stats:clear` wipes the log.", examples: ["blindfold stats", "blindfold stats:clear"] },
+
+  // ── Team & sharing ───────────────────────────────────────────────────────
+  {
+    name: "grant", group: "👥 Team & sharing", usage: "--host <host>[,<host2>...]",
+    summary: "Allow the enclave to reach an API's server. Do this once per API before the proxy can call it — e.g. allow api.openai.com so a sealed OpenAI key can be used.",
+    flags: [["--host <host,...>", "The API hostname(s) to allow, comma-separated. Each grant adds to the list."]],
+    examples: ["blindfold grant --host api.openai.com", "blindfold grant --host api.github.com,api.stripe.com"],
+    notes: "Why it's needed: the enclave refuses to call any host you haven't allowed (deny-by-default). Grant the host of each API whose key you've sealed.",
+  },
+  {
+    name: "share", group: "👥 Team & sharing", usage: "--to <agent-did> --host <host>[,...]",
+    summary: "Let a teammate use your sealed key for an API — they can make calls but never see the key itself.",
+    flags: [["--to <agent-did>", "The teammate's agent DID (their Terminal 3 identity)."], ["--host <host,...>", "Which API hosts they're allowed to reach through your enclave."]],
+    examples: ["blindfold share --to did:t3n:abc… --host api.openai.com"],
+  },
+  { name: "revoke", group: "👥 Team & sharing", usage: "--to <agent-did>", summary: "Take back a teammate's access you granted with `share` — immediate and complete.", flags: [["--to <agent-did>", "The teammate's agent DID to cut off."]], examples: ["blindfold revoke --to did:t3n:abc…"] },
+
+  // ── Enclave & admin ──────────────────────────────────────────────────────
+  { name: "publish", group: "📦 Enclave & admin", usage: "[--wasm <path>]", summary: "Publish the Rust→WASM contract to your tenant (one-time).", flags: [["--wasm <path>", "Path to blindfold_proxy.wasm (defaults to the bundled build)."]], examples: ["blindfold publish"] },
+  { name: "status", group: "📦 Enclave & admin", usage: "", summary: "One-glance overview: mode, tenant health, and the list of sealed secrets.", examples: ["blindfold status"] },
+  { name: "sealed", group: "📦 Enclave & admin", usage: "", summary: "List sealed keys — metadata only (name, byte-length, when, where). Never the value.", examples: ["blindfold sealed"] },
+  { name: "audit", group: "📦 Enclave & admin", usage: "", summary: "Verify the ledger hash-chain and reconcile it against the enclave (flags drift/tampering).", examples: ["blindfold audit"] },
+  { name: "compat", group: "📦 Enclave & admin", usage: "[--json]", summary: "Scan this machine for AI agent tools and print the exact env-var swap for each.", flags: [["--json", "Machine-readable output."]], examples: ["blindfold compat"] },
+  { name: "update", group: "📦 Enclave & admin", usage: "[--from <path>]", aliases: ["upgrade"], summary: "Update the global install (from npm, or a local repo with --from).", flags: [["--from <path>", "Build + install from a local repo checkout instead of npm."]], examples: ["blindfold update"] },
+
+  // ── Account ──────────────────────────────────────────────────────────────
+  {
+    name: "login", group: "👤 Account", usage: "[--did <did>] [--key <0x…>] [--env <net>] [--file]",
+    summary: "Store EXISTING Terminal 3 credentials (tenant key → OS keychain).",
+    flags: [
+      ["--did <did>", "Tenant DID (prompts if omitted)."],
+      ["--key <0x…>", "Tenant key (prompts hidden if omitted)."],
+      ["--env <net>", "testnet (default) or production."],
+      ["--file", "Force a 0600 config file instead of the OS keychain."],
+    ],
+    examples: ["blindfold login", "blindfold login --did did:t3n:… --env testnet"],
+  },
+  { name: "logout", group: "👤 Account", usage: "", summary: "Remove stored credentials (keychain entry + config file).", examples: ["blindfold logout"] },
+  { name: "whoami", group: "👤 Account", usage: "", summary: "Show tenant, env, and key source — never the value.", examples: ["blindfold whoami"] },
+
+  // ── Agent skill ──────────────────────────────────────────────────────────
+  {
+    name: "skill", group: "🤖 Agent skill", usage: "install [--global|--cursor|--opencode|--cline|--all]  |  uninstall",
+    summary: "Install the Blindfold agent skill so your coding agent handles secrets safely.",
+    flags: [
+      ["--global", "Install for every Claude Code session on this machine."],
+      ["--cursor / --opencode / --cline", "Install for that agent instead of Claude Code."],
+      ["--all", "Install everywhere at once."],
+    ],
+    examples: ["blindfold skill install", "blindfold skill install --all"],
+  },
+];
+
+/** Look up a command by name or alias. */
+export function findCommand(name: string): CmdDef | undefined {
+  return COMMANDS.find((c) => c.name === name || c.aliases?.includes(name));
+}
+
+/** The grouped overview: `blindfold help`. */
+export function renderMainHelp(): string {
+  const w = termWidth();
+  const out: string[] = [
+    "",
+    bannerBox("🛡️  Blindfold", "Protect your AI agent's API keys with Terminal 3 enclaves. The agent only ever holds a placeholder — the real key is substituted inside the TDX enclave."),
+    "",
+  ];
+
+  const nameW = Math.min(12, COMMANDS.reduce((m, cmd) => Math.max(m, vlen(cmd.name)), 0));
+  const descW = Math.max(16, w - 4 - nameW - 2);
+  const fit = (s: string, max: number): string => (s.length > max ? s.slice(0, Math.max(1, max - 1)) + "…" : s);
+
+  for (const group of GROUP_ORDER) {
+    const cmds = COMMANDS.filter((cmd) => cmd.group === group);
+    const lines: string[] = [];
+    for (const [idx, cmd] of cmds.entries()) {
+      if (idx > 0) lines.push(""); // breathing room between commands
+      const dl = wrapText(cmd.summary, descW);
+      // command name (bright) + summary
+      lines.push(pad(c.bold(c.cyan(cmd.name)), nameW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) lines.push(pad("", nameW) + "  " + (dl[i] ?? ""));
+      // one concrete example — the fastest way to "get" the command
+      const ex = fit(cmd.examples?.[0] ?? `blindfold ${cmd.name}`, descW - 5);
+      lines.push(pad("", nameW) + "  " + c.gray("e.g. ") + c.green(ex));
+    }
+    out.push(boxLines(group, lines));
+    out.push("");
+  }
+
+  out.push(
+    c.bold(c.magenta("▶ Quick start")),
+    `  ${c.green("blindfold signup --email you@x.com")}         ${c.gray("# create a funded testnet tenant")}`,
+    `  ${c.green("blindfold register --name openai_api_key")}   ${c.gray("# seal a key (hidden prompt)")}`,
+    `  ${c.green("blindfold proxy")}                            ${c.gray("# point your agent at http://127.0.0.1:8787")}`,
+    "",
+    `${c.gray("Full flags + more examples for any command:")}  ${c.cyan("blindfold <command> --help")}`,
+    `${c.gray("Docs:")} ${c.cyan("npmjs.com/package/@fiscalmindset/blindfold")}`,
+    "",
+  );
+  return out.join("\n");
+}
+
+/** Detailed help for one command: `blindfold <cmd> --help`. */
+export function renderCommandHelp(name: string): string {
+  const cmd = findCommand(name);
+  if (!cmd) return renderMainHelp();
+  const w = termWidth();
+  const out: string[] = ["", boxLines(`blindfold ${cmd.name}`, wrapText(cmd.summary, w - 4)), ""];
+
+  out.push(rule("Usage"));
+  out.push("  " + c.cyan(`blindfold ${cmd.name}${cmd.usage ? " " + cmd.usage : ""}`));
+  if (cmd.aliases?.length) out.push("  " + c.gray(`alias: ${cmd.aliases.map((a) => "blindfold " + a).join(", ")}`));
+  out.push("");
+
+  if (cmd.flags?.length) {
+    out.push(rule("Flags"));
+    const flagW = Math.min(24, cmd.flags.reduce((m, [f]) => Math.max(m, vlen(f)), 0));
+    const dW = Math.max(16, w - 2 - flagW - 2);
+    for (const [flag, desc] of cmd.flags) {
+      const dl = wrapText(desc, dW);
+      out.push("  " + pad(c.yellow(flag), flagW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) out.push("  " + pad("", flagW) + "  " + c.gray(dl[i] ?? ""));
+    }
+    out.push("");
+  }
+
+  if (cmd.examples?.length) {
+    out.push(rule("Examples"));
+    for (const ex of cmd.examples) out.push("  " + c.cyan(ex));
+    out.push("");
+  }
+
+  if (cmd.notes) {
+    out.push(rule("Notes"));
+    for (const nl of wrapText(cmd.notes, w - 2)) out.push("  " + c.gray(nl));
+    out.push("");
+  }
+
+  out.push(c.gray("See all commands: ") + c.cyan("blindfold help"));
+  return out.join("\n");
+}

package/src/tui.ts

@@ -45,9 +45,11 @@ export function vlen(s: string): number {
   }
   return w;
 }
-function padEnd(s: string, w: number): string {
+/** Pad `s` with spaces to display width `w` (ANSI/emoji aware). */
+export function pad(s: string, w: number): string {
   return s + " ".repeat(Math.max(0, w - vlen(s)));
 }
+const padEnd = pad;
 
 /** Word-wrap `text` to `width` columns (ANSI-aware). */
 export function wrapText(text: string, width: number): string[] {
@@ -113,6 +115,31 @@ export function commandBox(title: string, rows: Array<[string, string]>): string
   return out.join("\n");
 }
 
+/**
+ * Wrap pre-rendered content lines in a titled rounded box, padding each line to
+ * the inner width so the right border stays aligned. `title` is embedded in the
+ * top border. Content lines may already contain ANSI color.
+ */
+export function boxLines(title: string, lines: string[]): string {
+  const w = termWidth();
+  const inner = w - 4;
+  const prefix = B.tl + B.h + " ";
+  const fill = Math.max(0, w - vlen(prefix) - vlen(title) - 2);
+  const out: string[] = [dim(prefix) + c.bold(title) + dim(" " + B.h.repeat(fill) + B.tr)];
+  for (const l of lines) out.push(dim(B.v) + " " + pad(l, inner) + " " + dim(B.v));
+  out.push(dim(B.bl + B.h.repeat(w - 2) + B.br));
+  return out.join("\n");
+}
+
+/** A plain full-width rule with an optional bold label: "── Label ─────". */
+export function rule(label = ""): string {
+  const w = termWidth();
+  if (!label) return dim(B.h.repeat(w));
+  const left = B.h + B.h + " ";
+  const fill = Math.max(0, w - vlen(left) - vlen(label) - 1);
+  return dim(left) + c.bold(label) + dim(" " + B.h.repeat(fill));
+}
+
 /** Nearest command by edit distance, for "did you mean" suggestions. */
 export function nearest(input: string, candidates: string[]): string | null {
   let best: string | null = null;