@fiscalmindset/blindfold 0.4.0 → 0.4.2

package/assets/SKILL.md

@@ -14,11 +14,12 @@ You're working in (or with) Blindfold — a Terminal 3 TDX-enclave wrapper that
 - User asks about `.env`, sealing, vaulting, or "where do I put my key".
 - You're about to write code that would read `process.env.SOME_PROVIDER_KEY` for an outbound call.
 - User says "use Blindfold" or "seal it" or "make this safe".
+- User has no Terminal 3 tenant yet ("how do I start", "I don't have an account/DID", `doctor` shows creds MISSING) → point them at self-serve `blindfold signup` (see below).
 
 ## The four rules (mirror of `usage_by_claude.md` §3)
 
-1. **R1 — no-paste-into-chat.** If a new secret needs sealing, *propose* the command (`npm run blindfold -- register --name <KV_KEY>`) for the user to run in their own terminal. Do NOT ask them to paste the value into chat. Only use `printf 'VALUE' | ...` from chat as a fallback, and only after the user explicitly says "go ahead from here".
-2. **R2 — verify by fingerprint, never by value.** To check what's sealed: `npm run blindfold -- sealed`. To check what's in `.env`: `npm run env:fingerprint`. To check a specific sealed key matches an expected value: `npx tsx scripts/test-v5-release.ts <secret_name>` (prints `first3…last2 (N bytes)`, never plaintext). Ask the user to paste the *output* of those commands — that's safe.
+1. **R1 — no-paste-into-chat.** If a new secret needs sealing, *propose* the command (`blindfold register --name <KV_KEY>`) for the user to run in their own terminal. Do NOT ask them to paste the value into chat. Only use `printf 'VALUE' | ...` from chat as a fallback, and only after the user explicitly says "go ahead from here".
+2. **R2 — verify by fingerprint, never by value.** To check what's sealed: `blindfold sealed`. To check what's in `.env`: `npm run env:fingerprint`. To check a specific sealed key matches an expected value: `npx tsx scripts/test-v5-release.ts <secret_name>` (prints `first3…last2 (N bytes)`, never plaintext). Ask the user to paste the *output* of those commands — that's safe.
 3. **R3 — code uses release-broker pattern.** Any code you write that needs a provider key must fetch it from T3 just-in-time via `tenant.contracts.execute("blindfold-proxy", { version: CONTRACT_VERSION, functionName: "release-to-tenant", input: { secret_key: "<name>" } })`, use it inside a `try { … } finally { /* dropped */ }`, and never reference `process.env.<provider>_API_KEY`. Reference templates: `examples/grok-via-blindfold.ts` (HTTPS) and `scripts/smtp-with-blindfold.ts` (non-HTTP).
 4. **R4 — propose `.env` cleanup after every successful seal.** The sealed copy is canonical; the `.env` copy is leak surface. *Exception:* `T3N_API_KEY` itself stays in `.env` — it's the root credential, can't be sealed (chicken-and-egg).
 
@@ -26,19 +27,22 @@ You're working in (or with) Blindfold — a Terminal 3 TDX-enclave wrapper that
 
 | Command | Purpose | Safe to paste output? |
 |---|---|---|
-| `npm run blindfold -- doctor` | mode + cred presence (yes/no) | ✅ |
-| `npm run blindfold -- verify` | T3 round-trip status | ✅ |
-| `npm run blindfold -- login` | store tenant creds in `~/.blindfold` (OS keychain for the key) — works from any dir | ⚠ tell user to run it (prompts for key) |
-| `npm run blindfold -- whoami` | show config path, tenant, env, key source (never the value) | ✅ |
-| `npm run blindfold -- logout` | remove stored creds (keychain + `~/.blindfold/config.json`) | ✅ |
-| `npm run blindfold -- sealed` | sealed-keys ledger (metadata only, LOCAL) | ✅ |
-| `npm run blindfold -- audit` | reconcile ledger against the ENCLAVE — what's actually usable now | ✅ |
-| `npm run blindfold -- status` | one-glance: mode, tenant health, sealed list | ✅ |
+| `blindfold signup --email <addr>` | self-serve: mint a new testnet tenant (key local, email-verified) | ⚠ tell user to run it (prompts for the emailed code) |
+| `blindfold doctor` | mode + cred presence (yes/no) | ✅ |
+| `blindfold verify` | T3 round-trip status | ✅ |
+| `blindfold credit` | tenant token/credit balance | ✅ |
+| `blindfold attest [--pin]` | verify enclave TDX attestation; `--pin` gates seal/proxy on the code measurement | ✅ |
+| `blindfold login` | store tenant creds in `~/.blindfold` (OS keychain for the key) — works from any dir | ⚠ tell user to run it (prompts for key) |
+| `blindfold whoami` | show config path, tenant, env, key source (never the value) | ✅ |
+| `blindfold logout` | remove stored creds (keychain + `~/.blindfold/config.json`) | ✅ |
+| `blindfold sealed` | sealed-keys ledger (metadata only, LOCAL) | ✅ |
+| `blindfold audit` | reconcile ledger against the ENCLAVE — what's actually usable now | ✅ |
+| `blindfold status` | one-glance: mode, tenant health, sealed list | ✅ |
 | `npm run env:fingerprint` | `.env` lines as `KEY = first3…last2 (N bytes)` | ✅ |
 | `npx tsx scripts/test-v5-release.ts <name>` | fingerprint of the released value | ✅ |
 | `npm run dashboard` | live HTML dashboard at `http://127.0.0.1:8799` | n/a (UI) |
-| `npm run blindfold -- register --name <K>` | interactive seal (no echo) | ⚠ tell user to run in their terminal |
-| `printf 'V' \| npm run blindfold -- register --name <K>` | piped seal (value briefly in this process) | ⚠ only if user already pasted value |
+| `blindfold register --name <K>` | interactive seal (no echo) | ⚠ tell user to run in their terminal |
+| `printf 'V' \| blindfold register --name <K>` | piped seal (value briefly in this process) | ⚠ only if user already pasted value |
 
 ## Seal once, use forever (no re-seal per session)
 
@@ -51,16 +55,21 @@ To **use** already-sealed keys, a session needs three persistent things (all
 survive across sessions — none require re-sealing):
 
 1. **Tenant creds** — `T3N_API_KEY` + `DID`. These authenticate to the enclave
-   and are what release/proxy require. Two ways to provide them:
+   and are what release/proxy require. Ways to provide them:
+   - **`blindfold signup --email you@x.com`** (self-serve, the fastest start):
+     mints a brand-new Terminal 3 **testnet** tenant with no manual token claim —
+     generates the tenant key locally (→ OS keychain, never printed), verifies the
+     email by an emailed code, self-admits, and mints welcome credits. One email
+     binds to one tenant. Use this when the user has no tenant yet.
    - **Repo `.env`** (dev). Exception to R4: they stay in `.env`; see R4.
-   - **`blindfold login`** (v0.2+, product path): stores DID + settings in
+   - **`blindfold login`** (v0.2+, product path, for an EXISTING tenant): stores DID + settings in
      `~/.blindfold/config.json` and the tenant key in the **OS keychain** (v0.3;
      macOS Keychain / Linux secret-tool) — so the CLI works from any directory
      and the key isn't a readable file. Precedence: `process.env` > repo `.env` >
      `~/.blindfold`. State (ledger/usage/egress) also lives in `~/.blindfold`.
 2. **Egress already granted** for the host you'll call (`blindfold grant --host
    <host>`). The grant is per-tenant and persistent.
-3. **The proxy running** if using the HTTP path: `npm run blindfold -- proxy`
+3. **The proxy running** if using the HTTP path: `blindfold proxy`
    (listens on `127.0.0.1:8787`). Point the tool at it with base URL
    `http://127.0.0.1:8787/v1` and key `__BLINDFOLD__`. (Code paths use the
    release-broker instead — see R3.) On a shared machine, run `proxy --auth`:
@@ -76,6 +85,24 @@ re-sealing.
 
 ## What to do, by scenario
 
+### "I'm new / I don't have a Terminal 3 tenant yet" (onboarding)
+
+Blindfold is published on npm and onboarding is self-serve — no manual token claim.
+Propose (the user runs it in their own terminal):
+
+```bash
+npm i -g @fiscalmindset/blindfold
+blindfold signup --email you@example.com
+```
+
+`signup` generates the tenant key locally (→ OS keychain, never printed),
+verifies the email by an emailed code, self-admits a funded **testnet** tenant,
+and mints welcome credits. Then confirm with `blindfold doctor` (should show the
+tenant `active`) and `blindfold credit` (token balance). After that they can
+`register` and `use` keys. Notes: testnet-only; one email = one tenant (Gmail
+`+aliases` give fresh identities); if the email is already registered, use
+`blindfold login` with that tenant's key instead.
+
 ### "I want to seal my Stripe key" (or any new credential)
 
 **Don't ask for the value.** Respond with:
@@ -83,10 +110,10 @@ re-sealing.
 > In your own terminal, run:
 >
 > ```bash
-> npm run blindfold -- register --name stripe_api_key
+> blindfold register --name stripe_api_key
 > ```
 >
-> It'll prompt for the value with input hidden (no echo, no shell history). Paste your `sk_live_…` there, press Enter. Once done, paste me the output of `npm run blindfold -- sealed` so I can verify it landed in the right place.
+> It'll prompt for the value with input hidden (no echo, no shell history). Paste your `sk_live_…` there, press Enter. Once done, paste me the output of `blindfold sealed` so I can verify it landed in the right place.
 
 ### "Seal / use a webhook URL (Discord, Slack, …)"
 
@@ -126,7 +153,7 @@ end**; only the final `register` (plaintext) is handed back to the user.
    ```
 2. Rebuild (`npm run build` in `packages/blindfold`) so `dist/` picks up the entry.
 3. Hand back the two one-time human steps: seal the key —
-   `npm run blindfold -- register --name notion_api_key` (in their terminal, R1) —
+   `blindfold register --name notion_api_key` (in their terminal, R1) —
    and grant egress: `blindfold grant --host api.notion.com`.
 4. The agent then calls `http://127.0.0.1:8787/notion/...` with
    `Authorization: Bearer __BLINDFOLD__`; the enclave swaps in the sealed key.
@@ -139,7 +166,7 @@ auth scheme none of the four cover — otherwise this stays a TypeScript-only ch
 It's in our chat context now (can't undo). Reduce future surface:
 
 ```bash
-printf 'sk-...' | npx tsx packages/blindfold/bin/blindfold.ts register --name openai_api_key
+printf 'sk-...' | blindfold register --name openai_api_key
 ```
 
 Then propose deleting any `.env` copy. Note in your response that the chat-context exposure already happened and you can't retroactively fix it — only forward-protect.
@@ -174,9 +201,9 @@ Ask the user to paste that output. You get key *names* + lengths + first/last fe
 Run these in order, asking the user to paste each output:
 
 ```bash
-npm run blindfold -- doctor      # config sanity
-npm run blindfold -- verify      # T3 reachability
-npm run blindfold -- sealed      # is the key there?
+blindfold doctor      # config sanity
+blindfold verify      # T3 reachability
+blindfold sealed      # is the key there?
 ```
 
 Cross-reference any errors with `vicky.md` Q6 (keyword-indexed error table).

package/bin/blindfold.ts

@@ -4,7 +4,9 @@
  * helpers in ./cli-shared.ts. Every action prints what it did, never a secret.
  */
 import { type Argv, parseArgv } from "./cli-shared.ts";
-import { c, head } from "../src/color.ts";
+import { c, bad } from "../src/color.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";
@@ -34,54 +36,35 @@ 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 printHelp();
+  else printUnknown(cmd);
 }
 
-function printHelp(): void {
-  console.log(`${head("🛡️  Blindfold")} ${c.gray("— protect your AI agent's API keys with Terminal 3 enclaves.")}
-
-${c.bold("Commands:")}
-  signup   [--email <you@x.com>]                    Self-serve: create a Terminal 3 testnet tenant from scratch. Generates a key locally, verifies your email by code, and mints welcome credits — no manual provisioning. Then run doctor + register.
-  init     [--seed KV:ENV]... [--start]             One-command zero-knowledge setup. Walks through .env, build, auth, publish, seed; can auto-launch the proxy.
-  verify                                            Handshake + auth against T3 (smoke test).
-  compat   [--json]                                 Scan this machine for AI agent tools/SDKs and print the exact env-var swap for each.
-  register --name <KV_KEY> [--from-env <ENV_VAR>]  Seal a secret into the enclave (one-time). With --from-env: reads process.env. Without: prompts the terminal with no echo (preferred — never touches disk/history). Also accepts piped stdin.
-  use      --name <secret> [--as <ENV>] -- <cmd>   USE a sealed secret: release it and run <cmd> with it injected as $ENV for that command only — never back in your env. --as is auto-detected for known tools (gh→GH_TOKEN, psql→PGPASSWORD, …). Or  --url <https>  for a quick auth check.
-  rotate   --name <secret> [--from-env <ENV_VAR>]  Replace a sealed secret's value (snapshots the old value for rollback; shows before/after fingerprints, never the value).
-  export   --name <secret> [--as <ENV_VAR>]         CI-only: release a sealed secret into $GITHUB_ENV for later steps (masked in logs). Used by the Blindfold GitHub Action.
-  rollback --name <secret> [--to <fp|iso-ts>]      Restore a previous value snapshotted by rotate (most recent by default).
-  versions [--name <secret>]                        List the snapshots available to roll back to (metadata only).
-  migrate  [--dry-run] [--keep]                     Seal EVERY secret in your .env in one shot, then remove the plaintext lines (backup kept). --dry-run previews; --keep comments lines instead of deleting. Skips T3 creds + config.
-  status                                             One-glance overview: mode, tenant health, and the list of sealed secrets.
-  sealed                                             List sealed keys — metadata only (name, byte-length, when, where). Never the value.
-  audit                                              Verify the ledger's tamper-evident hash-chain AND reconcile it against the enclave (the source of truth) — flags drift/missing/tampering.
-  proxy    [--port 8787] [--auth] [--socket [path]] Run the local OpenAI-shaped proxy. --auth mints a per-session token; --socket binds a 0600 unix socket (only your OS user can connect).
-  attest   [--expect-rtmr3 <b64>] [--pin] [--json]  Verify the enclave's TDX attestation (chains to Intel's root CA). --pin records the RTMR3 so seal/proxy auto-verify it first.
-  publish  [--wasm path/to/blindfold_proxy.wasm]   Publish the Rust→WASM contract (one-time).
-  grant    --host <host>[,<host2>...]              Authorize the contract to call these hosts (required before the proxy / in-enclave path can reach them). E.g. --host api.openai.com
-  share    --to <agent-did> --host <host>[,...]    Let a teammate's agent USE your sealed keys for those hosts via the enclave — they never receive the plaintext (forward only, least privilege).
-  revoke   --to <agent-did>                         Remove a teammate's access. Immediate and complete — nobody holds a raw key copy.
-
-  skill    install [--global|--cursor|--opencode|--cline|--all]   Install the Blindfold agent skill so your coding agent handles secrets safely. Default: this project.
-  skill    uninstall                                Remove all installed skill files.
-
-  dashboard [--port 8799]                           Live HTML dashboard of proxy usage.
-  stats                                             CLI summary of proxy usage.
-  stats:clear                                       Wipe the usage log.
-  doctor                                            Show current mode + config.
-  credit   [--json]                                 Show the tenant's Terminal 3 token/credit balance (no credit cost).
-  update   [--from <path>]                           Update the global blindfold (from npm, or a local repo with --from).
-
-The friendliest path is just:  blindfold init
-
-Quick start:
-  1) ./scripts/build-contract.sh             # build the Rust contract (REAL mode only)
-  2) blindfold publish                        # register the contract on T3
-  3) blindfold register --name openai_api_key --from-env OPENAI_API_KEY
-  4) blindfold proxy                          # then point your agent at it
-`);
+/** Unknown command: a concise error with a "did you mean" suggestion — not the
+ *  full help dump (which used to appear on any typo). */
+function printUnknown(cmd: string): void {
+  const all = [...Object.keys(ROUTES), "help"];
+  const guess = nearest(cmd, all);
+  console.error(
+    bad(`✖ Unknown command: ${cmd}`) +
+    (guess ? `  ${c.gray("— did you mean")} ${c.cyan(guess)}${c.gray("?")}` : ""),
+  );
+  console.error(c.gray("  Run ") + c.cyan("blindfold help") + c.gray(" to see all commands."));
+  process.exit(1);
 }
 
 main().catch((e) => {

package/dist/cli.mjs

@@ -1374,6 +1374,364 @@ function die(msg) {
   process.exit(2);
 }
 
+// src/tui.ts
+function termWidth() {
+  const cols = process.stdout.columns;
+  if (typeof cols === "number" && cols >= 40) return Math.min(cols, 100);
+  const env = Number(process.env.COLUMNS);
+  if (Number.isFinite(env) && env >= 40) return Math.min(env, 100);
+  return 80;
+}
+var ANSI = /\x1b\[[0-9;]*m/g;
+function isWide(cp) {
+  return cp >= 4352 && cp <= 4447 || cp >= 9728 && cp <= 10175 || cp >= 11008 && cp <= 11263 || cp >= 11904 && cp <= 42191 || cp >= 44032 && cp <= 55203 || cp >= 63744 && cp <= 64255 || cp >= 65072 && cp <= 65103 || cp >= 65280 && cp <= 65376 || cp >= 65504 && cp <= 65510 || cp >= 126976 && cp <= 129791;
+}
+function vlen(s) {
+  let w = 0;
+  for (const ch of s.replace(ANSI, "")) {
+    const cp = ch.codePointAt(0) ?? 0;
+    if (cp === 8205 || cp >= 65024 && cp <= 65039 || cp >= 768 && cp <= 879) continue;
+    w += isWide(cp) ? 2 : 1;
+  }
+  return 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 = [];
+  for (const para of text.split("\n")) {
+    const words = para.split(/\s+/).filter(Boolean);
+    let cur = "";
+    for (const w of words) {
+      if (cur === "") cur = w;
+      else if (vlen(cur) + 1 + vlen(w) <= width) cur += " " + w;
+      else {
+        out.push(cur);
+        cur = w;
+      }
+    }
+    out.push(cur);
+  }
+  return out.length ? out : [""];
+}
+var B = { tl: "\u256D", tr: "\u256E", bl: "\u2570", br: "\u256F", h: "\u2500", v: "\u2502" };
+var dim = (s) => c.gray(s);
+function bannerBox(title, subtitle) {
+  const w = termWidth();
+  const inner = w - 4;
+  const top = dim(B.tl + B.h.repeat(w - 2) + B.tr);
+  const bot = dim(B.bl + B.h.repeat(w - 2) + B.br);
+  const row = (s) => dim(B.v) + " " + padEnd(s, inner) + " " + dim(B.v);
+  const lines = [top, row(c.bold(title))];
+  for (const sl of wrapText(subtitle, inner)) lines.push(row(dim(sl)));
+  lines.push(bot);
+  return lines.join("\n");
+}
+function boxLines(title, lines) {
+  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 = [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");
+}
+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;
+  for (const cand of candidates) {
+    const d = editDistance(input, cand);
+    if (d < bestD) {
+      bestD = d;
+      best = cand;
+    }
+  }
+  return bestD <= Math.max(2, Math.floor(input.length / 3)) ? best : null;
+}
+function editDistance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  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: "Authorize the contract to call these hosts (required before proxy/in-enclave can reach them).",
+    flags: [["--host <host,...>", "Comma-separated egress hosts to allow (additive)."]],
+    examples: ["blindfold grant --host api.openai.com", "blindfold grant --host api.github.com,api.stripe.com"]
+  },
+  {
+    name: "share",
+    group: "\u{1F465} Team & sharing",
+    usage: "--to <agent-did> --host <host>[,...]",
+    summary: "Let a teammate's agent USE your sealed keys for a host \u2014 forward only, never the plaintext.",
+    flags: [["--to <agent-did>", "The teammate's agent DID to authorize."], ["--host <host,...>", "Hosts they may reach through the enclave."]],
+    examples: ["blindfold share --to did:t3n:\u2026 --host api.openai.com"]
+  },
+  { name: "revoke", group: "\u{1F465} Team & sharing", usage: "--to <agent-did>", summary: "Remove a teammate's access \u2014 immediate and complete.", flags: [["--to <agent-did>", "The teammate's agent DID to revoke."]], examples: ["blindfold revoke --to did:t3n:\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);
+  for (const group of GROUP_ORDER) {
+    const cmds = COMMANDS.filter((cmd) => cmd.group === group);
+    const lines = [];
+    for (const cmd of cmds) {
+      const dl = wrapText(cmd.summary, descW);
+      lines.push(pad(c.cyan(cmd.name), nameW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) lines.push(pad("", nameW) + "  " + c.gray(dl[i] ?? ""));
+      if (cmd.usage) {
+        lines.push(pad("", nameW) + "  " + c.gray("\u21B3 blindfold " + cmd.name + " " + cmd.usage));
+      }
+    }
+    out.push(boxLines(group, lines));
+    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("Details for any command:")} ${c.cyan("blindfold <command> --help")}   ${c.gray("\xB7")}   ${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();
@@ -3368,11 +3726,11 @@ var bold = (s) => colour("1", s);
 var green = (s) => colour("32", s);
 var yellow = (s) => colour("33", s);
 var red = (s) => colour("31", s);
-var dim = (s) => colour("2", s);
+var dim2 = (s) => colour("2", s);
 var cyan = (s) => colour("36", s);
 function header(n, total, title) {
   process.stdout.write(`
-${dim(`[${n}/${total}]`)} ${bold(title)}
+${dim2(`[${n}/${total}]`)} ${bold(title)}
 `);
 }
 function ok2(line) {
@@ -3380,7 +3738,7 @@ function ok2(line) {
 `);
 }
 function info(line) {
-  process.stdout.write(`  ${dim("\xB7")} ${line}
+  process.stdout.write(`  ${dim2("\xB7")} ${line}
 `);
 }
 function warn2(line) {
@@ -3391,7 +3749,7 @@ function fail(line, fixHint) {
   process.stdout.write(`  ${red("\u2716")} ${line}
 `);
   if (fixHint) {
-    for (const ln of fixHint.split("\n")) process.stdout.write(`    ${dim("\u2192")} ${cyan(ln)}
+    for (const ln of fixHint.split("\n")) process.stdout.write(`    ${dim2("\u2192")} ${cyan(ln)}
 `);
   }
 }
@@ -3422,7 +3780,7 @@ async function runInit(opts = {}) {
   const total = 5;
   process.stdout.write(`
 ${bold("\u{1F6E1}\uFE0F  Blindfold \u2014 first-time setup")}
-${dim("This wizard sets up REAL T3 mode end-to-end. Secrets are read from your .env, never typed onto the command line.")}
+${dim2("This wizard sets up REAL T3 mode end-to-end. Secrets are read from your .env, never typed onto the command line.")}
 `);
   header(1, total, "Preflight");
   await ensureEnvOrPrompt(opts);
@@ -3432,7 +3790,7 @@ ${dim("This wizard sets up REAL T3 mode end-to-end. Secrets are read from your .
     fail("Still missing T3N_API_KEY and/or DID after .env walkthrough.", "Open .env, paste the two values, and re-run `npm run setup`.");
     throw new Error("preflight failed");
   }
-  ok2(`T3 ${env.t3Env} \xB7 tenant ${dim(env.did)}`);
+  ok2(`T3 ${env.t3Env} \xB7 tenant ${dim2(env.did)}`);
   const haveSdk = await isSdkInstalled2();
   if (!haveSdk) {
     fail("@terminal3/t3n-sdk is not installed.", "Run: npm install @terminal3/t3n-sdk");
@@ -3544,7 +3902,7 @@ Make sure ${fromEnv} is set in .env (you can delete it after sealing).`);
 ${green(bold("\u2713 All done."))}
 `);
   if (opts.start) {
-    process.stdout.write(`${dim("Starting the proxy now (Ctrl+C to stop) \u2026")}
+    process.stdout.write(`${dim2("Starting the proxy now (Ctrl+C to stop) \u2026")}
 `);
     const proxy = spawn2(process.execPath, [process.argv[1] ?? "", "proxy"], {
       cwd: REPO_ROOT2,
@@ -3553,15 +3911,15 @@ ${green(bold("\u2713 All done."))}
     proxy.on("exit", (code) => process.exit(code ?? 0));
     return;
   }
-  process.stdout.write(`${dim("Next:")}
+  process.stdout.write(`${dim2("Next:")}
 `);
-  process.stdout.write(`  ${cyan("npm run blindfold -- proxy")}        ${dim("# leave this running")}
+  process.stdout.write(`  ${cyan("npm run blindfold -- proxy")}        ${dim2("# leave this running")}
 `);
-  process.stdout.write(`  ${cyan("npm run dashboard")}                 ${dim("# open http://127.0.0.1:8799")}
+  process.stdout.write(`  ${cyan("npm run dashboard")}                 ${dim2("# open http://127.0.0.1:8799")}
 `);
-  process.stdout.write(`  ${dim("Then point your agent at:")} ${cyan("OPENAI_BASE_URL=http://127.0.0.1:8787/v1  OPENAI_API_KEY=__BLINDFOLD__")}
+  process.stdout.write(`  ${dim2("Then point your agent at:")} ${cyan("OPENAI_BASE_URL=http://127.0.0.1:8787/v1  OPENAI_API_KEY=__BLINDFOLD__")}
 `);
-  process.stdout.write(`${dim("Or re-run with")} ${cyan("--start")} ${dim("to launch the proxy automatically.")}
+  process.stdout.write(`${dim2("Or re-run with")} ${cyan("--start")} ${dim2("to launch the proxy automatically.")}
 `);
 }
 async function ensureEnvOrPrompt(opts) {
@@ -3673,7 +4031,7 @@ ${bold("\u{1F6E1}\uFE0F  Blindfold \u2014 verify")}
     warn2("MOCK mode \u2014 there's nothing to verify on the T3 side. Set T3N_API_KEY + DID.");
     return;
   }
-  process.stdout.write(`  ${dim("\xB7")} attempting handshake + authenticate against T3 \u2026
+  process.stdout.write(`  ${dim2("\xB7")} attempting handshake + authenticate against T3 \u2026
 `);
   try {
     const t3 = await openT3Client(env);
@@ -3701,7 +4059,7 @@ var HERE4 = path11.dirname(fileURLToPath5(import.meta.url));
 var REPO_ROOT3 = path11.resolve(HERE4, "..", "..", "..");
 var colour2 = process.stdout.isTTY ? (c2, s) => `\x1B[${c2}m${s}\x1B[0m` : (_, s) => s;
 var bold2 = (s) => colour2("1", s);
-var dim2 = (s) => colour2("2", s);
+var dim3 = (s) => colour2("2", s);
 var green2 = (s) => colour2("32", s);
 var yellow2 = (s) => colour2("33", s);
 var red2 = (s) => colour2("31", s);
@@ -3830,14 +4188,14 @@ async function runCompat(opts = {}) {
   }
   process.stdout.write(`
 ${bold2("\u{1F6E1}\uFE0F  Blindfold \u2014 compatibility scan")}
-${dim2("Probing local box for agent tools and SDKs Blindfold can protect.")}
+${dim3("Probing local box for agent tools and SDKs Blindfold can protect.")}
 
 `);
   const detected = results.filter((r) => r.detection.detected);
   const notFound = results.filter((r) => !r.detection.detected);
   process.stdout.write(`${bold2(`Detected (${detected.length}):`)}
 `);
-  if (detected.length === 0) process.stdout.write(`  ${dim2("(none \u2014 install one of the tools below, or just use the OpenAI/Anthropic SDK in your own code)")}
+  if (detected.length === 0) process.stdout.write(`  ${dim3("(none \u2014 install one of the tools below, or just use the OpenAI/Anthropic SDK in your own code)")}
 `);
   for (const r of detected) {
     renderTool(r.tool, r.detection, true);
@@ -3849,24 +4207,24 @@ ${bold2(`Not found on this machine (${notFound.length}):`)}
     renderTool(r.tool, r.detection, false);
   }
   process.stdout.write(`
-${dim2("For a longer-form compatibility writeup see docs/05-compatibility.md.")}
+${dim3("For a longer-form compatibility writeup see docs/05-compatibility.md.")}
 `);
 }
 function renderTool(tool, detection, detected) {
-  const mark = !detected ? dim2("\xB7") : tool.applies === "applies" ? green2("\u2713") : tool.applies === "depends" ? yellow2("?") : tool.applies === "needs-base-url" ? yellow2("!") : red2("\u2716");
-  const status = !detected ? dim2("(not installed)") : tool.applies === "applies" ? green2("Blindfold protects this") : tool.applies === "depends" ? yellow2("Depends on how you authenticate") : tool.applies === "needs-base-url" ? yellow2("No base-URL hook \u2014 needs upstream support") : red2("Doesn't apply (no user-supplied key)");
-  process.stdout.write(`  ${mark} ${bold2(tool.name)}  ${dim2("\xB7")}  ${status}
+  const mark = !detected ? dim3("\xB7") : tool.applies === "applies" ? green2("\u2713") : tool.applies === "depends" ? yellow2("?") : tool.applies === "needs-base-url" ? yellow2("!") : red2("\u2716");
+  const status = !detected ? dim3("(not installed)") : tool.applies === "applies" ? green2("Blindfold protects this") : tool.applies === "depends" ? yellow2("Depends on how you authenticate") : tool.applies === "needs-base-url" ? yellow2("No base-URL hook \u2014 needs upstream support") : red2("Doesn't apply (no user-supplied key)");
+  process.stdout.write(`  ${mark} ${bold2(tool.name)}  ${dim3("\xB7")}  ${status}
 `);
-  if (detected && detection.detail) process.stdout.write(`    ${dim2("at " + detection.detail)}
+  if (detected && detection.detail) process.stdout.write(`    ${dim3("at " + detection.detail)}
 `);
   if (detected && tool.recipe.env) {
     const envLine = Object.entries(tool.recipe.env).map(([k, v]) => `${k}=${v}`).join("  ");
     process.stdout.write(`    ${cyan2(envLine)}
 `);
   }
-  if (detected && tool.recipe.note) process.stdout.write(`    ${dim2(tool.recipe.note)}
+  if (detected && tool.recipe.note) process.stdout.write(`    ${dim3(tool.recipe.note)}
 `);
-  if (detected && tool.explanation) process.stdout.write(`    ${dim2(tool.explanation)}
+  if (detected && tool.explanation) process.stdout.write(`    ${dim3(tool.explanation)}
 `);
 }
 
@@ -4263,53 +4621,27 @@ 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 printHelp();
+  else printUnknown(cmd);
 }
-function printHelp() {
-  console.log(`${head("\u{1F6E1}\uFE0F  Blindfold")} ${c.gray("\u2014 protect your AI agent's API keys with Terminal 3 enclaves.")}
-
-${c.bold("Commands:")}
-  signup   [--email <you@x.com>]                    Self-serve: create a Terminal 3 testnet tenant from scratch. Generates a key locally, verifies your email by code, and mints welcome credits \u2014 no manual provisioning. Then run doctor + register.
-  init     [--seed KV:ENV]... [--start]             One-command zero-knowledge setup. Walks through .env, build, auth, publish, seed; can auto-launch the proxy.
-  verify                                            Handshake + auth against T3 (smoke test).
-  compat   [--json]                                 Scan this machine for AI agent tools/SDKs and print the exact env-var swap for each.
-  register --name <KV_KEY> [--from-env <ENV_VAR>]  Seal a secret into the enclave (one-time). With --from-env: reads process.env. Without: prompts the terminal with no echo (preferred \u2014 never touches disk/history). Also accepts piped stdin.
-  use      --name <secret> [--as <ENV>] -- <cmd>   USE a sealed secret: release it and run <cmd> with it injected as $ENV for that command only \u2014 never back in your env. --as is auto-detected for known tools (gh\u2192GH_TOKEN, psql\u2192PGPASSWORD, \u2026). Or  --url <https>  for a quick auth check.
-  rotate   --name <secret> [--from-env <ENV_VAR>]  Replace a sealed secret's value (snapshots the old value for rollback; shows before/after fingerprints, never the value).
-  export   --name <secret> [--as <ENV_VAR>]         CI-only: release a sealed secret into $GITHUB_ENV for later steps (masked in logs). Used by the Blindfold GitHub Action.
-  rollback --name <secret> [--to <fp|iso-ts>]      Restore a previous value snapshotted by rotate (most recent by default).
-  versions [--name <secret>]                        List the snapshots available to roll back to (metadata only).
-  migrate  [--dry-run] [--keep]                     Seal EVERY secret in your .env in one shot, then remove the plaintext lines (backup kept). --dry-run previews; --keep comments lines instead of deleting. Skips T3 creds + config.
-  status                                             One-glance overview: mode, tenant health, and the list of sealed secrets.
-  sealed                                             List sealed keys \u2014 metadata only (name, byte-length, when, where). Never the value.
-  audit                                              Verify the ledger's tamper-evident hash-chain AND reconcile it against the enclave (the source of truth) \u2014 flags drift/missing/tampering.
-  proxy    [--port 8787] [--auth] [--socket [path]] Run the local OpenAI-shaped proxy. --auth mints a per-session token; --socket binds a 0600 unix socket (only your OS user can connect).
-  attest   [--expect-rtmr3 <b64>] [--pin] [--json]  Verify the enclave's TDX attestation (chains to Intel's root CA). --pin records the RTMR3 so seal/proxy auto-verify it first.
-  publish  [--wasm path/to/blindfold_proxy.wasm]   Publish the Rust\u2192WASM contract (one-time).
-  grant    --host <host>[,<host2>...]              Authorize the contract to call these hosts (required before the proxy / in-enclave path can reach them). E.g. --host api.openai.com
-  share    --to <agent-did> --host <host>[,...]    Let a teammate's agent USE your sealed keys for those hosts via the enclave \u2014 they never receive the plaintext (forward only, least privilege).
-  revoke   --to <agent-did>                         Remove a teammate's access. Immediate and complete \u2014 nobody holds a raw key copy.
-
-  skill    install [--global|--cursor|--opencode|--cline|--all]   Install the Blindfold agent skill so your coding agent handles secrets safely. Default: this project.
-  skill    uninstall                                Remove all installed skill files.
-
-  dashboard [--port 8799]                           Live HTML dashboard of proxy usage.
-  stats                                             CLI summary of proxy usage.
-  stats:clear                                       Wipe the usage log.
-  doctor                                            Show current mode + config.
-  credit   [--json]                                 Show the tenant's Terminal 3 token/credit balance (no credit cost).
-  update   [--from <path>]                           Update the global blindfold (from npm, or a local repo with --from).
-
-The friendliest path is just:  blindfold init
-
-Quick start:
-  1) ./scripts/build-contract.sh             # build the Rust contract (REAL mode only)
-  2) blindfold publish                        # register the contract on T3
-  3) blindfold register --name openai_api_key --from-env OPENAI_API_KEY
-  4) blindfold proxy                          # then point your agent at it
-`);
+function printUnknown(cmd) {
+  const all = [...Object.keys(ROUTES), "help"];
+  const guess = nearest(cmd, all);
+  console.error(
+    bad(`\u2716 Unknown command: ${cmd}`) + (guess ? `  ${c.gray("\u2014 did you mean")} ${c.cyan(guess)}${c.gray("?")}` : "")
+  );
+  console.error(c.gray("  Run ") + c.cyan("blindfold help") + c.gray(" to see all commands."));
+  process.exit(1);
 }
 main().catch((e) => {
   console.error("\u2716", e.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiscalmindset/blindfold",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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,272 @@
+/**
+ * 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: "Authorize the contract to call these hosts (required before proxy/in-enclave can reach them).",
+    flags: [["--host <host,...>", "Comma-separated egress hosts to allow (additive)."]],
+    examples: ["blindfold grant --host api.openai.com", "blindfold grant --host api.github.com,api.stripe.com"],
+  },
+  {
+    name: "share", group: "👥 Team & sharing", usage: "--to <agent-did> --host <host>[,...]",
+    summary: "Let a teammate's agent USE your sealed keys for a host — forward only, never the plaintext.",
+    flags: [["--to <agent-did>", "The teammate's agent DID to authorize."], ["--host <host,...>", "Hosts they may reach through the enclave."]],
+    examples: ["blindfold share --to did:t3n:… --host api.openai.com"],
+  },
+  { name: "revoke", group: "👥 Team & sharing", usage: "--to <agent-did>", summary: "Remove a teammate's access — immediate and complete.", flags: [["--to <agent-did>", "The teammate's agent DID to revoke."]], examples: ["blindfold revoke --to did:t3n:…"] },
+
+  // ── 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);
+
+  for (const group of GROUP_ORDER) {
+    const cmds = COMMANDS.filter((cmd) => cmd.group === group);
+    const lines: string[] = [];
+    for (const cmd of cmds) {
+      const dl = wrapText(cmd.summary, descW);
+      lines.push(pad(c.cyan(cmd.name), nameW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) lines.push(pad("", nameW) + "  " + c.gray(dl[i] ?? ""));
+      if (cmd.usage) {
+        lines.push(pad("", nameW) + "  " + c.gray("↳ blindfold " + cmd.name + " " + cmd.usage));
+      }
+    }
+    out.push(boxLines(group, lines));
+    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("Details for any command:")} ${c.cyan("blindfold <command> --help")}   ${c.gray("·")}   ${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

@@ -0,0 +1,164 @@
+/**
+ * Tiny, dependency-free terminal UI primitives: responsive width, ANSI-aware
+ * wrapping, rounded boxes, and a two-column command table. Used to render a
+ * structured `blindfold help` that reflows to the terminal.
+ */
+import { c } from "./color.ts";
+
+/** Terminal width, clamped to a readable range. */
+export function termWidth(): number {
+  const cols = process.stdout.columns;
+  if (typeof cols === "number" && cols >= 40) return Math.min(cols, 100);
+  const env = Number(process.env.COLUMNS);
+  if (Number.isFinite(env) && env >= 40) return Math.min(env, 100);
+  return 80;
+}
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+/** True for code points most terminals render two columns wide (CJK, emoji). */
+function isWide(cp: number): boolean {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) ||
+    (cp >= 0x2600 && cp <= 0x27bf) ||
+    (cp >= 0x2b00 && cp <= 0x2bff) ||
+    (cp >= 0x2e80 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) ||
+    (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe4f) ||
+    (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f000 && cp <= 0x1faff)
+  );
+}
+
+/**
+ * Display width of a string (ANSI-stripped), accounting for double-width CJK/
+ * emoji and zero-width joiners/variation-selectors — so box borders line up.
+ */
+export function vlen(s: string): number {
+  let w = 0;
+  for (const ch of s.replace(ANSI, "")) {
+    const cp = ch.codePointAt(0) ?? 0;
+    if (cp === 0x200d || (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0x300 && cp <= 0x36f)) continue; // zero-width
+    w += isWide(cp) ? 2 : 1;
+  }
+  return w;
+}
+/** 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[] {
+  if (width <= 4) return [text];
+  const out: string[] = [];
+  for (const para of text.split("\n")) {
+    const words = para.split(/\s+/).filter(Boolean);
+    let cur = "";
+    for (const w of words) {
+      if (cur === "") cur = w;
+      else if (vlen(cur) + 1 + vlen(w) <= width) cur += " " + w;
+      else { out.push(cur); cur = w; }
+    }
+    out.push(cur);
+  }
+  return out.length ? out : [""];
+}
+
+// Rounded box-drawing set.
+const B = { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│" };
+const dim = (s: string): string => c.gray(s);
+
+/** A banner box with a bold title and a dim subtitle, sized to the terminal. */
+export function bannerBox(title: string, subtitle: string): string {
+  const w = termWidth();
+  const inner = w - 4;
+  const top = dim(B.tl + B.h.repeat(w - 2) + B.tr);
+  const bot = dim(B.bl + B.h.repeat(w - 2) + B.br);
+  const row = (s: string): string => dim(B.v) + " " + padEnd(s, inner) + " " + dim(B.v);
+  const lines = [top, row(c.bold(title))];
+  for (const sl of wrapText(subtitle, inner)) lines.push(row(dim(sl)));
+  lines.push(bot);
+  return lines.join("\n");
+}
+
+/**
+ * A titled box holding a two-column command table: the command in a fixed left
+ * column (cyan), the description wrapped in the remaining width. Right border
+ * stays aligned regardless of wrapping.
+ */
+export function commandBox(title: string, rows: Array<[string, string]>): string {
+  const w = termWidth();
+  const inner = w - 4; // inside "│ " … " │"
+  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);
+
+  // Title embedded in the top border: ╭─ Title ─────────╮ (border dim, title bold)
+  const prefix = B.tl + B.h + " ";
+  const fill = Math.max(0, w - vlen(prefix) - vlen(title) - 1 /* space */ - 1 /* tr */);
+  const out: string[] = [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));
+    }
+  }
+  out.push(dim(B.bl + B.h.repeat(w - 2) + B.br));
+  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;
+  let bestD = Infinity;
+  for (const cand of candidates) {
+    const d = editDistance(input, cand);
+    if (d < bestD) { bestD = d; best = cand; }
+  }
+  return bestD <= Math.max(2, Math.floor(input.length / 3)) ? best : null;
+}
+
+function editDistance(a: string, b: string): number {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0]![j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(dp[i - 1]![j]! + 1, dp[i]![j - 1]! + 1, dp[i - 1]![j - 1]! + cost);
+    }
+  }
+  return dp[a.length]![b.length]!;
+}