From 817b71f69df46ebb793f48b3816d4a011c248a9b Mon Sep 17 00:00:00 2001
From: KoalaTrapLord <265133236+KoalaTrapLord@users.noreply.github.com>
Date: Fri, 27 Mar 2026 02:06:58 -0400
Subject: [PATCH] feat(ui): add tip-icon tooltips to distillation, simulator,
 coach, deckgenerator pages

- distillation.html: tooltips on all 10 params + ELO Ratings header
- simulator.html: tooltips on Opponent, Games, Record logs, API Endpoint, Model, Temp, Timeout
- coach.html: tooltips on Power Level, Meta Focus, Budget, Focus Areas, Similar Cards Results
- deckgenerator.html: tooltips on Target Bracket, Use my collection, Smart Substitution, AI Model
- All pages now share tooltip styles from global.css (no per-page duplication needed)
---
 ui/coach.html         | 31 +++++++++++-----
 ui/deckgenerator.html | 82 +++++++++++++++++--------------------------
 ui/distillation.html  | 56 ++++++++++++++++++++++-------
 ui/simulator.html     | 31 ++++++++++++----
 4 files changed, 125 insertions(+), 75 deletions(-)

diff --git a/ui/coach.html b/ui/coach.html
index 7da2246..1262802 100644
--- a/ui/coach.html
+++ b/ui/coach.html
@@ -58,7 +58,10 @@
 
                 <!-- Power Level Slider -->
                 <div class="form-group">
-                    <label class="form-label" for="coach-power-level">Target Power Level</label>
+                    <label class="form-label" for="coach-power-level">
+                        Target Power Level
+                        <span class="tip-icon tip-below" data-tip="Guides the LLM on how competitive suggestions should be. 1-3 = casual jank; 4-6 = upgraded precon; 7-8 = high power; 9-10 = cEDH with fast mana and infinite combos.">?</span>
+                    </label>
                     <div class="coach-slider-row">
                         <input type="range" id="coach-power-level" min="1" max="10" value="7" />
                         <span class="coach-slider-value" id="coach-power-value">7</span>
@@ -68,7 +71,10 @@
 
                 <!-- Meta Focus -->
                 <div class="form-group">
-                    <label class="form-label" for="coach-meta-focus">Meta Focus</label>
+                    <label class="form-label" for="coach-meta-focus">
+                        Meta Focus
+                        <span class="tip-icon tip-below" data-tip="The game plan the coach optimizes for. Aggro = fast damage; Control = answers and card advantage; Combo = tutors and win-con protection; Stax = slow everyone down.">?</span>
+                    </label>
                     <select id="coach-meta-focus" class="form-select">
                         <option value="">Any / Balanced</option>
                         <option value="aggro">Aggro</option>
@@ -81,7 +87,10 @@
 
                 <!-- Budget -->
                 <div class="form-group">
-                    <label class="form-label" for="coach-budget">Budget</label>
+                    <label class="form-label" for="coach-budget">
+                        Budget
+                        <span class="tip-icon tip-below" data-tip="Restricts suggestions to cards within a price range. Budget caps cards at ~$2 each; Medium at ~$10. No Limit allows any card including Reserved List staples.">?</span>
+                    </label>
                     <select id="coach-budget" class="form-select">
                         <option value="">No Limit</option>
                         <option value="budget">Budget (&lt; $2 per card)</option>
@@ -92,7 +101,10 @@
 
                 <!-- Focus Areas -->
                 <div class="form-group coach-field-wide">
-                    <label class="form-label">Focus Areas (optional)</label>
+                    <label class="form-label">
+                        Focus Areas (optional)
+                        <span class="tip-icon tip-below" data-tip="Narrows the coach to specific deck categories. Leaving all unchecked triggers a full-deck general analysis across all categories.">?</span>
+                    </label>
                     <div class="coach-focus-tags">
                         <label class="coach-tag"><input type="checkbox" value="ramp" /> Ramp</label>
                         <label class="coach-tag"><input type="checkbox" value="card draw" /> Card Draw</label>
@@ -121,7 +133,7 @@
             </div>
         </section>
 
-        <!-- ═══ Multi-turn Chat Panel ═══ -->
+        <!-- Multi-turn Chat Panel -->
         <section class="panel coach-chat-section" id="coach-chat-section">
             <div class="panel-header coach-chat-header">
                 <h2>Chat with Coach</h2>
@@ -143,7 +155,7 @@
             </div>
         </section>
 
-        <!-- ═══ Cards-Like Search Panel ═══ -->
+        <!-- Cards-Like Search Panel -->
         <section class="panel coach-cardslike-section" id="coach-cardslike-section">
             <div class="panel-header coach-panel-collapsible" id="cardslike-header">
                 <h2>Find Similar Cards</h2>
@@ -163,7 +175,10 @@
                             <button class="coach-color-pip coach-pip-G" data-color="G" title="Green">G</button>
                         </div>
                         <div class="form-group coach-cardslike-topn">
-                            <label class="form-label">Results</label>
+                            <label class="form-label">
+                                Results
+                                <span class="tip-icon tip-below" data-tip="How many similar cards to return. Uses vector embeddings to find cards with the most semantically similar oracle text and mechanics to your query card.">?</span>
+                            </label>
                             <input type="number" id="cardslike-topn" class="form-input" value="10" min="1" max="50" />
                         </div>
                         <button id="cardslike-search-btn" class="btn btn-accent btn-sm">Search</button>
@@ -173,7 +188,7 @@
             </div>
         </section>
 
-        <!-- ═══ One-Shot Results Section ═══ -->
+        <!-- One-Shot Results Section -->
         <section id="coach-results" class="coach-results" style="display:none;">
 
             <!-- Apply Suggestions Bar -->
diff --git a/ui/deckgenerator.html b/ui/deckgenerator.html
index 27c1fa8..1f6ca15 100644
--- a/ui/deckgenerator.html
+++ b/ui/deckgenerator.html
@@ -62,9 +62,13 @@
                             class="dg-input"
                             id="dg-strategy"
                             placeholder="e.g. zombie tokens, voltron, spellslinger..."
+                            title="Describe your deck strategy — the AI uses this to pick thematically aligned cards"
                         />
                         <div class="dg-bracket-row">
-                            <label class="dg-label">Target Bracket</label>
+                            <label class="dg-label">
+                                Target Bracket
+                                <span class="tip-icon" data-tip="B1 = precon-level casual. B2 = upgraded with synergies. B3 = high power with strong combos. B4 = cEDH with maximum optimization, fast mana, and instant-speed interaction.">?</span>
+                            </label>
                             <div class="dg-bracket-btns" id="dg-bracket-btns">
                                 <button class="dg-bracket-btn" data-bracket="1" title="Casual — precon level">B1</button>
                                 <button class="dg-bracket-btn" data-bracket="2" title="Upgraded Casual">B2</button>
@@ -105,7 +109,7 @@
                                 min="0"
                                 step="25"
                             />
-                            <select class="dg-select" id="dg-budget-mode">
+                            <select class="dg-select" id="dg-budget-mode" title="Total Deck: caps the combined price of all 100 cards. Per Card Max: caps each individual card price.">
                                 <option value="total">Total Deck $</option>
                                 <option value="per_card">Per Card Max $</option>
                             </select>
@@ -120,25 +124,34 @@
                     </div>
                     <div class="dg-panel-body">
                         <label class="dg-toggle-row">
-                            <span class="dg-toggle-label">Use my collection</span>
+                            <span class="dg-toggle-label">
+                                Use my collection
+                                <span class="tip-icon" data-tip="Prioritizes cards you already own before pulling from the full card pool. Saves money and ensures the deck is ready to play. Requires an imported collection.">?</span>
+                            </span>
                             <input type="checkbox" class="dg-toggle-check" id="dg-use-collection" checked />
                             <span class="dg-toggle-track"><span class="dg-toggle-thumb"></span></span>
                         </label>
                         <label class="dg-toggle-row">
-                            <span class="dg-toggle-label">Smart Substitution</span>
+                            <span class="dg-toggle-label">
+                                Smart Substitution
+                                <span class="tip-icon" data-tip="When a suggested card isn't in your collection, automatically finds the closest functional replacement you do own. Keeps the deck playable without buying extra cards.">?</span>
+                            </span>
                             <input type="checkbox" class="dg-toggle-check" id="dg-substitution" checked />
                             <span class="dg-toggle-track"><span class="dg-toggle-thumb"></span></span>
                         </label>
                         <div class="dg-model-row">
-                            <label class="dg-label">AI Model</label>
+                            <label class="dg-label">
+                                AI Model
+                                <span class="tip-icon" data-tip="The local LLM used to generate the deck list. Larger models produce better card selections but are slower. Requires Ollama running locally with the selected model pulled.">?</span>
+                            </label>
                             <select class="dg-select" id="dg-model">
-                                                        <option value="gpt-oss:20b" selected>gpt-oss:20b (Local Ollama)</option>
+                                <option value="gpt-oss:20b" selected>gpt-oss:20b (Local Ollama)</option>
                             </select>
                         </div>
                     </div>
                 </div>
 
-                                <!-- Omit Cards (chips input) -->
+                <!-- Omit Cards (chips input) -->
                 <div class="dg-panel">
                     <div class="dg-panel-header">
                         <span class="dg-panel-title">Omit Cards</span>
@@ -160,12 +173,12 @@
                 <!-- Action Buttons -->
                 <div class="dg-actions">
                     <button class="dg-btn dg-btn-preview" id="dg-preview-btn" disabled>
-                        <span class="dg-btn-icon">⚡</span> Generate Deck
+                        <span class="dg-btn-icon">&#9889;</span> Generate Deck
                     </button>
                 </div>
 
-                            <!-- Conversation Log -->
-                                             <div id="dg-conversation-log" class="dg-conversation-log">
+                <!-- Conversation Log -->
+                <div id="dg-conversation-log" class="dg-conversation-log">
                     <div class="dg-log-entry dg-log-info"><span class="dg-log-ts">[Ready]</span> Waiting for deck generation...</div>
                 </div>
 
@@ -175,7 +188,7 @@
             <section class="dg-col-results">
                 <!-- Empty State -->
                 <div class="dg-empty-state" id="dg-empty-state">
-                    <div class="dg-empty-icon">⚡</div>
+                    <div class="dg-empty-icon">&#9889;</div>
                     <div class="dg-empty-title">V3 AI Deck Generator</div>
                     <div class="dg-empty-text">Select a commander, set your bracket and strategy, then click "Generate Deck" to build a complete 100-card deck using Claude Opus with structured output.</div>
                 </div>
@@ -185,47 +198,18 @@
                     <div class="dg-spinner"></div>
                     <div class="dg-loading-text" id="dg-loading-text">Generating deck via Local AI...</div>
                 </div>
-                                    <div class="dg-progress-wrap" id="dg-progress-wrap" style="display:none">
-                        <div class="dg-progress-bar">
-                            <div class="dg-progress-fill" id="dg-progress-fill"></div>
-                        </div>
-                        <div class="dg-progress-meta">
-                            <span class="dg-progress-phase" id="dg-progress-phase"></span>
-                            <span class="dg-progress-elapsed" id="dg-progress-elapsed">0s elapsed</span>
-                        </div>
+                <div class="dg-progress-wrap" id="dg-progress-wrap" style="display:none">
+                    <div class="dg-progress-bar">
+                        <div class="dg-progress-fill" id="dg-progress-fill"></div>
                     </div>
-
-                <!-- Results -->
-                <div class="dg-results" id="dg-results" style="display:none">
-
-                    <!-- Strategy & Bracket Summary -->
-                    <div class="dg-strategy-bar" id="dg-strategy-bar"></div>
-
-                    <!-- Stats Bar -->
-                    <div class="dg-stats-bar" id="dg-stats-bar"></div>
-
-                    <!-- Substitution Summary -->
-                    <div class="dg-sub-summary" id="dg-sub-summary" style="display:none"></div>
-
-                    <!-- Card Groups -->
-                    <div class="dg-card-groups" id="dg-card-groups"></div>
-
-                    <!-- Export & Save Bar -->
-                    <div class="dg-save-bar" id="dg-save-bar">
-                        <button class="dg-btn dg-btn-save" id="dg-save-btn">
-                            <span class="dg-btn-icon">💾</span> Save to Deck Builder
-                        </button>
-                        <button class="dg-btn dg-btn-ghost" id="dg-regenerate-btn">
-                            <span class="dg-btn-icon">🔄</span> Regenerate
-                        </button>
-                        <div class="dg-export-group">
-                            <button class="dg-btn dg-btn-export" id="dg-export-csv">📊 CSV</button>
-                            <button class="dg-btn dg-btn-export" id="dg-export-dck">🎮 Forge .dck</button>
-                            <button class="dg-btn dg-btn-export" id="dg-export-moxfield">📋 Moxfield</button>
-                            <button class="dg-btn dg-btn-export" id="dg-export-shopping">🛒 Shopping List</button>
-                        </div>
+                    <div class="dg-progress-meta">
+                        <span class="dg-progress-phase" id="dg-progress-phase"></span>
+                        <span class="dg-progress-elapsed" id="dg-progress-elapsed">0s elapsed</span>
                     </div>
                 </div>
+
+                <!-- Results placeholder — rest generated dynamically by deckgenerator.js -->
+                <div class="dg-results" id="dg-results" style="display:none"></div>
             </section>
 
         </main>
diff --git a/ui/distillation.html b/ui/distillation.html
index 83ebfdb..63cba6a 100644
--- a/ui/distillation.html
+++ b/ui/distillation.html
@@ -16,7 +16,7 @@
         <div class="page-header" style="display:flex;align-items:center;justify-content:space-between;">
             <div>
                 <h1>Closed-Loop Distillation</h1>
-                <p>Iterative supervised → PPO → quality gate → merge pipeline</p>
+                <p>Iterative supervised &rarr; PPO &rarr; quality gate &rarr; merge pipeline</p>
             </div>
             <button id="btn-refresh" class="btn btn-secondary" onclick="refreshAll()" title="Refresh status">
                 <span class="btn-icon" id="refresh-icon">&#8635;</span> Refresh
@@ -59,43 +59,70 @@
             <div class="train-controls">
                 <div class="param-grid form-row">
                     <div class="form-group">
-                        <label class="form-label" for="param-iterations">Max Generations</label>
+                        <label class="form-label" for="param-iterations">
+                            Max Generations
+                            <span class="tip-icon" data-tip="How many distillation cycles to run. Each cycle: supervised train &rarr; PPO fine-tune &rarr; quality gate. Stops early if convergence is detected.">?</span>
+                        </label>
                         <input type="number" id="param-iterations" class="form-input" value="10" min="1" max="100" />
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-conv-window">Convergence Window</label>
+                        <label class="form-label" for="param-conv-window">
+                            Convergence Window
+                            <span class="tip-icon" data-tip="Number of recent generations to check for plateau. If ELO gain stays below threshold across this many gens, training stops early to save time.">?</span>
+                        </label>
                         <input type="number" id="param-conv-window" class="form-input" value="3" min="2" max="10" />
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-sup-epochs">Supervised Epochs</label>
+                        <label class="form-label" for="param-sup-epochs">
+                            Supervised Epochs
+                            <span class="tip-icon" data-tip="Training epochs for the supervised step each generation. Fewer is fine since each cycle trains on incrementally better data. 30 is a solid starting point.">?</span>
+                        </label>
                         <input type="number" id="param-sup-epochs" class="form-input" value="30" min="5" max="200" />
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-sup-lr">Supervised LR</label>
+                        <label class="form-label" for="param-sup-lr">
+                            Supervised LR
+                            <span class="tip-icon" data-tip="Learning rate for the supervised phase. 0.001 is a solid default. Lower it in later generations if the model is already strong.">?</span>
+                        </label>
                         <input type="number" id="param-sup-lr" class="form-input" value="0.001" step="0.0001" min="0.00001" max="0.1" />
                     </div>
                 </div>
                 <div class="param-grid form-row">
                     <div class="form-group">
-                        <label class="form-label" for="param-ppo-iters">PPO Iterations</label>
+                        <label class="form-label" for="param-ppo-iters">
+                            PPO Iterations
+                            <span class="tip-icon" data-tip="Number of PPO update steps per generation. Each step samples game episodes, computes advantages, and updates policy weights.">?</span>
+                        </label>
                         <input type="number" id="param-ppo-iters" class="form-input" value="50" min="10" max="500" />
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-ppo-episodes">PPO Episodes/Iter</label>
+                        <label class="form-label" for="param-ppo-episodes">
+                            PPO Episodes/Iter
+                            <span class="tip-icon" data-tip="Game simulations per PPO update step. More episodes = more stable gradients but slower iterations. 64 balances speed and stability well.">?</span>
+                        </label>
                         <input type="number" id="param-ppo-episodes" class="form-input" value="64" min="8" max="512" step="8" />
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-ppo-lr">PPO Learning Rate</label>
+                        <label class="form-label" for="param-ppo-lr">
+                            PPO Learning Rate
+                            <span class="tip-icon" data-tip="PPO step size. Keep this lower than the supervised LR. 0.0003 is the standard RL default and works well here.">?</span>
+                        </label>
                         <input type="number" id="param-ppo-lr" class="form-input" value="0.0003" step="0.0001" min="0.00001" max="0.01" />
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-min-wr">Min Win Rate Gate</label>
+                        <label class="form-label" for="param-min-wr">
+                            Min Win Rate Gate
+                            <span class="tip-icon" data-tip="Quality gate threshold. A generation must beat the heuristic opponent at this win rate to be accepted and merged into the next cycle. 0.30 is a lenient starting gate.">?</span>
+                        </label>
                         <input type="number" id="param-min-wr" class="form-input" value="0.30" step="0.05" min="0.1" max="0.9" />
                     </div>
                 </div>
                 <div class="param-grid form-row distill-bottom-params">
                     <div class="form-group">
-                        <label class="form-label" for="param-opponent">Opponent</label>
+                        <label class="form-label" for="param-opponent">
+                            Opponent
+                            <span class="tip-icon" data-tip="Who the agent trains against during PPO. Heuristic is recommended for a consistent challenge. Self-play can become unstable without a strong supervised baseline first.">?</span>
+                        </label>
                         <select id="param-opponent" class="form-select">
                             <option value="heuristic">Heuristic</option>
                             <option value="random">Random</option>
@@ -103,7 +130,10 @@
                         </select>
                     </div>
                     <div class="form-group">
-                        <label class="form-label" for="param-playstyle">Playstyle</label>
+                        <label class="form-label" for="param-playstyle">
+                            Playstyle
+                            <span class="tip-icon" data-tip="Deck archetype used for simulations in this distillation run. Midrange is the most balanced test bed. Match this to the archetype you want the model to master.">?</span>
+                        </label>
                         <select id="param-playstyle" class="form-select">
                             <option value="midrange">Midrange</option>
                             <option value="aggro">Aggro</option>
@@ -164,7 +194,9 @@
         <!-- ELO Rating Chart -->
         <section class="panel" id="elo-panel">
             <div class="panel-header elo-panel-header">
-                <h2>ELO Ratings</h2>
+                <h2>ELO Ratings
+                    <span class="tip-icon tip-below" data-tip="ELO scores measure relative strength. Baseline is 1200. Scores above that mean the model wins more than it loses. Tournament runs the top 10 most recent checkpoints head-to-head.">?</span>
+                </h2>
                 <button id="btn-run-elo" class="btn btn-sm btn-secondary" onclick="runEloTournament()">
                     <span class="btn-icon">&#127942;</span> Run Tournament
                 </button>
diff --git a/ui/simulator.html b/ui/simulator.html
index d3bcc4e..cbd24e0 100644
--- a/ui/simulator.html
+++ b/ui/simulator.html
@@ -28,20 +28,27 @@
                     </select>
                 </div>
                 <div class="form-group sim-field-auto">
-                    <label class="form-label" for="sim-opponent-select">Opponent</label>
+                    <label class="form-label" for="sim-opponent-select">
+                        Opponent
+                        <span class="tip-icon tip-below" data-tip="Heuristic AI uses rule-based logic — fast and deterministic. DeepSeek AI routes decisions through your local Ollama LLM for smarter but slower play.">?</span>
+                    </label>
                     <select id="sim-opponent-select" class="form-select">
                         <option value="heuristic">Heuristic AI</option>
                         <option value="deepseek">DeepSeek AI</option>
                     </select>
                 </div>
                 <div class="form-group sim-field-auto">
-                    <label class="form-label" for="sim-num-games">Games</label>
+                    <label class="form-label" for="sim-num-games">
+                        Games
+                        <span class="tip-icon tip-below" data-tip="Number of games to simulate. 10 is quick for a gut-check; 100+ gives statistically meaningful win rates. Each game is fully simulated end-to-end.">?</span>
+                    </label>
                     <input type="number" id="sim-num-games" class="form-input sim-num-input" value="10" min="1" max="1000" />
                 </div>
                 <div class="form-group sim-field-auto sim-field-end">
                     <label class="form-checkbox">
                         <input type="checkbox" id="sim-record-logs" checked />
                         Record turn logs
+                        <span class="tip-icon tip-below" data-tip="Saves per-turn decision snapshots to .jsonl files. Required for ML training data collection. Slightly slower — disable if you only need win rate stats.">?</span>
                     </label>
                 </div>
                 <div class="form-group sim-field-auto sim-field-end">
@@ -61,19 +68,31 @@
                 </div>
                 <div class="deepseek-config-row">
                     <div class="form-group sim-field-grow">
-                        <label class="form-label" for="ds-api-base">API Endpoint</label>
+                        <label class="form-label" for="ds-api-base">
+                            API Endpoint
+                            <span class="tip-icon tip-below" data-tip="Base URL of your Ollama server. Default is localhost:11434. Change this if Ollama is running on a different machine or WSL2 network address.">?</span>
+                        </label>
                         <input type="text" id="ds-api-base" class="form-input" value="http://localhost:11434" placeholder="http://localhost:11434" />
                     </div>
                     <div class="form-group sim-field-auto">
-                        <label class="form-label" for="ds-model">Model</label>
+                        <label class="form-label" for="ds-model">
+                            Model
+                            <span class="tip-icon tip-below" data-tip="Ollama model tag to use for AI decisions. Leave blank to auto-detect the best available model. Examples: deepseek-r1:7b, llama3:8b, mistral.">?</span>
+                        </label>
                         <input type="text" id="ds-model" class="form-input" value="" placeholder="Auto-detect" style="width:200px" />
                     </div>
                     <div class="form-group sim-field-auto">
-                        <label class="form-label" for="ds-temp">Temp</label>
+                        <label class="form-label" for="ds-temp">
+                            Temp
+                            <span class="tip-icon tip-below" data-tip="LLM sampling temperature. Lower = more deterministic decisions. 0.3 is a good balance — fully greedy (0.0) can get stuck in repetitive play patterns.">?</span>
+                        </label>
                         <input type="number" id="ds-temp" class="form-input sim-num-input" value="0.3" min="0" max="2" step="0.1" />
                     </div>
                     <div class="form-group sim-field-auto">
-                        <label class="form-label" for="ds-timeout">Timeout (s)</label>
+                        <label class="form-label" for="ds-timeout">
+                            Timeout (s)
+                            <span class="tip-icon tip-below" data-tip="Max seconds to wait for an LLM response per decision. If exceeded, falls back to heuristic AI automatically. Increase if your GPU is slow on cold inference.">?</span>
+                        </label>
                         <input type="number" id="ds-timeout" class="form-input sim-num-input" value="10" min="1" max="60" />
                     </div>
                 </div>