claude-session-insights 0.3.2 → 0.4.0

package/README.md

@@ -10,6 +10,7 @@ Think "Spotify Wrapped" for your Claude Code usage — scores, summaries, badges
 - **Overall Summary** — natural-language assessment of your prompting habits with specific recommendations
 - **Per-Session Summary** — each session gets a plain-English breakdown of what happened, what went well, and what could improve
 - **Session Drill-down** — click any session to see the full conversation timeline with per-turn token counts, costs, tool calls, and prompt previews
+- **Workflow Optimizer** — analyzes your session patterns and recommends Claude Code setup improvements: skills to create, CLAUDE.md files to write, and subagents to configure. Optional AI generation produces ready-to-copy artifact content (full CLAUDE.md text, skill prompt bodies, agent configs)
 - **AI Insights** — on-demand deeper analysis powered by the Claude CLI, with model picker (Sonnet, Opus, Haiku) and streaming output
 - **Heaviest Sessions** — top sessions ranked by cost for quick identification of expensive outliers
 - **Daily Score Chart** — trend visualization of your efficiency score, session count, tokens, and cost over time
@@ -76,6 +77,19 @@ The dashboard generates rule-based summaries at two levels:
 
 **Per-session** — classifies each session (quick fix, focused task, long refactor), identifies the main cost driver, and highlights strengths. Displayed at the top of the session detail view.
 
+## Workflow Optimizer
+
+Closes the loop from "how am I doing?" to "here's what to build to do better." The optimizer runs two phases:
+
+**Phase 1 — Rule-based suggestions (instant):** Detects patterns from your badges, tool usage, session titles, and project history to recommend:
+
+- **Skills** — slash commands to create in `~/.claude/skills/`. Example: if you have the Vague Commander badge, it suggests a `/spec` skill to help you write thorough task specs before Claude starts working
+- **CLAUDE.md** — project-scoped or global config files to reduce repeated explanations. Triggered by projects with 5+ sessions, the Context Hoarder badge, Opus overuse, etc.
+- **Agents** — subagent configurations for offloading exploration or repetitive task types
+- **Plugins** — MCP servers only where CLI tools have a genuine capability gap (e.g. Playwright for browser tasks, not tools with good CLI equivalents that would just add context overhead)
+
+**Phase 2 — AI content generation (optional):** Click "Generate artifact content with AI" to stream ready-to-copy content for each suggestion — the actual CLAUDE.md file, the real skill prompt body, agent configuration — not just a description of what to build.
+
 ## AI Insights
 
 Click "Generate AI Insights" to run a deeper analysis using the Claude CLI. This streams a response via SSE that covers:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-session-insights",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Analyze Claude Code sessions for efficiency insights, scores, and team metrics",
   "type": "module",
   "bin": {

package/public/index.html

@@ -645,6 +645,129 @@
   }
   .ai-prompt-close:hover { color: var(--text); }
 
+  /* Workflow Optimizer */
+  .optimizer-card {
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: var(--radius); padding: 24px 28px; margin-bottom: 24px;
+    position: relative; overflow: visible; box-shadow: var(--shadow-card);
+  }
+  .optimizer-card::before {
+    content: ''; position: absolute; top: 0; left: 0; right: 0; height: 2px;
+    background: linear-gradient(90deg, var(--accent), var(--green));
+    opacity: 0.7; border-radius: var(--radius) var(--radius) 0 0;
+  }
+  .optimizer-card h3 {
+    font-size: 11px; text-transform: uppercase; letter-spacing: 0.8px;
+    color: var(--accent); margin-bottom: 14px; font-weight: 600;
+    display: flex; align-items: center; gap: 8px;
+  }
+  .optimizer-tabs {
+    display: flex; gap: 4px; margin-bottom: 16px; flex-wrap: wrap;
+  }
+  .optimizer-tab {
+    padding: 5px 12px; border-radius: 6px; border: 1px solid var(--border);
+    background: var(--surface2); color: var(--text2); font-size: 11px;
+    font-weight: 500; cursor: pointer; transition: all 0.15s;
+  }
+  .optimizer-tab:hover { background: var(--surface3); color: var(--text); }
+  .optimizer-tab.active {
+    background: var(--accent-dim); border-color: rgba(37,99,235,0.3);
+    color: var(--accent); font-weight: 600;
+  }
+  .optimizer-tab .tab-count {
+    display: inline-block; min-width: 16px; height: 16px; border-radius: 8px;
+    background: var(--surface3); color: var(--text3); font-size: 10px;
+    text-align: center; line-height: 16px; margin-left: 4px;
+  }
+  .optimizer-tab.active .tab-count {
+    background: rgba(37,99,235,0.2); color: var(--accent);
+  }
+  .optimizer-panel { display: none; }
+  .optimizer-panel.active { display: block; }
+  .suggestion-empty {
+    color: var(--text3); font-size: 13px; padding: 16px 0;
+    display: flex; align-items: center; gap: 8px;
+  }
+  .suggestion-card {
+    border: 1px solid var(--border); border-radius: 8px; padding: 14px 16px;
+    margin-bottom: 10px; background: var(--surface2);
+    transition: border-color 0.15s;
+  }
+  .suggestion-card:last-child { margin-bottom: 0; }
+  .suggestion-card:hover { border-color: var(--border-hover); }
+  .suggestion-header {
+    display: flex; align-items: flex-start; justify-content: space-between; gap: 10px;
+    margin-bottom: 6px;
+  }
+  .suggestion-title { font-size: 13px; font-weight: 600; color: var(--text); flex: 1; }
+  .suggestion-priority {
+    font-size: 10px; font-weight: 600; padding: 2px 8px; border-radius: 10px;
+    white-space: nowrap; flex-shrink: 0;
+  }
+  .priority-high { background: var(--red-dim); color: var(--red); }
+  .priority-medium { background: var(--yellow-dim); color: var(--yellow); }
+  .priority-low { background: var(--surface3); color: var(--text3); }
+  .suggestion-rationale {
+    font-size: 12px; color: var(--text2); line-height: 1.6; margin-bottom: 8px;
+  }
+  .suggestion-meta {
+    font-size: 11px; color: var(--text3); font-family: var(--mono);
+    display: flex; gap: 12px; flex-wrap: wrap;
+  }
+  .suggestion-meta span { display: flex; align-items: center; gap: 4px; }
+  .optimizer-ai-section {
+    margin-top: 20px; padding-top: 16px; border-top: 1px solid var(--border);
+  }
+  .optimizer-ai-controls {
+    display: flex; align-items: center; gap: 10px; flex-wrap: wrap; margin-bottom: 12px;
+  }
+  .optimizer-generate-btn {
+    background: var(--accent-dim); border: 1px solid rgba(37,99,235,0.2);
+    color: var(--accent); padding: 8px 16px; border-radius: 7px;
+    cursor: pointer; font-size: 12px; font-weight: 600; transition: all 0.2s;
+  }
+  .optimizer-generate-btn:hover {
+    background: rgba(37,99,235,0.15); border-color: rgba(37,99,235,0.3);
+  }
+  .optimizer-generate-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+  .optimizer-ai-content {
+    font-size: 13px; line-height: 1.75; color: var(--text);
+  }
+  .optimizer-ai-content h3 {
+    font-size: 13px; font-weight: 700; color: var(--text);
+    margin: 16px 0 8px; text-transform: none; letter-spacing: normal;
+    display: flex; align-items: center; justify-content: space-between;
+  }
+  .optimizer-ai-content p { margin-bottom: 8px; }
+  .optimizer-ai-content ul { padding-left: 18px; margin-bottom: 8px; }
+  .optimizer-ai-content li { margin-bottom: 4px; list-style: disc; }
+  .optimizer-ai-content strong { color: var(--text); }
+  .optimizer-ai-content code {
+    font-family: var(--mono); font-size: 11px; background: var(--surface3);
+    padding: 1px 5px; border-radius: 3px;
+  }
+  .optimizer-ai-content pre {
+    background: var(--surface3); border-radius: 6px; padding: 12px 14px;
+    font-family: var(--mono); font-size: 11px; line-height: 1.6;
+    overflow-x: auto; margin-bottom: 10px; white-space: pre-wrap; word-break: break-word;
+    position: relative;
+  }
+  .optimizer-ai-content hr {
+    border: none; border-top: 1px solid var(--border); margin: 16px 0;
+  }
+  .copy-btn {
+    background: var(--surface); border: 1px solid var(--border); color: var(--text3);
+    padding: 2px 8px; border-radius: 5px; cursor: pointer; font-size: 10px;
+    font-family: var(--mono); transition: all 0.15s; white-space: nowrap;
+  }
+  .copy-btn:hover { color: var(--text); border-color: var(--border-hover); }
+  .copy-btn.copied { color: var(--green); border-color: rgba(22,163,74,0.3); }
+  .optimizer-timestamp {
+    font-size: 10px; color: var(--text3); font-family: var(--mono);
+    margin-top: 14px; padding-top: 10px; border-top: 1px solid var(--border);
+    display: flex; align-items: center; gap: 10px;
+  }
+
   /* Share modal */
   .share-btn {
     background: var(--surface2); border: 1px solid var(--border); color: var(--text2);
@@ -653,6 +776,65 @@
     transition: all 0.2s; font-size: 12px; font-weight: 500; white-space: nowrap;
   }
   .share-btn:hover { background: var(--surface3); color: var(--text); border-color: var(--border-hover); }
+  /* What's New */
+  .whatsnew-overlay {
+    display: none; position: fixed; inset: 0; background: rgba(0,0,0,0.45);
+    z-index: 1100; align-items: center; justify-content: center;
+    backdrop-filter: blur(3px);
+  }
+  .whatsnew-overlay.open { display: flex; }
+  .whatsnew-modal {
+    background: var(--surface); border: 1px solid var(--border);
+    border-radius: var(--radius); padding: 28px 32px; max-width: 480px; width: 90%;
+    box-shadow: 0 12px 40px rgba(0,0,0,0.22); position: relative;
+  }
+  .whatsnew-modal::before {
+    content: ''; position: absolute; top: 0; left: 0; right: 0; height: 2px;
+    background: linear-gradient(90deg, var(--accent), var(--green));
+    border-radius: var(--radius) var(--radius) 0 0;
+  }
+  .whatsnew-version {
+    font-size: 10px; font-family: var(--mono); color: var(--accent);
+    font-weight: 600; text-transform: uppercase; letter-spacing: 0.8px;
+    margin-bottom: 6px;
+  }
+  .whatsnew-modal h2 {
+    font-size: 17px; font-weight: 700; color: var(--text);
+  }
+  .whatsnew-items { list-style: none; margin-bottom: 22px; }
+  .whatsnew-items li {
+    display: flex; gap: 10px; align-items: flex-start;
+    font-size: 13px; color: var(--text2); line-height: 1.55; margin-bottom: 12px;
+  }
+  .whatsnew-items li:last-child { margin-bottom: 0; }
+  .whatsnew-items li .wi-icon {
+    flex-shrink: 0; width: 20px; height: 20px; border-radius: 5px;
+    background: var(--accent-dim); color: var(--accent);
+    display: flex; align-items: center; justify-content: center;
+    font-size: 11px; margin-top: 1px;
+  }
+  .whatsnew-items li strong { color: var(--text); }
+  .whatsnew-x {
+    position: absolute; top: 12px; right: 14px; background: none; border: none;
+    color: var(--text3); cursor: pointer; font-size: 18px; line-height: 1; padding: 4px;
+  }
+  .whatsnew-x:hover { color: var(--text); }
+  .whatsnew-actions { display: flex; gap: 8px; }
+  .whatsnew-dismiss {
+    flex: 1; padding: 9px; border-radius: 7px;
+    background: var(--accent-dim); border: 1px solid rgba(37,99,235,0.2);
+    color: var(--accent); font-size: 13px; font-weight: 600;
+    cursor: pointer; transition: all 0.15s;
+  }
+  .whatsnew-dismiss:hover { background: rgba(37,99,235,0.15); }
+  .whatsnew-showme {
+    padding: 3px 10px; border-radius: 5px;
+    background: transparent; border: 1px solid var(--border);
+    color: var(--text3); font-size: 11px; font-weight: 500;
+    cursor: pointer; transition: all 0.15s; white-space: nowrap;
+  }
+  .whatsnew-showme:hover { color: var(--accent); border-color: var(--accent); }
+
   .share-overlay {
     display: none; position: fixed; inset: 0; background: rgba(0,0,0,0.4);
     z-index: 1000; align-items: center; justify-content: center;
@@ -1079,6 +1261,14 @@ function renderDashboard(data) {
         </div>
       </div>
     </section>
+    <section id="optimizer-section">
+      <div class="optimizer-card">
+        <h3>Workflow Optimizer</h3>
+        <div id="optimizer-body">
+          <div style="color:var(--text3); font-size:13px; padding: 4px 0 12px;">Loading suggestions<span id="optimizer-dots"></span></div>
+        </div>
+      </div>
+    </section>
     <div class="score-breakdown-overlay" id="score-breakdown-overlay" onclick="if(event.target===this)toggleScoreBreakdown()">
     <div class="score-breakdown">
       <button class="score-breakdown-close" onclick="toggleScoreBreakdown()">&times;</button>
@@ -1120,6 +1310,33 @@ function renderDashboard(data) {
         <pre id="ai-prompt-content">Loading...</pre>
       </div>
     </div>
+    <div class="whatsnew-overlay" id="whatsnew-overlay" onclick="if(event.target===this)closeWhatsNew(false)">
+      <div class="whatsnew-modal">
+        <button class="whatsnew-x" onclick="closeWhatsNew(false)">&times;</button>
+        <div class="whatsnew-version">v0.4.0 — What's New</div>
+        <div style="display:flex; align-items:baseline; gap:10px; margin-bottom:18px;">
+          <h2 style="margin-bottom:0">Workflow Optimizer</h2>
+          <button class="whatsnew-showme" onclick="showMeWhatsNew()">Take me there!</button>
+        </div>
+        <ul class="whatsnew-items">
+          <li>
+            <span class="wi-icon">&#9881;</span>
+            <span><strong>Rule-based suggestions</strong> — analyzes your badges, tool patterns, and session history to recommend skills, CLAUDE.md files, and subagents to create</span>
+          </li>
+          <li>
+            <span class="wi-icon">&#10024;</span>
+            <span><strong>AI artifact generation</strong> — streams ready-to-copy content: full CLAUDE.md text, skill prompt bodies, and agent configs tailored to your workflow</span>
+          </li>
+          <li>
+            <span class="wi-icon">&#128274;</span>
+            <span><strong>Context-aware plugin advice</strong> — only suggests MCP plugins where CLI tools have a real gap, avoiding unnecessary context overhead</span>
+          </li>
+        </ul>
+        <div class="whatsnew-actions">
+          <button class="whatsnew-dismiss" onclick="closeWhatsNew(true)">OK. Don't show again.</button>
+        </div>
+      </div>
+    </div>
     <div class="share-overlay" id="share-overlay" onclick="if(event.target===this)closeShareModal()">
       <div class="share-modal">
         <button class="share-close" onclick="closeShareModal()">&times;</button>
@@ -1590,6 +1807,309 @@ async function loadCachedAIInsights() {
   } catch {}
 }
 
+// --- Workflow Optimizer ---
+
+let optimizerSuggestions = null;
+let activeOptimizerTab = 'all';
+let cachedOptimizerAI = null;
+
+const OPTIMIZER_TABS = [
+  { id: 'all', label: 'All' },
+  { id: 'skills', label: 'Skills' },
+  { id: 'claudeMd', label: 'CLAUDE.md' },
+  { id: 'agents', label: 'Agents' },
+  { id: 'plugins', label: 'Plugins' },
+];
+
+async function loadSuggestions() {
+  let dotCount = 0;
+  const dotsEl = document.getElementById('optimizer-dots');
+  const dotTimer = setInterval(() => {
+    dotCount = (dotCount + 1) % 4;
+    if (dotsEl) dotsEl.textContent = '.'.repeat(dotCount);
+  }, 400);
+
+  try {
+    const res = await fetch('/api/suggestions');
+    optimizerSuggestions = await res.json();
+    clearInterval(dotTimer);
+    renderOptimizerTabs();
+  } catch {
+    clearInterval(dotTimer);
+    const body = document.getElementById('optimizer-body');
+    if (body) body.innerHTML = '<div class="suggestion-empty">Could not load suggestions.</div>';
+  }
+}
+
+function renderOptimizerTabs() {
+  const body = document.getElementById('optimizer-body');
+  if (!body || !optimizerSuggestions) return;
+
+  const total = OPTIMIZER_TABS.reduce((s, t) => s + (optimizerSuggestions[t.id] || []).length, 0);
+  if (total === 0) {
+    body.innerHTML = '<div class="suggestion-empty">No suggestions — your workflow looks well-optimized!</div>';
+    return;
+  }
+
+  const tabsHtml = OPTIMIZER_TABS.map(t => {
+    const count = t.id === 'all' ? total : (optimizerSuggestions[t.id] || []).length;
+    return `<button class="optimizer-tab${t.id === activeOptimizerTab ? ' active' : ''}" onclick="switchOptimizerTab('${t.id}')">
+      ${t.label}<span class="tab-count">${count}</span>
+    </button>`;
+  }).join('');
+
+  const allPanelHtml = OPTIMIZER_TABS.filter(t => t.id !== 'all').map(t => {
+    const items = optimizerSuggestions[t.id] || [];
+    if (!items.length) return '';
+    return `<div style="margin-bottom:18px">
+      <div style="font-size:10px;text-transform:uppercase;letter-spacing:0.7px;color:var(--text3);font-weight:600;margin-bottom:8px">${t.label}</div>
+      ${renderSuggestionList(t.id, items)}
+    </div>`;
+  }).join('');
+
+  const panelsHtml = OPTIMIZER_TABS.map(t => `
+    <div class="optimizer-panel${t.id === activeOptimizerTab ? ' active' : ''}" id="optimizer-panel-${t.id}">
+      ${t.id === 'all' ? allPanelHtml : renderSuggestionList(t.id, optimizerSuggestions[t.id] || [])}
+    </div>`).join('');
+
+  const aiSection = `
+    <div class="optimizer-ai-section">
+      <div class="optimizer-ai-controls">
+        <button class="optimizer-generate-btn" onclick="generateOptimizerContent()" id="optimizer-gen-btn">
+          Generate artifact content with AI
+        </button>
+        <span class="ai-model-picker" id="optimizer-model-picker">
+          <span class="ai-model-pill" onclick="toggleModelMenu(event)" data-tip="Click to switch model"></span>
+          <div class="ai-model-menu"></div>
+        </span>
+      </div>
+      <div id="optimizer-ai-output"></div>
+    </div>`;
+
+  body.innerHTML = `
+    <p style="font-size:12px; color:var(--text3); margin-bottom:12px;">
+      Based on ${(optimizerSuggestions.skills.length + optimizerSuggestions.claudeMd.length + optimizerSuggestions.agents.length + optimizerSuggestions.plugins.length)} patterns found in your sessions.
+    </p>
+    <div class="optimizer-tabs">${tabsHtml}</div>
+    ${panelsHtml}
+    ${aiSection}`;
+
+  // Sync model picker — reuse same aiModels
+  const optimizerPicker = document.getElementById('optimizer-model-picker');
+  if (optimizerPicker && aiModels.length > 0) {
+    const current = aiModels.find(m => m.id === selectedModelId) ||
+      aiModels.find(m => m.id === aiDefaultModel) || aiModels[0];
+    const pill = optimizerPicker.querySelector('.ai-model-pill');
+    const menu = optimizerPicker.querySelector('.ai-model-menu');
+    if (pill) pill.innerHTML = `${current.label} <span class="pill-chevron">&#x25BE;</span>`;
+    if (menu) menu.innerHTML = aiModels.map(m =>
+      `<div class="ai-model-option${m.id === selectedModelId ? ' active' : ''}" data-model="${m.id}" onclick="selectModel('${m.id}')">` +
+      `<span class="check">${m.id === selectedModelId ? '●' : ''}</span>${m.label}</div>`
+    ).join('');
+  }
+
+  if (cachedOptimizerAI) {
+    renderOptimizerAIComplete(cachedOptimizerAI.content, cachedOptimizerAI.generatedAt, cachedOptimizerAI.model);
+  }
+}
+
+function renderSuggestionList(type, items) {
+  if (!items.length) return '<div class="suggestion-empty">No suggestions for this category.</div>';
+  return items.map(item => {
+    const priorityClass = `priority-${item.priority || 'medium'}`;
+    const priorityLabel = (item.priority || 'medium').charAt(0).toUpperCase() + (item.priority || 'medium').slice(1);
+    let meta = '';
+    if (type === 'skills' && item.trigger) meta = `<span>trigger: <strong>${escHtml(item.trigger)}</strong></span>`;
+    if (type === 'claudeMd') meta = `<span>scope: <strong>${escHtml(item.scope)}${item.projectName ? ' · ' + escHtml(item.projectName) : ''}</strong></span>`;
+    if (type === 'plugins' && item.installCmd) meta = `<span style="font-family:var(--mono)">${escHtml(item.installCmd)}</span>`;
+    if (type === 'agents' && item.use_case) meta = `<span>${escHtml(item.use_case)}</span>`;
+    return `
+      <div class="suggestion-card">
+        <div class="suggestion-header">
+          <div class="suggestion-title">${escHtml(item.title || item.name || item.use_case || '')}</div>
+          <span class="suggestion-priority ${priorityClass}">${priorityLabel}</span>
+        </div>
+        <div class="suggestion-rationale">${escHtml(item.rationale)}</div>
+        ${meta ? `<div class="suggestion-meta">${meta}</div>` : ''}
+      </div>`;
+  }).join('');
+}
+
+function switchOptimizerTab(tabId) {
+  activeOptimizerTab = tabId;
+  document.querySelectorAll('.optimizer-panel').forEach(p => {
+    p.classList.toggle('active', p.id === `optimizer-panel-${tabId}`);
+  });
+  document.querySelectorAll('.optimizer-tab').forEach(t => {
+    const onclick = t.getAttribute('onclick') || '';
+    const match = onclick.match(/switchOptimizerTab\('([^']+)'\)/);
+    if (match) t.classList.toggle('active', match[1] === tabId);
+  });
+}
+
+function generateOptimizerContent() {
+  const btn = document.getElementById('optimizer-gen-btn');
+  const output = document.getElementById('optimizer-ai-output');
+  if (!btn || !output) return;
+
+  const wasActive = autoRefreshActive;
+  if (autoRefreshActive) pauseAutoRefresh();
+
+  const modelId = selectedModelId;
+  const modelParam = modelId ? `?model=${encodeURIComponent(modelId)}` : '';
+
+  btn.disabled = true;
+  output.innerHTML = `
+    <div class="ai-loading">
+      <div class="ai-spinner"></div>
+      <div>Generating with ${modelId ? modelLabel(modelId) : 'default model'}, please wait...</div>
+    </div>
+    <div class="optimizer-ai-content" id="optimizer-stream-content"></div>`;
+
+  streamOptimizerFetch(modelParam, output, wasActive);
+}
+
+async function streamOptimizerFetch(modelParam, output, wasActive) {
+  let fullContent = '';
+  let usedModel = '';
+
+  try {
+    const res = await fetch('/api/ai-suggestions' + modelParam, { method: 'POST' });
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop();
+
+      let currentEvent = '';
+      for (const line of lines) {
+        if (line.startsWith('event: ')) {
+          currentEvent = line.slice(7);
+        } else if (line.startsWith('data: ')) {
+          const data = line.slice(6);
+          if (currentEvent === 'model') {
+            usedModel = JSON.parse(data);
+            const loading = output.querySelector('.ai-loading div:last-child');
+            if (loading) loading.textContent = `Generating with ${modelLabel(usedModel)}, please wait...`;
+          } else if (currentEvent === 'chunk') {
+            fullContent += JSON.parse(data);
+            const el = document.getElementById('optimizer-stream-content');
+            if (el) el.innerHTML = renderOptimizerMarkdown(escHtml(fullContent));
+          } else if (currentEvent === 'done') {
+            const { generatedAt, model } = JSON.parse(data);
+            if (model) usedModel = model;
+            const loading = output.querySelector('.ai-loading');
+            if (loading) loading.remove();
+            renderOptimizerAIComplete(fullContent, generatedAt, usedModel);
+            if (wasActive) resumeAutoRefreshIfPaused();
+          } else if (currentEvent === 'error') {
+            const { message } = JSON.parse(data);
+            const btn = document.getElementById('optimizer-gen-btn');
+            if (btn) btn.disabled = false;
+            output.innerHTML = `<div class="ai-error">${escHtml(message)}</div>
+              <button class="optimizer-generate-btn" style="margin-top:8px" onclick="generateOptimizerContent()">Retry</button>`;
+            if (wasActive) resumeAutoRefreshIfPaused();
+          }
+        }
+      }
+    }
+  } catch (err) {
+    const btn = document.getElementById('optimizer-gen-btn');
+    if (btn) btn.disabled = false;
+    output.innerHTML = `<div class="ai-error">Failed to connect to server</div>
+      <button class="optimizer-generate-btn" style="margin-top:8px" onclick="generateOptimizerContent()">Retry</button>`;
+    if (wasActive) resumeAutoRefreshIfPaused();
+  }
+}
+
+function renderOptimizerMarkdown(text) {
+  // Handle code blocks first to protect their content
+  const codeBlocks = [];
+  text = text.replace(/```[\s\S]*?```/g, (match) => {
+    const idx = codeBlocks.length;
+    codeBlocks.push(match);
+    return `__CODEBLOCK_${idx}__`;
+  });
+
+  text = text
+    .replace(/^### (.+)$/gm, (_, t) =>
+      `<h3>${t} <button class="copy-btn" onclick="copySection(this)">copy</button></h3>`)
+    .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+    .replace(/`([^`]+)`/g, '<code>$1</code>')
+    .replace(/^\- (.+)$/gm, '<li>$1</li>')
+    .replace(/(<li>.*<\/li>\n?)+/gs, m => '<ul>' + m + '</ul>')
+    .replace(/^---$/gm, '<hr>')
+    .replace(/\n{2,}/g, '</p><p>')
+    .replace(/^(?!<[hul])/gm, s => s ? '<p>' + s : '')
+    .replace(/<p><\/p>/g, '')
+    .replace(/<p>(<[hul])/g, '$1');
+
+  // Restore code blocks as <pre>
+  text = text.replace(/__CODEBLOCK_(\d+)__/g, (_, i) => {
+    const raw = codeBlocks[parseInt(i)];
+    const inner = raw.replace(/^```[^\n]*\n?/, '').replace(/```$/, '');
+    return `<pre>${escHtml(inner)}<button class="copy-btn" style="position:absolute;top:6px;right:6px" onclick="copyPre(this)">copy</button></pre>`;
+  });
+
+  return text;
+}
+
+function renderOptimizerAIComplete(content, generatedAt, model) {
+  cachedOptimizerAI = { content, generatedAt, model };
+  const output = document.getElementById('optimizer-ai-output');
+  const btn = document.getElementById('optimizer-gen-btn');
+  if (!output) return;
+  if (btn) btn.disabled = false;
+  output.innerHTML = `
+    <div class="optimizer-ai-content">${renderOptimizerMarkdown(escHtml(content))}</div>
+    <div class="optimizer-timestamp">
+      Generated ${new Date(generatedAt).toLocaleString()}${model ? ' · ' + modelLabel(model) : ''}
+      <button class="optimizer-generate-btn" style="padding:4px 12px;font-size:11px;margin-left:8px" onclick="generateOptimizerContent()">Regenerate</button>
+      <button class="optimizer-generate-btn" style="padding:4px 12px;font-size:11px;background:var(--surface2);color:var(--text2)" onclick="clearOptimizerAI()">Clear</button>
+    </div>`;
+}
+
+function clearOptimizerAI() {
+  cachedOptimizerAI = null;
+  fetch('/api/ai-suggestions', { method: 'DELETE' }).catch(() => {});
+  const output = document.getElementById('optimizer-ai-output');
+  const btn = document.getElementById('optimizer-gen-btn');
+  if (output) output.innerHTML = '';
+  if (btn) btn.disabled = false;
+}
+
+function copySection(btn) {
+  const h3 = btn.closest('h3');
+  const section = [];
+  let el = h3?.nextElementSibling;
+  while (el && el.tagName !== 'H3' && el.tagName !== 'HR') {
+    section.push(el.innerText || el.textContent);
+    el = el.nextElementSibling;
+  }
+  const text = section.join('\n\n').trim();
+  if (text) copyToClipboard(btn, text);
+}
+
+function copyPre(btn) {
+  const pre = btn.closest('pre');
+  if (pre) copyToClipboard(btn, pre.textContent.replace('copy', '').trim());
+}
+
+function copyToClipboard(btn, text) {
+  navigator.clipboard.writeText(text).then(() => {
+    btn.textContent = 'copied!';
+    btn.classList.add('copied');
+    setTimeout(() => { btn.textContent = 'copy'; btn.classList.remove('copied'); }, 2000);
+  }).catch(() => {});
+}
+
 // --- Share as PNG ---
 
 const BADGE_EMOJI = BADGE_ICONS;
@@ -1998,15 +2518,46 @@ function resumeAutoRefreshIfPaused() {
 
 document.addEventListener('keydown', e => {
   if (e.key === 'Escape' && currentView === 'session') closeSessionDrawer();
+  if (e.key === 'Escape' && document.getElementById('whatsnew-overlay')?.classList.contains('open')) closeWhatsNew(false);
 });
 
 fetchData().then(data => {
   currentData = data;
   renderDashboard(data);
+  maybeShowWhatsNew();
   loadCachedAIInsights();
+  loadSuggestions();
   if (autoRefreshActive) startAutoRefresh();
 });
 
+// --- What's New ---
+
+const WHATS_NEW_VERSION = '0.4.0';
+
+function closeWhatsNew(persist) {
+  document.getElementById('whatsnew-overlay').classList.remove('open');
+  if (persist) localStorage.setItem('seenWhatsNew', WHATS_NEW_VERSION);
+}
+
+function showMeWhatsNew() {
+  closeWhatsNew(false);
+  setTimeout(() => {
+    const el = document.getElementById('optimizer-section');
+    if (el) {
+      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      el.style.transition = 'box-shadow 0.3s';
+      el.style.boxShadow = '0 0 0 2px var(--accent)';
+      setTimeout(() => { el.style.boxShadow = ''; }, 1800);
+    }
+  }, 200);
+}
+
+function maybeShowWhatsNew() {
+  if (localStorage.getItem('seenWhatsNew') !== WHATS_NEW_VERSION) {
+    document.getElementById('whatsnew-overlay').classList.add('open');
+  }
+}
+
 // Live reload via SSE
 const sse = new EventSource('/api/reload');
 sse.onmessage = async (e) => {

package/src/ai-analyze.js

@@ -124,7 +124,79 @@ Keep the entire response under 400 words. Use markdown formatting.`;
 
 export { buildPrompt, buildDataSnapshot };
 
+function buildSuggestionsPrompt(scoredData, suggestions) {
+  const { sessions, badges, overallScore } = scoredData;
+  const totalCost = sessions.reduce((s, x) => s + x.totals.estimatedCost, 0);
+  const projectNames = [...new Set(sessions.map((s) => s.project).filter(Boolean))].slice(0, 5);
+  const badgeNames = badges.map((b) => `${b.negative ? "⚠ " : "✓ "}${b.name}`).join(", ");
+
+  const topSkill = suggestions.skills[0];
+  const topClaudeMd = suggestions.claudeMd[0];
+  const topAgent = suggestions.agents[0];
+  const topPlugin = suggestions.plugins[0];
+
+  const parts = [];
+
+  if (topSkill) {
+    parts.push(`SKILL: "${topSkill.trigger}" — ${topSkill.title}
+Template hint: ${topSkill.templateHint}`);
+  }
+  if (topClaudeMd) {
+    parts.push(`CLAUDE.MD (${topClaudeMd.scope}${topClaudeMd.projectName ? ` for ${topClaudeMd.projectName}` : ""}):
+Sections to include: ${topClaudeMd.sections.join(", ")}`);
+  }
+  if (topAgent) {
+    parts.push(`AGENT: ${topAgent.name} — ${topAgent.use_case}
+Example usage: ${topAgent.example || "n/a"}`);
+  }
+  if (topPlugin) {
+    parts.push(`PLUGIN: ${topPlugin.name}
+Install: ${topPlugin.installCmd}`);
+  }
+
+  return `You are helping a developer improve their Claude Code workflow. Based on their session data, generate ready-to-use artifact content for the following recommendations.
+
+## Their Usage Context
+- ${sessions.length} total sessions across ${projectNames.length} project(s): ${projectNames.join(", ")}
+- Overall efficiency score: ${overallScore}/100
+- Total spend: $${totalCost.toFixed(2)}
+- Badges: ${badgeNames || "none"}
+
+## Recommendations to generate content for
+
+${parts.join("\n\n")}
+
+## Your output
+
+For each recommendation above, generate the actual content the user can copy and use immediately. Use this exact structure:
+
+${topSkill ? `### Skill: ${topSkill.trigger}
+Write the full skill prompt body (2-4 paragraphs). This is what Claude reads when the user types "${topSkill.trigger}". Make it specific, actionable, and tailored to the usage patterns above. Include what information the user should provide.
+
+---` : ""}
+
+${topClaudeMd ? `### CLAUDE.md${topClaudeMd.projectName ? ` (${topClaudeMd.projectName})` : " (global)"}
+Write a complete, ready-to-use CLAUDE.md file. Include all the sections listed. Be specific about the patterns implied by their badges and session data. Use markdown formatting.
+
+---` : ""}
+
+${topAgent ? `### Agent: ${topAgent.name}
+Describe exactly how to configure and invoke this agent in Claude Code. Include a sample prompt to use it effectively.
+
+---` : ""}
+
+${topPlugin ? `### Plugin: ${topPlugin.name}
+Explain the 2-3 best use cases for this plugin given their workflow, and give a sample prompt that takes advantage of it.
+
+---` : ""}
+
+Keep each artifact concise and immediately usable. No filler or generic advice.`;
+}
+
+export { buildSuggestionsPrompt };
+
 let cachedResult = null;
+let cachedSuggestionResult = null;
 const activeChildren = new Set();
 
 /**
@@ -275,3 +347,114 @@ export function getAvailableModels() {
     defaultModelLabel: prettyModelName(detectedDefaultModel),
   };
 }
+
+/**
+ * Stream AI-generated suggestion content (skills, CLAUDE.md, agents, plugins).
+ * Same SSE protocol as streamAIAnalysis.
+ */
+export function streamAISuggestions(scoredData, suggestions, res, modelId) {
+  const prompt = buildSuggestionsPrompt(scoredData, suggestions);
+
+  const args = ["-p", "-", "--output-format", "stream-json", "--verbose"];
+  if (modelId) args.push("--model", modelId);
+
+  const resolvedModel = modelId || "default";
+  console.log(`[ai-suggestions] Starting (model: ${resolvedModel})`);
+  res.write(`event: model\ndata: ${JSON.stringify(resolvedModel)}\n\n`);
+
+  const child = spawn("claude", args, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: cleanEnv,
+  });
+  activeChildren.add(child);
+
+  child.stdin.write(prompt);
+  child.stdin.end();
+
+  let fullContent = "";
+  let errOutput = "";
+  let detectedModel = modelId || detectedDefaultModel || null;
+  let lineBuf = "";
+
+  child.stdout.on("data", (buf) => {
+    lineBuf += buf.toString();
+    const lines = lineBuf.split("\n");
+    lineBuf = lines.pop();
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.type === "system" || obj.type === "rate_limit_event") continue;
+        if (obj.type === "result") {
+          const models = Object.keys(obj.modelUsage || {});
+          if (models.length > 0) {
+            detectedModel = models[0];
+            if (!modelId) detectedDefaultModel = models[0];
+          }
+          continue;
+        }
+        if (obj.type === "assistant" && obj.message?.content) {
+          for (const block of obj.message.content) {
+            if (block.type === "text" && block.text) {
+              fullContent += block.text;
+              res.write(`event: chunk\ndata: ${JSON.stringify(block.text)}\n\n`);
+            }
+          }
+          if (obj.message.model && !detectedModel) {
+            detectedModel = obj.message.model;
+            if (!modelId) detectedDefaultModel = obj.message.model;
+          }
+        }
+      } catch {
+        if (line.trim()) {
+          fullContent += line;
+          res.write(`event: chunk\ndata: ${JSON.stringify(line)}\n\n`);
+        }
+      }
+    }
+  });
+
+  child.stderr.on("data", (buf) => {
+    errOutput += buf.toString();
+  });
+
+  child.on("error", (err) => {
+    const message =
+      err.code === "ENOENT"
+        ? "Claude CLI not found. Make sure `claude` is installed and in your PATH."
+        : `Claude CLI error: ${err.message}`;
+    res.write(`event: error\ndata: ${JSON.stringify({ message })}\n\n`);
+    res.end();
+  });
+
+  child.on("close", (code) => {
+    activeChildren.delete(child);
+    if (code !== 0 && !fullContent) {
+      const message = errOutput.trim() || `Claude CLI exited with code ${code}`;
+      res.write(`event: error\ndata: ${JSON.stringify({ message })}\n\n`);
+    } else {
+      const finalModel = detectedModel || resolvedModel;
+      cachedSuggestionResult = {
+        content: fullContent.trim(),
+        generatedAt: new Date().toISOString(),
+        model: finalModel,
+      };
+      res.write(
+        `event: done\ndata: ${JSON.stringify({ generatedAt: cachedSuggestionResult.generatedAt, model: finalModel })}\n\n`
+      );
+    }
+    res.end();
+  });
+
+  res.on("close", () => {
+    if (child.exitCode === null) child.kill();
+  });
+}
+
+export function getCachedSuggestions() {
+  return cachedSuggestionResult;
+}
+
+export function clearCachedSuggestions() {
+  cachedSuggestionResult = null;
+}

package/src/server.js

@@ -7,7 +7,8 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { parseAllSessions } from "./parser.js";
 import { scoreAllSessions } from "./scorer.js";
-import { streamAIAnalysis, getCachedAnalysis, clearCachedAnalysis, getAvailableModels, killActiveProcesses, detectDefaultModel, buildPrompt, buildDataSnapshot } from "./ai-analyze.js";
+import { streamAIAnalysis, getCachedAnalysis, clearCachedAnalysis, getAvailableModels, killActiveProcesses, detectDefaultModel, buildPrompt, buildDataSnapshot, streamAISuggestions, getCachedSuggestions, clearCachedSuggestions } from "./ai-analyze.js";
+import { generateSuggestions } from "./suggestions.js";
 
 const execFileAsync = promisify(execFile);
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -177,6 +178,35 @@ export function startServer(port = 6543) {
         });
       }
 
+      if (url.pathname === "/api/suggestions" && req.method === "GET") {
+        const data = await getData();
+        const suggestions = generateSuggestions(data);
+        return json(res, suggestions);
+      }
+
+      if (url.pathname === "/api/ai-suggestions" && req.method === "POST") {
+        const data = await getData();
+        const suggestions = generateSuggestions(data);
+        const modelId = url.searchParams.get("model") || "";
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        });
+        streamAISuggestions(data, suggestions, res, modelId || undefined);
+        return;
+      }
+
+      if (url.pathname === "/api/ai-suggestions" && req.method === "DELETE") {
+        clearCachedSuggestions();
+        return json(res, { ok: true });
+      }
+
+      if (url.pathname === "/api/ai-suggestions" && req.method === "GET") {
+        const cached = getCachedSuggestions();
+        return json(res, cached || { content: null });
+      }
+
       if (url.pathname === "/api/refresh") {
         const data = await getData(true);
         return json(res, { sessions: data.sessions.length, overallScore: data.overallScore });

package/src/suggestions.js

@@ -0,0 +1,280 @@
+// Workflow Optimizer — rule-based suggestion engine
+// Analyzes session patterns and produces suggestions for skills, CLAUDE.md, agents, and plugins.
+
+// --- Helpers ---
+
+function computeVagueRate(sessions) {
+  let total = 0;
+  let vague = 0;
+  for (const s of sessions) {
+    const userTurns = s.turns.filter((t) => t.role === "user");
+    total += userTurns.length;
+    for (const turn of userTurns) {
+      if (turn.promptLength < 30) {
+        const idx = s.turns.indexOf(turn);
+        const next = s.turns.slice(idx + 1).find((t) => t.role === "assistant");
+        if (next && next.tokens.input + next.tokens.output > 50_000) vague++;
+      }
+    }
+  }
+  return total >= 5 ? vague / total : 0;
+}
+
+function computeAvgToolRatio(sessions) {
+  const qualifying = sessions.filter((s) => s.totals.userMessages > 0);
+  if (!qualifying.length) return 0;
+  return qualifying.reduce((sum, s) => sum + s.totals.toolCalls / s.totals.userMessages, 0) / qualifying.length;
+}
+
+/**
+ * Returns a map of tool name → fraction of all tool usages.
+ * Only counts turns that actually have tool calls.
+ */
+function detectToolPatterns(sessions) {
+  const counts = {};
+  let total = 0;
+  for (const s of sessions) {
+    for (const t of s.turns) {
+      for (const tool of t.toolCalls || []) {
+        const name = tool.toLowerCase();
+        counts[name] = (counts[name] || 0) + 1;
+        total++;
+      }
+    }
+  }
+  if (!total) return {};
+  const fractions = {};
+  for (const [k, v] of Object.entries(counts)) fractions[k] = v / total;
+  return fractions;
+}
+
+const TOPIC_PATTERNS = [
+  { topic: "git", re: /\b(git|github|commit|pull request|pr|merge|branch|rebase|stash)\b/i },
+  { topic: "test", re: /\b(test|spec|jest|vitest|cypress|playwright|coverage|assert)\b/i },
+  { topic: "deploy", re: /\b(deploy|release|build|ci|pipeline|docker|kubernetes|k8s|heroku|vercel)\b/i },
+  { topic: "debug", re: /\b(debug|fix|bug|error|crash|exception|trace|breakpoint)\b/i },
+  { topic: "review", re: /\b(review|refactor|cleanup|lint|format|code review)\b/i },
+  { topic: "api", re: /\b(api|endpoint|rest|graphql|backend|route|controller|service)\b/i },
+  { topic: "frontend", re: /\b(ui|component|css|style|react|vue|svelte|tailwind|design)\b/i },
+  { topic: "database", re: /\b(database|db|sql|query|migration|schema|postgres|mysql|sqlite|prisma|supabase)\b/i },
+  { topic: "docs", re: /\b(doc|readme|documentation|comment|jsdoc|typedoc)\b/i },
+];
+
+/**
+ * Groups sessions by dominant topic, returns sorted by count descending.
+ */
+function detectTitleClusters(sessions) {
+  const counts = {};
+  for (const s of sessions) {
+    const title = (s.title || "") + " " + (s.project || "");
+    for (const { topic, re } of TOPIC_PATTERNS) {
+      if (re.test(title)) {
+        counts[topic] = (counts[topic] || 0) + 1;
+        break; // one topic per session
+      }
+    }
+  }
+  return Object.entries(counts)
+    .map(([topic, count]) => ({ topic, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Returns sessions-per-project, sorted by count descending.
+ */
+function detectProjectPatterns(sessions) {
+  const counts = {};
+  for (const s of sessions) {
+    const p = s.project || "unknown";
+    counts[p] = (counts[p] || 0) + 1;
+  }
+  return Object.entries(counts)
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+// --- Main export ---
+
+/**
+ * Generates workflow suggestions from scored session data.
+ * Returns { skills, claudeMd, agents, plugins } — each an array of suggestion objects.
+ */
+export function generateSuggestions(scoredData) {
+  const { sessions, badges } = scoredData;
+  if (!sessions || sessions.length === 0) {
+    return { skills: [], claudeMd: [], agents: [], plugins: [] };
+  }
+
+  const badgeIds = new Set(badges.map((b) => b.id));
+  const toolPatterns = detectToolPatterns(sessions);
+  const titleClusters = detectTitleClusters(sessions);
+  const projectPatterns = detectProjectPatterns(sessions);
+  const avgToolRatio = computeAvgToolRatio(sessions);
+  const vagueRate = computeVagueRate(sessions);
+  const topCluster = titleClusters[0] || null;
+
+  const skills = [];
+  const claudeMd = [];
+  const agents = [];
+  const plugins = [];
+
+  // --- Skills ---
+
+  if (badgeIds.has("vague-commander") || vagueRate > 0.2) {
+    skills.push({
+      id: "spec-skill",
+      title: "Create a /spec planning skill",
+      trigger: "/spec",
+      rationale: `${Math.round(vagueRate * 100)}% of your prompts are very short and trigger expensive, wide-ranging Claude responses. A /spec skill prompts you to write a thorough task spec before Claude starts — reducing ambiguity and costly back-and-forth.`,
+      priority: "high",
+      templateHint:
+        "Before starting any implementation task, define: what to build, constraints, files to change, what to leave alone, and success criteria. Then hand this spec to Claude.",
+    });
+  }
+
+  if (badgeIds.has("context-hoarder")) {
+    skills.push({
+      id: "checkpoint-skill",
+      title: "Create a /checkpoint context-reset skill",
+      trigger: "/checkpoint",
+      rationale:
+        "Your sessions frequently experience cost inflection without context resets. A /checkpoint skill saves progress, summarizes state, then clears the context window — keeping sessions lean.",
+      priority: "high",
+      templateHint:
+        "Summarize what has been accomplished so far. List remaining tasks. Note any important decisions made. Then run /clear so the next phase starts fresh with this summary.",
+    });
+  }
+
+  if (avgToolRatio > 5 && !badgeIds.has("surgical-prompter")) {
+    skills.push({
+      id: "focus-skill",
+      title: "Create a /focus task-scoping skill",
+      trigger: "/focus",
+      rationale: `Your average tool ratio is ${avgToolRatio.toFixed(1)}x per message — Claude spends a lot of time searching for files and context. A /focus skill primes your prompts with exact file paths and scope to eliminate unnecessary exploration.`,
+      priority: "medium",
+      templateHint:
+        "For every task, include: exact files to change (with paths), specific line numbers if known, what NOT to modify, and the precise expected output or behavior.",
+    });
+  }
+
+  if (topCluster && topCluster.count >= 5) {
+    skills.push({
+      id: `domain-skill-${topCluster.topic}`,
+      title: `Create a /${topCluster.topic} workflow skill`,
+      trigger: `/${topCluster.topic}`,
+      rationale: `${topCluster.count} of your sessions involve "${topCluster.topic}" tasks. A dedicated skill standardizes how you kick off these workflows and gives Claude the right context from the start.`,
+      priority: "medium",
+      templateHint: `Standard workflow for ${topCluster.topic} tasks: include relevant context, patterns to follow, and any project-specific conventions.`,
+    });
+  }
+
+  // --- CLAUDE.md ---
+
+  const heavyProjects = projectPatterns.filter((p) => p.count >= 5 && p.name !== "unknown");
+  for (const proj of heavyProjects.slice(0, 2)) {
+    claudeMd.push({
+      id: `claudemd-project-${proj.name.replace(/[^a-z0-9]/gi, "-").toLowerCase()}`,
+      scope: "project",
+      projectName: proj.name,
+      rationale: `You have ${proj.count} sessions in "${proj.name}". A CLAUDE.md file in that project gives Claude persistent context about your codebase, architecture, and conventions — reducing repeated explanations every session.`,
+      priority: "high",
+      sections: ["Project overview and purpose", "Key files and architecture", "Coding conventions and patterns", "Common tasks and workflows", "What NOT to do"],
+    });
+  }
+
+  if (badgeIds.has("context-hoarder")) {
+    claudeMd.push({
+      id: "claudemd-clear-guidance",
+      scope: "global",
+      projectName: null,
+      rationale:
+        "Your sessions frequently experience cost inflection without context resets. Adding /clear guidance to your global CLAUDE.md establishes the habit of resetting context after each major task.",
+      priority: "medium",
+      sections: ["Context management: use /clear after completing each major task to keep sessions efficient"],
+    });
+  }
+
+  if (badgeIds.has("opus-addict")) {
+    claudeMd.push({
+      id: "claudemd-model-guidance",
+      scope: "global",
+      projectName: null,
+      rationale:
+        "You frequently use Opus for tasks where Sonnet performs equally well. Documenting model selection guidelines in CLAUDE.md (or setting a default model via claude config) could significantly reduce cost.",
+      priority: "high",
+      sections: ["Model selection: default to Sonnet for routine coding tasks, use Opus only for complex architecture decisions or deep reasoning"],
+    });
+  }
+
+  if (avgToolRatio > 5 && !badgeIds.has("surgical-prompter")) {
+    claudeMd.push({
+      id: "claudemd-prompt-conventions",
+      scope: "global",
+      projectName: null,
+      rationale:
+        "Your high tool-call ratio suggests Claude frequently has to search for context you could provide upfront. Adding prompt conventions to your CLAUDE.md establishes expectations for how specific your prompts should be.",
+      priority: "medium",
+      sections: ["Prompt conventions: always include exact file paths, avoid vague references like 'the function' or 'that thing'"],
+    });
+  }
+
+  // --- Agents ---
+
+  const highToolSessions = sessions.filter(
+    (s) => s.totals.toolCalls > 20 && s.totals.userMessages > 0
+  );
+  if (highToolSessions.length >= 3) {
+    agents.push({
+      id: "explore-agent",
+      name: "Explore subagent",
+      use_case: "Offload codebase exploration and file discovery",
+      rationale: `${highToolSessions.length} of your sessions use 20+ tool calls for file searches and codebase navigation. An Explore subagent handles this research in parallel and in a clean context, keeping your main session focused.`,
+      priority: "medium",
+      example:
+        'Launch with: Agent tool with subagent_type="Explore", prompt="Find all files related to authentication and explain the flow"',
+    });
+  }
+
+  if (topCluster && topCluster.count >= 8) {
+    agents.push({
+      id: `specialist-agent-${topCluster.topic}`,
+      name: `${topCluster.topic} specialist agent`,
+      use_case: `Handle ${topCluster.topic} tasks autonomously from a single high-level prompt`,
+      rationale: `You have ${topCluster.count} sessions focused on "${topCluster.topic}". A specialist subagent for this workflow could handle the entire task from a single high-level instruction, with expertise baked in.`,
+      priority: "low",
+      example: `Create a custom agent type optimized for ${topCluster.topic} tasks with relevant tools and context pre-loaded.`,
+    });
+  }
+
+  // --- Plugins ---
+  // Note: MCP servers load all their tool definitions into context on every message,
+  // adding token overhead even when unused. Only recommend MCPs where they provide
+  // a genuine capability gap over CLI tools (i.e., Bash can't do it well).
+
+  const bashFraction = toolPatterns["bash"] || 0;
+  const webSessions = sessions.filter((s) =>
+    /browser|playwright|scrape|screenshot|e2e|visual test/i.test(s.title)
+  );
+  if (bashFraction > 0.3 && webSessions.length >= 3) {
+    plugins.push({
+      id: "playwright-mcp",
+      name: "Playwright MCP",
+      rationale: `${webSessions.length} sessions involve browser tasks that curl/bash can't handle well — screenshots, JS-rendered pages, user interaction flows. Playwright MCP is one of the few cases where an MCP genuinely beats the CLI alternative.`,
+      installCmd: "claude mcp add playwright npx @playwright/mcp@latest",
+      url: "https://github.com/microsoft/playwright-mcp",
+      priority: "medium",
+    });
+  }
+
+  // Sort by priority
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  const byPriority = (a, b) =>
+    (priorityOrder[a.priority] ?? 1) - (priorityOrder[b.priority] ?? 1);
+
+  return {
+    skills: skills.sort(byPriority),
+    claudeMd: claudeMd.sort(byPriority),
+    agents: agents.sort(byPriority),
+    plugins: plugins.sort(byPriority),
+  };
+}