backlens 0.1.1 → 0.2.0

package/README.md

@@ -57,11 +57,13 @@ In the Compare tab, save a snapshot, change your code, restart, use the same pag
 
 Every issue has **Explain** and **Suggest fix**. A fix goes: a preview of exactly what would be sent and to whom, the model's answer as a diff, **Apply and check** (only on files with no uncommitted changes, with a backup), then backlens rebuilds if needed, restarts your app, replays the request that showed the issue and runs your tests. Only a fix that removes the issue and keeps the tests green is marked proven. Keep it, or revert to the exact files you had.
 
-Who answers is chosen per issue, with the reasons shown:
+Who answers is set up in **AI settings**, all from the dashboard. The first-run setup asks too.
 
-- **Local model** (free, private): any model in [Ollama](https://ollama.com). Picked by default when Ollama is running.
-- **Recorded answers** (free): no model; fixes come from `.backlens/ai-fixtures.json`. For trying the flow and for tests.
-- **Claude with your own key**: set `ANTHROPIC_API_KEY` before starting backlens. Explaining uses Claude Haiku 5.5; fixes use Sonnet 5.5 or Opus 5.5 depending on how hard the issue looks (files involved, issue type, test coverage, your past results), one step up after a failed check. Missing indexes never use a model. A daily budget (default $1) is enforced before sending.
+- **Local model** (free, private): runs on your computer through [Ollama](https://ollama.com). The card walks you through it: a link to install Ollama, then it notices when Ollama is running, suggests the model that fits your memory (`qwen2.5-coder` 3B for 8 GB, 7B for 16 GB, 14B for 32 GB) and downloads it with a progress bar. Small models explain well; their fixes are hit-and-miss, and every fix is checked anyway.
+- **Claude with your own key**: paste the key and backlens checks it for free before saving it in your user folder (`~/.config/backlens`, readable by you only), never in the project. `ANTHROPIC_API_KEY` in the environment wins if set. Explaining uses Claude Haiku 5.5; fixes use Sonnet 5.5 or Opus 5.5 depending on how hard the issue looks (files involved, issue type, test coverage, your past results), one step up after a failed check. A daily budget (default $1) is enforced before sending.
+- **No model**: explanations in backlens's own words.
+
+Some fixes never use a model: running independent calls together (`Promise.all`) and missing indexes are written by backlens itself, the same way every time.
 
 Values that look like secrets are masked, `.env` files and `node_modules` are never read, and requests kept for replay stay in memory only. Replaying a POST, PUT or DELETE runs it again against your dev database, so it is off unless you allow it in AI settings.
 

package/ai/credentials.js

@@ -0,0 +1,56 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * The user's Claude API key, pasted in the dashboard. It is kept outside every project, in the
+ * user's config folder, readable by the user only, so it can never be committed with the code.
+ * ANTHROPIC_API_KEY in the environment wins over the saved key. The key never goes back to the
+ * browser: the dashboard only sees its last four characters.
+ */
+
+export function configDir() {
+  if (process.env.BACKLENS_HOME) return process.env.BACKLENS_HOME;
+  if (process.platform === 'win32' && process.env.APPDATA) return join(process.env.APPDATA, 'backlens');
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'backlens');
+}
+
+const file = () => join(configDir(), 'credentials.json');
+
+/** A loose shape check, so a pasted sentence or a key from another service is caught early. */
+export function looksLikeKey(key) {
+  return typeof key === 'string' && /^sk-ant-[A-Za-z0-9_-]{20,300}$/.test(key);
+}
+
+export function savedKey() {
+  try {
+    const key = JSON.parse(readFileSync(file(), 'utf8')).anthropicApiKey;
+    return looksLikeKey(key) ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveKey(key) {
+  if (!looksLikeKey(key)) throw new Error('That does not look like a Claude API key. It starts with sk-ant-.');
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(file(), `${JSON.stringify({ anthropicApiKey: key }, null, 2)}\n`, { mode: 0o600 });
+  // mode only applies when the file is created; tighten an existing one too.
+  try {
+    chmodSync(file(), 0o600);
+  } catch {}
+}
+
+export function removeKey() {
+  rmSync(file(), { force: true });
+}
+
+/** The key to use and where it came from: the environment first, then the saved one. */
+export function currentKey() {
+  if (process.env.ANTHROPIC_API_KEY) return { key: process.env.ANTHROPIC_API_KEY, source: 'env' };
+  const key = savedKey();
+  return key ? { key, source: 'saved' } : { key: null, source: null };
+}
+
+export const lastFour = (key) => (key ? key.slice(-4) : '');

package/ai/fixes.js

@@ -6,7 +6,8 @@ import { dirname, join, relative } from 'node:path';
 import { checkTrace } from '../analyze.js';
 import { ensureIgnore } from '../config.js';
 import { buildContext, insideProject } from './context.js';
-import { anthropicStatus, ask, issuePrompt, ollamaStatus } from './providers.js';
+import { looksLikeKey, removeKey, saveKey } from './credentials.js';
+import { anthropicStatus, ask, issuePrompt, LOCAL_MODELS, ollamaStatus, startPull, stopPull, testKey } from './providers.js';
 import { route } from './router.js';
 import { promiseAll } from './templates.js';
 
@@ -19,7 +20,7 @@ import { promiseAll } from './templates.js';
  */
 
 // Replaying a write sends it again, so it changes the dev database twice: reads only unless asked.
-const DEFAULTS = { provider: null, ollamaModel: 'qwen2.5-coder:3b', dailyBudgetUsd: 1, replay: true, replayWrites: false };
+const DEFAULTS = { provider: null, ollamaModel: null, dailyBudgetUsd: 1, replay: true, replayWrites: false };
 const EDIT_REPAIRS = 2;
 const TYPE_REPAIRS = 2;
 
@@ -70,10 +71,13 @@ export function createAI(deps) {
   } catch {}
 
   async function resolvedSettings() {
-    // Nothing is ever paid by default: the local model if it is installed, recorded answers otherwise.
-    if (settings.provider) return settings;
     const local = await ollamaStatus();
-    return { ...settings, provider: local.running && local.models.includes(settings.ollamaModel) ? 'ollama' : 'mock' };
+    // No model picked yet: one already downloaded if there is one, else the size this machine suits.
+    const ollamaModel =
+      settings.ollamaModel || LOCAL_MODELS.map((m) => m.name).find((n) => local.models.includes(n)) || local.models.find((n) => /coder/.test(n)) || local.recommended;
+    // Nothing is ever paid by default: the local model if it is ready, recorded answers otherwise.
+    const provider = settings.provider || (local.running && local.models.includes(ollamaModel) ? 'ollama' : 'mock');
+    return { ...settings, ollamaModel, provider };
   }
 
   function spentToday() {
@@ -85,7 +89,7 @@ export function createAI(deps) {
 
   async function status() {
     const s = await resolvedSettings();
-    return { settings: s, ollama: await ollamaStatus(), anthropic: anthropicStatus(), spentTodayUsd: spentToday(), history: readLines(historyFile).length };
+    return { settings: s, configured: Boolean(settings.provider), ollama: await ollamaStatus(), anthropic: anthropicStatus(), spentTodayUsd: spentToday(), history: readLines(historyFile).length };
   }
 
   function saveSettings(next) {
@@ -206,7 +210,20 @@ export function createAI(deps) {
         replace = cleanCode(e.new_code);
         const ranges = shown.get(file);
         if (from < 1 || to < from || to > lines.length || !ranges.some((r) => from >= r.from && to <= r.to)) {
-          rejected.push({ file, from, to, reason: `lines ${from}-${to} are outside what you were shown in ${file} (${ranges.map((r) => `${r.from}-${r.to}`).join(', ')})` });
+          // Small models often number later edits as if the earlier ones were already applied.
+          const shift = ok
+            .filter((o) => o.file === file && o.to < from)
+            .reduce((n, o) => n + o.replace.split('\n').length - (o.to - o.from + 1), 0);
+          const was = { from: from - shift, to: to - shift };
+          const shifted = shift !== 0 && ranges.some((r) => was.from >= r.from && was.to <= r.to);
+          rejected.push({
+            file,
+            from,
+            to,
+            reason: shifted
+              ? `lines ${from}-${to} are numbered as if your earlier edit were already applied. Number every edit by the original lines shown: these look like lines ${was.from}-${was.to}`
+              : `lines ${from}-${to} are outside what you were shown in ${file} (${ranges.map((r) => `${r.from}-${r.to}`).join(', ')})`,
+          });
           continue;
         }
       } else if (typeof e.find === 'string' && e.find) {
@@ -612,5 +629,30 @@ export function createAI(deps) {
     if (waiter) waiter(trace);
   }
 
-  return { status, saveSettings, explain, startFix, getFix, send, apply, keep, revert, escalate, stop, onReplayTrace, replayEnabled: () => settings.replay };
+  /** Tests a pasted key (free) and saves it only if Claude accepts it. */
+  async function setKey(key) {
+    key = typeof key === 'string' ? key.trim() : '';
+    if (!looksLikeKey(key)) throw new Error('That does not look like a Claude API key. It starts with sk-ant-.');
+    const problem = await testKey(key);
+    if (problem) throw new Error(problem);
+    saveKey(key);
+    return status();
+  }
+
+  async function forgetKey() {
+    removeKey();
+    return status();
+  }
+
+  async function pullModel(model) {
+    startPull(model);
+    return status();
+  }
+
+  async function stopPullModel() {
+    stopPull();
+    return status();
+  }
+
+  return { setKey, forgetKey, pullModel, stopPullModel, status, saveSettings, explain, startFix, getFix, send, apply, keep, revert, escalate, stop, onReplayTrace, replayEnabled: () => settings.replay };
 }

package/ai/providers.js

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { totalmem } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { currentKey, lastFour } from './credentials.js';
 import { costUsd } from './router.js';
 
 /**
@@ -29,6 +31,7 @@ Risks or assumptions, or why there are no edits.
 
 Rules for edits:
 - An EDIT replaces whole lines, from the first to the last number given (inclusive), using the numbers shown. The code block is everything that goes there instead; it can have more or fewer lines. An empty code block deletes the lines.
+- Every EDIT uses the original line numbers shown, even after an earlier EDIT adds or removes lines. Never renumber.
 - Write as many EDIT blocks as needed, or none if no change is safe. CONFIDENCE is high, medium or low.
 - Only edit lines you were shown, in files you were shown. Edits must not overlap.
 - Change as little as possible. Keep the code's style, names and types. Do not change behaviour: same results, same errors, same order of side effects. Only remove repeated work or run independent work together.
@@ -132,16 +135,95 @@ function mock(task, issue, root) {
 // ---- ollama ---------------------------------------------------------------------------
 export const OLLAMA = 'http://127.0.0.1:11434';
 
+/** Coding models in sizes for 8, 16 and 32 GB of memory; download sizes as Ollama lists them. */
+export const LOCAL_MODELS = [
+  { name: 'qwen2.5-coder:3b', sizeGb: 1.9, minRamGb: 0, note: 'fits 8 GB. Explains well; fixes are hit-and-miss.' },
+  { name: 'qwen2.5-coder:7b', sizeGb: 4.7, minRamGb: 14, note: 'needs 16 GB. Better fixes, still check them.' },
+  { name: 'qwen2.5-coder:14b', sizeGb: 9.0, minRamGb: 28, note: 'needs 32 GB. The best of the three.' },
+];
+
+/** The biggest model this machine's memory can hold alongside the app and an editor. */
+export function recommendedModel(ramGb = totalmem() / 1024 ** 3) {
+  return [...LOCAL_MODELS].reverse().find((m) => ramGb >= m.minRamGb) || LOCAL_MODELS[0];
+}
+
+/** Whether the Ollama app or command is on this machine, even when it is not running. */
+function ollamaInstalled() {
+  const exe = process.platform === 'win32' ? 'ollama.exe' : 'ollama';
+  const places = [
+    ...(process.env.PATH || '').split(delimiter).map((d) => join(d, exe)),
+    '/Applications/Ollama.app',
+    join(process.env.HOME || '', 'Applications', 'Ollama.app'),
+    join(process.env.LOCALAPPDATA || '', 'Programs', 'Ollama', 'ollama.exe'),
+  ];
+  return places.some((p) => p && existsSync(p));
+}
+
 export async function ollamaStatus() {
+  const ramGb = Math.round(totalmem() / 1024 ** 3);
+  const base = { ramGb, recommended: recommendedModel(ramGb).name, catalog: LOCAL_MODELS, pull: pullState };
   try {
     const res = await fetch(`${OLLAMA}/api/tags`, { signal: AbortSignal.timeout(1500) });
     const body = await res.json();
-    return { running: true, models: (body.models || []).map((m) => m.name) };
+    return { ...base, installed: true, running: true, models: (body.models || []).map((m) => m.name) };
   } catch {
-    return { running: false, models: [] };
+    return { ...base, installed: ollamaInstalled(), running: false, models: [] };
   }
 }
 
+// ---- downloading a model, started from the dashboard ------------------------------------
+let pullState = null;
+let pullAbort = null;
+
+/** Starts downloading a model through Ollama's own API; progress is read from ollamaStatus().pull. */
+export function startPull(model) {
+  if (!/^[\w.-]{1,60}(:[\w.-]{1,40})?$/.test(model || '')) throw new Error('Not a model name.');
+  if (pullState && !pullState.done) throw new Error(`Already downloading ${pullState.model}.`);
+  pullAbort = new AbortController();
+  pullState = { model, status: 'starting', completed: 0, total: 0, done: false, error: null };
+  const state = pullState;
+  (async () => {
+    try {
+      const res = await fetch(`${OLLAMA}/api/pull`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ model, stream: true }),
+        signal: pullAbort.signal,
+      });
+      if (!res.ok) throw new Error(`Ollama answered ${res.status}.`);
+      const decoder = new TextDecoder();
+      let buffer = '';
+      // Ollama reports each layer separately; the big one is the model itself, so show the largest.
+      for await (const chunk of res.body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf('\n')) >= 0) {
+          const line = buffer.slice(0, nl).trim();
+          buffer = buffer.slice(nl + 1);
+          if (!line) continue;
+          const part = JSON.parse(line);
+          if (part.error) throw new Error(part.error);
+          state.status = part.status || state.status;
+          if (part.total && part.total >= state.total) {
+            state.total = part.total;
+            state.completed = part.completed || 0;
+          }
+        }
+      }
+      state.done = true;
+      state.status = 'success';
+    } catch (err) {
+      state.done = true;
+      state.error = err.name === 'AbortError' ? 'Download stopped.' : `Download failed: ${err.message}`;
+    }
+  })();
+  return state;
+}
+
+export function stopPull() {
+  if (pullAbort) pullAbort.abort();
+}
+
 /** Streams the answer, reporting tokens as they arrive, then parses the finished JSON. */
 async function ollama(task, messages, model, onProgress, signal) {
   let res;
@@ -163,10 +245,11 @@ async function ollama(task, messages, model, onProgress, signal) {
     });
   } catch (err) {
     if (signal && signal.aborted) throw new Error('Stopped.');
-    throw new Error('Ollama is not running. Start it (brew services start ollama) and try again.');
+    throw new Error('Ollama is not running. Open the Ollama app, then try again.');
   }
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
+    if (/not found/i.test(body.error || '')) throw new Error(`The local model ${model} is not downloaded yet. Download it in AI settings.`);
     throw new Error(body.error ? `Ollama: ${body.error}` : `Ollama answered ${res.status}.`);
   }
   let text = '';
@@ -217,23 +300,46 @@ function safeJson(text) {
 }
 
 // ---- anthropic (the user's own key) -------------------------------------------------------
+// A client per key, so pasting or removing a key in the dashboard takes effect at once.
 let sdk = null;
-async function client() {
-  if (!sdk) {
+async function client(key = currentKey().key) {
+  if (!sdk || sdk.key !== key) {
+    let mod;
     try {
-      const mod = await import('@anthropic-ai/sdk');
-      sdk = { Anthropic: mod.default, client: new mod.default() };
+      mod = await import('@anthropic-ai/sdk');
     } catch (err) {
-      throw new Error(`Could not start the Claude client: ${err.message}. Set ANTHROPIC_API_KEY, or run "ant auth login".`);
+      throw new Error(`Could not load the Claude client: ${err.message}.`);
+    }
+    try {
+      sdk = { key, Anthropic: mod.default, client: new mod.default(key ? { apiKey: key } : {}) };
+    } catch {
+      throw new Error('No Claude API key. Paste one in AI settings.');
     }
   }
   return sdk;
 }
 
+/** Where the key comes from. The key itself is never returned, only its last four characters. */
 export function anthropicStatus() {
-  if (process.env.ANTHROPIC_API_KEY) return { configured: true, source: 'ANTHROPIC_API_KEY' };
-  if (process.env.ANTHROPIC_AUTH_TOKEN) return { configured: true, source: 'ANTHROPIC_AUTH_TOKEN' };
-  return { configured: false, source: 'an "ant auth login" profile, if you have one' };
+  const { key, source } = currentKey();
+  if (key) return { configured: true, source, last4: lastFour(key) };
+  if (process.env.ANTHROPIC_AUTH_TOKEN) return { configured: true, source: 'token', last4: '' };
+  return { configured: false, source: null, last4: '' };
+}
+
+/** Checks a key by listing models, which costs nothing. Returns null when it works, else the reason. */
+export async function testKey(key) {
+  const { Anthropic, client: c } = await client(key);
+  try {
+    await c.models.list({ limit: 1 });
+    return null;
+  } catch (err) {
+    if (err instanceof Anthropic.AuthenticationError) return 'Claude rejected this key.';
+    if (err instanceof Anthropic.PermissionDeniedError) return 'This key is not allowed to use the API.';
+    if (err instanceof Anthropic.APIConnectionError) return 'Could not reach the Claude API. Check your connection.';
+    if (err instanceof Anthropic.APIError) return `Claude error ${err.status}: ${err.message}`;
+    return err.message;
+  }
 }
 
 async function anthropic(task, messages, routeInfo) {
@@ -254,7 +360,7 @@ async function anthropic(task, messages, routeInfo) {
         ? await c.messages.create(params)
         : await c.beta.messages.create({ ...params, betas: ['server-side-fallback-2026-07-01'], fallbacks: 'default' });
   } catch (err) {
-    if (err instanceof Anthropic.AuthenticationError) throw new Error('Claude rejected the key. Check ANTHROPIC_API_KEY.');
+    if (err instanceof Anthropic.AuthenticationError) throw new Error('Claude rejected the key. Paste a new one in AI settings.');
     if (err instanceof Anthropic.RateLimitError) throw new Error('Claude rate limit reached. Wait a minute and try again.');
     if (err instanceof Anthropic.APIError) throw new Error(`Claude error ${err.status}: ${err.message}`);
     throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlens",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Run your Node backend through backlens and see every request, every query, and what is wrong with them.",
   "license": "MIT",
   "type": "module",

package/server.js

@@ -306,6 +306,10 @@ export function startServer({ port, root = process.cwd(), token, manualArgv = nu
         const p = url.pathname;
         if (req.method === 'GET' && p === '/api/ai/status') return json(res, 200, await ai.status());
         if (req.method === 'POST' && p === '/api/ai/settings') return json(res, 200, { settings: ai.saveSettings(body) });
+        if (req.method === 'POST' && p === '/api/ai/key') return json(res, 200, await ai.setKey(body.key));
+        if (req.method === 'POST' && p === '/api/ai/key/remove') return json(res, 200, await ai.forgetKey());
+        if (req.method === 'POST' && p === '/api/ai/ollama/pull') return json(res, 200, await ai.pullModel(body.model));
+        if (req.method === 'POST' && p === '/api/ai/ollama/stop') return json(res, 200, await ai.stopPullModel());
         if (req.method === 'POST' && p === '/api/ai/explain') return json(res, 200, await ai.explain(body.key));
         if (req.method === 'POST' && p === '/api/ai/fix') return json(res, 200, await ai.startFix(body.key));
         const m = p.match(/^\/api\/ai\/fix\/([0-9a-f-]{36})(?:\/(send|apply|keep|revert|escalate|stop))?$/);

package/ui.html

@@ -152,6 +152,12 @@
   .conf.high { background: #12301f; color: #8de0b0; } .conf.medium { background: var(--warn-bg); color: var(--warn); } .conf.low { background: #3a1a1c; color: #f3a6a6; }
   .opt-card { display: block; border: 1px solid var(--line); border-radius: 8px; padding: 12px 14px; margin-bottom: 10px; cursor: pointer; }
   .opt-card:has(input:checked) { border-color: var(--accent); background: #ffffff05; }
+  .opt-card { cursor: default; } .opt-card > label { cursor: pointer; }
+  .opt-card a { color: var(--accent); }
+  .opt-card .btn { text-decoration: none; display: inline-block; }
+  .field input[type=password] { flex: 1; font: 13px var(--mono); color: var(--text); background: var(--bg); border: 1px solid var(--line-2); border-radius: 6px; padding: 6px 8px; }
+  .progress { height: 6px; border-radius: 3px; background: var(--raise); overflow: hidden; margin: 10px 0 0; }
+  .progress > div { height: 100%; background: var(--accent); transition: width .4s; }
   .opt-card b { font-size: 13px; } .opt-card small { display: block; color: var(--sub); font-size: 12px; margin-top: 4px; }
   .field { display: flex; align-items: center; gap: 10px; margin: 10px 0; font-size: 13px; color: var(--sub); }
   .field input[type=number], .field select { font: 13px var(--mono); color: var(--text); background: var(--bg); border: 1px solid var(--line-2); border-radius: 6px; padding: 5px 8px; }
@@ -423,6 +429,11 @@ function renderSetup() {
       <div class="hintline">A script that rebuilds on change (like dev or start:dev) means you never press restart.</div></fieldset>
     <fieldset><legend>Run the tests with</legend>${group(scripts, isTest, (n, c) => opt('test', n, c, n === guessTest), guessTest)}${opt('test', '', 'no tests', !guessTest)}</fieldset>
     <label class="toggle" style="margin-bottom:20px"><input type="checkbox" name="auto" ${current.autoRestart ? 'checked' : ''} /> restart the app when a file changes (for scripts that do not watch)</label>
+    ${cfg.needsSetup ? `<fieldset><legend>Explain and fix issues with</legend>
+      <label class="opt"><input type="radio" name="ai" value="ollama" checked /><span>Local model</span><code>free, private, runs on this computer</code></label>
+      <label class="opt"><input type="radio" name="ai" value="anthropic" /><span>Claude</span><code>your own API key, strongest fixes</code></label>
+      <label class="opt"><input type="radio" name="ai" value="" /><span>Later</span><code>change it any time in AI settings</code></label>
+      <div class="hintline">The next screen walks you through it. Nothing is downloaded or paid without a click.</div></fieldset>` : ''}
     <div class="row-actions"><button class="primary" type="submit">${cfg.needsSetup ? 'Start app' : 'Save and restart'}</button>${!cfg.needsSetup ? '<button class="ghost" type="button" id="setup-cancel">Cancel</button>' : ''}<span class="error" role="alert">${esc(setupError)}</span></div>
   </form>`;
 }
@@ -691,7 +702,10 @@ function feedItem(e) {
   if (e.kind === 'ask') {
     const secs = e.status === 'running' && e.startedAt && fixJob ? Math.max(0.1, (fixJob.now - e.startedAt) / 1000 + (Date.now() - fixFetchedAt) / 1000) : 0;
     const live = e.status === 'running' ? `${secs.toFixed(0)} s${e.tokens ? `, ${e.tokens} tokens, ${(e.tokens / secs).toFixed(1)} per second` : ', reading the code…'}` : esc(e.detail || '');
-    return `<li class="fi">${dot}<div><div class="fh"><b>${esc(e.title)}</b>${t}</div><div class="sub2">${live}</div>${e.status === 'running' ? '<button class="ghost" type="button" id="fix-stop" style="margin-top:6px">Stop</button>' : ''}</div></li>`;
+    // A local model under ~8 tokens a second takes minutes per answer: say why, and what helps.
+    const slow = e.status === 'running' && fixJob.route && fixJob.route.kind === 'ollama' && secs > 15 && e.tokens / secs < 8;
+    const hint = slow ? `<div class="sub2 muted">The local model is slow on this computer (it shares memory with your other apps). Closing some speeds it up; Claude answers in seconds.</div>` : '';
+    return `<li class="fi">${dot}<div><div class="fh"><b>${esc(e.title)}</b>${t}</div><div class="sub2">${live}</div>${hint}${e.status === 'running' ? '<button class="ghost" type="button" id="fix-stop" style="margin-top:6px">Stop</button>' : ''}</div></li>`;
   }
   if (e.kind === 'verdict') return `<li class="fi">${dot}<div class="verdict ${e.status === 'done' ? 'good' : e.status === 'warn' ? 'meh' : 'bad'}">${esc(e.title)}</div></li>`;
   const verb = e.kind === 'read' ? 'Read' : e.kind === 'repair' ? '↻' : '';
@@ -753,25 +767,105 @@ async function pollFix() {
 }
 setInterval(pollFix, 600);
 
+let aiNotice = '';
+const gb = (n) => `${n.toFixed(1)} GB`;
+
+/** The local model card's body: install, open, download, then ready. Polled while the panel is open. */
+function localBody(o, s) {
+  if (!o.running && !o.installed) {
+    return `<small>Runs an AI model on this computer: free, and your code never leaves it. Install Ollama, open it, and this card updates by itself.</small>
+      <span class="field"><a class="btn primary" href="https://ollama.com/download" target="_blank" rel="noopener">Get Ollama</a><span class="muted">waiting for Ollama…</span></span>`;
+  }
+  if (!o.running) {
+    return `<small>Ollama is installed but not running. Open the Ollama app; this card updates by itself.</small>
+      <span class="field"><span class="muted">waiting for Ollama…</span></span>`;
+  }
+  const names = [...new Set([...o.catalog.map((m) => m.name), ...o.models])];
+  const info = (n) => o.catalog.find((m) => m.name === n);
+  const label = (n) => {
+    const m = info(n);
+    const have = o.models.includes(n);
+    return `${n}${n === o.recommended ? ' (best for this computer)' : ''}${have ? ' · downloaded' : m ? ` · ${gb(m.sizeGb)} download` : ''}`;
+  };
+  const chosen = s.ollamaModel;
+  const ready = o.models.includes(chosen);
+  const pull = o.pull && o.pull.model === chosen ? o.pull : null;
+  let action = '';
+  if (pull && !pull.done) {
+    const pct = pull.total ? Math.floor((pull.completed / pull.total) * 100) : 0;
+    action = `<div class="progress"><div style="width:${pct}%"></div></div>
+      <span class="field"><span class="muted">${pull.total ? `${pct}% of ${gb(pull.total / 1024 ** 3)}` : esc(pull.status)}</span><button class="ghost" type="button" id="ai-pull-stop">Stop</button></span>`;
+  } else if (!ready) {
+    const m = info(chosen);
+    action = `<span class="field"><button class="primary" type="button" id="ai-pull" data-model="${esc(chosen)}">Download ${esc(chosen)}${m ? ` (${gb(m.sizeGb)})` : ''}</button>
+      ${pull && pull.error ? `<span class="error">${esc(pull.error)}</span>` : ''}</span>`;
+  }
+  const note = info(chosen) ? `<small>${esc(chosen)} ${esc(info(chosen).note)} This computer has ${o.ramGb} GB of memory.</small>` : '';
+  return `<small>${ready ? 'Ready. Code never leaves this machine.' : 'Ollama is running. Download a model to use it.'}</small>
+    <span class="field">model <select name="ollamaModel">${names.map((n) => `<option value="${esc(n)}" ${n === chosen ? 'selected' : ''}>${esc(label(n))}</option>`).join('')}</select></span>
+    ${action}${note}`;
+}
+
+function claudeBody(a, s) {
+  const keyLine = a.configured
+    ? `<span class="field"><span>Using the key ending in <code>${esc(a.last4 || '…')}</code>, ${a.source === 'env' ? 'from ANTHROPIC_API_KEY' : a.source === 'saved' ? 'saved on this computer' : 'from your environment'}.</span>${a.source === 'saved' ? '<button class="ghost" type="button" id="ai-key-remove">Remove</button>' : ''}</span>`
+    : `<span class="field"><input type="password" id="ai-key" placeholder="sk-ant-…" autocomplete="off" spellcheck="false" /><button class="primary" type="button" id="ai-key-save">Check and save</button></span>
+       <small>Create one at <a href="https://console.anthropic.com/settings/keys" target="_blank" rel="noopener">console.anthropic.com</a>. Checking it is free. It is saved in your user folder (~/.config/backlens), never in this project, and never shown again.</small>`;
+  return `<small>The strongest fixes. backlens picks Haiku, Sonnet or Opus per issue and shows the cost before sending.</small>
+    ${keyLine}
+    <span class="field">daily budget $ <input type="number" name="dailyBudgetUsd" min="0" step="0.5" value="${s.dailyBudgetUsd}" /> <span>spent today ${usd(aiStatus.spentTodayUsd)}</span></span>`;
+}
+
 async function renderAISettings() {
   const el = $('#aiset');
   try { aiStatus = await (await api('/api/ai/status')).json(); } catch { el.innerHTML = '<p class="error">Could not load AI settings.</p>'; return; }
   const s = aiStatus.settings, o = aiStatus.ollama, a = aiStatus.anthropic;
-  const models = o.models.length ? o.models : [s.ollamaModel];
-  el.innerHTML = `<button class="ghost close" type="button" id="aiset-close">Close</button><h2>AI settings</h2><p class="muted" style="font-size:13px">Who explains issues and suggests fixes. Saved in .backlens/ai.json.</p>
+  el.innerHTML = `<button class="ghost close" type="button" id="aiset-close">Close</button><h2>AI settings</h2><p class="muted" style="font-size:13px">Who explains issues and suggests fixes. Changes save as you make them.</p>
+    <p class="muted" style="font-size:12px">Some fixes never need a model: running independent calls together (Promise.all) and missing indexes are written by backlens itself.</p>
     <form id="aiset-form"><section>
-      <label class="opt-card"><input type="radio" name="provider" value="ollama" ${s.provider === 'ollama' ? 'checked' : ''}/> <b>Local model</b> <span class="chip">free</span> <span class="chip">private</span>
-        <small>${o.running ? `Ollama is running. Code never leaves this machine.` : 'Ollama is not running. Install it from ollama.com, or brew install ollama, then brew services start ollama.'}</small>
-        <span class="field">model <select name="ollamaModel">${models.map((m) => `<option ${m === s.ollamaModel ? 'selected' : ''}>${esc(m)}</option>`).join('')}</select></span></label>
-      <label class="opt-card"><input type="radio" name="provider" value="mock" ${s.provider === 'mock' ? 'checked' : ''}/> <b>Recorded answers</b> <span class="chip">free</span>
-        <small>No model at all. Explain uses backlens's own words; fixes come from .backlens/ai-fixtures.json. For trying the flow.</small></label>
-      <label class="opt-card"><input type="radio" name="provider" value="anthropic" ${s.provider === 'anthropic' ? 'checked' : ''}/> <b>Claude, with your own key</b> <span class="chip">paid by you</span>
-        <small>${a.configured ? `Key found in ${esc(a.source)}.` : `No key found. Set ANTHROPIC_API_KEY before starting backlens, or use ${esc(a.source)}.`} backlens picks Haiku, Sonnet or Opus per issue and shows the cost before sending.</small>
-        <span class="field">daily budget $ <input type="number" name="dailyBudgetUsd" min="0" step="0.5" value="${s.dailyBudgetUsd}" /> <span>spent today ${usd(aiStatus.spentTodayUsd)}</span></span></label>
+      <div class="opt-card ${s.provider === 'ollama' ? 'on' : ''}"><label><input type="radio" name="provider" value="ollama" ${s.provider === 'ollama' ? 'checked' : ''}/> <b>Local model</b> <span class="chip">free</span> <span class="chip">private</span></label>
+        <div id="ai-local">${localBody(o, s)}</div></div>
+      <div class="opt-card ${s.provider === 'anthropic' ? 'on' : ''}"><label><input type="radio" name="provider" value="anthropic" ${s.provider === 'anthropic' ? 'checked' : ''}/> <b>Claude, with your own key</b> <span class="chip">paid by you</span></label>
+        <div id="ai-claude">${claudeBody(a, s)}</div></div>
+      <div class="opt-card ${s.provider === 'mock' ? 'on' : ''}"><label><input type="radio" name="provider" value="mock" ${s.provider === 'mock' ? 'checked' : ''}/> <b>No model</b> <span class="chip">free</span></label>
+        <small>Explanations in backlens's own words. Fixes only where backlens can write them itself.</small></div>
     </section>
     <label class="toggle" style="margin:6px 0 6px"><input type="checkbox" name="replay" ${s.replay ? 'checked' : ''}/> keep recent requests in memory so a fix can be replayed (never written to disk, never sent to a model)</label>
     <label class="toggle" style="margin:0 0 16px"><input type="checkbox" name="replayWrites" ${s.replayWrites ? 'checked' : ''}/> also replay requests that change data (POST, PUT, DELETE): they run again against your dev database</label>
-    <div class="actions"><button class="primary" type="submit">Save</button><span class="muted" style="font-size:12px;align-self:center">${aiStatus.history} fix${aiStatus.history === 1 ? '' : 'es'} in local history</span></div></form>`;
+    <div class="actions"><span class="${aiNotice.startsWith('!') ? 'error' : 'muted'}" role="status" style="font-size:12px;align-self:center">${esc(aiNotice.replace(/^!/, ''))}</span><span class="muted" style="font-size:12px;align-self:center;margin-left:auto">${aiStatus.history} fix${aiStatus.history === 1 ? '' : 'es'} in local history</span></div></form>`;
+}
+
+// While the panel is open, follow Ollama starting and model downloads without redrawing the key box.
+setInterval(async () => {
+  if ($('#aiset').hidden || !aiStatus) return;
+  const o = aiStatus.ollama;
+  const waiting = !o.running || (o.pull && !o.pull.done) || !o.models.includes(aiStatus.settings.ollamaModel);
+  if (!waiting) return;
+  try {
+    const next = await (await api('/api/ai/status')).json();
+    const finished = o.pull && !o.pull.done && next.ollama.pull && next.ollama.pull.done;
+    aiStatus = next;
+    if (finished) { aiNotice = next.ollama.pull.error ? '!' + next.ollama.pull.error : `${next.ollama.pull.model} downloaded.`; return renderAISettings(); }
+    const box = $('#ai-local');
+    if (box && !box.contains(document.activeElement)) box.innerHTML = localBody(next.ollama, next.settings);
+  } catch {}
+}, 1500);
+
+async function saveAISettings() {
+  const f = new FormData($('#aiset-form'));
+  try {
+    await aiPost('/api/ai/settings', { provider: f.get('provider'), ollamaModel: f.get('ollamaModel') || aiStatus.settings.ollamaModel, dailyBudgetUsd: f.get('dailyBudgetUsd'), replay: f.get('replay') === 'on', replayWrites: f.get('replayWrites') === 'on' });
+    aiNotice = 'Saved.';
+  } catch (err) { aiNotice = '!' + err.message; }
+  renderAISettings();
+}
+document.addEventListener('change', (e) => { if (e.target.closest('#aiset-form') && e.target.id !== 'ai-key') saveAISettings(); });
+
+async function aiAction(button, path, body, done) {
+  button.disabled = true;
+  aiNotice = '';
+  try { await aiPost(path, body); aiNotice = done; } catch (err) { aiNotice = '!' + err.message; }
+  renderAISettings();
 }
 
 document.addEventListener('click', async (e) => {
@@ -807,16 +901,21 @@ document.addEventListener('click', async (e) => {
     if (action === 'keep' || action === 'revert') { lastTotal = -1; poll(); }
     return;
   }
-  if (e.target.closest('#ai-open')) { $('#aiset').hidden = false; renderAISettings(); return; }
+  if (e.target.closest('#ai-pull')) { const b = e.target.closest('#ai-pull'); return aiAction(b, '/api/ai/ollama/pull', { model: b.dataset.model }, ''); }
+  if (e.target.closest('#ai-pull-stop')) return aiAction(e.target.closest('#ai-pull-stop'), '/api/ai/ollama/stop', {}, '');
+  if (e.target.closest('#ai-key-save')) {
+    const input = $('#ai-key');
+    const key = input.value.trim();
+    input.value = '';
+    if (!key) { aiNotice = '!Paste a key first.'; return renderAISettings(); }
+    aiNotice = 'Checking the key…';
+    $('#ai-key-save').textContent = 'Checking…';
+    return aiAction(e.target.closest('#ai-key-save'), '/api/ai/key', { key }, 'Key works and is saved. Pick Claude above to use it.');
+  }
+  if (e.target.closest('#ai-key-remove')) return aiAction(e.target.closest('#ai-key-remove'), '/api/ai/key/remove', {}, 'Key removed from this computer.');
+  if (e.target.closest('#ai-open')) { aiNotice = ''; $('#aiset').hidden = false; renderAISettings(); return; }
   if (e.target.closest('#aiset-close')) { $('#aiset').hidden = true; return; }
 });
-document.addEventListener('submit', async (e) => {
-  if (e.target.id !== 'aiset-form') return;
-  e.preventDefault();
-  const f = new FormData(e.target);
-  await aiPost('/api/ai/settings', { provider: f.get('provider'), ollamaModel: f.get('ollamaModel'), dailyBudgetUsd: f.get('dailyBudgetUsd'), replay: f.get('replay') === 'on', replayWrites: f.get('replayWrites') === 'on' });
-  renderAISettings();
-});
 document.addEventListener('keydown', (e) => { if (e.key === 'Escape') { if (!$('#aiset').hidden) $('#aiset').hidden = true; else if (fixJob && !['thinking', 'verifying', 'reverting'].includes(fixJob.stage)) { fixJob = null; renderFix(); } } });
 
 function render() {
@@ -955,10 +1054,27 @@ document.addEventListener('submit', async (e) => {
   const res = await api('/api/config', { method: 'POST', body: JSON.stringify({ app: f.get('app'), test: f.get('test') || null, autoRestart: f.get('auto') === 'on' }) });
   if (!res.ok) { setupError = (await res.json()).error || 'Could not save.'; render(); return; }
   showSetup = false;
+  const ai = f.get('ai');
+  if (ai) {
+    try { await aiPost('/api/ai/settings', { provider: ai }); } catch {}
+  }
   await loadConfig();
   testInfo = null;
   render();
   pollApp();
+  // Open the AI settings when the chosen helper still needs a step (Ollama, a model, a key).
+  if (ai) {
+    try {
+      const st = await (await api('/api/ai/status')).json();
+      const ready = ai === 'ollama' ? st.ollama.running && st.ollama.models.includes(st.settings.ollamaModel) : st.anthropic.configured;
+      if (!ready) { aiNotice = ''; $('#aiset').hidden = false; renderAISettings(); }
+    } catch {}
+  }
+});
+document.addEventListener('submit', (e) => {
+  if (e.target.id !== 'aiset-form') return;
+  e.preventDefault();
+  if (document.activeElement && document.activeElement.id === 'ai-key') $('#ai-key-save').click();
 });
 document.addEventListener('click', async (e) => {
   if (e.target.closest('#setup-open') || e.target.closest('#setup-open-2')) { showSetup = true; render(); return; }