@fiscalmindset/blindfold 0.4.2 → 0.4.4

package/bin/cmd-enclave.ts

@@ -16,6 +16,7 @@ import { runCompat } from "../src/compat.ts";
 import { defaultSealedLogPath, readSealed, verifyLedgerChain } from "../src/sealed-ledger.ts";
 import { type Argv, die, assetPath, fingerprint, resolveEnvVar } from "./cli-shared.ts";
 import { c, ok, bad, warn, head } from "../src/color.ts";
+import { boxLines, rule } from "../src/tui.ts";
 
 export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]): Promise<void> {
   switch (cmd) {
@@ -32,15 +33,19 @@ export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]):
         const b = await client.getBalance();
         const tok = (n: number) => (n / BASE).toLocaleString(undefined, { maximumFractionDigits: 6 });
         if (argv.flags.json) { console.log(JSON.stringify(b, null, 2)); return; }
-        console.log(head(`💳 Terminal 3 credit`) + c.gray(` — ${env.did || "(no tenant)"}  (${env.mock ? "MOCK" : env.t3Env})`));
-        console.log(`  available:  ${c.bold(tok(b.available) + " tokens")}  ${c.gray("(" + b.available.toLocaleString() + " base units)")}`);
-        console.log(`  reserved:   ${b.reserved.toLocaleString()} base units`);
-        console.log(`  status:     ${b.creditExhausted ? warn("⚠ EXHAUSTED") : ok("✅ ok")}`);
+        const lines = [
+          c.gray(`${env.did || "(no tenant)"}  ·  ${env.mock ? "MOCK" : env.t3Env}`),
+          "",
+          `available:  ${c.bold(c.green(tok(b.available) + " tokens"))}  ${c.gray("(" + b.available.toLocaleString() + " base units)")}`,
+          `reserved:   ${b.reserved.toLocaleString()} base units`,
+          `status:     ${b.creditExhausted ? warn("⚠ EXHAUSTED") : ok("✅ ok")}`,
+        ];
         if (b.creditExhausted) {
-          console.log(`  Top up testnet credits, then re-check with \`blindfold credit\`:`);
-          console.log(`    https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens`);
+          lines.push("", c.yellow("Top up testnet credits, then re-check with `blindfold credit`:"),
+            c.cyan("  https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens"));
           process.exitCode = 1;
         }
+        console.log(boxLines("💳 Terminal 3 credit", lines));
       } finally {
         await client.close();
       }
@@ -136,9 +141,10 @@ export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]):
         console.log(`Seal one with:  blindfold register --name <KV_KEY>`);
         return;
       }
-      console.log(head("🔐 Sealed keys") + c.gray(`  (source: ${defaultSealedLogPath()})`) + "\n");
-      console.log("  WHEN                  NAME                       BYTES  MODE   WHERE");
-      console.log("  ────                  ────                       ─────  ────   ─────");
+      console.log(boxLines("🔐 Sealed keys", [c.gray(`source: ${defaultSealedLogPath()}`)]));
+      console.log("");
+      console.log(c.gray("  WHEN                  NAME                       BYTES  MODE   WHERE"));
+      console.log(c.gray("  ────                  ────                       ─────  ────   ─────"));
       for (const e of entries) {
         const when = e.t.replace("T", " ").slice(0, 19);
         const where = e.map_name.length > 60 ? e.map_name.slice(0, 57) + "…" : e.map_name;
@@ -150,9 +156,10 @@ export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]):
     case "audit": {
       // (1) Tamper-evidence: verify the local ledger's hash-chain.
       // (2) Reconcile against the enclave — the actual source of truth.
-      console.log("🔍 Blindfold audit\n");
+      console.log(boxLines("🔍 Blindfold audit", [c.gray("ledger hash-chain + reconciliation against the enclave")]));
+      console.log("");
       const chain = verifyLedgerChain();
-      console.log("  1. Ledger integrity (tamper-evidence)");
+      console.log(c.bold("  1. Ledger integrity (tamper-evidence)"));
       if (chain.total === 0) {
         console.log("     (ledger is empty)");
       } else if (chain.ok) {
@@ -203,44 +210,46 @@ export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]):
     case "status": {
       // One-glance overview: health + sealed inventory + what to do next.
       const env = loadBlindfoldEnv();
-      console.log(head("🛡️  Blindfold status") + "\n");
-      console.log(`  mode:    ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL"}   ·   T3 env: ${env.t3Env}`);
-      if (env.t3BaseUrl) console.log(`  node:    ${env.t3BaseUrl}  (override)`);
+      const lines: string[] = [];
+      lines.push(`mode:    ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL"}   ·   T3 env: ${env.t3Env}`);
+      if (env.t3BaseUrl) lines.push(`node:    ${env.t3BaseUrl}  (override)`);
       if (!env.mock) {
         try {
           const { openT3Client } = await import("../src/t3-client.ts");
           const client = await openT3Client(env);
           const info = await client.me();
-          console.log(`  tenant:  ${ok("✅ " + info.tenant)}  (status=${info.status ?? "?"})`);
+          lines.push(`tenant:  ${ok("✅ " + info.tenant)}  (status=${info.status ?? "?"})`);
         } catch (e) {
-          console.log(`  tenant:  ${bad("✖ " + (e as Error).message.slice(0, 90))}`);
-          console.log(`           → run \`blindfold doctor\` for a full diagnosis.`);
+          lines.push(`tenant:  ${bad("✖ " + (e as Error).message.slice(0, 90))}`);
+          lines.push(`         ${c.gray("→ run `blindfold doctor` for a full diagnosis.")}`);
           process.exitCode = 1;
         }
       }
       const entries = readSealed();
       const latest = new Map<string, (typeof entries)[number]>();
       for (const e of entries) latest.set(e.name, e); // last write wins
-      console.log(`\n  Sealed secrets (${latest.size}):`);
+      lines.push("", c.bold(`Sealed secrets (${latest.size})`));
       if (latest.size === 0) {
-        console.log(`    (none yet)   seal one:  blindfold register --name <X> --from-env <X>`);
+        lines.push(`  ${c.gray("(none yet)  seal one:")}  ${c.cyan("blindfold register --name <X>")}`);
       } else {
         for (const e of latest.values()) {
-          console.log(`    • ${e.name.padEnd(22)} ${String(e.length).padStart(4)} B   ${e.mode}`);
+          lines.push(`  ${c.green("•")} ${c.cyan(e.name.padEnd(22))} ${String(e.length).padStart(4)} B   ${c.gray(e.mode)}`);
         }
       }
-      console.log(`\n  Next:  blindfold use --name <secret> -- <command>     (use it, no code)`);
+      lines.push("", c.gray("Next:  ") + c.cyan("blindfold use --name <secret> -- <command>") + c.gray("   (use it, no code)"));
+      console.log(boxLines("🛡️  Blindfold status", lines));
       return;
     }
     case "doctor": {
       const env = loadBlindfoldEnv();
-      console.log(head("🩺 Blindfold doctor"));
-      console.log(`  mode:               ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL (T3)"}`);
-      console.log(`  T3N_API_KEY set:    ${env.t3nApiKey ? "yes" : "NO ✖"}`);
-      console.log(`  DID set:            ${env.did ? "yes" : "NO ✖"}`);
-      console.log(`  T3 environment:     ${env.t3Env}`);
-      console.log(`  node URL:           ${env.t3BaseUrl || `(SDK default for ${env.t3Env})`}`);
-      console.log(`  default proxy port: ${env.port}`);
+      console.log(boxLines("🩺 Blindfold doctor", [
+        `mode:          ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL (T3)"}`,
+        `T3N_API_KEY:   ${env.t3nApiKey ? ok("set") : bad("NOT set ✖")}`,
+        `DID:           ${env.did ? ok("set") : bad("NOT set ✖")}`,
+        `T3 env:        ${env.t3Env}`,
+        `node URL:      ${env.t3BaseUrl || c.gray(`(SDK default for ${env.t3Env})`)}`,
+        `proxy port:    ${env.port}`,
+      ]));
       if (!env.mock && (!env.t3nApiKey || !env.did)) {
         console.log("");
         console.log(`  ⚠  REAL mode is selected but credentials are missing.`);
@@ -254,8 +263,7 @@ export async function handleEnclave(cmd: string, argv: Argv, cmdArgs: string[]):
       // LIVE check: authenticate, then read the tenant behind the key. This is
       // what catches the painful "key authenticates but has no tenant" case,
       // which the server otherwise reports only as a bare HTTP 500.
-      console.log("");
-      console.log("  Live check (handshake + authenticate + me) …");
+      console.log("\n" + rule("Live check — handshake + authenticate + me"));
       const { openT3Client } = await import("../src/t3-client.ts");
       let client;
       try {

package/dist/cli.mjs

@@ -1309,6 +1309,7 @@ var c = {
   cyan: wrap("36"),
   gray: wrap("90")
 };
+var colorOn = on;
 var ok = (s) => c.green(s);
 var bad = (s) => c.red(s);
 var warn = (s) => c.yellow(s);
@@ -1434,12 +1435,31 @@ 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));
+  const fill = Math.max(0, w - vlen(prefix) - vlen(clip(title, inner)) - 2);
+  const out = [dim(prefix) + c.bold(clip(title, inner)) + dim(" " + B.h.repeat(fill) + B.tr)];
+  for (const l of lines) out.push(dim(B.v) + " " + pad(clip(l, inner), inner) + " " + dim(B.v));
   out.push(dim(B.bl + B.h.repeat(w - 2) + B.br));
   return out.join("\n");
 }
+function clip(s, width) {
+  if (vlen(s) <= width) return s;
+  let out = "";
+  let wSoFar = 0;
+  for (const part of s.split(/(\x1b\[[0-9;]*m)/)) {
+    if (part.startsWith("\x1B")) {
+      out += part;
+      continue;
+    }
+    for (const ch of part) {
+      const cp = ch.codePointAt(0) ?? 0;
+      const cw = cp === 8205 || cp >= 65024 && cp <= 65039 || cp >= 768 && cp <= 879 ? 0 : isWide(cp) ? 2 : 1;
+      if (wSoFar + cw > width - 1) return out + "\u2026" + (colorOn ? "\x1B[0m" : "");
+      out += ch;
+      wSoFar += cw;
+    }
+  }
+  return out + (colorOn ? "\x1B[0m" : "");
+}
 function rule(label = "") {
   const w = termWidth();
   if (!label) return dim(B.h.repeat(w));
@@ -1611,19 +1631,20 @@ var COMMANDS = [
     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"]
+    summary: "Allow the enclave to reach an API's server. Do this once per API before the proxy can call it \u2014 e.g. allow api.openai.com so a sealed OpenAI key can be used.",
+    flags: [["--host <host,...>", "The API hostname(s) to allow, comma-separated. Each grant adds to the list."]],
+    examples: ["blindfold grant --host api.openai.com", "blindfold grant --host api.github.com,api.stripe.com"],
+    notes: "Why it's needed: the enclave refuses to call any host you haven't allowed (deny-by-default). Grant the host of each API whose key you've sealed."
   },
   {
     name: "share",
     group: "\u{1F465} Team & sharing",
     usage: "--to <agent-did> --host <host>[,...]",
-    summary: "Let a teammate'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"]
+    summary: "Let a teammate use your sealed key for an API \u2014 they can make calls but never see the key itself.",
+    flags: [["--to <agent-did>", "The teammate's agent DID (their Terminal 3 identity)."], ["--host <host,...>", "Which API hosts they're allowed to reach through your enclave."]],
+    examples: ["blindfold share --to did:t3n:abc\u2026 --host api.openai.com"]
   },
-  { name: "revoke", group: "\u{1F465} Team & sharing", usage: "--to <agent-did>", summary: "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"] },
+  { name: "revoke", group: "\u{1F465} Team & sharing", usage: "--to <agent-did>", summary: "Take back a teammate's access you granted with `share` \u2014 immediate and complete.", flags: [["--to <agent-did>", "The teammate's agent DID to cut off."]], examples: ["blindfold revoke --to did:t3n:abc\u2026"] },
   // ── Enclave & admin ──────────────────────────────────────────────────────
   { name: "publish", group: "\u{1F4E6} Enclave & admin", usage: "[--wasm <path>]", summary: "Publish the Rust\u2192WASM contract to your tenant (one-time).", flags: [["--wasm <path>", "Path to blindfold_proxy.wasm (defaults to the bundled build)."]], examples: ["blindfold publish"] },
   { name: "status", group: "\u{1F4E6} Enclave & admin", usage: "", summary: "One-glance overview: mode, tenant health, and the list of sealed secrets.", examples: ["blindfold status"] },
@@ -1673,27 +1694,29 @@ function renderMainHelp() {
   ];
   const nameW = Math.min(12, COMMANDS.reduce((m, cmd) => Math.max(m, vlen(cmd.name)), 0));
   const descW = Math.max(16, w - 4 - nameW - 2);
+  const fit = (s, max) => s.length > max ? s.slice(0, Math.max(1, max - 1)) + "\u2026" : s;
   for (const group of GROUP_ORDER) {
     const cmds = COMMANDS.filter((cmd) => cmd.group === group);
     const lines = [];
-    for (const cmd of cmds) {
+    for (const [idx, cmd] of cmds.entries()) {
+      if (idx > 0) lines.push("");
       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));
-      }
+      lines.push(pad(c.bold(c.cyan(cmd.name)), nameW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) lines.push(pad("", nameW) + "  " + (dl[i] ?? ""));
+      const ex = fit(cmd.examples?.[0] ?? `blindfold ${cmd.name}`, descW - 5);
+      lines.push(pad("", nameW) + "  " + c.gray("e.g. ") + c.green(ex));
     }
     out.push(boxLines(group, lines));
     out.push("");
   }
   out.push(
-    c.bold("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.bold(c.magenta("\u25B6 Quick start")),
+    `  ${c.green("blindfold signup --email you@x.com")}         ${c.gray("# create a funded testnet tenant")}`,
+    `  ${c.green("blindfold register --name openai_api_key")}   ${c.gray("# seal a key (hidden prompt)")}`,
+    `  ${c.green("blindfold proxy")}                            ${c.gray("# point your agent at http://127.0.0.1:8787")}`,
     "",
-    `${c.gray("Details for any command:")} ${c.cyan("blindfold <command> --help")}   ${c.gray("\xB7")}   ${c.gray("Docs:")} ${c.cyan("npmjs.com/package/@fiscalmindset/blindfold")}`,
+    `${c.gray("Full flags + more examples for any command:")}  ${c.cyan("blindfold <command> --help")}`,
+    `${c.gray("Docs:")} ${c.cyan("npmjs.com/package/@fiscalmindset/blindfold")}`,
     ""
   );
   return out.join("\n");
@@ -4245,15 +4268,22 @@ async function handleEnclave(cmd, argv, cmdArgs) {
           console.log(JSON.stringify(b, null, 2));
           return;
         }
-        console.log(head(`\u{1F4B3} Terminal 3 credit`) + c.gray(` \u2014 ${env.did || "(no tenant)"}  (${env.mock ? "MOCK" : env.t3Env})`));
-        console.log(`  available:  ${c.bold(tok(b.available) + " tokens")}  ${c.gray("(" + b.available.toLocaleString() + " base units)")}`);
-        console.log(`  reserved:   ${b.reserved.toLocaleString()} base units`);
-        console.log(`  status:     ${b.creditExhausted ? warn("\u26A0 EXHAUSTED") : ok("\u2705 ok")}`);
+        const lines = [
+          c.gray(`${env.did || "(no tenant)"}  \xB7  ${env.mock ? "MOCK" : env.t3Env}`),
+          "",
+          `available:  ${c.bold(c.green(tok(b.available) + " tokens"))}  ${c.gray("(" + b.available.toLocaleString() + " base units)")}`,
+          `reserved:   ${b.reserved.toLocaleString()} base units`,
+          `status:     ${b.creditExhausted ? warn("\u26A0 EXHAUSTED") : ok("\u2705 ok")}`
+        ];
         if (b.creditExhausted) {
-          console.log(`  Top up testnet credits, then re-check with \`blindfold credit\`:`);
-          console.log(`    https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens`);
+          lines.push(
+            "",
+            c.yellow("Top up testnet credits, then re-check with `blindfold credit`:"),
+            c.cyan("  https://docs.terminal3.io/developers/adk/get-started/prerequisites/request-test-tokens")
+          );
           process.exitCode = 1;
         }
+        console.log(boxLines("\u{1F4B3} Terminal 3 credit", lines));
       } finally {
         await client.close();
       }
@@ -4345,9 +4375,10 @@ async function handleEnclave(cmd, argv, cmdArgs) {
         console.log(`Seal one with:  blindfold register --name <KV_KEY>`);
         return;
       }
-      console.log(head("\u{1F510} Sealed keys") + c.gray(`  (source: ${defaultSealedLogPath()})`) + "\n");
-      console.log("  WHEN                  NAME                       BYTES  MODE   WHERE");
-      console.log("  \u2500\u2500\u2500\u2500                  \u2500\u2500\u2500\u2500                       \u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500   \u2500\u2500\u2500\u2500\u2500");
+      console.log(boxLines("\u{1F510} Sealed keys", [c.gray(`source: ${defaultSealedLogPath()}`)]));
+      console.log("");
+      console.log(c.gray("  WHEN                  NAME                       BYTES  MODE   WHERE"));
+      console.log(c.gray("  \u2500\u2500\u2500\u2500                  \u2500\u2500\u2500\u2500                       \u2500\u2500\u2500\u2500\u2500  \u2500\u2500\u2500\u2500   \u2500\u2500\u2500\u2500\u2500"));
       for (const e of entries) {
         const when = e.t.replace("T", " ").slice(0, 19);
         const where = e.map_name.length > 60 ? e.map_name.slice(0, 57) + "\u2026" : e.map_name;
@@ -4357,9 +4388,10 @@ async function handleEnclave(cmd, argv, cmdArgs) {
       return;
     }
     case "audit": {
-      console.log("\u{1F50D} Blindfold audit\n");
+      console.log(boxLines("\u{1F50D} Blindfold audit", [c.gray("ledger hash-chain + reconciliation against the enclave")]));
+      console.log("");
       const chain = verifyLedgerChain();
-      console.log("  1. Ledger integrity (tamper-evidence)");
+      console.log(c.bold("  1. Ledger integrity (tamper-evidence)"));
       if (chain.total === 0) {
         console.log("     (ledger is empty)");
       } else if (chain.ok) {
@@ -4410,46 +4442,46 @@ async function handleEnclave(cmd, argv, cmdArgs) {
     }
     case "status": {
       const env = loadBlindfoldEnv();
-      console.log(head("\u{1F6E1}\uFE0F  Blindfold status") + "\n");
-      console.log(`  mode:    ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL"}   \xB7   T3 env: ${env.t3Env}`);
-      if (env.t3BaseUrl) console.log(`  node:    ${env.t3BaseUrl}  (override)`);
+      const lines = [];
+      lines.push(`mode:    ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL"}   \xB7   T3 env: ${env.t3Env}`);
+      if (env.t3BaseUrl) lines.push(`node:    ${env.t3BaseUrl}  (override)`);
       if (!env.mock) {
         try {
           const { openT3Client: openT3Client2 } = await Promise.resolve().then(() => (init_t3_client(), t3_client_exports));
           const client = await openT3Client2(env);
           const info2 = await client.me();
-          console.log(`  tenant:  ${ok("\u2705 " + info2.tenant)}  (status=${info2.status ?? "?"})`);
+          lines.push(`tenant:  ${ok("\u2705 " + info2.tenant)}  (status=${info2.status ?? "?"})`);
         } catch (e) {
-          console.log(`  tenant:  ${bad("\u2716 " + e.message.slice(0, 90))}`);
-          console.log(`           \u2192 run \`blindfold doctor\` for a full diagnosis.`);
+          lines.push(`tenant:  ${bad("\u2716 " + e.message.slice(0, 90))}`);
+          lines.push(`         ${c.gray("\u2192 run `blindfold doctor` for a full diagnosis.")}`);
           process.exitCode = 1;
         }
       }
       const entries = readSealed();
       const latest = /* @__PURE__ */ new Map();
       for (const e of entries) latest.set(e.name, e);
-      console.log(`
-  Sealed secrets (${latest.size}):`);
+      lines.push("", c.bold(`Sealed secrets (${latest.size})`));
       if (latest.size === 0) {
-        console.log(`    (none yet)   seal one:  blindfold register --name <X> --from-env <X>`);
+        lines.push(`  ${c.gray("(none yet)  seal one:")}  ${c.cyan("blindfold register --name <X>")}`);
       } else {
         for (const e of latest.values()) {
-          console.log(`    \u2022 ${e.name.padEnd(22)} ${String(e.length).padStart(4)} B   ${e.mode}`);
+          lines.push(`  ${c.green("\u2022")} ${c.cyan(e.name.padEnd(22))} ${String(e.length).padStart(4)} B   ${c.gray(e.mode)}`);
         }
       }
-      console.log(`
-  Next:  blindfold use --name <secret> -- <command>     (use it, no code)`);
+      lines.push("", c.gray("Next:  ") + c.cyan("blindfold use --name <secret> -- <command>") + c.gray("   (use it, no code)"));
+      console.log(boxLines("\u{1F6E1}\uFE0F  Blindfold status", lines));
       return;
     }
     case "doctor": {
       const env = loadBlindfoldEnv();
-      console.log(head("\u{1FA7A} Blindfold doctor"));
-      console.log(`  mode:               ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL (T3)"}`);
-      console.log(`  T3N_API_KEY set:    ${env.t3nApiKey ? "yes" : "NO \u2716"}`);
-      console.log(`  DID set:            ${env.did ? "yes" : "NO \u2716"}`);
-      console.log(`  T3 environment:     ${env.t3Env}`);
-      console.log(`  node URL:           ${env.t3BaseUrl || `(SDK default for ${env.t3Env})`}`);
-      console.log(`  default proxy port: ${env.port}`);
+      console.log(boxLines("\u{1FA7A} Blindfold doctor", [
+        `mode:          ${env.mock ? "MOCK (BLINDFOLD_MOCK=1)" : "REAL (T3)"}`,
+        `T3N_API_KEY:   ${env.t3nApiKey ? ok("set") : bad("NOT set \u2716")}`,
+        `DID:           ${env.did ? ok("set") : bad("NOT set \u2716")}`,
+        `T3 env:        ${env.t3Env}`,
+        `node URL:      ${env.t3BaseUrl || c.gray(`(SDK default for ${env.t3Env})`)}`,
+        `proxy port:    ${env.port}`
+      ]));
       if (!env.mock && (!env.t3nApiKey || !env.did)) {
         console.log("");
         console.log(`  \u26A0  REAL mode is selected but credentials are missing.`);
@@ -4459,8 +4491,7 @@ async function handleEnclave(cmd, argv, cmdArgs) {
         return;
       }
       if (env.mock) return;
-      console.log("");
-      console.log("  Live check (handshake + authenticate + me) \u2026");
+      console.log("\n" + rule("Live check \u2014 handshake + authenticate + me"));
       const { openT3Client: openT3Client2 } = await Promise.resolve().then(() => (init_t3_client(), t3_client_exports));
       let client;
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiscalmindset/blindfold",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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

@@ -139,17 +139,18 @@ export const COMMANDS: CmdDef[] = [
   // ── 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)."]],
+    summary: "Allow the enclave to reach an API's server. Do this once per API before the proxy can call it — e.g. allow api.openai.com so a sealed OpenAI key can be used.",
+    flags: [["--host <host,...>", "The API hostname(s) to allow, comma-separated. Each grant adds to the list."]],
     examples: ["blindfold grant --host api.openai.com", "blindfold grant --host api.github.com,api.stripe.com"],
+    notes: "Why it's needed: the enclave refuses to call any host you haven't allowed (deny-by-default). Grant the host of each API whose key you've sealed.",
   },
   {
     name: "share", group: "👥 Team & sharing", usage: "--to <agent-did> --host <host>[,...]",
-    summary: "Let a teammate'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"],
+    summary: "Let a teammate use your sealed key for an API — they can make calls but never see the key itself.",
+    flags: [["--to <agent-did>", "The teammate's agent DID (their Terminal 3 identity)."], ["--host <host,...>", "Which API hosts they're allowed to reach through your enclave."]],
+    examples: ["blindfold share --to did:t3n:abc… --host api.openai.com"],
   },
-  { name: "revoke", group: "👥 Team & sharing", usage: "--to <agent-did>", summary: "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:…"] },
+  { name: "revoke", group: "👥 Team & sharing", usage: "--to <agent-did>", summary: "Take back a teammate's access you granted with `share` — immediate and complete.", flags: [["--to <agent-did>", "The teammate's agent DID to cut off."]], examples: ["blindfold revoke --to did:t3n:abc…"] },
 
   // ── Enclave & admin ──────────────────────────────────────────────────────
   { name: "publish", group: "📦 Enclave & admin", usage: "[--wasm <path>]", summary: "Publish the Rust→WASM contract to your tenant (one-time).", flags: [["--wasm <path>", "Path to blindfold_proxy.wasm (defaults to the bundled build)."]], examples: ["blindfold publish"] },
@@ -203,29 +204,33 @@ export function renderMainHelp(): string {
 
   const nameW = Math.min(12, COMMANDS.reduce((m, cmd) => Math.max(m, vlen(cmd.name)), 0));
   const descW = Math.max(16, w - 4 - nameW - 2);
+  const fit = (s: string, max: number): string => (s.length > max ? s.slice(0, Math.max(1, max - 1)) + "…" : s);
 
   for (const group of GROUP_ORDER) {
     const cmds = COMMANDS.filter((cmd) => cmd.group === group);
     const lines: string[] = [];
-    for (const cmd of cmds) {
+    for (const [idx, cmd] of cmds.entries()) {
+      if (idx > 0) lines.push(""); // breathing room between commands
       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));
-      }
+      // command name (bright) + summary
+      lines.push(pad(c.bold(c.cyan(cmd.name)), nameW) + "  " + (dl[0] ?? ""));
+      for (let i = 1; i < dl.length; i++) lines.push(pad("", nameW) + "  " + (dl[i] ?? ""));
+      // one concrete example — the fastest way to "get" the command
+      const ex = fit(cmd.examples?.[0] ?? `blindfold ${cmd.name}`, descW - 5);
+      lines.push(pad("", nameW) + "  " + c.gray("e.g. ") + c.green(ex));
     }
     out.push(boxLines(group, lines));
     out.push("");
   }
 
   out.push(
-    c.bold("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.bold(c.magenta("▶ Quick start")),
+    `  ${c.green("blindfold signup --email you@x.com")}         ${c.gray("# create a funded testnet tenant")}`,
+    `  ${c.green("blindfold register --name openai_api_key")}   ${c.gray("# seal a key (hidden prompt)")}`,
+    `  ${c.green("blindfold proxy")}                            ${c.gray("# point your agent at http://127.0.0.1:8787")}`,
     "",
-    `${c.gray("Details for any command:")} ${c.cyan("blindfold <command> --help")}   ${c.gray("·")}   ${c.gray("Docs:")} ${c.cyan("npmjs.com/package/@fiscalmindset/blindfold")}`,
+    `${c.gray("Full flags + more examples for any command:")}  ${c.cyan("blindfold <command> --help")}`,
+    `${c.gray("Docs:")} ${c.cyan("npmjs.com/package/@fiscalmindset/blindfold")}`,
     "",
   );
   return out.join("\n");

package/src/tui.ts

@@ -3,7 +3,7 @@
  * 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";
+import { c, colorOn } from "./color.ts";
 
 /** Terminal width, clamped to a readable range. */
 export function termWidth(): number {
@@ -124,13 +124,32 @@ 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));
+  const fill = Math.max(0, w - vlen(prefix) - vlen(clip(title, inner)) - 2);
+  const out: string[] = [dim(prefix) + c.bold(clip(title, inner)) + dim(" " + B.h.repeat(fill) + B.tr)];
+  for (const l of lines) out.push(dim(B.v) + " " + pad(clip(l, inner), inner) + " " + dim(B.v));
   out.push(dim(B.bl + B.h.repeat(w - 2) + B.br));
   return out.join("\n");
 }
 
+/** Truncate a string to display width `width` (ANSI/emoji aware), appending …
+ *  and a reset so a clipped color can't bleed. No-op if it already fits. */
+export function clip(s: string, width: number): string {
+  if (vlen(s) <= width) return s;
+  let out = "";
+  let wSoFar = 0;
+  for (const part of s.split(/(\x1b\[[0-9;]*m)/)) {
+    if (part.startsWith("\x1b")) { out += part; continue; }
+    for (const ch of part) {
+      const cp = ch.codePointAt(0) ?? 0;
+      const cw = cp === 0x200d || (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0x300 && cp <= 0x36f) ? 0 : isWide(cp) ? 2 : 1;
+      if (wSoFar + cw > width - 1) return out + "…" + (colorOn ? "\x1b[0m" : "");
+      out += ch;
+      wSoFar += cw;
+    }
+  }
+  return out + (colorOn ? "\x1b[0m" : "");
+}
+
 /** A plain full-width rule with an optional bold label: "── Label ─────". */
 export function rule(label = ""): string {
   const w = termWidth();