@ethlete/agent-rules 0.1.0-next.3 → 0.1.0-next.5

package/content/skills/figma-export/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: figma-export
+description: Reconcile a component against a Figma export - which exports to ask the designer for (an .svg frame and its "copy as CSS" dump), how to dump the geometry out of each, which of their numbers are authoritative, and how to measure the real rendered result against them headlessly. Use whenever a design export is dropped next to a component and the component has to be matched to it.
+kind: skill
+scope: both
+---
+
+# Reconcile a component against a Figma export
+
+Three things arrive from Figma, and each answers a different question:
+
+| Export                    | Gives you                                                                     | Cannot tell you                             |
+| ------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------- |
+| **`.svg`** (Export frame) | Exact geometry with nesting, exact fills, and a picture once you rasterise it | Layer names, auto-layout intent, font sizes |
+| **`.css`** (Copy as CSS)  | Named layers, auto-layout properties, typography metrics, design-token names  | Any hierarchy at all — the dump is flat     |
+| **`.png`** (a screenshot) | Figma's own blue measurement overlays, and what the designer chose to frame   | Nothing machine-readable                    |
+
+**Ask for the `.svg` and the `.css` together, and do not start until you have both.** The two
+are complements, not alternatives: the SVG is the only export you can both look at and
+measure, and the CSS is the only one that names layers and records type. A PNG earns its place
+only when it is a _screenshot_ carrying dev-mode annotations — a PNG _render_ of the same frame
+adds nothing the SVG does not. None of the three tells you the colours.
+
+Say what you are missing and what it would settle, in one line — "I have the SVG; the `.css`
+export would give me the font sizes and whether these cards Hug or Fill" — and wait. Every
+number in your diff has to trace back to something in an export or to a token; a plausible
+`17px` you inferred from a 12px outlined glyph is worse than an open question, because it
+survives review as though it had been specified. If the pair genuinely cannot be produced, say
+in the write-up which numbers are therefore guesses.
+
+## 1. Read the export before touching code
+
+### From an `.svg` — look at it, then measure it
+
+Rasterise it and actually open the image. Figma outlines text on export, so this needs no
+webfonts and matches the frame exactly:
+
+```bash
+magick -density 144 <export.svg> <scratch>/frame.png    # then read frame.png
+```
+
+(If the render looks wrong, ImageMagick fell back to its own SVG renderer — check for
+`RSVG` in `magick -list format | grep SVG`, or screenshot the file in Playwright instead.)
+
+Then dump the geometry with {%resource:dump-figma-svg.py%} — every shape in document order,
+indented by group nesting, with absolute coordinates:
+
+```bash
+python3 dump-figma-svg.py <export.svg>
+```
+
+It closes with two summaries worth reading first: repeated rect sizes, which say _one
+component rendered N times_ where the CSS dump would show N unrelated frames; and the measured
+gaps between rects that share a top edge, which is the auto-layout gap without having to
+believe a label.
+
+What the SVG does **not** carry:
+
+- **Layer names.** Nothing is called `Card` or `Badge`; you match shapes to the picture.
+- **Auto-layout intent.** `Hug` vs `Fixed` vs `Fill` is gone, so a width you read off is the
+  width _at this one size_, not a rule. Derive padding and gaps from the coordinates, and
+  treat a child width as content-driven until the picture or the CSS dump says otherwise.
+- **Typography.** Outlined text is a `<path>`; the dumper labels the wide ones `text?` and
+  boxes them, which places a text run but tells you nothing about `font-size` or
+  `line-height`. If the designer exported with _Outline Text_ off, `<text>` nodes survive and
+  the dumper prints their font metrics and strings — take them when you get them.
+
+Two numbers to read carefully: a **stroke is centred**, so a 32px circle with a 1px border
+exports as `31 × 31` at `.5` offsets — add the stroke width back before comparing. And an
+**outlined glyph box is the ink**, not the line box: a 17px/20px title measures ~12px tall,
+the same cap-trim the CSS dump reports, so never match a text node's height.
+
+### From a `.css` dump — names, intent and type metrics
+
+Never grep the raw file — its layout defeats naive parsing (see the traps below). Run
+{%resource:dump-figma-layers.py%}:
+
+```bash
+python3 dump-figma-layers.py <export.css>                    # every layer, artwork dropped
+python3 dump-figma-layers.py <export.css> '^(Widget|Frame|Card)'   # only what you name
+```
+
+Then work out the frame's box model top-down — outer frame width and padding, then each
+child's `width`/`gap`/`flex-grow` — and write the ladder down before you start editing, so you
+can tell a deliberate design decision from a Figma artefact.
+
+### Whatever you have, look at the picture before you decide what to build
+
+The CSS dump is a **flat** sequence of layers with no nesting whatsoever, so the tree is not in
+it; the SVG has the tree but no names. The image is what disambiguates:
+
+- **Hierarchy and reading order** — which layer contains which. The only other clue in the CSS
+  is `order:` inside a sibling run, which does not cross frames.
+- **Repetition vs distinct layers.** Six blocks with identical declarations are one component
+  rendered six times. The CSS looks like six unrelated frames.
+- **Multiple states in one board.** Frames are routinely laid out side by side as
+  default / hover / selected / empty, with a pink cursor marking the interaction. The CSS
+  gives you every state flattened together with nothing saying which is which, so a number
+  read blind may belong to a hover state you are not building.
+- **Figma's own measurement overlays.** Blue annotations like `396 × 401 Hug` or `347 × 23`
+  are authoritative and frequently _absent_ from the CSS — `Hug` in particular tells you a
+  dimension is content-driven, which no declaration in the export records. These live only in
+  a canvas _screenshot_; a frame export of any format drops them.
+- **What is decoration.** Cursors, callout arrows and section captions painted on the board
+  are not part of the component, but they do emit layers.
+
+### Traps in the `.css` export itself
+
+- **Sub-comments carry the real properties.** Figma writes `/* Auto layout */`,
+  `/* Inside auto layout */`, `/* or 16px */` and token names like
+  `/* Brand/Chalk White/500 */` _between_ a layer's declarations. A parser that starts a new
+  layer at every comment reports frames with **zero properties** and swallows the geometry.
+  The dumper folds them in — it decides by the blank line that follows a real layer name, not
+  by the name, so component layers called `Profile/Badge` survive.
+- **Frame labels lie.** A frame _named_ "Widget 636px" routinely has `width: 640px`, and a
+  label like "8 rows = 564px" often does not reconcile with the grid it sits in. Trust the
+  declarations, never the label.
+- **Text heights are cap-trimmed.** With `leading-trim: both; text-edge: cap`, a 17px/20px
+  title reports `height: 12px`. Compare `font-size`, `line-height` and `letter-spacing`;
+  never compare a text node's height.
+- **Absolute `left`/`top`** are canvas coordinates of the whole board. Only the _differences_
+  within one frame mean anything.
+
+## 2. Decide what the export is allowed to dictate
+
+- **Authoritative:** geometry and typography metrics — widths, padding, gaps, `flex-grow`,
+  border radius, font size / weight / line-height / letter-spacing, and the breakpoints at
+  which the layout changes.
+- **Never authoritative: colour.** Backgrounds, text, borders and interaction states resolve
+  from the surface and colour theming tokens — see {%skill:theming%}. A hex in the
+  export is information about the _designer's_ palette, not a value to paste. Where the
+  export's colour and the token disagree, keep the token and note the delta for the design
+  review; the export can be wrong about contrast in a way the tokens are not. This holds
+  hardest for an SVG, whose fills are exact and therefore tempting: an exact wrong answer is
+  still wrong.
+- **Radius and spacing snap to the scale.** Round to the nearest token rather than emitting an
+  arbitrary value, and say so if the export's number is more than a step away.
+
+## 3. Ask before making a structural choice
+
+Matching numbers is mechanical; the choices around them are not. Stop and ask when the export
+implies:
+
+- a **breakpoint strategy** — container queries with an exact ladder vs a retuned
+  `auto-fill`/`auto-fit` grid;
+- **shared-component churn** — a new variant on a component other screens already use, vs a
+  local override;
+- a **scroll region** — which part scrolls and what stays pinned;
+- **fixed sizing** where the component is currently fluid, or the reverse;
+- anything the export shows that the API does not yet return.
+
+Colour deltas are informational — report them, do not block on them.
+
+## 4. Measure the real thing, don't eyeball it
+
+A build passing proves nothing about geometry. Render the component's real markup against the
+**production stylesheet** and read the computed boxes back. {%resource:measure-template.mjs%}
+is a working starting point; copy it into a scratch directory with the compiled stylesheet
+beside it:
+
+```bash
+# whatever your build emits — the point is a real, fully compiled stylesheet
+cp dist/apps/<app>/browser/styles-*.css <scratch>/styles.css
+node <scratch>/measure-template.mjs
+```
+
+Confirm the arbitrary utilities you wrote actually compiled — a typo in
+`@min-[392px]` fails silently:
+
+```bash
+grep -oE '@container \(width >= [0-9]+px\)|\.(h-15|rounded-sm)\{[^}]*\}' dist/apps/<app>/browser/styles-*.css | sort -u
+```
+
+Harness gotchas, each of which will cost you an hour:
+
+- **`page.setContent()` renders on `about:blank`, which blocks `file://` subresources** — the
+  stylesheet silently never loads. Write a real HTML file and `page.goto('file://…')`.
+- **Never lay the probes out in a flex _row_.** They shrink, and container queries then report
+  results for a width the component would never see. Stack them in a column at explicit widths.
+- **The harness has no webfonts** unless you copy the `@font-face` sources too. Text runs
+  ~1px wide of reality, so a label that wraps in the harness may well fit in the app. Check
+  before calling a wrap a defect.
+- Playwright is CommonJS and unresolvable from a scratch directory — `createRequire` against
+  the repo root, as the template does. The same applies when driving a story:
+  {%skill:verify-in-storybook%}.
+
+## 5. Close the loop
+
+Report the measured numbers next to the export's, per width — not "matches the design". Say
+explicitly which parts of the export you deliberately did **not** implement and why (colour
+kept as tokens, a label the product decided never to render, a field the API lacks). Then
+delete the export files once their component is signed off, so the folder always shows only
+what is still outstanding.

package/content/skills/figma-export/dump-figma-layers.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Dump the properties of every layer in a Figma "copy as CSS" export, in document order.
+
+    python3 dump-figma-layers.py <export.css> ['<name regex>']
+
+Without a regex every layer is printed except obvious vector artwork. With one, only the
+layers whose name matches it.
+
+Figma emits sub-comments — `/* Auto layout */`, `/* Inside auto layout */`, `/* or 16px */`
+and design-token names like `/* Brand/Chalk White/500 (base) */` — that carry properties
+belonging to the layer named above them. They are folded into that layer rather than treated
+as new ones: a parser that splits on every comment reports frames with zero properties.
+"""
+
+import re
+import sys
+
+COMMENT = re.compile(r'^/\* (.+) \*/$')
+LAYOUT_NOTE = re.compile(r'^(Auto layout|Inside auto layout|or [\d.]+px|Hug|Fixed|Fill|Effect style)$')
+ARTWORK = re.compile(
+    r'^(Polygon|Vector|Ellipse|Rectangle \d|Star|Union|Subtract|Group|Mask|Clip'
+    r'|Texture|Frame \d{6,})'
+)
+
+
+def read_blocks(path):
+    """Yield ('comment', name) and ('prop', text), skipping Figma's multi-line prose notes."""
+    lines = [line.rstrip('\n') for line in open(path)]
+    index, total = 0, len(lines)
+
+    while index < total:
+        stripped = lines[index].strip()
+
+        if stripped.startswith('/*') and not stripped.endswith('*/'):
+            while index < total and not lines[index].rstrip().endswith('*/'):
+                index += 1
+            index += 1
+            continue
+
+        comment = COMMENT.match(stripped)
+
+        if comment:
+            following = lines[index + 1].strip() if index + 1 < total else ''
+            yield 'comment', comment.group(1), following
+        elif ':' in stripped and not stripped.startswith('/*'):
+            yield 'prop', stripped, ''
+
+        index += 1
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+
+    path = sys.argv[1]
+    match = re.compile(sys.argv[2]).search if len(sys.argv) > 2 else None
+    show, index = False, 0
+
+    for kind, text, following in read_blocks(path):
+        if kind == 'prop':
+            if show:
+                print(f'    {text}')
+            continue
+
+        # A layer name is followed by a blank line; a sub-comment sits directly on top of the
+        # declarations it annotates. The name list covers the few notes Figma writes before
+        # another comment, where that spacing rule cannot decide.
+        is_declaration = ':' in following and not following.startswith('/*')
+
+        if is_declaration or LAYOUT_NOTE.match(text):
+            if show:
+                print(f'    /* {text} */')
+            continue
+
+        index += 1
+        show = match(text) is not None if match else not ARTWORK.match(text)
+
+        if show:
+            print(f'\n--- [{index}] {text}')
+
+
+if __name__ == '__main__':
+    main()

package/content/skills/figma-export/dump-figma-svg.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Dump the box tree of a Figma SVG export: every shape with absolute coordinates.
+
+    python3 dump-figma-svg.py <export.svg>
+
+Prints one line per drawn element in document order, indented by group nesting, then a
+summary of repeated shapes and of the gaps between shapes that share a row.
+
+An SVG export has no layer names and — because Figma outlines text on export — no strings
+or font metrics. What it does have is exact geometry: every rect carries its own x/y/
+width/height/rx, so padding and gaps are differences you can read off rather than numbers
+you have to trust a label for. Outlined text is measured by the bounding box of its path
+coordinates, which runs a fraction of a pixel wide because Bezier control points sit
+outside the curve — enough to place a text run, not to size a glyph.
+"""
+
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+SVG_NS = '{http://www.w3.org/2000/svg}'
+TRANSLATE = re.compile(r'translate\(\s*([-\d.]+)[\s,]+([-\d.]+)\s*\)')
+TOKEN = re.compile(r'([MmLlHhVvCcSsQqTtAaZz])|(-?\d*\.?\d+(?:e[-+]?\d+)?)', re.IGNORECASE)
+ARITY = {'m': 2, 'l': 2, 'h': 1, 'v': 1, 'c': 6, 's': 4, 'q': 4, 't': 2, 'a': 7, 'z': 0}
+SKIP = {'defs', 'clipPath', 'mask', 'filter', 'linearGradient', 'radialGradient', 'pattern'}
+
+
+def tag_of(element):
+    return element.tag[len(SVG_NS) :] if element.tag.startswith(SVG_NS) else element.tag
+
+
+def number(element, name, fallback=0.0):
+    try:
+        return float(element.get(name, fallback))
+    except ValueError:
+        return fallback
+
+
+def translation(element):
+    match = TRANSLATE.search(element.get('transform') or '')
+
+    return (float(match.group(1)), float(match.group(2))) if match else (0.0, 0.0)
+
+
+def path_points(data):
+    """Every point a path visits, control points included. `H`/`V`/`A` take counts of their
+    own, so pairing the numbers off two at a time reports a box the shape never occupies."""
+    tokens = TOKEN.findall(data)
+    index, command, x, y = 0, 'm', 0.0, 0.0
+
+    while index < len(tokens):
+        letter, value = tokens[index]
+
+        if letter:
+            command = letter
+            index += 1
+
+            if command.lower() == 'z':
+                continue
+
+        arity = ARITY[command.lower()]
+        args = [float(tokens[index + step][1]) for step in range(arity) if index + step < len(tokens)]
+
+        if len(args) < arity:
+            return
+
+        index += arity
+        relative = command.islower()
+
+        if command.lower() == 'h':
+            x = x + args[0] if relative else args[0]
+        elif command.lower() == 'v':
+            y = y + args[0] if relative else args[0]
+        else:
+            pairs = [(args[5], args[6])] if command.lower() == 'a' else list(zip(args[0::2], args[1::2]))
+
+            for point_x, point_y in pairs:
+                yield (x + point_x, y + point_y) if relative else (point_x, point_y)
+
+            x, y = (x + pairs[-1][0], y + pairs[-1][1]) if relative else pairs[-1]
+
+        yield x, y
+
+        if command == 'M':
+            command = 'L'
+        elif command == 'm':
+            command = 'l'
+
+
+def path_box(data):
+    points = list(path_points(data))
+    xs, ys = [point[0] for point in points], [point[1] for point in points]
+
+    if not xs:
+        return None
+
+    return min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys)
+
+
+def box_of(element):
+    name = tag_of(element)
+
+    if name in ('rect', 'image'):
+        return number(element, 'x'), number(element, 'y'), number(element, 'width'), number(element, 'height')
+
+    if name == 'path':
+        return path_box(element.get('d') or '')
+
+    if name in ('polygon', 'polyline'):
+        return path_box('M' + (element.get('points') or ''))
+
+    if name == 'circle':
+        radius = number(element, 'r')
+
+        return number(element, 'cx') - radius, number(element, 'cy') - radius, radius * 2, radius * 2
+
+    if name == 'ellipse':
+        rx, ry = number(element, 'rx'), number(element, 'ry')
+
+        return number(element, 'cx') - rx, number(element, 'cy') - ry, rx * 2, ry * 2
+
+    if name == 'line':
+        x1, y1 = number(element, 'x1'), number(element, 'y1')
+
+        return x1, y1, number(element, 'x2') - x1, number(element, 'y2') - y1
+
+    return None
+
+
+def trim(value):
+    return f'{value:.3f}'.rstrip('0').rstrip('.')
+
+
+def walk(element, offset, depth, boxes):
+    for child in element:
+        name = tag_of(child)
+
+        if name in SKIP:
+            continue
+
+        dx, dy = translation(child)
+        origin = (offset[0] + dx, offset[1] + dy)
+
+        if name in ('g', 'svg'):
+            print(f'{"  " * depth}<{name}>' + (f' translate({trim(dx)} {trim(dy)})' if (dx or dy) else ''))
+            walk(child, origin, depth + 1, boxes)
+            continue
+
+        if name == 'text':
+            content = ' '.join(''.join(child.itertext()).split())
+            metrics = ' '.join(
+                f'{key}={child.get(key)}'
+                for key in ('font-family', 'font-size', 'font-weight', 'letter-spacing')
+                if child.get(key)
+            )
+            x, y = number(child, 'x') + origin[0], number(child, 'y') + origin[1]
+            print(f'{"  " * depth}{"text":<6} {trim(x):>9} {trim(y):>8}  {metrics}  "{content}"')
+            continue
+
+        box = box_of(child)
+
+        if box is None:
+            continue
+
+        x, y, width, height = box[0] + origin[0], box[1] + origin[1], box[2], box[3]
+        radius = child.get('rx') if name == 'rect' else None
+        paint = child.get('fill') or child.get('stroke') or ''
+        detail = f' r={radius}' if radius else ''
+        detail += f' {"stroke" if child.get("stroke") else "fill"}={paint}' if paint and paint != 'none' else ''
+        label = 'text?' if name == 'path' and width >= height * 3 else name
+
+        print(f'{"  " * depth}{label:<6} {trim(x):>9} {trim(y):>8}  {trim(width):>8} × {trim(height):<8}{detail}'.rstrip())
+        boxes.append((x, y, width, height, name, radius, paint))
+
+
+def summarise(boxes):
+    shapes = {}
+
+    for x, y, width, height, name, radius, paint in boxes:
+        if name != 'rect':
+            continue
+
+        shapes.setdefault((round(width, 2), round(height, 2), radius), []).append((x, y, paint))
+
+    repeats = {key: hits for key, hits in shapes.items() if len(hits) > 1}
+
+    if repeats:
+        print('\nRepeated rects — one component rendered N times, not N designs:')
+
+        for (width, height, radius), hits in sorted(repeats.items(), key=lambda item: -len(item[1])):
+            fills = {paint for _, _, paint in hits}
+            varies = f', {len(fills)} fills' if len(fills) > 1 else ''
+            print(f'  {len(hits)}× {trim(width)} × {trim(height)}' + (f' r={radius}' if radius else '') + varies)
+
+    rows = {}
+
+    for x, y, width, height, name, _, _ in boxes:
+        if name == 'rect':
+            rows.setdefault(round(y, 2), set()).add((x, width))
+
+    printed = False
+
+    for y, hits in sorted(rows.items()):
+        spans, edge = [], None
+
+        for x, width in sorted(hits):
+            if edge is not None and x >= edge:
+                spans.append(round(x - edge, 2))
+
+            edge = max(edge or 0, x + width)
+
+        if not spans:
+            continue
+
+        if not printed:
+            print('\nGaps between rects sharing a top edge — the auto-layout gap, measured:')
+            printed = True
+
+        print(f'  y={trim(y):<8} {len(spans) + 1} columns, gaps: {", ".join(trim(span) for span in spans)}')
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+
+    root = ET.parse(sys.argv[1]).getroot()
+    boxes = []
+
+    print(f'canvas {root.get("width")} × {root.get("height")}  viewBox={root.get("viewBox")}\n')
+    walk(root, (0.0, 0.0), 0, boxes)
+    summarise(boxes)
+
+
+if __name__ == '__main__':
+    main()

package/content/skills/figma-export/measure-template.mjs

@@ -0,0 +1,87 @@
+/**
+ * Measure real rendered geometry against the numbers in a Figma export.
+ *
+ * Copy into a scratch directory next to a `styles.css` copied out of a production build,
+ * replace MARKUP / WIDTHS / DESIGN / probe(), then `node measure-template.mjs`.
+ */
+import { createRequire } from 'node:module';
+import { writeFileSync } from 'node:fs';
+
+// This runs from a scratch directory, so Playwright cannot be resolved by name — point
+// createRequire at the repo root. Playwright is CommonJS; a named import fails.
+const REPO_ROOT = '/absolute/path/to/repo'; // <-- change me
+const { chromium } = createRequire(`${REPO_ROOT}/`)('playwright');
+
+/** One instance of the thing under test. Keep the real component classes verbatim. */
+const MARKUP = (id) => `
+  <div id="${id}-card" class="…">
+    <h4 id="${id}-title" class="…">Some realistically long label</h4>
+  </div>`;
+
+/** Container widths to probe, taken from the export's frames — not from viewport breakpoints. */
+const WIDTHS = [956, 640];
+
+/** What the export says each width should produce. */
+const DESIGN = {
+  956: { cols: 4, cardW: 219, cardH: 60 },
+  640: { cols: 3, cardW: 192, cardH: 60 },
+};
+
+// Column, never row: in a flex row the harness items shrink, and container queries then
+// report results for a width the component would never actually see.
+const page = (blocks) => `<!doctype html><html class="et-surface--dark"><head><meta charset="utf-8">
+<link rel="stylesheet" href="./styles.css"></head>
+<body class="et-surface--dark" style="margin:0;padding:24px;display:flex;flex-direction:column;gap:24px;align-items:flex-start">
+${blocks}
+</body></html>`;
+
+const block = (width) => `<div id="w${width}" class="@container" style="width:${width}px">
+  <div class="…">${MARKUP(`w${width}`)}</div>
+</div>`;
+
+// page.setContent() renders on about:blank, which blocks file:// subresources — the
+// stylesheet would silently never load. Write a real file and navigate to it.
+writeFileSync('harness.html', page(WIDTHS.map(block).join('\n')));
+
+const browser = await chromium.launch();
+const tab = await browser.newPage({ viewport: { width: 1200, height: 900 }, deviceScaleFactor: 2 });
+
+await tab.goto(`file://${process.cwd()}/harness.html`);
+await tab.waitForTimeout(300);
+
+const measured = await tab.evaluate((widths) => {
+  const round = (value) => Math.round(value * 100) / 100;
+  const box = (id) => document.getElementById(id).getBoundingClientRect();
+  const font = (id) => getComputedStyle(document.getElementById(id));
+
+  return widths.map((width) => {
+    const card = box(`w${width}-card`);
+    const title = font(`w${width}-title`);
+
+    return {
+      width,
+      cardW: round(card.width),
+      cardH: round(card.height),
+      titleInset: round(box(`w${width}-title`).left - card.left),
+      fontSize: title.fontSize,
+      lineHeight: title.lineHeight,
+      letterSpacing: title.letterSpacing,
+    };
+  });
+}, WIDTHS);
+
+let failures = 0;
+
+for (const row of measured) {
+  const want = DESIGN[row.width];
+  const ok = Math.abs(row.cardW - want.cardW) < 1 && Math.abs(row.cardH - want.cardH) < 0.5;
+
+  if (!ok) failures++;
+
+  console.log(`${String(row.width).padStart(4)}px | ${ok ? 'OK ' : 'BAD'} |`, row);
+}
+
+console.log(failures === 0 ? '\nALL GEOMETRY MATCHES' : `\n${failures} MISMATCHES`);
+
+await tab.screenshot({ path: 'verify.png', fullPage: true });
+await browser.close();

package/content/skills/query/SKILL.md

@@ -79,6 +79,12 @@ raw `toObservable`). It emits `null` first - `pipe(filter(r => r !== null))`.
   drive **search-as-you-type**: back it with a search signal
   (`withArgs(() => ({ queryParams: { search: this.search() } }))`). Return
   `CLEAR_QUERY_ARGS` to reset args to `null` (pauses polling/auto-refresh).
+- **Prefer `withArgs` over passing `args` to `execute()`.** Args declared on the query
+  stay reactive: a `GET` re-executes itself when they change, and `withPolling` /
+  `withAutoRefresh` restart off the same signal - none of which happens for args handed
+  to `execute()`. A function route additionally throws without it. With `withArgs` in
+  place a mutation is just `.execute()`, which reuses the current `args()`. Reserve
+  `execute({ args })` for a one-off payload no signal holds (a form submit).
 - `withPolling({ interval })`, `withAutoRefresh({ onSignalChanges: [...] })`.
 - Side-effects: `withSuccessHandling`, `withErrorHandling`, `withLogging`.
 

package/content/skills/rxjs-signals/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rxjs-signals
-description: How to choose between signals and RxJS, and use each correctly - synchronous state vs asynchronous work, unsubscribing, and avoiding RxJS inside effects/computeds. Read when adding reactive state, wiring up an observable, or deciding whether something should be a signal or a stream. Part of the Ethlete styleguide (judgment beyond what lint enforces).
+description: How to choose between signals and RxJS, and use each correctly - synchronous state vs asynchronous work, unsubscribing, and avoiding RxJS inside effects/computeds. Read when adding reactive state, wiring up an observable, or deciding whether something should be a signal or a stream.
 kind: skill
 scope: both
 requires: ['@ethlete/core']

package/content/skills/theming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theming
-description: The two runtime theming systems in @ethlete/core - surface theming (elevation-aware neutrals) and color theming (semantic accent palettes) - how to register them in an app and how components must consume them. Read BEFORE writing or reviewing CSS that involves any color, background, border, or interaction state, and when wiring theme context across overlay/portal boundaries.
+description: The two runtime theming systems in @ethlete/core - surface theming (elevation-aware neutrals) and color theming (semantic accent palettes). Read BEFORE writing or reviewing CSS involving color, background, border, or interaction state, and when wiring theme context across overlay/portal boundaries.
 kind: skill
 scope: consumer
 requires: ['@ethlete/core']

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/agent-rules",
-  "version": "0.1.0-next.3",
+  "version": "0.1.0-next.5",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/lib/config.d.ts

@@ -16,7 +16,7 @@ export type SyncConfig = {
      * `AGENTS.md` marker block, and a second copy would load twice.
      */
     claudeMdImportsAgentsMd: boolean;
-    /** Opt-in Claude Code hooks (they run commands on the developer's machine, so never default). */
+    /** Opt-in agent hooks (they run commands on the developer's machine, so never default). */
     hooks: string[];
 };
 /**
@@ -26,11 +26,15 @@ export type SyncConfig = {
  * so nothing here may change what gets emitted:
  *
  * - `disableHooks: true` silences every generated hook, `["context-warning"]` just the named ones.
+ * - `disableAutoHandoffSave: true` keeps the context-warning hook's normal tiered messages (including
+ *   in auto mode), but at the critical tier in auto mode it falls back to just recommending
+ *   a handoff instead of writing the handoff file automatically.
  * - `sdkSourcePath` points at a local `ethlete-sdk` checkout, which the SDK source and local-build
  *   skills read when they need the SDK's own sources instead of the published package.
  */
 export type LocalConfig = {
     disableHooks?: boolean | string[];
+    disableAutoHandoffSave?: boolean;
     sdkSourcePath?: string;
 };
 export type LocalConfigState = {

package/src/lib/config.js

@@ -13,7 +13,7 @@ const readRawConfig = (root) => {
         return {};
     return JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
 };
-const LOCAL_CONFIG_KEYS = ['disableHooks', 'sdkSourcePath'];
+const LOCAL_CONFIG_KEYS = ['disableHooks', 'disableAutoHandoffSave', 'sdkSourcePath'];
 const readLocalConfig = (root) => {
     const path = (0, path_1.join)(root, exports.LOCAL_CONFIG_FILE_NAME);
     if (!(0, fs_1.existsSync)(path))