ai-speedometer 2.2.1 → 2.3.0

package/dist/ai-speedometer

@@ -1932,6 +1932,7 @@ async function benchmarkSingleModelRest(model, logger) {
     const finalInputTokens = inputTokens || Math.round(TEST_PROMPT.length / 4);
     const totalTokens = finalInputTokens + finalOutputTokens;
     const tokensPerSecond = generationTime > 0 ? finalOutputTokens / generationTime * 1000 : 0;
+    const f1000 = tokensPerSecond > 0 ? 1000 * (timeToFirstToken / 1000 + 300 / tokensPerSecond) / 3600 : Infinity;
     return {
       model: model.name,
       provider: model.providerName,
@@ -1939,6 +1940,7 @@ async function benchmarkSingleModelRest(model, logger) {
       timeToFirstToken,
       tokenCount: finalOutputTokens,
       tokensPerSecond,
+      f1000,
       promptTokens: finalInputTokens,
       totalTokens,
       usedEstimateForOutput,
@@ -1954,6 +1956,7 @@ async function benchmarkSingleModelRest(model, logger) {
       timeToFirstToken: 0,
       tokenCount: 0,
       tokensPerSecond: 0,
+      f1000: Infinity,
       promptTokens: 0,
       totalTokens: 0,
       usedEstimateForOutput: true,
@@ -2019,6 +2022,8 @@ function buildJsonOutput(providerName, providerId, modelName, modelId, result, f
     timeToFirstToken: result.timeToFirstToken,
     timeToFirstTokenSeconds: result.timeToFirstToken / 1000,
     tokensPerSecond: result.tokensPerSecond,
+    f1000: result.f1000,
+    f1000Hours: result.f1000 === Infinity ? null : result.f1000,
     outputTokens: result.tokenCount,
     promptTokens: result.promptTokens,
     totalTokens: result.totalTokens,
@@ -3011,7 +3016,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "ai-speedometer",
-    version: "2.2.1",
+    version: "2.3.0",
     description: "A comprehensive CLI tool for benchmarking AI models across multiple providers with parallel execution and professional metrics",
     bin: {
       "ai-speedometer": "dist/ai-speedometer",
@@ -3155,6 +3160,7 @@ function MainMenuScreen() {
   const ITEMS = [
     { label: "\u26A1 Run Benchmark", desc: "test model speed & throughput", color: theme.accent },
     { label: "\u2699  Manage Models", desc: "add providers and configure", color: theme.secondary },
+    { label: "?  FAQ / Learn", desc: "how metrics work & resources", color: theme.primary },
     { label: "\u2715  Exit", desc: "quit the application", color: theme.error }
   ];
   useAppKeyboard((key) => {
@@ -3168,6 +3174,8 @@ function MainMenuScreen() {
       else if (cursor === 1)
         navigate("model-menu");
       else if (cursor === 2)
+        navigate("faq");
+      else if (cursor === 3)
         renderer.destroy();
     }
   });
@@ -3202,7 +3210,7 @@ function MainMenuScreen() {
         borderStyle: "rounded",
         borderColor: theme.border,
         backgroundColor: theme.background,
-        width: 46,
+        width: 48,
         children: ITEMS.map((item, i) => {
           const active = i === cursor;
           return /* @__PURE__ */ jsxDEV7("box", {
@@ -3712,8 +3720,9 @@ var init_ModelSelectScreen = __esm(() => {
 
 // src/tui/components/BarChart.tsx
 import { jsxDEV as jsxDEV11 } from "@opentui/react/jsx-dev-runtime";
-function BarChart({ value, max, width, color }) {
-  const filled = max === 0 ? 0 : Math.round(value / max * width);
+function BarChart({ value, max, width, color, inverted = false }) {
+  const normalizedValue = inverted && max > 0 ? Math.max(0, max - value) : value;
+  const filled = max === 0 ? 0 : Math.round(normalizedValue / max * width);
   const empty = width - filled;
   const bar = "\u2588".repeat(filled) + "\u2591".repeat(empty);
   return /* @__PURE__ */ jsxDEV11("text", {
@@ -3817,13 +3826,17 @@ function trunc(s, w) {
 function ResultsTable({ results, pendingCount }) {
   const theme = useTheme();
   const sorted = [...results].sort((a, b) => b.tokensPerSecond - a.tokensPerSecond);
-  const C = { rank: 4, model: 18, prov: 12, time: 10, ttft: 8, tps: 11, out: 8, inp: 8, tot: 8 };
-  const totalW = C.rank + C.model + C.prov + C.time + C.ttft + C.tps + C.out + C.inp + C.tot + 9;
+  const C = { rank: 4, model: 16, prov: 10, time: 8, ttft: 7, tps: 9, f1000: 8, out: 6, inp: 6, tot: 6 };
+  const totalW = C.rank + C.model + C.prov + C.time + C.ttft + C.tps + C.f1000 + C.out + C.inp + C.tot + 10;
   const sep = "\u2500".repeat(totalW);
-  function row(rank, model, prov, time, ttft, tps, out, inp, tot) {
-    return lpad(rank, C.rank) + " \u2502 " + rpad(model, C.model) + " \u2502 " + rpad(prov, C.prov) + " \u2502 " + lpad(time, C.time) + " \u2502 " + lpad(ttft, C.ttft) + " \u2502 " + lpad(tps, C.tps) + " \u2502 " + lpad(out, C.out) + " \u2502 " + lpad(inp, C.inp) + " \u2502 " + lpad(tot, C.tot);
+  const maxTps = Math.max(...results.map((r) => r.tokensPerSecond), 0);
+  const minTtft = Math.min(...results.map((r) => r.timeToFirstToken), Infinity);
+  const validF1000s = results.map((r) => r.f1000).filter((f) => f !== Infinity);
+  const minF1000 = validF1000s.length > 0 ? Math.min(...validF1000s) : Infinity;
+  function row(rank, model, prov, time, ttft, tps, f1000, out, inp, tot) {
+    return lpad(rank, C.rank) + " \u2502 " + rpad(model, C.model) + " \u2502 " + rpad(prov, C.prov) + " \u2502 " + lpad(time, C.time) + " \u2502 " + lpad(ttft, C.ttft) + " \u2502 " + lpad(tps, C.tps) + " \u2502 " + lpad(f1000, C.f1000) + " \u2502 " + lpad(out, C.out) + " \u2502 " + lpad(inp, C.inp) + " \u2502 " + lpad(tot, C.tot);
   }
-  const header = row("#", "Model", "Provider", "Time(s)", "TTFT(s)", "Tokens/Sec", "Out", "In", "Total");
+  const header = row("#", "Model", "Provider", "Time(s)", "TTFT(s)", "Tok/s", "F1000(h)", "Out", "In", "Total");
   return /* @__PURE__ */ jsxDEV13("box", {
     flexDirection: "column",
     paddingLeft: 1,
@@ -3845,21 +3858,87 @@ function ResultsTable({ results, pendingCount }) {
       }, undefined, false, undefined, this),
       sorted.map((r, i) => {
         const rank = `${i + 1}`;
-        const timeSec = (r.totalTime / 1000).toFixed(2);
+        const timeSec = (r.totalTime / 1000).toFixed(1);
         const ttftSec = (r.timeToFirstToken / 1000).toFixed(2);
-        const tps = r.tokensPerSecond.toFixed(1);
-        const outTok = r.tokenCount.toString() + (r.usedEstimateForOutput ? "[e]" : "");
-        const inTok = r.promptTokens.toString() + (r.usedEstimateForInput ? "[e]" : "");
-        const totTok = r.totalTokens.toString() + (r.usedEstimateForOutput || r.usedEstimateForInput ? "[e]" : "");
+        const tps = r.tokensPerSecond.toFixed(0);
+        const f1000Val = r.f1000 === Infinity ? "\u221E" : r.f1000.toFixed(2);
+        const outTok = r.tokenCount.toString() + (r.usedEstimateForOutput ? "*" : "");
+        const inTok = r.promptTokens.toString() + (r.usedEstimateForInput ? "*" : "");
+        const totTok = r.totalTokens.toString() + (r.usedEstimateForOutput || r.usedEstimateForInput ? "*" : "");
         const hasEst = r.usedEstimateForOutput || r.usedEstimateForInput;
-        const line = row(rank, trunc(r.model, C.model), trunc(r.provider, C.prov), timeSec, ttftSec, tps, outTok, inTok, totTok);
+        const isBestTps = r.tokensPerSecond === maxTps && maxTps > 0;
+        const isBestTtft = r.timeToFirstToken === minTtft;
+        const isBestF1000 = r.f1000 === minF1000 && r.f1000 !== Infinity;
         return /* @__PURE__ */ jsxDEV13("box", {
           height: 1,
           flexDirection: "row",
           children: [
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: theme.dim,
+              children: [
+                lpad(rank, C.rank),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
             /* @__PURE__ */ jsxDEV13("text", {
               fg: theme.text,
-              children: line
+              children: [
+                rpad(trunc(r.model, C.model), C.model),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: theme.dim,
+              children: [
+                rpad(trunc(r.provider, C.prov), C.prov),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: theme.dim,
+              children: [
+                lpad(timeSec, C.time),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: isBestTtft ? theme.success : theme.dim,
+              children: [
+                lpad(ttftSec, C.ttft),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: isBestTps ? theme.success : theme.dim,
+              children: [
+                lpad(tps, C.tps),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: isBestF1000 ? theme.success : theme.dim,
+              children: [
+                lpad(f1000Val, C.f1000),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: theme.dim,
+              children: [
+                lpad(outTok, C.out),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: theme.dim,
+              children: [
+                lpad(inTok, C.inp),
+                " \u2502 "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV13("text", {
+              fg: theme.dim,
+              children: lpad(totTok, C.tot)
             }, undefined, false, undefined, this),
             hasEst && /* @__PURE__ */ jsxDEV13("text", {
               fg: theme.warning,
@@ -3975,7 +4054,9 @@ function BenchmarkScreen() {
   const maxTtft = Math.max(...done.map((m) => (m.result?.timeToFirstToken ?? 0) / 1000), 1);
   const tpsRanked = done.slice().sort((a, b) => (b.result?.tokensPerSecond ?? 0) - (a.result?.tokensPerSecond ?? 0));
   const ttftRanked = done.slice().sort((a, b) => (a.result?.timeToFirstToken ?? 0) - (b.result?.timeToFirstToken ?? 0));
+  const f1000Ranked = done.slice().sort((a, b) => (a.result?.f1000 ?? Infinity) - (b.result?.f1000 ?? Infinity));
   const maxTtftForBar = Math.max(...done.map((m) => (m.result?.timeToFirstToken ?? 0) / 1000), 1);
+  const maxF1000 = Math.max(...done.map((m) => m.result?.f1000 ?? 0), 1);
   const doneResults = tpsRanked.map((m) => m.result);
   const pendingCount = running.length + pending.length;
   const allRows = useMemo(() => {
@@ -4217,6 +4298,103 @@ function BenchmarkScreen() {
         }, `ttft-${s.model.id}-${s.model.providerId}`, true, undefined, this));
       }
     }
+    if (f1000Ranked.length > 0) {
+      rows.push(/* @__PURE__ */ jsxDEV14("box", {
+        height: 1,
+        backgroundColor: theme.border
+      }, "div-f1000", false, undefined, this));
+      rows.push(/* @__PURE__ */ jsxDEV14("box", {
+        height: 1,
+        flexDirection: "row",
+        paddingLeft: 1,
+        children: /* @__PURE__ */ jsxDEV14("text", {
+          fg: theme.primary,
+          children: " F1000 RANKING - First to 1000 Requests  (lower is better) "
+        }, undefined, false, undefined, this)
+      }, "hdr-f1000", false, undefined, this));
+      for (const [i, s] of f1000Ranked.entries()) {
+        const rank = i + 1;
+        const rankFg = rank === 1 ? theme.accent : rank === 2 ? theme.secondary : theme.dim;
+        const f1000 = s.result?.f1000 ?? Infinity;
+        const f1000Str = f1000 === Infinity ? "\u221E" : f1000.toFixed(2);
+        const ttft = (s.result?.timeToFirstToken ?? 0) / 1000;
+        const tps = s.result?.tokensPerSecond ?? 0;
+        const badge = rankBadge(rank).padStart(3);
+        const modelCol = s.model.name.padEnd(18).slice(0, 18);
+        const provCol = s.model.providerName.padEnd(12).slice(0, 12);
+        rows.push(/* @__PURE__ */ jsxDEV14("box", {
+          height: 1,
+          flexDirection: "row",
+          paddingLeft: 2,
+          children: [
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: rankFg,
+              children: [
+                badge,
+                "  "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.dim,
+              children: " \u2502 "
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.primary,
+              children: [
+                f1000Str.padStart(7),
+                "h  "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.dim,
+              children: " \u2502 "
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.secondary,
+              children: [
+                ttft.toFixed(2).padStart(5),
+                "s  "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.dim,
+              children: " \u2502 "
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.accent,
+              children: [
+                tps.toFixed(0).padStart(5),
+                " tok/s  "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.dim,
+              children: " \u2502 "
+            }, undefined, false, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.text,
+              children: [
+                modelCol,
+                "  "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV14("text", {
+              fg: theme.dim,
+              children: [
+                provCol,
+                "  \u2502  "
+              ]
+            }, undefined, true, undefined, this),
+            /* @__PURE__ */ jsxDEV14(BarChart, {
+              value: f1000 === Infinity ? maxF1000 : f1000,
+              max: maxF1000,
+              width: BAR_W2,
+              color: theme.primary
+            }, undefined, false, undefined, this)
+          ]
+        }, `f1000-${s.model.id}-${s.model.providerId}`, true, undefined, this));
+      }
+    }
     if (allDone && errors.length > 0) {
       rows.push(/* @__PURE__ */ jsxDEV14("box", {
         height: 1,
@@ -4311,7 +4489,7 @@ function BenchmarkScreen() {
       }, "results-empty", false, undefined, this));
     }
     return rows;
-  }, [modelStates, allDone, tpsRanked, ttftRanked, doneResults, pendingCount, maxTps, maxTtftForBar, theme]);
+  }, [modelStates, allDone, tpsRanked, ttftRanked, f1000Ranked, doneResults, pendingCount, maxTps, maxTtftForBar, maxF1000, theme]);
   useAppKeyboard((key) => {
     if (!allDone)
       return;
@@ -5933,9 +6111,276 @@ var init_ListProvidersScreen = __esm(() => {
   init_ThemeContext();
 });
 
+// src/tui/screens/FAQScreen.tsx
+import { jsxDEV as jsxDEV19 } from "@opentui/react/jsx-dev-runtime";
+function FAQScreen() {
+  const navigate = useNavigate();
+  const theme = useTheme();
+  useAppKeyboard((key) => {
+    if (key.name === "escape" || key.name === "q") {
+      navigate("main-menu");
+    }
+  });
+  return /* @__PURE__ */ jsxDEV19("box", {
+    flexDirection: "column",
+    flexGrow: 1,
+    alignItems: "center",
+    padding: 1,
+    children: /* @__PURE__ */ jsxDEV19("box", {
+      flexDirection: "column",
+      width: 70,
+      children: [
+        /* @__PURE__ */ jsxDEV19("box", {
+          marginBottom: 1,
+          children: /* @__PURE__ */ jsxDEV19("text", {
+            fg: theme.primary,
+            bold: true,
+            children: "FAQ / Learn"
+          }, undefined, false, undefined, this)
+        }, undefined, false, undefined, this),
+        /* @__PURE__ */ jsxDEV19("scrollbox", {
+          focused: true,
+          flexGrow: 1,
+          children: /* @__PURE__ */ jsxDEV19("box", {
+            flexDirection: "column",
+            children: [
+              /* @__PURE__ */ jsxDEV19("box", {
+                flexDirection: "column",
+                border: true,
+                borderStyle: "rounded",
+                borderColor: theme.border,
+                padding: 1,
+                marginBottom: 1,
+                children: [
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.accent,
+                    bold: true,
+                    children: "METRICS EXPLAINED"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "TPS (Tokens Per Second)"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  How fast a model generates tokens after the first one."
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Formula: output_tokens / generation_time"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.success,
+                    children: "  \u2192 Higher is better (faster streaming)"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "TTFT (Time To First Token)"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  Time from request to receiving the first token."
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Formula: first_token_time - request_start_time"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.success,
+                    children: "  \u2192 Lower is better (less waiting)"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "F1000 (First to 1000)"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  Time to complete 1000 agentic requests (~300 tokens each)."
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Formula: 1000 \xD7 (TTFT + 300/TPS) = hours"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.success,
+                    children: "  \u2192 Lower is better"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  Why it matters: In agentic coding (Cursor, Copilot, OpenCode),"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  models make hundreds of tool calls \u2014 TTFT adds up massively."
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  A 30 tok/s + 1s TTFT model can match a 60 tok/s + 6s TTFT model."
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "Total Time"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  Complete request duration from start to finish."
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Includes: connection, TTFT, and generation time"
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV19("box", {
+                flexDirection: "column",
+                border: true,
+                borderStyle: "rounded",
+                borderColor: theme.border,
+                padding: 1,
+                marginBottom: 1,
+                children: [
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.accent,
+                    bold: true,
+                    children: "LINKS"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "Discord Community"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  https://discord.gg/6S7HwCxbMy"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Join for help, updates, and discussions"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "Website & Leaderboard"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  https://ai-speedometer.oliveowl.xyz/"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Track OSS model speeds over time"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.secondary,
+                    bold: true,
+                    children: "GitHub"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  https://github.com/anomaly/ai-speedometer"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.dim,
+                    children: "  Source code, issues, contributions"
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV19("box", {
+                flexDirection: "column",
+                border: true,
+                borderStyle: "rounded",
+                borderColor: theme.border,
+                padding: 1,
+                marginBottom: 1,
+                children: [
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.accent,
+                    bold: true,
+                    children: "TIPS"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: " "
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  \u2022 Press [T] anytime to open the theme picker"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  \u2022 Use --log flag to save raw SSE data for debugging"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  \u2022 Run headless with ai-speedometer-headless for CI/CD"
+                  }, undefined, false, undefined, this),
+                  /* @__PURE__ */ jsxDEV19("text", {
+                    fg: theme.text,
+                    children: "  \u2022 [*] in results means token count was estimated"
+                  }, undefined, false, undefined, this)
+                ]
+              }, undefined, true, undefined, this),
+              /* @__PURE__ */ jsxDEV19("box", {
+                flexDirection: "row",
+                justifyContent: "center",
+                marginTop: 1,
+                children: /* @__PURE__ */ jsxDEV19("text", {
+                  fg: theme.dim,
+                  children: "Press [Q] or [Esc] to return to main menu"
+                }, undefined, false, undefined, this)
+              }, undefined, false, undefined, this)
+            ]
+          }, undefined, true, undefined, this)
+        }, undefined, false, undefined, this)
+      ]
+    }, undefined, true, undefined, this)
+  }, undefined, false, undefined, this);
+}
+var init_FAQScreen = __esm(() => {
+  init_useAppKeyboard();
+  init_AppContext();
+  init_ThemeContext();
+});
+
 // src/tui/App.tsx
 import { useKeyboard as useKeyboard3, useRenderer as useRenderer3 } from "@opentui/react";
-import { jsxDEV as jsxDEV19 } from "@opentui/react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV20 } from "@opentui/react/jsx-dev-runtime";
 function getHints(screen, benchResults) {
   switch (screen) {
     case "main-menu":
@@ -5950,6 +6395,8 @@ function getHints(screen, benchResults) {
     }
     case "list-providers":
       return ["[\u2191\u2193] scroll", "[Q] back"];
+    case "faq":
+      return ["[\u2191\u2193] scroll", "[Q] back"];
     case "add-verified":
       return ["[\u2191\u2193] navigate", "[Enter] select", "[Q] back"];
     case "add-custom":
@@ -5964,21 +6411,23 @@ function ActiveScreen() {
   const { state } = useAppContext();
   switch (state.screen) {
     case "main-menu":
-      return /* @__PURE__ */ jsxDEV19(MainMenuScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(MainMenuScreen, {}, undefined, false, undefined, this);
     case "model-menu":
-      return /* @__PURE__ */ jsxDEV19(ModelMenuScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(ModelMenuScreen, {}, undefined, false, undefined, this);
     case "model-select":
-      return /* @__PURE__ */ jsxDEV19(ModelSelectScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(ModelSelectScreen, {}, undefined, false, undefined, this);
     case "benchmark":
-      return /* @__PURE__ */ jsxDEV19(BenchmarkScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(BenchmarkScreen, {}, undefined, false, undefined, this);
     case "add-verified":
-      return /* @__PURE__ */ jsxDEV19(AddVerifiedScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(AddVerifiedScreen, {}, undefined, false, undefined, this);
     case "add-custom":
-      return /* @__PURE__ */ jsxDEV19(AddCustomScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(AddCustomScreen, {}, undefined, false, undefined, this);
     case "add-models":
-      return /* @__PURE__ */ jsxDEV19(AddModelsScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(AddModelsScreen, {}, undefined, false, undefined, this);
     case "list-providers":
-      return /* @__PURE__ */ jsxDEV19(ListProvidersScreen, {}, undefined, false, undefined, this);
+      return /* @__PURE__ */ jsxDEV20(ListProvidersScreen, {}, undefined, false, undefined, this);
+    case "faq":
+      return /* @__PURE__ */ jsxDEV20(FAQScreen, {}, undefined, false, undefined, this);
   }
 }
 function Shell() {
@@ -5995,36 +6444,36 @@ function Shell() {
       setModalOpen(!modalOpen);
     }
   });
-  return /* @__PURE__ */ jsxDEV19("box", {
+  return /* @__PURE__ */ jsxDEV20("box", {
     flexDirection: "column",
     height: "100%",
     width: "100%",
     backgroundColor: theme.background,
     children: [
-      /* @__PURE__ */ jsxDEV19(Header, {
+      /* @__PURE__ */ jsxDEV20(Header, {
         screen: state.screen
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV19("box", {
+      /* @__PURE__ */ jsxDEV20("box", {
         flexGrow: 1,
         flexDirection: "column",
-        children: /* @__PURE__ */ jsxDEV19(ActiveScreen, {}, undefined, false, undefined, this)
+        children: /* @__PURE__ */ jsxDEV20(ActiveScreen, {}, undefined, false, undefined, this)
       }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV19(Footer, {
+      /* @__PURE__ */ jsxDEV20(Footer, {
         hints: getHints(state.screen, state.benchResults)
       }, undefined, false, undefined, this),
-      modalOpen && /* @__PURE__ */ jsxDEV19(ThemePicker, {
+      modalOpen && /* @__PURE__ */ jsxDEV20(ThemePicker, {
         onClose: () => setModalOpen(false)
       }, undefined, false, undefined, this)
     ]
   }, undefined, true, undefined, this);
 }
 function App({ logMode = false, theme = "tokyonight" }) {
-  return /* @__PURE__ */ jsxDEV19(ThemeProvider, {
+  return /* @__PURE__ */ jsxDEV20(ThemeProvider, {
     name: theme,
-    children: /* @__PURE__ */ jsxDEV19(ModalProvider, {
-      children: /* @__PURE__ */ jsxDEV19(AppProvider, {
+    children: /* @__PURE__ */ jsxDEV20(ModalProvider, {
+      children: /* @__PURE__ */ jsxDEV20(AppProvider, {
         logMode,
-        children: /* @__PURE__ */ jsxDEV19(Shell, {}, undefined, false, undefined, this)
+        children: /* @__PURE__ */ jsxDEV20(Shell, {}, undefined, false, undefined, this)
       }, undefined, false, undefined, this)
     }, undefined, false, undefined, this)
   }, undefined, false, undefined, this);
@@ -6044,6 +6493,7 @@ var init_App = __esm(() => {
   init_AddCustomScreen();
   init_AddModelsScreen();
   init_ListProvidersScreen();
+  init_FAQScreen();
 });
 
 // src/tui/index.tsx
@@ -6053,7 +6503,7 @@ __export(exports_tui, {
 });
 import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
-import { jsxDEV as jsxDEV20 } from "@opentui/react/jsx-dev-runtime";
+import { jsxDEV as jsxDEV21 } from "@opentui/react/jsx-dev-runtime";
 async function startTui(logMode = false) {
   const { readThemeFromConfig: readThemeFromConfig2 } = await Promise.resolve().then(() => (init_ai_config(), exports_ai_config));
   const theme = await readThemeFromConfig2();
@@ -6070,7 +6520,7 @@ async function startTui(logMode = false) {
     renderer.destroy();
     process.exit(0);
   });
-  createRoot(renderer).render(/* @__PURE__ */ jsxDEV20(App, {
+  createRoot(renderer).render(/* @__PURE__ */ jsxDEV21(App, {
     logMode,
     theme
   }, undefined, false, undefined, this));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-speedometer",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "A comprehensive CLI tool for benchmarking AI models across multiple providers with parallel execution and professional metrics",
   "bin": {
     "ai-speedometer": "dist/ai-speedometer",