jig-ui 0.16.0 → 0.17.0

package/examples/README.md

@@ -0,0 +1,44 @@
+# Examples
+
+One file per rule, `<ID>.html`, showing what the rule forbids and what it asks for
+instead. A rule describes a failure in words; a reader recognises it by sight, and
+most of these failures are things people have seen a hundred times without a name
+for them. The example is the picture beside the name.
+
+## Shape
+
+```html
+<!-- A-58 · Decorative styling that implies meaning -->
+<figure data-example="dont">
+  …the failure, as small as it can be and still be recognised…
+</figure>
+<figure data-example="do">
+  …the same content, done the way the rule asks…
+</figure>
+```
+
+- **Exactly one `dont` and one `do`.** The `do` shows the same content, not a
+  different, easier one. A fix that changes the content proves nothing.
+- **Self-contained.** Styles are `style` attributes on the elements. No `<style>`,
+  `<script>`, `<link>`, event handler, or external URL. A consumer renders a figure
+  in a sandboxed frame or an inert box, and it has to look the same in both.
+- **Small.** A figure is drawn for a box about 320 by 180 pixels. It exaggerates
+  just enough to be recognised, and no more.
+- **Raw values are fine here.** An example has to show violet, a glow, a 44px
+  radius. It is a specimen of the failure, not a component, so the token rule
+  that governs a real page does not apply inside it.
+- **The `do` follows every rule**, not only its own. A fix that commits a
+  different failure teaches the second one.
+
+## Not for everything visible
+
+Some rules are about code, metadata or behaviour and have no look. Their example
+shows what a person meets because of it: the search result a missing description
+produces, the tab a link hands over, the field a password manager cannot fill.
+Where even that is impossible, the figure shows the code, set as code.
+
+## Checked
+
+`packages/cli/test/examples.test.ts` fails when a rule has no example, when a file
+has other than one `dont` and one `do`, or when a figure carries anything that
+would not render the same in a sandbox.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jig-ui",
-  "version": "0.16.0",
-  "description": "A design system for coding agents. 130 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
+  "version": "0.17.0",
+  "description": "A design system for coding agents. 143 numbered UI rules, brand x mode design tokens, and an installer for Claude Code, Codex, Cursor and opencode.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "rules",
+    "examples",
     "tokens",
     "templates",
     "references",

package/rules/00-anti-patterns.md

@@ -39,6 +39,7 @@ These are the strongest defaults in a model's training data and the fastest way
 ✅ Opaque `--color-bg-raised` with a `--color-stroke-weak` edge. Use translucency only over media, and only when legibility is verified against the worst frame.
 Both styles make sufficient contrast and clear hierarchy structurally difficult — neumorphism in particular defines every element with shadow alone, which fails at 3:1 almost by construction. Trend styles also age badly: the more of them a product carries, the more precisely it is dated. Minimal styling that foregrounds content lasts longer.
 Experiment freely — but not where it costs legibility or excludes people.
+**Everywhere is its own failure.** A frosted panel over a video is a layering decision; frosted cards, a frosted nav, frosted buttons and glowing glass borders on a flat page are decoration applied to everything, and they solve no layering problem at all.
 
 ### A-58 Decorative styling that implies meaning
 ❌ List items in assorted colours chosen for variety; a decorative icon beside a heading that looks pressable; a heading coloured and underlined though it is not a link
@@ -66,6 +67,7 @@ Where several already apply — a table's rows are aligned, alike, and close —
 ### A-06 The three-column feature grid reflex
 ❌ Icon-in-rounded-square + heading + two lines, three across, for any set of three things
 ✅ Let the content pick the layout. Three items of unequal weight are a list, not a grid.
+**The same reflex at any count.** Six or nine cards, each an icon, a title and a line, identical in size and shape, give every point the same weight whether it deserves it or not, and make the titles the only thing a reader can tell apart, so they skim all of them and remember none. When one point matters most, make it bigger, put it first, or give it the space the others do not get. Group related ones; drop the ones that are filler.
 
 ### A-07 Oversized radius everywhere
 ❌ One radius applied to cards, buttons, inputs and badges alike, regardless of element size
@@ -84,6 +86,61 @@ In `operator`, `--radius-surface` also selects `sm`, so cards, buttons and input
 ❌ Lorem ipsum, "Acme Inc", `https://example.com`, stock avatars left in
 ✅ Real content, or clearly marked `TODO:` that fails a build check. Placeholder text that survives to review costs a reviewer more than it saved you.
 
+### A-135 A kicker above every heading
+❌ A small uppercase, letter-spaced line over each section heading: "FEATURES" over "What you get", "HOW IT WORKS" over "Three steps to launch"
+✅ One heading that says it. If the kicker repeats the heading, delete it; if it adds something, work those words into the heading or the line under it.
+A kicker is one more line to read before the one that matters, and on every section it stops marking anything. It survives from print, where a section label helped a reader flip to a page. On a screen the heading is already the label.
+
+### A-136 An eyebrow chip over the headline
+❌ A rounded pill above the hero headline: "✦ Introducing v2", "New: AI-powered", with a border or tint that makes it look pressable
+✅ Put the news in the headline or the line under it. If the chip links somewhere, make it a link that reads as one.
+A pill is the shape of a control and of a filter, so people try to press it. When it does nothing, the page has taught them its shapes lie; when it does something, the most important action on the page is dressed as a label.
+
+### A-137 Cream and beige by reflex
+❌ A warm off-white page (`#f5f0e8`, `#faf7f2`), beige cards and a brown-grey text colour, chosen because the brief said "warm", "editorial" or nothing at all
+✅ The brand file's neutrals, or a decision recorded in `DECISIONS.md`. Cream is a fine answer to a question someone asked; it is a default when nobody did.
+Cream replaced violet (`A-01`) as the colour a model reaches for when asked to look tasteful. The failure is the same one: a palette nobody chose, which makes unrelated products look alike and dates every page that carries it.
+
+### A-138 An italic serif display headline
+❌ An oversized headline set in an italic serif, often with one word picked out: "Beautifully *crafted*", "Work, *reimagined*"
+✅ Type chosen for this product's voice (`DECISIONS.md`), set upright unless the italic means something. Emphasis comes from the words.
+It is the shortcut to an editorial look, and it has been taken so often that it now reads as the absence of a type decision rather than the presence of one.
+
+### A-139 A side-tab accent border
+❌ A thick coloured stripe down one side of an ordinary card, list item or panel
+✅ No stripe. Where the stripe would mean something, a status, a warning, the current item, say it with a label or an icon and text, and keep the stripe only as a second signal.
+A coloured edge on one side is the shape of an alert. Put on a card with nothing to announce, it makes the card look like a warning, and a page of them makes a real warning impossible to see.
+
+### A-140 A thick coloured border on a rounded element
+❌ A 2px or wider coloured outline around a card or button with a large radius
+✅ A hairline in `--color-stroke-weak`, or no border and a surface step. If the element must stand out, change its surface, not its outline.
+A heavy outline on a curve becomes the most visible shape in the element, and the eye traces it instead of reading what is inside.
+
+### A-141 Cards inside cards
+❌ A card holding a panel holding a card, each with its own border, padding and background
+✅ One container at most, and the groups inside it made with space, type and a divider (`A-67`).
+Every layer adds padding and an edge around the same content, and takes width from it. Three layers deep, the content has the least room on the page and the chrome has the most.
+
+### A-142 The soft rounded card
+❌ A 1px hairline and a wide soft shadow on the same card, a large radius, a pale tint: the card that holds every section of a generated page
+✅ Choose one edge: a hairline, or a surface step (`A-08`). Keep the radius to the element's size (`A-07`).
+An edge and a shadow both draw the same boundary, so the card has two outlines. Repeated down the page, the cards stop grouping anything and become the page's texture.
+
+### A-143 A decorative grid or stripe background
+❌ Faint grid lines, dot grids or repeating diagonal stripes filling the space behind content
+✅ A plain surface. Keep grids for what is measured or placed on them: a canvas, a map, a chart.
+A grid says "this is a workspace". Behind a paragraph it is noise at the one contrast level that makes text harder to read without being visible enough to mean anything.
+
+### A-144 Dark mode with glowing accents
+❌ Coloured glows on borders, buttons and headings of a dark page: `box-shadow: 0 0 24px #22d3ee`, neon outlines, a halo behind the hero
+✅ Dark mode from the token ramp (`C-21`, `C-66`), with the brand colour spent where it means something (`I-56`).
+Glow is contrast added without meaning. On a dark page everything that glows competes to be first, and the one element that needs attention looks like all the rest.
+
+### A-146 Numbered section labels
+❌ "01", "02", "03" in small type beside section headings that are not a sequence
+✅ Number only a real order: steps to follow, a ranking, a procedure. Anything else keeps its heading and no number.
+A number promises an order. A reader told there are three steps looks for what comes after the third, and a page that numbers its sections only because they are sections has promised something it does not deliver.
+
 ---
 
 ## B. Typography
@@ -503,6 +560,11 @@ Where people must *browse* to decide, split the list into two dependent fields
 iOS Safari zooms the whole page when a field whose text is below 16px takes focus, and it does not zoom back out when the field loses it. The reader is left with a form wider than the screen, scrolling sideways to find the next field (`D-115`).
 Setting `maximum-scale=1` on the viewport to stop it is not the fix. That disables pinch zoom for everyone, which is an accessibility failure in its own right.
 
+### F-147 Asking for more than the task needs
+❌ A sign-up that asks for a phone number, company size, job title and "how did you hear about us" before the person can try anything
+✅ Ask for what this step needs to work. Every other field is optional and says so, or it moves to the moment it becomes useful.
+Each field is a question someone has to answer and a reason to leave. The ones the product does not need yet are also the ones people fill with nonsense, so the data they were meant to collect is worse than none.
+
 ## G. Motion
 
 ### G-42 Entrance animation on everything
@@ -517,6 +579,11 @@ Setting `maximum-scale=1` on the viewport to stop it is not the fix. That disabl
 
 **A consequence worth stating: motion is never the sole signal, for the same reason colour is not (`C-20`).** Honouring the reduced-motion path removes the animation, so any state that was communicated by movement alone is communicated to that user by nothing at all. A field that only shakes on a bad password has no error state under reduced motion. Pair the motion with text, an icon, or a colour change that survives without it.
 
+### G-145 A pulsing status dot
+❌ A green dot that pulses or pings beside "All systems operational", "Live", "Online"
+✅ A still dot and the word. Motion is for a state that is changing now: a sync in progress, a recording under way.
+A pulse says "look here, something is happening". On a status that has not changed in a week it is a false alarm on a loop, and it trains people to ignore the one indicator whose job is to be noticed when it matters (`G-43` applies too: under reduced motion it must still read).
+
 ### G-44 Durations too long
 ❌ 500ms+ on UI feedback
 ✅ 100–200ms for state change, up to 300ms for larger transitions. If it can be perceived as waiting, it is too slow.

package/rules/01-modes.md

@@ -190,7 +190,7 @@ Attempting to vary these by mode is a category error:
 - **Accessibility floors.** Contrast, focus indication, target size, semantic markup. Identical in all three. `operator` being dense does not license a 24px tap target or a 3:1 body contrast.
 - **Brand identity.** Palette, typeface, logo, voice.
 - **State completeness.** Every mode renders loading, empty, error and disabled.
-- **The anti-pattern file.** All 112 rules in it apply everywhere.
+- **The anti-pattern file.** All 125 rules in it apply everywhere.
 
 ---
 

package/rules/03-patterns.md

@@ -479,7 +479,7 @@ Compose it for the phone first. Mobile navigation is a different control — not
 
 Not a component. The procedure for structuring any screen, before styling anything.
 
-### Step 1 — Group
+### Step 1: Group
 
 Four tools, weakest to strongest. Use the weakest that works (`A-67`):
 
@@ -492,7 +492,7 @@ Four tools, weakest to strongest. Use the weakest that works (`A-67`):
 
 Combine them and the container usually becomes unnecessary — a table's rows are already aligned, alike and close. Break continuity deliberately to mark the end of a group, or to interrupt a list with something that is not part of it.
 
-### Step 2 — Order by importance
+### Step 2: Order by importance
 
 Six variables carry hierarchy: **size**, **colour**, **contrast**, **spacing**, **position**, **depth**. The procedure:
 
@@ -504,11 +504,11 @@ Position does more than it looks: people best recall the **first and last** item
 
 Give elements *similar* prominence where they should be read as a pair — matching a label's weight to its icon's balances them instead of letting one shout.
 
-### Step 3 — Space from the inside out
+### Step 3: Space from the inside out
 
 Start at XS on the innermost rectangle and step up moving outward (`D-69`). Between two options, take the larger.
 
-### Step 4 — Align to a grid
+### Step 4: Align to a grid
 
 Main containers align to a 12-column grid; small elements *inside* them do not — those use the spacing options.
 
@@ -516,7 +516,7 @@ Main containers align to a 12-column grid; small elements *inside* them do not
 - **Gutters** fixed, narrower than columns, and kept empty. `--grid-gutter`.
 - **Margins** keep content off the screen edge, wider on large screens. `--grid-margin`.
 
-### Step 5 — The squint test
+### Step 5: The squint test
 
 Blur the design, zoom out, or step back. You should still be able to tell what the screen is for and which element matters most. If everything reads at one weight the hierarchy has failed; if elements smear together the white space is too tight.
 
@@ -524,7 +524,7 @@ Blur the design, zoom out, or step back. You should still be able to tell what t
 
 **When nothing can render it, use the analogue:** if all type were one size and one colour, would the layout still communicate its order? If the hierarchy depends entirely on type styling, it is too weak. The analogue is a fallback, not an equal — a reading of the source is not a look at the page.
 
-### Step 6 — Decide how it collapses
+### Step 6: Decide how it collapses
 
 A spec writes a composition per size. This step is what happens **between** them:
 the same content, arranged for less room. Six rules, and the first is the one

package/rules/04-principles.md

@@ -15,7 +15,7 @@ If you reach for Part 2 often, the rules in `00`–`03` are underspecified and t
 
 # Part 1 · Frames
 
-## R-01 · Frame 1 — Minimise usability risk
+## R-01 · Frame 1: Minimise usability risk
 
 **Ask: who could struggle with this, and why?**
 
@@ -35,7 +35,7 @@ The risk is rarely to the median user. It falls on people with reduced vision, l
 
 **Floor:** WCAG 2.1 level AA. Meeting AA is the starting point, not the achievement.
 
-## R-02 · Frame 2 — Every detail has a reason you can state
+## R-02 · Frame 2: Every detail has a reason you can state
 
 **Ask: why this way rather than another way?**
 
@@ -45,7 +45,7 @@ This is the test every rule in this system had to pass, and it is why the token
 
 **Use it like this:** when you make a call the rules do not cover, state the reason in one line. If you cannot, you are guessing — and a guess should be surfaced as a question, not shipped as a decision (Tiebreaker 5).
 
-## R-03 · Frame 3 — Minimise interaction cost
+## R-03 · Frame 3: Minimise interaction cost
 
 **Ask: what does this cost the user, counted?**
 
@@ -59,7 +59,7 @@ Three reliable reductions:
 
 **Use it like this:** count before and after, and state it. "3 clicks + 1 scroll → 2 clicks" is reviewable. "Improved the UX" is not. See `P-10`.
 
-## R-04 · Frame 4 — Minimise cognitive load
+## R-04 · Frame 4: Minimise cognitive load
 
 **Ask: how much thinking does this require that is not the user's actual task?**
 
@@ -73,7 +73,7 @@ Attention spent decoding the interface is unavailable for the work. Reliable red
 
 **Use it like this:** when something feels heavy but no rule is broken, the load is usually ungrouped information or an unnecessary decision. Split it or remove it. A long form becomes steps; a wide table becomes fewer default columns; six equal options become two recommended and four behind "more".
 
-## R-05 · Frame 5 — Optimise for the common path
+## R-05 · Frame 5: Optimise for the common path
 
 **Ask: what are most people here to do?**
 
@@ -91,31 +91,31 @@ Effort should follow it. Make the common task excellent before making the rare o
 
 Seven. Each resolves a specific conflict in a specific direction. A principle that does not tell you what to give up is decoration.
 
-## R-06 · Tiebreaker 1 — Prefer the loud failure
+## R-06 · Tiebreaker 1: Prefer the loud failure
 
 **Between silent failure and visible failure, choose visible.**
 
 A form that discards a submission and shows success is worse than one that errors. A page serving stale data without saying so is worse than a slow one. Silent failure is the most expensive class of defect, because the cost is paid by someone who never finds out.
 
-## R-07 · Tiebreaker 2 — Never destroy on suspicion
+## R-07 · Tiebreaker 2: Never destroy on suspicion
 
 **When the system suspects input is wrong, mark it and hold it. Do not discard it.**
 
 Spam scores, validation failures, duplicate detection — all heuristics, all wrong sometimes. Hold the item, record why, let a person decide. Applies equally to the user's typing: never clear a form, drop a draft, or overwrite without a copy.
 
-## R-08 · Tiebreaker 3 — Recoverable beats correct
+## R-08 · Tiebreaker 3: Recoverable beats correct
 
 **Between preventing a mistake and allowing it to be undone, choose undo.**
 
 Prevention charges every user friction on every interaction to guard against a rare error. Recovery costs nothing until the error happens. Exception: genuinely irreversible operations, which confirm — and in `operator`, confirm by typing.
 
-## R-09 · Tiebreaker 4 — Optimise for who is actually there
+## R-09 · Tiebreaker 4: Optimise for who is actually there
 
 **When density and legibility conflict, decide by the user's real conditions, not by preference.**
 
 A first-time visitor on mobile data in bright sun and an operator at a large display for eight hours need opposite things. Mode encodes this. When the mode is genuinely unclear, ask — do not average, because the average serves neither.
 
-## R-10 · Tiebreaker 5 — Restraint is the default
+## R-10 · Tiebreaker 5: Restraint is the default
 
 **When a decision has not been made, ship the plainer thing and surface the question.**
 
@@ -125,13 +125,13 @@ An invented accent, a decorative animation, a gradient filling an empty space
 
 **Ceiling: restraint applies to decoration, never to information.** Minimal is not the same as simple. A sparse interface that has dropped labels, selected states or visible actions is harder to use than a busier one that keeps them — it just photographs better. Strip styling freely; never strip the answers to *what is this*, *which one is selected*, and *what can I do next* (`E-63`).
 
-## R-11 · Tiebreaker 6 — The platform before the framework
+## R-11 · Tiebreaker 6: The platform before the framework
 
 **When the browser can already do it, use the browser.**
 
 `<dialog>`, `<details>`, `position: sticky`, `:has()`, container queries, native form validation, `popover`. Platform features carry accessibility, keyboard handling and state management that a reimplementation gets wrong and then needs maintaining.
 
-## R-12 · Tiebreaker 7 — Match the codebase before matching this document
+## R-12 · Tiebreaker 7: Match the codebase before matching this document
 
 **When local convention conflicts with these rules, local convention wins.**
 

package/rules/05-copy.md

@@ -54,6 +54,7 @@ Someone who reads only the heading still gets the point. Someone who needs the d
 ✅ "Beautiful waterfront location", "Fast check-in experience", "Free secure parking"
 A heading must carry its own meaning. People scan headings and skip the supporting text, and screen reader users routinely pull up a list of every heading on a page to navigate — a list of one-word labels tells them nothing.
 Break long passages into groups with a descriptive heading each, rather than one unbroken block.
+**The same holds for a page's headline.** "Build the future of work", "Your all-in-one platform", "Where ideas come to life" could sit above any product, which means they say nothing about this one. A headline names what the product does and for whom: "Search your logs by asking in plain English". If it would still be true after swapping in a competitor's name, rewrite it.
 
 ### I-82 Uneven text length across parallel elements
 ❌ Three feature columns of two, four and three lines
@@ -89,6 +90,7 @@ Whichever you choose, be consistent across sibling elements — a list where thr
 Interface text is read in fragments, at a glance, in a space someone else's content has to fit too. An em dash is a pause the reader has to interpret: it stands in for a comma, a colon, a bracket or a full stop, and which one it is only becomes clear after reading past it. The punctuation that says exactly one thing is faster.
 It is also the clearest tell of machine-written copy. Generated text reaches for the em dash far more often than a person does, and readers have learned to notice. Copy that reads as generated is copy the reader trusts less, whatever it says.
 This is about interface strings: labels, buttons, headings, errors, empty states, help text, and the prose a page ships. Markdown counts where a framework renders it as a page, which is most of them (`src/content`, `content/`, MDX routes). A repository document does not: `README.md`, `CHANGELOG.md`, `AGENTS.md` and their kin are written for whoever works on the code, and so are your commit messages and this file.
+A verbatim quotation keeps its own punctuation. Text a page quotes from another source (a document, a spec, a person), marked as a quotation with `<blockquote>` or `<q>`, is that source's words, and changing them to satisfy this rule would misquote it. The page's own copy around the quotation, and any heading or label it gives it, is still held to the rule.
 The en dash keeps its one job: ranges, where it is read as "to" (`2–10 seats`, `Mon–Fri`). That is not a pause, and it is not affected.
 
 ### I-87 Inconsistent vocabulary
@@ -111,6 +113,7 @@ Users assume different words mean different things, because in a well-built inte
 Screen reader users pull up a list of every link on a page; a list of "learn more" is useless. Sighted users scanning have to read the surrounding text to work out where each one goes. Three identical links also imply one destination.
 "Click here" is worse still: it explains a mechanism people already understand, and it is wrong for anyone on touch, keyboard or voice.
 Often the cleanest fix is to drop the link and make the **heading** the link.
+**Buttons too.** "Get started", "Learn more", "Try it free" on every call to action say that something happens, not what. Name the outcome: "Create a workspace", "Search your first log file", "Book a 20-minute demo". A button whose label would fit any product is a button the reader has to decode.
 
 ### I-57 Actions and text centred by default
 ❌ Centred buttons and centred body text as a general habit

package/rules.index.json

@@ -912,5 +912,106 @@
     "severity": "note",
     "since": "0.14.0",
     "pass": "code"
+  },
+  {
+    "id": "A-135",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "heading-kicker",
+    "pass": "code"
+  },
+  {
+    "id": "A-136",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "eyebrow-chip",
+    "pass": "code"
+  },
+  {
+    "id": "A-137",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "cream-palette",
+    "pass": "code"
+  },
+  {
+    "id": "A-138",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "italic-serif-display",
+    "pass": "code"
+  },
+  {
+    "id": "A-139",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "side-tab-border",
+    "pass": "code"
+  },
+  {
+    "id": "A-140",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "rounded-accent-border",
+    "pass": "code"
+  },
+  {
+    "id": "A-141",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.17.0",
+    "pass": "screen"
+  },
+  {
+    "id": "A-142",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.17.0",
+    "pass": "screen"
+  },
+  {
+    "id": "A-143",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "decorative-grid-background",
+    "pass": "code"
+  },
+  {
+    "id": "A-144",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "glow-accent",
+    "pass": "code"
+  },
+  {
+    "id": "G-145",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "pulsing-dot",
+    "pass": "code"
+  },
+  {
+    "id": "A-146",
+    "bucket": "hybrid",
+    "severity": "warning",
+    "since": "0.17.0",
+    "detector": "numbered-section-labels",
+    "pass": "code"
+  },
+  {
+    "id": "F-147",
+    "bucket": "judgment",
+    "severity": "warning",
+    "since": "0.17.0",
+    "pass": "screen"
   }
 ]

package/templates/COMMAND.md.tmpl

@@ -965,9 +965,13 @@ every rule.
 probe in the browser and save what it returns beside the verdicts:
 
 ```
-# If a browser is on this machine, one command renders and records all three:
+# If a browser is on this machine, one command renders and records every width:
 {{scripts_path}} probe --run <page> --save <surface>
 
+# A built site that links its styles from the site root (/assets/site.css) must be
+# served, or nothing loads. Name the build directory and the CLI serves it:
+{{scripts_path}} probe --run dist/pricing/index.html --serve dist --save <surface>
+
 # Otherwise, at each width: open the page in whatever browser you have, evaluate
 # what `{{scripts_path}} probe` prints, and pipe exactly what it returned into:
 {{scripts_path}} probe --save <surface>
@@ -976,7 +980,8 @@ probe in the browser and save what it returns beside the verdicts:
 `--run` drives a headless Chrome, Chromium or Edge it finds for itself — a
 project with Playwright or Puppeteer already has one — and needs nothing
 installed. The Stop hook runs it too, before it judges a review, so a render is
-not a step anyone can forget.
+not a step anyone can forget. Do not copy the build and rewrite its links to make
+a file load: `--serve` shows the page a browser actually gets.
 
 **The CLI writes the probe file, you do not.** `--save` reads the probe's output,
 stamps it with the page's checksum, and stores it. That is what makes the file a
@@ -1182,7 +1187,9 @@ Not a command to run. In Claude Code, `install` adds a Stop hook that runs
 `check` error or warning, or a critique's verdict files fail `verdicts`, it refuses
 to let you stop and hands you the failures as the reason. **Fix what it names.** Do
 not edit verdict files to satisfy it, and do not report the work as done while it is
-blocking.
+blocking. It also refuses when a critique's verdict files changed after `critique`
+wrote them, in a session that did not run `critique`: a fix is judged by the next
+review, never by the builder editing the last one.
 
 A warning you are sure is right as it stands, because the detector guessed and the
 guess is wrong here, is waived on its own line or the line above, in the file's