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

package/content/skills/design-exploration/check-story.mjs

@@ -0,0 +1,139 @@
+/**
+ * Find out why a story does not render, in the cheapest order.
+ *
+ * A compile error renders as an overlay on top of the story, so a screenshot of it looks
+ * like a design. Run this first, and never screenshot before it says `ok`.
+ *
+ * Copy to the repository root - Node resolves `playwright` from the working directory.
+ *
+ *   node check-story.mjs --lint <file>… --tsconfig <path>        # ~4s, no browser
+ *   node check-story.mjs --tsconfig <path> --story <story-id>    # + the render
+ *   SB_URL=http://localhost:4401 node check-story.mjs --story <story-id>
+ *
+ * Three stages, because they cost three different amounts:
+ *
+ * 1. `eslint` on the files you changed, about a second. Name the files - never a whole
+ *    project, which is far slower and can fight the user's own editor.
+ * 2. `tsc --noEmit` reads the source. It needs no dev server, waits for no rebuild, and
+ *    catches every syntax and type error in about three seconds. Almost everything you
+ *    break is caught here.
+ * 3. The browser catches what the source cannot: an Angular template error, a runtime
+ *    throw, a missing story id. It costs a browser launch, and it can only see a build the
+ *    dev server has already finished, so a fresh edit needs a few seconds first.
+ *
+ * A type error does not stop this repo's Storybook - it transpiles without checking - so
+ * stage 2 alone will report `ok` on a file that does not compile. That is why stage 1 exists.
+ */
+import { execFileSync } from 'node:child_process';
+
+const BASE = process.env.SB_URL ?? 'http://localhost:4400';
+
+/**
+ * The type checker to run. `tsc` resolves the one the repository installed. Set
+ * `TSC=@typescript/native-preview` for the Go port, which is about a third faster - but it
+ * rejects a `baseUrl` in the config, so a repository that still uses one cannot run it.
+ */
+const TSC = process.env.TSC ?? null;
+
+const flags = { '--lint': [], '--tsconfig': [], '--story': [] };
+let current = null;
+
+for (const arg of process.argv.slice(2)) {
+  if (arg in flags) current = arg;
+  else if (current) flags[current].push(arg);
+}
+
+const lintFiles = flags['--lint'];
+const [tsconfig] = flags['--tsconfig'];
+const [id] = flags['--story'];
+
+if (lintFiles.length === 0 && !tsconfig && !id) {
+  console.error('usage: node check-story.mjs [--lint <file>…] [--tsconfig <path>] [--story <id>]');
+  process.exit(2);
+}
+
+/** A bundler stack runs to hundreds of frames and says nothing. Keep the message. */
+const trim = (text) =>
+  [...new Set(text.split('\n').filter((line) => !/^\s+at /.test(line) && line.trim() !== ''))].slice(0, 12).join('\n');
+
+if (lintFiles.length > 0) {
+  try {
+    execFileSync('npx', ['eslint', ...lintFiles], { encoding: 'utf8', stdio: 'pipe' });
+  } catch (error) {
+    console.error(`LINT\n${trim(`${error.stdout ?? ''}${error.stderr ?? ''}`)}`);
+    process.exit(1);
+  }
+}
+
+if (tsconfig) {
+  try {
+    const cmd = TSC ? ['-y', TSC] : ['tsc'];
+    execFileSync('npx', [...cmd, '--noEmit', '-p', tsconfig], { encoding: 'utf8', stdio: 'pipe' });
+  } catch (error) {
+    console.error(`TYPE ERROR\n${trim(`${error.stdout ?? ''}${error.stderr ?? ''}`)}`);
+    process.exit(1);
+  }
+}
+
+if (!id) {
+  console.log('ok');
+  process.exit(0);
+}
+
+const { chromium } = await import('playwright');
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1400, height: 900 } });
+
+/** Angular throws at render time; the overlay never shows those, so read the console too. */
+const consoleErrors = [];
+page.on('console', (m) => m.type() === 'error' && consoleErrors.push(m.text()));
+page.on('pageerror', (e) => consoleErrors.push(e.message));
+
+await page.goto(`${BASE}/iframe.html?id=${id}&viewMode=story`, { waitUntil: 'domcontentloaded' });
+
+const rendered = await page
+  .locator('#storybook-root > *')
+  .first()
+  .waitFor({ timeout: 15000 })
+  .then(
+    () => true,
+    () => false,
+  );
+
+/** The webpack overlay is an iframe, so its text is only reachable through a frame locator. */
+const webpackOverlayText =
+  (await page.locator('#webpack-dev-server-client-overlay').count()) > 0
+    ? await page
+        .frameLocator('#webpack-dev-server-client-overlay')
+        .locator('body')
+        .innerText()
+        .catch(() => '(overlay present, text unreadable)')
+    : '';
+/** The Vite overlay keeps its text in a shadow root. */
+const viteOverlayText = await page.evaluate(() => {
+  const overlay = document.querySelector('vite-error-overlay');
+  if (!overlay) return '';
+  return overlay.shadowRoot?.textContent?.trim() || '(overlay present, text unreadable)';
+});
+const overlayText = webpackOverlayText || viteOverlayText;
+
+await browser.close();
+
+if (overlayText) {
+  console.error(`COMPILE ERROR on ${id}\n${trim(overlayText)}`);
+  process.exit(1);
+}
+
+if (!rendered) {
+  console.error(`EMPTY on ${id} - #storybook-root never got a child.`);
+  if (consoleErrors.length > 0) console.error(trim(consoleErrors.join('\n')));
+  process.exit(1);
+}
+
+if (consoleErrors.length > 0) {
+  console.error(`RENDERED WITH ERRORS on ${id}\n${trim(consoleErrors.join('\n'))}`);
+  process.exit(1);
+}
+
+console.log(`ok ${id}`);

package/content/skills/design-exploration/shoot-template.mjs

@@ -0,0 +1,61 @@
+/**
+ * Screenshot one Storybook story, with optional forced pseudo-states.
+ *
+ * Copy to the repository root - Node resolves `playwright` from the working directory.
+ *
+ *   node shoot.mjs <story-id> [width] [height] [out.png]
+ *
+ * To hold :hover / :focus-visible / :active open at the same time, fill FORCED below with
+ * one entry per element. A CSS selector is matched inside the story's document.
+ */
+import { chromium } from 'playwright';
+
+const BASE = process.env.SB_URL ?? 'http://localhost:4400';
+
+/** @type {{ selector: string, states: ('hover'|'focus'|'focus-visible'|'active')[] }[]} */
+const FORCED = [
+  // { selector: '[data-state="hover"] .the-band', states: ['hover'] },
+];
+
+const [id, width = '1100', height = '760', out = 'shot.png'] = process.argv.slice(2);
+
+if (!id) {
+  console.error('usage: node shoot.mjs <story-id> [width] [height] [out.png]');
+  process.exit(1);
+}
+
+const browser = await chromium.launch();
+const page = await browser.newPage({
+  viewport: { width: Number(width), height: Number(height) },
+  deviceScaleFactor: 2,
+});
+
+await page.goto(`${BASE}/iframe.html?id=${id}&viewMode=story`, { waitUntil: 'domcontentloaded' });
+await page.waitForSelector('#storybook-root > *', { timeout: 15000 });
+
+const overlays = await page.locator('#webpack-dev-server-client-overlay, vite-error-overlay').count();
+if (overlays > 0) {
+  console.error('compile error overlay is present - the image would lie');
+  await browser.close();
+  process.exit(1);
+}
+
+if (FORCED.length > 0) {
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send('DOM.enable');
+  await cdp.send('CSS.enable');
+  const { root } = await cdp.send('DOM.getDocument', { depth: -1 });
+
+  for (const { selector, states } of FORCED) {
+    const { nodeIds } = await cdp.send('DOM.querySelectorAll', { nodeId: root.nodeId, selector });
+    for (const nodeId of nodeIds) {
+      await cdp.send('CSS.forcePseudoState', { nodeId, forcedPseudoClasses: states });
+    }
+  }
+}
+
+await page.waitForTimeout(400);
+await page.screenshot({ path: out });
+await browser.close();
+
+console.log(out);

package/content/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily: only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording _that_ a decision was made and _why_, not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`): useful when decisions are revisited
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it; otherwise someone will suggest GraphQL again in six months.

package/content/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/content/skills/domain-modeling/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
+kind: skill
+scope: both
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the _active_ discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely _reading_ `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily: only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account': do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up: capture them as they happen. Use the format in {%resource:CONTEXT-FORMAT.md%}.
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in {%resource:ADR-FORMAT.md%}.
+
+---
+
+Vendored from [mattpocock/skills](https://github.com/mattpocock/skills) at `3cca18b`, MIT (Copyright (c) 2026 Matt Pocock).

package/content/skills/e2e-triage/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: e2e-triage
+description: Work through a failed Playwright e2e run - read the failures file the @ethlete/cli failure reporter writes, group the failures by error, fix the largest group first, and re-run only the specs that failed. Read when an e2e run fails with more than a few tests, when an `e2e-failures.jsonl` file is present, or before you start a full e2e run after a change.
+kind: skill
+scope: consumer
+requires: ['@ethlete/cli']
+vars: [docsBaseUrl]
+---
+
+# Triage a failed e2e run
+
+Many failed tests rarely mean many bugs. In one real run, a single change in a shared pipe failed 61
+tests. After the fix, 158 of the first 159 retried tests passed. So find the shared cause first, and
+never fix failures one test at a time from the top of the log.
+
+## Before the run
+
+1. Check that `playwright.config.ts` lists `@ethlete/cli/playwright/failure-reporter` in `reporter`.
+   If not, add it next to the reporter that is there: `[['list'], ['@ethlete/cli/playwright/failure-reporter']]`.
+   The reporter writes one JSON line per failed attempt while the run goes on. The guide is
+   {%docsBaseUrl%}/cli/e2e.
+2. Run the specs of the files you changed first. Start the full suite only when they pass. A full
+   run takes long, and one broken shared file fails it everywhere.
+
+## Read the failures
+
+The file is `e2e-failures.jsonl` next to `playwright.config.ts`, unless `E2E_FAILURES_FILE` or the
+`outputFile` option of the reporter names another path. You can read it while the run goes on.
+
+Each line has `test`, `location`, `project`, `status`, `retry`, `seconds`, `error`, `detail` and `context`.
+`error` holds the first lines of the message. `detail` holds the first later line with a URL, for errors whose first lines do not name it, or `null`. `context` is the path of Playwright's
+`error-context.md`, which holds the page snapshot at the failure.
+
+Do not parse the console log of the run. It mixes the output of parallel workers, and it has no end
+line if the run stops.
+
+## Group, then fix the largest group
+
+1. Normalize the `error` text of each line. Remove line and column numbers, timeouts in ms, ids,
+   hashes and dates. Keep the matcher, the locator and the expected value.
+2. Group the lines by the normalized text. Count the distinct spec files per group, not only the lines.
+   A group that spans many spec files points at shared code: a component, a pipe, a fixture or a
+   test helper.
+3. Take the largest group. Read one `context` file of it, then the code the error points at. Find
+   one cause that explains the whole group.
+4. Fix that cause. Then re-run only the spec files of that group.
+
+A group whose errors are a connection refused (`ERR_CONNECTION_REFUSED`, `ECONNREFUSED`) on a local mock or
+`webServer` port is an infrastructure group, not a test verdict. Check that the server is still up,
+restart it, and re-run those tests before you read them as failures.
+
+Small groups that differ only in a locator often have the same cause. Check them after the large group
+is fixed, because a fix often clears them too.
+
+## Re-run only what failed
+
+Take the spec file from `location`, without the `:line`. Collect each file once, then run:
+
+```bash
+npx playwright test <file> <file> --project=<project> --no-deps
+```
+
+- Pass each file as its own argument. In zsh, an unquoted `$files` is one argument, and Playwright
+  then finds no tests.
+- `--no-deps` skips the setup projects. Leave it out if the failure is in a setup project, or if the
+  setup state is gone.
+- `--project` comes from the `project` field. Run one call per project.
+
+## Retries and flaky tests
+
+With `retries` on, a test that fails each attempt has one line per attempt (`retry` 0, 1, and so on).
+A test with a line for `retry` 0 and no line for the last retry passed on a later attempt: it is flaky.
+Report a flaky test, but fix the stable failures first.
+
+## Rules
+
+- Never skip a failed test, or mark it with `test.fail()` or `test.fixme()`, to make a run pass.
+- Never change an assertion to match the wrong value the app shows now. A failed e2e test is a
+  signal first. If you think the test is wrong, say why, and ask before you change it.
+- Report per group: the cause, the fix, the spec files you re-ran, and what still fails.

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

@@ -0,0 +1,191 @@
+---
+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.** That pair is the preferred complete input:
+the SVG is the export you can look at and measure, and the CSS names layers and records
+type. A PNG earns its place only when it is a _screenshot_ carrying dev-mode annotations.
+Exports expose rendered color values, but they do not identify the authoritative semantic
+theme token.
+
+If one artifact is missing, inspect the existing code and the artifact you do have. List
+the exact facts that remain unknown and do not invent their measurements. Ask before a
+structural choice or an untraceable numeric value, not before useful read-only inspection.
+
+## 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: semantic colour choice.** Backgrounds, text, borders and
+  interaction states resolve from the repository's theme tokens. 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. When driving a story, follow the repository's
+  installed Storybook verification guidance if present.
+
+## 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
+report that the export files are no longer needed. Delete only artifacts this workflow
+created and only when the workflow or user explicitly authorizes cleanup; otherwise let the
+user decide whether supplied exports remain useful records.