feat(ui): info tooltips, help modal, more visible verdict box

- Add (ⓘ) info icon next to every form field with hover tooltip
explaining the parameter (theta, T_train, n_kv_heads, etc.)
- Add 📘 Help button in header opening modal with full manual:
what each recipe does, how to add models, parameter glossary,
privacy notes, what verdicts mean.
- Make verdict box much more prominent: bigger text (1.6rem),
emoji prefix (✅/❌/⚠), thicker border, more padding.
- Improve verdict-class detection for all verdict strings
(YES/NO/GO/MEMORY-LIMITED/TINY-MODEL/USE SOFT/etc.)
- Add console.log debug in renderResult to diagnose if verdict
rendering fails (helps users report bugs).
- Defensive null-checks on verdict/recipe_id/recipe_name fields.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

index.html

@@ -17,15 +17,120 @@
     <p class="subtle">
       All computation happens locally — your data never leaves this page.
     </p>
+    <p style="margin-top: 0.75rem;">
+      <button id="help-btn" type="button">📘 Help & examples</button>
+    </p>
   </header>
 
+  <!-- Help modal -->
+  <div id="help-modal">
+    <div class="help-content">
+      <button class="help-close" id="help-close">×</button>
+      <h2>📘 TAF Agent — User Manual</h2>
+
+      <h3>What does it do?</h3>
+      <p>Predicts <strong>practical viability</strong> of any transformer LLM <em>before you spend GPU/$</em>.
+      Answers questions like "will this model work at L=32K?" or "should I train custom or use API?" using
+      deterministic Python formulas (TAF — Thermodynamic Attention Framework).</p>
+
+      <h3>How to use — 2 modes</h3>
+      <p><strong>💬 Ask in plain English</strong> (default): type your question, the in-browser LLM picks
+      the right recipe and runs it. Best for casual exploration.</p>
+      <p><strong>📋 Pick recipe + form</strong>: select a recipe manually, fill the parameters, run.
+      Best when you want full control or know exactly what you need.</p>
+
+      <h3>The 5 recipes available</h3>
+
+      <p><strong>X-1 Custom training vs API</strong> — compares cost of training your own model vs paying for API access.</p>
+      <div class="help-example">
+        Try: <em>"Should I train an 8B custom model or use GPT-4o for 50M tokens/month?"</em><br>
+        Answer types: YES (custom) / NO (API) with break-even months.
+      </div>
+
+      <p><strong>X-2 Long Context Viability</strong> — predicts if a model serves a target context length reliably.</p>
+      <div class="help-example">
+        Try: <em>"Will Meta-Llama-3-8B handle 32000 tokens for retrieval?"</em><br>
+        Chains: γ_Padé → decomposition → d_horizon → NIAH ceiling → hallucination → KV memory.<br>
+        Verdict: YES / DEGRADED / NO with mitigation if needed.
+      </div>
+
+      <p><strong>X-3 Budget pre-flight</strong> — given $ budget, what model is feasible to train?</p>
+      <div class="help-example">
+        Try: <em>"I have $5000, what model can I train?"</em><br>
+        Answer: GO / TINY-MODEL / MEMORY-LIMITED with concrete N (params) and D (tokens).
+      </div>
+
+      <p><strong>X-5 Hardware selection</strong> — which GPU should I use to serve at target throughput?</p>
+      <div class="help-example">
+        Try: <em>"Cheapest hardware to serve Llama-3-8B at 10M tokens/day"</em><br>
+        Answer: best GPU + $/Mtok + capacity vs target.
+      </div>
+
+      <p><strong>X-19 KV Compression decision</strong> — should I use soft decay, hard cutoff, or literature methods?</p>
+      <div class="help-example">
+        Try: <em>"How to compress KV cache for Qwen2.5-7B at 32K?"</em><br>
+        Answer: USE SOFT DECAY / USE D_f CUTOFF / USE LITERATURE METHODS / USE HARD T_train.
+      </div>
+
+      <h3>Adding new models</h3>
+      <ul>
+        <li><strong>Preset list</strong>: 11 popular models curated. Just select from dropdown.</li>
+        <li><strong>HF Hub fetch</strong>: paste any model id (e.g. <code>Qwen/Qwen2.5-32B-Instruct</code>),
+          click 📥 Fetch. Browser downloads <code>config.json</code> directly from HuggingFace,
+          fills the form. Works for any public model.</li>
+        <li><strong>Manual</strong>: fill the form fields directly with values from the model card.</li>
+      </ul>
+
+      <h3>The audit chain</h3>
+      <p>Every result shows the full <strong>Computation Chain</strong> — each formula step with its inputs,
+      output, and interpretation. Click any step to expand. Cite section numbers (§26.1, §19.1, etc.) refer
+      to the underlying paper for derivation.</p>
+
+      <h3>The plain-English answer</h3>
+      <p>After the deterministic chain runs, an in-browser LLM (Qwen2.5-0.5B, ~350MB cached after first load)
+      synthesizes a plain-English summary. The numbers above are <em>always correct</em> (deterministic Python);
+      the synthesis is LLM-generated — verify against the chain if in doubt.</p>
+
+      <h3>Common parameters explained</h3>
+      <ul>
+        <li><strong>θ (rope_theta)</strong>: RoPE base frequency. Higher = more long-range capacity.
+          Typical: 10000 (early), 500000 (Llama-3), 1000000 (Qwen2.5).</li>
+        <li><strong>T_train</strong>: max context the model was trained on. From <code>max_position_embeddings</code>.</li>
+        <li><strong>T_eval</strong>: <em>your target</em> inference context length. The key knob.</li>
+        <li><strong>n_kv_heads &lt; n_attention_heads</strong>: model uses GQA (Grouped Query Attention).
+          Reduces KV memory but pushes γ toward Hagedorn.</li>
+        <li><strong>has_SWA</strong>: model uses Sliding Window Attention (Mistral, gemma-2).</li>
+        <li><strong>n_params</strong>: total parameter count. Threshold ~400M for induction-head emergence.</li>
+      </ul>
+
+      <h3>What to look for in verdicts</h3>
+      <ul>
+        <li><strong style="color:#3fb950;">YES / GO</strong> — proceed with confidence; numbers support the choice.</li>
+        <li><strong style="color:#d29922;">DEGRADED / TINY-MODEL</strong> — works but with caveats; read the action.</li>
+        <li><strong style="color:#f85149;">NO / MEMORY-LIMITED</strong> — don't proceed as-is; mitigation provided.</li>
+      </ul>
+
+      <h3>Privacy</h3>
+      <p>Everything runs in your browser. No telemetry, no analytics, no data sent anywhere. Even the LLM model
+      runs locally via WebGPU/WebAssembly. Your model_ids and questions never leave this page.</p>
+
+      <h3>Source & paper</h3>
+      <p>Source code: <a href="https://github.com/karlesmarin/tafagent" target="_blank">github.com/karlesmarin/tafagent</a><br>
+      Paper: <em>Marin 2026 — Transformer Thermodynamics</em> (arXiv forthcoming)</p>
+    </div>
+  </div>
+
   <main>
     <!-- Status -->
     <section id="status-bar"><div id="status">⏳ Loading Python runtime...</div></section>
 
     <!-- Mode toggle -->
     <section id="mode-section">
-      <h2>🎯 Mode</h2>
+      <h2>🎯 Mode <span class="info"><span class="tooltip"><strong>Two ways to use the tool</strong>.<br>
+        <strong>Ask</strong>: free-form question, browser LLM picks the right recipe.<br>
+        <strong>Recipe</strong>: manual selection with full form control.<br>
+        Same result either way — pick whichever fits your style.
+        </span></span></h2>
       <div class="mode-tabs">
         <button class="mode-btn active" data-mode="ask">💬 Ask in plain English</button>
         <button class="mode-btn" data-mode="recipe">📋 Pick recipe + fill form</button>

js/main.js

@@ -131,15 +131,23 @@ function buildDynamicForm(recipe) {
   recipe.params.forEach(name => {
     const div = document.createElement("div");
     div.className = "form-field";
-    const label = document.createElement("label");
-    label.textContent = paramLabel(name);
-    label.htmlFor = `param_${name}`;
+
+    const labelWrap = document.createElement("label");
+    labelWrap.htmlFor = `param_${name}`;
+    labelWrap.innerHTML = paramLabel(name);
+    if (PARAM_TOOLTIPS[name]) {
+      const info = document.createElement("span");
+      info.className = "info";
+      info.innerHTML = `<span class="tooltip">${PARAM_TOOLTIPS[name]}</span>`;
+      labelWrap.appendChild(info);
+    }
+    div.appendChild(labelWrap);
+
     const input = document.createElement("input");
     input.type = "text";
     input.id = `param_${name}`;
     input.dataset.param = name;
     input.value = defaults[name] !== undefined ? String(defaults[name]) : "";
-    div.appendChild(label);
     div.appendChild(input);
     container.appendChild(div);
   });
@@ -161,6 +169,29 @@ function paramLabel(name) {
   return labels[name] || name;
 }
 
+const PARAM_TOOLTIPS = {
+  theta: "<strong>RoPE base frequency</strong>. From <code>config.rope_theta</code>. Higher = more long-range capacity. Typical: <code>10000</code> early models, <code>500000</code> Llama-3, <code>1000000</code> Qwen2.5.",
+  T_train: "<strong>Max context the model was trained on</strong>. From <code>max_position_embeddings</code>. The model has never seen positions beyond this; extrapolating much further usually fails.",
+  T_eval: "<strong>Your target inference context length</strong>. The key knob. The whole question is: will the model behave well at <em>this</em> length?",
+  n_attention_heads: "Number of query heads. From <code>num_attention_heads</code>.",
+  n_kv_heads: "Number of K/V heads. If &lt; n_attention_heads → model uses GQA (Grouped Query Attention). Smaller = more memory-efficient KV cache but pushes γ toward Hagedorn boundary.",
+  d_head: "Per-head dimension. Typically <code>hidden_size / n_attention_heads</code>. Common: 64, 80, 128.",
+  n_layers: "Number of transformer layers. From <code>num_hidden_layers</code>.",
+  n_params: "<strong>Total parameter count</strong>. Use scientific notation: <code>8e9</code> for 8B. Threshold ~400M is the induction-head emergence boundary (sign-flip in Δγ).",
+  has_SWA: "Sliding Window Attention. <code>true</code> for Mistral, gemma-2, phi-3. SWA lowers γ_decomposition by ~0.21.",
+  N_params: "Same as n_params. Total parameter count, scientific notation (e.g. <code>8e9</code>).",
+  D_tokens: "Number of training tokens. Leave empty to use Chinchilla 20:1 default (D = 20·N).",
+  gpu: "GPU model from the catalog. Options: H100 SXM, H100 PCIe, H200, B200, A100 80GB, A100 40GB, L40S, MI300X, RTX 4090, RTX 5090, RTX 5060Ti.",
+  n_gpus: "Number of GPUs in your training/serving cluster.",
+  mfu: "<strong>Model FLOPs Utilization</strong>. Realistic fraction of peak FLOPs achieved. Typical: 0.4-0.5 for well-tuned. Default 0.45.",
+  api_model: "Frontier API to compare against. Options: GPT-4o, GPT-4o-mini, Claude-Opus-4, Claude-Sonnet-4, Claude-Haiku-4, Gemini-1.5-Pro, DeepSeek-V3, Llama-3.3-70B (Together).",
+  monthly_tokens_M: "Expected monthly token volume <em>in millions</em>. e.g. <code>10</code> = 10 million tokens/month.",
+  USD_budget: "Your training budget in US dollars (no symbol). e.g. <code>5000</code> for $5K.",
+  bytes_per_weight: "Memory per parameter. BF16/FP16 = 2, INT8 = 1, INT4 = 0.5.",
+  target_tokens_per_day: "How many tokens/day you need to serve. e.g. <code>10000000</code> = 10M tokens/day.",
+  concurrent_users: "Simultaneous concurrent requests. Affects KV cache memory needed.",
+};
+
 function getRecipeDefaults(recipeId) {
   const D = {
     "X-1": { N_params: "8e9", D_tokens: "", gpu: "H100 SXM", n_gpus: 8, mfu: 0.45,
@@ -405,6 +436,7 @@ json.dumps(result)
 }
 
 function renderResult(r) {
+  console.log("[TAF] renderResult called with:", r);
   if (r.error) {
     $("verdict-box").className = "verdict-no";
     $("verdict-box").innerHTML = `<strong>Error</strong>: ${escapeHtml(r.error)}`;
@@ -412,21 +444,28 @@ function renderResult(r) {
     return;
   }
   const vBox = $("verdict-box");
+  if (!vBox) {
+    console.error("[TAF] verdict-box element not found!");
+    return;
+  }
+  const verdictStr = String(r.verdict || "UNKNOWN");
   let vClass = "";
-  if (r.verdict.startsWith("YES") || r.verdict === "GO") vClass = "verdict-yes";
-  else if (r.verdict.startsWith("NO")) vClass = "verdict-no";
+  if (verdictStr.startsWith("YES") || verdictStr === "GO" || verdictStr.startsWith("USE SOFT")) vClass = "verdict-yes";
+  else if (verdictStr.startsWith("NO") || verdictStr.startsWith("MEMORY") || verdictStr === "TINY-MODEL") vClass = "verdict-no";
   else vClass = "verdict-degraded";
   vBox.className = vClass;
+  const verdictEmoji = vClass === "verdict-yes" ? "✅" : (vClass === "verdict-no" ? "❌" : "⚠");
   vBox.innerHTML = `
-    <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:0.5rem;">
-      <div style="font-size:1.3rem; font-weight:700;">${escapeHtml(r.verdict)}</div>
-      <div class="recipe-tag">${r.recipe_id} — ${escapeHtml(r.recipe_name)}</div>
+    <div style="display:flex; justify-content:space-between; align-items:center; margin-bottom:0.75rem; gap:1rem; flex-wrap:wrap;">
+      <div style="font-size:1.6rem; font-weight:800;">${verdictEmoji} ${escapeHtml(verdictStr)}</div>
+      <div class="recipe-tag">${escapeHtml(r.recipe_id || "")} — ${escapeHtml(r.recipe_name || "")}</div>
     </div>
-    <div><strong>Reason:</strong> ${escapeHtml(r.reason)}</div>
+    <div style="margin-bottom:0.5rem;"><strong>Reason:</strong> ${escapeHtml(r.reason || "(none)")}</div>
     ${r.mitigation && r.mitigation !== "None required." && r.mitigation !== "None — proceed with Chinchilla-optimal recipe."
-      ? `<div style="margin-top:0.5rem;"><strong>Action:</strong> ${escapeHtml(r.mitigation)}</div>`
+      ? `<div><strong>Action:</strong> ${escapeHtml(r.mitigation)}</div>`
       : ""}
   `;
+  console.log("[TAF] verdict-box populated with class:", vClass, "verdict:", verdictStr);
 
   const cBox = $("chain-box");
   cBox.innerHTML = "";
@@ -567,6 +606,15 @@ function formatResultPlain(r) {
   return String(r);
 }
 
+// ════════════════════════════════════════════════════════════════════
+// Help modal
+// ════════════════════════════════════════════════════════════════════
+$("help-btn").addEventListener("click", () => $("help-modal").classList.add("open"));
+$("help-close").addEventListener("click", () => $("help-modal").classList.remove("open"));
+$("help-modal").addEventListener("click", (e) => {
+  if (e.target.id === "help-modal") $("help-modal").classList.remove("open");
+});
+
 // ════════════════════════════════════════════════════════════════════
 // Bootstrap
 // ════════════════════════════════════════════════════════════════════

style.css

@@ -133,6 +133,117 @@ button:disabled { background: #444; cursor: not-allowed; }
   border-radius: 4px;
 }
 
+/* ─── Info icon + tooltip system ─── */
+.info {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px; height: 16px;
+  border-radius: 50%;
+  background: var(--bg-input);
+  color: var(--accent);
+  border: 1px solid var(--border);
+  font-size: 11px;
+  font-style: italic;
+  font-family: serif;
+  cursor: help;
+  margin-left: 0.3rem;
+  position: relative;
+  user-select: none;
+}
+.info:hover { border-color: var(--accent); background: var(--accent-dim); color: white; }
+.info::before { content: "i"; }
+
+.tooltip {
+  visibility: hidden;
+  opacity: 0;
+  transition: opacity 0.15s, visibility 0.15s;
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 50%;
+  transform: translateX(-50%);
+  background: #1a1f29;
+  color: var(--fg);
+  border: 1px solid var(--accent);
+  border-radius: 6px;
+  padding: 0.6rem 0.8rem;
+  font-size: 0.85rem;
+  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+  font-style: normal;
+  width: 280px;
+  z-index: 100;
+  text-align: left;
+  line-height: 1.5;
+  box-shadow: 0 4px 16px rgba(0,0,0,0.4);
+  pointer-events: none;
+}
+.tooltip strong { color: var(--accent); }
+.tooltip code {
+  background: var(--bg);
+  padding: 0.1rem 0.3rem;
+  border-radius: 3px;
+  font-family: monospace;
+  font-size: 0.85em;
+}
+.info:hover .tooltip { visibility: visible; opacity: 1; }
+.tooltip::after {
+  content: "";
+  position: absolute;
+  top: 100%; left: 50%;
+  margin-left: -6px;
+  border-width: 6px;
+  border-style: solid;
+  border-color: var(--accent) transparent transparent transparent;
+}
+
+/* Make verdict box more prominent */
+#verdict-box {
+  font-size: 1.1rem;
+  padding: 1.5rem;
+  border-radius: 8px;
+  border-left: 6px solid;
+  margin-bottom: 1rem;
+  min-height: 80px;
+}
+.verdict-yes { background: rgba(63, 185, 80, 0.15); border-color: var(--success); }
+.verdict-no { background: rgba(248, 81, 73, 0.15); border-color: var(--danger); }
+.verdict-degraded { background: rgba(210, 153, 34, 0.15); border-color: var(--warning); }
+
+/* Help modal */
+#help-btn {
+  background: transparent; color: var(--accent);
+  border: 1px solid var(--accent); border-radius: 6px;
+  padding: 0.3rem 0.7rem; font-size: 0.85rem;
+}
+#help-btn:hover { background: var(--accent); color: white; }
+#help-modal {
+  display: none; position: fixed; inset: 0;
+  background: rgba(0,0,0,0.7); z-index: 1000;
+  padding: 2rem; overflow-y: auto;
+}
+#help-modal.open { display: flex; align-items: flex-start; justify-content: center; }
+.help-content {
+  background: var(--bg-card); color: var(--fg);
+  max-width: 800px; width: 100%;
+  border: 1px solid var(--accent); border-radius: 12px;
+  padding: 2rem; position: relative;
+}
+.help-close {
+  position: absolute; top: 1rem; right: 1rem;
+  background: var(--bg-input); border: 1px solid var(--border);
+  color: var(--fg); border-radius: 50%;
+  width: 32px; height: 32px; cursor: pointer; font-size: 1.2rem;
+}
+.help-content h3 { color: var(--accent); margin-top: 1.5rem; }
+.help-content code {
+  background: var(--bg-input); padding: 0.1rem 0.4rem;
+  border-radius: 3px; font-family: monospace;
+}
+.help-example {
+  background: var(--bg-input); border-left: 3px solid var(--accent);
+  padding: 0.75rem 1rem; margin: 0.5rem 0; border-radius: 4px;
+}
+
 .mode-tabs { display: flex; gap: 0.5rem; margin-bottom: 0.75rem; flex-wrap: wrap; }
 .mode-btn {
   background: var(--bg-input); color: var(--fg-dim);