ucode-agent 1.63.0 → 1.64.0

package/README.md

@@ -365,7 +365,13 @@ Everything after the frontmatter is the instruction.
 | `/session delete 2,5` | delete saved conversations by number (or `d d` in the list) |
 | `/new` | save this one and start fresh |
 | `/remember <note>` | add a standing note to this project's `UCODE.md` |
-| `/undo` | put back every file the last turn changed |
+| `/undo [n]` | put the project back as it was before the last turn — or `n` turns — including what commands changed |
+| `/diff` | what has changed this session |
+| `/commit [msg]` | commit the changes, with a message written from the diff if you give none |
+| `/review` | read the uncommitted changes for bugs, changing nothing |
+| `/init` | read the project and write its `UCODE.md` |
+| `/mcp` | connected MCP servers and their tools |
+| `/permissions [ask\|auto]` | ask before every command, or run them; what is always allowed |
 | `/look [url]` | open the running app and report what is on the page |
 | `/deploy [folder]` | put the app online and get its link |
 | `/mic` | say what you want instead of typing it — same as `ctrl+t` |
@@ -393,6 +399,86 @@ Recording uses what the computer already has: Windows' built-in recorder, `sox`
 or `ffmpeg` on macOS (`brew install sox`), `arecord` or `sox` on Linux. If a
 quiet mic is taken for silence, set `UCODE_MIC_QUIET` lower than 800.
 
+### Your own commands
+
+A file `.ucode/commands/explain.md` (or `~/.ucode/commands/` for every
+project) becomes `/explain`. Its text is the prompt; `$ARGUMENTS` is replaced
+by whatever you type after the command.
+
+### MCP servers
+
+Connect tools from any MCP server — library docs, GitHub, a database:
+
+```
+ucode mcp add context7 npx -y @upstash/context7-mcp
+ucode mcp add github --url https://api.githubcopilot.com/mcp/ --header "Authorization=Bearer ${GITHUB_TOKEN}"
+ucode mcp list
+ucode mcp remove github
+```
+
+They are saved in `~/.ucode/mcp.json` (`--project` puts them in this folder's
+`.ucode/mcp.json`). ucode asks before each MCP tool runs; answer `a` to always
+allow that tool. A project's own servers and hooks only run once you approve them.
+
+### Permissions and hooks
+
+`.ucode/settings.json` (or `~/.ucode/settings.json`):
+
+```json
+{
+  "commands": "ask",
+  "allow": ["npm test", "git status"],
+  "hooks": {
+    "afterEdit": ["npx prettier --write {files}"],
+    "beforeCommand": ["node guard.js"]
+  }
+}
+```
+
+`"commands": "ask"` puts every command to you first (`/permissions ask`);
+answering `a` adds it to `allow`. A `beforeCommand` hook that exits non-zero
+stops the command; it sees it in `UCODE_COMMAND`.
+
+### Run it without a keyboard
+
+```
+ucode -p "fix the failing test"            prints the answer
+ucode -p "make a quiz app" --json --yes    one JSON line: ok, answer, files, steps, requests, time
+```
+
+Progress goes to stderr. With no `--yes`, anything that would be asked is declined.
+`npm run eval` runs ten real jobs this way and checks each one — use it before
+a release (it spends about 100 free requests).
+
+### Other models
+
+Any OpenAI-compatible server works, Ollama on your own computer included —
+free and offline:
+
+```
+UCODE_BASE_URL=http://localhost:11434/v1 UCODE_MODEL=qwen2.5-coder ucode
+```
+
+## How it thinks
+
+- **Thinking levels.** Flash-Lite does not think at all unless asked. ucode
+  asks for a little on every step (it costs nothing on a straightforward
+  write), more on the first step of a build, and the most when a fix has
+  already failed. `UCODE_THINK=0` turns it off.
+- **A design direction for every build** — a tone, two typefaces and an accent —
+  so two apps never come out the same, and a check for the generated look
+  (the starter's colours, Inter, purple gradients, gradient text, emoji icons)
+  that sends it back to be fixed. `UCODE_DESIGN_CHECK=0` turns the check off.
+- **Learns from its mistakes.** Problems ucode keeps catching are counted in
+  `~/.ucode/lessons.json`, and the common ones are warned about before the next build.
+- **Tries a different approach** when the same problem survives a fix, and
+  offers to hand that fix to Gemini 3.5 Flash — only if you say yes, since it
+  has about 20 free requests a day.
+- **Changes to existing code** get their own rules: find the code, read only
+  what is involved, make the smallest change in the code's own style.
+- **Stays under the free limit.** Requests are spaced to Google's per-minute
+  limit instead of being refused and waited out; `/stats` shows how many were sent.
+
 ## Options
 
 ```
@@ -401,6 +487,9 @@ ucode [options]
   -m, --model <id>   which model to use
   -C, --cwd <dir>    work in another directory
       --plan         start in plan mode
+  -p, --print <task> do one task with no keyboard, print the answer, exit
+      --json         with -p: one JSON object about the run
+  -y, --yes          with -p: say yes to anything that would be asked
       --debug        print stack traces when something breaks
   -v, --version      print the version
   -h, --help         the above
@@ -420,7 +509,11 @@ Environment overrides: `UCODE_MODEL`, `UCODE_WORKER_MODEL` (a faster model for
 parallel workers), `UCODE_WORKER_STEPS`, `UCODE_MAX_CONTEXT_TOKENS`,
 `UCODE_MAX_STEPS`, `UCODE_MAX_TOOL_OUTPUT`, `UCODE_REQUEST_TIMEOUT_MS`,
 `UCODE_STALL_MS` (how long a silent reply is waited on before asking again, 60s),
-`UCODE_BASE_URL`, `UCODE_NO_UPDATE`.
+`UCODE_BASE_URL`, `UCODE_NO_UPDATE`, `UCODE_THINK=0`, `UCODE_DESIGN_CHECK=0`,
+`UCODE_RPM` (requests a minute before pacing, 0 = off), `UCODE_RIPGREP=0`.
+
+Search uses ripgrep (`rg`) when it is installed — much faster on a big
+project — and its own search otherwise.
 
 Web search needs a Tavily key — free, 1000 searches a month, no card. Without
 one, ucode answers from what it knows and says that it could not check.

package/package.json

@@ -1,64 +1,65 @@
-{
-  "name": "ucode-agent",
-  "version": "1.63.0",
-  "description": "ucode - a terminal coding agent that reads, edits and runs your code, on Google Gemini models.",
-  "type": "module",
-  "main": "ucode.js",
-  "bin": {
-    "ucode": "ucode.js"
-  },
-  "files": [
-    "ucode.js",
-    "src/",
-    "skills/",
-    "templates/",
-    "THIRD_PARTY_NOTICES.md",
-    "LICENSE-APACHE"
-  ],
-  "scripts": {
-    "start": "node ucode.js",
-    "test": "node test/run.js",
-    "prepublishOnly": "node scripts/no-bundled-key.js && node test/run.js",
-    "hooks": "node scripts/install-hooks.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sppideey/ucode-agent.git"
-  },
-  "bugs": {
-    "url": "https://github.com/sppideey/ucode-agent/issues"
-  },
-  "homepage": "https://github.com/sppideey/ucode-agent#readme",
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "agent",
-    "cli",
-    "terminal",
-    "coding-agent",
-    "llm",
-    "gemini",
-    "google-gemini",
-    "ai"
-  ],
-  "author": "om dixit",
-  "license": "(MIT OR Apache-2.0)",
-  "dependencies": {
-    "@babel/parser": "^7.29.9",
-    "chalk": "^6.0.0",
-    "dotenv": "^18.0.3",
-    "jsonrepair": "^3.15.0",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "openai": "^7.23.0",
-    "playwright-core": "^1.63.0"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.2",
-    "typescript": "^5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "ucode-agent",
+  "version": "1.64.0",
+  "description": "ucode - a terminal coding agent that reads, edits and runs your code, on Google Gemini models.",
+  "type": "module",
+  "main": "ucode.js",
+  "bin": {
+    "ucode": "ucode.js"
+  },
+  "files": [
+    "ucode.js",
+    "src/",
+    "skills/",
+    "templates/",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE-APACHE"
+  ],
+  "scripts": {
+    "start": "node ucode.js",
+    "test": "node test/run.js",
+    "prepublishOnly": "node scripts/no-bundled-key.js && node test/run.js",
+    "hooks": "node scripts/install-hooks.js",
+    "eval": "node test/evals/run.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sppideey/ucode-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sppideey/ucode-agent/issues"
+  },
+  "homepage": "https://github.com/sppideey/ucode-agent#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "terminal",
+    "coding-agent",
+    "llm",
+    "gemini",
+    "google-gemini",
+    "ai"
+  ],
+  "author": "om dixit",
+  "license": "(MIT OR Apache-2.0)",
+  "dependencies": {
+    "@babel/parser": "^7.29.9",
+    "chalk": "^6.0.0",
+    "dotenv": "^18.0.3",
+    "jsonrepair": "^3.15.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "openai": "^7.23.0",
+    "playwright-core": "^1.63.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/core/commands.js

@@ -0,0 +1,44 @@
+/**
+ * commands.js — slash commands the user writes themselves.
+ *
+ *   ~/.ucode/commands/<name>.md          yours, everywhere
+ *   <project>/.ucode/commands/<name>.md  this project's (wins over yours)
+ *
+ * The file is a prompt. `/name some words` sends it, with $ARGUMENTS replaced
+ * by the words — or the words added at the end when the file has no
+ * $ARGUMENTS. Its first line is what /help shows.
+ */
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const USER_COMMANDS = path.join(os.homedir(), '.ucode', 'commands');
+export const projectCommands = (cwd) => path.join(cwd, '.ucode', 'commands');
+
+async function readDir(dir) {
+  const found = new Map();
+  for (const entry of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+    if (!entry.isFile() || !/\.md$/i.test(entry.name)) continue;
+    const name = entry.name.replace(/\.md$/i, '').toLowerCase();
+    if (!/^[a-z0-9][\w-]*$/.test(name)) continue;
+    const body = await fs.readFile(path.join(dir, entry.name), 'utf8').catch(() => null);
+    if (!body?.trim()) continue;
+    const first = body.trim().split('\n')[0].replace(/^#+\s*/, '').trim();
+    found.set(name, { name, body: body.trim(), description: first.slice(0, 70) });
+  }
+  return found;
+}
+
+/** Every command, by name without the slash. */
+export async function loadCommands(cwd, { userDir = USER_COMMANDS } = {}) {
+  const [mine, project] = await Promise.all([readDir(userDir), readDir(projectCommands(cwd))]);
+  return new Map([...mine, ...project]);
+}
+
+/** The prompt a command sends, given what was typed after it. */
+export function expandCommand(body, args = '') {
+  const words = String(args).trim();
+  if (body.includes('$ARGUMENTS')) return body.split('$ARGUMENTS').join(words);
+  return words ? `${body}\n\n${words}` : body;
+}

package/src/core/genericcheck.js

@@ -0,0 +1,147 @@
+/**
+ * genericcheck.js — the generated look, caught in code.
+ *
+ * The rules against it were already written down, in the system prompt and
+ * the ui-ux skill: not the starter's palette, not Inter at every size, not a
+ * purple-to-blue gradient, not emoji standing in for icons. Flash-Lite reads
+ * them and ships the starter's teal anyway. A rule the model can skip is a
+ * suggestion; a check that hands the problem back is a rule.
+ *
+ * Everything here is a few regular expressions over files already on disk —
+ * milliseconds, no model call. Only a hit costs anything: one fix round.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+/** The starter's own accent, which means nobody chose one. */
+const STARTER = {
+  'plain-html': { files: ['styles.css'], token: /--accent\s*:\s*#2dd4bf\b/i },
+  'next-shadcn': { files: ['src/app/globals.css'], token: /--primary\s*:\s*oklch\(\s*0\.53\s+0\.2\s+264\s*\)/i },
+};
+
+/** Files that carry a Next.js app's look. */
+const LOOK_FILES = {
+  'next-shadcn': ['src/app/globals.css', 'src/app/layout.tsx', 'src/app/page.tsx'],
+};
+
+const NAMED = {
+  purple: 300, violet: 300, indigo: 275, blueviolet: 271, mediumpurple: 260, rebeccapurple: 270,
+  darkviolet: 282, slateblue: 248, mediumslateblue: 249, darkslateblue: 248, magenta: 300, fuchsia: 300,
+  blue: 240, royalblue: 225, mediumblue: 240, dodgerblue: 210, cornflowerblue: 219,
+};
+
+/** Hue in degrees of one colour, or null for a grey or something unreadable. */
+export function hueOf(colour) {
+  const c = String(colour).trim().toLowerCase();
+  if (NAMED[c] !== undefined) return NAMED[c];
+
+  let r; let g; let b;
+  const hex = /^#([0-9a-f]{3,8})$/.exec(c);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3 || h.length === 4) h = [...h.slice(0, 3)].map((x) => x + x).join('');
+    [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+  }
+  const rgb = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/.exec(c);
+  if (rgb) [r, g, b] = rgb.slice(1, 4).map((v) => Number(v) / 255);
+  const hsl = /^hsla?\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%/.exec(c);
+  if (hsl) return Number(hsl[2]) < 25 ? null : Number(hsl[1]) % 360;
+  const lch = /^oklch\(\s*[\d.]+%?\s+([\d.]+)\s+([\d.]+)/.exec(c);
+  // oklch puts blue near 264 and purple near 300-310; shift to the same wheel as hsl.
+  if (lch) return Number(lch[1]) < 0.06 ? null : (Number(lch[2]) - 25 + 360) % 360;
+  if (r === undefined) return null;
+
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const d = max - min;
+  const light = (max + min) / 2;
+  const sat = d === 0 ? 0 : d / (1 - Math.abs(2 * light - 1));
+  if (sat < 0.25) return null;
+  let hue;
+  if (max === r) hue = ((g - b) / d) % 6;
+  else if (max === g) hue = (b - r) / d + 2;
+  else hue = (r - g) / d + 4;
+  return Math.round((hue * 60 + 360) % 360);
+}
+
+/** Every gradient's argument list, brackets balanced. */
+function gradients(css) {
+  const found = [];
+  const re = /(?:linear|radial|conic)-gradient\(/gi;
+  let m;
+  while ((m = re.exec(css))) {
+    let depth = 1;
+    let i = re.lastIndex;
+    for (; i < css.length && depth; i++) {
+      if (css[i] === '(') depth++;
+      else if (css[i] === ')') depth--;
+    }
+    found.push(css.slice(re.lastIndex, i - 1));
+  }
+  return found;
+}
+
+const COLOUR = /#[0-9a-f]{3,8}\b|(?:rgba?|hsla?|oklch)\([^)]*\)|\b[a-z]+\b/gi;
+
+/** The purple-to-blue gradient: every coloured stop blue-to-purple, at least one of them purple. */
+export function purpleGradient(css) {
+  return gradients(css).some((args) => {
+    const hues = (args.match(COLOUR) ?? []).map(hueOf).filter((h) => h !== null);
+    return hues.length >= 2 && hues.every((h) => h >= 200 && h <= 330) && hues.some((h) => h >= 250);
+  });
+}
+
+/**
+ * The files that make up the page. For a plain page that is index.html and
+ * whatever it actually links: a starter stylesheet left behind, unlinked,
+ * says nothing about how the app looks.
+ */
+async function lookFiles(dir, template) {
+  if (template !== 'plain-html') return LOOK_FILES[template] ?? [];
+  const html = await fs.readFile(path.join(dir, 'index.html'), 'utf8').catch(() => '');
+  const linked = [...html.matchAll(/<(?:link|script)\b[^>]*\b(?:href|src)\s*=\s*["']([^"'?#]+)/gi)]
+    .map((m) => m[1])
+    .filter((f) => !/^(?:[a-z]+:)?\/\//i.test(f) && /\.(?:css|m?js)$/i.test(f));
+  return ['index.html', ...new Set(linked)];
+}
+
+/** Problems with the look of the app in `dir`, as lines for the model. Never throws. */
+export async function genericLook(dir, template = 'plain-html') {
+  const files = await lookFiles(dir, template);
+  const texts = await Promise.all(files.map((f) => fs.readFile(path.join(dir, f), 'utf8').catch(() => '')));
+  const all = texts.join('\n');
+  if (!all.trim()) return [];
+
+  const problems = [];
+  const starter = STARTER[template];
+  if (starter) {
+    const own = starter.files.filter((f) => files.includes(f) || template !== 'plain-html');
+    const texts2 = await Promise.all(own.map((f) => fs.readFile(path.join(dir, f), 'utf8').catch(() => '')));
+    if (texts2.some((t) => starter.token.test(t))) {
+      problems.push('The accent is still the starter\'s own colour, so the app looks like every other one built from it. Pick an accent for this app and set it in the tokens.');
+    }
+  }
+  if (/font-family\s*:\s*["']?Inter["']?\s*[,;}]|--font-[\w-]+\s*:\s*["']?Inter["']?\s*[,;]|family=Inter(?![+\w])|import\s*\{[^}]*\bInter\b[^}]*\}\s*from\s*["']next\/font\/google/i.test(all)) {
+    problems.push('The type is Inter, the default of generated apps. Choose a typeface with a character that fits this app.');
+  }
+  if (purpleGradient(all)) {
+    problems.push('There is a purple-to-blue gradient, the most recognisable mark of a generated design. Use the app\'s own accent, flat or with a quiet tint.');
+  }
+  if (/(?:-webkit-)?background-clip\s*:\s*text/i.test(all)) {
+    problems.push('There is gradient text (background-clip: text). Set headings in a solid colour and let the type carry them.');
+  }
+  const emoji = all.match(/<(?:button|h[1-6])\b[^>]*>\s*\p{Extended_Pictographic}/gu) ?? [];
+  if (emoji.length >= 3) {
+    problems.push(`Emoji stand in for icons in ${emoji.length} buttons or headings. Use small inline SVG icons or plain words.`);
+  }
+  return problems;
+}
+
+/** The fix-round text for a list of look problems. */
+export function genericMessage(problems) {
+  return 'ucode checked the design for the generated look and found:\n' +
+    problems.map((p) => `- ${p}`).join('\n') +
+    '\nFix these in the design tokens and styles only - a new accent, a new typeface. Do not ' +
+    'restructure the app or change what it does.';
+}

package/src/core/headless.js

@@ -0,0 +1,73 @@
+/**
+ * headless.js — `ucode -p "task"`: one job, no keyboard, then exit.
+ *
+ * For scripts, CI and the eval set. Progress goes to stderr, the answer to
+ * stdout (or, with --json, one JSON object describing the run), and the exit
+ * code says whether it worked. Nobody is there to approve anything, so every
+ * question is answered no — unless --yes says to answer yes.
+ */
+
+import { Readable } from 'node:stream';
+import { Plain } from '../ui/plain.js';
+import { Agent } from './loop.js';
+import { requestCount } from './provider.js';
+import { stopServers } from '../tools/shell.js';
+import { closeBrowser } from '../tools/browser.js';
+
+export class Headless extends Plain {
+  constructor({ cwd, yes = false }) {
+    super({ cwd, input: Readable.from([]), output: process.stderr });
+    this.yes = yes;
+    this.answer = '';
+  }
+
+  assistant(text, opts = {}) {
+    super.assistant(text, opts);
+    if (!opts.replay && String(text).trim()) this.answer = String(text).trim();
+  }
+
+  confirm({ action }) {
+    this.note(`${this.yes ? 'approved' : 'declined'} (no one to ask): ${action}`);
+    return Promise.resolve(this.yes);
+  }
+}
+
+/** Run one prompt. Resolves to the exit code. */
+export async function runHeadless({ cwd, prompt, json = false, yes = false, plan = false, write = (s) => process.stdout.write(s) }) {
+  const ui = new Headless({ cwd, yes });
+  const agent = new Agent({ cwd, ui });
+  if (plan) ui.mode = 'plan';
+  const started = Date.now();
+  const sent = requestCount();
+  let error = null;
+  try {
+    await agent.bootstrap();
+    agent.startMcp();
+    await agent.mcpStarting;
+    await agent.turn(prompt);
+  } catch (err) {
+    error = err;
+    ui.error(err);
+  } finally {
+    stopServers();
+    agent.mcp?.close();
+    await closeBrowser().catch(() => {});
+    await agent.settled?.().catch(() => {});
+  }
+
+  const ok = !error && !agent.endedSilently;
+  if (json) {
+    write(`${JSON.stringify({
+      ok,
+      answer: ui.answer,
+      files: [...(agent.touched ?? [])],
+      steps: agent.stats.steps,
+      requests: requestCount() - sent,
+      ms: Date.now() - started,
+      error: error ? (error.failed ?? error.message ?? String(error)) : null,
+    })}\n`);
+  } else if (ui.answer) {
+    write(`${ui.answer}\n`);
+  }
+  return ok ? 0 : 1;
+}

package/src/core/lessons.js

@@ -0,0 +1,83 @@
+/**
+ * lessons.js — the mistakes ucode keeps catching, remembered across sessions.
+ *
+ * Every fix round is ucode finding something wrong with what the model built.
+ * The same few things come up build after build: a script that does not parse,
+ * a button wired to nothing, a list that forgets itself on reload. Counting
+ * them costs nothing, and the ones that keep happening go into the system
+ * prompt as a short warning — said before the build, where it is free, instead
+ * of after it, where it costs a fix round.
+ *
+ * The lessons themselves are fixed sentences, not something the model writes:
+ * a note in the prompt of every future build should never be a model's guess.
+ *
+ * Kept in ~/.ucode/lessons.json. Failing to read or write it never matters.
+ */
+
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const LESSONS_FILE = path.join(os.homedir(), '.ucode', 'lessons.json');
+
+const KINDS = [
+  { id: 'js-parse', test: /does not parse|SyntaxError|Unexpected token/i,
+    lesson: 'Scripts have failed to parse. Before finishing, check every script you wrote for unclosed brackets, braces and template strings.' },
+  { id: 'css-var', test: /custom propert(?:y is|ies are) used and never defined/i,
+    lesson: 'Stylesheets have used custom properties that were never defined. Define every token in :root before using it.' },
+  { id: 'dead-button', test: /NOTHING HAPPENS/,
+    lesson: 'Buttons have done nothing when clicked. Wire every control to a handler, attached after its element exists.' },
+  { id: 'add-broken', test: /ADDING DOES NOT WORK/,
+    lesson: 'Adding an item has failed. The form handler must prevent the default, read the inputs, update the list, render and save.' },
+  { id: 'no-persist', test: /works until you refresh/i,
+    lesson: 'Data has been lost on reload. Save to localStorage on every change and load it when the page starts.' },
+  { id: 'console', test: /Console errors/i,
+    lesson: 'Pages have thrown console errors. Check that every element you query exists, and wrap JSON.parse of saved data in try/catch.' },
+  { id: 'type-errors', test: /error TS\d+/,
+    lesson: 'TypeScript errors have come back. Match prop and function types exactly, and check an import exists before using it.' },
+  { id: 'tests', test: /tests covering your change fail/i,
+    lesson: 'Changes have broken existing tests. Read a function\'s tests before changing what it returns.' },
+  { id: 'generic', test: /generated look/i,
+    lesson: 'Designs have come out generic: the starter\'s colours, Inter, purple gradients. Choose the accent and typeface first, and use them.' },
+];
+
+/** Which kinds of mistake a block of problems text contains. */
+export function kindsIn(problems) {
+  const text = String(problems ?? '');
+  return KINDS.filter((k) => k.test.test(text)).map((k) => k.id);
+}
+
+async function readCounts(file) {
+  try {
+    const data = JSON.parse(await fs.readFile(file, 'utf8'));
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Count the mistakes in this fix round. Never throws. */
+export async function noteMistakes(problems, file = LESSONS_FILE) {
+  const found = kindsIn(problems);
+  if (!found.length || process.env.UCODE_LESSONS === '0') return;
+  try {
+    const counts = await readCounts(file);
+    const next = { ...counts };
+    for (const id of found) next[id] = (Number(next[id]) || 0) + 1;
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temp, JSON.stringify(next, null, 2));
+    await fs.rename(temp, file);
+  } catch { /* a lesson not saved is a lesson not learned, never a broken turn */ }
+}
+
+/** The lessons worth repeating: seen at least `min` times, the commonest first. */
+export async function lessonsText(file = LESSONS_FILE, { min = 2, max = 3 } = {}) {
+  if (process.env.UCODE_LESSONS === '0') return '';
+  const counts = await readCounts(file);
+  const top = KINDS
+    .filter((k) => (Number(counts[k.id]) || 0) >= min)
+    .sort((a, b) => counts[b.id] - counts[a.id])
+    .slice(0, max);
+  return top.map((k) => `- ${k.lesson}`).join('\n');
+}