@ethlete/agent-rules 0.1.0-next.4 → 0.1.0-next.6

package/content/hooks/context-warning.py

@@ -2,31 +2,47 @@
 """UserPromptSubmit hook: warn when the context window is getting large.
 
 Reads the hook input JSON from stdin, estimates the current context size from
-the last main-chain assistant message in the session transcript, and emits a
-warning (visible to both the user and Claude) when it crosses a threshold.
-Recommends the /handoff skill so work can continue in a fresh session.
+the session transcript, and emits a warning (visible to both the user and the
+agent) when it crosses a threshold. Recommends the handoff skill so work can
+continue in a fresh session.
+
+Runs under both Claude Code and Codex, selected by `--agent` on the command
+line rather than sniffed from the payload — the generator writes the flag, so
+the two never have to be told apart at runtime. The two differ in three ways
+that matter here, all captured in AGENT_PROFILES:
+
+  * Transcript format. Claude writes one JSON object per message with
+    `message.usage`; Codex writes a rollout stream whose `token_count` events
+    carry a TokenUsageInfo. Codex's rollout format is explicitly not a stable
+    interface, so the parser searches each line for the usage object instead of
+    walking a fixed path.
+  * Context budget. Claude's budget is capped at the 200k long-context pricing
+    boundary: on models with a larger window, every request past that point
+    bills the entire context at the premium rate, which costs far more than
+    handing off into a fresh session ever would. Codex has no such boundary, so
+    its budget is just the window.
+  * How a handoff is invoked. Claude has a slash command and /clear; Codex has
+    neither and reads the skill from disk. The skill's own name differs per repo
+    (`ethlete-handoff` where the generator installed it, `handoff` where the repo
+    ships its own copy), so it is resolved at runtime — see handoff_skill().
 
 At the critical tier, if the session's permission_mode is "auto", the
 instruction escalates from "recommend" to "just do it": auto mode already
-means the user wants Claude acting without stopping to ask, and clearing +
+means the user wants the agent acting without stopping to ask, and clearing +
 resuming can't be triggered programmatically (no hook or tool can submit
 input to a running session), so the best available automation is to save the
-handoff file itself immediately rather than waiting for Claude to notice a
-natural stopping point.
-
-The thresholds are fractions of a token budget, and the budget is capped at the
-200k long-context pricing boundary: on models with a larger window, every
-request past that point bills the entire context at the premium rate, which
-costs far more than handing off into a fresh session ever would.
+handoff file itself immediately rather than waiting for a natural stopping
+point. Codex's permission_mode value set is undocumented, so its profile lists
+no auto modes and the escalation stays off there.
 
 Warns once per tier per session (state kept in a temp file); re-arms itself
-if the context shrinks again (e.g. after /compact).
+if the context shrinks again (e.g. after a compaction).
 
 Can be disabled per machine via a gitignored ethlete-agents.config.local.json
 at the repo root: {"disableHooks": true} or {"disableHooks": ["context-warning"]}.
 To keep the tiered warnings but drop just the auto-mode auto-save escalation,
 use {"disableAutoHandoffSave": true} instead - the critical tier then falls
-back to recommending /handoff, same as non-auto mode.
+back to recommending a handoff, same as non-auto mode.
 
 Fail-safe: any error exits 0 with no output — the hook must never block a prompt.
 """
@@ -64,10 +80,110 @@ CONTEXT_WINDOWS = (
 )
 DEFAULT_WINDOW = 200_000
 
+AGENT_PROFILES = {
+    "claude": {
+        "premium_boundary": PREMIUM_BOUNDARY,
+        # Claude's transcript reports no window, so it is resolved from the model id.
+        "default_window": None,
+        "auto_modes": ("auto",),
+        "emits_system_message": True,
+        "act_now": "Run /{handoff} now and continue in a fresh session.",
+        "act_later": "consider /{handoff} to continue in a fresh session",
+        "recommend": "recommend the user run /{handoff} to save state and start a fresh session",
+        "suggest": "suggest the user run /{handoff} to save state and start a fresh session",
+        "save_now": (
+            "run the handoff skill's save mode right now (finish only an in-flight atomic "
+            "edit first, nothing new). Then tell the user exactly which handoff file was "
+            "written and that they should run /clear, then '/{handoff} resume <slug>', to "
+            "continue — clearing and resuming can't be done programmatically, so this is "
+            "the one step still on them."
+        ),
+    },
+    "codex": {
+        "premium_boundary": None,
+        # Only reached if a rollout omits model_context_window; the CONTEXT_WINDOWS table
+        # holds Claude model ids and would never match a Codex one.
+        "default_window": 272_000,
+        # Codex's permission_mode values are undocumented; until one is confirmed to mean
+        # "never ask", no value enables the auto-save escalation.
+        "auto_modes": (),
+        # Only hookSpecificOutput.additionalContext is documented for Codex, so the
+        # user-facing line is folded into the model-facing text instead.
+        "emits_system_message": False,
+        "act_now": "Save a handoff now and continue in a fresh session.",
+        "act_later": "consider saving a handoff and continuing in a fresh session",
+        "recommend": (
+            "tell the user you are near the context limit, then follow "
+            ".agents/skills/{handoff}/SKILL.md to save a handoff and have them start a "
+            "fresh session"
+        ),
+        "suggest": (
+            "suggest saving a handoff via .agents/skills/{handoff}/SKILL.md and "
+            "continuing in a fresh session"
+        ),
+        "save_now": (
+            "follow .agents/skills/{handoff}/SKILL.md and save a handoff right now "
+            "(finish only an in-flight atomic edit first, nothing new). Then tell the user "
+            "exactly which handoff file was written and that they should start a fresh "
+            "codex session and resume from it."
+        ),
+    },
+}
+
+
+def handoff_skill(root):
+    """Name of the handoff skill installed in this repo.
+
+    The generator prefixes every skill it writes, so the command is /ethlete-handoff in a
+    consumer repo — but a repo that excludes the generated copy and ships its own (the SDK
+    itself) has a plain /handoff instead. Naming the wrong one sends the user to a slash
+    command that does not exist, so it is read off disk rather than assumed.
+    """
+    for name in ("ethlete-handoff", "handoff"):
+        for skills_dir in (".claude/skills", ".agents/skills"):
+            if os.path.isdir(os.path.join(root or ".", skills_dir, name)):
+                return name
+    return "ethlete-handoff"
+
+
+def resolve_profile(profile, skill):
+    """Fills the installed handoff skill's name into a profile's message fragments."""
+    return {
+        key: value.replace("{handoff}", skill) if isinstance(value, str) else value
+        for key, value in profile.items()
+    }
+
+
+def agent_name(argv):
+    """The --agent value, defaulting to claude — older registrations pass no flag."""
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
 
-def load_local_config():
+
+def repo_root(data):
+    """Repo root: the env var the agent sets, else derived from this script's own location.
+
+    The script always lives at <root>/.<agent>/hooks/ethlete/context-warning.py, so walking
+    four levels up works for any agent that has no project-dir variable of its own.
+    """
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
     """Parsed ethlete-agents.config.local.json at the repo root, or {} if missing/unreadable."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR")
     if not root:
         return {}
     try:
@@ -98,10 +214,11 @@ def window_for(model):
     return DEFAULT_WINDOW
 
 
-def context_state(transcript_path):
-    """(tokens, model) from the last main-chain assistant message.
+def claude_context_state(transcript_path):
+    """(tokens, model, window) from the last main-chain assistant message.
 
-    tokens ≈ its total input tokens (fresh + cache read + cache creation).
+    tokens ≈ its total input tokens (fresh + cache read + cache creation). Claude reports no
+    window in the transcript, so it is resolved from the model id by the caller.
     """
     last_usage = None
     last_model = None
@@ -119,111 +236,154 @@ def context_state(transcript_path):
                 last_usage = usage
                 last_model = message.get("model") or last_model
     if not last_usage:
-        return 0, last_model
+        return 0, last_model, None
     tokens = (
         last_usage.get("input_tokens", 0)
         + last_usage.get("cache_read_input_tokens", 0)
         + last_usage.get("cache_creation_input_tokens", 0)
     )
-    return tokens, last_model
+    return tokens, last_model, None
+
+
+def find_token_usage_info(node):
+    """The deepest TokenUsageInfo-shaped dict in a parsed rollout line, or None.
+
+    Codex documents its rollout format as unstable, so this searches for the shape
+    (a dict carrying `last_token_usage`) rather than walking a fixed key path.
+    """
+    if isinstance(node, dict):
+        if isinstance(node.get("last_token_usage"), dict):
+            return node
+        for value in node.values():
+            found = find_token_usage_info(value)
+            if found:
+                return found
+    elif isinstance(node, list):
+        for value in node:
+            found = find_token_usage_info(value)
+            if found:
+                return found
+    return None
+
+
+def codex_context_state(transcript_path):
+    """(tokens, model, window) from the last token_count event in a Codex rollout.
+
+    tokens is the last request's `total_tokens` — Codex's own `tokens_in_context_window()`
+    is exactly that field, and `last_token_usage` is replaced per request while
+    `total_token_usage` accumulates across the whole session.
+    """
+    last_info = None
+    last_model = None
+    with open(transcript_path, encoding="utf-8") as f:
+        for line in f:
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            model = (obj.get("payload") or {}).get("model") if isinstance(obj.get("payload"), dict) else None
+            if isinstance(model, str) and model:
+                last_model = model
+            info = find_token_usage_info(obj)
+            if info:
+                last_info = info
+    if not last_info:
+        return 0, last_model, None
+    usage = last_info.get("last_token_usage") or {}
+    window = last_info.get("model_context_window")
+    return usage.get("total_tokens", 0), last_model, window if isinstance(window, int) else None
+
 
+CONTEXT_READERS = {"claude": claude_context_state, "codex": codex_context_state}
 
-def messages(tier, tokens, budget, priced, auto_mode):
+
+def messages(profile, tier, tokens, budget, priced, auto_mode):
     """(systemMessage, additionalContext) for a tier.
 
     priced: the budget is the pricing boundary, not the window — the reason to
     hand off is cost, not an imminent auto-compact.
-    auto_mode: at the critical tier, escalates from "recommend /handoff" to
+    auto_mode: at the critical tier, escalates from "recommend a handoff" to
     "save it now" — see the module docstring for why.
     """
     k = f"~{tokens // 1000}k"
     pct = round(tokens / budget * 100)
     budget_k = f"{budget // 1000}k"
-    if tier == 2 and auto_mode and priced:
-        return (
-            f"🔴 Context is at {k} tokens — about to cross the {budget_k} long-context "
-            f"pricing boundary. Auto mode is active: saving a handoff now.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary. Auto mode is active, so don't just "
-            "recommend a handoff — run the handoff skill's save mode right now (finish only "
-            "an in-flight atomic edit first, nothing new). Then tell the user exactly which "
-            "handoff file was written and that they should run /clear, then "
-            "'/handoff resume <slug>', to continue — clearing and resuming can't be done "
-            "programmatically, so this is the one step still on them.",
+
+    if priced:
+        approach = "about to cross" if tier == 2 else "approaching"
+        headline = f"Context is at {k} tokens — {approach} the {budget_k} long-context pricing boundary"
+        detail = (
+            f"The context is at {k} tokens — {pct}% of the {budget_k} long-context "
+            f"pricing boundary."
         )
-    if tier == 2 and auto_mode:
-        return (
-            f"🔴 Context is at {k} tokens ({pct}% of the {budget_k} window) — "
-            f"auto-compact is imminent. Auto mode is active: saving a handoff now.",
-            f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-            f"this model's {budget_k} window (critical, ≥{int(CRITICAL_FRACTION * 100)}%). "
-            "Auto mode is active, so don't just recommend a handoff — run the handoff "
-            "skill's save mode right now (finish only an in-flight atomic edit first, "
-            "nothing new). Then tell the user exactly which handoff file was written and "
-            "that they should run /clear, then '/handoff resume <slug>', to continue — "
-            "clearing and resuming can't be done programmatically, so this is the one step "
-            "still on them.",
-        )
-    if tier == 2 and priced:
-        return (
-            f"🔴 Context is at {k} tokens — about to cross the {budget_k} long-context "
-            f"pricing boundary, after which every request bills the whole context at the "
-            f"premium rate. Run /handoff now and continue in a fresh session.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary. Past it every request is billed at "
-            "the premium rate. Finish only the immediate step, then recommend the user run "
-            "/handoff to save state and start a fresh session. Do not start new sub-tasks.",
+    else:
+        headline = f"Context is at {k} tokens ({pct}% of the {budget_k} window)"
+        detail = (
+            f"The context window is at {k} tokens — {pct}% of this model's "
+            f"{budget_k} window"
         )
+
     if tier == 2:
-        return (
-            f"🔴 Context is at {k} tokens ({pct}% of the {budget_k} window) — "
-            f"auto-compact is imminent. Run /handoff now and continue in a fresh session.",
-            f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-            f"this model's {budget_k} window (critical, ≥{int(CRITICAL_FRACTION * 100)}%). "
-            "Finish only the immediate step, then recommend the user run /handoff to "
-            "save state and start a fresh session. Do not start new sub-tasks.",
+        threshold = f" (critical, ≥{int(CRITICAL_FRACTION * 100)}%)"
+        detail = detail if priced else f"{detail}{threshold}."
+        pressure = (
+            "Past it every request is billed at the premium rate. "
+            if priced
+            else ""
         )
-    if priced:
+        tail = "" if priced else " — auto-compact is imminent"
+        if auto_mode:
+            return (
+                f"🔴 {headline}{tail}. Auto mode is active: saving a handoff now.",
+                f"[context-warning hook] {detail} {pressure}Auto mode is active, so don't "
+                f"just recommend a handoff — {profile['save_now']}",
+            )
         return (
-            f"🟡 Context is at {k} tokens, approaching the {budget_k} long-context "
-            f"pricing boundary. At the next natural stopping point, consider /handoff "
-            f"to continue in a fresh session.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary, past which every request is "
-            "billed at the premium rate. When the current task reaches a natural "
-            "stopping point, suggest the user run /handoff to save state and start a "
-            "fresh session. Keep working normally until then.",
+            f"🔴 {headline}{tail}. {profile['act_now']}",
+            f"[context-warning hook] {detail} {pressure}Finish only the immediate step, "
+            f"then {profile['recommend']}. Do not start new sub-tasks.",
         )
+
+    threshold = f" (≥{int(WARN_FRACTION * 100)}%)"
+    detail = detail if priced else f"{detail}{threshold}."
+    pressure = "Past it every request is billed at the premium rate. " if priced else ""
     return (
-        f"🟡 Context is at {k} tokens ({pct}% of the {budget_k} window). At the next "
-        f"natural stopping point, consider /handoff to continue in a fresh session.",
-        f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-        f"this model's {budget_k} window (≥{int(WARN_FRACTION * 100)}%). When the "
-        "current task reaches a natural stopping point, suggest the user run "
-        "/handoff to save state and start a fresh session. Keep working normally until then.",
+        f"🟡 {headline}. At the next natural stopping point, {profile['act_later']}.",
+        f"[context-warning hook] {detail} {pressure}When the current task reaches a "
+        f"natural stopping point, {profile['suggest']}. Keep working normally until then.",
     )
 
 
 def main():
-    local_config = load_local_config()
-    if disabled_locally(local_config):
+    agent = agent_name(sys.argv[1:])
+    profile = AGENT_PROFILES.get(agent)
+    if not profile:
         return
+
     data = json.load(sys.stdin)
+    root = repo_root(data)
+    local_config = load_local_config(root)
+    if disabled_locally(local_config):
+        return
+
+    profile = resolve_profile(profile, handoff_skill(root))
+
     transcript_path = data.get("transcript_path")
     session_id = data.get("session_id", "unknown")
-    auto_mode = data.get("permission_mode") == "auto" and not auto_handoff_save_disabled(local_config)
+    auto_mode = data.get("permission_mode") in profile["auto_modes"] and not auto_handoff_save_disabled(local_config)
     if not transcript_path or not os.path.isfile(transcript_path):
         return
 
-    tokens, model = context_state(transcript_path)
-    window = window_for(model)
-    budget = min(window, PREMIUM_BOUNDARY)
+    tokens, model, reported_window = CONTEXT_READERS[agent](transcript_path)
+    window = reported_window or profile["default_window"] or window_for(model)
+    boundary = profile["premium_boundary"]
+    budget = min(window, boundary) if boundary else window
     warn_tokens = int(budget * WARN_FRACTION)
     critical_tokens = int(budget * CRITICAL_FRACTION)
     tier = 2 if tokens >= critical_tokens else 1 if tokens >= warn_tokens else 0
 
     state_file = os.path.join(
-        tempfile.gettempdir(), f"claude-context-warning-{session_id}"
+        tempfile.gettempdir(), f"{agent}-context-warning-{session_id}"
     )
     prev_tier = 0
     try:
@@ -243,21 +403,23 @@ def main():
         return  # already warned at this tier (or context shrank — state re-armed above)
 
     system_message, additional_context = messages(
-        tier, tokens, budget, budget < window, auto_mode
+        profile, tier, tokens, budget, budget < window, auto_mode
     )
 
-    print(
-        json.dumps(
-            {
-                "systemMessage": system_message,
-                "suppressOutput": True,
-                "hookSpecificOutput": {
-                    "hookEventName": "UserPromptSubmit",
-                    "additionalContext": additional_context,
-                },
-            }
-        )
-    )
+    if not profile["emits_system_message"]:
+        additional_context = f"{additional_context}\n\nTell the user: {system_message}"
+
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": additional_context,
+        }
+    }
+    if profile["emits_system_message"]:
+        payload["systemMessage"] = system_message
+        payload["suppressOutput"] = True
+
+    print(json.dumps(payload))
 
 
 if __name__ == "__main__":

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.