ucode-agent 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucode-agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "ucode - a terminal coding agent that reads, edits and runs your code. NVIDIA and Cohere models over OpenRouter.",
   "type": "module",
   "main": "ucode.js",

package/skills/build-app/SKILL.md

@@ -1,81 +1,160 @@
 ---
 name: build-app
-description: Take something from nothing to running — choosing the stack, laying out the files, installing, wiring it up, and proving it works before saying it does.
-auto: scaffold, new project, from scratch, build an app, make an app, create an app, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app
+description: Take an app from nothing to running and finished — stack choice, non-interactive scaffolding, project structure, secrets, AI and API integration, error handling, and proving it works before saying it does.
+auto: scaffold, new project, from scratch, build an app, make an app, create an app, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app, full stack, fullstack, saas, mvp
 ---
 
 # Building something from nothing
 
-The failure mode here is not writing bad code. It is delivering a folder of
-files that has never been run, described as if it works.
+The failure mode is not bad code. It is a folder of files that has never been
+run, handed over as if it works. Everything here is ordered to prevent that.
 
-## Decide the shape before writing anything
+## 1. Decide the shape, out loud, before any file exists
 
-State these in one line each, out loud, then build to them:
+One line each:
 
-- **What it does** — the single sentence a user would say.
-- **The stack** — and why. Default to the smallest thing that does the job: a
-  single HTML file with no build step is a legitimate answer and often the
-  right one. Reach for a framework when routing, state or a component tree
-  genuinely earns it, not because the project sounds serious.
-- **The files** — the whole list, before you create any of them.
+- **What it does** — the sentence a user would say.
+- **The core loop** — the one path through it that must work perfectly
+  (e.g. upload a photo → analysed → see a score and the problems).
+- **The stack, and why** — the smallest thing that does the job:
 
-If the request has a user interface in it, the `ui-ux` skill is already loaded.
-Follow it. Do not design as you go and tidy up afterwards.
+  | Need | Choose |
+  | --- | --- |
+  | One page, no secrets, no server | a single `index.html`, no build step |
+  | Interactive client app, no secrets | Vite + React + TypeScript |
+  | Pages plus a server, secrets, API routes, SEO | Next.js App Router + TypeScript |
+  | An API on its own | Node (Hono/Express) or Python (FastAPI) |
 
-## Scaffold without being asked questions
+- **The file list** — the whole tree, before creating any of it.
 
-Nothing you run has a keyboard. A scaffolder that stops to ask "Would you like
-to use TypeScript?" gets no answer and fails, so give it every answer up front:
+If there is a user interface, the `ui-ux` skill is already loaded. Decide the
+design direction now, not after the logic works.
+
+## 2. Scaffold without being asked questions
+
+Nothing you run has a keyboard. A scaffolder that asks "Would you like to use
+TypeScript?" gets no answer and fails, so give it every answer up front:
 
 ```bash
-# Next.js — creates ./my-app; use . instead of a name to fill the current folder
+# Next.js into ./my-app (use . to fill the current folder — it must be empty)
 npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm --yes
 
-# shadcn/ui, from inside the Next.js project
+# shadcn/ui, from inside the project — every component you need, in one add
 npx shadcn@latest init -d -y
-npx shadcn@latest add button card input label badge progress separator skeleton sonner -y
+npx shadcn@latest add button card input label badge progress separator skeleton sonner tooltip -y
 ```
 
-For any other scaffolder, find its flags for every question it would ask
-(`--help` lists them) before running it for real.
-
-`create-next-app` refuses a folder that already has files in it. If the current
-folder is not empty, scaffold into a named subfolder and pass that as `cwd` to
-every command after it.
-
-Add every shadcn component you will need in one `add` call, not one per call.
-
-## Lay it out in one pass
-
-Use `batch_write` for the whole skeleton rather than `write_file` twenty times.
-One call, every file, in dependency order. Then `run_command` the install, and
-`run_commands` for anything independent that can happen at the same time.
+- `create-next-app` refuses a folder that already has files. If the current
+  folder is not empty, scaffold into a named subfolder and pass it as `cwd` to
+  every later command.
+- For any other scaffolder, find the flag for every question (`--help`) first.
+- Install dependencies once, all together: `npm i zod lucide-react` — not one
+  `npm i` per package.
 
-Real content from the first pass. Placeholder copy, `TODO`, and a commented-out
-function are all the same thing: a promise you did not keep, in a file the user
-now has to find.
+## 3. Structure it like a real project
 
-## Wire everything
+For Next.js App Router:
 
-Every button does its thing. Every form submits, validates and says what went
-wrong. Every list has an empty state. Every request has a loading state and a
-failure state. A control that does nothing is worse than no control, because
-the user has to try it to find out.
-
-If it stores anything, decide where, and make it survive a reload.
-
-## Run it, then look at it
-
-- Start it with `run_command`. A dev server needs `background: true`, which
-  returns immediately with a PID — a foreground server just burns the turn and
-  gets killed.
-- Then actually exercise it: `curl` the routes, run the tests, open the page.
-  A clean build is not evidence that it works, only that it compiles.
-- Fix what you find and run it again.
+```
+src/
+  app/
+    layout.tsx          fonts, metadata, <body> shell, Toaster
+    page.tsx            the screen — composes components, holds little logic
+    globals.css         design tokens and the shadcn theme variables
+    api/<name>/route.ts server-only endpoints; the only place secrets live
+  components/
+    <feature>/          one folder per feature: its pieces, split by job
+    ui/                 shadcn components (generated — edit via the theme)
+  lib/
+    <service>.ts        calls to outside services, typed in and out
+    schemas.ts          zod schemas shared by client and server
+    utils.ts
+  types/                shared TypeScript types, if lib/ does not own them
+```
 
-## Report what happened
+- **One component per file**, named for what it is (`ScoreDial.tsx`,
+  `NutrientFindings.tsx`, `LabelUpload.tsx`), not a 600-line `page.tsx`.
+- Server components by default; `"use client"` only on the interactive parts.
+- Types at every boundary. Parse external data with zod rather than trusting
+  its shape.
+
+## 4. Secrets and outside services
+
+- **A key never reaches the browser.** It lives in a server route or server
+  action. Anything imported by a `"use client"` file ships to every visitor —
+  including a "hardcoded for now" key. If the user asks to hardcode one, put it
+  in a server-only module (`lib/server/*.ts`, or `import 'server-only'`) and
+  say where it is so they can move it to `.env.local` later.
+- Every outbound call gets: a timeout (`AbortSignal.timeout(60_000)`), a check
+  of the response status, and an error that says what failed — surfaced to the
+  UI as a real message, never a silent `catch {}`.
+
+### Calling an AI model (OpenRouter or any OpenAI-compatible API)
+
+```ts
+// src/app/api/analyze/route.ts — runs on the server only
+export const runtime = 'nodejs';
+export const maxDuration = 60;
+
+const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    model: 'provider/model-id',
+    messages: [
+      { role: 'system', content: 'Reply with JSON only, matching this shape: {...}' },
+      { role: 'user', content: [
+        { type: 'text', text: 'Analyse this nutrition label.' },
+        { type: 'image_url', image_url: { url: dataUrl } },   // data:image/jpeg;base64,...
+      ] },
+    ],
+  }),
+  signal: AbortSignal.timeout(60_000),
+});
+```
 
-Say what you built, how to start it, and what you checked. If something is
-untested or unfinished, say which part and why — that sentence costs you
-nothing and saves the user an hour of finding out on their own.
+- **Ask for JSON and parse it defensively.** Models wrap JSON in prose or code
+  fences: extract the first `{...}` block, `JSON.parse` it, validate with zod,
+  and on failure return a clear "could not read the result" error rather than
+  crashing. Clamp numbers to their range.
+- **Put the judgement rules in the prompt, explicitly** — thresholds, what
+  counts as "too much", what to omit. A vague prompt gives a different answer
+  every time; a specific one gives the product its consistency.
+- **Images:** check type and size on the client (e.g. ≤ 5 MB, jpeg/png/webp),
+  downscale large photos in a canvas before upload, send as a base64 data URL.
+- Reasoning models may take 10–60s. Show progress, and make the route's
+  timeout longer than the model's.
+
+## 5. Build order
+
+1. Skeleton and design tokens, so every later piece is styled correctly first time.
+2. The server route with the real integration, tested with `curl` before any UI.
+3. The core loop UI, wired to the real route.
+4. Every state: empty, loading, success, error, and invalid input.
+5. Polish: motion, responsive, copy, favicon, page title and metadata.
+
+Use `batch_write` for the skeleton — one call, every file.
+
+## 6. Prove it works
+
+- `npm run build` — it type-checks and lints; a build that fails is not done.
+- Start it: `npm run dev` goes to the background on its own and comes back with
+  the URL once ready. Do not start it twice.
+- Exercise it: `curl` the API route with real input, load the page, check the
+  core loop end to end. A clean build proves it compiles, not that it works.
+- Fix what you find and check again.
+
+## 7. Definition of done
+
+- The core loop works end to end against the real service.
+- No `TODO`, no placeholder copy, no dead buttons, no console errors.
+- Every async action has loading, success and error states.
+- Invalid input is caught with a useful message before it reaches the server.
+- Secrets only on the server.
+- `npm run build` passes.
+
+## 8. Report
+
+What you built, the URL, how to start it again, and what you checked. If
+anything is untested or unfinished, name it — one sentence of honesty saves the
+user an hour of finding out on their own.

package/skills/code-review/SKILL.md

@@ -1,36 +1,81 @@
 ---
 name: code-review
-description: Review a change the way a careful colleague would — correctness first, then the things that will hurt later, with the reasoning attached.
+description: Review code the way a senior engineer would — correctness first, then security, failure handling, contracts, performance and tests, with every finding ranked, located and backed by a concrete failing scenario.
+auto: review, code review, review my, review this, audit this, look over, check my code, pr review, pull request
 ---
 
 # Reviewing code
 
-A review that lists everything is not a review, it is a linter with opinions.
-Rank what you find, and be honest about which parts you actually verified.
+A review that lists everything is a linter with opinions. The value is in
+finding what will actually break, ranking it, and being honest about what you
+verified versus what you suspect.
 
-## Read it in this order
+## 1. Understand before judging
 
-1. **Correctness.** Does it do what it claims? Walk the edge cases: empty,
-   one, many, null, the boundary value, the concurrent call, the second run.
-2. **Failure.** What happens when the thing it depends on fails? A swallowed
-   error and a bare `catch {}` are bugs waiting for the worst possible moment.
-3. **Security.** Untrusted input reaching a query, a shell, a path, or the DOM.
-   Secrets in the source. Credentials in a log line.
-4. **Contracts.** Did a signature, a return shape or a stored format change
-   without every caller and every existing row being accounted for?
-5. **Clarity.** Names that say what the thing is. Comments that explain why,
-   never what. A function that fits in your head.
-6. **Tests.** Does the test actually fail when the code is wrong? A test that
-   asserts a mock was called proves nothing about behaviour.
+- What is the change trying to do? Read the description, the diff, and enough of
+  the surrounding code to know the callers and the data it touches.
+- Get the diff: `git diff`, `git diff main...HEAD`, or the files named. Read
+  every changed file in full, not only the hunks — context is where bugs hide.
+- If there are tests, run them. If it runs, run it.
 
-## Say it usefully
+## 2. Passes, in order of what hurts most
 
-For each finding: the file and line, what breaks, and the input that breaks it.
-"This could be cleaner" is not actionable. "`parse()` throws on an empty body,
-which the retry path hits on a 204" is.
+1. **Correctness** — does it do what it claims for every input? Walk: empty,
+   one, many, null/undefined, the boundary value, duplicates, the second call,
+   concurrent calls, a slow or failing dependency.
+2. **Security** — untrusted input reaching SQL, a shell, a file path, a URL
+   fetch (SSRF), `innerHTML`/`dangerouslySetInnerHTML`, `eval`, a redirect.
+   Secrets in source, in client bundles, or in logs. Missing auth or
+   authorization checks on a route. IDs a user can change to see someone
+   else's data.
+3. **Failure handling** — errors swallowed (`catch {}`), a fallback that hides
+   a real failure, no timeout on an outbound call, a partial write left behind,
+   an error message that leaks internals.
+4. **Contracts** — a changed signature, return shape, API response, or stored
+   format without every caller and every existing record accounted for.
+   Migrations that are not reversible or not safe on live data.
+5. **Performance** — N+1 queries, unbounded loops over user data, missing
+   pagination, work in a render loop, a huge dependency for a small job,
+   blocking I/O on a hot path.
+6. **Concurrency and state** — shared mutable state, race conditions,
+   stale caches, React effects with missing or wrong dependencies.
+7. **Tests** — do they fail when the code is wrong? A test asserting a mock was
+   called proves nothing about behaviour. Are the risky paths covered?
+8. **Clarity** — names that say what things are, functions that fit in your
+   head, comments that explain *why*. Only flag this when it will cause a real
+   misunderstanding.
 
-Separate what you know from what you suspect, and say which is which. If you
-did not run it, do not describe the behaviour as if you watched it happen.
+## 3. Verify before you report
 
-Say what is good, briefly, and only where it is genuinely worth copying.
-Reviews that never approve of anything stop being read.
+For each suspected issue, check it: read the caller, trace the value, run the
+case if you can. Drop anything you cannot substantiate, or label it clearly as
+a question rather than a finding.
+
+## 4. Write findings that can be acted on
+
+Rank by severity:
+
+- **Blocker** — wrong results, data loss, a security hole, a crash on a normal path.
+- **Major** — breaks on a realistic edge case, or a failure that will be hard to diagnose.
+- **Minor** — a real but small risk, or a clear maintainability cost.
+- **Nit** — style and preference. Keep these few, or leave them out.
+
+Each finding: **where** (`path:line`), **what breaks**, **the input or sequence
+that breaks it**, and **the fix**. For example:
+
+> **Major** — `src/app/api/analyze/route.ts:42` — `JSON.parse(text)` throws when
+> the model wraps its reply in a code fence, which it does intermittently. The
+> route then returns a 500 with no message. Extract the first `{…}` block and
+> validate it with the zod schema; return a 422 with "could not read the label"
+> on failure.
+
+"This could be cleaner" is not a finding.
+
+## 5. Close out
+
+Start with a one-line verdict (ship / ship after fixes / needs rework), then
+the findings, most severe first. Mention what is genuinely good only where it
+is worth copying. State what you did not review or could not run.
+
+If asked to fix the findings, fix blockers and majors first, re-run the tests,
+and report what changed.

package/skills/debug/SKILL.md

@@ -1,47 +1,89 @@
 ---
 name: debug
-description: Find the actual cause of a bug instead of the first plausible one — reproduce it, narrow it, prove the fix, and leave a test behind.
+description: Find and fix the real cause of a bug — reproduce it, narrow it down with evidence, prove the fix, guard it with a test, and check for the same bug elsewhere.
+auto: bug, crash, crashes, crashing, broken, not working, doesn't work, does not work, stack trace, exception, traceback, throws, failing, fails, regression, undefined is not, cannot read properties, 500 error, blank page, hangs, freezes
 ---
 
 # Debugging
 
-The temptation is to read the code, form a theory, change something, and
-declare victory when the symptom disappears. That is how a bug gets moved
-rather than fixed.
+The temptation is to read the code, form a theory, change something, and call
+it fixed when the symptom goes away. That moves bugs rather than fixing them.
+Work from evidence, in this order.
 
-## Reproduce it first
+## 1. Reproduce it yourself
 
-Do not start from the description. Run the thing and see the failure with your
-own eyes: the command, the input, the exact error and where it comes from. If
-you cannot reproduce it, say so and ask for what you need — the input, the
-version, the full stack. Guessing from a paraphrase wastes everyone's turn.
+Do not debug from the description. Run it and see it fail: the exact command,
+the input, the full error, the line it comes from. Write down the reproduction
+as a single command or a few steps — you will run it again at the end.
 
-## Narrow before you theorise
+If you cannot reproduce it, say so and ask for exactly what is missing: the
+input, the environment, the version, the full output. Guessing from a
+paraphrase wastes everyone's turn.
 
-- Read the whole stack trace, including the frames you assume are irrelevant.
-  The top frame is where it surfaced, not necessarily where it went wrong.
-- `grep` for the message text to find where it is produced.
-- Cut the search space in half at a time: does the smaller input fail? Does it
-  fail on the previous commit? Does the layer below get the right value?
-- Print or log the values at the boundary rather than reasoning about what they
-  should be. What you believe is in that variable is the thing under suspicion.
+## 2. Read the whole error
 
-## Fix the cause
+- The whole stack trace, including frames you assume are irrelevant. The top
+  frame is where it surfaced, not necessarily where it went wrong.
+- The first error, not the last. Later errors are often consequences.
+- `grep` for the exact message text to find where it is produced.
+- Check the obvious before the clever: is the file saved, the server restarted,
+  the right branch checked out, the env var set, the dependency installed, the
+  cache cleared (`.next`, `node_modules/.vite`, `__pycache__`)?
 
-State the cause in one sentence before you change anything: *this value is
-undefined here because the caller only sets it on the success path*. If you
-cannot write that sentence, you have not found it yet.
+## 3. Narrow it down
 
-Then fix that, not the symptom. A guard that hides the undefined value leaves
-the real defect in place, with one more layer over it.
+Cut the search space in half each step:
 
-## Prove it
+- **Input:** does a smaller or simpler input still fail? Find the smallest one
+  that does.
+- **Code:** comment out or bypass half the path. Does it still fail?
+- **Time:** did it work before? `git log` / `git diff` since then, or
+  `git bisect` between a good and a bad commit.
+- **Layer:** is the value right when it enters the function? When it leaves?
+  At the API boundary? In the database? Log it at each boundary and look,
+  rather than reasoning about what it "should" be.
 
-- Run the original reproduction. It must now pass.
-- Run the rest of the tests. A fix that breaks two other things is a trade,
-  and the user gets to make it, not you.
-- Write a test that fails without your fix. A bug with no regression test comes
-  back.
+The value you are sure about is the one under suspicion. Print it.
 
-Then say what the cause actually was, in one or two sentences. If you fixed
-something adjacent along the way, say that too.
+## 4. Know where bugs usually live
+
+- **Async:** a missing `await`, a race between two requests, state read before
+  it is set, a promise rejection nobody catches.
+- **State:** stale closures in React effects, mutation of shared objects, a
+  cache that was never invalidated.
+- **Boundaries:** off-by-one, empty arrays, `null` vs `undefined` vs `''`,
+  timezones, number parsing (`'10' + 1`), float rounding.
+- **Data shape:** the API returned something different from the type — an
+  error object, a wrapped payload, a string instead of JSON.
+- **Environment:** missing env var, wrong Node version, path case sensitivity,
+  Windows vs POSIX paths and line endings, a port already in use.
+- **Build tooling:** a stale build cache, a server/client boundary violation in
+  Next.js, a default vs named export mismatch, ESM vs CommonJS.
+
+## 5. State the cause before fixing it
+
+Write it in one sentence: *"`score` is `undefined` here because the parser
+returns `{ data: {...} }` and the component reads `result.score`."* If you
+cannot write that sentence, you have not found the cause yet — keep narrowing.
+
+## 6. Fix the cause, not the symptom
+
+A `?.` or a `try/catch` that hides the failure leaves the defect in place under
+one more layer. Fix it where it originates. Keep the change as small as the
+cause allows, and do not refactor unrelated code in the same change.
+
+## 7. Prove it
+
+- Run the original reproduction. It must pass now.
+- Run the whole test suite. A fix that breaks two other things is a trade the
+  user gets to decide on, not you.
+- Add a regression test that fails without the fix and passes with it — then
+  briefly revert the fix to confirm the test really catches it.
+- Look for the same mistake elsewhere: `grep` for the same pattern, call, or
+  assumption. Bugs come in families.
+
+## 8. Report
+
+The cause in one or two sentences, the fix, how you verified it, and anything
+adjacent you noticed but did not change. If you could not fully confirm it,
+say what is still uncertain.

package/skills/ui-ux/SKILL.md

@@ -1,237 +1,300 @@
 ---
 name: ui-ux
-description: How to design and build an interface that looks deliberate rather than generated — direction, tokens, layout, states, motion, accessibility. Loads itself for any work with a user interface in it.
-auto: app, apps, ui, ux, website, web app, webapp, web page, webpage, landing page, dashboard, frontend, front-end, interface, css, tailwind, html, react, vue, svelte, nextjs, next.js, redesign, restyle, responsive, dark mode, ugly, styling, stylesheet, mockup, prototype
+description: Design and build interfaces at the level of a senior product designer who also ships the code — direction, type, colour, layout, components, states, motion, accessibility and performance, verified on screen. Loads itself for any work with a user interface in it.
+auto: app, apps, ui, ux, website, web app, webapp, web page, webpage, landing page, dashboard, frontend, front-end, interface, css, tailwind, html, react, vue, svelte, nextjs, next.js, shadcn, redesign, restyle, responsive, dark mode, ugly, styling, stylesheet, mockup, prototype, component, components, polished, beautiful, good looking, visually
 ---
 
-# Interfaces
+# Interfaces, done properly
 
 The house style of a language model is a centred column, a purple-to-blue
-gradient, three equal cards and a lot of empty space. It is recognisable on
-sight, and everyone has now seen it a thousand times. Your job is to not
-produce it.
+gradient, three identical cards, Inter at every size, and a lot of empty space.
+Everyone has seen it a thousand times, and it reads as generated on sight.
+This skill exists to stop you producing it.
 
-This is not decoration applied at the end. It is the order the work happens in:
-direction, then structure, then tokens, then states, then verification.
+Work in this order and do not skip ahead. Most bad interfaces are good CSS
+applied to an undecided design.
 
-## 1. Decide the direction before writing any CSS
+1. Direction  2. Structure  3. Tokens  4. Components  5. States  6. Motion
+7. Accessibility and performance  8. Look at it  9. Report
 
-Answer these to yourself in one line each, then build to the answers:
-
-1. **Job** — what does this screen actually do?
-2. **Who** — who opens it, how often, and what do they need first?
-3. **Tone** — pick one and commit: utilitarian, editorial, technical, playful,
-   industrial, calm, dense. "Modern and clean" is not a tone, it is a way of
-   avoiding the question.
-4. **One memorable detail** — a colour, a texture, a typographic move, a single
-   interaction. Exactly one. It is the difference between a design and a
-   template.
-
-## 2. Pick the mode from the surface, not the product
-
-The mode names what success looks like for the person in front of it. It
-decides how much the interface is allowed to perform.
-
-- **Operate** — they are completing a task. App UI, dashboards, editors,
-  admin, settings, tools. Scannability, consistency and speed beat expression
-  every time. The personality lives in precise details, not in the hero.
-- **Persuade** — they are deciding whether to act. Landing pages, pricing,
-  marketing. Here the design *is* the product; earn the attention.
-- **Read** — they are trying to understand something. Docs, articles, guides.
-  Structure for comprehension first, then make reading pleasant enough to stay.
-- **Experience** — they are looking at the work itself. Portfolios, galleries.
-  The artifact leads from the first screen and the interface gets out of the way.
+---
 
-A tool's landing page is still Persuade. A dashboard is still Operate however
-beautiful the brand is. Never put a marketing hero on top of a working tool.
+## 1. Decide the direction before any code
+
+Write these down in one line each, then build to them:
+
+- **Job** — what does this screen do, in one sentence a user would say?
+- **Who and when** — who opens it, how often, on what device, in what light?
+  A tool opened forty times a day and a page seen once need opposite things.
+- **Mode** — pick one:
+  - **Operate**: completing a task (apps, dashboards, tools, settings). Speed,
+    scannability and consistency beat expression. Personality lives in details.
+  - **Persuade**: deciding whether to act (landing, pricing, marketing). The
+    design is the product; it has to earn attention in one screen.
+  - **Read**: understanding something (docs, articles). Measure, rhythm and
+    hierarchy first; decoration last.
+  - **Experience**: looking at the work itself (portfolio, gallery). The
+    content leads; the interface gets out of the way.
+- **Tone** — one word you commit to: clinical, warm, editorial, technical,
+  playful, industrial, calm, dense. "Modern and clean" is not a tone.
+- **The one memorable thing** — a colour, a type move, a texture, a single
+  interaction. Exactly one. It is the difference between a design and a theme.
+
+A dashboard stays Operate however loud the brand is. A tool's landing page is
+still Persuade. Never put a marketing hero on top of a working tool.
+
+## 2. Structure: hierarchy before decoration
+
+- Decide what the eye lands on first, second, third. Build that with **size,
+  weight, colour and position** before reaching for a box, a border or a card.
+  Three levels — primary, secondary, muted — is usually all a screen needs.
+- **The primary thing gets disproportionate size.** If a score, a total or a
+  status is the point of the screen, make it unmistakably larger than
+  everything around it — not 10% bigger, three or four times bigger.
+- Align to a grid and share edges. Ragged left edges are the single most common
+  reason a page feels amateur. Pick a max content width (e.g. 1120px for apps,
+  68ch for prose) and hold it.
+- Group by proximity: space **inside** a group must be smaller than space
+  **between** groups, or the grouping reads wrong however good the rest is.
+- One job per element. A card that is a link, a form and a menu is three cards.
+- Put actions where the eye already is: primary action at the end of the flow it
+  completes, destructive actions separated from safe ones.
 
-## 3. Tokens first, then never a raw value again
+## 3. Tokens: set them once, never use a raw value again
 
-Set these at the top and use them everywhere. One-off hard-coded values are
-exactly how a design drifts out of alignment with itself.
+Everything below is a starting point to adjust, not a look to ship unchanged.
+The palette in particular must be re-picked for the product's tone.
 
 ```css
 :root {
-  --font: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-  --mono: ui-monospace, SFMono-Regular, "Cascadia Code", Consolas, monospace;
-
-  /* One scale. Nothing between the steps. */
-  --text--1: .8125rem; --text-0: 1rem;   --text-1: 1.25rem;
-  --text-2:  1.5rem;   --text-3: 2rem;   --text-4: 2.75rem;
-
-  --s1: .25rem; --s2: .5rem; --s3: .75rem; --s4: 1rem;
-  --s5: 1.5rem; --s6: 2rem;  --s7: 3rem;   --s8: 4rem;
-
-  /* Neutrals carry a hue. Flat #808080 grey is what makes a UI look dead. */
-  --bg: #fbfaf9;  --surface: #ffffff; --line: #e6e2dd;
-  --ink: #17161a; --ink-2: #55525c;   --ink-3: #8a8792;
-
-  --accent: #2f6fe0; --accent-ink: #ffffff; --accent-soft: #eaf1fe;
-  --danger: #b42318; --ok: #217a4b; --warn: #b25e09;
-
-  --radius: 10px; --radius-sm: 6px;
-  --shadow: 0 1px 2px rgb(20 18 24 / .05), 0 8px 24px rgb(20 18 24 / .07);
+  /* Type — a real scale, fluid between mobile and desktop. */
+  --font-sans: "Inter Tight", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-display: var(--font-sans);
+  --font-mono: ui-monospace, "Cascadia Code", "JetBrains Mono", Consolas, monospace;
+
+  --text-xs:  .75rem;
+  --text-sm:  .875rem;
+  --text-md:  1rem;
+  --text-lg:  clamp(1.125rem, 1rem + .4vw, 1.25rem);
+  --text-xl:  clamp(1.375rem, 1.1rem + .9vw, 1.75rem);
+  --text-2xl: clamp(1.75rem, 1.3rem + 1.6vw, 2.5rem);
+  --text-3xl: clamp(2.25rem, 1.5rem + 3vw, 3.75rem);
+  --text-hero: clamp(3rem, 2rem + 5vw, 6rem);
+
+  /* Space — one scale, nothing in between. */
+  --s-1: .25rem; --s-2: .5rem; --s-3: .75rem; --s-4: 1rem;  --s-5: 1.5rem;
+  --s-6: 2rem;   --s-7: 3rem;  --s-8: 4rem;   --s-9: 6rem;  --s-10: 8rem;
+
+  /* Colour — neutrals carry a hue; flat #808080 grey is what makes a UI look dead.
+     OKLCH so lightness steps are perceptually even. */
+  --bg:        oklch(98.5% .004 90);
+  --surface:   oklch(100% 0 0);
+  --surface-2: oklch(96.5% .006 90);
+  --line:      oklch(90% .008 90);
+  --ink:       oklch(22% .01 90);
+  --ink-2:     oklch(45% .012 90);
+  --ink-3:     oklch(60% .01 90);
+
+  --accent:      oklch(58% .19 255);
+  --accent-ink:  oklch(99% 0 0);
+  --accent-soft: oklch(95% .03 255);
+
+  --good: oklch(62% .16 150);  --good-soft: oklch(95% .04 150);
+  --warn: oklch(72% .16 70);   --warn-soft: oklch(96% .05 80);
+  --bad:  oklch(58% .21 25);   --bad-soft:  oklch(95% .04 25);
+
+  --radius-sm: 6px; --radius: 10px; --radius-lg: 16px; --radius-full: 999px;
+  --shadow-sm: 0 1px 2px oklch(20% .01 90 / .06);
+  --shadow:    0 1px 2px oklch(20% .01 90 / .05), 0 8px 24px oklch(20% .01 90 / .08);
+  --shadow-lg: 0 2px 4px oklch(20% .01 90 / .06), 0 24px 48px oklch(20% .01 90 / .14);
   --focus: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent);
+
+  --ease-out: cubic-bezier(.22, 1, .36, 1);
+  --dur-1: 120ms; --dur-2: 200ms; --dur-3: 320ms;
 }
 
 @media (prefers-color-scheme: dark) {
   :root {
-    --bg: #101014;  --surface: #17171c; --line: #2a2a33;
-    --ink: #f2f1f5; --ink-2: #b3b0bd;   --ink-3: #807d8a;
-    --accent: #6fa4ff; --accent-ink: #0f1016; --accent-soft: #16203a;
+    --bg: oklch(16% .008 260);   --surface: oklch(20% .01 260);
+    --surface-2: oklch(24% .012 260); --line: oklch(30% .012 260);
+    --ink: oklch(95% .005 260);  --ink-2: oklch(76% .01 260); --ink-3: oklch(60% .01 260);
+    --accent: oklch(70% .16 255); --accent-ink: oklch(18% .02 260); --accent-soft: oklch(28% .06 255);
   }
 }
 
-* { box-sizing: border-box; }
+*, *::before, *::after { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; }
 body {
   margin: 0; background: var(--bg); color: var(--ink);
-  font: var(--text-0)/1.6 var(--font);
-  -webkit-font-smoothing: antialiased;
+  font: var(--text-md)/1.6 var(--font-sans);
+  -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility;
 }
-h1, h2, h3 { margin: 0; line-height: 1.15; letter-spacing: -.02em; }
-:focus-visible { outline: none; box-shadow: var(--focus); }
+h1, h2, h3 { margin: 0; line-height: 1.1; letter-spacing: -.02em; text-wrap: balance; }
+p { text-wrap: pretty; }
+:focus-visible { outline: none; box-shadow: var(--focus); border-radius: var(--radius-sm); }
+.num { font-variant-numeric: tabular-nums; }
 @media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after { animation: none !important; transition: none !important; }
+  *, *::before, *::after { animation-duration: 1ms !important; transition-duration: 1ms !important; }
 }
 ```
 
-**Swap the four palette lines to change direction, and keep everything else:**
-
-- **Paper** — `--bg:#faf9f7; --surface:#fff; --ink:#1a1815; --accent:#b45309`.
-  Warm, calm, for reading and for tools used daily.
-- **Console** — `--bg:#0d1117; --surface:#161b22; --ink:#e6edf3; --accent:#2f81f7`
-  with `--line:#30363d`. Technical and dense, for dashboards and dev tools.
-- **Editorial** — `--bg:#fffdf8; --surface:#fff; --ink:#141414; --accent:#c2410c`
-  plus a serif on headings only. For content and landing pages.
-
-One direction, all the way through. Half Console and half Editorial reads as a
-mistake, because it is one.
-
-**The rules behind the tokens**, for when you need a value that is not in them:
-
-- **Spacing** — every value from the scale. Space *inside* a group must be
-  smaller than the space *around* it, or the grouping reads wrong however good
-  the rest is.
-- **Type** — one family for UI, at most one more for display. Body 15–17px,
-  line-height 1.5–1.65, measure capped at 65–75ch. Headings tighter: 1.1–1.25,
-  and `letter-spacing: -.02em` above 28px.
-- **Colour** — one accent hue, one neutral ramp, semantic red/amber/green. Never
-  pure `#000` on pure `#fff`.
-- **Radius** — pick one and derive: inputs and buttons 6–8, cards 10–12,
-  pills 999. Four unrelated radii look like an accident.
-- **Depth** — borders and background steps first, shadows last, and only for
-  things that genuinely float: menus, modals, toasts. A shadow on every card
-  flattens the hierarchy instead of building it.
-- **Dark mode** — swap the variables. Never invert. Surfaces get *lighter* as
-  they rise, and pure white on near-black is too harsh: use around 90%.
-
-## 4. Layout
-
-- Build hierarchy with size, weight and colour before reaching for a box.
-  Three levels — primary, secondary, muted — is usually all you need.
-- Align to a grid and share edges. Ragged left edges are the single most
-  common reason a page feels amateur.
-- Full width is not a layout. Constrain content to what the content needs: a
-  table wants width, prose does not.
-- One job per element. A card that is a link, a form and a menu is three cards.
-
-## 5. States are most of the work
-
-An interface that only handles the happy path is a mockup. For every screen:
-
-- **Empty** — first run, nothing there yet. Say what this is and how to make
-  the first one. Never a blank box.
-- **Loading** — skeletons shaped like the real content, or a spinner on the
-  control that was pressed. Do not blank the page.
-- **Error** — what failed and what they can do about it. Keep their input.
-- **Partial** — one row failed and the rest loaded.
-
-And for every interactive element: `:hover`, `:focus-visible`, `:active`,
-`:disabled`, and the selected state. A control with only a default state is
-unfinished, not minimal. `outline: none` with no replacement focus ring is a
-bug, not a style choice.
+**The rules behind the tokens**, for when you need a value that is not there:
+
+- **Type.** One family for UI, at most one more for display. Body 15–17px at
+  1.5–1.65 line height, measure 60–75ch. Headings 1.05–1.2 line height with
+  negative tracking above 28px. Weight does more than size for mid-level
+  hierarchy: 600 for labels that matter, 400 for body, 500 for UI controls.
+  Use `tabular-nums` anywhere numbers line up or change in place.
+- **Pick a typeface with intent.** Inter everywhere is the generated look. Good
+  free choices through `next/font/google` or Google Fonts: *Inter Tight,
+  Geist, Manrope, DM Sans, Plus Jakarta Sans, Instrument Sans, Space Grotesk,
+  IBM Plex Sans* for UI; *Fraunces, Instrument Serif, Bricolage Grotesque,
+  Newsreader* for display. Load only the weights you use, `display: swap`.
+- **Colour.** One accent hue, one neutral ramp tinted slightly toward it, and
+  semantic good/warn/bad that mean one thing each. Colour is for meaning and
+  emphasis, not decoration. Never pure `#000` on pure `#fff`. Count the hue
+  families at the end: more than one accent plus the semantics means the
+  palette got away from you.
+- **Radius.** Pick one base and derive: controls 6–8, cards 10–16, pills full.
+  Four unrelated radii look like an accident.
+- **Depth.** Borders and background steps first; shadows only for things that
+  genuinely float (menus, popovers, modals, toasts). A shadow on every card
+  flattens the hierarchy it was meant to create.
+- **Dark mode.** Swap variables, never invert. Surfaces get *lighter* as they
+  rise. Text around 92–95% lightness, not pure white. Re-check every accent for
+  contrast in dark — most need to get lighter.
+
+### With Tailwind and shadcn/ui
+
+- shadcn ships with a neutral slate look. **Re-theme it** in `globals.css` by
+  setting its CSS variables (`--background`, `--foreground`, `--primary`,
+  `--muted`, `--accent`, `--destructive`, `--border`, `--ring`, `--radius`) to
+  your palette. Shipping the default theme is shipping someone else's design.
+- Use components for behaviour and accessibility (Dialog, Popover, Tabs,
+  Select, Tooltip, Toast/Sonner), then style them to the direction. Do not wrap
+  every region of the page in a `Card` — that is the three-card look again.
+- Extend the Tailwind theme with your tokens rather than scattering arbitrary
+  values (`text-[17px]`, `mt-[13px]`). Arbitrary values are the raw values this
+  section forbids, in a different syntax.
+- Icons: `lucide-react`, one stroke width throughout, sized to the text beside
+  them (16px with 14–15px text, 20px with 16–18px). Never emoji as UI icons.
+
+## 4. Components, with every state built in
+
+Every interactive element needs **default, hover, focus-visible, active,
+disabled**, and where it applies **selected, loading, error**. A control with
+only a default state is unfinished, not minimal.
 
 ```css
 .btn {
-  font: 500 var(--text-0)/1 var(--font);
-  padding: var(--s3) var(--s5);
+  display: inline-flex; align-items: center; justify-content: center; gap: var(--s-2);
+  min-height: 44px; padding: 0 var(--s-5);
+  font: 500 var(--text-md)/1 var(--font-sans);
   border: 1px solid transparent; border-radius: var(--radius-sm);
   background: var(--accent); color: var(--accent-ink);
-  cursor: pointer; transition: filter .15s, transform .05s;
-}
-.btn:hover    { filter: brightness(1.08); }
-.btn:active   { transform: translateY(1px); }
-.btn:disabled { opacity: .45; cursor: not-allowed; filter: none; }
-.btn--quiet   { background: transparent; color: var(--ink); border-color: var(--line); }
-.btn--quiet:hover { background: var(--accent-soft); }
-
-.input {
-  width: 100%; padding: var(--s3) var(--s4);
-  font: var(--text-0) var(--font); color: var(--ink);
-  background: var(--surface);
-  border: 1px solid var(--line); border-radius: var(--radius-sm);
+  cursor: pointer; transition: filter var(--dur-1), transform var(--dur-1) var(--ease-out);
 }
-.input::placeholder { color: var(--ink-3); }
+.btn:hover { filter: brightness(1.07); }
+.btn:active { transform: translateY(1px) scale(.99); }
+.btn:disabled, .btn[aria-busy="true"] { opacity: .5; cursor: not-allowed; filter: none; }
+.btn--quiet { background: transparent; color: var(--ink); border-color: var(--line); }
+.btn--quiet:hover { background: var(--surface-2); }
 ```
 
-## 6. Motion
+- **Buttons:** verb labels ("Analyze label", not "Submit"). One primary per
+  view. Loading state replaces the label's icon with a spinner and keeps the
+  width fixed so nothing jumps.
+- **Inputs:** a visible `<label>` always — a placeholder is not a label. Help
+  text below, errors below in `--bad` with an icon, `aria-invalid` and
+  `aria-describedby` wired up. Validate on blur, re-validate on input once
+  an error is showing, never shout on the first keystroke.
+- **File upload:** a real drop zone *and* a click target, keyboard operable,
+  showing accepted types and max size before the user tries. Show the chosen
+  file (thumbnail for images), let them replace or remove it, validate type and
+  size on the client before sending anything.
+- **Scores and metrics:** the number large, with its scale ("7.4 / 10"), a
+  label that says what it measures, and a colour band (good/warn/bad) that is
+  never the *only* signal — pair it with a word ("Good", "Moderate", "Poor").
+- **Lists of issues or findings:** most severe first; each with the thing, the
+  value, why it matters, in one or two lines. If there are none, say so plainly
+  once — do not render an empty section header.
+- **Tables:** right-align numbers, left-align text, tabular numerals, sticky
+  header on long tables, row hover, and a real empty state.
+
+## 5. States are most of the work
 
-One authored moment, not effects scattered everywhere, and not the same
-entrance animation on every section. 120–200ms, on `transform`, `opacity`,
-`filter` and colour only — never on `height` or `width`. Ease out from a state
-that is already visible. Honour `prefers-reduced-motion` every time.
+An interface that only handles the happy path is a mockup. For every screen
+and every async action:
 
-## 7. Non-negotiable
+- **Empty / first run** — what this is, and the one action that starts it.
+  Illustrated or typographic, never a blank rectangle.
+- **Loading** — skeletons shaped like the real content, or a progress
+  indicator on the control that was pressed. Say what is happening if it takes
+  more than a second ("Reading the label…"). Never blank the page.
+- **Success** — the result, with a clear next action (try another, share, copy).
+- **Error** — what failed in plain words, what to do next, and the user's input
+  preserved. Distinguish "you can fix this" (wrong file type) from "we failed"
+  (network, model error) — they need different words and different actions.
+- **Partial** — some parts loaded, one failed; show what worked.
+- **Edge content** — the longest realistic name, a value of zero, a missing
+  field, a thousand rows. Design for them, do not discover them.
+
+Announce async results to screen readers with an `aria-live="polite"` region.
+
+## 6. Motion
 
-- Contrast 4.5:1 for body text and placeholders, 3:1 for large text and for
-  the borders of controls.
-- Every control reachable and operable by keyboard, in the order it appears.
-- Labels on inputs. A placeholder is not a label.
-- Touch targets 44px.
-- `<button>` for actions, `<a href>` for navigation. Never a `<div>` with an
-  onClick.
-- `aria-label` on any icon-only button; real `alt` text on meaningful images.
-- Nothing shifts as content loads: reserve the space, set image dimensions.
-- 16px minimum body text on mobile, and `<meta name="viewport" content="width=device-width, initial-scale=1">`.
+One authored moment, not effects scattered everywhere. For a result screen that
+might be the score counting up and the findings staggering in 40–60ms apart.
+Everything else: 120–200ms, ease-out, on `transform`, `opacity`, `filter` and
+colour only — never animate `width`, `height`, `top` or `left`. Content must
+be readable with motion off; honour `prefers-reduced-motion` every time.
+
+## 7. Accessibility and performance — non-negotiable
+
+- Contrast: 4.5:1 body text and placeholders, 3:1 large text, icons and control
+  borders. `--ink-3` on `--bg` is for hints only.
+- Keyboard: every control reachable in visual order, visible focus ring,
+  Escape closes overlays, focus returns to the trigger.
+- Semantics: `<button>` for actions, `<a href>` for navigation, landmarks
+  (`header`, `main`, `nav`), one `<h1>`, headings in order.
+- Targets 44×44px on touch. `aria-label` on icon-only buttons. Real `alt` text.
+- Viewport meta, 16px minimum input text on mobile (iOS zooms below that).
+- No layout shift: reserve space for images and async content, set image
+  dimensions, use `next/image` in Next.js, `font-display: swap`.
+- Ship less JS: server components by default in Next.js, `"use client"` only on
+  the parts that are interactive.
 
 ## 8. Do not
 
-These are the defaults of the category rather than laws — a brief can earn any
-of them — but reaching for one *because it was the first thing to hand* means
-you were not deciding.
-
-- Purple-to-blue gradient headers. Gradient text. Glassmorphism as decoration.
-- Three identical feature cards with a lorem sentence each. Same-size icon +
-  heading + text cards used as the whole page structure. Nested cards.
-- The hero-metric template: big number, small label, three supporting stats.
-- A tracked uppercase eyebrow over every section, or 01 / 02 / 03 section
-  numbers where the order carries no information.
-- Emoji as interface icons. Use an icon set or well-drawn inline SVG.
-- Monospace as a costume for "technical" when there is no code or data in it.
-- A modal for something that needs neither interruption nor protected focus.
-- Centring everything. Long centred paragraphs are genuinely harder to read.
-- Inventing a component library when the project already has one. Look for
-  existing components, tokens and utilities first, and use them.
-- Placeholder copy. Write the real words — they are part of the design.
-
-## 9. Before you say it is done
-
-Open it and look at it. Then walk this list and fix what fails. The last three
-are the ones that get skipped, so do not skip them:
-
-1. **375px wide.** No horizontal scrollbar, nothing overlapping, nothing cut
-   off. If you wrote no media query at all, you have not done this.
-2. **The longest realistic string** in every label and every cell. Does the row
-   hold, or does one long title break the layout?
-3. **Empty data.** Is there a real empty state, or a blank rectangle?
-4. **Keyboard only.** Tab through everything. Can you see where you are at
-   every step?
-5. **Count the accent hues.** More than one family means the palette got away
-   from you. Put it back.
-6. **Contrast.** `--ink-3` on `--bg` is for hints, never for anything that has
-   to be read.
-
-Then say which of these you actually checked and what you found. Do not claim
-it works on mobile if you never made it narrow. If it runs in a browser, start
-it with `run_command` and `background: true` and open it before you call it
-finished.
+Defaults of the category. A brief can earn any of them; reaching for one
+because it was first to hand means you were not deciding.
+
+- Purple-to-blue gradients, gradient text, glassmorphism as decoration,
+  glowing blobs in the background.
+- Three identical feature cards; icon + heading + sentence cards as the whole
+  page; cards inside cards.
+- The hero-metric template: big number, small label, three stats in a row.
+- A tracked uppercase eyebrow over every section; 01/02/03 section numbers.
+- Emoji as icons. Monospace as a costume. Centred long paragraphs.
+- The default shadcn slate theme, unchanged.
+- Lorem ipsum, "Feature 1", "John Doe", placeholder images. Write the real copy
+  — it is part of the design.
+- A modal for anything that does not need to interrupt.
+
+## 9. Look at it, then report
+
+Run it (`npm run dev` starts in the background and returns the URL) and check:
+
+1. **375px wide** — no horizontal scroll, nothing overlapping or clipped. If you
+   wrote no responsive rules at all, you have not done this.
+2. **1440px wide** — the content has a max width and does not stretch into
+   unreadable lines.
+3. **Longest realistic content** in every label, cell and card.
+4. **Every state** — empty, loading, success, error — reachable and designed.
+5. **Keyboard only** — tab through everything; focus always visible.
+6. **Contrast** of body text, muted text and the accent on its background.
+7. **Hue count** — one accent family plus semantics.
+8. **The first thing the eye lands on** is the thing that matters most.
+
+Then say which of these you actually checked and what you found. Never claim it
+works on mobile if you never made it narrow.

package/skills/write-tests/SKILL.md

@@ -1,47 +1,85 @@
 ---
 name: write-tests
-description: Write tests that fail for the right reason — behaviour over implementation, real edges, and no assertions that can never break.
+description: Write tests that catch real regressions — the right level for each behaviour, real edge cases, deterministic setups, mocks only at the boundaries, and proof that each test can actually fail.
+auto: write tests, add tests, add a test, unit test, unit tests, test coverage, integration test, e2e test, end to end test, testing, vitest, jest, pytest, playwright
 ---
 
 # Writing tests
 
-The test that matters is the one that fails the day someone breaks the thing it
+The test that matters is the one that fails the day someone breaks what it
 covers. Every other test is overhead with a green tick on it.
 
-## Test behaviour, not implementation
+## 1. Find how this project tests
 
-Assert on what a caller can observe: the return value, the state afterwards,
-the thing that was written. A test that checks a private helper was called
-locks the implementation in place and will need rewriting the first time
-anyone refactors — while still not proving the feature works.
+- Look for the runner and its config before writing anything: `vitest.config.*`,
+  `jest.config.*`, `playwright.config.*`, `pytest.ini`/`pyproject.toml`,
+  `go test`, the `test` script in `package.json`.
+- Match the existing style: file location (`__tests__/`, `*.test.ts` beside the
+  source, `tests/`), naming, helpers, fixtures. Use what is there.
+- If nothing exists, pick the standard for the stack — Vitest for Vite and
+  Next.js, pytest for Python, the built-in `go test` — and add the script.
 
-## Cover the edges, not five versions of the middle
+## 2. Pick the right level for each behaviour
 
-For each unit, the ones that actually find bugs:
+- **Unit** — pure logic: parsing, scoring, validation, formatting, reducers.
+  Fast, many, no I/O.
+- **Integration** — a route handler with its validation and error paths, a
+  component with its real children, a module against a real temporary
+  database or filesystem.
+- **End to end** — the one or two core user journeys, in a real browser
+  (Playwright). Few, because they are slow and brittle.
+
+Most value per minute is in unit tests of the logic that makes decisions and
+integration tests of the boundaries where data comes in.
+
+## 3. Test behaviour, not implementation
+
+Assert what a caller can observe — the return value, the rendered output, the
+response, the state afterwards. A test that checks a private helper was called
+breaks on every refactor while proving nothing about the feature.
+
+For UI, query the way a user finds things: by role, label and text
+(`getByRole('button', { name: /analyze/i })`), not by class names or test IDs
+unless there is no accessible alternative.
+
+## 4. Cover the cases that find bugs
+
+For every unit, go through:
 
 - empty, one, many
-- the boundary: 0, -1, the last index, the maximum
-- null, undefined, the missing field, the wrong type
-- the failure path: the dependency throws, the network times out, the file is
-  gone
-- the second call: is it idempotent, is state left behind?
-
-## Make each test readable on its own
-
-- The name says the behaviour: `returns null when the session file is missing`.
-- Arrange, act, assert, in that order and visibly separated.
-- One reason to fail per test. Six assertions in a row means the first failure
-  hides the other five.
-- No shared mutable state between tests, and no dependence on the order they
-  run in.
-- Real values over mocks wherever it is affordable. Mock the network and the
-  clock; do not mock the thing you are testing.
-
-## Prove the test works
-
-Break the code on purpose and watch the test fail, then put it back. A test
-that has never failed is a test you have no reason to trust. If a test cannot
-fail — an assertion on a constant, a mock asserting itself — delete it.
-
-Then run the whole suite and report the real numbers, including anything that
-was already failing before you started.
+- boundaries: 0, -1, the exact threshold, just over and just under it, the max
+- missing: `null`, `undefined`, missing field, empty string, wrong type
+- malformed input: invalid JSON, a string where a number was expected,
+  a reply wrapped in prose
+- failure paths: the dependency throws, times out, returns an error status
+- repetition: the second call, the same input twice, concurrent calls
+
+A threshold rule ("sodium over 600mg is flagged") needs a test at 599, 600 and
+601. That is where the off-by-one lives.
+
+## 5. Keep tests deterministic and independent
+
+- Control time (`vi.useFakeTimers()`, a fixed clock) and randomness (a seed).
+- No real network. Mock at the boundary — the HTTP call, the SDK client — and
+  never mock the thing under test.
+- Each test sets up what it needs and cleans up after. No reliance on order.
+- Build test data with small factories so each test states only what matters
+  to it.
+- One behaviour per test, named for it:
+  `flags sodium when it is over the daily threshold`.
+- Arrange, act, assert — visibly separated.
+- Snapshots only for stable, small output; a 400-line snapshot gets approved
+  without being read.
+
+## 6. Prove each test can fail
+
+Break the code on purpose — flip a comparison, delete a branch — and watch the
+test fail, then restore it. A test that has never failed is a test you have no
+reason to trust. Delete tests that cannot fail (asserting a constant, a mock
+asserting itself).
+
+## 7. Run and report
+
+Run the whole suite, not only the new file. Report the real numbers — passed,
+failed, skipped — including anything that was already failing before you
+started, and anything you could not cover and why.

package/src/core/loop.js

@@ -1053,8 +1053,9 @@ export class Agent {
       .slice(-count);
 
     for (const m of tail) {
-      if (m.role === 'user') this.ui.write(`${blue('›')} ${dim(m.content.split('\n')[0])}`);
-      else this.ui.assistant(m.content);
+      if (m.role !== 'user') this.ui.assistant(m.content);
+      else if (this.ui.userMessage) this.ui.userMessage(m.content);
+      else this.ui.write(`${blue('›')} ${dim(m.content.split('\n')[0])}`);
     }
     if (tail.length) this.ui.write(dim('  ── picking up here ──\n'));
   }

package/src/ui/screen.js

@@ -240,6 +240,34 @@ export class Screen {
     this.render();
   }
 
+  /**
+   * Something the user said, in the conversation, in the same blue box as the
+   * input it was typed into.
+   *
+   * A long session is mostly the agent's output — tool calls, diffs, answers.
+   * Your own messages are the landmarks you scroll back looking for, so they
+   * get the frame: every one of them is findable at a glance, and the box
+   * matches the one below so it is plain where each came from.
+   */
+  userMessage(text) {
+    const width = this.width();
+    const room = Math.max(8, width - 6);   // borders, padding, and the caret column
+
+    const rows = [];
+    for (const paragraph of String(text).replace(/\r/g, '').split('\n')) {
+      for (const line of wrapAnsi(paragraph, room)) rows.push(line);
+    }
+
+    this.add('');
+    this.add(boxTop(width, edge));
+    rows.forEach((row, i) => {
+      const lead = i === 0 ? blue('›') : ' ';
+      this.add(boxRow(` ${lead} ${chalk.white(row)}`, width, edge));
+    });
+    this.add(boxBottom(width, edge));
+    this.render();
+  }
+
   /**
    * A tool call, as it happens: "● Listing src".
    *
@@ -894,10 +922,9 @@ export class Screen {
         this.historyIndex = -1;
         if (text.trim()) {
           this.history.unshift(text);
-          // Echo it so the transcript reads as a conversation rather than as
-          // a series of unprompted answers.
-          this.push('');
-          this.push(`${blue('›')} ${chalk.white(text)}`);
+          // Answers to a y/N or a numbered pick are not messages, so they are
+          // not echoed: the prompt reports its own outcome.
+          if (!this.pendingPrompt) this.userMessage(text);
         }
         this.render();
         this.submit(text);