jig-ui 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,208 @@
 # Changelog
 
+## 0.25.0 (2026-10-09)
+
+Link previews, code and tables that reflow on an `editorial` phone, and the
+gate's rules stated before a session stops.
+
+### Added
+
+- **The render probe measures a box that scrolls sideways.** `editorial`
+  allows no scrolling region on a phone (`M-01`), and the probe only measured
+  a page wider than the screen. In a control run on this release's reflow
+  text, a spec said the code would wrap and the built page scrolled it in a
+  box, and nothing caught it. The probe now records each box that scrolls
+  sideways, and on an `editorial` surface at phone width each is a measured
+  failure: a critique reports it, `ship` counts it, and the gate holds make and
+  tweak until the page reflows.
+- **J-164: an indexable page a link preview cannot read.** A page pasted into a
+  message or a post is met as a card before anyone opens it, and the card is
+  built from `og:title` and `og:description`. Section J said it covered the link
+  preview, and no rule asked for one, so `seo` and `check` passed a site with no
+  preview on any page. `check` reports it in a file that writes its own
+  `<head>`, and in a head fragment (`<svelte:head>`, Astro, `next/head`) that
+  writes the page's own description and no `og:description`, which no layout
+  can supply; elsewhere a layout may write it, and the render decides: the probe
+  now reads `og:description`, and a served page missing either tag is a
+  finding on the page. An image and `og:url` need the page's full address, so
+  the rule asks for them once a site has one. 160 rules, 40 of them decided by
+  a machine.
+
+### Changed
+
+- **`editorial` on a phone says what replaces a scrolling box.** `L-01` sent a
+  wide code block or table to scroll inside itself, and the same sentence said
+  `editorial` allows no scrolling region on mobile, naming nothing in its
+  place. `L-01`, `D-115` and `M-01` now say it: a code block keeps its line
+  breaks and indents and wraps its long lines, a table too wide for the screen
+  stacks its rows with each cell's column name in front and stays a `<table>`,
+  and a long identifier breaks where it must.
+- **`E-51`'s near-universal glyphs are a test, not a list.** Close, search and
+  menu were read as the only icon-only controls allowed. The rule now asks
+  whether most readers would name the glyph the same way without its label,
+  with examples that pass (a theme's sun and moon, a well-known service's mark)
+  and that do not.
+- **`E-28` says what a browser's own tab stop on an `<iframe>` gets.** One that
+  only shows something is taken out of the tab order rather than given states;
+  one the reader uses keeps its stop and shows focus.
+- **spec, mockup and tweak each end with what the gate holds them to.** A short
+  "Before you stop" list names the checks the Stop hook makes on what that
+  command records, beyond the shape its steps already teach: where it may write, whose words a quotation is, the check record's
+  format, what counts as the owner's confirmation or approval, and what
+  `tweak.json` holds. Sessions learned these from refusals, and each refusal
+  cost a round of fixing, re-checking and committing. A test pairs each check
+  with its line in the list, so a check added without one fails.
+- **`jig check` exits non-zero on a mechanical error, with or without `--ci`.**
+  It used to exit 0 whatever it found, so a pre-commit hook, a CI step or a
+  script running it as a linter read a run full of errors as a pass. Judgment
+  findings are still reported without failing the run. `--ci` now only limits
+  the run to the mechanical rules.
+
+### Fixed
+
+- **The skill and `spec` say `L-01` has six steps, and `spec` names the sixth.**
+  `L-01` gained step 6, how a screen collapses, and both kept telling the agent
+  to run "its five steps", so it stopped before the one that gives the phone
+  composition. In a control run on this release's reflow text, a spec chose a
+  sideways-scrolling code block for an `editorial` phone. A test now ties the
+  count to `L-01`'s own step headings.
+- **`I-118` exempts quoted output in the rule and in `check`, as the probe
+  already did.** The rule exempted a quotation in `<blockquote>` or `<q>`; the
+  render probe also leaves `<pre>`, `<code>`, `<samp>` and `<kbd>` alone, and
+  `check` exempted none of them. A page quoting a tool's real output was told
+  by `check` to rewrite it, and by the rule to keep the quotation's own
+  punctuation. All three now agree.
+- **A critique is no longer held on what the page fails.** An em dash on the
+  rendered page, a missing or overlong title or description, unresolved tokens
+  or the browser's default font are failures of the page, not of the review.
+  `verdicts` reported them as a critique left incomplete, so the gate held the
+  critique session until they were gone, and the session could clear them only
+  by editing the page, which a critique never does. They are now listed apart,
+  under `!`, as `measured=` on the `JIG_VERDICTS` line, and once each rather than
+  at every width. A critique reports them and finishes; `ship` counts them as
+  findings, and the gate holds make and tweak until the page is fixed. A verdict
+  the probe contradicts still means the review re-runs.
+- **A quoted `mockup:` value reads as the value it holds.** A spec that wrote
+  `mockup: "skipped — the owner: \"…\""`, valid YAML, read to the gate as the
+  word `"skipped`, so every tweak of the page was refused for having no approved
+  drawing, and the check that the owner's words are quoted was silently skipped.
+- **An em dash inside tool output no longer counts as the page's own.** The
+  probe leaves quotations and `<pre>`, `<code>`, `<samp>` and `<kbd>` out of the
+  dash scan, but it cut them out of the page's text one string at a time. An
+  inline `<code>` earlier in the prose, such as a rule id, removed those
+  characters from the output block below it, the block no longer matched, and
+  its dash was reported. Quotations are now left out of the text as it is read.
+- **The README no longer says every command is also a slash command.** `gate`
+  has no slash form (only the Stop hook runs it), and six slash commands are
+  agent procedures with no command of their own in the CLI. The table under it
+  was right; the sentence above it now says what the table does.
+- **`check` no longer says it examined nothing while reporting findings.** A
+  file styled only with utility classes, such as `class="p-[13px]"`, is read by
+  H-47 but was left out of the styled-file count. A change to such a file
+  reported H-47 errors and, below them, that no file carried a style region. The
+  count now includes markup whose class attributes hold classes.
+
+## 0.24.0 (2026-09-30)
+
+The owner's word held to one rule, Jig's instructions in your project's AGENTS.md,
+and Jig tested on Linux, macOS and Windows.
+
+### Added
+
+- **`jig checksum <spec>`** prints a spec's checksum, the value its
+  `.checked.json` records. It had been left to agents to compute from the
+  procedure's description, and a hand-computed value was easily wrong.
+- **`route:` is a spec field**, for a page whose surface name does not say where
+  it is served.
+- **Your project's `AGENTS.md` carries Jig's instructions for your agent.**
+  `init`, `install` and `update` create the file if it is missing, or add Jig's
+  block to the one you have: load the skill before UI work, how the loop runs,
+  the owner's-word rule, and what each of Jig's files is for. With Claude Code,
+  a block in `CLAUDE.md` imports it, so every session loads it. Jig owns only
+  what is between its markers. `check` reports the block missing or edited,
+  `ship` is not ready without it, the Stop hook holds a session that removed it,
+  and `jig update` puts it back.
+
+### Changed
+
+- **The owner's word is held to one rule, everywhere Jig records it.** A spec
+  confirmed, a drawing approved or skipped, a re-judge left for later, a tweak's
+  change and a decision's reason are each the owner's own words, and words that
+  say that thing: a remark about the layout is not a skip of the mockup, and a
+  yes to one question is not a yes to the spec. One check now covers all of
+  them. Three had no check before: `confirmed: true` needs the owner's yes to
+  being asked, a tweak's `change` must be words they said, and `decide`'s quoted
+  reasons must be too. The skill states the rule.
+- **A field Jig does not read is refused where it would be written.** When the
+  procedure named no place for something, agents invented one: front-matter
+  keys, verdict ids, JSON fields that nothing reads, so what they said reached
+  no check. A spec key a session adds, a verdict-file field holding a list or an
+  object, and an unknown tweak.json field are now refused, each pointing at the
+  place that exists. Keys a spec already had are not held against it.
+- **A spec is drafted where Jig reads it, and checked as itself.** It is written
+  at `.jig/specs/<name>.spec.md` from the first draft, and its shape is checked
+  before the owner is asked to confirm it. Asking to confirm a spec that is not
+  there is refused, and so is finishing a spec session without writing it. A
+  named spec is never checked in place of another page's.
+- **A critique files one problem once.** A difference goes under `differences`
+  only when no rule or decision already holds it, so the counts `ship` reports
+  count problems, not entries.
+- **The gate asks for the probe files it re-takes to be committed.** It renders
+  a changed page again as a session stops, after the last commit; like the
+  lock, it now stops once to have those files committed on their own.
+- **`jig gate` run by hand reports and renders nothing.** Without a transcript
+  it cannot tell which pages are in play, and it had re-rendered every one.
+- **`motion: none` can say why**, as in `none — this page adds no movement`.
+- **A file a session never wrote is taken as it found it**, committed or not,
+  so a session is not answerable for a draft it found.
+
+### Fixed
+
+- **Jig works the same on Linux, macOS and Windows, and is tested on all three.**
+  Every change now runs the full suite on each, on Node 22 and 24. The first run
+  found that rendering a page needed a WebSocket Node 20 does not have, so Jig
+  now needs Node 22 or later (Node 20 is end-of-life) and says so if it is run
+  on an older one; and that on Windows no browser was ever found to render with:
+  Edge, Chrome installed per user, and commands on PATH are now found.
+- **A project checked out on Windows reads the same as anywhere else.** Git on
+  Windows gives files CRLF line endings. Jig parsed a spec with them as having
+  no regions at all, a spec's check no longer matched it, and every comparison
+  with a file's committed copy read as a change. Every text file Jig parses or
+  compares is now read with its line endings normalised.
+- **Two Jig runs at once no longer fail on Windows.** Windows refuses to replace
+  a file another process has open, where Linux and macOS allow it; writing a
+  file Jig records (the install manifest among them) now retries briefly there,
+  and the manifest's lock treats a lock file Windows is still deleting as held
+  for a moment, not as an error.
+
+- **The docs say what the code does.** The README said `check` reports a
+  pre-0.4.0 install's leftovers (only `init` does); the procedure named five
+  reasons `ship` owes a page (there are six, one a re-probe) and described the
+  spec checksum as leaving out one line where the code leaves out two. Tests
+  now fail when the procedure stops naming a state `ship` reports, a line the
+  checksum leaves out, or a command the CLI registers.
+- **The README no longer counts the rules `check` decides by hand.** It named
+  "the seven mechanical rules" from 0.1.0; it now points at `rules.index.json`.
+- **An `exempt` path works the way you write it.** `./src/card.tsx`,
+  `src\\card.tsx` and an absolute path inside the project all mean
+  `src/card.tsx`. A path outside the project was dropped without a word; it is
+  now named in the report with what to write instead, and a bare file name that
+  matches nothing is answered with where that file is.
+- **A fact's `source` that holds a sentence** is told to put it in `note`.
+- **The README says what Jig does.** It said `init` was the only command that
+  writes into your repo and that nothing of Jig's is kept in it (a project-scope
+  install writes the skill and rules into your repo's agent folder); pointed
+  agents at `AGENTS.md`, which users do not receive; counted 95 rules the CLI
+  cannot decide (it is 120), two critique readers (three) and four per-page
+  commands; described `check --ci` as errors only; said the token layer changes
+  nothing on the page, beside a `color-scheme` line that does; and claimed Jig
+  knows every page that changed, which it does not for a page rendered on
+  request. Its `exempt` example named one project's files as if they were a
+  pattern; it now explains how to choose your own: a file that renders outside
+  your stylesheets, or a page you will not revisit, since `check --all` and
+  `ship` read every file. The slash-command table
+  lists `verdicts`, `probe` and `checksum`.
+
 ## 0.23.0 (2026-09-29)
 
 Rules for the prose a page ships and for how it moves, a spec that says what

package/README.md

@@ -2,23 +2,38 @@
 
 A design system written to be consumed by coding agents, not read by designers.
 
-Framework-agnostic. Tokens are CSS custom properties; rules are stated in CSS
-properties and behaviour, never in one framework's class names.
-
-Installed as `npx jig-ui` — the bare name was taken on npm.
+**Jig is framework-agnostic.** It works with what you already build with:
+
+- **Any framework.** React and Next.js, Vue and Nuxt, Svelte and SvelteKit,
+  Astro, Angular, Solid, Rails, Laravel, Django, Phoenix, ASP.NET, or plain
+  HTML. `check` reads each one's files as they are (see
+  [What `check` covers](#what-check-covers)).
+- **Any way you style.** Plain CSS, SCSS or Less, CSS modules, Tailwind, or
+  CSS-in-JS.
+- **Any content.** Pages built ahead of time or rendered from a backend.
+- **Any coding agent.** Claude Code, Codex, Cursor, opencode, Gemini CLI, or any
+  other that reads a skill file.
+- **Any operating system.** macOS, Linux and Windows.
+
+Nothing in it belongs to one framework: the tokens are CSS custom properties,
+and every rule is stated in CSS properties and behaviour, never in one
+framework's class names.
+
+Installed as `npx jig-ui` — the bare name was taken on npm. It needs Node 22 or
+later.
 
 ## Two ways to use it
 
 Jig is **a skill your coding agent reads**, and **a CLI you can run yourself**.
 They are two halves of the same thing, and the split is not arbitrary:
 
-- Of the 159 rules, **39 can be decided by a machine** — a hard-coded colour, a
+- Of the 160 rules, **40 can be decided by a machine** — a hard-coded colour, a
   contrast ratio below the floor, a removed focus ring. The CLI decides those.
 - The other **120 are judgment** — whether an empty state says anything useful,
   whether a label reads as an instruction, whether motion earns its place. No
   regex settles those. An agent reads the rules and applies them.
 
-Running only the CLI gets you the 39. Running only the agent gets you the 120 with
+Running only the CLI gets you the 40. Running only the agent gets you the 120 with
 no verification. **A clean `jig check` is not a clean review**, and the skill
 says so to every agent that reads it.
 
@@ -85,24 +100,43 @@ but never adds one.
 
 Every agent reads a `skills/jig/SKILL.md`, so adding a new harness is a config
 change rather than a new code path. Codex uses the cross-agent `.agents/`
-directory and additionally gets a short pointer block in `AGENTS.md` — that file
-is read into every session, so it names the skill rather than restating it.
+directory.
 
-Install writes the skill file **and its rules** to one place only — beside the
-skill file itself. Nothing of Jig's is vendored into your repo; your agent reads
-the rules from the install. Installing at project scope when the same agent is
+Install writes the skill file **and its rules** to one place only, beside the
+skill file itself: in your repo's agent folder at project scope (the default),
+in your home directory with `--scope global`. Your agent reads the rules from
+there; nothing is copied into your source. At project scope it also keeps a
+block in `AGENTS.md` (below). Installing at project scope when the same agent is
 already installed globally warns rather than creating a second, contradicting
 skill.
 
+### Your agent's instructions: `AGENTS.md` and `CLAUDE.md`
+
+Most people run Jig through an agent, and `AGENTS.md` is the file agents read at
+the start of every session. So Jig makes sure your project has one: `init`,
+`install` and `update` create it if it is missing, or add Jig's block to the one
+you have. The block is short: load the Jig skill before any UI work, how the
+loop runs, the owner's-word rule, and what each of Jig's files is for.
+
+With Claude Code, which reads `CLAUDE.md` instead, Jig also adds a block there
+that imports `AGENTS.md` (`@AGENTS.md`), so every session loads it without the
+agent having to choose to.
+
+Jig owns only what sits between its markers, `<!-- jig:start -->` and
+`<!-- jig:end -->`. Write your own instructions above or below the block; Jig
+never reads or changes them. If the block goes missing or is edited, `check`
+says so, `ship` is not ready until it is back, a session that removed it is held
+by the Stop hook, and `jig update` puts it back.
+
 ## Set the project up
 
 ```bash
 npx jig-ui@latest init
 ```
 
-`init` is the only command that writes into your repo. It runs on a project
-with nothing in it and on one with years of CSS, and behaves differently in
-each — because the useful thing to do differs.
+`init` sets the project up: the token layer, `jig.config.json`, one import in
+your stylesheet, and Jig's block in `AGENTS.md` for your agent. It runs on a project with nothing in it and on one with years of
+CSS, and behaves differently in each, because the useful thing to do differs.
 
 ### An existing site
 
@@ -157,15 +191,17 @@ set of cards with no list element — rather than a wall.
 #### When you do run `init`
 
 The token layer is a set of custom property declarations. Declarations nothing
-references change no pixel, so adding it does not restyle your site.
+references change no pixel, so adding it does not restyle anything you have
+styled. One line is the exception, below.
 
 - **Different names never collide.** Your tokens and Jig's sit side by side; each
   is used by whoever asks for it. You can adopt one token at a time, or none.
 - **If a name is the same in both, yours wins.** The import goes above your own
   rules, and the later declaration is the one that applies.
 - **One line does more than declare a token:** `color-scheme: light dark`, which
-  tells the browser your page supports both, so scrollbars and form controls
-  follow the reader's system setting.
+  tells the browser your page supports both. On a reader's dark system,
+  scrollbars, form controls and any background you have not set yourself turn
+  dark. If your site is light only, remove that line from the brand file.
 
 #### You decide how it is wired
 
@@ -233,8 +269,9 @@ are a list. That is the whole loop. Repeat it wherever it is worth repeating.
 The first `check --all` on a big repo is a long list, and the list is not a
 to-do. Read it in this order:
 
-1. **`check --all --ci` first.** Mechanical bucket, errors only, exit code you
-   can put in CI. It is the short list, and every line on it is decidable.
+1. **`check --all --ci` first.** The rules a machine decides, and nothing else,
+   with an exit code you can put in CI: it fails on any error. It is the short
+   list, and every line on it is decidable.
 2. **Then warnings, by rule rather than by file.** The report groups by rule id,
    and a rule firing forty times is one decision made once, not forty.
 3. **Then one page at a time.** `check` defaults to the files you changed, so
@@ -329,9 +366,6 @@ coherent monochrome UI and makes the missing decision visible instead of
 inventing a purple (`A-01`). Set `--brand-h/-s/-l` in the brand file when you
 have decided, or tell your agent to ask you.
 
-Add `--yes` to accept every derived default non-interactively — the mode CI and
-agents run in.
-
 ### Where the token layer goes
 
 Beside the stylesheet it wires, so it sits with the rest of your CSS rather than
@@ -370,11 +404,12 @@ overwrites a config or brand file you have edited.
 
 | Command | What it does |
 | --- | --- |
-| `install --agent <name> [--scope project\|global] [--hook]` | Puts the skill and its rules where your agent will find them. Writes nothing else into your repo, unless you ask for `--hook`. |
-| `init [--yes]` | Sets the project up: CSS system, brand colour, token files, `jig.config.json`, wired imports, baseline check. The only command that writes into your repo. |
-| `check [--all] [--ci] [--json]` | Runs the rules a machine can decide. Reports findings by rule id. |
+| `install --agent <name> [--scope project\|global] [--hook]` | Puts the skill and its rules where your agent will find them. At project scope, also keeps Jig's block in `AGENTS.md` (and `CLAUDE.md` for Claude Code); with `--hook`, adds the Stop hook. |
+| `init [--yes]` | Sets the project up: CSS system, brand colour, token files, `jig.config.json`, wired imports, baseline check. |
+| `check [--all] [--ci] [--json]` | Runs the rules a machine can decide. Reports findings by rule id, and exits non-zero on any mechanical error. |
 | `update` | Refreshes an install to a newer version, leaving alone any file you have edited. |
 | `seo [--json]` | Audits what a search engine and a link preview read, across the whole project: a route whose metadata says `noindex` sitting in the sitemap, two pages claiming one title, a sitemap that lists nothing or lists paths a crawler drops. Whether a sitemap and a robots file exist is counted, not reported: no rule asks for either, and a site with no domain yet cannot write an honest sitemap. Needs no config, no decisions and no spec. |
+| `checksum <spec>` | Prints a spec's checksum, the value its `.checked.json` records as `spec`, so the spec's reader never computes it by hand. |
 | `verdicts <surface>` | Verifies a critique's verdict files and computes its counts: every rule in each pass judged once, no id that does not exist, no rule in the wrong arm, and no verdict the render probe contradicts. |
 | `probe` | Prints the render probe — one expression the critique runs in a browser at each width. It operates the menu, measures sideways scroll, and reads whether the styles and tokens applied. |
 | `ship` | Says whether the project is ready to ship, by everything Jig checks: `check --all --ci` and `seo` with no errors, and every confirmed page critiqued as it stands, with no finding you have not ruled on. Exits non-zero until it is, and names what Jig does not check. |
@@ -387,7 +422,7 @@ Flags worth knowing:
 | --- | --- |
 | `check --all` | Scan the whole repo instead of just changed files. Use on a first run. |
 | `explain --list` | Every rule id and title. Add a section letter (`explain G --list`) for one section. |
-| `check --ci` | Mechanical bucket only — deterministic, and exits non-zero on any error. |
+| `check --ci` | Mechanical bucket only, so the run is deterministic. |
 | `check --json` | Machine-readable findings, for tooling or for reading every finding when the terminal output elides repeats. |
 | `init --yes` | Non-interactive; accept every derived default. |
 | `install --scope global` | Install once for every project. |
@@ -400,9 +435,12 @@ mean it could never move.
 
 ### As slash commands
 
-Every command is also a slash command in your agent, installed alongside the
-skill. `/jig check --all` does what `npx jig-ui check --all` does, and then acts
-on the result — the CLI reports, the agent applies the judgment half.
+Every command but `gate`, which only the Stop hook runs, is also a slash command
+in your agent, installed alongside the skill. `/jig check --all` does what
+`npx jig-ui check --all` does, and then acts on the result — the CLI reports, the
+agent applies the judgment half. Six slash commands are agent procedures with no
+command of their own in the CLI: `decide`, `spec`, `mockup`, `make`, `critique` and
+`tweak` (`critique` runs `verdicts` and `probe` along the way).
 
 | Slash command | Equivalent |
 | --- | --- |
@@ -417,12 +455,17 @@ on the result — the CLI reports, the agent applies the judgment half.
 | `/jig spec invoice page` | No CLI. What exactly is being built — a page, feature or functionality — at its smallest useful version, at every screen size |
 | `/jig mockup` | No CLI. Low-fidelity design of that spec, reviewed before code — in HTML, Figma or Google Stitch, whichever you choose |
 | `/jig make` | No CLI. High-fidelity: builds the actual page or feature from the spec and mockup |
-| `/jig critique` | `jig verdicts` + `jig probe`. Scrutinises what was built against the rules, its spec and its mockup: two reader arms write their verdicts to files, the CLI decides whether the review is complete, and a browser probe checks the verdicts against what the page actually does |
+| `/jig critique` | `jig verdicts` + `jig probe`. Scrutinises what was built against the rules, its spec and its mockup: three readers that cannot see each other (one looks at the rendered page, one reads the source, one holds it to your decisions) write their verdicts to files, the CLI decides whether the review is complete, and a browser probe checks the verdicts against what the page actually does |
 | `/jig tweak` | No CLI. A small change to a built page that its approved mockup does not show: decided if it is a decision, specced, built, and re-judged where it could matter |
 | `/jig ship` | `jig ship` — then critiques every page that owes one, puts the findings to you, and runs again until the project is ready |
+| `/jig verdicts <page>` | `jig verdicts <page>` — reports whether a critique is complete, unchanged |
+| `/jig probe` | `jig probe` — the render probe a critique runs in a browser |
+| `/jig checksum <spec>` | `jig checksum <spec>` — the value a spec's check records |
 
-`decide` runs once. The other four run for each page, feature or functionality, one
-at a time — never the whole product at once.
+`decide` runs once. `spec`, `mockup` (or skipping it), `make` and `critique` run for
+each page, feature or functionality, one at a time, never the whole product at
+once; `tweak` handles a small change to a built page, and `ship` checks the whole
+project before you release.
 
 Where each lands:
 
@@ -579,7 +622,10 @@ critiquing any page whenever you like, and `ship` judges every one.
 
 Waiting is tracked, not forgotten. The verdict lock records the page each
 critique judged, so Jig knows every page that changed since, every tweak that
-left its re-judge for later, and every page never judged. `/jig ship` is where
+left its re-judge for later, and every page never judged. It knows a page by its
+built file: a page rendered only on request is not tracked this way yet, and a
+built page whose content comes from a backend reads as changed when that content
+does. `/jig ship` is where
 none of it is optional: `jig ship` runs `check --all --ci` and `seo`, and names
 each page that owes a critique; the agent critiques each one in full, with
 readers that have not seen the conversation, and puts the findings to you. Each
@@ -599,7 +645,8 @@ metadata in the same change as the headline, and `check` holds the budgets.
 
 **Which pages are meant to be found is decided by mode, not by taste.**
 `editorial` is first-visit content, so it is indexable and needs its own title
-and description. `product` and `operator` are what somebody reaches after signing
+and description, and its own link preview (`og:title` and `og:description`) for
+the card a pasted link shows. `product` and `operator` are what somebody reaches after signing
 in, so they must carry `noindex` — an admin screen in a search result is an
 invitation, and a sign-in page in one invites credential stuffing. A spec
 overrides the default per page, with a reason: a CV shared by link, a
@@ -654,7 +701,7 @@ No agent required. `check` is a linter with a design system behind it.
 ```bash
 npx jig-ui@latest check --all      # everything
 npx jig-ui@latest check            # just what changed
-npx jig-ui@latest check --ci       # for CI: deterministic, non-zero on error
+npx jig-ui@latest check --ci       # for CI: mechanical rules only, deterministic
 npx jig-ui@latest check --json     # for tooling
 ```
 
@@ -668,8 +715,8 @@ In CI:
 code — nothing model-dependent, no network. As a pre-commit hook, plain `check`
 looks at changed files only.
 
-What you will not get from the CLI alone is the other 95 rules. `check` says so
-rather than letting a narrow pass read as a broad one.
+What you will not get from the CLI alone is the 120 judgment rules. `check` says
+so rather than letting a narrow pass read as a broad one.
 
 ## What `check` covers
 
@@ -690,10 +737,11 @@ character positions preserved, so a finding's line points at the real line in
 your `.vue` or `.tsx` file. Application code outside a style region is never read
 as CSS.
 
-The seven mechanical rules: hard-coded values past the token layer (`H-47`),
-contrast below the floor (`C-19`), removed focus rings (`E-29`), gradient text
-(`A-02`), backdrop blur (`A-04`), pure black and white (`C-18`), and the
-violet-band hue check (`A-01`, which asks rather than fails).
+Which rules it decides: every rule in `rules.index.json` that names a
+`detector`, among them hard-coded values past the token layer (`H-47`), contrast
+below the floor (`C-19`) and removed focus rings (`E-29`). A `hybrid` one warns
+and asks rather than fails (the violet-band hue check, `A-01`). `jig explain
+<id>` prints any rule with who checks it.
 
 **It also reads the token layer itself.** The token layer is not application
 code, so no detector scans it — but it is where a mistake costs most, since every
@@ -736,10 +784,10 @@ npx jig-ui@latest update
 ```
 
 Files you have edited are left alone. Upgrading from a pre-0.4.0 install that
-vendored rules into your project's `.jig/`? `init` and `check` detect the
-leftover files, report them, and — with your consent, and never for a file you
-have edited — offer to remove just the install artifacts, keeping your tokens
-and config untouched.
+vendored rules into your project's `.jig/`? `init` detects the leftover files,
+reports them, and — with your consent, and never for a file you have edited —
+offers to remove just the install artifacts, keeping your tokens and config
+untouched. (`update`, finding no install, names them and points you to `init`.)
 
 Cursor's skill moved from `.cursor/rules/jig.mdc` to
 `.cursor/skills/jig/SKILL.md`; `init` finds the old file and offers the same
@@ -749,7 +797,7 @@ treatment.
 
 | File | Contents |
 | --- | --- |
-| `rules/00-anti-patterns.md` | 128 universal rules with corrections |
+| `rules/00-anti-patterns.md` | 129 universal rules with corrections |
 | `rules/01-modes.md` | `editorial` / `product` / `operator` profiles |
 | `rules/02-tokens.md` | Token contract, naming, consumption |
 | `rules/03-patterns.md` | Component anatomy and behaviour |
@@ -760,12 +808,15 @@ treatment.
 | `<css dir>/jig/mode.*.css` | Density, scale, rhythm, motion |
 | `<css dir>/jig/theme.css` | The barrel — brand + mode. This is what you import. With more than one mode, `theme.<mode>.css`, one per mode, each imported by its routes' layout. |
 | `.jig/state.json` | What `init` wrote, with checksums. `update` reads it to leave your edits alone. |
+| `AGENTS.md`, `CLAUDE.md` | Your agent's instructions. Jig keeps one marked block in each (`CLAUDE.md` only with Claude Code); the rest is yours. |
 | `.jig/specs/`, `.jig/mockups/`, `.jig/critique/` | The design loop's record: what was agreed, what was drawn, what the review found. |
 
-`rules/*` and `rules.index.json` live beside your installed skill file, not
-in the project — see above.
+`rules/*` and `rules.index.json` live beside your installed skill file: in
+your repo's agent folder at project scope, in your home directory at global
+scope. See Install, above.
 
-Which of these an agent loads, and when, is `AGENTS.md`.
+Which of these an agent loads, and when, is the skill file's to say: `SKILL.md`,
+beside the rules.
 
 ## Per-project declaration
 
@@ -787,20 +838,19 @@ Drop this in the project root so mode selection does not require asking on every
     { "match": "/admin/**", "mode": "operator"  }
   ],
 
-  // Files that render OUTSIDE the cascade, where a literal is the only thing
-  // that works: an OG card serialised into an SVG `foreignObject` carries no
-  // stylesheet, and a PDF drawn by a React renderer never sees CSS.
-  //
-  // Prefer an exact path. An exemption is a claim about ONE file's rendering
-  // context, and that is usually literally true of one file. Reach for a glob
-  // only where the directory exists to hold them — `src/cv/pdf/**` is a fact
-  // about that tree; `**/*-card.tsx` is a naming coincidence that would also
-  // excuse every real card component you have.
+  // Files `check` should skip. Empty unless you add to it; Jig never does.
+  // Add:
+  //   - a file that renders outside your stylesheets (a generated social
+  //     card, a PDF or email template), where literal values are the only
+  //     thing that works;
+  //   - an old page you will not revisit. Plain `check` reads only the files
+  //     you change, but `check --all` and `ship` read every file.
   //
-  // `check` names the pattern and its match count on every run, and says so
-  // when one is excusing enough files to look like a mistake. Nothing is ever
-  // exempt by default: this list is the only source.
-  "exempt": ["src/components/og-card.tsx", "src/cv/pdf/**"],
+  // Write each path from the project folder (where this file is), the way
+  // your editor shows it: "src/social-card.tsx". A whole folder:
+  // "src/emails/**". `check` lists every entry and how many files it
+  // matched on every run, and tells you when one matches nothing.
+  "exempt": ["src/social-card.tsx", "src/emails/**"],
 
   // When pages are critiqued. Leave it out to decide each time; "at-ship"
   // says once that critiques and a tweak's re-judge wait for `/jig ship`,