claude-finops 0.13.0 → 0.14.0

package/web/app.js

@@ -148,6 +148,7 @@ const NAV = [
     ['attribution', 'users', 'Who used the tokens', 'priced'],
     ['waste', 'trash', 'Waste detection'],
     ['freemodels', 'gift', 'Free models', 'claude'],
+    ['jev', 'sparkles', 'Jev (fast decisions)'],
     ['compare', 'scale', 'Compare models', 'priced'],
     ['toolkit', 'wrench', 'Skills & MCP', 'claude'],
     ['recommendations', 'listChecks', 'Recommendations'],
@@ -159,6 +160,9 @@ const NAV = [
     ['cloud', 'cloud', 'Billed vs local', 'cloud'],
     ['exports', 'download', 'Export & data'],
   ]],
+  ['Setup', [
+    ['settings', 'cog', 'Settings'],
+  ]],
 ];
 
 // Toolbar icons: 24px line icons drawn in currentColor, so they follow the theme.
@@ -194,6 +198,7 @@ const IP = {
   copy: '<rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1"/>',
   handover: '<path d="m15 17 5-5-5-5"/><path d="M4 18v-2a4 4 0 0 1 4-4h12"/>',
   plus: '<path d="M12 5v14M5 12h14"/>',
+  help: '<circle cx="12" cy="12" r="9"/><path d="M9.5 9a2.5 2.5 0 1 1 3.5 2.3c-.6.3-1 .9-1 1.6V14"/><path d="M12 17h.01"/>',
   pause: '<rect x="6" y="4" width="4" height="16" rx="1"/><rect x="14" y="4" width="4" height="16" rx="1"/>',
   stop: '<rect x="5" y="5" width="14" height="14" rx="2"/>',
   play: '<path d="M7 4v16l13-8z"/>',
@@ -463,7 +468,7 @@ function filterBar() {
       ${esc(o.meta.transcript_files)} transcripts · since ${esc(o.date_range.first)}</span>`;
 
   $('#filters').querySelectorAll('[data-range]').forEach(b =>
-    b.onclick = () => { if (b.dataset.range === 'custom') return openCustom(b);
+    b.onclick = e => { if (b.dataset.range === 'custom') { e.stopPropagation(); return openCustom(b); }
       applyRange(b.dataset.range); bust(); render(); });
   $('#filters').querySelectorAll('[data-agent]').forEach(b => b.onclick = e => {
     const id = b.dataset.agent;
@@ -525,13 +530,15 @@ function openPop(btn, kind) {
   }
 }
 function openCustom(btn) {
-  closePops();
-  const pop = h(`<div class="pop"><div class="hd">From</div>
+  const open = btn.parentElement.querySelector('.pop');
+  closePops(); if (open) return;
+  const pop = h(`<div class="pop" style="left:auto;right:0"><div class="hd">From</div>
     <input type="date" id="cs" value="${S.filter.start || S.opts.date_range.first}">
     <div class="hd">To</div>
     <input type="date" id="ce" value="${S.filter.end || S.opts.date_range.last}">
     <button class="chip on" id="ca" style="width:100%;justify-content:center">Apply</button></div>`);
-  btn.parentElement.insertBefore(pop, btn.nextSibling);
+  btn.parentElement.style.position = 'relative';
+  btn.parentElement.appendChild(pop);
   pop.onclick = e => e.stopPropagation();
   pop.querySelector('#ca').onclick = () => {
     S.filter.start = pop.querySelector('#cs').value;
@@ -1368,6 +1375,15 @@ VIEWS.projects = async (page) => {
 };
 
 /* ---------- sessions ---------- */
+// With a session token budget the dot follows it (whole-session tokens); without one,
+// it keeps flagging rows far above the loaded average.
+function sessFlag(r, avgTok) {
+  if (!r.budget_tokens) return r.tokens > avgTok * 3 ? dot('red') + ' ' : '';
+  const pct = 100 * (r.session_tokens || 0) / r.budget_tokens;
+  if (pct < 75) return '';
+  return `<span title="${fmtPct(pct)} of your ${fmtNum(r.budget_tokens)}-token session budget">${
+    dot(pct >= 100 ? 'red' : 'yellow')}</span> `;
+}
 VIEWS.sessions = async (page) => {
   const order = S.sessOrder || 'cost';
   const sp = S.sessPage;
@@ -1389,7 +1405,9 @@ VIEWS.sessions = async (page) => {
            ['prompts', 'Most prompts'], ['recent', 'Most recent']].map(([k, l]) =>
           `<button class="chip ${order === k ? 'on' : ''}" data-so="${k}">${l}</button>`).join('')}
         <span class="spacer"></span>
-        <span class="note">rows above ${fmtNum(avgTok * 3)} tokens are unusually expensive</span>
+        <span class="note">${rows.some(r => r.budget_tokens)
+          ? 'dots mark sessions at 75% (amber) and 100% (red) of your session token budget'
+          : `rows above ${fmtNum(avgTok * 3)} tokens are unusually expensive`}</span>
       </div><div id="st"></div>
       <div class="filters" style="margin-top:8px">
         <span class="note">Showing ${fmtInt(Math.min(rows.length, total))} of ${fmtInt(total)}</span>
@@ -1416,7 +1434,7 @@ VIEWS.sessions = async (page) => {
   if (sessMore) sessMore.onclick = () => { sp.offset += sp.limit; bust(); render(); };
   $('#st', page).innerHTML = table([
     {h: 'Session', trunc: 1, title: r => r.session_id,
-     f: r => `${r.tokens > avgTok * 3 ? dot('red') + ' ' : ''}${esc(stitle(r))}
+     f: r => `${sessFlag(r, avgTok)}${esc(stitle(r))}
        <div class="sub mono">${esc(shortId(r.session_id))}</div>`},
     {h: '', f: r => rowActs(r, live)},
     {h: 'Project', f: r => esc(r.project)},
@@ -1995,6 +2013,71 @@ const usageBody = u => {
     <div class="note">${esc(u.note || '')}${u.cached ? ` · read ${dur(u.age_s)} ago` : ''}${u.stale
       ? ` · <b>last good read</b> (refresh failed: ${esc(u.error || '')})` : ''}</div>`;
 };
+/* ---------- one running session's own token limit ---------- */
+function limitBadge(sid) {
+  const o = ((S.opts?.settings?.guard || {}).sessions || {})[sid];
+  if (!o) return '';
+  return o.off ? '<span class="pill" title="The session guard is off for this conversation">Guard off</span>'
+    : `<span class="pill" data-limit-badge="${esc(sid)}" title="This conversation's own token limit">Limit ${esc(fmtNum(o.session_tokens))}</span>`;
+}
+// The Set limit panel: tokens used so far (as the guard counts them), the limit box with
+// suggestions from that number, and save / remove / turn off.
+async function drawLimit(box, x, i) {
+  const sid = x.session_id;
+  box.innerHTML = '<div class="note">Counting this conversation\'s tokens…</div>';
+  let d;
+  try {
+    const r = await fetch(`/api/guard/session/${encodeURIComponent(sid)}`);
+    d = await r.json();
+    if (!r.ok) throw new Error(d.error || 'Could not read this session.');
+  } catch (e) { box.innerHTML = `<div class="live-msg err">${esc(e.message)}</div>`; return; }
+  const own = d.limit, id = `lim-${i}`, used = d.tokens || 0;
+  const now = own?.off ? 'The guard is off for this conversation.'
+    : own ? `This conversation's limit: <b>${fmtNum(own.session_tokens)}</b> (${fmtPct(100 * used / own.session_tokens, 0)} used).`
+    : d.applies ? `No limit of its own yet. It uses the per-session budget from Budgets: <b>${fmtNum(d.applies)}</b>.`
+    : 'No limit yet.';
+  box.innerHTML = `<div class="cfg">
+    <div class="fld-hint">Used so far: <b>${fmtNum(used)}</b> tokens. This counts everything the conversation has used,
+      including re-reading its context at every step, so it is much bigger than the context size above.</div>
+    ${d.installed ? '' : `<div class="lb-state warn" style="margin-top:6px">Live warnings are not installed, so a limit
+      here won't do anything yet. <button class="act" data-lim-setup>Set up live warnings</button></div>`}
+    <div class="fld-hint" style="margin-top:6px">${now}</div>
+    ${amountField({id, label: 'Token limit for this conversation', kind: 'tokens', value: own?.session_tokens ?? null,
+      chips: tokChips([[used * 1.1, '+10%'], [used * 1.25, '+25%'], [used * 1.5, '+50%'], [used * 2, '2×']], 3)})}
+    <div class="fld-hint">When this conversation reaches its limit, Claude Code asks you "continue?" before its next
+      step. Your warn percentages from Budgets apply too. The limit is forgotten after 30 days.</div>
+    <div class="live-actions">
+      <button class="act" data-lim-save>Save limit</button>
+      ${own ? '<button class="act ghost" data-lim-rm>Remove limit</button>' : ''}
+      ${own?.off ? '' : '<button class="act ghost" data-lim-off>Turn the guard off for this conversation</button>'}
+      <span class="live-msg" role="status"></span>
+    </div></div>`;
+  const inp = $('#' + id, box), msg = box.querySelector('.live-msg');
+  box.querySelectorAll('[data-fill]').forEach(c => c.onclick = () => {
+    inp.value = shortAmount(+c.dataset.v); inp.dispatchEvent(new Event('input')); });
+  inp.addEventListener('input', () => clearErr(box, id));
+  const setup = box.querySelector('[data-lim-setup]');
+  if (setup) setup.onclick = () => go('budgets');
+  const send = async (body, done) => {
+    try {
+      await doAction(`session_limit/${encodeURIComponent(sid)}`, body);
+      S.opts = await fetch('/api/options').then(r => r.json());
+      const hd = box.closest('.item')?.querySelector('.hd');
+      hd?.querySelectorAll('.pill[title]').forEach(p => p.remove());
+      hd?.querySelector('.spacer')?.insertAdjacentHTML('beforebegin', limitBadge(sid));
+      await drawLimit(box, x, i);
+      const m = box.querySelector('.live-msg'); if (m) { m.classList.add('ok'); m.textContent = done; }
+    } catch (e) { msg.classList.add('err'); msg.textContent = e.message; }
+  };
+  box.querySelector('[data-lim-save]').onclick = () => {
+    const e = amountError(inp) || (inp.value.trim() ? '' : 'Type a limit, or tap a suggestion.');
+    if (e) return setErr(box, id, e);
+    send({session_tokens: parseAmount(inp.value, 'tokens').value}, 'Saved. It applies from the next step.');
+  };
+  box.querySelector('[data-lim-rm]')?.addEventListener('click', () => send({remove: true}, 'Removed.'));
+  box.querySelector('[data-lim-off]')?.addEventListener('click', () => send({off: true}, 'The guard is off for this conversation.'));
+}
+
 VIEWS.live = async (page) => {
   const [res, usage0] = await Promise.all([
     fetch('/api/live?agents=' + encodeURIComponent(S.filter.agents.join(','))).then(r => r.json()),   // never cached: always live
@@ -2030,6 +2113,7 @@ VIEWS.live = async (page) => {
           <span class="pill">${esc(agentName(x.agent))}</span>
           ${esc((!MASKED && x.name) || shortId(x.session_id))} <span class="note">· ${esc(x.project)}${x.pid ? ` · pid ${x.pid}` : ''}${x.model ? ` · ${esc(x.model)}` : ''}</span>
           ${x.hosts_dashboard ? '<span class="status high">runs this dashboard</span>' : ''}
+          ${x.agent === 'claude' ? limitBadge(x.session_id) : ''}
           <span class="spacer"></span>
           <span style="font-variant-numeric:tabular-nums">${x.context == null ? 'context not recorded' : fmtNum(x.context) + ' context'} · ${fmtInt(x.steps)} steps${x.est_cost_usd == null ? '' : ' · ' + fmtUSD(x.est_cost_usd)}</span></div>
         <div class="dt">${x.status === 'busy' ? '<b>Working now</b>' : 'Idle'}${x.uptime ? ` · up ${esc(x.uptime)}` : ''} ·
@@ -2045,6 +2129,7 @@ VIEWS.live = async (page) => {
           <button class="act danger" data-a="kill">${I('x')} Force kill</button>` : `<span class="note">${x.agent === 'cursor' ? 'Runs inside the Cursor IDE: stop it there.' : 'No matching process found: stop it in its terminal.'}</span>`}
           ${x.resume ? `<button class="act ghost" data-copy="${esc(x.resume)}">Copy resume command</button>` : ''}
           ${x.agent === 'claude' ? '<button class="act ghost" data-ho="1">' + I('handover') + ' Hand over / split</button>' : ''}
+          ${x.agent === 'claude' && x.session_id ? '<button class="act ghost" data-lim="1">' + I('gauge') + ' Set limit</button>' : ''}
           <span class="live-msg"></span>
         </div>
         ${x.agent !== 'claude' ? '' : `<div class="handover" hidden>
@@ -2059,6 +2144,7 @@ VIEWS.live = async (page) => {
           </div>
           <div class="ho-out note"></div>
         </div>`}
+        ${x.agent === 'claude' && x.session_id ? `<div class="handover limitbox" hidden></div>` : ''}
       </div>`).join('') || `<div class="empty">No ${esc(agentWord())} sessions are running</div>`}</div>`;
   $('#live-refresh', page).onclick = () => render();
   const ub = $('#usage-refresh', page);
@@ -2094,6 +2180,11 @@ VIEWS.live = async (page) => {
     }
     row.querySelectorAll('button.act:not(.ho-go):not(.ho-brief)').forEach(b => {
       if (b.dataset.ho) { b.onclick = () => { ho.hidden = !ho.hidden; if (!ho.hidden) ta.focus(); }; return; }
+      if (b.dataset.lim) {
+        const box = row.querySelector('.limitbox');
+        b.onclick = () => { box.hidden = !box.hidden; if (!box.hidden) drawLimit(box, x, +row.dataset.i); };
+        return;
+      }
       if (b.dataset.copy) { b.onclick = async () => { try { await navigator.clipboard.writeText(b.dataset.copy); msg.textContent = 'Copied'; } catch { msg.textContent = b.dataset.copy; } }; return; }
       const label = b.textContent;
       b.onclick = async () => {
@@ -2327,22 +2418,395 @@ VIEWS.forecast = async (page) => {
 };
 
 /* ---------- budgets ---------- */
+/* ---------- budgets form helpers ---------- */
+// "20M", "500k", "$3,000", "2.5B" -> number; blank -> null. kind: 'tokens' | 'usd' | 'count'
+function parseAmount(raw, kind) {
+  const s = String(raw ?? '').trim().replace(/[,\s_]/g, '').replace(/^\$/, '');
+  if (s === '') return {value: null};
+  const m = /^(\d+(?:\.\d+)?|\.\d+)([kmb])?$/i.exec(s);
+  if (!m) return {error: kind === 'usd' ? 'Enter an amount like 3000, $3,000 or 3k.'
+                        : 'Enter a number like 20M, 500k or 2,000,000.'};
+  const v = parseFloat(m[1]) * ({k: 1e3, m: 1e6, b: 1e9}[(m[2] || '').toLowerCase()] || 1);
+  return {value: kind === 'usd' ? Math.round(v * 100) / 100 : Math.round(v)};
+}
+// Round up to `sig` significant figures (two by default), so suggestions are round numbers.
+const niceUp = (v, sig = 2) => {
+  if (!(v > 0)) return 0;
+  const p = 10 ** (Math.floor(Math.log10(v)) - sig + 1);
+  return Math.ceil(v / p - 1e-9) * p;
+};
+// 8400000 -> "8.4M": compact, and parseAmount reads it back exactly for round numbers.
+function shortAmount(v) {
+  const u = [[1e9, 'B'], [1e6, 'M'], [1e3, 'k']].find(([d]) => Math.abs(v) >= d);
+  return u ? +(v / u[0]).toFixed(2) + u[1] : String(Math.round(v));
+}
+// items: a number, or [value, label, title]; data-driven ones are rounded up, zeros dropped
+function suggChips(items, fmt, sig = 2) {
+  const seen = new Set();
+  return items.map(it => Array.isArray(it) ? {v: niceUp(it[0], sig), l: it[1], t: it[2]} : {v: it})
+    .filter(c => c.v > 0 && !seen.has(c.v) && seen.add(c.v))
+    .map(c => ({...c, l: c.l ? `${c.l} · ${fmt(c.v)}` : fmt(c.v)}));
+}
+const usdChips = items => suggChips(items, v => '$' + shortAmount(v));
+const tokChips = (items, sig) => suggChips(items, shortAmount, sig);
+
+function amountField({id, label, value, kind, zero, chips = [], hint = ''}) {
+  const shown = value == null ? '' : kind === 'usd' ? String(value) : Number(value).toLocaleString('en-US');
+  return `<div class="fld">
+    <div class="hd"><label for="${id}">${label}</label></div>
+    <input type="text" inputmode="decimal" id="${id}" data-kind="${kind}" ${zero ? 'data-zero="1"' : ''}
+      value="${esc(shown)}" placeholder="not set" autocomplete="off" spellcheck="false"
+      aria-describedby="${id}-hint ${id}-err">
+    ${chips.length ? `<div class="sugg" aria-label="Suggestions">${chips.map(c =>
+      `<button type="button" class="chip" data-fill="${id}" data-v="${c.v}" title="${esc(c.t || 'Use this value')}">${esc(c.l)}</button>`).join('')}</div>` : ''}
+    <div class="fld-hint" id="${id}-hint">${hint}</div>
+    <div class="fld-err" id="${id}-err" role="alert"></div>
+  </div>`;
+}
+// The reason a typed amount is not acceptable, or '' when it is (blank is always fine).
+function amountError(el) {
+  const r = parseAmount(el.value, el.dataset.kind);
+  if (r.error) return r.error;
+  if (r.value == null) return '';
+  if (r.value < 0) return 'Cannot be negative.';
+  if (r.value === 0 && !el.dataset.zero) return 'Must be more than 0, or leave it blank.';
+  return '';
+}
+// Toggle chips for a list of percentages, plus a box to add another one.
+function pctField({id, label, values, presets, max}) {
+  const all = [...new Set([...presets, ...values])].sort((a, b) => a - b);
+  return `<div class="fld"><div class="hd">${label}</div>
+    <div class="sugg" id="${id}" data-max="${max}">${all.map(p =>
+      `<button type="button" class="chip ${values.includes(p) ? 'on' : ''}" data-pct="${p}" aria-pressed="${values.includes(p)}">${p}%</button>`).join('')}
+      <input type="text" inputmode="decimal" class="pct-add" placeholder="+ other %" aria-label="Add another percentage"
+        style="width:92px;padding:2px 8px;border-radius:99px">
+    </div>
+    <div class="fld-err" id="${id}-err" role="alert"></div></div>`;
+}
+function wirePct(page) {
+  page.querySelectorAll('.cfg [data-max]').forEach(box => {
+    const toggle = b => b.onclick = () => {
+      b.classList.toggle('on'); b.setAttribute('aria-pressed', b.classList.contains('on'));
+      clearErr(page, box.id);
+    };
+    box.querySelectorAll('[data-pct]').forEach(toggle);
+    const add = box.querySelector('.pct-add');
+    const commit = () => {
+      const raw = add.value.trim().replace(/%$/, '');
+      if (!raw) return;
+      const v = +raw, max = +box.dataset.max;
+      if (!Number.isFinite(v) || v < 1 || v > max) return setErr(page, box.id, `Enter a percentage from 1 to ${max}.`);
+      let b = box.querySelector(`[data-pct="${v}"]`);
+      if (!b) {
+        b = h(`<button type="button" class="chip" data-pct="${v}" aria-pressed="false">${v}%</button>`);
+        const after = [...box.querySelectorAll('[data-pct]')].find(x => +x.dataset.pct > v);
+        box.insertBefore(b, after || add);
+        toggle(b);
+      }
+      if (!b.classList.contains('on')) b.click();
+      add.value = '';
+      clearErr(page, box.id);
+    };
+    add.onkeydown = e => { if (e.key === 'Enter') { e.preventDefault(); commit(); } };
+    add.onblur = commit;
+  });
+}
+function setErr(page, id, text) {
+  const e = $('#' + id + '-err', page); if (e) e.textContent = text;
+  const el = $('#' + id, page) || $('#' + id + '-tok', page);
+  if (el && el.tagName !== 'DIV') el.classList.add('bad');
+}
+function clearErr(page, id) {
+  const e = $('#' + id + '-err', page); if (e) e.textContent = '';
+  [$('#' + id, page), $('#' + id + '-tok', page), $('#' + id + '-path', page)]
+    .forEach(el => el && el.classList.remove('bad'));
+}
+
+// API keys: status only ever comes back from the server, never the key itself.
+async function drawKeys(page) {
+  const host = $('#cfg-keys', page);
+  if (!host) return;
+  let ks;
+  try { ks = await fetch('/api/keys').then(r => r.json()); }
+  catch (e) { host.innerHTML = '<div class="note">Could not read the key status.</div>'; return; }
+  host.innerHTML = Object.entries(ks).map(([pid, k]) => `
+    <div class="item">
+      <div class="hd">${esc(k.name)}<span class="spacer"></span>
+        <span class="badge ${k.source ? '' : 'na'}">${k.source === 'env' ? 'set by $' + esc(k.env)
+          : k.source === 'stored' ? 'stored' + (k.last4 ? ' · ends ' + esc(k.last4) : '') : 'not set'}</span></div>
+      <div class="dt"><b>Gives you:</b> ${esc(k.covers)}</div>
+      <div class="dt"><b>Get a key:</b> ${esc(k.how)}</div>
+      ${k.source === 'env'
+        ? `<div class="fld-hint">The ${esc(k.env)} environment variable takes priority. Unset it to manage the key here.</div>`
+        : `<div style="display:flex;gap:6px;align-items:center;margin-top:6px">
+            <input type="password" id="key-${pid}" autocomplete="off" spellcheck="false" style="flex:1;min-width:0"
+              aria-label="${esc(k.name)} key" placeholder="${k.source ? 'paste a new key to replace it' : 'paste the key'}">
+            <button class="act" data-keysave="${pid}">Save key</button>
+            ${k.source === 'stored' ? `<button class="act" data-keyrm="${pid}">Remove</button>` : ''}
+          </div>`}
+      <div class="fld-err" id="key-${pid}-err" role="alert"></div>
+      <div class="fld-hint ok" id="key-${pid}-ok" role="status"></div>
+    </div>`).join('');
+  const done = async (pid, text) => {
+    S.opts = await fetch('/api/options').then(r => r.json());
+    applyAgentChrome();                    // Billed vs local appears once a key exists
+    await drawKeys(page);
+    const ok = $('#key-' + pid + '-ok', page); if (ok) ok.textContent = text;
+  };
+  host.querySelectorAll('[data-keysave]').forEach(b => {
+    const pid = b.dataset.keysave, inp = $('#key-' + pid, host), err = $('#key-' + pid + '-err', host);
+    inp.oninput = () => { err.textContent = ''; inp.classList.remove('bad'); };
+    inp.onkeydown = e => { if (e.key === 'Enter') b.click(); };
+    b.onclick = async () => {
+      if (!inp.value.trim()) { err.textContent = 'Paste a key first.'; inp.classList.add('bad'); return; }
+      b.disabled = true;
+      try {
+        await doAction('key/' + pid, {value: inp.value});
+        inp.value = '';
+        await done(pid, 'Saved. Billed vs local uses it on the next Refresh.');
+      } catch (e) { err.textContent = e.message; inp.classList.add('bad'); b.disabled = false; }
+    };
+  });
+  host.querySelectorAll('[data-keyrm]').forEach(b => b.onclick = async () => {
+    if (!b.dataset.armed) {            // two clicks, like the other destructive actions
+      b.dataset.armed = '1'; b.textContent = 'Click again to remove';
+      setTimeout(() => { if (b.isConnected) { delete b.dataset.armed; b.textContent = 'Remove'; } }, 4000);
+      return;
+    }
+    const pid = b.dataset.keyrm;
+    try { await doAction('key/' + pid, {remove: true}); await done(pid, 'Removed.'); }
+    catch (e) { const err = $('#key-' + pid + '-err', host); if (err) err.textContent = e.message; }
+  });
+}
+
+/* ---------- guides: picture slides that explain a page ---------- */
+const GUIDES = {};
+let GUIDE = null;          // {name, i, opener, el}
+const guideSeenKey = name => `finops.guide.${name}.seen`;
+
+function openGuide(name, slideId, opener) {
+  const slides = GUIDES[name];
+  if (!slides || !slides.length) return;
+  closeGuide();
+  const el = document.createElement('div');
+  el.className = 'guide-layer';
+  el.innerHTML = `<div class="guide" role="dialog" aria-modal="true" aria-labelledby="guide-title" tabindex="-1"></div>`;
+  document.body.appendChild(el);
+  el.addEventListener('click', e => { if (e.target === el) closeGuide(); });
+  GUIDE = {name, i: Math.max(0, slides.findIndex(s => s.id === slideId)), opener: opener || document.activeElement, el};
+  document.addEventListener('keydown', guideKeys, true);
+  try { localStorage.setItem(guideSeenKey(name), '1'); } catch (_) {}
+  drawGuide();
+}
+function closeGuide() {
+  if (!GUIDE) return;
+  const {el, opener} = GUIDE;
+  GUIDE = null;
+  document.removeEventListener('keydown', guideKeys, true);
+  el.remove();
+  if (opener && opener.isConnected && opener.focus) opener.focus();
+}
+function guideKeys(e) {
+  if (!GUIDE) return;
+  e.stopPropagation();
+  const slides = GUIDES[GUIDE.name];
+  if (e.key === 'Escape') { e.preventDefault(); closeGuide(); }
+  else if (e.key === 'ArrowRight' && GUIDE.i < slides.length - 1) { e.preventDefault(); GUIDE.i++; drawGuide(); }
+  else if (e.key === 'ArrowLeft' && GUIDE.i > 0) { e.preventDefault(); GUIDE.i--; drawGuide(); }
+  else if (e.key === 'Tab') {                       // keep focus inside the dialog
+    const f = [...GUIDE.el.querySelectorAll('button:not([disabled]), a[href]')];
+    if (!f.length) return;
+    const first = f[0], last = f[f.length - 1];
+    if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+    else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+  }
+}
+function drawGuide() {
+  const slides = GUIDES[GUIDE.name], s = slides[GUIDE.i], n = slides.length, last = GUIDE.i === n - 1;
+  const box = GUIDE.el.querySelector('.guide');
+  box.innerHTML = `
+    <header><span class="g-step">${GUIDE.i + 1} of ${n}</span>
+      <h2 id="guide-title">${esc(s.title)}</h2>
+      <button class="act g-x" data-g="close" aria-label="Close guide">${I('x')}</button></header>
+    <div class="g-pic">${s.img
+      ? `<span class="g-fig"><img src="${esc(s.img)}" alt="${esc(s.alt || '')}">${(s.marks || []).map(m =>
+          `<span class="g-mark" style="left:${m.x}%;top:${m.y}%">${m.n}</span>`).join('')}</span>`
+      : '<div class="g-ex">Example</div><div class="g-live"></div>'}</div>
+    <div class="g-text" aria-live="polite">${s.text.map(t => `<p>${t}</p>`).join('')}</div>
+    <footer>
+      <div class="g-dots" aria-hidden="true">${slides.map((_, i) => `<i class="${i === GUIDE.i ? 'on' : ''}"></i>`).join('')}</div>
+      <span class="spacer"></span>
+      ${s.target ? '<button class="act" data-g="show">Show me on the page</button>' : ''}
+      <button class="act" data-g="back" ${GUIDE.i ? '' : 'disabled'}>Back</button>
+      <button class="chip on" data-g="${last ? 'close' : 'next'}">${last ? 'Done' : 'Next'}</button>
+    </footer>`;
+  if (s.live) s.live(box.querySelector('.g-live'));
+  box.querySelectorAll('[data-g]').forEach(b => b.onclick = () => {
+    const a = b.dataset.g;
+    if (a === 'close') closeGuide();
+    else if (a === 'next') { GUIDE.i++; drawGuide(); }
+    else if (a === 'back') { GUIDE.i--; drawGuide(); }
+    else if (a === 'show') { const t = s.target; closeGuide(); showMe(t); }
+  });
+  (box.querySelector('[data-g="next"], [data-g="close"]:not(.g-x)') || box).focus();
+}
+function showMe(selector) {
+  const t = $(selector);
+  if (!t) return;
+  if (t.tagName === 'DETAILS') t.open = true;
+  t.scrollIntoView({block: 'center', behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth'});
+  t.classList.remove('pulse'); void t.offsetWidth; t.classList.add('pulse');
+  setTimeout(() => t.classList.remove('pulse'), 2200);
+}
+// First visit to a page with a guide: open it once. Never on top of the welcome tour.
+function maybeGuide(name) {
+  let seen = true;
+  try { seen = localStorage.getItem(guideSeenKey(name)) === '1'; } catch (_) {}
+  if (seen || !GUIDES[name]) return;
+  const tryOpen = () => {
+    if (S.view !== name || GUIDE) return;
+    try { if (localStorage.getItem(guideSeenKey(name)) === '1') return; } catch (_) {}
+    if (TOUR) return setTimeout(tryOpen, 800);     // wait for the welcome tour to finish
+    openGuide(name);
+  };
+  setTimeout(tryOpen, 400);
+}
+
+// A frozen copy of a form block for a guide picture: demo values, no ids that clash.
+function guideCopy(host, html) {
+  host.innerHTML = `<div class="cfg">${html}</div>`;
+  host.querySelectorAll('[id]').forEach(el => el.id = 'gcopy-' + el.id);
+  host.querySelectorAll('[for]').forEach(el => el.setAttribute('for', 'gcopy-' + el.getAttribute('for')));
+  host.querySelectorAll('[aria-describedby]').forEach(el => el.setAttribute('aria-describedby',
+    el.getAttribute('aria-describedby').split(/\s+/).filter(Boolean).map(t => 'gcopy-' + t).join(' ')));
+  host.querySelectorAll('input, select, button, textarea').forEach(el => { el.disabled = true; el.tabIndex = -1; });
+}
+const DEMO = {spend: 312, day: 14, busy: 29, tokens: 7.4e8, typical: 8.5e6, large: 3.3e7};
+
+GUIDES.budgets = [
+  {id: 'overview', title: 'What is this page?', img: 'guide/budgets.png',
+   alt: 'The Budgets page: your results on one side, your limits on the other',
+   marks: [{n: 1, x: 30, y: 8.5}, {n: 2, x: 96, y: 26}, {n: 3, x: 94, y: 51.5}],
+   text: ['This page helps you stop spending too much on AI.',
+          '<b>①</b> The results show how you are doing so far. <b>②</b> Here you set your money and token limits. <b>③</b> The session limit stops one conversation from getting too big. (On the real page the results are at the top and the limits are below them.)',
+          'You only need to fill in what you care about. Everything else can stay empty.'],
+   target: '[data-blk="money"]'},
+  {id: 'money', title: '① Money limits', target: '[data-blk="money"]',
+   live: h => guideCopy(h, `<div class="grid g2">
+     ${amountField({id: 'b-monthly', label: 'Monthly budget (USD)', kind: 'usd', value: 400,
+        chips: usdChips([[DEMO.spend, 'Last 30 days'], 250, 500])})}
+     ${amountField({id: 'b-daily', label: 'Daily budget (USD)', kind: 'usd', value: null,
+        chips: usdChips([[DEMO.day, 'Average day'], [DEMO.busy, 'Busy day']])})}</div>`),
+   text: ['Type the most money you want to spend in a month, or in a day.',
+          'Not sure? Tap a suggestion. They come from your own recent spending.',
+          'We warn you as you get close. Leave a box empty if you don\'t need it.']},
+  {id: 'tokens', title: '② Token limits', target: '[data-blk="tokens"]',
+   live: h => guideCopy(h, amountField({id: 'b-tokens', label: 'Monthly token budget', kind: 'tokens',
+     value: 9e8, chips: tokChips([[DEMO.tokens, 'Last 30 days'], 1e9, 5e9])})),
+   text: ['A token is a small piece of text, about ¾ of a word. Claude counts all its work in tokens.',
+          'Set how many tokens you want to use in a month. You can type short numbers like <b>900M</b> or <b>2B</b>.']},
+  {id: 'session', title: '③ Session limit', target: '[data-blk="session"]',
+   live: h => guideCopy(h, `<div class="grid g2">
+     ${amountField({id: 'g-tokens', label: 'Per-session token budget', kind: 'tokens', value: 8e6,
+        chips: tokChips([[DEMO.typical, 'Typical'], [DEMO.large, 'Large'], 5e6, 10e6])})}
+     ${pctField({id: 'g-warn', label: 'Warn me at', values: [75, 80], presets: [50, 60, 70, 75, 80, 90], max: 99})}</div>`),
+   text: ['A session is one Claude Code conversation.',
+          'Long conversations cost more, because Claude re-reads everything each time.',
+          'Set a limit for one conversation. Then pick when you want a warning, like at 75% and 80%.']},
+  {id: 'after', title: 'After you say "continue", and project limits', target: '#g-projects',
+   live: h => guideCopy(h, `<div class="grid g2">
+     <div class="fld"><div class="hd">After I say "continue"</div>
+       <label style="display:flex;gap:6px;margin:6px 0"><input type="radio" checked> Ask again every +25%</label>
+       <label style="display:flex;gap:6px;margin:6px 0"><input type="radio"> Once per session</label></div>
+     <div class="fld"><div class="hd">Different limit for a project</div>
+       <div style="display:flex;gap:6px;align-items:center"><select><option>shop-app</option></select>
+         <input type="text" value="15M" style="width:90px"><label><input type="checkbox"> off</label></div></div></div>`),
+   text: ['When a conversation reaches its limit, you can let it keep going.',
+          'Choose if we ask you again a bit later, or never again for that conversation.',
+          'A big project can have its own, bigger limit. Or you can turn the limit off for it.']},
+  {id: 'live', title: 'Live warnings (optional)', target: '#livebox',
+   live: h => { h.innerHTML = `<div class="cfg"><div class="livebox"><div class="lb-head"><b>Live warnings in Claude Code</b>
+       <span class="blk-sub">(optional)</span><span class="spacer"></span><span class="lb-state">○ Not installed</span>
+       <button class="act" disabled>Install</button></div></div>
+       <div class="g-cc">Session guard: this session has used 8.4M tokens, 105% of its 8M budget.
+         Allow this tool call? <b>❯ Yes</b> &nbsp; No</div></div>`; },
+   text: ['<b>You don\'t need this for your limits to work.</b>',
+          'Install it if you want Claude Code itself to warn you while you work, and to ask "continue?" when a conversation reaches its limit. The dark box shows what that looks like.',
+          'You can uninstall it any time.']},
+  {id: 'advanced', title: 'Advanced (you can skip this)', target: '[data-blk="advanced"]',
+   live: h => guideCopy(h, `<div class="grid g2">
+     ${amountField({id: 'l-cost', label: 'Monthly cost allowance (USD)', kind: 'usd', zero: 1, value: null})}
+     ${pctField({id: 't-thr', label: 'Warn when a budget reaches', values: [50, 75, 90, 100], presets: [25, 50, 75, 90, 100, 110], max: 1000})}</div>`),
+   text: ['<b>Plan limits:</b> only fill these in if you know your plan\'s real numbers.',
+          '<b>Alert thresholds:</b> when a money or token limit reaches these percentages, it gets marked.',
+          'Most people never need to change these.']},
+  {id: 'save', title: 'Save, then check your results', target: '#savecfg',
+   live: h => { h.innerHTML = `<div class="cfg"><div class="save-row"><button class="chip on" disabled>Save</button>
+       <span class="ok">Saved.</span></div>
+       <div class="meter high" style="margin:8px 0"><i style="width:82%"></i></div>
+       <div class="fld-hint">Monthly spend · 82% used</div>
+       <div style="margin-top:8px">${dot('yellow')} a conversation at 75% of its limit &nbsp; ${dot('red')} over its limit</div></div>`; },
+   text: ['Press <b>Save</b>. Your limits are kept on this computer.',
+          'The top of this page then shows how you are doing against each limit.',
+          'On the <b>Sessions</b> page, amber and red dots show conversations near or over their limit.']},
+];
+
+
 VIEWS.budgets = async (page) => {
   const b = await api('budgets');
   const st = S.opts.settings;
+  const sg = st.guard || {};
+  // suggestions from your own recent usage (see Analytics.budget_suggestions)
+  const SG = b.suggest || {}, sizes = SG.session_tokens || [];
+  const pctile = q => sizes.length ? sizes[Math.min(sizes.length - 1, Math.floor(q * sizes.length))] : 0;
+  const overShare = v => {
+    let lo = 0, hi = sizes.length;
+    while (lo < hi) { const m = (lo + hi) >> 1; if (sizes[m] > v) hi = m; else lo = m + 1; }
+    const n = sizes.length - lo;
+    return n ? `${fmtInt(n)} of your ${fmtInt(sizes.length)} past sessions (${fmtPct(100 * n / sizes.length, 0)}) went over this.`
+      : `None of your ${fmtInt(sizes.length)} past sessions went over this.`;
+  };
+  const HINTS = {
+    'b-monthly': v => v ? `At your last-30-days pace (${fmtUSD(SG.spend_30d)}) you would use ${fmtPct(100 * SG.spend_30d / v, 0)} of this.`
+      : `Last 30 days: ${fmtUSD(SG.spend_30d)} (estimated).`,
+    'b-daily': () => `Your average day is ${fmtUSD(SG.daily_avg)}; 1 day in 10 costs more than ${fmtUSD(SG.daily_p90)}.`,
+    'b-tokens': v => v ? `The last 30 days used ${fmtNum(SG.tokens_30d)} tokens, ${fmtPct(100 * SG.tokens_30d / v, 0)} of this.`
+      : `Last 30 days: ${fmtNum(SG.tokens_30d)} tokens.`,
+    'g-tokens': v => !sizes.length ? '' : v ? overShare(v) : `Half your sessions stay under ${fmtNum(pctile(.5))} tokens.`,
+  };
+  const planHint = `Your own figure, from your plan or invoice. ${esc(agentWord())} data does not include it.`;
+  const stepVal = sg.step_pct ?? 25;
+  // Does any per-session budget exist (global or a project override)? The hook needs one.
+  const anyBudget = !!sg.session_tokens || [sg.projects, sg.sessions].some(m => Object.values(m || {}).some(o => o.session_tokens));
+  const liveBox = () => {
+    const on = !!S.opts.guard_installed;
+    const state = !on ? `<span class="lb-state">○ Not installed</span>`
+      : anyBudget ? `<span class="lb-state on">● Installed · works in new Claude Code sessions</span>`
+      : `<span class="lb-state warn">Installed, but it does nothing until you set a per-session token budget above.</span>`;
+    return `<div class="livebox" id="livebox">
+      <div class="lb-head"><b>Live warnings in Claude Code</b> <span class="blk-sub">(optional)</span>
+        <span class="spacer"></span>${state}
+        <button class="act" id="g-install">${on ? 'Uninstall' : 'Install'}</button></div>
+      <p>Your limits above already work without this. Install it if you want Claude Code itself to warn
+        you at your warn percentages, and ask "continue?" when a conversation reaches its limit.</p>
+      <p class="blk-sub">It is a small helper that runs inside Claude Code. Needs: a per-session token budget.
+        It cannot end a conversation, and if it ever fails it lets Claude carry on. Undo any time.</p>
+      <div class="fld-hint" id="g-msg" role="status"></div></div>`;
+  };
   page.innerHTML = `
-    ${card('Budget vs actual vs forecast', `<div class="stack">${b.lines.map(l => l.configured ? `
+    ${card('Budget vs actual vs forecast', `<p class="blk-intro" style="margin-top:0">How you're doing against your limits. Set your limits below.</p><div class="stack">${b.lines.map(l => l.configured ? `
       <div class="item">
         <div class="hd">${esc(l.name)}<span class="spacer"></span>${statusChip(l.status)}</div>
         <div class="grid g4" style="gap:8px;margin:4px 0">
           ${kpi('Budget', l.unit === 'tokens' ? fmtNum(l.budget) : fmtUSD(l.budget), null, {small: 1})}
           ${kpi('Actual', l.unit === 'tokens' ? fmtNum(l.actual) : fmtUSD(l.actual),
             fmtPct(l.used_pct) + ' used', {small: 1, badge: BADGE.estimated})}
-          ${kpi('Forecast', l.forecast == null ? null
+          ${kpi('Forecast', l.sessions_over != null ? '—' : l.forecast == null ? null
             : (l.unit === 'tokens' ? fmtNum(l.forecast) : fmtUSD(l.forecast)),
-            l.forecast_pct == null ? '' : fmtPct(l.forecast_pct) + ' of budget',
+            l.sessions_over != null ? 'not forecast per session'
+              : l.forecast_pct == null ? '' : fmtPct(l.forecast_pct) + ' of budget',
             {small: 1, badge: BADGE.forecast})}
-          ${kpi('Variance', l.variance == null ? null
+          ${kpi('Variance', l.sessions_over != null ? '—' : l.variance == null ? null
             : (l.variance >= 0 ? '+' : '') + (l.unit === 'tokens' ? fmtNum(l.variance) : fmtUSD(l.variance)),
             l.variance == null ? '' : (l.variance > 0 ? 'over budget' : 'under budget'), {small: 1})}
         </div>
@@ -2351,6 +2815,9 @@ VIEWS.budgets = async (page) => {
           ${l.thresholds_breached.length ? `<span>${I('alert')} breached ${l.thresholds_breached.join('%, ')}%</span>` : '<span>No threshold breached</span>'}
           ${l.thresholds_forecast_breach.length
             ? `<span style="color:var(--serious-ink)">forecast to breach ${l.thresholds_forecast_breach.join('%, ')}%</span>` : ''}
+          ${l.sessions_over == null ? '' : `<span title="Most of a long session's tokens are cache reads, priced at about a tenth of the input rate.">
+            ${l.sessions_over ? `<a href="#" data-over="1">${fmtInt(l.sessions_over)} session${l.sessions_over === 1 ? '' : 's'} over budget this period</a>`
+              : 'No session over budget this period'} · largest session shown</span>`}
         </div></div>`
       : `<div class="item"><div class="hd">${esc(l.name)}<span class="spacer"></span>
           <span class="badge na">not configured</span></div>
@@ -2358,57 +2825,238 @@ VIEWS.budgets = async (page) => {
             (estimated). Set a budget below to track variance and get threshold warnings.</div></div>`
       ).join('')}</div>`, {badge: BADGE.estimated,
       hint: `alert thresholds: ${b.thresholds_pct.join('%, ')}%`})}
-    ${card('Configure budgets, limits and thresholds', `
-      <div class="grid g3">
-        <div><div class="hd" style="font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.07em;font-weight:620;margin-bottom:6px">Budgets</div>
-          <label class="pop" style="position:static;display:block;border:none;box-shadow:none;padding:0">
-            <div class="hd">Monthly budget (USD)</div>
-            <input type="number" step="1" id="b-monthly" value="${st.budgets.monthly_usd ?? ''}" placeholder="not set">
-            <div class="hd">Daily budget (USD)</div>
-            <input type="number" step="0.5" id="b-daily" value="${st.budgets.daily_usd ?? ''}" placeholder="not set">
-            <div class="hd">Monthly token budget</div>
-            <input type="number" id="b-tokens" value="${st.budgets.monthly_tokens ?? ''}" placeholder="not set">
-          </label></div>
-        <div><div class="hd" style="font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.07em;font-weight:620;margin-bottom:6px">Plan limits</div>
-          <label class="pop" style="position:static;display:block;border:none;box-shadow:none;padding:0">
-            <div class="hd">Monthly cost allowance (USD)</div>
-            <input type="number" step="1" id="l-cost" value="${st.limits.monthly_cost_allowance_usd ?? ''}" placeholder="not exposed by ${agentWord()} data">
-            <div class="hd">Monthly token allowance</div>
-            <input type="number" id="l-tok" value="${st.limits.monthly_token_allowance ?? ''}" placeholder="not exposed by ${agentWord()} data">
-            <div class="hd">Monthly request allowance</div>
-            <input type="number" id="l-req" value="${st.limits.monthly_request_allowance ?? ''}" placeholder="not exposed by ${agentWord()} data">
-            <div class="hd">Remaining credits (USD)</div>
-            <input type="number" step="0.01" id="l-cred" value="${st.limits.remaining_credits_usd ?? ''}" placeholder="not exposed by ${agentWord()} data">
-          </label></div>
-        <div><div class="hd" style="font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.07em;font-weight:620;margin-bottom:6px">Alert thresholds</div>
-          <label class="pop" style="position:static;display:block;border:none;box-shadow:none;padding:0">
-            <div class="hd">Comma-separated %</div>
-            <input type="text" id="t-thr" value="${st.alert_thresholds_pct.join(',')}"
-              style="width:100%;padding:5px 7px;border-radius:6px;border:1px solid var(--border);background:var(--surface-2)">
-          </label>
-          <button class="chip on" id="savecfg" style="margin-top:10px;width:100%;justify-content:center">Save configuration</button>
-          <div class="note" style="margin-top:8px">Writes to <span class="mono">config/settings.json</span>.
-          Leave a field blank to keep it unconfigured — the dashboard will report it as unavailable
-          rather than inventing a value.</div>
+    ${card('Set your limits', `<div class="cfg">
+      <section class="blk" data-blk="money">
+        <h4><span class="num">①</span> Money limits <button type="button" class="blk-help" data-guide="money" aria-label="Help: money limits">?</button></h4>
+        <p class="blk-intro">Set the most money you want to spend. We warn you before you go over.</p>
+        <div class="grid g2">
+          ${amountField({id: 'b-monthly', label: 'Monthly budget (USD)', kind: 'usd', value: st.budgets.monthly_usd,
+            chips: usdChips([[SG.spend_30d, 'Last 30 days', 'Your estimated spend over the last 30 days, rounded up'],
+                             [SG.spend_30d * 1.1, 'Last 30 days +10%', 'Some headroom over your recent spend'],
+                             1000, 2500, 5000])})}
+          ${amountField({id: 'b-daily', label: 'Daily budget (USD)', kind: 'usd', value: st.budgets.daily_usd,
+            chips: usdChips([[SG.daily_avg, 'Average day', 'Your average day over the last 30 days, rounded up'],
+                             [SG.daily_p90, 'Busy day', '1 day in 10 costs more than this'], 50, 100, 250])})}
+        </div>
+      </section>
+      <section class="blk" data-blk="tokens">
+        <h4><span class="num">②</span> Token limits <button type="button" class="blk-help" data-guide="tokens" aria-label="Help: token limits">?</button></h4>
+        <p class="blk-intro">Tokens are the small pieces of text Claude reads and writes (about ¾ of a word).
+          Set how many you want to use in a month.</p>
+        <div class="grid g2">
+          ${amountField({id: 'b-tokens', label: 'Monthly token budget', kind: 'tokens', value: st.budgets.monthly_tokens,
+            chips: tokChips([[SG.tokens_30d, 'Last 30 days', 'Billable tokens over the last 30 days, rounded up'],
+                             1e9, 5e9, 10e9])})}
+          <div></div>
         </div>
-      </div>`, {footer: `Plan allowances are NOT available from ${agentWord()} data. Anything you enter here is your own declared figure, used only to compute usage-vs-limit and days-until-limit.`})}`;
+      </section>
+      <section class="blk" data-blk="session">
+        <h4><span class="num">③</span> Session limit <button type="button" class="blk-help" data-guide="session" aria-label="Help: session limit">?</button></h4>
+        <p class="blk-intro">A session is one Claude Code conversation. Stop one conversation from getting too big.</p>
+        <div class="grid g3">
+        <div>
+          ${amountField({id: 'g-tokens', label: 'Per-session token budget', kind: 'tokens', value: sg.session_tokens,
+            chips: tokChips([[pctile(.75), 'Typical', '3 in 4 of your sessions stay under this'],
+                             [pctile(.9), 'Large', '9 in 10 of your sessions stay under this'],
+                             5e6, 10e6, 25e6, 50e6])})}
+          ${pctField({id: 'g-warn', label: 'Warn me at', values: sg.warn_pct || [], presets: [50, 60, 70, 75, 80, 90], max: 99})}
+        </div>
+        <div>
+          <div class="fld"><div class="hd">After I say "continue"</div>
+            <label style="display:flex;gap:6px;align-items:center;margin:6px 0;flex-wrap:wrap">
+              <input type="radio" name="g-after" value="step" ${sg.after_approval !== 'once' ? 'checked' : ''}>
+              Ask again every
+              <select id="g-step-sel" style="width:auto">
+                ${[10, 25, 50, 100].map(v => `<option value="${v}" ${stepVal === v ? 'selected' : ''}>+${v}%</option>`).join('')}
+                <option value="other" ${[10, 25, 50, 100].includes(stepVal) ? '' : 'selected'}>other…</option>
+              </select>
+              <input type="text" inputmode="decimal" id="g-step" value="${stepVal}" placeholder="%"
+                style="width:64px;${[10, 25, 50, 100].includes(stepVal) ? 'display:none' : ''}"></label>
+            <label style="display:flex;gap:6px;align-items:center;margin:6px 0">
+              <input type="radio" name="g-after" value="once" ${sg.after_approval === 'once' ? 'checked' : ''}>
+              Once per session</label>
+            <div class="fld-err" id="g-step-err" role="alert"></div>
+          </div>
+        </div>
+        <div>
+          <div class="fld"><div class="hd">Different limit for a project</div>
+            <div id="g-projects"></div>
+            <datalist id="gtok-list">${[pctile(.75), pctile(.9), 5e6, 10e6, 25e6, 50e6].filter(v => v > 0)
+              .map(v => `<option value="${shortAmount(niceUp(v))}">`).join('')}</datalist>
+            <button class="act" id="g-add" style="margin-top:6px">${I('plus')} Add override</button>
+          </div>
+        </div>
+        </div>
+        ${liveBox()}
+      </section>
+      <details class="blk adv" data-blk="advanced">
+        <summary><h4>Advanced: plan limits and alert thresholds <span class="blk-sub">(most people can skip this)</span>
+          <button type="button" class="blk-help" data-guide="advanced" aria-label="Help: advanced">?</button></h4></summary>
+        <div class="grid g2">
+          <div><div class="sec">Plan limits</div>
+          <div class="fld-hint" style="margin:-2px 2px 6px">${planHint}</div>
+          ${amountField({id: 'l-cost', label: 'Monthly cost allowance (USD)', kind: 'usd', zero: 1,
+            value: st.limits.monthly_cost_allowance_usd})}
+          ${amountField({id: 'l-tok', label: 'Monthly token allowance', kind: 'tokens', zero: 1,
+            value: st.limits.monthly_token_allowance})}
+          ${amountField({id: 'l-req', label: 'Monthly request allowance', kind: 'count', zero: 1,
+            value: st.limits.monthly_request_allowance})}
+          ${amountField({id: 'l-cred', label: 'Remaining credits (USD)', kind: 'usd', zero: 1,
+            value: st.limits.remaining_credits_usd})}
+          </div>
+          <div><div class="sec">Alert thresholds</div>
+            <p class="blk-intro">When a money or token limit reaches these percentages, the dashboard marks it.</p>
+          ${pctField({id: 't-thr', label: 'Warn when a budget reaches', values: st.alert_thresholds_pct,
+            presets: [25, 50, 75, 90, 100, 110], max: 1000})}
+          </div>
+        </div>
+      </details>
+      <div class="save-row">
+        <button class="chip on" id="savecfg">Save</button><span id="cfg-msg" role="status"></span>
+        <span class="fld-hint">Saved on this computer only. Amounts take shorthand: 20M, 500k, $3,000.</span>
+      </div>
+    </div>`, {actions: `<button class="act" id="guide-open">${I('help')} How does this work?</button>`})}`;
+  // amounts: chips fill the field; hints follow what is typed; errors clear as you edit
+  page.querySelectorAll('.cfg [data-fill]').forEach(c => c.onclick = () => {
+    const el = $('#' + c.dataset.fill, page);
+    el.value = el.dataset.kind === 'usd' ? String(+c.dataset.v) : shortAmount(+c.dataset.v);
+    el.dispatchEvent(new Event('input'));
+  });
+  page.querySelectorAll('.cfg input[data-kind]').forEach(el => {
+    const upd = () => {
+      clearErr(page, el.id);
+      const hint = HINTS[el.id], h = $('#' + el.id + '-hint', page);
+      if (hint && h) { const r = parseAmount(el.value, el.dataset.kind); h.textContent = r.error ? '' : hint(r.value); }
+    };
+    el.addEventListener('input', upd);
+    el.addEventListener('blur', () => { const e = amountError(el); if (e) setErr(page, el.id, e); });
+    upd();
+  });
+  wirePct(page);
+  const stepSel = $('#g-step-sel', page), stepIn = $('#g-step', page);
+  stepSel.onchange = () => {
+    stepIn.style.display = stepSel.value === 'other' ? '' : 'none';
+    if (stepSel.value !== 'other') stepIn.value = stepSel.value; else stepIn.focus();
+    clearErr(page, 'g-step');
+  };
+  // project overrides: [{path, off, tokens}], edited in place, saved with the rest
+  const gp = Object.entries(sg.projects || {}).map(([path, o]) =>
+    ({path, off: !!o.off, tokens: o.session_tokens == null ? '' : o.session_tokens.toLocaleString('en-US')}));
+  const known = [...new Map((S.opts.projects || [])
+    .filter(p => p.path && (p.agent || 'claude') === 'claude' && !p.is_sandbox)
+    .map(p => [p.path, p])).values()].sort((a, b) => a.name.localeCompare(b.name));
+  const drawProjects = () => {
+    $('#g-projects', page).innerHTML = gp.length ? gp.map((o, i) => `
+      <div style="display:flex;gap:6px;align-items:center;margin:4px 0">
+        <select data-gp="${i}" data-k="path" id="gp-${i}-path" style="flex:1;min-width:0">
+          <option value="">choose a project</option>
+          ${[...new Set([o.path, ...known.map(p => p.path)].filter(Boolean))].map(path => {
+            const p = known.find(k => k.path === path);
+            return `<option value="${esc(path)}" ${path === o.path ? 'selected' : ''} title="${esc(path)}">${esc(p ? p.name : path)}</option>`;
+          }).join('')}
+        </select>
+        <input type="text" inputmode="decimal" list="gtok-list" data-gp="${i}" data-k="tokens" id="gp-${i}-tok"
+          value="${esc(o.tokens)}" placeholder="budget, e.g. 20M" style="width:130px;flex:none" ${o.off ? 'disabled' : ''}>
+        <label style="display:flex;gap:3px;align-items:center"><input type="checkbox" data-gp="${i}" data-k="off" ${o.off ? 'checked' : ''}>off</label>
+        <button class="act" data-gp-rm="${i}" title="Remove override" aria-label="Remove override">${I('x')}</button>
+      </div>
+      <div class="fld-err" id="gp-${i}-err" role="alert"></div>`).join('')
+      : '<div class="fld-hint">None: every project uses the per-session budget.</div>';
+    page.querySelectorAll('[data-gp]').forEach(el => el[el.type === 'text' ? 'oninput' : 'onchange'] = () => {
+      const o = gp[+el.dataset.gp], k = el.dataset.k;
+      o[k] = k === 'off' ? el.checked : el.value;
+      clearErr(page, `gp-${el.dataset.gp}`);
+      if (k === 'off') drawProjects();
+    });
+    page.querySelectorAll('[data-gp-rm]').forEach(b => b.onclick = () => { gp.splice(+b.dataset.gpRm, 1); drawProjects(); });
+  };
+  drawProjects();
+  $('#g-add', page).onclick = () => { gp.push({path: '', off: false, tokens: ''}); drawProjects(); };
+  $('#g-install', page).onclick = async () => {
+    const msg = $('#g-msg', page);
+    try {
+      const r = await doAction('guard', {remove: !!S.opts.guard_installed});
+      S.opts = await fetch('/api/options').then(r => r.json());
+      bust(); await render();
+      const m = $('#g-msg'); if (m) m.textContent = r.message;
+    } catch (e) { msg.textContent = e.message; }
+  };
+  page.querySelectorAll('[data-over]').forEach(a => a.onclick = e => {
+    e.preventDefault(); S.sessOrder = 'tokens'; S.sessPage.offset = 0; bust(); go('sessions'); });
   $('#savecfg', page).onclick = async () => {
-    const v = id => { const x = $('#' + id, page).value.trim(); return x === '' ? null : +x; };
-    await fetch('/api/settings', {method: 'POST', headers: {'Content-Type': 'application/json', 'X-FinOps-Action': '1'},
-      body: JSON.stringify({
-        budgets: {monthly_usd: v('b-monthly'), daily_usd: v('b-daily'), monthly_tokens: v('b-tokens')},
-        limits: {monthly_cost_allowance_usd: v('l-cost'), monthly_token_allowance: v('l-tok'),
-                 monthly_request_allowance: v('l-req'), remaining_credits_usd: v('l-cred')},
-        alert_thresholds_pct: $('#t-thr', page).value.split(',').map(x => +x.trim()).filter(Boolean),
-      })}).then(r => r.json());
+    const msg = $('#cfg-msg', page);
+    msg.className = ''; msg.textContent = '';
+    page.querySelectorAll('.cfg .fld-err').forEach(e => { if (!e.id.startsWith('key-')) e.textContent = ''; });
+    page.querySelectorAll('.cfg .bad').forEach(e => e.classList.remove('bad'));
+    const errs = [];
+    const amt = id => { const el = $('#' + id, page), e = amountError(el); if (e) errs.push([id, e]);
+      return e ? null : parseAmount(el.value, el.dataset.kind).value; };
+    const pcts = id => [...page.querySelectorAll(`#${id} [data-pct].on`)].map(b => +b.dataset.pct).sort((a, b) => a - b);
+    const budgets = {monthly_usd: amt('b-monthly'), daily_usd: amt('b-daily'), monthly_tokens: amt('b-tokens')};
+    const limits = {monthly_cost_allowance_usd: amt('l-cost'), monthly_token_allowance: amt('l-tok'),
+                    monthly_request_allowance: amt('l-req'), remaining_credits_usd: amt('l-cred')};
+    const thr = pcts('t-thr');
+    if (!thr.length) errs.push(['t-thr', 'Pick at least one percentage.']);
+    const after = (page.querySelector('[name=g-after]:checked') || {}).value || 'step';
+    let step = stepSel.value === 'other' ? parseAmount(stepIn.value, 'count').value : +stepSel.value;
+    if (after === 'step' && !(step >= 1 && step <= 1000)) errs.push(['g-step', 'Enter a step between 1 and 1000%.']);
+    if (!(step >= 1 && step <= 1000)) step = 25;
+    const projects = {};
+    gp.forEach((o, i) => {
+      const id = `gp-${i}`;
+      if (!o.path) return errs.push([id, 'Pick a project, or remove this row.']);
+      if (projects[o.path]) return errs.push([id, 'This project already has an override above.']);
+      if (o.off) return (projects[o.path] = {off: true});
+      const r = parseAmount(o.tokens, 'tokens');
+      if (r.error) return errs.push([id, r.error]);
+      if (!(r.value > 0)) return errs.push([id, 'Enter a budget, or tick off.']);
+      projects[o.path] = {session_tokens: r.value};
+    });
+    const guard = {session_tokens: amt('g-tokens'), warn_pct: pcts('g-warn'), after_approval: after,
+                   step_pct: step, projects};
+    if (errs.length) {
+      errs.forEach(([id, e]) => setErr(page, id, e));
+      page.querySelectorAll('details.adv').forEach(d => { if (d.querySelector('.fld-err:not(:empty)')) d.open = true; });
+      msg.className = 'err';
+      msg.textContent = `Fix ${errs.length} field${errs.length === 1 ? '' : 's'} before saving.`;
+      const first = $('#' + errs[0][0], page) || $('#' + errs[0][0] + '-err', page);
+      if (first) { first.scrollIntoView({block: 'center', behavior: 'smooth'}); first.focus && first.focus(); }
+      return;
+    }
+    let res;
+    try {
+      res = await fetch('/api/settings', {method: 'POST', headers: {'Content-Type': 'application/json', 'X-FinOps-Action': '1'},
+        body: JSON.stringify({budgets, limits, alert_thresholds_pct: thr, guard})}).then(r => r.json());
+    } catch (e) { res = {error: 'Could not reach the dashboard server. Is it still running?'}; }
+    if (res.error) { msg.className = 'err'; msg.textContent = 'Not saved: ' + res.error; return; }
     S.opts = await fetch('/api/options').then(r => r.json());
-    bust(); render();
+    bust(); await render();
+    const m = $('#cfg-msg'); if (m) { m.className = 'ok'; m.textContent = 'Saved.'; }
   };
   const bl = b.lines.filter(l => l.configured && l.budget);
   if (bl.length) addChart(page, 'Budget used', el => C.barsH(el, {
     rows: bl, label: l => l.name, value: l => 100 * l.actual / l.budget, fmt: v => fmtPct(v), max: 100,
     color: l => l.actual >= l.budget ? 'var(--critical)' : l.actual >= 0.75 * l.budget ? 'var(--warning)' : seriesVar(2)}),
     {badge: BADGE.estimated, after: '.nothing'});
+  $('#guide-open', page).onclick = e => openGuide('budgets', null, e.currentTarget);
+  page.querySelectorAll('[data-guide]').forEach(b => b.onclick = e => {
+    e.preventDefault(); e.stopPropagation();          // inside <summary>: don't toggle Advanced
+    openGuide('budgets', b.dataset.guide, b);
+  });
+  maybeGuide('budgets');
+};
+
+/* ---------- settings ---------- */
+VIEWS.settings = async (page) => {
+  page.innerHTML = card('API keys', `<div class="cfg">
+      <div class="fld-hint" style="margin-bottom:8px">An API key is a password that lets this dashboard ask
+        Anthropic or Cursor for your company's bill. You only need one for the <b>Billed vs local</b> page,
+        which compares what was billed with what this computer recorded. That page shows up in the sidebar
+        once a key is saved. Skip this if you don't use it. Keys stay on this computer, in a file only you
+        can read. They are never shown again.</div>
+      <div id="cfg-keys" class="stack"><div class="note">Loading…</div></div></div>`,
+    {hint: 'optional'});
+  drawKeys(page);
 };
 
 /* ---------- scorecard ---------- */
@@ -2428,7 +3076,7 @@ VIEWS.scorecard = async (page) => {
           : d.score >= 30 ? 'approaching' : 'critical'}"><i style="width:${d.score}%"></i></div>
         <div class="note">${esc(d.detail)}</div></div>`).join('')}
       </div></div>`, {badge: BADGE.estimated,
-      footer: 'Each dimension is measured from your transcripts; budget adherence needs a budget in Settings.'})}
+      footer: 'Each dimension is measured from your transcripts; budget adherence needs a budget on the Budgets page.'})}
     <div class="grid g3">
       ${card('What is good', `<ul style="margin:0 0 0 18px;font-size:12.5px">${
         sc.what_is_good.map(x => `<li style="margin-bottom:6px">${esc(x)}</li>`).join('')
@@ -3216,6 +3864,121 @@ VIEWS.compare = async (page) => {
 };
 
 /* ---------- skills & MCP from recurring work ---------- */
+/* ---------- jev: TypeSafe's fast decision model ---------- */
+let JEV_MSG = null;          // {where: 'install'|'key', ok, text}: shown once after the page redraws
+VIEWS.jev = async (page) => {
+  const d = await api('jev');
+  const st = d.status, k = d.key, fit = d.fit;
+  const flash = where => JEV_MSG && JEV_MSG.where === where
+    ? `<div class="fld-hint ${JEV_MSG.ok ? 'ok' : ''}" style="${JEV_MSG.ok ? '' : 'color:var(--critical-ink)'}">${esc(JEV_MSG.text)}</div>` : '';
+  const state = !st.claude
+    ? `<span class="lb-state warn">Claude Code's <code>claude</code> command was not found on this computer, so Jev can't be installed from here.</span>`
+    : st.installed ? `<span class="lb-state on">● Installed${st.version ? ' · version ' + esc(st.version) : ''}${st.enabled === false ? ' (turned off in Claude Code)' : ''}</span>`
+    : '<span class="lb-state">○ Not installed</span>';
+  const keyState = k.source === 'shell' ? `set in your shell${k.last4 ? ' · ends ' + esc(k.last4) : ''}`
+    : k.source ? `saved${k.last4 ? ' · ends ' + esc(k.last4) : ''}` : 'not set';
+  const small = fit.share_pct < 1;
+  const usd = v => v ? fmtUSD(v) : '$0';
+  page.innerHTML = `
+    ${card('What is Jev?', `<div class="cfg">
+      <p class="blk-intro">Jev is a very fast, very cheap AI that makes decisions. It picks one option, answers yes or no,
+        gives a score, or pulls out a value. It can't write text or code.</p>
+      <p class="blk-intro">It doesn't make Claude Code itself cheaper. It makes the apps and scripts you build cheaper, by
+        replacing AI calls that only make a decision, like sorting tickets or checking a pull request.</p>
+      <p class="blk-intro">Installing it teaches Claude how to use Jev when you build those.
+        <a href="https://docs.typesafe.ai" target="_blank" rel="noopener">Read Jev's docs</a></p></div>`,
+      {hint: 'made by TypeSafe AI'})}
+    ${card('Set up Jev', `<div class="cfg">
+      <section class="blk">
+        <h4><span class="num">①</span> Install the Jev plugin for Claude Code</h4>
+        <div class="lb-head">${state}<span class="spacer"></span>
+          ${st.claude && !st.installed ? '<button class="act" id="jev-install">Install</button>' : ''}
+          ${st.installed ? '<button class="act" id="jev-uninstall">Uninstall</button>' : ''}</div>
+        <div class="livebox" id="jev-confirm" hidden>
+          <p><b>This adds TypeSafe's plugin to Claude Code for all your projects.</b> It runs these two commands:</p>
+          <pre class="mono" style="margin:6px 0;white-space:pre-wrap">claude plugin marketplace add typesafe-ai/skills
+claude plugin install typesafe@typesafe-ai</pre>
+          <p class="blk-sub">Jev only sees what the apps you build send it. Uninstall any time.</p>
+          <div class="live-actions"><button class="chip on" id="jev-go">Confirm install</button>
+            <button class="act ghost" id="jev-cancel">Cancel</button></div></div>
+        <div id="jev-log"></div>${flash('install')}
+      </section>
+      <section class="blk">
+        <h4><span class="num">②</span> Add your Jev API key</h4>
+        <p class="blk-intro">The key lets your apps and Claude talk to Jev. Get one at
+          <a href="https://console.typesafe.ai" target="_blank" rel="noopener">console.typesafe.ai</a>.</p>
+        <div class="lb-head"><span class="lb-state ${k.source ? 'on' : ''}">Key: ${keyState}</span></div>
+        <div style="display:flex;gap:6px;align-items:center;margin-top:6px">
+          <input type="password" id="jev-key" autocomplete="off" spellcheck="false" style="flex:1;min-width:0"
+            aria-label="Jev API key" placeholder="${k.source ? 'paste a new key to replace it' : 'paste your Jev API key'}">
+          <button class="act" id="jev-key-save">Save key</button>
+          ${k.source === 'claude_settings' ? '<button class="act" id="jev-key-rm">Remove</button>' : ''}</div>
+        <div class="fld-err" id="jev-key-err" role="alert"></div>${flash('key')}
+        <p class="fld-hint">It is saved in Claude Code's settings (<span class="mono">~/.claude/settings.json</span>), so new
+          Claude Code sessions can use it. Restart any open ones. This page never shows the key again.
+          ${k.source === 'shell' ? ' A key set in your shell takes priority over a saved one.' : ''}</p>
+      </section></div>`)}
+    ${card('Where Jev fits in your work', `<div class="cfg">
+      <p class="blk-intro">We looked for your Claude Code prompts that were really just a decision: short, no tools, and
+        asking "which one", "yes or no", "classify" and the like.</p>
+      <div class="grid g4">
+        ${kpi('Decision-like prompts', fmtInt(fit.prompts), `of ${fmtInt(fit.total_prompts)} in this range`)}
+        ${kpi('Cost on Claude', usd(fit.claude_cost), fmtPct(fit.share_pct, 2) + ' of your spend', {badge: BADGE.estimated})}
+        ${kpi('Rough cost on Jev', usd(fit.jev_cost), 'at TypeSafe\'s published price', {badge: BADGE.estimated})}
+        ${kpi('Saving', usd(Math.max(fit.claude_cost - fit.jev_cost, 0)), 'if these had gone to Jev')}
+      </div>
+      ${small ? `<p class="fld-hint" style="margin-top:8px">Your Claude Code work is mostly writing code, which Jev can't do.
+        Jev pays off in apps and scripts that make many decisions, like sorting support tickets or reviewing pull requests.</p>` : ''}
+      ${fit.examples.length ? `<div class="sec" style="margin-top:12px">Examples</div><div class="stack">${fit.examples.map(e =>
+        `<div class="item"><div class="dt">${MASKED ? '<i>Prompt text hidden</i>' : esc(e.text)}
+          <span class="spacer"></span> ${fmtUSD(e.cost)}</div></div>`).join('')}</div>` : ''}</div>`,
+      {badge: BADGE.estimated, hint: 'read-only, from this computer\'s transcripts'})}`;
+  JEV_MSG = null;
+  const redraw = msg => { JEV_MSG = msg; bust(); render(); };
+  const confirmBox = $('#jev-confirm', page);
+  const inst = $('#jev-install', page);
+  if (inst) inst.onclick = () => { confirmBox.hidden = false; $('#jev-go', page).focus(); };
+  $('#jev-cancel', page).onclick = () => { confirmBox.hidden = true; };
+  const runJob = async (what, btn) => {
+    btn.disabled = true;
+    try {
+      const {job} = await doAction('jev/' + what);
+      const j = await followJob(job, $('#jev-log', page));
+      redraw({where: 'install', ok: j.state === 'done',
+              text: j.state === 'done' ? (what === 'install' ? 'Installed. Restart any open Claude Code sessions to use it.' : 'Removed.')
+                : (j.log[j.log.length - 1] || 'It did not finish.')});
+    } catch (e) { redraw({where: 'install', ok: false, text: e.message}); }
+  };
+  $('#jev-go', page).onclick = e => runJob('install', e.currentTarget);
+  const un = $('#jev-uninstall', page);
+  if (un) un.onclick = () => {
+    if (!un.dataset.armed) {
+      un.dataset.armed = '1'; un.textContent = 'Click again to uninstall';
+      setTimeout(() => { if (un.isConnected) { delete un.dataset.armed; un.textContent = 'Uninstall'; } }, 4000);
+      return;
+    }
+    runJob('uninstall', un);
+  };
+  const keyIn = $('#jev-key', page), keyErr = $('#jev-key-err', page);
+  keyIn.oninput = () => { keyErr.textContent = ''; keyIn.classList.remove('bad'); };
+  keyIn.onkeydown = e => { if (e.key === 'Enter') $('#jev-key-save', page).click(); };
+  $('#jev-key-save', page).onclick = async () => {
+    if (!keyIn.value.trim()) { keyErr.textContent = 'Paste your Jev API key first.'; keyIn.classList.add('bad'); return; }
+    try { await doAction('jev/key', {value: keyIn.value}); redraw({where: 'key', ok: true, text: 'Saved. New Claude Code sessions will use it.'}); }
+    catch (e) { keyErr.textContent = e.message; keyIn.classList.add('bad'); }
+  };
+  const rm = $('#jev-key-rm', page);
+  if (rm) rm.onclick = async () => {
+    if (!rm.dataset.armed) {
+      rm.dataset.armed = '1'; rm.textContent = 'Click again to remove';
+      setTimeout(() => { if (rm.isConnected) { delete rm.dataset.armed; rm.textContent = 'Remove'; } }, 4000);
+      return;
+    }
+    try { await doAction('jev/key', {remove: true}); redraw({where: 'key', ok: true, text: 'Removed.'}); }
+    catch (e) { keyErr.textContent = e.message; }
+  };
+};
+
 VIEWS.toolkit = async (page) => {
   const d = await fetch('/api/suggestions').then(r => r.json());
   const ev = x => (x || []).map(e => `<code>${esc(e)}</code>`).join(' ');
@@ -3273,9 +4036,8 @@ VIEWS.cloud = async (page) => {
         <span class="note">${cfg[k] ? 'key found' : 'no key'}</span></div>
       <div class="dt"><b>Gives you:</b> ${esc(p.covers)}</div>
       <div class="dt"><b>Get a key:</b> ${esc(p.how)}</div>
-      <div class="dt">Then set <code>${esc(p.env)}</code> in your environment, or add
-        <code>"${esc(p.field)}"</code> to <code>~/.claude-finops/secrets.local.json</code>
-        (gitignored, never packaged). Restart the dashboard afterwards.</div>
+      <div class="dt">Then add it on the <a href="#" data-go-settings>Settings</a> page,
+        run <code>claude-finops --set-key</code>, or set <code>${esc(p.env)}</code> in your environment.</div>
     </div>`).join('');
   page.innerHTML = `
     <div class="note"><b>The only page that talks to the internet.</b> ${esc(d.note)}
@@ -3297,7 +4059,7 @@ VIEWS.cloud = async (page) => {
         `${fmtInt(t.cursor_members)} members`, {badge: BADGE.actual})}
     </div>
     ${card('Set up the APIs', `<div class="stack">${setup}</div>`,
-      {hint: 'Keys are read from your environment or a local file; the dashboard never stores them'})}
+      {hint: 'Stored keys stay on this machine (0600) and are never shown again'})}
     ${card('Billed vs local, per day', `<div id="cl-day"></div>`, {flush: 1, badge: BADGE.actual,
       hint: 'Claude Code: what the vendor billed against what this machine recorded'})}
     ${card('Claude Code users (org-wide)', `<div id="cl-users"></div>`, {flush: 1, badge: BADGE.actual,
@@ -3305,6 +4067,7 @@ VIEWS.cloud = async (page) => {
     ${card('Cursor members', `<div id="cl-cur"></div>`, {flush: 1, badge: BADGE.actual})}
     ${card('Billed API cost by line item', `<div id="cl-api"></div>`, {flush: 1, badge: BADGE.actual,
       hint: 'From the Anthropic cost report: API spend only, not subscription plans'})}`;
+  page.querySelectorAll('[data-go-settings]').forEach(a => a.onclick = e => { e.preventDefault(); go('settings'); });
   $('#cl-day', page).innerHTML = table([
     {h: 'Day', f: r => esc(r.day)},
     {h: 'Billed $', num: 1, f: r => fmtUSD(r.billed_cost)},
@@ -3495,6 +4258,10 @@ const TOURS = {
     {el: 'card:High waste', t: 'High waste', see: 'The rules that fired hardest: repeated reads, retries, stale sessions.', get: 'The costly patterns, each with the baseline it is measured against.', act: 'Open <b>Show flagged items</b> to see the evidence, then fix these first.'},
     {el: 'card:Optimization opportunities', t: 'Medium findings', see: 'Patterns worth changing but not urgent.', get: 'The next tier of opportunities.', act: 'Batch these into one config change.'},
     {el: 'card:Low-priority observations', t: 'Low-priority observations', see: 'Small findings, kept for completeness.', get: 'Context for the numbers above.', act: 'Skim them; act only if one matches a habit you want to change.'}],
+  jev: [
+    {el: 'card:What is Jev?', t: 'What Jev is', see: 'A fast, cheap AI that only makes decisions: pick one, yes or no, a score, a value.', get: 'Cheaper, faster apps and scripts, wherever an AI call only decides something.', act: 'Read the three lines. Jev does not make Claude Code itself cheaper.'},
+    {el: 'card:Set up Jev', t: 'Install and key', see: 'One click installs the Jev plugin for Claude Code; the key is saved in Claude Code\'s settings.', get: 'Claude knows how to use Jev when you build something.', act: 'Press Install, check the two commands, then Confirm. Paste your key and Save.'},
+    {el: 'card:Where Jev fits', t: 'Where Jev fits', see: 'Your prompts that were really just a decision, and what they would cost on Jev.', get: 'An honest number before you change anything.', act: 'If it is tiny, Jev belongs in your apps, not your coding sessions.'}],
   freemodels: [
     {el: 'card:How to use and test a free model', t: 'How it works', see: 'How to plug a local or free cloud model into Claude Code, and how to test it.', get: 'Zero-cost options for simple or private work.', act: 'Read the RAM guidance before you pick a model.'},
     {el: 'card1', t: 'A model', see: 'Each model with its size, RAM needs, strengths and limits.', get: 'A realistic idea of what runs on your machine.', act: `Click <b>${I('plus')} Add</b> on a model that fits your RAM.`}],
@@ -3520,10 +4287,14 @@ const TOURS = {
     {el: 'card:Scenarios', t: 'Scenarios', see: 'Optimistic, expected and pessimistic end-of-period totals.', get: 'A best and worst case to plan against.', act: 'Budget against the pessimistic number.'}],
   budgets: [
     {el: 'card:Budget vs actual vs forecast', t: 'Budget vs actual', see: 'Each budget line with its budget, actual, forecast and variance.', get: 'A warning before you overspend, not after.', act: 'Watch the variance column: a positive forecast variance means trouble.'},
-    {el: 'card:Configure budgets', t: 'Configure budgets', see: 'Your budget lines, limits and alert thresholds.', get: 'Numbers that make the forecast and burn dashboards meaningful.', act: 'Edit a budget and save; every dashboard picks it up.'}],
+    {el: 'card:Set your limits', t: 'Configure budgets', see: 'Your budget lines, limits and alert thresholds.', get: 'Numbers that make the forecast and burn dashboards meaningful.', act: 'Edit a budget and save; every dashboard picks it up.'},
+    {el: 'card:Set your limits', t: 'Suggestions and shorthand', see: 'Chips under each amount suggest values from your own last 30 days and session sizes; amounts accept 20M, 500k or $3,000.', get: 'A sensible budget in one click, and a clear message when a value will not work.', act: 'Click a suggestion, adjust it, and Save.'},
+    {el: 'card:Set your limits', t: 'Session guard', see: 'A token budget for each Claude Code session, warn percentages, what happens after you approve, per-project overrides, and the Live warnings box (optional).', get: 'A warning while a session grows, and a pause for your approval once it reaches its budget.', act: 'Set a budget, save, then, if you want live warnings, <b>Install</b> in the Live warnings box. It is optional. It applies to new sessions.'}],
+  settings: [
+    {el: 'card:API keys', t: 'API keys', see: 'Optional keys for the Anthropic Admin API and Cursor.', get: 'The Billed vs local page, without the terminal.', act: 'Paste a key and press Save key. It is never shown again, only its last four characters.'}],
   cloud: [
     {el: 'kpis', t: 'Billed vs local', see: 'What the vendor billed the whole organisation next to what this machine recorded.', get: 'The gap: usage from other machines, other members, or work off this machine.', act: `Click <b>${I('cloudDown')} Refresh from APIs</b> to fetch — this is the only page that goes online.`},
-    {el: 'card:Set up the APIs', t: 'Set up the APIs', see: 'Which provider keys were found, and how to get each one.', get: 'Org-wide Claude Code usage per user, and Cursor team spend.', act: 'Run claude-finops --set-key, or set the environment variable, then restart.'},
+    {el: 'card:Set up the APIs', t: 'Set up the APIs', see: 'Which provider keys were found, and how to get each one.', get: 'Org-wide Claude Code usage per user, and Cursor team spend.', act: 'Add a key on the Settings page, or run claude-finops --set-key.'},
     {el: 'card:Billed vs local', t: 'The comparison', see: 'Billed totals against local totals for the same period.', get: 'Proof of how much of the bill this machine explains.', act: 'A large gap means most spend happens elsewhere: check the user tables.'},
     {el: 'card:Claude Code users', t: 'Users org-wide', see: 'Each Claude Code user in the organisation and their usage.', get: 'Who drives the bill across the team.', act: 'Compare your own row with the team average.'},
     {el: 'card:Cursor members', t: 'Cursor members', see: 'Cursor team members and their spend.', get: 'The same picture for Cursor seats.', act: 'Look for seats with no usage at all.'},