@fiscalmindset/blindfold 0.4.0 → 0.4.1

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,8 @@
  * 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 { bannerBox, commandBox, nearest } from "../src/tui.ts";
 import { handleAuth } from "./cmd-auth.ts";
 import { handleSecrets } from "./cmd-secrets.ts";
 import { handleLifecycle } from "./cmd-lifecycle.ts";
@@ -36,52 +37,89 @@ async function main(): Promise<void> {
   const cmd = argv._[0] ?? "help";
   const handler = ROUTES[cmd];
   if (handler) await handler(cmd, argv, cmdArgs);
-  else printHelp();
+  else if (cmd === "help" || cmd === "--help" || cmd === "-h") 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).
+/** 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);
+}
 
-The friendliest path is just:  blindfold init
+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."],
+    ]],
+  ];
 
-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
-`);
+  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) => {

package/dist/cli.mjs

@@ -1374,6 +1374,110 @@ 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 padEnd(s, w) {
+  return s + " ".repeat(Math.max(0, w - vlen(s)));
+}
+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 commandBox(title, rows) {
+  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 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));
+    }
+  }
+  out.push(dim(B.bl + B.h.repeat(w - 2) + B.br));
+  return out.join("\n");
+}
+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];
+}
+
 // bin/cmd-auth.ts
 init_env();
 init_keychain();
@@ -3368,11 +3472,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 +3484,7 @@ function ok2(line) {
 `);
 }
 function info(line) {
-  process.stdout.write(`  ${dim("\xB7")} ${line}
+  process.stdout.write(`  ${dim2("\xB7")} ${line}
 `);
 }
 function warn2(line) {
@@ -3391,7 +3495,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 +3526,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 +3536,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 +3648,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 +3657,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 +3777,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 +3805,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 +3934,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 +3953,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)}
 `);
 }
 
@@ -4265,51 +4369,83 @@ async function main() {
   const cmd = argv._[0] ?? "help";
   const handler = ROUTES[cmd];
   if (handler) await handler(cmd, argv, cmdArgs);
-  else printHelp();
+  else if (cmd === "help" || cmd === "--help" || cmd === "-h") printHelp();
+  else printUnknown(cmd);
+}
+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);
 }
 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
-`);
+  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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiscalmindset/blindfold",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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/tui.ts

@@ -0,0 +1,137 @@
+/**
+ * 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;
+}
+function padEnd(s: string, w: number): string {
+  return s + " ".repeat(Math.max(0, w - vlen(s)));
+}
+
+/** 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");
+}
+
+/** 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]!;
+}