jig-ui 0.12.0 → 0.14.0

package/templates/COMMAND.md.tmpl

@@ -6,7 +6,7 @@ these, say so, list them, and stop.
 
 There are two kinds of subcommand, and they are not run the same way.
 
-**CLI-backed** — `install`, `update`, `init`, `check`, `explain`, `verdicts`, `gate`, `probe`. Run the
+**CLI-backed** — `install`, `update`, `init`, `check`, `explain`, `verdicts`, `gate`, `probe`, `seo`. Run the
 matching command with `{{scripts_path}}`, passing the flags through unchanged,
 then do the work below for that subcommand. Read the command's full output —
 findings are ordered by severity, not position, so `head`, `tail`, `grep` and
@@ -218,6 +218,33 @@ Read `DECISIONS.md` before asking anything. Do not re-ask what it already record
 cite it instead. If the screen touches an item in its **Unresolved** section, ask the user
 about it by name; do not settle it in the spec.
 
+### 0. If the page already exists, describe it before you change anything
+
+An existing page is specified from what is there, not redesigned on the way past.
+Read the page and its stylesheet, render it at each size the spec will name, and
+write the frontmatter from what you find: the regions in their real order, the
+hierarchy as built, the navigation at each width. Then ask the user the questions
+below only where the page does not answer them — what it is for, who arrives, what
+is deferred — and show them the description to confirm or correct.
+
+Two things this is not. It is not a redesign: a region you would have arranged
+differently is still recorded as it is, and `critique` is where that argument
+belongs, with the rules behind it. And it is not a rubber stamp: a page that
+contradicts `DECISIONS.md` is described accurately and the contradiction noted in
+the prose, because the spec is a record of what is, and the review is what says
+whether that is right.
+
+**Asked to redesign it instead, run this command normally.** The difference is
+what the old page counts as: its content is the brief — the copy, the real data,
+the questions its FAQ answers — and its structure is not. Decide the composition
+from the rules and the answers, not from what the markup happens to do now, or
+the redesign is the same page in new colours. Anything that genuinely must
+survive is a constraint and belongs in the spec by name: a URL linked from
+elsewhere, a field order the back end depends on, wording somebody signed off.
+Ask which of those exist; do not assume the whole page is one.
+
+The commands after this run unchanged.
+
 ### 1. Ask, two or three questions at a time
 
 **This is a required interaction, not a suggestion.** Ask two or three questions,
@@ -231,9 +258,17 @@ settled at `init` and live in `{{config_file}}` and the token layer; re-deciding
 them per screen creates a second source of truth for the values Jig exists to
 centralise. If the user raises appearance, record it and move on.
 
+**Every question carries an example answer**, for the same reason `decide`'s do: a
+question someone has to decode gets a worse answer than one they can react to, and
+the example shows the shape. Say it is an example, not a suggestion.
+
 - Round 1 — what is it for? What does the user need to do there ("create an
   invoice")? Who arrives, and what is the single most important thing they must be
   able to see or do?
+  > *For example: "comprehension first, sign-up second. They arrive from the
+  > product page having already decided to try it, so no explainer above the
+  > cards. The most important thing is the limits — the price matters equally and
+  > must never dominate."*
 - **Then scope it — be a pessimist.** Of everything this could include,
   what is the smallest version that is useful on its own? Ask that plainly and
   expect to cut. "Comments with attachments, mentions, reactions, editing,
@@ -242,11 +277,20 @@ centralise. If the user raises appearance, record it and move on.
   forgotten. Everything after this designs V1 only.
 - Round 2 — what content and states does it carry? Empty, loading, error,
   first-run, and the realistic range (0 items, 5, 500)?
+  > *For example: "three plans, a monthly/annual choice, four FAQ questions, a
+  > footer. The billing choice is the only state — the page is static, nothing
+  > loads, nothing fails."*
 - Round 3 — only what is still unresolved: entry points, where it leads, what
   must not happen here.
+  > *For example: "they arrive from the product page or a docs search, and every
+  > plan goes straight to sign-up. Nothing on this page may ask for a sales
+  > call."*
 
 **Ask about the phone by name.** What does the reader see first on a phone, and
-what moves, stacks, or goes behind a control? If the conversation only ever
+what moves, stacks, or goes behind a control?
+> *For example: "the plans come first on the phone" — that is the answer this
+> question wants, and everything else about the narrow composition is the
+> system's to settle.* If the conversation only ever
 describes the wide screen, the phone composition will be derived from it rather
 than designed — and a derived phone composition is a squeezed desktop.
 
@@ -296,9 +340,15 @@ sizes:                     # phone first. Each size is a whole composition, not
     grouping: { form: proximity, brand: common region }
     grid: { columns: 12, form: 5, brand: 6 }
     nav: none on this screen
+  wide:                    # judged at 1600px — where a layout with no upper bound shows itself
+    same-as: desktop
+    why: "content is capped at 1200px, so 1600 adds margin and nothing else"
 states: [default, loading, error, success]
 decisions: [The Engineer Reads First]     # every DECISIONS.md entry this screen implements, by name
 later: [social sign-in, remember this device]   # cut from V1, by name — the next specs start here
+indexable: true            # from the mode — editorial yes, product/operator no. Say why when you override it.
+title: "Pricing — Hoistline"          # ≤ 60 characters, the search result's first line
+description: "Three plans, every price visible. No sales call."   # ≤ 155
 mockup: pending            # `mockup` sets approved or skipped, from the user's own words
 mockup_at:                 # where the approved drawing is: a .jig/mockups path, or a Figma or Stitch link
 deviations: []             # `make` writes here; `spec` leaves it empty
@@ -307,6 +357,24 @@ deviations: []             # `make` writes here; `spec` leaves it empty
 
 - **`phone` is written first, and in full.** It is the most common screen, and the
   one a derived composition fails on worst.
+- **`indexable:`, `title:` and `description:` are copy, decided here.** The mode
+  sets the default — `editorial` is first-visit content and is indexable,
+  `product` and `operator` are what somebody reaches after signing in and are
+  not — and a page overrides it with a reason: a CV shared by link, a
+  confirmation page, a page that exists for one recipient. A page that is not
+  indexable needs no title or description here and must carry `noindex` when
+  built (`J-123`).
+- **`wide` is required too, and is where an unbounded layout shows itself.** A
+  page judged only to 1280 never reveals that its content has no cap: at 1600 a
+  three-column grid becomes four thin ones, a header's logo and nav drift apart,
+  and a line of prose runs past its measure (`B-11`). `same-as: desktop` with a
+  `why:` is the right answer for a page that caps its content — and saying so is
+  the point.
+- **`landscape` is optional, judged at 900px.** Write it only when the
+  composition genuinely changes between tablet and desktop — a navigation that
+  expands there, a grid that goes three to two. Most pages do not, and a size
+  written to be written costs a composition, a frame, a render and a row of
+  verdicts on every page afterwards.
 - **`tablet` and `desktop` are written in full too.** `same-as: <size>` is allowed
   when nothing changes, but only with `why:`. It is a claim that the composition
   holds at that width — `critique` checks it on a render — not a way to leave the
@@ -318,6 +386,11 @@ deviations: []             # `make` writes here; `spec` leaves it empty
 - **No shell before there are features.** If the product has no navigation yet,
   `nav:` says `none yet` — it is decided once there is more than one feature to
   move between, not invented for the first one.
+- **Regions say what the content is, not what it looks like.** `- plans: three
+  cards` describes a shape; `- plans: a comparable set, one per tier` describes
+  content, and the second is what `make` can choose an element from. `H-119` runs
+  its decision order against these lines, so a region named only by its
+  appearance leaves the element to chance.
 - **`nav:` at every size, on any screen with navigation — decided by `P-14`'s table
   at that width, not copied.** It is the field most likely to be written once and
   copied, and most likely to be genuinely different at every size on a page that
@@ -428,7 +501,7 @@ before drawing. Do not switch to HTML on their behalf; offer it, and let them
 choose.
 
 - **Drawing in Figma.** One page named for the feature, one frame per size at the
-  spec's widths — 360, 768, 1280 — phone first. Grey fills and strokes only; no
+  spec's widths — 360, 768, 1280, 1600 — phone first. Grey fills and strokes only; no
   library components, styles or variables from the product's design system, for
   the same reason the HTML carries no tokens.
 - **Drawing in Stitch.** Ask for a low-fidelity grayscale wireframe of this one
@@ -483,7 +556,7 @@ look. So the drawing contains:
   what goes there. An icon is its name in brackets: `[search]`.
 - **Real words, not lorem ipsum.** Labels, headings and button text are part of the
   structure — "Create invoice" versus "Submit" is a decision worth reviewing.
-- **Every size the spec names, as its own frame** — phone, then tablet, then desktop,
+- **Every size the spec names, as its own frame** — phone, then tablet, then desktop, then wide,
   stacked top to bottom, each drawn with its own markup. Size is structure, not
   detail: a phone composition that is only the desktop one narrower is the failure
   specs are written per size to prevent. A `same-as:` size is drawn anyway, so the
@@ -510,6 +583,8 @@ look. So the drawing contains:
   .frame[data-size="phone"] { width: 360px; }
   .frame[data-size="tablet"] { width: 768px; }
   .frame[data-size="desktop"] { width: 1280px; }
+  .frame[data-size="wide"] { width: 1600px; }
+  .frame[data-size="landscape"] { width: 900px; }
   .region { border: 1px dashed #aaa; padding: 12px; margin: 0 0 12px; }
   .region > .name { display: block; font-size: 12px; color: #777; margin: 0 0 8px; }
   .media { background: #ddd; color: #555; display: grid; place-items: center; min-height: 120px; }
@@ -641,6 +716,20 @@ change. Write base styles for the phone and add width as it is available — not
 the desktop layout with overrides that take it apart again. A layout built wide
 and subtracted from ends up correct at exactly the widths somebody checked.
 
+**Choose every element from what its content is, before styling any of it**
+(`H-119`). For each region in the spec, run the decision order: what is this
+content — a heading, a list, a sequence, a quotation, tabular data, navigation,
+a control, a landmark? Is there a native element whose meaning is that? Does it
+describe the content accurately? Only when nothing fits is a generic container
+right. The page must read as what it is with the stylesheet off, in an order
+that makes sense; CSS then arranges it, and never the reverse.
+
+**Write the metadata in this change, not the next one** (`J-120`). The title,
+description and preview text are copy: they come from the spec, they are written
+by whoever wrote the headline, and they move when it moves. A page that is not
+indexable carries `noindex` instead, from its own metadata rather than from
+`robots.txt`, which is public and advisory and protects nothing.
+
 Then the ordinary rules apply: tokens by semantic name, the relevant
 `03-patterns.md` section for each component, `05-copy.md` for every string.
 
@@ -675,7 +764,7 @@ one. A report with no `JIG_CHECK:` line, or one you typed yourself, is not a fin
 build.
 
 **2. The build matches the approved mockup at each size.** Skip only when
-`mockup: skipped`. Render the page at 360px, 768px and 1280px — with a browser, not in
+`mockup: skipped`. Render the page at 360px, 768px, 1280px and 1600px — with a browser, not in
 your head — and set each render beside the mockup at the same width. Go region by
 region, in the mockup's order:
 
@@ -742,7 +831,9 @@ conversation that built the page. Running them in one head anchors them to each
 other; do not shortcut it for cost, speed or context size.
 
 - **A — the reader.** Delegate to a subagent. Give it the URL or file, the spec,
-  the approved mockup (from `mockup_at:`), `DECISIONS.md`, and the corpus. It judges the `pass: screen` rules against the render, **and the `P-` patterns the spec's regions use** — a navigation region means `P-14`. Those patterns are not in `rules.index.json`, so walking the index alone never reaches them. It writes its verdicts to `.jig/critique/<surface>/screen.json` (step 1c). Do
+  the approved mockup (from `mockup_at:`), `DECISIONS.md`, and the corpus. It also
+  judges every decision in `DECISIONS.md` against the page and writes
+  `decisions.json` (step 1c). It judges the `pass: screen` rules against the render, **and the `P-` patterns the spec's regions use** — a navigation region means `P-14`. Those patterns are not in `rules.index.json`, so walking the index alone never reaches them. It writes its verdicts to `.jig/critique/<surface>/screen.json` (step 1c). Do
   **not** give it the build conversation. If it needs that conversation, it is
   not reviewing the page, it is agreeing with itself.
 - **B — the machine.** Run `check`. Deterministic, same input same output. It
@@ -837,9 +928,9 @@ Each reader arm writes its own file. The arm reports back only that it wrote it.
 ```json
 {
   "rendered": true,
-  "artefacts": [".jig/critique/pricing/360.png", ".jig/critique/pricing/768.png", ".jig/critique/pricing/1280.png"],
+  "artefacts": [".jig/critique/pricing/360.png", ".jig/critique/pricing/768.png", ".jig/critique/pricing/1280.png", ".jig/critique/pricing/1600.png"],
   "verdicts": [
-    { "id": "D-115", "verdict": "ok", "reason": "no sideways scroll at 360, 768 or 1280" },
+    { "id": "D-115", "verdict": "ok", "reason": "no sideways scroll at 360, 768, 1280 or 1600" },
     { "id": "P-14", "verdict": "finding", "reason": "menu button at 360 does not open; aria-expanded never set" },
     { "id": "A-60", "verdict": "n/a", "reason": "A-60 is about competing icons; this page has none" }
   ]
@@ -848,16 +939,44 @@ Each reader arm writes its own file. The arm reports back only that it wrote it.
 
 `screen.json` carries `rendered` and `artefacts`; `code.json` needs only `verdicts`.
 
-**A rendered review is measured, not only described.** At 360, 768 and 1280px, run the
+**And the project's own decisions, one verdict each**, in
+`.jig/critique/<surface>/decisions.json`:
+
+```json
+{
+  "verdicts": [
+    { "decision": "Voice", "verdict": "finding", "reason": "headings and buttons are Title Case; the decision says lowercase" },
+    { "decision": "Trial and onboarding", "verdict": "finding", "reason": "Team and Scale say \"start free trial\"; the trial was replaced by the free Solo plan" },
+    { "decision": "Navigation", "verdict": "ok", "reason": "menu button top right at 360, five links at 768 and above" }
+  ]
+}
+```
+
+Every `##` and `###` heading in `DECISIONS.md` is a decision and gets exactly one
+verdict, judged against the built page. `Unresolved` is not a decision. The rules
+are the system's; these are the project's, and a page can satisfy all 115 rules
+while breaking the file written to hold what this project chose. In a live round
+one page shipped "start free trial" two commands after the owner had killed
+trials, and another used Title Case against a lowercase decision. Both passed
+every rule.
+
+**A rendered review is measured, not only described.** At 360, 768, 1280 and 1600px, run the
 probe in the browser and save what it returns beside the verdicts:
 
 ```
-{{scripts_path}} probe > .jig/probe.js
-# at each width: set the viewport, open the page, evaluate .jig/probe.js, and pipe
-# exactly what it returned into:
+# If a browser is on this machine, one command renders and records all three:
+{{scripts_path}} probe --run <page> --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>
 ```
 
+`--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.
+
 **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
 measurement: `verdicts` recomputes the checksum, so a file written by hand, or one
@@ -907,17 +1026,37 @@ source and imagining the page is not a render.
   that works: in a live run four of six pages shipped a phone menu that did not open,
   or no menu at all, and every review that only looked passed them.
 - **Render at every size the spec names** — phone at 360px, tablet at 768px,
-  desktop at 1280px — and judge each size's fields against its own render. A
+  desktop at 1280px, wide at 1600px — and judge each size's fields against its own render. A
   `same-as:` claim is checked like any other field: render that size and see
   whether the composition really does hold.
 - At every size, measure `document.documentElement.scrollWidth` against
   `clientWidth`. Greater means the page scrolls sideways at that width, which is a
   finding however good the rest of it looks.
+- **Judge the collapse, not only the sizes** (`L-01` step 6). Between one width
+  and the next: did the column count drop rather than the columns shrink, did the
+  reading order hold, did an emphasised item stay distinguishable once everything
+  was in one column, did anything genuinely wider scroll inside itself rather
+  than taking the page with it?
 - Compare the sizes. Did the phone change the **composition**, or only the
   **dimensions**? Reordering, stacking, collapsing, a different control — that is
   composition. The same layout with smaller numbers is not.
 - Check the page is styled at all. A stylesheet that 404s renders a page that
   passes every file-based check ever written.
+- **Read what a stranger meets first** (`J-120`). Open the head: does the title
+  still describe this page, does the description still say what the page now
+  says, and would either have survived the last copy change? A page whose
+  metadata contradicts its own headline is the commonest drift there is, because
+  a copy pass reads pages and nobody reads the head. Run `{{scripts_path}} seo`
+  for what one page cannot see: a route that says `noindex` and sits in the
+  sitemap, two pages claiming the same title, a site with neither sitemap nor
+  robots.
+- **Read the markup as a document, not a layout** (`H-119`). For each region:
+  does its element say what the content is? Would the page still read correctly
+  with the stylesheet off, in this order? A row of links that is not a `<nav>`, a
+  heading that is a styled `<div>`, steps in no particular element, a comparison
+  of values that is not a table: each is a finding, and each names the element
+  the content asks for. A `<div>` is right where nothing more specific is true;
+  say so rather than inventing a fault.
 - Run the squint test from `L-01` against the render, not the analogue: render
   each size once more with `filter: grayscale(1)` on the root, and check that the
   primary action, the headings and the groups still read in order without colour.
@@ -957,10 +1096,10 @@ preserve while fixing them.
 Then the attestation:
 
 ```text
-JIG_CRITIQUE: version=<version> mode=<mode> surface=<name> spec=<confirmed|missing|unconfirmed> mockup=<approved|skipped|missing> rendered=<yes|no> screen=<ran|skipped>:<n> code=<ran|skipped>:<n> mechanical=<pass|fail|skipped>:<n> warnings=<n>
+JIG_CRITIQUE: version=<version> mode=<mode> surface=<name> spec=<confirmed|missing|unconfirmed> mockup=<approved|skipped|missing> rendered=<yes|no> screen=<ran|skipped>:<n> code=<ran|skipped>:<n> decisions=<ran|incomplete|missing>:<n> mechanical=<pass|fail|skipped>:<n> warnings=<n>
 ```
 
-**Take `screen=`, `code=` and `rendered=` from `jig verdicts`, never from your own
+**Take `screen=`, `code=`, `decisions=` and `rendered=` from `jig verdicts`, never from your own
 count.** If it reported an arm incomplete, that arm is `skipped` here with the reason,
 until it is re-run and passes.
 
@@ -1015,6 +1154,22 @@ Run `{{scripts_path}} probe`. It prints one JavaScript expression — the render
 for the critique's screen arm to evaluate in a browser at each width. See step 1c of
 `critique`. It changes nothing on its own.
 
+## seo
+
+Run `{{scripts_path}} seo` and report what it says. It needs no `DECISIONS.md`,
+no spec and no confirmation: it reads what the project already serves, so it is
+safe to run on the first day and on somebody else's codebase. It audits the whole project,
+which is what one file cannot: a route whose metadata says `noindex` sitting in
+the sitemap, two pages claiming the same title, indexable pages with no sitemap,
+a sitemap that lists nothing.
+
+It is not a phase. The per-page half belongs where the copy is decided and
+written — `spec` records whether a page is indexable and what it claims, `make`
+writes the metadata in the same change as the headline, `check` enforces the
+budgets — because a pass you run afterwards is a pass that gets skipped on the
+day the copy changes, which is exactly how a live site ended up serving
+positioning it had already dropped.
+
 ## gate
 
 Not a command to run. In Claude Code, `install` adds a Stop hook that runs
@@ -1045,7 +1200,10 @@ wherever `brand` in `{{config_file}}` puts the token files.
 
 `spec`, `mockup`, `make` and `critique` are blocked until this exists: `spec` and
 `critique` refuse to start without it, and `mockup` and `make` need a confirmed spec.
-Nothing else is blocked — `install`, `init`, `check` and `explain` run without it.
+Nothing else is blocked — `install`, `init`, `check`, `explain`, `seo`, `probe`
+and `verdicts` all run without it. `seo` in particular is an audit of what is
+already there, and a project with no decisions yet still has a sitemap that
+either contradicts its pages or does not.
 `init` comes first, because this file sits beside the token files `init` writes.
 
 ### What belongs in it, and what does not
@@ -1089,14 +1247,87 @@ at all. If the design system has a position, it is in the rules; if it has none,
 you are looking for is the places where this project has already chosen
 something, or will have to:
 
+**Ask every question with an example answer attached.** A question someone has to
+decode gets a worse answer than one they can react to, and the example shows the
+shape you need — a sentence about this product, not an adjective. Say plainly
+that it is an example, not a suggestion.
+
 - Round 1 — what is this product, and who is it for in a sentence the team would
   recognise? What should it never look like? Name real products, not adjectives.
+  > *For example: "hosted log search — you point it at your cluster and ask in
+  > plain text. For a backend engineer who has tried grep over SSH. It must never
+  > look like an enterprise console: no SKU matrix, no 'contact us' pricing.
+  > Closer to Fly.io than to a Datadog dashboard."*
+- Round 1b — **what the product is for, and what you give up for it.** This file
+  is project-wide, so both answers are about the product, not a page. A page's
+  own purpose is `spec`'s question, and it inherits its direction from here.
+  - *"If this product works, what can someone do that they could not before?"*
+    That is the north star: one outcome, in the product's own words, that every
+    later argument is settled against. A design direction without one drifts
+    screen by screen, each change defensible on its own.
+    > *For example: "an engineer finds the line in their logs without learning a
+    > query language" — not "be the best log tool", which no screen can serve or
+    > fail. The test: could you look at a design and say whether it moves toward
+    > that sentence?*
+  - *"When two good options conflict here, which side do you take?"* Fast over
+    complete, plain over clever, fewer choices over more, density over comfort.
+    > *For example: "comprehension wins over persuasion — if the clearer page
+    > converts worse, we ship the clearer page", or "recovery wins over speed:
+    > every destructive action is undoable, even where that costs a step".*
+    Jig's own tiebreakers settle the system's conflicts; this settles the
+    project's, and without it the agent settles them alone. In a live run a
+    decision about where the accent may appear collided with a component rule
+    and the agent resolved it on its own, correctly as it happens, and recorded
+    the collision as a deviation. One line here would have decided it.
+
+  **Refuse an adjective, ask again.** "Bold", "human", "trustworthy" and
+  "premium" cannot be checked against a page, and every decision in this file is
+  now judged against one. Push for the form that can: what it is closer to, what
+  it would rather be than, what it refuses.
+- Round 1c — **the personality, asked through the four things that produce it.**
+  Every interface has one whether it was chosen or not, and it is not a mood
+  board: it is decided by type, colour, corners and language, each of which is a
+  value this project is about to set. Ask about all four, one question each, and
+  say what each answer will become.
+  - **Type.** Serif reads classic or editorial; a rounded sans reads friendly; a
+    neutral sans stays out of the way and lets everything else carry the
+    personality. Which is this? *(Becomes `--font-text` and `--font-display`.)*
+  - **Colour.** Which colour is this product's, and what does it mean here? The
+    psychology matters less than the reason: blue is familiar and safe, gold
+    reads expensive, pink reads unserious. *(Becomes `--color-brand`, and the
+    contrast floors still apply — a palette that fails them is not a
+    personality.)*
+  - **Corners.** Square reads formal or technical, a small radius is neutral,
+    a large one reads playful. One answer for the whole interface: mixing square
+    and round in one screen looks worse than either. *(Becomes the `--radius-*`
+    scale.)*
+  - **Language.** Official and impersonal, or plain and conversational? Words
+    appear in every screen, so this decides more of the personality than any
+    single visual choice. *(Becomes a voice decision here, applied by
+    `05-copy.md`.)*
+  > *For example: "neutral sans — the type should disappear. One colour, a muted
+  > olive, because it is the one thing on the page that is not a plan or a price.
+  > Square corners; this is a tool, not a toy. Lowercase and technical: ingest,
+  > retention, seat — plain words, undefined, no throat-clearing."*
+
+  **When they have no gut feeling, ask what the reader already uses.** The sites
+  this audience spends its day in set the expectation; matching that is cheaper
+  than teaching a new one. Take the direction, never the design: a project that
+  borrows from a direct competitor looks like a second-rate version of it, which
+  is also `A-01`'s point about invented decoration seen from the other side.
 - Round 2 — for each thing the tokens already set, is there a rule about *how* it
   is used? Where does the brand colour go, and where is it forbidden? What earns
   emphasis?
+  > *For example: "the accent appears exactly twice per page, both clickable —
+  > the primary action and the active side of a control. Never on a checkmark, a
+  > limit number or a feature list. Emphasis is earned by the one thing the
+  > reader came to do."*
 - Round 3 — what has the team already argued about, or reversed? A decision with
   a history is the one most worth recording, because it is the one most likely to
   be re-made wrongly.
+  > *For example: "we shipped a 'most popular' badge for six weeks. Conversion
+  > rose slightly; wrong-plan signups and support tickets rose more. We pulled
+  > it, and that covers the effect, not the widget — no raised card either."*
 
 **All three rounds run.** Do not write the file after round 2 because the answers
 look complete. Round 3 asks for the one kind of decision a user does not volunteer
@@ -1105,7 +1336,10 @@ reason. In the arm that did ask, round 3 is where the unresolved items surfaced.
 
 **Round 3 also asks, by name, what is still undecided.** "Is there anything the team
 has not settled yet — something still argued about, or waiting on someone?" Ask it
-even when nothing so far suggests there is. Whatever the answer names goes in the
+even when nothing so far suggests there is.
+> *For example: "whether we publish a public status page. It is between showing
+> uptime on the pricing page and not mentioning it at all, and it waits on
+> whether support can staff it."* Whatever the answer names goes in the
 **Unresolved** section below, not into a decision the user did not make. Four of six
 files in a live run dropped the one open item the owner had named.
 
@@ -1127,6 +1361,27 @@ wrong.
 A name gives the team something to cite in review. A reason lets a future agent
 tell when the rule does not apply, which a bare instruction never can.
 
+**The north star and the tiebreaker are decisions like any other**, written with
+the same shape and judged against every page:
+
+```markdown
+### What this page is for
+
+A reader leaves knowing which plan fits them and which limit they would hit
+first. Nothing else on the page outranks that.
+
+**Why:** they arrive from the product page already interested; the job is to
+remove the last doubt, not to sell again.
+
+### When two options conflict
+
+Comprehension wins over persuasion. If a clearer page converts worse, we ship
+the clearer page.
+
+**Why:** the reader is an engineer who has been sold to badly before, and the
+support cost of a wrong-plan signup outweighs the signup.
+```
+
 **The reason is the owner's, or it is not written.** Write the `Why:` the user gave,
 in their words or close to them. If they gave none, ask for it. If they still give
 none, write `**Why:** not given` — never a reason you supplied. A live run invented

package/templates/command-metadata.json

@@ -24,14 +24,19 @@
     "argumentHint": "[--all] [--ci] [--json]",
     "status": "available"
   },
+  "seo": {
+    "description": "Audit what a search engine and a link preview read, across the whole project: a noindex route in the sitemap, two pages with one title, indexable pages with no sitemap, a sitemap that lists nothing. The per-page half lives in spec, make and check.",
+    "argumentHint": "[--json]",
+    "status": "available"
+  },
   "verdicts": {
     "description": "Verify a critique's verdict files: every rule in each pass judged once, no id that does not exist, no rule in the wrong arm, rendered only with a screenshot. Computes the counts the critique reports, so the agent never writes them.",
     "argumentHint": "<surface>",
     "status": "available"
   },
   "probe": {
-    "description": "Print the render probe: a script the critique runs in a browser at 360, 768 and 1280px. With --save it records what the probe returned, stamped with the page's checksum, so `verdicts` can tell a measurement from a claim.",
-    "argumentHint": "[--save <surface>]",
+    "description": "Print the render probe, or run it here. `--run <page> --save <surface>` drives a headless browser it finds for itself and records the measurement at 360, 768 and 1280, stamped with the page's checksum, so `verdicts` can tell a measurement from a claim.",
+    "argumentHint": "[--run <page>] [--save <surface>]",
     "status": "available"
   },
   "gate": {